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.4
  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  SDCDB and ucSim are currently not available on Win32 platforms.
 249
 250 \newline
 251
 252 \newline
 253 The latest version can be downloaded from
 254 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
 255
 256 \end_inset
 257
 258 .
 259
 260 \series bold
 261
 262 \series default
 263 \emph on
 264 Please note: the compiler will probably always be some steps ahead of this
 265  documentation
 266 \series bold
 267 \emph default
 268
 269 \begin_inset LatexCommand \index{Status of documentation}
 270
 271 \end_inset
 272
 273
 274 \begin_inset Foot
 275 collapsed false
 276
 277 \layout Standard
 278
 279 Obviously this has pros and cons
 280 \end_inset
 281
 282 .
 283 \layout Section
 284
 285 Open Source
 286 \layout Standard
 287
 288 All packages used in this compiler system are
 289 \emph on
 290 open source
 291 \emph default
 292  and
 293 \emph on
 294 freeware
 295 \emph default
 296 ; source code for all the sub-packages (pre-processor, assemblers, linkers
 297  etc) is distributed with the package.
 298  This documentation is maintained using a freeware word processor (LyX).
 299 \newline
 300 This program is free software; you can redistribute it and/or modify it
 301  under the terms of the GNU General Public License
 302 \begin_inset LatexCommand \index{GNU General Public License, GPL}
 303
 304 \end_inset
 305
 306  as published by the Free Software Foundation; either version 2, or (at
 307  your option) any later version.
 308  This program is distributed in the hope that it will be useful, but WITHOUT
 309  ANY WARRANTY; without even the implied warranty
 310 \begin_inset LatexCommand \index{warranty}
 311
 312 \end_inset
 313
 314  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 315  See the GNU General Public License for more details.
 316  You should have received a copy of the GNU General Public License along
 317  with this program; if not, write to the Free Software Foundation, 59 Temple
 318  Place - Suite 330, Boston, MA 02111-1307, USA.
 319  In other words, you are welcome to use, share and improve this program.
 320  You are forbidden to forbid anyone else to use, share and improve what
 321  you give them.
 322  Help stamp out software-hoarding!
 323 \layout Section
 324
 325 Typographic conventions
 326 \begin_inset LatexCommand \index{Typographic conventions}
 327
 328 \end_inset
 329
 330
 331 \layout Standard
 332
 333 Throughout this manual, we will use the following convention.
 334  Commands you have to type in are printed in
 335 \family sans
 336 \series bold
 337 "sans serif"
 338 \series default
 339 .
 340
 341 \family default
 342  Code samples are printed in
 343 \family typewriter
 344 typewriter font.
 345
 346 \family default
 347  Interesting items and new terms are printed in
 348 \emph on
 349 italic.
 350 \layout Section
 351
 352 Compatibility with previous versions
 353 \begin_inset LatexCommand \index{Compatibility with previous versions}
 354
 355 \end_inset
 356
 357
 358 \layout Standard
 359
 360 This version has numerous bug fixes compared with the previous version.
 361  But we also introduced some incompatibilities with older versions.
 362  Not just for the fun of it, but to make the compiler more stable, efficient
 363  and ANSI compliant
 364 \begin_inset LatexCommand \index{ANSI-compliance}
 365
 366 \end_inset
 367
 368  (see section
 369 \begin_inset LatexCommand \ref{sub:ANSI-Compliance}
 370
 371 \end_inset
 372
 373  for ANSI-Compliance).
 374
 375 \newline
 376
 377 \layout Itemize
 378
 379 short is now equivalent to int (16 bits), it used to be equivalent to char
 380  (8 bits) which is not ANSI compliant.
 381 \layout Itemize
 382
 383 the default directory for gcc-builds where include, library and documentation
 384  files are stored is now in /usr/local/share.
 385 \layout Itemize
 386
 387 char type parameters to vararg functions are casted to int unless explicitly
 388  casted, e.g.:
 389 \newline
 390
 391 \family typewriter
 392 \SpecialChar ~
 393 \SpecialChar ~
 394 char a=3;
 395 \newline
 396 \SpecialChar ~
 397 \SpecialChar ~
 398 printf ("%d %c
 399 \backslash
 400 n", a, (char)a);
 401 \family default
 402
 403 \newline
 404  will push a as an int and as a char resp.
 405 \layout Itemize
 406
 407 option -
 408 \begin_inset ERT
 409 status Collapsed
 410
 411 \layout Standard
 412
 413 \backslash
 414 /
 415 \end_inset
 416
 417 -regextend has been removed.
 418 \layout Itemize
 419
 420 option -
 421 \begin_inset ERT
 422 status Collapsed
 423
 424 \layout Standard
 425
 426 \backslash
 427 /
 428 \end_inset
 429
 430 -noregparms has been removed.
 431 \layout Itemize
 432
 433 option -
 434 \begin_inset ERT
 435 status Collapsed
 436
 437 \layout Standard
 438
 439 \backslash
 440 /
 441 \end_inset
 442
 443 -stack-after-data has been removed.
 444 \layout Itemize
 445
 446 bit
 447 \begin_inset LatexCommand \index{bit}
 448
 449 \end_inset
 450
 451  and sbit
 452 \begin_inset LatexCommand \index{sbit}
 453
 454 \end_inset
 455
 456
 457 \begin_inset LatexCommand \index{\_\_sbit}
 458
 459 \end_inset
 460
 461  types now consistently behave like the C99 _Bool type with respect to type
 462  conversion
 463 \begin_inset LatexCommand \index{type conversion}
 464
 465 \end_inset
 466
 467
 468 \begin_inset LatexCommand \index{type promotion}
 469
 470 \end_inset
 471
 472 .
 473  The most common incompatibility resulting from this change is related to
 474  bit toggling
 475 \begin_inset LatexCommand \index{Bit toggling}
 476
 477 \end_inset
 478
 479  idioms, e.g.:
 480 \newline
 481
 482 \family typewriter
 483 \SpecialChar ~
 484 \SpecialChar ~
 485 bit b;
 486 \newline
 487 \SpecialChar ~
 488 \SpecialChar ~
 489 b = ~b; /* equivalent to b=1 instead of toggling b */
 490 \newline
 491 \SpecialChar ~
 492 \SpecialChar ~
 493 b = !b; /* toggles b */
 494 \newline
 495
 496 \family default
 497 In previous versions, both forms would have toggled the bit.
 498 \layout Standard
 499
 500
 501 \emph on
 502 <pending: more incompatibilities?>
 503 \layout Section
 504
 505 System Requirements
 506 \layout Standard
 507
 508 What do you need before you start installation of SDCC? A computer, and
 509  a desire to compute.
 510  The preferred method of installation is to compile SDCC from source using
 511  GNU gcc and make.
 512  For Windows some pre-compiled binary distributions are available for your
 513  convenience.
 514  You should have some experience with command line tools and compiler use.
 515 \layout Section
 516
 517 Other Resources
 518 \layout Standard
 519
 520 The SDCC home page at
 521 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
 522
 523 \end_inset
 524
 525  is a great place to find distribution sets.
 526  You can also find links to the user mailing lists that offer help or discuss
 527  SDCC with other SDCC users.
 528  Web links to other SDCC related sites can also be found here.
 529  This document can be found in the DOC directory of the source package as
 530  a text or HTML file.
 531  A pdf version of this document is available at
 532 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
 533
 534 \end_inset
 535
 536 .
 537  Some of the other tools (simulator and assembler) included with SDCC contain
 538  their own documentation and can be found in the source distribution.
 539  If you want the latest unreleased software, the complete source package
 540  is available directly by anonymous CVS on cvs.sdcc.sourceforge.net.
 541 \layout Section
 542
 543 Wishes for the future
 544 \layout Standard
 545
 546 There are (and always will be) some things that could be done.
 547  Here are some I can think of:
 548 \newline
 549
 550 \layout Standard
 551
 552
 553 \family typewriter
 554 char KernelFunction3(char p) at 0x340;
 555 \newline
 556
 557 \layout Standard
 558
 559
 560 \family typewriter
 561 better code banking
 562 \begin_inset LatexCommand \index{code banking (limited support)}
 563
 564 \end_inset
 565
 566  support for mcs51
 567 \newline
 568
 569 \newline
 570
 571 \family default
 572 If you can think of some more, please see the section
 573 \begin_inset LatexCommand \ref{sub:Requesting-Features}
 574
 575 \end_inset
 576
 577  about filing feature requests
 578 \begin_inset LatexCommand \index{Requesting features}
 579
 580 \end_inset
 581
 582
 583 \begin_inset LatexCommand \index{Feature request}
 584
 585 \end_inset
 586
 587 .
 588 \newline
 589
 590 \layout Chapter
 591
 592 Installing SDCC
 593 \begin_inset LatexCommand \index{Installation}
 594
 595 \end_inset
 596
 597
 598 \layout Standard
 599
 600 For most users it is sufficient to skip to either section
 601 \begin_inset LatexCommand \ref{sub:Building-SDCC-on-Linux}
 602
 603 \end_inset
 604
 605  or section
 606 \begin_inset LatexCommand \ref{sub:Windows-Install}
 607
 608 \end_inset
 609
 610 .
 611  More detailled instructions follow below.
 612 \layout Section
 613
 614 Configure Options
 615 \begin_inset LatexCommand \index{Options SDCC configuration}
 616
 617 \end_inset
 618
 619
 620 \layout Standard
 621
 622 The install paths, search paths and other options are defined when running
 623  'configure'.
 624  The defaults can be overridden by:
 625 \layout List
 626 \labelwidthstring 00.00.0000
 627
 628 -
 629 \begin_inset ERT
 630 status Collapsed
 631
 632 \layout Standard
 633
 634 \backslash
 635 /
 636 \end_inset
 637
 638 -prefix see table below
 639 \layout List
 640 \labelwidthstring 00.00.0000
 641
 642 -
 643 \begin_inset ERT
 644 status Collapsed
 645
 646 \layout Standard
 647
 648 \backslash
 649 /
 650 \end_inset
 651
 652 -exec_prefix see table below
 653 \layout List
 654 \labelwidthstring 00.00.0000
 655
 656 -
 657 \begin_inset ERT
 658 status Collapsed
 659
 660 \layout Standard
 661
 662 \backslash
 663 /
 664 \end_inset
 665
 666 -bindir see table below
 667 \layout List
 668 \labelwidthstring 00.00.0000
 669
 670 -
 671 \begin_inset ERT
 672 status Collapsed
 673
 674 \layout Standard
 675
 676 \backslash
 677 /
 678 \end_inset
 679
 680 -datadir see table below
 681 \layout List
 682 \labelwidthstring 00.00.0000
 683
 684 docdir environment variable, see table below
 685 \layout List
 686 \labelwidthstring 00.00.0000
 687
 688 include_dir_suffix environment variable, see table below
 689 \layout List
 690 \labelwidthstring 00.00.0000
 691
 692 lib_dir_suffix environment variable, see table below
 693 \layout List
 694 \labelwidthstring 00.00.0000
 695
 696 sdccconf_h_dir_separator environment variable, either / or
 697 \backslash
 698
 699 \backslash
 700  makes sense here.
 701  This character will only be used in sdccconf.h; don't forget it's a C-header,
 702  therefore a double-backslash is needed there.
 703 \layout List
 704 \labelwidthstring 00.00.0000
 705
 706 -
 707 \begin_inset ERT
 708 status Collapsed
 709
 710 \layout Standard
 711
 712 \backslash
 713 /
 714 \end_inset
 715
 716 -disable-mcs51-port Excludes the Intel mcs51 port
 717 \layout List
 718 \labelwidthstring 00.00.0000
 719
 720 -
 721 \begin_inset ERT
 722 status Collapsed
 723
 724 \layout Standard
 725
 726 \backslash
 727 /
 728 \end_inset
 729
 730 -disable-gbz80-port Excludes the Gameboy gbz80 port
 731 \layout List
 732 \labelwidthstring 00.00.0000
 733
 734 -
 735 \begin_inset ERT
 736 status Collapsed
 737
 738 \layout Standard
 739
 740 \backslash
 741 /
 742 \end_inset
 743
 744 -disable-z80-port Excludes the z80 port
 745 \layout List
 746 \labelwidthstring 00.00.0000
 747
 748 -
 749 \begin_inset ERT
 750 status Collapsed
 751
 752 \layout Standard
 753
 754 \backslash
 755 /
 756 \end_inset
 757
 758 -disable-avr-port Excludes the AVR port
 759 \layout List
 760 \labelwidthstring 00.00.0000
 761
 762 -
 763 \begin_inset ERT
 764 status Collapsed
 765
 766 \layout Standard
 767
 768 \backslash
 769 /
 770 \end_inset
 771
 772 -disable-ds390-port Excludes the DS390 port
 773 \layout List
 774 \labelwidthstring 00.00.0000
 775
 776 -
 777 \begin_inset ERT
 778 status Collapsed
 779
 780 \layout Standard
 781
 782 \backslash
 783 /
 784 \end_inset
 785
 786 -disable-hc08-port Excludes the HC08 port
 787 \layout List
 788 \labelwidthstring 00.00.0000
 789
 790 -
 791 \begin_inset ERT
 792 status Collapsed
 793
 794 \layout Standard
 795
 796 \backslash
 797 /
 798 \end_inset
 799
 800 -disable-pic-port Excludes the PIC port
 801 \layout List
 802 \labelwidthstring 00.00.0000
 803
 804 -
 805 \begin_inset ERT
 806 status Collapsed
 807
 808 \layout Standard
 809
 810 \backslash
 811 /
 812 \end_inset
 813
 814 -disable-xa51-port Excludes the XA51 port
 815 \layout List
 816 \labelwidthstring 00.00.0000
 817
 818 -
 819 \begin_inset ERT
 820 status Collapsed
 821
 822 \layout Standard
 823
 824 \backslash
 825 /
 826 \end_inset
 827
 828 -disable-ucsim Disables configuring and building of ucsim
 829 \layout List
 830 \labelwidthstring 00.00.0000
 831
 832 -
 833 \begin_inset ERT
 834 status Collapsed
 835
 836 \layout Standard
 837
 838 \backslash
 839 /
 840 \end_inset
 841
 842 -disable-device-lib-build Disables automatically building device libraries
 843 \layout List
 844 \labelwidthstring 00.00.0000
 845
 846 -
 847 \begin_inset ERT
 848 status Collapsed
 849
 850 \layout Standard
 851
 852 \backslash
 853 /
 854 \end_inset
 855
 856 -disable-packihx Disables building packihx
 857 \layout List
 858 \labelwidthstring 00.00.0000
 859
 860 -
 861 \begin_inset ERT
 862 status Collapsed
 863
 864 \layout Standard
 865
 866 \backslash
 867 /
 868 \end_inset
 869
 870 -enable-libgc Use the Bohem memory allocator.
 871  Lower runtime footprint.
 872 \layout Standard
 873
 874 Furthermore the environment variables CC, CFLAGS, ...
 875  the tools and their arguments can be influenced.
 876  Please see `configure -
 877 \begin_inset ERT
 878 status Collapsed
 879
 880 \layout Standard
 881
 882 \backslash
 883 /
 884 \end_inset
 885
 886 -help` and the man/info pages of `configure` for details.
 887 \newline
 888
 889 \newline
 890 The names of the standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB,
 891  STD_FP_LIB, STD_DS390_LIB, STD_XA51_LIB and the environment variables SDCC_DIR_
 892 NAME, SDCC_INCLUDE_NAME, SDCC_LIB_NAME are defined by `configure` too.
 893  At the moment it's not possible to change the default settings (it was
 894  simply never required).
 895 \newline
 896
 897 \newline
 898 These configure options are compiled into the binaries, and can only be
 899  changed by rerunning 'configure' and recompiling SDCC.
 900  The configure options are written in
 901 \emph on
 902 italics
 903 \emph default
 904  to distinguish them from run time environment variables (see section search
 905  paths).
 906 \newline
 907
 908 \newline
 909 The settings for
 910 \begin_inset Quotes sld
 911 \end_inset
 912
 913 Win32 builds
 914 \begin_inset Quotes srd
 915 \end_inset
 916
 917  are used by the SDCC team to build the official Win32 binaries.
 918  The SDCC team uses Mingw32 to build the official Windows binaries, because
 919  it's
 920 \layout Enumerate
 921
 922 open source,
 923 \layout Enumerate
 924
 925 a gcc compiler and last but not least
 926 \layout Enumerate
 927
 928 the binaries can be built by cross compiling on Sourceforge's compile farm.
 929 \layout Standard
 930
 931 See the examples, how to pass the Win32 settings to 'configure'.
 932  The other Win32 builds using Borland, VC or whatever don't use 'configure',
 933  but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
 934  for Win32.
 935 \newline
 936
 937 \newline
 938 These defaults are:
 939 \newline
 940
 941 \layout Standard
 942 \align center
 943
 944 \begin_inset  Tabular
 945 <lyxtabular version="3" rows="8" columns="3">
 946 <features>
 947 <column alignment="block" valignment="top" leftline="true" width="0in">
 948 <column alignment="block" valignment="top" leftline="true" width="0in">
 949 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
 950 <row topline="true" bottomline="true">
 951 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 952 \begin_inset Text
 953
 954 \layout Standard
 955
 956 Variable
 957 \end_inset
 958 </cell>
 959 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 960 \begin_inset Text
 961
 962 \layout Standard
 963
 964 default
 965 \end_inset
 966 </cell>
 967 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 968 \begin_inset Text
 969
 970 \layout Standard
 971
 972 Win32 builds
 973 \end_inset
 974 </cell>
 975 </row>
 976 <row topline="true">
 977 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 978 \begin_inset Text
 979
 980 \layout Standard
 981
 982
 983 \emph on
 984 PREFIX
 985 \end_inset
 986 </cell>
 987 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 988 \begin_inset Text
 989
 990 \layout Standard
 991
 992 /usr/local
 993 \end_inset
 994 </cell>
 995 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 996 \begin_inset Text
 997
 998 \layout Standard
 999
1000
1001 \backslash
1002 sdcc
1003 \end_inset
1004 </cell>
1005 </row>
1006 <row topline="true">
1007 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1008 \begin_inset Text
1009
1010 \layout Standard
1011
1012
1013 \emph on
1014 EXEC_PREFIX
1015 \end_inset
1016 </cell>
1017 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1018 \begin_inset Text
1019
1020 \layout Standard
1021
1022
1023 \emph on
1024 $PREFIX
1025 \end_inset
1026 </cell>
1027 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1028 \begin_inset Text
1029
1030 \layout Standard
1031
1032
1033 \emph on
1034 $PREFIX
1035 \end_inset
1036 </cell>
1037 </row>
1038 <row topline="true">
1039 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1040 \begin_inset Text
1041
1042 \layout Standard
1043
1044
1045 \emph on
1046 BINDIR
1047 \end_inset
1048 </cell>
1049 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1050 \begin_inset Text
1051
1052 \layout Standard
1053
1054
1055 \emph on
1056 $EXECPREFIX
1057 \emph default
1058 /bin
1059 \end_inset
1060 </cell>
1061 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1062 \begin_inset Text
1063
1064 \layout Standard
1065
1066
1067 \emph on
1068 $EXECPREFIX
1069 \emph default
1070
1071 \backslash
1072 bin
1073 \end_inset
1074 </cell>
1075 </row>
1076 <row topline="true">
1077 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1078 \begin_inset Text
1079
1080 \layout Standard
1081
1082
1083 \emph on
1084 DATADIR
1085 \end_inset
1086 </cell>
1087 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1088 \begin_inset Text
1089
1090 \layout Standard
1091
1092
1093 \emph on
1094 $PREFIX
1095 \emph default
1096 /share
1097 \end_inset
1098 </cell>
1099 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1100 \begin_inset Text
1101
1102 \layout Standard
1103
1104
1105 \emph on
1106 $PREFIX
1107 \end_inset
1108 </cell>
1109 </row>
1110 <row topline="true">
1111 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1112 \begin_inset Text
1113
1114 \layout Standard
1115
1116
1117 \emph on
1118 DOCDIR
1119 \end_inset
1120 </cell>
1121 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1122 \begin_inset Text
1123
1124 \layout Standard
1125
1126
1127 \emph on
1128 $DATADIR
1129 \emph default
1130 /sdcc/doc
1131 \end_inset
1132 </cell>
1133 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1134 \begin_inset Text
1135
1136 \layout Standard
1137
1138
1139 \emph on
1140 $DATADIR
1141 \emph default
1142
1143 \backslash
1144 doc
1145 \end_inset
1146 </cell>
1147 </row>
1148 <row topline="true">
1149 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1150 \begin_inset Text
1151
1152 \layout Standard
1153
1154
1155 \emph on
1156 INCLUDE_DIR_SUFFIX
1157 \end_inset
1158 </cell>
1159 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1160 \begin_inset Text
1161
1162 \layout Standard
1163
1164 sdcc/include
1165 \end_inset
1166 </cell>
1167 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1168 \begin_inset Text
1169
1170 \layout Standard
1171
1172 include
1173 \end_inset
1174 </cell>
1175 </row>
1176 <row topline="true" bottomline="true">
1177 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1178 \begin_inset Text
1179
1180 \layout Standard
1181
1182
1183 \emph on
1184 LIB_DIR_SUFFIX
1185 \end_inset
1186 </cell>
1187 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1188 \begin_inset Text
1189
1190 \layout Standard
1191
1192 sdcc/lib
1193 \end_inset
1194 </cell>
1195 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1196 \begin_inset Text
1197
1198 \layout Standard
1199
1200 lib
1201 \end_inset
1202 </cell>
1203 </row>
1204 </lyxtabular>
1205
1206 \end_inset
1207
1208
1209 \newline
1210
1211 \layout Standard
1212 \noindent
1213 'configure' also computes relative paths.
1214  This is needed for full relocatability of a binary package and to complete
1215  search paths (see section search paths below):
1216 \newline
1217
1218 \layout Standard
1219 \align center
1220
1221 \begin_inset  Tabular
1222 <lyxtabular version="3" rows="4" columns="3">
1223 <features>
1224 <column alignment="block" valignment="top" leftline="true" width="0in">
1225 <column alignment="block" valignment="top" leftline="true" width="0in">
1226 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1227 <row topline="true" bottomline="true">
1228 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1229 \begin_inset Text
1230
1231 \layout Standard
1232
1233 Variable (computed)
1234 \end_inset
1235 </cell>
1236 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1237 \begin_inset Text
1238
1239 \layout Standard
1240
1241 default
1242 \end_inset
1243 </cell>
1244 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1245 \begin_inset Text
1246
1247 \layout Standard
1248
1249 Win32 builds
1250 \end_inset
1251 </cell>
1252 </row>
1253 <row topline="true" bottomline="true">
1254 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1255 \begin_inset Text
1256
1257 \layout Standard
1258
1259
1260 \emph on
1261 BIN2DATA_DIR
1262 \end_inset
1263 </cell>
1264 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1265 \begin_inset Text
1266
1267 \layout Standard
1268
1269 ../share
1270 \end_inset
1271 </cell>
1272 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1273 \begin_inset Text
1274
1275 \layout Standard
1276
1277 ..
1278 \end_inset
1279 </cell>
1280 </row>
1281 <row bottomline="true">
1282 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1283 \begin_inset Text
1284
1285 \layout Standard
1286
1287
1288 \emph on
1289 PREFIX2BIN_DIR
1290 \end_inset
1291 </cell>
1292 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1293 \begin_inset Text
1294
1295 \layout Standard
1296
1297 bin
1298 \end_inset
1299 </cell>
1300 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1301 \begin_inset Text
1302
1303 \layout Standard
1304
1305 bin
1306 \end_inset
1307 </cell>
1308 </row>
1309 <row bottomline="true">
1310 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1311 \begin_inset Text
1312
1313 \layout Standard
1314
1315
1316 \emph on
1317 PREFIX2DATA_DIR
1318 \end_inset
1319 </cell>
1320 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1321 \begin_inset Text
1322
1323 \layout Standard
1324
1325 share/sdcc
1326 \end_inset
1327 </cell>
1328 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1329 \begin_inset Text
1330
1331 \layout Standard
1332
1333 \end_inset
1334 </cell>
1335 </row>
1336 </lyxtabular>
1337
1338 \end_inset
1339
1340
1341 \newline
1342
1343 \layout Standard
1344 \noindent
1345 Examples:
1346 \layout LyX-Code
1347
1348 ./configure
1349 \newline
1350 ./configure -
1351 \begin_inset ERT
1352 status Collapsed
1353
1354 \layout Standard
1355
1356 \backslash
1357 /
1358 \end_inset
1359
1360 -prefix=
1361 \begin_inset Quotes srd
1362 \end_inset
1363
1364 /usr/bin
1365 \begin_inset Quotes srd
1366 \end_inset
1367
1368  -
1369 \begin_inset ERT
1370 status Collapsed
1371
1372 \layout Standard
1373
1374 \backslash
1375 /
1376 \end_inset
1377
1378 -datadir=
1379 \begin_inset Quotes srd
1380 \end_inset
1381
1382 /usr/share
1383 \begin_inset Quotes srd
1384 \end_inset
1385
1386
1387 \newline
1388 ./configure -
1389 \begin_inset ERT
1390 status Collapsed
1391
1392 \layout Standard
1393
1394 \backslash
1395 /
1396 \end_inset
1397
1398 -disable-avr-port -
1399 \begin_inset ERT
1400 status Collapsed
1401
1402 \layout Standard
1403
1404 \backslash
1405 /
1406 \end_inset
1407
1408 -disable-xa51-port
1409 \layout Standard
1410
1411 To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw
1412 32'):
1413 \layout LyX-Code
1414
1415 ./configure
1416 \backslash
1417
1418 \newline
1419 CC=
1420 \begin_inset Quotes srd
1421 \end_inset
1422
1423 i586-mingw32msvc-gcc
1424 \begin_inset Quotes srd
1425 \end_inset
1426
1427  CXX=
1428 \begin_inset Quotes srd
1429 \end_inset
1430
1431 i586-mingw32msvc-g++
1432 \begin_inset Quotes srd
1433 \end_inset
1434
1435
1436 \backslash
1437
1438 \newline
1439 RANLIB=
1440 \begin_inset Quotes srd
1441 \end_inset
1442
1443 i586-mingw32msvc-ranlib
1444 \begin_inset Quotes srd
1445 \end_inset
1446
1447
1448 \backslash
1449
1450 \newline
1451 STRIP=
1452 \begin_inset Quotes srd
1453 \end_inset
1454
1455 i586-mingw32msvc-strip
1456 \begin_inset Quotes srd
1457 \end_inset
1458
1459
1460 \backslash
1461
1462 \newline
1463 -
1464 \begin_inset ERT
1465 status Collapsed
1466
1467 \layout Standard
1468
1469 \backslash
1470 /
1471 \end_inset
1472
1473 -prefix=
1474 \begin_inset Quotes srd
1475 \end_inset
1476
1477 /sdcc
1478 \begin_inset Quotes srd
1479 \end_inset
1480
1481
1482 \backslash
1483
1484 \newline
1485 -
1486 \begin_inset ERT
1487 status Collapsed
1488
1489 \layout Standard
1490
1491 \backslash
1492 /
1493 \end_inset
1494
1495 -datadir=
1496 \begin_inset Quotes srd
1497 \end_inset
1498
1499 /sdcc
1500 \begin_inset Quotes srd
1501 \end_inset
1502
1503
1504 \backslash
1505
1506 \newline
1507 docdir=
1508 \begin_inset Quotes srd
1509 \end_inset
1510
1511 /sdcc/doc
1512 \begin_inset Quotes srd
1513 \end_inset
1514
1515
1516 \backslash
1517
1518 \newline
1519 include_dir_suffix=
1520 \begin_inset Quotes srd
1521 \end_inset
1522
1523 include
1524 \begin_inset Quotes srd
1525 \end_inset
1526
1527
1528 \backslash
1529
1530 \newline
1531 lib_dir_suffix=
1532 \begin_inset Quotes srd
1533 \end_inset
1534
1535 lib
1536 \begin_inset Quotes srd
1537 \end_inset
1538
1539
1540 \backslash
1541
1542 \newline
1543 sdccconf_h_dir_separator=
1544 \begin_inset Quotes srd
1545 \end_inset
1546
1547
1548 \backslash
1549
1550 \backslash
1551
1552 \backslash
1553
1554 \backslash
1555
1556 \begin_inset Quotes srd
1557 \end_inset
1558
1559
1560 \backslash
1561
1562 \newline
1563 -
1564 \begin_inset ERT
1565 status Collapsed
1566
1567 \layout Standard
1568
1569 \backslash
1570 /
1571 \end_inset
1572
1573 -disable-device-lib-build
1574 \backslash
1575
1576 \newline
1577 -
1578 \begin_inset ERT
1579 status Collapsed
1580
1581 \layout Standard
1582
1583 \backslash
1584 /
1585 \end_inset
1586
1587 -disable-ucsim
1588 \backslash
1589
1590 \newline
1591 -
1592 \begin_inset ERT
1593 status Collapsed
1594
1595 \layout Standard
1596
1597 \backslash
1598 /
1599 \end_inset
1600
1601 -host=i586-mingw32msvc -
1602 \begin_inset ERT
1603 status Collapsed
1604
1605 \layout Standard
1606
1607 \backslash
1608 /
1609 \end_inset
1610
1611 -build=unknown-unknown-linux-gnu
1612 \layout Standard
1613
1614 To
1615 \begin_inset Quotes sld
1616 \end_inset
1617
1618 cross
1619 \begin_inset Quotes srd
1620 \end_inset
1621
1622 compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32
1623 ):
1624 \layout LyX-Code
1625
1626 ./configure -C
1627 \backslash
1628
1629 \newline
1630 CFLAGS=
1631 \begin_inset Quotes srd
1632 \end_inset
1633
1634 -mno-cygwin -O2
1635 \begin_inset Quotes srd
1636 \end_inset
1637
1638
1639 \backslash
1640
1641 \newline
1642 LDFLAGS=
1643 \begin_inset Quotes srd
1644 \end_inset
1645
1646 -mno-cygwin
1647 \begin_inset Quotes srd
1648 \end_inset
1649
1650
1651 \backslash
1652
1653 \newline
1654 -
1655 \begin_inset ERT
1656 status Collapsed
1657
1658 \layout Standard
1659
1660 \backslash
1661 /
1662 \end_inset
1663
1664 -prefix=
1665 \begin_inset Quotes srd
1666 \end_inset
1667
1668 /sdcc
1669 \begin_inset Quotes srd
1670 \end_inset
1671
1672
1673 \backslash
1674
1675 \newline
1676 -
1677 \begin_inset ERT
1678 status Collapsed
1679
1680 \layout Standard
1681
1682 \backslash
1683 /
1684 \end_inset
1685
1686 -datadir=
1687 \begin_inset Quotes srd
1688 \end_inset
1689
1690 /sdcc
1691 \begin_inset Quotes srd
1692 \end_inset
1693
1694
1695 \backslash
1696
1697 \newline
1698 docdir=
1699 \begin_inset Quotes srd
1700 \end_inset
1701
1702 /sdcc/doc
1703 \begin_inset Quotes srd
1704 \end_inset
1705
1706
1707 \backslash
1708
1709 \newline
1710 include_dir_suffix=
1711 \begin_inset Quotes srd
1712 \end_inset
1713
1714 include
1715 \begin_inset Quotes srd
1716 \end_inset
1717
1718
1719 \backslash
1720
1721 \newline
1722 lib_dir_suffix=
1723 \begin_inset Quotes srd
1724 \end_inset
1725
1726 lib
1727 \begin_inset Quotes srd
1728 \end_inset
1729
1730
1731 \backslash
1732
1733 \newline
1734 sdccconf_h_dir_separator=
1735 \begin_inset Quotes srd
1736 \end_inset
1737
1738
1739 \backslash
1740
1741 \backslash
1742
1743 \backslash
1744
1745 \backslash
1746
1747 \begin_inset Quotes srd
1748 \end_inset
1749
1750
1751 \backslash
1752
1753 \newline
1754 -
1755 \begin_inset ERT
1756 status Collapsed
1757
1758 \layout Standard
1759
1760 \backslash
1761 /
1762 \end_inset
1763
1764 -disable-ucsim
1765 \layout Standard
1766
1767 'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
1768  The option '-
1769 \begin_inset ERT
1770 status Collapsed
1771
1772 \layout Standard
1773
1774 \backslash
1775 /
1776 \end_inset
1777
1778 -C' turns on caching, which gives a little bit extra speed.
1779  However if options are changed, it can be necessary to delete the config.cache
1780  file.
1781 \layout Section
1782
1783 Install paths
1784 \begin_inset LatexCommand \label{sub:Install-paths}
1785
1786 \end_inset
1787
1788
1789 \begin_inset LatexCommand \index{Install paths}
1790
1791 \end_inset
1792
1793
1794 \layout Standard
1795 \added_space_top medskip \align center
1796
1797 \begin_inset  Tabular
1798 <lyxtabular version="3" rows="5" columns="4">
1799 <features>
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" width="0">
1803 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
1804 <row topline="true" bottomline="true">
1805 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1806 \begin_inset Text
1807
1808 \layout Standard
1809
1810
1811 \series bold
1812 Description
1813 \end_inset
1814 </cell>
1815 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1816 \begin_inset Text
1817
1818 \layout Standard
1819
1820
1821 \series bold
1822 Path
1823 \end_inset
1824 </cell>
1825 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1826 \begin_inset Text
1827
1828 \layout Standard
1829
1830
1831 \series bold
1832 Default
1833 \end_inset
1834 </cell>
1835 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1836 \begin_inset Text
1837
1838 \layout Standard
1839
1840
1841 \series bold
1842 Win32 builds
1843 \end_inset
1844 </cell>
1845 </row>
1846 <row topline="true">
1847 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1848 \begin_inset Text
1849
1850 \layout Standard
1851
1852 Binary files*
1853 \end_inset
1854 </cell>
1855 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1856 \begin_inset Text
1857
1858 \layout Standard
1859
1860
1861 \emph on
1862 $EXEC_PREFIX
1863 \end_inset
1864 </cell>
1865 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1866 \begin_inset Text
1867
1868 \layout Standard
1869
1870 /usr/local/bin
1871 \end_inset
1872 </cell>
1873 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1874 \begin_inset Text
1875
1876 \layout Standard
1877
1878
1879 \backslash
1880 sdcc
1881 \backslash
1882 bin
1883 \end_inset
1884 </cell>
1885 </row>
1886 <row topline="true">
1887 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1888 \begin_inset Text
1889
1890 \layout Standard
1891
1892 Include files
1893 \end_inset
1894 </cell>
1895 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1896 \begin_inset Text
1897
1898 \layout Standard
1899
1900
1901 \emph on
1902 $DATADIR/ $INCLUDE_DIR_SUFFIX
1903 \end_inset
1904 </cell>
1905 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1906 \begin_inset Text
1907
1908 \layout Standard
1909
1910 /usr/local/share/sdcc/include
1911 \end_inset
1912 </cell>
1913 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1914 \begin_inset Text
1915
1916 \layout Standard
1917
1918
1919 \backslash
1920 sdcc
1921 \backslash
1922 include
1923 \end_inset
1924 </cell>
1925 </row>
1926 <row topline="true">
1927 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1928 \begin_inset Text
1929
1930 \layout Standard
1931
1932 Library file**
1933 \end_inset
1934 </cell>
1935 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1936 \begin_inset Text
1937
1938 \layout Standard
1939
1940
1941 \emph on
1942 $DATADIR/$LIB_DIR_SUFFIX
1943 \end_inset
1944 </cell>
1945 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1946 \begin_inset Text
1947
1948 \layout Standard
1949
1950 /usr/local/share/sdcc/lib
1951 \end_inset
1952 </cell>
1953 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1954 \begin_inset Text
1955
1956 \layout Standard
1957
1958
1959 \backslash
1960 sdcc
1961 \backslash
1962 lib
1963 \end_inset
1964 </cell>
1965 </row>
1966 <row topline="true" bottomline="true">
1967 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1968 \begin_inset Text
1969
1970 \layout Standard
1971
1972 Documentation
1973 \end_inset
1974 </cell>
1975 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1976 \begin_inset Text
1977
1978 \layout Standard
1979
1980
1981 \emph on
1982 $DOCDIR
1983 \end_inset
1984 </cell>
1985 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1986 \begin_inset Text
1987
1988 \layout Standard
1989
1990 /usr/local/share/sdcc/doc
1991 \end_inset
1992 </cell>
1993 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1994 \begin_inset Text
1995
1996 \layout Standard
1997
1998
1999 \backslash
2000 sdcc
2001 \backslash
2002 doc
2003 \end_inset
2004 </cell>
2005 </row>
2006 </lyxtabular>
2007
2008 \end_inset
2009
2010
2011 \layout Verse
2012
2013
2014 \size footnotesize
2015 *compiler, preprocessor, assembler, and linker
2016 \newline
2017 **the
2018 \shape italic
2019 model
2020 \shape default
2021  is auto-appended by the compiler, e.g.
2022  small, large, z80, ds390 etc
2023 \layout Standard
2024 \noindent
2025 The install paths can still be changed during `make install` with e.g.:
2026 \layout LyX-Code
2027
2028 make install prefix=$(HOME)/local/sdcc
2029 \layout Standard
2030
2031 Of course this doesn't change the search paths compiled into the binaries.
2032 \newline
2033
2034 \newline
2035 Moreover the install path can be changed by defining DESTDIR
2036 \begin_inset LatexCommand \index{DESTDIR}
2037
2038 \end_inset
2039
2040 :
2041 \layout LyX-Code
2042
2043 make install DESTDIR=$(HOME)/sdcc.rpm/
2044 \layout Standard
2045
2046 Please note that DESTDIR must have a trailing slash!
2047 \layout Section
2048
2049 Search Paths
2050 \begin_inset LatexCommand \label{sub:Search-Paths}
2051
2052 \end_inset
2053
2054
2055 \begin_inset LatexCommand \index{Search path}
2056
2057 \end_inset
2058
2059
2060 \layout Standard
2061
2062 Some search paths or parts of them are determined by configure variables
2063  (in
2064 \emph on
2065 italics
2066 \emph default
2067 , see section above).
2068  Further search paths are determined by environment variables during runtime.
2069
2070 \newline
2071 The paths searched when running the compiler are as follows (the first catch
2072  wins):
2073 \newline
2074
2075 \newline
2076 1.
2077  Binary files (preprocessor, assembler and linker)
2078 \newline
2079
2080 \layout Standard
2081 \align center
2082
2083 \begin_inset  Tabular
2084 <lyxtabular version="3" rows="4" columns="3">
2085 <features>
2086 <column alignment="block" valignment="top" leftline="true" width="0in">
2087 <column alignment="block" valignment="top" leftline="true" width="0in">
2088 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2089 <row topline="true" bottomline="true">
2090 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2091 \begin_inset Text
2092
2093 \layout Standard
2094
2095 Search path
2096 \end_inset
2097 </cell>
2098 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2099 \begin_inset Text
2100
2101 \layout Standard
2102
2103 default
2104 \end_inset
2105 </cell>
2106 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2107 \begin_inset Text
2108
2109 \layout Standard
2110
2111 Win32 builds
2112 \end_inset
2113 </cell>
2114 </row>
2115 <row topline="true">
2116 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2117 \begin_inset Text
2118
2119 \layout Standard
2120
2121 $SDCC_HOME/
2122 \emph on
2123 $PPREFIX2BIN_DIR
2124 \end_inset
2125 </cell>
2126 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2127 \begin_inset Text
2128
2129 \layout Standard
2130
2131 $SDCC_HOME/bin
2132 \end_inset
2133 </cell>
2134 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2135 \begin_inset Text
2136
2137 \layout Standard
2138
2139 $SDCC_HOME
2140 \backslash
2141 bin
2142 \end_inset
2143 </cell>
2144 </row>
2145 <row topline="true">
2146 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2147 \begin_inset Text
2148
2149 \layout Standard
2150
2151 Path of argv[0] (if available)
2152 \end_inset
2153 </cell>
2154 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2155 \begin_inset Text
2156
2157 \layout Standard
2158
2159 Path of argv[0]
2160 \end_inset
2161 </cell>
2162 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2163 \begin_inset Text
2164
2165 \layout Standard
2166
2167 Path of argv[0]
2168 \end_inset
2169 </cell>
2170 </row>
2171 <row topline="true" bottomline="true">
2172 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2173 \begin_inset Text
2174
2175 \layout Standard
2176
2177 $PATH
2178 \end_inset
2179 </cell>
2180 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2181 \begin_inset Text
2182
2183 \layout Standard
2184
2185 $PATH
2186 \end_inset
2187 </cell>
2188 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2189 \begin_inset Text
2190
2191 \layout Standard
2192
2193 $PATH
2194 \end_inset
2195 </cell>
2196 </row>
2197 </lyxtabular>
2198
2199 \end_inset
2200
2201
2202 \newline
2203
2204 \layout Standard
2205 \noindent
2206 2.
2207  Include files
2208 \newline
2209
2210 \layout Standard
2211 \align center
2212
2213 \begin_inset  Tabular
2214 <lyxtabular version="3" rows="6" columns="3">
2215 <features>
2216 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2217 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2218 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2219 <row topline="true" bottomline="true">
2220 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2221 \begin_inset Text
2222
2223 \layout Standard
2224
2225 Search path
2226 \end_inset
2227 </cell>
2228 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2229 \begin_inset Text
2230
2231 \layout Standard
2232
2233 default
2234 \end_inset
2235 </cell>
2236 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2237 \begin_inset Text
2238
2239 \layout Standard
2240
2241 Win32 builds
2242 \end_inset
2243 </cell>
2244 </row>
2245 <row topline="true">
2246 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2247 \begin_inset Text
2248
2249 \layout Standard
2250
2251 -
2252 \begin_inset ERT
2253 status Collapsed
2254
2255 \layout Standard
2256
2257 \backslash
2258 /
2259 \end_inset
2260
2261 -I dir
2262 \end_inset
2263 </cell>
2264 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2265 \begin_inset Text
2266
2267 \layout Standard
2268
2269 -
2270 \begin_inset ERT
2271 status Collapsed
2272
2273 \layout Standard
2274
2275 \backslash
2276 /
2277 \end_inset
2278
2279 -I dir
2280 \end_inset
2281 </cell>
2282 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2283 \begin_inset Text
2284
2285 \layout Standard
2286
2287 -
2288 \begin_inset ERT
2289 status Collapsed
2290
2291 \layout Standard
2292
2293 \backslash
2294 /
2295 \end_inset
2296
2297 -I dir
2298 \end_inset
2299 </cell>
2300 </row>
2301 <row topline="true">
2302 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2303 \begin_inset Text
2304
2305 \layout Standard
2306
2307 $SDCC_INCLUDE
2308 \end_inset
2309 </cell>
2310 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2311 \begin_inset Text
2312
2313 \layout Standard
2314
2315 $SDCC_INCLUDE
2316 \end_inset
2317 </cell>
2318 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2319 \begin_inset Text
2320
2321 \layout Standard
2322
2323 $SDCC_INCLUDE
2324 \end_inset
2325 </cell>
2326 </row>
2327 <row topline="true">
2328 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2329 \begin_inset Text
2330
2331 \layout Standard
2332
2333 $SDCC_HOME/
2334 \newline
2335
2336 \emph on
2337 $PREFIX2DATA_DIR/
2338 \newline
2339 $INCLUDE_DIR_SUFFIX
2340 \end_inset
2341 </cell>
2342 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2343 \begin_inset Text
2344
2345 \layout Standard
2346
2347 $SDCC_ HOME/
2348 \newline
2349 share/sdcc/
2350 \newline
2351 include
2352 \end_inset
2353 </cell>
2354 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2355 \begin_inset Text
2356
2357 \layout Standard
2358
2359 $SDCC_HOME
2360 \backslash
2361 include
2362 \end_inset
2363 </cell>
2364 </row>
2365 <row topline="true">
2366 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2367 \begin_inset Text
2368
2369 \layout Standard
2370
2371 path(argv[0])/
2372 \newline
2373
2374 \emph on
2375 $BIN2DATADIR/
2376 \emph default
2377
2378 \newline
2379
2380 \emph on
2381 $INCLUDE_DIR_SUFFIX
2382 \end_inset
2383 </cell>
2384 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2385 \begin_inset Text
2386
2387 \layout Standard
2388
2389 path(argv[0])/
2390 \newline
2391 ../sdcc/include
2392 \newline
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 \SpecialChar ~
2431
2432 \end_inset
2433 </cell>
2434 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2435 \begin_inset Text
2436
2437 \layout Standard
2438
2439 path(argv[0])
2440 \backslash
2441 ..
2442 \backslash
2443 include
2444 \end_inset
2445 </cell>
2446 </row>
2447 <row topline="true" bottomline="true">
2448 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2449 \begin_inset Text
2450
2451 \layout Standard
2452
2453
2454 \emph on
2455 $DATADIR/
2456 \emph default
2457
2458 \newline
2459
2460 \emph on
2461 $INCLUDE_DIR_SUFFIX
2462 \end_inset
2463 </cell>
2464 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2465 \begin_inset Text
2466
2467 \layout Standard
2468
2469 /usr/local/share/sdcc/
2470 \newline
2471 include
2472 \end_inset
2473 </cell>
2474 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2475 \begin_inset Text
2476
2477 \layout Standard
2478
2479 (not on Win32)
2480 \end_inset
2481 </cell>
2482 </row>
2483 </lyxtabular>
2484
2485 \end_inset
2486
2487
2488 \newline
2489
2490 \layout Standard
2491 \noindent
2492 The option -
2493 \begin_inset ERT
2494 status Collapsed
2495
2496 \layout Standard
2497
2498 \backslash
2499 /
2500 \end_inset
2501
2502 -nostdinc disables the last two search paths.
2503 \newline
2504
2505 \newline
2506 3.
2507  Library files
2508 \newline
2509
2510 \layout Standard
2511
2512 With the exception of
2513 \begin_inset Quotes sld
2514 \end_inset
2515
2516 -
2517 \begin_inset ERT
2518 status Collapsed
2519
2520 \layout Standard
2521
2522 \backslash
2523 /
2524 \end_inset
2525
2526 -L dir
2527 \begin_inset Quotes srd
2528 \end_inset
2529
2530  the
2531 \shape italic
2532 model
2533 \shape default
2534  is auto-appended by the compiler (e.g.
2535  small, large, z80, ds390 etc.).
2536
2537 \newline
2538
2539 \layout Standard
2540 \align center
2541
2542 \begin_inset  Tabular
2543 <lyxtabular version="3" rows="6" columns="3">
2544 <features>
2545 <column alignment="block" valignment="top" leftline="true" width="1.7in">
2546 <column alignment="block" valignment="top" leftline="true" width="1.2in">
2547 <column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
2548 <row topline="true" bottomline="true">
2549 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2550 \begin_inset Text
2551
2552 \layout Standard
2553
2554 Search path
2555 \end_inset
2556 </cell>
2557 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2558 \begin_inset Text
2559
2560 \layout Standard
2561
2562 default
2563 \end_inset
2564 </cell>
2565 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2566 \begin_inset Text
2567
2568 \layout Standard
2569
2570 Win32 builds
2571 \end_inset
2572 </cell>
2573 </row>
2574 <row topline="true">
2575 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2576 \begin_inset Text
2577
2578 \layout Standard
2579
2580 -
2581 \begin_inset ERT
2582 status Collapsed
2583
2584 \layout Standard
2585
2586 \backslash
2587 /
2588 \end_inset
2589
2590 -L dir
2591 \end_inset
2592 </cell>
2593 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2594 \begin_inset Text
2595
2596 \layout Standard
2597
2598 -
2599 \begin_inset ERT
2600 status Collapsed
2601
2602 \layout Standard
2603
2604 \backslash
2605 /
2606 \end_inset
2607
2608 -L dir
2609 \end_inset
2610 </cell>
2611 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2612 \begin_inset Text
2613
2614 \layout Standard
2615
2616 -
2617 \begin_inset ERT
2618 status Collapsed
2619
2620 \layout Standard
2621
2622 \backslash
2623 /
2624 \end_inset
2625
2626 -L dir
2627 \end_inset
2628 </cell>
2629 </row>
2630 <row topline="true">
2631 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2632 \begin_inset Text
2633
2634 \layout Standard
2635
2636 $SDCC_LIB/
2637 \newline
2638
2639 \emph on
2640 <model>
2641 \end_inset
2642 </cell>
2643 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2644 \begin_inset Text
2645
2646 \layout Standard
2647
2648 $SDCC_LIB/
2649 \newline
2650
2651 \emph on
2652 <model>
2653 \end_inset
2654 </cell>
2655 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2656 \begin_inset Text
2657
2658 \layout Standard
2659
2660 $SDCC_LIB
2661 \backslash
2662
2663 \newline
2664
2665 \emph on
2666 <model>
2667 \end_inset
2668 </cell>
2669 </row>
2670 <row topline="true">
2671 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2672 \begin_inset Text
2673
2674 \layout Standard
2675
2676 $SDCC_HOME/
2677 \newline
2678
2679 \emph on
2680 $PREFIX2DATA_DIR/
2681 \newline
2682 $LIB_DIR_SUFFIX/<model>
2683 \end_inset
2684 </cell>
2685 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2686 \begin_inset Text
2687
2688 \layout Standard
2689
2690 $SDCC_HOME/
2691 \newline
2692 share/sdcc/
2693 \newline
2694 lib/
2695 \emph on
2696 <model>
2697 \end_inset
2698 </cell>
2699 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2700 \begin_inset Text
2701
2702 \layout Standard
2703
2704 $SDCC_HOME
2705 \backslash
2706 lib
2707 \backslash
2708
2709 \emph on
2710
2711 \newline
2712 <model>
2713 \end_inset
2714 </cell>
2715 </row>
2716 <row topline="true">
2717 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2718 \begin_inset Text
2719
2720 \layout Standard
2721
2722 path(argv[0])/
2723 \newline
2724
2725 \emph on
2726 $BIN2DATADIR/
2727 \emph default
2728
2729 \newline
2730
2731 \emph on
2732 $LIB_DIR_SUFFIX/<model>
2733 \end_inset
2734 </cell>
2735 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2736 \begin_inset Text
2737
2738 \layout Standard
2739
2740 path(argv[0])/
2741 \newline
2742 ../sdcc/lib/
2743 \emph on
2744 <model>
2745 \newline
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 \SpecialChar ~
2785
2786 \end_inset
2787 </cell>
2788 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2789 \begin_inset Text
2790
2791 \layout Standard
2792
2793 path(argv[0])
2794 \backslash
2795
2796 \newline
2797 ..
2798 \backslash
2799 lib
2800 \backslash
2801
2802 \emph on
2803 <model>
2804 \newline
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 \SpecialChar ~
2840
2841 \end_inset
2842 </cell>
2843 </row>
2844 <row topline="true" bottomline="true">
2845 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2846 \begin_inset Text
2847
2848 \layout Standard
2849
2850
2851 \emph on
2852 $DATADIR/
2853 \newline
2854 $LIB_DIR_SUFFIX/<model>
2855 \end_inset
2856 </cell>
2857 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2858 \begin_inset Text
2859
2860 \layout Standard
2861
2862 /usr/local/share/sdcc/
2863 \newline
2864 lib/
2865 \emph on
2866 <model>
2867 \end_inset
2868 </cell>
2869 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2870 \begin_inset Text
2871
2872 \layout Standard
2873
2874 (not on Win32)
2875 \end_inset
2876 </cell>
2877 </row>
2878 </lyxtabular>
2879
2880 \end_inset
2881
2882
2883 \newline
2884
2885 \layout Comment
2886
2887 Don't delete any of the stray spaces in the table above without checking
2888  the HTML output (last line)!
2889 \layout Standard
2890
2891 \SpecialChar ~
2892
2893 \newline
2894 The option -
2895 \begin_inset ERT
2896 status Collapsed
2897
2898 \layout Standard
2899
2900 \backslash
2901 /
2902 \end_inset
2903
2904 -nostdlib disables the last two search paths.
2905 \layout Section
2906
2907 Building SDCC
2908 \begin_inset LatexCommand \index{Building SDCC}
2909
2910 \end_inset
2911
2912
2913 \layout Subsection
2914
2915 Building SDCC on Linux
2916 \begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux}
2917
2918 \end_inset
2919
2920
2921 \layout Enumerate
2922
2923
2924 \series medium
2925 Download the source package
2926 \series default
2927  either from the SDCC CVS repository or from the nightly snapshots
2928 \series medium
2929 , it will be named something like sdcc
2930 \series default
2931 .src
2932 \series medium
2933 .t
2934 \series default
2935 ar.
2936 \series medium
2937 gz
2938 \series default
2939
2940 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
2941
2942 \end_inset
2943
2944 .
2945 \layout Enumerate
2946
2947
2948 \series medium
2949 Bring up a command line terminal, such as xterm.
2950 \layout Enumerate
2951
2952
2953 \series medium
2954 Unpack the file using a command like:
2955 \family sans
2956 \series bold
2957 "tar -xvzf sdcc.src.tar.gz
2958 \family default
2959 \series default
2960 "
2961 \series medium
2962 , this will create a sub-directory called sdcc with all of the sources.
2963 \layout Enumerate
2964
2965 Change directory into the main SDCC directory, for example type:
2966 \family sans
2967 \series bold
2968 "cd sdcc
2969 \series default
2970 ".
2971 \layout Enumerate
2972
2973
2974 \series medium
2975 Type
2976 \family sans
2977 \series bold
2978 "./configure
2979 \family default
2980 \series default
2981 ".
2982  This configures the package for compilation on your system.
2983 \layout Enumerate
2984
2985
2986 \series medium
2987 Type
2988 \family sans
2989 \series bold
2990 "make
2991 \family default
2992 \series default
2993 "
2994 \series medium
2995 .
2996
2997 \series default
2998  All of the source packages will compile, this can take a while.
2999 \layout Enumerate
3000
3001
3002 \series medium
3003 Type
3004 \family sans
3005 \series bold
3006 "make install"
3007 \family default
3008 \series default
3009  as root
3010 \series medium
3011 .
3012
3013 \series default
3014  This copies the binary executables, the include files, the libraries and
3015  the documentation to the install directories.
3016  Proceed with section
3017 \begin_inset LatexCommand \ref{sec:Testing-the-SDCC}
3018
3019 \end_inset
3020
3021 .
3022 \layout Subsection
3023
3024 Building SDCC on OSX 2.x
3025 \layout Standard
3026
3027 Follow the instruction for Linux.
3028 \newline
3029
3030 \newline
3031 On OSX 2.x it was reported, that the default gcc (version 3.1 20020420 (prerelease
3032 )) fails to compile SDCC.
3033  Fortunately there's also gcc 2.9.x installed, which works fine.
3034  This compiler can be selected by running 'configure' with:
3035 \layout LyX-Code
3036
3037 ./configure CC=gcc2 CXX=g++2
3038 \layout Subsection
3039
3040 Cross compiling SDCC on Linux for Windows
3041 \layout Standard
3042
3043 With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
3044  See section 'Configure Options'.
3045 \layout Subsection
3046
3047 Building SDCC on Windows
3048 \layout Standard
3049
3050 With the exception of Cygwin the SDCC binaries uCsim and sdcdb can't be
3051  built on Windows.
3052  They use Unix-sockets, which are not available on Win32.
3053 \layout Subsection
3054
3055 Building SDCC using Cygwin and Mingw32
3056 \layout Standard
3057
3058 For building and installing a Cygwin executable follow the instructions
3059  for Linux.
3060 \newline
3061
3062 \newline
3063 On Cygwin a
3064 \begin_inset Quotes sld
3065 \end_inset
3066
3067 native
3068 \begin_inset Quotes srd
3069 \end_inset
3070
3071  Win32-binary can be built, which will not need the Cygwin-DLL.
3072  For the necessary 'configure' options see section 'configure options' or
3073  the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'.
3074 \newline
3075
3076 \newline
3077 In order to install Cygwin on Windows download setup.exe from
3078 \begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
3079
3080 \end_inset
3081
3082 .
3083  Run it, set the
3084 \begin_inset Quotes sld
3085 \end_inset
3086
3087 default text file type
3088 \begin_inset Quotes srd
3089 \end_inset
3090
3091  to
3092 \begin_inset Quotes sld
3093 \end_inset
3094
3095 unix
3096 \begin_inset Quotes srd
3097 \end_inset
3098
3099  and download/install at least the following packages.
3100  Some packages are selected by default, others will be automatically selected
3101  because of dependencies with the manually selected packages.
3102  Never deselect these packages!
3103 \layout Itemize
3104
3105 flex
3106 \layout Itemize
3107
3108 bison
3109 \layout Itemize
3110
3111 gcc ; version 3.x is fine, no need to use the old 2.9x
3112 \layout Itemize
3113
3114 binutils ; selected with gcc
3115 \layout Itemize
3116
3117 make
3118 \layout Itemize
3119
3120 rxvt ; a nice console, which makes life much easier under windoze (see below)
3121 \layout Itemize
3122
3123 man ; not really needed for building SDCC, but you'll miss it sooner or
3124  later
3125 \layout Itemize
3126
3127 less ; not really needed for building SDCC, but you'll miss it sooner or
3128  later
3129 \layout Itemize
3130
3131 cvs ; only if you use CVS access
3132 \layout Standard
3133
3134 If you want to develop something you'll need:
3135 \layout Itemize
3136
3137 python ; for the regression tests
3138 \layout Itemize
3139
3140 gdb ; the gnu debugger, together with the nice GUI
3141 \begin_inset Quotes sld
3142 \end_inset
3143
3144 insight
3145 \begin_inset Quotes srd
3146 \end_inset
3147
3148
3149 \layout Itemize
3150
3151 openssh ; to access the CF or commit changes
3152 \layout Itemize
3153
3154 autoconf and autoconf-devel ; if you want to fight with 'configure', don't
3155  use autoconf-stable!
3156 \layout Standard
3157
3158 rxvt is a nice console with history.
3159  Replace in your cygwin.bat the line
3160 \layout LyX-Code
3161
3162 bash -
3163 \begin_inset ERT
3164 status Collapsed
3165
3166 \layout Standard
3167
3168 \backslash
3169 /
3170 \end_inset
3171
3172 -login -i
3173 \layout Standard
3174
3175 with (one line):
3176 \layout LyX-Code
3177
3178 rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
3179 \layout LyX-Code
3180
3181      -bg black -fg white -geometry 100x65 -e bash -
3182 \begin_inset ERT
3183 status Collapsed
3184
3185 \layout Standard
3186
3187 \backslash
3188 /
3189 \end_inset
3190
3191 -login
3192 \layout Standard
3193
3194 Text selected with the mouse is automatically copied to the clipboard, pasting
3195  works with shift-insert.
3196 \newline
3197
3198 \newline
3199 The other good tip is to make sure you have no //c/-style paths anywhere,
3200  use /cygdrive/c/ instead.
3201  Using // invokes a network lookup which is very slow.
3202  If you think
3203 \begin_inset Quotes sld
3204 \end_inset
3205
3206 cygdrive
3207 \begin_inset Quotes srd
3208 \end_inset
3209
3210  is too long, you can change it with e.g.
3211 \layout LyX-Code
3212
3213 mount -s -u -c /mnt
3214 \layout Standard
3215
3216 SDCC sources use the unix line ending LF.
3217  Life is much easier, if you store the source tree on a drive which is mounted
3218  in binary mode.
3219  And use an editor which can handle LF-only line endings.
3220  Make sure not to commit files with windows line endings.
3221  The tabulator spacing
3222 \begin_inset LatexCommand \index{tabulator spacing (8 columns)}
3223
3224 \end_inset
3225
3226  used in the project is 8.
3227  Although a tabulator spacing of 8 is a sensible choice for programmers
3228  (it's a power of 2 and allows to display 8/16 bit signed variables without
3229  loosing columns) the plan is to move towards using only spaces in the source.
3230 \layout Subsection
3231
3232 Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
3233 \layout Standard
3234
3235
3236 \series medium
3237 Download the source package
3238 \series default
3239  either from the SDCC CVS repository or from the
3240 \begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
3241
3242 \end_inset
3243
3244
3245 \series medium
3246 , it will be named something like sdcc
3247 \series default
3248 .src
3249 \series medium
3250 .tgz.
3251
3252 \series default
3253  SDCC is distributed with all the projects, workspaces, and files you need
3254  to build it using Visual C++ 6.0/NET (except for sdcdb.exe which currently
3255  doesn't build under MSVC).
3256  The workspace name is 'sdcc.dsw'.
3257  Please note that as it is now, all the executables are created in a folder
3258  called sdcc
3259 \backslash
3260 bin_vc.
3261  Once built you need to copy the executables from sdcc
3262 \backslash
3263 bin_vc to sdcc
3264 \backslash
3265 bin before running SDCC.
3266
3267 \newline
3268
3269 \newline
3270 WARNING: Visual studio is very picky with line terminations; it expects
3271  the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings.
3272  When using the CVS repository it's easiest to configure the cvs client
3273  to convert automatically for you.
3274  If however you are getting a message such as "This makefile was not generated
3275  by Developer Studio etc.
3276  etc.
3277 \begin_inset Quotes srd
3278 \end_inset
3279
3280  when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
3281  need to convert the Unix style line endings to DOS style line endings.
3282  To do so you can use the
3283 \begin_inset Quotes sld
3284 \end_inset
3285
3286 unix2dos
3287 \begin_inset Quotes srd
3288 \end_inset
3289
3290  utility freely available on the internet.
3291  Doug Hawkins reported in the sdcc-user list that this works:
3292 \newline
3293
3294 \newline
3295 C:
3296 \backslash
3297 Programming
3298 \backslash
3299 SDCC> unix2dos sdcc.dsw
3300 \newline
3301 C:
3302 \backslash
3303 Programming
3304 \backslash
3305 SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
3306 \newline
3307
3308 \newline
3309 In order to build SDCC with MSVC you need win32 executables of bison.exe,
3310  flex.exe, and gawk.exe.
3311  One good place to get them is
3312 \begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
3313
3314 \end_inset
3315
3316
3317 \newline
3318
3319 \newline
3320 Download the file UnxUtils
3321 \begin_inset LatexCommand \index{UnxUtils}
3322
3323 \end_inset
3324
3325 .zip.
3326  Now you have to install the utilities and setup MSVC so it can locate the
3327  required programs.
3328  Here there are two alternatives (choose one!):
3329 \layout Enumerate
3330
3331 The easy way:
3332 \newline
3333
3334 \newline
3335 a) Extract UnxUtils.zip to your C:
3336 \backslash
3337  hard disk PRESERVING the original paths, otherwise bison won't work.
3338  (If you are using WinZip make certain that 'Use folder names' is selected)
3339 \newline
3340
3341 \newline
3342 b) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3343  in 'Show directories for:' select 'Executable files', and in the directories
3344  window add a new path: 'C:
3345 \backslash
3346 user
3347 \backslash
3348 local
3349 \backslash
3350 wbin', click ok.
3351 \newline
3352
3353 \newline
3354 (As a side effect, you get a bunch of Unix utilities that could be useful,
3355  such as diff and patch.)
3356 \layout Enumerate
3357
3358 A more compact way:
3359 \newline
3360
3361 \newline
3362 This one avoids extracting a bunch of files you may not use, but requires
3363  some extra work:
3364 \newline
3365
3366 \newline
3367 a) Create a directory were to put the tools needed, or use a directory already
3368  present.
3369  Say for example 'C:
3370 \backslash
3371 util'.
3372 \newline
3373
3374 \newline
3375 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
3376  to such directory WITHOUT preserving the original paths.
3377  (If you are using WinZip make certain that 'Use folder names' is not selected)
3378 \newline
3379
3380 \newline
3381 c) Rename bison.exe to '_bison.exe'.
3382 \newline
3383
3384 \newline
3385 d) Create a batch file 'bison.bat' in 'C:
3386 \backslash
3387 util
3388 \backslash
3389 ' and add these lines:
3390 \newline
3391 \SpecialChar ~
3392 \SpecialChar ~
3393 set BISON_SIMPLE=C:
3394 \backslash
3395 util
3396 \backslash
3397 bison.simple
3398 \newline
3399 \SpecialChar ~
3400 \SpecialChar ~
3401 set BISON_HAIRY=C:
3402 \backslash
3403 util
3404 \backslash
3405 bison.hairy
3406 \newline
3407 \SpecialChar ~
3408 \SpecialChar ~
3409 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
3410 \newline
3411
3412 \newline
3413 Steps 'c' and 'd' are needed because bison requires by default that the
3414  files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory,
3415  '/usr/local/share/' I think.
3416  So it is necessary to tell bison where those files are located if they
3417  are not in such directory.
3418  That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
3419 \newline
3420
3421 \newline
3422 e) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3423  in 'Show directories for:' select 'Executable files', and in the directories
3424  window add a new path: 'c:
3425 \backslash
3426 util', click ok.
3427  Note that you can use any other path instead of 'c:
3428 \backslash
3429 util', even the path where the Visual C++ tools are, probably: 'C:
3430 \backslash
3431 Program Files
3432 \backslash
3433 Microsoft Visual Studio
3434 \backslash
3435 Common
3436 \backslash
3437 Tools'.
3438  So you don't have to execute step 'e' :)
3439 \layout Standard
3440
3441 That is it.
3442  Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
3443  the executables from sdcc
3444 \backslash
3445 bin_vc to sdcc
3446 \backslash
3447 bin, and you can compile using SDCC.
3448 \layout Subsection
3449
3450 Building SDCC Using Borland
3451 \layout Enumerate
3452
3453 From the sdcc directory, run the command "make -f Makefile.bcc".
3454  This should regenerate all the .exe files in the bin directory except for
3455  sdcdb.exe (which currently doesn't build under Borland C++).
3456 \layout Enumerate
3457
3458 If you modify any source files and need to rebuild, be aware that the dependenci
3459 es may not be correctly calculated.
3460  The safest option is to delete all .obj files and run the build again.
3461  From a Cygwin BASH prompt, this can easily be done with the command (be
3462  sure you are in the sdcc directory):
3463 \newline
3464
3465 \newline
3466
3467 \family sans
3468 \series bold
3469 find .
3470
3471 \backslash
3472 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
3473 \backslash
3474 ) -print -exec rm {}
3475 \backslash
3476 ;
3477 \family default
3478 \series default
3479
3480 \newline
3481
3482 \newline
3483 or on Windows NT/2000/XP from the command prompt with the command:
3484 \newline
3485
3486 \family sans
3487 \series bold
3488
3489 \newline
3490 del /s *.obj *.lib *.rul
3491 \family default
3492 \series default
3493  from the sdcc directory.
3494 \layout Subsection
3495
3496 Windows Install Using a ZIP Package
3497 \layout Enumerate
3498
3499 Download the binary zip package from
3500 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3501
3502 \end_inset
3503
3504  and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
3505  This should unpack to a group of sub-directories.
3506  An example directory structure after unpacking the mingw32 package is:
3507  c:
3508 \backslash
3509 sdcc
3510 \backslash
3511 bin for the executables, c:
3512 \backslash
3513 sdcc
3514 \backslash
3515 include and c:
3516 \backslash
3517 sdcc
3518 \backslash
3519 lib for the include and libraries.
3520 \layout Enumerate
3521
3522 Adjust your environment variable PATH to include the location of the bin
3523  directory or start sdcc using the full path.
3524 \layout Subsection
3525
3526 Windows Install Using the Setup Program
3527 \begin_inset LatexCommand \label{sub:Windows-Install}
3528
3529 \end_inset
3530
3531
3532 \layout Standard
3533
3534 Download the setup program
3535 \emph on
3536 sdcc-x.y.z-setup.exe
3537 \emph default
3538  for an official release from
3539 \newline
3540
3541 \begin_inset LatexCommand \url{http://sf.net/project/showfiles.php?group_id=599}
3542
3543 \end_inset
3544
3545  or a setup program for one of the snapshots
3546 \emph on
3547 sdcc_yyyymmdd_setup.exe
3548 \emph default
3549  from
3550 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3551
3552 \end_inset
3553
3554  and execute it.
3555  A windows typical installer will guide you through the installation process.
3556 \layout Section
3557
3558 Building the Documentation
3559 \layout Standard
3560
3561 If the necessary tools (LyX, LaTeX, LaTeX2HTML) are installed it is as easy
3562  as changing into the doc directory and typing
3563 \family sans
3564 \series bold
3565
3566 \begin_inset Quotes srd
3567 \end_inset
3568
3569 make
3570 \begin_inset Quotes srd
3571 \end_inset
3572
3573
3574 \family default
3575 \series default
3576  there.
3577  You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
3578 x).
3579  Using LyX
3580 \begin_inset LatexCommand \url{http://www.lyx.org}
3581
3582 \end_inset
3583
3584  as editor this is straightforward.
3585  Prebuilt documentation in html and pdf format is available from
3586 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3587
3588 \end_inset
3589
3590 .
3591 \layout Section
3592
3593 Reading the Documentation
3594 \layout Standard
3595
3596 Currently reading the document in pdf format is recommended, as for unknown
3597  reason the hyperlinks are working there whereas in the html version they
3598  are not
3599 \begin_inset Foot
3600 collapsed false
3601
3602 \layout Standard
3603
3604 If you should know why please drop us a note
3605 \end_inset
3606
3607 .
3608
3609 \newline
3610 You'll find the pdf version
3611 \begin_inset LatexCommand \index{PDF version of this document}
3612
3613 \end_inset
3614
3615  at
3616 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.pdf}
3617
3618 \end_inset
3619
3620 .
3621
3622 \newline
3623 A html version
3624 \begin_inset LatexCommand \index{HTML version of this document}
3625
3626 \end_inset
3627
3628  should be online at
3629 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.html/index.html}
3630
3631 \end_inset
3632
3633 .
3634 \newline
3635 This documentation is in some aspects different from a commercial documentation:
3636
3637 \layout Itemize
3638
3639 It tries to document SDCC for several processor architectures in one document
3640  (commercially these probably would be separate documents/products).
3641  This document
3642 \begin_inset LatexCommand \index{Status of documentation}
3643
3644 \end_inset
3645
3646  currently matches SDCC for mcs51 and DS390 best and does give too few informati
3647 on about f.e.
3648  Z80, PIC14, PIC16 and HC08.
3649 \layout Itemize
3650
3651 There are many references pointing away from this documentation.
3652  Don't let this distract you.
3653  If there f.e.
3654  was a reference like
3655 \begin_inset LatexCommand \url{http://www.opencores.org}
3656
3657 \end_inset
3658
3659  together with a statement
3660 \begin_inset Quotes sld
3661 \end_inset
3662
3663 some processors which are targetted by SDCC can be implemented in a
3664 \emph on
3665 f
3666 \emph default
3667 ield
3668 \emph on
3669 p
3670 \emph default
3671 rogrammable
3672 \emph on
3673 g
3674 \emph default
3675 ate
3676 \emph on
3677 a
3678 \emph default
3679 rray
3680 \begin_inset LatexCommand \index{fpga (field programmable gate array)}
3681
3682 \end_inset
3683
3684
3685 \begin_inset Quotes srd
3686 \end_inset
3687
3688  we expect you to have a quick look there and come back.
3689  If you read this you are on the right track.
3690 \layout Itemize
3691
3692 Some sections attribute more space to problems, restrictions and warnings
3693  than to the solution.
3694 \layout Itemize
3695
3696 The installation section and the section about the debugger is intimidating.
3697 \layout Itemize
3698
3699 There are still lots of typos and there are more different writing styles
3700  than pictures.
3701 \layout Section
3702
3703 Testing the SDCC Compiler
3704 \begin_inset LatexCommand \label{sec:Testing-the-SDCC}
3705
3706 \end_inset
3707
3708
3709 \layout Standard
3710
3711 The first thing you should do after installing your SDCC compiler is to
3712  see if it runs.
3713  Type
3714 \family sans
3715 \series bold
3716 "sdcc -
3717 \begin_inset ERT
3718 status Collapsed
3719
3720 \layout Standard
3721
3722 \backslash
3723 /
3724 \end_inset
3725
3726 -version"
3727 \begin_inset LatexCommand \index{version}
3728
3729 \end_inset
3730
3731
3732 \family default
3733 \series default
3734  at the prompt, and the program should run and tell you the version.
3735  If it doesn't run, or gives a message about not finding sdcc program, then
3736  you need to check over your installation.
3737  Make sure that the sdcc bin directory is in your executable search path
3738  defined by the PATH environment setting (
3739 \series medium
3740 see
3741 \series default
3742 section
3743 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3744
3745 \end_inset
3746
3747 \SpecialChar ~
3748
3749 \series medium
3750 Install trouble-shooting for suggestions
3751 \series default
3752 ).
3753  Make sure that the sdcc program is in the bin folder, if not perhaps something
3754  did not install correctly.
3755 \newline
3756
3757 \newline
3758
3759 \series medium
3760 SDCC
3761 \series default
3762 is commonly installed as described in section
3763 \begin_inset Quotes sld
3764 \end_inset
3765
3766 Install and search paths
3767 \begin_inset Quotes srd
3768 \end_inset
3769
3770 .
3771 \newline
3772
3773 \newline
3774
3775 \series medium
3776 Make sure the compiler works on a very simple example.
3777  Type in the following test.c program using your favorite
3778 \series default
3779 ASCII
3780 \series medium
3781 editor:
3782 \layout Verse
3783
3784
3785 \family typewriter
3786 char test;
3787 \newline
3788
3789 \newline
3790 void main(void) {
3791 \newline
3792 \SpecialChar ~
3793 \SpecialChar ~
3794 \SpecialChar ~
3795 \SpecialChar ~
3796 test=0;
3797 \newline
3798 }
3799 \layout Standard
3800
3801
3802 \series medium
3803 Compile this using the following command:
3804 \family sans
3805 \series bold
3806 "sdcc -c test.c".
3807
3808 \family default
3809 \series default
3810
3811 \series medium
3812 If all goes well, the compiler will generate a test.asm and test.rel file.
3813  Congratulations, you've just compiled your first program with SDCC.
3814  We used the -c option to tell SDCC not to link the generated code, just
3815  to keep things simple for this step.
3816 \series default
3817
3818 \newline
3819
3820 \newline
3821
3822 \series medium
3823 The next step is to try it with the linker.
3824  Type in
3825 \family sans
3826 \series bold
3827 "sdcc test.c
3828 \family default
3829 \series default
3830 "
3831 \series medium
3832 .
3833  If all goes well the compiler will link with the libraries and produce
3834  a test.ihx output file.
3835  If this step fails
3836 \series default
3837
3838 \series medium
3839 (no test.ihx, and the linker generates warnings), then the problem is most
3840  likely that
3841 \series default
3842 SDCC
3843 \series medium
3844  cannot find the
3845 \series default
3846 /
3847 \series medium
3848 usr/local/share/sdcc/lib directory
3849 \series default
3850
3851 \series medium
3852 (see
3853 \series default
3854 section
3855 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3856
3857 \end_inset
3858
3859 \SpecialChar ~
3860
3861 \series medium
3862 Install trouble-shooting for suggestions).
3863 \series default
3864
3865 \newline
3866
3867 \newline
3868
3869 \series medium
3870 The final test is to ensure
3871 \series default
3872 SDCC
3873 \series medium
3874  can use the
3875 \series default
3876 standard
3877 \series medium
3878  header files and libraries.
3879  Edit test.c and change it to the following:
3880 \layout Verse
3881
3882
3883 \family typewriter
3884 #include <string.h>
3885 \newline
3886
3887 \newline
3888 char str1[10];
3889 \newline
3890
3891 \newline
3892 void main(void) {
3893 \newline
3894 \SpecialChar ~
3895 \SpecialChar ~
3896 strcpy(str1, "testing");
3897 \newline
3898 }
3899 \layout Standard
3900
3901
3902 \series medium
3903 Compile this by typing
3904 \family sans
3905 \series bold
3906 "sdcc test.c"
3907 \family default
3908 \series medium
3909 .
3910  This should generate a test.ihx output file, and it should give no warnings
3911  such as not finding the string.h file.
3912  If it cannot find the string.h file, then the problem is that
3913 \series default
3914 SDCC
3915 \series medium
3916  cannot find the /usr/local/share/sdcc/include directory
3917 \series default
3918
3919 \series medium
3920 (see the
3921 \series default
3922 section
3923 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3924
3925 \end_inset
3926
3927 \SpecialChar ~
3928
3929 \series medium
3930 Install trouble-shooting section for suggestions).
3931
3932 \series default
3933  Use option
3934 \series bold
3935 -
3936 \begin_inset ERT
3937 status Collapsed
3938
3939 \layout Standard
3940
3941 \backslash
3942 /
3943 \end_inset
3944
3945 -print-search-dirs
3946 \series default
3947
3948 \begin_inset LatexCommand \index{-\/-print-search-dirs}
3949
3950 \end_inset
3951
3952  to find exactly where SDCC is looking for the include and lib files.
3953 \layout Section
3954
3955 Install Trouble-shooting
3956 \begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
3957
3958 \end_inset
3959
3960
3961 \begin_inset LatexCommand \index{Install trouble-shooting}
3962
3963 \end_inset
3964
3965
3966 \layout Subsection
3967
3968 If SDCC does not build correctly
3969 \layout Standard
3970
3971 A thing to try is starting from scratch by unpacking the .tgz source package
3972  again in an empty directory.
3973  Configure it like:
3974 \newline
3975
3976 \newline
3977
3978 \family sans
3979 \series bold
3980 ./configure 2>&1 | tee configure.log
3981 \family default
3982 \series default
3983
3984 \newline
3985
3986 \newline
3987 and build it like:
3988 \newline
3989
3990 \newline
3991
3992 \family sans
3993 \series bold
3994 make 2>&1 | tee make.log
3995 \family default
3996 \series default
3997
3998 \newline
3999
4000 \newline
4001 If anything goes wrong, you can review the log files to locate the problem.
4002  Or a relevant part of this can be attached to an email that could be helpful
4003  when requesting help from the mailing list.
4004 \layout Subsection
4005
4006 What the
4007 \begin_inset Quotes sld
4008 \end_inset
4009
4010 ./configure
4011 \begin_inset Quotes srd
4012 \end_inset
4013
4014  does
4015 \layout Standard
4016
4017 The
4018 \begin_inset Quotes sld
4019 \end_inset
4020
4021 ./configure
4022 \begin_inset Quotes srd
4023 \end_inset
4024
4025  command is a script that analyzes your system and performs some configuration
4026  to ensure the source package compiles on your system.
4027  It will take a few minutes to run, and will compile a few tests to determine
4028  what compiler features are installed.
4029 \layout Subsection
4030
4031 What the
4032 \begin_inset Quotes sld
4033 \end_inset
4034
4035 make
4036 \begin_inset Quotes srd
4037 \end_inset
4038
4039  does
4040 \layout Standard
4041
4042 This runs the GNU make tool, which automatically compiles all the source
4043  packages into the final installed binary executables.
4044 \layout Subsection
4045
4046 What the
4047 \begin_inset Quotes sld
4048 \end_inset
4049
4050 make install
4051 \begin_inset Quotes erd
4052 \end_inset
4053
4054  command does.
4055 \layout Standard
4056
4057 This will install the compiler, other executables libraries and include
4058  files into the appropriate directories.
4059  See sections
4060 \begin_inset LatexCommand \ref{sub:Install-paths}
4061
4062 \end_inset
4063
4064 ,\SpecialChar ~
4065
4066 \begin_inset LatexCommand \ref{sub:Search-Paths}
4067
4068 \end_inset
4069
4070 \SpecialChar ~
4071 about install and search paths.
4072 \newline
4073 On most systems you will need super-user privileges to do this.
4074 \layout Section
4075
4076 Components of SDCC
4077 \layout Standard
4078
4079 SDCC is not just a compiler, but a collection of tools by various developers.
4080  These include linkers, assemblers, simulators and other components.
4081  Here is a summary of some of the components.
4082  Note that the included simulator and assembler have separate documentation
4083  which you can find in the source package in their respective directories.
4084  As SDCC grows to include support for other processors, other packages from
4085  various developers are included and may have their own sets of documentation.
4086 \newline
4087
4088 \newline
4089 You might want to look at the files which are installed in <installdir>.
4090  At the time of this writing, we find the following programs for gcc-builds:
4091 \newline
4092
4093 \newline
4094 In <installdir>/bin:
4095 \layout Itemize
4096
4097 sdcc - The compiler.
4098 \layout Itemize
4099
4100 sdcpp - The C preprocessor.
4101 \layout Itemize
4102
4103 asx8051 - The assembler for 8051 type processors.
4104 \layout Itemize
4105
4106 as-z80
4107 \series bold
4108 ,
4109 \series default
4110 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
4111 \layout Itemize
4112
4113 aslink -The linker for 8051 type processors.
4114 \layout Itemize
4115
4116 link-z80
4117 \series bold
4118 ,
4119 \series default
4120 link-gbz80 - The Z80 and GameBoy Z80 linkers.
4121 \layout Itemize
4122
4123 s51 - The ucSim 8051 simulator.
4124  Not available on Win32 platforms.
4125 \layout Itemize
4126
4127 sdcdb - The source debugger.
4128  Not available on Win32 platforms.
4129 \layout Itemize
4130
4131 packihx - A tool to pack (compress) Intel hex files.
4132 \layout Standard
4133
4134 In <installdir>/share/sdcc/include
4135 \layout Itemize
4136
4137 the include files
4138 \layout Standard
4139
4140 In <installdir>/share/sdcc/lib
4141 \layout Itemize
4142
4143 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
4144  relocatables.
4145 \layout Standard
4146
4147 In <installdir>/share/sdcc/doc
4148 \layout Itemize
4149
4150 the documentation
4151 \layout Standard
4152
4153 As development for other processors proceeds, this list will expand to include
4154  executables to support processors like AVR, PIC, etc.
4155 \layout Subsection
4156
4157 sdcc - The Compiler
4158 \layout Standard
4159
4160 This is the actual compiler, it in turn uses the c-preprocessor and invokes
4161  the assembler and linkage editor.
4162 \layout Subsection
4163
4164 sdcpp - The C-Preprocessor
4165 \layout Standard
4166
4167 The preprocessor
4168 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
4169
4170 \end_inset
4171
4172  is a modified version of the GNU preprocessor.
4173  The C preprocessor is used to pull in #include sources, process #ifdef
4174  statements, #defines and so on.
4175 \layout Subsection
4176
4177 as
4178 \emph on
4179 xxxx
4180 \emph default
4181 , aslink, link-
4182 \emph on
4183 xxx
4184 \emph default
4185  - The Assemblers and Linkage Editors
4186 \layout Standard
4187
4188 This is retargettable assembler & linkage editor, it was developed by Alan
4189  Baldwin.
4190  John Hartman created the version for 8051, and I (Sandeep) have made some
4191  enhancements and bug fixes for it to work properly with SDCC.
4192 \layout Subsection
4193
4194 s51 - The Simulator
4195 \layout Standard
4196
4197 S51
4198 \begin_inset LatexCommand \index{s51}
4199
4200 \end_inset
4201
4202  is a freeware, opensource simulator developed by Daniel Drotos.
4203  The simulator is built as part of the build process.
4204  For more information visit Daniel's web site at:
4205 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
4206
4207 \end_inset
4208
4209 .
4210  It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
4211  XA51 family.
4212  S51 is currently not available on Win32 platfors.
4213 \layout Subsection
4214
4215 sdcdb - Source Level Debugger
4216 \layout Standard
4217
4218 Sdcdb
4219 \begin_inset LatexCommand \index{sdcdb (debugger)}
4220
4221 \end_inset
4222
4223  is the companion source level debugger.
4224  More about sdcdb in section
4225 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
4226
4227 \end_inset
4228
4229 .
4230  The current version of the debugger uses Daniel's Simulator S51
4231 \begin_inset LatexCommand \index{s51}
4232
4233 \end_inset
4234
4235 , but can be easily changed to use other simulators.
4236  Sdcdb is currently not available on Win32 platfors.
4237 \layout Chapter
4238
4239 Using SDCC
4240 \layout Section
4241
4242 Compiling
4243 \layout Subsection
4244
4245 Single Source File Projects
4246 \layout Standard
4247
4248 For single source file 8051 projects the process is very simple.
4249  Compile your programs with the following command
4250 \family sans
4251 \series bold
4252 "sdcc sourcefile.c".
4253
4254 \family default
4255 \series default
4256  This will compile, assemble and link your source file.
4257  Output files are as follows:
4258 \layout Itemize
4259
4260 sourcefile.asm
4261 \begin_inset LatexCommand \index{<file>.asm}
4262
4263 \end_inset
4264
4265  - Assembler source
4266 \begin_inset LatexCommand \index{Assembler source}
4267
4268 \end_inset
4269
4270  file created by the compiler
4271 \layout Itemize
4272
4273 sourcefile.lst
4274 \begin_inset LatexCommand \index{<file>.lst}
4275
4276 \end_inset
4277
4278  - Assembler listing
4279 \begin_inset LatexCommand \index{Assembler listing}
4280
4281 \end_inset
4282
4283  file created by the Assembler
4284 \layout Itemize
4285
4286 sourcefile.rst
4287 \begin_inset LatexCommand \index{<file>.rst}
4288
4289 \end_inset
4290
4291  - Assembler listing
4292 \begin_inset LatexCommand \index{Assembler listing}
4293
4294 \end_inset
4295
4296  file updated with linkedit information, created by linkage editor
4297 \layout Itemize
4298
4299 sourcefile.sym
4300 \begin_inset LatexCommand \index{<file>.sym}
4301
4302 \end_inset
4303
4304  - symbol listing
4305 \begin_inset LatexCommand \index{Symbol listing}
4306
4307 \end_inset
4308
4309  for the sourcefile, created by the assembler
4310 \layout Itemize
4311
4312 sourcefile.rel
4313 \begin_inset LatexCommand \index{<file>.rel}
4314
4315 \end_inset
4316
4317  or sourcefile.o
4318 \begin_inset LatexCommand \index{<file>.o}
4319
4320 \end_inset
4321
4322  - Object file
4323 \begin_inset LatexCommand \index{Object file}
4324
4325 \end_inset
4326
4327  created by the assembler, input to Linkage editor
4328 \layout Itemize
4329
4330 sourcefile.map
4331 \begin_inset LatexCommand \index{<file>.map}
4332
4333 \end_inset
4334
4335  - The memory map
4336 \begin_inset LatexCommand \index{Memory map}
4337
4338 \end_inset
4339
4340  for the load module, created by the Linker
4341 \layout Itemize
4342
4343 sourcefile.mem
4344 \begin_inset LatexCommand \index{<file>.mem}
4345
4346 \end_inset
4347
4348  - A file with a summary of the memory usage
4349 \layout Itemize
4350
4351 sourcefile.ihx
4352 \begin_inset LatexCommand \index{<file>.ihx}
4353
4354 \end_inset
4355
4356  - The load module in Intel hex format
4357 \begin_inset LatexCommand \index{Intel hex format}
4358
4359 \end_inset
4360
4361  (you can select the Motorola S19 format
4362 \begin_inset LatexCommand \index{Motorola S19 format}
4363
4364 \end_inset
4365
4366  with -
4367 \begin_inset ERT
4368 status Collapsed
4369
4370 \layout Standard
4371
4372 \backslash
4373 /
4374 \end_inset
4375
4376 -out-fmt-s19
4377 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
4378
4379 \end_inset
4380
4381 .
4382  If you need another format you might want to use
4383 \family sans
4384 \shape italic
4385 objdump
4386 \family default
4387 \shape default
4388
4389 \begin_inset LatexCommand \index{objdump (tool)}
4390
4391 \end_inset
4392
4393  or
4394 \family sans
4395 \shape italic
4396  srecord
4397 \family default
4398 \shape default
4399
4400 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4401
4402 \end_inset
4403
4404 ).
4405  Both formats are documented in the documentation of srecord
4406 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4407
4408 \end_inset
4409
4410
4411 \layout Itemize
4412
4413 sourcefile.adb
4414 \begin_inset LatexCommand \index{<file>.adb}
4415
4416 \end_inset
4417
4418  - An intermediate file containing debug information needed to create the
4419  .cdb file (with -
4420 \begin_inset ERT
4421 status Open
4422
4423 \layout Standard
4424
4425 \backslash
4426 /
4427 \end_inset
4428
4429 -debug
4430 \begin_inset LatexCommand \index{-\/-debug}
4431
4432 \end_inset
4433
4434 )
4435 \layout Itemize
4436
4437 sourcefile.cdb
4438 \begin_inset LatexCommand \index{<file>.cdb}
4439
4440 \end_inset
4441
4442  - An optional file (with -
4443 \begin_inset ERT
4444 status Collapsed
4445
4446 \layout Standard
4447
4448 \backslash
4449 /
4450 \end_inset
4451
4452 -debug) containing debug information.
4453  The format is documented in cdbfileformat.pdf
4454 \layout Itemize
4455
4456 sourcefile.
4457  - (no extension)
4458 \begin_inset LatexCommand \index{<file> (no extension)}
4459
4460 \end_inset
4461
4462  An optional AOMF or AOMF51
4463 \begin_inset LatexCommand \index{AOMF, AOMF51}
4464
4465 \end_inset
4466
4467  file containing debug information (generated with option -
4468 \begin_inset ERT
4469 status Collapsed
4470
4471 \layout Standard
4472
4473 \backslash
4474 /
4475 \end_inset
4476
4477 -debug).
4478  The (Intel)
4479 \emph on
4480  a
4481 \emph default
4482 bsolute
4483 \emph on
4484 o
4485 \emph default
4486 bject
4487 \emph on
4488 m
4489 \emph default
4490 odule
4491 \emph on
4492 f
4493 \emph default
4494 ormat is commonly used by third party tools (debuggers
4495 \begin_inset LatexCommand \index{Debugger}
4496
4497 \end_inset
4498
4499 , simulators, emulators)
4500 \layout Itemize
4501
4502 sourcefile.dump*
4503 \begin_inset LatexCommand \index{<file>.dump*}
4504
4505 \end_inset
4506
4507  - Dump file to debug the compiler it self (generated with option -
4508 \begin_inset ERT
4509 status Collapsed
4510
4511 \layout Standard
4512
4513 \backslash
4514 /
4515 \end_inset
4516
4517 -dumpall) (see section
4518 \begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
4519
4520 \end_inset
4521
4522 \SpecialChar ~
4523  and section
4524 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
4525
4526 \end_inset
4527
4528 \SpecialChar ~
4529
4530 \begin_inset Quotes sld
4531 \end_inset
4532
4533 Anatomy of the compiler
4534 \begin_inset Quotes srd
4535 \end_inset
4536
4537 ).
4538 \layout Subsection
4539
4540 Projects with Multiple Source Files
4541 \layout Standard
4542
4543 SDCC can compile only ONE file at a time.
4544  Let us for example assume that you have a project containing the following
4545  files:
4546 \newline
4547
4548 \newline
4549 foo1.c (contains some functions)
4550 \newline
4551 foo2.c (contains some more functions)
4552 \newline
4553 foomain.c (contains more functions and the function main)
4554 \newline
4555
4556 \size footnotesize
4557
4558 \newline
4559
4560 \size default
4561 The first two files will need to be compiled separately with the commands:
4562 \size footnotesize
4563
4564 \size default
4565
4566 \newline
4567
4568 \newline
4569
4570 \family sans
4571 \series bold
4572 sdcc\SpecialChar ~
4573 -c\SpecialChar ~
4574 foo1.c
4575 \family default
4576 \series default
4577 \size footnotesize
4578
4579 \newline
4580
4581 \family sans
4582 \series bold
4583 \size default
4584 sdcc\SpecialChar ~
4585 -c\SpecialChar ~
4586 foo2.c
4587 \family default
4588 \series default
4589
4590 \newline
4591
4592 \newline
4593 Then compile the source file containing the
4594 \emph on
4595 main()
4596 \emph default
4597  function and link
4598 \begin_inset LatexCommand \index{Linker}
4599
4600 \end_inset
4601
4602  the files together with the following command:
4603 \newline
4604
4605 \newline
4606
4607 \family sans
4608 \series bold
4609 sdcc\SpecialChar ~
4610 foomain.c\SpecialChar ~
4611 foo1.rel\SpecialChar ~
4612 foo2.rel
4613 \family default
4614 \series default
4615
4616 \begin_inset LatexCommand \index{<file>.rel}
4617
4618 \end_inset
4619
4620
4621 \newline
4622
4623 \newline
4624 Alternatively,
4625 \emph on
4626 foomain.c
4627 \emph default
4628 can be separately compiled as well:
4629 \family sans
4630 \series bold
4631
4632 \newline
4633
4634 \newline
4635 sdcc\SpecialChar ~
4636 -c\SpecialChar ~
4637 foomain.c
4638 \newline
4639 sdcc foomain.rel foo1.rel foo2.rel
4640 \newline
4641
4642 \newline
4643
4644 \family default
4645 \series default
4646 The file containing the
4647 \emph on
4648 main()
4649 \emph default
4650  function
4651 \emph on
4652
4653 \emph default
4654 \noun on
4655 must
4656 \noun default
4657  be the
4658 \noun on
4659 first
4660 \noun default
4661  file specified in the command line, since the linkage editor processes
4662  file in the order they are presented to it.
4663  The linker is invoked from SDCC using a script file with extension .lnk
4664 \begin_inset LatexCommand \index{<file>.lnk}
4665
4666 \end_inset
4667
4668 .
4669  You can view this file to troubleshoot linking problems such as those arising
4670  from missing libraries.
4671 \layout Subsection
4672
4673 Projects with Additional Libraries
4674 \begin_inset LatexCommand \index{Libraries}
4675
4676 \end_inset
4677
4678
4679 \layout Standard
4680
4681 Some reusable routines may be compiled into a library, see the documentation
4682  for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
4683  for how to create a
4684 \emph on
4685 .lib
4686 \begin_inset LatexCommand \index{<file>.lib}
4687
4688 \end_inset
4689
4690
4691 \emph default
4692  library file.
4693  Libraries created in this manner can be included in the command line.
4694  Make sure you include the -L <library-path> option to tell the linker where
4695  to look for these files if they are not in the current directory.
4696  Here is an example, assuming you have the source file
4697 \emph on
4698 foomain.c
4699 \emph default
4700  and a library
4701 \emph on
4702  foolib.lib
4703 \emph default
4704  in the directory
4705 \emph on
4706 mylib
4707 \emph default
4708  (if that is not the same as your current project):
4709 \newline
4710
4711 \newline
4712
4713 \family sans
4714 \series bold
4715 sdcc foomain.c foolib.lib -L mylib
4716 \newline
4717
4718 \newline
4719
4720 \family default
4721 \series default
4722 Note here that
4723 \emph on
4724  mylib
4725 \emph default
4726  must be an absolute path name.
4727 \newline
4728
4729 \newline
4730 The most efficient way to use libraries is to keep separate modules in separate
4731  source files.
4732  The lib file now should name all the modules.rel
4733 \begin_inset LatexCommand \index{<file>.rel}
4734
4735 \end_inset
4736
4737  files.
4738  For an example see the standard library file
4739 \emph on
4740 libsdcc.lib
4741 \emph default
4742  in the directory <installdir>/share/lib/small.
4743 \layout Subsection
4744
4745 Using sdcclib to Create and Manage Libraries
4746 \begin_inset LatexCommand \index{sdcclib}
4747
4748 \end_inset
4749
4750
4751 \layout Standard
4752
4753 Alternatively, instead of having a .rel file for each entry on the library
4754  file as described in the preceding section, sdcclib can be used to embed
4755  all the modules belonging to such library in the library file itself.
4756  This results in a larger library file, but it greatly reduces the number
4757  of disk files accessed by the linker.
4758   Additionally, the packed library file contains an index of all include
4759  modules and symbols that significantly speeds up the linking process.
4760  To display a list of options supported by sdcclib type:
4761 \newline
4762
4763 \layout Standard
4764
4765
4766 \family sans
4767 \series bold
4768 sdcclib -?
4769 \begin_inset LatexCommand \index{sdcclib}
4770
4771 \end_inset
4772
4773
4774 \newline
4775
4776 \newline
4777
4778 \family default
4779 \series default
4780 To create a new library file, start by compiling all the required modules.
4781  For example:
4782 \newline
4783
4784 \layout Standard
4785
4786
4787 \family sans
4788 \series bold
4789 sdcc -c _divsint.c
4790 \layout Standard
4791
4792
4793 \family sans
4794 \series bold
4795 sdcc -c _divuint.c
4796 \layout Standard
4797
4798
4799 \family sans
4800 \series bold
4801 sdcc -c _modsint.c
4802 \layout Standard
4803
4804
4805 \family sans
4806 \series bold
4807 sdcc -c _moduint.c
4808 \layout Standard
4809
4810
4811 \family sans
4812 \series bold
4813 sdcc -c _mulint.c
4814 \newline
4815
4816 \layout Standard
4817
4818 This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
4819  and _mulint.rel.
4820  The next step is to add the .rel files to the library file:
4821 \newline
4822
4823 \layout Standard
4824
4825
4826 \family sans
4827 \series bold
4828 sdcclib libint.lib _divsint.rel
4829 \family default
4830
4831 \begin_inset LatexCommand \index{sdcclib}
4832
4833 \end_inset
4834
4835
4836 \layout Standard
4837
4838
4839 \family sans
4840 \series bold
4841 sdcclib libint.lib _divuint.rel
4842 \layout Standard
4843
4844
4845 \family sans
4846 \series bold
4847 sdcclib libint.lib _modsint.rel
4848 \layout Standard
4849
4850
4851 \family sans
4852 \series bold
4853 sdcclib libint.lib _moduint.rel
4854 \layout Standard
4855
4856
4857 \family sans
4858 \series bold
4859 sdcclib libint.lib _mulint.rel
4860 \series default
4861
4862 \newline
4863
4864 \layout Standard
4865
4866 If the file already exists in the library, it will be replaced.
4867  To see what modules and symbols are included in the library, options -s
4868  and -m are available.
4869  For example:
4870 \newline
4871
4872 \newline
4873
4874 \family sans
4875 \series bold
4876 sdcclib -s libint.lib
4877 \family default
4878
4879 \begin_inset LatexCommand \index{sdcclib}
4880
4881 \end_inset
4882
4883
4884 \newline
4885
4886 \family typewriter
4887 \series default
4888 _divsint.rel:
4889 \layout Standard
4890
4891
4892 \family typewriter
4893 __divsint_a_1_1
4894 \layout Standard
4895
4896
4897 \family typewriter
4898 __divsint_PARM_2
4899 \layout Standard
4900
4901
4902 \family typewriter
4903 __divsint
4904 \newline
4905 _divuint.rel:
4906 \layout Standard
4907
4908
4909 \family typewriter
4910 __divuint_a_1_1
4911 \layout Standard
4912
4913
4914 \family typewriter
4915 __divuint_PARM_2
4916 \layout Standard
4917
4918
4919 \family typewriter
4920 __divuint_reste_1_1
4921 \layout Standard
4922
4923
4924 \family typewriter
4925 __divuint_count_1_1
4926 \layout Standard
4927
4928
4929 \family typewriter
4930 __divuint
4931 \newline
4932 _modsint.rel:
4933 \layout Standard
4934
4935
4936 \family typewriter
4937 __modsint_a_1_1
4938 \layout Standard
4939
4940
4941 \family typewriter
4942 __modsint_PARM_2
4943 \layout Standard
4944
4945
4946 \family typewriter
4947 __modsint
4948 \newline
4949 _moduint.rel:
4950 \layout Standard
4951
4952
4953 \family typewriter
4954 __moduint_a_1_1
4955 \layout Standard
4956
4957
4958 \family typewriter
4959 __moduint_PARM_2
4960 \layout Standard
4961
4962
4963 \family typewriter
4964 __moduint_count_1_1
4965 \layout Standard
4966
4967
4968 \family typewriter
4969 __moduint
4970 \newline
4971 _mulint.rel:
4972 \layout Standard
4973
4974
4975 \family typewriter
4976 __mulint_PARM_2
4977 \layout Standard
4978
4979
4980 \family typewriter
4981 __mulint
4982 \family default
4983 \series bold
4984
4985 \newline
4986
4987 \layout Standard
4988
4989 If the source files are compiled using -
4990 \begin_inset ERT
4991 status Open
4992
4993 \layout Standard
4994
4995 \backslash
4996 /
4997 \end_inset
4998
4999 -debug
5000 \begin_inset LatexCommand \index{-\/-debug}
5001
5002 \end_inset
5003
5004 , the corresponding debug information file .adb will be include in the library
5005  file as well.
5006  The library files created with sdcclib are plain text files, so they can
5007  be viewed with a text editor.
5008  It is not recomended to modify a library file created with sdcclib using
5009  a text editor, as there are file indexes numbers located accross the file
5010  used by the linker to quickly locate the required module to link.
5011  Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
5012  it can be safely deleted, since all the information required for linking
5013  is embedded in the library file itself.
5014  Library files created using sdcclib are used as described in the preceding
5015  sections.
5016 \layout Section
5017
5018 Command Line Options
5019 \begin_inset LatexCommand \index{Command Line Options}
5020
5021 \end_inset
5022
5023
5024 \layout Subsection
5025
5026 Processor Selection Options
5027 \begin_inset LatexCommand \index{Options processor selection}
5028
5029 \end_inset
5030
5031
5032 \begin_inset LatexCommand \index{Processor selection options}
5033
5034 \end_inset
5035
5036
5037 \layout List
5038 \labelwidthstring 00.00.0000
5039
5040
5041 \series bold
5042 -mmcs51
5043 \begin_inset LatexCommand \index{-mmcs51}
5044
5045 \end_inset
5046
5047
5048 \series default
5049  Generate code for the Intel MCS51
5050 \begin_inset LatexCommand \index{MCS51}
5051
5052 \end_inset
5053
5054  family of processors.
5055  This is the default processor target.
5056 \layout List
5057 \labelwidthstring 00.00.0000
5058
5059
5060 \series bold
5061 -mds390
5062 \begin_inset LatexCommand \index{-mds390}
5063
5064 \end_inset
5065
5066
5067 \series default
5068  Generate code for the Dallas DS80C390
5069 \begin_inset LatexCommand \index{DS80C390}
5070
5071 \end_inset
5072
5073  processor.
5074 \layout List
5075 \labelwidthstring 00.00.0000
5076
5077
5078 \series bold
5079 -mds400
5080 \begin_inset LatexCommand \index{-mds400}
5081
5082 \end_inset
5083
5084
5085 \series default
5086  Generate code for the Dallas DS80C400
5087 \begin_inset LatexCommand \index{DS80C400}
5088
5089 \end_inset
5090
5091  processor.
5092 \layout List
5093 \labelwidthstring 00.00.0000
5094
5095
5096 \series bold
5097 -mhc08
5098 \begin_inset LatexCommand \index{-mhc08}
5099
5100 \end_inset
5101
5102
5103 \series default
5104  Generate code for the Freescale/Motorola HC08
5105 \begin_inset LatexCommand \index{HC08}
5106
5107 \end_inset
5108
5109  family of processors.
5110 \layout List
5111 \labelwidthstring 00.00.0000
5112
5113
5114 \series bold
5115 -mz80
5116 \begin_inset LatexCommand \index{-mz80}
5117
5118 \end_inset
5119
5120
5121 \series default
5122  Generate code for the Zilog Z80
5123 \begin_inset LatexCommand \index{Z80}
5124
5125 \end_inset
5126
5127  family of processors.
5128 \layout List
5129 \labelwidthstring 00.00.0000
5130
5131
5132 \series bold
5133 -mgbz80
5134 \begin_inset LatexCommand \index{-mgbz80}
5135
5136 \end_inset
5137
5138
5139 \series default
5140  Generate code for the GameBoy Z80
5141 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
5142
5143 \end_inset
5144
5145  processor (Not actively maintained).
5146 \layout List
5147 \labelwidthstring 00.00.0000
5148
5149
5150 \series bold
5151 -mavr
5152 \begin_inset LatexCommand \index{-mavr}
5153
5154 \end_inset
5155
5156
5157 \series default
5158  Generate code for the Atmel AVR
5159 \begin_inset LatexCommand \index{AVR}
5160
5161 \end_inset
5162
5163  processor (In development, not complete).
5164  AVR users should probably have a look at winavr
5165 \begin_inset LatexCommand \url{http://sourceforge.net/projects/winavr}
5166
5167 \end_inset
5168
5169  or
5170 \begin_inset LatexCommand \url{http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index}
5171
5172 \end_inset
5173
5174 .
5175 \layout Comment
5176
5177 I think it is fair to direct users there for now.
5178  Open source is also about avoiding unnecessary work .
5179  But I didn't find the 'official' link.
5180 \layout List
5181 \labelwidthstring 00.00.0000
5182
5183
5184 \series bold
5185 -mpic14
5186 \begin_inset LatexCommand \index{-mpic14}
5187
5188 \end_inset
5189
5190
5191 \series default
5192  Generate code for the Microchip PIC 14
5193 \begin_inset LatexCommand \index{PIC14}
5194
5195 \end_inset
5196
5197 -bit processors (p16f84 and variants.
5198  In development, not complete).
5199 \layout Comment
5200
5201 p16f627 p16f628 p16f84 p16f873 p16f877?
5202 \layout List
5203 \labelwidthstring 00.00.0000
5204
5205
5206 \series bold
5207 -mpic16
5208 \begin_inset LatexCommand \index{-mpic16}
5209
5210 \end_inset
5211
5212
5213 \series default
5214  Generate code for the Microchip PIC 16
5215 \begin_inset LatexCommand \index{PIC16}
5216
5217 \end_inset
5218
5219 -bit processors (p18f452 and variants.
5220  In development, not complete).
5221 \layout List
5222 \labelwidthstring 00.00.0000
5223
5224
5225 \series bold
5226 -mtlcs900h
5227 \series default
5228  Generate code for the Toshiba TLCS-900H
5229 \begin_inset LatexCommand \index{TLCS-900H}
5230
5231 \end_inset
5232
5233  processor (Not maintained, not complete).
5234 \layout List
5235 \labelwidthstring 00.00.0000
5236
5237
5238 \series bold
5239 -mxa51
5240 \begin_inset LatexCommand \index{-mxa51}
5241
5242 \end_inset
5243
5244
5245 \series default
5246  Generate code for the Phillips XA51
5247 \begin_inset LatexCommand \index{XA51}
5248
5249 \end_inset
5250
5251  processor (Not maintained, not complete).
5252 \layout Subsection
5253
5254 Preprocessor Options
5255 \begin_inset LatexCommand \index{Options preprocessor}
5256
5257 \end_inset
5258
5259
5260 \begin_inset LatexCommand \index{Preprocessor options}
5261
5262 \end_inset
5263
5264
5265 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5266
5267 \end_inset
5268
5269
5270 \layout List
5271 \labelwidthstring 00.00.0000
5272
5273
5274 \series bold
5275 -I<path>
5276 \begin_inset LatexCommand \index{-I<path>}
5277
5278 \end_inset
5279
5280
5281 \series default
5282  The additional location where the pre processor will look for <..h> or
5283 \begin_inset Quotes eld
5284 \end_inset
5285
5286 ..h
5287 \begin_inset Quotes erd
5288 \end_inset
5289
5290  files.
5291 \layout List
5292 \labelwidthstring 00.00.0000
5293
5294
5295 \series bold
5296 -D<macro[=value]>
5297 \begin_inset LatexCommand \index{-D<macro[=value]>}
5298
5299 \end_inset
5300
5301
5302 \series default
5303  Command line definition of macros.
5304  Passed to the preprocessor.
5305 \layout List
5306 \labelwidthstring 00.00.0000
5307
5308
5309 \series bold
5310 -M
5311 \begin_inset LatexCommand \index{-M}
5312
5313 \end_inset
5314
5315
5316 \series default
5317  Tell the preprocessor to output a rule suitable for make describing the
5318  dependencies of each object file.
5319  For each source file, the preprocessor outputs one make-rule whose target
5320  is the object file name for that source file and whose dependencies are
5321  all the files `#include'd in it.
5322  This rule may be a single line or may be continued with `
5323 \backslash
5324 '-newline if it is long.
5325  The list of rules is printed on standard output instead of the preprocessed
5326  C program.
5327  `-M' implies `-E
5328 \begin_inset LatexCommand \index{-E}
5329
5330 \end_inset
5331
5332 '.
5333 \layout List
5334 \labelwidthstring 00.00.0000
5335
5336
5337 \series bold
5338 -C
5339 \begin_inset LatexCommand \index{-C}
5340
5341 \end_inset
5342
5343
5344 \series default
5345  Tell the preprocessor not to discard comments.
5346  Used with the `-E' option.
5347 \layout List
5348 \labelwidthstring 00.00.0000
5349
5350
5351 \series bold
5352 -MM
5353 \begin_inset LatexCommand \index{-MM}
5354
5355 \end_inset
5356
5357
5358 \size large
5359 \bar under
5360
5361 \series default
5362 \size default
5363 \bar default
5364 Like `-M' but the output mentions only the user header files included with
5365  `#include
5366 \begin_inset Quotes eld
5367 \end_inset
5368
5369 file"'.
5370  System header files included with `#include <file>' are omitted.
5371 \layout List
5372 \labelwidthstring 00.00.0000
5373
5374
5375 \series bold
5376 -Aquestion(answer)
5377 \begin_inset LatexCommand \index{-Aquestion(answer)}
5378
5379 \end_inset
5380
5381
5382 \series default
5383  Assert the answer answer for question, in case it is tested with a preprocessor
5384  conditional such as `#if #question(answer)'.
5385  `-A-' disables the standard assertions that normally describe the target
5386  machine.
5387 \layout List
5388 \labelwidthstring 00.00.0000
5389
5390
5391 \series bold
5392 -Umacro
5393 \begin_inset LatexCommand \index{-Umacro}
5394
5395 \end_inset
5396
5397
5398 \series default
5399  Undefine macro macro.
5400  `-U' options are evaluated after all `-D' options, but before any `-include'
5401  and `-imacros' options.
5402 \layout List
5403 \labelwidthstring 00.00.0000
5404
5405
5406 \series bold
5407 -dM
5408 \begin_inset LatexCommand \index{-dM}
5409
5410 \end_inset
5411
5412
5413 \series default
5414  Tell the preprocessor to output only a list of the macro definitions that
5415  are in effect at the end of preprocessing.
5416  Used with the `-E' option.
5417 \layout List
5418 \labelwidthstring 00.00.0000
5419
5420
5421 \series bold
5422 -dD
5423 \begin_inset LatexCommand \index{-dD}
5424
5425 \end_inset
5426
5427
5428 \series default
5429  Tell the preprocessor to pass all macro definitions into the output, in
5430  their proper sequence in the rest of the output.
5431 \layout List
5432 \labelwidthstring 00.00.0000
5433
5434
5435 \series bold
5436 -dN
5437 \begin_inset LatexCommand \index{-dN}
5438
5439 \end_inset
5440
5441
5442 \size large
5443 \bar under
5444
5445 \series default
5446 \size default
5447 \bar default
5448 Like `-dD' except that the macro arguments and contents are omitted.
5449  Only `#define name' is included in the output.
5450 \layout List
5451 \labelwidthstring 00.00.0000
5452
5453
5454 \series bold
5455 -Wp\SpecialChar ~
5456 preprocessorOption[,preprocessorOption]
5457 \series default
5458
5459 \begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
5460
5461 \end_inset
5462
5463 ...
5464  Pass the preprocessorOption to the preprocessor
5465 \family typewriter
5466 sdcpp
5467 \family default
5468
5469 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5470
5471 \end_inset
5472
5473 .
5474  SDCC uses an adapted version of the preprocessor cpp of the GNU Compiler
5475  Collection (gcc), if you need more dedicated options please refer to the
5476  documentation at
5477 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
5478
5479 \end_inset
5480
5481 .
5482 \layout Subsection
5483
5484 Linker Options
5485 \begin_inset LatexCommand \index{Options linker}
5486
5487 \end_inset
5488
5489
5490 \begin_inset LatexCommand \index{Linker options}
5491
5492 \end_inset
5493
5494
5495 \layout List
5496 \labelwidthstring 00.00.0000
5497
5498
5499 \series bold
5500 -L\SpecialChar ~
5501 -
5502 \series default
5503
5504 \begin_inset ERT
5505 status Collapsed
5506
5507 \layout Standard
5508
5509 \backslash
5510 /
5511 \end_inset
5512
5513
5514 \series bold
5515 -lib-path
5516 \begin_inset LatexCommand \index{-\/-lib-path <path>}
5517
5518 \end_inset
5519
5520
5521 \begin_inset LatexCommand \index{-L -\/-lib-path}
5522
5523 \end_inset
5524
5525
5526 \series default
5527 \SpecialChar ~
5528 <absolute path to additional libraries> This option is passed to the linkage
5529  editor's additional libraries
5530 \begin_inset LatexCommand \index{Libraries}
5531
5532 \end_inset
5533
5534  search path.
5535  The path name must be absolute.
5536  Additional library files may be specified in the command line.
5537  See section Compiling programs for more details.
5538 \layout List
5539 \labelwidthstring 00.00.0000
5540
5541
5542 \series bold
5543 -
5544 \begin_inset ERT
5545 status Collapsed
5546
5547 \layout Standard
5548
5549 \backslash
5550 /
5551 \end_inset
5552
5553 -xram-loc
5554 \series default
5555
5556 \begin_inset LatexCommand \index{-\/-xram-loc <Value>}
5557
5558 \end_inset
5559
5560 \SpecialChar ~
5561 <Value> The start location of the external ram
5562 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
5563
5564 \end_inset
5565
5566 , default value is 0.
5567  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5568 \begin_inset ERT
5569 status Collapsed
5570
5571 \layout Standard
5572
5573 \backslash
5574 /
5575 \end_inset
5576
5577 -xram-loc 0x8000 or -
5578 \begin_inset ERT
5579 status Collapsed
5580
5581 \layout Standard
5582
5583 \backslash
5584 /
5585 \end_inset
5586
5587 -xram-loc 32768.
5588 \layout List
5589 \labelwidthstring 00.00.0000
5590
5591
5592 \series bold
5593 -
5594 \begin_inset ERT
5595 status Collapsed
5596
5597 \layout Standard
5598
5599 \backslash
5600 /
5601 \end_inset
5602
5603 -code-loc
5604 \series default
5605
5606 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
5607
5608 \end_inset
5609
5610 \SpecialChar ~
5611 <Value> The start location of the code
5612 \begin_inset LatexCommand \index{code}
5613
5614 \end_inset
5615
5616  segment, default value 0.
5617  Note when this option is used the interrupt vector table is also relocated
5618  to the given address.
5619  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5620 \begin_inset ERT
5621 status Collapsed
5622
5623 \layout Standard
5624
5625 \backslash
5626 /
5627 \end_inset
5628
5629 -code-loc 0x8000 or -
5630 \begin_inset ERT
5631 status Collapsed
5632
5633 \layout Standard
5634
5635 \backslash
5636 /
5637 \end_inset
5638
5639 -code-loc 32768.
5640 \layout List
5641 \labelwidthstring 00.00.0000
5642
5643
5644 \series bold
5645 -
5646 \begin_inset ERT
5647 status Collapsed
5648
5649 \layout Standard
5650
5651 \backslash
5652 /
5653 \end_inset
5654
5655 -stack-loc
5656 \series default
5657
5658 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
5659
5660 \end_inset
5661
5662 \SpecialChar ~
5663 <Value> By default the stack
5664 \begin_inset LatexCommand \index{stack}
5665
5666 \end_inset
5667
5668  is placed after the data segment.
5669  Using this option the stack can be placed anywhere in the internal memory
5670  space of the 8051.
5671  The value entered can be in Hexadecimal or Decimal format, e.g.
5672  -
5673 \begin_inset ERT
5674 status Collapsed
5675
5676 \layout Standard
5677
5678 \backslash
5679 /
5680 \end_inset
5681
5682 -stack-loc 0x20 or -
5683 \begin_inset ERT
5684 status Collapsed
5685
5686 \layout Standard
5687
5688 \backslash
5689 /
5690 \end_inset
5691
5692 -stack-loc 32.
5693  Since the sp register is incremented before a push or call, the initial
5694  sp will be set to one byte prior the provided value.
5695  The provided value should not overlap any other memory areas such as used
5696  register banks or the data segment and with enough space for the current
5697  application.
5698  The
5699 \series bold
5700 -
5701 \begin_inset ERT
5702 status Collapsed
5703
5704 \layout Standard
5705
5706 \backslash
5707 /
5708 \end_inset
5709
5710 -pack-iram
5711 \series default
5712 \SpecialChar ~
5713
5714 \begin_inset LatexCommand \index{-\/-pack-iram}
5715
5716 \end_inset
5717
5718  option (which is now a default setting) will override this setting, so
5719  you should also specify the
5720 \series bold
5721 -
5722 \begin_inset ERT
5723 status Collapsed
5724
5725 \layout Standard
5726
5727 \backslash
5728 /
5729 \end_inset
5730
5731 -no-pack-iram
5732 \series default
5733 \SpecialChar ~
5734
5735 \begin_inset LatexCommand \index{-\/-no-pack-iram}
5736
5737 \end_inset
5738
5739  option if you need to manually place the stack.
5740 \layout List
5741 \labelwidthstring 00.00.0000
5742
5743
5744 \series bold
5745 -
5746 \begin_inset ERT
5747 status Collapsed
5748
5749 \layout Standard
5750
5751 \backslash
5752 /
5753 \end_inset
5754
5755 -data-loc
5756 \series default
5757
5758 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
5759
5760 \end_inset
5761
5762 \SpecialChar ~
5763 <Value> The start location of the internal ram data
5764 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
5765
5766 \end_inset
5767
5768  segment.
5769  The value entered can be in Hexadecimal or Decimal format, eg.
5770  -
5771 \begin_inset ERT
5772 status Collapsed
5773
5774 \layout Standard
5775
5776 \backslash
5777 /
5778 \end_inset
5779
5780 -data-loc 0x20 or -
5781 \begin_inset ERT
5782 status Collapsed
5783
5784 \layout Standard
5785
5786 \backslash
5787 /
5788 \end_inset
5789
5790 -data-loc 32.
5791  (By default, the start location of the internal ram data segment  is set
5792  as low as possible in memory, taking into account the used register banks
5793  and the bit segment at address 0x20.
5794  For example if register banks 0 and 1 are used without bit variables, the
5795  data segment will be set, if -
5796 \begin_inset ERT
5797 status Collapsed
5798
5799 \layout Standard
5800
5801 \backslash
5802 /
5803 \end_inset
5804
5805 -data-loc is not used, to location 0x10.)
5806 \layout List
5807 \labelwidthstring 00.00.0000
5808
5809
5810 \series bold
5811 -
5812 \begin_inset ERT
5813 status Collapsed
5814
5815 \layout Standard
5816
5817 \backslash
5818 /
5819 \end_inset
5820
5821 -idata-loc
5822 \series default
5823
5824 \begin_inset LatexCommand \index{-\/-idata-loc <Value>}
5825
5826 \end_inset
5827
5828 \SpecialChar ~
5829 <Value> The start location of the indirectly addressable internal ram
5830 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
5831
5832 \end_inset
5833
5834  of the 8051, default value is 0x80.
5835  The value entered can be in Hexadecimal or Decimal format, eg.
5836  -
5837 \begin_inset ERT
5838 status Collapsed
5839
5840 \layout Standard
5841
5842 \backslash
5843 /
5844 \end_inset
5845
5846 -idata-loc 0x88 or -
5847 \begin_inset ERT
5848 status Collapsed
5849
5850 \layout Standard
5851
5852 \backslash
5853 /
5854 \end_inset
5855
5856 -idata-loc 136.
5857 \layout List
5858 \labelwidthstring 00.00.0000
5859
5860
5861 \series bold
5862 -
5863 \begin_inset ERT
5864 status Collapsed
5865
5866 \layout Standard
5867
5868 \backslash
5869 /
5870 \end_inset
5871
5872 -bit-loc
5873 \series default
5874 \SpecialChar ~
5875 <Value> The start location of the bit
5876 \begin_inset LatexCommand \index{bit}
5877
5878 \end_inset
5879
5880  addressable internal ram of the 8051.
5881  This is
5882 \emph on
5883 not
5884 \emph default
5885  implemented yet.
5886  Instead an option can be passed directly to the linker: -Wl\SpecialChar ~
5887 -bBSEG=<Value>.
5888 \layout List
5889 \labelwidthstring 00.00.0000
5890
5891
5892 \series bold
5893 -
5894 \begin_inset ERT
5895 status Collapsed
5896
5897 \layout Standard
5898
5899 \backslash
5900 /
5901 \end_inset
5902
5903 -out-fmt-ihx
5904 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
5905
5906 \end_inset
5907
5908
5909 \bar under
5910
5911 \series default
5912 \bar default
5913 The linker output (final object code) is in Intel Hex format.
5914 \begin_inset LatexCommand \index{Intel hex format}
5915
5916 \end_inset
5917
5918  This is the default option.
5919  The format itself is documented in the documentation of srecord
5920 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
5921
5922 \end_inset
5923
5924 .
5925 \layout List
5926 \labelwidthstring 00.00.0000
5927
5928
5929 \series bold
5930 -
5931 \begin_inset ERT
5932 status Collapsed
5933
5934 \layout Standard
5935
5936 \backslash
5937 /
5938 \end_inset
5939
5940 -out-fmt-s19
5941 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
5942
5943 \end_inset
5944
5945
5946 \bar under
5947
5948 \series default
5949 \bar default
5950 The linker output (final object code) is in Motorola S19 format
5951 \begin_inset LatexCommand \index{Motorola S19 format}
5952
5953 \end_inset
5954
5955 .
5956  The format itself is documented in the documentation of srecord.
5957 \layout List
5958 \labelwidthstring 00.00.0000
5959
5960
5961 \series bold
5962 -
5963 \begin_inset ERT
5964 status Collapsed
5965
5966 \layout Standard
5967
5968 \backslash
5969 /
5970 \end_inset
5971
5972 -out-fmt-elf
5973 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
5974
5975 \end_inset
5976
5977
5978 \bar under
5979
5980 \series default
5981 \bar default
5982 The linker output (final object code) is in ELF format
5983 \begin_inset LatexCommand \index{ELF format}
5984
5985 \end_inset
5986
5987 .
5988  (Currently only supported for the HC08 processors)
5989 \layout List
5990 \labelwidthstring 00.00.0000
5991
5992
5993 \series bold
5994 -Wl\SpecialChar ~
5995 linkOption[,linkOption]
5996 \series default
5997
5998 \begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
5999
6000 \end_inset
6001
6002 ...
6003  Pass the linkOption to the linker.
6004  See file sdcc/as/doc/asxhtm.html for more on linker options.
6005 \layout Subsection
6006
6007 MCS51 Options
6008 \begin_inset LatexCommand \index{Options MCS51}
6009
6010 \end_inset
6011
6012
6013 \begin_inset LatexCommand \index{MCS51 options}
6014
6015 \end_inset
6016
6017
6018 \layout List
6019 \labelwidthstring 00.00.0000
6020
6021
6022 \series bold
6023 -
6024 \begin_inset ERT
6025 status Collapsed
6026
6027 \layout Standard
6028
6029 \backslash
6030 /
6031 \end_inset
6032
6033 -model-small
6034 \begin_inset LatexCommand \index{-\/-model-small}
6035
6036 \end_inset
6037
6038
6039 \series default
6040 \size large
6041 \emph on
6042
6043 \size default
6044 \emph default
6045 Generate code for Small Model programs, see section Memory Models for more
6046  details.
6047  This is the default model.
6048 \layout List
6049 \labelwidthstring 00.00.0000
6050
6051
6052 \series bold
6053 -
6054 \begin_inset ERT
6055 status Collapsed
6056
6057 \layout Standard
6058
6059 \backslash
6060 /
6061 \end_inset
6062
6063 -model-medium
6064 \begin_inset LatexCommand \index{-\/-model-medium}
6065
6066 \end_inset
6067
6068
6069 \series default
6070  Generate code for Medium model programs, see section Memory Models for
6071  more details.
6072  If this option is used all source files in the project have to be compiled
6073  with this option.
6074  It must also be used when invoking the linker.
6075 \layout List
6076 \labelwidthstring 00.00.0000
6077
6078
6079 \series bold
6080 -
6081 \begin_inset ERT
6082 status Collapsed
6083
6084 \layout Standard
6085
6086 \backslash
6087 /
6088 \end_inset
6089
6090 -model-large
6091 \begin_inset LatexCommand \index{-\/-model-large}
6092
6093 \end_inset
6094
6095
6096 \series default
6097  Generate code for Large model programs, see section Memory Models for more
6098  details.
6099  If this option is used all source files in the project have to be compiled
6100  with this option.
6101  It must also be used when invoking the linker.
6102 \layout List
6103 \labelwidthstring 00.00.0000
6104
6105
6106 \series bold
6107 -
6108 \begin_inset ERT
6109 status Collapsed
6110
6111 \layout Standard
6112
6113 \backslash
6114 /
6115 \end_inset
6116
6117 -xstack
6118 \begin_inset LatexCommand \index{-\/-xstack}
6119
6120 \end_inset
6121
6122
6123 \series default
6124  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
6125  variables and passing parameters.
6126  See section
6127 \begin_inset LatexCommand \ref{sub:External-Stack}
6128
6129 \end_inset
6130
6131 \SpecialChar ~
6132  External Stack for more details.
6133 \layout List
6134 \labelwidthstring 00.00.0000
6135
6136
6137 \series bold
6138 -
6139 \begin_inset ERT
6140 status Collapsed
6141
6142 \layout Standard
6143
6144 \backslash
6145 /
6146 \end_inset
6147
6148 -iram-size
6149 \series default
6150 \SpecialChar ~
6151 <Value>
6152 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
6153
6154 \end_inset
6155
6156  Causes the linker to check if the internal ram usage is within limits of
6157  the given value.
6158 \layout List
6159 \labelwidthstring 00.00.0000
6160
6161
6162 \series bold
6163 -
6164 \begin_inset ERT
6165 status Collapsed
6166
6167 \layout Standard
6168
6169 \backslash
6170 /
6171 \end_inset
6172
6173 -xram-size
6174 \series default
6175 \SpecialChar ~
6176 <Value>
6177 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
6178
6179 \end_inset
6180
6181  Causes the linker to check if the external ram usage is within limits of
6182  the given value.
6183 \layout List
6184 \labelwidthstring 00.00.0000
6185
6186
6187 \series bold
6188 -
6189 \begin_inset ERT
6190 status Collapsed
6191
6192 \layout Standard
6193
6194 \backslash
6195 /
6196 \end_inset
6197
6198 -code-size
6199 \series default
6200 \SpecialChar ~
6201 <Value>
6202 \begin_inset LatexCommand \index{-\/-code-size <Value>}
6203
6204 \end_inset
6205
6206  Causes the linker to check if the code memory usage is within limits of
6207  the given value.
6208 \layout List
6209 \labelwidthstring 00.00.0000
6210
6211
6212 \series bold
6213 -
6214 \begin_inset ERT
6215 status Collapsed
6216
6217 \layout Standard
6218
6219 \backslash
6220 /
6221 \end_inset
6222
6223 -stack-size
6224 \series default
6225 \SpecialChar ~
6226 <Value>
6227 \begin_inset LatexCommand \index{-\/-stack-size <Value>}
6228
6229 \end_inset
6230
6231  Causes the linker to check if there is at minimum <Value> bytes for stack.
6232 \layout List
6233 \labelwidthstring 00.00.0000
6234
6235
6236 \series bold
6237 -
6238 \begin_inset ERT
6239 status Collapsed
6240
6241 \layout Standard
6242
6243 \backslash
6244 /
6245 \end_inset
6246
6247 -pack-iram
6248 \series default
6249 \SpecialChar ~
6250
6251 \begin_inset LatexCommand \index{-\/-pack-iram}
6252
6253 \end_inset
6254
6255  Causes the linker to use unused register banks for data variables and pack
6256  data, idata and stack together.
6257  This is the default now.
6258 \layout List
6259 \labelwidthstring 00.00.0000
6260
6261
6262 \series bold
6263 -
6264 \begin_inset ERT
6265 status Collapsed
6266
6267 \layout Standard
6268
6269 \backslash
6270 /
6271 \end_inset
6272
6273 -no-pack-iram
6274 \series default
6275 \SpecialChar ~
6276
6277 \begin_inset LatexCommand \index{-\/-no-pack-iram}
6278
6279 \end_inset
6280
6281  Causes the linker to use old style for allocating memory areas.
6282 \layout Subsection
6283
6284 DS390 / DS400 Options
6285 \begin_inset LatexCommand \index{Options DS390}
6286
6287 \end_inset
6288
6289
6290 \begin_inset LatexCommand \index{DS390 options}
6291
6292 \end_inset
6293
6294
6295 \layout List
6296 \labelwidthstring 00.00.0000
6297
6298
6299 \series bold
6300 -
6301 \begin_inset ERT
6302 status Collapsed
6303
6304 \layout Standard
6305
6306 \backslash
6307 /
6308 \end_inset
6309
6310 -model-flat24
6311 \series default
6312
6313 \begin_inset LatexCommand \index{-\/-model-flat24}
6314
6315 \end_inset
6316
6317
6318 \size large
6319 \emph on
6320
6321 \size default
6322 \emph default
6323 Generate 24-bit flat mode code.
6324  This is the one and only that the ds390 code generator supports right now
6325  and is default when using
6326 \emph on
6327 -mds390
6328 \emph default
6329 .
6330  See section Memory Models for more details.
6331 \layout List
6332 \labelwidthstring 00.00.0000
6333
6334
6335 \series bold
6336 -
6337 \begin_inset ERT
6338 status Collapsed
6339
6340 \layout Standard
6341
6342 \backslash
6343 /
6344 \end_inset
6345
6346 -protect-sp-update
6347 \begin_inset LatexCommand \index{-\/-protect-sp-update}
6348
6349 \end_inset
6350
6351
6352 \series default
6353  disable interrupts during ESP:SP updates.
6354 \layout List
6355 \labelwidthstring 00.00.0000
6356
6357
6358 \series bold
6359 -
6360 \begin_inset ERT
6361 status Collapsed
6362
6363 \layout Standard
6364
6365 \backslash
6366 /
6367 \end_inset
6368
6369 -stack-10bit
6370 \series default
6371
6372 \begin_inset LatexCommand \index{-\/-stack-10bit}
6373
6374 \end_inset
6375
6376  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
6377  This is the one and only that the ds390 code generator supports right now
6378  and is default when using
6379 \emph on
6380 -mds390
6381 \emph default
6382 .
6383  In this mode, the stack is located in the lower 1K of the internal RAM,
6384  which is mapped to 0x400000.
6385  Note that the support is incomplete, since it still uses a single byte
6386  as the stack pointer.
6387  This means that only the lower 256 bytes of the potential 1K stack space
6388  will actually be used.
6389  However, this does allow you to reclaim the precious 256 bytes of low RAM
6390  for use for the DATA and IDATA segments.
6391  The compiler will not generate any code to put the processor into 10 bit
6392  stack mode.
6393  It is important to ensure that the processor is in this mode before calling
6394  any re-entrant functions compiled with this option.
6395  In principle, this should work with the
6396 \emph on
6397 -
6398 \begin_inset ERT
6399 status Collapsed
6400
6401 \layout Standard
6402
6403 \backslash
6404 /
6405 \end_inset
6406
6407 -stack-auto
6408 \begin_inset LatexCommand \index{-\/-stack-auto}
6409
6410 \end_inset
6411
6412
6413 \emph default
6414  option, but that has not been tested.
6415  It is incompatible with the
6416 \emph on
6417 -
6418 \begin_inset ERT
6419 status Collapsed
6420
6421 \layout Standard
6422
6423 \backslash
6424 /
6425 \end_inset
6426
6427 -xstack
6428 \begin_inset LatexCommand \index{-\/-xstack}
6429
6430 \end_inset
6431
6432
6433 \emph default
6434  option.
6435  It also only makes sense if the processor is in 24 bit contiguous addressing
6436  mode (see the
6437 \emph on
6438 -
6439 \begin_inset ERT
6440 status Collapsed
6441
6442 \layout Standard
6443
6444 \backslash
6445 /
6446 \end_inset
6447
6448 -model-flat24 option
6449 \emph default
6450 ).
6451 \layout List
6452 \labelwidthstring 00.00.0000
6453
6454
6455 \series bold
6456 -
6457 \begin_inset ERT
6458 status Collapsed
6459
6460 \layout Standard
6461
6462 \backslash
6463 /
6464 \end_inset
6465
6466 -stack-probe
6467 \begin_inset LatexCommand \index{-\/-stack-probe}
6468
6469 \end_inset
6470
6471
6472 \series default
6473  insert call to function __stack_probe at each function prologue.
6474 \layout List
6475 \labelwidthstring 00.00.0000
6476
6477
6478 \series bold
6479 -
6480 \begin_inset ERT
6481 status Collapsed
6482
6483 \layout Standard
6484
6485 \backslash
6486 /
6487 \end_inset
6488
6489 -tini-libid
6490 \begin_inset LatexCommand \index{-\/-tini-libid}
6491
6492 \end_inset
6493
6494
6495 \series default
6496  <nnnn> LibraryID used in -mTININative.
6497
6498 \layout List
6499 \labelwidthstring 00.00.0000
6500
6501
6502 \series bold
6503 -
6504 \begin_inset ERT
6505 status Collapsed
6506
6507 \layout Standard
6508
6509 \backslash
6510 /
6511 \end_inset
6512
6513 -use-accelerator
6514 \begin_inset LatexCommand \index{-\/-use-accelerator}
6515
6516 \end_inset
6517
6518
6519 \series default
6520  generate code for DS390 Arithmetic Accelerator.
6521
6522 \layout Subsection
6523
6524 Z80 Options
6525 \begin_inset LatexCommand \index{Options Z80}
6526
6527 \end_inset
6528
6529
6530 \begin_inset LatexCommand \index{Z80 options}
6531
6532 \end_inset
6533
6534
6535 \layout List
6536 \labelwidthstring 00.00.0000
6537
6538
6539 \series bold
6540 -
6541 \begin_inset ERT
6542 status Collapsed
6543
6544 \layout Standard
6545
6546 \backslash
6547 /
6548 \end_inset
6549
6550 -callee-saves-bc
6551 \series default
6552
6553 \begin_inset LatexCommand \index{-\/-callee-saves-bc}
6554
6555 \end_inset
6556
6557
6558 \size large
6559 \emph on
6560
6561 \size default
6562 \emph default
6563 Force a called function to always save BC.
6564 \layout List
6565 \labelwidthstring 00.00.0000
6566
6567
6568 \series bold
6569 -
6570 \begin_inset ERT
6571 status Collapsed
6572
6573 \layout Standard
6574
6575 \backslash
6576 /
6577 \end_inset
6578
6579 -no-std-crt0
6580 \series default
6581
6582 \begin_inset LatexCommand \index{-\/-no-std-crt0}
6583
6584 \end_inset
6585
6586  When linking, skip the standard crt0.o object file.
6587  You must provide your own crt0.o for your system when linking.
6588
6589 \layout Subsection
6590
6591 Optimization Options
6592 \begin_inset LatexCommand \index{Options optimization}
6593
6594 \end_inset
6595
6596
6597 \begin_inset LatexCommand \index{Optimization options}
6598
6599 \end_inset
6600
6601
6602 \layout List
6603 \labelwidthstring 00.00.0000
6604
6605
6606 \series bold
6607 -
6608 \begin_inset ERT
6609 status Collapsed
6610
6611 \layout Standard
6612
6613 \backslash
6614 /
6615 \end_inset
6616
6617 -nogcse
6618 \begin_inset LatexCommand \index{-\/-nogcse}
6619
6620 \end_inset
6621
6622
6623 \series default
6624  Will not do global subexpression elimination, this option may be used when
6625  the compiler creates undesirably large stack/data spaces to store compiler
6626  temporaries (
6627 \emph on
6628 s
6629 \emph default
6630 pill
6631 \emph on
6632 loc
6633 \emph default
6634 ations, sloc
6635 \begin_inset LatexCommand \index{sloc (spill location)}
6636
6637 \end_inset
6638
6639 ).
6640  A warning message will be generated when this happens and the compiler
6641  will indicate the number of extra bytes it allocated.
6642  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6643 nogcse
6644 \begin_inset LatexCommand \index{\#pragma nogcse}
6645
6646 \end_inset
6647
6648  can be used to turn off global subexpression elimination
6649 \begin_inset LatexCommand \index{Subexpression elimination}
6650
6651 \end_inset
6652
6653  for a given function only.
6654 \layout List
6655 \labelwidthstring 00.00.0000
6656
6657
6658 \series bold
6659 -
6660 \begin_inset ERT
6661 status Collapsed
6662
6663 \layout Standard
6664
6665 \backslash
6666 /
6667 \end_inset
6668
6669 -noinvariant
6670 \begin_inset LatexCommand \index{-\/-noinvariant}
6671
6672 \end_inset
6673
6674
6675 \series default
6676  Will not do loop invariant optimizations, this may be turned off for reasons
6677  explained for the previous option.
6678  For more details of loop optimizations performed see Loop Invariants in
6679  section
6680 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
6681
6682 \end_inset
6683
6684 .
6685  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6686 noinvariant
6687 \begin_inset LatexCommand \index{\#pragma noinvariant}
6688
6689 \end_inset
6690
6691  can be used to turn off invariant optimizations for a given function only.
6692 \layout List
6693 \labelwidthstring 00.00.0000
6694
6695
6696 \series bold
6697 -
6698 \begin_inset ERT
6699 status Collapsed
6700
6701 \layout Standard
6702
6703 \backslash
6704 /
6705 \end_inset
6706
6707 -noinduction
6708 \begin_inset LatexCommand \index{-\/-noinduction}
6709
6710 \end_inset
6711
6712
6713 \series default
6714  Will not do loop induction optimizations, see section strength reduction
6715  for more details.
6716  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6717 noinduction
6718 \begin_inset LatexCommand \index{\#pragma noinduction}
6719
6720 \end_inset
6721
6722  can be used to turn off induction optimizations for a given function only.
6723 \layout List
6724 \labelwidthstring 00.00.0000
6725
6726
6727 \series bold
6728 -
6729 \begin_inset ERT
6730 status Collapsed
6731
6732 \layout Standard
6733
6734 \backslash
6735 /
6736 \end_inset
6737
6738 -nojtbound
6739 \begin_inset LatexCommand \index{-\/-nojtbound}
6740
6741 \end_inset
6742
6743
6744 \size large
6745 \bar under
6746
6747 \series default
6748 \size default
6749 \bar default
6750  Will not generate boundary condition check when switch statements
6751 \begin_inset LatexCommand \index{switch statement}
6752
6753 \end_inset
6754
6755  are implemented using jump-tables.
6756  See section
6757 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
6758
6759 \end_inset
6760
6761 \SpecialChar ~
6762 Switch Statements for more details.
6763  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6764 nojtbound
6765 \begin_inset LatexCommand \index{\#pragma nojtbound}
6766
6767 \end_inset
6768
6769  can be used to turn off boundary checking for jump tables for a given function
6770  only.
6771 \layout List
6772 \labelwidthstring 00.00.0000
6773
6774
6775 \series bold
6776 -
6777 \begin_inset ERT
6778 status Collapsed
6779
6780 \layout Standard
6781
6782 \backslash
6783 /
6784 \end_inset
6785
6786 -noloopreverse
6787 \begin_inset LatexCommand \index{-\/-noloopreverse}
6788
6789 \end_inset
6790
6791
6792 \series default
6793 \size large
6794
6795 \size default
6796 Will not do loop reversal
6797 \begin_inset LatexCommand \index{Loop reversing}
6798
6799 \end_inset
6800
6801 optimization.
6802 \layout List
6803 \labelwidthstring 00.00.0000
6804
6805 -
6806 \begin_inset ERT
6807 status Collapsed
6808
6809 \layout Standard
6810
6811 \backslash
6812 /
6813 \end_inset
6814
6815 -
6816 \series bold
6817 nolabelopt
6818 \series default
6819
6820 \begin_inset LatexCommand \index{-\/-nolabelopt }
6821
6822 \end_inset
6823
6824 Will not optimize labels (makes the dumpfiles more readable).
6825 \layout List
6826 \labelwidthstring 00.00.0000
6827
6828
6829 \series bold
6830 -
6831 \begin_inset ERT
6832 status Collapsed
6833
6834 \layout Standard
6835
6836 \backslash
6837 /
6838 \end_inset
6839
6840 -no-xinit-opt
6841 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
6842
6843 \end_inset
6844
6845
6846 \series default
6847  Will not memcpy initialized data from code space into xdata space.
6848  This saves a few bytes in code space if you don't have initialized data
6849 \begin_inset LatexCommand \index{Variable initialization}
6850
6851 \end_inset
6852
6853 .
6854 \layout List
6855 \labelwidthstring 00.00.0000
6856
6857
6858 \series bold
6859 -
6860 \begin_inset ERT
6861 status Collapsed
6862
6863 \layout Standard
6864
6865 \backslash
6866 /
6867 \end_inset
6868
6869 -nooverlay
6870 \begin_inset LatexCommand \index{-\/-nooverlay}
6871
6872 \end_inset
6873
6874
6875 \series default
6876   The compiler will not overlay parameters and local variables of any function,
6877  see section Parameters and local variables for more details.
6878 \layout List
6879 \labelwidthstring 00.00.0000
6880
6881
6882 \series bold
6883 -
6884 \begin_inset ERT
6885 status Collapsed
6886
6887 \layout Standard
6888
6889 \backslash
6890 /
6891 \end_inset
6892
6893 -no-peep
6894 \begin_inset LatexCommand \index{-\/-no-peep}
6895
6896 \end_inset
6897
6898
6899 \series default
6900  Disable peep-hole optimization.
6901 \layout List
6902 \labelwidthstring 00.00.0000
6903
6904
6905 \series bold
6906 -
6907 \begin_inset ERT
6908 status Collapsed
6909
6910 \layout Standard
6911
6912 \backslash
6913 /
6914 \end_inset
6915
6916 -peep-file
6917 \series default
6918
6919 \begin_inset LatexCommand \index{-\/-peep-file}
6920
6921 \end_inset
6922
6923 \SpecialChar ~
6924 <filename> This option can be used to use additional rules to be used by
6925  the peep hole optimizer.
6926  See section
6927 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
6928
6929 \end_inset
6930
6931 \SpecialChar ~
6932 Peep Hole optimizations for details on how to write these rules.
6933 \layout List
6934 \labelwidthstring 00.00.0000
6935
6936
6937 \series bold
6938 -
6939 \begin_inset ERT
6940 status Collapsed
6941
6942 \layout Standard
6943
6944 \backslash
6945 /
6946 \end_inset
6947
6948 -peep-asm
6949 \begin_inset LatexCommand \index{-\/-peep-asm}
6950
6951 \end_inset
6952
6953
6954 \series default
6955  Pass the inline assembler code through the peep hole optimizer.
6956  This can cause unexpected changes to inline assembler code, please go through
6957  the peephole optimizer
6958 \begin_inset LatexCommand \index{Peephole optimizer}
6959
6960 \end_inset
6961
6962  rules defined in the source file tree '<target>/peeph.def' before using
6963  this option.
6964 \layout List
6965 \labelwidthstring 00.00.0000
6966
6967
6968 \series bold
6969 -
6970 \begin_inset ERT
6971 status Collapsed
6972
6973 \layout Standard
6974
6975 \backslash
6976 /
6977 \end_inset
6978
6979 -opt-code-speed
6980 \begin_inset LatexCommand \index{-\/-opt-code-speed}
6981
6982 \end_inset
6983
6984
6985 \series default
6986  The compiler will optimize code generation towards fast code, possibly
6987  at the expense of code size.
6988 \layout List
6989 \labelwidthstring 00.00.0000
6990
6991
6992 \series bold
6993 -
6994 \begin_inset ERT
6995 status Collapsed
6996
6997 \layout Standard
6998
6999 \backslash
7000 /
7001 \end_inset
7002
7003 -opt-code-size
7004 \begin_inset LatexCommand \index{-\/-opt-code-size}
7005
7006 \end_inset
7007
7008
7009 \series default
7010  The compiler will optimize code generation towards compact code, possibly
7011  at the expense of code speed.
7012 \layout Subsection
7013
7014 Other Options
7015 \begin_inset LatexCommand \index{Options other}
7016
7017 \end_inset
7018
7019
7020 \layout List
7021 \labelwidthstring 00.00.0000
7022
7023
7024 \series bold
7025 -c\SpecialChar ~
7026 -
7027 \begin_inset ERT
7028 status Collapsed
7029
7030 \layout Standard
7031
7032 \backslash
7033 /
7034 \end_inset
7035
7036 -compile-only
7037 \begin_inset LatexCommand \index{-\/-compile-only}
7038
7039 \end_inset
7040
7041
7042 \begin_inset LatexCommand \index{-c -\/-compile-only}
7043
7044 \end_inset
7045
7046
7047 \series default
7048  will compile and assemble the source, but will not call the linkage editor.
7049 \layout List
7050 \labelwidthstring 00.00.0000
7051
7052
7053 \series bold
7054 -
7055 \series default
7056
7057 \begin_inset ERT
7058 status Collapsed
7059
7060 \layout Standard
7061
7062 \backslash
7063 /
7064 \end_inset
7065
7066
7067 \series bold
7068 -c1mode
7069 \begin_inset LatexCommand \index{-\/-c1mode}
7070
7071 \end_inset
7072
7073
7074 \series default
7075  reads the preprocessed source from standard input and compiles it.
7076  The file name for the assembler output must be specified using the -o option.
7077 \layout List
7078 \labelwidthstring 00.00.0000
7079
7080
7081 \series bold
7082 -E
7083 \begin_inset LatexCommand \index{-E}
7084
7085 \end_inset
7086
7087
7088 \series default
7089  Run only the C preprocessor.
7090  Preprocess all the C source files specified and output the results to standard
7091  output.
7092 \layout List
7093 \labelwidthstring 00.00.0000
7094
7095
7096 \series bold
7097 -o\SpecialChar ~
7098 <path/file>
7099 \begin_inset LatexCommand \index{-o <path/file>}
7100
7101 \end_inset
7102
7103
7104 \series default
7105 The output path resp.
7106  file where everything will be placed.
7107  If the parameter is a path, it must have a trailing slash (or backslash
7108  for the Windows binaries) to be recognized as a path.
7109
7110 \layout List
7111 \labelwidthstring 00.00.0000
7112
7113
7114 \series bold
7115 -
7116 \begin_inset ERT
7117 status Collapsed
7118
7119 \layout Standard
7120
7121 \backslash
7122 /
7123 \end_inset
7124
7125 -stack-auto
7126 \begin_inset LatexCommand \index{-\/-stack-auto}
7127
7128 \end_inset
7129
7130
7131 \series default
7132 \size large
7133 \emph on
7134
7135 \size default
7136 \emph default
7137 All functions in the source file will be compiled as
7138 \emph on
7139 reentrant
7140 \emph default
7141
7142 \begin_inset LatexCommand \index{reentrant}
7143
7144 \end_inset
7145
7146 , i.e.
7147  the parameters and local variables will be allocated on the stack
7148 \begin_inset LatexCommand \index{stack}
7149
7150 \end_inset
7151
7152 .
7153  See section
7154 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
7155
7156 \end_inset
7157
7158  Parameters and Local Variables for more details.
7159  If this option is used all source files in the project should be compiled
7160  with this option.
7161  It automatically implies --int-long-reent and --float-reent.
7162
7163 \layout List
7164 \labelwidthstring 00.00.0000
7165
7166
7167 \series bold
7168 -
7169 \begin_inset ERT
7170 status Collapsed
7171
7172 \layout Standard
7173
7174 \backslash
7175 /
7176 \end_inset
7177
7178 -callee-saves
7179 \begin_inset LatexCommand \index{-\/-callee-saves}
7180
7181 \end_inset
7182
7183  function1[,function2][,function3]....
7184
7185 \series default
7186  The compiler by default uses a caller saves convention for register saving
7187  across function calls, however this can cause unnecessary register pushing
7188  & popping when calling small functions from larger functions.
7189  This option can be used to switch the register saving convention for the
7190  function names specified.
7191  The compiler will not save registers when calling these functions, no extra
7192  code will be generated at the entry & exit (function prologue
7193 \series bold
7194
7195 \begin_inset LatexCommand \index{function prologue}
7196
7197 \end_inset
7198
7199
7200 \series default
7201  & epilogue
7202 \series bold
7203
7204 \begin_inset LatexCommand \index{function epilogue}
7205
7206 \end_inset
7207
7208
7209 \series default
7210 ) for these functions to save & restore the registers used by these functions,
7211  this can SUBSTANTIALLY reduce code & improve run time performance of the
7212  generated code.
7213  In the future the compiler (with inter procedural analysis) will be able
7214  to determine the appropriate scheme to use for each function call.
7215  DO NOT use this option for built-in functions such as _mulint..., if this
7216  option is used for a library function the appropriate library function
7217  needs to be recompiled with the same option.
7218  If the project consists of multiple source files then all the source file
7219  should be compiled with the same -
7220 \begin_inset ERT
7221 status Collapsed
7222
7223 \layout Standard
7224
7225 \backslash
7226 /
7227 \end_inset
7228
7229 -callee-saves option string.
7230  Also see #pragma\SpecialChar ~
7231 callee_saves
7232 \begin_inset LatexCommand \index{\#pragma callee\_saves}
7233
7234 \end_inset
7235
7236 .
7237 \layout List
7238 \labelwidthstring 00.00.0000
7239
7240
7241 \series bold
7242 -
7243 \begin_inset ERT
7244 status Collapsed
7245
7246 \layout Standard
7247
7248 \backslash
7249 /
7250 \end_inset
7251
7252 -debug
7253 \begin_inset LatexCommand \index{-\/-debug}
7254
7255 \end_inset
7256
7257
7258 \bar under
7259
7260 \series default
7261 \bar default
7262 When this option is used the compiler will generate debug information.
7263  The debug information collected in a file with .cdb extension can be used
7264  with the SDCDB.
7265  For more information see documentation for SDCDB.
7266  Another file with no extension contains debug information in AOMF or AOMF51
7267 \begin_inset LatexCommand \index{AOMF, AOMF51}
7268
7269 \end_inset
7270
7271  format which is commonly used by third party tools.
7272 \layout List
7273 \labelwidthstring 00.00.0000
7274
7275
7276 \series bold
7277 -S
7278 \begin_inset LatexCommand \index{-S}
7279
7280 \end_inset
7281
7282
7283 \size large
7284 \bar under
7285
7286 \series default
7287 \size default
7288 \bar default
7289 Stop after the stage of compilation proper; do not assemble.
7290  The output is an assembler code file for the input file specified.
7291 \layout List
7292 \labelwidthstring 00.00.0000
7293
7294
7295 \series bold
7296 -
7297 \begin_inset ERT
7298 status Collapsed
7299
7300 \layout Standard
7301
7302 \backslash
7303 /
7304 \end_inset
7305
7306 -int-long-reent
7307 \begin_inset LatexCommand \index{-\/-int-long-reent}
7308
7309 \end_inset
7310
7311
7312 \series default
7313  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
7314  Note by default these libraries are compiled as non-reentrant.
7315  See section Installation for more details.
7316 \layout List
7317 \labelwidthstring 00.00.0000
7318
7319
7320 \series bold
7321 -
7322 \begin_inset ERT
7323 status Collapsed
7324
7325 \layout Standard
7326
7327 \backslash
7328 /
7329 \end_inset
7330
7331 -cyclomatic
7332 \begin_inset LatexCommand \index{-\/-cyclomatic}
7333
7334 \end_inset
7335
7336
7337 \bar under
7338
7339 \series default
7340 \bar default
7341 This option will cause the compiler to generate an information message for
7342  each function in the source file.
7343  The message contains some
7344 \emph on
7345 important
7346 \emph default
7347  information about the function.
7348  The number of edges and nodes the compiler detected in the control flow
7349  graph of the function, and most importantly the
7350 \emph on
7351 cyclomatic complexity
7352 \begin_inset LatexCommand \index{Cyclomatic complexity}
7353
7354 \end_inset
7355
7356
7357 \emph default
7358  see section on Cyclomatic Complexity for more details.
7359 \layout List
7360 \labelwidthstring 00.00.0000
7361
7362
7363 \series bold
7364 -
7365 \begin_inset ERT
7366 status Collapsed
7367
7368 \layout Standard
7369
7370 \backslash
7371 /
7372 \end_inset
7373
7374 -float-reent
7375 \begin_inset LatexCommand \index{-\/-float-reent}
7376
7377 \end_inset
7378
7379
7380 \series default
7381  Floating point library is compiled as reentrant
7382 \begin_inset LatexCommand \index{reentrant}
7383
7384 \end_inset
7385
7386 .
7387  See section Installation for more details.
7388 \layout List
7389 \labelwidthstring 00.00.0000
7390
7391
7392 \series bold
7393 -
7394 \begin_inset ERT
7395 status Collapsed
7396
7397 \layout Standard
7398
7399 \backslash
7400 /
7401 \end_inset
7402
7403 -main-return
7404 \begin_inset LatexCommand \index{-\/-main-return}
7405
7406 \end_inset
7407
7408
7409 \series default
7410  This option can be used if the code generated is called by a monitor program
7411  or if the main routine includes an endless loop.
7412  This option might result in slightly smaller code and save two bytes of
7413  stack space.
7414  The return from the 'main'
7415 \begin_inset LatexCommand \index{main return}
7416
7417 \end_inset
7418
7419  function will return to the function calling main.
7420  The default setting is to lock up i.e.
7421  generate a '
7422 \family typewriter
7423 sjmp .
7424 \family default
7425 '.
7426 \layout List
7427 \labelwidthstring 00.00.0000
7428
7429
7430 \series bold
7431 -
7432 \begin_inset ERT
7433 status Collapsed
7434
7435 \layout Standard
7436
7437 \backslash
7438 /
7439 \end_inset
7440
7441 -nostdinc
7442 \begin_inset LatexCommand \index{-\/-nostdinc}
7443
7444 \end_inset
7445
7446
7447 \series default
7448  This will prevent the compiler from passing on the default include path
7449  to the preprocessor.
7450 \layout List
7451 \labelwidthstring 00.00.0000
7452
7453
7454 \series bold
7455 -
7456 \begin_inset ERT
7457 status Collapsed
7458
7459 \layout Standard
7460
7461 \backslash
7462 /
7463 \end_inset
7464
7465 -nostdlib
7466 \begin_inset LatexCommand \index{-\/-nostdlib}
7467
7468 \end_inset
7469
7470
7471 \series default
7472  This will prevent the compiler from passing on the default library
7473 \begin_inset LatexCommand \index{Libraries}
7474
7475 \end_inset
7476
7477  path to the linker.
7478 \layout List
7479 \labelwidthstring 00.00.0000
7480
7481
7482 \series bold
7483 -
7484 \begin_inset ERT
7485 status Collapsed
7486
7487 \layout Standard
7488
7489 \backslash
7490 /
7491 \end_inset
7492
7493 -verbose
7494 \begin_inset LatexCommand \index{-\/-verbose}
7495
7496 \end_inset
7497
7498
7499 \series default
7500  Shows the various actions the compiler is performing.
7501 \layout List
7502 \labelwidthstring 00.00.0000
7503
7504
7505 \series bold
7506 -V
7507 \begin_inset LatexCommand \index{-V}
7508
7509 \end_inset
7510
7511
7512 \series default
7513  Shows the actual commands the compiler is executing.
7514 \layout List
7515 \labelwidthstring 00.00.0000
7516
7517
7518 \series bold
7519 -
7520 \begin_inset ERT
7521 status Collapsed
7522
7523 \layout Standard
7524
7525 \backslash
7526 /
7527 \end_inset
7528
7529 -no-c-code-in-asm
7530 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
7531
7532 \end_inset
7533
7534
7535 \series default
7536  Hides your ugly and inefficient c-code from the asm file, so you can always
7537  blame the compiler :)
7538 \layout List
7539 \labelwidthstring 00.00.0000
7540
7541
7542 \series bold
7543 -
7544 \begin_inset ERT
7545 status Collapsed
7546
7547 \layout Standard
7548
7549 \backslash
7550 /
7551 \end_inset
7552
7553 -no-peep-comments
7554 \begin_inset LatexCommand \index{-\/-no-peep-comments}
7555
7556 \end_inset
7557
7558
7559 \series default
7560  Will not include peep-hole comments in the generated files.
7561 \layout List
7562 \labelwidthstring 00.00.0000
7563
7564
7565 \series bold
7566 -
7567 \begin_inset ERT
7568 status Collapsed
7569
7570 \layout Standard
7571
7572 \backslash
7573 /
7574 \end_inset
7575
7576 -i-code-in-asm
7577 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
7578
7579 \end_inset
7580
7581
7582 \series default
7583  Include i-codes in the asm file.
7584  Sounds like noise but is most helpful for debugging the compiler itself.
7585 \layout List
7586 \labelwidthstring 00.00.0000
7587
7588
7589 \series bold
7590 -
7591 \begin_inset ERT
7592 status Collapsed
7593
7594 \layout Standard
7595
7596 \backslash
7597 /
7598 \end_inset
7599
7600 -less-pedantic
7601 \begin_inset LatexCommand \index{-\/-less-pedantic}
7602
7603 \end_inset
7604
7605
7606 \series default
7607  Disable some of the more pedantic warnings
7608 \begin_inset LatexCommand \index{Warnings}
7609
7610 \end_inset
7611
7612  (jwk burps: please be more specific here, please!).
7613 \layout List
7614 \labelwidthstring 00.00.0000
7615
7616
7617 \series bold
7618 -
7619 \begin_inset ERT
7620 status Collapsed
7621
7622 \layout Standard
7623
7624 \backslash
7625 /
7626 \end_inset
7627
7628 -disable-warning\SpecialChar ~
7629 <nnnn>
7630 \begin_inset LatexCommand \index{-\/-disable-warning}
7631
7632 \end_inset
7633
7634
7635 \series default
7636  Disable specific warning with number <nnnn>.
7637 \layout List
7638 \labelwidthstring 00.00.0000
7639
7640
7641 \series bold
7642 -
7643 \begin_inset ERT
7644 status Collapsed
7645
7646 \layout Standard
7647
7648 \backslash
7649 /
7650 \end_inset
7651
7652 -print-search-dirs
7653 \begin_inset LatexCommand \index{-\/-print-search-dirs}
7654
7655 \end_inset
7656
7657
7658 \series default
7659  Display the directories in the compiler's search path
7660 \layout List
7661 \labelwidthstring 00.00.0000
7662
7663
7664 \series bold
7665 -
7666 \begin_inset ERT
7667 status Collapsed
7668
7669 \layout Standard
7670
7671 \backslash
7672 /
7673 \end_inset
7674
7675 -vc
7676 \begin_inset LatexCommand \index{-\/-vc}
7677
7678 \end_inset
7679
7680
7681 \series default
7682  Display errors and warnings using MSVC style, so you can use SDCC with
7683  visual studio.
7684 \layout List
7685 \labelwidthstring 00.00.0000
7686
7687
7688 \series bold
7689 -
7690 \begin_inset ERT
7691 status Collapsed
7692
7693 \layout Standard
7694
7695 \backslash
7696 /
7697 \end_inset
7698
7699 -use-stdout
7700 \begin_inset LatexCommand \index{-\/-use-stdout}
7701
7702 \end_inset
7703
7704
7705 \series default
7706  Send errors and warnings to stdout instead of stderr.
7707 \layout List
7708 \labelwidthstring 00.00.0000
7709
7710
7711 \series bold
7712 -Wa\SpecialChar ~
7713 asmOption[,asmOption]
7714 \series default
7715
7716 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
7717
7718 \end_inset
7719
7720 ...
7721  Pass the asmOption to the assembler
7722 \begin_inset LatexCommand \index{Options assembler}
7723
7724 \end_inset
7725
7726
7727 \begin_inset LatexCommand \index{Assembler options}
7728
7729 \end_inset
7730
7731 .
7732  See file sdcc/as/doc/asxhtm.html for assembler options.cd
7733 \layout List
7734 \labelwidthstring 00.00.0000
7735
7736
7737 \series bold
7738 -
7739 \begin_inset ERT
7740 status Collapsed
7741
7742 \layout Standard
7743
7744 \backslash
7745 /
7746 \end_inset
7747
7748 -std-sdcc89
7749 \begin_inset LatexCommand \index{-\/-std-sdcc89}
7750
7751 \end_inset
7752
7753
7754 \series default
7755  Generally follow the C89 standard, but allow SDCC features that conflict
7756  with the standard (default).
7757 \layout List
7758 \labelwidthstring 00.00.0000
7759
7760
7761 \series bold
7762 -
7763 \begin_inset ERT
7764 status Collapsed
7765
7766 \layout Standard
7767
7768 \backslash
7769 /
7770 \end_inset
7771
7772 -std-c89
7773 \begin_inset LatexCommand \index{-\/-std-c89}
7774
7775 \end_inset
7776
7777
7778 \series default
7779  Follow the C89 standard and disable SDCC features that conflict with the
7780  standard.
7781 \layout List
7782 \labelwidthstring 00.00.0000
7783
7784
7785 \series bold
7786 -
7787 \begin_inset ERT
7788 status Collapsed
7789
7790 \layout Standard
7791
7792 \backslash
7793 /
7794 \end_inset
7795
7796 -std-sdcc99
7797 \begin_inset LatexCommand \index{-\/-std-sdcc99}
7798
7799 \end_inset
7800
7801
7802 \series default
7803  Generally follow the C99 standard, but allow SDCC features that conflict
7804  with the standard (incomplete support).
7805 \layout List
7806 \labelwidthstring 00.00.0000
7807
7808
7809 \series bold
7810 -
7811 \begin_inset ERT
7812 status Collapsed
7813
7814 \layout Standard
7815
7816 \backslash
7817 /
7818 \end_inset
7819
7820 -std-c99
7821 \begin_inset LatexCommand \index{-\/-std-sdcc99}
7822
7823 \end_inset
7824
7825
7826 \series default
7827  Follow the C99 standard and disable SDCC features that conflict with the
7828  standard (incomplete support).
7829 \layout List
7830 \labelwidthstring 00.00.0000
7831
7832
7833 \series bold
7834 -
7835 \begin_inset ERT
7836 status Collapsed
7837
7838 \layout Standard
7839
7840 \backslash
7841 /
7842 \end_inset
7843
7844 -codeseg
7845 \series default
7846
7847 \begin_inset LatexCommand \index{-\/-codeseg <Value>}
7848
7849 \end_inset
7850
7851 \SpecialChar ~
7852 <Name> The name to be used for the code
7853 \begin_inset LatexCommand \index{code}
7854
7855 \end_inset
7856
7857  segment, default CSEG.
7858  This is useful if you need to tell the compiler to put the code in a special
7859  segment so you can later on tell the linker to put this segment in a special
7860  place in memory.
7861  Can be used for instance when using bank switching to put the code in a
7862  bank.
7863 \layout List
7864 \labelwidthstring 00.00.0000
7865
7866
7867 \series bold
7868 -
7869 \begin_inset ERT
7870 status Collapsed
7871
7872 \layout Standard
7873
7874 \backslash
7875 /
7876 \end_inset
7877
7878 -constseg
7879 \series default
7880
7881 \begin_inset LatexCommand \index{-\/-constseg <Value>}
7882
7883 \end_inset
7884
7885 \SpecialChar ~
7886 <Name> The name to be used for the const
7887 \begin_inset LatexCommand \index{code}
7888
7889 \end_inset
7890
7891  segment, default CONST.
7892  This is useful if you need to tell the compiler to put the const data in
7893  a special segment so you can later on tell the linker to put this segment
7894  in a special place in memory.
7895  Can be used for instance when using bank switching to put the const data
7896  in a bank.
7897 \layout List
7898 \labelwidthstring 00.00.0000
7899
7900
7901 \series bold
7902 more-pedantic
7903 \series default
7904  Actually this is
7905 \series bold
7906 \emph on
7907 not
7908 \series default
7909 \emph default
7910  a SDCC compiler option but if you want
7911 \emph on
7912 more
7913 \emph default
7914  warnings you can use a separate tool dedicated to syntax checking like
7915  splint
7916 \begin_inset LatexCommand \label{lyx:more-pedantic-SPLINT}
7917
7918 \end_inset
7919
7920
7921 \begin_inset LatexCommand \index{lint (syntax checking tool)}
7922
7923 \end_inset
7924
7925
7926 \begin_inset LatexCommand \url{http://www.splint.org}
7927
7928 \end_inset
7929
7930 .
7931  To make your source files parseable by splint you will have to include
7932
7933 \family sans
7934 lint.h
7935 \family default
7936
7937 \begin_inset LatexCommand \index{splint (syntax checking tool)}
7938
7939 \end_inset
7940
7941  in your source file and add brackets around extended keywords (like
7942 \family sans
7943
7944 \begin_inset Quotes sld
7945 \end_inset
7946
7947 __at\SpecialChar ~
7948
7949 \series bold
7950 (
7951 \series default
7952 0xab
7953 \series bold
7954 )
7955 \series default
7956
7957 \begin_inset Quotes srd
7958 \end_inset
7959
7960
7961 \family default
7962  and
7963 \family sans
7964
7965 \begin_inset Quotes sld
7966 \end_inset
7967
7968 __interrupt\SpecialChar ~
7969 (2)
7970 \begin_inset Quotes srd
7971 \end_inset
7972
7973
7974 \family default
7975 ).
7976
7977 \newline
7978 Splint has an excellent on line manual at
7979 \begin_inset LatexCommand \url{http://www.splint.org/manual/}
7980
7981 \end_inset
7982
7983  and it's capabilities go beyond pure syntax checking.
7984  You'll need to tell splint the location of SDCC's include files so a typical
7985  command line could look like this:
7986 \newline
7987
7988 \family sans
7989 splint\SpecialChar ~
7990 -I\SpecialChar ~
7991 /usr/local/share/sdcc/include/mcs51/\SpecialChar ~
7992 \SpecialChar ~
7993 myprogram.c
7994 \layout Subsection
7995
7996 Intermediate Dump Options
7997 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
7998
7999 \end_inset
8000
8001
8002 \begin_inset LatexCommand \index{Options intermediate dump}
8003
8004 \end_inset
8005
8006
8007 \begin_inset LatexCommand \index{Intermediate dump options}
8008
8009 \end_inset
8010
8011
8012 \layout Standard
8013
8014 The following options are provided for the purpose of retargetting and debugging
8015  the compiler.
8016  They provide a means to dump the intermediate code (iCode
8017 \begin_inset LatexCommand \index{iCode}
8018
8019 \end_inset
8020
8021 ) generated by the compiler in human readable form at various stages of
8022  the compilation process.
8023  More on iCodes see chapter
8024 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
8025
8026 \end_inset
8027
8028
8029 \begin_inset Quotes srd
8030 \end_inset
8031
8032 The anatomy of the compiler
8033 \begin_inset Quotes srd
8034 \end_inset
8035
8036 .
8037 \layout List
8038 \labelwidthstring 00.00.0000
8039
8040
8041 \series bold
8042 -
8043 \begin_inset ERT
8044 status Collapsed
8045
8046 \layout Standard
8047
8048 \backslash
8049 /
8050 \end_inset
8051
8052 -dumpraw
8053 \begin_inset LatexCommand \index{-\/-dumpraw}
8054
8055 \end_inset
8056
8057
8058 \series default
8059  This option will cause the compiler to dump the intermediate code into
8060  a file of named
8061 \emph on
8062 <source filename>.dumpraw
8063 \emph default
8064  just after the intermediate code has been generated for a function, i.e.
8065  before any optimizations are done.
8066  The basic blocks
8067 \begin_inset LatexCommand \index{Basic blocks}
8068
8069 \end_inset
8070
8071  at this stage ordered in the depth first number, so they may not be in
8072  sequence of execution.
8073 \layout List
8074 \labelwidthstring 00.00.0000
8075
8076
8077 \series bold
8078 -
8079 \begin_inset ERT
8080 status Collapsed
8081
8082 \layout Standard
8083
8084 \backslash
8085 /
8086 \end_inset
8087
8088 -dumpgcse
8089 \begin_inset LatexCommand \index{-\/-dumpgcse}
8090
8091 \end_inset
8092
8093
8094 \series default
8095  Will create a dump of iCode's, after global subexpression elimination
8096 \begin_inset LatexCommand \index{Global subexpression elimination}
8097
8098 \end_inset
8099
8100 , into a file named
8101 \emph on
8102 <source filename>.dumpgcse.
8103 \layout List
8104 \labelwidthstring 00.00.0000
8105
8106
8107 \series bold
8108 -
8109 \begin_inset ERT
8110 status Collapsed
8111
8112 \layout Standard
8113
8114 \backslash
8115 /
8116 \end_inset
8117
8118 -dumpdeadcode
8119 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
8120
8121 \end_inset
8122
8123
8124 \series default
8125  Will create a dump of iCode's, after deadcode elimination
8126 \begin_inset LatexCommand \index{Dead-code elimination}
8127
8128 \end_inset
8129
8130 , into a file named
8131 \emph on
8132 <source filename>.dumpdeadcode.
8133 \layout List
8134 \labelwidthstring 00.00.0000
8135
8136
8137 \series bold
8138 -
8139 \begin_inset ERT
8140 status Collapsed
8141
8142 \layout Standard
8143
8144 \backslash
8145 /
8146 \end_inset
8147
8148 -dumploop
8149 \begin_inset LatexCommand \index{-\/-dumploop}
8150
8151 \end_inset
8152
8153
8154 \series default
8155 \size large
8156
8157 \size default
8158 Will create a dump of iCode's, after loop optimizations
8159 \begin_inset LatexCommand \index{Loop optimization}
8160
8161 \end_inset
8162
8163 , into a file named
8164 \emph on
8165 <source filename>.dumploop.
8166 \layout List
8167 \labelwidthstring 00.00.0000
8168
8169
8170 \series bold
8171 -
8172 \begin_inset ERT
8173 status Collapsed
8174
8175 \layout Standard
8176
8177 \backslash
8178 /
8179 \end_inset
8180
8181 -dumprange
8182 \begin_inset LatexCommand \index{-\/-dumprange}
8183
8184 \end_inset
8185
8186
8187 \series default
8188 \size large
8189
8190 \size default
8191 Will create a dump of iCode's, after live range analysis
8192 \begin_inset LatexCommand \index{Live range analysis}
8193
8194 \end_inset
8195
8196 , into a file named
8197 \emph on
8198 <source filename>.dumprange.
8199 \layout List
8200 \labelwidthstring 00.00.0000
8201
8202
8203 \series bold
8204 -
8205 \begin_inset ERT
8206 status Collapsed
8207
8208 \layout Standard
8209
8210 \backslash
8211 /
8212 \end_inset
8213
8214 -dumlrange
8215 \begin_inset LatexCommand \index{-\/-dumlrange}
8216
8217 \end_inset
8218
8219
8220 \series default
8221  Will dump the life ranges
8222 \begin_inset LatexCommand \index{Live range analysis}
8223
8224 \end_inset
8225
8226  for all symbols.
8227 \layout List
8228 \labelwidthstring 00.00.0000
8229
8230
8231 \series bold
8232 -
8233 \begin_inset ERT
8234 status Collapsed
8235
8236 \layout Standard
8237
8238 \backslash
8239 /
8240 \end_inset
8241
8242 -dumpregassign
8243 \begin_inset LatexCommand \index{-\/-dumpregassign}
8244
8245 \end_inset
8246
8247
8248 \bar under
8249
8250 \series default
8251 \bar default
8252 Will create a dump of iCode's, after register assignment
8253 \begin_inset LatexCommand \index{Register assignment}
8254
8255 \end_inset
8256
8257 , into a file named
8258 \emph on
8259 <source filename>.dumprassgn.
8260 \layout List
8261 \labelwidthstring 00.00.0000
8262
8263
8264 \series bold
8265 -
8266 \begin_inset ERT
8267 status Collapsed
8268
8269 \layout Standard
8270
8271 \backslash
8272 /
8273 \end_inset
8274
8275 -dumplrange
8276 \begin_inset LatexCommand \index{-\/-dumplrange}
8277
8278 \end_inset
8279
8280
8281 \series default
8282  Will create a dump of the live ranges of iTemp's
8283 \layout List
8284 \labelwidthstring 00.00.0000
8285
8286
8287 \series bold
8288 -
8289 \begin_inset ERT
8290 status Collapsed
8291
8292 \layout Standard
8293
8294 \backslash
8295 /
8296 \end_inset
8297
8298 -dumpall
8299 \begin_inset LatexCommand \index{-\/-dumpall}
8300
8301 \end_inset
8302
8303
8304 \size large
8305 \bar under
8306
8307 \series default
8308 \size default
8309 \bar default
8310 Will cause all the above mentioned dumps to be created.
8311 \layout Subsection
8312
8313 Redirecting output on Windows Shells
8314 \layout Standard
8315
8316 By default SDCC writes it's error messages to
8317 \begin_inset Quotes sld
8318 \end_inset
8319
8320 standard error
8321 \begin_inset Quotes srd
8322 \end_inset
8323
8324 .
8325  To force all messages to
8326 \begin_inset Quotes sld
8327 \end_inset
8328
8329 standard output
8330 \begin_inset Quotes srd
8331 \end_inset
8332
8333  use
8334 \series bold
8335 -
8336 \series default
8337 \emph on
8338
8339 \begin_inset ERT
8340 status Collapsed
8341
8342 \layout Standard
8343
8344 \backslash
8345 /
8346 \end_inset
8347
8348
8349 \series bold
8350 \emph default
8351 -
8352 \series default
8353 use-stdout
8354 \begin_inset LatexCommand \index{-\/-use-stdout}
8355
8356 \end_inset
8357
8358 .
8359  Additionally, if you happen to have visual studio installed in your windows
8360  machine, you can use it to compile your sources using a custom build and
8361  the SDCC -
8362 \emph on
8363
8364 \begin_inset ERT
8365 status Collapsed
8366
8367 \layout Standard
8368
8369 \backslash
8370 /
8371 \end_inset
8372
8373
8374 \emph default
8375 -vc
8376 \begin_inset LatexCommand \index{-\/-vc}
8377
8378 \end_inset
8379
8380  option.
8381  Something like this should work:
8382 \newline
8383
8384 \newline
8385
8386 \series bold
8387 c:
8388 \backslash
8389 sdcc
8390 \backslash
8391 bin
8392 \backslash
8393 sdcc.exe -
8394 \series default
8395 \emph on
8396
8397 \begin_inset ERT
8398 status Collapsed
8399
8400 \layout Standard
8401
8402 \backslash
8403 /
8404 \end_inset
8405
8406
8407 \series bold
8408 \emph default
8409 -vc -
8410 \series default
8411 \emph on
8412
8413 \begin_inset ERT
8414 status Collapsed
8415
8416 \layout Standard
8417
8418 \backslash
8419 /
8420 \end_inset
8421
8422
8423 \series bold
8424 \emph default
8425 -model-large -c $(InputPath)
8426 \layout Section
8427
8428 Environment variables
8429 \begin_inset LatexCommand \index{Environment variables}
8430
8431 \end_inset
8432
8433
8434 \layout Standard
8435
8436 SDCC recognizes the following environment variables:
8437 \layout List
8438 \labelwidthstring 00.00.0000
8439
8440
8441 \series bold
8442 SDCC_LEAVE_SIGNALS
8443 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
8444
8445 \end_inset
8446
8447
8448 \series default
8449  SDCC installs a signal handler
8450 \begin_inset LatexCommand \index{signal handler}
8451
8452 \end_inset
8453
8454  to be able to delete temporary files after an user break (^C) or an exception.
8455  If this environment variable is set, SDCC won't install the signal handler
8456  in order to be able to debug SDCC.
8457 \layout List
8458 \labelwidthstring 00.00.0000
8459
8460
8461 \series bold
8462 TMP,\SpecialChar ~
8463 TEMP,\SpecialChar ~
8464 TMPDIR
8465 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
8466
8467 \end_inset
8468
8469
8470 \series default
8471  Path, where temporary files will be created.
8472  The order of the variables is the search order.
8473  In a standard *nix environment these variables are not set, and there's
8474  no need to set them.
8475  On Windows it's recommended to set one of them.
8476 \layout List
8477 \labelwidthstring 00.00.0000
8478
8479
8480 \series bold
8481 SDCC_HOME
8482 \begin_inset LatexCommand \index{SDCC\_HOME}
8483
8484 \end_inset
8485
8486
8487 \series default
8488  Path, see section
8489 \begin_inset LatexCommand \ref{sub:Install-paths}
8490
8491 \end_inset
8492
8493 \SpecialChar ~
8494
8495 \begin_inset Quotes sld
8496 \end_inset
8497
8498  Install Paths
8499 \begin_inset Quotes srd
8500 \end_inset
8501
8502 .
8503 \layout List
8504 \labelwidthstring 00.00.0000
8505
8506
8507 \series bold
8508 SDCC_INCLUDE
8509 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
8510
8511 \end_inset
8512
8513
8514 \series default
8515  Path, see section
8516 \begin_inset LatexCommand \ref{sub:Search-Paths}
8517
8518 \end_inset
8519
8520 \SpecialChar ~
8521
8522 \begin_inset Quotes sld
8523 \end_inset
8524
8525 Search Paths
8526 \begin_inset Quotes srd
8527 \end_inset
8528
8529 .
8530 \layout List
8531 \labelwidthstring 00.00.0000
8532
8533
8534 \series bold
8535 SDCC_LIB
8536 \begin_inset LatexCommand \index{SDCC\_LIB}
8537
8538 \end_inset
8539
8540
8541 \series default
8542  Path, see section
8543 \begin_inset LatexCommand \ref{sub:Search-Paths}
8544
8545 \end_inset
8546
8547 \SpecialChar ~
8548
8549 \begin_inset Quotes sld
8550 \end_inset
8551
8552 Search Paths
8553 \begin_inset Quotes srd
8554 \end_inset
8555
8556 ..
8557 \layout Standard
8558
8559 There are some more environment variables recognized by SDCC, but these
8560  are solely used for debugging purposes.
8561  They can change or disappear very quickly, and will never be documented.
8562 \layout Section
8563
8564 Storage Class Language Extensions
8565 \layout Subsection
8566
8567 MCS51/DS390 Storage Class
8568 \begin_inset LatexCommand \index{Storage class}
8569
8570 \end_inset
8571
8572  Language Extensions
8573 \layout Standard
8574
8575 In addition to the ANSI storage classes SDCC allows the following MCS51
8576  specific storage classes:
8577 \layout Subsubsection
8578
8579 data
8580 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
8581
8582 \end_inset
8583
8584
8585 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
8586
8587 \end_inset
8588
8589  / near
8590 \begin_inset LatexCommand \index{near (storage class)}
8591
8592 \end_inset
8593
8594
8595 \begin_inset LatexCommand \index{\_\_near (storage class)}
8596
8597 \end_inset
8598
8599
8600 \layout Standard
8601
8602 This is the
8603 \series bold
8604 default
8605 \series default
8606  storage class for the Small Memory model (
8607 \emph on
8608 data
8609 \emph default
8610  and
8611 \emph on
8612 near
8613 \emph default
8614  can be used synonymously).
8615  Variables declared with this storage class will be allocated in the directly
8616  addressable portion of the internal RAM of a 8051, e.g.:
8617 \layout Verse
8618
8619
8620 \family typewriter
8621 data unsigned char test_data;
8622 \layout Standard
8623
8624 Writing 0x01 to this variable generates the assembly code:
8625 \layout Verse
8626
8627
8628 \family typewriter
8629 75*00 01\SpecialChar ~
8630 \SpecialChar ~
8631 \SpecialChar ~
8632 mov\SpecialChar ~
8633 \SpecialChar ~
8634 _test_data,#0x01
8635 \layout Subsubsection
8636
8637 xdata
8638 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8639
8640 \end_inset
8641
8642
8643 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
8644
8645 \end_inset
8646
8647  / far
8648 \begin_inset LatexCommand \index{far (storage class)}
8649
8650 \end_inset
8651
8652
8653 \begin_inset LatexCommand \index{\_\_far (storage class)}
8654
8655 \end_inset
8656
8657
8658 \layout Standard
8659
8660 Variables declared with this storage class will be placed in the external
8661  RAM.
8662  This is the
8663 \series bold
8664 default
8665 \series default
8666  storage class for the Large Memory model, e.g.:
8667 \layout Verse
8668
8669
8670 \family typewriter
8671 xdata unsigned char test_xdata;
8672 \layout Standard
8673
8674 Writing 0x01 to this variable generates the assembly code:
8675 \layout Verse
8676
8677
8678 \family typewriter
8679 90s00r00\SpecialChar ~
8680 \SpecialChar ~
8681 \SpecialChar ~
8682 mov\SpecialChar ~
8683 \SpecialChar ~
8684 dptr,#_test_xdata
8685 \newline
8686 74\SpecialChar ~
8687 01\SpecialChar ~
8688 \SpecialChar ~
8689 \SpecialChar ~
8690 \SpecialChar ~
8691 \SpecialChar ~
8692 \SpecialChar ~
8693 mov\SpecialChar ~
8694 \SpecialChar ~
8695 a,#0x01
8696 \newline
8697 F0\SpecialChar ~
8698 \SpecialChar ~
8699 \SpecialChar ~
8700 \SpecialChar ~
8701 \SpecialChar ~
8702 \SpecialChar ~
8703 \SpecialChar ~
8704 \SpecialChar ~
8705 \SpecialChar ~
8706 movx\SpecialChar ~
8707 @dptr,a
8708 \layout Subsubsection
8709
8710 idata
8711 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
8712
8713 \end_inset
8714
8715
8716 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
8717
8718 \end_inset
8719
8720
8721 \layout Standard
8722
8723 Variables declared with this storage class will be allocated into the indirectly
8724  addressable portion of the internal ram of a 8051, e.g.:
8725 \layout Verse
8726
8727
8728 \family typewriter
8729 idata unsigned char test_idata;
8730 \layout Standard
8731
8732 Writing 0x01 to this variable generates the assembly code:
8733 \layout Verse
8734
8735
8736 \family typewriter
8737 78r00\SpecialChar ~
8738 \SpecialChar ~
8739 \SpecialChar ~
8740 \SpecialChar ~
8741 \SpecialChar ~
8742 \SpecialChar ~
8743 \SpecialChar ~
8744 mov\SpecialChar ~
8745 \SpecialChar ~
8746 r0,#_test_idata
8747 \newline
8748 76\SpecialChar ~
8749 01\SpecialChar ~
8750 \SpecialChar ~
8751 \SpecialChar ~
8752 \SpecialChar ~
8753 \SpecialChar ~
8754 \SpecialChar ~
8755 \SpecialChar ~
8756 mov\SpecialChar ~
8757 \SpecialChar ~
8758 @r0,#0x01
8759 \layout Standard
8760
8761 Please note, the first 128 byte of idata physically access the same RAM
8762  as the data memory.
8763  The original 8051 had 128 byte idata memory, nowadays most devices have
8764  256 byte idata memory.
8765  The stack
8766 \begin_inset LatexCommand \index{stack}
8767
8768 \end_inset
8769
8770  is located in idata memory.
8771 \layout Subsubsection
8772
8773 pdata
8774 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
8775
8776 \end_inset
8777
8778
8779 \begin_inset LatexCommand \index{\_\_pdata (mcs51, ds390 storage class)}
8780
8781 \end_inset
8782
8783
8784 \layout Standard
8785
8786 Paged xdata access is just as straightforward as using the other addressing
8787  modes of a 8051.
8788  It is typically located at the start of xdata and has a maximum size of
8789  256 bytes.
8790  The following example writes 0x01 to the pdata variable.
8791  Please note, pdata access physically accesses xdata memory.
8792  The high byte of the address is determined by port P2
8793 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
8794
8795 \end_inset
8796
8797 (or in case of some 8051 variants by a separate Special Function Register,
8798  see section
8799 \begin_inset LatexCommand \ref{sub:MCS51-variants}
8800
8801 \end_inset
8802
8803 ).
8804  This is the
8805 \series bold
8806 default
8807 \series default
8808  storage class for the Medium Memory model, e.g.:
8809 \layout Verse
8810
8811
8812 \family typewriter
8813 pdata unsigned char test_pdata;
8814 \layout Standard
8815
8816 Writing 0x01 to this variable generates the assembly code:
8817 \layout Verse
8818
8819
8820 \family typewriter
8821 78r00\SpecialChar ~
8822 \SpecialChar ~
8823 \SpecialChar ~
8824 \SpecialChar ~
8825 \SpecialChar ~
8826 \SpecialChar ~
8827 mov r0,#_test_pdata
8828 \newline
8829 74 01\SpecialChar ~
8830 \SpecialChar ~
8831 \SpecialChar ~
8832 \SpecialChar ~
8833 \SpecialChar ~
8834 \SpecialChar ~
8835 mov a,#0x01
8836 \newline
8837 F2\SpecialChar ~
8838 \SpecialChar ~
8839 \SpecialChar ~
8840 \SpecialChar ~
8841 \SpecialChar ~
8842 \SpecialChar ~
8843 \SpecialChar ~
8844 \SpecialChar ~
8845 \SpecialChar ~
8846 movx @r0,a
8847 \layout Standard
8848
8849 If the -
8850 \begin_inset ERT
8851 status Collapsed
8852
8853 \layout Standard
8854
8855 \backslash
8856 /
8857 \end_inset
8858
8859 -xstack
8860 \begin_inset LatexCommand \index{-\/-xstack}
8861
8862 \end_inset
8863
8864  option is used the pdata memory area is followed by the xstack memory area
8865  and the sum of their sizes is limited to 256 bytes.
8866 \layout Subsubsection
8867
8868 code
8869 \begin_inset LatexCommand \index{code}
8870
8871 \end_inset
8872
8873
8874 \begin_inset LatexCommand \index{\_\_code}
8875
8876 \end_inset
8877
8878
8879 \layout Standard
8880
8881 'Variables' declared with this storage class will be placed in the code
8882  memory:
8883 \layout Verse
8884
8885
8886 \family typewriter
8887 code unsigned char test_code;
8888 \layout Standard
8889
8890 Read access to this variable generates the assembly code:
8891 \layout Verse
8892
8893
8894 \family typewriter
8895 90s00r6F\SpecialChar ~
8896 \SpecialChar ~
8897 \SpecialChar ~
8898 mov dptr,#_test_code
8899 \newline
8900 E4\SpecialChar ~
8901 \SpecialChar ~
8902 \SpecialChar ~
8903 \SpecialChar ~
8904 \SpecialChar ~
8905 \SpecialChar ~
8906 \SpecialChar ~
8907 \SpecialChar ~
8908 \SpecialChar ~
8909 clr a
8910 \newline
8911 93\SpecialChar ~
8912 \SpecialChar ~
8913 \SpecialChar ~
8914 \SpecialChar ~
8915 \SpecialChar ~
8916 \SpecialChar ~
8917 \SpecialChar ~
8918 \SpecialChar ~
8919 \SpecialChar ~
8920 movc a,@a+dptr
8921 \layout Standard
8922
8923
8924 \family typewriter
8925 char
8926 \family default
8927  indexed arrays of characters in code memory can be accessed efficiently:
8928 \layout Verse
8929
8930
8931 \family typewriter
8932 code char test_array[] = {'c','h','e','a','p'};
8933 \layout Standard
8934
8935 Read access to this array using an 8-bit unsigned index generates the assembly
8936  code:
8937 \layout Verse
8938
8939
8940 \family typewriter
8941 E5*00\SpecialChar ~
8942 \SpecialChar ~
8943 \SpecialChar ~
8944 \SpecialChar ~
8945 \SpecialChar ~
8946 \SpecialChar ~
8947 mov a,_index
8948 \layout Verse
8949
8950
8951 \family typewriter
8952 90s00r41\SpecialChar ~
8953 \SpecialChar ~
8954 \SpecialChar ~
8955 mov dptr,#_test_array
8956 \layout Verse
8957
8958
8959 \family typewriter
8960 93\SpecialChar ~
8961 \SpecialChar ~
8962 \SpecialChar ~
8963 \SpecialChar ~
8964 \SpecialChar ~
8965 \SpecialChar ~
8966 \SpecialChar ~
8967 \SpecialChar ~
8968 \SpecialChar ~
8969 movc a,@a+dptr
8970 \layout Subsubsection
8971
8972 bit
8973 \begin_inset LatexCommand \index{bit}
8974
8975 \end_inset
8976
8977
8978 \begin_inset LatexCommand \index{\_\_bit}
8979
8980 \end_inset
8981
8982
8983 \layout Standard
8984
8985 This is a data-type and a storage class specifier.
8986  When a variable is declared as a bit, it is allocated into the bit addressable
8987  memory of 8051, e.g.:
8988 \layout Verse
8989
8990
8991 \family typewriter
8992 bit test_bit;
8993 \layout Standard
8994
8995 Writing 1 to this variable generates the assembly code:
8996 \layout Verse
8997
8998
8999 \family typewriter
9000 D2*00\SpecialChar ~
9001 \SpecialChar ~
9002 \SpecialChar ~
9003 \SpecialChar ~
9004 \SpecialChar ~
9005 \SpecialChar ~
9006 \SpecialChar ~
9007 setb\SpecialChar ~
9008 _test_bit
9009 \layout Standard
9010
9011 The bit addressable memory consists of 128 bits which are located from 0x20
9012  to 0x2f in data memory.
9013
9014 \newline
9015 Apart from this 8051 specific storage class most architectures support ANSI-C
9016  bitfields
9017 \begin_inset LatexCommand \index{bitfields}
9018
9019 \end_inset
9020
9021
9022 \begin_inset Foot
9023 collapsed false
9024
9025 \layout Standard
9026
9027 Not really meant as examples, but nevertheless showing what bitfields are
9028  about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
9029 \end_inset
9030
9031 .
9032  In accordance with ISO/IEC 9899 bits and bitfields without an explicit
9033  signed modifier are implemented as unsigned.
9034 \layout Subsubsection
9035
9036 sfr
9037 \begin_inset LatexCommand \index{sfr}
9038
9039 \end_inset
9040
9041
9042 \begin_inset LatexCommand \index{\_\_sfr}
9043
9044 \end_inset
9045
9046  / sfr16
9047 \begin_inset LatexCommand \index{sfr16}
9048
9049 \end_inset
9050
9051
9052 \begin_inset LatexCommand \index{\_\_sfr16}
9053
9054 \end_inset
9055
9056  / sfr32
9057 \begin_inset LatexCommand \index{sfr32}
9058
9059 \end_inset
9060
9061
9062 \begin_inset LatexCommand \index{\_\_sfr32}
9063
9064 \end_inset
9065
9066  / sbit
9067 \begin_inset LatexCommand \index{\_\_sbit}
9068
9069 \end_inset
9070
9071
9072 \layout Standard
9073
9074 Like the bit keyword,
9075 \emph on
9076 sfr / sfr16 / sfr32 / sbit
9077 \emph default
9078 signify both a data-type and storage class, they are used to describe the
9079
9080 \emph on
9081 s
9082 \emph default
9083 pecial
9084 \emph on
9085 f
9086 \emph default
9087 unction
9088 \emph on
9089 r
9090 \emph default
9091 egisters and
9092 \emph on
9093 s
9094 \emph default
9095 pecial
9096 \emph on
9097 bit
9098 \emph default
9099  variables of a 8051, eg:
9100 \layout Verse
9101
9102
9103 \family typewriter
9104 sfr at
9105 \begin_inset LatexCommand \index{at}
9106
9107 \end_inset
9108
9109
9110 \begin_inset LatexCommand \index{\_\_at}
9111
9112 \end_inset
9113
9114  0x80 P0;\SpecialChar ~
9115  /* special function register P0 at location 0x80 */
9116 \newline
9117 /* 16 bit special function register combination for timer 0 */
9118 \newline
9119 /* with the high byte at location 0x8C and the low byte at location 0x8A
9120  */
9121 \newline
9122 sfr16 at
9123 \begin_inset LatexCommand \index{at}
9124
9125 \end_inset
9126
9127
9128 \begin_inset LatexCommand \index{\_\_at}
9129
9130 \end_inset
9131
9132  0x8C8A TMR0;
9133 \newline
9134 sbit at 0xd7 CY; /* CY (Carry Flag
9135 \begin_inset LatexCommand \index{Flags}
9136
9137 \end_inset
9138
9139
9140 \begin_inset LatexCommand \index{Carry flag}
9141
9142 \end_inset
9143
9144 ) */
9145 \layout Standard
9146
9147 Special function registers which are located on an address dividable by
9148  8 are bit-addressable, an
9149 \emph on
9150  sbit
9151 \emph default
9152  addresses a specific bit within these sfr.
9153 \newline
9154 16 Bit and 32 bit special function register combinations which require a
9155  certain access order are better not declared using
9156 \emph on
9157 sfr16
9158 \emph default
9159  or
9160 \emph on
9161 sfr32.
9162
9163 \emph default
9164  Allthough SDCC usually accesses them Least Significant Byte (LSB) first,
9165  this is not guaranteed.
9166 \layout Subsubsection
9167
9168 Pointers
9169 \begin_inset LatexCommand \index{Pointer}
9170
9171 \end_inset
9172
9173  to MCS51/DS390 specific memory spaces
9174 \layout Standard
9175
9176 SDCC allows (via language extensions) pointers to explicitly point to any
9177  of the memory spaces
9178 \begin_inset LatexCommand \index{Memory model}
9179
9180 \end_inset
9181
9182  of the 8051.
9183  In addition to the explicit pointers, the compiler uses (by default) generic
9184  pointers which can be used to point to any of the memory spaces.
9185 \newline
9186
9187 \newline
9188 Pointer declaration examples:
9189 \layout Verse
9190
9191
9192 \family typewriter
9193 /* pointer physically in internal ram pointing to object in external ram
9194  */
9195 \newline
9196 xdata unsigned char * data p;
9197 \newline
9198
9199 \newline
9200 /* pointer physically in external ram pointing to object in internal ram
9201  */
9202 \newline
9203 data unsigned char * xdata p;
9204 \newline
9205
9206 \newline
9207 /* pointer physically in code rom pointing to data in xdata space */
9208 \newline
9209 xdata unsigned char * code p;
9210 \newline
9211
9212 \newline
9213 /* pointer physically in code space pointing to data in code space */
9214 \newline
9215 code unsigned char * code p;
9216 \newline
9217
9218 \newline
9219 /* the following is a generic pointer physically located in xdata space
9220  */
9221 \newline
9222 char * xdata p;
9223 \newline
9224
9225 \newline
9226 /* the following is a function pointer physically located in data space
9227  */
9228 \newline
9229 char (* data fp)(void);
9230 \layout Standard
9231
9232 Well you get the idea.
9233
9234 \newline
9235
9236 \newline
9237 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
9238 \emph on
9239 generic
9240 \emph default
9241  pointers.
9242
9243 \size small
9244
9245 \newline
9246
9247 \newline
9248
9249 \size default
9250 The highest order byte of the
9251 \emph on
9252 generic
9253 \emph default
9254  pointers contains the data space information.
9255  Assembler support routines are called whenever data is stored or retrieved
9256  using
9257 \emph on
9258 generic
9259 \emph default
9260  pointers.
9261  These are useful for developing reusable library
9262 \begin_inset LatexCommand \index{Libraries}
9263
9264 \end_inset
9265
9266  routines.
9267  Explicitly specifying the pointer type will generate the most efficient
9268  code.
9269 \layout Subsubsection
9270
9271 Notes on MCS51 memory
9272 \begin_inset LatexCommand \index{MCS51 memory}
9273
9274 \end_inset
9275
9276  layout
9277 \layout Standard
9278
9279 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
9280  RAM memory which is structured as follows:
9281 \newline
9282
9283 \newline
9284 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
9285
9286 \newline
9287 - Bytes 20-2F - 16 bytes to hold 128 bit
9288 \begin_inset LatexCommand \index{bit}
9289
9290 \end_inset
9291
9292  variables and,
9293 \newline
9294 - Bytes 30-7F - 80 bytes for general purpose use.
9295 \newline
9296
9297 \layout Standard
9298
9299 Additionally some members of the MCS51 family may have up to 128 bytes of
9300  additional, indirectly addressable, internal RAM memory (
9301 \emph on
9302 idata
9303 \emph default
9304
9305 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
9306
9307 \end_inset
9308
9309
9310 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
9311
9312 \end_inset
9313
9314 ).
9315  Furthermore, some chips may have some built in external memory (
9316 \emph on
9317 xdata
9318 \emph default
9319
9320 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9321
9322 \end_inset
9323
9324
9325 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9326
9327 \end_inset
9328
9329 ) which should not be confused with the internal, directly addressable RAM
9330  memory (
9331 \emph on
9332 data
9333 \emph default
9334
9335 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
9336
9337 \end_inset
9338
9339
9340 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
9341
9342 \end_inset
9343
9344 ).
9345  Sometimes this built in
9346 \emph on
9347 xdata
9348 \emph default
9349  memory has to be activated before using it (you can probably find this
9350  information on the datasheet of the microcontroller your are using, see
9351  also section
9352 \begin_inset LatexCommand \ref{sub:Startup-Code}
9353
9354 \end_inset
9355
9356 \SpecialChar ~
9357 Startup-Code).
9358 \layout Standard
9359
9360 Normally SDCC will only use the first bank
9361 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
9362
9363 \end_inset
9364
9365  of registers (register bank 0), but it is possible to specify that other
9366  banks of registers (keyword
9367 \emph on
9368 using
9369 \emph default
9370
9371 \emph on
9372
9373 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
9374
9375 \end_inset
9376
9377
9378 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
9379
9380 \end_inset
9381
9382
9383 \emph default
9384 ) should be used in interrupt
9385 \begin_inset LatexCommand \index{interrupt}
9386
9387 \end_inset
9388
9389
9390 \begin_inset LatexCommand \index{\_\_interrupt}
9391
9392 \end_inset
9393
9394  routines.
9395  By default, the compiler will place the stack after the last byte of allocated
9396  memory for variables.
9397  For example, if the first 2 banks of registers are used, and only four
9398  bytes are used for
9399 \emph on
9400 data
9401 \emph default
9402  variables, it will position the base of the internal stack at address 20
9403  (0x14).
9404  This implies that as the stack
9405 \begin_inset LatexCommand \index{stack}
9406
9407 \end_inset
9408
9409  grows, it will use up the remaining register banks, and the 16 bytes used
9410  by the 128 bit variables, and 80 bytes for general purpose use.
9411  If any bit variables are used, the data variables will be placed in unused
9412  register banks and after the byte holding the last bit variable.
9413  For example, if register banks 0 and 1 are used, and there are 9 bit variables
9414  (two bytes used),
9415 \emph on
9416 data
9417 \emph default
9418  variables will be placed starting from address 0x10 to 0x20 and continue
9419  at address 0x22.
9420  You can also use -
9421 \begin_inset ERT
9422 status Collapsed
9423
9424 \layout Standard
9425
9426 \backslash
9427 /
9428 \end_inset
9429
9430 -data-loc
9431 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
9432
9433 \end_inset
9434
9435  to specify the start address of the
9436 \emph on
9437 data
9438 \emph default
9439  and -
9440 \begin_inset ERT
9441 status Collapsed
9442
9443 \layout Standard
9444
9445 \backslash
9446 /
9447 \end_inset
9448
9449 -iram-size
9450 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
9451
9452 \end_inset
9453
9454  to specify the size of the total internal RAM (
9455 \emph on
9456 data
9457 \emph default
9458 +
9459 \emph on
9460 idata
9461 \emph default
9462 ).
9463
9464 \layout Standard
9465
9466 By default the 8051 linker will place the stack after the last byte of (i)data
9467  variables.
9468  Option -
9469 \begin_inset ERT
9470 status Collapsed
9471
9472 \layout Standard
9473
9474 \backslash
9475 /
9476 \end_inset
9477
9478 -stack-loc
9479 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
9480
9481 \end_inset
9482
9483  allows you to specify the start of the stack, i.e.
9484  you could start it after any data in the general purpose area.
9485  If your microcontroller has additional indirectly addressable internal
9486  RAM (
9487 \emph on
9488 idata
9489 \emph default
9490 ) you can place the stack on it.
9491  You may also need to use -
9492 \begin_inset ERT
9493 status Collapsed
9494
9495 \layout Standard
9496
9497 \backslash
9498 /
9499 \end_inset
9500
9501 -xdata-loc
9502 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
9503
9504 \end_inset
9505
9506  to set the start address of the external RAM (
9507 \emph on
9508 xdata
9509 \emph default
9510 ) and -
9511 \begin_inset ERT
9512 status Collapsed
9513
9514 \layout Standard
9515
9516 \backslash
9517 /
9518 \end_inset
9519
9520 -xram-size
9521 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
9522
9523 \end_inset
9524
9525  to specify its size.
9526  Same goes for the code memory, using -
9527 \begin_inset ERT
9528 status Collapsed
9529
9530 \layout Standard
9531
9532 \backslash
9533 /
9534 \end_inset
9535
9536 -code-loc
9537 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
9538
9539 \end_inset
9540
9541  and -
9542 \begin_inset ERT
9543 status Collapsed
9544
9545 \layout Standard
9546
9547 \backslash
9548 /
9549 \end_inset
9550
9551 -code-size
9552 \begin_inset LatexCommand \index{-\/-code-size <Value>}
9553
9554 \end_inset
9555
9556 .
9557  If in doubt, don't specify any options and see if the resulting memory
9558  layout is appropriate, then you can adjust it.
9559 \layout Standard
9560
9561 The linker generates two files with memory allocation information.
9562  The first, with extension .map
9563 \begin_inset LatexCommand \index{<file>.map}
9564
9565 \end_inset
9566
9567  shows all the variables and segments.
9568  The second with extension .mem
9569 \begin_inset LatexCommand \index{<file>.mem}
9570
9571 \end_inset
9572
9573  shows the final memory layout.
9574  The linker will complain either if memory segments overlap, there is not
9575  enough memory, or there is not enough space for stack.
9576  If you get any linking warnings and/or errors related to stack or segments
9577  allocation, take a look at either the .map or .mem files to find out what
9578  the problem is.
9579  The .mem file may even suggest a solution to the problem.
9580 \layout Subsection
9581
9582 Z80/Z180 Storage Class
9583 \begin_inset LatexCommand \index{Storage class}
9584
9585 \end_inset
9586
9587  Language Extensions
9588 \layout Subsubsection
9589
9590 sfr
9591 \begin_inset LatexCommand \index{sfr}
9592
9593 \end_inset
9594
9595
9596 \begin_inset LatexCommand \index{\_\_sfr}
9597
9598 \end_inset
9599
9600  (in/out to 8-bit addresses)
9601 \layout Standard
9602
9603 The Z80
9604 \begin_inset LatexCommand \index{Z80}
9605
9606 \end_inset
9607
9608  family has separate address spaces for memory and
9609 \emph on
9610 i
9611 \emph default
9612 nput/
9613 \emph on
9614 o
9615 \emph default
9616 utput memory.
9617  I/O memory
9618 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
9619
9620 \end_inset
9621
9622  is accessed with special instructions, e.g.:
9623 \layout Verse
9624
9625
9626 \family typewriter
9627 sfr at 0x78 IoPort;\SpecialChar ~
9628 \SpecialChar ~
9629 /* define a var in I/O space at 78h called IoPort */
9630
9631 \layout Standard
9632
9633 Writing 0x01 to this variable generates the assembly code:
9634 \layout Verse
9635
9636
9637 \family typewriter
9638 3E 01\SpecialChar ~
9639 \SpecialChar ~
9640 \SpecialChar ~
9641 \SpecialChar ~
9642 \SpecialChar ~
9643 \SpecialChar ~
9644 ld a,#0x01
9645 \newline
9646 D3 78\SpecialChar ~
9647 \SpecialChar ~
9648 \SpecialChar ~
9649 \SpecialChar ~
9650 \SpecialChar ~
9651 \SpecialChar ~
9652 out (_IoPort),a
9653 \layout Subsubsection
9654
9655 banked sfr
9656 \begin_inset LatexCommand \index{sfr}
9657
9658 \end_inset
9659
9660
9661 \begin_inset LatexCommand \index{\_\_sfr}
9662
9663 \end_inset
9664
9665  (in/out to 16-bit addresses)
9666 \layout Standard
9667
9668 The keyword
9669 \emph on
9670 banked
9671 \emph default
9672  is used to support 16 bit addresses in I/O memory e.g.:
9673 \layout Verse
9674
9675
9676 \family typewriter
9677 sfr banked at
9678 \begin_inset LatexCommand \index{at}
9679
9680 \end_inset
9681
9682
9683 \begin_inset LatexCommand \index{\_\_at}
9684
9685 \end_inset
9686
9687  0x123 IoPort;
9688 \layout Standard
9689
9690 Writing 0x01 to this variable generates the assembly code:
9691 \layout Verse
9692
9693
9694 \family typewriter
9695 01 23 01\SpecialChar ~
9696 \SpecialChar ~
9697 \SpecialChar ~
9698 ld bc,#_IoPort
9699 \newline
9700 3E 01\SpecialChar ~
9701 \SpecialChar ~
9702 \SpecialChar ~
9703 \SpecialChar ~
9704 \SpecialChar ~
9705 \SpecialChar ~
9706 ld a,#0x01
9707 \newline
9708 ED 79\SpecialChar ~
9709 \SpecialChar ~
9710 \SpecialChar ~
9711 \SpecialChar ~
9712 \SpecialChar ~
9713 \SpecialChar ~
9714 out (c),a
9715 \layout Subsubsection
9716
9717 sfr
9718 \begin_inset LatexCommand \index{sfr}
9719
9720 \end_inset
9721
9722
9723 \begin_inset LatexCommand \index{\_\_sfr}
9724
9725 \end_inset
9726
9727  (in0/out0 to 8 bit addresses on Z180
9728 \begin_inset LatexCommand \index{Z180}
9729
9730 \end_inset
9731
9732 /HD64180
9733 \begin_inset LatexCommand \index{HD64180}
9734
9735 \end_inset
9736
9737 )
9738 \layout Standard
9739
9740 The compiler option -
9741 \begin_inset ERT
9742 status Collapsed
9743
9744 \layout Standard
9745
9746 \backslash
9747 /
9748 \end_inset
9749
9750 -portmode=180 (80) and a compiler #pragma\SpecialChar ~
9751 portmode
9752 \begin_inset LatexCommand \index{\#pragma portmode}
9753
9754 \end_inset
9755
9756 =z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
9757 ns
9758 \family typewriter
9759 in0/out0
9760 \family default
9761  instead of
9762 \family typewriter
9763 in/out
9764 \family default
9765 .
9766  If you include the file z180.h this will be set automatically.
9767 \layout Subsection
9768
9769 HC08 Storage Class
9770 \begin_inset LatexCommand \index{Storage class}
9771
9772 \end_inset
9773
9774  Language Extensions
9775 \layout Subsubsection
9776
9777 data
9778 \begin_inset LatexCommand \index{data (hc08 storage class)}
9779
9780 \end_inset
9781
9782
9783 \begin_inset LatexCommand \index{\_\_data (hc08 storage class)}
9784
9785 \end_inset
9786
9787
9788 \layout Standard
9789
9790 The data storage class declares a variable that resides in the first 256
9791  bytes of memory (the direct page).
9792  The HC08 is most efficient at accessing variables (especially pointers)
9793  stored here.
9794 \layout Subsubsection
9795
9796 xdata
9797 \begin_inset LatexCommand \index{xdata (hc08 storage class)}
9798
9799 \end_inset
9800
9801
9802 \begin_inset LatexCommand \index{\_\_xdata (hc08 storage class)}
9803
9804 \end_inset
9805
9806
9807 \layout Standard
9808
9809 The xdata storage class declares a variable that can reside anywhere in
9810  memory.
9811  This is the default if no storage class is specified.
9812
9813 \layout Section
9814
9815 Absolute Addressing
9816 \begin_inset LatexCommand \index{Absolute addressing}
9817
9818 \end_inset
9819
9820
9821 \layout Standard
9822
9823 Data items can be assigned an absolute address with the
9824 \emph on
9825 at
9826 \begin_inset LatexCommand \index{at}
9827
9828 \end_inset
9829
9830
9831 \begin_inset LatexCommand \index{\_\_at}
9832
9833 \end_inset
9834
9835  <address>
9836 \emph default
9837  keyword, in addition to a storage class, e.g.:
9838 \layout Verse
9839
9840
9841 \family typewriter
9842 xdata
9843 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9844
9845 \end_inset
9846
9847
9848 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9849
9850 \end_inset
9851
9852  at
9853 \begin_inset LatexCommand \index{at}
9854
9855 \end_inset
9856
9857
9858 \begin_inset LatexCommand \index{\_\_at}
9859
9860 \end_inset
9861
9862  0x7ffe unsigned int chksum;
9863 \layout Standard
9864
9865 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
9866  of the external ram.
9867  The compiler does
9868 \emph on
9869 not
9870 \emph default
9871  reserve any space for variables declared in this way (they are implemented
9872  with an equate in the assembler).
9873  Thus it is left to the programmer to make sure there are no overlaps with
9874  other variables that are declared without the absolute address.
9875  The assembler listing file (.lst
9876 \begin_inset LatexCommand \index{<file>.lst}
9877
9878 \end_inset
9879
9880 ) and the linker output files (.rst
9881 \begin_inset LatexCommand \index{<file>.rst}
9882
9883 \end_inset
9884
9885 ) and (.map
9886 \begin_inset LatexCommand \index{<file>.map}
9887
9888 \end_inset
9889
9890 ) are good places to look for such overlaps.
9891  Variables with an absolute address are
9892 \emph on
9893 not
9894 \emph default
9895  initialized
9896 \begin_inset LatexCommand \index{Variable initialization}
9897
9898 \end_inset
9899
9900 .
9901 \layout Standard
9902
9903 In case of memory mapped I/O devices the keyword
9904 \emph on
9905 volatile
9906 \emph default
9907  has to be used to tell the compiler that accesses might not be removed:
9908 \layout Verse
9909
9910
9911 \family typewriter
9912 volatile
9913 \begin_inset LatexCommand \index{volatile}
9914
9915 \end_inset
9916
9917  xdata
9918 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9919
9920 \end_inset
9921
9922  at
9923 \begin_inset LatexCommand \index{at}
9924
9925 \end_inset
9926
9927  0x8000 unsigned char PORTA_8255;
9928 \layout Standard
9929
9930 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
9931 r) array
9932 \family typewriter
9933 \size footnotesize
9934
9935 \begin_inset LatexCommand \index{Aligned array}
9936
9937 \end_inset
9938
9939
9940 \family default
9941 \size default
9942  starts at a block (256 byte) boundary
9943 \begin_inset LatexCommand \index{block boundary}
9944
9945 \end_inset
9946
9947  (section
9948 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
9949
9950 \end_inset
9951
9952  has an example).
9953 \newline
9954 Absolute addresses can be specified for variables in all storage classes,
9955  e.g.:
9956 \layout Verse
9957
9958
9959 \family typewriter
9960 bit
9961 \begin_inset LatexCommand \index{bit}
9962
9963 \end_inset
9964
9965  at
9966 \begin_inset LatexCommand \index{at}
9967
9968 \end_inset
9969
9970  0x02 bvar;
9971 \layout Standard
9972
9973 The above example will allocate the variable at offset 0x02 in the bit-addressab
9974 le space.
9975  There is no real advantage to assigning absolute addresses to variables
9976  in this manner, unless you want strict control over all the variables allocated.
9977  One possible use would be to write hardware portable code.
9978  For example, if you have a routine that uses one or more of the microcontroller
9979  I/O pins, and such pins are different for two different hardwares, you
9980  can declare the I/O pins in your routine using:
9981 \layout Verse
9982
9983
9984 \family typewriter
9985 extern volatile
9986 \begin_inset LatexCommand \index{volatile}
9987
9988 \end_inset
9989
9990  bit MOSI;\SpecialChar ~
9991 \SpecialChar ~
9992 \SpecialChar ~
9993 \SpecialChar ~
9994 /* master out, slave in */
9995 \newline
9996 extern volatile bit MISO;\SpecialChar ~
9997 \SpecialChar ~
9998 \SpecialChar ~
9999 \SpecialChar ~
10000 /* master in, slave out */
10001 \newline
10002 extern volatile bit MCLK;\SpecialChar ~
10003 \SpecialChar ~
10004 \SpecialChar ~
10005 \SpecialChar ~
10006 /* master clock */
10007 \newline
10008
10009 \newline
10010 /* Input and Output of a byte on a 3-wire serial bus.
10011 \newline
10012 \SpecialChar ~
10013 \SpecialChar ~
10014 \SpecialChar ~
10015 If needed adapt polarity of clock, polarity of data and bit order
10016 \newline
10017 \SpecialChar ~
10018 */
10019 \newline
10020 unsigned char spi_io(unsigned char out_byte)
10021 \newline
10022 {
10023 \newline
10024 \SpecialChar ~
10025 \SpecialChar ~
10026 \SpecialChar ~
10027 \SpecialChar ~
10028 unsigned char i=8;
10029 \newline
10030 \SpecialChar ~
10031 \SpecialChar ~
10032 \SpecialChar ~
10033 \SpecialChar ~
10034 do {
10035 \newline
10036 \SpecialChar ~
10037 \SpecialChar ~
10038 \SpecialChar ~
10039 \SpecialChar ~
10040 \SpecialChar ~
10041 \SpecialChar ~
10042 \SpecialChar ~
10043 \SpecialChar ~
10044 MOSI = out_byte & 0x80;
10045 \newline
10046 \SpecialChar ~
10047 \SpecialChar ~
10048 \SpecialChar ~
10049 \SpecialChar ~
10050 \SpecialChar ~
10051 \SpecialChar ~
10052 \SpecialChar ~
10053 \SpecialChar ~
10054 out_byte <<= 1;
10055 \newline
10056 \SpecialChar ~
10057 \SpecialChar ~
10058 \SpecialChar ~
10059 \SpecialChar ~
10060 \SpecialChar ~
10061 \SpecialChar ~
10062 \SpecialChar ~
10063 \SpecialChar ~
10064 MCLK = 1;
10065 \newline
10066 \SpecialChar ~
10067 \SpecialChar ~
10068 \SpecialChar ~
10069 \SpecialChar ~
10070 \SpecialChar ~
10071 \SpecialChar ~
10072 \SpecialChar ~
10073 \SpecialChar ~
10074 /* _asm nop _endasm; */\SpecialChar ~
10075 \SpecialChar ~
10076 \SpecialChar ~
10077 \SpecialChar ~
10078 \SpecialChar ~
10079 \SpecialChar ~
10080 \SpecialChar ~
10081 \SpecialChar ~
10082 /* for slow peripherals */
10083 \newline
10084 \SpecialChar ~
10085 \SpecialChar ~
10086 \SpecialChar ~
10087 \SpecialChar ~
10088 \SpecialChar ~
10089 \SpecialChar ~
10090 \SpecialChar ~
10091 \SpecialChar ~
10092 if(MISO)
10093 \newline
10094 \SpecialChar ~
10095 \SpecialChar ~
10096 \SpecialChar ~
10097 \SpecialChar ~
10098 \SpecialChar ~
10099 \SpecialChar ~
10100 \SpecialChar ~
10101 \SpecialChar ~
10102 \SpecialChar ~
10103 \SpecialChar ~
10104 \SpecialChar ~
10105 \SpecialChar ~
10106 out_byte += 1;
10107 \newline
10108 \SpecialChar ~
10109 \SpecialChar ~
10110 \SpecialChar ~
10111 \SpecialChar ~
10112 \SpecialChar ~
10113 \SpecialChar ~
10114 \SpecialChar ~
10115 \SpecialChar ~
10116 MCLK = 0;
10117 \newline
10118 \SpecialChar ~
10119 \SpecialChar ~
10120 \SpecialChar ~
10121 \SpecialChar ~
10122 } while(--i);
10123 \newline
10124 \SpecialChar ~
10125 \SpecialChar ~
10126 \SpecialChar ~
10127 \SpecialChar ~
10128 return out_byte;
10129 \newline
10130 }
10131 \layout Standard
10132
10133 Then, someplace in the code for the first hardware you would use
10134 \layout Verse
10135
10136
10137 \family typewriter
10138 bit at
10139 \begin_inset LatexCommand \index{at}
10140
10141 \end_inset
10142
10143
10144 \begin_inset LatexCommand \index{\_\_at}
10145
10146 \end_inset
10147
10148  0x80 MOSI;\SpecialChar ~
10149 \SpecialChar ~
10150 \SpecialChar ~
10151 \SpecialChar ~
10152 /* I/O port 0, bit 0 */
10153 \newline
10154 bit at 0x81 MISO;\SpecialChar ~
10155 \SpecialChar ~
10156 \SpecialChar ~
10157 \SpecialChar ~
10158 /* I/O port 0, bit 1 */
10159 \newline
10160 bit at 0x82 MCLK;\SpecialChar ~
10161 \SpecialChar ~
10162 \SpecialChar ~
10163 \SpecialChar ~
10164 /* I/O port 0, bit 2 */
10165 \layout Standard
10166
10167 Similarly, for the second hardware you would use
10168 \layout Verse
10169
10170
10171 \family typewriter
10172 bit at 0x83 MOSI;\SpecialChar ~
10173 \SpecialChar ~
10174 \SpecialChar ~
10175 \SpecialChar ~
10176 /* I/O port 0, bit 3 */
10177 \newline
10178 bit at 0x91 MISO;\SpecialChar ~
10179 \SpecialChar ~
10180 \SpecialChar ~
10181 \SpecialChar ~
10182 /* I/O port 1, bit 1 */
10183 \newline
10184 bit
10185 \begin_inset LatexCommand \index{bit}
10186
10187 \end_inset
10188
10189  at 0x92 MCLK;\SpecialChar ~
10190 \SpecialChar ~
10191 \SpecialChar ~
10192 \SpecialChar ~
10193 /* I/O port 1, bit 2 */
10194 \layout Standard
10195
10196 and you can use the same hardware dependent routine without changes, as
10197  for example in a library.
10198  This is somehow similar to sbit, but only one absolute address has to be
10199  specified in the whole project.
10200 \layout Section
10201
10202 Parameters
10203 \begin_inset LatexCommand \index{Parameters}
10204
10205 \end_inset
10206
10207
10208 \begin_inset LatexCommand \index{function parameter}
10209
10210 \end_inset
10211
10212  & Local Variables
10213 \begin_inset LatexCommand \index{local variables}
10214
10215 \end_inset
10216
10217
10218 \begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
10219
10220 \end_inset
10221
10222
10223 \layout Standard
10224
10225 Automatic (local) variables and parameters to functions can either be placed
10226  on the stack or in data-space.
10227  The default action of the compiler is to place these variables in the internal
10228  RAM (for small model) or external RAM (for large model).
10229  This in fact makes them similar to
10230 \emph on
10231 static
10232 \begin_inset LatexCommand \index{static}
10233
10234 \end_inset
10235
10236
10237 \emph default
10238  so by default functions are non-reentrant
10239 \begin_inset LatexCommand \index{reentrant}
10240
10241 \end_inset
10242
10243 .
10244
10245 \newline
10246
10247 \newline
10248 They can be placed on the stack
10249 \begin_inset LatexCommand \index{stack}
10250
10251 \end_inset
10252
10253  by using the
10254 \emph on
10255  -
10256 \begin_inset ERT
10257 status Collapsed
10258
10259 \layout Standard
10260
10261 \backslash
10262 /
10263 \end_inset
10264
10265 -stack-auto
10266 \begin_inset LatexCommand \index{-\/-stack-auto}
10267
10268 \end_inset
10269
10270
10271 \emph default
10272  option, by using
10273 \emph on
10274 #pragma\SpecialChar ~
10275 stackauto
10276 \emph default
10277
10278 \begin_inset LatexCommand \index{\#pragma stackauto}
10279
10280 \end_inset
10281
10282  or by using the
10283 \emph on
10284 reentrant
10285 \begin_inset LatexCommand \index{reentrant}
10286
10287 \end_inset
10288
10289
10290 \emph default
10291  keyword in the function declaration, e.g.:
10292 \layout Verse
10293
10294
10295 \family typewriter
10296 unsigned char foo(char i) reentrant
10297 \newline
10298 {
10299 \newline
10300 \SpecialChar ~
10301 \SpecialChar ~
10302 \SpecialChar ~
10303 \SpecialChar ~
10304 ...
10305
10306 \newline
10307 }
10308 \layout Standard
10309
10310 Since stack space on 8051 is limited, the
10311 \emph on
10312 reentrant
10313 \emph default
10314 keyword or the
10315 \emph on
10316  -
10317 \begin_inset ERT
10318 status Collapsed
10319
10320 \layout Standard
10321
10322 \backslash
10323 /
10324 \end_inset
10325
10326 -stack-auto
10327 \emph default
10328  option should be used sparingly.
10329  Note that the reentrant keyword just means that the parameters & local
10330  variables will be allocated to the stack, it
10331 \emph on
10332 does not
10333 \emph default
10334  mean that the function is register bank
10335 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
10336
10337 \end_inset
10338
10339  independent.
10340 \newline
10341
10342 \newline
10343 Local variables
10344 \begin_inset LatexCommand \index{local variables}
10345
10346 \end_inset
10347
10348  can be assigned storage classes and absolute
10349 \begin_inset LatexCommand \index{Absolute addressing}
10350
10351 \end_inset
10352
10353  addresses, e.g.:
10354 \layout Verse
10355
10356
10357 \family typewriter
10358 unsigned char foo()
10359 \newline
10360 {
10361 \newline
10362 \SpecialChar ~
10363 \SpecialChar ~
10364 \SpecialChar ~
10365 \SpecialChar ~
10366 xdata unsigned char i;
10367 \newline
10368 \SpecialChar ~
10369 \SpecialChar ~
10370 \SpecialChar ~
10371 \SpecialChar ~
10372 bit bvar;
10373 \newline
10374 \SpecialChar ~
10375 \SpecialChar ~
10376 \SpecialChar ~
10377 \SpecialChar ~
10378 data at
10379 \begin_inset LatexCommand \index{at}
10380
10381 \end_inset
10382
10383  0x31 unsigned char j;
10384 \newline
10385 \SpecialChar ~
10386 \SpecialChar ~
10387 \SpecialChar ~
10388 \SpecialChar ~
10389 ...
10390
10391 \newline
10392 }
10393 \layout Standard
10394
10395 In the above example the variable
10396 \emph on
10397 i
10398 \emph default
10399  will be allocated in the external ram,
10400 \emph on
10401 bvar
10402 \emph default
10403  in bit addressable space and
10404 \emph on
10405  j
10406 \emph default
10407  in internal ram.
10408  When compiled with
10409 \emph on
10410 -
10411 \begin_inset ERT
10412 status Collapsed
10413
10414 \layout Standard
10415
10416 \backslash
10417 /
10418 \end_inset
10419
10420 -stack-auto
10421 \emph default
10422  or when a function is declared as
10423 \emph on
10424 reentrant
10425 \emph default
10426  this should only be done for static variables.
10427 \layout Standard
10428
10429 Parameters
10430 \begin_inset LatexCommand \index{function parameter}
10431
10432 \end_inset
10433
10434  however are not allowed any storage class
10435 \begin_inset LatexCommand \index{Storage class}
10436
10437 \end_inset
10438
10439 , (storage classes for parameters will be ignored), their allocation is
10440  governed by the memory model in use, and the reentrancy options.
10441 \layout Standard
10442
10443 It is however allowed to use bit parameters in reentrant functions and also
10444  non-static local bit variables are supported.
10445  Efficient use is limited to 8 semi-bitregisters in bit space.
10446  They are pushed and popped to stack as a single byte just like the normal
10447  registers.
10448 \layout Section
10449
10450 Overlaying
10451 \begin_inset LatexCommand \label{sub:Overlaying}
10452
10453 \end_inset
10454
10455
10456 \begin_inset LatexCommand \index{Overlaying}
10457
10458 \end_inset
10459
10460
10461 \layout Standard
10462
10463 For non-reentrant
10464 \begin_inset LatexCommand \index{reentrant}
10465
10466 \end_inset
10467
10468  functions SDCC will try to reduce internal ram space usage by overlaying
10469  parameters and local variables of a function (if possible).
10470  Parameters and local variables
10471 \begin_inset LatexCommand \index{local variables}
10472
10473 \end_inset
10474
10475  of a function will be allocated to an overlayable segment if the function
10476  has
10477 \emph on
10478 no other function calls and the function is non-reentrant and the memory
10479  model
10480 \begin_inset LatexCommand \index{Memory model}
10481
10482 \end_inset
10483
10484  is small.
10485
10486 \emph default
10487  If an explicit storage class
10488 \begin_inset LatexCommand \index{Storage class}
10489
10490 \end_inset
10491
10492  is specified for a local variable, it will NOT be overlayed.
10493 \layout Standard
10494
10495 Note that the compiler (not the linkage editor) makes the decision for overlayin
10496 g the data items.
10497  Functions that are called from an interrupt service routine should be preceded
10498  by a #pragma\SpecialChar ~
10499 nooverlay
10500 \begin_inset LatexCommand \index{\#pragma nooverlay}
10501
10502 \end_inset
10503
10504  if they are not reentrant.
10505 \layout Standard
10506
10507 Also note that the compiler does not do any processing of inline assembler
10508  code, so the compiler might incorrectly assign local variables and parameters
10509  of a function into the overlay segment if the inline assembler code calls
10510  other c-functions that might use the overlay.
10511  In that case the #pragma\SpecialChar ~
10512 nooverlay should be used.
10513 \layout Standard
10514
10515 Parameters and local variables of functions that contain 16 or 32 bit multiplica
10516 tion
10517 \begin_inset LatexCommand \index{Multiplication}
10518
10519 \end_inset
10520
10521  or division
10522 \begin_inset LatexCommand \index{Division}
10523
10524 \end_inset
10525
10526  will NOT be overlayed since these are implemented using external functions,
10527  e.g.:
10528 \layout Verse
10529
10530
10531 \family typewriter
10532 #pragma save
10533 \newline
10534 #pragma nooverlay
10535 \begin_inset LatexCommand \index{\#pragma nooverlay}
10536
10537 \end_inset
10538
10539
10540 \newline
10541 void set_error(unsigned char errcd)
10542 \newline
10543 {
10544 \newline
10545 \SpecialChar ~
10546 \SpecialChar ~
10547 \SpecialChar ~
10548 \SpecialChar ~
10549 P3 = errcd;
10550 \newline
10551 }
10552 \newline
10553 #pragma restore
10554 \newline
10555
10556 \newline
10557 void some_isr () interrupt
10558 \begin_inset LatexCommand \index{interrupt}
10559
10560 \end_inset
10561
10562  2
10563 \newline
10564 {
10565 \newline
10566 \SpecialChar ~
10567 \SpecialChar ~
10568 \SpecialChar ~
10569 \SpecialChar ~
10570 ...
10571 \newline
10572 \SpecialChar ~
10573 \SpecialChar ~
10574 \SpecialChar ~
10575 \SpecialChar ~
10576 set_error(10);
10577 \newline
10578 \SpecialChar ~
10579 \SpecialChar ~
10580 \SpecialChar ~
10581 \SpecialChar ~
10582 ...
10583
10584 \newline
10585 }
10586 \layout Standard
10587
10588 In the above example the parameter
10589 \emph on
10590 errcd
10591 \emph default
10592  for the function
10593 \emph on
10594 set_error
10595 \emph default
10596  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
10597 nooverlay was
10598  not present, this could cause unpredictable runtime behavior when called
10599  from an interrupt service routine.
10600  The #pragma\SpecialChar ~
10601 nooverlay ensures that the parameters and local variables for
10602  the function are NOT overlayed.
10603 \layout Section
10604
10605 Interrupt Service Routines
10606 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
10607
10608 \end_inset
10609
10610
10611 \layout Subsection
10612
10613 General Information
10614 \layout Standard
10615
10616 SDCC allows
10617 \emph on
10618 i
10619 \emph default
10620 nterrupt
10621 \emph on
10622 s
10623 \emph default
10624 ervice
10625 \emph on
10626 r
10627 \emph default
10628 outines to be coded in C, with some extended keywords.
10629 \layout Verse
10630
10631
10632 \family typewriter
10633 void timer_isr (void) interrupt 1 using 1
10634 \newline
10635 {
10636 \newline
10637 \SpecialChar ~
10638 \SpecialChar ~
10639 \SpecialChar ~
10640 \SpecialChar ~
10641 ...
10642
10643 \newline
10644 }
10645 \layout Standard
10646
10647 The optional number following the
10648 \emph on
10649 interrupt
10650 \begin_inset LatexCommand \index{interrupt}
10651
10652 \end_inset
10653
10654
10655 \begin_inset LatexCommand \index{\_\_interrupt}
10656
10657 \end_inset
10658
10659
10660 \emph default
10661  keyword is the interrupt number this routine will service.
10662  When present, the compiler will insert a call to this routine in the interrupt
10663  vector table for the interrupt number specified.
10664  If you have multiple source files in your project, interrupt service routines
10665  can be present in any of them, but a prototype of the isr MUST be present
10666  or included in the file that contains the function
10667 \emph on
10668 main
10669 \emph default
10670 .
10671  The optional
10672 \emph on
10673 using
10674 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10675
10676 \end_inset
10677
10678
10679 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
10680
10681 \end_inset
10682
10683
10684 \emph default
10685  keyword can be used to tell the compiler to use the specified register
10686  bank (8051 specific) when generating code for this function.
10687
10688 \newline
10689
10690 \layout Standard
10691
10692 Interrupt service routines open the door for some very interesting bugs:
10693 \newline
10694 If an interrupt service routine changes variables which are accessed by
10695  other functions these variables have to be declared
10696 \emph on
10697 volatile
10698 \emph default
10699
10700 \begin_inset LatexCommand \index{volatile}
10701
10702 \end_inset
10703
10704 .
10705
10706 \layout Standard
10707
10708 If the access to these variables is not
10709 \emph on
10710 atomic
10711 \begin_inset LatexCommand \index{atomic}
10712
10713 \end_inset
10714
10715
10716 \emph default
10717  (i.e.
10718  the processor needs more than one instruction for the access and could
10719  be interrupted while accessing the variable) the interrupt must be disabled
10720  during the access to avoid inconsistent data.
10721  Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
10722  and should be protected by disabling interrupts.
10723  You're not automatically on the safe side if you use 8 bit variables though.
10724  We need an example here: f.e.
10725  on the 8051 the harmless looking
10726 \begin_inset Quotes srd
10727 \end_inset
10728
10729
10730 \family typewriter
10731 flags\SpecialChar ~
10732 |=\SpecialChar ~
10733 0x80;
10734 \family default
10735
10736 \begin_inset Quotes sld
10737 \end_inset
10738
10739  is not atomic if
10740 \family typewriter
10741 flags
10742 \family default
10743  resides in xdata.
10744  Setting
10745 \begin_inset Quotes srd
10746 \end_inset
10747
10748
10749 \family typewriter
10750 flags\SpecialChar ~
10751 |=\SpecialChar ~
10752 0x40;
10753 \family default
10754
10755 \begin_inset Quotes sld
10756 \end_inset
10757
10758  from within an interrupt routine might get lost if the interrupt occurs
10759  at the wrong time.
10760
10761 \begin_inset Quotes sld
10762 \end_inset
10763
10764
10765 \family typewriter
10766 counter\SpecialChar ~
10767 +=\SpecialChar ~
10768 8;
10769 \family default
10770
10771 \begin_inset Quotes srd
10772 \end_inset
10773
10774  is not atomic on the 8051 even if
10775 \family typewriter
10776 counter
10777 \family default
10778  is located in data memory.
10779  Bugs like these are hard to reproduce and can cause a lot of trouble.
10780
10781 \layout Standard
10782
10783 The return address and the registers used in the interrupt service routine
10784  are saved on the stack
10785 \begin_inset LatexCommand \index{stack}
10786
10787 \end_inset
10788
10789  so there must be sufficient stack space.
10790  If there isn't variables or registers (or even the return address itself)
10791  will be corrupted.
10792  This
10793 \emph on
10794 stack overflow
10795 \emph default
10796
10797 \begin_inset LatexCommand \index{stack overflow}
10798
10799 \end_inset
10800
10801  is most likely to happen if the interrupt occurs during the
10802 \begin_inset Quotes sld
10803 \end_inset
10804
10805 deepest
10806 \begin_inset Quotes srd
10807 \end_inset
10808
10809  subroutine when the stack is already in use for f.e.
10810  many return addresses.
10811 \layout Standard
10812
10813 A special note here, int (16 bit) and long (32 bit) integer division
10814 \begin_inset LatexCommand \index{Division}
10815
10816 \end_inset
10817
10818 , multiplication
10819 \begin_inset LatexCommand \index{Multiplication}
10820
10821 \end_inset
10822
10823  & modulus
10824 \begin_inset LatexCommand \index{Modulus}
10825
10826 \end_inset
10827
10828  and floating-point
10829 \begin_inset LatexCommand \index{Floating point support}
10830
10831 \end_inset
10832
10833  operations are implemented using external support routines developed in
10834  ANSI-C.
10835  If an interrupt service routine needs to do any of these operations then
10836  the support routines (as mentioned in a following section) will have to
10837  be recompiled using the
10838 \emph on
10839  -
10840 \begin_inset ERT
10841 status Collapsed
10842
10843 \layout Standard
10844
10845 \backslash
10846 /
10847 \end_inset
10848
10849 -stack-auto
10850 \begin_inset LatexCommand \index{-\/-stack-auto}
10851
10852 \end_inset
10853
10854
10855 \emph default
10856  option and the source file will need to be compiled using the
10857 \emph on
10858 -
10859 \begin_inset ERT
10860 status Collapsed
10861
10862 \layout Standard
10863
10864 \backslash
10865 /
10866 \end_inset
10867
10868 -int-long-reent
10869 \emph default
10870
10871 \begin_inset LatexCommand \index{-\/-int-long-reent}
10872
10873 \end_inset
10874
10875  compiler option.
10876 \layout Standard
10877
10878 Calling other functions from an interrupt service routine is not recommended,
10879  avoid it if possible.
10880  Note that when some function is called from an interrupt service routine
10881  it should be preceded by a #pragma\SpecialChar ~
10882 nooverlay
10883 \begin_inset LatexCommand \index{\#pragma nooverlay}
10884
10885 \end_inset
10886
10887  if it is not reentrant.
10888  Furthermore nonreentrant functions should not be called from the main program
10889  while the interrupt service routine might be active.
10890
10891 \newline
10892
10893 \newline
10894 Also see section
10895 \begin_inset LatexCommand \ref{sub:Overlaying}
10896
10897 \end_inset
10898
10899 \SpecialChar ~
10900 about Overlaying and section
10901 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
10902
10903 \end_inset
10904
10905 \SpecialChar ~
10906 about Functions using private register banks.
10907 \layout Subsection
10908
10909 MCS51/DS390 Interrupt Service Routines
10910 \layout Standard
10911
10912 Interrupt numbers and the corresponding address & descriptions for the Standard
10913  8051/8052 are listed below.
10914  SDCC will automatically adjust the interrupt vector table to the maximum
10915  interrupt number specified.
10916 \newline
10917
10918 \layout Standard
10919 \align center
10920
10921 \begin_inset  Tabular
10922 <lyxtabular version="3" rows="7" columns="3">
10923 <features>
10924 <column alignment="center" valignment="top" leftline="true" width="0in">
10925 <column alignment="center" valignment="top" leftline="true" width="0in">
10926 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
10927 <row topline="true" bottomline="true">
10928 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10929 \begin_inset Text
10930
10931 \layout Standard
10932
10933 Interrupt #
10934 \end_inset
10935 </cell>
10936 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10937 \begin_inset Text
10938
10939 \layout Standard
10940
10941 Description
10942 \end_inset
10943 </cell>
10944 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10945 \begin_inset Text
10946
10947 \layout Standard
10948
10949 Vector Address
10950 \end_inset
10951 </cell>
10952 </row>
10953 <row topline="true">
10954 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10955 \begin_inset Text
10956
10957 \layout Standard
10958
10959 0
10960 \end_inset
10961 </cell>
10962 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10963 \begin_inset Text
10964
10965 \layout Standard
10966
10967 External 0
10968 \end_inset
10969 </cell>
10970 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10971 \begin_inset Text
10972
10973 \layout Standard
10974
10975 0x0003
10976 \end_inset
10977 </cell>
10978 </row>
10979 <row topline="true">
10980 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10981 \begin_inset Text
10982
10983 \layout Standard
10984
10985 1
10986 \end_inset
10987 </cell>
10988 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10989 \begin_inset Text
10990
10991 \layout Standard
10992
10993 Timer 0
10994 \end_inset
10995 </cell>
10996 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10997 \begin_inset Text
10998
10999 \layout Standard
11000
11001 0x000B
11002 \end_inset
11003 </cell>
11004 </row>
11005 <row topline="true">
11006 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11007 \begin_inset Text
11008
11009 \layout Standard
11010
11011 2
11012 \end_inset
11013 </cell>
11014 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11015 \begin_inset Text
11016
11017 \layout Standard
11018
11019 External 1
11020 \end_inset
11021 </cell>
11022 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11023 \begin_inset Text
11024
11025 \layout Standard
11026
11027 0x0013
11028 \end_inset
11029 </cell>
11030 </row>
11031 <row topline="true">
11032 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11033 \begin_inset Text
11034
11035 \layout Standard
11036
11037 3
11038 \end_inset
11039 </cell>
11040 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11041 \begin_inset Text
11042
11043 \layout Standard
11044
11045 Timer 1
11046 \end_inset
11047 </cell>
11048 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11049 \begin_inset Text
11050
11051 \layout Standard
11052
11053 0x001B
11054 \end_inset
11055 </cell>
11056 </row>
11057 <row topline="true">
11058 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11059 \begin_inset Text
11060
11061 \layout Standard
11062
11063 4
11064 \end_inset
11065 </cell>
11066 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11067 \begin_inset Text
11068
11069 \layout Standard
11070
11071 Serial
11072 \end_inset
11073 </cell>
11074 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11075 \begin_inset Text
11076
11077 \layout Standard
11078
11079 0x0023
11080 \end_inset
11081 </cell>
11082 </row>
11083 <row topline="true" bottomline="true">
11084 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11085 \begin_inset Text
11086
11087 \layout Standard
11088
11089 5
11090 \end_inset
11091 </cell>
11092 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11093 \begin_inset Text
11094
11095 \layout Standard
11096
11097 Timer 2 (8052)
11098 \end_inset
11099 </cell>
11100 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11101 \begin_inset Text
11102
11103 \layout Standard
11104
11105 0x002B
11106 \end_inset
11107 </cell>
11108 </row>
11109 </lyxtabular>
11110
11111 \end_inset
11112
11113
11114 \newline
11115
11116 \layout Standard
11117
11118 If the interrupt service routine is defined without
11119 \emph on
11120 using
11121 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11122
11123 \end_inset
11124
11125
11126 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11127
11128 \end_inset
11129
11130
11131 \emph default
11132  a register bank or with register bank 0 (
11133 \emph on
11134 using
11135 \emph default
11136  0), the compiler will save the registers used by itself on the stack upon
11137  entry and restore them at exit, however if such an interrupt service routine
11138  calls another function then the entire register bank will be saved on the
11139  stack.
11140  This scheme may be advantageous for small interrupt service routines which
11141  have low register usage.
11142 \layout Standard
11143
11144 If the interrupt service routine is defined to be using a specific register
11145  bank then only
11146 \emph on
11147 a, b, dptr
11148 \emph default
11149  & psw are saved and restored, if such an interrupt service routine calls
11150  another function (using another register bank) then the entire register
11151  bank of the called function will be saved on the stack.
11152  This scheme is recommended for larger interrupt service routines.
11153 \layout Subsection
11154
11155 HC08 Interrupt Service Routines
11156 \layout Standard
11157
11158 Since the number of interrupts available is chip specific and the interrupt
11159  vector table always ends at the last byte of memory, the interrupt numbers
11160  corresponds to the interrupt vectors in reverse order of address.
11161  For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
11162  2 will use the interrupt vector at 0xfffa, and so on.
11163  However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
11164  this way; instead see section
11165 \begin_inset LatexCommand \ref{sub:Startup-Code}
11166
11167 \end_inset
11168
11169  for details on customizing startup.
11170 \layout Subsection
11171
11172 Z80 Interrupt Service Routines
11173 \layout Standard
11174
11175 The Z80 uses several different methods for determining the correct interrupt
11176  vector depending on the hardware implementation.
11177  Therefore, SDCC ignores the optional interrupt number and does not attempt
11178  to generate an interrupt vector table.
11179 \layout Standard
11180
11181 By default, SDCC generates code for a maskable interrupt, which uses an
11182  RETI instruction to return from the interrupt.
11183  To write an interrupt handler for the non-maskable interrupt, which needs
11184  an RETN instruction instead, add the
11185 \emph on
11186 critical
11187 \emph default
11188  keyword:
11189 \layout Verse
11190
11191
11192 \family typewriter
11193 void nmi_isr (void) critical interrupt
11194 \newline
11195 {
11196 \newline
11197 \SpecialChar ~
11198 \SpecialChar ~
11199 \SpecialChar ~
11200 \SpecialChar ~
11201 ...
11202
11203 \newline
11204 }
11205 \layout Section
11206
11207 Enabling and Disabling Interrupts
11208 \layout Subsection
11209
11210 Critical Functions and Critical Statements
11211 \layout Standard
11212
11213 A special keyword may be associated with a block or a function declaring
11214  it as
11215 \emph on
11216 critical
11217 \emph default
11218 .
11219  SDCC will generate code to disable all interrupts
11220 \begin_inset LatexCommand \index{interrupt}
11221
11222 \end_inset
11223
11224  upon entry to a critical function and restore the interrupt enable to the
11225  previous state before returning.
11226  Nesting critical functions will need one additional byte on the stack
11227 \begin_inset LatexCommand \index{stack}
11228
11229 \end_inset
11230
11231  for each call.
11232 \layout Verse
11233
11234
11235 \family typewriter
11236 int foo () critical
11237 \begin_inset LatexCommand \index{critical}
11238
11239 \end_inset
11240
11241
11242 \begin_inset LatexCommand \index{\_\_critical}
11243
11244 \end_inset
11245
11246
11247 \newline
11248 {
11249 \newline
11250 \SpecialChar ~
11251 \SpecialChar ~
11252 \SpecialChar ~
11253 \SpecialChar ~
11254 ...
11255
11256 \newline
11257 \SpecialChar ~
11258 \SpecialChar ~
11259 \SpecialChar ~
11260 \SpecialChar ~
11261 ...
11262
11263 \newline
11264 }
11265 \layout Standard
11266
11267 The critical attribute maybe used with other attributes like
11268 \emph on
11269 reentrant.
11270 \emph default
11271
11272 \newline
11273 The keyword
11274 \emph on
11275 critical
11276 \emph default
11277  may also be used to disable interrupts more locally:
11278 \layout Verse
11279
11280
11281 \family typewriter
11282 critical{ i++; }
11283 \layout Standard
11284
11285 More than one statement could have been included in the block.
11286 \layout Subsection
11287
11288 Enabling and Disabling Interrupts directly
11289 \layout Standard
11290
11291 Interrupts
11292 \begin_inset LatexCommand \index{interrupt}
11293
11294 \end_inset
11295
11296  can also be disabled and enabled directly (8051):
11297 \layout Verse
11298
11299
11300 \family typewriter
11301 EA = 0;\SpecialChar ~
11302 \SpecialChar ~
11303 \SpecialChar ~
11304 \SpecialChar ~
11305 \SpecialChar ~
11306 \SpecialChar ~
11307 \SpecialChar ~
11308 \SpecialChar ~
11309 \SpecialChar ~
11310 \SpecialChar ~
11311 \SpecialChar ~
11312 \SpecialChar ~
11313 or:\SpecialChar ~
11314 \SpecialChar ~
11315 \SpecialChar ~
11316 \SpecialChar ~
11317 \SpecialChar ~
11318 \SpecialChar ~
11319 \SpecialChar ~
11320 \SpecialChar ~
11321 \SpecialChar ~
11322 \SpecialChar ~
11323 \SpecialChar ~
11324 EA_SAVE = EA;
11325 \layout Verse
11326
11327
11328 \family typewriter
11329 ...\SpecialChar ~
11330 \SpecialChar ~
11331 \SpecialChar ~
11332 \SpecialChar ~
11333 \SpecialChar ~
11334 \SpecialChar ~
11335 \SpecialChar ~
11336 \SpecialChar ~
11337 \SpecialChar ~
11338 \SpecialChar ~
11339 \SpecialChar ~
11340 \SpecialChar ~
11341 \SpecialChar ~
11342 \SpecialChar ~
11343 \SpecialChar ~
11344 \SpecialChar ~
11345 \SpecialChar ~
11346 \SpecialChar ~
11347 \SpecialChar ~
11348 \SpecialChar ~
11349 \SpecialChar ~
11350 \SpecialChar ~
11351 \SpecialChar ~
11352 \SpecialChar ~
11353 \SpecialChar ~
11354 \SpecialChar ~
11355 \SpecialChar ~
11356 \SpecialChar ~
11357 \SpecialChar ~
11358 \SpecialChar ~
11359 EA = 0;
11360 \layout Verse
11361
11362
11363 \family typewriter
11364 EA = 1;\SpecialChar ~
11365 \SpecialChar ~
11366 \SpecialChar ~
11367 \SpecialChar ~
11368 \SpecialChar ~
11369 \SpecialChar ~
11370 \SpecialChar ~
11371 \SpecialChar ~
11372 \SpecialChar ~
11373 \SpecialChar ~
11374 \SpecialChar ~
11375 \SpecialChar ~
11376 \SpecialChar ~
11377 \SpecialChar ~
11378 \SpecialChar ~
11379 \SpecialChar ~
11380 \SpecialChar ~
11381 \SpecialChar ~
11382 \SpecialChar ~
11383 \SpecialChar ~
11384 \SpecialChar ~
11385 \SpecialChar ~
11386 \SpecialChar ~
11387 \SpecialChar ~
11388 \SpecialChar ~
11389 \SpecialChar ~
11390 ...
11391 \layout Verse
11392
11393
11394 \family typewriter
11395 \SpecialChar ~
11396 \SpecialChar ~
11397 \SpecialChar ~
11398 \SpecialChar ~
11399 \SpecialChar ~
11400 \SpecialChar ~
11401 \SpecialChar ~
11402 \SpecialChar ~
11403 \SpecialChar ~
11404 \SpecialChar ~
11405 \SpecialChar ~
11406 \SpecialChar ~
11407 \SpecialChar ~
11408 \SpecialChar ~
11409 \SpecialChar ~
11410 \SpecialChar ~
11411 \SpecialChar ~
11412 \SpecialChar ~
11413 \SpecialChar ~
11414 \SpecialChar ~
11415 \SpecialChar ~
11416 \SpecialChar ~
11417 \SpecialChar ~
11418 \SpecialChar ~
11419 \SpecialChar ~
11420 \SpecialChar ~
11421 \SpecialChar ~
11422 \SpecialChar ~
11423 \SpecialChar ~
11424 \SpecialChar ~
11425 \SpecialChar ~
11426 \SpecialChar ~
11427 \SpecialChar ~
11428 EA = EA_SAVE;
11429 \layout Standard
11430
11431 On other architectures which have seperate opcodes for enabling and disabling
11432  interrupts you might want to make use of defines with inline assembly
11433 \begin_inset LatexCommand \index{Assembler routines}
11434
11435 \end_inset
11436
11437  (HC08):
11438 \layout Verse
11439
11440
11441 \family typewriter
11442 #define CLI _asm
11443 \begin_inset LatexCommand \index{\_asm}
11444
11445 \end_inset
11446
11447 \SpecialChar ~
11448 \SpecialChar ~
11449 cli\SpecialChar ~
11450 \SpecialChar ~
11451 _endasm
11452 \begin_inset LatexCommand \index{\_endasm}
11453
11454 \end_inset
11455
11456 ;
11457 \layout Verse
11458
11459
11460 \family typewriter
11461 #define SEI _asm\SpecialChar ~
11462 \SpecialChar ~
11463 sei\SpecialChar ~
11464 \SpecialChar ~
11465 _endasm;
11466 \layout Verse
11467
11468
11469 \family typewriter
11470 ...
11471 \layout Standard
11472
11473 Note: it is sometimes sufficient to disable only a specific interrupt source
11474  like f.e.
11475  a timer or serial interrupt by manipulating an
11476 \emph on
11477 interrupt mask
11478 \begin_inset LatexCommand \index{interrupt mask}
11479
11480 \end_inset
11481
11482
11483 \emph default
11484  register.
11485
11486 \layout Standard
11487
11488 Usually the time during which interrupts are disabled should be kept as
11489  short as possible.
11490  This minimizes both
11491 \emph on
11492 interrupt latency
11493 \emph default
11494
11495 \begin_inset LatexCommand \index{interrupt latency}
11496
11497 \end_inset
11498
11499  (the time between the occurrence of the interrupt and the execution of
11500  the first code in the interrupt routine) and
11501 \emph on
11502 interrupt jitter
11503 \emph default
11504
11505 \begin_inset LatexCommand \index{interrupt jitter}
11506
11507 \end_inset
11508
11509  (the difference between the shortest and the longest interrupt latency).
11510  These really are something different, f.e.
11511  a serial interrupt has to be served before its buffer overruns so it cares
11512  for the maximum interrupt latency, whereas it does not care about jitter.
11513  On a loudspeaker driven via a digital to analog converter which is fed
11514  by an interrupt a latency of a few milliseconds might be tolerable, whereas
11515  a much smaller jitter will be very audible.
11516 \layout Standard
11517
11518 You can reenable interrupts within an interrupt routine and on some architecture
11519 s you can make use of two (or more) levels of
11520 \emph on
11521 interrupt priorities
11522 \emph default
11523
11524 \begin_inset LatexCommand \index{interrupt priority}
11525
11526 \end_inset
11527
11528 .
11529  On some architectures which don't support interrupt priorities these can
11530  be implemented by manipulating the interrupt mask and reenabling interrupts
11531  within the interrupt routine.
11532  Check there is sufficient space on the stack
11533 \begin_inset LatexCommand \index{stack}
11534
11535 \end_inset
11536
11537  and don't add complexity unless you have to.
11538
11539 \layout Subsection
11540
11541 Semaphore
11542 \begin_inset LatexCommand \index{semaphore}
11543
11544 \end_inset
11545
11546  locking (mcs51/ds390)
11547 \layout Standard
11548
11549 Some architectures (mcs51/ds390) have an atomic
11550 \begin_inset LatexCommand \index{atomic}
11551
11552 \end_inset
11553
11554  bit test and
11555 \emph on
11556
11557 \emph default
11558 clear
11559 \emph on
11560
11561 \emph default
11562 instruction.
11563  These type of instructions are typically used in preemptive multitasking
11564  systems, where a routine f.e.
11565  claims the use of a data structure ('acquires a lock
11566 \begin_inset LatexCommand \index{lock}
11567
11568 \end_inset
11569
11570  on it'), makes some modifications and then releases the lock when the data
11571  structure is consistent again.
11572  The instruction may also be used if interrupt and non-interrupt code have
11573  to compete for a resource.
11574  With the atomic bit test and clear instruction interrupts
11575 \begin_inset LatexCommand \index{interrupt}
11576
11577 \end_inset
11578
11579  don't have to be disabled for the locking operation.
11580
11581 \layout Standard
11582
11583 SDCC generates this instruction if the source follows this pattern:
11584 \layout Verse
11585
11586
11587 \family typewriter
11588 volatile
11589 \begin_inset LatexCommand \index{volatile}
11590
11591 \end_inset
11592
11593  bit resource_is_free;
11594 \newline
11595
11596 \newline
11597 if (resource_is_free)
11598 \newline
11599 \SpecialChar ~
11600 \SpecialChar ~
11601 {
11602 \newline
11603 \SpecialChar ~
11604 \SpecialChar ~
11605 \SpecialChar ~
11606 \SpecialChar ~
11607 resource_is_free=0;
11608 \newline
11609 \SpecialChar ~
11610 \SpecialChar ~
11611 \SpecialChar ~
11612 \SpecialChar ~
11613 ...
11614
11615 \newline
11616 \SpecialChar ~
11617 \SpecialChar ~
11618 \SpecialChar ~
11619 \SpecialChar ~
11620 resource_is_free=1;
11621 \newline
11622 \SpecialChar ~
11623 \SpecialChar ~
11624 }
11625 \layout Standard
11626
11627 Note, mcs51 and ds390 support only an atomic
11628 \begin_inset LatexCommand \index{atomic}
11629
11630 \end_inset
11631
11632  bit test and
11633 \emph on
11634 clear
11635 \emph default
11636  instruction (as opposed to atomic bit test and
11637 \emph on
11638 set).
11639 \layout Section
11640
11641 Functions using private register banks
11642 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
11643
11644 \end_inset
11645
11646  (mcs51/ds390)
11647 \layout Standard
11648
11649 Some architectures have support for quickly changing register sets.
11650  SDCC supports this feature with the
11651 \emph on
11652 using
11653 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11654
11655 \end_inset
11656
11657
11658 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11659
11660 \end_inset
11661
11662
11663 \emph default
11664  attribute (which tells the compiler to use a register bank
11665 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
11666
11667 \end_inset
11668
11669  other than the default bank zero).
11670  It should only be applied to
11671 \emph on
11672 interrupt
11673 \begin_inset LatexCommand \index{interrupt}
11674
11675 \end_inset
11676
11677
11678 \emph default
11679  functions (see footnote below).
11680  This will in most circumstances make the generated ISR code more efficient
11681  since it will not have to save registers on the stack.
11682 \layout Standard
11683
11684 The
11685 \emph on
11686 using
11687 \emph default
11688  attribute will have no effect on the generated code for a
11689 \emph on
11690 non-interrupt
11691 \emph default
11692  function (but may occasionally be useful anyway
11693 \begin_inset Foot
11694 collapsed false
11695
11696 \layout Standard
11697
11698 possible exception: if a function is called ONLY from 'interrupt' functions
11699  using a particular bank, it can be declared with the same 'using' attribute
11700  as the calling 'interrupt' functions.
11701  For instance, if you have several ISRs using bank one, and all of them
11702  call memcpy(), it might make sense to create a specialized version of memcpy()
11703  'using 1', since this would prevent the ISR from having to save bank zero
11704  to the stack on entry and switch to bank zero before calling the function
11705 \end_inset
11706
11707 ).
11708 \newline
11709
11710 \emph on
11711 (pending: I don't think this has been done yet)
11712 \layout Standard
11713
11714 An
11715 \emph on
11716 interrupt
11717 \emph default
11718  function using a non-zero bank will assume that it can trash that register
11719  bank, and will not save it.
11720  Since high-priority interrupts
11721 \begin_inset LatexCommand \index{interrupts}
11722
11723 \end_inset
11724
11725
11726 \begin_inset LatexCommand \index{interrupt priority}
11727
11728 \end_inset
11729
11730  can interrupt low-priority ones on the 8051 and friends, this means that
11731  if a high-priority ISR
11732 \emph on
11733 using
11734 \emph default
11735  a particular bank occurs while processing a low-priority ISR
11736 \emph on
11737 using
11738 \emph default
11739  the same bank, terrible and bad things can happen.
11740  To prevent this, no single register bank should be
11741 \emph on
11742 used
11743 \emph default
11744  by both a high priority and a low priority ISR.
11745  This is probably most easily done by having all high priority ISRs use
11746  one bank and all low priority ISRs use another.
11747  If you have an ISR which can change priority at runtime, you're on your
11748  own: I suggest using the default bank zero and taking the small performance
11749  hit.
11750 \layout Standard
11751
11752 It is most efficient if your ISR calls no other functions.
11753  If your ISR must call other functions, it is most efficient if those functions
11754  use the same bank as the ISR (see note 1 below); the next best is if the
11755  called functions use bank zero.
11756  It is very inefficient to call a function using a different, non-zero bank
11757  from an ISR.
11758
11759 \layout Section
11760
11761 Startup Code
11762 \begin_inset LatexCommand \label{sub:Startup-Code}
11763
11764 \end_inset
11765
11766
11767 \begin_inset LatexCommand \index{Startup code}
11768
11769 \end_inset
11770
11771
11772 \layout Subsection
11773
11774 MCS51/DS390 Startup Code
11775 \layout Standard
11776
11777 The compiler inserts a call to the C routine
11778 \emph on
11779 _sdcc_external_startup()
11780 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
11781
11782 \end_inset
11783
11784
11785 \series bold
11786 \emph default
11787
11788 \series default
11789 at the start of the CODE area.
11790  This routine is in the runtime library
11791 \begin_inset LatexCommand \index{Runtime library}
11792
11793 \end_inset
11794
11795 .
11796  By default this routine returns 0, if this routine returns a non-zero value,
11797  the static & global variable initialization will be skipped and the function
11798  main will be invoked.
11799  Otherwise static & global variables will be initialized before the function
11800  main is invoked.
11801  You could add a
11802 \emph on
11803 _sdcc_external_startup()
11804 \emph default
11805  routine to your program to override the default if you need to setup hardware
11806  or perform some other critical operation prior to static & global variable
11807  initialization
11808 \begin_inset LatexCommand \index{Variable initialization}
11809
11810 \end_inset
11811
11812 .
11813  On some mcs51 variants xdata
11814 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
11815
11816 \end_inset
11817
11818  memory has to be explicitly enabled before it can be accessed or if the
11819  watchdog needs to be disabled, this is the place to do it.
11820  The startup code clears all internal data memory, 256 bytes by default,
11821  but from 0 to n-1 if
11822 \emph on
11823 -
11824 \begin_inset ERT
11825 status Collapsed
11826
11827 \layout Standard
11828
11829 \backslash
11830 /
11831 \end_inset
11832
11833 -iram-size
11834 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
11835
11836 \end_inset
11837
11838 n
11839 \emph default
11840  is used.
11841  (recommended for Chipcon CC1010).
11842 \layout Standard
11843
11844 See also the compiler option
11845 \emph on
11846 -
11847 \begin_inset ERT
11848 status Collapsed
11849
11850 \layout Standard
11851
11852 \backslash
11853 /
11854 \end_inset
11855
11856 -no-xinit
11857 \emph default
11858 -
11859 \emph on
11860 opt
11861 \emph default
11862
11863 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
11864
11865 \end_inset
11866
11867  and section
11868 \begin_inset LatexCommand \ref{sub:MCS51-variants}
11869
11870 \end_inset
11871
11872 \SpecialChar ~
11873 about MCS51-variants.
11874 \layout Subsection
11875
11876 HC08 Startup Code
11877 \layout Standard
11878
11879 The HC08 startup code follows the same scheme as the MCS51 startup code.
11880 \layout Subsection
11881
11882 Z80 Startup Code
11883 \layout Standard
11884
11885 On the Z80 the startup code is inserted by linking with crt0.o which is generated
11886  from sdcc/device/lib/z80/crt0.s.
11887  If you need a different startup code you can use the compiler option
11888 \emph on
11889 -
11890 \series bold
11891 \emph default
11892
11893 \begin_inset ERT
11894 status Collapsed
11895
11896 \layout Standard
11897
11898 \backslash
11899 /
11900 \end_inset
11901
11902
11903 \series default
11904 \emph on
11905 -no-std-crt0
11906 \emph default
11907
11908 \begin_inset LatexCommand \index{-\/-no-std-crt0}
11909
11910 \end_inset
11911
11912  and provide your own crt0.o.
11913
11914 \layout Section
11915
11916 Inline Assembler Code
11917 \begin_inset LatexCommand \index{Assembler routines}
11918
11919 \end_inset
11920
11921
11922 \layout Subsection
11923
11924 A Step by Step Introduction
11925 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
11926
11927 \end_inset
11928
11929
11930 \layout Standard
11931
11932 Starting from a small snippet of c-code this example shows for the MCS51
11933  how to use inline assembly, access variables, a function parameter and
11934  an array in xdata memory.
11935  The example uses an MCS51 here but is easily adapted for other architectures.
11936  This is a buffer routine which should be optimized:
11937 \layout Verse
11938
11939
11940 \family typewriter
11941 \size footnotesize
11942 unsigned char far
11943 \begin_inset LatexCommand \index{far (storage class)}
11944
11945 \end_inset
11946
11947
11948 \begin_inset LatexCommand \index{\_\_far (storage class)}
11949
11950 \end_inset
11951
11952  at
11953 \begin_inset LatexCommand \index{at}
11954
11955 \end_inset
11956
11957
11958 \begin_inset LatexCommand \index{\_\_at}
11959
11960 \end_inset
11961
11962  0x7f00 buf[0x100];
11963 \begin_inset LatexCommand \index{Aligned array}
11964
11965 \end_inset
11966
11967
11968 \newline
11969 unsigned char head,tail;
11970 \newline
11971
11972 \newline
11973 void to_buffer( unsigned char c )
11974 \newline
11975 {
11976 \newline
11977 \SpecialChar ~
11978 \SpecialChar ~
11979 \SpecialChar ~
11980 \SpecialChar ~
11981 if( head != tail-1 )
11982 \newline
11983 \SpecialChar ~
11984 \SpecialChar ~
11985 \SpecialChar ~
11986 \SpecialChar ~
11987 \SpecialChar ~
11988 \SpecialChar ~
11989 \SpecialChar ~
11990 \SpecialChar ~
11991 buf[ head++ ] = c;\SpecialChar ~
11992 \SpecialChar ~
11993 \SpecialChar ~
11994 \SpecialChar ~
11995 /* access to a 256 byte aligned array */
11996 \newline
11997 }
11998 \layout Standard
11999
12000 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
12001  then a corresponding buffer.asm file is generated.
12002  We define a new function
12003 \family typewriter
12004 to_buffer_asm()
12005 \family default
12006  in file buffer.c in which we cut and paste the generated code, removing
12007  unwanted comments and some ':'.
12008  Then add
12009 \begin_inset Quotes sld
12010 \end_inset
12011
12012 _asm
12013 \begin_inset Quotes srd
12014 \end_inset
12015
12016  and
12017 \begin_inset Quotes sld
12018 \end_inset
12019
12020 _endasm;
12021 \begin_inset Quotes srd
12022 \end_inset
12023
12024  to the beginning and the end of the function body:
12025 \layout Verse
12026
12027
12028 \family typewriter
12029 \size footnotesize
12030 /* With a cut and paste from the .asm file, we have something to start with.
12031 \newline
12032 \SpecialChar ~
12033 \SpecialChar ~
12034 \SpecialChar ~
12035 The function is not yet OK! (registers aren't saved) */
12036 \newline
12037 void to_buffer_asm( unsigned char c )
12038 \newline
12039 {
12040 \newline
12041 \SpecialChar ~
12042 \SpecialChar ~
12043 \SpecialChar ~
12044 \SpecialChar ~
12045 _asm
12046 \begin_inset LatexCommand \index{\_asm}
12047
12048 \end_inset
12049
12050
12051 \begin_inset LatexCommand \index{\_\_asm}
12052
12053 \end_inset
12054
12055
12056 \newline
12057 \SpecialChar ~
12058 \SpecialChar ~
12059 \SpecialChar ~
12060 \SpecialChar ~
12061 mov\SpecialChar ~
12062 \SpecialChar ~
12063 r2,dpl
12064 \newline
12065 ;buffer.c if( head != tail-1 )
12066 \newline
12067 \SpecialChar ~
12068 \SpecialChar ~
12069 \SpecialChar ~
12070 \SpecialChar ~
12071 mov\SpecialChar ~
12072 \SpecialChar ~
12073 a,_tail
12074 \newline
12075 \SpecialChar ~
12076 \SpecialChar ~
12077 \SpecialChar ~
12078 \SpecialChar ~
12079 dec\SpecialChar ~
12080 \SpecialChar ~
12081 a
12082 \newline
12083 \SpecialChar ~
12084 \SpecialChar ~
12085 \SpecialChar ~
12086 \SpecialChar ~
12087 mov\SpecialChar ~
12088 \SpecialChar ~
12089 r3,a
12090 \newline
12091 \SpecialChar ~
12092 \SpecialChar ~
12093 \SpecialChar ~
12094 \SpecialChar ~
12095 mov\SpecialChar ~
12096 \SpecialChar ~
12097 a,_head
12098 \newline
12099 \SpecialChar ~
12100 \SpecialChar ~
12101 \SpecialChar ~
12102 \SpecialChar ~
12103 cjne a,ar3,00106$
12104 \newline
12105 \SpecialChar ~
12106 \SpecialChar ~
12107 \SpecialChar ~
12108 \SpecialChar ~
12109 ret
12110 \newline
12111 00106$:
12112 \newline
12113 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
12114 \begin_inset LatexCommand \index{Aligned array}
12115
12116 \end_inset
12117
12118
12119 \newline
12120 \SpecialChar ~
12121 \SpecialChar ~
12122 \SpecialChar ~
12123 \SpecialChar ~
12124 mov\SpecialChar ~
12125 \SpecialChar ~
12126 r3,_head
12127 \newline
12128 \SpecialChar ~
12129 \SpecialChar ~
12130 \SpecialChar ~
12131 \SpecialChar ~
12132 inc\SpecialChar ~
12133 \SpecialChar ~
12134 _head
12135 \newline
12136 \SpecialChar ~
12137 \SpecialChar ~
12138 \SpecialChar ~
12139 \SpecialChar ~
12140 mov\SpecialChar ~
12141 \SpecialChar ~
12142 dpl,r3
12143 \newline
12144 \SpecialChar ~
12145 \SpecialChar ~
12146 \SpecialChar ~
12147 \SpecialChar ~
12148 mov\SpecialChar ~
12149 \SpecialChar ~
12150 dph,#(_buf >> 8)
12151 \newline
12152 \SpecialChar ~
12153 \SpecialChar ~
12154 \SpecialChar ~
12155 \SpecialChar ~
12156 mov\SpecialChar ~
12157 \SpecialChar ~
12158 a,r2
12159 \newline
12160 \SpecialChar ~
12161 \SpecialChar ~
12162 \SpecialChar ~
12163 \SpecialChar ~
12164 movx @dptr,a
12165 \newline
12166 00103$:
12167 \newline
12168 \SpecialChar ~
12169 \SpecialChar ~
12170 \SpecialChar ~
12171 \SpecialChar ~
12172 ret
12173 \newline
12174 \SpecialChar ~
12175 \SpecialChar ~
12176 \SpecialChar ~
12177 \SpecialChar ~
12178 _endasm
12179 \begin_inset LatexCommand \index{\_endasm}
12180
12181 \end_inset
12182
12183
12184 \begin_inset LatexCommand \index{\_\_endasm}
12185
12186 \end_inset
12187
12188 ;
12189 \newline
12190 }
12191 \layout Standard
12192
12193 The new file buffer.c should compile with only one warning about the unreferenced
12194  function argument 'c'.
12195  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
12196  (1) and finally have:
12197 \layout Verse
12198
12199
12200 \family typewriter
12201 \size footnotesize
12202 unsigned char far at 0x7f00 buf[0x100];
12203 \newline
12204 unsigned char head,tail;
12205 \newline
12206 #define USE_ASSEMBLY (1)
12207 \newline
12208
12209 \newline
12210 #if !USE_ASSEMBLY
12211 \newline
12212
12213 \newline
12214 void to_buffer( unsigned char c )
12215 \newline
12216 {
12217 \newline
12218 \SpecialChar ~
12219 \SpecialChar ~
12220 \SpecialChar ~
12221 \SpecialChar ~
12222 if( head != tail-1 )
12223 \newline
12224 \SpecialChar ~
12225 \SpecialChar ~
12226 \SpecialChar ~
12227 \SpecialChar ~
12228 \SpecialChar ~
12229 \SpecialChar ~
12230 \SpecialChar ~
12231 \SpecialChar ~
12232 buf[ head++ ] = c;
12233 \newline
12234 }
12235 \newline
12236
12237 \newline
12238 #else
12239 \newline
12240
12241 \newline
12242 void to_buffer( unsigned char c )
12243 \newline
12244 {
12245 \newline
12246 \SpecialChar ~
12247 \SpecialChar ~
12248 \SpecialChar ~
12249 \SpecialChar ~
12250 c; // to avoid warning: unreferenced function argument
12251 \newline
12252 \SpecialChar ~
12253 \SpecialChar ~
12254 \SpecialChar ~
12255 \SpecialChar ~
12256 _asm
12257 \begin_inset LatexCommand \index{\_asm}
12258
12259 \end_inset
12260
12261
12262 \begin_inset LatexCommand \index{\_\_asm}
12263
12264 \end_inset
12265
12266
12267 \newline
12268 \SpecialChar ~
12269 \SpecialChar ~
12270 \SpecialChar ~
12271 \SpecialChar ~
12272 \SpecialChar ~
12273 \SpecialChar ~
12274 \SpecialChar ~
12275 \SpecialChar ~
12276 ; save used registers here.
12277
12278 \newline
12279 \SpecialChar ~
12280 \SpecialChar ~
12281 \SpecialChar ~
12282 \SpecialChar ~
12283 \SpecialChar ~
12284 \SpecialChar ~
12285 \SpecialChar ~
12286 \SpecialChar ~
12287 ; If we were still using r2,r3 we would have to push them here.
12288
12289 \newline
12290 ; if( head != tail-1 )
12291 \newline
12292 \SpecialChar ~
12293 \SpecialChar ~
12294 \SpecialChar ~
12295 \SpecialChar ~
12296 \SpecialChar ~
12297 \SpecialChar ~
12298 \SpecialChar ~
12299 \SpecialChar ~
12300 mov\SpecialChar ~
12301  a,_tail
12302 \newline
12303 \SpecialChar ~
12304 \SpecialChar ~
12305 \SpecialChar ~
12306 \SpecialChar ~
12307 \SpecialChar ~
12308 \SpecialChar ~
12309 \SpecialChar ~
12310 \SpecialChar ~
12311 dec\SpecialChar ~
12312  a
12313 \newline
12314 \SpecialChar ~
12315 \SpecialChar ~
12316 \SpecialChar ~
12317 \SpecialChar ~
12318 \SpecialChar ~
12319 \SpecialChar ~
12320 \SpecialChar ~
12321 \SpecialChar ~
12322 xrl\SpecialChar ~
12323  a,_head
12324 \newline
12325 \SpecialChar ~
12326 \SpecialChar ~
12327 \SpecialChar ~
12328 \SpecialChar ~
12329 \SpecialChar ~
12330 \SpecialChar ~
12331 \SpecialChar ~
12332 \SpecialChar ~
12333 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
12334 \newline
12335 \SpecialChar ~
12336 \SpecialChar ~
12337 \SpecialChar ~
12338 \SpecialChar ~
12339 \SpecialChar ~
12340 \SpecialChar ~
12341 \SpecialChar ~
12342 \SpecialChar ~
12343 jz\SpecialChar ~
12344 \SpecialChar ~
12345  t_b_end$
12346 \newline
12347 \SpecialChar ~
12348 \SpecialChar ~
12349 \SpecialChar ~
12350 \SpecialChar ~
12351 \SpecialChar ~
12352 \SpecialChar ~
12353 \SpecialChar ~
12354 \SpecialChar ~
12355 ;
12356 \newline
12357 ; buf[ head++ ] = c;
12358 \newline
12359 \SpecialChar ~
12360 \SpecialChar ~
12361 \SpecialChar ~
12362 \SpecialChar ~
12363 \SpecialChar ~
12364 \SpecialChar ~
12365 \SpecialChar ~
12366 \SpecialChar ~
12367 mov\SpecialChar ~
12368  a,dpl \SpecialChar ~
12369 \SpecialChar ~
12370 \SpecialChar ~
12371 \SpecialChar ~
12372 \SpecialChar ~
12373 \SpecialChar ~
12374 \SpecialChar ~
12375 ; dpl holds lower byte of function argument
12376 \newline
12377 \SpecialChar ~
12378 \SpecialChar ~
12379 \SpecialChar ~
12380 \SpecialChar ~
12381 \SpecialChar ~
12382 \SpecialChar ~
12383 \SpecialChar ~
12384 \SpecialChar ~
12385 mov\SpecialChar ~
12386  dpl,_head \SpecialChar ~
12387 \SpecialChar ~
12388 \SpecialChar ~
12389 ; buf is 0x100 byte aligned so head can be used directly
12390 \newline
12391 \SpecialChar ~
12392 \SpecialChar ~
12393 \SpecialChar ~
12394 \SpecialChar ~
12395 \SpecialChar ~
12396 \SpecialChar ~
12397 \SpecialChar ~
12398 \SpecialChar ~
12399 mov\SpecialChar ~
12400  dph,#(_buf>>8)
12401 \newline
12402 \SpecialChar ~
12403 \SpecialChar ~
12404 \SpecialChar ~
12405 \SpecialChar ~
12406 \SpecialChar ~
12407 \SpecialChar ~
12408 \SpecialChar ~
12409 \SpecialChar ~
12410 movx @dptr,a
12411 \newline
12412 \SpecialChar ~
12413 \SpecialChar ~
12414 \SpecialChar ~
12415 \SpecialChar ~
12416 \SpecialChar ~
12417 \SpecialChar ~
12418 \SpecialChar ~
12419 \SpecialChar ~
12420 inc \SpecialChar ~
12421 _head
12422 \newline
12423 \SpecialChar ~
12424 \SpecialChar ~
12425 \SpecialChar ~
12426 \SpecialChar ~
12427 \SpecialChar ~
12428 \SpecialChar ~
12429 \SpecialChar ~
12430 \SpecialChar ~
12431 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
12432 \newline
12433 t_b_end$:
12434 \newline
12435 \SpecialChar ~
12436 \SpecialChar ~
12437 \SpecialChar ~
12438 \SpecialChar ~
12439 \SpecialChar ~
12440 \SpecialChar ~
12441 \SpecialChar ~
12442 \SpecialChar ~
12443 ; restore used registers here
12444 \newline
12445 \SpecialChar ~
12446 \SpecialChar ~
12447 \SpecialChar ~
12448 \SpecialChar ~
12449 _endasm
12450 \begin_inset LatexCommand \index{\_endasm}
12451
12452 \end_inset
12453
12454
12455 \begin_inset LatexCommand \index{\_\_endasm}
12456
12457 \end_inset
12458
12459 ;
12460 \newline
12461 }
12462 \newline
12463 #endif
12464 \layout Standard
12465
12466 The inline assembler code can contain any valid code understood by the assembler
12467 , this includes any assembler directives and comment lines
12468 \begin_inset Foot
12469 collapsed false
12470
12471 \layout Standard
12472
12473 The assembler does not like some characters like ':' or ''' in comments.
12474  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
12475 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
12476
12477 \end_inset
12478
12479
12480 \begin_inset LatexCommand \index{Assembler documentation}
12481
12482 \end_inset
12483
12484
12485 \end_inset
12486
12487 .
12488  The compiler does not do any validation of the code within the
12489 \family typewriter
12490 _asm
12491 \begin_inset LatexCommand \index{\_asm}
12492
12493 \end_inset
12494
12495
12496 \begin_inset LatexCommand \index{\_\_asm}
12497
12498 \end_inset
12499
12500  ...
12501  _endasm
12502 \size footnotesize
12503
12504 \begin_inset LatexCommand \index{\_endasm}
12505
12506 \end_inset
12507
12508
12509 \begin_inset LatexCommand \index{\_\_endasm}
12510
12511 \end_inset
12512
12513
12514 \size default
12515 ;
12516 \family default
12517  keyword pair.
12518  Specifically it will not know which registers are used and thus register
12519  pushing/popping
12520 \begin_inset LatexCommand \index{push/pop}
12521
12522 \end_inset
12523
12524  has to be done manually.
12525
12526 \layout Standard
12527
12528 It is recommended that each assembly instruction (including labels) be placed
12529  in a separate line (as the example shows).
12530  When the -
12531 \begin_inset ERT
12532 status Collapsed
12533
12534 \layout Standard
12535
12536 \backslash
12537 /
12538 \end_inset
12539
12540 -
12541 \emph on
12542 peep-asm
12543 \begin_inset LatexCommand \index{-\/-peep-asm}
12544
12545 \end_inset
12546
12547
12548 \emph default
12549  command line option is used, the inline assembler code will be passed through
12550  the peephole optimizer
12551 \begin_inset LatexCommand \index{Peephole optimizer}
12552
12553 \end_inset
12554
12555 .
12556  There are only a few (if any) cases where this option makes sense, it might
12557  cause some unexpected changes in the inline assembler code.
12558  Please go through the peephole optimizer rules defined in file
12559 \emph on
12560 SDCCpeeph.def
12561 \emph default
12562  before using this option.
12563 \layout Subsection
12564
12565 Naked Functions
12566 \begin_inset LatexCommand \label{sub:Naked-Functions}
12567
12568 \end_inset
12569
12570
12571 \begin_inset LatexCommand \index{Naked functions}
12572
12573 \end_inset
12574
12575
12576 \layout Standard
12577
12578 A special keyword may be associated with a function declaring it as
12579 \emph on
12580 _naked
12581 \begin_inset LatexCommand \index{\_naked}
12582
12583 \end_inset
12584
12585
12586 \begin_inset LatexCommand \index{\_\_naked}
12587
12588 \end_inset
12589
12590 .
12591
12592 \emph default
12593 The
12594 \emph on
12595 _naked
12596 \emph default
12597  function modifier attribute prevents the compiler from generating prologue
12598 \begin_inset LatexCommand \index{function prologue}
12599
12600 \end_inset
12601
12602  and epilogue
12603 \begin_inset LatexCommand \index{function epilogue}
12604
12605 \end_inset
12606
12607  code for that function.
12608  This means that the user is entirely responsible for such things as saving
12609  any registers that may need to be preserved, selecting the proper register
12610  bank, generating the
12611 \emph on
12612 return
12613 \emph default
12614  instruction at the end, etc.
12615  Practically, this means that the contents of the function must be written
12616  in inline assembler.
12617  This is particularly useful for interrupt functions, which can have a large
12618  (and often unnecessary) prologue/epilogue.
12619  For example, compare the code generated by these two functions:
12620 \layout Verse
12621
12622
12623 \family typewriter
12624 volatile
12625 \begin_inset LatexCommand \index{volatile}
12626
12627 \end_inset
12628
12629  data unsigned char counter;
12630 \newline
12631
12632 \newline
12633 void simpleInterrupt(void) interrupt
12634 \begin_inset LatexCommand \index{interrupt}
12635
12636 \end_inset
12637
12638
12639 \begin_inset LatexCommand \index{\_\_interrupt}
12640
12641 \end_inset
12642
12643  1
12644 \newline
12645 {
12646 \newline
12647 \SpecialChar ~
12648 \SpecialChar ~
12649 \SpecialChar ~
12650 \SpecialChar ~
12651 counter++;
12652 \newline
12653 }
12654 \newline
12655
12656 \newline
12657 void nakedInterrupt(void) interrupt 2 _naked
12658 \newline
12659 {
12660 \newline
12661 \SpecialChar ~
12662 \SpecialChar ~
12663 \SpecialChar ~
12664 \SpecialChar ~
12665 _asm
12666 \begin_inset LatexCommand \index{\_asm}
12667
12668 \end_inset
12669
12670
12671 \begin_inset LatexCommand \index{\_\_asm}
12672
12673 \end_inset
12674
12675
12676 \newline
12677 \SpecialChar ~
12678 \SpecialChar ~
12679 \SpecialChar ~
12680 \SpecialChar ~
12681 \SpecialChar ~
12682 \SpecialChar ~
12683 inc\SpecialChar ~
12684 \SpecialChar ~
12685 \SpecialChar ~
12686 \SpecialChar ~
12687 \SpecialChar ~
12688 _counter ; does not change flags, no need to save psw
12689 \newline
12690 \SpecialChar ~
12691 \SpecialChar ~
12692 \SpecialChar ~
12693 \SpecialChar ~
12694 \SpecialChar ~
12695 \SpecialChar ~
12696 reti\SpecialChar ~
12697 \SpecialChar ~
12698 \SpecialChar ~
12699 \SpecialChar ~
12700 ; MUST explicitly include ret or reti in _naked function.
12701 \newline
12702 \SpecialChar ~
12703 \SpecialChar ~
12704 \SpecialChar ~
12705 \SpecialChar ~
12706 _endasm
12707 \begin_inset LatexCommand \index{\_endasm}
12708
12709 \end_inset
12710
12711
12712 \begin_inset LatexCommand \index{\_\_endasm}
12713
12714 \end_inset
12715
12716 ;
12717 \newline
12718 }
12719 \layout Standard
12720
12721 For an 8051 target, the generated simpleInterrupt looks like:
12722 \layout Verse
12723
12724
12725 \family typewriter
12726 _simpleInterrupt:
12727 \newline
12728 \SpecialChar ~
12729 \SpecialChar ~
12730 \SpecialChar ~
12731 \SpecialChar ~
12732 push\SpecialChar ~
12733 \SpecialChar ~
12734 \SpecialChar ~
12735 \SpecialChar ~
12736 acc
12737 \newline
12738 \SpecialChar ~
12739 \SpecialChar ~
12740 \SpecialChar ~
12741 \SpecialChar ~
12742 push\SpecialChar ~
12743 \SpecialChar ~
12744 \SpecialChar ~
12745 \SpecialChar ~
12746 b
12747 \newline
12748 \SpecialChar ~
12749 \SpecialChar ~
12750 \SpecialChar ~
12751 \SpecialChar ~
12752 push\SpecialChar ~
12753 \SpecialChar ~
12754 \SpecialChar ~
12755 \SpecialChar ~
12756 dpl
12757 \newline
12758 \SpecialChar ~
12759 \SpecialChar ~
12760 \SpecialChar ~
12761 \SpecialChar ~
12762 push\SpecialChar ~
12763 \SpecialChar ~
12764 \SpecialChar ~
12765 \SpecialChar ~
12766 dph
12767 \newline
12768 \SpecialChar ~
12769 \SpecialChar ~
12770 \SpecialChar ~
12771 \SpecialChar ~
12772 push\SpecialChar ~
12773 \SpecialChar ~
12774 \SpecialChar ~
12775 \SpecialChar ~
12776 psw
12777 \newline
12778 \SpecialChar ~
12779 \SpecialChar ~
12780 \SpecialChar ~
12781 \SpecialChar ~
12782 mov\SpecialChar ~
12783 \SpecialChar ~
12784 \SpecialChar ~
12785 \SpecialChar ~
12786 \SpecialChar ~
12787 psw,#0x00
12788 \newline
12789 \SpecialChar ~
12790 \SpecialChar ~
12791 \SpecialChar ~
12792 \SpecialChar ~
12793 inc\SpecialChar ~
12794 \SpecialChar ~
12795 \SpecialChar ~
12796 \SpecialChar ~
12797 \SpecialChar ~
12798 _counter
12799 \newline
12800 \SpecialChar ~
12801 \SpecialChar ~
12802 \SpecialChar ~
12803 \SpecialChar ~
12804 pop\SpecialChar ~
12805 \SpecialChar ~
12806 \SpecialChar ~
12807 \SpecialChar ~
12808 \SpecialChar ~
12809 psw
12810 \newline
12811 \SpecialChar ~
12812 \SpecialChar ~
12813 \SpecialChar ~
12814 \SpecialChar ~
12815 pop\SpecialChar ~
12816 \SpecialChar ~
12817 \SpecialChar ~
12818 \SpecialChar ~
12819 \SpecialChar ~
12820 dph
12821 \newline
12822 \SpecialChar ~
12823 \SpecialChar ~
12824 \SpecialChar ~
12825 \SpecialChar ~
12826 pop\SpecialChar ~
12827 \SpecialChar ~
12828 \SpecialChar ~
12829 \SpecialChar ~
12830 \SpecialChar ~
12831 dpl
12832 \newline
12833 \SpecialChar ~
12834 \SpecialChar ~
12835 \SpecialChar ~
12836 \SpecialChar ~
12837 pop\SpecialChar ~
12838 \SpecialChar ~
12839 \SpecialChar ~
12840 \SpecialChar ~
12841 \SpecialChar ~
12842 b
12843 \newline
12844 \SpecialChar ~
12845 \SpecialChar ~
12846 \SpecialChar ~
12847 \SpecialChar ~
12848 pop\SpecialChar ~
12849 \SpecialChar ~
12850 \SpecialChar ~
12851 \SpecialChar ~
12852 \SpecialChar ~
12853 acc
12854 \newline
12855 \SpecialChar ~
12856 \SpecialChar ~
12857 \SpecialChar ~
12858 \SpecialChar ~
12859 reti
12860 \layout Standard
12861
12862 whereas nakedInterrupt looks like:
12863 \layout Verse
12864
12865
12866 \family typewriter
12867 _nakedInterrupt:
12868 \newline
12869 \SpecialChar ~
12870 \SpecialChar ~
12871 \SpecialChar ~
12872 \SpecialChar ~
12873 inc\SpecialChar ~
12874 \SpecialChar ~
12875 \SpecialChar ~
12876 \SpecialChar ~
12877 _counter ; does not change flags, no need to save psw
12878 \newline
12879 \SpecialChar ~
12880 \SpecialChar ~
12881 \SpecialChar ~
12882 \SpecialChar ~
12883 reti\SpecialChar ~
12884 \SpecialChar ~
12885 \SpecialChar ~
12886 \SpecialChar ~
12887 \SpecialChar ~
12888 \SpecialChar ~
12889 \SpecialChar ~
12890 \SpecialChar ~
12891 \SpecialChar ~
12892 \SpecialChar ~
12893 \SpecialChar ~
12894 \SpecialChar ~
12895 ; MUST explicitly include ret or reti in _naked function
12896 \layout Standard
12897
12898 The related directive #pragma exclude
12899 \begin_inset LatexCommand \index{\#pragma exclude}
12900
12901 \end_inset
12902
12903  allows a more fine grained control over pushing & popping
12904 \begin_inset LatexCommand \index{push/pop}
12905
12906 \end_inset
12907
12908  the registers.
12909 \layout Standard
12910
12911 While there is nothing preventing you from writing C code inside a
12912 \family typewriter
12913 _naked
12914 \family default
12915  function, there are many ways to shoot yourself in the foot doing this,
12916  and it is recommended that you stick to inline assembler.
12917 \layout Subsection
12918
12919 Use of Labels within Inline Assembler
12920 \layout Standard
12921
12922 SDCC allows the use of in-line assembler with a few restrictions regarding
12923  labels.
12924  In older versions of the compiler all labels defined within inline assembler
12925  code
12926 \emph on
12927 had to be
12928 \emph default
12929  of the form
12930 \emph on
12931 nnnnn$
12932 \emph default
12933  where nnnn is a number less than 100 (which implies a limit of utmost 100
12934  inline assembler labels
12935 \emph on
12936 per function
12937 \emph default
12938 \noun on
12939 )
12940 \noun default
12941 .
12942
12943 \layout Verse
12944
12945
12946 \family typewriter
12947 _asm
12948 \begin_inset LatexCommand \index{\_asm}
12949
12950 \end_inset
12951
12952
12953 \begin_inset LatexCommand \index{\_\_asm}
12954
12955 \end_inset
12956
12957
12958 \newline
12959 \SpecialChar ~
12960 \SpecialChar ~
12961 \SpecialChar ~
12962 \SpecialChar ~
12963 mov\SpecialChar ~
12964 \SpecialChar ~
12965 \SpecialChar ~
12966 \SpecialChar ~
12967 \SpecialChar ~
12968 b,#10
12969 \newline
12970 00001$:
12971 \newline
12972 \SpecialChar ~
12973 \SpecialChar ~
12974 \SpecialChar ~
12975 \SpecialChar ~
12976 djnz\SpecialChar ~
12977 \SpecialChar ~
12978 \SpecialChar ~
12979 \SpecialChar ~
12980 b,00001$
12981 \newline
12982 _endasm
12983 \begin_inset LatexCommand \index{\_endasm}
12984
12985 \end_inset
12986
12987
12988 \begin_inset LatexCommand \index{\_\_endasm}
12989
12990 \end_inset
12991
12992  ;
12993 \layout Standard
12994
12995 Inline assembler code cannot reference any C-Labels, however it can reference
12996  labels
12997 \begin_inset LatexCommand \index{Labels}
12998
12999 \end_inset
13000
13001  defined by the inline assembler, e.g.:
13002 \layout Verse
13003
13004
13005 \family typewriter
13006 foo() {
13007 \newline
13008 \SpecialChar ~
13009 \SpecialChar ~
13010 \SpecialChar ~
13011 \SpecialChar ~
13012 /* some c code */
13013 \newline
13014 \SpecialChar ~
13015 \SpecialChar ~
13016 \SpecialChar ~
13017 \SpecialChar ~
13018 _asm
13019 \newline
13020 \SpecialChar ~
13021 \SpecialChar ~
13022 \SpecialChar ~
13023 \SpecialChar ~
13024 \SpecialChar ~
13025 \SpecialChar ~
13026 ; some assembler code
13027 \newline
13028 \SpecialChar ~
13029 \SpecialChar ~
13030 \SpecialChar ~
13031 \SpecialChar ~
13032 \SpecialChar ~
13033 \SpecialChar ~
13034 ljmp $0003
13035 \newline
13036 \SpecialChar ~
13037 \SpecialChar ~
13038 \SpecialChar ~
13039 \SpecialChar ~
13040 _endasm;
13041 \newline
13042 \SpecialChar ~
13043 \SpecialChar ~
13044 \SpecialChar ~
13045 \SpecialChar ~
13046 /* some more c code */
13047 \newline
13048 clabel:\SpecialChar ~
13049 \SpecialChar ~
13050 /* inline assembler cannot reference this label */
13051 \newline
13052 \SpecialChar ~
13053 \SpecialChar ~
13054 \SpecialChar ~
13055 \SpecialChar ~
13056 _asm
13057 \newline
13058 \SpecialChar ~
13059 \SpecialChar ~
13060 \SpecialChar ~
13061 \SpecialChar ~
13062 $0003: ;label (can be referenced by inline assembler only)
13063 \newline
13064 \SpecialChar ~
13065 \SpecialChar ~
13066 \SpecialChar ~
13067 \SpecialChar ~
13068 _endasm
13069 \begin_inset LatexCommand \index{\_endasm}
13070
13071 \end_inset
13072
13073
13074 \begin_inset LatexCommand \index{\_\_endasm}
13075
13076 \end_inset
13077
13078  ;
13079 \newline
13080 \SpecialChar ~
13081 \SpecialChar ~
13082 \SpecialChar ~
13083 \SpecialChar ~
13084 /* some more c code */
13085 \newline
13086 }
13087 \layout Standard
13088
13089 In other words inline assembly code can access labels defined in inline
13090  assembly within the scope of the function.
13091  The same goes the other way, i.e.
13092  labels defines in inline assembly can not be accessed by C statements.
13093 \layout Section
13094
13095 Interfacing with Assembler Code
13096 \begin_inset LatexCommand \index{Assembler routines}
13097
13098 \end_inset
13099
13100
13101 \layout Subsection
13102
13103 Global Registers used for Parameter Passing
13104 \begin_inset LatexCommand \index{Parameter passing}
13105
13106 \end_inset
13107
13108
13109 \layout Standard
13110
13111 The compiler always uses the global registers
13112 \emph on
13113 DPL, DPH
13114 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
13115
13116 \end_inset
13117
13118
13119 \begin_inset LatexCommand \index{DPTR}
13120
13121 \end_inset
13122
13123 , B
13124 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
13125
13126 \end_inset
13127
13128
13129 \emph default
13130 and
13131 \emph on
13132  ACC
13133 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
13134
13135 \end_inset
13136
13137
13138 \emph default
13139  to pass the first parameter to a routine.
13140  The second parameter onwards is either allocated on the stack (for reentrant
13141  routines or if -
13142 \begin_inset ERT
13143 status Collapsed
13144
13145 \layout Standard
13146
13147 \backslash
13148 /
13149 \end_inset
13150
13151 -stack-auto is used) or in data / xdata memory (depending on the memory
13152  model).
13153
13154 \layout Subsection
13155
13156 Assembler Routine (non-reentrant)
13157 \layout Standard
13158
13159 In the following example
13160 \begin_inset LatexCommand \index{reentrant}
13161
13162 \end_inset
13163
13164
13165 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
13166
13167 \end_inset
13168
13169  the function c_func calls an assembler routine asm_func, which takes two
13170  parameters
13171 \begin_inset LatexCommand \index{function parameter}
13172
13173 \end_inset
13174
13175 .
13176 \layout Verse
13177
13178
13179 \family typewriter
13180 extern int asm_func(unsigned char, unsigned char);
13181 \newline
13182
13183 \newline
13184 int c_func (unsigned char i, unsigned char j)
13185 \newline
13186 {
13187 \newline
13188 \SpecialChar ~
13189 \SpecialChar ~
13190 \SpecialChar ~
13191 \SpecialChar ~
13192 return asm_func(i,j);
13193 \newline
13194 }
13195 \newline
13196
13197 \newline
13198 int main()
13199 \newline
13200 {
13201 \newline
13202 \SpecialChar ~
13203 \SpecialChar ~
13204 \SpecialChar ~
13205 \SpecialChar ~
13206 return c_func(10,9);
13207 \newline
13208 }
13209 \layout Standard
13210
13211 The corresponding assembler function is:
13212 \layout Verse
13213
13214
13215 \family typewriter
13216 .globl _asm_func_PARM_2
13217 \newline
13218 \SpecialChar ~
13219 \SpecialChar ~
13220 \SpecialChar ~
13221 \SpecialChar ~
13222 \SpecialChar ~
13223 \SpecialChar ~
13224 \SpecialChar ~
13225 \SpecialChar ~
13226 .globl _asm_func
13227 \newline
13228 \SpecialChar ~
13229 \SpecialChar ~
13230 \SpecialChar ~
13231 \SpecialChar ~
13232 \SpecialChar ~
13233 \SpecialChar ~
13234 \SpecialChar ~
13235 \SpecialChar ~
13236 .area OSEG
13237 \newline
13238 _asm_func_PARM_2:
13239 \newline
13240 \SpecialChar ~
13241 \SpecialChar ~
13242 \SpecialChar ~
13243 \SpecialChar ~
13244 \SpecialChar ~
13245 \SpecialChar ~
13246 \SpecialChar ~
13247 \SpecialChar ~
13248 .ds    1
13249 \newline
13250 \SpecialChar ~
13251 \SpecialChar ~
13252 \SpecialChar ~
13253 \SpecialChar ~
13254 \SpecialChar ~
13255 \SpecialChar ~
13256 \SpecialChar ~
13257 \SpecialChar ~
13258 .area CSEG
13259 \newline
13260 _asm_func:
13261 \newline
13262 \SpecialChar ~
13263 \SpecialChar ~
13264 \SpecialChar ~
13265 \SpecialChar ~
13266 \SpecialChar ~
13267 \SpecialChar ~
13268 \SpecialChar ~
13269 \SpecialChar ~
13270 mov\SpecialChar ~
13271 \SpecialChar ~
13272 \SpecialChar ~
13273 \SpecialChar ~
13274 a,dpl
13275 \newline
13276 \SpecialChar ~
13277 \SpecialChar ~
13278 \SpecialChar ~
13279 \SpecialChar ~
13280 \SpecialChar ~
13281 \SpecialChar ~
13282 \SpecialChar ~
13283 \SpecialChar ~
13284 add\SpecialChar ~
13285 \SpecialChar ~
13286 \SpecialChar ~
13287 \SpecialChar ~
13288 a,_asm_func_PARM_2
13289 \newline
13290 \SpecialChar ~
13291 \SpecialChar ~
13292 \SpecialChar ~
13293 \SpecialChar ~
13294 \SpecialChar ~
13295 \SpecialChar ~
13296 \SpecialChar ~
13297 \SpecialChar ~
13298 mov\SpecialChar ~
13299 \SpecialChar ~
13300 \SpecialChar ~
13301 \SpecialChar ~
13302 dpl,a
13303 \newline
13304 \SpecialChar ~
13305 \SpecialChar ~
13306 \SpecialChar ~
13307 \SpecialChar ~
13308 \SpecialChar ~
13309 \SpecialChar ~
13310 \SpecialChar ~
13311 \SpecialChar ~
13312 mov\SpecialChar ~
13313 \SpecialChar ~
13314 \SpecialChar ~
13315 \SpecialChar ~
13316 dph
13317 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
13318
13319 \end_inset
13320
13321 ,#0x00
13322 \newline
13323 \SpecialChar ~
13324 \SpecialChar ~
13325 \SpecialChar ~
13326 \SpecialChar ~
13327 \SpecialChar ~
13328 \SpecialChar ~
13329 \SpecialChar ~
13330 \SpecialChar ~
13331 ret
13332 \layout Standard
13333
13334 Note here that the return values
13335 \begin_inset LatexCommand \index{return value}
13336
13337 \end_inset
13338
13339  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
13340  two byte values.
13341  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
13342 b' & 'acc' for four byte values.
13343 \layout Standard
13344
13345 The parameter naming convention is _<function_name>_PARM_<n>, where n is
13346  the parameter number starting from 1, and counting from the left.
13347  The first parameter is passed in
13348 \begin_inset Quotes eld
13349 \end_inset
13350
13351 dpl
13352 \begin_inset Quotes erd
13353 \end_inset
13354
13355  for a one byte parameter,
13356 \begin_inset Quotes eld
13357 \end_inset
13358
13359 dptr
13360 \begin_inset Quotes erd
13361 \end_inset
13362
13363  for two bytes,
13364 \begin_inset Quotes eld
13365 \end_inset
13366
13367 b,dptr
13368 \begin_inset Quotes erd
13369 \end_inset
13370
13371  for three bytes and
13372 \begin_inset Quotes eld
13373 \end_inset
13374
13375 acc,b,dptr
13376 \begin_inset Quotes erd
13377 \end_inset
13378
13379  for a four bytes parameter.
13380  The variable name for the second parameter will be _<function_name>_PARM_2.
13381 \newline
13382
13383 \newline
13384 Assemble the assembler routine with the following command:
13385 \newline
13386
13387 \newline
13388
13389 \family sans
13390 \series bold
13391 asx8051 -losg asmfunc.asm
13392 \newline
13393
13394 \newline
13395
13396 \family default
13397 \series default
13398 Then compile and link the assembler routine to the C source file with the
13399  following command:
13400 \newline
13401
13402 \newline
13403
13404 \family sans
13405 \series bold
13406 sdcc cfunc.c asmfunc.rel
13407 \layout Subsection
13408
13409 Assembler Routine (reentrant)
13410 \layout Standard
13411
13412 In this case
13413 \begin_inset LatexCommand \index{reentrant}
13414
13415 \end_inset
13416
13417
13418 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
13419
13420 \end_inset
13421
13422  the second parameter
13423 \begin_inset LatexCommand \index{function parameter}
13424
13425 \end_inset
13426
13427  onwards will be passed on the stack, the parameters are pushed from right
13428  to left i.e.
13429  after the call the leftmost parameter will be on the top of the stack.
13430  Here is an example:
13431 \layout Verse
13432
13433
13434 \family typewriter
13435 extern int asm_func(unsigned char, unsigned char);
13436 \newline
13437
13438 \newline
13439 int c_func (unsigned char i, unsigned char j) reentrant
13440 \newline
13441 {
13442 \newline
13443 \SpecialChar ~
13444 \SpecialChar ~
13445 \SpecialChar ~
13446 \SpecialChar ~
13447 return asm_func(i,j);
13448 \newline
13449 }
13450 \newline
13451
13452 \newline
13453 int main()
13454 \newline
13455 {
13456 \newline
13457 \SpecialChar ~
13458 \SpecialChar ~
13459 \SpecialChar ~
13460 \SpecialChar ~
13461 return c_func(10,9);
13462 \newline
13463 }
13464 \layout Standard
13465
13466 The corresponding assembler routine is:
13467 \layout Verse
13468
13469
13470 \family typewriter
13471 .globl _asm_func
13472 \newline
13473 _asm_func:
13474 \newline
13475 \SpecialChar ~
13476 \SpecialChar ~
13477 \SpecialChar ~
13478 \SpecialChar ~
13479 push  _bp
13480 \newline
13481 \SpecialChar ~
13482 \SpecialChar ~
13483 \SpecialChar ~
13484 \SpecialChar ~
13485 mov _bp,sp
13486 \newline
13487 \SpecialChar ~
13488 \SpecialChar ~
13489 \SpecialChar ~
13490 \SpecialChar ~
13491 mov r2,dpl
13492 \newline
13493 \SpecialChar ~
13494 \SpecialChar ~
13495 \SpecialChar ~
13496 \SpecialChar ~
13497 mov a,_bp
13498 \newline
13499 \SpecialChar ~
13500 \SpecialChar ~
13501 \SpecialChar ~
13502 \SpecialChar ~
13503 add a,#0xfd
13504 \newline
13505 \SpecialChar ~
13506 \SpecialChar ~
13507 \SpecialChar ~
13508 \SpecialChar ~
13509 mov r0,a
13510 \newline
13511 \SpecialChar ~
13512 \SpecialChar ~
13513 \SpecialChar ~
13514 \SpecialChar ~
13515 add  a,#0xfc ;?
13516 \newline
13517 \SpecialChar ~
13518 \SpecialChar ~
13519 \SpecialChar ~
13520 \SpecialChar ~
13521 mov  r1,a
13522 \newline
13523 \SpecialChar ~
13524 \SpecialChar ~
13525 \SpecialChar ~
13526 \SpecialChar ~
13527 mov  a,@r0
13528 \newline
13529 \SpecialChar ~
13530 \SpecialChar ~
13531 \SpecialChar ~
13532 \SpecialChar ~
13533 add  a,r2 ;?
13534 \newline
13535 \SpecialChar ~
13536 \SpecialChar ~
13537 \SpecialChar ~
13538 \SpecialChar ~
13539 mov  dpl,a
13540 \newline
13541 \SpecialChar ~
13542 \SpecialChar ~
13543 \SpecialChar ~
13544 \SpecialChar ~
13545 mov  dph,#0x00
13546 \newline
13547 \SpecialChar ~
13548 \SpecialChar ~
13549 \SpecialChar ~
13550 \SpecialChar ~
13551 mov  sp,_bp
13552 \newline
13553 \SpecialChar ~
13554 \SpecialChar ~
13555 \SpecialChar ~
13556 \SpecialChar ~
13557 pop  _bp
13558 \newline
13559 \SpecialChar ~
13560 \SpecialChar ~
13561 \SpecialChar ~
13562 \SpecialChar ~
13563 ret
13564 \layout Standard
13565
13566 The compiling and linking procedure remains the same, however note the extra
13567  entry & exit linkage required for the assembler code, _bp is the stack
13568  frame pointer and is used to compute the offset into the stack for parameters
13569  and local variables.
13570 \layout Section
13571
13572 int (16 bit)
13573 \begin_inset LatexCommand \index{int (16 bit)}
13574
13575 \end_inset
13576
13577  and long (32 bit)
13578 \begin_inset LatexCommand \index{long (32 bit)}
13579
13580 \end_inset
13581
13582  Support
13583 \layout Standard
13584
13585 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
13586  multiplication and modulus operations are implemented by support routines.
13587  These support routines are all developed in ANSI-C to facilitate porting
13588  to other MCUs, although some model specific assembler optimizations are
13589  used.
13590  The following files contain the described routines, all of them can be
13591  found in <installdir>/share/sdcc/lib.
13592 \newline
13593
13594 \layout Standard
13595 \align center
13596
13597 \begin_inset  Tabular
13598 <lyxtabular version="3" rows="11" columns="2">
13599 <features>
13600 <column alignment="center" valignment="top" leftline="true" width="0">
13601 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
13602 <row topline="true" bottomline="true">
13603 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13604 \begin_inset Text
13605
13606 \layout Standard
13607
13608
13609 \series bold
13610 Function
13611 \end_inset
13612 </cell>
13613 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13614 \begin_inset Text
13615
13616 \layout Standard
13617
13618
13619 \series bold
13620 Description
13621 \end_inset
13622 </cell>
13623 </row>
13624 <row topline="true">
13625 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13626 \begin_inset Text
13627
13628 \layout Standard
13629
13630 _mulint.c
13631 \end_inset
13632 </cell>
13633 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13634 \begin_inset Text
13635
13636 \layout Standard
13637
13638 16 bit multiplication
13639 \end_inset
13640 </cell>
13641 </row>
13642 <row topline="true">
13643 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13644 \begin_inset Text
13645
13646 \layout Standard
13647
13648 _divsint.c
13649 \end_inset
13650 </cell>
13651 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13652 \begin_inset Text
13653
13654 \layout Standard
13655
13656  signed 16 bit division (calls _divuint)
13657 \end_inset
13658 </cell>
13659 </row>
13660 <row topline="true">
13661 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13662 \begin_inset Text
13663
13664 \layout Standard
13665
13666 _divuint.c
13667 \end_inset
13668 </cell>
13669 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13670 \begin_inset Text
13671
13672 \layout Standard
13673
13674  unsigned 16 bit division
13675 \end_inset
13676 </cell>
13677 </row>
13678 <row topline="true">
13679 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13680 \begin_inset Text
13681
13682 \layout Standard
13683
13684 _modsint.c
13685 \end_inset
13686 </cell>
13687 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13688 \begin_inset Text
13689
13690 \layout Standard
13691
13692 signed 16 bit modulus (calls _moduint)
13693 \end_inset
13694 </cell>
13695 </row>
13696 <row topline="true">
13697 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13698 \begin_inset Text
13699
13700 \layout Standard
13701
13702 _moduint.c
13703 \end_inset
13704 </cell>
13705 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13706 \begin_inset Text
13707
13708 \layout Standard
13709
13710 unsigned 16 bit modulus
13711 \end_inset
13712 </cell>
13713 </row>
13714 <row topline="true">
13715 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13716 \begin_inset Text
13717
13718 \layout Standard
13719
13720 _mullong.c
13721 \end_inset
13722 </cell>
13723 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13724 \begin_inset Text
13725
13726 \layout Standard
13727
13728 32 bit multiplication
13729 \end_inset
13730 </cell>
13731 </row>
13732 <row topline="true">
13733 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13734 \begin_inset Text
13735
13736 \layout Standard
13737
13738 _divslong.c
13739 \end_inset
13740 </cell>
13741 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13742 \begin_inset Text
13743
13744 \layout Standard
13745
13746  signed 32 division (calls _divulong)
13747 \end_inset
13748 </cell>
13749 </row>
13750 <row topline="true">
13751 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13752 \begin_inset Text
13753
13754 \layout Standard
13755
13756 _divulong.c
13757 \end_inset
13758 </cell>
13759 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13760 \begin_inset Text
13761
13762 \layout Standard
13763
13764 unsigned 32 division
13765 \end_inset
13766 </cell>
13767 </row>
13768 <row topline="true">
13769 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13770 \begin_inset Text
13771
13772 \layout Standard
13773
13774 _modslong.c
13775 \end_inset
13776 </cell>
13777 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13778 \begin_inset Text
13779
13780 \layout Standard
13781
13782  signed 32 bit modulus (calls _modulong)
13783 \end_inset
13784 </cell>
13785 </row>
13786 <row topline="true" bottomline="true">
13787 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13788 \begin_inset Text
13789
13790 \layout Standard
13791
13792 _modulong.c
13793 \end_inset
13794 </cell>
13795 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13796 \begin_inset Text
13797
13798 \layout Standard
13799
13800 unsigned 32 bit modulus
13801 \end_inset
13802 </cell>
13803 </row>
13804 </lyxtabular>
13805
13806 \end_inset
13807
13808
13809 \newline
13810
13811 \layout Standard
13812
13813 Since they are compiled as
13814 \emph on
13815 non-reentrant
13816 \emph default
13817
13818 \begin_inset LatexCommand \index{reentrant}
13819
13820 \end_inset
13821
13822 , interrupt
13823 \begin_inset LatexCommand \index{interrupt}
13824
13825 \end_inset
13826
13827  service routines should not do any of the above operations.
13828  If this is unavoidable then the above routines will need to be compiled
13829  with the
13830 \emph on
13831 -
13832 \begin_inset ERT
13833 status Collapsed
13834
13835 \layout Standard
13836
13837 \backslash
13838 /
13839 \end_inset
13840
13841 -stack-auto
13842 \begin_inset LatexCommand \index{-\/-stack-auto}
13843
13844 \end_inset
13845
13846
13847 \emph default
13848  option, after which the source program will have to be compiled with
13849 \emph on
13850 -
13851 \begin_inset ERT
13852 status Collapsed
13853
13854 \layout Standard
13855
13856 \backslash
13857 /
13858 \end_inset
13859
13860 -int-long-reent
13861 \begin_inset LatexCommand \index{-\/-int-long-reent}
13862
13863 \end_inset
13864
13865
13866 \emph default
13867  option.
13868  Notice that you don't have to call these routines directly.
13869  The compiler will use them automatically every time an integer operation
13870  is required.
13871 \layout Section
13872
13873 Floating Point Support
13874 \begin_inset LatexCommand \index{Floating point support}
13875
13876 \end_inset
13877
13878
13879 \layout Standard
13880
13881 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
13882  floating point support routines are derived from gcc's floatlib.c and consist
13883  of the following routines:
13884 \newline
13885
13886 \layout Standard
13887 \align center
13888
13889 \size footnotesize
13890
13891 \begin_inset  Tabular
13892 <lyxtabular version="3" rows="17" columns="2">
13893 <features>
13894 <column alignment="center" valignment="top" leftline="true" width="0">
13895 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
13896 <row topline="true" bottomline="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 Function
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 Description
13920 \end_inset
13921 </cell>
13922 </row>
13923 <row topline="true">
13924 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13925 \begin_inset Text
13926
13927 \layout Standard
13928
13929
13930 \family roman
13931 \series medium
13932 \shape up
13933 \size normal
13934 \emph off
13935 \bar no
13936 \noun off
13937 \color none
13938 _fsadd.c
13939 \end_inset
13940 </cell>
13941 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13942 \begin_inset Text
13943
13944 \layout Standard
13945
13946
13947 \family roman
13948 \series medium
13949 \shape up
13950 \size normal
13951 \emph off
13952 \bar no
13953 \noun off
13954 \color none
13955 add floating point numbers
13956 \end_inset
13957 </cell>
13958 </row>
13959 <row topline="true">
13960 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13961 \begin_inset Text
13962
13963 \layout Standard
13964
13965
13966 \family roman
13967 \series medium
13968 \shape up
13969 \size normal
13970 \emph off
13971 \bar no
13972 \noun off
13973 \color none
13974 _fssub.c
13975 \end_inset
13976 </cell>
13977 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13978 \begin_inset Text
13979
13980 \layout Standard
13981
13982
13983 \family roman
13984 \series medium
13985 \shape up
13986 \size normal
13987 \emph off
13988 \bar no
13989 \noun off
13990 \color none
13991 subtract floating point numbers
13992 \end_inset
13993 </cell>
13994 </row>
13995 <row topline="true">
13996 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13997 \begin_inset Text
13998
13999 \layout Standard
14000
14001
14002 \family roman
14003 \series medium
14004 \shape up
14005 \size normal
14006 \emph off
14007 \bar no
14008 \noun off
14009 \color none
14010 _fsdiv.c
14011 \end_inset
14012 </cell>
14013 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14014 \begin_inset Text
14015
14016 \layout Standard
14017
14018
14019 \family roman
14020 \series medium
14021 \shape up
14022 \size normal
14023 \emph off
14024 \bar no
14025 \noun off
14026 \color none
14027 divide floating point numbers
14028 \end_inset
14029 </cell>
14030 </row>
14031 <row topline="true">
14032 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14033 \begin_inset Text
14034
14035 \layout Standard
14036
14037
14038 \family roman
14039 \series medium
14040 \shape up
14041 \size normal
14042 \emph off
14043 \bar no
14044 \noun off
14045 \color none
14046 _fsmul.c
14047 \end_inset
14048 </cell>
14049 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14050 \begin_inset Text
14051
14052 \layout Standard
14053
14054
14055 \family roman
14056 \series medium
14057 \shape up
14058 \size normal
14059 \emph off
14060 \bar no
14061 \noun off
14062 \color none
14063 multiply floating point numbers
14064 \end_inset
14065 </cell>
14066 </row>
14067 <row topline="true">
14068 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14069 \begin_inset Text
14070
14071 \layout Standard
14072
14073
14074 \family roman
14075 \series medium
14076 \shape up
14077 \size normal
14078 \emph off
14079 \bar no
14080 \noun off
14081 \color none
14082 _fs2uchar.c
14083 \end_inset
14084 </cell>
14085 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14086 \begin_inset Text
14087
14088 \layout Standard
14089
14090
14091 \family roman
14092 \series medium
14093 \shape up
14094 \size normal
14095 \emph off
14096 \bar no
14097 \noun off
14098 \color none
14099 convert floating point to unsigned char
14100 \end_inset
14101 </cell>
14102 </row>
14103 <row topline="true">
14104 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14105 \begin_inset Text
14106
14107 \layout Standard
14108
14109
14110 \family roman
14111 \series medium
14112 \shape up
14113 \size normal
14114 \emph off
14115 \bar no
14116 \noun off
14117 \color none
14118 _fs2char.c
14119 \end_inset
14120 </cell>
14121 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14122 \begin_inset Text
14123
14124 \layout Standard
14125
14126
14127 \family roman
14128 \series medium
14129 \shape up
14130 \size normal
14131 \emph off
14132 \bar no
14133 \noun off
14134 \color none
14135 convert floating point to signed char
14136 \end_inset
14137 </cell>
14138 </row>
14139 <row topline="true">
14140 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14141 \begin_inset Text
14142
14143 \layout Standard
14144
14145
14146 \family roman
14147 \series medium
14148 \shape up
14149 \size normal
14150 \emph off
14151 \bar no
14152 \noun off
14153 \color none
14154 _fs2uint.c
14155 \end_inset
14156 </cell>
14157 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14158 \begin_inset Text
14159
14160 \layout Standard
14161
14162
14163 \family roman
14164 \series medium
14165 \shape up
14166 \size normal
14167 \emph off
14168 \bar no
14169 \noun off
14170 \color none
14171 convert floating point to unsigned int
14172 \end_inset
14173 </cell>
14174 </row>
14175 <row topline="true">
14176 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14177 \begin_inset Text
14178
14179 \layout Standard
14180
14181
14182 \family roman
14183 \series medium
14184 \shape up
14185 \size normal
14186 \emph off
14187 \bar no
14188 \noun off
14189 \color none
14190 _fs2int.c
14191 \end_inset
14192 </cell>
14193 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14194 \begin_inset Text
14195
14196 \layout Standard
14197
14198
14199 \family roman
14200 \series medium
14201 \shape up
14202 \size normal
14203 \emph off
14204 \bar no
14205 \noun off
14206 \color none
14207 convert floating point to signed int
14208 \end_inset
14209 </cell>
14210 </row>
14211 <row topline="true">
14212 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14213 \begin_inset Text
14214
14215 \layout Standard
14216
14217
14218 \family roman
14219 \series medium
14220 \shape up
14221 \size normal
14222 \emph off
14223 \bar no
14224 \noun off
14225 \color none
14226 _fs2ulong.
14227 \family default
14228 \series default
14229 \shape default
14230 \size default
14231 \emph default
14232 \bar default
14233 \noun default
14234 \color default
14235 c
14236 \end_inset
14237 </cell>
14238 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14239 \begin_inset Text
14240
14241 \layout Standard
14242
14243
14244 \family roman
14245 \series medium
14246 \shape up
14247 \size normal
14248 \emph off
14249 \bar no
14250 \noun off
14251 \color none
14252 convert floating point to unsigned long
14253 \end_inset
14254 </cell>
14255 </row>
14256 <row topline="true">
14257 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14258 \begin_inset Text
14259
14260 \layout Standard
14261
14262
14263 \family roman
14264 \series medium
14265 \shape up
14266 \size normal
14267 \emph off
14268 \bar no
14269 \noun off
14270 \color none
14271 _fs2long.c
14272 \end_inset
14273 </cell>
14274 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14275 \begin_inset Text
14276
14277 \layout Standard
14278
14279
14280 \family roman
14281 \series medium
14282 \shape up
14283 \size normal
14284 \emph off
14285 \bar no
14286 \noun off
14287 \color none
14288 convert floating point to signed long
14289 \end_inset
14290 </cell>
14291 </row>
14292 <row topline="true">
14293 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14294 \begin_inset Text
14295
14296 \layout Standard
14297
14298
14299 \family roman
14300 \series medium
14301 \shape up
14302 \size normal
14303 \emph off
14304 \bar no
14305 \noun off
14306 \color none
14307 _uchar2fs.c
14308 \end_inset
14309 </cell>
14310 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14311 \begin_inset Text
14312
14313 \layout Standard
14314
14315
14316 \family roman
14317 \series medium
14318 \shape up
14319 \size normal
14320 \emph off
14321 \bar no
14322 \noun off
14323 \color none
14324 convert unsigned char to floating point
14325 \end_inset
14326 </cell>
14327 </row>
14328 <row topline="true">
14329 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14330 \begin_inset Text
14331
14332 \layout Standard
14333
14334
14335 \family roman
14336 \series medium
14337 \shape up
14338 \size normal
14339 \emph off
14340 \bar no
14341 \noun off
14342 \color none
14343 _char2fs.c
14344 \end_inset
14345 </cell>
14346 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14347 \begin_inset Text
14348
14349 \layout Standard
14350
14351
14352 \family roman
14353 \series medium
14354 \shape up
14355 \size normal
14356 \emph off
14357 \bar no
14358 \noun off
14359 \color none
14360 convert char to floating point number
14361 \end_inset
14362 </cell>
14363 </row>
14364 <row topline="true">
14365 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14366 \begin_inset Text
14367
14368 \layout Standard
14369
14370
14371 \family roman
14372 \series medium
14373 \shape up
14374 \size normal
14375 \emph off
14376 \bar no
14377 \noun off
14378 \color none
14379 _uint2fs.c
14380 \end_inset
14381 </cell>
14382 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14383 \begin_inset Text
14384
14385 \layout Standard
14386
14387
14388 \family roman
14389 \series medium
14390 \shape up
14391 \size normal
14392 \emph off
14393 \bar no
14394 \noun off
14395 \color none
14396 convert unsigned int to floating point
14397 \end_inset
14398 </cell>
14399 </row>
14400 <row topline="true">
14401 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14402 \begin_inset Text
14403
14404 \layout Standard
14405
14406
14407 \family roman
14408 \series medium
14409 \shape up
14410 \size normal
14411 \emph off
14412 \bar no
14413 \noun off
14414 \color none
14415 _int2fs.c
14416 \end_inset
14417 </cell>
14418 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14419 \begin_inset Text
14420
14421 \layout Standard
14422
14423
14424 \family roman
14425 \series medium
14426 \shape up
14427 \size normal
14428 \emph off
14429 \bar no
14430 \noun off
14431 \color none
14432 convert int to floating point numbers
14433 \end_inset
14434 </cell>
14435 </row>
14436 <row topline="true">
14437 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14438 \begin_inset Text
14439
14440 \layout Standard
14441
14442
14443 \family roman
14444 \series medium
14445 \shape up
14446 \size normal
14447 \emph off
14448 \bar no
14449 \noun off
14450 \color none
14451 _ulong2fs.c
14452 \end_inset
14453 </cell>
14454 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14455 \begin_inset Text
14456
14457 \layout Standard
14458
14459
14460 \family roman
14461 \series medium
14462 \shape up
14463 \size normal
14464 \emph off
14465 \bar no
14466 \noun off
14467 \color none
14468 convert unsigned long to floating point number
14469 \end_inset
14470 </cell>
14471 </row>
14472 <row topline="true" bottomline="true">
14473 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14474 \begin_inset Text
14475
14476 \layout Standard
14477
14478
14479 \family roman
14480 \series medium
14481 \shape up
14482 \size normal
14483 \emph off
14484 \bar no
14485 \noun off
14486 \color none
14487 _long2fs.c
14488 \end_inset
14489 </cell>
14490 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14491 \begin_inset Text
14492
14493 \layout Standard
14494
14495
14496 \family roman
14497 \series medium
14498 \shape up
14499 \size normal
14500 \emph off
14501 \bar no
14502 \noun off
14503 \color none
14504 convert long to floating point number
14505 \end_inset
14506 </cell>
14507 </row>
14508 </lyxtabular>
14509
14510 \end_inset
14511
14512
14513 \newline
14514
14515 \layout Standard
14516
14517 These support routines are developed in ANSI-C so there is room for space
14518  and speed improvement
14519 \begin_inset Foot
14520 collapsed false
14521
14522 \layout Standard
14523
14524 The floating point routines for the mcs51 are implemented in assembler
14525 \end_inset
14526
14527 .
14528  Note if all these routines are used simultaneously the data space might
14529  overflow.
14530  For serious floating point usage the large model might be needed.
14531  Also notice that you don't have to call this routines directly.
14532  The compiler will use them automatically every time a floating point operation
14533  is required.
14534 \layout Section
14535
14536 Library Routines
14537 \begin_inset LatexCommand \index{Libraries}
14538
14539 \end_inset
14540
14541
14542 \layout Standard
14543
14544
14545 \emph on
14546 <pending: this is messy and incomplete - a little more information is in
14547  sdcc/doc/libdoc.txt
14548 \emph default
14549  >
14550 \layout Subsection
14551
14552 Compiler support routines (_gptrget, _mulint etc.)
14553 \layout Subsection
14554
14555 Stdclib functions (puts, printf, strcat etc.)
14556 \layout Subsubsection
14557
14558 <stdio.h>
14559 \layout Standard
14560
14561
14562 \begin_inset LatexCommand \index{<stdio.h>}
14563
14564 \end_inset
14565
14566 As usual on embedded systems you have to provide your own
14567 \family typewriter
14568 getchar()
14569 \begin_inset LatexCommand \index{getchar()}
14570
14571 \end_inset
14572
14573
14574 \family default
14575 and
14576 \family typewriter
14577 putchar()
14578 \begin_inset LatexCommand \index{putchar()}
14579
14580 \end_inset
14581
14582
14583 \family default
14584  routines.
14585  SDCC does not know whether the system connects to a serial line with or
14586  without handshake, LCD, keyboard or other device.
14587  You'll find examples for serial routines f.e.
14588  in sdcc/device/lib.
14589 \layout Standard
14590
14591 The default
14592 \family typewriter
14593  printf()
14594 \begin_inset LatexCommand \index{printf()}
14595
14596 \end_inset
14597
14598
14599 \family default
14600 implementation in
14601 \family typewriter
14602  printf_large.c
14603 \family default
14604  does not support float (except on ds390).
14605  To enable this recompile it with the option
14606 \emph on
14607 -
14608 \begin_inset ERT
14609 status Collapsed
14610
14611 \layout Standard
14612
14613 \backslash
14614 /
14615 \end_inset
14616
14617 DUSE_FLOATS=1
14618 \begin_inset LatexCommand \index{USE\_FLOATS}
14619
14620 \end_inset
14621
14622
14623 \emph default
14624  on the command line.
14625  Use
14626 \emph on
14627 -
14628 \begin_inset ERT
14629 status Collapsed
14630
14631 \layout Standard
14632
14633 \backslash
14634 /
14635 \end_inset
14636
14637 -model-large
14638 \begin_inset LatexCommand \index{-\/-model-large}
14639
14640 \end_inset
14641
14642
14643 \emph default
14644  for the mcs51 port, since this uses a lot of memory.
14645 \layout Standard
14646
14647 If you're short on memory you might want to use
14648 \family typewriter
14649 printf_small()
14650 \begin_inset LatexCommand \index{printf\_small()}
14651
14652 \end_inset
14653
14654
14655 \family default
14656
14657 \emph on
14658 instead
14659 \emph default
14660  of
14661 \family typewriter
14662  printf().
14663
14664 \family default
14665  For the mcs51 there additionally are assembly versions
14666 \family typewriter
14667 printf_tiny()
14668 \begin_inset LatexCommand \index{printf\_tiny() (mcs51)}
14669
14670 \end_inset
14671
14672
14673 \family default
14674  and
14675 \family typewriter
14676 printf_fast()
14677 \begin_inset LatexCommand \index{printf\_fast() (mcs51)}
14678
14679 \end_inset
14680
14681
14682 \family default
14683 and
14684 \family typewriter
14685  printf_fast_f()
14686 \begin_inset LatexCommand \index{printf\_fast\_f() (mcs51)}
14687
14688 \end_inset
14689
14690
14691 \family default
14692  which should fit the requirements of many embedded systems (printf_fast()
14693  can be customized by unsetting #defines to
14694 \emph on
14695 not
14696 \emph default
14697  support long variables and field widths).
14698 \layout Subsection
14699
14700 Math functions (sin, pow, sqrt etc.)
14701 \layout Subsection
14702
14703 Other libraries
14704 \layout Standard
14705
14706 Libraries
14707 \begin_inset LatexCommand \index{Libraries}
14708
14709 \end_inset
14710
14711  included in SDCC should have a license at least as liberal as the GNU Lesser
14712  General Public License
14713 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
14714
14715 \end_inset
14716
14717
14718 \emph on
14719 LGPL
14720 \emph default
14721 .
14722 \layout Comment
14723
14724 license statements for the libraries are missing.
14725  sdcc/device/lib/ser_ir.c
14726 \layout Comment
14727
14728 or _decdptr f.e.
14729  come with a GPL (as opposed to LGPL) License - this will not be liberal
14730  enough for many embedded programmers.
14731 \layout Standard
14732
14733 If you have ported some library or want to share experience about some code
14734  which f.e.
14735  falls into any of these categories Busses (I
14736 \begin_inset Formula $^{\textrm{2}}$
14737 \end_inset
14738
14739 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
14740  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
14741  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
14742 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
14743
14744 \end_inset
14745
14746 \SpecialChar ~
14747 would certainly like to hear about it.
14748  Programmers coding for embedded systems are not especially famous for being
14749  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
14750 e these references are very valuable.
14751  Let's help to create a climate where information is shared.
14752 \layout Section
14753
14754 Memory Models
14755 \layout Subsection
14756
14757 MCS51 Memory Models
14758 \begin_inset LatexCommand \index{Memory model}
14759
14760 \end_inset
14761
14762
14763 \begin_inset LatexCommand \index{MCS51 memory model}
14764
14765 \end_inset
14766
14767
14768 \layout Subsubsection
14769
14770 Small, Medium and Large
14771 \layout Standard
14772
14773 SDCC allows three memory models for MCS51 code,
14774 \shape slanted
14775 small, medium
14776 \shape default
14777  and
14778 \shape slanted
14779 large
14780 \shape default
14781 .
14782  Modules compiled with different memory models should
14783 \emph on
14784 never
14785 \emph default
14786  be combined together or the results would be unpredictable.
14787  The library routines supplied with the compiler are compiled as small,
14788  medium and large.
14789  The compiled library modules are contained in separate directories as small,
14790  medium and large so that you can link to the appropriate set.
14791 \layout Standard
14792
14793 When the medium or large model is used all variables declared without a
14794  storage class will be allocated into the external ram, this includes all
14795  parameters and local variables (for non-reentrant
14796 \begin_inset LatexCommand \index{reentrant}
14797
14798 \end_inset
14799
14800  functions).
14801  When the small model is used variables without storage class are allocated
14802  in the internal ram.
14803 \layout Standard
14804
14805 Judicious usage of the processor specific storage classes
14806 \begin_inset LatexCommand \index{Storage class}
14807
14808 \end_inset
14809
14810  and the 'reentrant' function type will yield much more efficient code,
14811  than using the large model.
14812  Several optimizations are disabled when the program is compiled using the
14813  large model, it is therefore recommended that the small model be used unless
14814  absolutely required.
14815 \layout Subsubsection
14816
14817 External Stack
14818 \begin_inset LatexCommand \label{sub:External-Stack}
14819
14820 \end_inset
14821
14822
14823 \begin_inset LatexCommand \index{stack}
14824
14825 \end_inset
14826
14827
14828 \begin_inset LatexCommand \index{External stack (mcs51)}
14829
14830 \end_inset
14831
14832
14833 \layout Standard
14834
14835 The external stack (-
14836 \begin_inset ERT
14837 status Collapsed
14838
14839 \layout Standard
14840
14841 \backslash
14842 /
14843 \end_inset
14844
14845 -xstack option
14846 \begin_inset LatexCommand \index{-\/-xstack}
14847
14848 \end_inset
14849
14850 ) is located in pdata
14851 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
14852
14853 \end_inset
14854
14855  memory (usually at the start of the external ram segment) and uses all
14856  unused space in pdata (max.
14857  256 bytes).
14858  When -
14859 \begin_inset ERT
14860 status Collapsed
14861
14862 \layout Standard
14863
14864 \backslash
14865 /
14866 \end_inset
14867
14868 -xstack option is used to compile the program, the parameters and local
14869  variables
14870 \begin_inset LatexCommand \index{local variables}
14871
14872 \end_inset
14873
14874  of all reentrant functions are allocated in this area.
14875  This option is provided for programs with large stack space requirements.
14876  When used with the -
14877 \begin_inset ERT
14878 status Collapsed
14879
14880 \layout Standard
14881
14882 \backslash
14883 /
14884 \end_inset
14885
14886 -stack-auto
14887 \begin_inset LatexCommand \index{-\/-stack-auto}
14888
14889 \end_inset
14890
14891  option, all parameters and local variables are allocated on the external
14892  stack (note: support libraries will need to be recompiled with the same
14893  options.
14894  There is a predefined target in the library makefile).
14895 \layout Standard
14896
14897 The compiler outputs the higher order address byte of the external ram segment
14898  into port P2
14899 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
14900
14901 \end_inset
14902
14903  (see also section
14904 \begin_inset LatexCommand \ref{sub:MCS51-variants}
14905
14906 \end_inset
14907
14908 ), therefore when using the External Stack option, this port
14909 \emph on
14910 may not
14911 \emph default
14912  be used by the application program.
14913 \layout Subsection
14914
14915 DS390 Memory Model
14916 \begin_inset LatexCommand \index{Memory model}
14917
14918 \end_inset
14919
14920
14921 \begin_inset LatexCommand \index{DS390 memory model}
14922
14923 \end_inset
14924
14925
14926 \layout Standard
14927
14928 The only model supported is Flat 24
14929 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
14930
14931 \end_inset
14932
14933 .
14934  This generates code for the 24 bit contiguous addressing mode of the Dallas
14935  DS80C390 part.
14936  In this mode, up to four meg of external RAM or code space can be directly
14937  addressed.
14938  See the data sheets at www.dalsemi.com for further information on this part.
14939 \newline
14940
14941 \newline
14942 Note that the compiler does not generate any code to place the processor
14943  into 24 bitmode (although
14944 \emph on
14945 tinibios
14946 \emph default
14947  in the ds390 libraries will do that for you).
14948  If you don't use
14949 \emph on
14950 tinibios
14951 \emph default
14952
14953 \begin_inset LatexCommand \index{Tinibios (DS390)}
14954
14955 \end_inset
14956
14957 , the boot loader or similar code must ensure that the processor is in 24
14958  bit contiguous addressing mode before calling the SDCC startup code.
14959 \newline
14960
14961 \newline
14962 Like the
14963 \emph on
14964 -
14965 \begin_inset ERT
14966 status Collapsed
14967
14968 \layout Standard
14969
14970 \backslash
14971 /
14972 \end_inset
14973
14974 -model-large
14975 \emph default
14976  option, variables will by default be placed into the XDATA segment.
14977
14978 \newline
14979
14980 \newline
14981 Segments may be placed anywhere in the 4 meg address space using the usual
14982  -
14983 \begin_inset ERT
14984 status Collapsed
14985
14986 \layout Standard
14987
14988 \backslash
14989 /
14990 \end_inset
14991
14992 -*-loc options.
14993  Note that if any segments are located above 64K, the -r flag must be passed
14994  to the linker to generate the proper segment relocations, and the Intel
14995  HEX output format must be used.
14996  The -r flag can be passed to the linker by using the option
14997 \emph on
14998 -Wl-r
14999 \emph default
15000  on the SDCC command line.
15001  However, currently the linker can not handle code segments > 64k.
15002 \layout Section
15003
15004 Pragmas
15005 \begin_inset LatexCommand \index{Pragmas}
15006
15007 \end_inset
15008
15009
15010 \layout Standard
15011
15012 SDCC supports the following #pragma directives:
15013 \layout Itemize
15014
15015 save
15016 \begin_inset LatexCommand \index{\#pragma save}
15017
15018 \end_inset
15019
15020  - this will save all current options to the save/restore stack.
15021  See #pragma\SpecialChar ~
15022 restore.
15023 \layout Itemize
15024
15025 restore
15026 \begin_inset LatexCommand \index{\#pragma restore}
15027
15028 \end_inset
15029
15030  - will restore saved options from the last save.
15031  saves & restores can be nested.
15032  SDCC uses a save/restore stack: save pushes current options to the stack,
15033  restore pulls current options from the stack.
15034  See #pragma\SpecialChar ~
15035 save.
15036 \newline
15037
15038 \layout Itemize
15039
15040 callee_saves
15041 \begin_inset LatexCommand \index{\#pragma callee\_saves}
15042
15043 \end_inset
15044
15045
15046 \begin_inset LatexCommand \index{function prologue}
15047
15048 \end_inset
15049
15050  function1[,function2[,function3...]] - The compiler by default uses a caller
15051  saves convention for register saving across function calls, however this
15052  can cause unnecessary register pushing & popping
15053 \begin_inset LatexCommand \index{push/pop}
15054
15055 \end_inset
15056
15057  when calling small functions from larger functions.
15058  This option can be used to switch off the register saving convention for
15059  the function names specified.
15060  The compiler will not save registers when calling these functions, extra
15061  code need to be manually inserted at the entry & exit for these functions
15062  to save & restore the registers used by these functions, this can SUBSTANTIALLY
15063  reduce code & improve run time performance of the generated code.
15064  In the future the compiler (with inter procedural analysis) may be able
15065  to determine the appropriate scheme to use for each function call.
15066  If -
15067 \begin_inset ERT
15068 status Collapsed
15069
15070 \layout Standard
15071
15072 \backslash
15073 /
15074 \end_inset
15075
15076 -callee-saves command line option is used, the function names specified
15077  in #pragma\SpecialChar ~
15078 callee_saves
15079 \begin_inset LatexCommand \index{\#pragma callee\_saves}
15080
15081 \end_inset
15082
15083  is appended to the list of functions specified in the command line.
15084 \layout Itemize
15085
15086 exclude
15087 \begin_inset LatexCommand \index{\#pragma exclude}
15088
15089 \end_inset
15090
15091  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
15092  of pairs of push/pop
15093 \begin_inset LatexCommand \index{push/pop}
15094
15095 \end_inset
15096
15097  instructions in
15098 \emph on
15099 I
15100 \emph default
15101 nterrupt
15102 \begin_inset LatexCommand \index{interrupt}
15103
15104 \end_inset
15105
15106
15107 \emph on
15108 S
15109 \emph default
15110 ervice
15111 \emph on
15112 R
15113 \emph default
15114 outines.
15115  The directive should be placed immediately before the ISR function definition
15116  and it affects ALL ISR functions following it.
15117  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
15118 exclude\SpecialChar ~
15119 none
15120 \begin_inset LatexCommand \index{\#pragma exclude}
15121
15122 \end_inset
15123
15124 .
15125  See also the related keyword _naked
15126 \begin_inset LatexCommand \index{\_naked}
15127
15128 \end_inset
15129
15130
15131 \begin_inset LatexCommand \index{\_\_naked}
15132
15133 \end_inset
15134
15135 .
15136 \layout Itemize
15137
15138 less_pedantic
15139 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
15140
15141 \end_inset
15142
15143  - the compiler will not warn you anymore for obvious mistakes, you'r on
15144  your own now ;-(
15145 \layout Itemize
15146
15147 disable_warning <nnnn>
15148 \begin_inset LatexCommand \index{\#pragma disable\_warning}
15149
15150 \end_inset
15151
15152  - the compiler will not warn you anymore about warning number <nnnn>.
15153 \layout Itemize
15154
15155 nogcse
15156 \begin_inset LatexCommand \index{\#pragma nogcse}
15157
15158 \end_inset
15159
15160  - will stop global common subexpression elimination.
15161 \layout Itemize
15162
15163 noinduction
15164 \begin_inset LatexCommand \index{\#pragma noinduction}
15165
15166 \end_inset
15167
15168  - will stop loop induction optimizations.
15169 \layout Itemize
15170
15171 noinvariant
15172 \begin_inset LatexCommand \index{\#pragma noinvariant}
15173
15174 \end_inset
15175
15176  - will not do loop invariant optimizations.
15177  For more details see Loop Invariants in section
15178 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
15179
15180 \end_inset
15181
15182 .
15183 \layout Itemize
15184
15185 noiv
15186 \begin_inset LatexCommand \index{\#pragma noiv}
15187
15188 \end_inset
15189
15190  - Do not generate interrupt
15191 \begin_inset LatexCommand \index{interrupt}
15192
15193 \end_inset
15194
15195  vector table entries for all ISR functions defined after the pragma.
15196  This is useful in cases where the interrupt vector table must be defined
15197  manually, or when there is a secondary, manually defined interrupt vector
15198  table (e.g.
15199  for the autovector feature of the Cypress EZ-USB FX2).
15200  More elegantly this can be achieved by obmitting the optional interrupt
15201  number after the interrupt keyword, see section
15202 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
15203
15204 \end_inset
15205
15206 \SpecialChar ~
15207 about interrupts.
15208 \layout Itemize
15209
15210 nojtbound
15211 \begin_inset LatexCommand \index{\#pragma nojtbound}
15212
15213 \end_inset
15214
15215  - will not generate code for boundary value checking, when switch statements
15216  are turned into jump-tables (dangerous).
15217  For more details see section
15218 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
15219
15220 \end_inset
15221
15222 .
15223 \layout Itemize
15224
15225 noloopreverse
15226 \begin_inset LatexCommand \index{\#pragma noloopreverse}
15227
15228 \end_inset
15229
15230  - Will not do loop reversal optimization
15231 \layout Itemize
15232
15233 nooverlay
15234 \begin_inset LatexCommand \index{\#pragma nooverlay}
15235
15236 \end_inset
15237
15238  - the compiler will not overlay the parameters and local variables of a
15239  function.
15240 \layout Itemize
15241
15242 stackauto
15243 \begin_inset LatexCommand \index{\#pragma stackauto}
15244
15245 \end_inset
15246
15247 - See option -
15248 \begin_inset ERT
15249 status Collapsed
15250
15251 \layout Standard
15252
15253 \backslash
15254 /
15255 \end_inset
15256
15257 -stack-auto
15258 \begin_inset LatexCommand \index{-\/-stack-auto}
15259
15260 \end_inset
15261
15262  and section
15263 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
15264
15265 \end_inset
15266
15267  Parameters and Local Variables.
15268 \layout Itemize
15269
15270 opt_code_speed
15271 \begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
15272
15273 \end_inset
15274
15275 - The compiler will optimize code generation towards fast code, possibly
15276  at the expense of code size.
15277 \layout Itemize
15278
15279 opt_code_size
15280 \begin_inset LatexCommand \index{\#pragma opt\_code\_size}
15281
15282 \end_inset
15283
15284 - The compiler will optimize code generation towards compact code, possibly
15285  at the expense of code speed.
15286 \layout Itemize
15287
15288 opt_code_balanced
15289 \begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
15290
15291 \end_inset
15292
15293 - The compiler will attempt to generate code that is both compact and fast,
15294  as long as meeting one goal is not a detriment to the other (this is the
15295  default).
15296
15297 \layout Itemize
15298
15299 std_sdcc89
15300 \begin_inset LatexCommand \index{\#pragma std\_sdcc89}
15301
15302 \end_inset
15303
15304 - Generally follow the C89 standard, but allow SDCC features that conflict
15305  with the standard (default).
15306 \layout Itemize
15307
15308 std_c89
15309 \begin_inset LatexCommand \index{\#pragma std\_c89}
15310
15311 \end_inset
15312
15313 - Follow the C89 standard and disable SDCC features that conflict with the
15314  standard.
15315 \layout Itemize
15316
15317 std_sdcc99
15318 \begin_inset LatexCommand \index{\#pragma std\_sdcc99}
15319
15320 \end_inset
15321
15322 - Generally follow the C99 standard, but allow SDCC features that conflict
15323  with the standard (incomplete support).
15324 \layout Itemize
15325
15326 std_c99
15327 \begin_inset LatexCommand \index{\#pragma std\_c99}
15328
15329 \end_inset
15330
15331 - Follow the C99 standard and disable SDCC features that conflict with the
15332  standard (incomplete support).
15333 \layout Itemize
15334
15335 codeseg <name>
15336 \begin_inset LatexCommand \index{\#pragma codeseg}
15337
15338 \end_inset
15339
15340 - Use this name (max.
15341  8 characters) for the code segment.
15342 \layout Itemize
15343
15344 constseg <name>
15345 \begin_inset LatexCommand \index{\#pragma constseg}
15346
15347 \end_inset
15348
15349 - Use this name (max.
15350  8 characters) for the const segment.
15351 \layout Standard
15352
15353 SDCPP supports the following #pragma directives:
15354 \layout Itemize
15355
15356 preproc_asm
15357 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
15358
15359 \end_inset
15360
15361  (+ | -) - switch _asm _endasm block preprocessing on / off.
15362  Default is on.
15363 \layout Standard
15364
15365 The pragma's are intended to be used to turn-on or off certain optimizations
15366  which might cause the compiler to generate extra stack / data space to
15367  store compiler generated temporary variables.
15368  This usually happens in large functions.
15369  Pragma directives should be used as shown in the following example, they
15370  are used to control options & optimizations for a given function; pragmas
15371  should be placed before and/or after a function, placing pragma's inside
15372  a function body could have unpredictable results.
15373 \layout Verse
15374
15375
15376 \family typewriter
15377 #pragma save
15378 \begin_inset LatexCommand \index{\#pragma save}
15379
15380 \end_inset
15381
15382  \SpecialChar ~
15383 \SpecialChar ~
15384 \SpecialChar ~
15385 \SpecialChar ~
15386 \SpecialChar ~
15387 \SpecialChar ~
15388 \SpecialChar ~
15389 /* save the current settings */
15390 \newline
15391 #pragma nogcse
15392 \begin_inset LatexCommand \index{\#pragma nogcse}
15393
15394 \end_inset
15395
15396  \SpecialChar ~
15397 \SpecialChar ~
15398 \SpecialChar ~
15399 \SpecialChar ~
15400 \SpecialChar ~
15401 /* turnoff global subexpression elimination */
15402 \newline
15403 #pragma noinduction
15404 \begin_inset LatexCommand \index{\#pragma noinduction}
15405
15406 \end_inset
15407
15408  /* turn off induction optimizations */
15409 \newline
15410 int foo ()
15411 \newline
15412 {
15413 \newline
15414 \SpecialChar ~
15415  \SpecialChar ~
15416  ...
15417
15418 \newline
15419 \SpecialChar ~
15420  \SpecialChar ~
15421  /* large code */
15422 \newline
15423 \SpecialChar ~
15424  \SpecialChar ~
15425  ...
15426
15427 \newline
15428 }
15429 \newline
15430 #pragma restore
15431 \begin_inset LatexCommand \index{\#pragma restore}
15432
15433 \end_inset
15434
15435  /* turn the optimizations back on */
15436 \layout Standard
15437
15438 The compiler will generate a warning message when extra space is allocated.
15439  It is strongly recommended that the save and restore pragma's be used when
15440  changing options for a function.
15441 \layout Section
15442
15443 Defines Created by the Compiler
15444 \layout Standard
15445
15446 The compiler creates the following #defines
15447 \begin_inset LatexCommand \index{\#defines}
15448
15449 \end_inset
15450
15451
15452 \begin_inset LatexCommand \index{Defines created by the compiler}
15453
15454 \end_inset
15455
15456 :
15457 \newline
15458
15459 \layout Standard
15460
15461
15462 \begin_inset  Tabular
15463 <lyxtabular version="3" rows="11" columns="2">
15464 <features>
15465 <column alignment="center" valignment="top" leftline="true" width="0">
15466 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15467 <row topline="true" bottomline="true">
15468 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15469 \begin_inset Text
15470
15471 \layout Standard
15472
15473
15474 \series bold
15475 #define
15476 \end_inset
15477 </cell>
15478 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15479 \begin_inset Text
15480
15481 \layout Standard
15482
15483
15484 \series bold
15485 Description
15486 \end_inset
15487 </cell>
15488 </row>
15489 <row topline="true">
15490 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15491 \begin_inset Text
15492
15493 \layout Standard
15494
15495 SDCC
15496 \begin_inset LatexCommand \index{SDCC}
15497
15498 \end_inset
15499
15500
15501 \end_inset
15502 </cell>
15503 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15504 \begin_inset Text
15505
15506 \layout Standard
15507
15508 this Symbol is always defined
15509 \end_inset
15510 </cell>
15511 </row>
15512 <row topline="true">
15513 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15514 \begin_inset Text
15515
15516 \layout Standard
15517
15518 SDCC_mcs51
15519 \begin_inset LatexCommand \index{SDCC\_mcs51}
15520
15521 \end_inset
15522
15523  or SDCC_ds390
15524 \begin_inset LatexCommand \index{SDCC\_ds390}
15525
15526 \end_inset
15527
15528  or SDCC_z80
15529 \begin_inset LatexCommand \index{SDCC\_z80}
15530
15531 \end_inset
15532
15533 , etc
15534 \end_inset
15535 </cell>
15536 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15537 \begin_inset Text
15538
15539 \layout Standard
15540
15541 depending on the model used (e.g.: -mds390
15542 \end_inset
15543 </cell>
15544 </row>
15545 <row topline="true">
15546 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15547 \begin_inset Text
15548
15549 \layout Standard
15550
15551 __mcs51
15552 \begin_inset LatexCommand \index{\_\_mcs51}
15553
15554 \end_inset
15555
15556 , __ds390
15557 \begin_inset LatexCommand \index{\_\_ds390}
15558
15559 \end_inset
15560
15561 , __hc08
15562 \begin_inset LatexCommand \index{\_\_hc08}
15563
15564 \end_inset
15565
15566 , __z80
15567 \begin_inset LatexCommand \index{\_\_z80}
15568
15569 \end_inset
15570
15571 , etc
15572 \end_inset
15573 </cell>
15574 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15575 \begin_inset Text
15576
15577 \layout Standard
15578
15579 depending on the model used (e.g.
15580  -mz80)
15581 \end_inset
15582 </cell>
15583 </row>
15584 <row topline="true">
15585 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15586 \begin_inset Text
15587
15588 \layout Standard
15589
15590 SDCC_STACK_AUTO
15591 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
15592
15593 \end_inset
15594
15595
15596 \end_inset
15597 </cell>
15598 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15599 \begin_inset Text
15600
15601 \layout Standard
15602
15603 when
15604 \emph on
15605 -
15606 \begin_inset ERT
15607 status Collapsed
15608
15609 \layout Standard
15610
15611 \backslash
15612 /
15613 \end_inset
15614
15615 -stack-auto
15616 \emph default
15617  option is used
15618 \end_inset
15619 </cell>
15620 </row>
15621 <row topline="true">
15622 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15623 \begin_inset Text
15624
15625 \layout Standard
15626
15627 SDCC_MODEL_SMALL
15628 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
15629
15630 \end_inset
15631
15632
15633 \end_inset
15634 </cell>
15635 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15636 \begin_inset Text
15637
15638 \layout Standard
15639
15640 when
15641 \emph on
15642 -
15643 \begin_inset ERT
15644 status Collapsed
15645
15646 \layout Standard
15647
15648 \backslash
15649 /
15650 \end_inset
15651
15652 -model-small
15653 \emph default
15654  is used
15655 \end_inset
15656 </cell>
15657 </row>
15658 <row topline="true">
15659 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15660 \begin_inset Text
15661
15662 \layout Standard
15663
15664 SDCC_MODEL_MEDIUM
15665 \begin_inset LatexCommand \index{SDCC\_MODEL\_MEDIUM}
15666
15667 \end_inset
15668
15669
15670 \end_inset
15671 </cell>
15672 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15673 \begin_inset Text
15674
15675 \layout Standard
15676
15677 when
15678 \emph on
15679 -
15680 \begin_inset ERT
15681 status Collapsed
15682
15683 \layout Standard
15684
15685 \backslash
15686 /
15687 \end_inset
15688
15689 -model-medium
15690 \emph default
15691  is used
15692 \end_inset
15693 </cell>
15694 </row>
15695 <row topline="true">
15696 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15697 \begin_inset Text
15698
15699 \layout Standard
15700
15701 SDCC_MODEL_LARGE
15702 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
15703
15704 \end_inset
15705
15706
15707 \end_inset
15708 </cell>
15709 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15710 \begin_inset Text
15711
15712 \layout Standard
15713
15714 when
15715 \emph on
15716 -
15717 \begin_inset ERT
15718 status Collapsed
15719
15720 \layout Standard
15721
15722 \backslash
15723 /
15724 \end_inset
15725
15726 -model-large
15727 \emph default
15728  is used
15729 \end_inset
15730 </cell>
15731 </row>
15732 <row topline="true">
15733 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15734 \begin_inset Text
15735
15736 \layout Standard
15737
15738 SDCC_USE_XSTACK
15739 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
15740
15741 \end_inset
15742
15743
15744 \end_inset
15745 </cell>
15746 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15747 \begin_inset Text
15748
15749 \layout Standard
15750
15751 when
15752 \emph on
15753 -
15754 \begin_inset ERT
15755 status Collapsed
15756
15757 \layout Standard
15758
15759 \backslash
15760 /
15761 \end_inset
15762
15763 -xstack
15764 \emph default
15765  option is used
15766 \end_inset
15767 </cell>
15768 </row>
15769 <row topline="true">
15770 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15771 \begin_inset Text
15772
15773 \layout Standard
15774
15775 SDCC_STACK_TENBIT
15776 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
15777
15778 \end_inset
15779
15780
15781 \end_inset
15782 </cell>
15783 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15784 \begin_inset Text
15785
15786 \layout Standard
15787
15788 when
15789 \emph on
15790 -mds390
15791 \emph default
15792  is used
15793 \end_inset
15794 </cell>
15795 </row>
15796 <row topline="true" bottomline="true">
15797 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15798 \begin_inset Text
15799
15800 \layout Standard
15801
15802 SDCC_MODEL_FLAT24
15803 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
15804
15805 \end_inset
15806
15807
15808 \end_inset
15809 </cell>
15810 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15811 \begin_inset Text
15812
15813 \layout Standard
15814
15815 when
15816 \emph on
15817 -mds390
15818 \emph default
15819  is used
15820 \end_inset
15821 </cell>
15822 </row>
15823 </lyxtabular>
15824
15825 \end_inset
15826
15827
15828 \layout Chapter
15829
15830 Notes on supported Processors
15831 \layout Section
15832
15833 MCS51 variants
15834 \begin_inset LatexCommand \label{sub:MCS51-variants}
15835
15836 \end_inset
15837
15838
15839 \begin_inset LatexCommand \index{MCS51 variants}
15840
15841 \end_inset
15842
15843
15844 \layout Standard
15845
15846 MCS51 processors are available from many vendors and come in many different
15847  flavours.
15848  While they might differ considerably in respect to Special Function Registers
15849  the core MCS51 is usually not modified or is kept compatible.
15850
15851 \layout Subsection
15852
15853 pdata access by SFR
15854 \layout Standard
15855
15856 With the upcome of devices with internal xdata and flash memory devices
15857  using port P2
15858 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
15859
15860 \end_inset
15861
15862  as dedicated I/O port is becoming more popular.
15863  Switching the high byte for pdata
15864 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
15865
15866 \end_inset
15867
15868  access which was formerly done by port P2 is then achieved by a Special
15869  Function Register
15870 \begin_inset LatexCommand \index{sfr}
15871
15872 \end_inset
15873
15874 .
15875  In well-established MCS51 tradition the address of this
15876 \emph on
15877 sfr
15878 \emph default
15879  is where the chip designers decided to put it.
15880  Needless to say that they didn't agree on a common name either.
15881  So that the startup code can correctly initialize xdata variables, you
15882  should define an sfr with the name _XPAGE
15883 \family typewriter
15884
15885 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
15886
15887 \end_inset
15888
15889
15890 \family default
15891  at the appropriate location if the default, port P2, is not used for this.
15892  Some examples are:
15893 \layout Verse
15894
15895
15896 \family typewriter
15897 sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
15898 \layout Verse
15899
15900
15901 \family typewriter
15902 sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
15903 \layout Verse
15904
15905
15906 \family typewriter
15907 sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
15908 \layout Standard
15909
15910 For more exotic implementations further customizations may be needed.
15911  See section
15912 \begin_inset LatexCommand \ref{sub:Startup-Code}
15913
15914 \end_inset
15915
15916  for other possibilities.
15917 \layout Subsection
15918
15919 Other Features available by SFR
15920 \layout Standard
15921
15922 Some MCS51 variants offer features like Double DPTR
15923 \begin_inset LatexCommand \index{DPTR}
15924
15925 \end_inset
15926
15927 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
15928  These are currently not used for the MCS51 port.
15929  If you absolutely need them you can fall back to inline assembly or submit
15930  a patch to SDCC.
15931 \layout Section
15932
15933 DS400 port
15934 \layout Standard
15935
15936 The DS80C400 microcontroller has a rich set of peripherals.
15937  In its built-in ROM library it includes functions to access some of the
15938  features, among them is a TCP stack with IP4 and IP6 support.
15939  Library headers (currently in beta status) and other files are provided
15940  at
15941 \size footnotesize
15942
15943 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
15944
15945 \end_inset
15946
15947 .
15948
15949 \layout Section
15950
15951 The Z80 and gbz80 port
15952 \layout Standard
15953
15954 SDCC can target both the Zilog
15955 \begin_inset LatexCommand \index{Z80}
15956
15957 \end_inset
15958
15959  and the Nintendo Gameboy's Z80-like gbz80
15960 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
15961
15962 \end_inset
15963
15964 .
15965  The Z80 port is passed through the same
15966 \emph on
15967 regressions tests
15968 \begin_inset LatexCommand \index{Regression test}
15969
15970 \end_inset
15971
15972
15973 \emph default
15974  as the MCS51 and DS390 ports, so floating point support, support for long
15975  variables and bitfield support is fine.
15976  See mailing lists and forums about interrupt routines.
15977 \layout Standard
15978
15979 As always, the code is the authoritative reference - see z80/ralloc.c and
15980  z80/gen.c.
15981  The stack
15982 \begin_inset LatexCommand \index{stack}
15983
15984 \end_inset
15985
15986  frame is similar to that generated by the IAR Z80 compiler.
15987  IX is used as the base pointer, HL and IY are used as a temporary registers,
15988  and BC and DE are available for holding variables.
15989  Return values
15990 \begin_inset LatexCommand \index{return value}
15991
15992 \end_inset
15993
15994  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
15995  bytes).
15996  The gbz80 port use the same set of registers for the return values, but
15997  in a different order of significance: E (one byte), DE (two bytes), or
15998  HLDE (four bytes).
15999 \layout Section
16000
16001 The HC08 port
16002 \layout Standard
16003
16004 The port to the Motorola HC08
16005 \begin_inset LatexCommand \index{HC08}
16006
16007 \end_inset
16008
16009  family has been added in October 2003, and is still undergoing some basic
16010  development.
16011  The code generator is complete, but the register allocation is still quite
16012  unoptimized.
16013  Some of the SDCC's standard C library functions have embedded non-HC08
16014  inline assembly and so are not yet usable.
16015 \newline
16016
16017 \newline
16018
16019 \layout Section
16020
16021 The PIC14 port
16022 \layout Standard
16023
16024 The 14bit PIC
16025 \begin_inset LatexCommand \index{PIC14}
16026
16027 \end_inset
16028
16029  port still requires a major effort from the development community.
16030  However it can work for very simple code.
16031 \layout Subsection
16032
16033 C code and 14bit PIC code page
16034 \begin_inset LatexCommand \index{code page (pic14)}
16035
16036 \end_inset
16037
16038  and RAM banks
16039 \begin_inset LatexCommand \index{RAM bank (pic14)}
16040
16041 \end_inset
16042
16043
16044 \layout Standard
16045
16046 The linker organizes allocation for the code page and RAM banks.
16047  It does not have intimate knowledge of the code flow.
16048  It will put all the code section of a single asm file into a single code
16049  page.
16050  In order to make use of multiple code pages, separate asm files must be
16051  used.
16052  The compiler treats all functions of a single C file as being in the same
16053  code page unless it is non static.
16054  The compiler treats all local variables of a single C file as being in
16055  the same RAM bank unless it is an extern.
16056 \newline
16057
16058 \newline
16059 To get the best follow these guide lines:
16060 \layout Enumerate
16061
16062 make local functions static, as non static functions require code page selection
16063  overhead.
16064 \layout Enumerate
16065
16066 Make local variables static as extern variables require RAM bank selection
16067  overhead.
16068 \layout Enumerate
16069
16070 For devices that have multiple code pages it is more efficient to use the
16071  same number of files as pages, i.e.
16072  for the 16F877 use 4 separate files and i.e.
16073  for the 16F874 use 2 separate files.
16074  This way the linker can put the code for each file into different code
16075  pages and the compiler can allocate reusable variables more efficiently
16076  and there's less page selection overhead.
16077  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
16078  instruction set) use 'unsigned char' whereever possible instead of 'int'.
16079 \layout Subsection
16080
16081 Creating a device include file
16082 \layout Standard
16083
16084 For generating a device include file use the support perl script inc2h.pl
16085  kept in directory support/script.
16086 \layout Subsection
16087
16088 Interrupt code
16089 \layout Standard
16090
16091 For the interrupt function, use the keyword 'interrupt'
16092 \begin_inset LatexCommand \index{interrupt}
16093
16094 \end_inset
16095
16096  with level number of 0 (PIC14 only has 1 interrupt so this number is only
16097  there to avoid a syntax error - it ought to be fixed).
16098  E.g.:
16099 \layout Verse
16100
16101
16102 \family typewriter
16103 void Intr(void) interrupt 0
16104 \newline
16105 {
16106 \newline
16107 \SpecialChar ~
16108 \SpecialChar ~
16109 T0IF = 0; /* Clear timer interrupt */
16110 \newline
16111 }
16112 \layout Subsection
16113
16114 Linking and assembling
16115 \layout Standard
16116
16117 For assembling you can use either GPUTILS'
16118 \begin_inset LatexCommand \index{gputils (pic tools)}
16119
16120 \end_inset
16121
16122  gpasm.exe or MPLAB's mpasmwin.exe.
16123  GPUTILS is available from
16124 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
16125
16126 \end_inset
16127
16128 .
16129  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
16130  If you use MPLAB and an interrupt function then the linker script file
16131  vectors section will need to be enlarged to link with mplink.
16132 \newline
16133
16134 \newline
16135 Here is a
16136 \family typewriter
16137 Makefile
16138 \family default
16139  using GPUTILS:
16140 \layout Verse
16141
16142
16143 \family typewriter
16144 .c.o:
16145 \newline
16146 \SpecialChar ~
16147 \SpecialChar ~
16148 \SpecialChar ~
16149 \SpecialChar ~
16150 \SpecialChar ~
16151 \SpecialChar ~
16152 \SpecialChar ~
16153 \SpecialChar ~
16154 sdcc -S -V -mpic14 -p16F877 $<
16155 \newline
16156 \SpecialChar ~
16157 \SpecialChar ~
16158 \SpecialChar ~
16159 \SpecialChar ~
16160 \SpecialChar ~
16161 \SpecialChar ~
16162 \SpecialChar ~
16163 \SpecialChar ~
16164 gpasm -c $*.asm
16165 \newline
16166
16167 \newline
16168 $(PRJ).hex: $(OBJS)
16169 \newline
16170 \SpecialChar ~
16171 \SpecialChar ~
16172 \SpecialChar ~
16173 \SpecialChar ~
16174 \SpecialChar ~
16175 \SpecialChar ~
16176 \SpecialChar ~
16177 \SpecialChar ~
16178 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS) libsdcc.lib
16179 \layout Standard
16180
16181 Here is a
16182 \family typewriter
16183 Makefile
16184 \family default
16185  using MPLAB:
16186 \layout Verse
16187
16188
16189 \family typewriter
16190 .c.o:
16191 \newline
16192 \SpecialChar ~
16193 \SpecialChar ~
16194 \SpecialChar ~
16195 \SpecialChar ~
16196 \SpecialChar ~
16197 \SpecialChar ~
16198 \SpecialChar ~
16199 \SpecialChar ~
16200 sdcc -S -V -mpic14 -p16F877 $<
16201 \newline
16202 \SpecialChar ~
16203 \SpecialChar ~
16204 \SpecialChar ~
16205 \SpecialChar ~
16206 \SpecialChar ~
16207 \SpecialChar ~
16208 \SpecialChar ~
16209 \SpecialChar ~
16210 mpasmwin /q /o $*.asm
16211 \newline
16212
16213 \newline
16214 $(PRJ).hex: $(OBJS)
16215 \newline
16216 \SpecialChar ~
16217 \SpecialChar ~
16218 \SpecialChar ~
16219 \SpecialChar ~
16220 \SpecialChar ~
16221 \SpecialChar ~
16222 \SpecialChar ~
16223 \SpecialChar ~
16224 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS) libsdcc.lib
16225 \layout Standard
16226
16227 Please note that indentations within a
16228 \family typewriter
16229  Makefile
16230 \family default
16231  have to be done with a tabulator character.
16232 \layout Subsection
16233
16234 Command-line options
16235 \layout Standard
16236
16237 Besides the switches common to all SDCC backends, the PIC14 port accepts
16238  the following options (for an updated list see sdcc -
16239 \begin_inset ERT
16240 status Collapsed
16241
16242 \layout Standard
16243
16244 \backslash
16245 /
16246 \end_inset
16247
16248 -help):
16249 \layout List
16250 \labelwidthstring 00.00.0000
16251
16252 -
16253 \begin_inset ERT
16254 status Collapsed
16255
16256 \layout Standard
16257
16258 \backslash
16259 /
16260 \end_inset
16261
16262 -debug-extra emit debug info in assembly output
16263 \layout List
16264 \labelwidthstring 00.00.0000
16265
16266 -
16267 \begin_inset ERT
16268 status Collapsed
16269
16270 \layout Standard
16271
16272 \backslash
16273 /
16274 \end_inset
16275
16276 -no-pcode-opt disable (slightly faulty) optimization on pCode
16277 \layout Subsection
16278
16279 The library
16280 \layout Subsubsection
16281
16282 error: missing definition for symbol
16283 \begin_inset Quotes sld
16284 \end_inset
16285
16286 __gptrget1
16287 \begin_inset Quotes srd
16288 \end_inset
16289
16290
16291 \layout Standard
16292
16293 The PIC14 port uses library routines to provide more complex operations
16294  like multiplication, division/modulus and (generic) pointer dereferencing.
16295  In order to add these routines to your project, you must link with PIC14's
16296
16297 \family typewriter
16298 libsdcc.lib
16299 \family default
16300 .
16301  For single source file projects this is done automatically, more complex
16302  projects must add
16303 \family typewriter
16304 libsdcc.lib
16305 \family default
16306  to the linker's arguments.
16307  Make sure you also add an include path for the library (using the -I switch
16308  to the linker)!
16309 \layout Subsubsection
16310
16311 Processor mismatch in file
16312 \begin_inset Quotes sld
16313 \end_inset
16314
16315 XXX
16316 \begin_inset Quotes srd
16317 \end_inset
16318
16319 .
16320 \layout Standard
16321
16322 This warning can usually be ignored due to the very good compatibility amongst
16323  14 bit PIC devices.
16324 \layout Standard
16325
16326 You might also consider recompiling the library for your specific device
16327  by changing the ARCH=p16f877 (default target) entry in
16328 \family typewriter
16329 device/lib/pic/Makefile.in
16330 \family default
16331  and
16332 \family typewriter
16333 device/lib/pic/Makefile
16334 \family default
16335  to reflect your device.
16336  This might even improve performance for smaller devices as unneccesary
16337  BANKSELs migth be removed.
16338 \layout Subsection
16339
16340 Known bugs
16341 \layout Subsubsection
16342
16343 initialized data
16344 \layout Standard
16345
16346 Currently, data can only be initialized if it resides in the source file
16347  together with
16348 \emph on
16349 main()
16350 \emph default
16351 .
16352  Data in other source files will silently
16353 \series bold
16354 not
16355 \series default
16356  be initialized.
16357 \layout Section
16358
16359 The PIC16
16360 \begin_inset LatexCommand \index{PIC16}
16361
16362 \end_inset
16363
16364  port
16365 \layout Standard
16366
16367 The PIC16
16368 \begin_inset LatexCommand \index{PIC16}
16369
16370 \end_inset
16371
16372  port is the portion of SDCC that is responsible to produce code for the
16373  Microchip
16374 \begin_inset LatexCommand \index{Microchip}
16375
16376 \end_inset
16377
16378 (TM) microcontrollers with 16 bit core.
16379  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
16380  Currently supported devices are:
16381 \layout Standard
16382 \align center
16383
16384 \begin_inset  Tabular
16385 <lyxtabular version="3" rows="4" columns="6">
16386 <features>
16387 <column alignment="center" valignment="top" leftline="true" width="0">
16388 <column alignment="center" valignment="top" leftline="true" width="0">
16389 <column alignment="center" valignment="top" leftline="true" width="0">
16390 <column alignment="center" valignment="top" leftline="true" width="0">
16391 <column alignment="center" valignment="top" leftline="true" width="0">
16392 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16393 <row topline="true">
16394 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16395 \begin_inset Text
16396
16397 \layout Standard
16398
16399 18F242
16400 \end_inset
16401 </cell>
16402 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16403 \begin_inset Text
16404
16405 \layout Standard
16406
16407 18F248
16408 \end_inset
16409 </cell>
16410 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16411 \begin_inset Text
16412
16413 \layout Standard
16414
16415 18F252
16416 \end_inset
16417 </cell>
16418 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16419 \begin_inset Text
16420
16421 \layout Standard
16422
16423 18F258
16424 \end_inset
16425 </cell>
16426 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16427 \begin_inset Text
16428
16429 \layout Standard
16430
16431 18F442
16432 \end_inset
16433 </cell>
16434 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16435 \begin_inset Text
16436
16437 \layout Standard
16438
16439 18F448
16440 \end_inset
16441 </cell>
16442 </row>
16443 <row topline="true">
16444 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16445 \begin_inset Text
16446
16447 \layout Standard
16448
16449 18F452
16450 \end_inset
16451 </cell>
16452 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16453 \begin_inset Text
16454
16455 \layout Standard
16456
16457 18F458
16458 \end_inset
16459 </cell>
16460 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16461 \begin_inset Text
16462
16463 \layout Standard
16464
16465 18F1220
16466 \end_inset
16467 </cell>
16468 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16469 \begin_inset Text
16470
16471 \layout Standard
16472
16473 18F2220
16474 \end_inset
16475 </cell>
16476 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16477 \begin_inset Text
16478
16479 \layout Standard
16480
16481 18F2550
16482 \end_inset
16483 </cell>
16484 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16485 \begin_inset Text
16486
16487 \layout Standard
16488
16489 18F4331
16490 \end_inset
16491 </cell>
16492 </row>
16493 <row topline="true">
16494 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16495 \begin_inset Text
16496
16497 \layout Standard
16498
16499 18F4455
16500 \end_inset
16501 </cell>
16502 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16503 \begin_inset Text
16504
16505 \layout Standard
16506
16507 18F6520
16508 \end_inset
16509 </cell>
16510 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16511 \begin_inset Text
16512
16513 \layout Standard
16514
16515 18F6620
16516 \end_inset
16517 </cell>
16518 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16519 \begin_inset Text
16520
16521 \layout Standard
16522
16523 18F6680
16524 \end_inset
16525 </cell>
16526 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16527 \begin_inset Text
16528
16529 \layout Standard
16530
16531 18F6720
16532 \end_inset
16533 </cell>
16534 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16535 \begin_inset Text
16536
16537 \layout Standard
16538
16539 18F8520
16540 \end_inset
16541 </cell>
16542 </row>
16543 <row topline="true" bottomline="true">
16544 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16545 \begin_inset Text
16546
16547 \layout Standard
16548
16549 18F8620
16550 \end_inset
16551 </cell>
16552 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16553 \begin_inset Text
16554
16555 \layout Standard
16556
16557 18F8680
16558 \end_inset
16559 </cell>
16560 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16561 \begin_inset Text
16562
16563 \layout Standard
16564
16565 18F8720
16566 \end_inset
16567 </cell>
16568 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16569 \begin_inset Text
16570
16571 \layout Standard
16572
16573 \end_inset
16574 </cell>
16575 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16576 \begin_inset Text
16577
16578 \layout Standard
16579
16580 \end_inset
16581 </cell>
16582 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16583 \begin_inset Text
16584
16585 \layout Standard
16586
16587 \end_inset
16588 </cell>
16589 </row>
16590 </lyxtabular>
16591
16592 \end_inset
16593
16594
16595 \layout Subsection
16596
16597 Global Options
16598 \layout Standard
16599
16600 PIC16 port supports the standard command line arguments as supposed, with
16601  the exception of certain cases that will be mentioned in the following
16602  list:
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 -callee-saves See -
16617 \begin_inset ERT
16618 status Collapsed
16619
16620 \layout Standard
16621
16622 \backslash
16623 /
16624 \end_inset
16625
16626 -all-callee-saves
16627 \layout List
16628 \labelwidthstring 00.00.0000
16629
16630 -
16631 \begin_inset ERT
16632 status Collapsed
16633
16634 \layout Standard
16635
16636 \backslash
16637 /
16638 \end_inset
16639
16640 -all-callee-saves All function arguments are passed on stack by default.
16641
16642 \emph on
16643 There is no need to specify this in the command line.
16644 \layout List
16645 \labelwidthstring 00.00.0000
16646
16647 -
16648 \begin_inset ERT
16649 status Collapsed
16650
16651 \layout Standard
16652
16653 \backslash
16654 /
16655 \end_inset
16656
16657 -fommit-frame-pointer Frame pointer will be omitted when the function uses
16658  no local variables.
16659 \layout Subsection
16660
16661 Port Specific Options
16662 \begin_inset LatexCommand \index{Options PIC16}
16663
16664 \end_inset
16665
16666
16667 \layout Standard
16668
16669 The port specific options appear after the global options in the sdcc --help
16670  output.
16671 \layout Subsubsection
16672
16673 General Options
16674 \layout Standard
16675
16676 General options enable certain port features and optimizations.
16677 \layout List
16678 \labelwidthstring 00.00.0000
16679
16680 -
16681 \begin_inset ERT
16682 status Collapsed
16683
16684 \layout Standard
16685
16686 \backslash
16687 /
16688 \end_inset
16689
16690 -stack-model=[model] Used in conjuction with the command above.
16691  Defines the stack model to be used, valid stack models are :
16692 \begin_deeper
16693 \layout List
16694 \labelwidthstring 00.00.0000
16695
16696
16697 \emph on
16698 small
16699 \emph default
16700  Selects small stack model.
16701  8 bit stack and frame pointers.
16702  Supports 256 bytes stack size.
16703 \layout List
16704 \labelwidthstring 00.00.0000
16705
16706
16707 \emph on
16708 large
16709 \emph default
16710  Selects large stack model.
16711  16 bit stack and frame pointers.
16712  Supports 65536 bytes stack size.
16713 \end_deeper
16714 \layout List
16715 \labelwidthstring 00.00.0000
16716
16717 -
16718 \begin_inset ERT
16719 status Collapsed
16720
16721 \layout Standard
16722
16723 \backslash
16724 /
16725 \end_inset
16726
16727 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
16728  unitialized data variables with [kword].
16729  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
16730 \layout List
16731 \labelwidthstring 00.00.0000
16732
16733 -
16734 \begin_inset ERT
16735 status Collapsed
16736
16737 \layout Standard
16738
16739 \backslash
16740 /
16741 \end_inset
16742
16743 -ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
16744  Useful for bootloaders.
16745 \layout List
16746 \labelwidthstring 00.00.0000
16747
16748 -
16749 \begin_inset ERT
16750 status Collapsed
16751
16752 \layout Standard
16753
16754 \backslash
16755 /
16756 \end_inset
16757
16758 -asm= sets the full path and name of an external assembler to call.
16759 \layout List
16760 \labelwidthstring 00.00.0000
16761
16762 -
16763 \begin_inset ERT
16764 status Collapsed
16765
16766 \layout Standard
16767
16768 \backslash
16769 /
16770 \end_inset
16771
16772 -link= sets the full path and name of an external linker to call.
16773 \layout List
16774 \labelwidthstring 00.00.0000
16775
16776 -
16777 \begin_inset ERT
16778 status Collapsed
16779
16780 \layout Standard
16781
16782 \backslash
16783 /
16784 \end_inset
16785
16786 -mplab-comp MPLAB compatibility option.
16787  Currently only suppresses special gpasm directives.
16788 \layout Subsubsection
16789
16790 Optimization Options
16791 \layout List
16792 \labelwidthstring 00.00.0000
16793
16794 -
16795 \begin_inset ERT
16796 status Collapsed
16797
16798 \layout Standard
16799
16800 \backslash
16801 /
16802 \end_inset
16803
16804 -optimize-goto Try to use (conditional) BRA instead of GOTO
16805 \layout List
16806 \labelwidthstring 00.00.0000
16807
16808 -
16809 \begin_inset ERT
16810 status Collapsed
16811
16812 \layout Standard
16813
16814 \backslash
16815 /
16816 \end_inset
16817
16818 -optimize-cmp Try to optimize some compares.
16819 \layout List
16820 \labelwidthstring 00.00.0000
16821
16822 -
16823 \begin_inset ERT
16824 status Collapsed
16825
16826 \layout Standard
16827
16828 \backslash
16829 /
16830 \end_inset
16831
16832 -optimize-df Analyze the dataflow of the generated code and improve it.
16833 \layout List
16834 \labelwidthstring 00.00.0000
16835
16836 -
16837 \begin_inset ERT
16838 status Collapsed
16839
16840 \layout Standard
16841
16842 \backslash
16843 /
16844 \end_inset
16845
16846 -obanksel=nn Set optimization level for inserting BANKSELs.
16847 \newline
16848
16849 \begin_deeper
16850 \layout List
16851 \labelwidthstring 00.00.0000
16852
16853 0 no optimization
16854 \layout List
16855 \labelwidthstring 00.00.0000
16856
16857 1 checks previous used register and if it is the same then does not emit
16858  BANKSEL, accounts only for labels.
16859 \layout List
16860 \labelwidthstring 00.00.0000
16861
16862 2 tries to check the location of (even different) symbols and removes BANKSELs
16863  if they are in the same bank.
16864
16865 \newline
16866
16867 \emph on
16868 Important: There might be problems if the linker script has data sections
16869  across bank borders!
16870 \end_deeper
16871 \layout Subsubsection
16872
16873 Linking Options
16874 \layout List
16875 \labelwidthstring 00.00.0000
16876
16877 -
16878 \begin_inset ERT
16879 status Collapsed
16880
16881 \layout Standard
16882
16883 \backslash
16884 /
16885 \end_inset
16886
16887 -nodefaultlibs do not link default libraries when linking
16888 \layout List
16889 \labelwidthstring 00.00.0000
16890
16891 -
16892 \begin_inset ERT
16893 status Collapsed
16894
16895 \layout Standard
16896
16897 \backslash
16898 /
16899 \end_inset
16900
16901 -no-crt Don't link the default run-time modules
16902 \layout List
16903 \labelwidthstring 00.00.0000
16904
16905 -
16906 \begin_inset ERT
16907 status Collapsed
16908
16909 \layout Standard
16910
16911 \backslash
16912 /
16913 \end_inset
16914
16915 -use-crt= Use a custom run-time module instead of the defaults.
16916 \layout Subsubsection
16917
16918 Debugging Options
16919 \layout Standard
16920
16921 Debugging options enable extra debugging information in the output files.
16922 \layout List
16923 \labelwidthstring 00.00.0000
16924
16925 -
16926 \begin_inset ERT
16927 status Collapsed
16928
16929 \layout Standard
16930
16931 \backslash
16932 /
16933 \end_inset
16934
16935 -debug-xtra Similar to -
16936 \begin_inset ERT
16937 status Collapsed
16938
16939 \layout Standard
16940
16941 \backslash
16942 /
16943 \end_inset
16944
16945 -debug
16946 \begin_inset LatexCommand \index{-\/-debug}
16947
16948 \end_inset
16949
16950 , but dumps more information.
16951 \layout List
16952 \labelwidthstring 00.00.0000
16953
16954 -
16955 \begin_inset ERT
16956 status Collapsed
16957
16958 \layout Standard
16959
16960 \backslash
16961 /
16962 \end_inset
16963
16964 -debug-ralloc Force register allocator to dump <source>.d file with debugging
16965  information.
16966  <source> is the name of the file compiled.
16967 \layout List
16968 \labelwidthstring 00.00.0000
16969
16970 -
16971 \begin_inset ERT
16972 status Collapsed
16973
16974 \layout Standard
16975
16976 \backslash
16977 /
16978 \end_inset
16979
16980 -pcode-verbose Enable pcode debugging information in translation.
16981 \layout List
16982 \labelwidthstring 00.00.0000
16983
16984 -
16985 \begin_inset ERT
16986 status Collapsed
16987
16988 \layout Standard
16989
16990 \backslash
16991 /
16992 \end_inset
16993
16994 -denable-peeps Force the usage of peepholes.
16995  Use with care.
16996 \layout List
16997 \labelwidthstring 00.00.0000
16998
16999 -
17000 \begin_inset ERT
17001 status Collapsed
17002
17003 \layout Standard
17004
17005 \backslash
17006 /
17007 \end_inset
17008
17009 -gstack Trace push/pops for stack pointer overflow
17010 \layout List
17011 \labelwidthstring 00.00.0000
17012
17013 -
17014 \begin_inset ERT
17015 status Collapsed
17016
17017 \layout Standard
17018
17019 \backslash
17020 /
17021 \end_inset
17022
17023 -call-tree dump call tree in .calltree file
17024 \layout Subsection
17025
17026 Enviromental Variables
17027 \layout Standard
17028
17029 There is a number of enviromental variables that can be used when running
17030  SDCC to enable certain optimizations or force a specific program behaviour.
17031  these variables are primarily for debugging purposes so they can be enabled/dis
17032 abled at will.
17033 \layout Standard
17034
17035 Currently there is only two such variables available:
17036 \layout List
17037 \labelwidthstring 00.00.0000
17038
17039 OPTIMIZE_BITFIELD_POINTER_GET when this variable exists reading of structure
17040  bitfields is optimized by directly loading FSR0 with the address of the
17041  bitfield structure.
17042  Normally SDCC will cast the bitfield structure to a bitfield pointer and
17043  then load FSR0.
17044  This step saves data ram and code space for functions that perform heavy
17045  use of bitfields.
17046  (ie.
17047  80 bytes of code space are saved when compiling malloc.c with this option).
17048
17049 \layout List
17050 \labelwidthstring 00.00.0000
17051
17052 NO_REG_OPT do not perform pCode registers optimization.
17053  This should be used for debugging purposes.
17054  In some where bugs in the pcode optimizer are found, users can benefit
17055  from temporarily disabling the optimizer until the bug is fixed.
17056 \layout Subsection
17057
17058 Preprocessor Macros
17059 \layout Standard
17060
17061 PIC16 port defines the following preprocessor macros while translating a
17062  source.
17063 \layout Standard
17064 \align center
17065
17066 \begin_inset  Tabular
17067 <lyxtabular version="3" rows="6" columns="2">
17068 <features>
17069 <column alignment="center" valignment="top" leftline="true" width="0">
17070 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17071 <row topline="true" bottomline="true">
17072 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17073 \begin_inset Text
17074
17075 \layout Standard
17076
17077 Macro
17078 \end_inset
17079 </cell>
17080 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17081 \begin_inset Text
17082
17083 \layout Standard
17084
17085 Description
17086 \end_inset
17087 </cell>
17088 </row>
17089 <row topline="true">
17090 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17091 \begin_inset Text
17092
17093 \layout Standard
17094
17095 SDCC_pic16
17096 \end_inset
17097 </cell>
17098 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17099 \begin_inset Text
17100
17101 \layout Standard
17102
17103 Port identification
17104 \end_inset
17105 </cell>
17106 </row>
17107 <row topline="true">
17108 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17109 \begin_inset Text
17110
17111 \layout Standard
17112
17113 _
17114 \begin_inset ERT
17115 status Collapsed
17116
17117 \layout Standard
17118
17119 \backslash
17120 /
17121 \end_inset
17122
17123 _pic16
17124 \end_inset
17125 </cell>
17126 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17127 \begin_inset Text
17128
17129 \layout Standard
17130
17131 Port identification (same as above)
17132 \end_inset
17133 </cell>
17134 </row>
17135 <row topline="true">
17136 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17137 \begin_inset Text
17138
17139 \layout Standard
17140
17141 pic18fxxxx
17142 \end_inset
17143 </cell>
17144 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17145 \begin_inset Text
17146
17147 \layout Standard
17148
17149 MCU Identification.
17150
17151 \emph on
17152 xxxx
17153 \emph default
17154  is the microcontrol identification number, i.e.
17155  452, 6620, etc
17156 \end_inset
17157 </cell>
17158 </row>
17159 <row topline="true">
17160 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17161 \begin_inset Text
17162
17163 \layout Standard
17164
17165 _
17166 \begin_inset ERT
17167 status Collapsed
17168
17169 \layout Standard
17170
17171 \backslash
17172 /
17173 \end_inset
17174
17175 _18Fxxxx
17176 \end_inset
17177 </cell>
17178 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17179 \begin_inset Text
17180
17181 \layout Standard
17182
17183 MCU Identification (same as above)
17184 \end_inset
17185 </cell>
17186 </row>
17187 <row topline="true" bottomline="true">
17188 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17189 \begin_inset Text
17190
17191 \layout Standard
17192
17193 STACK_MODEL_nnn
17194 \end_inset
17195 </cell>
17196 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17197 \begin_inset Text
17198
17199 \layout Standard
17200
17201 nnn = SMALL or LARGE respectively according to the stack model used
17202 \end_inset
17203 </cell>
17204 </row>
17205 </lyxtabular>
17206
17207 \end_inset
17208
17209
17210 \layout Standard
17211
17212 In addition the following macros are defined when calling assembler:
17213 \layout Standard
17214 \align center
17215
17216 \begin_inset  Tabular
17217 <lyxtabular version="3" rows="4" columns="2">
17218 <features>
17219 <column alignment="center" valignment="top" leftline="true" width="0">
17220 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17221 <row topline="true" bottomline="true">
17222 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17223 \begin_inset Text
17224
17225 \layout Standard
17226
17227 Macro
17228 \end_inset
17229 </cell>
17230 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17231 \begin_inset Text
17232
17233 \layout Standard
17234
17235 Description
17236 \end_inset
17237 </cell>
17238 </row>
17239 <row topline="true">
17240 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17241 \begin_inset Text
17242
17243 \layout Standard
17244
17245 __18Fxxxx
17246 \end_inset
17247 </cell>
17248 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17249 \begin_inset Text
17250
17251 \layout Standard
17252
17253 MCU Identification.
17254
17255 \emph on
17256 xxxx
17257 \emph default
17258  is the microcontrol identification number, i.e.
17259  452, 6620, etc
17260 \end_inset
17261 </cell>
17262 </row>
17263 <row topline="true">
17264 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17265 \begin_inset Text
17266
17267 \layout Standard
17268
17269 SDCC_MODEL_nnn
17270 \end_inset
17271 </cell>
17272 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17273 \begin_inset Text
17274
17275 \layout Standard
17276
17277 nnn = SMALL or LARGE respectively according to the memory model used for
17278  SDCC
17279 \end_inset
17280 </cell>
17281 </row>
17282 <row topline="true" bottomline="true">
17283 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17284 \begin_inset Text
17285
17286 \layout Standard
17287
17288 STACK_MODEL_nnn
17289 \end_inset
17290 </cell>
17291 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17292 \begin_inset Text
17293
17294 \layout Standard
17295
17296 nnn = SMALL or LARGE respectively according to the stack model used
17297 \end_inset
17298 </cell>
17299 </row>
17300 </lyxtabular>
17301
17302 \end_inset
17303
17304
17305 \layout Subsection
17306
17307 Directories
17308 \layout Standard
17309
17310 PIC16
17311 \begin_inset LatexCommand \index{PIC16}
17312
17313 \end_inset
17314
17315  port uses the following directories for searching header files and libraries.
17316 \layout Standard
17317 \align center
17318
17319 \begin_inset  Tabular
17320 <lyxtabular version="3" rows="3" columns="4">
17321 <features>
17322 <column alignment="center" valignment="top" leftline="true" width="0">
17323 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17324 <column alignment="center" valignment="top" width="0">
17325 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17326 <row topline="true" bottomline="true">
17327 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17328 \begin_inset Text
17329
17330 \layout Standard
17331
17332 Directory
17333 \end_inset
17334 </cell>
17335 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17336 \begin_inset Text
17337
17338 \layout Standard
17339
17340 Description
17341 \end_inset
17342 </cell>
17343 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17344 \begin_inset Text
17345
17346 \layout Standard
17347
17348 Target
17349 \end_inset
17350 </cell>
17351 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17352 \begin_inset Text
17353
17354 \layout Standard
17355
17356 Command prefix
17357 \end_inset
17358 </cell>
17359 </row>
17360 <row topline="true">
17361 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17362 \begin_inset Text
17363
17364 \layout Standard
17365
17366 PREFIX/sdcc/include/pic16
17367 \end_inset
17368 </cell>
17369 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17370 \begin_inset Text
17371
17372 \layout Standard
17373
17374 PIC16 specific headers
17375 \end_inset
17376 </cell>
17377 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17378 \begin_inset Text
17379
17380 \layout Standard
17381
17382 Compiler
17383 \end_inset
17384 </cell>
17385 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17386 \begin_inset Text
17387
17388 \layout Standard
17389
17390 -I
17391 \end_inset
17392 </cell>
17393 </row>
17394 <row topline="true" bottomline="true">
17395 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17396 \begin_inset Text
17397
17398 \layout Standard
17399
17400 PREFIX/sdcc/lib/pic16
17401 \end_inset
17402 </cell>
17403 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17404 \begin_inset Text
17405
17406 \layout Standard
17407
17408 PIC16 specific libraries
17409 \end_inset
17410 </cell>
17411 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17412 \begin_inset Text
17413
17414 \layout Standard
17415
17416 Linker
17417 \end_inset
17418 </cell>
17419 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17420 \begin_inset Text
17421
17422 \layout Standard
17423
17424 -L
17425 \end_inset
17426 </cell>
17427 </row>
17428 </lyxtabular>
17429
17430 \end_inset
17431
17432
17433 \layout Subsection
17434
17435 Pragmas
17436 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
17437
17438 \end_inset
17439
17440
17441 \layout Standard
17442
17443 PIC16 port currently supports the following pragmas:
17444 \layout List
17445 \labelwidthstring 00.00.0000
17446
17447 stack pragma stack forces the code generator to initialize the stack & frame
17448  pointers at a specific address.
17449  This is an adhoc solution for cases where no STACK directive is available
17450  in the linker script or gplink is not instructed to create a stack section.
17451 \newline
17452 The stack pragma should be used only once in a project.
17453  Multiple pragmas may result in indeterminate behaviour of the program.
17454 \begin_inset Foot
17455 collapsed false
17456
17457 \layout Standard
17458
17459 The old format (ie.
17460  #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
17461  cross page boundaries (or even exceed the available data RAM) and crash
17462  the program.
17463  Make sure that stack does not cross page boundaries when using the SMALL
17464  stack model.
17465 \end_inset
17466
17467
17468 \newline
17469 The format is as follows:
17470 \layout LyX-Code
17471
17472 #pragma stack bottom_address [stack_size]
17473 \layout Standard
17474
17475
17476 \emph on
17477 bottom_address
17478 \emph default
17479  is the lower bound of the stack section.
17480  The stack pointer initially will point at address (bottom_address+stack_size-1).
17481 \layout LyX-Code
17482
17483 Example:
17484 \layout LyX-Code
17485
17486 \layout LyX-Code
17487
17488 /* initializes stack of 100 bytes at RAM address 0x200 */
17489 \layout LyX-Code
17490
17491 #pragma stack 0x200 100
17492 \layout Standard
17493
17494 If the stack_size field is omitted then a stack is created with the default
17495  size of 64.
17496  This size might be enough for most programs, but its not enough for operations
17497  with deep function nesting or excessive stack usage.
17498 \layout List
17499 \labelwidthstring 00.00.0000
17500
17501 wparam
17502 \emph on
17503 This pragma is deprecated.
17504  Its use will cause a warning message to be issued.
17505 \emph default
17506
17507 \newline
17508
17509 \layout List
17510 \labelwidthstring 00.00.0000
17511
17512 code place a function symbol at static FLASH address
17513 \layout LyX-Code
17514
17515 Example:
17516 \layout LyX-Code
17517
17518 \layout LyX-Code
17519
17520 /* place function test_func at 0x4000 */
17521 \layout LyX-Code
17522
17523 #pragma code test_func 0x4000
17524 \layout LyX-Code
17525
17526 \layout List
17527 \labelwidthstring 00.00.0000
17528
17529 library instructs the linker to use a library module.
17530 \newline
17531 Usage:
17532 \layout LyX-Code
17533
17534 #pragma library module_name
17535 \layout Standard
17536
17537
17538 \emph on
17539 module_name
17540 \emph default
17541  can be any library or object file (including its path).
17542  Note that there are four reserved keywords which have special meaning.
17543  These are:
17544 \layout Standard
17545 \align center
17546
17547 \begin_inset  Tabular
17548 <lyxtabular version="3" rows="6" columns="3">
17549 <features>
17550 <column alignment="center" valignment="top" leftline="true" width="0">
17551 <column alignment="block" valignment="top" leftline="true" width="20page%">
17552 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
17553 <row topline="true" bottomline="true">
17554 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17555 \begin_inset Text
17556
17557 \layout Standard
17558
17559 Keyword
17560 \end_inset
17561 </cell>
17562 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17563 \begin_inset Text
17564
17565 \layout Standard
17566
17567 Description
17568 \end_inset
17569 </cell>
17570 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17571 \begin_inset Text
17572
17573 \layout Standard
17574
17575 Module to link
17576 \end_inset
17577 </cell>
17578 </row>
17579 <row topline="true">
17580 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17581 \begin_inset Text
17582
17583 \layout Standard
17584
17585
17586 \series bold
17587 ignore
17588 \end_inset
17589 </cell>
17590 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17591 \begin_inset Text
17592
17593 \layout Standard
17594
17595 ignore all library pragmas
17596 \end_inset
17597 </cell>
17598 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17599 \begin_inset Text
17600
17601 \layout Standard
17602
17603
17604 \emph on
17605 (none)
17606 \end_inset
17607 </cell>
17608 </row>
17609 <row topline="true">
17610 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17611 \begin_inset Text
17612
17613 \layout Standard
17614
17615
17616 \series bold
17617 c
17618 \end_inset
17619 </cell>
17620 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17621 \begin_inset Text
17622
17623 \layout Standard
17624
17625 link the C library
17626 \end_inset
17627 </cell>
17628 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17629 \begin_inset Text
17630
17631 \layout Standard
17632
17633
17634 \emph on
17635 libc18f
17636 \emph default
17637 .lib
17638 \end_inset
17639 </cell>
17640 </row>
17641 <row topline="true">
17642 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17643 \begin_inset Text
17644
17645 \layout Standard
17646
17647
17648 \series bold
17649 math
17650 \end_inset
17651 </cell>
17652 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17653 \begin_inset Text
17654
17655 \layout Standard
17656
17657 link the Math libarary
17658 \end_inset
17659 </cell>
17660 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17661 \begin_inset Text
17662
17663 \layout Standard
17664
17665
17666 \emph on
17667 libm18f
17668 \emph default
17669 .lib
17670 \end_inset
17671 </cell>
17672 </row>
17673 <row topline="true">
17674 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17675 \begin_inset Text
17676
17677 \layout Standard
17678
17679
17680 \series bold
17681 io
17682 \end_inset
17683 </cell>
17684 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17685 \begin_inset Text
17686
17687 \layout Standard
17688
17689 link the I/O library
17690 \end_inset
17691 </cell>
17692 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17693 \begin_inset Text
17694
17695 \layout Standard
17696
17697
17698 \emph on
17699 libio18f*
17700 \emph default
17701 .lib
17702 \end_inset
17703 </cell>
17704 </row>
17705 <row topline="true" bottomline="true">
17706 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17707 \begin_inset Text
17708
17709 \layout Standard
17710
17711
17712 \series bold
17713 debug
17714 \end_inset
17715 </cell>
17716 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17717 \begin_inset Text
17718
17719 \layout Standard
17720
17721 link the debug library
17722 \end_inset
17723 </cell>
17724 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17725 \begin_inset Text
17726
17727 \layout Standard
17728
17729
17730 \emph on
17731 libdebug
17732 \emph default
17733 .lib
17734 \end_inset
17735 </cell>
17736 </row>
17737 </lyxtabular>
17738
17739 \end_inset
17740
17741
17742 \newline
17743 * is the device number, i.e.
17744  452 for PIC18F452 MCU.
17745 \layout Standard
17746
17747 This feature allows for linking with specific libraries withoug having to
17748  explicit name them in the command line.
17749  Note that the
17750 \noun on
17751 ignore
17752 \noun default
17753  keyword will reject all modules specified by the library pragma.
17754 \layout List
17755 \labelwidthstring 00.00.0000
17756
17757 udata pragma udata instructs the compiler to emit code so that linker will
17758  place a variable at a specific memory bank
17759 \layout LyX-Code
17760
17761 Example:
17762 \layout LyX-Code
17763
17764 \layout LyX-Code
17765
17766 /* places variable foo at bank2 */
17767 \layout LyX-Code
17768
17769 #pragma udata bank2 foo
17770 \layout LyX-Code
17771
17772 char foo;
17773 \layout Standard
17774
17775 In order for this pragma to work extra SECTION directives should be added
17776  in the .lkr script.
17777  In the following example a sample .lkr file is shown:
17778 \layout LyX-Code
17779
17780 \layout LyX-Code
17781
17782 // Sample linker script for the PIC18F452 processor
17783 \layout LyX-Code
17784
17785 LIBPATH .
17786 \layout LyX-Code
17787
17788 CODEPAGE   NAME=vectors    START=0x0            END=0x29           PROTECTED
17789 \layout LyX-Code
17790
17791 CODEPAGE   NAME=page       START=0x2A           END=0x7FFF
17792 \layout LyX-Code
17793
17794 CODEPAGE   NAME=idlocs     START=0x200000       END=0x200007       PROTECTED
17795 \layout LyX-Code
17796
17797 CODEPAGE   NAME=config     START=0x300000       END=0x30000D       PROTECTED
17798 \layout LyX-Code
17799
17800 CODEPAGE   NAME=devid      START=0x3FFFFE       END=0x3FFFFF       PROTECTED
17801 \layout LyX-Code
17802
17803 CODEPAGE   NAME=eedata     START=0xF00000       END=0xF000FF       PROTECTED
17804 \layout LyX-Code
17805
17806 ACCESSBANK NAME=accessram  START=0x0            END=0x7F
17807 \layout LyX-Code
17808
17809 \layout LyX-Code
17810
17811 DATABANK   NAME=gpr0       START=0x80           END=0xFF
17812 \layout LyX-Code
17813
17814 DATABANK   NAME=gpr1       START=0x100          END=0x1FF
17815 \layout LyX-Code
17816
17817 DATABANK   NAME=gpr2       START=0x200          END=0x2FF
17818 \layout LyX-Code
17819
17820 DATABANK   NAME=gpr3       START=0x300          END=0x3FF
17821 \layout LyX-Code
17822
17823 DATABANK   NAME=gpr4       START=0x400          END=0x4FF
17824 \layout LyX-Code
17825
17826 DATABANK   NAME=gpr5       START=0x500          END=0x5FF
17827 \layout LyX-Code
17828
17829 ACCESSBANK NAME=accesssfr  START=0xF80          END=0xFFF          PROTECTED
17830 \layout LyX-Code
17831
17832 \layout LyX-Code
17833
17834 SECTION    NAME=CONFIG     ROM=config
17835 \layout LyX-Code
17836
17837 \layout LyX-Code
17838
17839 SECTION    NAME=bank0      RAM=gpr0       # these SECTION directives
17840 \layout LyX-Code
17841
17842 SECTION    NAME=bank1      RAM=gpr1       # should be added to link
17843 \layout LyX-Code
17844
17845 SECTION    NAME=bank2      RAM=gpr2       # section name 'bank?' with
17846 \layout LyX-Code
17847
17848 SECTION    NAME=bank3      RAM=gpr3       # a specific DATABANK name
17849 \layout LyX-Code
17850
17851 SECTION    NAME=bank4      RAM=gpr4
17852 \layout LyX-Code
17853
17854 SECTION    NAME=bank5      RAM=gpr5
17855 \layout Standard
17856
17857 The linker will recognise the section name set in the pragma statement and
17858  will position the variable at the memory bank set with the RAM field at
17859  the SECTION line in the linker script file.
17860 \layout Subsection
17861
17862 Header Files
17863 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
17864
17865 \end_inset
17866
17867
17868 \layout Standard
17869
17870 There is one main header file that can be included to the source files using
17871  the pic16 port.
17872  That file is the
17873 \series bold
17874 pic18fregs.h
17875 \series default
17876 .
17877  This header file contains the definitions for the processor special registers,
17878  so it is necessary if the source accesses them.
17879  It can be included by adding the following line in the beginning of the
17880  file:
17881 \layout LyX-Code
17882
17883 #include <pic18fregs.h>
17884 \layout Standard
17885
17886 The specific microcontroller is selected within the pic18fregs.h automatically,
17887  so the same source can be used with a variety of devices.
17888 \layout Subsection
17889
17890 Libraries
17891 \layout Standard
17892
17893 The libraries that PIC16
17894 \begin_inset LatexCommand \index{PIC16}
17895
17896 \end_inset
17897
17898  port depends on are the microcontroller device libraries which contain
17899  the symbol definitions for the microcontroller special function registers.
17900  These libraries have the format pic18fxxxx.lib, where
17901 \emph on
17902 xxxx
17903 \emph default
17904  is the microcontroller identification number.
17905  The specific library is selected automatically by the compiler at link
17906  stage according to the selected device.
17907 \layout Standard
17908
17909 Libraries are created with gplib which is part of the gputils package
17910 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
17911
17912 \end_inset
17913
17914 .
17915 \layout Subsubsection*
17916
17917 Building the libraries
17918 \layout Standard
17919
17920 Before using SDCC/pic16 there are some libraries that need to be compiled.
17921  This process is not done automatically by SDCC since not all users use
17922  SDCC for pic16 projects.
17923  So each user should compile the libraries separately.
17924 \layout Standard
17925
17926 The steps to compile the pic16 libraries under Linux are:
17927 \layout LyX-Code
17928
17929 cd device/lib/pic16
17930 \layout LyX-Code
17931
17932 ./configure
17933 \layout LyX-Code
17934
17935 make
17936 \layout LyX-Code
17937
17938 cd ..
17939 \layout LyX-Code
17940
17941 make model-pic16
17942 \layout LyX-Code
17943
17944 su -c 'make install'     # install the libraries, you need the root password
17945 \layout Standard
17946
17947 If you need to install the headers too, do:
17948 \layout LyX-Code
17949
17950 cd device/include
17951 \layout LyX-Code
17952
17953 su -c 'make install'     # install the headers, you need the root password
17954 \layout Standard
17955
17956 There exist a special target to build the I/O libraries.
17957  This target is not automatically build because it will build the I/O library
17958  for
17959 \emph on
17960 every
17961 \emph default
17962  supported device.
17963  This way building will take quite a lot of time.
17964  Users are advised to edit the
17965 \series bold
17966 device/lib/pic16/pics.build
17967 \series default
17968  file and then execute:
17969 \layout LyX-Code
17970
17971 make lib-io
17972 \layout Subsection
17973
17974 Memory Models
17975 \layout Standard
17976
17977 The following memory models are supported by the PIC16 port:
17978 \layout Itemize
17979
17980 small model
17981 \layout Itemize
17982
17983 large model
17984 \layout Standard
17985
17986 Memory model affects the default size of pointers within the source.
17987  The sizes are shown in the next table:
17988 \layout Standard
17989 \align center
17990
17991 \begin_inset  Tabular
17992 <lyxtabular version="3" rows="3" columns="3">
17993 <features>
17994 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17995 <column alignment="center" valignment="top" leftline="true" width="0">
17996 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17997 <row topline="true" bottomline="true">
17998 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17999 \begin_inset Text
18000
18001 \layout Standard
18002
18003 Pointer sizes according to memory model
18004 \end_inset
18005 </cell>
18006 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18007 \begin_inset Text
18008
18009 \layout Standard
18010
18011 small model
18012 \end_inset
18013 </cell>
18014 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18015 \begin_inset Text
18016
18017 \layout Standard
18018
18019 large model
18020 \end_inset
18021 </cell>
18022 </row>
18023 <row topline="true" bottomline="true">
18024 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18025 \begin_inset Text
18026
18027 \layout Standard
18028
18029 code pointers
18030 \end_inset
18031 </cell>
18032 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18033 \begin_inset Text
18034
18035 \layout Standard
18036
18037 16-bits
18038 \end_inset
18039 </cell>
18040 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18041 \begin_inset Text
18042
18043 \layout Standard
18044
18045 24-bits
18046 \end_inset
18047 </cell>
18048 </row>
18049 <row topline="true" bottomline="true">
18050 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18051 \begin_inset Text
18052
18053 \layout Standard
18054
18055 data pointers
18056 \end_inset
18057 </cell>
18058 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
18059 \begin_inset Text
18060
18061 \layout Standard
18062
18063 16-bits
18064 \end_inset
18065 </cell>
18066 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18067 \begin_inset Text
18068
18069 \layout Standard
18070
18071 16-bits
18072 \end_inset
18073 </cell>
18074 </row>
18075 </lyxtabular>
18076
18077 \end_inset
18078
18079
18080 \layout Standard
18081
18082 It is advisable that all sources within a project are compiled with the
18083  same memory model.
18084  If one wants to override the default memory model, this can be done by
18085  declaring a pointer as
18086 \series bold
18087 far
18088 \series default
18089  or
18090 \series bold
18091 near
18092 \series default
18093 .
18094  Far selects large memory model's pointers, while near selects small memory
18095  model's pointers.
18096 \layout Standard
18097
18098 The standard device libraries (see
18099 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
18100
18101 \end_inset
18102
18103 ) contain no reference to pointers, so they can be used with both memory
18104  models.
18105 \layout Subsection
18106
18107 Stack
18108 \layout Standard
18109
18110 The stack implementation for the PIC16 port uses two indirect registers,
18111  FSR1 and FSR2.
18112 \layout List
18113 \labelwidthstring 00.00.0000
18114
18115 FSR1 is assigned as stack pointer
18116 \layout List
18117 \labelwidthstring 00.00.0000
18118
18119 FSR2 is assigned as frame pointer
18120 \layout Standard
18121
18122 The following stack models are supported by the PIC16 port
18123 \layout Itemize
18124
18125
18126 \noun on
18127 small
18128 \noun default
18129  model
18130 \layout Itemize
18131
18132
18133 \noun on
18134 large
18135 \noun default
18136  model
18137 \layout Standard
18138
18139
18140 \noun on
18141 Small
18142 \noun default
18143  model means that only the FSRxL byte is used to access stack and frame,
18144  while
18145 \emph on
18146 \noun on
18147 large
18148 \emph default
18149 \noun default
18150  uses both FSRxL and FSRxH registers.
18151  The following table shows the stack/frame pointers sizes according to stack
18152  model and the maximum space they can address:
18153 \layout Standard
18154 \align center
18155
18156 \begin_inset  Tabular
18157 <lyxtabular version="3" rows="3" columns="3">
18158 <features>
18159 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18160 <column alignment="center" valignment="top" leftline="true" width="0">
18161 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18162 <row topline="true" bottomline="true">
18163 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18164 \begin_inset Text
18165
18166 \layout Standard
18167
18168 Stack & Frame pointer sizes according to stack model
18169 \end_inset
18170 </cell>
18171 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18172 \begin_inset Text
18173
18174 \layout Standard
18175
18176 small
18177 \end_inset
18178 </cell>
18179 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18180 \begin_inset Text
18181
18182 \layout Standard
18183
18184 large
18185 \end_inset
18186 </cell>
18187 </row>
18188 <row topline="true">
18189 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18190 \begin_inset Text
18191
18192 \layout Standard
18193
18194 Stack pointer FSR1
18195 \end_inset
18196 </cell>
18197 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18198 \begin_inset Text
18199
18200 \layout Standard
18201
18202 8-bits
18203 \end_inset
18204 </cell>
18205 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18206 \begin_inset Text
18207
18208 \layout Standard
18209
18210 16-bits
18211 \end_inset
18212 </cell>
18213 </row>
18214 <row topline="true" bottomline="true">
18215 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18216 \begin_inset Text
18217
18218 \layout Standard
18219
18220 Frame pointer FSR2
18221 \end_inset
18222 </cell>
18223 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18224 \begin_inset Text
18225
18226 \layout Standard
18227
18228 8-bits
18229 \end_inset
18230 </cell>
18231 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18232 \begin_inset Text
18233
18234 \layout Standard
18235
18236 16-bits
18237 \end_inset
18238 </cell>
18239 </row>
18240 </lyxtabular>
18241
18242 \end_inset
18243
18244
18245 \layout Standard
18246
18247
18248 \noun on
18249 Large
18250 \noun default
18251 stack model is currently not working properly throughout the code generator.
18252  So its use is not advised.
18253  Also there are some other points that need special care:
18254 \newline
18255
18256 \layout Enumerate
18257
18258 Do not create stack sections with size more than one physical bank (that
18259  is 256 bytes)
18260 \layout Enumerate
18261
18262 Stack sections should no cross physical bank limits (i.e.
18263  #pragma stack 0x50 0x100)
18264 \layout Standard
18265
18266 These limitations are caused by the fact that only FSRxL is modified when
18267  using SMALL stack model, so no more than 256 bytes of stack can be used.
18268  This problem will disappear after LARGE model is fully implemented.
18269 \layout Subsection
18270
18271 Functions
18272 \layout Standard
18273
18274 In addition to the standard SDCC function keywords, PIC16 port makes available
18275  two more:
18276 \layout List
18277 \labelwidthstring 00.00.0000
18278
18279 wparam Use the WREG to pass one byte of the first function argument.
18280  This improves speed but you may not use this for functions with arguments
18281  that are called via function pointers, otherwise the first byte of the
18282  first parameter will get lost.
18283  Usage:
18284 \layout LyX-Code
18285
18286 void func_wparam(int a) wparam
18287 \layout LyX-Code
18288
18289 {
18290 \layout LyX-Code
18291
18292     /* WREG hold the lower part of a */
18293 \layout LyX-Code
18294
18295     /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
18296  */
18297 \layout LyX-Code
18298
18299 ...
18300 \layout LyX-Code
18301
18302 }
18303 \layout Standard
18304
18305 This keyword replaces the deprecated wparam pragma.
18306 \layout List
18307 \labelwidthstring 00.00.0000
18308
18309 shadowregs When entering/exiting an ISR, it is possible to take advantage
18310  of the PIC18F hardware shadow registers which hold the values of WREG,
18311  STATUS and BSR registers.
18312  This can be done by adding the keyword
18313 \emph on
18314 shadowregs
18315 \emph default
18316  before the
18317 \emph on
18318 interrupt
18319 \emph default
18320  keyword in the function's header.
18321 \layout LyX-Code
18322
18323 void isr_shadow(void) shadowregs interrupt 1
18324 \layout LyX-Code
18325
18326 {
18327 \layout LyX-Code
18328
18329 ...
18330 \layout LyX-Code
18331
18332 }
18333 \layout Standard
18334
18335
18336 \emph on
18337 shadowregs
18338 \emph default
18339  instructs the code generator not to store/restore WREG, STATUS, BSR when
18340  entering/exiting the ISR.
18341 \layout Subsection
18342
18343 Function return values
18344 \layout Standard
18345
18346 Return values from functions are placed to the appropriate registers following
18347  a modified Microchip policy optimized for SDCC.
18348  The following table shows these registers:
18349 \layout Standard
18350 \align center
18351
18352 \begin_inset  Tabular
18353 <lyxtabular version="3" rows="6" columns="2">
18354 <features>
18355 <column alignment="center" valignment="top" leftline="true" width="0">
18356 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18357 <row topline="true" bottomline="true">
18358 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18359 \begin_inset Text
18360
18361 \layout Standard
18362
18363 size
18364 \end_inset
18365 </cell>
18366 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18367 \begin_inset Text
18368
18369 \layout Standard
18370
18371 destination register
18372 \end_inset
18373 </cell>
18374 </row>
18375 <row topline="true">
18376 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18377 \begin_inset Text
18378
18379 \layout Standard
18380
18381 8 bits
18382 \end_inset
18383 </cell>
18384 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18385 \begin_inset Text
18386
18387 \layout Standard
18388
18389 WREG
18390 \end_inset
18391 </cell>
18392 </row>
18393 <row topline="true">
18394 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18395 \begin_inset Text
18396
18397 \layout Standard
18398
18399 16 bits
18400 \end_inset
18401 </cell>
18402 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18403 \begin_inset Text
18404
18405 \layout Standard
18406
18407 PRODL:WREG
18408 \end_inset
18409 </cell>
18410 </row>
18411 <row topline="true">
18412 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18413 \begin_inset Text
18414
18415 \layout Standard
18416
18417 24 bits
18418 \end_inset
18419 </cell>
18420 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18421 \begin_inset Text
18422
18423 \layout Standard
18424
18425 PRODH:PRODL:WREG
18426 \end_inset
18427 </cell>
18428 </row>
18429 <row topline="true">
18430 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18431 \begin_inset Text
18432
18433 \layout Standard
18434
18435 32 bits
18436 \end_inset
18437 </cell>
18438 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18439 \begin_inset Text
18440
18441 \layout Standard
18442
18443 FSR0L:PRODH:PRODL:WREG
18444 \end_inset
18445 </cell>
18446 </row>
18447 <row topline="true" bottomline="true">
18448 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18449 \begin_inset Text
18450
18451 \layout Standard
18452
18453 >32 bits
18454 \end_inset
18455 </cell>
18456 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18457 \begin_inset Text
18458
18459 \layout Standard
18460
18461 on stack, FSR0 points to the beginning
18462 \end_inset
18463 </cell>
18464 </row>
18465 </lyxtabular>
18466
18467 \end_inset
18468
18469
18470 \layout Subsection
18471
18472 Interrupts
18473 \layout Standard
18474
18475 An interrupt servive routine (ISR) is declared using the
18476 \emph on
18477 interrupt
18478 \emph default
18479  keyword.
18480 \layout LyX-Code
18481
18482 void isr(void) interrupt
18483 \emph on
18484 n
18485 \layout LyX-Code
18486
18487 {
18488 \layout LyX-Code
18489
18490 ...
18491 \layout LyX-Code
18492
18493 }
18494 \layout Standard
18495
18496
18497 \emph on
18498 n
18499 \emph default
18500  is the interrupt number, which for PIC18F devices can be:
18501 \layout Standard
18502 \align center
18503
18504 \begin_inset  Tabular
18505 <lyxtabular version="3" rows="4" columns="3">
18506 <features>
18507 <column alignment="center" valignment="top" leftline="true" width="0">
18508 <column alignment="center" valignment="top" leftline="true" width="0">
18509 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18510 <row topline="true" bottomline="true">
18511 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18512 \begin_inset Text
18513
18514 \layout Standard
18515
18516
18517 \emph on
18518 n
18519 \end_inset
18520 </cell>
18521 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18522 \begin_inset Text
18523
18524 \layout Standard
18525
18526 Interrupt Vector
18527 \end_inset
18528 </cell>
18529 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18530 \begin_inset Text
18531
18532 \layout Standard
18533
18534 Interrupt Vector Address
18535 \end_inset
18536 </cell>
18537 </row>
18538 <row topline="true">
18539 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18540 \begin_inset Text
18541
18542 \layout Standard
18543
18544 0
18545 \end_inset
18546 </cell>
18547 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18548 \begin_inset Text
18549
18550 \layout Standard
18551
18552 RESET vector
18553 \end_inset
18554 </cell>
18555 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18556 \begin_inset Text
18557
18558 \layout Standard
18559
18560 0x000000
18561 \end_inset
18562 </cell>
18563 </row>
18564 <row topline="true">
18565 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18566 \begin_inset Text
18567
18568 \layout Standard
18569
18570
18571 \family roman
18572 \series medium
18573 \shape up
18574 \size normal
18575 \emph off
18576 \bar no
18577 \noun off
18578 \color none
18579 1
18580 \end_inset
18581 </cell>
18582 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18583 \begin_inset Text
18584
18585 \layout Standard
18586
18587
18588 \family roman
18589 \series medium
18590 \shape up
18591 \size normal
18592 \emph off
18593 \bar no
18594 \noun off
18595 \color none
18596 HIGH priority interrupts
18597 \end_inset
18598 </cell>
18599 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18600 \begin_inset Text
18601
18602 \layout Standard
18603
18604 0x000008
18605 \end_inset
18606 </cell>
18607 </row>
18608 <row topline="true" bottomline="true">
18609 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18610 \begin_inset Text
18611
18612 \layout Standard
18613
18614 2
18615 \end_inset
18616 </cell>
18617 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18618 \begin_inset Text
18619
18620 \layout Standard
18621
18622 LOW priority interrupts
18623 \end_inset
18624 </cell>
18625 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18626 \begin_inset Text
18627
18628 \layout Standard
18629
18630 0x000018
18631 \end_inset
18632 </cell>
18633 </row>
18634 </lyxtabular>
18635
18636 \end_inset
18637
18638
18639 \layout Standard
18640
18641 When generating assembly code for ISR the code generator places a
18642 \noun on
18643 goto
18644 \noun default
18645 instruction at the
18646 \emph on
18647 Interrupt Vector Address
18648 \emph default
18649  which points at the genetated ISR.
18650  This single GOTO instruction is part of an automatically generated
18651 \emph on
18652 interrupt entry point
18653 \emph default
18654  function.
18655  The actuall ISR code is placed as normally would in the code space.
18656  Upon interrupt request, the GOTO instruction is executed which jumps to
18657  the ISR code.
18658  When declaring interrupt functions as _naked this GOTO instruction is
18659 \series bold
18660 not
18661 \series default
18662  generated.
18663  The whole interrupt functions is therefore placed at the Interrupt Vector
18664  Address of the specific interrupt.
18665  This is not a problem for the LOW priority interrupts, but it is a problem
18666  for the RESET and the HIGH priority interrupts because code may be written
18667  at the next interrupt´s vector address and cause undeterminate program
18668  behaviour if that interrupt is raised.
18669 \begin_inset Foot
18670 collapsed false
18671
18672 \layout Standard
18673
18674 This is not a problem when
18675 \layout Enumerate
18676
18677 this is a HIGH interrupt ISR and LOW interrupts are
18678 \emph on
18679 disabled
18680 \emph default
18681  or not used.
18682 \layout Enumerate
18683
18684 when the ISR is small enough not to reach the next interrupt´s vector address.
18685 \end_inset
18686
18687
18688 \layout Standard
18689
18690
18691 \emph on
18692 n
18693 \emph default
18694  is possible to be omitted.
18695  This way a function is generated similar to an ISR, but it is not assigned
18696  to any interrupt.
18697 \layout Standard
18698
18699 When entering an interrupt, currently the PIC16
18700 \begin_inset LatexCommand \index{PIC16}
18701
18702 \end_inset
18703
18704  port automatically saves the following registers:
18705 \layout Itemize
18706
18707 WREG
18708 \layout Itemize
18709
18710 STATUS
18711 \layout Itemize
18712
18713 BSR
18714 \layout Itemize
18715
18716 PROD (PRODL and PRODH)
18717 \layout Itemize
18718
18719 FSR0 (FSR0L and FSR0H)
18720 \layout Standard
18721
18722 These registers are restored upon return from the interrupt routine.
18723 \begin_inset Foot
18724 collapsed false
18725
18726 \layout Standard
18727
18728 NOTE that when the _naked attribute is specified for an interrupt routine,
18729  then NO registers are stored or restored.
18730 \end_inset
18731
18732
18733 \layout Subsection
18734
18735 Generic Pointers
18736 \layout Standard
18737
18738 Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
18739  There are 3 types of generic pointers currently implemented data, code
18740  and eeprom pointers.
18741  They are differentiated by the value of the 7th and 6th bits of the upper
18742  byte:
18743 \layout Standard
18744 \align center
18745
18746 \begin_inset  Tabular
18747 <lyxtabular version="3" rows="5" columns="5">
18748 <features>
18749 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18750 <column alignment="center" valignment="top" width="0">
18751 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18752 <column alignment="center" valignment="top" width="0">
18753 <column alignment="left" valignment="top" rightline="true" width="0">
18754 <row topline="true" bottomline="true">
18755 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18756 \begin_inset Text
18757
18758 \layout Standard
18759
18760 pointer type
18761 \end_inset
18762 </cell>
18763 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18764 \begin_inset Text
18765
18766 \layout Standard
18767
18768 7th bit
18769 \end_inset
18770 </cell>
18771 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18772 \begin_inset Text
18773
18774 \layout Standard
18775
18776 6th bit
18777 \end_inset
18778 </cell>
18779 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18780 \begin_inset Text
18781
18782 \layout Standard
18783
18784 rest of the pointer
18785 \end_inset
18786 </cell>
18787 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18788 \begin_inset Text
18789
18790 \layout Standard
18791
18792 descrption
18793 \end_inset
18794 </cell>
18795 </row>
18796 <row topline="true" bottomline="true">
18797 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18798 \begin_inset Text
18799
18800 \layout Standard
18801
18802 data
18803 \end_inset
18804 </cell>
18805 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18806 \begin_inset Text
18807
18808 \layout Standard
18809
18810 1
18811 \end_inset
18812 </cell>
18813 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18814 \begin_inset Text
18815
18816 \layout Standard
18817
18818 0
18819 \end_inset
18820 </cell>
18821 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18822 \begin_inset Text
18823
18824 \layout Standard
18825
18826
18827 \family typewriter
18828 \shape slanted
18829 \emph on
18830 uuuuuu uuuuxxxx xxxxxxxx
18831 \end_inset
18832 </cell>
18833 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18834 \begin_inset Text
18835
18836 \layout Standard
18837
18838 a 12-bit data pointer in data RAM memory
18839 \end_inset
18840 </cell>
18841 </row>
18842 <row bottomline="true">
18843 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18844 \begin_inset Text
18845
18846 \layout Standard
18847
18848 code
18849 \end_inset
18850 </cell>
18851 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18852 \begin_inset Text
18853
18854 \layout Standard
18855
18856 0
18857 \end_inset
18858 </cell>
18859 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18860 \begin_inset Text
18861
18862 \layout Standard
18863
18864 0
18865 \end_inset
18866 </cell>
18867 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18868 \begin_inset Text
18869
18870 \layout Standard
18871
18872
18873 \family typewriter
18874 \shape slanted
18875 \emph on
18876 uxxxxx xxxxxxxx xxxxxxxx
18877 \end_inset
18878 </cell>
18879 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18880 \begin_inset Text
18881
18882 \layout Standard
18883
18884 a 21-bit code pointer in FLASH memory
18885 \end_inset
18886 </cell>
18887 </row>
18888 <row bottomline="true">
18889 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18890 \begin_inset Text
18891
18892 \layout Standard
18893
18894 eeprom
18895 \end_inset
18896 </cell>
18897 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18898 \begin_inset Text
18899
18900 \layout Standard
18901
18902 0
18903 \end_inset
18904 </cell>
18905 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18906 \begin_inset Text
18907
18908 \layout Standard
18909
18910 1
18911 \end_inset
18912 </cell>
18913 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18914 \begin_inset Text
18915
18916 \layout Standard
18917
18918
18919 \family typewriter
18920 \shape slanted
18921 \emph on
18922 uuuuuu uuuuuuxx xxxxxxxx
18923 \end_inset
18924 </cell>
18925 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18926 \begin_inset Text
18927
18928 \layout Standard
18929
18930 a 10-bit eeprom pointer in EEPROM memory
18931 \end_inset
18932 </cell>
18933 </row>
18934 <row bottomline="true">
18935 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18936 \begin_inset Text
18937
18938 \layout Standard
18939
18940 (unimplemented)
18941 \end_inset
18942 </cell>
18943 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18944 \begin_inset Text
18945
18946 \layout Standard
18947
18948 1
18949 \end_inset
18950 </cell>
18951 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18952 \begin_inset Text
18953
18954 \layout Standard
18955
18956 1
18957 \end_inset
18958 </cell>
18959 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18960 \begin_inset Text
18961
18962 \layout Standard
18963
18964
18965 \family typewriter
18966 \shape slanted
18967 \emph on
18968 xxxxxx xxxxxxxx xxxxxxxx
18969 \end_inset
18970 </cell>
18971 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18972 \begin_inset Text
18973
18974 \layout Standard
18975
18976 unimplemented pointer type
18977 \end_inset
18978 </cell>
18979 </row>
18980 </lyxtabular>
18981
18982 \end_inset
18983
18984
18985 \layout Standard
18986
18987 Generic pointer are read and written with a set of library functions which
18988  read/write 1, 2, 3, 4 bytes.
18989 \layout Subsection
18990
18991 PIC16 C Libraries
18992 \layout Subsubsection
18993
18994 Standard I/O Streams
18995 \layout Standard
18996
18997 In the
18998 \emph on
18999 stdio.h
19000 \emph default
19001  the type FILE is defined as:
19002 \layout LyX-Code
19003
19004 typedef char * FILE;
19005 \layout Standard
19006
19007 This type is the stream type implemented I/O in the PIC18F devices.
19008  Also the standard input and output streams are declared in stdio.h:
19009 \layout LyX-Code
19010
19011 extern FILE * stdin;
19012 \layout LyX-Code
19013
19014 extern FILE * stdout;
19015 \layout Standard
19016
19017 The FILE type is actually a generic pointer which defines one more type
19018  of generic pointers, the
19019 \emph on
19020 stream
19021 \emph default
19022 pointer.
19023  This new type has the format:
19024 \layout Standard
19025 \align center
19026
19027 \begin_inset  Tabular
19028 <lyxtabular version="3" rows="2" columns="7">
19029 <features>
19030 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19031 <column alignment="center" valignment="top" width="0">
19032 <column alignment="center" valignment="top" leftline="true" width="0">
19033 <column alignment="center" valignment="top" leftline="true" width="0">
19034 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19035 <column alignment="center" valignment="top" width="0">
19036 <column alignment="left" valignment="top" rightline="true" width="0">
19037 <row topline="true" bottomline="true">
19038 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19039 \begin_inset Text
19040
19041 \layout Standard
19042
19043 pointer type
19044 \end_inset
19045 </cell>
19046 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19047 \begin_inset Text
19048
19049 \layout Standard
19050
19051 <7:6>
19052 \end_inset
19053 </cell>
19054 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19055 \begin_inset Text
19056
19057 \layout Standard
19058
19059 <5>
19060 \end_inset
19061 </cell>
19062 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19063 \begin_inset Text
19064
19065 \layout Standard
19066
19067 <4>
19068 \end_inset
19069 </cell>
19070 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19071 \begin_inset Text
19072
19073 \layout Standard
19074
19075 <3:0>
19076 \end_inset
19077 </cell>
19078 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19079 \begin_inset Text
19080
19081 \layout Standard
19082
19083 rest of the pointer
19084 \end_inset
19085 </cell>
19086 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19087 \begin_inset Text
19088
19089 \layout Standard
19090
19091 descrption
19092 \end_inset
19093 </cell>
19094 </row>
19095 <row topline="true" bottomline="true">
19096 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19097 \begin_inset Text
19098
19099 \layout Standard
19100
19101 stream
19102 \end_inset
19103 </cell>
19104 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19105 \begin_inset Text
19106
19107 \layout Standard
19108
19109 00
19110 \end_inset
19111 </cell>
19112 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19113 \begin_inset Text
19114
19115 \layout Standard
19116
19117 1
19118 \end_inset
19119 </cell>
19120 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19121 \begin_inset Text
19122
19123 \layout Standard
19124
19125 0
19126 \end_inset
19127 </cell>
19128 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19129 \begin_inset Text
19130
19131 \layout Standard
19132
19133 nnnn
19134 \end_inset
19135 </cell>
19136 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19137 \begin_inset Text
19138
19139 \layout Standard
19140
19141
19142 \family typewriter
19143 \shape slanted
19144 \emph on
19145 uuuuuuuu uuuuuuuu
19146 \end_inset
19147 </cell>
19148 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19149 \begin_inset Text
19150
19151 \layout Standard
19152
19153 upper byte high nubble is 0x2n, the rest are zeroes
19154 \end_inset
19155 </cell>
19156 </row>
19157 </lyxtabular>
19158
19159 \end_inset
19160
19161
19162 \layout Standard
19163
19164 Currently implemented there are 3 types of streams defined:
19165 \layout Standard
19166 \align center
19167
19168 \begin_inset  Tabular
19169 <lyxtabular version="3" rows="4" columns="4">
19170 <features>
19171 <column alignment="center" valignment="top" leftline="true" width="0">
19172 <column alignment="center" valignment="top" leftline="true" width="0">
19173 <column alignment="center" valignment="top" leftline="true" width="0">
19174 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19175 <row topline="true" bottomline="true">
19176 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19177 \begin_inset Text
19178
19179 \layout Standard
19180
19181 stream type
19182 \end_inset
19183 </cell>
19184 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19185 \begin_inset Text
19186
19187 \layout Standard
19188
19189 value
19190 \end_inset
19191 </cell>
19192 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19193 \begin_inset Text
19194
19195 \layout Standard
19196
19197 module
19198 \end_inset
19199 </cell>
19200 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19201 \begin_inset Text
19202
19203 \layout Standard
19204
19205 description
19206 \end_inset
19207 </cell>
19208 </row>
19209 <row topline="true">
19210 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19211 \begin_inset Text
19212
19213 \layout Standard
19214
19215 STREAM_USART
19216 \end_inset
19217 </cell>
19218 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19219 \begin_inset Text
19220
19221 \layout Standard
19222
19223
19224 \family typewriter
19225 0x200000UL
19226 \end_inset
19227 </cell>
19228 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19229 \begin_inset Text
19230
19231 \layout Standard
19232
19233 USART
19234 \end_inset
19235 </cell>
19236 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19237 \begin_inset Text
19238
19239 \layout Standard
19240
19241 Writes/Reads characters via the USART peripheral
19242 \end_inset
19243 </cell>
19244 </row>
19245 <row topline="true">
19246 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19247 \begin_inset Text
19248
19249 \layout Standard
19250
19251 STREAM_MSSP
19252 \end_inset
19253 </cell>
19254 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19255 \begin_inset Text
19256
19257 \layout Standard
19258
19259
19260 \family typewriter
19261 0x210000UL
19262 \end_inset
19263 </cell>
19264 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19265 \begin_inset Text
19266
19267 \layout Standard
19268
19269 MSSP
19270 \end_inset
19271 </cell>
19272 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19273 \begin_inset Text
19274
19275 \layout Standard
19276
19277 Writes/Reads characters via the MSSP peripheral
19278 \end_inset
19279 </cell>
19280 </row>
19281 <row topline="true" bottomline="true">
19282 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19283 \begin_inset Text
19284
19285 \layout Standard
19286
19287 STREAM_USER
19288 \end_inset
19289 </cell>
19290 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19291 \begin_inset Text
19292
19293 \layout Standard
19294
19295
19296 \family typewriter
19297 0x2f0000UL
19298 \end_inset
19299 </cell>
19300 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19301 \begin_inset Text
19302
19303 \layout Standard
19304
19305 (none)
19306 \end_inset
19307 </cell>
19308 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19309 \begin_inset Text
19310
19311 \layout Standard
19312
19313 Writes/Reads characters via used defined functions
19314 \end_inset
19315 </cell>
19316 </row>
19317 </lyxtabular>
19318
19319 \end_inset
19320
19321
19322 \layout Standard
19323
19324 The stream identifiers are declared as macros in the stdio.h header.
19325 \layout Standard
19326
19327 In the libc library there exist the functions that are used to write to
19328  each of the above streams.
19329  These are
19330 \layout List
19331 \labelwidthstring 00.00.0000
19332
19333 _
19334 \begin_inset ERT
19335 status Collapsed
19336
19337 \layout Standard
19338
19339 \backslash
19340 /
19341 \end_inset
19342
19343 _stream_usart_putchar writes a character at the USART stream
19344 \layout List
19345 \labelwidthstring 00.00.0000
19346
19347 _
19348 \begin_inset ERT
19349 status Collapsed
19350
19351 \layout Standard
19352
19353 \backslash
19354 /
19355 \end_inset
19356
19357 _stream_mssp_putchar writes a character at the MSSP stream
19358 \layout List
19359 \labelwidthstring 00.00.0000
19360
19361 putchar dummy function.
19362  This writes a character to a user specified manner.
19363 \layout Standard
19364
19365 In order to increase performance
19366 \emph on
19367 putchar
19368 \emph default
19369 is declared in stdio.h as having its parameter in WREG (it has the wparam
19370  keyword).
19371  In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
19372  in a user-friendly way.
19373
19374 \emph on
19375 arg
19376 \emph default
19377  is the name of the variable that holds the character to print.
19378  An example follows:
19379 \layout LyX-Code
19380
19381 #include <pic18fregs.h>
19382 \newline
19383 #include <stdio.h>
19384 \newline
19385
19386 \newline
19387 PUTCHAR( c )
19388 \layout LyX-Code
19389
19390 {
19391 \layout LyX-Code
19392
19393     PORTA = c;    /* dump character c to PORTA */
19394 \layout LyX-Code
19395
19396 }
19397 \newline
19398
19399 \newline
19400 void main(void)
19401 \layout LyX-Code
19402
19403 {
19404 \layout LyX-Code
19405
19406     stdout = STREAM_USER;    /* this is not necessery, since stdout points
19407 \layout LyX-Code
19408
19409                               * by default to STREAM_USER */
19410 \layout LyX-Code
19411
19412     printf (¨This is a printf test
19413 \backslash
19414 n¨);
19415 \layout LyX-Code
19416
19417 }
19418 \layout LyX-Code
19419
19420 \layout Subsubsection
19421
19422 Printing functions
19423 \layout Standard
19424
19425 PIC16 contains an implementation of the printf-family of functions.
19426  There exist the following functions:
19427 \layout LyX-Code
19428
19429 extern unsigned int sprintf(char *buf, char *fmt, ...);
19430 \layout LyX-Code
19431
19432 extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
19433 \layout LyX-Code
19434
19435 \layout LyX-Code
19436
19437 extern unsigned int printf(char *fmt, ...);
19438 \layout LyX-Code
19439
19440 extern unsigned int vprintf(char *fmt, va_lista ap);
19441 \layout LyX-Code
19442
19443 \layout LyX-Code
19444
19445 extern unsigned int fprintf(FILE *fp, char *fmt, ...);
19446 \layout LyX-Code
19447
19448 extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
19449 \layout Standard
19450
19451 For sprintf and vsprintf
19452 \emph on
19453 buf
19454 \emph default
19455 should normally be a data pointer where the resulting string will be placed.
19456  No range checking is done so the user should allocate the necessery buffer.
19457  For fprintf and vfprintf
19458 \emph on
19459 fp
19460 \emph default
19461  should be a stream pointer (i.e.
19462  stdout, STREAM_MSSP, etc...).
19463 \layout Subsubsection
19464
19465 Signals
19466 \layout Standard
19467
19468 The PIC18F family of microcontrollers supports a number of interrupt sources.
19469  A list of these interrupts is shown in the following table:
19470 \layout Standard
19471 \align center
19472
19473 \begin_inset  Tabular
19474 <lyxtabular version="3" rows="11" columns="4">
19475 <features>
19476 <column alignment="left" valignment="top" leftline="true" width="0">
19477 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19478 <column alignment="left" valignment="top" leftline="true" width="0">
19479 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19480 <row topline="true" bottomline="true">
19481 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19482 \begin_inset Text
19483
19484 \layout Standard
19485
19486 signal name
19487 \end_inset
19488 </cell>
19489 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19490 \begin_inset Text
19491
19492 \layout Standard
19493
19494 description
19495 \end_inset
19496 </cell>
19497 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19498 \begin_inset Text
19499
19500 \layout Standard
19501
19502 signal name
19503 \end_inset
19504 </cell>
19505 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19506 \begin_inset Text
19507
19508 \layout Standard
19509
19510 descritpion
19511 \end_inset
19512 </cell>
19513 </row>
19514 <row topline="true">
19515 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19516 \begin_inset Text
19517
19518 \layout Standard
19519
19520 SIG_RB
19521 \end_inset
19522 </cell>
19523 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19524 \begin_inset Text
19525
19526 \layout Standard
19527
19528 PORTB change interrupt
19529 \end_inset
19530 </cell>
19531 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19532 \begin_inset Text
19533
19534 \layout Standard
19535
19536 SIG_EE
19537 \end_inset
19538 </cell>
19539 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19540 \begin_inset Text
19541
19542 \layout Standard
19543
19544 EEPROM/FLASH write complete interrupt
19545 \end_inset
19546 </cell>
19547 </row>
19548 <row topline="true">
19549 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19550 \begin_inset Text
19551
19552 \layout Standard
19553
19554 SIG_INT0
19555 \end_inset
19556 </cell>
19557 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19558 \begin_inset Text
19559
19560 \layout Standard
19561
19562 INT0 external interrupt
19563 \end_inset
19564 </cell>
19565 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19566 \begin_inset Text
19567
19568 \layout Standard
19569
19570 SIG_BCOL
19571 \end_inset
19572 </cell>
19573 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19574 \begin_inset Text
19575
19576 \layout Standard
19577
19578 Bus collision interrupt
19579 \end_inset
19580 </cell>
19581 </row>
19582 <row topline="true">
19583 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19584 \begin_inset Text
19585
19586 \layout Standard
19587
19588 SIG_INT1
19589 \end_inset
19590 </cell>
19591 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19592 \begin_inset Text
19593
19594 \layout Standard
19595
19596 INT1 external interrupt
19597 \end_inset
19598 </cell>
19599 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19600 \begin_inset Text
19601
19602 \layout Standard
19603
19604 SIG_LVD
19605 \end_inset
19606 </cell>
19607 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19608 \begin_inset Text
19609
19610 \layout Standard
19611
19612 Low voltage detect interrupt
19613 \end_inset
19614 </cell>
19615 </row>
19616 <row topline="true">
19617 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19618 \begin_inset Text
19619
19620 \layout Standard
19621
19622 SIG_INT2
19623 \end_inset
19624 </cell>
19625 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19626 \begin_inset Text
19627
19628 \layout Standard
19629
19630 INT2 external interrupt
19631 \end_inset
19632 </cell>
19633 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19634 \begin_inset Text
19635
19636 \layout Standard
19637
19638 SIG_PSP
19639 \end_inset
19640 </cell>
19641 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19642 \begin_inset Text
19643
19644 \layout Standard
19645
19646 Parallel slave port interrupt
19647 \end_inset
19648 </cell>
19649 </row>
19650 <row topline="true">
19651 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19652 \begin_inset Text
19653
19654 \layout Standard
19655
19656 SIG_CCP1
19657 \end_inset
19658 </cell>
19659 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19660 \begin_inset Text
19661
19662 \layout Standard
19663
19664 CCP1 module interrupt
19665 \end_inset
19666 </cell>
19667 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19668 \begin_inset Text
19669
19670 \layout Standard
19671
19672 SIG_AD
19673 \end_inset
19674 </cell>
19675 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19676 \begin_inset Text
19677
19678 \layout Standard
19679
19680 AD convertion complete interrupt
19681 \end_inset
19682 </cell>
19683 </row>
19684 <row topline="true">
19685 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19686 \begin_inset Text
19687
19688 \layout Standard
19689
19690 SIG_CCP2
19691 \end_inset
19692 </cell>
19693 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19694 \begin_inset Text
19695
19696 \layout Standard
19697
19698 CCP2 module interrupt
19699 \end_inset
19700 </cell>
19701 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19702 \begin_inset Text
19703
19704 \layout Standard
19705
19706 SIG_RC
19707 \end_inset
19708 </cell>
19709 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19710 \begin_inset Text
19711
19712 \layout Standard
19713
19714 USART receive interrupt
19715 \end_inset
19716 </cell>
19717 </row>
19718 <row topline="true">
19719 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19720 \begin_inset Text
19721
19722 \layout Standard
19723
19724 SIG_TMR0
19725 \end_inset
19726 </cell>
19727 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19728 \begin_inset Text
19729
19730 \layout Standard
19731
19732 TMR0 overflow interrupt
19733 \end_inset
19734 </cell>
19735 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19736 \begin_inset Text
19737
19738 \layout Standard
19739
19740 SIG_TX
19741 \end_inset
19742 </cell>
19743 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19744 \begin_inset Text
19745
19746 \layout Standard
19747
19748 USART transmit interrupt
19749 \end_inset
19750 </cell>
19751 </row>
19752 <row topline="true">
19753 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19754 \begin_inset Text
19755
19756 \layout Standard
19757
19758 SIG_TMR1
19759 \end_inset
19760 </cell>
19761 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19762 \begin_inset Text
19763
19764 \layout Standard
19765
19766 TMR1 overflow interrupt
19767 \end_inset
19768 </cell>
19769 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19770 \begin_inset Text
19771
19772 \layout Standard
19773
19774 SIG_MSSP
19775 \end_inset
19776 </cell>
19777 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19778 \begin_inset Text
19779
19780 \layout Standard
19781
19782 SSP receive/transmit interrupt
19783 \end_inset
19784 </cell>
19785 </row>
19786 <row topline="true">
19787 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19788 \begin_inset Text
19789
19790 \layout Standard
19791
19792 SIG_TMR2
19793 \end_inset
19794 </cell>
19795 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19796 \begin_inset Text
19797
19798 \layout Standard
19799
19800 TMR2 matches PR2 interrupt
19801 \end_inset
19802 </cell>
19803 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19804 \begin_inset Text
19805
19806 \layout Standard
19807
19808 \end_inset
19809 </cell>
19810 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19811 \begin_inset Text
19812
19813 \layout Standard
19814
19815 \end_inset
19816 </cell>
19817 </row>
19818 <row topline="true" bottomline="true">
19819 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19820 \begin_inset Text
19821
19822 \layout Standard
19823
19824 SIG_TMR3
19825 \end_inset
19826 </cell>
19827 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19828 \begin_inset Text
19829
19830 \layout Standard
19831
19832 TMR3 overflow interrupt
19833 \end_inset
19834 </cell>
19835 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19836 \begin_inset Text
19837
19838 \layout Standard
19839
19840 \end_inset
19841 </cell>
19842 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19843 \begin_inset Text
19844
19845 \layout Standard
19846
19847 \end_inset
19848 </cell>
19849 </row>
19850 </lyxtabular>
19851
19852 \end_inset
19853
19854
19855 \layout Standard
19856
19857 The prototypes for these names are defined in the header file
19858 \emph on
19859 signal.h
19860 \emph default
19861  .
19862 \layout Standard
19863
19864 In order to simplify signal handling, a number of macros is provided:
19865 \layout List
19866 \labelwidthstring 00.00.0000
19867
19868 DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
19869  high priority interrupts.
19870
19871 \emph on
19872 name
19873 \emph default
19874  is the function name to use.
19875 \layout List
19876 \labelwidthstring 00.00.0000
19877
19878 DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
19879  low priority interrupt.
19880
19881 \emph on
19882 name
19883 \emph default
19884  is the function name to use.
19885 \layout List
19886 \labelwidthstring 00.00.0000
19887
19888 DEF_HANDLER(sig,handler) define a handler for signal
19889 \emph on
19890 sig.
19891 \layout List
19892 \labelwidthstring 00.00.0000
19893
19894 END_DEF end the declaration of the dispatch table.
19895 \layout Standard
19896
19897 Additionally there are two more macros to simplify the declaration of the
19898  signal handler:
19899 \layout List
19900 \labelwidthstring 00.00.0000
19901
19902
19903 \series medium
19904 SIGHANDLER(handler)
19905 \series default
19906 this declares the function prototype for the
19907 \emph on
19908 handler
19909 \emph default
19910  function.
19911 \layout List
19912 \labelwidthstring 00.00.0000
19913
19914 SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
19915 \layout Standard
19916
19917 An example of using the macros above is shown below:
19918 \layout LyX-Code
19919
19920 #include <pic18fregs.h>
19921 \layout LyX-Code
19922
19923 #include <signal.h>
19924 \newline
19925
19926 \newline
19927 DEF_INTHIGH(high_int)
19928 \layout LyX-Code
19929
19930 DEF_HANDLER(SIG_TMR0, _tmr0_handler)
19931 \layout LyX-Code
19932
19933 DEF_HANDLER(SIG_BCOL, _bcol_handler)
19934 \layout LyX-Code
19935
19936 END_DEF
19937 \newline
19938
19939 \newline
19940 SIGHANDLER(_tmr0_handler)
19941 \layout LyX-Code
19942
19943 {
19944 \layout LyX-Code
19945
19946   /* action to be taken when timer 0 overflows */
19947 \layout LyX-Code
19948
19949 }
19950 \newline
19951
19952 \newline
19953 SIGHANDLERNAKED(_bcol_handler)
19954 \layout LyX-Code
19955
19956 {
19957 \layout LyX-Code
19958
19959   _asm
19960 \layout LyX-Code
19961
19962     /* action to be taken when bus collision occurs */
19963 \layout LyX-Code
19964
19965     retfie
19966 \layout LyX-Code
19967
19968  _endasm;
19969 \layout LyX-Code
19970
19971 }
19972 \layout Standard
19973
19974
19975 \series bold
19976 NOTES:
19977 \series default
19978  Special care should be taken when using the above scheme:
19979 \layout Itemize
19980
19981 do not place a colon (;) at the end of the DEF_* and END_DEF macros.
19982 \layout Itemize
19983
19984 when declaring SIGHANDLERNAKED handler never forget to use
19985 \emph on
19986 retfie
19987 \emph default
19988  for proper returning.
19989 \layout Subsection
19990
19991 PIC16 Port -- Tips
19992 \layout Standard
19993
19994 Here you can find some general tips for compiling programs with SDCC/pic16.
19995 \layout Subsubsection
19996
19997 Stack size
19998 \layout Standard
19999
20000 The default stack size (that is 64 bytes) probably is enough for many programs.
20001  One must take care that when there are many levels of function nesting,
20002  or there is excessive usage of stack, its size should be extended.
20003  An example of such a case is the printf/sprintf family of functions.
20004  If you encounter problems like not being able to print integers, then you
20005  need to set the stack size around the maximum (256 for small stack model).
20006  The following diagram shows what happens when calling printf to print an
20007  integer:
20008 \layout LyX-Code
20009
20010 printf () --> ltoa () --> ultoa () --> divschar ()
20011 \layout Standard
20012
20013 It is should be understood that stack is easily consumed when calling complicate
20014 d functions.
20015  Using command line arguments like -
20016 \begin_inset ERT
20017 status Collapsed
20018
20019 \layout Standard
20020
20021 \backslash
20022 /
20023 \end_inset
20024
20025 -fommit-frame-pointer might reduce stack usage by not creating unnecessery
20026  stack frames.
20027  Other ways to reduce stack usage may exist.
20028 \layout Chapter
20029
20030 Debugging with SDCDB
20031 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
20032
20033 \end_inset
20034
20035
20036 \begin_inset LatexCommand \index{sdcdb (debugger)}
20037
20038 \end_inset
20039
20040
20041 \layout Standard
20042
20043 SDCC is distributed with a source level debugger
20044 \begin_inset LatexCommand \index{Debugger}
20045
20046 \end_inset
20047
20048 .
20049  The debugger uses a command line interface, the command repertoire of the
20050  debugger has been kept as close to gdb
20051 \begin_inset LatexCommand \index{gdb}
20052
20053 \end_inset
20054
20055  (the GNU debugger) as possible.
20056  The configuration and build process is part of the standard compiler installati
20057 on, which also builds and installs the debugger in the target directory
20058  specified during configuration.
20059  The debugger allows you debug BOTH at the C source and at the ASM source
20060  level.
20061  Sdcdb is currently not available on Win32 platforms.
20062 \layout Section
20063
20064 Compiling for Debugging
20065 \layout Standard
20066
20067 The -
20068 \begin_inset ERT
20069 status Collapsed
20070
20071 \layout Standard
20072
20073 \backslash
20074 /
20075 \end_inset
20076
20077 -debug
20078 \begin_inset LatexCommand \index{-\/-debug}
20079
20080 \end_inset
20081
20082  option must be specified for all files for which debug information is to
20083  be generated.
20084  The complier generates a .adb file for each of these files.
20085  The linker creates the .cdb
20086 \begin_inset LatexCommand \index{<file>.cdb}
20087
20088 \end_inset
20089
20090  file from the .adb
20091 \begin_inset LatexCommand \index{<file>.adb}
20092
20093 \end_inset
20094
20095  files and the address information.
20096  This .cdb is used by the debugger.
20097 \layout Section
20098
20099 How the Debugger Works
20100 \layout Standard
20101
20102 When the -
20103 \begin_inset ERT
20104 status Collapsed
20105
20106 \layout Standard
20107
20108 \backslash
20109 /
20110 \end_inset
20111
20112 -debug option is specified the compiler generates extra symbol information
20113  some of which are put into the assembler source and some are put into the
20114  .adb file.
20115   Then the linker creates the .cdb file from the individual .adb files with
20116  the address information for the symbols.
20117  The debugger reads the symbolic information generated by the compiler &
20118  the address information generated by the linker.
20119  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
20120  execution is controlled by the debugger.
20121  When a command is issued for the debugger, it translates it into appropriate
20122  commands for the simulator.
20123 \layout Section
20124
20125 Starting the Debugger
20126 \layout Standard
20127
20128 The debugger can be started using the following command line.
20129  (Assume the file you are debugging has the file name foo).
20130 \newline
20131
20132 \newline
20133
20134 \family sans
20135 \series bold
20136 sdcdb foo
20137 \newline
20138
20139 \family default
20140 \series default
20141
20142 \newline
20143 The debugger will look for the following files.
20144 \layout Itemize
20145
20146 foo.c - the source file.
20147 \layout Itemize
20148
20149 foo.cdb - the debugger symbol information file.
20150 \layout Itemize
20151
20152 foo.ihx - the Intel hex format
20153 \begin_inset LatexCommand \index{Intel hex format}
20154
20155 \end_inset
20156
20157  object file.
20158 \layout Section
20159
20160 Command Line Options
20161 \layout Itemize
20162
20163 -
20164 \begin_inset ERT
20165 status Collapsed
20166
20167 \layout Standard
20168
20169 \backslash
20170 /
20171 \end_inset
20172
20173 -directory=<source file directory> this option can used to specify the directory
20174  search list.
20175  The debugger will look into the directory list specified for source, cdb
20176  & ihx files.
20177  The items in the directory list must be separated by ':', e.g.
20178  if the source files can be in the directories /home/src1 and /home/src2,
20179  the -
20180 \begin_inset ERT
20181 status Collapsed
20182
20183 \layout Standard
20184
20185 \backslash
20186 /
20187 \end_inset
20188
20189 -directory option should be -
20190 \begin_inset ERT
20191 status Collapsed
20192
20193 \layout Standard
20194
20195 \backslash
20196 /
20197 \end_inset
20198
20199 -directory=/home/src1:/home/src2.
20200  Note there can be no spaces in the option.
20201
20202 \layout Itemize
20203
20204 -cd <directory> - change to the <directory>.
20205 \layout Itemize
20206
20207 -fullname - used by GUI front ends.
20208 \layout Itemize
20209
20210 -cpu <cpu-type> - this argument is passed to the simulator please see the
20211  simulator docs for details.
20212 \layout Itemize
20213
20214 -X <Clock frequency > this options is passed to the simulator please see
20215  the simulator docs for details.
20216 \layout Itemize
20217
20218 -s <serial port file> passed to simulator see the simulator docs for details.
20219 \layout Itemize
20220
20221 -S <serial in,out> passed to simulator see the simulator docs for details.
20222 \layout Itemize
20223
20224 -k <port number> passed to simulator see the simulator docs for details.
20225 \layout Section
20226
20227 Debugger Commands
20228 \layout Standard
20229
20230 As mentioned earlier the command interface for the debugger has been deliberatel
20231 y kept as close the GNU debugger gdb, as possible.
20232  This will help the integration with existing graphical user interfaces
20233  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
20234  If you use a graphical user interface for the debugger you can skip this
20235  section.
20236 \layout Subsubsection*
20237
20238 break [line | file:line | function | file:function]
20239 \layout Standard
20240
20241 Set breakpoint at specified line or function:
20242 \newline
20243
20244 \newline
20245
20246 \family sans
20247 \series bold
20248 sdcdb>break 100
20249 \newline
20250 sdcdb>break foo.c:100
20251 \newline
20252 sdcdb>break funcfoo
20253 \newline
20254 sdcdb>break foo.c:funcfoo
20255 \layout Subsubsection*
20256
20257 clear [line | file:line | function | file:function ]
20258 \layout Standard
20259
20260 Clear breakpoint at specified line or function:
20261 \newline
20262
20263 \newline
20264
20265 \family sans
20266 \series bold
20267 sdcdb>clear 100
20268 \newline
20269 sdcdb>clear foo.c:100
20270 \newline
20271 sdcdb>clear funcfoo
20272 \newline
20273 sdcdb>clear foo.c:funcfoo
20274 \layout Subsubsection*
20275
20276 continue
20277 \layout Standard
20278
20279 Continue program being debugged, after breakpoint.
20280 \layout Subsubsection*
20281
20282 finish
20283 \layout Standard
20284
20285 Execute till the end of the current function.
20286 \layout Subsubsection*
20287
20288 delete [n]
20289 \layout Standard
20290
20291 Delete breakpoint number 'n'.
20292  If used without any option clear ALL user defined break points.
20293 \layout Subsubsection*
20294
20295 info [break | stack | frame | registers ]
20296 \layout Itemize
20297
20298 info break - list all breakpoints
20299 \layout Itemize
20300
20301 info stack - show the function call stack.
20302 \layout Itemize
20303
20304 info frame - show information about the current execution frame.
20305 \layout Itemize
20306
20307 info registers - show content of all registers.
20308 \layout Subsubsection*
20309
20310 step
20311 \layout Standard
20312
20313 Step program until it reaches a different source line.
20314  Note: pressing <return> repeats the last command.
20315 \layout Subsubsection*
20316
20317 next
20318 \layout Standard
20319
20320 Step program, proceeding through subroutine calls.
20321 \layout Subsubsection*
20322
20323 run
20324 \layout Standard
20325
20326 Start debugged program.
20327 \layout Subsubsection*
20328
20329 ptype variable
20330 \layout Standard
20331
20332 Print type information of the variable.
20333 \layout Subsubsection*
20334
20335 print variable
20336 \layout Standard
20337
20338 print value of variable.
20339 \layout Subsubsection*
20340
20341 file filename
20342 \layout Standard
20343
20344 load the given file name.
20345  Note this is an alternate method of loading file for debugging.
20346 \layout Subsubsection*
20347
20348 frame
20349 \layout Standard
20350
20351 print information about current frame.
20352 \layout Subsubsection*
20353
20354 set srcmode
20355 \layout Standard
20356
20357 Toggle between C source & assembly source.
20358 \layout Subsubsection*
20359
20360 ! simulator command
20361 \layout Standard
20362
20363 Send the string following '!' to the simulator, the simulator response is
20364  displayed.
20365  Note the debugger does not interpret the command being sent to the simulator,
20366  so if a command like 'go' is sent the debugger can loose its execution
20367  context and may display incorrect values.
20368 \layout Subsubsection*
20369
20370 quit
20371 \layout Standard
20372
20373 "Watch me now.
20374  Iam going Down.
20375  My name is Bobby Brown"
20376 \layout Section
20377
20378 Interfacing with DDD
20379 \layout Comment
20380
20381 The screenshot was converted from png to eps with:
20382 \begin_inset Quotes sld
20383 \end_inset
20384
20385 bmeps -c -e8f -p3 ddd_example.png >ddd_example.eps
20386 \begin_inset Quotes srd
20387 \end_inset
20388
20389  which produces a pretty compact eps file which is free from compression
20390  artifacts.
20391 \layout Comment
20392
20393 The screenshot was included in sdccman.lyx cvs version 1.120 but later removed
20394  as this broke the build system on Sourceforge (pdf-file was broken).
20395 \layout Standard
20396
20397 The .eps File
20398 \size footnotesize
20399
20400 \begin_inset LatexCommand \url{http://cvs.sourceforge.net/viewcvs.py/*checkout*/sdcc/sdcc/doc/figures/ddd_example.eps}
20401
20402 \end_inset
20403
20404
20405 \size default
20406  shows a screenshot of a debugging session with DDD
20407 \begin_inset LatexCommand \index{DDD (debugger)}
20408
20409 \end_inset
20410
20411  (Unix only) on a simulated 8032.
20412  The debugging session might not run as smoothly as the screenshot suggests.
20413  The debugger allows setting of breakpoints, displaying and changing variables,
20414  single stepping through C and assembler code.
20415
20416 \newline
20417 The source was compiled with
20418 \family sans
20419 \series bold
20420
20421 \newline
20422
20423 \newline
20424 sdcc -
20425 \family default
20426 \series default
20427
20428 \begin_inset ERT
20429 status Collapsed
20430
20431 \layout Standard
20432
20433 \backslash
20434 /
20435 \end_inset
20436
20437
20438 \family sans
20439 \series bold
20440 -debug ddd_example.c
20441 \family default
20442 \series default
20443
20444 \family sans
20445 \series bold
20446
20447 \newline
20448
20449 \family default
20450 \series default
20451
20452 \newline
20453 and DDD was invoked with
20454 \family sans
20455 \series bold
20456
20457 \newline
20458
20459 \newline
20460 ddd -debugger 'sdcdb -cpu 8032 ddd_example'
20461 \layout Section
20462
20463 Interfacing with XEmacs
20464 \begin_inset LatexCommand \index{XEmacs}
20465
20466 \end_inset
20467
20468
20469 \begin_inset LatexCommand \index{Emacs}
20470
20471 \end_inset
20472
20473
20474 \layout Standard
20475
20476 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
20477  sdcdb.el and sdcdbsrc.el.
20478  These two files can be found in the $(prefix)/bin directory after the installat
20479 ion is complete.
20480  These files need to be loaded into XEmacs for the interface to work.
20481  This can be done at XEmacs startup time by inserting the following into
20482  your '.xemacs' file (which can be found in your HOME directory):
20483 \newline
20484
20485 \newline
20486
20487 \family typewriter
20488 (load-file sdcdbsrc.el)
20489 \family default
20490
20491 \newline
20492
20493 \newline
20494 .xemacs is a lisp file so the () around the command is REQUIRED.
20495  The files can also be loaded dynamically while XEmacs is running, set the
20496  environment variable 'EMACSLOADPATH' to the installation bin directory
20497  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
20498  To start the interface enter the following command:
20499 \newline
20500
20501 \newline
20502
20503 \family sans
20504 \series bold
20505 ESC-x sdcdbsrc
20506 \family default
20507 \series default
20508
20509 \newline
20510
20511 \newline
20512 You will prompted to enter the file name to be debugged.
20513
20514 \newline
20515
20516 \newline
20517 The command line options that are passed to the simulator directly are bound
20518  to default values in the file sdcdbsrc.el.
20519  The variables are listed below, these values maybe changed as required.
20520 \layout Itemize
20521
20522 sdcdbsrc-cpu-type '51
20523 \layout Itemize
20524
20525 sdcdbsrc-frequency '11059200
20526 \layout Itemize
20527
20528 sdcdbsrc-serial nil
20529 \layout Standard
20530
20531 The following is a list of key mapping for the debugger interface.
20532 \layout Standard
20533
20534 \SpecialChar ~
20535
20536 \family typewriter
20537
20538 \newline
20539 ;;\SpecialChar ~
20540 Current Listing ::
20541 \newline
20542 ;;key\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 binding\SpecialChar ~
20557 \SpecialChar ~
20558 \SpecialChar ~
20559 \SpecialChar ~
20560 \SpecialChar ~
20561 \SpecialChar ~
20562 \SpecialChar ~
20563 \SpecialChar ~
20564 \SpecialChar ~
20565 \SpecialChar ~
20566 \SpecialChar ~
20567 \SpecialChar ~
20568 \SpecialChar ~
20569 \SpecialChar ~
20570 \SpecialChar ~
20571 \SpecialChar ~
20572 \SpecialChar ~
20573 \SpecialChar ~
20574 \SpecialChar ~
20575 \SpecialChar ~
20576 \SpecialChar ~
20577 \SpecialChar ~
20578 Comment
20579 \newline
20580 ;;---\SpecialChar ~
20581 \SpecialChar ~
20582 \SpecialChar ~
20583 \SpecialChar ~
20584 \SpecialChar ~
20585 \SpecialChar ~
20586 \SpecialChar ~
20587 \SpecialChar ~
20588 \SpecialChar ~
20589 \SpecialChar ~
20590 \SpecialChar ~
20591 \SpecialChar ~
20592 \SpecialChar ~
20593 \SpecialChar ~
20594 -------\SpecialChar ~
20595 \SpecialChar ~
20596 \SpecialChar ~
20597 \SpecialChar ~
20598 \SpecialChar ~
20599 \SpecialChar ~
20600 \SpecialChar ~
20601 \SpecialChar ~
20602 \SpecialChar ~
20603 \SpecialChar ~
20604 \SpecialChar ~
20605 \SpecialChar ~
20606 \SpecialChar ~
20607 \SpecialChar ~
20608 \SpecialChar ~
20609 \SpecialChar ~
20610 \SpecialChar ~
20611 \SpecialChar ~
20612 \SpecialChar ~
20613 \SpecialChar ~
20614 \SpecialChar ~
20615 \SpecialChar ~
20616 -------
20617 \newline
20618 ;;
20619 \newline
20620 ;;\SpecialChar ~
20621 n\SpecialChar ~
20622 \SpecialChar ~
20623 \SpecialChar ~
20624 \SpecialChar ~
20625 \SpecialChar ~
20626 \SpecialChar ~
20627 \SpecialChar ~
20628 \SpecialChar ~
20629 \SpecialChar ~
20630 \SpecialChar ~
20631 \SpecialChar ~
20632 \SpecialChar ~
20633 \SpecialChar ~
20634 \SpecialChar ~
20635 \SpecialChar ~
20636 sdcdb-next-from-src\SpecialChar ~
20637 \SpecialChar ~
20638 \SpecialChar ~
20639 \SpecialChar ~
20640 \SpecialChar ~
20641 \SpecialChar ~
20642 \SpecialChar ~
20643 \SpecialChar ~
20644 \SpecialChar ~
20645 \SpecialChar ~
20646 SDCDB next command
20647 \newline
20648 ;;\SpecialChar ~
20649 b\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 sdcdb-back-from-src\SpecialChar ~
20665 \SpecialChar ~
20666 \SpecialChar ~
20667 \SpecialChar ~
20668 \SpecialChar ~
20669 \SpecialChar ~
20670 \SpecialChar ~
20671 \SpecialChar ~
20672 \SpecialChar ~
20673 \SpecialChar ~
20674 SDCDB back command
20675 \newline
20676 ;;\SpecialChar ~
20677 c\SpecialChar ~
20678 \SpecialChar ~
20679 \SpecialChar ~
20680 \SpecialChar ~
20681 \SpecialChar ~
20682 \SpecialChar ~
20683 \SpecialChar ~
20684 \SpecialChar ~
20685 \SpecialChar ~
20686 \SpecialChar ~
20687 \SpecialChar ~
20688 \SpecialChar ~
20689 \SpecialChar ~
20690 \SpecialChar ~
20691 \SpecialChar ~
20692 sdcdb-cont-from-src\SpecialChar ~
20693 \SpecialChar ~
20694 \SpecialChar ~
20695 \SpecialChar ~
20696 \SpecialChar ~
20697 \SpecialChar ~
20698 \SpecialChar ~
20699 \SpecialChar ~
20700 \SpecialChar ~
20701 \SpecialChar ~
20702 SDCDB continue command
20703 \newline
20704 ;;\SpecialChar ~
20705 s\SpecialChar ~
20706 \SpecialChar ~
20707 \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 sdcdb-step-from-src\SpecialChar ~
20721 \SpecialChar ~
20722 \SpecialChar ~
20723 \SpecialChar ~
20724 \SpecialChar ~
20725 \SpecialChar ~
20726 \SpecialChar ~
20727 \SpecialChar ~
20728 \SpecialChar ~
20729 \SpecialChar ~
20730 SDCDB step command
20731 \newline
20732 ;;\SpecialChar ~
20733 ?\SpecialChar ~
20734 \SpecialChar ~
20735 \SpecialChar ~
20736 \SpecialChar ~
20737 \SpecialChar ~
20738 \SpecialChar ~
20739 \SpecialChar ~
20740 \SpecialChar ~
20741 \SpecialChar ~
20742 \SpecialChar ~
20743 \SpecialChar ~
20744 \SpecialChar ~
20745 \SpecialChar ~
20746 \SpecialChar ~
20747 \SpecialChar ~
20748 sdcdb-whatis-c-sexp\SpecialChar ~
20749 \SpecialChar ~
20750 \SpecialChar ~
20751 \SpecialChar ~
20752 \SpecialChar ~
20753 \SpecialChar ~
20754 \SpecialChar ~
20755 \SpecialChar ~
20756 \SpecialChar ~
20757 \SpecialChar ~
20758 SDCDB ptypecommand for data at
20759 \newline
20760 ;;\SpecialChar ~
20761 \SpecialChar ~
20762 \SpecialChar ~
20763 \SpecialChar ~
20764 \SpecialChar ~
20765 \SpecialChar ~
20766 \SpecialChar ~
20767 \SpecialChar ~
20768 \SpecialChar ~
20769 \SpecialChar ~
20770 \SpecialChar ~
20771 \SpecialChar ~
20772 \SpecialChar ~
20773 \SpecialChar ~
20774 \SpecialChar ~
20775 \SpecialChar ~
20776 \SpecialChar ~
20777 \SpecialChar ~
20778 \SpecialChar ~
20779 \SpecialChar ~
20780 \SpecialChar ~
20781 \SpecialChar ~
20782 \SpecialChar ~
20783 \SpecialChar ~
20784 \SpecialChar ~
20785 \SpecialChar ~
20786 \SpecialChar ~
20787 \SpecialChar ~
20788 \SpecialChar ~
20789 \SpecialChar ~
20790 \SpecialChar ~
20791 \SpecialChar ~
20792 \SpecialChar ~
20793 \SpecialChar ~
20794 \SpecialChar ~
20795 \SpecialChar ~
20796 \SpecialChar ~
20797 \SpecialChar ~
20798 \SpecialChar ~
20799 \SpecialChar ~
20800 \SpecialChar ~
20801 \SpecialChar ~
20802 \SpecialChar ~
20803 \SpecialChar ~
20804 \SpecialChar ~
20805 \SpecialChar ~
20806 \SpecialChar ~
20807 buffer point
20808 \newline
20809 ;;\SpecialChar ~
20810 x\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 sdcdbsrc-delete\SpecialChar ~
20826 \SpecialChar ~
20827 \SpecialChar ~
20828 \SpecialChar ~
20829 \SpecialChar ~
20830 \SpecialChar ~
20831 \SpecialChar ~
20832 \SpecialChar ~
20833 \SpecialChar ~
20834 \SpecialChar ~
20835 \SpecialChar ~
20836 \SpecialChar ~
20837 \SpecialChar ~
20838 \SpecialChar ~
20839 SDCDB Delete all breakpoints if no arg
20840 \newline
20841 ;;\SpecialChar ~
20842 \SpecialChar ~
20843 \SpecialChar ~
20844 \SpecialChar ~
20845 \SpecialChar ~
20846 \SpecialChar ~
20847 \SpecialChar ~
20848 \SpecialChar ~
20849 \SpecialChar ~
20850 \SpecialChar ~
20851 \SpecialChar ~
20852 \SpecialChar ~
20853 \SpecialChar ~
20854 \SpecialChar ~
20855 \SpecialChar ~
20856 \SpecialChar ~
20857 \SpecialChar ~
20858 \SpecialChar ~
20859 \SpecialChar ~
20860 \SpecialChar ~
20861 \SpecialChar ~
20862 \SpecialChar ~
20863 \SpecialChar ~
20864 \SpecialChar ~
20865 \SpecialChar ~
20866 \SpecialChar ~
20867 \SpecialChar ~
20868 \SpecialChar ~
20869 \SpecialChar ~
20870 \SpecialChar ~
20871 \SpecialChar ~
20872 \SpecialChar ~
20873 \SpecialChar ~
20874 \SpecialChar ~
20875 \SpecialChar ~
20876 \SpecialChar ~
20877 \SpecialChar ~
20878 \SpecialChar ~
20879 \SpecialChar ~
20880 \SpecialChar ~
20881 \SpecialChar ~
20882 \SpecialChar ~
20883 \SpecialChar ~
20884 \SpecialChar ~
20885 \SpecialChar ~
20886 \SpecialChar ~
20887 \SpecialChar ~
20888 given or delete arg (C-u arg x)
20889 \newline
20890 ;;\SpecialChar ~
20891 m\SpecialChar ~
20892 \SpecialChar ~
20893 \SpecialChar ~
20894 \SpecialChar ~
20895 \SpecialChar ~
20896 \SpecialChar ~
20897 \SpecialChar ~
20898 \SpecialChar ~
20899 \SpecialChar ~
20900 \SpecialChar ~
20901 \SpecialChar ~
20902 \SpecialChar ~
20903 \SpecialChar ~
20904 \SpecialChar ~
20905 \SpecialChar ~
20906 sdcdbsrc-frame\SpecialChar ~
20907 \SpecialChar ~
20908 \SpecialChar ~
20909 \SpecialChar ~
20910 \SpecialChar ~
20911 \SpecialChar ~
20912 \SpecialChar ~
20913 \SpecialChar ~
20914 \SpecialChar ~
20915 \SpecialChar ~
20916 \SpecialChar ~
20917 \SpecialChar ~
20918 \SpecialChar ~
20919 \SpecialChar ~
20920 \SpecialChar ~
20921 SDCDB Display current frame if no arg,
20922 \newline
20923 ;;\SpecialChar ~
20924 \SpecialChar ~
20925 \SpecialChar ~
20926 \SpecialChar ~
20927 \SpecialChar ~
20928 \SpecialChar ~
20929 \SpecialChar ~
20930 \SpecialChar ~
20931 \SpecialChar ~
20932 \SpecialChar ~
20933 \SpecialChar ~
20934 \SpecialChar ~
20935 \SpecialChar ~
20936 \SpecialChar ~
20937 \SpecialChar ~
20938 \SpecialChar ~
20939 \SpecialChar ~
20940 \SpecialChar ~
20941 \SpecialChar ~
20942 \SpecialChar ~
20943 \SpecialChar ~
20944 \SpecialChar ~
20945 \SpecialChar ~
20946 \SpecialChar ~
20947 \SpecialChar ~
20948 \SpecialChar ~
20949 \SpecialChar ~
20950 \SpecialChar ~
20951 \SpecialChar ~
20952 \SpecialChar ~
20953 \SpecialChar ~
20954 \SpecialChar ~
20955 \SpecialChar ~
20956 \SpecialChar ~
20957 \SpecialChar ~
20958 \SpecialChar ~
20959 \SpecialChar ~
20960 \SpecialChar ~
20961 \SpecialChar ~
20962 \SpecialChar ~
20963 \SpecialChar ~
20964 \SpecialChar ~
20965 \SpecialChar ~
20966 \SpecialChar ~
20967 \SpecialChar ~
20968 \SpecialChar ~
20969 \SpecialChar ~
20970 given or display frame arg
20971 \newline
20972 ;;\SpecialChar ~
20973 \SpecialChar ~
20974 \SpecialChar ~
20975 \SpecialChar ~
20976 \SpecialChar ~
20977 \SpecialChar ~
20978 \SpecialChar ~
20979 \SpecialChar ~
20980 \SpecialChar ~
20981 \SpecialChar ~
20982 \SpecialChar ~
20983 \SpecialChar ~
20984 \SpecialChar ~
20985 \SpecialChar ~
20986 \SpecialChar ~
20987 \SpecialChar ~
20988 \SpecialChar ~
20989 \SpecialChar ~
20990 \SpecialChar ~
20991 \SpecialChar ~
20992 \SpecialChar ~
20993 \SpecialChar ~
20994 \SpecialChar ~
20995 \SpecialChar ~
20996 \SpecialChar ~
20997 \SpecialChar ~
20998 \SpecialChar ~
20999 \SpecialChar ~
21000 \SpecialChar ~
21001 \SpecialChar ~
21002 \SpecialChar ~
21003 \SpecialChar ~
21004 \SpecialChar ~
21005 \SpecialChar ~
21006 \SpecialChar ~
21007 \SpecialChar ~
21008 \SpecialChar ~
21009 \SpecialChar ~
21010 \SpecialChar ~
21011 \SpecialChar ~
21012 \SpecialChar ~
21013 \SpecialChar ~
21014 \SpecialChar ~
21015 \SpecialChar ~
21016 \SpecialChar ~
21017 \SpecialChar ~
21018 \SpecialChar ~
21019 buffer point
21020 \newline
21021 ;;\SpecialChar ~
21022 !\SpecialChar ~
21023 \SpecialChar ~
21024 \SpecialChar ~
21025 \SpecialChar ~
21026 \SpecialChar ~
21027 \SpecialChar ~
21028 \SpecialChar ~
21029 \SpecialChar ~
21030 \SpecialChar ~
21031 \SpecialChar ~
21032 \SpecialChar ~
21033 \SpecialChar ~
21034 \SpecialChar ~
21035 \SpecialChar ~
21036 \SpecialChar ~
21037 sdcdbsrc-goto-sdcdb\SpecialChar ~
21038 \SpecialChar ~
21039 \SpecialChar ~
21040 \SpecialChar ~
21041 \SpecialChar ~
21042 \SpecialChar ~
21043 \SpecialChar ~
21044 \SpecialChar ~
21045 \SpecialChar ~
21046 \SpecialChar ~
21047 Goto the SDCDB output buffer
21048 \newline
21049 ;;\SpecialChar ~
21050 p\SpecialChar ~
21051 \SpecialChar ~
21052 \SpecialChar ~
21053 \SpecialChar ~
21054 \SpecialChar ~
21055 \SpecialChar ~
21056 \SpecialChar ~
21057 \SpecialChar ~
21058 \SpecialChar ~
21059 \SpecialChar ~
21060 \SpecialChar ~
21061 \SpecialChar ~
21062 \SpecialChar ~
21063 \SpecialChar ~
21064 \SpecialChar ~
21065 sdcdb-print-c-sexp\SpecialChar ~
21066 \SpecialChar ~
21067 \SpecialChar ~
21068 \SpecialChar ~
21069 \SpecialChar ~
21070 \SpecialChar ~
21071 \SpecialChar ~
21072 \SpecialChar ~
21073 \SpecialChar ~
21074 \SpecialChar ~
21075 \SpecialChar ~
21076 SDCDB print command for data at
21077 \newline
21078 ;;\SpecialChar ~
21079 \SpecialChar ~
21080 \SpecialChar ~
21081 \SpecialChar ~
21082 \SpecialChar ~
21083 \SpecialChar ~
21084 \SpecialChar ~
21085 \SpecialChar ~
21086 \SpecialChar ~
21087 \SpecialChar ~
21088 \SpecialChar ~
21089 \SpecialChar ~
21090 \SpecialChar ~
21091 \SpecialChar ~
21092 \SpecialChar ~
21093 \SpecialChar ~
21094 \SpecialChar ~
21095 \SpecialChar ~
21096 \SpecialChar ~
21097 \SpecialChar ~
21098 \SpecialChar ~
21099 \SpecialChar ~
21100 \SpecialChar ~
21101 \SpecialChar ~
21102 \SpecialChar ~
21103 \SpecialChar ~
21104 \SpecialChar ~
21105 \SpecialChar ~
21106 \SpecialChar ~
21107 \SpecialChar ~
21108 \SpecialChar ~
21109 \SpecialChar ~
21110 \SpecialChar ~
21111 \SpecialChar ~
21112 \SpecialChar ~
21113 \SpecialChar ~
21114 \SpecialChar ~
21115 \SpecialChar ~
21116 \SpecialChar ~
21117 \SpecialChar ~
21118 \SpecialChar ~
21119 \SpecialChar ~
21120 \SpecialChar ~
21121 \SpecialChar ~
21122 \SpecialChar ~
21123 \SpecialChar ~
21124 \SpecialChar ~
21125 buffer point
21126 \newline
21127 ;;\SpecialChar ~
21128 g\SpecialChar ~
21129 \SpecialChar ~
21130 \SpecialChar ~
21131 \SpecialChar ~
21132 \SpecialChar ~
21133 \SpecialChar ~
21134 \SpecialChar ~
21135 \SpecialChar ~
21136 \SpecialChar ~
21137 \SpecialChar ~
21138 \SpecialChar ~
21139 \SpecialChar ~
21140 \SpecialChar ~
21141 \SpecialChar ~
21142 \SpecialChar ~
21143 sdcdbsrc-goto-sdcdb\SpecialChar ~
21144 \SpecialChar ~
21145 \SpecialChar ~
21146 \SpecialChar ~
21147 \SpecialChar ~
21148 \SpecialChar ~
21149 \SpecialChar ~
21150 \SpecialChar ~
21151 \SpecialChar ~
21152 \SpecialChar ~
21153 Goto the SDCDB output buffer
21154 \newline
21155 ;;\SpecialChar ~
21156 t\SpecialChar ~
21157 \SpecialChar ~
21158 \SpecialChar ~
21159 \SpecialChar ~
21160 \SpecialChar ~
21161 \SpecialChar ~
21162 \SpecialChar ~
21163 \SpecialChar ~
21164 \SpecialChar ~
21165 \SpecialChar ~
21166 \SpecialChar ~
21167 \SpecialChar ~
21168 \SpecialChar ~
21169 \SpecialChar ~
21170 \SpecialChar ~
21171 sdcdbsrc-mode\SpecialChar ~
21172 \SpecialChar ~
21173 \SpecialChar ~
21174 \SpecialChar ~
21175 \SpecialChar ~
21176 \SpecialChar ~
21177 \SpecialChar ~
21178 \SpecialChar ~
21179 \SpecialChar ~
21180 \SpecialChar ~
21181 \SpecialChar ~
21182 \SpecialChar ~
21183 \SpecialChar ~
21184 \SpecialChar ~
21185 \SpecialChar ~
21186 \SpecialChar ~
21187 Toggles Sdcdbsrc mode (turns it off)
21188 \newline
21189 ;;
21190 \newline
21191 ;;\SpecialChar ~
21192 C-c\SpecialChar ~
21193 C-f\SpecialChar ~
21194 \SpecialChar ~
21195 \SpecialChar ~
21196 \SpecialChar ~
21197 \SpecialChar ~
21198 \SpecialChar ~
21199 \SpecialChar ~
21200 \SpecialChar ~
21201 \SpecialChar ~
21202 sdcdb-finish-from-src\SpecialChar ~
21203 \SpecialChar ~
21204 \SpecialChar ~
21205 \SpecialChar ~
21206 \SpecialChar ~
21207 \SpecialChar ~
21208 \SpecialChar ~
21209 \SpecialChar ~
21210 SDCDB finish command
21211 \newline
21212 ;;
21213 \newline
21214 ;;\SpecialChar ~
21215 C-x\SpecialChar ~
21216 SPC\SpecialChar ~
21217 \SpecialChar ~
21218 \SpecialChar ~
21219 \SpecialChar ~
21220 \SpecialChar ~
21221 \SpecialChar ~
21222 \SpecialChar ~
21223 \SpecialChar ~
21224 \SpecialChar ~
21225 sdcdb-break\SpecialChar ~
21226 \SpecialChar ~
21227 \SpecialChar ~
21228 \SpecialChar ~
21229 \SpecialChar ~
21230 \SpecialChar ~
21231 \SpecialChar ~
21232 \SpecialChar ~
21233 \SpecialChar ~
21234 \SpecialChar ~
21235 \SpecialChar ~
21236 \SpecialChar ~
21237 \SpecialChar ~
21238 \SpecialChar ~
21239 \SpecialChar ~
21240 \SpecialChar ~
21241 \SpecialChar ~
21242 \SpecialChar ~
21243 Set break for line with point
21244 \newline
21245 ;;\SpecialChar ~
21246 ESC\SpecialChar ~
21247 t\SpecialChar ~
21248 \SpecialChar ~
21249 \SpecialChar ~
21250 \SpecialChar ~
21251 \SpecialChar ~
21252 \SpecialChar ~
21253 \SpecialChar ~
21254 \SpecialChar ~
21255 \SpecialChar ~
21256 \SpecialChar ~
21257 \SpecialChar ~
21258 sdcdbsrc-mode\SpecialChar ~
21259 \SpecialChar ~
21260 \SpecialChar ~
21261 \SpecialChar ~
21262 \SpecialChar ~
21263 \SpecialChar ~
21264 \SpecialChar ~
21265 \SpecialChar ~
21266 \SpecialChar ~
21267 \SpecialChar ~
21268 \SpecialChar ~
21269 \SpecialChar ~
21270 \SpecialChar ~
21271 \SpecialChar ~
21272 \SpecialChar ~
21273 \SpecialChar ~
21274 Toggle Sdcdbsrc mode
21275 \newline
21276 ;;\SpecialChar ~
21277 ESC\SpecialChar ~
21278 m\SpecialChar ~
21279 \SpecialChar ~
21280 \SpecialChar ~
21281 \SpecialChar ~
21282 \SpecialChar ~
21283 \SpecialChar ~
21284 \SpecialChar ~
21285 \SpecialChar ~
21286 \SpecialChar ~
21287 \SpecialChar ~
21288 \SpecialChar ~
21289 sdcdbsrc-srcmode\SpecialChar ~
21290 \SpecialChar ~
21291 \SpecialChar ~
21292 \SpecialChar ~
21293 \SpecialChar ~
21294 \SpecialChar ~
21295 \SpecialChar ~
21296 \SpecialChar ~
21297 \SpecialChar ~
21298 \SpecialChar ~
21299 \SpecialChar ~
21300 \SpecialChar ~
21301 \SpecialChar ~
21302 Toggle list mode
21303 \newline
21304 ;;
21305 \newline
21306
21307 \layout Chapter
21308 \pagebreak_top
21309 TIPS
21310 \layout Standard
21311
21312 Here are a few guidelines that will help the compiler generate more efficient
21313  code, some of the tips are specific to this compiler others are generally
21314  good programming practice.
21315 \layout Itemize
21316
21317 Use the smallest data type to represent your data-value.
21318  If it is known in advance that the value is going to be less than 256 then
21319  use an 'unsigned char' instead of a 'short' or 'int'.
21320  Please note, that ANSI C requires both signed and unsigned chars to be
21321  promoted to 'signed int' before doing any operation.
21322  This promotion
21323 \begin_inset LatexCommand \index{type promotion}
21324
21325 \end_inset
21326
21327  can be omitted, if the result is the same.
21328  The effect of the promotion rules together with the sign-extension is often
21329  surprising:
21330 \begin_deeper
21331 \layout Verse
21332
21333
21334 \family typewriter
21335 unsigned char uc = 0xfe;
21336 \newline
21337 if (uc * uc < 0) /* this is true! */
21338 \newline
21339 {
21340 \newline
21341 \SpecialChar ~
21342 \SpecialChar ~
21343 \SpecialChar ~
21344 \SpecialChar ~
21345 ....
21346 \newline
21347 }
21348 \layout Standard
21349
21350
21351 \family typewriter
21352 uc * uc
21353 \family default
21354  is evaluated as
21355 \family typewriter
21356 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
21357 \family default
21358 .
21359
21360 \newline
21361 Another one:
21362 \layout Verse
21363
21364
21365 \family typewriter
21366 (unsigned char) -12 / (signed char) -3 = ...
21367 \layout Standard
21368
21369 No, the result is not 4:
21370 \layout Verse
21371
21372
21373 \family typewriter
21374 (int) (unsigned char) -12 / (int) (signed char) -3 =
21375 \newline
21376 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
21377 \newline
21378 (int) 0x00f4 / (int) 0xfffd =
21379 \newline
21380 (int) 0x00f4 / (int) 0xfffd =
21381 \newline
21382 (int) 244 / (int) -3 =
21383 \newline
21384 (int) -81 = (int) 0xffaf;
21385 \layout Standard
21386
21387 Don't complain, that gcc gives you a different result.
21388  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
21389  Therefore the results are different.
21390 \newline
21391 From
21392 \begin_inset Quotes sld
21393 \end_inset
21394
21395 comp.lang.c FAQ
21396 \begin_inset Quotes srd
21397 \end_inset
21398
21399 :
21400 \layout Quote
21401
21402 If well-defined overflow characteristics are important and negative values
21403  are not, or if you want to steer clear of sign-extension problems when
21404  manipulating bits or bytes, use one of the corresponding unsigned types.
21405  (Beware when mixing signed and unsigned values in expressions, though.)
21406 \newline
21407 Although character types (especially unsigned char) can be used as "tiny"
21408  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
21409 ble sign extension and increased code size.
21410 \end_deeper
21411 \layout Itemize
21412
21413 Use unsigned when it is known in advance that the value is not going to
21414  be negative.
21415  This helps especially if you are doing division or multiplication, bit-shifting
21416  or are using an array index.
21417 \layout Itemize
21418
21419 NEVER jump into a LOOP.
21420 \layout Itemize
21421
21422 Declare the variables to be local
21423 \begin_inset LatexCommand \index{local variables}
21424
21425 \end_inset
21426
21427  whenever possible, especially loop control variables (induction).
21428 \layout Itemize
21429
21430 Since the compiler does not always do implicit integral promotion, the programme
21431 r should do an explicit cast when integral promotion is required.
21432 \layout Itemize
21433
21434 Reducing the size of division, multiplication & modulus operations can reduce
21435  code size substantially.
21436  Take the following code for example.
21437 \begin_deeper
21438 \layout Verse
21439
21440
21441 \family typewriter
21442 foobar(unsigned int p1, unsigned char ch)
21443 \newline
21444 {
21445 \newline
21446 \SpecialChar ~
21447 \SpecialChar ~
21448 \SpecialChar ~
21449 \SpecialChar ~
21450 unsigned char ch1 = p1 % ch ;
21451 \newline
21452 \SpecialChar ~
21453 \SpecialChar ~
21454 \SpecialChar ~
21455 \SpecialChar ~
21456 ....
21457 \newline
21458 }
21459 \layout Standard
21460
21461 For the modulus operation the variable ch will be promoted to unsigned int
21462  first then the modulus operation will be performed (this will lead to a
21463  call to support routine _moduint()), and the result will be casted to a
21464  char.
21465  If the code is changed to
21466 \layout Verse
21467
21468
21469 \family typewriter
21470 foobar(unsigned int p1, unsigned char ch)
21471 \newline
21472 {
21473 \newline
21474 \SpecialChar ~
21475 \SpecialChar ~
21476 \SpecialChar ~
21477 \SpecialChar ~
21478 unsigned char ch1 = (unsigned char)p1 % ch ;
21479 \newline
21480 \SpecialChar ~
21481 \SpecialChar ~
21482 \SpecialChar ~
21483 \SpecialChar ~
21484 ....
21485 \newline
21486 }
21487 \layout Standard
21488
21489 It would substantially reduce the code generated (future versions of the
21490  compiler will be smart enough to detect such optimization opportunities).
21491 \end_deeper
21492 \layout Itemize
21493
21494 Have a look at the assembly listing to get a
21495 \begin_inset Quotes sld
21496 \end_inset
21497
21498 feeling
21499 \begin_inset Quotes srd
21500 \end_inset
21501
21502  for the code generation.
21503 \layout Section
21504
21505 Tools
21506 \begin_inset LatexCommand \index{Tools}
21507
21508 \end_inset
21509
21510  included in the distribution
21511 \layout Standard
21512 \align center
21513
21514 \begin_inset  Tabular
21515 <lyxtabular version="3" rows="12" columns="3">
21516 <features>
21517 <column alignment="center" valignment="top" leftline="true" width="0pt">
21518 <column alignment="center" valignment="top" leftline="true" width="0pt">
21519 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
21520 <row topline="true" bottomline="true">
21521 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21522 \begin_inset Text
21523
21524 \layout Standard
21525
21526 Name
21527 \end_inset
21528 </cell>
21529 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21530 \begin_inset Text
21531
21532 \layout Standard
21533
21534 Purpose
21535 \end_inset
21536 </cell>
21537 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21538 \begin_inset Text
21539
21540 \layout Standard
21541
21542 Directory
21543 \end_inset
21544 </cell>
21545 </row>
21546 <row topline="true">
21547 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21548 \begin_inset Text
21549
21550 \layout Standard
21551
21552 uCsim
21553 \end_inset
21554 </cell>
21555 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21556 \begin_inset Text
21557
21558 \layout Standard
21559
21560 Simulator for various architectures
21561 \end_inset
21562 </cell>
21563 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21564 \begin_inset Text
21565
21566 \layout Standard
21567
21568 sdcc/sim/ucsim
21569 \end_inset
21570 </cell>
21571 </row>
21572 <row topline="true">
21573 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21574 \begin_inset Text
21575
21576 \layout Standard
21577
21578 keil2sdcc.pl
21579 \end_inset
21580 </cell>
21581 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21582 \begin_inset Text
21583
21584 \layout Standard
21585
21586 header file conversion
21587 \end_inset
21588 </cell>
21589 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21590 \begin_inset Text
21591
21592 \layout Standard
21593
21594 sdcc/support/scripts
21595 \end_inset
21596 </cell>
21597 </row>
21598 <row topline="true">
21599 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21600 \begin_inset Text
21601
21602 \layout Standard
21603
21604 mh2h.c
21605 \end_inset
21606 </cell>
21607 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21608 \begin_inset Text
21609
21610 \layout Standard
21611
21612 header file conversion
21613 \end_inset
21614 </cell>
21615 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21616 \begin_inset Text
21617
21618 \layout Standard
21619
21620 sdcc/support/scripts
21621 \end_inset
21622 </cell>
21623 </row>
21624 <row topline="true">
21625 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21626 \begin_inset Text
21627
21628 \layout Standard
21629
21630 as-gbz80
21631 \end_inset
21632 </cell>
21633 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21634 \begin_inset Text
21635
21636 \layout Standard
21637
21638 Assembler
21639 \end_inset
21640 </cell>
21641 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21642 \begin_inset Text
21643
21644 \layout Standard
21645
21646
21647 \family roman
21648 \series medium
21649 \shape up
21650 \size normal
21651 \emph off
21652 \bar no
21653 \noun off
21654 \color none
21655 sdcc/bin
21656 \end_inset
21657 </cell>
21658 </row>
21659 <row topline="true">
21660 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21661 \begin_inset Text
21662
21663 \layout Standard
21664
21665 as-z80
21666 \end_inset
21667 </cell>
21668 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21669 \begin_inset Text
21670
21671 \layout Standard
21672
21673 Assembler
21674 \end_inset
21675 </cell>
21676 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21677 \begin_inset Text
21678
21679 \layout Standard
21680
21681
21682 \family roman
21683 \series medium
21684 \shape up
21685 \size normal
21686 \emph off
21687 \bar no
21688 \noun off
21689 \color none
21690 sdcc/bin
21691 \end_inset
21692 </cell>
21693 </row>
21694 <row topline="true">
21695 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21696 \begin_inset Text
21697
21698 \layout Standard
21699
21700 asx8051
21701 \end_inset
21702 </cell>
21703 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21704 \begin_inset Text
21705
21706 \layout Standard
21707
21708 Assembler
21709 \end_inset
21710 </cell>
21711 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21712 \begin_inset Text
21713
21714 \layout Standard
21715
21716
21717 \family roman
21718 \series medium
21719 \shape up
21720 \size normal
21721 \emph off
21722 \bar no
21723 \noun off
21724 \color none
21725 sdcc/bin
21726 \end_inset
21727 </cell>
21728 </row>
21729 <row topline="true">
21730 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21731 \begin_inset Text
21732
21733 \layout Standard
21734
21735 sdcdb
21736 \end_inset
21737 </cell>
21738 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21739 \begin_inset Text
21740
21741 \layout Standard
21742
21743 Simulator
21744 \end_inset
21745 </cell>
21746 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21747 \begin_inset Text
21748
21749 \layout Standard
21750
21751
21752 \family roman
21753 \series medium
21754 \shape up
21755 \size normal
21756 \emph off
21757 \bar no
21758 \noun off
21759 \color none
21760 sdcc/bin
21761 \end_inset
21762 </cell>
21763 </row>
21764 <row topline="true">
21765 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21766 \begin_inset Text
21767
21768 \layout Standard
21769
21770 aslink
21771 \end_inset
21772 </cell>
21773 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21774 \begin_inset Text
21775
21776 \layout Standard
21777
21778 Linker
21779 \end_inset
21780 </cell>
21781 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21782 \begin_inset Text
21783
21784 \layout Standard
21785
21786
21787 \family roman
21788 \series medium
21789 \shape up
21790 \size normal
21791 \emph off
21792 \bar no
21793 \noun off
21794 \color none
21795 sdcc/bin
21796 \end_inset
21797 </cell>
21798 </row>
21799 <row topline="true">
21800 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21801 \begin_inset Text
21802
21803 \layout Standard
21804
21805 link-z80
21806 \end_inset
21807 </cell>
21808 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21809 \begin_inset Text
21810
21811 \layout Standard
21812
21813 Linker
21814 \end_inset
21815 </cell>
21816 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21817 \begin_inset Text
21818
21819 \layout Standard
21820
21821
21822 \family roman
21823 \series medium
21824 \shape up
21825 \size normal
21826 \emph off
21827 \bar no
21828 \noun off
21829 \color none
21830 sdcc/bin
21831 \end_inset
21832 </cell>
21833 </row>
21834 <row topline="true">
21835 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21836 \begin_inset Text
21837
21838 \layout Standard
21839
21840 link-gbz80
21841 \end_inset
21842 </cell>
21843 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21844 \begin_inset Text
21845
21846 \layout Standard
21847
21848 Linker
21849 \end_inset
21850 </cell>
21851 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21852 \begin_inset Text
21853
21854 \layout Standard
21855
21856
21857 \family roman
21858 \series medium
21859 \shape up
21860 \size normal
21861 \emph off
21862 \bar no
21863 \noun off
21864 \color none
21865 sdcc/bin
21866 \end_inset
21867 </cell>
21868 </row>
21869 <row topline="true" bottomline="true">
21870 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21871 \begin_inset Text
21872
21873 \layout Standard
21874
21875 packihx
21876 \end_inset
21877 </cell>
21878 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21879 \begin_inset Text
21880
21881 \layout Standard
21882
21883 ihx packer
21884 \end_inset
21885 </cell>
21886 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21887 \begin_inset Text
21888
21889 \layout Standard
21890
21891
21892 \family roman
21893 \series medium
21894 \shape up
21895 \size normal
21896 \emph off
21897 \bar no
21898 \noun off
21899 \color none
21900 sdcc/bin
21901 \end_inset
21902 </cell>
21903 </row>
21904 </lyxtabular>
21905
21906 \end_inset
21907
21908
21909 \newline
21910
21911 \layout Section
21912
21913 Documentation
21914 \begin_inset LatexCommand \index{Documentation}
21915
21916 \end_inset
21917
21918  included in the distribution
21919 \layout Standard
21920 \align center
21921
21922 \begin_inset  Tabular
21923 <lyxtabular version="3" rows="10" columns="2">
21924 <features>
21925 <column alignment="left" valignment="top" leftline="true" width="0">
21926 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
21927 <row topline="true" bottomline="true">
21928 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21929 \begin_inset Text
21930
21931 \layout Standard
21932
21933 Subject / Title
21934 \end_inset
21935 </cell>
21936 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21937 \begin_inset Text
21938
21939 \layout Standard
21940
21941 Where to get / filename
21942 \end_inset
21943 </cell>
21944 </row>
21945 <row topline="true">
21946 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21947 \begin_inset Text
21948
21949 \layout Standard
21950
21951 SDCC Compiler User Guide
21952 \end_inset
21953 </cell>
21954 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21955 \begin_inset Text
21956
21957 \layout Standard
21958
21959 You're reading it right now
21960 \end_inset
21961 </cell>
21962 </row>
21963 <row topline="true">
21964 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21965 \begin_inset Text
21966
21967 \layout Standard
21968
21969 Changelog of SDCC
21970 \end_inset
21971 </cell>
21972 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21973 \begin_inset Text
21974
21975 \layout Standard
21976
21977 sdcc/Changelog
21978 \end_inset
21979 </cell>
21980 </row>
21981 <row topline="true">
21982 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21983 \begin_inset Text
21984
21985 \layout Standard
21986
21987 ASXXXX
21988 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
21989
21990 \end_inset
21991
21992
21993 \begin_inset LatexCommand \index{Assembler documentation}
21994
21995 \end_inset
21996
21997  Assemblers and ASLINK
21998 \begin_inset LatexCommand \index{aslink}
21999
22000 \end_inset
22001
22002
22003 \begin_inset LatexCommand \index{Linker documentation}
22004
22005 \end_inset
22006
22007  Relocating Linker
22008 \end_inset
22009 </cell>
22010 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22011 \begin_inset Text
22012
22013 \layout Standard
22014
22015 sdcc/as/doc/asxhtm.html
22016 \end_inset
22017 </cell>
22018 </row>
22019 <row topline="true">
22020 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22021 \begin_inset Text
22022
22023 \layout Standard
22024
22025 SDCC regression test
22026 \begin_inset LatexCommand \index{Regression test}
22027
22028 \end_inset
22029
22030
22031 \end_inset
22032 </cell>
22033 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22034 \begin_inset Text
22035
22036 \layout Standard
22037
22038 sdcc/doc/test_suite_spec.pdf
22039 \end_inset
22040 </cell>
22041 </row>
22042 <row topline="true">
22043 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22044 \begin_inset Text
22045
22046 \layout Standard
22047
22048 Various notes
22049 \end_inset
22050 </cell>
22051 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22052 \begin_inset Text
22053
22054 \layout Standard
22055
22056 sdcc/doc/*
22057 \end_inset
22058 </cell>
22059 </row>
22060 <row topline="true">
22061 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22062 \begin_inset Text
22063
22064 \layout Standard
22065
22066 Notes on debugging with sdcdb
22067 \begin_inset LatexCommand \index{sdcdb (debugger)}
22068
22069 \end_inset
22070
22071
22072 \end_inset
22073 </cell>
22074 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22075 \begin_inset Text
22076
22077 \layout Standard
22078
22079 sdcc/debugger/README
22080 \end_inset
22081 </cell>
22082 </row>
22083 <row topline="true">
22084 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22085 \begin_inset Text
22086
22087 \layout Standard
22088
22089 Software simulator for microcontrollers
22090 \end_inset
22091 </cell>
22092 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22093 \begin_inset Text
22094
22095 \layout Standard
22096
22097
22098 \family roman
22099 \series medium
22100 \shape up
22101 \size normal
22102 \emph off
22103 \bar no
22104 \noun off
22105 \color none
22106 sdcc/sim/ucsim/doc
22107 \family default
22108 \series default
22109 \shape default
22110 \size default
22111 \emph default
22112 \bar default
22113 \noun default
22114 \color default
22115 /index.html
22116 \end_inset
22117 </cell>
22118 </row>
22119 <row topline="true">
22120 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22121 \begin_inset Text
22122
22123 \layout Standard
22124
22125 Temporary notes on the pic16
22126 \begin_inset LatexCommand \index{PIC16}
22127
22128 \end_inset
22129
22130  port
22131 \end_inset
22132 </cell>
22133 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22134 \begin_inset Text
22135
22136 \layout Standard
22137
22138 sdcc/src/pic16/NOTES
22139 \end_inset
22140 </cell>
22141 </row>
22142 <row topline="true" bottomline="true">
22143 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22144 \begin_inset Text
22145
22146 \layout Standard
22147
22148 SDCC internal documentation (debugging file format)
22149 \end_inset
22150 </cell>
22151 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22152 \begin_inset Text
22153
22154 \layout Standard
22155
22156 sdcc/doc/
22157 \family roman
22158 \series medium
22159 \shape up
22160 \size normal
22161 \emph off
22162 \bar no
22163 \noun off
22164 \color none
22165 cdbfileformat.pd
22166 \family default
22167 \series default
22168 \shape default
22169 \size default
22170 \emph default
22171 \bar default
22172 \noun default
22173 \color default
22174 f
22175 \end_inset
22176 </cell>
22177 </row>
22178 </lyxtabular>
22179
22180 \end_inset
22181
22182
22183 \newline
22184
22185 \layout Section
22186
22187 Related open source tools
22188 \begin_inset LatexCommand \index{Related tools}
22189
22190 \end_inset
22191
22192
22193 \layout Standard
22194 \align center
22195
22196 \begin_inset  Tabular
22197 <lyxtabular version="3" rows="11" columns="3">
22198 <features>
22199 <column alignment="center" valignment="top" leftline="true" width="0pt">
22200 <column alignment="block" valignment="top" leftline="true" width="30line%">
22201 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
22202 <row topline="true" bottomline="true">
22203 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22204 \begin_inset Text
22205
22206 \layout Standard
22207
22208 Name
22209 \end_inset
22210 </cell>
22211 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22212 \begin_inset Text
22213
22214 \layout Standard
22215
22216 Purpose
22217 \end_inset
22218 </cell>
22219 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22220 \begin_inset Text
22221
22222 \layout Standard
22223
22224 Where to get
22225 \end_inset
22226 </cell>
22227 </row>
22228 <row topline="true">
22229 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22230 \begin_inset Text
22231
22232 \layout Standard
22233
22234 gpsim
22235 \begin_inset LatexCommand \index{gpsim (pic simulator)}
22236
22237 \end_inset
22238
22239
22240 \end_inset
22241 </cell>
22242 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22243 \begin_inset Text
22244
22245 \layout Standard
22246
22247 PIC simulator
22248 \end_inset
22249 </cell>
22250 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22251 \begin_inset Text
22252
22253 \layout Standard
22254
22255
22256 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
22257
22258 \end_inset
22259
22260
22261 \end_inset
22262 </cell>
22263 </row>
22264 <row topline="true">
22265 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22266 \begin_inset Text
22267
22268 \layout Standard
22269
22270 gputils
22271 \begin_inset LatexCommand \index{gputils (pic tools)}
22272
22273 \end_inset
22274
22275
22276 \end_inset
22277 </cell>
22278 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22279 \begin_inset Text
22280
22281 \layout Standard
22282
22283 GNU PIC utilities
22284 \end_inset
22285 </cell>
22286 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22287 \begin_inset Text
22288
22289 \layout Standard
22290
22291
22292 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
22293
22294 \end_inset
22295
22296
22297 \end_inset
22298 </cell>
22299 </row>
22300 <row topline="true">
22301 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22302 \begin_inset Text
22303
22304 \layout Standard
22305
22306 flP5
22307 \end_inset
22308 </cell>
22309 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22310 \begin_inset Text
22311
22312 \layout Standard
22313
22314 PIC programmer
22315 \end_inset
22316 </cell>
22317 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22318 \begin_inset Text
22319
22320 \layout Standard
22321
22322
22323 \begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/}
22324
22325 \end_inset
22326
22327
22328 \end_inset
22329 </cell>
22330 </row>
22331 <row topline="true">
22332 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22333 \begin_inset Text
22334
22335 \layout Standard
22336
22337 indent
22338 \begin_inset LatexCommand \index{indent (source formatting tool)}
22339
22340 \end_inset
22341
22342
22343 \end_inset
22344 </cell>
22345 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22346 \begin_inset Text
22347
22348 \layout Standard
22349
22350 Formats C source - Master of the white spaces
22351 \end_inset
22352 </cell>
22353 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22354 \begin_inset Text
22355
22356 \layout Standard
22357
22358
22359 \begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html}
22360
22361 \end_inset
22362
22363
22364 \end_inset
22365 </cell>
22366 </row>
22367 <row topline="true">
22368 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22369 \begin_inset Text
22370
22371 \layout Standard
22372
22373 srecord
22374 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
22375
22376 \end_inset
22377
22378
22379 \end_inset
22380 </cell>
22381 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22382 \begin_inset Text
22383
22384 \layout Standard
22385
22386 Object file conversion, checksumming, ...
22387 \end_inset
22388 </cell>
22389 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22390 \begin_inset Text
22391
22392 \layout Standard
22393
22394
22395 \begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord}
22396
22397 \end_inset
22398
22399
22400 \end_inset
22401 </cell>
22402 </row>
22403 <row topline="true">
22404 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22405 \begin_inset Text
22406
22407 \layout Standard
22408
22409 objdump
22410 \begin_inset LatexCommand \index{objdump (tool)}
22411
22412 \end_inset
22413
22414
22415 \end_inset
22416 </cell>
22417 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22418 \begin_inset Text
22419
22420 \layout Standard
22421
22422 Object file conversion, ...
22423 \end_inset
22424 </cell>
22425 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22426 \begin_inset Text
22427
22428 \layout Standard
22429
22430 Part of binutils (should be there anyway)
22431 \end_inset
22432 </cell>
22433 </row>
22434 <row topline="true">
22435 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22436 \begin_inset Text
22437
22438 \layout Standard
22439
22440 doxygen
22441 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
22442
22443 \end_inset
22444
22445
22446 \end_inset
22447 </cell>
22448 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22449 \begin_inset Text
22450
22451 \layout Standard
22452
22453 Source code documentation system
22454 \end_inset
22455 </cell>
22456 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22457 \begin_inset Text
22458
22459 \layout Standard
22460
22461
22462 \begin_inset LatexCommand \url{http://www.doxygen.org}
22463
22464 \end_inset
22465
22466
22467 \end_inset
22468 </cell>
22469 </row>
22470 <row topline="true">
22471 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22472 \begin_inset Text
22473
22474 \layout Standard
22475
22476 kdevelop
22477 \end_inset
22478 </cell>
22479 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22480 \begin_inset Text
22481
22482 \layout Standard
22483
22484 IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
22485 \end_inset
22486 </cell>
22487 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22488 \begin_inset Text
22489
22490 \layout Standard
22491
22492
22493 \begin_inset LatexCommand \url{http://www.kdevelop.org}
22494
22495 \end_inset
22496
22497
22498 \end_inset
22499 </cell>
22500 </row>
22501 <row topline="true">
22502 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22503 \begin_inset Text
22504
22505 \layout Standard
22506
22507 splint
22508 \begin_inset LatexCommand \index{splint (syntax checking tool)}
22509
22510 \end_inset
22511
22512
22513 \end_inset
22514 </cell>
22515 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22516 \begin_inset Text
22517
22518 \layout Standard
22519
22520 Statically checks c sources (see
22521 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
22522
22523 \end_inset
22524
22525 )
22526 \end_inset
22527 </cell>
22528 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22529 \begin_inset Text
22530
22531 \layout Standard
22532
22533
22534 \begin_inset LatexCommand \url{http://www.splint.org}
22535
22536 \end_inset
22537
22538
22539 \end_inset
22540 </cell>
22541 </row>
22542 <row topline="true" bottomline="true">
22543 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22544 \begin_inset Text
22545
22546 \layout Standard
22547
22548 ddd
22549 \begin_inset LatexCommand \index{ddd (debugger)}
22550
22551 \end_inset
22552
22553
22554 \end_inset
22555 </cell>
22556 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22557 \begin_inset Text
22558
22559 \layout Standard
22560
22561 Debugger, serves nicely as GUI to sdcdb
22562 \begin_inset LatexCommand \index{sdcdb (debugger)}
22563
22564 \end_inset
22565
22566  (Unix only)
22567 \end_inset
22568 </cell>
22569 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22570 \begin_inset Text
22571
22572 \layout Standard
22573
22574
22575 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
22576
22577 \end_inset
22578
22579
22580 \end_inset
22581 </cell>
22582 </row>
22583 </lyxtabular>
22584
22585 \end_inset
22586
22587
22588 \newline
22589
22590 \layout Section
22591
22592 Related documentation / recommended reading
22593 \layout Standard
22594 \align center
22595
22596 \begin_inset  Tabular
22597 <lyxtabular version="3" rows="6" columns="3">
22598 <features>
22599 <column alignment="center" valignment="top" leftline="true" width="0pt">
22600 <column alignment="block" valignment="top" leftline="true" width="30line%">
22601 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
22602 <row topline="true" bottomline="true">
22603 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22604 \begin_inset Text
22605
22606 \layout Standard
22607
22608 Name
22609 \end_inset
22610 </cell>
22611 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22612 \begin_inset Text
22613
22614 \layout Standard
22615
22616 Subject / Title
22617 \end_inset
22618 </cell>
22619 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22620 \begin_inset Text
22621
22622 \layout Standard
22623
22624 Where to get
22625 \end_inset
22626 </cell>
22627 </row>
22628 <row topline="true">
22629 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22630 \begin_inset Text
22631
22632 \layout Standard
22633
22634
22635 \family roman
22636 \series medium
22637 \shape up
22638 \size normal
22639 \emph off
22640 \bar no
22641 \noun off
22642 \color none
22643 c-refcard.pdf
22644 \end_inset
22645 </cell>
22646 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22647 \begin_inset Text
22648
22649 \layout Standard
22650
22651 C Reference Card
22652 \begin_inset LatexCommand \index{C Reference card}
22653
22654 \end_inset
22655
22656 , 2 pages
22657 \end_inset
22658 </cell>
22659 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22660 \begin_inset Text
22661
22662 \layout Standard
22663
22664
22665 \begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html}
22666
22667 \end_inset
22668
22669
22670 \end_inset
22671 </cell>
22672 </row>
22673 <row topline="true">
22674 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22675 \begin_inset Text
22676
22677 \layout Standard
22678
22679 c-faq
22680 \end_inset
22681 </cell>
22682 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22683 \begin_inset Text
22684
22685 \layout Standard
22686
22687 C-FAQ-list
22688 \end_inset
22689 </cell>
22690 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22691 \begin_inset Text
22692
22693 \layout Standard
22694
22695
22696 \begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
22697
22698 \end_inset
22699
22700
22701 \end_inset
22702 </cell>
22703 </row>
22704 <row topline="true">
22705 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22706 \begin_inset Text
22707
22708 \layout Standard
22709
22710 \end_inset
22711 </cell>
22712 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22713 \begin_inset Text
22714
22715 \layout Standard
22716
22717 Latest datasheet of the target CPU
22718 \end_inset
22719 </cell>
22720 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22721 \begin_inset Text
22722
22723 \layout Standard
22724
22725 vendor
22726 \end_inset
22727 </cell>
22728 </row>
22729 <row topline="true">
22730 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22731 \begin_inset Text
22732
22733 \layout Standard
22734
22735 \end_inset
22736 </cell>
22737 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22738 \begin_inset Text
22739
22740 \layout Standard
22741
22742 Revision history of datasheet
22743 \end_inset
22744 </cell>
22745 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22746 \begin_inset Text
22747
22748 \layout Standard
22749
22750 vendor
22751 \end_inset
22752 </cell>
22753 </row>
22754 <row topline="true" bottomline="true">
22755 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22756 \begin_inset Text
22757
22758 \layout Standard
22759
22760 S.
22761  S.
22762  Muchnick
22763 \end_inset
22764 </cell>
22765 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22766 \begin_inset Text
22767
22768 \layout Standard
22769
22770 Advanced Compiler Design and Implementation
22771 \end_inset
22772 </cell>
22773 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22774 \begin_inset Text
22775
22776 \layout Standard
22777
22778 bookstore (very dedicated, probably read other books first)
22779 \end_inset
22780 </cell>
22781 </row>
22782 </lyxtabular>
22783
22784 \end_inset
22785
22786
22787 \newline
22788
22789 \layout Section
22790
22791 Some Questions
22792 \layout Standard
22793
22794 Some questions answered, some pointers given - it might be time to in turn
22795  ask
22796 \emph on
22797 you
22798 \emph default
22799  some questions:
22800 \layout Itemize
22801
22802 can you solve your project with the selected microcontroller? Would you
22803  find out early or rather late that your target is too small/slow/whatever?
22804  Can you switch to a slightly better device if it doesn't fit?
22805 \layout Itemize
22806
22807 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
22808  and/or another programming language be more adequate? Would an operating
22809  system on the target device help?
22810 \layout Itemize
22811
22812 if you solved the problem, will the marketing department be happy?
22813 \layout Itemize
22814
22815 if the marketing department is happy, will customers be happy?
22816 \layout Itemize
22817
22818 if you're the project manager, marketing department and maybe even the customer
22819  in one person, have you tried to see the project from the outside?
22820 \layout Itemize
22821
22822 is the project done if you think it is done? Or is just that other interface/pro
22823 tocol/feature/configuration/option missing? How about website, manual(s),
22824  internationali(z|s)ation, packaging, labels, 2nd source for components,
22825  electromagnetic compatability/interference, documentation for production,
22826  production test software, update mechanism, patent issues?
22827 \layout Itemize
22828
22829 is your project adequately positioned in that magic triangle: fame, fortune,
22830  fun?
22831 \layout Standard
22832
22833 Maybe not all answers to these questions are known and some answers may
22834  even be
22835 \emph on
22836 no
22837 \emph default
22838 , nevertheless knowing these questions may help you to avoid burnout
22839 \begin_inset Foot
22840 collapsed false
22841
22842 \layout Standard
22843
22844 burnout is bad for electronic devices, programmers and motorcycle tyres
22845 \end_inset
22846
22847 .
22848  Chances are you didn't want to hear some of them...
22849 \layout Chapter
22850
22851 Support
22852 \begin_inset LatexCommand \index{Support}
22853
22854 \end_inset
22855
22856
22857 \layout Standard
22858
22859 SDCC has grown to be a large project.
22860  The compiler alone (without the preprocessor, assembler and linker) is
22861  well over 100,000 lines of code (blank stripped).
22862  The open source nature of this project is a key to its continued growth
22863  and support.
22864  You gain the benefit and support of many active software developers and
22865  end users.
22866  Is SDCC perfect? No, that's why we need your help.
22867  The developers take pride in fixing reported bugs.
22868  You can help by reporting the bugs and helping other SDCC users.
22869  There are lots of ways to contribute, and we encourage you to take part
22870  in making SDCC a great software package.
22871
22872 \layout Standard
22873
22874 The SDCC project is hosted on the SDCC sourceforge site at
22875 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
22876
22877 \end_inset
22878
22879 .
22880  You'll find the complete set of mailing lists
22881 \begin_inset LatexCommand \index{Mailing list(s)}
22882
22883 \end_inset
22884
22885 , forums, bug reporting system, patch submission
22886 \begin_inset LatexCommand \index{Patch submission}
22887
22888 \end_inset
22889
22890  system, download
22891 \begin_inset LatexCommand \index{download}
22892
22893 \end_inset
22894
22895  area and cvs code repository
22896 \begin_inset LatexCommand \index{cvs code repository}
22897
22898 \end_inset
22899
22900  there.
22901 \layout Section
22902
22903 Reporting Bugs
22904 \begin_inset LatexCommand \index{Bug reporting}
22905
22906 \end_inset
22907
22908
22909 \begin_inset LatexCommand \index{Reporting bugs}
22910
22911 \end_inset
22912
22913
22914 \layout Standard
22915
22916 The recommended way of reporting bugs is using the infrastructure of the
22917  sourceforge site.
22918  You can follow the status of bug reports there and have an overview about
22919  the known bugs.
22920 \layout Standard
22921
22922 Bug reports are automatically forwarded to the developer mailing list and
22923  will be fixed ASAP.
22924  When reporting a bug, it is very useful to include a small test program
22925  (the smaller the better) which reproduces the problem.
22926  If you can isolate the problem by looking at the generated assembly code,
22927  this can be very helpful.
22928  Compiling your program with the -
22929 \begin_inset ERT
22930 status Collapsed
22931
22932 \layout Standard
22933
22934 \backslash
22935 /
22936 \end_inset
22937
22938 -dumpall
22939 \begin_inset LatexCommand \index{-\/-dumpall}
22940
22941 \end_inset
22942
22943  option can sometimes be useful in locating optimization problems.
22944  When reporting a bug please maker sure you:
22945 \layout Enumerate
22946
22947 Attach the code you are compiling with SDCC.
22948
22949 \layout Enumerate
22950
22951 Specify the exact command you use to run SDCC, or attach your Makefile.
22952
22953 \layout Enumerate
22954
22955 Specify the SDCC version (type "
22956 \family sans
22957 \series bold
22958 sdcc -v
22959 \family default
22960 \series default
22961 "), your platform, and operating system.
22962
22963 \layout Enumerate
22964
22965 Provide an exact copy of any error message or incorrect output.
22966
22967 \layout Enumerate
22968
22969 Put something meaningful in the subject of your message.
22970 \layout Standard
22971
22972 Please attempt to include these 5 important parts, as applicable, in all
22973  requests for support or when reporting any problems or bugs with SDCC.
22974  Though this will make your message lengthy, it will greatly improve your
22975  chance that SDCC users and developers will be able to help you.
22976  Some SDCC developers are frustrated by bug reports without code provided
22977  that they can use to reproduce and ultimately fix the problem, so please
22978  be sure to provide sample code if you are reporting a bug!
22979 \layout Standard
22980
22981 Please have a short check that you are using a recent version of SDCC and
22982  the bug is not yet known.
22983  This is the link for reporting bugs:
22984 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
22985
22986 \end_inset
22987
22988 .
22989 \layout Section
22990
22991 Requesting Features
22992 \begin_inset LatexCommand \label{sub:Requesting-Features}
22993
22994 \end_inset
22995
22996
22997 \begin_inset LatexCommand \index{Feature request}
22998
22999 \end_inset
23000
23001
23002 \begin_inset LatexCommand \index{Requesting features}
23003
23004 \end_inset
23005
23006
23007 \layout Standard
23008
23009 Like bug reports feature requests are forwarded to the developer mailing
23010  list.
23011  This is the link for requesting features:
23012 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
23013
23014 \end_inset
23015
23016 .
23017 \layout Section
23018
23019 Submitting patches
23020 \layout Standard
23021
23022 Like bug reports contributed patches are forwarded to the developer mailing
23023  list.
23024  This is the link for submitting patches
23025 \begin_inset LatexCommand \index{Patch submission}
23026
23027 \end_inset
23028
23029 :
23030 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
23031
23032 \end_inset
23033
23034 .
23035 \layout Standard
23036
23037 You need to specify some parameters to the
23038 \family typewriter
23039 diff
23040 \family default
23041  command for the patches to be useful.
23042  If you modified more than one file a patch created f.e.
23043  with
23044 \family sans
23045 \series bold
23046
23047 \begin_inset Quotes sld
23048 \end_inset
23049
23050 diff -Naur unmodified_directory modified_directory >my_changes.patch
23051 \begin_inset Quotes srd
23052 \end_inset
23053
23054
23055 \family default
23056 \series default
23057  will be fine, otherwise
23058 \family sans
23059 \series bold
23060
23061 \begin_inset Quotes sld
23062 \end_inset
23063
23064 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
23065 \begin_inset Quotes srd
23066 \end_inset
23067
23068
23069 \series default
23070
23071 \family default
23072 will do.
23073 \layout Section
23074
23075 Getting Help
23076 \layout Standard
23077
23078 These links should take you directly to the
23079 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
23080
23081 \end_inset
23082
23083
23084 \begin_inset Foot
23085 collapsed false
23086
23087 \layout Standard
23088
23089 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
23090  automated messages (mid 2003)
23091 \end_inset
23092
23093  and the
23094 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
23095
23096 \end_inset
23097
23098 , lists
23099 \begin_inset LatexCommand \index{Mailing list(s)}
23100
23101 \end_inset
23102
23103  and forums are archived and searchable so if you are lucky someone already
23104  had a similar problem.
23105  While mails to the lists themselves are delivered promptly their web front
23106  end on sourceforge sometimes shows a severe time lag (up to several weeks),
23107  if you're seriously using SDCC please consider subscribing to the lists.
23108 \layout Section
23109
23110 ChangeLog
23111 \layout Standard
23112
23113 You can follow the status of the cvs version
23114 \begin_inset LatexCommand \index{version}
23115
23116 \end_inset
23117
23118  of SDCC by watching the Changelog
23119 \begin_inset LatexCommand \index{Changelog}
23120
23121 \end_inset
23122
23123  in the cvs-repository
23124 \newline
23125
23126 \size footnotesize
23127
23128 \begin_inset LatexCommand \htmlurl{http://cvs.sf.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
23129
23130 \end_inset
23131
23132 .
23133 \layout Section
23134
23135 Release policy
23136 \begin_inset LatexCommand \index{Release policy}
23137
23138 \end_inset
23139
23140
23141 \layout Standard
23142
23143 Historically there often were long delays between official releases and
23144  the sourceforge download area tends to get not updated at all.
23145  Excuses in the past might have referred to problems with live range analysis,
23146  but as this was fixed a while ago, the current problem is that another
23147  excuse has to be found.
23148  Kidding aside, we have to get better there! On the other hand there are
23149  daily snapshots available at
23150 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
23151
23152 \end_inset
23153
23154 , and you can always build the very last version (hopefully with many bugs
23155  fixed, and features added) from the source code available at
23156 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
23157
23158 \end_inset
23159
23160 .
23161 \layout Section
23162
23163 Examples
23164 \begin_inset LatexCommand \index{Examples}
23165
23166 \end_inset
23167
23168
23169 \layout Standard
23170
23171 You'll find some small examples in the directory
23172 \emph on
23173 sdcc/device/examples/.
23174
23175 \emph default
23176 More examples and libraries are available at
23177 \emph on
23178  The SDCC Open Knowledge Resource
23179 \begin_inset LatexCommand \url{http://sdccokr.dl9sec.de/}
23180
23181 \end_inset
23182
23183
23184 \emph default
23185 web site or at
23186 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
23187
23188 \end_inset
23189
23190 .
23191 \layout Comment
23192
23193 I did insert a reference to Paul's web site here although it seems rather
23194  dedicated to a specific 8032 board (I think it's okay because it f.e.
23195  shows LCD/Harddisc interface and has a free 8051 monitor.
23196  Independent 8032 board vendors face hard competition of heavily subsidized
23197  development boards anyway).
23198 \layout Comment
23199
23200 Maybe we should include some links to real world applications.
23201  Preferably pointer to pointers (one for each architecture) so this stays
23202  manageable here?
23203 \layout Section
23204
23205 Quality control
23206 \begin_inset LatexCommand \index{Quality control}
23207
23208 \end_inset
23209
23210
23211 \layout Standard
23212
23213 The compiler is passed through nightly compile and build checks.
23214  The so called
23215 \shape italic
23216 regression tests
23217 \shape default
23218
23219 \begin_inset LatexCommand \index{Regression test}
23220
23221 \end_inset
23222
23223  check that SDCC itself compiles flawlessly on several platforms and checks
23224  the quality of the code generated by SDCC by running the code through simulator
23225 s.
23226  There is a separate document
23227 \shape italic
23228 test_suite.pdf
23229 \begin_inset LatexCommand \index{Test suite}
23230
23231 \end_inset
23232
23233
23234 \shape default
23235  about this.
23236 \layout Standard
23237
23238 You'll find the test code in the directory
23239 \shape italic
23240 sdcc/support/regression
23241 \shape default
23242 .
23243  You can run these tests manually by running
23244 \family sans
23245 make
23246 \family default
23247  in this directory (or f.e.
23248
23249 \family sans
23250 \series bold
23251
23252 \begin_inset Quotes sld
23253 \end_inset
23254
23255 make test-mcs51
23256 \begin_inset Quotes srd
23257 \end_inset
23258
23259
23260 \family default
23261 \series default
23262  if you don't want to run the complete tests).
23263  The test code might also be interesting if you want to look for examples
23264 \begin_inset LatexCommand \index{Examples}
23265
23266 \end_inset
23267
23268  checking corner cases of SDCC or if you plan to submit patches
23269 \begin_inset LatexCommand \index{Patch submission}
23270
23271 \end_inset
23272
23273 .
23274 \layout Standard
23275
23276 The pic port uses a different set of regression tests, you'll find them
23277  in the directory
23278 \shape italic
23279 sdcc/src/regression
23280 \shape default
23281 .
23282 \layout Chapter
23283 \pagebreak_top
23284 SDCC Technical Data
23285 \layout Section
23286
23287 Optimizations
23288 \begin_inset LatexCommand \index{Optimizations}
23289
23290 \end_inset
23291
23292
23293 \layout Standard
23294
23295 SDCC performs a host of standard optimizations in addition to some MCU specific
23296  optimizations.
23297
23298 \layout Subsection
23299
23300 Sub-expression Elimination
23301 \begin_inset LatexCommand \index{Subexpression elimination}
23302
23303 \end_inset
23304
23305
23306 \layout Standard
23307
23308 The compiler does local and
23309 \emph on
23310 g
23311 \emph default
23312 lobal
23313 \emph on
23314 c
23315 \emph default
23316 ommon
23317 \emph on
23318 s
23319 \emph default
23320 ubexpression
23321 \emph on
23322 e
23323 \emph default
23324 limination, e.g.:
23325 \layout Verse
23326
23327
23328 \family typewriter
23329 i = x + y + 1;
23330 \newline
23331 j = x + y;
23332 \layout Standard
23333
23334 will be translated to
23335 \layout Verse
23336
23337
23338 \family typewriter
23339 iTemp = x + y;
23340 \newline
23341 i = iTemp + 1;
23342 \newline
23343 j = iTemp;
23344 \layout Standard
23345
23346 Some subexpressions are not as obvious as the above example, e.g.:
23347 \layout Verse
23348
23349
23350 \family typewriter
23351 a->b[i].c = 10;
23352 \newline
23353 a->b[i].d = 11;
23354 \layout Standard
23355
23356 In this case the address arithmetic a->b[i] will be computed only once;
23357  the equivalent code in C would be.
23358 \layout Verse
23359
23360
23361 \family typewriter
23362 iTemp = a->b[i];
23363 \newline
23364 iTemp.c = 10;
23365 \newline
23366 iTemp.d = 11;
23367 \layout Standard
23368
23369 The compiler will try to keep these temporary variables in registers.
23370 \layout Subsection
23371
23372 Dead-Code Elimination
23373 \begin_inset LatexCommand \index{Dead-code elimination}
23374
23375 \end_inset
23376
23377
23378 \layout Verse
23379
23380
23381 \family typewriter
23382 int global;
23383 \newline
23384
23385 \newline
23386 void f () {
23387 \newline
23388 \SpecialChar ~
23389 \SpecialChar ~
23390 int i;
23391 \newline
23392 \SpecialChar ~
23393 \SpecialChar ~
23394 i = 1; \SpecialChar ~
23395 \SpecialChar ~
23396 \SpecialChar ~
23397 \SpecialChar ~
23398 \SpecialChar ~
23399 /* dead store */
23400 \newline
23401 \SpecialChar ~
23402 \SpecialChar ~
23403 global = 1;\SpecialChar ~
23404 /* dead store */
23405 \newline
23406 \SpecialChar ~
23407 \SpecialChar ~
23408 global = 2;
23409 \newline
23410 \SpecialChar ~
23411 \SpecialChar ~
23412 return;
23413 \newline
23414 \SpecialChar ~
23415 \SpecialChar ~
23416 global = 3;\SpecialChar ~
23417 /* unreachable */
23418 \newline
23419 }
23420 \layout Standard
23421
23422 will be changed to
23423 \layout Verse
23424
23425
23426 \family typewriter
23427 int global;
23428 \newline
23429
23430 \newline
23431 void f () {
23432 \newline
23433 \SpecialChar ~
23434 \SpecialChar ~
23435 global = 2;
23436 \newline
23437 }
23438 \layout Subsection
23439
23440 Copy-Propagation
23441 \begin_inset LatexCommand \index{Copy propagation}
23442
23443 \end_inset
23444
23445
23446 \layout Verse
23447
23448
23449 \family typewriter
23450 int f() {
23451 \newline
23452 \SpecialChar ~
23453 \SpecialChar ~
23454 int i, j;
23455 \newline
23456 \SpecialChar ~
23457 \SpecialChar ~
23458 i = 10;
23459 \newline
23460 \SpecialChar ~
23461 \SpecialChar ~
23462 j = i;
23463 \newline
23464 \SpecialChar ~
23465 \SpecialChar ~
23466 return j;
23467 \newline
23468 }
23469 \layout Standard
23470
23471 will be changed to
23472 \layout Verse
23473
23474
23475 \family typewriter
23476 int f() {
23477 \newline
23478 \SpecialChar ~
23479 \SpecialChar ~
23480 int i, j;
23481 \newline
23482 \SpecialChar ~
23483 \SpecialChar ~
23484 i = 10;
23485 \newline
23486 \SpecialChar ~
23487 \SpecialChar ~
23488 j = 10;
23489 \newline
23490 \SpecialChar ~
23491 \SpecialChar ~
23492 return 10;
23493 \newline
23494 }
23495 \layout Standard
23496
23497 Note: the dead stores created by this copy propagation will be eliminated
23498  by dead-code elimination.
23499 \layout Subsection
23500
23501 Loop Optimizations
23502 \begin_inset LatexCommand \index{Loop optimization}
23503
23504 \end_inset
23505
23506
23507 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
23508
23509 \end_inset
23510
23511
23512 \layout Standard
23513
23514 Two types of loop optimizations are done by SDCC
23515 \emph on
23516 loop invariant
23517 \emph default
23518  lifting and
23519 \emph on
23520  strength reduction
23521 \emph default
23522  of loop induction variables.
23523  In addition to the strength reduction the optimizer marks the induction
23524  variables and the register allocator tries to keep the induction variables
23525  in registers for the duration of the loop.
23526  Because of this preference of the register allocator
23527 \begin_inset LatexCommand \index{Register allocation}
23528
23529 \end_inset
23530
23531 , loop induction optimization causes an increase in register pressure, which
23532  may cause unwanted spilling of other temporary variables into the stack
23533 \begin_inset LatexCommand \index{stack}
23534
23535 \end_inset
23536
23537  / data space.
23538  The compiler will generate a warning message when it is forced to allocate
23539  extra space either on the stack or data space.
23540  If this extra space allocation is undesirable then induction optimization
23541  can be eliminated either for the entire source file (with -
23542 \begin_inset ERT
23543 status Collapsed
23544
23545 \layout Standard
23546
23547 \backslash
23548 /
23549 \end_inset
23550
23551 -noinduction option) or for a given function only using #pragma\SpecialChar ~
23552 noinduction
23553 \begin_inset LatexCommand \index{\#pragma noinduction}
23554
23555 \end_inset
23556
23557 .
23558 \newline
23559
23560 \newline
23561 Loop Invariant:
23562 \layout Verse
23563
23564
23565 \family typewriter
23566 for (i = 0 ; i < 100 ; i ++)
23567 \newline
23568 \SpecialChar ~
23569 \SpecialChar ~
23570 \SpecialChar ~
23571 \SpecialChar ~
23572 f += k + l;
23573 \layout Standard
23574
23575 changed to
23576 \layout Verse
23577
23578
23579 \family typewriter
23580 itemp = k + l;
23581 \newline
23582 for (i = 0; i < 100; i++)
23583 \newline
23584 \SpecialChar ~
23585 \SpecialChar ~
23586 \SpecialChar ~
23587 \SpecialChar ~
23588 f += itemp;
23589 \layout Standard
23590
23591 As mentioned previously some loop invariants are not as apparent, all static
23592  address computations are also moved out of the loop.
23593 \newline
23594
23595 \newline
23596 Strength Reduction
23597 \begin_inset LatexCommand \index{Strength reduction}
23598
23599 \end_inset
23600
23601 , this optimization substitutes an expression by a cheaper expression:
23602 \layout Verse
23603
23604
23605 \family typewriter
23606 for (i=0;i < 100; i++)
23607 \newline
23608 \SpecialChar ~
23609 \SpecialChar ~
23610 \SpecialChar ~
23611 \SpecialChar ~
23612 ar[i*5] = i*3;
23613 \layout Standard
23614
23615 changed to
23616 \layout Verse
23617
23618
23619 \family typewriter
23620 itemp1 = 0;
23621 \newline
23622 itemp2 = 0;
23623 \newline
23624 for (i=0;i< 100;i++) {
23625 \newline
23626 \SpecialChar ~
23627 \SpecialChar ~
23628 \SpecialChar ~
23629 \SpecialChar ~
23630 ar[itemp1] = itemp2;
23631 \newline
23632 \SpecialChar ~
23633 \SpecialChar ~
23634 \SpecialChar ~
23635 \SpecialChar ~
23636 itemp1 += 5;
23637 \newline
23638 \SpecialChar ~
23639 \SpecialChar ~
23640 \SpecialChar ~
23641 \SpecialChar ~
23642 itemp2 += 3;
23643 \newline
23644 }
23645 \layout Standard
23646
23647 The more expensive multiplication
23648 \begin_inset LatexCommand \index{Multiplication}
23649
23650 \end_inset
23651
23652  is changed to a less expensive addition.
23653 \layout Subsection
23654
23655 Loop Reversing
23656 \begin_inset LatexCommand \index{Loop reversing}
23657
23658 \end_inset
23659
23660
23661 \layout Standard
23662
23663 This optimization is done to reduce the overhead of checking loop boundaries
23664  for every iteration.
23665  Some simple loops can be reversed and implemented using a
23666 \begin_inset Quotes eld
23667 \end_inset
23668
23669 decrement and jump if not zero
23670 \begin_inset Quotes erd
23671 \end_inset
23672
23673  instruction.
23674  SDCC checks for the following criterion to determine if a loop is reversible
23675  (note: more sophisticated compilers use data-dependency analysis to make
23676  this determination, SDCC uses a more simple minded analysis).
23677 \layout Itemize
23678
23679 The 'for' loop is of the form
23680 \newline
23681
23682 \newline
23683
23684 \family typewriter
23685 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
23686  += 1])
23687 \newline
23688 \SpecialChar ~
23689 \SpecialChar ~
23690 \SpecialChar ~
23691 \SpecialChar ~
23692 <for body>
23693 \layout Itemize
23694
23695 The <for body> does not contain
23696 \begin_inset Quotes eld
23697 \end_inset
23698
23699 continue
23700 \begin_inset Quotes erd
23701 \end_inset
23702
23703  or 'break
23704 \begin_inset Quotes erd
23705 \end_inset
23706
23707 .
23708 \layout Itemize
23709
23710 All goto's are contained within the loop.
23711 \layout Itemize
23712
23713 No function calls within the loop.
23714 \layout Itemize
23715
23716 The loop control variable <sym> is not assigned any value within the loop
23717 \layout Itemize
23718
23719 The loop control variable does NOT participate in any arithmetic operation
23720  within the loop.
23721 \layout Itemize
23722
23723 There are NO switch statements in the loop.
23724 \layout Subsection
23725
23726 Algebraic Simplifications
23727 \layout Standard
23728
23729 SDCC does numerous algebraic simplifications, the following is a small sub-set
23730  of these optimizations.
23731 \layout Verse
23732
23733
23734 \family typewriter
23735 i = j + 0;\SpecialChar ~
23736 \SpecialChar ~
23737 \SpecialChar ~
23738 \SpecialChar ~
23739  /* changed to: */\SpecialChar ~
23740 \SpecialChar ~
23741 \SpecialChar ~
23742 \SpecialChar ~
23743  i = j;
23744 \newline
23745 i /= 2;\SpecialChar ~
23746 \SpecialChar ~
23747 \SpecialChar ~
23748 \SpecialChar ~
23749 \SpecialChar ~
23750 \SpecialChar ~
23751 \SpecialChar ~
23752  /* changed to: */\SpecialChar ~
23753 \SpecialChar ~
23754 \SpecialChar ~
23755 \SpecialChar ~
23756  i >>= 1;
23757 \newline
23758 i = j - j;\SpecialChar ~
23759 \SpecialChar ~
23760 \SpecialChar ~
23761 \SpecialChar ~
23762  /* changed to: */\SpecialChar ~
23763 \SpecialChar ~
23764 \SpecialChar ~
23765 \SpecialChar ~
23766  i = 0;
23767 \newline
23768 i = j / 1;\SpecialChar ~
23769 \SpecialChar ~
23770 \SpecialChar ~
23771 \SpecialChar ~
23772  /* changed to: */\SpecialChar ~
23773 \SpecialChar ~
23774 \SpecialChar ~
23775 \SpecialChar ~
23776  i = j;
23777 \layout Standard
23778
23779 Note the subexpressions
23780 \begin_inset LatexCommand \index{Subexpression}
23781
23782 \end_inset
23783
23784  given above are generally introduced by macro expansions or as a result
23785  of copy/constant propagation.
23786 \layout Subsection
23787
23788 'switch' Statements
23789 \begin_inset LatexCommand \label{sub:'switch'-Statements}
23790
23791 \end_inset
23792
23793
23794 \begin_inset LatexCommand \index{switch statement}
23795
23796 \end_inset
23797
23798
23799 \layout Standard
23800
23801 SDCC can optimize switch statements to jump tables
23802 \begin_inset LatexCommand \index{jump tables}
23803
23804 \end_inset
23805
23806 .
23807  It makes the decision based on an estimate of the generated code size.
23808  SDCC is quite liberal in the requirements for jump table generation:
23809 \layout Itemize
23810
23811 The labels need not be in order, and the starting number need not be one
23812  or zero, the case labels are in numerical sequence or not too many case
23813  labels are missing.
23814 \begin_deeper
23815 \layout Verse
23816
23817
23818 \family typewriter
23819 switch(i) {\SpecialChar ~
23820 \SpecialChar ~
23821 \SpecialChar ~
23822 \SpecialChar ~
23823 \SpecialChar ~
23824 \SpecialChar ~
23825 \SpecialChar ~
23826 \SpecialChar ~
23827 \SpecialChar ~
23828 \SpecialChar ~
23829 \SpecialChar ~
23830 \SpecialChar ~
23831 \SpecialChar ~
23832 \SpecialChar ~
23833 \SpecialChar ~
23834 \SpecialChar ~
23835 \SpecialChar ~
23836 \SpecialChar ~
23837 \SpecialChar ~
23838 \SpecialChar ~
23839 \SpecialChar ~
23840 \SpecialChar ~
23841 \SpecialChar ~
23842 \SpecialChar ~
23843 \SpecialChar ~
23844 \SpecialChar ~
23845 switch (i) {
23846 \newline
23847 \SpecialChar ~
23848 \SpecialChar ~
23849 \SpecialChar ~
23850 case 4: ...\SpecialChar ~
23851 \SpecialChar ~
23852 \SpecialChar ~
23853 \SpecialChar ~
23854 \SpecialChar ~
23855 \SpecialChar ~
23856 \SpecialChar ~
23857 \SpecialChar ~
23858 \SpecialChar ~
23859 \SpecialChar ~
23860 \SpecialChar ~
23861 \SpecialChar ~
23862 \SpecialChar ~
23863 \SpecialChar ~
23864 \SpecialChar ~
23865 \SpecialChar ~
23866 \SpecialChar ~
23867 \SpecialChar ~
23868 \SpecialChar ~
23869 \SpecialChar ~
23870 \SpecialChar ~
23871 \SpecialChar ~
23872 \SpecialChar ~
23873 \SpecialChar ~
23874 \SpecialChar ~
23875 \SpecialChar ~
23876 case 0: ...
23877
23878 \newline
23879 \SpecialChar ~
23880 \SpecialChar ~
23881 \SpecialChar ~
23882 case 5: ...\SpecialChar ~
23883 \SpecialChar ~
23884 \SpecialChar ~
23885 \SpecialChar ~
23886 \SpecialChar ~
23887 \SpecialChar ~
23888 \SpecialChar ~
23889 \SpecialChar ~
23890 \SpecialChar ~
23891 \SpecialChar ~
23892 \SpecialChar ~
23893 \SpecialChar ~
23894 \SpecialChar ~
23895 \SpecialChar ~
23896 \SpecialChar ~
23897 \SpecialChar ~
23898 \SpecialChar ~
23899 \SpecialChar ~
23900 \SpecialChar ~
23901 \SpecialChar ~
23902 \SpecialChar ~
23903 \SpecialChar ~
23904 \SpecialChar ~
23905 \SpecialChar ~
23906 \SpecialChar ~
23907 \SpecialChar ~
23908 case 1: ...
23909
23910 \newline
23911 \SpecialChar ~
23912 \SpecialChar ~
23913 \SpecialChar ~
23914 case 3: ...\SpecialChar ~
23915 \SpecialChar ~
23916 \SpecialChar ~
23917 \SpecialChar ~
23918 \SpecialChar ~
23919 \SpecialChar ~
23920 \SpecialChar ~
23921 \SpecialChar ~
23922 \SpecialChar ~
23923 \SpecialChar ~
23924 \SpecialChar ~
23925 \SpecialChar ~
23926 \SpecialChar ~
23927 \SpecialChar ~
23928 \SpecialChar ~
23929 \SpecialChar ~
23930 \SpecialChar ~
23931 \SpecialChar ~
23932 \SpecialChar ~
23933 \SpecialChar ~
23934 \SpecialChar ~
23935 \SpecialChar ~
23936 \SpecialChar ~
23937 \SpecialChar ~
23938 \SpecialChar ~
23939 \SpecialChar ~
23940
23941 \newline
23942 \SpecialChar ~
23943 \SpecialChar ~
23944 \SpecialChar ~
23945 case 6: ...\SpecialChar ~
23946 \SpecialChar ~
23947 \SpecialChar ~
23948 \SpecialChar ~
23949 \SpecialChar ~
23950 \SpecialChar ~
23951 \SpecialChar ~
23952 \SpecialChar ~
23953 \SpecialChar ~
23954 \SpecialChar ~
23955 \SpecialChar ~
23956 \SpecialChar ~
23957 \SpecialChar ~
23958 \SpecialChar ~
23959 \SpecialChar ~
23960 \SpecialChar ~
23961 \SpecialChar ~
23962 \SpecialChar ~
23963 \SpecialChar ~
23964 \SpecialChar ~
23965 \SpecialChar ~
23966 \SpecialChar ~
23967 \SpecialChar ~
23968 \SpecialChar ~
23969 \SpecialChar ~
23970 \SpecialChar ~
23971 case 3: ...
23972
23973 \newline
23974 \SpecialChar ~
23975 \SpecialChar ~
23976 \SpecialChar ~
23977 case 7: ...\SpecialChar ~
23978 \SpecialChar ~
23979 \SpecialChar ~
23980 \SpecialChar ~
23981 \SpecialChar ~
23982 \SpecialChar ~
23983 \SpecialChar ~
23984 \SpecialChar ~
23985 \SpecialChar ~
23986 \SpecialChar ~
23987 \SpecialChar ~
23988 \SpecialChar ~
23989 \SpecialChar ~
23990 \SpecialChar ~
23991 \SpecialChar ~
23992 \SpecialChar ~
23993 \SpecialChar ~
23994 \SpecialChar ~
23995 \SpecialChar ~
23996 \SpecialChar ~
23997 \SpecialChar ~
23998 \SpecialChar ~
23999 \SpecialChar ~
24000 \SpecialChar ~
24001 \SpecialChar ~
24002 \SpecialChar ~
24003 case 4: ...
24004
24005 \newline
24006 \SpecialChar ~
24007 \SpecialChar ~
24008 \SpecialChar ~
24009 case 8: ...\SpecialChar ~
24010 \SpecialChar ~
24011 \SpecialChar ~
24012 \SpecialChar ~
24013 \SpecialChar ~
24014 \SpecialChar ~
24015 \SpecialChar ~
24016 \SpecialChar ~
24017 \SpecialChar ~
24018 \SpecialChar ~
24019 \SpecialChar ~
24020 \SpecialChar ~
24021 \SpecialChar ~
24022 \SpecialChar ~
24023 \SpecialChar ~
24024 \SpecialChar ~
24025 \SpecialChar ~
24026 \SpecialChar ~
24027 \SpecialChar ~
24028 \SpecialChar ~
24029 \SpecialChar ~
24030 \SpecialChar ~
24031 \SpecialChar ~
24032 \SpecialChar ~
24033 \SpecialChar ~
24034 \SpecialChar ~
24035 case 5: ...
24036
24037 \newline
24038 \SpecialChar ~
24039 \SpecialChar ~
24040 \SpecialChar ~
24041 case 9: ...\SpecialChar ~
24042 \SpecialChar ~
24043 \SpecialChar ~
24044 \SpecialChar ~
24045 \SpecialChar ~
24046 \SpecialChar ~
24047 \SpecialChar ~
24048 \SpecialChar ~
24049 \SpecialChar ~
24050 \SpecialChar ~
24051 \SpecialChar ~
24052 \SpecialChar ~
24053 \SpecialChar ~
24054 \SpecialChar ~
24055 \SpecialChar ~
24056 \SpecialChar ~
24057 \SpecialChar ~
24058 \SpecialChar ~
24059 \SpecialChar ~
24060 \SpecialChar ~
24061 \SpecialChar ~
24062 \SpecialChar ~
24063 \SpecialChar ~
24064 \SpecialChar ~
24065 \SpecialChar ~
24066 \SpecialChar ~
24067 case 6: ...
24068
24069 \newline
24070 \SpecialChar ~
24071 \SpecialChar ~
24072 \SpecialChar ~
24073 case 10: ...\SpecialChar ~
24074 \SpecialChar ~
24075 \SpecialChar ~
24076 \SpecialChar ~
24077 \SpecialChar ~
24078 \SpecialChar ~
24079 \SpecialChar ~
24080 \SpecialChar ~
24081 \SpecialChar ~
24082 \SpecialChar ~
24083 \SpecialChar ~
24084 \SpecialChar ~
24085 \SpecialChar ~
24086 \SpecialChar ~
24087 \SpecialChar ~
24088 \SpecialChar ~
24089 \SpecialChar ~
24090 \SpecialChar ~
24091 \SpecialChar ~
24092 \SpecialChar ~
24093 \SpecialChar ~
24094 \SpecialChar ~
24095 \SpecialChar ~
24096 \SpecialChar ~
24097 \SpecialChar ~
24098 case 7: ...
24099
24100 \newline
24101 \SpecialChar ~
24102 \SpecialChar ~
24103 \SpecialChar ~
24104 case 11: ...\SpecialChar ~
24105 \SpecialChar ~
24106 \SpecialChar ~
24107 \SpecialChar ~
24108 \SpecialChar ~
24109 \SpecialChar ~
24110 \SpecialChar ~
24111 \SpecialChar ~
24112 \SpecialChar ~
24113 \SpecialChar ~
24114 \SpecialChar ~
24115 \SpecialChar ~
24116 \SpecialChar ~
24117 \SpecialChar ~
24118 \SpecialChar ~
24119 \SpecialChar ~
24120 \SpecialChar ~
24121 \SpecialChar ~
24122 \SpecialChar ~
24123 \SpecialChar ~
24124 \SpecialChar ~
24125 \SpecialChar ~
24126 \SpecialChar ~
24127 \SpecialChar ~
24128 \SpecialChar ~
24129 case 8: ...
24130
24131 \newline
24132 }\SpecialChar ~
24133 \SpecialChar ~
24134 \SpecialChar ~
24135 \SpecialChar ~
24136 \SpecialChar ~
24137 \SpecialChar ~
24138 \SpecialChar ~
24139 \SpecialChar ~
24140 \SpecialChar ~
24141 \SpecialChar ~
24142 \SpecialChar ~
24143 \SpecialChar ~
24144 \SpecialChar ~
24145 \SpecialChar ~
24146 \SpecialChar ~
24147 \SpecialChar ~
24148 \SpecialChar ~
24149 \SpecialChar ~
24150 \SpecialChar ~
24151 \SpecialChar ~
24152 \SpecialChar ~
24153 \SpecialChar ~
24154 \SpecialChar ~
24155 \SpecialChar ~
24156 \SpecialChar ~
24157 \SpecialChar ~
24158 \SpecialChar ~
24159 \SpecialChar ~
24160 \SpecialChar ~
24161 \SpecialChar ~
24162 \SpecialChar ~
24163 \SpecialChar ~
24164 \SpecialChar ~
24165 \SpecialChar ~
24166 \SpecialChar ~
24167 \SpecialChar ~
24168 }
24169 \layout Standard
24170
24171 Both the above switch statements will be implemented using a jump-table.
24172  The example to the right side is slightly more efficient as the check for
24173  the lower boundary of the jump-table is not needed.
24174 \end_deeper
24175 \layout Itemize
24176
24177 The number of case labels is not larger than supported by the target architectur
24178 e.
24179 \layout Itemize
24180
24181 If the case labels are not in numerical sequence ('gaps' between cases)
24182  SDCC checks whether a jump table with additionally inserted dummy cases
24183  is still attractive.
24184
24185 \layout Itemize
24186
24187 If the starting number is not zero and a check for the lower boundary of
24188  the jump-table can thus be eliminated SDCC might insert dummy cases 0,
24189  ...
24190  .
24191 \layout Standard
24192
24193 Switch statements which have large gaps in the numeric sequence or those
24194  that have too many case labels can be split into more than one switch statement
24195  for efficient code generation, e.g.:
24196 \layout Verse
24197
24198
24199 \family typewriter
24200 switch (i) {
24201 \newline
24202 \SpecialChar ~
24203 \SpecialChar ~
24204 case 1: ...
24205
24206 \newline
24207 \SpecialChar ~
24208 \SpecialChar ~
24209 case 2: ...
24210
24211 \newline
24212 \SpecialChar ~
24213 \SpecialChar ~
24214 case 3: ...
24215
24216 \newline
24217 \SpecialChar ~
24218 \SpecialChar ~
24219 case 4: ...
24220
24221 \newline
24222 \SpecialChar ~
24223 \SpecialChar ~
24224 case 5: ...
24225
24226 \newline
24227 \SpecialChar ~
24228 \SpecialChar ~
24229 case 6: ...
24230
24231 \newline
24232 \SpecialChar ~
24233 \SpecialChar ~
24234 case 7: ...
24235
24236 \newline
24237 \SpecialChar ~
24238 \SpecialChar ~
24239 case 101: ...
24240
24241 \newline
24242 \SpecialChar ~
24243 \SpecialChar ~
24244 case 102: ...
24245
24246 \newline
24247 \SpecialChar ~
24248 \SpecialChar ~
24249 case 103: ...
24250
24251 \newline
24252 \SpecialChar ~
24253 \SpecialChar ~
24254 case 104: ...
24255
24256 \newline
24257 \SpecialChar ~
24258 \SpecialChar ~
24259 case 105: ...
24260
24261 \newline
24262 \SpecialChar ~
24263 \SpecialChar ~
24264 case 106: ...
24265
24266 \newline
24267 \SpecialChar ~
24268 \SpecialChar ~
24269 case 107: ...
24270
24271 \newline
24272 }
24273 \layout Standard
24274
24275 If the above switch statement is broken down into two switch statements
24276 \layout Verse
24277
24278
24279 \family typewriter
24280 switch (i) {
24281 \newline
24282 \SpecialChar ~
24283 \SpecialChar ~
24284 case 1: ...
24285
24286 \newline
24287 \SpecialChar ~
24288 \SpecialChar ~
24289 case 2: ...
24290
24291 \newline
24292 \SpecialChar ~
24293 \SpecialChar ~
24294 case 3: ...
24295
24296 \newline
24297 \SpecialChar ~
24298 \SpecialChar ~
24299 case 4: ...
24300
24301 \newline
24302 \SpecialChar ~
24303 \SpecialChar ~
24304 case 5: ...
24305
24306 \newline
24307 \SpecialChar ~
24308 \SpecialChar ~
24309 case 6: ...
24310
24311 \newline
24312 \SpecialChar ~
24313 \SpecialChar ~
24314 case 7: ...
24315
24316 \newline
24317 }
24318 \layout Standard
24319
24320 and
24321 \layout Verse
24322
24323
24324 \family typewriter
24325 switch (i) {
24326 \newline
24327 \SpecialChar ~
24328 \SpecialChar ~
24329 case 101: ...
24330
24331 \newline
24332 \SpecialChar ~
24333 \SpecialChar ~
24334 case 102: ...
24335
24336 \newline
24337 \SpecialChar ~
24338 \SpecialChar ~
24339 case 103: ...
24340
24341 \newline
24342 \SpecialChar ~
24343 \SpecialChar ~
24344 case 104: ...
24345
24346 \newline
24347 \SpecialChar ~
24348 \SpecialChar ~
24349 case 105: ...
24350
24351 \newline
24352 \SpecialChar ~
24353 \SpecialChar ~
24354 case 106: ...
24355
24356 \newline
24357 \SpecialChar ~
24358 \SpecialChar ~
24359 case 107: ...
24360
24361 \newline
24362 }
24363 \layout Standard
24364
24365 then both the switch statements will be implemented using jump-tables whereas
24366  the unmodified switch statement will not be.
24367 \layout Comment
24368
24369 There might be reasons which SDCC cannot know about to either favour or
24370  not favour jump tables.
24371  If the target system has to be as quick for the last switch case as for
24372  the first (pro jump table), or if the switch argument is known to be zero
24373  in the majority of the cases (contra jump table).
24374 \layout Standard
24375
24376 The pragma nojtbound
24377 \begin_inset LatexCommand \index{\#pragma nojtbound}
24378
24379 \end_inset
24380
24381  can be used to turn off checking the
24382 \emph on
24383 j
24384 \emph default
24385 ump
24386 \emph on
24387 t
24388 \emph default
24389 able
24390 \emph on
24391 bound
24392 \emph default
24393 aries.
24394  It has no effect if a default label is supplied.
24395  Use of this pragma is dangerous: if the switch
24396 \begin_inset LatexCommand \index{switch statement}
24397
24398 \end_inset
24399
24400  argument is not matched by a case statement the processor will happily
24401  jump into Nirvana.
24402 \layout Subsection
24403
24404 Bit-shifting Operations
24405 \begin_inset LatexCommand \index{Bit shifting}
24406
24407 \end_inset
24408
24409 .
24410 \layout Standard
24411
24412 Bit shifting is one of the most frequently used operation in embedded programmin
24413 g.
24414  SDCC tries to implement bit-shift operations in the most efficient way
24415  possible, e.g.:
24416 \layout Verse
24417
24418
24419 \family typewriter
24420 unsigned char i;
24421 \newline
24422 ...
24423
24424 \newline
24425 i >>= 4;
24426 \newline
24427 ...
24428 \layout Standard
24429
24430 generates the following code:
24431 \layout Verse
24432
24433
24434 \family typewriter
24435 mov\SpecialChar ~
24436  a,_i
24437 \newline
24438 swap a
24439 \newline
24440 anl\SpecialChar ~
24441  a,#0x0f
24442 \newline
24443 mov\SpecialChar ~
24444  _i,a
24445 \layout Standard
24446
24447 In general SDCC will never setup a loop if the shift count is known.
24448  Another example:
24449 \layout Verse
24450
24451
24452 \family typewriter
24453 unsigned int i;
24454 \newline
24455 ...
24456
24457 \newline
24458 i >>= 9;
24459 \newline
24460 ...
24461 \layout Standard
24462
24463 will generate:
24464 \layout Verse
24465
24466
24467 \family typewriter
24468 mov\SpecialChar ~
24469 \SpecialChar ~
24470 a,(_i + 1)
24471 \newline
24472 mov\SpecialChar ~
24473 \SpecialChar ~
24474 (_i + 1),#0x00
24475 \newline
24476 clr\SpecialChar ~
24477 \SpecialChar ~
24478 c
24479 \newline
24480 rrc\SpecialChar ~
24481 \SpecialChar ~
24482 a
24483 \newline
24484 mov\SpecialChar ~
24485 \SpecialChar ~
24486 _i,a
24487 \layout Subsection
24488
24489 Bit-rotation
24490 \begin_inset LatexCommand \index{Bit rotation}
24491
24492 \end_inset
24493
24494
24495 \layout Standard
24496
24497 A special case of the bit-shift operation is bit rotation
24498 \begin_inset LatexCommand \index{rotating bits}
24499
24500 \end_inset
24501
24502 , SDCC recognizes the following expression to be a left bit-rotation:
24503 \layout Verse
24504
24505
24506 \family typewriter
24507 \series bold
24508 unsigned
24509 \series default
24510 \SpecialChar ~
24511 \SpecialChar ~
24512 char i;\SpecialChar ~
24513 \SpecialChar ~
24514 \SpecialChar ~
24515 \SpecialChar ~
24516 \SpecialChar ~
24517 \SpecialChar ~
24518 \SpecialChar ~
24519 \SpecialChar ~
24520 \SpecialChar ~
24521 \SpecialChar ~
24522 \SpecialChar ~
24523 /* unsigned is needed for rotation */
24524 \newline
24525 ...
24526
24527 \newline
24528 i = ((i << 1) | (i >> 7));
24529 \family default
24530
24531 \newline
24532
24533 \family typewriter
24534 ...
24535 \layout Standard
24536
24537 will generate the following code:
24538 \layout Verse
24539
24540
24541 \family typewriter
24542 mov\SpecialChar ~
24543 \SpecialChar ~
24544 a,_i
24545 \newline
24546 rl\SpecialChar ~
24547 \SpecialChar ~
24548 \SpecialChar ~
24549 a
24550 \newline
24551 mov\SpecialChar ~
24552 \SpecialChar ~
24553 _i,a
24554 \layout Standard
24555
24556 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
24557 ns of this case will also be recognized as bit-rotation, i.e.:
24558 \layout Verse
24559
24560
24561 \family typewriter
24562 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
24563 \layout Subsection
24564
24565 Nibble and Byte Swapping
24566 \layout Standard
24567
24568 Other special cases of the bit-shift operations are nibble or byte swapping
24569 \begin_inset LatexCommand \index{swapping nibbles/bytes}
24570
24571 \end_inset
24572
24573 , SDCC recognizes the following expressions:
24574 \layout Verse
24575
24576
24577 \family typewriter
24578 \series bold
24579 unsigned
24580 \series default
24581 \SpecialChar ~
24582 \SpecialChar ~
24583 char i;
24584 \newline
24585
24586 \series bold
24587 unsigned
24588 \series default
24589 \SpecialChar ~
24590 \SpecialChar ~
24591 int j;
24592 \newline
24593 ...
24594
24595 \newline
24596 i = ((i << 4) | (i >> 4));
24597 \family default
24598
24599 \newline
24600
24601 \family typewriter
24602 j = ((j << 8) | (j >> 8));
24603 \layout Standard
24604
24605 and generates a swap instruction for the nibble swapping
24606 \begin_inset LatexCommand \index{Nibble swapping}
24607
24608 \end_inset
24609
24610  or move instructions for the byte swapping
24611 \begin_inset LatexCommand \index{Byte swapping}
24612
24613 \end_inset
24614
24615 .
24616  The
24617 \begin_inset Quotes sld
24618 \end_inset
24619
24620 j
24621 \begin_inset Quotes srd
24622 \end_inset
24623
24624  example can be used to convert from little to big-endian or vice versa.
24625  If you want to change the endianness of a
24626 \emph on
24627 signed
24628 \emph default
24629  integer you have to cast to
24630 \family typewriter
24631 (unsigned int)
24632 \family default
24633  first.
24634 \layout Standard
24635
24636 Note that SDCC stores numbers in little-endian
24637 \begin_inset Foot
24638 collapsed false
24639
24640 \layout Standard
24641
24642 Usually 8-bit processors don't care much about endianness.
24643  This is not the case for the standard 8051 which only has an instruction
24644  to increment its
24645 \emph on
24646 dptr
24647 \emph default
24648
24649 \begin_inset LatexCommand \index{DPTR}
24650
24651 \end_inset
24652
24653 -datapointer
24654 \emph on
24655
24656 \emph default
24657 so little-endian is the more efficient byte order.
24658 \end_inset
24659
24660
24661 \begin_inset LatexCommand \index{little-endian}
24662
24663 \end_inset
24664
24665
24666 \begin_inset LatexCommand \index{Endianness}
24667
24668 \end_inset
24669
24670  format (i.e.
24671  lowest order first).
24672 \layout Subsection
24673
24674 Highest Order Bit
24675 \begin_inset LatexCommand \index{Highest Order Bit}
24676
24677 \end_inset
24678
24679  / Any Order Bit
24680 \begin_inset LatexCommand \index{Any Order Bit}
24681
24682 \end_inset
24683
24684
24685 \layout Standard
24686
24687 It is frequently required to obtain the highest order bit of an integral
24688  type (long, int, short or char types).
24689  Also obtaining any other order bit is not uncommon.
24690  SDCC recognizes the following expressions to yield the highest order bit
24691  and generates optimized code for it, e.g.:
24692 \layout Verse
24693
24694
24695 \family typewriter
24696 unsigned int gint;
24697 \newline
24698
24699 \newline
24700 foo () {
24701 \newline
24702 \SpecialChar ~
24703 \SpecialChar ~
24704 unsigned char hob1, aob1;
24705 \newline
24706 \SpecialChar ~
24707 \SpecialChar ~
24708 bit hob2, hob3, aob2, aob3;
24709 \newline
24710 \SpecialChar ~
24711 \SpecialChar ~
24712 ...
24713
24714 \newline
24715 \SpecialChar ~
24716 \SpecialChar ~
24717 hob1 = (gint >> 15) & 1;
24718 \newline
24719 \SpecialChar ~
24720 \SpecialChar ~
24721 hob2 = (gint >> 15) & 1;
24722 \newline
24723 \SpecialChar ~
24724 \SpecialChar ~
24725 hob3 = gint & 0x8000;
24726 \newline
24727 \SpecialChar ~
24728 \SpecialChar ~
24729 aob1 = (gint >> 9) & 1;
24730 \newline
24731 \SpecialChar ~
24732 \SpecialChar ~
24733 aob2 = (gint >> 8) & 1;
24734 \newline
24735 \SpecialChar ~
24736 \SpecialChar ~
24737 aob3 = gint & 0x0800;
24738 \newline
24739 \SpecialChar ~
24740 \SpecialChar ~
24741 ..
24742
24743 \newline
24744 }
24745 \layout Standard
24746
24747 will generate the following code:
24748 \layout Verse
24749
24750
24751 \family typewriter
24752 \SpecialChar ~
24753 \SpecialChar ~
24754 \SpecialChar ~
24755 \SpecialChar ~
24756 \SpecialChar ~
24757 \SpecialChar ~
24758 \SpecialChar ~
24759 \SpecialChar ~
24760 \SpecialChar ~
24761 \SpecialChar ~
24762 \SpecialChar ~
24763 \SpecialChar ~
24764 \SpecialChar ~
24765 \SpecialChar ~
24766 \SpecialChar ~
24767 \SpecialChar ~
24768 \SpecialChar ~
24769 \SpecialChar ~
24770 \SpecialChar ~
24771 \SpecialChar ~
24772 \SpecialChar ~
24773 \SpecialChar ~
24774 \SpecialChar ~
24775 \SpecialChar ~
24776 \SpecialChar ~
24777  61 ;\SpecialChar ~
24778  hob.c 7
24779 \newline
24780 000A E5*01\SpecialChar ~
24781 \SpecialChar ~
24782 \SpecialChar ~
24783 \SpecialChar ~
24784 \SpecialChar ~
24785 \SpecialChar ~
24786 \SpecialChar ~
24787 \SpecialChar ~
24788 \SpecialChar ~
24789 \SpecialChar ~
24790 \SpecialChar ~
24791 \SpecialChar ~
24792 \SpecialChar ~
24793 \SpecialChar ~
24794 \SpecialChar ~
24795  62\SpecialChar ~
24796 \SpecialChar ~
24797 \SpecialChar ~
24798 \SpecialChar ~
24799 \SpecialChar ~
24800 \SpecialChar ~
24801 \SpecialChar ~
24802 \SpecialChar ~
24803  mov\SpecialChar ~
24804 \SpecialChar ~
24805  a,(_gint + 1)
24806 \newline
24807 000C 23\SpecialChar ~
24808 \SpecialChar ~
24809 \SpecialChar ~
24810 \SpecialChar ~
24811 \SpecialChar ~
24812 \SpecialChar ~
24813 \SpecialChar ~
24814 \SpecialChar ~
24815 \SpecialChar ~
24816 \SpecialChar ~
24817 \SpecialChar ~
24818 \SpecialChar ~
24819 \SpecialChar ~
24820 \SpecialChar ~
24821 \SpecialChar ~
24822 \SpecialChar ~
24823 \SpecialChar ~
24824 \SpecialChar ~
24825  63\SpecialChar ~
24826 \SpecialChar ~
24827 \SpecialChar ~
24828 \SpecialChar ~
24829 \SpecialChar ~
24830 \SpecialChar ~
24831 \SpecialChar ~
24832 \SpecialChar ~
24833  rl\SpecialChar ~
24834 \SpecialChar ~
24835 \SpecialChar ~
24836  a
24837 \newline
24838 000D 54 01\SpecialChar ~
24839 \SpecialChar ~
24840 \SpecialChar ~
24841 \SpecialChar ~
24842 \SpecialChar ~
24843 \SpecialChar ~
24844 \SpecialChar ~
24845 \SpecialChar ~
24846 \SpecialChar ~
24847 \SpecialChar ~
24848 \SpecialChar ~
24849 \SpecialChar ~
24850 \SpecialChar ~
24851 \SpecialChar ~
24852 \SpecialChar ~
24853  64\SpecialChar ~
24854 \SpecialChar ~
24855 \SpecialChar ~
24856 \SpecialChar ~
24857 \SpecialChar ~
24858 \SpecialChar ~
24859 \SpecialChar ~
24860 \SpecialChar ~
24861  anl\SpecialChar ~
24862 \SpecialChar ~
24863  a,#0x01
24864 \newline
24865 000F F5*02\SpecialChar ~
24866 \SpecialChar ~
24867 \SpecialChar ~
24868 \SpecialChar ~
24869 \SpecialChar ~
24870 \SpecialChar ~
24871 \SpecialChar ~
24872 \SpecialChar ~
24873 \SpecialChar ~
24874 \SpecialChar ~
24875 \SpecialChar ~
24876 \SpecialChar ~
24877 \SpecialChar ~
24878 \SpecialChar ~
24879 \SpecialChar ~
24880  65\SpecialChar ~
24881 \SpecialChar ~
24882 \SpecialChar ~
24883 \SpecialChar ~
24884 \SpecialChar ~
24885 \SpecialChar ~
24886 \SpecialChar ~
24887 \SpecialChar ~
24888  mov\SpecialChar ~
24889 \SpecialChar ~
24890  _foo_hob1_1_1,a
24891 \newline
24892 \SpecialChar ~
24893 \SpecialChar ~
24894 \SpecialChar ~
24895 \SpecialChar ~
24896 \SpecialChar ~
24897 \SpecialChar ~
24898 \SpecialChar ~
24899 \SpecialChar ~
24900 \SpecialChar ~
24901 \SpecialChar ~
24902 \SpecialChar ~
24903 \SpecialChar ~
24904 \SpecialChar ~
24905 \SpecialChar ~
24906 \SpecialChar ~
24907 \SpecialChar ~
24908 \SpecialChar ~
24909 \SpecialChar ~
24910 \SpecialChar ~
24911 \SpecialChar ~
24912 \SpecialChar ~
24913 \SpecialChar ~
24914 \SpecialChar ~
24915 \SpecialChar ~
24916 \SpecialChar ~
24917  66 ;\SpecialChar ~
24918  hob.c 8
24919 \newline
24920 0011 E5*01\SpecialChar ~
24921 \SpecialChar ~
24922 \SpecialChar ~
24923 \SpecialChar ~
24924 \SpecialChar ~
24925 \SpecialChar ~
24926 \SpecialChar ~
24927 \SpecialChar ~
24928 \SpecialChar ~
24929 \SpecialChar ~
24930 \SpecialChar ~
24931 \SpecialChar ~
24932 \SpecialChar ~
24933 \SpecialChar ~
24934 \SpecialChar ~
24935  67\SpecialChar ~
24936 \SpecialChar ~
24937 \SpecialChar ~
24938 \SpecialChar ~
24939 \SpecialChar ~
24940 \SpecialChar ~
24941 \SpecialChar ~
24942 \SpecialChar ~
24943  mov\SpecialChar ~
24944 \SpecialChar ~
24945  a,(_gint + 1)
24946 \newline
24947 0013 33\SpecialChar ~
24948 \SpecialChar ~
24949 \SpecialChar ~
24950 \SpecialChar ~
24951 \SpecialChar ~
24952 \SpecialChar ~
24953 \SpecialChar ~
24954 \SpecialChar ~
24955 \SpecialChar ~
24956 \SpecialChar ~
24957 \SpecialChar ~
24958 \SpecialChar ~
24959 \SpecialChar ~
24960 \SpecialChar ~
24961 \SpecialChar ~
24962 \SpecialChar ~
24963 \SpecialChar ~
24964 \SpecialChar ~
24965  68\SpecialChar ~
24966 \SpecialChar ~
24967 \SpecialChar ~
24968 \SpecialChar ~
24969 \SpecialChar ~
24970 \SpecialChar ~
24971 \SpecialChar ~
24972 \SpecialChar ~
24973  rlc\SpecialChar ~
24974 \SpecialChar ~
24975  a
24976 \newline
24977 0014 92*00\SpecialChar ~
24978 \SpecialChar ~
24979 \SpecialChar ~
24980 \SpecialChar ~
24981 \SpecialChar ~
24982 \SpecialChar ~
24983 \SpecialChar ~
24984 \SpecialChar ~
24985 \SpecialChar ~
24986 \SpecialChar ~
24987 \SpecialChar ~
24988 \SpecialChar ~
24989 \SpecialChar ~
24990 \SpecialChar ~
24991 \SpecialChar ~
24992  69\SpecialChar ~
24993 \SpecialChar ~
24994 \SpecialChar ~
24995 \SpecialChar ~
24996 \SpecialChar ~
24997 \SpecialChar ~
24998 \SpecialChar ~
24999 \SpecialChar ~
25000  mov\SpecialChar ~
25001 \SpecialChar ~
25002  _foo_hob2_1_1,c
25003 \newline
25004 \SpecialChar ~
25005 \SpecialChar ~
25006 \SpecialChar ~
25007 \SpecialChar ~
25008 \SpecialChar ~
25009 \SpecialChar ~
25010 \SpecialChar ~
25011 \SpecialChar ~
25012 \SpecialChar ~
25013 \SpecialChar ~
25014 \SpecialChar ~
25015 \SpecialChar ~
25016 \SpecialChar ~
25017 \SpecialChar ~
25018 \SpecialChar ~
25019 \SpecialChar ~
25020 \SpecialChar ~
25021 \SpecialChar ~
25022 \SpecialChar ~
25023 \SpecialChar ~
25024 \SpecialChar ~
25025 \SpecialChar ~
25026 \SpecialChar ~
25027 \SpecialChar ~
25028 \SpecialChar ~
25029  66 ;\SpecialChar ~
25030  hob.c 9
25031 \newline
25032 0016 E5*01\SpecialChar ~
25033 \SpecialChar ~
25034 \SpecialChar ~
25035 \SpecialChar ~
25036 \SpecialChar ~
25037 \SpecialChar ~
25038 \SpecialChar ~
25039 \SpecialChar ~
25040 \SpecialChar ~
25041 \SpecialChar ~
25042 \SpecialChar ~
25043 \SpecialChar ~
25044 \SpecialChar ~
25045 \SpecialChar ~
25046 \SpecialChar ~
25047  67\SpecialChar ~
25048 \SpecialChar ~
25049 \SpecialChar ~
25050 \SpecialChar ~
25051 \SpecialChar ~
25052 \SpecialChar ~
25053 \SpecialChar ~
25054 \SpecialChar ~
25055  mov\SpecialChar ~
25056 \SpecialChar ~
25057  a,(_gint + 1)
25058 \newline
25059 0018 33\SpecialChar ~
25060 \SpecialChar ~
25061 \SpecialChar ~
25062 \SpecialChar ~
25063 \SpecialChar ~
25064 \SpecialChar ~
25065 \SpecialChar ~
25066 \SpecialChar ~
25067 \SpecialChar ~
25068 \SpecialChar ~
25069 \SpecialChar ~
25070 \SpecialChar ~
25071 \SpecialChar ~
25072 \SpecialChar ~
25073 \SpecialChar ~
25074 \SpecialChar ~
25075 \SpecialChar ~
25076 \SpecialChar ~
25077  68\SpecialChar ~
25078 \SpecialChar ~
25079 \SpecialChar ~
25080 \SpecialChar ~
25081 \SpecialChar ~
25082 \SpecialChar ~
25083 \SpecialChar ~
25084 \SpecialChar ~
25085  rlc\SpecialChar ~
25086 \SpecialChar ~
25087  a
25088 \newline
25089 0019 92*01\SpecialChar ~
25090 \SpecialChar ~
25091 \SpecialChar ~
25092 \SpecialChar ~
25093 \SpecialChar ~
25094 \SpecialChar ~
25095 \SpecialChar ~
25096 \SpecialChar ~
25097 \SpecialChar ~
25098 \SpecialChar ~
25099 \SpecialChar ~
25100 \SpecialChar ~
25101 \SpecialChar ~
25102 \SpecialChar ~
25103 \SpecialChar ~
25104  69\SpecialChar ~
25105 \SpecialChar ~
25106 \SpecialChar ~
25107 \SpecialChar ~
25108 \SpecialChar ~
25109 \SpecialChar ~
25110 \SpecialChar ~
25111 \SpecialChar ~
25112  mov\SpecialChar ~
25113 \SpecialChar ~
25114  _foo_hob3_1_1,c
25115 \newline
25116 \SpecialChar ~
25117 \SpecialChar ~
25118 \SpecialChar ~
25119 \SpecialChar ~
25120 \SpecialChar ~
25121 \SpecialChar ~
25122 \SpecialChar ~
25123 \SpecialChar ~
25124 \SpecialChar ~
25125 \SpecialChar ~
25126 \SpecialChar ~
25127 \SpecialChar ~
25128 \SpecialChar ~
25129 \SpecialChar ~
25130 \SpecialChar ~
25131 \SpecialChar ~
25132 \SpecialChar ~
25133 \SpecialChar ~
25134 \SpecialChar ~
25135 \SpecialChar ~
25136 \SpecialChar ~
25137 \SpecialChar ~
25138 \SpecialChar ~
25139 \SpecialChar ~
25140 \SpecialChar ~
25141  70 ;\SpecialChar ~
25142  hob.c 10
25143 \newline
25144 001B E5*01\SpecialChar ~
25145 \SpecialChar ~
25146 \SpecialChar ~
25147 \SpecialChar ~
25148 \SpecialChar ~
25149 \SpecialChar ~
25150 \SpecialChar ~
25151 \SpecialChar ~
25152 \SpecialChar ~
25153 \SpecialChar ~
25154 \SpecialChar ~
25155 \SpecialChar ~
25156 \SpecialChar ~
25157 \SpecialChar ~
25158 \SpecialChar ~
25159  71\SpecialChar ~
25160 \SpecialChar ~
25161 \SpecialChar ~
25162 \SpecialChar ~
25163 \SpecialChar ~
25164 \SpecialChar ~
25165 \SpecialChar ~
25166 \SpecialChar ~
25167  mov\SpecialChar ~
25168 \SpecialChar ~
25169  a,(_gint + 1)
25170 \newline
25171 001D 03\SpecialChar ~
25172 \SpecialChar ~
25173 \SpecialChar ~
25174 \SpecialChar ~
25175 \SpecialChar ~
25176 \SpecialChar ~
25177 \SpecialChar ~
25178 \SpecialChar ~
25179 \SpecialChar ~
25180 \SpecialChar ~
25181 \SpecialChar ~
25182 \SpecialChar ~
25183 \SpecialChar ~
25184 \SpecialChar ~
25185 \SpecialChar ~
25186 \SpecialChar ~
25187 \SpecialChar ~
25188 \SpecialChar ~
25189  72\SpecialChar ~
25190 \SpecialChar ~
25191 \SpecialChar ~
25192 \SpecialChar ~
25193 \SpecialChar ~
25194 \SpecialChar ~
25195 \SpecialChar ~
25196 \SpecialChar ~
25197  rr\SpecialChar ~
25198 \SpecialChar ~
25199 \SpecialChar ~
25200  a
25201 \newline
25202 001E 54 01\SpecialChar ~
25203 \SpecialChar ~
25204 \SpecialChar ~
25205 \SpecialChar ~
25206 \SpecialChar ~
25207 \SpecialChar ~
25208 \SpecialChar ~
25209 \SpecialChar ~
25210 \SpecialChar ~
25211 \SpecialChar ~
25212 \SpecialChar ~
25213 \SpecialChar ~
25214 \SpecialChar ~
25215 \SpecialChar ~
25216 \SpecialChar ~
25217  73\SpecialChar ~
25218 \SpecialChar ~
25219 \SpecialChar ~
25220 \SpecialChar ~
25221 \SpecialChar ~
25222 \SpecialChar ~
25223 \SpecialChar ~
25224 \SpecialChar ~
25225  anl\SpecialChar ~
25226 \SpecialChar ~
25227  a,#0x01
25228 \newline
25229 0020 F5*03\SpecialChar ~
25230 \SpecialChar ~
25231 \SpecialChar ~
25232 \SpecialChar ~
25233 \SpecialChar ~
25234 \SpecialChar ~
25235 \SpecialChar ~
25236 \SpecialChar ~
25237 \SpecialChar ~
25238 \SpecialChar ~
25239 \SpecialChar ~
25240 \SpecialChar ~
25241 \SpecialChar ~
25242 \SpecialChar ~
25243 \SpecialChar ~
25244  74\SpecialChar ~
25245 \SpecialChar ~
25246 \SpecialChar ~
25247 \SpecialChar ~
25248 \SpecialChar ~
25249 \SpecialChar ~
25250 \SpecialChar ~
25251 \SpecialChar ~
25252  mov\SpecialChar ~
25253 \SpecialChar ~
25254  _foo_aob1_1_1,a
25255 \newline
25256 \SpecialChar ~
25257 \SpecialChar ~
25258 \SpecialChar ~
25259 \SpecialChar ~
25260 \SpecialChar ~
25261 \SpecialChar ~
25262 \SpecialChar ~
25263 \SpecialChar ~
25264 \SpecialChar ~
25265 \SpecialChar ~
25266 \SpecialChar ~
25267 \SpecialChar ~
25268 \SpecialChar ~
25269 \SpecialChar ~
25270 \SpecialChar ~
25271 \SpecialChar ~
25272 \SpecialChar ~
25273 \SpecialChar ~
25274 \SpecialChar ~
25275 \SpecialChar ~
25276 \SpecialChar ~
25277 \SpecialChar ~
25278 \SpecialChar ~
25279 \SpecialChar ~
25280 \SpecialChar ~
25281  75 ;\SpecialChar ~
25282  hob.c 11
25283 \newline
25284 0022 E5*01\SpecialChar ~
25285 \SpecialChar ~
25286 \SpecialChar ~
25287 \SpecialChar ~
25288 \SpecialChar ~
25289 \SpecialChar ~
25290 \SpecialChar ~
25291 \SpecialChar ~
25292 \SpecialChar ~
25293 \SpecialChar ~
25294 \SpecialChar ~
25295 \SpecialChar ~
25296 \SpecialChar ~
25297 \SpecialChar ~
25298 \SpecialChar ~
25299  76\SpecialChar ~
25300 \SpecialChar ~
25301 \SpecialChar ~
25302 \SpecialChar ~
25303 \SpecialChar ~
25304 \SpecialChar ~
25305 \SpecialChar ~
25306 \SpecialChar ~
25307  mov\SpecialChar ~
25308 \SpecialChar ~
25309  a,(_gint + 1)
25310 \newline
25311 0024 13\SpecialChar ~
25312 \SpecialChar ~
25313 \SpecialChar ~
25314 \SpecialChar ~
25315 \SpecialChar ~
25316 \SpecialChar ~
25317 \SpecialChar ~
25318 \SpecialChar ~
25319 \SpecialChar ~
25320 \SpecialChar ~
25321 \SpecialChar ~
25322 \SpecialChar ~
25323 \SpecialChar ~
25324 \SpecialChar ~
25325 \SpecialChar ~
25326 \SpecialChar ~
25327 \SpecialChar ~
25328 \SpecialChar ~
25329  77\SpecialChar ~
25330 \SpecialChar ~
25331 \SpecialChar ~
25332 \SpecialChar ~
25333 \SpecialChar ~
25334 \SpecialChar ~
25335 \SpecialChar ~
25336 \SpecialChar ~
25337  rrc\SpecialChar ~
25338 \SpecialChar ~
25339  a
25340 \newline
25341 0025 92*02\SpecialChar ~
25342 \SpecialChar ~
25343 \SpecialChar ~
25344 \SpecialChar ~
25345 \SpecialChar ~
25346 \SpecialChar ~
25347 \SpecialChar ~
25348 \SpecialChar ~
25349 \SpecialChar ~
25350 \SpecialChar ~
25351 \SpecialChar ~
25352 \SpecialChar ~
25353 \SpecialChar ~
25354 \SpecialChar ~
25355 \SpecialChar ~
25356  78\SpecialChar ~
25357 \SpecialChar ~
25358 \SpecialChar ~
25359 \SpecialChar ~
25360 \SpecialChar ~
25361 \SpecialChar ~
25362 \SpecialChar ~
25363 \SpecialChar ~
25364  mov\SpecialChar ~
25365 \SpecialChar ~
25366  _foo_aob2_1_1,c
25367 \newline
25368 \SpecialChar ~
25369 \SpecialChar ~
25370 \SpecialChar ~
25371 \SpecialChar ~
25372 \SpecialChar ~
25373 \SpecialChar ~
25374 \SpecialChar ~
25375 \SpecialChar ~
25376 \SpecialChar ~
25377 \SpecialChar ~
25378 \SpecialChar ~
25379 \SpecialChar ~
25380 \SpecialChar ~
25381 \SpecialChar ~
25382 \SpecialChar ~
25383 \SpecialChar ~
25384 \SpecialChar ~
25385 \SpecialChar ~
25386 \SpecialChar ~
25387 \SpecialChar ~
25388 \SpecialChar ~
25389 \SpecialChar ~
25390 \SpecialChar ~
25391 \SpecialChar ~
25392 \SpecialChar ~
25393  79 ;\SpecialChar ~
25394  hob.c 12
25395 \newline
25396 0027 E5*01\SpecialChar ~
25397 \SpecialChar ~
25398 \SpecialChar ~
25399 \SpecialChar ~
25400 \SpecialChar ~
25401 \SpecialChar ~
25402 \SpecialChar ~
25403 \SpecialChar ~
25404 \SpecialChar ~
25405 \SpecialChar ~
25406 \SpecialChar ~
25407 \SpecialChar ~
25408 \SpecialChar ~
25409 \SpecialChar ~
25410 \SpecialChar ~
25411  80\SpecialChar ~
25412 \SpecialChar ~
25413 \SpecialChar ~
25414 \SpecialChar ~
25415 \SpecialChar ~
25416 \SpecialChar ~
25417 \SpecialChar ~
25418 \SpecialChar ~
25419  mov\SpecialChar ~
25420 \SpecialChar ~
25421  a,(_gint + 1)
25422 \newline
25423 0029 A2 E3\SpecialChar ~
25424 \SpecialChar ~
25425 \SpecialChar ~
25426 \SpecialChar ~
25427 \SpecialChar ~
25428 \SpecialChar ~
25429 \SpecialChar ~
25430 \SpecialChar ~
25431 \SpecialChar ~
25432 \SpecialChar ~
25433 \SpecialChar ~
25434 \SpecialChar ~
25435 \SpecialChar ~
25436 \SpecialChar ~
25437 \SpecialChar ~
25438  81\SpecialChar ~
25439 \SpecialChar ~
25440 \SpecialChar ~
25441 \SpecialChar ~
25442 \SpecialChar ~
25443 \SpecialChar ~
25444 \SpecialChar ~
25445 \SpecialChar ~
25446  mov\SpecialChar ~
25447 \SpecialChar ~
25448  c,acc[3]
25449 \newline
25450 002B 92*03\SpecialChar ~
25451 \SpecialChar ~
25452 \SpecialChar ~
25453 \SpecialChar ~
25454 \SpecialChar ~
25455 \SpecialChar ~
25456 \SpecialChar ~
25457 \SpecialChar ~
25458 \SpecialChar ~
25459 \SpecialChar ~
25460 \SpecialChar ~
25461 \SpecialChar ~
25462 \SpecialChar ~
25463 \SpecialChar ~
25464 \SpecialChar ~
25465  82\SpecialChar ~
25466 \SpecialChar ~
25467 \SpecialChar ~
25468 \SpecialChar ~
25469 \SpecialChar ~
25470 \SpecialChar ~
25471 \SpecialChar ~
25472 \SpecialChar ~
25473  mov\SpecialChar ~
25474 \SpecialChar ~
25475  _foo_aob3_1_1,c
25476 \layout Standard
25477
25478 Other variations of these cases however will
25479 \emph on
25480 not
25481 \emph default
25482  be recognized.
25483  They are standard C expressions, so I heartily recommend these be the only
25484  way to get the highest order bit, (it is portable).
25485  Of course it will be recognized even if it is embedded in other expressions,
25486  e.g.:
25487 \layout Verse
25488
25489
25490 \family typewriter
25491 xyz = gint + ((gint >> 15) & 1);
25492 \layout Standard
25493
25494 will still be recognized.
25495 \layout Subsection
25496
25497 Higher Order Byte
25498 \begin_inset LatexCommand \index{Higher Order Byte}
25499
25500 \end_inset
25501
25502  / Higher Order Word
25503 \begin_inset LatexCommand \index{Higher Order Word}
25504
25505 \end_inset
25506
25507
25508 \layout Standard
25509
25510 It is also frequently required to obtain a higher order byte or word of
25511  a larger integral type (long, int or short types).
25512  SDCC recognizes the following expressions to yield the higher order byte
25513  or word and generates optimized code for it, e.g.:
25514 \layout Verse
25515
25516
25517 \family typewriter
25518 unsigned int gint;
25519 \newline
25520 unsigned long int glong;
25521 \newline
25522
25523 \newline
25524 foo () {
25525 \newline
25526 \SpecialChar ~
25527 \SpecialChar ~
25528 unsigned char hob1, hob2;
25529 \newline
25530 \SpecialChar ~
25531 \SpecialChar ~
25532 unsigned int how1, how2;
25533 \newline
25534 \SpecialChar ~
25535 \SpecialChar ~
25536 ...
25537
25538 \newline
25539 \SpecialChar ~
25540 \SpecialChar ~
25541 hob1 = (gint >> 8) & 0xFF;
25542 \newline
25543 \SpecialChar ~
25544 \SpecialChar ~
25545 hob2 = glong >> 24;
25546 \newline
25547 \SpecialChar ~
25548 \SpecialChar ~
25549 how1 = (glong >> 16) & 0xFFFF;
25550 \newline
25551 \SpecialChar ~
25552 \SpecialChar ~
25553 how2 = glong >> 8;
25554 \newline
25555 \SpecialChar ~
25556 \SpecialChar ~
25557 ..
25558
25559 \newline
25560 }
25561 \layout Standard
25562
25563 will generate the following code:
25564 \layout Verse
25565
25566
25567 \family typewriter
25568 \SpecialChar ~
25569 \SpecialChar ~
25570 \SpecialChar ~
25571 \SpecialChar ~
25572 \SpecialChar ~
25573 \SpecialChar ~
25574 \SpecialChar ~
25575 \SpecialChar ~
25576 \SpecialChar ~
25577 \SpecialChar ~
25578 \SpecialChar ~
25579 \SpecialChar ~
25580 \SpecialChar ~
25581 \SpecialChar ~
25582 \SpecialChar ~
25583 \SpecialChar ~
25584 \SpecialChar ~
25585 \SpecialChar ~
25586 \SpecialChar ~
25587 \SpecialChar ~
25588 \SpecialChar ~
25589 \SpecialChar ~
25590 \SpecialChar ~
25591 \SpecialChar ~
25592 \SpecialChar ~
25593  91 ;\SpecialChar ~
25594  hob.c 15
25595 \newline
25596 0037 85*01*06\SpecialChar ~
25597 \SpecialChar ~
25598 \SpecialChar ~
25599 \SpecialChar ~
25600 \SpecialChar ~
25601 \SpecialChar ~
25602 \SpecialChar ~
25603 \SpecialChar ~
25604 \SpecialChar ~
25605 \SpecialChar ~
25606 \SpecialChar ~
25607 \SpecialChar ~
25608  92\SpecialChar ~
25609 \SpecialChar ~
25610 \SpecialChar ~
25611 \SpecialChar ~
25612 \SpecialChar ~
25613 \SpecialChar ~
25614 \SpecialChar ~
25615 \SpecialChar ~
25616  mov\SpecialChar ~
25617 \SpecialChar ~
25618  _foo_hob1_1_1,(_gint + 1)
25619 \newline
25620 \SpecialChar ~
25621 \SpecialChar ~
25622 \SpecialChar ~
25623 \SpecialChar ~
25624 \SpecialChar ~
25625 \SpecialChar ~
25626 \SpecialChar ~
25627 \SpecialChar ~
25628 \SpecialChar ~
25629 \SpecialChar ~
25630 \SpecialChar ~
25631 \SpecialChar ~
25632 \SpecialChar ~
25633 \SpecialChar ~
25634 \SpecialChar ~
25635 \SpecialChar ~
25636 \SpecialChar ~
25637 \SpecialChar ~
25638 \SpecialChar ~
25639 \SpecialChar ~
25640 \SpecialChar ~
25641 \SpecialChar ~
25642 \SpecialChar ~
25643 \SpecialChar ~
25644 \SpecialChar ~
25645  93 ;\SpecialChar ~
25646  hob.c 16
25647 \newline
25648 003A 85*05*07\SpecialChar ~
25649 \SpecialChar ~
25650 \SpecialChar ~
25651 \SpecialChar ~
25652 \SpecialChar ~
25653 \SpecialChar ~
25654 \SpecialChar ~
25655 \SpecialChar ~
25656 \SpecialChar ~
25657 \SpecialChar ~
25658 \SpecialChar ~
25659 \SpecialChar ~
25660  94\SpecialChar ~
25661 \SpecialChar ~
25662 \SpecialChar ~
25663 \SpecialChar ~
25664 \SpecialChar ~
25665 \SpecialChar ~
25666 \SpecialChar ~
25667 \SpecialChar ~
25668  mov\SpecialChar ~
25669 \SpecialChar ~
25670  _foo_hob2_1_1,(_glong + 3)
25671 \newline
25672 \SpecialChar ~
25673 \SpecialChar ~
25674 \SpecialChar ~
25675 \SpecialChar ~
25676 \SpecialChar ~
25677 \SpecialChar ~
25678 \SpecialChar ~
25679 \SpecialChar ~
25680 \SpecialChar ~
25681 \SpecialChar ~
25682 \SpecialChar ~
25683 \SpecialChar ~
25684 \SpecialChar ~
25685 \SpecialChar ~
25686 \SpecialChar ~
25687 \SpecialChar ~
25688 \SpecialChar ~
25689 \SpecialChar ~
25690 \SpecialChar ~
25691 \SpecialChar ~
25692 \SpecialChar ~
25693 \SpecialChar ~
25694 \SpecialChar ~
25695 \SpecialChar ~
25696 \SpecialChar ~
25697  95 ;\SpecialChar ~
25698  hob.c 17
25699 \newline
25700 003D 85*04*08\SpecialChar ~
25701 \SpecialChar ~
25702 \SpecialChar ~
25703 \SpecialChar ~
25704 \SpecialChar ~
25705 \SpecialChar ~
25706 \SpecialChar ~
25707 \SpecialChar ~
25708 \SpecialChar ~
25709 \SpecialChar ~
25710 \SpecialChar ~
25711 \SpecialChar ~
25712  96\SpecialChar ~
25713 \SpecialChar ~
25714 \SpecialChar ~
25715 \SpecialChar ~
25716 \SpecialChar ~
25717 \SpecialChar ~
25718 \SpecialChar ~
25719 \SpecialChar ~
25720  mov\SpecialChar ~
25721 \SpecialChar ~
25722  _foo_how1_1_1,(_glong + 2)
25723 \newline
25724 0040 85*05*09\SpecialChar ~
25725 \SpecialChar ~
25726 \SpecialChar ~
25727 \SpecialChar ~
25728 \SpecialChar ~
25729 \SpecialChar ~
25730 \SpecialChar ~
25731 \SpecialChar ~
25732 \SpecialChar ~
25733 \SpecialChar ~
25734 \SpecialChar ~
25735 \SpecialChar ~
25736  97\SpecialChar ~
25737 \SpecialChar ~
25738 \SpecialChar ~
25739 \SpecialChar ~
25740 \SpecialChar ~
25741 \SpecialChar ~
25742 \SpecialChar ~
25743 \SpecialChar ~
25744  mov\SpecialChar ~
25745 \SpecialChar ~
25746  (_foo_how1_1_1 + 1),(_glong + 3)
25747 \newline
25748 0043 85*03*0A\SpecialChar ~
25749 \SpecialChar ~
25750 \SpecialChar ~
25751 \SpecialChar ~
25752 \SpecialChar ~
25753 \SpecialChar ~
25754 \SpecialChar ~
25755 \SpecialChar ~
25756 \SpecialChar ~
25757 \SpecialChar ~
25758 \SpecialChar ~
25759 \SpecialChar ~
25760  98\SpecialChar ~
25761 \SpecialChar ~
25762 \SpecialChar ~
25763 \SpecialChar ~
25764 \SpecialChar ~
25765 \SpecialChar ~
25766 \SpecialChar ~
25767 \SpecialChar ~
25768  mov\SpecialChar ~
25769 \SpecialChar ~
25770  _foo_how2_1_1,(_glong + 1)
25771 \newline
25772 0046 85*04*0B\SpecialChar ~
25773 \SpecialChar ~
25774 \SpecialChar ~
25775 \SpecialChar ~
25776 \SpecialChar ~
25777 \SpecialChar ~
25778 \SpecialChar ~
25779 \SpecialChar ~
25780 \SpecialChar ~
25781 \SpecialChar ~
25782 \SpecialChar ~
25783 \SpecialChar ~
25784  99\SpecialChar ~
25785 \SpecialChar ~
25786 \SpecialChar ~
25787 \SpecialChar ~
25788 \SpecialChar ~
25789 \SpecialChar ~
25790 \SpecialChar ~
25791 \SpecialChar ~
25792  mov\SpecialChar ~
25793 \SpecialChar ~
25794  (_foo_how2_1_1 + 1),(_glong + 2)
25795 \layout Standard
25796
25797 Again, variations of these cases may
25798 \emph on
25799 not
25800 \emph default
25801  be recognized.
25802  They are standard C expressions, so I heartily recommend these be the only
25803  way to get the higher order byte/word, (it is portable).
25804  Of course it will be recognized even if it is embedded in other expressions,
25805  e.g.:
25806 \layout Verse
25807
25808
25809 \family typewriter
25810 xyz = gint + ((gint >> 8) & 0xFF);
25811 \layout Standard
25812
25813 will still be recognized.
25814 \layout Subsection
25815
25816 Peephole Optimizer
25817 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
25818
25819 \end_inset
25820
25821
25822 \begin_inset LatexCommand \index{Peephole optimizer}
25823
25824 \end_inset
25825
25826
25827 \layout Standard
25828
25829 The compiler uses a rule based, pattern matching and re-writing mechanism
25830  for peep-hole optimization.
25831  It is inspired by
25832 \emph on
25833 copt
25834 \emph default
25835  a peep-hole optimizer by Christopher W.
25836  Fraser (cwfraser\SpecialChar ~
25837 @\SpecialChar ~
25838 microsoft.com).
25839  A default set of rules are compiled into the compiler, additional rules
25840  may be added with the
25841 \emph on
25842 -
25843 \begin_inset ERT
25844 status Collapsed
25845
25846 \layout Standard
25847
25848 \backslash
25849 /
25850 \end_inset
25851
25852 -peep-file
25853 \begin_inset LatexCommand \index{-\/-peep-file}
25854
25855 \end_inset
25856
25857  <filename>
25858 \emph default
25859  option.
25860  The rule language is best illustrated with examples.
25861 \layout Verse
25862
25863
25864 \family typewriter
25865 replace {
25866 \newline
25867 \SpecialChar ~
25868 \SpecialChar ~
25869 mov %1,a
25870 \newline
25871 \SpecialChar ~
25872 \SpecialChar ~
25873 mov a,%1
25874 \newline
25875 } by {
25876 \newline
25877 \SpecialChar ~
25878 \SpecialChar ~
25879 mov %1,a
25880 \newline
25881 }
25882 \layout Standard
25883
25884 The above rule will change the following assembly
25885 \begin_inset LatexCommand \index{Assembler routines}
25886
25887 \end_inset
25888
25889  sequence:
25890 \layout Verse
25891
25892
25893 \family typewriter
25894 mov r1,a
25895 \newline
25896 mov a,r1
25897 \layout Standard
25898
25899 to
25900 \layout Verse
25901
25902
25903 \family typewriter
25904 mov r1,a
25905 \layout Standard
25906
25907 Note: All occurrences of a
25908 \emph on
25909 %n
25910 \emph default
25911  (pattern variable) must denote the same string.
25912  With the above rule, the assembly sequence:
25913 \layout Verse
25914
25915
25916 \family typewriter
25917 mov r1,a
25918 \newline
25919 mov a,r2
25920 \layout Standard
25921
25922 will remain unmodified.
25923 \newline
25924
25925 \newline
25926 Other special case optimizations may be added by the user (via
25927 \emph on
25928 -
25929 \begin_inset ERT
25930 status Collapsed
25931
25932 \layout Standard
25933
25934 \backslash
25935 /
25936 \end_inset
25937
25938 -peep-file option
25939 \emph default
25940 ).
25941  E.g.
25942  some variants of the 8051 MCU
25943 \begin_inset LatexCommand \index{MCS51 variants}
25944
25945 \end_inset
25946
25947  allow only
25948 \family typewriter
25949 ajmp
25950 \family default
25951  and
25952 \family typewriter
25953 acall
25954 \family default
25955 .
25956  The following two rules will change all
25957 \family typewriter
25958 ljmp
25959 \family default
25960  and
25961 \family typewriter
25962 lcall
25963 \family default
25964  to
25965 \family typewriter
25966 ajmp
25967 \family default
25968  and
25969 \family typewriter
25970 acall
25971 \layout Verse
25972
25973
25974 \family typewriter
25975 replace { lcall %1 } by { acall %1 }
25976 \newline
25977 replace { ljmp %1 } by { ajmp %1 }
25978 \layout Standard
25979
25980 The
25981 \emph on
25982 inline-assembler code
25983 \emph default
25984  is also passed through the peep hole optimizer, thus the peephole optimizer
25985  can also be used as an assembly level macro expander.
25986  The rules themselves are MCU dependent whereas the rule language infra-structur
25987 e is MCU independent.
25988  Peephole optimization rules for other MCU can be easily programmed using
25989  the rule language.
25990 \newline
25991
25992 \newline
25993 The syntax for a rule is as follows:
25994 \layout Verse
25995
25996
25997 \family typewriter
25998 rule := replace [ restart ] '{' <assembly sequence> '
25999 \backslash
26000 n'
26001 \newline
26002 \SpecialChar ~
26003  \SpecialChar ~
26004  \SpecialChar ~
26005  \SpecialChar ~
26006  \SpecialChar ~
26007  \SpecialChar ~
26008  \SpecialChar ~
26009  \SpecialChar ~
26010  \SpecialChar ~
26011  \SpecialChar ~
26012  \SpecialChar ~
26013  \SpecialChar ~
26014  \SpecialChar ~
26015  \SpecialChar ~
26016  '}' by '{' '
26017 \backslash
26018 n'
26019 \newline
26020 \SpecialChar ~
26021  \SpecialChar ~
26022  \SpecialChar ~
26023  \SpecialChar ~
26024  \SpecialChar ~
26025  \SpecialChar ~
26026  \SpecialChar ~
26027  \SpecialChar ~
26028  \SpecialChar ~
26029  \SpecialChar ~
26030  \SpecialChar ~
26031  \SpecialChar ~
26032  \SpecialChar ~
26033  \SpecialChar ~
26034  \SpecialChar ~
26035  \SpecialChar ~
26036  <assembly sequence> '
26037 \backslash
26038 n'
26039 \newline
26040 \SpecialChar ~
26041  \SpecialChar ~
26042  \SpecialChar ~
26043  \SpecialChar ~
26044  \SpecialChar ~
26045  \SpecialChar ~
26046  \SpecialChar ~
26047  \SpecialChar ~
26048  \SpecialChar ~
26049  \SpecialChar ~
26050  \SpecialChar ~
26051  \SpecialChar ~
26052  \SpecialChar ~
26053  \SpecialChar ~
26054  '}' [if <functionName> ] '
26055 \backslash
26056 n'
26057 \layout Standard
26058
26059 <assembly sequence> := assembly instruction (each instruction including
26060  labels must be on a separate line).
26061 \newline
26062
26063 \newline
26064 The optimizer will apply to the rules one by one from the top in the sequence
26065  of their appearance, it will terminate when all rules are exhausted.
26066  If the 'restart' option is specified, then the optimizer will start matching
26067  the rules again from the top, this option for a rule is expensive (performance)
26068 , it is intended to be used in situations where a transformation will trigger
26069  the same rule again.
26070  An example of this (not a good one, it has side effects) is the following
26071  rule:
26072 \layout Verse
26073
26074
26075 \family typewriter
26076 replace restart {
26077 \newline
26078 \SpecialChar ~
26079 \SpecialChar ~
26080 pop %1
26081 \newline
26082 \SpecialChar ~
26083 \SpecialChar ~
26084 push %1 } by {
26085 \newline
26086 \SpecialChar ~
26087 \SpecialChar ~
26088 ; nop
26089 \newline
26090 }
26091 \layout Standard
26092
26093 Note that the replace pattern cannot be a blank, but can be a comment line.
26094  Without the 'restart' option only the innermost 'pop' 'push' pair would
26095  be eliminated, i.e.:
26096 \layout Verse
26097
26098
26099 \family typewriter
26100 pop ar1
26101 \newline
26102 pop ar2
26103 \newline
26104 push ar2
26105 \newline
26106 push ar1
26107 \layout Standard
26108
26109 would result in:
26110 \layout Verse
26111
26112
26113 \family typewriter
26114 pop ar1
26115 \newline
26116 ; nop
26117 \newline
26118 push ar1
26119 \layout Standard
26120
26121
26122 \emph on
26123 with
26124 \emph default
26125  the restart option the rule will be applied again to the resulting code
26126  and then all the pop-push pairs will be eliminated to yield:
26127 \layout Verse
26128
26129
26130 \family typewriter
26131 ; nop
26132 \newline
26133 ; nop
26134 \layout Standard
26135
26136 A conditional function can be attached to a rule.
26137  Attaching rules are somewhat more involved, let me illustrate this with
26138  an example.
26139 \layout Verse
26140
26141
26142 \family typewriter
26143 replace {
26144 \newline
26145 \SpecialChar ~
26146  \SpecialChar ~
26147  \SpecialChar ~
26148 ljmp %5
26149 \newline
26150 %2:
26151 \newline
26152 } by {
26153 \newline
26154 \SpecialChar ~
26155  \SpecialChar ~
26156  \SpecialChar ~
26157 sjmp %5
26158 \newline
26159 %2:
26160 \newline
26161 } if labelInRange
26162 \layout Standard
26163
26164 The optimizer does a look-up of a function name table defined in function
26165
26166 \emph on
26167 callFuncByName
26168 \emph default
26169  in the source file SDCCpeeph.c, with the name
26170 \emph on
26171 labelInRange
26172 \emph default
26173 .
26174  If it finds a corresponding entry the function is called.
26175  Note there can be no parameters specified for these functions, in this
26176  case the use of
26177 \emph on
26178 %5
26179 \emph default
26180  is crucial, since the function
26181 \emph on
26182 labelInRange
26183 \emph default
26184  expects to find the label in that particular variable (the hash table containin
26185 g the variable bindings is passed as a parameter).
26186  If you want to code more such functions, take a close look at the function
26187  labelInRange and the calling mechanism in source file SDCCpeeph.c.
26188  Currently implemented are
26189 \emph on
26190 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
26191  24bitMode, portIsDS390, 24bitModeAndPortDS390
26192 \emph default
26193 and
26194 \emph on
26195  notVolatile
26196 \emph default
26197 .
26198 \layout Standard
26199
26200 I know this whole thing is a little kludgey, but maybe some day we will
26201  have some better means.
26202  If you are looking at this file, you will see the default rules that are
26203  compiled into the compiler, you can add your own rules in the default set
26204  there if you get tired of specifying the -
26205 \begin_inset ERT
26206 status Collapsed
26207
26208 \layout Standard
26209
26210 \backslash
26211 /
26212 \end_inset
26213
26214 -peep-file option.
26215 \layout Section
26216
26217 ANSI-Compliance
26218 \begin_inset LatexCommand \index{ANSI-compliance}
26219
26220 \end_inset
26221
26222
26223 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
26224
26225 \end_inset
26226
26227
26228 \layout Standard
26229
26230 Deviations from the compliance:
26231 \layout Itemize
26232
26233 functions are not reentrant
26234 \begin_inset LatexCommand \index{reentrant}
26235
26236 \end_inset
26237
26238  unless explicitly declared as such or the
26239 \series bold
26240 -
26241 \begin_inset ERT
26242 status Collapsed
26243
26244 \layout Standard
26245
26246 \backslash
26247 /
26248 \end_inset
26249
26250 -stack-auto
26251 \begin_inset LatexCommand \index{-\/-stack-auto}
26252
26253 \end_inset
26254
26255
26256 \series default
26257  command line option is specified.
26258 \layout Itemize
26259
26260 structures and unions cannot be assigned values directly, cannot be passed
26261  as function parameters or assigned to each other and cannot be a return
26262  value from a function, e.g.:
26263 \begin_deeper
26264 \layout Verse
26265
26266
26267 \family typewriter
26268 struct s { ...
26269  };
26270 \newline
26271 struct s s1, s2;
26272 \newline
26273 foo()
26274 \newline
26275 {
26276 \newline
26277 \SpecialChar ~
26278 \SpecialChar ~
26279 \SpecialChar ~
26280 \SpecialChar ~
26281 ...
26282
26283 \newline
26284 \SpecialChar ~
26285 \SpecialChar ~
26286 \SpecialChar ~
26287 \SpecialChar ~
26288 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
26289 \newline
26290 \SpecialChar ~
26291 \SpecialChar ~
26292 \SpecialChar ~
26293 \SpecialChar ~
26294 ...
26295
26296 \newline
26297 }
26298 \newline
26299 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
26300  */
26301 \newline
26302 {
26303 \newline
26304 \SpecialChar ~
26305 \SpecialChar ~
26306 \SpecialChar ~
26307 \SpecialChar ~
26308 struct s rets;
26309 \newline
26310 \SpecialChar ~
26311 \SpecialChar ~
26312 \SpecialChar ~
26313 \SpecialChar ~
26314 ...
26315
26316 \newline
26317 \SpecialChar ~
26318 \SpecialChar ~
26319 \SpecialChar ~
26320 \SpecialChar ~
26321 return rets;/* is invalid in SDCC although allowed in ANSI */
26322 \newline
26323 }
26324 \end_deeper
26325 \layout Itemize
26326
26327 initialization of structure arrays must be fully braced.
26328 \begin_deeper
26329 \layout Verse
26330
26331
26332 \family typewriter
26333 struct s { char x } a[] = {1, 2}; /* invalid in SDCC */
26334 \newline
26335 struct s { char x } a[] = {{1}, {2}}; /* OK */
26336 \end_deeper
26337 \layout Itemize
26338
26339 'long long
26340 \begin_inset LatexCommand \index{long long (not supported)}
26341
26342 \end_inset
26343
26344 ' (64 bit integers
26345 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
26346
26347 \end_inset
26348
26349 ) not supported.
26350 \layout Itemize
26351
26352 'double
26353 \begin_inset LatexCommand \index{double (not supported)}
26354
26355 \end_inset
26356
26357 ' precision floating point
26358 \begin_inset LatexCommand \index{Floating point support}
26359
26360 \end_inset
26361
26362 not supported.
26363 \layout Itemize
26364
26365 No support for setjmp
26366 \begin_inset LatexCommand \index{setjmp (not supported)}
26367
26368 \end_inset
26369
26370  and longjmp
26371 \begin_inset LatexCommand \index{longjmp (not supported)}
26372
26373 \end_inset
26374
26375  (for now).
26376 \layout Itemize
26377
26378 Old K&R style
26379 \begin_inset LatexCommand \index{K\&R style}
26380
26381 \end_inset
26382
26383  function declarations are NOT allowed.
26384 \begin_deeper
26385 \layout Verse
26386
26387
26388 \family typewriter
26389 foo(i,j) /* this old style of function declarations */
26390 \newline
26391 int i,j; /* are valid in ANSI but not valid in SDCC */
26392 \newline
26393 {
26394 \newline
26395 \SpecialChar ~
26396 \SpecialChar ~
26397 \SpecialChar ~
26398 \SpecialChar ~
26399 ...
26400
26401 \newline
26402 }
26403 \end_deeper
26404 \layout Itemize
26405
26406 Certain words that are valid identifiers in the standard may be reserved
26407  words in SDCC unless the
26408 \series bold
26409 -
26410 \begin_inset ERT
26411 status Collapsed
26412
26413 \layout Standard
26414
26415 \backslash
26416 /
26417 \end_inset
26418
26419 -std-c89
26420 \begin_inset LatexCommand \index{-\/-std-c89}
26421
26422 \end_inset
26423
26424  or -
26425 \begin_inset ERT
26426 status Collapsed
26427
26428 \layout Standard
26429
26430 \backslash
26431 /
26432 \end_inset
26433
26434 -std-c99
26435 \begin_inset LatexCommand \index{-\/-std-c99}
26436
26437 \end_inset
26438
26439
26440 \series default
26441  command line options are used.
26442  These may include (depending on the selected processor): 'at', 'banked',
26443  'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup
26444 t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs',
26445  'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and
26446  '_naked'.
26447  Compliant equivalents of these keywords are always available in a form
26448  that begin with two underscores
26449 \begin_inset LatexCommand \index{\_\_ (prefix for extended keywords)}
26450
26451 \end_inset
26452
26453 , f.e.
26454  '__data' instead of 'data'.
26455 \layout Section
26456
26457 Cyclomatic Complexity
26458 \begin_inset LatexCommand \index{Cyclomatic complexity}
26459
26460 \end_inset
26461
26462
26463 \layout Standard
26464
26465 Cyclomatic complexity of a function is defined as the number of independent
26466  paths the program can take during execution of the function.
26467  This is an important number since it defines the number test cases you
26468  have to generate to validate the function.
26469  The accepted industry standard for complexity number is 10, if the cyclomatic
26470  complexity reported by SDCC exceeds 10 you should think about simplification
26471  of the function logic.
26472  Note that the complexity level is not related to the number of lines of
26473  code in a function.
26474  Large functions can have low complexity, and small functions can have large
26475  complexity levels.
26476
26477 \newline
26478
26479 \newline
26480 SDCC uses the following formula to compute the complexity:
26481 \newline
26482
26483 \layout Standard
26484
26485 complexity = (number of edges in control flow graph) - (number of nodes
26486  in control flow graph) + 2;
26487 \newline
26488
26489 \newline
26490 Having said that the industry standard is 10, you should be aware that in
26491  some cases it be may unavoidable to have a complexity level of less than
26492  10.
26493  For example if you have switch statement with more than 10 case labels,
26494  each case label adds one to the complexity level.
26495  The complexity level is by no means an absolute measure of the algorithmic
26496  complexity of the function, it does however provide a good starting point
26497  for which functions you might look at for further optimization.
26498 \layout Section
26499
26500 Retargetting for other Processors
26501 \layout Standard
26502
26503 The issues for retargetting the compiler are far too numerous to be covered
26504  by this document.
26505  What follows is a brief description of each of the seven phases of the
26506  compiler and its MCU dependency.
26507 \layout Itemize
26508
26509 Parsing the source and building the annotated parse tree.
26510  This phase is largely MCU independent (except for the language extensions).
26511  Syntax & semantic checks are also done in this phase, along with some initial
26512  optimizations like back patching labels and the pattern matching optimizations
26513  like bit-rotation etc.
26514 \layout Itemize
26515
26516 The second phase involves generating an intermediate code which can be easy
26517  manipulated during the later phases.
26518  This phase is entirely MCU independent.
26519  The intermediate code generation assumes the target machine has unlimited
26520  number of registers, and designates them with the name iTemp.
26521  The compiler can be made to dump a human readable form of the code generated
26522  by using the -
26523 \begin_inset ERT
26524 status Collapsed
26525
26526 \layout Standard
26527
26528 \backslash
26529 /
26530 \end_inset
26531
26532 -dumpraw option.
26533 \layout Itemize
26534
26535 This phase does the bulk of the standard optimizations and is also MCU independe
26536 nt.
26537  This phase can be broken down into several sub-phases:
26538 \newline
26539
26540 \newline
26541 Break down intermediate code (iCode) into basic blocks.
26542 \newline
26543 Do control flow & data flow analysis on the basic blocks.
26544 \newline
26545 Do local common subexpression elimination, then global subexpression elimination
26546 \newline
26547 Dead code elimination
26548 \newline
26549 Loop optimizations
26550 \newline
26551 If loop optimizations caused any changes then do 'global subexpression eliminati
26552 on' and 'dead code elimination' again.
26553 \layout Itemize
26554
26555 This phase determines the live-ranges; by live range I mean those iTemp
26556  variables defined by the compiler that still survive after all the optimization
26557 s.
26558  Live range analysis
26559 \begin_inset LatexCommand \index{Live range analysis}
26560
26561 \end_inset
26562
26563  is essential for register allocation, since these computation determines
26564  which of these iTemps will be assigned to registers, and for how long.
26565 \layout Itemize
26566
26567 Phase five is register allocation.
26568  There are two parts to this process.
26569 \newline
26570
26571 \newline
26572 The first part I call 'register packing' (for lack of a better term).
26573  In this case several MCU specific expression folding is done to reduce
26574  register pressure.
26575 \newline
26576
26577 \newline
26578 The second part is more MCU independent and deals with allocating registers
26579  to the remaining live ranges.
26580  A lot of MCU specific code does creep into this phase because of the limited
26581  number of index registers available in the 8051.
26582 \layout Itemize
26583
26584 The Code generation phase is (unhappily), entirely MCU dependent and very
26585  little (if any at all) of this code can be reused for other MCU.
26586  However the scheme for allocating a homogenized assembler operand for each
26587  iCode operand may be reused.
26588 \layout Itemize
26589
26590 As mentioned in the optimization section the peep-hole optimizer is rule
26591  based system, which can reprogrammed for other MCUs.
26592 \layout Chapter
26593
26594 Compiler internals
26595 \begin_inset LatexCommand \index{Compiler internals}
26596
26597 \end_inset
26598
26599
26600 \layout Section
26601
26602 The anatomy of the compiler
26603 \begin_inset LatexCommand \label{sub:The-anatomy-of}
26604
26605 \end_inset
26606
26607
26608 \layout Standard
26609
26610
26611 \shape italic
26612 This is an excerpt from an article published in Circuit Cellar Magazine
26613  in
26614 \series bold
26615 August 2000
26616 \series default
26617 .
26618  It's a little outdated (the compiler is much more efficient now and user/develo
26619 per friendly), but pretty well exposes the guts of it all.
26620 \shape default
26621
26622 \newline
26623
26624 \newline
26625 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
26626  It is fairly easy to retarget for other 8-bit MCU.
26627  Here we take a look at some of the internals of the compiler.
26628
26629 \layout Paragraph*
26630
26631 Parsing
26632 \begin_inset LatexCommand \index{Parsing}
26633
26634 \end_inset
26635
26636
26637 \layout Standard
26638
26639 Parsing the input source file and creating an AST (Annotated Syntax Tree
26640 \begin_inset LatexCommand \index{Annotated syntax tree}
26641
26642 \end_inset
26643
26644 ).
26645  This phase also involves propagating types (annotating each node of the
26646  parse tree with type information) and semantic analysis.
26647  There are some MCU specific parsing rules.
26648  For example the storage classes, the extended storage classes are MCU specific
26649  while there may be a xdata storage class for 8051 there is no such storage
26650  class for z80 or Atmel AVR.
26651  SDCC allows MCU specific storage class extensions, i.e.
26652  xdata will be treated as a storage class specifier when parsing 8051 C
26653  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
26654  C code.
26655 \layout Paragraph*
26656
26657 Generating iCode
26658 \begin_inset LatexCommand \index{iCode}
26659
26660 \end_inset
26661
26662
26663 \layout Standard
26664
26665 Intermediate code generation.
26666  In this phase the AST is broken down into three-operand form (iCode).
26667  These three operand forms are represented as doubly linked lists.
26668  ICode is the term given to the intermediate form generated by the compiler.
26669  ICode example section shows some examples of iCode generated for some simple
26670  C source functions.
26671 \layout Paragraph*
26672
26673 Optimizations
26674 \begin_inset LatexCommand \index{Optimizations}
26675
26676 \end_inset
26677
26678 .
26679 \layout Standard
26680
26681 Bulk of the target independent optimizations is performed in this phase.
26682  The optimizations include constant propagation, common sub-expression eliminati
26683 on, loop invariant code movement, strength reduction of loop induction variables
26684  and dead-code elimination.
26685 \layout Paragraph*
26686
26687 Live range analysis
26688 \begin_inset LatexCommand \index{Live range analysis}
26689
26690 \end_inset
26691
26692
26693 \layout Standard
26694
26695 During intermediate code generation phase, the compiler assumes the target
26696  machine has infinite number of registers and generates a lot of temporary
26697  variables.
26698  The live range computation determines the lifetime of each of these compiler-ge
26699 nerated temporaries.
26700  A picture speaks a thousand words.
26701  ICode example sections show the live range annotations for each of the
26702  operand.
26703  It is important to note here, each iCode is assigned a number in the order
26704  of its execution in the function.
26705  The live ranges are computed in terms of these numbers.
26706  The from number is the number of the iCode which first defines the operand
26707  and the to number signifies the iCode which uses this operand last.
26708 \layout Paragraph*
26709
26710 Register Allocation
26711 \begin_inset LatexCommand \index{Register allocation}
26712
26713 \end_inset
26714
26715
26716 \layout Standard
26717
26718 The register allocation determines the type and number of registers needed
26719  by each operand.
26720  In most MCUs only a few registers can be used for indirect addressing.
26721  In case of 8051 for example the registers R0 & R1 can be used to indirectly
26722  address the internal ram and DPTR to indirectly address the external ram.
26723  The compiler will try to allocate the appropriate register to pointer variables
26724  if it can.
26725  ICode example section shows the operands annotated with the registers assigned
26726  to them.
26727  The compiler will try to keep operands in registers as much as possible;
26728  there are several schemes the compiler uses to do achieve this.
26729  When the compiler runs out of registers the compiler will check to see
26730  if there are any live operands which is not used or defined in the current
26731  basic block being processed, if there are any found then it will push that
26732  operand and use the registers in this block, the operand will then be popped
26733  at the end of the basic block.
26734
26735 \layout Standard
26736
26737 There are other MCU specific considerations in this phase.
26738  Some MCUs have an accumulator; very short-lived operands could be assigned
26739  to the accumulator instead of a general-purpose register.
26740 \layout Paragraph*
26741
26742 Code generation
26743 \layout Standard
26744
26745 Figure II gives a table of iCode operations supported by the compiler.
26746  The code generation involves translating these operations into corresponding
26747  assembly code for the processor.
26748  This sounds overly simple but that is the essence of code generation.
26749  Some of the iCode operations are generated on a MCU specific manner for
26750  example, the z80 port does not use registers to pass parameters so the
26751  SEND and RECV iCode operations will not be generated, and it also does
26752  not support JUMPTABLES.
26753
26754 \newline
26755
26756 \series bold
26757 \shape italic
26758 \color red
26759 <Where is Figure II?>
26760 \layout Comment
26761
26762 In the original article Figure II was announced to be downloadable on
26763 \shape italic
26764 Circuit Cellar
26765 \shape default
26766 's web site.
26767  Unfortunately it never seemed to have shown up there, so: where is Figure
26768  II?
26769 \layout Paragraph*
26770
26771 ICode Example
26772 \begin_inset LatexCommand \index{iCode}
26773
26774 \end_inset
26775
26776
26777 \layout Standard
26778
26779 This section shows some details of iCode.
26780  The example C code does not do anything useful; it is used as an example
26781  to illustrate the intermediate code generated by the compiler.
26782 \layout Verse
26783
26784
26785 \family typewriter
26786 1.\SpecialChar ~
26787 xdata int * p;
26788 \newline
26789 2.\SpecialChar ~
26790 int gint;
26791 \newline
26792 3.\SpecialChar ~
26793 /* This function does nothing useful.
26794  It is used
26795 \newline
26796 4.\SpecialChar ~
26797 \SpecialChar ~
26798 \SpecialChar ~
26799 \SpecialChar ~
26800 for the purpose of explaining iCode */
26801 \newline
26802 5.\SpecialChar ~
26803 short function (data int *x)
26804 \newline
26805 6.\SpecialChar ~
26806 {
26807 \newline
26808 7.\SpecialChar ~
26809 \SpecialChar ~
26810 \SpecialChar ~
26811 short i=10; \SpecialChar ~
26812 \SpecialChar ~
26813 /* dead initialization eliminated */
26814 \newline
26815 8.\SpecialChar ~
26816 \SpecialChar ~
26817 \SpecialChar ~
26818 short sum=10; /* dead initialization eliminated */
26819 \newline
26820 9.\SpecialChar ~
26821 \SpecialChar ~
26822 \SpecialChar ~
26823 short mul;
26824 \newline
26825 10.\SpecialChar ~
26826 \SpecialChar ~
26827 int j ;
26828 \newline
26829 11.\SpecialChar ~
26830 \SpecialChar ~
26831 while (*x) *x++ = *p++;
26832 \newline
26833 12.\SpecialChar ~
26834 \SpecialChar ~
26835 \SpecialChar ~
26836 \SpecialChar ~
26837 sum = 0 ;
26838 \newline
26839 13.\SpecialChar ~
26840 \SpecialChar ~
26841 mul = 0;
26842 \newline
26843 14.\SpecialChar ~
26844 \SpecialChar ~
26845 /* compiler detects i,j to be induction variables */
26846 \newline
26847 15.\SpecialChar ~
26848 \SpecialChar ~
26849 for (i = 0, j = 10 ; i < 10 ; i++, j
26850 \family default
26851 -
26852 \begin_inset ERT
26853 status Collapsed
26854
26855 \layout Standard
26856
26857 \backslash
26858 /
26859 \end_inset
26860
26861 -
26862 \family typewriter
26863 ) {
26864 \newline
26865 16.\SpecialChar ~
26866 \SpecialChar ~
26867 \SpecialChar ~
26868 \SpecialChar ~
26869 sum += i;
26870 \newline
26871 17.\SpecialChar ~
26872 \SpecialChar ~
26873 \SpecialChar ~
26874 \SpecialChar ~
26875 mul += i * 3; \SpecialChar ~
26876 \SpecialChar ~
26877 /* this multiplication remains */
26878 \newline
26879 18.\SpecialChar ~
26880 \SpecialChar ~
26881 \SpecialChar ~
26882 \SpecialChar ~
26883 gint += j * 3;\SpecialChar ~
26884 \SpecialChar ~
26885 /* this multiplication changed to addition */
26886 \newline
26887 19.\SpecialChar ~
26888 \SpecialChar ~
26889 }
26890 \newline
26891 20.\SpecialChar ~
26892 \SpecialChar ~
26893 return sum+mul;
26894 \newline
26895 21.\SpecialChar ~
26896 }
26897 \layout Standard
26898
26899 In addition to the operands each iCode contains information about the filename
26900  and line it corresponds to in the source file.
26901  The first field in the listing should be interpreted as follows:
26902 \newline
26903
26904 \shape italic
26905 \size footnotesize
26906 Filename(linenumber: iCode Execution sequence number : ICode hash table
26907  key : loop depth of the iCode).
26908 \shape default
26909 \size default
26910
26911 \newline
26912 Then follows the human readable form of the ICode operation.
26913  Each operand of this triplet form can be of three basic types a) compiler
26914  generated temporary b) user defined variable c) a constant value.
26915  Note that local variables and parameters are replaced by compiler generated
26916  temporaries.
26917  Live ranges
26918 \begin_inset LatexCommand \index{Live range analysis}
26919
26920 \end_inset
26921
26922  are computed only for temporaries (i.e.
26923  live ranges are not computed for global variables).
26924  Registers
26925 \begin_inset LatexCommand \index{Register allocation}
26926
26927 \end_inset
26928
26929  are allocated for temporaries only.
26930  Operands are formatted in the following manner:
26931 \newline
26932
26933 \shape italic
26934 \size footnotesize
26935 Operand Name [lr live-from : live-to ] { type information } [ registers
26936  allocated ].
26937 \shape default
26938 \size default
26939
26940 \newline
26941 As mentioned earlier the live ranges are computed in terms of the execution
26942  sequence number of the iCodes, for example
26943 \newline
26944 the iTemp0 is live from (i.e.
26945  first defined in iCode with execution sequence number 3, and is last used
26946  in the iCode with sequence number 5).
26947  For induction variables such as iTemp21 the live range computation extends
26948  the lifetime from the start to the end of the loop.
26949 \newline
26950 The register allocator used the live range information to allocate registers,
26951  the same registers may be used for different temporaries if their live
26952  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
26953  iTemp17 since their live ranges do not overlap.
26954  In addition the allocator also takes into consideration the type and usage
26955  of a temporary, for example itemp6 is a pointer to near space and is used
26956  as to fetch data from (i.e.
26957  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
26958  Some short lived temporaries are allocated to special registers which have
26959  meaning to the code generator e.g.
26960  iTemp13 is allocated to a pseudo register CC which tells the back end that
26961  the temporary is used only for a conditional jump the code generation makes
26962  use of this information to optimize a compare and jump ICode.
26963 \newline
26964 There are several loop optimizations
26965 \begin_inset LatexCommand \index{Loop optimization}
26966
26967 \end_inset
26968
26969  performed by the compiler.
26970  It can detect induction variables iTemp21(i) and iTemp23(j).
26971  Also note the compiler does selective strength reduction
26972 \begin_inset LatexCommand \index{Strength reduction}
26973
26974 \end_inset
26975
26976 , i.e.
26977  the multiplication of an induction variable in line 18 (gint = j * 3) is
26978  changed to addition, a new temporary iTemp17 is allocated and assigned
26979  a initial value, a constant 3 is then added for each iteration of the loop.
26980  The compiler does not change the multiplication
26981 \begin_inset LatexCommand \index{Multiplication}
26982
26983 \end_inset
26984
26985  in line 17 however since the processor does support an 8 * 8 bit multiplication.
26986 \newline
26987 Note the dead code elimination
26988 \begin_inset LatexCommand \index{Dead-code elimination}
26989
26990 \end_inset
26991
26992  optimization eliminated the dead assignments in line 7 & 8 to I and sum
26993  respectively.
26994 \newline
26995
26996 \layout Standard
26997
26998
26999 \size footnotesize
27000 Sample.c (5:1:0:0) _entry($9) :
27001 \layout Standard
27002
27003
27004 \size footnotesize
27005 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
27006 \layout Standard
27007
27008
27009 \size footnotesize
27010 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
27011 \layout Standard
27012
27013
27014 \size footnotesize
27015 Sample.c(11:4:53:0) preHeaderLbl0($11) :
27016 \layout Standard
27017
27018
27019 \size footnotesize
27020 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
27021  * int}[r2]
27022 \layout Standard
27023
27024
27025 \size footnotesize
27026 Sample.c(11:6:5:1) _whilecontinue_0($1) :
27027 \layout Standard
27028
27029
27030 \size footnotesize
27031 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
27032  int}[r0]]
27033 \layout Standard
27034
27035
27036 \size footnotesize
27037 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
27038 \layout Standard
27039
27040
27041 \size footnotesize
27042 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
27043  * int}
27044 \layout Standard
27045
27046
27047 \size footnotesize
27048 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
27049  {short}
27050 \layout Standard
27051
27052
27053 \size footnotesize
27054 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
27055  * int}[DPTR]]
27056 \layout Standard
27057
27058
27059 \size footnotesize
27060 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
27061 }[r2 r3]
27062 \layout Standard
27063
27064
27065 \size footnotesize
27066 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
27067  * int}[r0] + 0x2 {short}
27068 \layout Standard
27069
27070
27071 \size footnotesize
27072 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
27073 \layout Standard
27074
27075
27076 \size footnotesize
27077 Sample.c(11:17:21:0)_whilebreak_0($3) :
27078 \layout Standard
27079
27080
27081 \size footnotesize
27082 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
27083 \layout Standard
27084
27085
27086 \size footnotesize
27087 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
27088 \layout Standard
27089
27090
27091 \size footnotesize
27092 Sample.c(15:20:54:0)preHeaderLbl1($13) :
27093 \layout Standard
27094
27095
27096 \size footnotesize
27097 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
27098 \layout Standard
27099
27100
27101 \size footnotesize
27102 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
27103 \layout Standard
27104
27105
27106 \size footnotesize
27107 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
27108 \layout Standard
27109
27110
27111 \size footnotesize
27112 Sample.c(15:24:26:1)_forcond_0($4) :
27113 \layout Standard
27114
27115
27116 \size footnotesize
27117 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
27118  < 0xa {short}
27119 \layout Standard
27120
27121
27122 \size footnotesize
27123 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
27124 \layout Standard
27125
27126
27127 \size footnotesize
27128 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
27129  + ITemp21 [lr21:38]{short}[r4]
27130 \layout Standard
27131
27132
27133 \size footnotesize
27134 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
27135  * 0x3 {short}
27136 \layout Standard
27137
27138
27139 \size footnotesize
27140 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
27141  + iTemp15 [lr29:30]{short}[r1]
27142 \layout Standard
27143
27144
27145 \size footnotesize
27146 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
27147  r0]- 0x3 {short}
27148 \layout Standard
27149
27150
27151 \size footnotesize
27152 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
27153 int}[r7 r0]
27154 \layout Standard
27155
27156
27157 \size footnotesize
27158 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
27159  + 0x1 {short}
27160 \layout Standard
27161
27162
27163 \size footnotesize
27164 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
27165  r6]- 0x1 {short}
27166 \layout Standard
27167
27168
27169 \size footnotesize
27170 Sample.c(19:38:47:1) goto _forcond_0($4)
27171 \layout Standard
27172
27173
27174 \size footnotesize
27175 Sample.c(19:39:48:0)_forbreak_0($7) :
27176 \layout Standard
27177
27178
27179 \size footnotesize
27180 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
27181  + ITemp11 [lr19:40]{short}[r3]
27182 \layout Standard
27183
27184
27185 \size footnotesize
27186 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
27187 \layout Standard
27188
27189
27190 \size footnotesize
27191 Sample.c(20:42:51:0)_return($8) :
27192 \layout Standard
27193
27194
27195 \size footnotesize
27196 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
27197 \size default
27198
27199 \newline
27200
27201 \newline
27202 Finally the code generated for this function:
27203 \newline
27204
27205 \layout Standard
27206
27207
27208 \size footnotesize
27209 .area DSEG (DATA)
27210 \layout Standard
27211
27212
27213 \size footnotesize
27214 _p::
27215 \layout Standard
27216
27217
27218 \size footnotesize
27219 \SpecialChar ~
27220 \SpecialChar ~
27221 .ds 2
27222 \layout Standard
27223
27224
27225 \size footnotesize
27226 _gint::
27227 \layout Standard
27228
27229
27230 \size footnotesize
27231 \SpecialChar ~
27232 \SpecialChar ~
27233 .ds 2
27234 \layout Standard
27235
27236
27237 \size footnotesize
27238 ; sample.c 5
27239 \layout Standard
27240
27241
27242 \size footnotesize
27243 ; ----------------------------------------------
27244 \layout Standard
27245
27246
27247 \size footnotesize
27248 ; function function
27249 \layout Standard
27250
27251
27252 \size footnotesize
27253 ; ----------------------------------------------
27254 \layout Standard
27255
27256
27257 \size footnotesize
27258 _function:
27259 \layout Standard
27260
27261
27262 \size footnotesize
27263 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
27264 \layout Standard
27265
27266
27267 \size footnotesize
27268 \SpecialChar ~
27269 \SpecialChar ~
27270 mov r2,dpl
27271 \layout Standard
27272
27273
27274 \size footnotesize
27275 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
27276 \layout Standard
27277
27278
27279 \size footnotesize
27280 \SpecialChar ~
27281 \SpecialChar ~
27282 mov ar0,r2
27283 \layout Standard
27284
27285
27286 \size footnotesize
27287 ;_whilecontinue_0($1) :
27288 \layout Standard
27289
27290
27291 \size footnotesize
27292 00101$:
27293 \layout Standard
27294
27295
27296 \size footnotesize
27297 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
27298 \layout Standard
27299
27300
27301 \size footnotesize
27302 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
27303 \layout Standard
27304
27305
27306 \size footnotesize
27307 \SpecialChar ~
27308 \SpecialChar ~
27309 mov ar2,@r0
27310 \layout Standard
27311
27312
27313 \size footnotesize
27314 \SpecialChar ~
27315 \SpecialChar ~
27316 inc r0
27317 \layout Standard
27318
27319
27320 \size footnotesize
27321 \SpecialChar ~
27322 \SpecialChar ~
27323 mov ar3,@r0
27324 \layout Standard
27325
27326
27327 \size footnotesize
27328 \SpecialChar ~
27329 \SpecialChar ~
27330 dec r0
27331 \layout Standard
27332
27333
27334 \size footnotesize
27335 \SpecialChar ~
27336 \SpecialChar ~
27337 mov a,r2
27338 \layout Standard
27339
27340
27341 \size footnotesize
27342 \SpecialChar ~
27343 \SpecialChar ~
27344 orl a,r3
27345 \layout Standard
27346
27347
27348 \size footnotesize
27349 \SpecialChar ~
27350 \SpecialChar ~
27351 jz 00103$
27352 \layout Standard
27353
27354
27355 \size footnotesize
27356 00114$:
27357 \layout Standard
27358
27359
27360 \size footnotesize
27361 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
27362 \layout Standard
27363
27364
27365 \size footnotesize
27366 \SpecialChar ~
27367 \SpecialChar ~
27368 mov dpl,_p
27369 \layout Standard
27370
27371
27372 \size footnotesize
27373 \SpecialChar ~
27374 \SpecialChar ~
27375 mov dph,(_p + 1)
27376 \layout Standard
27377
27378
27379 \size footnotesize
27380 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
27381 \layout Standard
27382
27383
27384 \size footnotesize
27385 \SpecialChar ~
27386 \SpecialChar ~
27387 mov a,#0x02
27388 \layout Standard
27389
27390
27391 \size footnotesize
27392 \SpecialChar ~
27393 \SpecialChar ~
27394 add a,_p
27395 \layout Standard
27396
27397
27398 \size footnotesize
27399 \SpecialChar ~
27400 \SpecialChar ~
27401 mov _p,a
27402 \layout Standard
27403
27404
27405 \size footnotesize
27406 \SpecialChar ~
27407 \SpecialChar ~
27408 clr a
27409 \layout Standard
27410
27411
27412 \size footnotesize
27413 \SpecialChar ~
27414 \SpecialChar ~
27415 addc a,(_p + 1)
27416 \layout Standard
27417
27418
27419 \size footnotesize
27420 \SpecialChar ~
27421 \SpecialChar ~
27422 mov (_p + 1),a
27423 \layout Standard
27424
27425
27426 \size footnotesize
27427 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
27428 \layout Standard
27429
27430
27431 \size footnotesize
27432 \SpecialChar ~
27433 \SpecialChar ~
27434 movx a,@dptr
27435 \layout Standard
27436
27437
27438 \size footnotesize
27439 \SpecialChar ~
27440 \SpecialChar ~
27441 mov r2,a
27442 \layout Standard
27443
27444
27445 \size footnotesize
27446 \SpecialChar ~
27447 \SpecialChar ~
27448 inc dptr
27449 \layout Standard
27450
27451
27452 \size footnotesize
27453 \SpecialChar ~
27454 \SpecialChar ~
27455 movx a,@dptr
27456 \layout Standard
27457
27458
27459 \size footnotesize
27460 \SpecialChar ~
27461 \SpecialChar ~
27462 mov r3,a
27463 \layout Standard
27464
27465
27466 \size footnotesize
27467 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
27468 \layout Standard
27469
27470
27471 \size footnotesize
27472 \SpecialChar ~
27473 \SpecialChar ~
27474 mov @r0,ar2
27475 \layout Standard
27476
27477
27478 \size footnotesize
27479 \SpecialChar ~
27480 \SpecialChar ~
27481 inc r0
27482 \layout Standard
27483
27484
27485 \size footnotesize
27486 \SpecialChar ~
27487 \SpecialChar ~
27488 mov @r0,ar3
27489 \layout Standard
27490
27491
27492 \size footnotesize
27493 ; iTemp6 [lr5:16]{_near * int}[r0] =
27494 \layout Standard
27495
27496
27497 \size footnotesize
27498 ; iTemp6 [lr5:16]{_near * int}[r0] +
27499 \layout Standard
27500
27501
27502 \size footnotesize
27503 ; 0x2 {short}
27504 \layout Standard
27505
27506
27507 \size footnotesize
27508 \SpecialChar ~
27509 \SpecialChar ~
27510 inc r0
27511 \layout Standard
27512
27513
27514 \size footnotesize
27515 ; goto _whilecontinue_0($1)
27516 \layout Standard
27517
27518
27519 \size footnotesize
27520 \SpecialChar ~
27521 \SpecialChar ~
27522 sjmp 00101$
27523 \layout Standard
27524
27525
27526 \size footnotesize
27527 ; _whilebreak_0($3) :
27528 \layout Standard
27529
27530
27531 \size footnotesize
27532 00103$:
27533 \layout Standard
27534
27535
27536 \size footnotesize
27537 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
27538 \layout Standard
27539
27540
27541 \size footnotesize
27542 \SpecialChar ~
27543 \SpecialChar ~
27544 mov r2,#0x00
27545 \layout Standard
27546
27547
27548 \size footnotesize
27549 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
27550 \layout Standard
27551
27552
27553 \size footnotesize
27554 \SpecialChar ~
27555 \SpecialChar ~
27556 mov r3,#0x00
27557 \layout Standard
27558
27559
27560 \size footnotesize
27561 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
27562 \layout Standard
27563
27564
27565 \size footnotesize
27566 \SpecialChar ~
27567 \SpecialChar ~
27568 mov r4,#0x00
27569 \layout Standard
27570
27571
27572 \size footnotesize
27573 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
27574 \layout Standard
27575
27576
27577 \size footnotesize
27578 \SpecialChar ~
27579 \SpecialChar ~
27580 mov r5,#0x0A
27581 \layout Standard
27582
27583
27584 \size footnotesize
27585 \SpecialChar ~
27586 \SpecialChar ~
27587 mov r6,#0x00
27588 \layout Standard
27589
27590
27591 \size footnotesize
27592 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
27593 \layout Standard
27594
27595
27596 \size footnotesize
27597 \SpecialChar ~
27598 \SpecialChar ~
27599 mov r7,#0x1E
27600 \layout Standard
27601
27602
27603 \size footnotesize
27604 \SpecialChar ~
27605 \SpecialChar ~
27606 mov r0,#0x00
27607 \layout Standard
27608
27609
27610 \size footnotesize
27611 ; _forcond_0($4) :
27612 \layout Standard
27613
27614
27615 \size footnotesize
27616 00104$:
27617 \layout Standard
27618
27619
27620 \size footnotesize
27621 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
27622 \layout Standard
27623
27624
27625 \size footnotesize
27626 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
27627 \layout Standard
27628
27629
27630 \size footnotesize
27631 \SpecialChar ~
27632 \SpecialChar ~
27633 clr c
27634 \layout Standard
27635
27636
27637 \size footnotesize
27638 \SpecialChar ~
27639 \SpecialChar ~
27640 mov a,r4
27641 \layout Standard
27642
27643
27644 \size footnotesize
27645 \SpecialChar ~
27646 \SpecialChar ~
27647 xrl a,#0x80
27648 \layout Standard
27649
27650
27651 \size footnotesize
27652 \SpecialChar ~
27653 \SpecialChar ~
27654 subb a,#0x8a
27655 \layout Standard
27656
27657
27658 \size footnotesize
27659 \SpecialChar ~
27660 \SpecialChar ~
27661 jnc 00107$
27662 \layout Standard
27663
27664
27665 \size footnotesize
27666 00115$:
27667 \layout Standard
27668
27669
27670 \size footnotesize
27671 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
27672 \layout Standard
27673
27674
27675 \size footnotesize
27676 ; iTemp21 [lr21:38]{short}[r4]
27677 \layout Standard
27678
27679
27680 \size footnotesize
27681 \SpecialChar ~
27682 \SpecialChar ~
27683 mov a,r4
27684 \layout Standard
27685
27686
27687 \size footnotesize
27688 \SpecialChar ~
27689 \SpecialChar ~
27690 add a,r2
27691 \layout Standard
27692
27693
27694 \size footnotesize
27695 \SpecialChar ~
27696 \SpecialChar ~
27697 mov r2,a
27698 \layout Standard
27699
27700
27701 \size footnotesize
27702 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
27703 \layout Standard
27704
27705
27706 \size footnotesize
27707 \SpecialChar ~
27708 \SpecialChar ~
27709 mov b,#0x03
27710 \layout Standard
27711
27712
27713 \size footnotesize
27714 \SpecialChar ~
27715 \SpecialChar ~
27716 mov a,r4
27717 \layout Standard
27718
27719
27720 \size footnotesize
27721 \SpecialChar ~
27722 \SpecialChar ~
27723 mul ab
27724 \layout Standard
27725
27726
27727 \size footnotesize
27728 \SpecialChar ~
27729 \SpecialChar ~
27730 mov r1,a
27731 \layout Standard
27732
27733
27734 \size footnotesize
27735 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
27736 \layout Standard
27737
27738
27739 \size footnotesize
27740 ; iTemp15 [lr29:30]{short}[r1]
27741 \layout Standard
27742
27743
27744 \size footnotesize
27745 \SpecialChar ~
27746 \SpecialChar ~
27747 add a,r3
27748 \layout Standard
27749
27750
27751 \size footnotesize
27752 \SpecialChar ~
27753 \SpecialChar ~
27754 mov r3,a
27755 \layout Standard
27756
27757
27758 \size footnotesize
27759 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
27760 \layout Standard
27761
27762
27763 \size footnotesize
27764 \SpecialChar ~
27765 \SpecialChar ~
27766 mov a,r7
27767 \layout Standard
27768
27769
27770 \size footnotesize
27771 \SpecialChar ~
27772 \SpecialChar ~
27773 add a,#0xfd
27774 \layout Standard
27775
27776
27777 \size footnotesize
27778 \SpecialChar ~
27779 \SpecialChar ~
27780 mov r7,a
27781 \layout Standard
27782
27783
27784 \size footnotesize
27785 \SpecialChar ~
27786 \SpecialChar ~
27787 mov a,r0
27788 \layout Standard
27789
27790
27791 \size footnotesize
27792 \SpecialChar ~
27793 \SpecialChar ~
27794 addc a,#0xff
27795 \layout Standard
27796
27797
27798 \size footnotesize
27799 \SpecialChar ~
27800 \SpecialChar ~
27801 mov r0,a
27802 \layout Standard
27803
27804
27805 \size footnotesize
27806 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
27807 \layout Standard
27808
27809
27810 \size footnotesize
27811 \SpecialChar ~
27812 \SpecialChar ~
27813 mov a,r7
27814 \layout Standard
27815
27816
27817 \size footnotesize
27818 \SpecialChar ~
27819 \SpecialChar ~
27820 add a,_gint
27821 \layout Standard
27822
27823
27824 \size footnotesize
27825 \SpecialChar ~
27826 \SpecialChar ~
27827 mov _gint,a
27828 \layout Standard
27829
27830
27831 \size footnotesize
27832 \SpecialChar ~
27833 \SpecialChar ~
27834 mov a,r0
27835 \layout Standard
27836
27837
27838 \size footnotesize
27839 \SpecialChar ~
27840 \SpecialChar ~
27841 addc a,(_gint + 1)
27842 \layout Standard
27843
27844
27845 \size footnotesize
27846 \SpecialChar ~
27847 \SpecialChar ~
27848 mov (_gint + 1),a
27849 \layout Standard
27850
27851
27852 \size footnotesize
27853 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
27854 \layout Standard
27855
27856
27857 \size footnotesize
27858 \SpecialChar ~
27859 \SpecialChar ~
27860 inc r4
27861 \layout Standard
27862
27863
27864 \size footnotesize
27865 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
27866 \layout Standard
27867
27868
27869 \size footnotesize
27870 \SpecialChar ~
27871 \SpecialChar ~
27872 dec r5
27873 \layout Standard
27874
27875
27876 \size footnotesize
27877 \SpecialChar ~
27878 \SpecialChar ~
27879 cjne r5,#0xff,00104$
27880 \layout Standard
27881
27882
27883 \size footnotesize
27884 \SpecialChar ~
27885 \SpecialChar ~
27886 dec r6
27887 \layout Standard
27888
27889
27890 \size footnotesize
27891 ; goto _forcond_0($4)
27892 \layout Standard
27893
27894
27895 \size footnotesize
27896 \SpecialChar ~
27897 \SpecialChar ~
27898 sjmp 00104$
27899 \layout Standard
27900
27901
27902 \size footnotesize
27903 ; _forbreak_0($7) :
27904 \layout Standard
27905
27906
27907 \size footnotesize
27908 00107$:
27909 \layout Standard
27910
27911
27912 \size footnotesize
27913 ; ret iTemp24 [lr40:41]{short}
27914 \layout Standard
27915
27916
27917 \size footnotesize
27918 \SpecialChar ~
27919 \SpecialChar ~
27920 mov a,r3
27921 \layout Standard
27922
27923
27924 \size footnotesize
27925 \SpecialChar ~
27926 \SpecialChar ~
27927 add a,r2
27928 \layout Standard
27929
27930
27931 \size footnotesize
27932 \SpecialChar ~
27933 \SpecialChar ~
27934 mov dpl,a
27935 \layout Standard
27936
27937
27938 \size footnotesize
27939 ; _return($8) :
27940 \layout Standard
27941
27942
27943 \size footnotesize
27944 00108$:
27945 \layout Standard
27946
27947
27948 \size footnotesize
27949 \SpecialChar ~
27950 \SpecialChar ~
27951 ret
27952 \newline
27953
27954 \layout Section
27955
27956 A few words about basic block successors, predecessors and dominators
27957 \layout Standard
27958
27959 Successors are basic blocks
27960 \begin_inset LatexCommand \index{Basic blocks}
27961
27962 \end_inset
27963
27964  that might execute after this basic block.
27965 \newline
27966 Predecessors are basic blocks that might execute before reaching this basic
27967  block.
27968 \newline
27969 Dominators are basic blocks that WILL execute before reaching this basic
27970  block.
27971 \newline
27972
27973 \layout Standard
27974
27975 [basic block 1]
27976 \layout Standard
27977
27978 if (something)
27979 \layout Standard
27980
27981 \SpecialChar ~
27982 \SpecialChar ~
27983 \SpecialChar ~
27984 \SpecialChar ~
27985 [basic block 2]
27986 \layout Standard
27987
27988 else
27989 \layout Standard
27990
27991 \SpecialChar ~
27992 \SpecialChar ~
27993 \SpecialChar ~
27994 \SpecialChar ~
27995 [basic block 3]
27996 \layout Standard
27997
27998 [basic block 4]
27999 \newline
28000
28001 \layout Standard
28002
28003 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
28004 \layout Standard
28005
28006 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
28007 \layout Standard
28008
28009 c) domVect of [BB4] = BB1 ...
28010  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
28011  was executed.
28012 \layout Chapter
28013
28014 Acknowledgments
28015 \layout Standard
28016
28017
28018 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
28019
28020 \end_inset
28021
28022
28023 \newline
28024
28025 \newline
28026
28027 \emph on
28028 Thanks to all the other volunteer developers who have helped with coding,
28029  testing, web-page creation, distribution sets, etc.
28030  You know who you are :-)
28031 \emph default
28032
28033 \newline
28034
28035 \layout Standard
28036
28037 This document was initially written by Sandeep Dutta
28038 \layout Standard
28039
28040 All product names mentioned herein may be trademarks
28041 \begin_inset LatexCommand \index{Trademarks}
28042
28043 \end_inset
28044
28045  of their respective companies.
28046
28047 \layout Section*
28048
28049 Alphabetical index
28050 \layout Standard
28051
28052 To avoid confusion, the installation and building options for SDCC itself
28053  (chapter 2) are not part of the index.
28054 \layout Standard
28055
28056
28057 \begin_inset LatexCommand \printindex{}
28058
28059 \end_inset
28060
28061
28062 \the_end