git.gag.com Git - fw/sdcc/blob - doc/sdccman.lyx

   1 #LyX 1.3 created this file. For more info see http://www.lyx.org/
   2 \lyxformat 221
   3 \textclass book
   4 \begin_preamble
   5 \pdfoptionpdfminorversion=3
   6 \usepackage[
   7   pdftitle={SDCC Compiler User Guide},
   8   pdfauthor={SDCC development team},
   9   pdfsubject={installation, user manual},
  10   pdfkeywords={8032 8051 ansi c compiler CPU DS390
  11                embedded GPL HC08 manual mcs51 microcontroller PIC Z80},
  12   colorlinks=true,
  13   linkcolor=blue] {hyperref}
  14 %
  15 \sloppy
  16 \tolerance=500
  17 \emergencystretch=30pt
  18 %
  19 \date{}
  20 \end_preamble
  21 \language english
  22 \inputencoding default
  23 \fontscheme pslatex
  24 \graphics default
  25 \paperfontsize default
  26 \spacing single
  27 \papersize letterpaper
  28 \paperpackage a4
  29 \use_geometry 1
  30 \use_amsmath 0
  31 \use_natbib 0
  32 \use_numerical_citations 0
  33 \paperorientation portrait
  34 \leftmargin 30mm
  35 \topmargin 20mm
  36 \rightmargin 25mm
  37 \bottommargin 20mm
  38 \secnumdepth 3
  39 \tocdepth 3
  40 \paragraph_separation indent
  41 \defskip medskip
  42 \quotes_language swedish
  43 \quotes_times 2
  44 \papercolumns 1
  45 \papersides 1
  46 \paperpagestyle fancy
  47
  48 \layout Comment
  49
  50 Please note: double dashed longoptions (e.g.
  51  --version) are written this way: -
  52 \begin_inset ERT
  53 status Collapsed
  54
  55 \layout Standard
  56
  57 \backslash
  58 /
  59 \end_inset
  60
  61 -
  62 \layout Comment
  63
  64 Two resp.
  65  three consecutive dashes simply result in a long resp.
  66  extra long dash.
  67 \layout Comment
  68
  69 Architecture specific stuff (like memory models, code examples) should maybe
  70  later go
  71 \layout Comment
  72
  73 into seperate sections/chapters/appendices (it is hard to document PIC or
  74  Z80 in
  75 \layout Comment
  76
  77 a 8051 centered document) - for now simply add.
  78 \layout Title
  79
  80 SDCC Compiler User Guide
  81 \layout Date
  82
  83
  84 \size normal
  85 SDCC 2.5.5
  86 \size footnotesize
  87
  88 \newline
  89 $Date$
  90 \newline
  91 $Revision$
  92 \layout Comment
  93
  94 The above strings enclosed in $ are automatically updated by 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  or
3689 \begin_inset LatexCommand \url{http://sf.net/projects/fpgac}
3690
3691 \end_inset
3692
3693
3694 \begin_inset LatexCommand \index{FpgaC ((subset of) C to FPGA compiler)}
3695
3696 \end_inset
3697
3698
3699 \begin_inset Quotes sld
3700 \end_inset
3701
3702 have you ever heard of an open source compiler that compiles a subset of
3703  C for an FPGA?
3704 \begin_inset Quotes srd
3705 \end_inset
3706
3707  we expect you to have a quick look there and come back.
3708  If you read this you are on the right track.
3709 \layout Itemize
3710
3711 Some sections attribute more space to problems, restrictions and warnings
3712  than to the solution.
3713 \layout Itemize
3714
3715 The installation section and the section about the debugger is intimidating.
3716 \layout Itemize
3717
3718 There are still lots of typos and there are more different writing styles
3719  than pictures.
3720 \layout Section
3721
3722 Testing the SDCC Compiler
3723 \begin_inset LatexCommand \label{sec:Testing-the-SDCC}
3724
3725 \end_inset
3726
3727
3728 \layout Standard
3729
3730 The first thing you should do after installing your SDCC compiler is to
3731  see if it runs.
3732  Type
3733 \family sans
3734 \series bold
3735 "sdcc -
3736 \begin_inset ERT
3737 status Collapsed
3738
3739 \layout Standard
3740
3741 \backslash
3742 /
3743 \end_inset
3744
3745 -version"
3746 \begin_inset LatexCommand \index{version}
3747
3748 \end_inset
3749
3750
3751 \family default
3752 \series default
3753  at the prompt, and the program should run and tell you the version.
3754  If it doesn't run, or gives a message about not finding sdcc program, then
3755  you need to check over your installation.
3756  Make sure that the sdcc bin directory is in your executable search path
3757  defined by the PATH environment setting (
3758 \series medium
3759 see
3760 \series default
3761 section
3762 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3763
3764 \end_inset
3765
3766 \SpecialChar ~
3767
3768 \series medium
3769 Install trouble-shooting for suggestions
3770 \series default
3771 ).
3772  Make sure that the sdcc program is in the bin folder, if not perhaps something
3773  did not install correctly.
3774 \newline
3775
3776 \newline
3777
3778 \series medium
3779 SDCC
3780 \series default
3781 is commonly installed as described in section
3782 \begin_inset Quotes sld
3783 \end_inset
3784
3785 Install and search paths
3786 \begin_inset Quotes srd
3787 \end_inset
3788
3789 .
3790 \newline
3791
3792 \newline
3793
3794 \series medium
3795 Make sure the compiler works on a very simple example.
3796  Type in the following test.c program using your favorite
3797 \series default
3798 ASCII
3799 \series medium
3800 editor:
3801 \layout Verse
3802
3803
3804 \family typewriter
3805 char test;
3806 \newline
3807
3808 \newline
3809 void main(void) {
3810 \newline
3811 \SpecialChar ~
3812 \SpecialChar ~
3813 \SpecialChar ~
3814 \SpecialChar ~
3815 test=0;
3816 \newline
3817 }
3818 \layout Standard
3819
3820
3821 \series medium
3822 Compile this using the following command:
3823 \family sans
3824 \series bold
3825 "sdcc -c test.c".
3826
3827 \family default
3828 \series default
3829
3830 \series medium
3831 If all goes well, the compiler will generate a test.asm and test.rel file.
3832  Congratulations, you've just compiled your first program with SDCC.
3833  We used the -c option to tell SDCC not to link the generated code, just
3834  to keep things simple for this step.
3835 \series default
3836
3837 \newline
3838
3839 \newline
3840
3841 \series medium
3842 The next step is to try it with the linker.
3843  Type in
3844 \family sans
3845 \series bold
3846 "sdcc test.c
3847 \family default
3848 \series default
3849 "
3850 \series medium
3851 .
3852  If all goes well the compiler will link with the libraries and produce
3853  a test.ihx output file.
3854  If this step fails
3855 \series default
3856
3857 \series medium
3858 (no test.ihx, and the linker generates warnings), then the problem is most
3859  likely that
3860 \series default
3861 SDCC
3862 \series medium
3863  cannot find the
3864 \series default
3865 /
3866 \series medium
3867 usr/local/share/sdcc/lib directory
3868 \series default
3869
3870 \series medium
3871 (see
3872 \series default
3873 section
3874 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3875
3876 \end_inset
3877
3878 \SpecialChar ~
3879
3880 \series medium
3881 Install trouble-shooting for suggestions).
3882 \series default
3883
3884 \newline
3885
3886 \newline
3887
3888 \series medium
3889 The final test is to ensure
3890 \series default
3891 SDCC
3892 \series medium
3893  can use the
3894 \series default
3895 standard
3896 \series medium
3897  header files and libraries.
3898  Edit test.c and change it to the following:
3899 \layout Verse
3900
3901
3902 \family typewriter
3903 #include <string.h>
3904 \newline
3905
3906 \newline
3907 char str1[10];
3908 \newline
3909
3910 \newline
3911 void main(void) {
3912 \newline
3913 \SpecialChar ~
3914 \SpecialChar ~
3915 strcpy(str1, "testing");
3916 \newline
3917 }
3918 \layout Standard
3919
3920
3921 \series medium
3922 Compile this by typing
3923 \family sans
3924 \series bold
3925 "sdcc test.c"
3926 \family default
3927 \series medium
3928 .
3929  This should generate a test.ihx output file, and it should give no warnings
3930  such as not finding the string.h file.
3931  If it cannot find the string.h file, then the problem is that
3932 \series default
3933 SDCC
3934 \series medium
3935  cannot find the /usr/local/share/sdcc/include directory
3936 \series default
3937
3938 \series medium
3939 (see the
3940 \series default
3941 section
3942 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3943
3944 \end_inset
3945
3946 \SpecialChar ~
3947
3948 \series medium
3949 Install trouble-shooting section for suggestions).
3950
3951 \series default
3952  Use option
3953 \series bold
3954 -
3955 \begin_inset ERT
3956 status Collapsed
3957
3958 \layout Standard
3959
3960 \backslash
3961 /
3962 \end_inset
3963
3964 -print-search-dirs
3965 \series default
3966
3967 \begin_inset LatexCommand \index{-\/-print-search-dirs}
3968
3969 \end_inset
3970
3971  to find exactly where SDCC is looking for the include and lib files.
3972 \layout Section
3973
3974 Install Trouble-shooting
3975 \begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
3976
3977 \end_inset
3978
3979
3980 \begin_inset LatexCommand \index{Install trouble-shooting}
3981
3982 \end_inset
3983
3984
3985 \layout Subsection
3986
3987 If SDCC does not build correctly
3988 \layout Standard
3989
3990 A thing to try is starting from scratch by unpacking the .tgz source package
3991  again in an empty directory.
3992  Configure it like:
3993 \newline
3994
3995 \newline
3996
3997 \family sans
3998 \series bold
3999 ./configure 2>&1 | tee configure.log
4000 \family default
4001 \series default
4002
4003 \newline
4004
4005 \newline
4006 and build it like:
4007 \newline
4008
4009 \newline
4010
4011 \family sans
4012 \series bold
4013 make 2>&1 | tee make.log
4014 \family default
4015 \series default
4016
4017 \newline
4018
4019 \newline
4020 If anything goes wrong, you can review the log files to locate the problem.
4021  Or a relevant part of this can be attached to an email that could be helpful
4022  when requesting help from the mailing list.
4023 \layout Subsection
4024
4025 What the
4026 \begin_inset Quotes sld
4027 \end_inset
4028
4029 ./configure
4030 \begin_inset Quotes srd
4031 \end_inset
4032
4033  does
4034 \layout Standard
4035
4036 The
4037 \begin_inset Quotes sld
4038 \end_inset
4039
4040 ./configure
4041 \begin_inset Quotes srd
4042 \end_inset
4043
4044  command is a script that analyzes your system and performs some configuration
4045  to ensure the source package compiles on your system.
4046  It will take a few minutes to run, and will compile a few tests to determine
4047  what compiler features are installed.
4048 \layout Subsection
4049
4050 What the
4051 \begin_inset Quotes sld
4052 \end_inset
4053
4054 make
4055 \begin_inset Quotes srd
4056 \end_inset
4057
4058  does
4059 \layout Standard
4060
4061 This runs the GNU make tool, which automatically compiles all the source
4062  packages into the final installed binary executables.
4063 \layout Subsection
4064
4065 What the
4066 \begin_inset Quotes sld
4067 \end_inset
4068
4069 make install
4070 \begin_inset Quotes erd
4071 \end_inset
4072
4073  command does.
4074 \layout Standard
4075
4076 This will install the compiler, other executables libraries and include
4077  files into the appropriate directories.
4078  See sections
4079 \begin_inset LatexCommand \ref{sub:Install-paths}
4080
4081 \end_inset
4082
4083 ,\SpecialChar ~
4084
4085 \begin_inset LatexCommand \ref{sub:Search-Paths}
4086
4087 \end_inset
4088
4089 \SpecialChar ~
4090 about install and search paths.
4091 \newline
4092 On most systems you will need super-user privileges to do this.
4093 \layout Section
4094
4095 Components of SDCC
4096 \layout Standard
4097
4098 SDCC is not just a compiler, but a collection of tools by various developers.
4099  These include linkers, assemblers, simulators and other components.
4100  Here is a summary of some of the components.
4101  Note that the included simulator and assembler have separate documentation
4102  which you can find in the source package in their respective directories.
4103  As SDCC grows to include support for other processors, other packages from
4104  various developers are included and may have their own sets of documentation.
4105 \newline
4106
4107 \newline
4108 You might want to look at the files which are installed in <installdir>.
4109  At the time of this writing, we find the following programs for gcc-builds:
4110 \newline
4111
4112 \newline
4113 In <installdir>/bin:
4114 \layout Itemize
4115
4116 sdcc - The compiler.
4117 \layout Itemize
4118
4119 sdcpp - The C preprocessor.
4120 \layout Itemize
4121
4122 asx8051 - The assembler for 8051 type processors.
4123 \layout Itemize
4124
4125 as-z80
4126 \series bold
4127 ,
4128 \series default
4129 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
4130 \layout Itemize
4131
4132 aslink -The linker for 8051 type processors.
4133 \layout Itemize
4134
4135 link-z80
4136 \series bold
4137 ,
4138 \series default
4139 link-gbz80 - The Z80 and GameBoy Z80 linkers.
4140 \layout Itemize
4141
4142 s51 - The ucSim 8051 simulator.
4143  Not available on Win32 platforms.
4144 \layout Itemize
4145
4146 sdcdb - The source debugger.
4147  Not available on Win32 platforms.
4148 \layout Itemize
4149
4150 packihx - A tool to pack (compress) Intel hex files.
4151 \layout Standard
4152
4153 In <installdir>/share/sdcc/include
4154 \layout Itemize
4155
4156 the include files
4157 \layout Standard
4158
4159 In <installdir>/share/sdcc/lib
4160 \layout Itemize
4161
4162 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
4163  relocatables.
4164 \layout Standard
4165
4166 In <installdir>/share/sdcc/doc
4167 \layout Itemize
4168
4169 the documentation
4170 \layout Standard
4171
4172 As development for other processors proceeds, this list will expand to include
4173  executables to support processors like AVR, PIC, etc.
4174 \layout Subsection
4175
4176 sdcc - The Compiler
4177 \layout Standard
4178
4179 This is the actual compiler, it in turn uses the c-preprocessor and invokes
4180  the assembler and linkage editor.
4181 \layout Subsection
4182
4183 sdcpp - The C-Preprocessor
4184 \layout Standard
4185
4186 The preprocessor
4187 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
4188
4189 \end_inset
4190
4191  is a modified version of the GNU preprocessor.
4192  The C preprocessor is used to pull in #include sources, process #ifdef
4193  statements, #defines and so on.
4194 \layout Subsection
4195
4196 as
4197 \emph on
4198 xxxx
4199 \emph default
4200 , aslink, link-
4201 \emph on
4202 xxx
4203 \emph default
4204  - The Assemblers and Linkage Editors
4205 \layout Standard
4206
4207 This is retargettable assembler & linkage editor, it was developed by Alan
4208  Baldwin.
4209  John Hartman created the version for 8051, and I (Sandeep) have made some
4210  enhancements and bug fixes for it to work properly with SDCC.
4211 \layout Subsection
4212
4213 s51 - The Simulator
4214 \layout Standard
4215
4216 S51
4217 \begin_inset LatexCommand \index{s51}
4218
4219 \end_inset
4220
4221  is a freeware, opensource simulator developed by Daniel Drotos.
4222  The simulator is built as part of the build process.
4223  For more information visit Daniel's web site at:
4224 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
4225
4226 \end_inset
4227
4228 .
4229  It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
4230  XA51 family.
4231  S51 is currently not available on Win32 platfors.
4232 \layout Subsection
4233
4234 sdcdb - Source Level Debugger
4235 \layout Standard
4236
4237 Sdcdb
4238 \begin_inset LatexCommand \index{sdcdb (debugger)}
4239
4240 \end_inset
4241
4242  is the companion source level debugger.
4243  More about sdcdb in section
4244 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
4245
4246 \end_inset
4247
4248 .
4249  The current version of the debugger uses Daniel's Simulator S51
4250 \begin_inset LatexCommand \index{s51}
4251
4252 \end_inset
4253
4254 , but can be easily changed to use other simulators.
4255  Sdcdb is currently not available on Win32 platfors.
4256 \layout Chapter
4257
4258 Using SDCC
4259 \layout Section
4260
4261 Compiling
4262 \layout Subsection
4263
4264 Single Source File Projects
4265 \layout Standard
4266
4267 For single source file 8051 projects the process is very simple.
4268  Compile your programs with the following command
4269 \family sans
4270 \series bold
4271 "sdcc sourcefile.c".
4272
4273 \family default
4274 \series default
4275  This will compile, assemble and link your source file.
4276  Output files are as follows:
4277 \layout Itemize
4278
4279 sourcefile.asm
4280 \begin_inset LatexCommand \index{<file>.asm}
4281
4282 \end_inset
4283
4284  - Assembler source
4285 \begin_inset LatexCommand \index{Assembler source}
4286
4287 \end_inset
4288
4289  file created by the compiler
4290 \layout Itemize
4291
4292 sourcefile.lst
4293 \begin_inset LatexCommand \index{<file>.lst}
4294
4295 \end_inset
4296
4297  - Assembler listing
4298 \begin_inset LatexCommand \index{Assembler listing}
4299
4300 \end_inset
4301
4302  file created by the Assembler
4303 \layout Itemize
4304
4305 sourcefile.rst
4306 \begin_inset LatexCommand \index{<file>.rst}
4307
4308 \end_inset
4309
4310  - Assembler listing
4311 \begin_inset LatexCommand \index{Assembler listing}
4312
4313 \end_inset
4314
4315  file updated with linkedit information, created by linkage editor
4316 \layout Itemize
4317
4318 sourcefile.sym
4319 \begin_inset LatexCommand \index{<file>.sym}
4320
4321 \end_inset
4322
4323  - symbol listing
4324 \begin_inset LatexCommand \index{Symbol listing}
4325
4326 \end_inset
4327
4328  for the sourcefile, created by the assembler
4329 \layout Itemize
4330
4331 sourcefile.rel
4332 \begin_inset LatexCommand \index{<file>.rel}
4333
4334 \end_inset
4335
4336  or sourcefile.o
4337 \begin_inset LatexCommand \index{<file>.o}
4338
4339 \end_inset
4340
4341  - Object file
4342 \begin_inset LatexCommand \index{Object file}
4343
4344 \end_inset
4345
4346  created by the assembler, input to Linkage editor
4347 \layout Itemize
4348
4349 sourcefile.map
4350 \begin_inset LatexCommand \index{<file>.map}
4351
4352 \end_inset
4353
4354  - The memory map
4355 \begin_inset LatexCommand \index{Memory map}
4356
4357 \end_inset
4358
4359  for the load module, created by the Linker
4360 \layout Itemize
4361
4362 sourcefile.mem
4363 \begin_inset LatexCommand \index{<file>.mem}
4364
4365 \end_inset
4366
4367  - A file with a summary of the memory usage
4368 \layout Itemize
4369
4370 sourcefile.ihx
4371 \begin_inset LatexCommand \index{<file>.ihx}
4372
4373 \end_inset
4374
4375  - The load module in Intel hex format
4376 \begin_inset LatexCommand \index{Intel hex format}
4377
4378 \end_inset
4379
4380  (you can select the Motorola S19 format
4381 \begin_inset LatexCommand \index{Motorola S19 format}
4382
4383 \end_inset
4384
4385  with -
4386 \begin_inset ERT
4387 status Collapsed
4388
4389 \layout Standard
4390
4391 \backslash
4392 /
4393 \end_inset
4394
4395 -out-fmt-s19
4396 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
4397
4398 \end_inset
4399
4400 .
4401  If you need another format you might want to use
4402 \family sans
4403 \shape italic
4404 objdump
4405 \family default
4406 \shape default
4407
4408 \begin_inset LatexCommand \index{objdump (tool)}
4409
4410 \end_inset
4411
4412  or
4413 \family sans
4414 \shape italic
4415  srecord
4416 \family default
4417 \shape default
4418
4419 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4420
4421 \end_inset
4422
4423 ).
4424  Both formats are documented in the documentation of srecord
4425 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4426
4427 \end_inset
4428
4429
4430 \layout Itemize
4431
4432 sourcefile.adb
4433 \begin_inset LatexCommand \index{<file>.adb}
4434
4435 \end_inset
4436
4437  - An intermediate file containing debug information needed to create the
4438  .cdb file (with -
4439 \begin_inset ERT
4440 status Open
4441
4442 \layout Standard
4443
4444 \backslash
4445 /
4446 \end_inset
4447
4448 -debug
4449 \begin_inset LatexCommand \index{-\/-debug}
4450
4451 \end_inset
4452
4453 )
4454 \layout Itemize
4455
4456 sourcefile.cdb
4457 \begin_inset LatexCommand \index{<file>.cdb}
4458
4459 \end_inset
4460
4461  - An optional file (with -
4462 \begin_inset ERT
4463 status Collapsed
4464
4465 \layout Standard
4466
4467 \backslash
4468 /
4469 \end_inset
4470
4471 -debug) containing debug information.
4472  The format is documented in cdbfileformat.pdf
4473 \layout Itemize
4474
4475 sourcefile.
4476  - (no extension)
4477 \begin_inset LatexCommand \index{<file> (no extension)}
4478
4479 \end_inset
4480
4481  An optional AOMF or AOMF51
4482 \begin_inset LatexCommand \index{AOMF, AOMF51}
4483
4484 \end_inset
4485
4486  file containing debug information (generated with option -
4487 \begin_inset ERT
4488 status Collapsed
4489
4490 \layout Standard
4491
4492 \backslash
4493 /
4494 \end_inset
4495
4496 -debug).
4497  The (Intel)
4498 \emph on
4499  a
4500 \emph default
4501 bsolute
4502 \emph on
4503 o
4504 \emph default
4505 bject
4506 \emph on
4507 m
4508 \emph default
4509 odule
4510 \emph on
4511 f
4512 \emph default
4513 ormat is commonly used by third party tools (debuggers
4514 \begin_inset LatexCommand \index{Debugger}
4515
4516 \end_inset
4517
4518 , simulators, emulators)
4519 \layout Itemize
4520
4521 sourcefile.dump*
4522 \begin_inset LatexCommand \index{<file>.dump*}
4523
4524 \end_inset
4525
4526  - Dump file to debug the compiler it self (generated with option -
4527 \begin_inset ERT
4528 status Collapsed
4529
4530 \layout Standard
4531
4532 \backslash
4533 /
4534 \end_inset
4535
4536 -dumpall) (see section
4537 \begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
4538
4539 \end_inset
4540
4541 \SpecialChar ~
4542  and section
4543 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
4544
4545 \end_inset
4546
4547 \SpecialChar ~
4548
4549 \begin_inset Quotes sld
4550 \end_inset
4551
4552 Anatomy of the compiler
4553 \begin_inset Quotes srd
4554 \end_inset
4555
4556 ).
4557 \layout Subsection
4558
4559 Projects with Multiple Source Files
4560 \layout Standard
4561
4562 SDCC can compile only ONE file at a time.
4563  Let us for example assume that you have a project containing the following
4564  files:
4565 \newline
4566
4567 \newline
4568 foo1.c (contains some functions)
4569 \newline
4570 foo2.c (contains some more functions)
4571 \newline
4572 foomain.c (contains more functions and the function main)
4573 \newline
4574
4575 \size footnotesize
4576
4577 \newline
4578
4579 \size default
4580 The first two files will need to be compiled separately with the commands:
4581 \size footnotesize
4582
4583 \size default
4584
4585 \newline
4586
4587 \newline
4588
4589 \family sans
4590 \series bold
4591 sdcc\SpecialChar ~
4592 -c\SpecialChar ~
4593 foo1.c
4594 \family default
4595 \series default
4596 \size footnotesize
4597
4598 \newline
4599
4600 \family sans
4601 \series bold
4602 \size default
4603 sdcc\SpecialChar ~
4604 -c\SpecialChar ~
4605 foo2.c
4606 \family default
4607 \series default
4608
4609 \newline
4610
4611 \newline
4612 Then compile the source file containing the
4613 \emph on
4614 main()
4615 \emph default
4616  function and link
4617 \begin_inset LatexCommand \index{Linker}
4618
4619 \end_inset
4620
4621  the files together with the following command:
4622 \newline
4623
4624 \newline
4625
4626 \family sans
4627 \series bold
4628 sdcc\SpecialChar ~
4629 foomain.c\SpecialChar ~
4630 foo1.rel\SpecialChar ~
4631 foo2.rel
4632 \family default
4633 \series default
4634
4635 \begin_inset LatexCommand \index{<file>.rel}
4636
4637 \end_inset
4638
4639
4640 \newline
4641
4642 \newline
4643 Alternatively,
4644 \emph on
4645 foomain.c
4646 \emph default
4647 can be separately compiled as well:
4648 \family sans
4649 \series bold
4650
4651 \newline
4652
4653 \newline
4654 sdcc\SpecialChar ~
4655 -c\SpecialChar ~
4656 foomain.c
4657 \newline
4658 sdcc foomain.rel foo1.rel foo2.rel
4659 \newline
4660
4661 \newline
4662
4663 \family default
4664 \series default
4665 The file containing the
4666 \emph on
4667 main()
4668 \emph default
4669  function
4670 \emph on
4671
4672 \emph default
4673 \noun on
4674 must
4675 \noun default
4676  be the
4677 \noun on
4678 first
4679 \noun default
4680  file specified in the command line, since the linkage editor processes
4681  file in the order they are presented to it.
4682  The linker is invoked from SDCC using a script file with extension .lnk
4683 \begin_inset LatexCommand \index{<file>.lnk}
4684
4685 \end_inset
4686
4687 .
4688  You can view this file to troubleshoot linking problems such as those arising
4689  from missing libraries.
4690 \layout Subsection
4691
4692 Projects with Additional Libraries
4693 \begin_inset LatexCommand \index{Libraries}
4694
4695 \end_inset
4696
4697
4698 \layout Standard
4699
4700 Some reusable routines may be compiled into a library, see the documentation
4701  for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
4702  for how to create a
4703 \emph on
4704 .lib
4705 \begin_inset LatexCommand \index{<file>.lib}
4706
4707 \end_inset
4708
4709
4710 \emph default
4711  library file.
4712  Libraries created in this manner can be included in the command line.
4713  Make sure you include the -L <library-path> option to tell the linker where
4714  to look for these files if they are not in the current directory.
4715  Here is an example, assuming you have the source file
4716 \emph on
4717 foomain.c
4718 \emph default
4719  and a library
4720 \emph on
4721  foolib.lib
4722 \emph default
4723  in the directory
4724 \emph on
4725 mylib
4726 \emph default
4727  (if that is not the same as your current project):
4728 \newline
4729
4730 \newline
4731
4732 \family sans
4733 \series bold
4734 sdcc foomain.c foolib.lib -L mylib
4735 \newline
4736
4737 \newline
4738
4739 \family default
4740 \series default
4741 Note here that
4742 \emph on
4743  mylib
4744 \emph default
4745  must be an absolute path name.
4746 \newline
4747
4748 \newline
4749 The most efficient way to use libraries is to keep separate modules in separate
4750  source files.
4751  The lib file now should name all the modules.rel
4752 \begin_inset LatexCommand \index{<file>.rel}
4753
4754 \end_inset
4755
4756  files.
4757  For an example see the standard library file
4758 \emph on
4759 libsdcc.lib
4760 \emph default
4761  in the directory <installdir>/share/lib/small.
4762 \layout Subsection
4763
4764 Using sdcclib to Create and Manage Libraries
4765 \begin_inset LatexCommand \index{sdcclib}
4766
4767 \end_inset
4768
4769
4770 \layout Standard
4771
4772 Alternatively, instead of having a .rel file for each entry on the library
4773  file as described in the preceding section, sdcclib can be used to embed
4774  all the modules belonging to such library in the library file itself.
4775  This results in a larger library file, but it greatly reduces the number
4776  of disk files accessed by the linker.
4777   Additionally, the packed library file contains an index of all include
4778  modules and symbols that significantly speeds up the linking process.
4779  To display a list of options supported by sdcclib type:
4780 \newline
4781
4782 \layout Standard
4783
4784
4785 \family sans
4786 \series bold
4787 sdcclib -?
4788 \begin_inset LatexCommand \index{sdcclib}
4789
4790 \end_inset
4791
4792
4793 \newline
4794
4795 \newline
4796
4797 \family default
4798 \series default
4799 To create a new library file, start by compiling all the required modules.
4800  For example:
4801 \newline
4802
4803 \layout Standard
4804
4805
4806 \family sans
4807 \series bold
4808 sdcc -c _divsint.c
4809 \layout Standard
4810
4811
4812 \family sans
4813 \series bold
4814 sdcc -c _divuint.c
4815 \layout Standard
4816
4817
4818 \family sans
4819 \series bold
4820 sdcc -c _modsint.c
4821 \layout Standard
4822
4823
4824 \family sans
4825 \series bold
4826 sdcc -c _moduint.c
4827 \layout Standard
4828
4829
4830 \family sans
4831 \series bold
4832 sdcc -c _mulint.c
4833 \newline
4834
4835 \layout Standard
4836
4837 This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
4838  and _mulint.rel.
4839  The next step is to add the .rel files to the library file:
4840 \newline
4841
4842 \layout Standard
4843
4844
4845 \family sans
4846 \series bold
4847 sdcclib libint.lib _divsint.rel
4848 \family default
4849
4850 \begin_inset LatexCommand \index{sdcclib}
4851
4852 \end_inset
4853
4854
4855 \layout Standard
4856
4857
4858 \family sans
4859 \series bold
4860 sdcclib libint.lib _divuint.rel
4861 \layout Standard
4862
4863
4864 \family sans
4865 \series bold
4866 sdcclib libint.lib _modsint.rel
4867 \layout Standard
4868
4869
4870 \family sans
4871 \series bold
4872 sdcclib libint.lib _moduint.rel
4873 \layout Standard
4874
4875
4876 \family sans
4877 \series bold
4878 sdcclib libint.lib _mulint.rel
4879 \series default
4880
4881 \newline
4882
4883 \layout Standard
4884
4885 If the file already exists in the library, it will be replaced.
4886  To see what modules and symbols are included in the library, options -s
4887  and -m are available.
4888  For example:
4889 \newline
4890
4891 \newline
4892
4893 \family sans
4894 \series bold
4895 sdcclib -s libint.lib
4896 \family default
4897
4898 \begin_inset LatexCommand \index{sdcclib}
4899
4900 \end_inset
4901
4902
4903 \newline
4904
4905 \family typewriter
4906 \series default
4907 _divsint.rel:
4908 \layout Standard
4909
4910
4911 \family typewriter
4912 __divsint_a_1_1
4913 \layout Standard
4914
4915
4916 \family typewriter
4917 __divsint_PARM_2
4918 \layout Standard
4919
4920
4921 \family typewriter
4922 __divsint
4923 \newline
4924 _divuint.rel:
4925 \layout Standard
4926
4927
4928 \family typewriter
4929 __divuint_a_1_1
4930 \layout Standard
4931
4932
4933 \family typewriter
4934 __divuint_PARM_2
4935 \layout Standard
4936
4937
4938 \family typewriter
4939 __divuint_reste_1_1
4940 \layout Standard
4941
4942
4943 \family typewriter
4944 __divuint_count_1_1
4945 \layout Standard
4946
4947
4948 \family typewriter
4949 __divuint
4950 \newline
4951 _modsint.rel:
4952 \layout Standard
4953
4954
4955 \family typewriter
4956 __modsint_a_1_1
4957 \layout Standard
4958
4959
4960 \family typewriter
4961 __modsint_PARM_2
4962 \layout Standard
4963
4964
4965 \family typewriter
4966 __modsint
4967 \newline
4968 _moduint.rel:
4969 \layout Standard
4970
4971
4972 \family typewriter
4973 __moduint_a_1_1
4974 \layout Standard
4975
4976
4977 \family typewriter
4978 __moduint_PARM_2
4979 \layout Standard
4980
4981
4982 \family typewriter
4983 __moduint_count_1_1
4984 \layout Standard
4985
4986
4987 \family typewriter
4988 __moduint
4989 \newline
4990 _mulint.rel:
4991 \layout Standard
4992
4993
4994 \family typewriter
4995 __mulint_PARM_2
4996 \layout Standard
4997
4998
4999 \family typewriter
5000 __mulint
5001 \family default
5002 \series bold
5003
5004 \newline
5005
5006 \layout Standard
5007
5008 If the source files are compiled using -
5009 \begin_inset ERT
5010 status Open
5011
5012 \layout Standard
5013
5014 \backslash
5015 /
5016 \end_inset
5017
5018 -debug
5019 \begin_inset LatexCommand \index{-\/-debug}
5020
5021 \end_inset
5022
5023 , the corresponding debug information file .adb will be include in the library
5024  file as well.
5025  The library files created with sdcclib are plain text files, so they can
5026  be viewed with a text editor.
5027  It is not recomended to modify a library file created with sdcclib using
5028  a text editor, as there are file indexes numbers located accross the file
5029  used by the linker to quickly locate the required module to link.
5030  Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
5031  it can be safely deleted, since all the information required for linking
5032  is embedded in the library file itself.
5033  Library files created using sdcclib are used as described in the preceding
5034  sections.
5035 \layout Section
5036
5037 Command Line Options
5038 \begin_inset LatexCommand \index{Command Line Options}
5039
5040 \end_inset
5041
5042
5043 \layout Subsection
5044
5045 Processor Selection Options
5046 \begin_inset LatexCommand \index{Options processor selection}
5047
5048 \end_inset
5049
5050
5051 \begin_inset LatexCommand \index{Processor selection options}
5052
5053 \end_inset
5054
5055
5056 \layout List
5057 \labelwidthstring 00.00.0000
5058
5059
5060 \series bold
5061 -mmcs51
5062 \begin_inset LatexCommand \index{-mmcs51}
5063
5064 \end_inset
5065
5066
5067 \series default
5068  Generate code for the Intel MCS51
5069 \begin_inset LatexCommand \index{MCS51}
5070
5071 \end_inset
5072
5073  family of processors.
5074  This is the default processor target.
5075 \layout List
5076 \labelwidthstring 00.00.0000
5077
5078
5079 \series bold
5080 -mds390
5081 \begin_inset LatexCommand \index{-mds390}
5082
5083 \end_inset
5084
5085
5086 \series default
5087  Generate code for the Dallas DS80C390
5088 \begin_inset LatexCommand \index{DS80C390}
5089
5090 \end_inset
5091
5092  processor.
5093 \layout List
5094 \labelwidthstring 00.00.0000
5095
5096
5097 \series bold
5098 -mds400
5099 \begin_inset LatexCommand \index{-mds400}
5100
5101 \end_inset
5102
5103
5104 \series default
5105  Generate code for the Dallas DS80C400
5106 \begin_inset LatexCommand \index{DS80C400}
5107
5108 \end_inset
5109
5110  processor.
5111 \layout List
5112 \labelwidthstring 00.00.0000
5113
5114
5115 \series bold
5116 -mhc08
5117 \begin_inset LatexCommand \index{-mhc08}
5118
5119 \end_inset
5120
5121
5122 \series default
5123  Generate code for the Freescale/Motorola HC08
5124 \begin_inset LatexCommand \index{HC08}
5125
5126 \end_inset
5127
5128  family of processors.
5129 \layout List
5130 \labelwidthstring 00.00.0000
5131
5132
5133 \series bold
5134 -mz80
5135 \begin_inset LatexCommand \index{-mz80}
5136
5137 \end_inset
5138
5139
5140 \series default
5141  Generate code for the Zilog Z80
5142 \begin_inset LatexCommand \index{Z80}
5143
5144 \end_inset
5145
5146  family of processors.
5147 \layout List
5148 \labelwidthstring 00.00.0000
5149
5150
5151 \series bold
5152 -mgbz80
5153 \begin_inset LatexCommand \index{-mgbz80}
5154
5155 \end_inset
5156
5157
5158 \series default
5159  Generate code for the GameBoy Z80
5160 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
5161
5162 \end_inset
5163
5164  processor (Not actively maintained).
5165 \layout List
5166 \labelwidthstring 00.00.0000
5167
5168
5169 \series bold
5170 -mavr
5171 \begin_inset LatexCommand \index{-mavr}
5172
5173 \end_inset
5174
5175
5176 \series default
5177  Generate code for the Atmel AVR
5178 \begin_inset LatexCommand \index{AVR}
5179
5180 \end_inset
5181
5182  processor (In development, not complete).
5183  AVR users should probably have a look at winavr
5184 \begin_inset LatexCommand \url{http://sourceforge.net/projects/winavr}
5185
5186 \end_inset
5187
5188  or
5189 \begin_inset LatexCommand \url{http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index}
5190
5191 \end_inset
5192
5193 .
5194 \layout Comment
5195
5196 I think it is fair to direct users there for now.
5197  Open source is also about avoiding unnecessary work .
5198  But I didn't find the 'official' link.
5199 \layout List
5200 \labelwidthstring 00.00.0000
5201
5202
5203 \series bold
5204 -mpic14
5205 \begin_inset LatexCommand \index{-mpic14}
5206
5207 \end_inset
5208
5209
5210 \series default
5211  Generate code for the Microchip PIC 14
5212 \begin_inset LatexCommand \index{PIC14}
5213
5214 \end_inset
5215
5216 -bit processors (p16f84 and variants.
5217  In development, not complete).
5218 \layout Comment
5219
5220 p16f627 p16f628 p16f84 p16f873 p16f877?
5221 \layout List
5222 \labelwidthstring 00.00.0000
5223
5224
5225 \series bold
5226 -mpic16
5227 \begin_inset LatexCommand \index{-mpic16}
5228
5229 \end_inset
5230
5231
5232 \series default
5233  Generate code for the Microchip PIC 16
5234 \begin_inset LatexCommand \index{PIC16}
5235
5236 \end_inset
5237
5238 -bit processors (p18f452 and variants.
5239  In development, not complete).
5240 \layout List
5241 \labelwidthstring 00.00.0000
5242
5243
5244 \series bold
5245 -mtlcs900h
5246 \series default
5247  Generate code for the Toshiba TLCS-900H
5248 \begin_inset LatexCommand \index{TLCS-900H}
5249
5250 \end_inset
5251
5252  processor (Not maintained, not complete).
5253 \layout List
5254 \labelwidthstring 00.00.0000
5255
5256
5257 \series bold
5258 -mxa51
5259 \begin_inset LatexCommand \index{-mxa51}
5260
5261 \end_inset
5262
5263
5264 \series default
5265  Generate code for the Phillips XA51
5266 \begin_inset LatexCommand \index{XA51}
5267
5268 \end_inset
5269
5270  processor (Not maintained, not complete).
5271 \layout Subsection
5272
5273 Preprocessor Options
5274 \begin_inset LatexCommand \index{Options preprocessor}
5275
5276 \end_inset
5277
5278
5279 \begin_inset LatexCommand \index{Preprocessor options}
5280
5281 \end_inset
5282
5283
5284 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5285
5286 \end_inset
5287
5288
5289 \layout List
5290 \labelwidthstring 00.00.0000
5291
5292
5293 \series bold
5294 -I<path>
5295 \begin_inset LatexCommand \index{-I<path>}
5296
5297 \end_inset
5298
5299
5300 \series default
5301  The additional location where the pre processor will look for <..h> or
5302 \begin_inset Quotes eld
5303 \end_inset
5304
5305 ..h
5306 \begin_inset Quotes erd
5307 \end_inset
5308
5309  files.
5310 \layout List
5311 \labelwidthstring 00.00.0000
5312
5313
5314 \series bold
5315 -D<macro[=value]>
5316 \begin_inset LatexCommand \index{-D<macro[=value]>}
5317
5318 \end_inset
5319
5320
5321 \series default
5322  Command line definition of macros.
5323  Passed to the preprocessor.
5324 \layout List
5325 \labelwidthstring 00.00.0000
5326
5327
5328 \series bold
5329 -M
5330 \begin_inset LatexCommand \index{-M}
5331
5332 \end_inset
5333
5334
5335 \series default
5336  Tell the preprocessor to output a rule suitable for make describing the
5337  dependencies of each object file.
5338  For each source file, the preprocessor outputs one make-rule whose target
5339  is the object file name for that source file and whose dependencies are
5340  all the files `#include'd in it.
5341  This rule may be a single line or may be continued with `
5342 \backslash
5343 '-newline if it is long.
5344  The list of rules is printed on standard output instead of the preprocessed
5345  C program.
5346  `-M' implies `-E
5347 \begin_inset LatexCommand \index{-E}
5348
5349 \end_inset
5350
5351 '.
5352 \layout List
5353 \labelwidthstring 00.00.0000
5354
5355
5356 \series bold
5357 -C
5358 \begin_inset LatexCommand \index{-C}
5359
5360 \end_inset
5361
5362
5363 \series default
5364  Tell the preprocessor not to discard comments.
5365  Used with the `-E' option.
5366 \layout List
5367 \labelwidthstring 00.00.0000
5368
5369
5370 \series bold
5371 -MM
5372 \begin_inset LatexCommand \index{-MM}
5373
5374 \end_inset
5375
5376
5377 \size large
5378 \bar under
5379
5380 \series default
5381 \size default
5382 \bar default
5383 Like `-M' but the output mentions only the user header files included with
5384  `#include
5385 \begin_inset Quotes eld
5386 \end_inset
5387
5388 file"'.
5389  System header files included with `#include <file>' are omitted.
5390 \layout List
5391 \labelwidthstring 00.00.0000
5392
5393
5394 \series bold
5395 -Aquestion(answer)
5396 \begin_inset LatexCommand \index{-Aquestion(answer)}
5397
5398 \end_inset
5399
5400
5401 \series default
5402  Assert the answer answer for question, in case it is tested with a preprocessor
5403  conditional such as `#if #question(answer)'.
5404  `-A-' disables the standard assertions that normally describe the target
5405  machine.
5406 \layout List
5407 \labelwidthstring 00.00.0000
5408
5409
5410 \series bold
5411 -Umacro
5412 \begin_inset LatexCommand \index{-Umacro}
5413
5414 \end_inset
5415
5416
5417 \series default
5418  Undefine macro macro.
5419  `-U' options are evaluated after all `-D' options, but before any `-include'
5420  and `-imacros' options.
5421 \layout List
5422 \labelwidthstring 00.00.0000
5423
5424
5425 \series bold
5426 -dM
5427 \begin_inset LatexCommand \index{-dM}
5428
5429 \end_inset
5430
5431
5432 \series default
5433  Tell the preprocessor to output only a list of the macro definitions that
5434  are in effect at the end of preprocessing.
5435  Used with the `-E' option.
5436 \layout List
5437 \labelwidthstring 00.00.0000
5438
5439
5440 \series bold
5441 -dD
5442 \begin_inset LatexCommand \index{-dD}
5443
5444 \end_inset
5445
5446
5447 \series default
5448  Tell the preprocessor to pass all macro definitions into the output, in
5449  their proper sequence in the rest of the output.
5450 \layout List
5451 \labelwidthstring 00.00.0000
5452
5453
5454 \series bold
5455 -dN
5456 \begin_inset LatexCommand \index{-dN}
5457
5458 \end_inset
5459
5460
5461 \size large
5462 \bar under
5463
5464 \series default
5465 \size default
5466 \bar default
5467 Like `-dD' except that the macro arguments and contents are omitted.
5468  Only `#define name' is included in the output.
5469 \layout List
5470 \labelwidthstring 00.00.0000
5471
5472
5473 \series bold
5474 -Wp\SpecialChar ~
5475 preprocessorOption[,preprocessorOption]
5476 \series default
5477
5478 \begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
5479
5480 \end_inset
5481
5482 ...
5483  Pass the preprocessorOption to the preprocessor
5484 \family typewriter
5485 sdcpp
5486 \family default
5487
5488 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5489
5490 \end_inset
5491
5492 .
5493  SDCC uses an adapted version of the preprocessor cpp of the GNU Compiler
5494  Collection (gcc), if you need more dedicated options please refer to the
5495  documentation at
5496 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
5497
5498 \end_inset
5499
5500 .
5501 \layout Subsection
5502
5503 Linker Options
5504 \begin_inset LatexCommand \index{Options linker}
5505
5506 \end_inset
5507
5508
5509 \begin_inset LatexCommand \index{Linker options}
5510
5511 \end_inset
5512
5513
5514 \layout List
5515 \labelwidthstring 00.00.0000
5516
5517
5518 \series bold
5519 -L\SpecialChar ~
5520 -
5521 \series default
5522
5523 \begin_inset ERT
5524 status Collapsed
5525
5526 \layout Standard
5527
5528 \backslash
5529 /
5530 \end_inset
5531
5532
5533 \series bold
5534 -lib-path
5535 \begin_inset LatexCommand \index{-\/-lib-path <path>}
5536
5537 \end_inset
5538
5539
5540 \begin_inset LatexCommand \index{-L -\/-lib-path}
5541
5542 \end_inset
5543
5544
5545 \series default
5546 \SpecialChar ~
5547 <absolute path to additional libraries> This option is passed to the linkage
5548  editor's additional libraries
5549 \begin_inset LatexCommand \index{Libraries}
5550
5551 \end_inset
5552
5553  search path.
5554  The path name must be absolute.
5555  Additional library files may be specified in the command line.
5556  See section Compiling programs for more details.
5557 \layout List
5558 \labelwidthstring 00.00.0000
5559
5560
5561 \series bold
5562 -
5563 \begin_inset ERT
5564 status Collapsed
5565
5566 \layout Standard
5567
5568 \backslash
5569 /
5570 \end_inset
5571
5572 -xram-loc
5573 \series default
5574
5575 \begin_inset LatexCommand \index{-\/-xram-loc <Value>}
5576
5577 \end_inset
5578
5579 \SpecialChar ~
5580 <Value> The start location of the external ram
5581 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
5582
5583 \end_inset
5584
5585 , default value is 0.
5586  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5587 \begin_inset ERT
5588 status Collapsed
5589
5590 \layout Standard
5591
5592 \backslash
5593 /
5594 \end_inset
5595
5596 -xram-loc 0x8000 or -
5597 \begin_inset ERT
5598 status Collapsed
5599
5600 \layout Standard
5601
5602 \backslash
5603 /
5604 \end_inset
5605
5606 -xram-loc 32768.
5607 \layout List
5608 \labelwidthstring 00.00.0000
5609
5610
5611 \series bold
5612 -
5613 \begin_inset ERT
5614 status Collapsed
5615
5616 \layout Standard
5617
5618 \backslash
5619 /
5620 \end_inset
5621
5622 -code-loc
5623 \series default
5624
5625 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
5626
5627 \end_inset
5628
5629 \SpecialChar ~
5630 <Value> The start location of the code
5631 \begin_inset LatexCommand \index{code}
5632
5633 \end_inset
5634
5635  segment, default value 0.
5636  Note when this option is used the interrupt vector table is also relocated
5637  to the given address.
5638  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5639 \begin_inset ERT
5640 status Collapsed
5641
5642 \layout Standard
5643
5644 \backslash
5645 /
5646 \end_inset
5647
5648 -code-loc 0x8000 or -
5649 \begin_inset ERT
5650 status Collapsed
5651
5652 \layout Standard
5653
5654 \backslash
5655 /
5656 \end_inset
5657
5658 -code-loc 32768.
5659 \layout List
5660 \labelwidthstring 00.00.0000
5661
5662
5663 \series bold
5664 -
5665 \begin_inset ERT
5666 status Collapsed
5667
5668 \layout Standard
5669
5670 \backslash
5671 /
5672 \end_inset
5673
5674 -stack-loc
5675 \series default
5676
5677 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
5678
5679 \end_inset
5680
5681 \SpecialChar ~
5682 <Value> By default the stack
5683 \begin_inset LatexCommand \index{stack}
5684
5685 \end_inset
5686
5687  is placed after the data segment.
5688  Using this option the stack can be placed anywhere in the internal memory
5689  space of the 8051.
5690  The value entered can be in Hexadecimal or Decimal format, e.g.
5691  -
5692 \begin_inset ERT
5693 status Collapsed
5694
5695 \layout Standard
5696
5697 \backslash
5698 /
5699 \end_inset
5700
5701 -stack-loc 0x20 or -
5702 \begin_inset ERT
5703 status Collapsed
5704
5705 \layout Standard
5706
5707 \backslash
5708 /
5709 \end_inset
5710
5711 -stack-loc 32.
5712  Since the sp register is incremented before a push or call, the initial
5713  sp will be set to one byte prior the provided value.
5714  The provided value should not overlap any other memory areas such as used
5715  register banks or the data segment and with enough space for the current
5716  application.
5717  The
5718 \series bold
5719 -
5720 \begin_inset ERT
5721 status Collapsed
5722
5723 \layout Standard
5724
5725 \backslash
5726 /
5727 \end_inset
5728
5729 -pack-iram
5730 \series default
5731 \SpecialChar ~
5732
5733 \begin_inset LatexCommand \index{-\/-pack-iram}
5734
5735 \end_inset
5736
5737  option (which is now a default setting) will override this setting, so
5738  you should also specify the
5739 \series bold
5740 -
5741 \begin_inset ERT
5742 status Collapsed
5743
5744 \layout Standard
5745
5746 \backslash
5747 /
5748 \end_inset
5749
5750 -no-pack-iram
5751 \series default
5752 \SpecialChar ~
5753
5754 \begin_inset LatexCommand \index{-\/-no-pack-iram}
5755
5756 \end_inset
5757
5758  option if you need to manually place the stack.
5759 \layout List
5760 \labelwidthstring 00.00.0000
5761
5762
5763 \series bold
5764 -
5765 \begin_inset ERT
5766 status Collapsed
5767
5768 \layout Standard
5769
5770 \backslash
5771 /
5772 \end_inset
5773
5774 -xstack-loc
5775 \series default
5776
5777 \begin_inset LatexCommand \index{-\/-xstack-loc <Value>}
5778
5779 \end_inset
5780
5781 \SpecialChar ~
5782 <Value> By default the external stack
5783 \begin_inset LatexCommand \index{xstack}
5784
5785 \end_inset
5786
5787  is placed after the pdata segment.
5788  Using this option the xstack can be placed anywhere in the external memory
5789  space of the 8051.
5790  The value entered can be in Hexadecimal or Decimal format, e.g.
5791  -
5792 \begin_inset ERT
5793 status Collapsed
5794
5795 \layout Standard
5796
5797 \backslash
5798 /
5799 \end_inset
5800
5801 -xstack-loc 0x8000 or -
5802 \begin_inset ERT
5803 status Collapsed
5804
5805 \layout Standard
5806
5807 \backslash
5808 /
5809 \end_inset
5810
5811 -stack-loc 32768.
5812  The provided value should not overlap any other memory areas such as the
5813  pdata or xdata segment and with enough space for the current application.
5814 \layout List
5815 \labelwidthstring 00.00.0000
5816
5817
5818 \series bold
5819 -
5820 \begin_inset ERT
5821 status Collapsed
5822
5823 \layout Standard
5824
5825 \backslash
5826 /
5827 \end_inset
5828
5829 -data-loc
5830 \series default
5831
5832 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
5833
5834 \end_inset
5835
5836 \SpecialChar ~
5837 <Value> The start location of the internal ram data
5838 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
5839
5840 \end_inset
5841
5842  segment.
5843  The value entered can be in Hexadecimal or Decimal format, eg.
5844  -
5845 \begin_inset ERT
5846 status Collapsed
5847
5848 \layout Standard
5849
5850 \backslash
5851 /
5852 \end_inset
5853
5854 -data-loc 0x20 or -
5855 \begin_inset ERT
5856 status Collapsed
5857
5858 \layout Standard
5859
5860 \backslash
5861 /
5862 \end_inset
5863
5864 -data-loc 32.
5865  (By default, the start location of the internal ram data segment  is set
5866  as low as possible in memory, taking into account the used register banks
5867  and the bit segment at address 0x20.
5868  For example if register banks 0 and 1 are used without bit variables, the
5869  data segment will be set, if -
5870 \begin_inset ERT
5871 status Collapsed
5872
5873 \layout Standard
5874
5875 \backslash
5876 /
5877 \end_inset
5878
5879 -data-loc is not used, to location 0x10.)
5880 \layout List
5881 \labelwidthstring 00.00.0000
5882
5883
5884 \series bold
5885 -
5886 \begin_inset ERT
5887 status Collapsed
5888
5889 \layout Standard
5890
5891 \backslash
5892 /
5893 \end_inset
5894
5895 -idata-loc
5896 \series default
5897
5898 \begin_inset LatexCommand \index{-\/-idata-loc <Value>}
5899
5900 \end_inset
5901
5902 \SpecialChar ~
5903 <Value> The start location of the indirectly addressable internal ram
5904 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
5905
5906 \end_inset
5907
5908  of the 8051, default value is 0x80.
5909  The value entered can be in Hexadecimal or Decimal format, eg.
5910  -
5911 \begin_inset ERT
5912 status Collapsed
5913
5914 \layout Standard
5915
5916 \backslash
5917 /
5918 \end_inset
5919
5920 -idata-loc 0x88 or -
5921 \begin_inset ERT
5922 status Collapsed
5923
5924 \layout Standard
5925
5926 \backslash
5927 /
5928 \end_inset
5929
5930 -idata-loc 136.
5931 \layout List
5932 \labelwidthstring 00.00.0000
5933
5934
5935 \series bold
5936 -
5937 \begin_inset ERT
5938 status Collapsed
5939
5940 \layout Standard
5941
5942 \backslash
5943 /
5944 \end_inset
5945
5946 -bit-loc
5947 \series default
5948 \SpecialChar ~
5949 <Value> The start location of the bit
5950 \begin_inset LatexCommand \index{bit}
5951
5952 \end_inset
5953
5954  addressable internal ram of the 8051.
5955  This is
5956 \emph on
5957 not
5958 \emph default
5959  implemented yet.
5960  Instead an option can be passed directly to the linker: -Wl\SpecialChar ~
5961 -bBSEG=<Value>.
5962 \layout List
5963 \labelwidthstring 00.00.0000
5964
5965
5966 \series bold
5967 -
5968 \begin_inset ERT
5969 status Collapsed
5970
5971 \layout Standard
5972
5973 \backslash
5974 /
5975 \end_inset
5976
5977 -out-fmt-ihx
5978 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
5979
5980 \end_inset
5981
5982
5983 \bar under
5984
5985 \series default
5986 \bar default
5987 The linker output (final object code) is in Intel Hex format.
5988 \begin_inset LatexCommand \index{Intel hex format}
5989
5990 \end_inset
5991
5992  This is the default option.
5993  The format itself is documented in the documentation of srecord
5994 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
5995
5996 \end_inset
5997
5998 .
5999 \layout List
6000 \labelwidthstring 00.00.0000
6001
6002
6003 \series bold
6004 -
6005 \begin_inset ERT
6006 status Collapsed
6007
6008 \layout Standard
6009
6010 \backslash
6011 /
6012 \end_inset
6013
6014 -out-fmt-s19
6015 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
6016
6017 \end_inset
6018
6019
6020 \bar under
6021
6022 \series default
6023 \bar default
6024 The linker output (final object code) is in Motorola S19 format
6025 \begin_inset LatexCommand \index{Motorola S19 format}
6026
6027 \end_inset
6028
6029 .
6030  The format itself is documented in the documentation of srecord.
6031 \layout List
6032 \labelwidthstring 00.00.0000
6033
6034
6035 \series bold
6036 -
6037 \begin_inset ERT
6038 status Collapsed
6039
6040 \layout Standard
6041
6042 \backslash
6043 /
6044 \end_inset
6045
6046 -out-fmt-elf
6047 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
6048
6049 \end_inset
6050
6051
6052 \bar under
6053
6054 \series default
6055 \bar default
6056 The linker output (final object code) is in ELF format
6057 \begin_inset LatexCommand \index{ELF format}
6058
6059 \end_inset
6060
6061 .
6062  (Currently only supported for the HC08 processors)
6063 \layout List
6064 \labelwidthstring 00.00.0000
6065
6066
6067 \series bold
6068 -Wl\SpecialChar ~
6069 linkOption[,linkOption]
6070 \series default
6071
6072 \begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
6073
6074 \end_inset
6075
6076 ...
6077  Pass the linkOption to the linker.
6078  See file sdcc/as/doc/asxhtm.html for more on linker options.
6079 \layout Subsection
6080
6081 MCS51 Options
6082 \begin_inset LatexCommand \index{Options MCS51}
6083
6084 \end_inset
6085
6086
6087 \begin_inset LatexCommand \index{MCS51 options}
6088
6089 \end_inset
6090
6091
6092 \layout List
6093 \labelwidthstring 00.00.0000
6094
6095
6096 \series bold
6097 -
6098 \begin_inset ERT
6099 status Collapsed
6100
6101 \layout Standard
6102
6103 \backslash
6104 /
6105 \end_inset
6106
6107 -model-small
6108 \begin_inset LatexCommand \index{-\/-model-small}
6109
6110 \end_inset
6111
6112
6113 \series default
6114 \size large
6115 \emph on
6116
6117 \size default
6118 \emph default
6119 Generate code for Small Model programs, see section Memory Models for more
6120  details.
6121  This is the default model.
6122 \layout List
6123 \labelwidthstring 00.00.0000
6124
6125
6126 \series bold
6127 -
6128 \begin_inset ERT
6129 status Collapsed
6130
6131 \layout Standard
6132
6133 \backslash
6134 /
6135 \end_inset
6136
6137 -model-medium
6138 \begin_inset LatexCommand \index{-\/-model-medium}
6139
6140 \end_inset
6141
6142
6143 \series default
6144  Generate code for Medium model programs, see section Memory Models for
6145  more details.
6146  If this option is used all source files in the project have to be compiled
6147  with this option.
6148  It must also be used when invoking the linker.
6149 \layout List
6150 \labelwidthstring 00.00.0000
6151
6152
6153 \series bold
6154 -
6155 \begin_inset ERT
6156 status Collapsed
6157
6158 \layout Standard
6159
6160 \backslash
6161 /
6162 \end_inset
6163
6164 -model-large
6165 \begin_inset LatexCommand \index{-\/-model-large}
6166
6167 \end_inset
6168
6169
6170 \series default
6171  Generate code for Large model programs, see section Memory Models for more
6172  details.
6173  If this option is used all source files in the project have to be compiled
6174  with this option.
6175  It must also be used when invoking the linker.
6176 \layout List
6177 \labelwidthstring 00.00.0000
6178
6179
6180 \series bold
6181 -
6182 \begin_inset ERT
6183 status Collapsed
6184
6185 \layout Standard
6186
6187 \backslash
6188 /
6189 \end_inset
6190
6191 -xstack
6192 \begin_inset LatexCommand \index{-\/-xstack}
6193
6194 \end_inset
6195
6196
6197 \series default
6198  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
6199  variables and passing parameters.
6200  See section
6201 \begin_inset LatexCommand \ref{sub:External-Stack}
6202
6203 \end_inset
6204
6205 \SpecialChar ~
6206  External Stack for more details.
6207 \layout List
6208 \labelwidthstring 00.00.0000
6209
6210
6211 \series bold
6212 -
6213 \begin_inset ERT
6214 status Collapsed
6215
6216 \layout Standard
6217
6218 \backslash
6219 /
6220 \end_inset
6221
6222 -iram-size
6223 \series default
6224 \SpecialChar ~
6225 <Value>
6226 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
6227
6228 \end_inset
6229
6230  Causes the linker to check if the internal ram usage is within limits of
6231  the given value.
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 -xram-size
6248 \series default
6249 \SpecialChar ~
6250 <Value>
6251 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
6252
6253 \end_inset
6254
6255  Causes the linker to check if the external ram usage is within limits of
6256  the given value.
6257 \layout List
6258 \labelwidthstring 00.00.0000
6259
6260
6261 \series bold
6262 -
6263 \begin_inset ERT
6264 status Collapsed
6265
6266 \layout Standard
6267
6268 \backslash
6269 /
6270 \end_inset
6271
6272 -code-size
6273 \series default
6274 \SpecialChar ~
6275 <Value>
6276 \begin_inset LatexCommand \index{-\/-code-size <Value>}
6277
6278 \end_inset
6279
6280  Causes the linker to check if the code memory usage is within limits of
6281  the given value.
6282 \layout List
6283 \labelwidthstring 00.00.0000
6284
6285
6286 \series bold
6287 -
6288 \begin_inset ERT
6289 status Collapsed
6290
6291 \layout Standard
6292
6293 \backslash
6294 /
6295 \end_inset
6296
6297 -stack-size
6298 \series default
6299 \SpecialChar ~
6300 <Value>
6301 \begin_inset LatexCommand \index{-\/-stack-size <Value>}
6302
6303 \end_inset
6304
6305  Causes the linker to check if there is at minimum <Value> bytes for stack.
6306 \layout List
6307 \labelwidthstring 00.00.0000
6308
6309
6310 \series bold
6311 -
6312 \begin_inset ERT
6313 status Collapsed
6314
6315 \layout Standard
6316
6317 \backslash
6318 /
6319 \end_inset
6320
6321 -pack-iram
6322 \series default
6323 \SpecialChar ~
6324
6325 \begin_inset LatexCommand \index{-\/-pack-iram}
6326
6327 \end_inset
6328
6329  Causes the linker to use unused register banks for data variables and pack
6330  data, idata and stack together.
6331  This is the default now.
6332 \layout List
6333 \labelwidthstring 00.00.0000
6334
6335
6336 \series bold
6337 -
6338 \begin_inset ERT
6339 status Collapsed
6340
6341 \layout Standard
6342
6343 \backslash
6344 /
6345 \end_inset
6346
6347 -no-pack-iram
6348 \series default
6349 \SpecialChar ~
6350
6351 \begin_inset LatexCommand \index{-\/-no-pack-iram}
6352
6353 \end_inset
6354
6355  Causes the linker to use old style for allocating memory areas.
6356 \layout Subsection
6357
6358 DS390 / DS400 Options
6359 \begin_inset LatexCommand \index{Options DS390}
6360
6361 \end_inset
6362
6363
6364 \begin_inset LatexCommand \index{DS390 options}
6365
6366 \end_inset
6367
6368
6369 \layout List
6370 \labelwidthstring 00.00.0000
6371
6372
6373 \series bold
6374 -
6375 \begin_inset ERT
6376 status Collapsed
6377
6378 \layout Standard
6379
6380 \backslash
6381 /
6382 \end_inset
6383
6384 -model-flat24
6385 \series default
6386
6387 \begin_inset LatexCommand \index{-\/-model-flat24}
6388
6389 \end_inset
6390
6391
6392 \size large
6393 \emph on
6394
6395 \size default
6396 \emph default
6397 Generate 24-bit flat mode code.
6398  This is the one and only that the ds390 code generator supports right now
6399  and is default when using
6400 \emph on
6401 -mds390
6402 \emph default
6403 .
6404  See section Memory Models for more details.
6405 \layout List
6406 \labelwidthstring 00.00.0000
6407
6408
6409 \series bold
6410 -
6411 \begin_inset ERT
6412 status Collapsed
6413
6414 \layout Standard
6415
6416 \backslash
6417 /
6418 \end_inset
6419
6420 -protect-sp-update
6421 \begin_inset LatexCommand \index{-\/-protect-sp-update}
6422
6423 \end_inset
6424
6425
6426 \series default
6427  disable interrupts during ESP:SP updates.
6428 \layout List
6429 \labelwidthstring 00.00.0000
6430
6431
6432 \series bold
6433 -
6434 \begin_inset ERT
6435 status Collapsed
6436
6437 \layout Standard
6438
6439 \backslash
6440 /
6441 \end_inset
6442
6443 -stack-10bit
6444 \series default
6445
6446 \begin_inset LatexCommand \index{-\/-stack-10bit}
6447
6448 \end_inset
6449
6450  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
6451  This is the one and only that the ds390 code generator supports right now
6452  and is default when using
6453 \emph on
6454 -mds390
6455 \emph default
6456 .
6457  In this mode, the stack is located in the lower 1K of the internal RAM,
6458  which is mapped to 0x400000.
6459  Note that the support is incomplete, since it still uses a single byte
6460  as the stack pointer.
6461  This means that only the lower 256 bytes of the potential 1K stack space
6462  will actually be used.
6463  However, this does allow you to reclaim the precious 256 bytes of low RAM
6464  for use for the DATA and IDATA segments.
6465  The compiler will not generate any code to put the processor into 10 bit
6466  stack mode.
6467  It is important to ensure that the processor is in this mode before calling
6468  any re-entrant functions compiled with this option.
6469  In principle, this should work with the
6470 \emph on
6471 -
6472 \begin_inset ERT
6473 status Collapsed
6474
6475 \layout Standard
6476
6477 \backslash
6478 /
6479 \end_inset
6480
6481 -stack-auto
6482 \begin_inset LatexCommand \index{-\/-stack-auto}
6483
6484 \end_inset
6485
6486
6487 \emph default
6488  option, but that has not been tested.
6489  It is incompatible with the
6490 \emph on
6491 -
6492 \begin_inset ERT
6493 status Collapsed
6494
6495 \layout Standard
6496
6497 \backslash
6498 /
6499 \end_inset
6500
6501 -xstack
6502 \begin_inset LatexCommand \index{-\/-xstack}
6503
6504 \end_inset
6505
6506
6507 \emph default
6508  option.
6509  It also only makes sense if the processor is in 24 bit contiguous addressing
6510  mode (see the
6511 \emph on
6512 -
6513 \begin_inset ERT
6514 status Collapsed
6515
6516 \layout Standard
6517
6518 \backslash
6519 /
6520 \end_inset
6521
6522 -model-flat24 option
6523 \emph default
6524 ).
6525 \layout List
6526 \labelwidthstring 00.00.0000
6527
6528
6529 \series bold
6530 -
6531 \begin_inset ERT
6532 status Collapsed
6533
6534 \layout Standard
6535
6536 \backslash
6537 /
6538 \end_inset
6539
6540 -stack-probe
6541 \begin_inset LatexCommand \index{-\/-stack-probe}
6542
6543 \end_inset
6544
6545
6546 \series default
6547  insert call to function __stack_probe at each function prologue.
6548 \layout List
6549 \labelwidthstring 00.00.0000
6550
6551
6552 \series bold
6553 -
6554 \begin_inset ERT
6555 status Collapsed
6556
6557 \layout Standard
6558
6559 \backslash
6560 /
6561 \end_inset
6562
6563 -tini-libid
6564 \begin_inset LatexCommand \index{-\/-tini-libid}
6565
6566 \end_inset
6567
6568
6569 \series default
6570  <nnnn> LibraryID used in -mTININative.
6571
6572 \layout List
6573 \labelwidthstring 00.00.0000
6574
6575
6576 \series bold
6577 -
6578 \begin_inset ERT
6579 status Collapsed
6580
6581 \layout Standard
6582
6583 \backslash
6584 /
6585 \end_inset
6586
6587 -use-accelerator
6588 \begin_inset LatexCommand \index{-\/-use-accelerator}
6589
6590 \end_inset
6591
6592
6593 \series default
6594  generate code for DS390 Arithmetic Accelerator.
6595
6596 \layout Subsection
6597
6598 Z80 Options
6599 \begin_inset LatexCommand \index{Options Z80}
6600
6601 \end_inset
6602
6603
6604 \begin_inset LatexCommand \index{Z80 options}
6605
6606 \end_inset
6607
6608
6609 \layout List
6610 \labelwidthstring 00.00.0000
6611
6612
6613 \series bold
6614 -
6615 \begin_inset ERT
6616 status Collapsed
6617
6618 \layout Standard
6619
6620 \backslash
6621 /
6622 \end_inset
6623
6624 -callee-saves-bc
6625 \series default
6626
6627 \begin_inset LatexCommand \index{-\/-callee-saves-bc}
6628
6629 \end_inset
6630
6631
6632 \size large
6633 \emph on
6634
6635 \size default
6636 \emph default
6637 Force a called function to always save BC.
6638 \layout List
6639 \labelwidthstring 00.00.0000
6640
6641
6642 \series bold
6643 -
6644 \begin_inset ERT
6645 status Collapsed
6646
6647 \layout Standard
6648
6649 \backslash
6650 /
6651 \end_inset
6652
6653 -no-std-crt0
6654 \series default
6655
6656 \begin_inset LatexCommand \index{-\/-no-std-crt0}
6657
6658 \end_inset
6659
6660  When linking, skip the standard crt0.o object file.
6661  You must provide your own crt0.o for your system when linking.
6662
6663 \layout Subsection
6664
6665 Optimization Options
6666 \begin_inset LatexCommand \index{Options optimization}
6667
6668 \end_inset
6669
6670
6671 \begin_inset LatexCommand \index{Optimization options}
6672
6673 \end_inset
6674
6675
6676 \layout List
6677 \labelwidthstring 00.00.0000
6678
6679
6680 \series bold
6681 -
6682 \begin_inset ERT
6683 status Collapsed
6684
6685 \layout Standard
6686
6687 \backslash
6688 /
6689 \end_inset
6690
6691 -nogcse
6692 \begin_inset LatexCommand \index{-\/-nogcse}
6693
6694 \end_inset
6695
6696
6697 \series default
6698  Will not do global subexpression elimination, this option may be used when
6699  the compiler creates undesirably large stack/data spaces to store compiler
6700  temporaries (
6701 \emph on
6702 s
6703 \emph default
6704 pill
6705 \emph on
6706 loc
6707 \emph default
6708 ations, sloc
6709 \begin_inset LatexCommand \index{sloc (spill location)}
6710
6711 \end_inset
6712
6713 ).
6714  A warning message will be generated when this happens and the compiler
6715  will indicate the number of extra bytes it allocated.
6716  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6717 nogcse
6718 \begin_inset LatexCommand \index{\#pragma nogcse}
6719
6720 \end_inset
6721
6722  can be used to turn off global subexpression elimination
6723 \begin_inset LatexCommand \index{Subexpression elimination}
6724
6725 \end_inset
6726
6727  for a given function only.
6728 \layout List
6729 \labelwidthstring 00.00.0000
6730
6731
6732 \series bold
6733 -
6734 \begin_inset ERT
6735 status Collapsed
6736
6737 \layout Standard
6738
6739 \backslash
6740 /
6741 \end_inset
6742
6743 -noinvariant
6744 \begin_inset LatexCommand \index{-\/-noinvariant}
6745
6746 \end_inset
6747
6748
6749 \series default
6750  Will not do loop invariant optimizations, this may be turned off for reasons
6751  explained for the previous option.
6752  For more details of loop optimizations performed see Loop Invariants in
6753  section
6754 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
6755
6756 \end_inset
6757
6758 .
6759  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6760 noinvariant
6761 \begin_inset LatexCommand \index{\#pragma noinvariant}
6762
6763 \end_inset
6764
6765  can be used to turn off invariant optimizations for a given function only.
6766 \layout List
6767 \labelwidthstring 00.00.0000
6768
6769
6770 \series bold
6771 -
6772 \begin_inset ERT
6773 status Collapsed
6774
6775 \layout Standard
6776
6777 \backslash
6778 /
6779 \end_inset
6780
6781 -noinduction
6782 \begin_inset LatexCommand \index{-\/-noinduction}
6783
6784 \end_inset
6785
6786
6787 \series default
6788  Will not do loop induction optimizations, see section strength reduction
6789  for more details.
6790  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6791 noinduction
6792 \begin_inset LatexCommand \index{\#pragma noinduction}
6793
6794 \end_inset
6795
6796  can be used to turn off induction optimizations for a given function only.
6797 \layout List
6798 \labelwidthstring 00.00.0000
6799
6800
6801 \series bold
6802 -
6803 \begin_inset ERT
6804 status Collapsed
6805
6806 \layout Standard
6807
6808 \backslash
6809 /
6810 \end_inset
6811
6812 -nojtbound
6813 \begin_inset LatexCommand \index{-\/-nojtbound}
6814
6815 \end_inset
6816
6817
6818 \size large
6819 \bar under
6820
6821 \series default
6822 \size default
6823 \bar default
6824  Will not generate boundary condition check when switch statements
6825 \begin_inset LatexCommand \index{switch statement}
6826
6827 \end_inset
6828
6829  are implemented using jump-tables.
6830  See section
6831 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
6832
6833 \end_inset
6834
6835 \SpecialChar ~
6836 Switch Statements for more details.
6837  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6838 nojtbound
6839 \begin_inset LatexCommand \index{\#pragma nojtbound}
6840
6841 \end_inset
6842
6843  can be used to turn off boundary checking for jump tables for a given function
6844  only.
6845 \layout List
6846 \labelwidthstring 00.00.0000
6847
6848
6849 \series bold
6850 -
6851 \begin_inset ERT
6852 status Collapsed
6853
6854 \layout Standard
6855
6856 \backslash
6857 /
6858 \end_inset
6859
6860 -noloopreverse
6861 \begin_inset LatexCommand \index{-\/-noloopreverse}
6862
6863 \end_inset
6864
6865
6866 \series default
6867 \size large
6868
6869 \size default
6870 Will not do loop reversal
6871 \begin_inset LatexCommand \index{Loop reversing}
6872
6873 \end_inset
6874
6875 optimization.
6876 \layout List
6877 \labelwidthstring 00.00.0000
6878
6879 -
6880 \begin_inset ERT
6881 status Collapsed
6882
6883 \layout Standard
6884
6885 \backslash
6886 /
6887 \end_inset
6888
6889 -
6890 \series bold
6891 nolabelopt
6892 \series default
6893
6894 \begin_inset LatexCommand \index{-\/-nolabelopt }
6895
6896 \end_inset
6897
6898 Will not optimize labels (makes the dumpfiles more readable).
6899 \layout List
6900 \labelwidthstring 00.00.0000
6901
6902
6903 \series bold
6904 -
6905 \begin_inset ERT
6906 status Collapsed
6907
6908 \layout Standard
6909
6910 \backslash
6911 /
6912 \end_inset
6913
6914 -no-xinit-opt
6915 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
6916
6917 \end_inset
6918
6919
6920 \series default
6921  Will not memcpy initialized data from code space into xdata space.
6922  This saves a few bytes in code space if you don't have initialized data
6923 \begin_inset LatexCommand \index{Variable initialization}
6924
6925 \end_inset
6926
6927 .
6928 \layout List
6929 \labelwidthstring 00.00.0000
6930
6931
6932 \series bold
6933 -
6934 \begin_inset ERT
6935 status Collapsed
6936
6937 \layout Standard
6938
6939 \backslash
6940 /
6941 \end_inset
6942
6943 -nooverlay
6944 \begin_inset LatexCommand \index{-\/-nooverlay}
6945
6946 \end_inset
6947
6948
6949 \series default
6950   The compiler will not overlay parameters and local variables of any function,
6951  see section Parameters and local variables for more details.
6952 \layout List
6953 \labelwidthstring 00.00.0000
6954
6955
6956 \series bold
6957 -
6958 \begin_inset ERT
6959 status Collapsed
6960
6961 \layout Standard
6962
6963 \backslash
6964 /
6965 \end_inset
6966
6967 -no-peep
6968 \begin_inset LatexCommand \index{-\/-no-peep}
6969
6970 \end_inset
6971
6972
6973 \series default
6974  Disable peep-hole optimization.
6975 \layout List
6976 \labelwidthstring 00.00.0000
6977
6978
6979 \series bold
6980 -
6981 \begin_inset ERT
6982 status Collapsed
6983
6984 \layout Standard
6985
6986 \backslash
6987 /
6988 \end_inset
6989
6990 -peep-file
6991 \series default
6992
6993 \begin_inset LatexCommand \index{-\/-peep-file}
6994
6995 \end_inset
6996
6997 \SpecialChar ~
6998 <filename> This option can be used to use additional rules to be used by
6999  the peep hole optimizer.
7000  See section
7001 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
7002
7003 \end_inset
7004
7005 \SpecialChar ~
7006 Peep Hole optimizations for details on how to write these rules.
7007 \layout List
7008 \labelwidthstring 00.00.0000
7009
7010
7011 \series bold
7012 -
7013 \begin_inset ERT
7014 status Collapsed
7015
7016 \layout Standard
7017
7018 \backslash
7019 /
7020 \end_inset
7021
7022 -peep-asm
7023 \begin_inset LatexCommand \index{-\/-peep-asm}
7024
7025 \end_inset
7026
7027
7028 \series default
7029  Pass the inline assembler code through the peep hole optimizer.
7030  This can cause unexpected changes to inline assembler code, please go through
7031  the peephole optimizer
7032 \begin_inset LatexCommand \index{Peephole optimizer}
7033
7034 \end_inset
7035
7036  rules defined in the source file tree '<target>/peeph.def' before using
7037  this option.
7038 \layout List
7039 \labelwidthstring 00.00.0000
7040
7041
7042 \series bold
7043 -
7044 \begin_inset ERT
7045 status Collapsed
7046
7047 \layout Standard
7048
7049 \backslash
7050 /
7051 \end_inset
7052
7053 -opt-code-speed
7054 \begin_inset LatexCommand \index{-\/-opt-code-speed}
7055
7056 \end_inset
7057
7058
7059 \series default
7060  The compiler will optimize code generation towards fast code, possibly
7061  at the expense of code size.
7062 \layout List
7063 \labelwidthstring 00.00.0000
7064
7065
7066 \series bold
7067 -
7068 \begin_inset ERT
7069 status Collapsed
7070
7071 \layout Standard
7072
7073 \backslash
7074 /
7075 \end_inset
7076
7077 -opt-code-size
7078 \begin_inset LatexCommand \index{-\/-opt-code-size}
7079
7080 \end_inset
7081
7082
7083 \series default
7084  The compiler will optimize code generation towards compact code, possibly
7085  at the expense of code speed.
7086 \layout Subsection
7087
7088 Other Options
7089 \begin_inset LatexCommand \index{Options other}
7090
7091 \end_inset
7092
7093
7094 \layout List
7095 \labelwidthstring 00.00.0000
7096
7097
7098 \series bold
7099 -c\SpecialChar ~
7100 -
7101 \begin_inset ERT
7102 status Collapsed
7103
7104 \layout Standard
7105
7106 \backslash
7107 /
7108 \end_inset
7109
7110 -compile-only
7111 \begin_inset LatexCommand \index{-\/-compile-only}
7112
7113 \end_inset
7114
7115
7116 \begin_inset LatexCommand \index{-c -\/-compile-only}
7117
7118 \end_inset
7119
7120
7121 \series default
7122  will compile and assemble the source, but will not call the linkage editor.
7123 \layout List
7124 \labelwidthstring 00.00.0000
7125
7126
7127 \series bold
7128 -
7129 \series default
7130
7131 \begin_inset ERT
7132 status Collapsed
7133
7134 \layout Standard
7135
7136 \backslash
7137 /
7138 \end_inset
7139
7140
7141 \series bold
7142 -c1mode
7143 \begin_inset LatexCommand \index{-\/-c1mode}
7144
7145 \end_inset
7146
7147
7148 \series default
7149  reads the preprocessed source from standard input and compiles it.
7150  The file name for the assembler output must be specified using the -o option.
7151 \layout List
7152 \labelwidthstring 00.00.0000
7153
7154
7155 \series bold
7156 -E
7157 \begin_inset LatexCommand \index{-E}
7158
7159 \end_inset
7160
7161
7162 \series default
7163  Run only the C preprocessor.
7164  Preprocess all the C source files specified and output the results to standard
7165  output.
7166 \layout List
7167 \labelwidthstring 00.00.0000
7168
7169
7170 \series bold
7171 -o\SpecialChar ~
7172 <path/file>
7173 \begin_inset LatexCommand \index{-o <path/file>}
7174
7175 \end_inset
7176
7177
7178 \series default
7179 The output path resp.
7180  file where everything will be placed.
7181  If the parameter is a path, it must have a trailing slash (or backslash
7182  for the Windows binaries) to be recognized as a path.
7183
7184 \layout List
7185 \labelwidthstring 00.00.0000
7186
7187
7188 \series bold
7189 -
7190 \begin_inset ERT
7191 status Collapsed
7192
7193 \layout Standard
7194
7195 \backslash
7196 /
7197 \end_inset
7198
7199 -stack-auto
7200 \begin_inset LatexCommand \index{-\/-stack-auto}
7201
7202 \end_inset
7203
7204
7205 \series default
7206 \size large
7207 \emph on
7208
7209 \size default
7210 \emph default
7211 All functions in the source file will be compiled as
7212 \emph on
7213 reentrant
7214 \emph default
7215
7216 \begin_inset LatexCommand \index{reentrant}
7217
7218 \end_inset
7219
7220 , i.e.
7221  the parameters and local variables will be allocated on the stack
7222 \begin_inset LatexCommand \index{stack}
7223
7224 \end_inset
7225
7226 .
7227  See section
7228 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
7229
7230 \end_inset
7231
7232  Parameters and Local Variables for more details.
7233  If this option is used all source files in the project should be compiled
7234  with this option.
7235  It automatically implies --int-long-reent and --float-reent.
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 -callee-saves
7253 \begin_inset LatexCommand \index{-\/-callee-saves}
7254
7255 \end_inset
7256
7257  function1[,function2][,function3]....
7258
7259 \series default
7260  The compiler by default uses a caller saves convention for register saving
7261  across function calls, however this can cause unnecessary register pushing
7262  & popping when calling small functions from larger functions.
7263  This option can be used to switch the register saving convention for the
7264  function names specified.
7265  The compiler will not save registers when calling these functions, no extra
7266  code will be generated at the entry & exit (function prologue
7267 \series bold
7268
7269 \begin_inset LatexCommand \index{function prologue}
7270
7271 \end_inset
7272
7273
7274 \series default
7275  & epilogue
7276 \series bold
7277
7278 \begin_inset LatexCommand \index{function epilogue}
7279
7280 \end_inset
7281
7282
7283 \series default
7284 ) for these functions to save & restore the registers used by these functions,
7285  this can SUBSTANTIALLY reduce code & improve run time performance of the
7286  generated code.
7287  In the future the compiler (with inter procedural analysis) will be able
7288  to determine the appropriate scheme to use for each function call.
7289  DO NOT use this option for built-in functions such as _mulint..., if this
7290  option is used for a library function the appropriate library function
7291  needs to be recompiled with the same option.
7292  If the project consists of multiple source files then all the source file
7293  should be compiled with the same -
7294 \begin_inset ERT
7295 status Collapsed
7296
7297 \layout Standard
7298
7299 \backslash
7300 /
7301 \end_inset
7302
7303 -callee-saves option string.
7304  Also see #pragma\SpecialChar ~
7305 callee_saves
7306 \begin_inset LatexCommand \index{\#pragma callee\_saves}
7307
7308 \end_inset
7309
7310 .
7311 \layout List
7312 \labelwidthstring 00.00.0000
7313
7314
7315 \series bold
7316 -
7317 \begin_inset ERT
7318 status Collapsed
7319
7320 \layout Standard
7321
7322 \backslash
7323 /
7324 \end_inset
7325
7326 -debug
7327 \begin_inset LatexCommand \index{-\/-debug}
7328
7329 \end_inset
7330
7331
7332 \bar under
7333
7334 \series default
7335 \bar default
7336 When this option is used the compiler will generate debug information.
7337  The debug information collected in a file with .cdb extension can be used
7338  with the SDCDB.
7339  For more information see documentation for SDCDB.
7340  Another file with no extension contains debug information in AOMF or AOMF51
7341 \begin_inset LatexCommand \index{AOMF, AOMF51}
7342
7343 \end_inset
7344
7345  format which is commonly used by third party tools.
7346 \layout List
7347 \labelwidthstring 00.00.0000
7348
7349
7350 \series bold
7351 -S
7352 \begin_inset LatexCommand \index{-S}
7353
7354 \end_inset
7355
7356
7357 \size large
7358 \bar under
7359
7360 \series default
7361 \size default
7362 \bar default
7363 Stop after the stage of compilation proper; do not assemble.
7364  The output is an assembler code file for the input file specified.
7365 \layout List
7366 \labelwidthstring 00.00.0000
7367
7368
7369 \series bold
7370 -
7371 \begin_inset ERT
7372 status Collapsed
7373
7374 \layout Standard
7375
7376 \backslash
7377 /
7378 \end_inset
7379
7380 -int-long-reent
7381 \begin_inset LatexCommand \index{-\/-int-long-reent}
7382
7383 \end_inset
7384
7385
7386 \series default
7387  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
7388  Note by default these libraries are compiled as non-reentrant.
7389  See section Installation for more details.
7390 \layout List
7391 \labelwidthstring 00.00.0000
7392
7393
7394 \series bold
7395 -
7396 \begin_inset ERT
7397 status Collapsed
7398
7399 \layout Standard
7400
7401 \backslash
7402 /
7403 \end_inset
7404
7405 -cyclomatic
7406 \begin_inset LatexCommand \index{-\/-cyclomatic}
7407
7408 \end_inset
7409
7410
7411 \bar under
7412
7413 \series default
7414 \bar default
7415 This option will cause the compiler to generate an information message for
7416  each function in the source file.
7417  The message contains some
7418 \emph on
7419 important
7420 \emph default
7421  information about the function.
7422  The number of edges and nodes the compiler detected in the control flow
7423  graph of the function, and most importantly the
7424 \emph on
7425 cyclomatic complexity
7426 \begin_inset LatexCommand \index{Cyclomatic complexity}
7427
7428 \end_inset
7429
7430
7431 \emph default
7432  see section on Cyclomatic Complexity for more details.
7433 \layout List
7434 \labelwidthstring 00.00.0000
7435
7436
7437 \series bold
7438 -
7439 \begin_inset ERT
7440 status Collapsed
7441
7442 \layout Standard
7443
7444 \backslash
7445 /
7446 \end_inset
7447
7448 -float-reent
7449 \begin_inset LatexCommand \index{-\/-float-reent}
7450
7451 \end_inset
7452
7453
7454 \series default
7455  Floating point library is compiled as reentrant
7456 \begin_inset LatexCommand \index{reentrant}
7457
7458 \end_inset
7459
7460 .
7461  See section Installation for more details.
7462 \layout List
7463 \labelwidthstring 00.00.0000
7464
7465
7466 \series bold
7467 -
7468 \begin_inset ERT
7469 status Collapsed
7470
7471 \layout Standard
7472
7473 \backslash
7474 /
7475 \end_inset
7476
7477 -main-return
7478 \begin_inset LatexCommand \index{-\/-main-return}
7479
7480 \end_inset
7481
7482
7483 \series default
7484  This option can be used if the code generated is called by a monitor program
7485  or if the main routine includes an endless loop.
7486  This option might result in slightly smaller code and save two bytes of
7487  stack space.
7488  The return from the 'main'
7489 \begin_inset LatexCommand \index{main return}
7490
7491 \end_inset
7492
7493  function will return to the function calling main.
7494  The default setting is to lock up i.e.
7495  generate a '
7496 \family typewriter
7497 sjmp .
7498 \family default
7499 '.
7500 \layout List
7501 \labelwidthstring 00.00.0000
7502
7503
7504 \series bold
7505 -
7506 \begin_inset ERT
7507 status Collapsed
7508
7509 \layout Standard
7510
7511 \backslash
7512 /
7513 \end_inset
7514
7515 -nostdinc
7516 \begin_inset LatexCommand \index{-\/-nostdinc}
7517
7518 \end_inset
7519
7520
7521 \series default
7522  This will prevent the compiler from passing on the default include path
7523  to the preprocessor.
7524 \layout List
7525 \labelwidthstring 00.00.0000
7526
7527
7528 \series bold
7529 -
7530 \begin_inset ERT
7531 status Collapsed
7532
7533 \layout Standard
7534
7535 \backslash
7536 /
7537 \end_inset
7538
7539 -nostdlib
7540 \begin_inset LatexCommand \index{-\/-nostdlib}
7541
7542 \end_inset
7543
7544
7545 \series default
7546  This will prevent the compiler from passing on the default library
7547 \begin_inset LatexCommand \index{Libraries}
7548
7549 \end_inset
7550
7551  path to the linker.
7552 \layout List
7553 \labelwidthstring 00.00.0000
7554
7555
7556 \series bold
7557 -
7558 \begin_inset ERT
7559 status Collapsed
7560
7561 \layout Standard
7562
7563 \backslash
7564 /
7565 \end_inset
7566
7567 -verbose
7568 \begin_inset LatexCommand \index{-\/-verbose}
7569
7570 \end_inset
7571
7572
7573 \series default
7574  Shows the various actions the compiler is performing.
7575 \layout List
7576 \labelwidthstring 00.00.0000
7577
7578
7579 \series bold
7580 -V
7581 \begin_inset LatexCommand \index{-V}
7582
7583 \end_inset
7584
7585
7586 \series default
7587  Shows the actual commands the compiler is executing.
7588 \layout List
7589 \labelwidthstring 00.00.0000
7590
7591
7592 \series bold
7593 -
7594 \begin_inset ERT
7595 status Collapsed
7596
7597 \layout Standard
7598
7599 \backslash
7600 /
7601 \end_inset
7602
7603 -no-c-code-in-asm
7604 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
7605
7606 \end_inset
7607
7608
7609 \series default
7610  Hides your ugly and inefficient c-code from the asm file, so you can always
7611  blame the compiler :)
7612 \layout List
7613 \labelwidthstring 00.00.0000
7614
7615
7616 \series bold
7617 -
7618 \begin_inset ERT
7619 status Collapsed
7620
7621 \layout Standard
7622
7623 \backslash
7624 /
7625 \end_inset
7626
7627 -no-peep-comments
7628 \begin_inset LatexCommand \index{-\/-no-peep-comments}
7629
7630 \end_inset
7631
7632
7633 \series default
7634  Will not include peep-hole comments in the generated files.
7635 \layout List
7636 \labelwidthstring 00.00.0000
7637
7638
7639 \series bold
7640 -
7641 \begin_inset ERT
7642 status Collapsed
7643
7644 \layout Standard
7645
7646 \backslash
7647 /
7648 \end_inset
7649
7650 -i-code-in-asm
7651 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
7652
7653 \end_inset
7654
7655
7656 \series default
7657  Include i-codes in the asm file.
7658  Sounds like noise but is most helpful for debugging the compiler itself.
7659 \layout List
7660 \labelwidthstring 00.00.0000
7661
7662
7663 \series bold
7664 -
7665 \begin_inset ERT
7666 status Collapsed
7667
7668 \layout Standard
7669
7670 \backslash
7671 /
7672 \end_inset
7673
7674 -less-pedantic
7675 \begin_inset LatexCommand \index{-\/-less-pedantic}
7676
7677 \end_inset
7678
7679
7680 \series default
7681  Disable some of the more pedantic warnings
7682 \begin_inset LatexCommand \index{Warnings}
7683
7684 \end_inset
7685
7686  (jwk burps: please be more specific here, please!).
7687 \layout List
7688 \labelwidthstring 00.00.0000
7689
7690
7691 \series bold
7692 -
7693 \begin_inset ERT
7694 status Collapsed
7695
7696 \layout Standard
7697
7698 \backslash
7699 /
7700 \end_inset
7701
7702 -disable-warning\SpecialChar ~
7703 <nnnn>
7704 \begin_inset LatexCommand \index{-\/-disable-warning}
7705
7706 \end_inset
7707
7708
7709 \series default
7710  Disable specific warning with number <nnnn>.
7711 \layout List
7712 \labelwidthstring 00.00.0000
7713
7714
7715 \series bold
7716 -
7717 \begin_inset ERT
7718 status Collapsed
7719
7720 \layout Standard
7721
7722 \backslash
7723 /
7724 \end_inset
7725
7726 -print-search-dirs
7727 \begin_inset LatexCommand \index{-\/-print-search-dirs}
7728
7729 \end_inset
7730
7731
7732 \series default
7733  Display the directories in the compiler's search path
7734 \layout List
7735 \labelwidthstring 00.00.0000
7736
7737
7738 \series bold
7739 -
7740 \begin_inset ERT
7741 status Collapsed
7742
7743 \layout Standard
7744
7745 \backslash
7746 /
7747 \end_inset
7748
7749 -vc
7750 \begin_inset LatexCommand \index{-\/-vc}
7751
7752 \end_inset
7753
7754
7755 \series default
7756  Display errors and warnings using MSVC style, so you can use SDCC with
7757  visual studio.
7758 \layout List
7759 \labelwidthstring 00.00.0000
7760
7761
7762 \series bold
7763 -
7764 \begin_inset ERT
7765 status Collapsed
7766
7767 \layout Standard
7768
7769 \backslash
7770 /
7771 \end_inset
7772
7773 -use-stdout
7774 \begin_inset LatexCommand \index{-\/-use-stdout}
7775
7776 \end_inset
7777
7778
7779 \series default
7780  Send errors and warnings to stdout instead of stderr.
7781 \layout List
7782 \labelwidthstring 00.00.0000
7783
7784
7785 \series bold
7786 -Wa\SpecialChar ~
7787 asmOption[,asmOption]
7788 \series default
7789
7790 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
7791
7792 \end_inset
7793
7794 ...
7795  Pass the asmOption to the assembler
7796 \begin_inset LatexCommand \index{Options assembler}
7797
7798 \end_inset
7799
7800
7801 \begin_inset LatexCommand \index{Assembler options}
7802
7803 \end_inset
7804
7805 .
7806  See file sdcc/as/doc/asxhtm.html for assembler options.cd
7807 \layout List
7808 \labelwidthstring 00.00.0000
7809
7810
7811 \series bold
7812 -
7813 \begin_inset ERT
7814 status Collapsed
7815
7816 \layout Standard
7817
7818 \backslash
7819 /
7820 \end_inset
7821
7822 -std-sdcc89
7823 \begin_inset LatexCommand \index{-\/-std-sdcc89}
7824
7825 \end_inset
7826
7827
7828 \series default
7829  Generally follow the C89 standard, but allow SDCC features that conflict
7830  with the standard (default).
7831 \layout List
7832 \labelwidthstring 00.00.0000
7833
7834
7835 \series bold
7836 -
7837 \begin_inset ERT
7838 status Collapsed
7839
7840 \layout Standard
7841
7842 \backslash
7843 /
7844 \end_inset
7845
7846 -std-c89
7847 \begin_inset LatexCommand \index{-\/-std-c89}
7848
7849 \end_inset
7850
7851
7852 \series default
7853  Follow the C89 standard and disable SDCC features that conflict with the
7854  standard.
7855 \layout List
7856 \labelwidthstring 00.00.0000
7857
7858
7859 \series bold
7860 -
7861 \begin_inset ERT
7862 status Collapsed
7863
7864 \layout Standard
7865
7866 \backslash
7867 /
7868 \end_inset
7869
7870 -std-sdcc99
7871 \begin_inset LatexCommand \index{-\/-std-sdcc99}
7872
7873 \end_inset
7874
7875
7876 \series default
7877  Generally follow the C99 standard, but allow SDCC features that conflict
7878  with the standard (incomplete support).
7879 \layout List
7880 \labelwidthstring 00.00.0000
7881
7882
7883 \series bold
7884 -
7885 \begin_inset ERT
7886 status Collapsed
7887
7888 \layout Standard
7889
7890 \backslash
7891 /
7892 \end_inset
7893
7894 -std-c99
7895 \begin_inset LatexCommand \index{-\/-std-sdcc99}
7896
7897 \end_inset
7898
7899
7900 \series default
7901  Follow the C99 standard and disable SDCC features that conflict with the
7902  standard (incomplete support).
7903 \layout List
7904 \labelwidthstring 00.00.0000
7905
7906
7907 \series bold
7908 -
7909 \begin_inset ERT
7910 status Collapsed
7911
7912 \layout Standard
7913
7914 \backslash
7915 /
7916 \end_inset
7917
7918 -codeseg
7919 \series default
7920
7921 \begin_inset LatexCommand \index{-\/-codeseg <Value>}
7922
7923 \end_inset
7924
7925 \SpecialChar ~
7926 <Name> The name to be used for the code
7927 \begin_inset LatexCommand \index{code}
7928
7929 \end_inset
7930
7931  segment, default CSEG.
7932  This is useful if you need to tell the compiler to put the code in a special
7933  segment so you can later on tell the linker to put this segment in a special
7934  place in memory.
7935  Can be used for instance when using bank switching to put the code in a
7936  bank.
7937 \layout List
7938 \labelwidthstring 00.00.0000
7939
7940
7941 \series bold
7942 -
7943 \begin_inset ERT
7944 status Collapsed
7945
7946 \layout Standard
7947
7948 \backslash
7949 /
7950 \end_inset
7951
7952 -constseg
7953 \series default
7954
7955 \begin_inset LatexCommand \index{-\/-constseg <Value>}
7956
7957 \end_inset
7958
7959 \SpecialChar ~
7960 <Name> The name to be used for the const
7961 \begin_inset LatexCommand \index{code}
7962
7963 \end_inset
7964
7965  segment, default CONST.
7966  This is useful if you need to tell the compiler to put the const data in
7967  a special segment so you can later on tell the linker to put this segment
7968  in a special place in memory.
7969  Can be used for instance when using bank switching to put the const data
7970  in a bank.
7971 \layout List
7972 \labelwidthstring 00.00.0000
7973
7974
7975 \series bold
7976 more-pedantic
7977 \series default
7978  Actually this is
7979 \series bold
7980 \emph on
7981 not
7982 \series default
7983 \emph default
7984  a SDCC compiler option but if you want
7985 \emph on
7986 more
7987 \emph default
7988  warnings you can use a separate tool dedicated to syntax checking like
7989  splint
7990 \begin_inset LatexCommand \label{lyx:more-pedantic-SPLINT}
7991
7992 \end_inset
7993
7994
7995 \begin_inset LatexCommand \index{lint (syntax checking tool)}
7996
7997 \end_inset
7998
7999
8000 \begin_inset LatexCommand \url{http://www.splint.org}
8001
8002 \end_inset
8003
8004 .
8005  To make your source files parseable by splint you will have to include
8006
8007 \family sans
8008 lint.h
8009 \family default
8010
8011 \begin_inset LatexCommand \index{splint (syntax checking tool)}
8012
8013 \end_inset
8014
8015  in your source file and add brackets around extended keywords (like
8016 \family sans
8017
8018 \begin_inset Quotes sld
8019 \end_inset
8020
8021 __at\SpecialChar ~
8022
8023 \series bold
8024 (
8025 \series default
8026 0xab
8027 \series bold
8028 )
8029 \series default
8030
8031 \begin_inset Quotes srd
8032 \end_inset
8033
8034
8035 \family default
8036  and
8037 \family sans
8038
8039 \begin_inset Quotes sld
8040 \end_inset
8041
8042 __interrupt\SpecialChar ~
8043 (2)
8044 \begin_inset Quotes srd
8045 \end_inset
8046
8047
8048 \family default
8049 ).
8050
8051 \newline
8052 Splint has an excellent on line manual at
8053 \begin_inset LatexCommand \url{http://www.splint.org/manual/}
8054
8055 \end_inset
8056
8057  and it's capabilities go beyond pure syntax checking.
8058  You'll need to tell splint the location of SDCC's include files so a typical
8059  command line could look like this:
8060 \newline
8061
8062 \family sans
8063 splint\SpecialChar ~
8064 -I\SpecialChar ~
8065 /usr/local/share/sdcc/include/mcs51/\SpecialChar ~
8066 \SpecialChar ~
8067 myprogram.c
8068 \layout Subsection
8069
8070 Intermediate Dump Options
8071 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
8072
8073 \end_inset
8074
8075
8076 \begin_inset LatexCommand \index{Options intermediate dump}
8077
8078 \end_inset
8079
8080
8081 \begin_inset LatexCommand \index{Intermediate dump options}
8082
8083 \end_inset
8084
8085
8086 \layout Standard
8087
8088 The following options are provided for the purpose of retargetting and debugging
8089  the compiler.
8090  They provide a means to dump the intermediate code (iCode
8091 \begin_inset LatexCommand \index{iCode}
8092
8093 \end_inset
8094
8095 ) generated by the compiler in human readable form at various stages of
8096  the compilation process.
8097  More on iCodes see chapter
8098 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
8099
8100 \end_inset
8101
8102
8103 \begin_inset Quotes srd
8104 \end_inset
8105
8106 The anatomy of the compiler
8107 \begin_inset Quotes srd
8108 \end_inset
8109
8110 .
8111 \layout List
8112 \labelwidthstring 00.00.0000
8113
8114
8115 \series bold
8116 -
8117 \begin_inset ERT
8118 status Collapsed
8119
8120 \layout Standard
8121
8122 \backslash
8123 /
8124 \end_inset
8125
8126 -dumpraw
8127 \begin_inset LatexCommand \index{-\/-dumpraw}
8128
8129 \end_inset
8130
8131
8132 \series default
8133  This option will cause the compiler to dump the intermediate code into
8134  a file of named
8135 \emph on
8136 <source filename>.dumpraw
8137 \emph default
8138  just after the intermediate code has been generated for a function, i.e.
8139  before any optimizations are done.
8140  The basic blocks
8141 \begin_inset LatexCommand \index{Basic blocks}
8142
8143 \end_inset
8144
8145  at this stage ordered in the depth first number, so they may not be in
8146  sequence of execution.
8147 \layout List
8148 \labelwidthstring 00.00.0000
8149
8150
8151 \series bold
8152 -
8153 \begin_inset ERT
8154 status Collapsed
8155
8156 \layout Standard
8157
8158 \backslash
8159 /
8160 \end_inset
8161
8162 -dumpgcse
8163 \begin_inset LatexCommand \index{-\/-dumpgcse}
8164
8165 \end_inset
8166
8167
8168 \series default
8169  Will create a dump of iCode's, after global subexpression elimination
8170 \begin_inset LatexCommand \index{Global subexpression elimination}
8171
8172 \end_inset
8173
8174 , into a file named
8175 \emph on
8176 <source filename>.dumpgcse.
8177 \layout List
8178 \labelwidthstring 00.00.0000
8179
8180
8181 \series bold
8182 -
8183 \begin_inset ERT
8184 status Collapsed
8185
8186 \layout Standard
8187
8188 \backslash
8189 /
8190 \end_inset
8191
8192 -dumpdeadcode
8193 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
8194
8195 \end_inset
8196
8197
8198 \series default
8199  Will create a dump of iCode's, after deadcode elimination
8200 \begin_inset LatexCommand \index{Dead-code elimination}
8201
8202 \end_inset
8203
8204 , into a file named
8205 \emph on
8206 <source filename>.dumpdeadcode.
8207 \layout List
8208 \labelwidthstring 00.00.0000
8209
8210
8211 \series bold
8212 -
8213 \begin_inset ERT
8214 status Collapsed
8215
8216 \layout Standard
8217
8218 \backslash
8219 /
8220 \end_inset
8221
8222 -dumploop
8223 \begin_inset LatexCommand \index{-\/-dumploop}
8224
8225 \end_inset
8226
8227
8228 \series default
8229 \size large
8230
8231 \size default
8232 Will create a dump of iCode's, after loop optimizations
8233 \begin_inset LatexCommand \index{Loop optimization}
8234
8235 \end_inset
8236
8237 , into a file named
8238 \emph on
8239 <source filename>.dumploop.
8240 \layout List
8241 \labelwidthstring 00.00.0000
8242
8243
8244 \series bold
8245 -
8246 \begin_inset ERT
8247 status Collapsed
8248
8249 \layout Standard
8250
8251 \backslash
8252 /
8253 \end_inset
8254
8255 -dumprange
8256 \begin_inset LatexCommand \index{-\/-dumprange}
8257
8258 \end_inset
8259
8260
8261 \series default
8262 \size large
8263
8264 \size default
8265 Will create a dump of iCode's, after live range analysis
8266 \begin_inset LatexCommand \index{Live range analysis}
8267
8268 \end_inset
8269
8270 , into a file named
8271 \emph on
8272 <source filename>.dumprange.
8273 \layout List
8274 \labelwidthstring 00.00.0000
8275
8276
8277 \series bold
8278 -
8279 \begin_inset ERT
8280 status Collapsed
8281
8282 \layout Standard
8283
8284 \backslash
8285 /
8286 \end_inset
8287
8288 -dumlrange
8289 \begin_inset LatexCommand \index{-\/-dumlrange}
8290
8291 \end_inset
8292
8293
8294 \series default
8295  Will dump the life ranges
8296 \begin_inset LatexCommand \index{Live range analysis}
8297
8298 \end_inset
8299
8300  for all symbols.
8301 \layout List
8302 \labelwidthstring 00.00.0000
8303
8304
8305 \series bold
8306 -
8307 \begin_inset ERT
8308 status Collapsed
8309
8310 \layout Standard
8311
8312 \backslash
8313 /
8314 \end_inset
8315
8316 -dumpregassign
8317 \begin_inset LatexCommand \index{-\/-dumpregassign}
8318
8319 \end_inset
8320
8321
8322 \bar under
8323
8324 \series default
8325 \bar default
8326 Will create a dump of iCode's, after register assignment
8327 \begin_inset LatexCommand \index{Register assignment}
8328
8329 \end_inset
8330
8331 , into a file named
8332 \emph on
8333 <source filename>.dumprassgn.
8334 \layout List
8335 \labelwidthstring 00.00.0000
8336
8337
8338 \series bold
8339 -
8340 \begin_inset ERT
8341 status Collapsed
8342
8343 \layout Standard
8344
8345 \backslash
8346 /
8347 \end_inset
8348
8349 -dumplrange
8350 \begin_inset LatexCommand \index{-\/-dumplrange}
8351
8352 \end_inset
8353
8354
8355 \series default
8356  Will create a dump of the live ranges of iTemp's
8357 \layout List
8358 \labelwidthstring 00.00.0000
8359
8360
8361 \series bold
8362 -
8363 \begin_inset ERT
8364 status Collapsed
8365
8366 \layout Standard
8367
8368 \backslash
8369 /
8370 \end_inset
8371
8372 -dumpall
8373 \begin_inset LatexCommand \index{-\/-dumpall}
8374
8375 \end_inset
8376
8377
8378 \size large
8379 \bar under
8380
8381 \series default
8382 \size default
8383 \bar default
8384 Will cause all the above mentioned dumps to be created.
8385 \layout Subsection
8386
8387 Redirecting output on Windows Shells
8388 \layout Standard
8389
8390 By default SDCC writes it's error messages to
8391 \begin_inset Quotes sld
8392 \end_inset
8393
8394 standard error
8395 \begin_inset Quotes srd
8396 \end_inset
8397
8398 .
8399  To force all messages to
8400 \begin_inset Quotes sld
8401 \end_inset
8402
8403 standard output
8404 \begin_inset Quotes srd
8405 \end_inset
8406
8407  use
8408 \series bold
8409 -
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 -
8426 \series default
8427 use-stdout
8428 \begin_inset LatexCommand \index{-\/-use-stdout}
8429
8430 \end_inset
8431
8432 .
8433  Additionally, if you happen to have visual studio installed in your windows
8434  machine, you can use it to compile your sources using a custom build and
8435  the SDCC -
8436 \emph on
8437
8438 \begin_inset ERT
8439 status Collapsed
8440
8441 \layout Standard
8442
8443 \backslash
8444 /
8445 \end_inset
8446
8447
8448 \emph default
8449 -vc
8450 \begin_inset LatexCommand \index{-\/-vc}
8451
8452 \end_inset
8453
8454  option.
8455  Something like this should work:
8456 \newline
8457
8458 \newline
8459
8460 \series bold
8461 c:
8462 \backslash
8463 sdcc
8464 \backslash
8465 bin
8466 \backslash
8467 sdcc.exe -
8468 \series default
8469 \emph on
8470
8471 \begin_inset ERT
8472 status Collapsed
8473
8474 \layout Standard
8475
8476 \backslash
8477 /
8478 \end_inset
8479
8480
8481 \series bold
8482 \emph default
8483 -vc -
8484 \series default
8485 \emph on
8486
8487 \begin_inset ERT
8488 status Collapsed
8489
8490 \layout Standard
8491
8492 \backslash
8493 /
8494 \end_inset
8495
8496
8497 \series bold
8498 \emph default
8499 -model-large -c $(InputPath)
8500 \layout Section
8501
8502 Environment variables
8503 \begin_inset LatexCommand \index{Environment variables}
8504
8505 \end_inset
8506
8507
8508 \layout Standard
8509
8510 SDCC recognizes the following environment variables:
8511 \layout List
8512 \labelwidthstring 00.00.0000
8513
8514
8515 \series bold
8516 SDCC_LEAVE_SIGNALS
8517 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
8518
8519 \end_inset
8520
8521
8522 \series default
8523  SDCC installs a signal handler
8524 \begin_inset LatexCommand \index{signal handler}
8525
8526 \end_inset
8527
8528  to be able to delete temporary files after an user break (^C) or an exception.
8529  If this environment variable is set, SDCC won't install the signal handler
8530  in order to be able to debug SDCC.
8531 \layout List
8532 \labelwidthstring 00.00.0000
8533
8534
8535 \series bold
8536 TMP,\SpecialChar ~
8537 TEMP,\SpecialChar ~
8538 TMPDIR
8539 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
8540
8541 \end_inset
8542
8543
8544 \series default
8545  Path, where temporary files will be created.
8546  The order of the variables is the search order.
8547  In a standard *nix environment these variables are not set, and there's
8548  no need to set them.
8549  On Windows it's recommended to set one of them.
8550 \layout List
8551 \labelwidthstring 00.00.0000
8552
8553
8554 \series bold
8555 SDCC_HOME
8556 \begin_inset LatexCommand \index{SDCC\_HOME}
8557
8558 \end_inset
8559
8560
8561 \series default
8562  Path, see section
8563 \begin_inset LatexCommand \ref{sub:Install-paths}
8564
8565 \end_inset
8566
8567 \SpecialChar ~
8568
8569 \begin_inset Quotes sld
8570 \end_inset
8571
8572  Install Paths
8573 \begin_inset Quotes srd
8574 \end_inset
8575
8576 .
8577 \layout List
8578 \labelwidthstring 00.00.0000
8579
8580
8581 \series bold
8582 SDCC_INCLUDE
8583 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
8584
8585 \end_inset
8586
8587
8588 \series default
8589  Path, see section
8590 \begin_inset LatexCommand \ref{sub:Search-Paths}
8591
8592 \end_inset
8593
8594 \SpecialChar ~
8595
8596 \begin_inset Quotes sld
8597 \end_inset
8598
8599 Search Paths
8600 \begin_inset Quotes srd
8601 \end_inset
8602
8603 .
8604 \layout List
8605 \labelwidthstring 00.00.0000
8606
8607
8608 \series bold
8609 SDCC_LIB
8610 \begin_inset LatexCommand \index{SDCC\_LIB}
8611
8612 \end_inset
8613
8614
8615 \series default
8616  Path, see section
8617 \begin_inset LatexCommand \ref{sub:Search-Paths}
8618
8619 \end_inset
8620
8621 \SpecialChar ~
8622
8623 \begin_inset Quotes sld
8624 \end_inset
8625
8626 Search Paths
8627 \begin_inset Quotes srd
8628 \end_inset
8629
8630 ..
8631 \layout Standard
8632
8633 There are some more environment variables recognized by SDCC, but these
8634  are solely used for debugging purposes.
8635  They can change or disappear very quickly, and will never be documented.
8636 \layout Section
8637
8638 Storage Class Language Extensions
8639 \layout Subsection
8640
8641 MCS51/DS390 Storage Class
8642 \begin_inset LatexCommand \index{Storage class}
8643
8644 \end_inset
8645
8646  Language Extensions
8647 \layout Standard
8648
8649 In addition to the ANSI storage classes SDCC allows the following MCS51
8650  specific storage classes:
8651 \layout Subsubsection
8652
8653 data
8654 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
8655
8656 \end_inset
8657
8658
8659 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
8660
8661 \end_inset
8662
8663  / near
8664 \begin_inset LatexCommand \index{near (storage class)}
8665
8666 \end_inset
8667
8668
8669 \begin_inset LatexCommand \index{\_\_near (storage class)}
8670
8671 \end_inset
8672
8673
8674 \layout Standard
8675
8676 This is the
8677 \series bold
8678 default
8679 \series default
8680  storage class for the Small Memory model (
8681 \emph on
8682 data
8683 \emph default
8684  and
8685 \emph on
8686 near
8687 \emph default
8688  can be used synonymously).
8689  Variables declared with this storage class will be allocated in the directly
8690  addressable portion of the internal RAM of a 8051, e.g.:
8691 \layout Verse
8692
8693
8694 \family typewriter
8695 data unsigned char test_data;
8696 \layout Standard
8697
8698 Writing 0x01 to this variable generates the assembly code:
8699 \layout Verse
8700
8701
8702 \family typewriter
8703 75*00 01\SpecialChar ~
8704 \SpecialChar ~
8705 \SpecialChar ~
8706 mov\SpecialChar ~
8707 \SpecialChar ~
8708 _test_data,#0x01
8709 \layout Subsubsection
8710
8711 xdata
8712 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8713
8714 \end_inset
8715
8716
8717 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
8718
8719 \end_inset
8720
8721  / far
8722 \begin_inset LatexCommand \index{far (storage class)}
8723
8724 \end_inset
8725
8726
8727 \begin_inset LatexCommand \index{\_\_far (storage class)}
8728
8729 \end_inset
8730
8731
8732 \layout Standard
8733
8734 Variables declared with this storage class will be placed in the external
8735  RAM.
8736  This is the
8737 \series bold
8738 default
8739 \series default
8740  storage class for the Large Memory model, e.g.:
8741 \layout Verse
8742
8743
8744 \family typewriter
8745 xdata unsigned char test_xdata;
8746 \layout Standard
8747
8748 Writing 0x01 to this variable generates the assembly code:
8749 \layout Verse
8750
8751
8752 \family typewriter
8753 90s00r00\SpecialChar ~
8754 \SpecialChar ~
8755 \SpecialChar ~
8756 mov\SpecialChar ~
8757 \SpecialChar ~
8758 dptr,#_test_xdata
8759 \newline
8760 74\SpecialChar ~
8761 01\SpecialChar ~
8762 \SpecialChar ~
8763 \SpecialChar ~
8764 \SpecialChar ~
8765 \SpecialChar ~
8766 \SpecialChar ~
8767 mov\SpecialChar ~
8768 \SpecialChar ~
8769 a,#0x01
8770 \newline
8771 F0\SpecialChar ~
8772 \SpecialChar ~
8773 \SpecialChar ~
8774 \SpecialChar ~
8775 \SpecialChar ~
8776 \SpecialChar ~
8777 \SpecialChar ~
8778 \SpecialChar ~
8779 \SpecialChar ~
8780 movx\SpecialChar ~
8781 @dptr,a
8782 \layout Subsubsection
8783
8784 idata
8785 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
8786
8787 \end_inset
8788
8789
8790 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
8791
8792 \end_inset
8793
8794
8795 \layout Standard
8796
8797 Variables declared with this storage class will be allocated into the indirectly
8798  addressable portion of the internal ram of a 8051, e.g.:
8799 \layout Verse
8800
8801
8802 \family typewriter
8803 idata unsigned char test_idata;
8804 \layout Standard
8805
8806 Writing 0x01 to this variable generates the assembly code:
8807 \layout Verse
8808
8809
8810 \family typewriter
8811 78r00\SpecialChar ~
8812 \SpecialChar ~
8813 \SpecialChar ~
8814 \SpecialChar ~
8815 \SpecialChar ~
8816 \SpecialChar ~
8817 \SpecialChar ~
8818 mov\SpecialChar ~
8819 \SpecialChar ~
8820 r0,#_test_idata
8821 \newline
8822 76\SpecialChar ~
8823 01\SpecialChar ~
8824 \SpecialChar ~
8825 \SpecialChar ~
8826 \SpecialChar ~
8827 \SpecialChar ~
8828 \SpecialChar ~
8829 \SpecialChar ~
8830 mov\SpecialChar ~
8831 \SpecialChar ~
8832 @r0,#0x01
8833 \layout Standard
8834
8835 Please note, the first 128 byte of idata physically access the same RAM
8836  as the data memory.
8837  The original 8051 had 128 byte idata memory, nowadays most devices have
8838  256 byte idata memory.
8839  The stack
8840 \begin_inset LatexCommand \index{stack}
8841
8842 \end_inset
8843
8844  is located in idata memory.
8845 \layout Subsubsection
8846
8847 pdata
8848 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
8849
8850 \end_inset
8851
8852
8853 \begin_inset LatexCommand \index{\_\_pdata (mcs51, ds390 storage class)}
8854
8855 \end_inset
8856
8857
8858 \layout Standard
8859
8860 Paged xdata access is just as straightforward as using the other addressing
8861  modes of a 8051.
8862  It is typically located at the start of xdata and has a maximum size of
8863  256 bytes.
8864  The following example writes 0x01 to the pdata variable.
8865  Please note, pdata access physically accesses xdata memory.
8866  The high byte of the address is determined by port P2
8867 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
8868
8869 \end_inset
8870
8871 (or in case of some 8051 variants by a separate Special Function Register,
8872  see section
8873 \begin_inset LatexCommand \ref{sub:MCS51-variants}
8874
8875 \end_inset
8876
8877 ).
8878  This is the
8879 \series bold
8880 default
8881 \series default
8882  storage class for the Medium Memory model, e.g.:
8883 \layout Verse
8884
8885
8886 \family typewriter
8887 pdata unsigned char test_pdata;
8888 \layout Standard
8889
8890 Writing 0x01 to this variable generates the assembly code:
8891 \layout Verse
8892
8893
8894 \family typewriter
8895 78r00\SpecialChar ~
8896 \SpecialChar ~
8897 \SpecialChar ~
8898 \SpecialChar ~
8899 \SpecialChar ~
8900 \SpecialChar ~
8901 mov r0,#_test_pdata
8902 \newline
8903 74 01\SpecialChar ~
8904 \SpecialChar ~
8905 \SpecialChar ~
8906 \SpecialChar ~
8907 \SpecialChar ~
8908 \SpecialChar ~
8909 mov a,#0x01
8910 \newline
8911 F2\SpecialChar ~
8912 \SpecialChar ~
8913 \SpecialChar ~
8914 \SpecialChar ~
8915 \SpecialChar ~
8916 \SpecialChar ~
8917 \SpecialChar ~
8918 \SpecialChar ~
8919 \SpecialChar ~
8920 movx @r0,a
8921 \layout Standard
8922
8923 If the -
8924 \begin_inset ERT
8925 status Collapsed
8926
8927 \layout Standard
8928
8929 \backslash
8930 /
8931 \end_inset
8932
8933 -xstack
8934 \begin_inset LatexCommand \index{-\/-xstack}
8935
8936 \end_inset
8937
8938  option is used the pdata memory area is followed by the xstack memory area
8939  and the sum of their sizes is limited to 256 bytes.
8940 \layout Subsubsection
8941
8942 code
8943 \begin_inset LatexCommand \index{code}
8944
8945 \end_inset
8946
8947
8948 \begin_inset LatexCommand \index{\_\_code}
8949
8950 \end_inset
8951
8952
8953 \layout Standard
8954
8955 'Variables' declared with this storage class will be placed in the code
8956  memory:
8957 \layout Verse
8958
8959
8960 \family typewriter
8961 code unsigned char test_code;
8962 \layout Standard
8963
8964 Read access to this variable generates the assembly code:
8965 \layout Verse
8966
8967
8968 \family typewriter
8969 90s00r6F\SpecialChar ~
8970 \SpecialChar ~
8971 \SpecialChar ~
8972 mov dptr,#_test_code
8973 \newline
8974 E4\SpecialChar ~
8975 \SpecialChar ~
8976 \SpecialChar ~
8977 \SpecialChar ~
8978 \SpecialChar ~
8979 \SpecialChar ~
8980 \SpecialChar ~
8981 \SpecialChar ~
8982 \SpecialChar ~
8983 clr a
8984 \newline
8985 93\SpecialChar ~
8986 \SpecialChar ~
8987 \SpecialChar ~
8988 \SpecialChar ~
8989 \SpecialChar ~
8990 \SpecialChar ~
8991 \SpecialChar ~
8992 \SpecialChar ~
8993 \SpecialChar ~
8994 movc a,@a+dptr
8995 \layout Standard
8996
8997
8998 \family typewriter
8999 char
9000 \family default
9001  indexed arrays of characters in code memory can be accessed efficiently:
9002 \layout Verse
9003
9004
9005 \family typewriter
9006 code char test_array[] = {'c','h','e','a','p'};
9007 \layout Standard
9008
9009 Read access to this array using an 8-bit unsigned index generates the assembly
9010  code:
9011 \layout Verse
9012
9013
9014 \family typewriter
9015 E5*00\SpecialChar ~
9016 \SpecialChar ~
9017 \SpecialChar ~
9018 \SpecialChar ~
9019 \SpecialChar ~
9020 \SpecialChar ~
9021 mov a,_index
9022 \layout Verse
9023
9024
9025 \family typewriter
9026 90s00r41\SpecialChar ~
9027 \SpecialChar ~
9028 \SpecialChar ~
9029 mov dptr,#_test_array
9030 \layout Verse
9031
9032
9033 \family typewriter
9034 93\SpecialChar ~
9035 \SpecialChar ~
9036 \SpecialChar ~
9037 \SpecialChar ~
9038 \SpecialChar ~
9039 \SpecialChar ~
9040 \SpecialChar ~
9041 \SpecialChar ~
9042 \SpecialChar ~
9043 movc a,@a+dptr
9044 \layout Subsubsection
9045
9046 bit
9047 \begin_inset LatexCommand \index{bit}
9048
9049 \end_inset
9050
9051
9052 \begin_inset LatexCommand \index{\_\_bit}
9053
9054 \end_inset
9055
9056
9057 \layout Standard
9058
9059 This is a data-type and a storage class specifier.
9060  When a variable is declared as a bit, it is allocated into the bit addressable
9061  memory of 8051, e.g.:
9062 \layout Verse
9063
9064
9065 \family typewriter
9066 bit test_bit;
9067 \layout Standard
9068
9069 Writing 1 to this variable generates the assembly code:
9070 \layout Verse
9071
9072
9073 \family typewriter
9074 D2*00\SpecialChar ~
9075 \SpecialChar ~
9076 \SpecialChar ~
9077 \SpecialChar ~
9078 \SpecialChar ~
9079 \SpecialChar ~
9080 \SpecialChar ~
9081 setb\SpecialChar ~
9082 _test_bit
9083 \layout Standard
9084
9085 The bit addressable memory consists of 128 bits which are located from 0x20
9086  to 0x2f in data memory.
9087
9088 \newline
9089 Apart from this 8051 specific storage class most architectures support ANSI-C
9090  bitfields
9091 \begin_inset LatexCommand \index{bitfields}
9092
9093 \end_inset
9094
9095
9096 \begin_inset Foot
9097 collapsed false
9098
9099 \layout Standard
9100
9101 Not really meant as examples, but nevertheless showing what bitfields are
9102  about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
9103 \end_inset
9104
9105 .
9106  In accordance with ISO/IEC 9899 bits and bitfields without an explicit
9107  signed modifier are implemented as unsigned.
9108 \layout Subsubsection
9109
9110 sfr
9111 \begin_inset LatexCommand \index{sfr}
9112
9113 \end_inset
9114
9115
9116 \begin_inset LatexCommand \index{\_\_sfr}
9117
9118 \end_inset
9119
9120  / sfr16
9121 \begin_inset LatexCommand \index{sfr16}
9122
9123 \end_inset
9124
9125
9126 \begin_inset LatexCommand \index{\_\_sfr16}
9127
9128 \end_inset
9129
9130  / sfr32
9131 \begin_inset LatexCommand \index{sfr32}
9132
9133 \end_inset
9134
9135
9136 \begin_inset LatexCommand \index{\_\_sfr32}
9137
9138 \end_inset
9139
9140  / sbit
9141 \begin_inset LatexCommand \index{\_\_sbit}
9142
9143 \end_inset
9144
9145
9146 \layout Standard
9147
9148 Like the bit keyword,
9149 \emph on
9150 sfr / sfr16 / sfr32 / sbit
9151 \emph default
9152 signify both a data-type and storage class, they are used to describe the
9153
9154 \emph on
9155 s
9156 \emph default
9157 pecial
9158 \emph on
9159 f
9160 \emph default
9161 unction
9162 \emph on
9163 r
9164 \emph default
9165 egisters and
9166 \emph on
9167 s
9168 \emph default
9169 pecial
9170 \emph on
9171 bit
9172 \emph default
9173  variables of a 8051, eg:
9174 \layout Verse
9175
9176
9177 \family typewriter
9178 sfr at
9179 \begin_inset LatexCommand \index{at}
9180
9181 \end_inset
9182
9183
9184 \begin_inset LatexCommand \index{\_\_at}
9185
9186 \end_inset
9187
9188  0x80 P0;\SpecialChar ~
9189  /* special function register P0 at location 0x80 */
9190 \newline
9191 /* 16 bit special function register combination for timer 0 */
9192 \newline
9193 /* with the high byte at location 0x8C and the low byte at location 0x8A
9194  */
9195 \newline
9196 sfr16 at
9197 \begin_inset LatexCommand \index{at}
9198
9199 \end_inset
9200
9201
9202 \begin_inset LatexCommand \index{\_\_at}
9203
9204 \end_inset
9205
9206  0x8C8A TMR0;
9207 \newline
9208 sbit at 0xd7 CY; /* CY (Carry Flag
9209 \begin_inset LatexCommand \index{Flags}
9210
9211 \end_inset
9212
9213
9214 \begin_inset LatexCommand \index{Carry flag}
9215
9216 \end_inset
9217
9218 ) */
9219 \layout Standard
9220
9221 Special function registers which are located on an address dividable by
9222  8 are bit-addressable, an
9223 \emph on
9224  sbit
9225 \emph default
9226  addresses a specific bit within these sfr.
9227 \newline
9228 16 Bit and 32 bit special function register combinations which require a
9229  certain access order are better not declared using
9230 \emph on
9231 sfr16
9232 \emph default
9233  or
9234 \emph on
9235 sfr32.
9236
9237 \emph default
9238  Allthough SDCC usually accesses them Least Significant Byte (LSB) first,
9239  this is not guaranteed.
9240 \layout Subsubsection
9241
9242 Pointers
9243 \begin_inset LatexCommand \index{Pointer}
9244
9245 \end_inset
9246
9247  to MCS51/DS390 specific memory spaces
9248 \layout Standard
9249
9250 SDCC allows (via language extensions) pointers to explicitly point to any
9251  of the memory spaces
9252 \begin_inset LatexCommand \index{Memory model}
9253
9254 \end_inset
9255
9256  of the 8051.
9257  In addition to the explicit pointers, the compiler uses (by default) generic
9258  pointers which can be used to point to any of the memory spaces.
9259 \newline
9260
9261 \newline
9262 Pointer declaration examples:
9263 \layout Verse
9264
9265
9266 \family typewriter
9267 /* pointer physically in internal ram pointing to object in external ram
9268  */
9269 \newline
9270 xdata unsigned char * data p;
9271 \newline
9272
9273 \newline
9274 /* pointer physically in external ram pointing to object in internal ram
9275  */
9276 \newline
9277 data unsigned char * xdata p;
9278 \newline
9279
9280 \newline
9281 /* pointer physically in code rom pointing to data in xdata space */
9282 \newline
9283 xdata unsigned char * code p;
9284 \newline
9285
9286 \newline
9287 /* pointer physically in code space pointing to data in code space */
9288 \newline
9289 code unsigned char * code p;
9290 \newline
9291
9292 \newline
9293 /* the following is a generic pointer physically located in xdata space
9294  */
9295 \newline
9296 char * xdata p;
9297 \newline
9298
9299 \newline
9300 /* the following is a function pointer physically located in data space
9301  */
9302 \newline
9303 char (* data fp)(void);
9304 \layout Standard
9305
9306 Well you get the idea.
9307
9308 \newline
9309
9310 \newline
9311 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
9312 \emph on
9313 generic
9314 \emph default
9315  pointers.
9316
9317 \size small
9318
9319 \newline
9320
9321 \newline
9322
9323 \size default
9324 The highest order byte of the
9325 \emph on
9326 generic
9327 \emph default
9328  pointers contains the data space information.
9329  Assembler support routines are called whenever data is stored or retrieved
9330  using
9331 \emph on
9332 generic
9333 \emph default
9334  pointers.
9335  These are useful for developing reusable library
9336 \begin_inset LatexCommand \index{Libraries}
9337
9338 \end_inset
9339
9340  routines.
9341  Explicitly specifying the pointer type will generate the most efficient
9342  code.
9343 \layout Subsubsection
9344
9345 Notes on MCS51 memory
9346 \begin_inset LatexCommand \index{MCS51 memory}
9347
9348 \end_inset
9349
9350  layout
9351 \layout Standard
9352
9353 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
9354  RAM memory which is structured as follows:
9355 \newline
9356
9357 \newline
9358 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
9359
9360 \newline
9361 - Bytes 20-2F - 16 bytes to hold 128 bit
9362 \begin_inset LatexCommand \index{bit}
9363
9364 \end_inset
9365
9366  variables and,
9367 \newline
9368 - Bytes 30-7F - 80 bytes for general purpose use.
9369 \newline
9370
9371 \layout Standard
9372
9373 Additionally some members of the MCS51 family may have up to 128 bytes of
9374  additional, indirectly addressable, internal RAM memory (
9375 \emph on
9376 idata
9377 \emph default
9378
9379 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
9380
9381 \end_inset
9382
9383
9384 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
9385
9386 \end_inset
9387
9388 ).
9389  Furthermore, some chips may have some built in external memory (
9390 \emph on
9391 xdata
9392 \emph default
9393
9394 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9395
9396 \end_inset
9397
9398
9399 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9400
9401 \end_inset
9402
9403 ) which should not be confused with the internal, directly addressable RAM
9404  memory (
9405 \emph on
9406 data
9407 \emph default
9408
9409 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
9410
9411 \end_inset
9412
9413
9414 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
9415
9416 \end_inset
9417
9418 ).
9419  Sometimes this built in
9420 \emph on
9421 xdata
9422 \emph default
9423  memory has to be activated before using it (you can probably find this
9424  information on the datasheet of the microcontroller your are using, see
9425  also section
9426 \begin_inset LatexCommand \ref{sub:Startup-Code}
9427
9428 \end_inset
9429
9430 \SpecialChar ~
9431 Startup-Code).
9432 \layout Standard
9433
9434 Normally SDCC will only use the first bank
9435 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
9436
9437 \end_inset
9438
9439  of registers (register bank 0), but it is possible to specify that other
9440  banks of registers (keyword
9441 \emph on
9442 using
9443 \emph default
9444
9445 \emph on
9446
9447 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
9448
9449 \end_inset
9450
9451
9452 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
9453
9454 \end_inset
9455
9456
9457 \emph default
9458 ) should be used in interrupt
9459 \begin_inset LatexCommand \index{interrupt}
9460
9461 \end_inset
9462
9463
9464 \begin_inset LatexCommand \index{\_\_interrupt}
9465
9466 \end_inset
9467
9468  routines.
9469  By default, the compiler will place the stack after the last byte of allocated
9470  memory for variables.
9471  For example, if the first 2 banks of registers are used, and only four
9472  bytes are used for
9473 \emph on
9474 data
9475 \emph default
9476  variables, it will position the base of the internal stack at address 20
9477  (0x14).
9478  This implies that as the stack
9479 \begin_inset LatexCommand \index{stack}
9480
9481 \end_inset
9482
9483  grows, it will use up the remaining register banks, and the 16 bytes used
9484  by the 128 bit variables, and 80 bytes for general purpose use.
9485  If any bit variables are used, the data variables will be placed in unused
9486  register banks and after the byte holding the last bit variable.
9487  For example, if register banks 0 and 1 are used, and there are 9 bit variables
9488  (two bytes used),
9489 \emph on
9490 data
9491 \emph default
9492  variables will be placed starting from address 0x10 to 0x20 and continue
9493  at address 0x22.
9494  You can also use -
9495 \begin_inset ERT
9496 status Collapsed
9497
9498 \layout Standard
9499
9500 \backslash
9501 /
9502 \end_inset
9503
9504 -data-loc
9505 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
9506
9507 \end_inset
9508
9509  to specify the start address of the
9510 \emph on
9511 data
9512 \emph default
9513  and -
9514 \begin_inset ERT
9515 status Collapsed
9516
9517 \layout Standard
9518
9519 \backslash
9520 /
9521 \end_inset
9522
9523 -iram-size
9524 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
9525
9526 \end_inset
9527
9528  to specify the size of the total internal RAM (
9529 \emph on
9530 data
9531 \emph default
9532 +
9533 \emph on
9534 idata
9535 \emph default
9536 ).
9537
9538 \layout Standard
9539
9540 By default the 8051 linker will place the stack after the last byte of (i)data
9541  variables.
9542  Option -
9543 \begin_inset ERT
9544 status Collapsed
9545
9546 \layout Standard
9547
9548 \backslash
9549 /
9550 \end_inset
9551
9552 -stack-loc
9553 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
9554
9555 \end_inset
9556
9557  allows you to specify the start of the stack, i.e.
9558  you could start it after any data in the general purpose area.
9559  If your microcontroller has additional indirectly addressable internal
9560  RAM (
9561 \emph on
9562 idata
9563 \emph default
9564 ) you can place the stack on it.
9565  You may also need to use -
9566 \begin_inset ERT
9567 status Collapsed
9568
9569 \layout Standard
9570
9571 \backslash
9572 /
9573 \end_inset
9574
9575 -xdata-loc
9576 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
9577
9578 \end_inset
9579
9580  to set the start address of the external RAM (
9581 \emph on
9582 xdata
9583 \emph default
9584 ) and -
9585 \begin_inset ERT
9586 status Collapsed
9587
9588 \layout Standard
9589
9590 \backslash
9591 /
9592 \end_inset
9593
9594 -xram-size
9595 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
9596
9597 \end_inset
9598
9599  to specify its size.
9600  Same goes for the code memory, using -
9601 \begin_inset ERT
9602 status Collapsed
9603
9604 \layout Standard
9605
9606 \backslash
9607 /
9608 \end_inset
9609
9610 -code-loc
9611 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
9612
9613 \end_inset
9614
9615  and -
9616 \begin_inset ERT
9617 status Collapsed
9618
9619 \layout Standard
9620
9621 \backslash
9622 /
9623 \end_inset
9624
9625 -code-size
9626 \begin_inset LatexCommand \index{-\/-code-size <Value>}
9627
9628 \end_inset
9629
9630 .
9631  If in doubt, don't specify any options and see if the resulting memory
9632  layout is appropriate, then you can adjust it.
9633 \layout Standard
9634
9635 The linker generates two files with memory allocation information.
9636  The first, with extension .map
9637 \begin_inset LatexCommand \index{<file>.map}
9638
9639 \end_inset
9640
9641  shows all the variables and segments.
9642  The second with extension .mem
9643 \begin_inset LatexCommand \index{<file>.mem}
9644
9645 \end_inset
9646
9647  shows the final memory layout.
9648  The linker will complain either if memory segments overlap, there is not
9649  enough memory, or there is not enough space for stack.
9650  If you get any linking warnings and/or errors related to stack or segments
9651  allocation, take a look at either the .map or .mem files to find out what
9652  the problem is.
9653  The .mem file may even suggest a solution to the problem.
9654 \layout Subsection
9655
9656 Z80/Z180 Storage Class
9657 \begin_inset LatexCommand \index{Storage class}
9658
9659 \end_inset
9660
9661  Language Extensions
9662 \layout Subsubsection
9663
9664 sfr
9665 \begin_inset LatexCommand \index{sfr}
9666
9667 \end_inset
9668
9669
9670 \begin_inset LatexCommand \index{\_\_sfr}
9671
9672 \end_inset
9673
9674  (in/out to 8-bit addresses)
9675 \layout Standard
9676
9677 The Z80
9678 \begin_inset LatexCommand \index{Z80}
9679
9680 \end_inset
9681
9682  family has separate address spaces for memory and
9683 \emph on
9684 i
9685 \emph default
9686 nput/
9687 \emph on
9688 o
9689 \emph default
9690 utput memory.
9691  I/O memory
9692 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
9693
9694 \end_inset
9695
9696  is accessed with special instructions, e.g.:
9697 \layout Verse
9698
9699
9700 \family typewriter
9701 sfr at 0x78 IoPort;\SpecialChar ~
9702 \SpecialChar ~
9703 /* define a var in I/O space at 78h called IoPort */
9704
9705 \layout Standard
9706
9707 Writing 0x01 to this variable generates the assembly code:
9708 \layout Verse
9709
9710
9711 \family typewriter
9712 3E 01\SpecialChar ~
9713 \SpecialChar ~
9714 \SpecialChar ~
9715 \SpecialChar ~
9716 \SpecialChar ~
9717 \SpecialChar ~
9718 ld a,#0x01
9719 \newline
9720 D3 78\SpecialChar ~
9721 \SpecialChar ~
9722 \SpecialChar ~
9723 \SpecialChar ~
9724 \SpecialChar ~
9725 \SpecialChar ~
9726 out (_IoPort),a
9727 \layout Subsubsection
9728
9729 banked sfr
9730 \begin_inset LatexCommand \index{sfr}
9731
9732 \end_inset
9733
9734
9735 \begin_inset LatexCommand \index{\_\_sfr}
9736
9737 \end_inset
9738
9739  (in/out to 16-bit addresses)
9740 \layout Standard
9741
9742 The keyword
9743 \emph on
9744 banked
9745 \emph default
9746  is used to support 16 bit addresses in I/O memory e.g.:
9747 \layout Verse
9748
9749
9750 \family typewriter
9751 sfr banked at
9752 \begin_inset LatexCommand \index{at}
9753
9754 \end_inset
9755
9756
9757 \begin_inset LatexCommand \index{\_\_at}
9758
9759 \end_inset
9760
9761  0x123 IoPort;
9762 \layout Standard
9763
9764 Writing 0x01 to this variable generates the assembly code:
9765 \layout Verse
9766
9767
9768 \family typewriter
9769 01 23 01\SpecialChar ~
9770 \SpecialChar ~
9771 \SpecialChar ~
9772 ld bc,#_IoPort
9773 \newline
9774 3E 01\SpecialChar ~
9775 \SpecialChar ~
9776 \SpecialChar ~
9777 \SpecialChar ~
9778 \SpecialChar ~
9779 \SpecialChar ~
9780 ld a,#0x01
9781 \newline
9782 ED 79\SpecialChar ~
9783 \SpecialChar ~
9784 \SpecialChar ~
9785 \SpecialChar ~
9786 \SpecialChar ~
9787 \SpecialChar ~
9788 out (c),a
9789 \layout Subsubsection
9790
9791 sfr
9792 \begin_inset LatexCommand \index{sfr}
9793
9794 \end_inset
9795
9796
9797 \begin_inset LatexCommand \index{\_\_sfr}
9798
9799 \end_inset
9800
9801  (in0/out0 to 8 bit addresses on Z180
9802 \begin_inset LatexCommand \index{Z180}
9803
9804 \end_inset
9805
9806 /HD64180
9807 \begin_inset LatexCommand \index{HD64180}
9808
9809 \end_inset
9810
9811 )
9812 \layout Standard
9813
9814 The compiler option -
9815 \begin_inset ERT
9816 status Collapsed
9817
9818 \layout Standard
9819
9820 \backslash
9821 /
9822 \end_inset
9823
9824 -portmode=180 (80) and a compiler #pragma\SpecialChar ~
9825 portmode
9826 \begin_inset LatexCommand \index{\#pragma portmode}
9827
9828 \end_inset
9829
9830 =z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
9831 ns
9832 \family typewriter
9833 in0/out0
9834 \family default
9835  instead of
9836 \family typewriter
9837 in/out
9838 \family default
9839 .
9840  If you include the file z180.h this will be set automatically.
9841 \layout Subsection
9842
9843 HC08 Storage Class
9844 \begin_inset LatexCommand \index{Storage class}
9845
9846 \end_inset
9847
9848  Language Extensions
9849 \layout Subsubsection
9850
9851 data
9852 \begin_inset LatexCommand \index{data (hc08 storage class)}
9853
9854 \end_inset
9855
9856
9857 \begin_inset LatexCommand \index{\_\_data (hc08 storage class)}
9858
9859 \end_inset
9860
9861
9862 \layout Standard
9863
9864 The data storage class declares a variable that resides in the first 256
9865  bytes of memory (the direct page).
9866  The HC08 is most efficient at accessing variables (especially pointers)
9867  stored here.
9868 \layout Subsubsection
9869
9870 xdata
9871 \begin_inset LatexCommand \index{xdata (hc08 storage class)}
9872
9873 \end_inset
9874
9875
9876 \begin_inset LatexCommand \index{\_\_xdata (hc08 storage class)}
9877
9878 \end_inset
9879
9880
9881 \layout Standard
9882
9883 The xdata storage class declares a variable that can reside anywhere in
9884  memory.
9885  This is the default if no storage class is specified.
9886
9887 \layout Section
9888
9889 Absolute Addressing
9890 \begin_inset LatexCommand \index{Absolute addressing}
9891
9892 \end_inset
9893
9894
9895 \layout Standard
9896
9897 Data items can be assigned an absolute address with the
9898 \emph on
9899 at
9900 \begin_inset LatexCommand \index{at}
9901
9902 \end_inset
9903
9904
9905 \begin_inset LatexCommand \index{\_\_at}
9906
9907 \end_inset
9908
9909  <address>
9910 \emph default
9911  keyword, in addition to a storage class, e.g.:
9912 \layout Verse
9913
9914
9915 \family typewriter
9916 xdata
9917 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9918
9919 \end_inset
9920
9921
9922 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9923
9924 \end_inset
9925
9926  at
9927 \begin_inset LatexCommand \index{at}
9928
9929 \end_inset
9930
9931
9932 \begin_inset LatexCommand \index{\_\_at}
9933
9934 \end_inset
9935
9936  0x7ffe unsigned int chksum;
9937 \layout Standard
9938
9939 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
9940  of the external ram.
9941  The compiler does
9942 \emph on
9943 not
9944 \emph default
9945  reserve any space for variables declared in this way (they are implemented
9946  with an equate in the assembler).
9947  Thus it is left to the programmer to make sure there are no overlaps with
9948  other variables that are declared without the absolute address.
9949  The assembler listing file (.lst
9950 \begin_inset LatexCommand \index{<file>.lst}
9951
9952 \end_inset
9953
9954 ) and the linker output files (.rst
9955 \begin_inset LatexCommand \index{<file>.rst}
9956
9957 \end_inset
9958
9959 ) and (.map
9960 \begin_inset LatexCommand \index{<file>.map}
9961
9962 \end_inset
9963
9964 ) are good places to look for such overlaps.
9965  Variables with an absolute address are
9966 \emph on
9967 not
9968 \emph default
9969  initialized
9970 \begin_inset LatexCommand \index{Variable initialization}
9971
9972 \end_inset
9973
9974 .
9975 \layout Standard
9976
9977 In case of memory mapped I/O devices the keyword
9978 \emph on
9979 volatile
9980 \emph default
9981  has to be used to tell the compiler that accesses might not be removed:
9982 \layout Verse
9983
9984
9985 \family typewriter
9986 volatile
9987 \begin_inset LatexCommand \index{volatile}
9988
9989 \end_inset
9990
9991  xdata
9992 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9993
9994 \end_inset
9995
9996  at
9997 \begin_inset LatexCommand \index{at}
9998
9999 \end_inset
10000
10001  0x8000 unsigned char PORTA_8255;
10002 \layout Standard
10003
10004 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
10005 r) array
10006 \family typewriter
10007 \size footnotesize
10008
10009 \begin_inset LatexCommand \index{Aligned array}
10010
10011 \end_inset
10012
10013
10014 \family default
10015 \size default
10016  starts at a block (256 byte) boundary
10017 \begin_inset LatexCommand \index{block boundary}
10018
10019 \end_inset
10020
10021  (section
10022 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
10023
10024 \end_inset
10025
10026  has an example).
10027 \newline
10028 Absolute addresses can be specified for variables in all storage classes,
10029  e.g.:
10030 \layout Verse
10031
10032
10033 \family typewriter
10034 bit
10035 \begin_inset LatexCommand \index{bit}
10036
10037 \end_inset
10038
10039  at
10040 \begin_inset LatexCommand \index{at}
10041
10042 \end_inset
10043
10044  0x02 bvar;
10045 \layout Standard
10046
10047 The above example will allocate the variable at offset 0x02 in the bit-addressab
10048 le space.
10049  There is no real advantage to assigning absolute addresses to variables
10050  in this manner, unless you want strict control over all the variables allocated.
10051  One possible use would be to write hardware portable code.
10052  For example, if you have a routine that uses one or more of the microcontroller
10053  I/O pins, and such pins are different for two different hardwares, you
10054  can declare the I/O pins in your routine using:
10055 \layout Verse
10056
10057
10058 \family typewriter
10059 extern volatile
10060 \begin_inset LatexCommand \index{volatile}
10061
10062 \end_inset
10063
10064  bit MOSI;\SpecialChar ~
10065 \SpecialChar ~
10066 \SpecialChar ~
10067 \SpecialChar ~
10068 /* master out, slave in */
10069 \newline
10070 extern volatile bit MISO;\SpecialChar ~
10071 \SpecialChar ~
10072 \SpecialChar ~
10073 \SpecialChar ~
10074 /* master in, slave out */
10075 \newline
10076 extern volatile bit MCLK;\SpecialChar ~
10077 \SpecialChar ~
10078 \SpecialChar ~
10079 \SpecialChar ~
10080 /* master clock */
10081 \newline
10082
10083 \newline
10084 /* Input and Output of a byte on a 3-wire serial bus.
10085 \newline
10086 \SpecialChar ~
10087 \SpecialChar ~
10088 \SpecialChar ~
10089 If needed adapt polarity of clock, polarity of data and bit order
10090 \newline
10091 \SpecialChar ~
10092 */
10093 \newline
10094 unsigned char spi_io(unsigned char out_byte)
10095 \newline
10096 {
10097 \newline
10098 \SpecialChar ~
10099 \SpecialChar ~
10100 \SpecialChar ~
10101 \SpecialChar ~
10102 unsigned char i=8;
10103 \newline
10104 \SpecialChar ~
10105 \SpecialChar ~
10106 \SpecialChar ~
10107 \SpecialChar ~
10108 do {
10109 \newline
10110 \SpecialChar ~
10111 \SpecialChar ~
10112 \SpecialChar ~
10113 \SpecialChar ~
10114 \SpecialChar ~
10115 \SpecialChar ~
10116 \SpecialChar ~
10117 \SpecialChar ~
10118 MOSI = out_byte & 0x80;
10119 \newline
10120 \SpecialChar ~
10121 \SpecialChar ~
10122 \SpecialChar ~
10123 \SpecialChar ~
10124 \SpecialChar ~
10125 \SpecialChar ~
10126 \SpecialChar ~
10127 \SpecialChar ~
10128 out_byte <<= 1;
10129 \newline
10130 \SpecialChar ~
10131 \SpecialChar ~
10132 \SpecialChar ~
10133 \SpecialChar ~
10134 \SpecialChar ~
10135 \SpecialChar ~
10136 \SpecialChar ~
10137 \SpecialChar ~
10138 MCLK = 1;
10139 \newline
10140 \SpecialChar ~
10141 \SpecialChar ~
10142 \SpecialChar ~
10143 \SpecialChar ~
10144 \SpecialChar ~
10145 \SpecialChar ~
10146 \SpecialChar ~
10147 \SpecialChar ~
10148 /* _asm nop _endasm; */\SpecialChar ~
10149 \SpecialChar ~
10150 \SpecialChar ~
10151 \SpecialChar ~
10152 \SpecialChar ~
10153 \SpecialChar ~
10154 \SpecialChar ~
10155 \SpecialChar ~
10156 /* for slow peripherals */
10157 \newline
10158 \SpecialChar ~
10159 \SpecialChar ~
10160 \SpecialChar ~
10161 \SpecialChar ~
10162 \SpecialChar ~
10163 \SpecialChar ~
10164 \SpecialChar ~
10165 \SpecialChar ~
10166 if(MISO)
10167 \newline
10168 \SpecialChar ~
10169 \SpecialChar ~
10170 \SpecialChar ~
10171 \SpecialChar ~
10172 \SpecialChar ~
10173 \SpecialChar ~
10174 \SpecialChar ~
10175 \SpecialChar ~
10176 \SpecialChar ~
10177 \SpecialChar ~
10178 \SpecialChar ~
10179 \SpecialChar ~
10180 out_byte += 1;
10181 \newline
10182 \SpecialChar ~
10183 \SpecialChar ~
10184 \SpecialChar ~
10185 \SpecialChar ~
10186 \SpecialChar ~
10187 \SpecialChar ~
10188 \SpecialChar ~
10189 \SpecialChar ~
10190 MCLK = 0;
10191 \newline
10192 \SpecialChar ~
10193 \SpecialChar ~
10194 \SpecialChar ~
10195 \SpecialChar ~
10196 } while(--i);
10197 \newline
10198 \SpecialChar ~
10199 \SpecialChar ~
10200 \SpecialChar ~
10201 \SpecialChar ~
10202 return out_byte;
10203 \newline
10204 }
10205 \layout Standard
10206
10207 Then, someplace in the code for the first hardware you would use
10208 \layout Verse
10209
10210
10211 \family typewriter
10212 bit at
10213 \begin_inset LatexCommand \index{at}
10214
10215 \end_inset
10216
10217
10218 \begin_inset LatexCommand \index{\_\_at}
10219
10220 \end_inset
10221
10222  0x80 MOSI;\SpecialChar ~
10223 \SpecialChar ~
10224 \SpecialChar ~
10225 \SpecialChar ~
10226 /* I/O port 0, bit 0 */
10227 \newline
10228 bit at 0x81 MISO;\SpecialChar ~
10229 \SpecialChar ~
10230 \SpecialChar ~
10231 \SpecialChar ~
10232 /* I/O port 0, bit 1 */
10233 \newline
10234 bit at 0x82 MCLK;\SpecialChar ~
10235 \SpecialChar ~
10236 \SpecialChar ~
10237 \SpecialChar ~
10238 /* I/O port 0, bit 2 */
10239 \layout Standard
10240
10241 Similarly, for the second hardware you would use
10242 \layout Verse
10243
10244
10245 \family typewriter
10246 bit at 0x83 MOSI;\SpecialChar ~
10247 \SpecialChar ~
10248 \SpecialChar ~
10249 \SpecialChar ~
10250 /* I/O port 0, bit 3 */
10251 \newline
10252 bit at 0x91 MISO;\SpecialChar ~
10253 \SpecialChar ~
10254 \SpecialChar ~
10255 \SpecialChar ~
10256 /* I/O port 1, bit 1 */
10257 \newline
10258 bit
10259 \begin_inset LatexCommand \index{bit}
10260
10261 \end_inset
10262
10263  at 0x92 MCLK;\SpecialChar ~
10264 \SpecialChar ~
10265 \SpecialChar ~
10266 \SpecialChar ~
10267 /* I/O port 1, bit 2 */
10268 \layout Standard
10269
10270 and you can use the same hardware dependent routine without changes, as
10271  for example in a library.
10272  This is somehow similar to sbit, but only one absolute address has to be
10273  specified in the whole project.
10274 \layout Section
10275
10276 Parameters
10277 \begin_inset LatexCommand \index{Parameters}
10278
10279 \end_inset
10280
10281
10282 \begin_inset LatexCommand \index{function parameter}
10283
10284 \end_inset
10285
10286  & Local Variables
10287 \begin_inset LatexCommand \index{local variables}
10288
10289 \end_inset
10290
10291
10292 \begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
10293
10294 \end_inset
10295
10296
10297 \layout Standard
10298
10299 Automatic (local) variables and parameters to functions can either be placed
10300  on the stack or in data-space.
10301  The default action of the compiler is to place these variables in the internal
10302  RAM (for small model) or external RAM (for large model).
10303  This in fact makes them similar to
10304 \emph on
10305 static
10306 \begin_inset LatexCommand \index{static}
10307
10308 \end_inset
10309
10310
10311 \emph default
10312  so by default functions are non-reentrant
10313 \begin_inset LatexCommand \index{reentrant}
10314
10315 \end_inset
10316
10317 .
10318
10319 \newline
10320
10321 \newline
10322 They can be placed on the stack
10323 \begin_inset LatexCommand \index{stack}
10324
10325 \end_inset
10326
10327  by using the
10328 \emph on
10329  -
10330 \begin_inset ERT
10331 status Collapsed
10332
10333 \layout Standard
10334
10335 \backslash
10336 /
10337 \end_inset
10338
10339 -stack-auto
10340 \begin_inset LatexCommand \index{-\/-stack-auto}
10341
10342 \end_inset
10343
10344
10345 \emph default
10346  option, by using
10347 \emph on
10348 #pragma\SpecialChar ~
10349 stackauto
10350 \emph default
10351
10352 \begin_inset LatexCommand \index{\#pragma stackauto}
10353
10354 \end_inset
10355
10356  or by using the
10357 \emph on
10358 reentrant
10359 \begin_inset LatexCommand \index{reentrant}
10360
10361 \end_inset
10362
10363
10364 \emph default
10365  keyword in the function declaration, e.g.:
10366 \layout Verse
10367
10368
10369 \family typewriter
10370 unsigned char foo(char i) reentrant
10371 \newline
10372 {
10373 \newline
10374 \SpecialChar ~
10375 \SpecialChar ~
10376 \SpecialChar ~
10377 \SpecialChar ~
10378 ...
10379
10380 \newline
10381 }
10382 \layout Standard
10383
10384 Since stack space on 8051 is limited, the
10385 \emph on
10386 reentrant
10387 \emph default
10388 keyword or the
10389 \emph on
10390  -
10391 \begin_inset ERT
10392 status Collapsed
10393
10394 \layout Standard
10395
10396 \backslash
10397 /
10398 \end_inset
10399
10400 -stack-auto
10401 \emph default
10402  option should be used sparingly.
10403  Note that the reentrant keyword just means that the parameters & local
10404  variables will be allocated to the stack, it
10405 \emph on
10406 does not
10407 \emph default
10408  mean that the function is register bank
10409 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
10410
10411 \end_inset
10412
10413  independent.
10414 \newline
10415
10416 \newline
10417 Local variables
10418 \begin_inset LatexCommand \index{local variables}
10419
10420 \end_inset
10421
10422  can be assigned storage classes and absolute
10423 \begin_inset LatexCommand \index{Absolute addressing}
10424
10425 \end_inset
10426
10427  addresses, e.g.:
10428 \layout Verse
10429
10430
10431 \family typewriter
10432 unsigned char foo()
10433 \newline
10434 {
10435 \newline
10436 \SpecialChar ~
10437 \SpecialChar ~
10438 \SpecialChar ~
10439 \SpecialChar ~
10440 xdata unsigned char i;
10441 \newline
10442 \SpecialChar ~
10443 \SpecialChar ~
10444 \SpecialChar ~
10445 \SpecialChar ~
10446 bit bvar;
10447 \newline
10448 \SpecialChar ~
10449 \SpecialChar ~
10450 \SpecialChar ~
10451 \SpecialChar ~
10452 data at
10453 \begin_inset LatexCommand \index{at}
10454
10455 \end_inset
10456
10457  0x31 unsigned char j;
10458 \newline
10459 \SpecialChar ~
10460 \SpecialChar ~
10461 \SpecialChar ~
10462 \SpecialChar ~
10463 ...
10464
10465 \newline
10466 }
10467 \layout Standard
10468
10469 In the above example the variable
10470 \emph on
10471 i
10472 \emph default
10473  will be allocated in the external ram,
10474 \emph on
10475 bvar
10476 \emph default
10477  in bit addressable space and
10478 \emph on
10479  j
10480 \emph default
10481  in internal ram.
10482  When compiled with
10483 \emph on
10484 -
10485 \begin_inset ERT
10486 status Collapsed
10487
10488 \layout Standard
10489
10490 \backslash
10491 /
10492 \end_inset
10493
10494 -stack-auto
10495 \emph default
10496  or when a function is declared as
10497 \emph on
10498 reentrant
10499 \emph default
10500  this should only be done for static variables.
10501 \layout Standard
10502
10503 Parameters
10504 \begin_inset LatexCommand \index{function parameter}
10505
10506 \end_inset
10507
10508  however are not allowed any storage class
10509 \begin_inset LatexCommand \index{Storage class}
10510
10511 \end_inset
10512
10513 , (storage classes for parameters will be ignored), their allocation is
10514  governed by the memory model in use, and the reentrancy options.
10515 \layout Standard
10516
10517 It is however allowed to use bit parameters in reentrant functions and also
10518  non-static local bit variables are supported.
10519  Efficient use is limited to 8 semi-bitregisters in bit space.
10520  They are pushed and popped to stack as a single byte just like the normal
10521  registers.
10522 \layout Section
10523
10524 Overlaying
10525 \begin_inset LatexCommand \label{sub:Overlaying}
10526
10527 \end_inset
10528
10529
10530 \begin_inset LatexCommand \index{Overlaying}
10531
10532 \end_inset
10533
10534
10535 \layout Standard
10536
10537 For non-reentrant
10538 \begin_inset LatexCommand \index{reentrant}
10539
10540 \end_inset
10541
10542  functions SDCC will try to reduce internal ram space usage by overlaying
10543  parameters and local variables of a function (if possible).
10544  Parameters and local variables
10545 \begin_inset LatexCommand \index{local variables}
10546
10547 \end_inset
10548
10549  of a function will be allocated to an overlayable segment if the function
10550  has
10551 \emph on
10552 no other function calls and the function is non-reentrant and the memory
10553  model
10554 \begin_inset LatexCommand \index{Memory model}
10555
10556 \end_inset
10557
10558  is small.
10559
10560 \emph default
10561  If an explicit storage class
10562 \begin_inset LatexCommand \index{Storage class}
10563
10564 \end_inset
10565
10566  is specified for a local variable, it will NOT be overlayed.
10567 \layout Standard
10568
10569 Note that the compiler (not the linkage editor) makes the decision for overlayin
10570 g the data items.
10571  Functions that are called from an interrupt service routine should be preceded
10572  by a #pragma\SpecialChar ~
10573 nooverlay
10574 \begin_inset LatexCommand \index{\#pragma nooverlay}
10575
10576 \end_inset
10577
10578  if they are not reentrant.
10579 \layout Standard
10580
10581 Also note that the compiler does not do any processing of inline assembler
10582  code, so the compiler might incorrectly assign local variables and parameters
10583  of a function into the overlay segment if the inline assembler code calls
10584  other c-functions that might use the overlay.
10585  In that case the #pragma\SpecialChar ~
10586 nooverlay should be used.
10587 \layout Standard
10588
10589 Parameters and local variables of functions that contain 16 or 32 bit multiplica
10590 tion
10591 \begin_inset LatexCommand \index{Multiplication}
10592
10593 \end_inset
10594
10595  or division
10596 \begin_inset LatexCommand \index{Division}
10597
10598 \end_inset
10599
10600  will NOT be overlayed since these are implemented using external functions,
10601  e.g.:
10602 \layout Verse
10603
10604
10605 \family typewriter
10606 #pragma save
10607 \newline
10608 #pragma nooverlay
10609 \begin_inset LatexCommand \index{\#pragma nooverlay}
10610
10611 \end_inset
10612
10613
10614 \newline
10615 void set_error(unsigned char errcd)
10616 \newline
10617 {
10618 \newline
10619 \SpecialChar ~
10620 \SpecialChar ~
10621 \SpecialChar ~
10622 \SpecialChar ~
10623 P3 = errcd;
10624 \newline
10625 }
10626 \newline
10627 #pragma restore
10628 \newline
10629
10630 \newline
10631 void some_isr () interrupt
10632 \begin_inset LatexCommand \index{interrupt}
10633
10634 \end_inset
10635
10636  2
10637 \newline
10638 {
10639 \newline
10640 \SpecialChar ~
10641 \SpecialChar ~
10642 \SpecialChar ~
10643 \SpecialChar ~
10644 ...
10645 \newline
10646 \SpecialChar ~
10647 \SpecialChar ~
10648 \SpecialChar ~
10649 \SpecialChar ~
10650 set_error(10);
10651 \newline
10652 \SpecialChar ~
10653 \SpecialChar ~
10654 \SpecialChar ~
10655 \SpecialChar ~
10656 ...
10657
10658 \newline
10659 }
10660 \layout Standard
10661
10662 In the above example the parameter
10663 \emph on
10664 errcd
10665 \emph default
10666  for the function
10667 \emph on
10668 set_error
10669 \emph default
10670  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
10671 nooverlay was
10672  not present, this could cause unpredictable runtime behavior when called
10673  from an interrupt service routine.
10674  The #pragma\SpecialChar ~
10675 nooverlay ensures that the parameters and local variables for
10676  the function are NOT overlayed.
10677 \layout Section
10678
10679 Interrupt Service Routines
10680 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
10681
10682 \end_inset
10683
10684
10685 \layout Subsection
10686
10687 General Information
10688 \layout Standard
10689
10690 SDCC allows
10691 \emph on
10692 i
10693 \emph default
10694 nterrupt
10695 \emph on
10696 s
10697 \emph default
10698 ervice
10699 \emph on
10700 r
10701 \emph default
10702 outines to be coded in C, with some extended keywords.
10703 \layout Verse
10704
10705
10706 \family typewriter
10707 void timer_isr (void) interrupt 1 using 1
10708 \newline
10709 {
10710 \newline
10711 \SpecialChar ~
10712 \SpecialChar ~
10713 \SpecialChar ~
10714 \SpecialChar ~
10715 ...
10716
10717 \newline
10718 }
10719 \layout Standard
10720
10721 The optional number following the
10722 \emph on
10723 interrupt
10724 \begin_inset LatexCommand \index{interrupt}
10725
10726 \end_inset
10727
10728
10729 \begin_inset LatexCommand \index{\_\_interrupt}
10730
10731 \end_inset
10732
10733
10734 \emph default
10735  keyword is the interrupt number this routine will service.
10736  When present, the compiler will insert a call to this routine in the interrupt
10737  vector table for the interrupt number specified.
10738  If you have multiple source files in your project, interrupt service routines
10739  can be present in any of them, but a prototype of the isr MUST be present
10740  or included in the file that contains the function
10741 \emph on
10742 main
10743 \emph default
10744 .
10745  The optional
10746 \emph on
10747 using
10748 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10749
10750 \end_inset
10751
10752
10753 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
10754
10755 \end_inset
10756
10757
10758 \emph default
10759  keyword can be used to tell the compiler to use the specified register
10760  bank (8051 specific) when generating code for this function.
10761
10762 \newline
10763
10764 \layout Standard
10765
10766 Interrupt service routines open the door for some very interesting bugs:
10767 \newline
10768 If an interrupt service routine changes variables which are accessed by
10769  other functions these variables have to be declared
10770 \emph on
10771 volatile
10772 \emph default
10773
10774 \begin_inset LatexCommand \index{volatile}
10775
10776 \end_inset
10777
10778 .
10779
10780 \layout Standard
10781
10782 If the access to these variables is not
10783 \emph on
10784 atomic
10785 \begin_inset LatexCommand \index{atomic}
10786
10787 \end_inset
10788
10789
10790 \emph default
10791  (i.e.
10792  the processor needs more than one instruction for the access and could
10793  be interrupted while accessing the variable) the interrupt must be disabled
10794  during the access to avoid inconsistent data.
10795  Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
10796  and should be protected by disabling interrupts.
10797  You're not automatically on the safe side if you use 8 bit variables though.
10798  We need an example here: f.e.
10799  on the 8051 the harmless looking
10800 \begin_inset Quotes srd
10801 \end_inset
10802
10803
10804 \family typewriter
10805 flags\SpecialChar ~
10806 |=\SpecialChar ~
10807 0x80;
10808 \family default
10809
10810 \begin_inset Quotes sld
10811 \end_inset
10812
10813  is not atomic if
10814 \family typewriter
10815 flags
10816 \family default
10817  resides in xdata.
10818  Setting
10819 \begin_inset Quotes srd
10820 \end_inset
10821
10822
10823 \family typewriter
10824 flags\SpecialChar ~
10825 |=\SpecialChar ~
10826 0x40;
10827 \family default
10828
10829 \begin_inset Quotes sld
10830 \end_inset
10831
10832  from within an interrupt routine might get lost if the interrupt occurs
10833  at the wrong time.
10834
10835 \begin_inset Quotes sld
10836 \end_inset
10837
10838
10839 \family typewriter
10840 counter\SpecialChar ~
10841 +=\SpecialChar ~
10842 8;
10843 \family default
10844
10845 \begin_inset Quotes srd
10846 \end_inset
10847
10848  is not atomic on the 8051 even if
10849 \family typewriter
10850 counter
10851 \family default
10852  is located in data memory.
10853  Bugs like these are hard to reproduce and can cause a lot of trouble.
10854
10855 \layout Standard
10856
10857 The return address and the registers used in the interrupt service routine
10858  are saved on the stack
10859 \begin_inset LatexCommand \index{stack}
10860
10861 \end_inset
10862
10863  so there must be sufficient stack space.
10864  If there isn't variables or registers (or even the return address itself)
10865  will be corrupted.
10866  This
10867 \emph on
10868 stack overflow
10869 \emph default
10870
10871 \begin_inset LatexCommand \index{stack overflow}
10872
10873 \end_inset
10874
10875  is most likely to happen if the interrupt occurs during the
10876 \begin_inset Quotes sld
10877 \end_inset
10878
10879 deepest
10880 \begin_inset Quotes srd
10881 \end_inset
10882
10883  subroutine when the stack is already in use for f.e.
10884  many return addresses.
10885 \layout Standard
10886
10887 A special note here, int (16 bit) and long (32 bit) integer division
10888 \begin_inset LatexCommand \index{Division}
10889
10890 \end_inset
10891
10892 , multiplication
10893 \begin_inset LatexCommand \index{Multiplication}
10894
10895 \end_inset
10896
10897  & modulus
10898 \begin_inset LatexCommand \index{Modulus}
10899
10900 \end_inset
10901
10902  and floating-point
10903 \begin_inset LatexCommand \index{Floating point support}
10904
10905 \end_inset
10906
10907  operations are implemented using external support routines developed in
10908  ANSI-C.
10909  If an interrupt service routine needs to do any of these operations then
10910  the support routines (as mentioned in a following section) will have to
10911  be recompiled using the
10912 \emph on
10913  -
10914 \begin_inset ERT
10915 status Collapsed
10916
10917 \layout Standard
10918
10919 \backslash
10920 /
10921 \end_inset
10922
10923 -stack-auto
10924 \begin_inset LatexCommand \index{-\/-stack-auto}
10925
10926 \end_inset
10927
10928
10929 \emph default
10930  option and the source file will need to be compiled using the
10931 \emph on
10932 -
10933 \begin_inset ERT
10934 status Collapsed
10935
10936 \layout Standard
10937
10938 \backslash
10939 /
10940 \end_inset
10941
10942 -int-long-reent
10943 \emph default
10944
10945 \begin_inset LatexCommand \index{-\/-int-long-reent}
10946
10947 \end_inset
10948
10949  compiler option.
10950 \layout Standard
10951
10952 Calling other functions from an interrupt service routine is not recommended,
10953  avoid it if possible.
10954  Note that when some function is called from an interrupt service routine
10955  it should be preceded by a #pragma\SpecialChar ~
10956 nooverlay
10957 \begin_inset LatexCommand \index{\#pragma nooverlay}
10958
10959 \end_inset
10960
10961  if it is not reentrant.
10962  Furthermore nonreentrant functions should not be called from the main program
10963  while the interrupt service routine might be active.
10964  They also must not be called from low priority interrupt service routines
10965  while a high priority interrupt service routine might be active.
10966  You could use semaphores or make the function
10967 \emph on
10968  critical
10969 \emph default
10970  if all parameters are passed in registers.
10971 \newline
10972
10973 \newline
10974 Also see section
10975 \begin_inset LatexCommand \ref{sub:Overlaying}
10976
10977 \end_inset
10978
10979 \SpecialChar ~
10980 about Overlaying and section
10981 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
10982
10983 \end_inset
10984
10985 \SpecialChar ~
10986 about Functions using private register banks.
10987 \layout Subsection
10988
10989 MCS51/DS390 Interrupt Service Routines
10990 \layout Standard
10991
10992 Interrupt numbers and the corresponding address & descriptions for the Standard
10993  8051/8052 are listed below.
10994  SDCC will automatically adjust the interrupt vector table to the maximum
10995  interrupt number specified.
10996 \newline
10997
10998 \layout Standard
10999 \align center
11000
11001 \begin_inset  Tabular
11002 <lyxtabular version="3" rows="7" columns="3">
11003 <features>
11004 <column alignment="center" valignment="top" leftline="true" width="0in">
11005 <column alignment="center" valignment="top" leftline="true" width="0in">
11006 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
11007 <row topline="true" bottomline="true">
11008 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11009 \begin_inset Text
11010
11011 \layout Standard
11012
11013 Interrupt #
11014 \end_inset
11015 </cell>
11016 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11017 \begin_inset Text
11018
11019 \layout Standard
11020
11021 Description
11022 \end_inset
11023 </cell>
11024 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11025 \begin_inset Text
11026
11027 \layout Standard
11028
11029 Vector Address
11030 \end_inset
11031 </cell>
11032 </row>
11033 <row topline="true">
11034 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11035 \begin_inset Text
11036
11037 \layout Standard
11038
11039 0
11040 \end_inset
11041 </cell>
11042 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11043 \begin_inset Text
11044
11045 \layout Standard
11046
11047 External 0
11048 \end_inset
11049 </cell>
11050 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11051 \begin_inset Text
11052
11053 \layout Standard
11054
11055 0x0003
11056 \end_inset
11057 </cell>
11058 </row>
11059 <row topline="true">
11060 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11061 \begin_inset Text
11062
11063 \layout Standard
11064
11065 1
11066 \end_inset
11067 </cell>
11068 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11069 \begin_inset Text
11070
11071 \layout Standard
11072
11073 Timer 0
11074 \end_inset
11075 </cell>
11076 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11077 \begin_inset Text
11078
11079 \layout Standard
11080
11081 0x000B
11082 \end_inset
11083 </cell>
11084 </row>
11085 <row topline="true">
11086 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11087 \begin_inset Text
11088
11089 \layout Standard
11090
11091 2
11092 \end_inset
11093 </cell>
11094 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11095 \begin_inset Text
11096
11097 \layout Standard
11098
11099 External 1
11100 \end_inset
11101 </cell>
11102 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11103 \begin_inset Text
11104
11105 \layout Standard
11106
11107 0x0013
11108 \end_inset
11109 </cell>
11110 </row>
11111 <row topline="true">
11112 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11113 \begin_inset Text
11114
11115 \layout Standard
11116
11117 3
11118 \end_inset
11119 </cell>
11120 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11121 \begin_inset Text
11122
11123 \layout Standard
11124
11125 Timer 1
11126 \end_inset
11127 </cell>
11128 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11129 \begin_inset Text
11130
11131 \layout Standard
11132
11133 0x001B
11134 \end_inset
11135 </cell>
11136 </row>
11137 <row topline="true">
11138 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11139 \begin_inset Text
11140
11141 \layout Standard
11142
11143 4
11144 \end_inset
11145 </cell>
11146 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11147 \begin_inset Text
11148
11149 \layout Standard
11150
11151 Serial
11152 \end_inset
11153 </cell>
11154 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11155 \begin_inset Text
11156
11157 \layout Standard
11158
11159 0x0023
11160 \end_inset
11161 </cell>
11162 </row>
11163 <row topline="true" bottomline="true">
11164 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11165 \begin_inset Text
11166
11167 \layout Standard
11168
11169 5
11170 \end_inset
11171 </cell>
11172 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11173 \begin_inset Text
11174
11175 \layout Standard
11176
11177 Timer 2 (8052)
11178 \end_inset
11179 </cell>
11180 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11181 \begin_inset Text
11182
11183 \layout Standard
11184
11185 0x002B
11186 \end_inset
11187 </cell>
11188 </row>
11189 </lyxtabular>
11190
11191 \end_inset
11192
11193
11194 \newline
11195
11196 \layout Standard
11197
11198 If the interrupt service routine is defined without
11199 \emph on
11200 using
11201 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11202
11203 \end_inset
11204
11205
11206 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11207
11208 \end_inset
11209
11210
11211 \emph default
11212  a register bank or with register bank 0 (
11213 \emph on
11214 using
11215 \emph default
11216  0), the compiler will save the registers used by itself on the stack upon
11217  entry and restore them at exit, however if such an interrupt service routine
11218  calls another function then the entire register bank will be saved on the
11219  stack.
11220  This scheme may be advantageous for small interrupt service routines which
11221  have low register usage.
11222 \layout Standard
11223
11224 If the interrupt service routine is defined to be using a specific register
11225  bank then only
11226 \emph on
11227 a, b, dptr
11228 \emph default
11229  & psw are saved and restored, if such an interrupt service routine calls
11230  another function (using another register bank) then the entire register
11231  bank of the called function will be saved on the stack.
11232  This scheme is recommended for larger interrupt service routines.
11233 \layout Subsection
11234
11235 HC08 Interrupt Service Routines
11236 \layout Standard
11237
11238 Since the number of interrupts available is chip specific and the interrupt
11239  vector table always ends at the last byte of memory, the interrupt numbers
11240  corresponds to the interrupt vectors in reverse order of address.
11241  For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
11242  2 will use the interrupt vector at 0xfffa, and so on.
11243  However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
11244  this way; instead see section
11245 \begin_inset LatexCommand \ref{sub:Startup-Code}
11246
11247 \end_inset
11248
11249  for details on customizing startup.
11250 \layout Subsection
11251
11252 Z80 Interrupt Service Routines
11253 \layout Standard
11254
11255 The Z80 uses several different methods for determining the correct interrupt
11256  vector depending on the hardware implementation.
11257  Therefore, SDCC ignores the optional interrupt number and does not attempt
11258  to generate an interrupt vector table.
11259 \layout Standard
11260
11261 By default, SDCC generates code for a maskable interrupt, which uses an
11262  RETI instruction to return from the interrupt.
11263  To write an interrupt handler for the non-maskable interrupt, which needs
11264  an RETN instruction instead, add the
11265 \emph on
11266 critical
11267 \emph default
11268  keyword:
11269 \layout Verse
11270
11271
11272 \family typewriter
11273 void nmi_isr (void) critical interrupt
11274 \newline
11275 {
11276 \newline
11277 \SpecialChar ~
11278 \SpecialChar ~
11279 \SpecialChar ~
11280 \SpecialChar ~
11281 ...
11282
11283 \newline
11284 }
11285 \layout Section
11286
11287 Enabling and Disabling Interrupts
11288 \layout Subsection
11289
11290 Critical Functions and Critical Statements
11291 \layout Standard
11292
11293 A special keyword may be associated with a block or a function declaring
11294  it as
11295 \emph on
11296 critical
11297 \emph default
11298 .
11299  SDCC will generate code to disable all interrupts
11300 \begin_inset LatexCommand \index{interrupt}
11301
11302 \end_inset
11303
11304  upon entry to a critical function and restore the interrupt enable to the
11305  previous state before returning.
11306  Nesting critical functions will need one additional byte on the stack
11307 \begin_inset LatexCommand \index{stack}
11308
11309 \end_inset
11310
11311  for each call.
11312 \layout Verse
11313
11314
11315 \family typewriter
11316 int foo () critical
11317 \begin_inset LatexCommand \index{critical}
11318
11319 \end_inset
11320
11321
11322 \begin_inset LatexCommand \index{\_\_critical}
11323
11324 \end_inset
11325
11326
11327 \newline
11328 {
11329 \newline
11330 \SpecialChar ~
11331 \SpecialChar ~
11332 \SpecialChar ~
11333 \SpecialChar ~
11334 ...
11335
11336 \newline
11337 \SpecialChar ~
11338 \SpecialChar ~
11339 \SpecialChar ~
11340 \SpecialChar ~
11341 ...
11342
11343 \newline
11344 }
11345 \layout Standard
11346
11347 The critical attribute maybe used with other attributes like
11348 \emph on
11349 reentrant.
11350 \emph default
11351
11352 \newline
11353 The keyword
11354 \emph on
11355 critical
11356 \emph default
11357  may also be used to disable interrupts more locally:
11358 \layout Verse
11359
11360
11361 \family typewriter
11362 critical{ i++; }
11363 \layout Standard
11364
11365 More than one statement could have been included in the block.
11366 \layout Subsection
11367
11368 Enabling and Disabling Interrupts directly
11369 \layout Standard
11370
11371 Interrupts
11372 \begin_inset LatexCommand \index{interrupt}
11373
11374 \end_inset
11375
11376  can also be disabled and enabled directly (8051):
11377 \layout Verse
11378
11379
11380 \family typewriter
11381 EA = 0;\SpecialChar ~
11382 \SpecialChar ~
11383 \SpecialChar ~
11384 \SpecialChar ~
11385 \SpecialChar ~
11386 \SpecialChar ~
11387 \SpecialChar ~
11388 \SpecialChar ~
11389 \SpecialChar ~
11390 \SpecialChar ~
11391 \SpecialChar ~
11392 \SpecialChar ~
11393 or:\SpecialChar ~
11394 \SpecialChar ~
11395 \SpecialChar ~
11396 \SpecialChar ~
11397 \SpecialChar ~
11398 \SpecialChar ~
11399 \SpecialChar ~
11400 \SpecialChar ~
11401 \SpecialChar ~
11402 \SpecialChar ~
11403 \SpecialChar ~
11404 EA_SAVE = EA;
11405 \layout Verse
11406
11407
11408 \family typewriter
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 \SpecialChar ~
11429 \SpecialChar ~
11430 \SpecialChar ~
11431 \SpecialChar ~
11432 \SpecialChar ~
11433 \SpecialChar ~
11434 \SpecialChar ~
11435 \SpecialChar ~
11436 \SpecialChar ~
11437 \SpecialChar ~
11438 \SpecialChar ~
11439 EA = 0;
11440 \layout Verse
11441
11442
11443 \family typewriter
11444 EA = 1;\SpecialChar ~
11445 \SpecialChar ~
11446 \SpecialChar ~
11447 \SpecialChar ~
11448 \SpecialChar ~
11449 \SpecialChar ~
11450 \SpecialChar ~
11451 \SpecialChar ~
11452 \SpecialChar ~
11453 \SpecialChar ~
11454 \SpecialChar ~
11455 \SpecialChar ~
11456 \SpecialChar ~
11457 \SpecialChar ~
11458 \SpecialChar ~
11459 \SpecialChar ~
11460 \SpecialChar ~
11461 \SpecialChar ~
11462 \SpecialChar ~
11463 \SpecialChar ~
11464 \SpecialChar ~
11465 \SpecialChar ~
11466 \SpecialChar ~
11467 \SpecialChar ~
11468 \SpecialChar ~
11469 \SpecialChar ~
11470 ...
11471 \layout Verse
11472
11473
11474 \family typewriter
11475 \SpecialChar ~
11476 \SpecialChar ~
11477 \SpecialChar ~
11478 \SpecialChar ~
11479 \SpecialChar ~
11480 \SpecialChar ~
11481 \SpecialChar ~
11482 \SpecialChar ~
11483 \SpecialChar ~
11484 \SpecialChar ~
11485 \SpecialChar ~
11486 \SpecialChar ~
11487 \SpecialChar ~
11488 \SpecialChar ~
11489 \SpecialChar ~
11490 \SpecialChar ~
11491 \SpecialChar ~
11492 \SpecialChar ~
11493 \SpecialChar ~
11494 \SpecialChar ~
11495 \SpecialChar ~
11496 \SpecialChar ~
11497 \SpecialChar ~
11498 \SpecialChar ~
11499 \SpecialChar ~
11500 \SpecialChar ~
11501 \SpecialChar ~
11502 \SpecialChar ~
11503 \SpecialChar ~
11504 \SpecialChar ~
11505 \SpecialChar ~
11506 \SpecialChar ~
11507 \SpecialChar ~
11508 EA = EA_SAVE;
11509 \layout Standard
11510
11511 On other architectures which have seperate opcodes for enabling and disabling
11512  interrupts you might want to make use of defines with inline assembly
11513 \begin_inset LatexCommand \index{Assembler routines}
11514
11515 \end_inset
11516
11517  (HC08):
11518 \layout Verse
11519
11520
11521 \family typewriter
11522 #define CLI _asm
11523 \begin_inset LatexCommand \index{\_asm}
11524
11525 \end_inset
11526
11527 \SpecialChar ~
11528 \SpecialChar ~
11529 cli\SpecialChar ~
11530 \SpecialChar ~
11531 _endasm
11532 \begin_inset LatexCommand \index{\_endasm}
11533
11534 \end_inset
11535
11536 ;
11537 \layout Verse
11538
11539
11540 \family typewriter
11541 #define SEI _asm\SpecialChar ~
11542 \SpecialChar ~
11543 sei\SpecialChar ~
11544 \SpecialChar ~
11545 _endasm;
11546 \layout Verse
11547
11548
11549 \family typewriter
11550 ...
11551 \layout Standard
11552
11553 Note: it is sometimes sufficient to disable only a specific interrupt source
11554  like f.e.
11555  a timer or serial interrupt by manipulating an
11556 \emph on
11557 interrupt mask
11558 \begin_inset LatexCommand \index{interrupt mask}
11559
11560 \end_inset
11561
11562
11563 \emph default
11564  register.
11565
11566 \layout Standard
11567
11568 Usually the time during which interrupts are disabled should be kept as
11569  short as possible.
11570  This minimizes both
11571 \emph on
11572 interrupt latency
11573 \emph default
11574
11575 \begin_inset LatexCommand \index{interrupt latency}
11576
11577 \end_inset
11578
11579  (the time between the occurrence of the interrupt and the execution of
11580  the first code in the interrupt routine) and
11581 \emph on
11582 interrupt jitter
11583 \emph default
11584
11585 \begin_inset LatexCommand \index{interrupt jitter}
11586
11587 \end_inset
11588
11589  (the difference between the shortest and the longest interrupt latency).
11590  These really are something different, f.e.
11591  a serial interrupt has to be served before its buffer overruns so it cares
11592  for the maximum interrupt latency, whereas it does not care about jitter.
11593  On a loudspeaker driven via a digital to analog converter which is fed
11594  by an interrupt a latency of a few milliseconds might be tolerable, whereas
11595  a much smaller jitter will be very audible.
11596 \layout Standard
11597
11598 You can reenable interrupts within an interrupt routine and on some architecture
11599 s you can make use of two (or more) levels of
11600 \emph on
11601 interrupt priorities
11602 \emph default
11603
11604 \begin_inset LatexCommand \index{interrupt priority}
11605
11606 \end_inset
11607
11608 .
11609  On some architectures which don't support interrupt priorities these can
11610  be implemented by manipulating the interrupt mask and reenabling interrupts
11611  within the interrupt routine.
11612  Check there is sufficient space on the stack
11613 \begin_inset LatexCommand \index{stack}
11614
11615 \end_inset
11616
11617  and don't add complexity unless you have to.
11618
11619 \layout Subsection
11620
11621 Semaphore
11622 \begin_inset LatexCommand \index{semaphore}
11623
11624 \end_inset
11625
11626  locking (mcs51/ds390)
11627 \layout Standard
11628
11629 Some architectures (mcs51/ds390) have an atomic
11630 \begin_inset LatexCommand \index{atomic}
11631
11632 \end_inset
11633
11634  bit test and
11635 \emph on
11636
11637 \emph default
11638 clear
11639 \emph on
11640
11641 \emph default
11642 instruction.
11643  These type of instructions are typically used in preemptive multitasking
11644  systems, where a routine f.e.
11645  claims the use of a data structure ('acquires a lock
11646 \begin_inset LatexCommand \index{lock}
11647
11648 \end_inset
11649
11650  on it'), makes some modifications and then releases the lock when the data
11651  structure is consistent again.
11652  The instruction may also be used if interrupt and non-interrupt code have
11653  to compete for a resource.
11654  With the atomic bit test and clear instruction interrupts
11655 \begin_inset LatexCommand \index{interrupt}
11656
11657 \end_inset
11658
11659  don't have to be disabled for the locking operation.
11660
11661 \layout Standard
11662
11663 SDCC generates this instruction if the source follows this pattern:
11664 \layout Verse
11665
11666
11667 \family typewriter
11668 volatile
11669 \begin_inset LatexCommand \index{volatile}
11670
11671 \end_inset
11672
11673  bit resource_is_free;
11674 \newline
11675
11676 \newline
11677 if (resource_is_free)
11678 \newline
11679 \SpecialChar ~
11680 \SpecialChar ~
11681 {
11682 \newline
11683 \SpecialChar ~
11684 \SpecialChar ~
11685 \SpecialChar ~
11686 \SpecialChar ~
11687 resource_is_free=0;
11688 \newline
11689 \SpecialChar ~
11690 \SpecialChar ~
11691 \SpecialChar ~
11692 \SpecialChar ~
11693 ...
11694
11695 \newline
11696 \SpecialChar ~
11697 \SpecialChar ~
11698 \SpecialChar ~
11699 \SpecialChar ~
11700 resource_is_free=1;
11701 \newline
11702 \SpecialChar ~
11703 \SpecialChar ~
11704 }
11705 \layout Standard
11706
11707 Note, mcs51 and ds390 support only an atomic
11708 \begin_inset LatexCommand \index{atomic}
11709
11710 \end_inset
11711
11712  bit test and
11713 \emph on
11714 clear
11715 \emph default
11716  instruction (as opposed to atomic bit test and
11717 \emph on
11718 set).
11719 \layout Section
11720
11721 Functions using private register banks
11722 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
11723
11724 \end_inset
11725
11726  (mcs51/ds390)
11727 \layout Standard
11728
11729 Some architectures have support for quickly changing register sets.
11730  SDCC supports this feature with the
11731 \emph on
11732 using
11733 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11734
11735 \end_inset
11736
11737
11738 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11739
11740 \end_inset
11741
11742
11743 \emph default
11744  attribute (which tells the compiler to use a register bank
11745 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
11746
11747 \end_inset
11748
11749  other than the default bank zero).
11750  It should only be applied to
11751 \emph on
11752 interrupt
11753 \begin_inset LatexCommand \index{interrupt}
11754
11755 \end_inset
11756
11757
11758 \emph default
11759  functions (see footnote below).
11760  This will in most circumstances make the generated ISR code more efficient
11761  since it will not have to save registers on the stack.
11762 \layout Standard
11763
11764 The
11765 \emph on
11766 using
11767 \emph default
11768  attribute will have no effect on the generated code for a
11769 \emph on
11770 non-interrupt
11771 \emph default
11772  function (but may occasionally be useful anyway
11773 \begin_inset Foot
11774 collapsed false
11775
11776 \layout Standard
11777
11778 possible exception: if a function is called ONLY from 'interrupt' functions
11779  using a particular bank, it can be declared with the same 'using' attribute
11780  as the calling 'interrupt' functions.
11781  For instance, if you have several ISRs using bank one, and all of them
11782  call memcpy(), it might make sense to create a specialized version of memcpy()
11783  'using 1', since this would prevent the ISR from having to save bank zero
11784  to the stack on entry and switch to bank zero before calling the function
11785 \end_inset
11786
11787 ).
11788 \newline
11789
11790 \emph on
11791 (pending: I don't think this has been done yet)
11792 \layout Standard
11793
11794 An
11795 \emph on
11796 interrupt
11797 \emph default
11798  function using a non-zero bank will assume that it can trash that register
11799  bank, and will not save it.
11800  Since high-priority interrupts
11801 \begin_inset LatexCommand \index{interrupts}
11802
11803 \end_inset
11804
11805
11806 \begin_inset LatexCommand \index{interrupt priority}
11807
11808 \end_inset
11809
11810  can interrupt low-priority ones on the 8051 and friends, this means that
11811  if a high-priority ISR
11812 \emph on
11813 using
11814 \emph default
11815  a particular bank occurs while processing a low-priority ISR
11816 \emph on
11817 using
11818 \emph default
11819  the same bank, terrible and bad things can happen.
11820  To prevent this, no single register bank should be
11821 \emph on
11822 used
11823 \emph default
11824  by both a high priority and a low priority ISR.
11825  This is probably most easily done by having all high priority ISRs use
11826  one bank and all low priority ISRs use another.
11827  If you have an ISR which can change priority at runtime, you're on your
11828  own: I suggest using the default bank zero and taking the small performance
11829  hit.
11830 \layout Standard
11831
11832 It is most efficient if your ISR calls no other functions.
11833  If your ISR must call other functions, it is most efficient if those functions
11834  use the same bank as the ISR (see note 1 below); the next best is if the
11835  called functions use bank zero.
11836  It is very inefficient to call a function using a different, non-zero bank
11837  from an ISR.
11838
11839 \layout Section
11840
11841 Startup Code
11842 \begin_inset LatexCommand \label{sub:Startup-Code}
11843
11844 \end_inset
11845
11846
11847 \begin_inset LatexCommand \index{Startup code}
11848
11849 \end_inset
11850
11851
11852 \layout Subsection
11853
11854 MCS51/DS390 Startup Code
11855 \layout Standard
11856
11857 The compiler inserts a call to the C routine
11858 \emph on
11859 _sdcc_external_startup()
11860 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
11861
11862 \end_inset
11863
11864
11865 \series bold
11866 \emph default
11867
11868 \series default
11869 at the start of the CODE area.
11870  This routine is in the runtime library
11871 \begin_inset LatexCommand \index{Runtime library}
11872
11873 \end_inset
11874
11875 .
11876  By default this routine returns 0, if this routine returns a non-zero value,
11877  the static & global variable initialization will be skipped and the function
11878  main will be invoked.
11879  Otherwise static & global variables will be initialized before the function
11880  main is invoked.
11881  You could add a
11882 \emph on
11883 _sdcc_external_startup()
11884 \emph default
11885  routine to your program to override the default if you need to setup hardware
11886  or perform some other critical operation prior to static & global variable
11887  initialization
11888 \begin_inset LatexCommand \index{Variable initialization}
11889
11890 \end_inset
11891
11892 .
11893  On some mcs51 variants xdata
11894 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
11895
11896 \end_inset
11897
11898  memory has to be explicitly enabled before it can be accessed or if the
11899  watchdog needs to be disabled, this is the place to do it.
11900  The startup code clears all internal data memory, 256 bytes by default,
11901  but from 0 to n-1 if
11902 \emph on
11903 -
11904 \begin_inset ERT
11905 status Collapsed
11906
11907 \layout Standard
11908
11909 \backslash
11910 /
11911 \end_inset
11912
11913 -iram-size
11914 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
11915
11916 \end_inset
11917
11918 n
11919 \emph default
11920  is used.
11921  (recommended for Chipcon CC1010).
11922 \layout Standard
11923
11924 See also the compiler option
11925 \emph on
11926 -
11927 \begin_inset ERT
11928 status Collapsed
11929
11930 \layout Standard
11931
11932 \backslash
11933 /
11934 \end_inset
11935
11936 -no-xinit
11937 \emph default
11938 -
11939 \emph on
11940 opt
11941 \emph default
11942
11943 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
11944
11945 \end_inset
11946
11947  and section
11948 \begin_inset LatexCommand \ref{sub:MCS51-variants}
11949
11950 \end_inset
11951
11952 \SpecialChar ~
11953 about MCS51-variants.
11954 \layout Subsection
11955
11956 HC08 Startup Code
11957 \layout Standard
11958
11959 The HC08 startup code follows the same scheme as the MCS51 startup code.
11960 \layout Subsection
11961
11962 Z80 Startup Code
11963 \layout Standard
11964
11965 On the Z80 the startup code is inserted by linking with crt0.o which is generated
11966  from sdcc/device/lib/z80/crt0.s.
11967  If you need a different startup code you can use the compiler option
11968 \emph on
11969 -
11970 \series bold
11971 \emph default
11972
11973 \begin_inset ERT
11974 status Collapsed
11975
11976 \layout Standard
11977
11978 \backslash
11979 /
11980 \end_inset
11981
11982
11983 \series default
11984 \emph on
11985 -no-std-crt0
11986 \emph default
11987
11988 \begin_inset LatexCommand \index{-\/-no-std-crt0}
11989
11990 \end_inset
11991
11992  and provide your own crt0.o.
11993
11994 \layout Section
11995
11996 Inline Assembler Code
11997 \begin_inset LatexCommand \index{Assembler routines}
11998
11999 \end_inset
12000
12001
12002 \layout Subsection
12003
12004 A Step by Step Introduction
12005 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
12006
12007 \end_inset
12008
12009
12010 \layout Standard
12011
12012 Starting from a small snippet of c-code this example shows for the MCS51
12013  how to use inline assembly, access variables, a function parameter and
12014  an array in xdata memory.
12015  The example uses an MCS51 here but is easily adapted for other architectures.
12016  This is a buffer routine which should be optimized:
12017 \layout Verse
12018
12019
12020 \family typewriter
12021 \size footnotesize
12022 unsigned char far
12023 \begin_inset LatexCommand \index{far (storage class)}
12024
12025 \end_inset
12026
12027
12028 \begin_inset LatexCommand \index{\_\_far (storage class)}
12029
12030 \end_inset
12031
12032  at
12033 \begin_inset LatexCommand \index{at}
12034
12035 \end_inset
12036
12037
12038 \begin_inset LatexCommand \index{\_\_at}
12039
12040 \end_inset
12041
12042  0x7f00 buf[0x100];
12043 \begin_inset LatexCommand \index{Aligned array}
12044
12045 \end_inset
12046
12047
12048 \newline
12049 unsigned char head,tail;
12050 \newline
12051
12052 \newline
12053 void to_buffer( unsigned char c )
12054 \newline
12055 {
12056 \newline
12057 \SpecialChar ~
12058 \SpecialChar ~
12059 \SpecialChar ~
12060 \SpecialChar ~
12061 if( head != tail-1 )
12062 \newline
12063 \SpecialChar ~
12064 \SpecialChar ~
12065 \SpecialChar ~
12066 \SpecialChar ~
12067 \SpecialChar ~
12068 \SpecialChar ~
12069 \SpecialChar ~
12070 \SpecialChar ~
12071 buf[ head++ ] = c;\SpecialChar ~
12072 \SpecialChar ~
12073 \SpecialChar ~
12074 \SpecialChar ~
12075 /* access to a 256 byte aligned array */
12076 \newline
12077 }
12078 \layout Standard
12079
12080 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
12081  then a corresponding buffer.asm file is generated.
12082  We define a new function
12083 \family typewriter
12084 to_buffer_asm()
12085 \family default
12086  in file buffer.c in which we cut and paste the generated code, removing
12087  unwanted comments and some ':'.
12088  Then add
12089 \begin_inset Quotes sld
12090 \end_inset
12091
12092 _asm
12093 \begin_inset Quotes srd
12094 \end_inset
12095
12096  and
12097 \begin_inset Quotes sld
12098 \end_inset
12099
12100 _endasm;
12101 \begin_inset Quotes srd
12102 \end_inset
12103
12104  to the beginning and the end of the function body:
12105 \layout Verse
12106
12107
12108 \family typewriter
12109 \size footnotesize
12110 /* With a cut and paste from the .asm file, we have something to start with.
12111 \newline
12112 \SpecialChar ~
12113 \SpecialChar ~
12114 \SpecialChar ~
12115 The function is not yet OK! (registers aren't saved) */
12116 \newline
12117 void to_buffer_asm( unsigned char c )
12118 \newline
12119 {
12120 \newline
12121 \SpecialChar ~
12122 \SpecialChar ~
12123 \SpecialChar ~
12124 \SpecialChar ~
12125 _asm
12126 \begin_inset LatexCommand \index{\_asm}
12127
12128 \end_inset
12129
12130
12131 \begin_inset LatexCommand \index{\_\_asm}
12132
12133 \end_inset
12134
12135
12136 \newline
12137 \SpecialChar ~
12138 \SpecialChar ~
12139 \SpecialChar ~
12140 \SpecialChar ~
12141 mov\SpecialChar ~
12142 \SpecialChar ~
12143 r2,dpl
12144 \newline
12145 ;buffer.c if( head != tail-1 )
12146 \newline
12147 \SpecialChar ~
12148 \SpecialChar ~
12149 \SpecialChar ~
12150 \SpecialChar ~
12151 mov\SpecialChar ~
12152 \SpecialChar ~
12153 a,_tail
12154 \newline
12155 \SpecialChar ~
12156 \SpecialChar ~
12157 \SpecialChar ~
12158 \SpecialChar ~
12159 dec\SpecialChar ~
12160 \SpecialChar ~
12161 a
12162 \newline
12163 \SpecialChar ~
12164 \SpecialChar ~
12165 \SpecialChar ~
12166 \SpecialChar ~
12167 mov\SpecialChar ~
12168 \SpecialChar ~
12169 r3,a
12170 \newline
12171 \SpecialChar ~
12172 \SpecialChar ~
12173 \SpecialChar ~
12174 \SpecialChar ~
12175 mov\SpecialChar ~
12176 \SpecialChar ~
12177 a,_head
12178 \newline
12179 \SpecialChar ~
12180 \SpecialChar ~
12181 \SpecialChar ~
12182 \SpecialChar ~
12183 cjne a,ar3,00106$
12184 \newline
12185 \SpecialChar ~
12186 \SpecialChar ~
12187 \SpecialChar ~
12188 \SpecialChar ~
12189 ret
12190 \newline
12191 00106$:
12192 \newline
12193 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
12194 \begin_inset LatexCommand \index{Aligned array}
12195
12196 \end_inset
12197
12198
12199 \newline
12200 \SpecialChar ~
12201 \SpecialChar ~
12202 \SpecialChar ~
12203 \SpecialChar ~
12204 mov\SpecialChar ~
12205 \SpecialChar ~
12206 r3,_head
12207 \newline
12208 \SpecialChar ~
12209 \SpecialChar ~
12210 \SpecialChar ~
12211 \SpecialChar ~
12212 inc\SpecialChar ~
12213 \SpecialChar ~
12214 _head
12215 \newline
12216 \SpecialChar ~
12217 \SpecialChar ~
12218 \SpecialChar ~
12219 \SpecialChar ~
12220 mov\SpecialChar ~
12221 \SpecialChar ~
12222 dpl,r3
12223 \newline
12224 \SpecialChar ~
12225 \SpecialChar ~
12226 \SpecialChar ~
12227 \SpecialChar ~
12228 mov\SpecialChar ~
12229 \SpecialChar ~
12230 dph,#(_buf >> 8)
12231 \newline
12232 \SpecialChar ~
12233 \SpecialChar ~
12234 \SpecialChar ~
12235 \SpecialChar ~
12236 mov\SpecialChar ~
12237 \SpecialChar ~
12238 a,r2
12239 \newline
12240 \SpecialChar ~
12241 \SpecialChar ~
12242 \SpecialChar ~
12243 \SpecialChar ~
12244 movx @dptr,a
12245 \newline
12246 00103$:
12247 \newline
12248 \SpecialChar ~
12249 \SpecialChar ~
12250 \SpecialChar ~
12251 \SpecialChar ~
12252 ret
12253 \newline
12254 \SpecialChar ~
12255 \SpecialChar ~
12256 \SpecialChar ~
12257 \SpecialChar ~
12258 _endasm
12259 \begin_inset LatexCommand \index{\_endasm}
12260
12261 \end_inset
12262
12263
12264 \begin_inset LatexCommand \index{\_\_endasm}
12265
12266 \end_inset
12267
12268 ;
12269 \newline
12270 }
12271 \layout Standard
12272
12273 The new file buffer.c should compile with only one warning about the unreferenced
12274  function argument 'c'.
12275  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
12276  (1) and finally have:
12277 \layout Verse
12278
12279
12280 \family typewriter
12281 \size footnotesize
12282 unsigned char far at 0x7f00 buf[0x100];
12283 \newline
12284 unsigned char head,tail;
12285 \newline
12286 #define USE_ASSEMBLY (1)
12287 \newline
12288
12289 \newline
12290 #if !USE_ASSEMBLY
12291 \newline
12292
12293 \newline
12294 void to_buffer( unsigned char c )
12295 \newline
12296 {
12297 \newline
12298 \SpecialChar ~
12299 \SpecialChar ~
12300 \SpecialChar ~
12301 \SpecialChar ~
12302 if( head != tail-1 )
12303 \newline
12304 \SpecialChar ~
12305 \SpecialChar ~
12306 \SpecialChar ~
12307 \SpecialChar ~
12308 \SpecialChar ~
12309 \SpecialChar ~
12310 \SpecialChar ~
12311 \SpecialChar ~
12312 buf[ head++ ] = c;
12313 \newline
12314 }
12315 \newline
12316
12317 \newline
12318 #else
12319 \newline
12320
12321 \newline
12322 void to_buffer( unsigned char c )
12323 \newline
12324 {
12325 \newline
12326 \SpecialChar ~
12327 \SpecialChar ~
12328 \SpecialChar ~
12329 \SpecialChar ~
12330 c; // to avoid warning: unreferenced function argument
12331 \newline
12332 \SpecialChar ~
12333 \SpecialChar ~
12334 \SpecialChar ~
12335 \SpecialChar ~
12336 _asm
12337 \begin_inset LatexCommand \index{\_asm}
12338
12339 \end_inset
12340
12341
12342 \begin_inset LatexCommand \index{\_\_asm}
12343
12344 \end_inset
12345
12346
12347 \newline
12348 \SpecialChar ~
12349 \SpecialChar ~
12350 \SpecialChar ~
12351 \SpecialChar ~
12352 \SpecialChar ~
12353 \SpecialChar ~
12354 \SpecialChar ~
12355 \SpecialChar ~
12356 ; save used registers here.
12357
12358 \newline
12359 \SpecialChar ~
12360 \SpecialChar ~
12361 \SpecialChar ~
12362 \SpecialChar ~
12363 \SpecialChar ~
12364 \SpecialChar ~
12365 \SpecialChar ~
12366 \SpecialChar ~
12367 ; If we were still using r2,r3 we would have to push them here.
12368
12369 \newline
12370 ; if( head != tail-1 )
12371 \newline
12372 \SpecialChar ~
12373 \SpecialChar ~
12374 \SpecialChar ~
12375 \SpecialChar ~
12376 \SpecialChar ~
12377 \SpecialChar ~
12378 \SpecialChar ~
12379 \SpecialChar ~
12380 mov\SpecialChar ~
12381  a,_tail
12382 \newline
12383 \SpecialChar ~
12384 \SpecialChar ~
12385 \SpecialChar ~
12386 \SpecialChar ~
12387 \SpecialChar ~
12388 \SpecialChar ~
12389 \SpecialChar ~
12390 \SpecialChar ~
12391 dec\SpecialChar ~
12392  a
12393 \newline
12394 \SpecialChar ~
12395 \SpecialChar ~
12396 \SpecialChar ~
12397 \SpecialChar ~
12398 \SpecialChar ~
12399 \SpecialChar ~
12400 \SpecialChar ~
12401 \SpecialChar ~
12402 xrl\SpecialChar ~
12403  a,_head
12404 \newline
12405 \SpecialChar ~
12406 \SpecialChar ~
12407 \SpecialChar ~
12408 \SpecialChar ~
12409 \SpecialChar ~
12410 \SpecialChar ~
12411 \SpecialChar ~
12412 \SpecialChar ~
12413 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
12414 \newline
12415 \SpecialChar ~
12416 \SpecialChar ~
12417 \SpecialChar ~
12418 \SpecialChar ~
12419 \SpecialChar ~
12420 \SpecialChar ~
12421 \SpecialChar ~
12422 \SpecialChar ~
12423 jz\SpecialChar ~
12424 \SpecialChar ~
12425  t_b_end$
12426 \newline
12427 \SpecialChar ~
12428 \SpecialChar ~
12429 \SpecialChar ~
12430 \SpecialChar ~
12431 \SpecialChar ~
12432 \SpecialChar ~
12433 \SpecialChar ~
12434 \SpecialChar ~
12435 ;
12436 \newline
12437 ; buf[ head++ ] = c;
12438 \newline
12439 \SpecialChar ~
12440 \SpecialChar ~
12441 \SpecialChar ~
12442 \SpecialChar ~
12443 \SpecialChar ~
12444 \SpecialChar ~
12445 \SpecialChar ~
12446 \SpecialChar ~
12447 mov\SpecialChar ~
12448  a,dpl \SpecialChar ~
12449 \SpecialChar ~
12450 \SpecialChar ~
12451 \SpecialChar ~
12452 \SpecialChar ~
12453 \SpecialChar ~
12454 \SpecialChar ~
12455 ; dpl holds lower byte of function argument
12456 \newline
12457 \SpecialChar ~
12458 \SpecialChar ~
12459 \SpecialChar ~
12460 \SpecialChar ~
12461 \SpecialChar ~
12462 \SpecialChar ~
12463 \SpecialChar ~
12464 \SpecialChar ~
12465 mov\SpecialChar ~
12466  dpl,_head \SpecialChar ~
12467 \SpecialChar ~
12468 \SpecialChar ~
12469 ; buf is 0x100 byte aligned so head can be used directly
12470 \newline
12471 \SpecialChar ~
12472 \SpecialChar ~
12473 \SpecialChar ~
12474 \SpecialChar ~
12475 \SpecialChar ~
12476 \SpecialChar ~
12477 \SpecialChar ~
12478 \SpecialChar ~
12479 mov\SpecialChar ~
12480  dph,#(_buf>>8)
12481 \newline
12482 \SpecialChar ~
12483 \SpecialChar ~
12484 \SpecialChar ~
12485 \SpecialChar ~
12486 \SpecialChar ~
12487 \SpecialChar ~
12488 \SpecialChar ~
12489 \SpecialChar ~
12490 movx @dptr,a
12491 \newline
12492 \SpecialChar ~
12493 \SpecialChar ~
12494 \SpecialChar ~
12495 \SpecialChar ~
12496 \SpecialChar ~
12497 \SpecialChar ~
12498 \SpecialChar ~
12499 \SpecialChar ~
12500 inc \SpecialChar ~
12501 _head
12502 \newline
12503 \SpecialChar ~
12504 \SpecialChar ~
12505 \SpecialChar ~
12506 \SpecialChar ~
12507 \SpecialChar ~
12508 \SpecialChar ~
12509 \SpecialChar ~
12510 \SpecialChar ~
12511 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
12512 \newline
12513 t_b_end$:
12514 \newline
12515 \SpecialChar ~
12516 \SpecialChar ~
12517 \SpecialChar ~
12518 \SpecialChar ~
12519 \SpecialChar ~
12520 \SpecialChar ~
12521 \SpecialChar ~
12522 \SpecialChar ~
12523 ; restore used registers here
12524 \newline
12525 \SpecialChar ~
12526 \SpecialChar ~
12527 \SpecialChar ~
12528 \SpecialChar ~
12529 _endasm
12530 \begin_inset LatexCommand \index{\_endasm}
12531
12532 \end_inset
12533
12534
12535 \begin_inset LatexCommand \index{\_\_endasm}
12536
12537 \end_inset
12538
12539 ;
12540 \newline
12541 }
12542 \newline
12543 #endif
12544 \layout Standard
12545
12546 The inline assembler code can contain any valid code understood by the assembler
12547 , this includes any assembler directives and comment lines
12548 \begin_inset Foot
12549 collapsed false
12550
12551 \layout Standard
12552
12553 The assembler does not like some characters like ':' or ''' in comments.
12554  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
12555 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
12556
12557 \end_inset
12558
12559
12560 \begin_inset LatexCommand \index{Assembler documentation}
12561
12562 \end_inset
12563
12564
12565 \end_inset
12566
12567 .
12568  The compiler does not do any validation of the code within the
12569 \family typewriter
12570 _asm
12571 \begin_inset LatexCommand \index{\_asm}
12572
12573 \end_inset
12574
12575
12576 \begin_inset LatexCommand \index{\_\_asm}
12577
12578 \end_inset
12579
12580  ...
12581  _endasm
12582 \size footnotesize
12583
12584 \begin_inset LatexCommand \index{\_endasm}
12585
12586 \end_inset
12587
12588
12589 \begin_inset LatexCommand \index{\_\_endasm}
12590
12591 \end_inset
12592
12593
12594 \size default
12595 ;
12596 \family default
12597  keyword pair.
12598  Specifically it will not know which registers are used and thus register
12599  pushing/popping
12600 \begin_inset LatexCommand \index{push/pop}
12601
12602 \end_inset
12603
12604  has to be done manually.
12605
12606 \layout Standard
12607
12608 It is recommended that each assembly instruction (including labels) be placed
12609  in a separate line (as the example shows).
12610  When the -
12611 \begin_inset ERT
12612 status Collapsed
12613
12614 \layout Standard
12615
12616 \backslash
12617 /
12618 \end_inset
12619
12620 -
12621 \emph on
12622 peep-asm
12623 \begin_inset LatexCommand \index{-\/-peep-asm}
12624
12625 \end_inset
12626
12627
12628 \emph default
12629  command line option is used, the inline assembler code will be passed through
12630  the peephole optimizer
12631 \begin_inset LatexCommand \index{Peephole optimizer}
12632
12633 \end_inset
12634
12635 .
12636  There are only a few (if any) cases where this option makes sense, it might
12637  cause some unexpected changes in the inline assembler code.
12638  Please go through the peephole optimizer rules defined in file
12639 \emph on
12640 SDCCpeeph.def
12641 \emph default
12642  before using this option.
12643 \layout Subsection
12644
12645 Naked Functions
12646 \begin_inset LatexCommand \label{sub:Naked-Functions}
12647
12648 \end_inset
12649
12650
12651 \begin_inset LatexCommand \index{Naked functions}
12652
12653 \end_inset
12654
12655
12656 \layout Standard
12657
12658 A special keyword may be associated with a function declaring it as
12659 \emph on
12660 _naked
12661 \begin_inset LatexCommand \index{\_naked}
12662
12663 \end_inset
12664
12665
12666 \begin_inset LatexCommand \index{\_\_naked}
12667
12668 \end_inset
12669
12670 .
12671
12672 \emph default
12673 The
12674 \emph on
12675 _naked
12676 \emph default
12677  function modifier attribute prevents the compiler from generating prologue
12678 \begin_inset LatexCommand \index{function prologue}
12679
12680 \end_inset
12681
12682  and epilogue
12683 \begin_inset LatexCommand \index{function epilogue}
12684
12685 \end_inset
12686
12687  code for that function.
12688  This means that the user is entirely responsible for such things as saving
12689  any registers that may need to be preserved, selecting the proper register
12690  bank, generating the
12691 \emph on
12692 return
12693 \emph default
12694  instruction at the end, etc.
12695  Practically, this means that the contents of the function must be written
12696  in inline assembler.
12697  This is particularly useful for interrupt functions, which can have a large
12698  (and often unnecessary) prologue/epilogue.
12699  For example, compare the code generated by these two functions:
12700 \layout Verse
12701
12702
12703 \family typewriter
12704 volatile
12705 \begin_inset LatexCommand \index{volatile}
12706
12707 \end_inset
12708
12709  data unsigned char counter;
12710 \newline
12711
12712 \newline
12713 void simpleInterrupt(void) interrupt
12714 \begin_inset LatexCommand \index{interrupt}
12715
12716 \end_inset
12717
12718
12719 \begin_inset LatexCommand \index{\_\_interrupt}
12720
12721 \end_inset
12722
12723  1
12724 \newline
12725 {
12726 \newline
12727 \SpecialChar ~
12728 \SpecialChar ~
12729 \SpecialChar ~
12730 \SpecialChar ~
12731 counter++;
12732 \newline
12733 }
12734 \newline
12735
12736 \newline
12737 void nakedInterrupt(void) interrupt 2 _naked
12738 \newline
12739 {
12740 \newline
12741 \SpecialChar ~
12742 \SpecialChar ~
12743 \SpecialChar ~
12744 \SpecialChar ~
12745 _asm
12746 \begin_inset LatexCommand \index{\_asm}
12747
12748 \end_inset
12749
12750
12751 \begin_inset LatexCommand \index{\_\_asm}
12752
12753 \end_inset
12754
12755
12756 \newline
12757 \SpecialChar ~
12758 \SpecialChar ~
12759 \SpecialChar ~
12760 \SpecialChar ~
12761 \SpecialChar ~
12762 \SpecialChar ~
12763 inc\SpecialChar ~
12764 \SpecialChar ~
12765 \SpecialChar ~
12766 \SpecialChar ~
12767 \SpecialChar ~
12768 _counter ; does not change flags, no need to save psw
12769 \newline
12770 \SpecialChar ~
12771 \SpecialChar ~
12772 \SpecialChar ~
12773 \SpecialChar ~
12774 \SpecialChar ~
12775 \SpecialChar ~
12776 reti\SpecialChar ~
12777 \SpecialChar ~
12778 \SpecialChar ~
12779 \SpecialChar ~
12780 ; MUST explicitly include ret or reti in _naked function.
12781 \newline
12782 \SpecialChar ~
12783 \SpecialChar ~
12784 \SpecialChar ~
12785 \SpecialChar ~
12786 _endasm
12787 \begin_inset LatexCommand \index{\_endasm}
12788
12789 \end_inset
12790
12791
12792 \begin_inset LatexCommand \index{\_\_endasm}
12793
12794 \end_inset
12795
12796 ;
12797 \newline
12798 }
12799 \layout Standard
12800
12801 For an 8051 target, the generated simpleInterrupt looks like:
12802 \layout Verse
12803
12804
12805 \family typewriter
12806 _simpleInterrupt:
12807 \newline
12808 \SpecialChar ~
12809 \SpecialChar ~
12810 \SpecialChar ~
12811 \SpecialChar ~
12812 push\SpecialChar ~
12813 \SpecialChar ~
12814 \SpecialChar ~
12815 \SpecialChar ~
12816 acc
12817 \newline
12818 \SpecialChar ~
12819 \SpecialChar ~
12820 \SpecialChar ~
12821 \SpecialChar ~
12822 push\SpecialChar ~
12823 \SpecialChar ~
12824 \SpecialChar ~
12825 \SpecialChar ~
12826 b
12827 \newline
12828 \SpecialChar ~
12829 \SpecialChar ~
12830 \SpecialChar ~
12831 \SpecialChar ~
12832 push\SpecialChar ~
12833 \SpecialChar ~
12834 \SpecialChar ~
12835 \SpecialChar ~
12836 dpl
12837 \newline
12838 \SpecialChar ~
12839 \SpecialChar ~
12840 \SpecialChar ~
12841 \SpecialChar ~
12842 push\SpecialChar ~
12843 \SpecialChar ~
12844 \SpecialChar ~
12845 \SpecialChar ~
12846 dph
12847 \newline
12848 \SpecialChar ~
12849 \SpecialChar ~
12850 \SpecialChar ~
12851 \SpecialChar ~
12852 push\SpecialChar ~
12853 \SpecialChar ~
12854 \SpecialChar ~
12855 \SpecialChar ~
12856 psw
12857 \newline
12858 \SpecialChar ~
12859 \SpecialChar ~
12860 \SpecialChar ~
12861 \SpecialChar ~
12862 mov\SpecialChar ~
12863 \SpecialChar ~
12864 \SpecialChar ~
12865 \SpecialChar ~
12866 \SpecialChar ~
12867 psw,#0x00
12868 \newline
12869 \SpecialChar ~
12870 \SpecialChar ~
12871 \SpecialChar ~
12872 \SpecialChar ~
12873 inc\SpecialChar ~
12874 \SpecialChar ~
12875 \SpecialChar ~
12876 \SpecialChar ~
12877 \SpecialChar ~
12878 _counter
12879 \newline
12880 \SpecialChar ~
12881 \SpecialChar ~
12882 \SpecialChar ~
12883 \SpecialChar ~
12884 pop\SpecialChar ~
12885 \SpecialChar ~
12886 \SpecialChar ~
12887 \SpecialChar ~
12888 \SpecialChar ~
12889 psw
12890 \newline
12891 \SpecialChar ~
12892 \SpecialChar ~
12893 \SpecialChar ~
12894 \SpecialChar ~
12895 pop\SpecialChar ~
12896 \SpecialChar ~
12897 \SpecialChar ~
12898 \SpecialChar ~
12899 \SpecialChar ~
12900 dph
12901 \newline
12902 \SpecialChar ~
12903 \SpecialChar ~
12904 \SpecialChar ~
12905 \SpecialChar ~
12906 pop\SpecialChar ~
12907 \SpecialChar ~
12908 \SpecialChar ~
12909 \SpecialChar ~
12910 \SpecialChar ~
12911 dpl
12912 \newline
12913 \SpecialChar ~
12914 \SpecialChar ~
12915 \SpecialChar ~
12916 \SpecialChar ~
12917 pop\SpecialChar ~
12918 \SpecialChar ~
12919 \SpecialChar ~
12920 \SpecialChar ~
12921 \SpecialChar ~
12922 b
12923 \newline
12924 \SpecialChar ~
12925 \SpecialChar ~
12926 \SpecialChar ~
12927 \SpecialChar ~
12928 pop\SpecialChar ~
12929 \SpecialChar ~
12930 \SpecialChar ~
12931 \SpecialChar ~
12932 \SpecialChar ~
12933 acc
12934 \newline
12935 \SpecialChar ~
12936 \SpecialChar ~
12937 \SpecialChar ~
12938 \SpecialChar ~
12939 reti
12940 \layout Standard
12941
12942 whereas nakedInterrupt looks like:
12943 \layout Verse
12944
12945
12946 \family typewriter
12947 _nakedInterrupt:
12948 \newline
12949 \SpecialChar ~
12950 \SpecialChar ~
12951 \SpecialChar ~
12952 \SpecialChar ~
12953 inc\SpecialChar ~
12954 \SpecialChar ~
12955 \SpecialChar ~
12956 \SpecialChar ~
12957 _counter ; does not change flags, no need to save psw
12958 \newline
12959 \SpecialChar ~
12960 \SpecialChar ~
12961 \SpecialChar ~
12962 \SpecialChar ~
12963 reti\SpecialChar ~
12964 \SpecialChar ~
12965 \SpecialChar ~
12966 \SpecialChar ~
12967 \SpecialChar ~
12968 \SpecialChar ~
12969 \SpecialChar ~
12970 \SpecialChar ~
12971 \SpecialChar ~
12972 \SpecialChar ~
12973 \SpecialChar ~
12974 \SpecialChar ~
12975 ; MUST explicitly include ret or reti in _naked function
12976 \layout Standard
12977
12978 The related directive #pragma exclude
12979 \begin_inset LatexCommand \index{\#pragma exclude}
12980
12981 \end_inset
12982
12983  allows a more fine grained control over pushing & popping
12984 \begin_inset LatexCommand \index{push/pop}
12985
12986 \end_inset
12987
12988  the registers.
12989 \layout Standard
12990
12991 While there is nothing preventing you from writing C code inside a
12992 \family typewriter
12993 _naked
12994 \family default
12995  function, there are many ways to shoot yourself in the foot doing this,
12996  and it is recommended that you stick to inline assembler.
12997 \layout Subsection
12998
12999 Use of Labels within Inline Assembler
13000 \layout Standard
13001
13002 SDCC allows the use of in-line assembler with a few restrictions regarding
13003  labels.
13004  In older versions of the compiler all labels defined within inline assembler
13005  code
13006 \emph on
13007 had to be
13008 \emph default
13009  of the form
13010 \emph on
13011 nnnnn$
13012 \emph default
13013  where nnnn is a number less than 100 (which implies a limit of utmost 100
13014  inline assembler labels
13015 \emph on
13016 per function
13017 \emph default
13018 \noun on
13019 )
13020 \noun default
13021 .
13022
13023 \layout Verse
13024
13025
13026 \family typewriter
13027 _asm
13028 \begin_inset LatexCommand \index{\_asm}
13029
13030 \end_inset
13031
13032
13033 \begin_inset LatexCommand \index{\_\_asm}
13034
13035 \end_inset
13036
13037
13038 \newline
13039 \SpecialChar ~
13040 \SpecialChar ~
13041 \SpecialChar ~
13042 \SpecialChar ~
13043 mov\SpecialChar ~
13044 \SpecialChar ~
13045 \SpecialChar ~
13046 \SpecialChar ~
13047 \SpecialChar ~
13048 b,#10
13049 \newline
13050 00001$:
13051 \newline
13052 \SpecialChar ~
13053 \SpecialChar ~
13054 \SpecialChar ~
13055 \SpecialChar ~
13056 djnz\SpecialChar ~
13057 \SpecialChar ~
13058 \SpecialChar ~
13059 \SpecialChar ~
13060 b,00001$
13061 \newline
13062 _endasm
13063 \begin_inset LatexCommand \index{\_endasm}
13064
13065 \end_inset
13066
13067
13068 \begin_inset LatexCommand \index{\_\_endasm}
13069
13070 \end_inset
13071
13072  ;
13073 \layout Standard
13074
13075 Inline assembler code cannot reference any C-Labels, however it can reference
13076  labels
13077 \begin_inset LatexCommand \index{Labels}
13078
13079 \end_inset
13080
13081  defined by the inline assembler, e.g.:
13082 \layout Verse
13083
13084
13085 \family typewriter
13086 foo() {
13087 \newline
13088 \SpecialChar ~
13089 \SpecialChar ~
13090 \SpecialChar ~
13091 \SpecialChar ~
13092 /* some c code */
13093 \newline
13094 \SpecialChar ~
13095 \SpecialChar ~
13096 \SpecialChar ~
13097 \SpecialChar ~
13098 _asm
13099 \newline
13100 \SpecialChar ~
13101 \SpecialChar ~
13102 \SpecialChar ~
13103 \SpecialChar ~
13104 \SpecialChar ~
13105 \SpecialChar ~
13106 ; some assembler code
13107 \newline
13108 \SpecialChar ~
13109 \SpecialChar ~
13110 \SpecialChar ~
13111 \SpecialChar ~
13112 \SpecialChar ~
13113 \SpecialChar ~
13114 ljmp $0003
13115 \newline
13116 \SpecialChar ~
13117 \SpecialChar ~
13118 \SpecialChar ~
13119 \SpecialChar ~
13120 _endasm;
13121 \newline
13122 \SpecialChar ~
13123 \SpecialChar ~
13124 \SpecialChar ~
13125 \SpecialChar ~
13126 /* some more c code */
13127 \newline
13128 clabel:\SpecialChar ~
13129 \SpecialChar ~
13130 /* inline assembler cannot reference this label */
13131 \newline
13132 \SpecialChar ~
13133 \SpecialChar ~
13134 \SpecialChar ~
13135 \SpecialChar ~
13136 _asm
13137 \newline
13138 \SpecialChar ~
13139 \SpecialChar ~
13140 \SpecialChar ~
13141 \SpecialChar ~
13142 $0003: ;label (can be referenced by inline assembler only)
13143 \newline
13144 \SpecialChar ~
13145 \SpecialChar ~
13146 \SpecialChar ~
13147 \SpecialChar ~
13148 _endasm
13149 \begin_inset LatexCommand \index{\_endasm}
13150
13151 \end_inset
13152
13153
13154 \begin_inset LatexCommand \index{\_\_endasm}
13155
13156 \end_inset
13157
13158  ;
13159 \newline
13160 \SpecialChar ~
13161 \SpecialChar ~
13162 \SpecialChar ~
13163 \SpecialChar ~
13164 /* some more c code */
13165 \newline
13166 }
13167 \layout Standard
13168
13169 In other words inline assembly code can access labels defined in inline
13170  assembly within the scope of the function.
13171  The same goes the other way, i.e.
13172  labels defines in inline assembly can not be accessed by C statements.
13173 \layout Section
13174
13175 Interfacing with Assembler Code
13176 \begin_inset LatexCommand \index{Assembler routines}
13177
13178 \end_inset
13179
13180
13181 \layout Subsection
13182
13183 Global Registers used for Parameter Passing
13184 \begin_inset LatexCommand \index{Parameter passing}
13185
13186 \end_inset
13187
13188
13189 \layout Standard
13190
13191 The compiler always uses the global registers
13192 \emph on
13193 DPL, DPH
13194 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
13195
13196 \end_inset
13197
13198
13199 \begin_inset LatexCommand \index{DPTR}
13200
13201 \end_inset
13202
13203 , B
13204 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
13205
13206 \end_inset
13207
13208
13209 \emph default
13210 and
13211 \emph on
13212  ACC
13213 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
13214
13215 \end_inset
13216
13217
13218 \emph default
13219  to pass the first parameter to a routine.
13220  The second parameter onwards is either allocated on the stack (for reentrant
13221  routines or if -
13222 \begin_inset ERT
13223 status Collapsed
13224
13225 \layout Standard
13226
13227 \backslash
13228 /
13229 \end_inset
13230
13231 -stack-auto is used) or in data / xdata memory (depending on the memory
13232  model).
13233
13234 \layout Subsection
13235
13236 Assembler Routine (non-reentrant)
13237 \layout Standard
13238
13239 In the following example
13240 \begin_inset LatexCommand \index{reentrant}
13241
13242 \end_inset
13243
13244
13245 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
13246
13247 \end_inset
13248
13249  the function c_func calls an assembler routine asm_func, which takes two
13250  parameters
13251 \begin_inset LatexCommand \index{function parameter}
13252
13253 \end_inset
13254
13255 .
13256 \layout Verse
13257
13258
13259 \family typewriter
13260 extern int asm_func(unsigned char, unsigned char);
13261 \newline
13262
13263 \newline
13264 int c_func (unsigned char i, unsigned char j)
13265 \newline
13266 {
13267 \newline
13268 \SpecialChar ~
13269 \SpecialChar ~
13270 \SpecialChar ~
13271 \SpecialChar ~
13272 return asm_func(i,j);
13273 \newline
13274 }
13275 \newline
13276
13277 \newline
13278 int main()
13279 \newline
13280 {
13281 \newline
13282 \SpecialChar ~
13283 \SpecialChar ~
13284 \SpecialChar ~
13285 \SpecialChar ~
13286 return c_func(10,9);
13287 \newline
13288 }
13289 \layout Standard
13290
13291 The corresponding assembler function is:
13292 \layout Verse
13293
13294
13295 \family typewriter
13296 .globl _asm_func_PARM_2
13297 \newline
13298 \SpecialChar ~
13299 \SpecialChar ~
13300 \SpecialChar ~
13301 \SpecialChar ~
13302 \SpecialChar ~
13303 \SpecialChar ~
13304 \SpecialChar ~
13305 \SpecialChar ~
13306 .globl _asm_func
13307 \newline
13308 \SpecialChar ~
13309 \SpecialChar ~
13310 \SpecialChar ~
13311 \SpecialChar ~
13312 \SpecialChar ~
13313 \SpecialChar ~
13314 \SpecialChar ~
13315 \SpecialChar ~
13316 .area OSEG
13317 \newline
13318 _asm_func_PARM_2:
13319 \newline
13320 \SpecialChar ~
13321 \SpecialChar ~
13322 \SpecialChar ~
13323 \SpecialChar ~
13324 \SpecialChar ~
13325 \SpecialChar ~
13326 \SpecialChar ~
13327 \SpecialChar ~
13328 .ds    1
13329 \newline
13330 \SpecialChar ~
13331 \SpecialChar ~
13332 \SpecialChar ~
13333 \SpecialChar ~
13334 \SpecialChar ~
13335 \SpecialChar ~
13336 \SpecialChar ~
13337 \SpecialChar ~
13338 .area CSEG
13339 \newline
13340 _asm_func:
13341 \newline
13342 \SpecialChar ~
13343 \SpecialChar ~
13344 \SpecialChar ~
13345 \SpecialChar ~
13346 \SpecialChar ~
13347 \SpecialChar ~
13348 \SpecialChar ~
13349 \SpecialChar ~
13350 mov\SpecialChar ~
13351 \SpecialChar ~
13352 \SpecialChar ~
13353 \SpecialChar ~
13354 a,dpl
13355 \newline
13356 \SpecialChar ~
13357 \SpecialChar ~
13358 \SpecialChar ~
13359 \SpecialChar ~
13360 \SpecialChar ~
13361 \SpecialChar ~
13362 \SpecialChar ~
13363 \SpecialChar ~
13364 add\SpecialChar ~
13365 \SpecialChar ~
13366 \SpecialChar ~
13367 \SpecialChar ~
13368 a,_asm_func_PARM_2
13369 \newline
13370 \SpecialChar ~
13371 \SpecialChar ~
13372 \SpecialChar ~
13373 \SpecialChar ~
13374 \SpecialChar ~
13375 \SpecialChar ~
13376 \SpecialChar ~
13377 \SpecialChar ~
13378 mov\SpecialChar ~
13379 \SpecialChar ~
13380 \SpecialChar ~
13381 \SpecialChar ~
13382 dpl,a
13383 \newline
13384 \SpecialChar ~
13385 \SpecialChar ~
13386 \SpecialChar ~
13387 \SpecialChar ~
13388 \SpecialChar ~
13389 \SpecialChar ~
13390 \SpecialChar ~
13391 \SpecialChar ~
13392 mov\SpecialChar ~
13393 \SpecialChar ~
13394 \SpecialChar ~
13395 \SpecialChar ~
13396 dph
13397 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
13398
13399 \end_inset
13400
13401 ,#0x00
13402 \newline
13403 \SpecialChar ~
13404 \SpecialChar ~
13405 \SpecialChar ~
13406 \SpecialChar ~
13407 \SpecialChar ~
13408 \SpecialChar ~
13409 \SpecialChar ~
13410 \SpecialChar ~
13411 ret
13412 \layout Standard
13413
13414 Note here that the return values
13415 \begin_inset LatexCommand \index{return value}
13416
13417 \end_inset
13418
13419  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
13420  two byte values.
13421  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
13422 b' & 'acc' for four byte values.
13423 \layout Standard
13424
13425 The parameter naming convention is _<function_name>_PARM_<n>, where n is
13426  the parameter number starting from 1, and counting from the left.
13427  The first parameter is passed in
13428 \begin_inset Quotes eld
13429 \end_inset
13430
13431 dpl
13432 \begin_inset Quotes erd
13433 \end_inset
13434
13435  for a one byte parameter,
13436 \begin_inset Quotes eld
13437 \end_inset
13438
13439 dptr
13440 \begin_inset Quotes erd
13441 \end_inset
13442
13443  for two bytes,
13444 \begin_inset Quotes eld
13445 \end_inset
13446
13447 b,dptr
13448 \begin_inset Quotes erd
13449 \end_inset
13450
13451  for three bytes and
13452 \begin_inset Quotes eld
13453 \end_inset
13454
13455 acc,b,dptr
13456 \begin_inset Quotes erd
13457 \end_inset
13458
13459  for a four bytes parameter.
13460  The variable name for the second parameter will be _<function_name>_PARM_2.
13461 \newline
13462
13463 \newline
13464 Assemble the assembler routine with the following command:
13465 \newline
13466
13467 \newline
13468
13469 \family sans
13470 \series bold
13471 asx8051 -losg asmfunc.asm
13472 \newline
13473
13474 \newline
13475
13476 \family default
13477 \series default
13478 Then compile and link the assembler routine to the C source file with the
13479  following command:
13480 \newline
13481
13482 \newline
13483
13484 \family sans
13485 \series bold
13486 sdcc cfunc.c asmfunc.rel
13487 \layout Subsection
13488
13489 Assembler Routine (reentrant)
13490 \layout Standard
13491
13492 In this case
13493 \begin_inset LatexCommand \index{reentrant}
13494
13495 \end_inset
13496
13497
13498 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
13499
13500 \end_inset
13501
13502  the second parameter
13503 \begin_inset LatexCommand \index{function parameter}
13504
13505 \end_inset
13506
13507  onwards will be passed on the stack, the parameters are pushed from right
13508  to left i.e.
13509  after the call the leftmost parameter will be on the top of the stack.
13510  Here is an example:
13511 \layout Verse
13512
13513
13514 \family typewriter
13515 extern int asm_func(unsigned char, unsigned char);
13516 \newline
13517
13518 \newline
13519 int c_func (unsigned char i, unsigned char j) reentrant
13520 \newline
13521 {
13522 \newline
13523 \SpecialChar ~
13524 \SpecialChar ~
13525 \SpecialChar ~
13526 \SpecialChar ~
13527 return asm_func(i,j);
13528 \newline
13529 }
13530 \newline
13531
13532 \newline
13533 int main()
13534 \newline
13535 {
13536 \newline
13537 \SpecialChar ~
13538 \SpecialChar ~
13539 \SpecialChar ~
13540 \SpecialChar ~
13541 return c_func(10,9);
13542 \newline
13543 }
13544 \layout Standard
13545
13546 The corresponding assembler routine is:
13547 \layout Verse
13548
13549
13550 \family typewriter
13551 .globl _asm_func
13552 \newline
13553 _asm_func:
13554 \newline
13555 \SpecialChar ~
13556 \SpecialChar ~
13557 \SpecialChar ~
13558 \SpecialChar ~
13559 push  _bp
13560 \newline
13561 \SpecialChar ~
13562 \SpecialChar ~
13563 \SpecialChar ~
13564 \SpecialChar ~
13565 mov _bp,sp
13566 \newline
13567 \SpecialChar ~
13568 \SpecialChar ~
13569 \SpecialChar ~
13570 \SpecialChar ~
13571 mov r2,dpl
13572 \newline
13573 \SpecialChar ~
13574 \SpecialChar ~
13575 \SpecialChar ~
13576 \SpecialChar ~
13577 mov a,_bp
13578 \newline
13579 \SpecialChar ~
13580 \SpecialChar ~
13581 \SpecialChar ~
13582 \SpecialChar ~
13583 add a,#0xfd
13584 \newline
13585 \SpecialChar ~
13586 \SpecialChar ~
13587 \SpecialChar ~
13588 \SpecialChar ~
13589 mov r0,a
13590 \newline
13591 \SpecialChar ~
13592 \SpecialChar ~
13593 \SpecialChar ~
13594 \SpecialChar ~
13595 add  a,#0xfc ;?
13596 \newline
13597 \SpecialChar ~
13598 \SpecialChar ~
13599 \SpecialChar ~
13600 \SpecialChar ~
13601 mov  r1,a
13602 \newline
13603 \SpecialChar ~
13604 \SpecialChar ~
13605 \SpecialChar ~
13606 \SpecialChar ~
13607 mov  a,@r0
13608 \newline
13609 \SpecialChar ~
13610 \SpecialChar ~
13611 \SpecialChar ~
13612 \SpecialChar ~
13613 add  a,r2 ;?
13614 \newline
13615 \SpecialChar ~
13616 \SpecialChar ~
13617 \SpecialChar ~
13618 \SpecialChar ~
13619 mov  dpl,a
13620 \newline
13621 \SpecialChar ~
13622 \SpecialChar ~
13623 \SpecialChar ~
13624 \SpecialChar ~
13625 mov  dph,#0x00
13626 \newline
13627 \SpecialChar ~
13628 \SpecialChar ~
13629 \SpecialChar ~
13630 \SpecialChar ~
13631 mov  sp,_bp
13632 \newline
13633 \SpecialChar ~
13634 \SpecialChar ~
13635 \SpecialChar ~
13636 \SpecialChar ~
13637 pop  _bp
13638 \newline
13639 \SpecialChar ~
13640 \SpecialChar ~
13641 \SpecialChar ~
13642 \SpecialChar ~
13643 ret
13644 \layout Standard
13645
13646 The compiling and linking procedure remains the same, however note the extra
13647  entry & exit linkage required for the assembler code, _bp is the stack
13648  frame pointer and is used to compute the offset into the stack for parameters
13649  and local variables.
13650 \layout Section
13651
13652 int (16 bit)
13653 \begin_inset LatexCommand \index{int (16 bit)}
13654
13655 \end_inset
13656
13657  and long (32 bit)
13658 \begin_inset LatexCommand \index{long (32 bit)}
13659
13660 \end_inset
13661
13662  Support
13663 \layout Standard
13664
13665 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
13666  multiplication and modulus operations are implemented by support routines.
13667  These support routines are all developed in ANSI-C to facilitate porting
13668  to other MCUs, although some model specific assembler optimizations are
13669  used.
13670  The following files contain the described routines, all of them can be
13671  found in <installdir>/share/sdcc/lib.
13672 \newline
13673
13674 \layout Standard
13675 \align center
13676
13677 \begin_inset  Tabular
13678 <lyxtabular version="3" rows="11" columns="2">
13679 <features>
13680 <column alignment="center" valignment="top" leftline="true" width="0">
13681 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
13682 <row topline="true" bottomline="true">
13683 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13684 \begin_inset Text
13685
13686 \layout Standard
13687
13688
13689 \series bold
13690 Function
13691 \end_inset
13692 </cell>
13693 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13694 \begin_inset Text
13695
13696 \layout Standard
13697
13698
13699 \series bold
13700 Description
13701 \end_inset
13702 </cell>
13703 </row>
13704 <row topline="true">
13705 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13706 \begin_inset Text
13707
13708 \layout Standard
13709
13710 _mulint.c
13711 \end_inset
13712 </cell>
13713 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13714 \begin_inset Text
13715
13716 \layout Standard
13717
13718 16 bit multiplication
13719 \end_inset
13720 </cell>
13721 </row>
13722 <row topline="true">
13723 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13724 \begin_inset Text
13725
13726 \layout Standard
13727
13728 _divsint.c
13729 \end_inset
13730 </cell>
13731 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13732 \begin_inset Text
13733
13734 \layout Standard
13735
13736  signed 16 bit division (calls _divuint)
13737 \end_inset
13738 </cell>
13739 </row>
13740 <row topline="true">
13741 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13742 \begin_inset Text
13743
13744 \layout Standard
13745
13746 _divuint.c
13747 \end_inset
13748 </cell>
13749 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13750 \begin_inset Text
13751
13752 \layout Standard
13753
13754  unsigned 16 bit division
13755 \end_inset
13756 </cell>
13757 </row>
13758 <row topline="true">
13759 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13760 \begin_inset Text
13761
13762 \layout Standard
13763
13764 _modsint.c
13765 \end_inset
13766 </cell>
13767 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13768 \begin_inset Text
13769
13770 \layout Standard
13771
13772 signed 16 bit modulus (calls _moduint)
13773 \end_inset
13774 </cell>
13775 </row>
13776 <row topline="true">
13777 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13778 \begin_inset Text
13779
13780 \layout Standard
13781
13782 _moduint.c
13783 \end_inset
13784 </cell>
13785 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13786 \begin_inset Text
13787
13788 \layout Standard
13789
13790 unsigned 16 bit modulus
13791 \end_inset
13792 </cell>
13793 </row>
13794 <row topline="true">
13795 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13796 \begin_inset Text
13797
13798 \layout Standard
13799
13800 _mullong.c
13801 \end_inset
13802 </cell>
13803 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13804 \begin_inset Text
13805
13806 \layout Standard
13807
13808 32 bit multiplication
13809 \end_inset
13810 </cell>
13811 </row>
13812 <row topline="true">
13813 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13814 \begin_inset Text
13815
13816 \layout Standard
13817
13818 _divslong.c
13819 \end_inset
13820 </cell>
13821 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13822 \begin_inset Text
13823
13824 \layout Standard
13825
13826  signed 32 division (calls _divulong)
13827 \end_inset
13828 </cell>
13829 </row>
13830 <row topline="true">
13831 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13832 \begin_inset Text
13833
13834 \layout Standard
13835
13836 _divulong.c
13837 \end_inset
13838 </cell>
13839 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13840 \begin_inset Text
13841
13842 \layout Standard
13843
13844 unsigned 32 division
13845 \end_inset
13846 </cell>
13847 </row>
13848 <row topline="true">
13849 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13850 \begin_inset Text
13851
13852 \layout Standard
13853
13854 _modslong.c
13855 \end_inset
13856 </cell>
13857 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13858 \begin_inset Text
13859
13860 \layout Standard
13861
13862  signed 32 bit modulus (calls _modulong)
13863 \end_inset
13864 </cell>
13865 </row>
13866 <row topline="true" bottomline="true">
13867 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13868 \begin_inset Text
13869
13870 \layout Standard
13871
13872 _modulong.c
13873 \end_inset
13874 </cell>
13875 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13876 \begin_inset Text
13877
13878 \layout Standard
13879
13880 unsigned 32 bit modulus
13881 \end_inset
13882 </cell>
13883 </row>
13884 </lyxtabular>
13885
13886 \end_inset
13887
13888
13889 \newline
13890
13891 \layout Standard
13892
13893 Since they are compiled as
13894 \emph on
13895 non-reentrant
13896 \emph default
13897
13898 \begin_inset LatexCommand \index{reentrant}
13899
13900 \end_inset
13901
13902 , interrupt
13903 \begin_inset LatexCommand \index{interrupt}
13904
13905 \end_inset
13906
13907  service routines should not do any of the above operations.
13908  If this is unavoidable then the above routines will need to be compiled
13909  with the
13910 \emph on
13911 -
13912 \begin_inset ERT
13913 status Collapsed
13914
13915 \layout Standard
13916
13917 \backslash
13918 /
13919 \end_inset
13920
13921 -stack-auto
13922 \begin_inset LatexCommand \index{-\/-stack-auto}
13923
13924 \end_inset
13925
13926
13927 \emph default
13928  option, after which the source program will have to be compiled with
13929 \emph on
13930 -
13931 \begin_inset ERT
13932 status Collapsed
13933
13934 \layout Standard
13935
13936 \backslash
13937 /
13938 \end_inset
13939
13940 -int-long-reent
13941 \begin_inset LatexCommand \index{-\/-int-long-reent}
13942
13943 \end_inset
13944
13945
13946 \emph default
13947  option.
13948  Notice that you don't have to call these routines directly.
13949  The compiler will use them automatically every time an integer operation
13950  is required.
13951 \layout Section
13952
13953 Floating Point Support
13954 \begin_inset LatexCommand \index{Floating point support}
13955
13956 \end_inset
13957
13958
13959 \layout Standard
13960
13961 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
13962  floating point support routines are derived from gcc's floatlib.c and consist
13963  of the following routines:
13964 \newline
13965
13966 \layout Standard
13967 \align center
13968
13969 \size footnotesize
13970
13971 \begin_inset  Tabular
13972 <lyxtabular version="3" rows="17" columns="2">
13973 <features>
13974 <column alignment="center" valignment="top" leftline="true" width="0">
13975 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
13976 <row topline="true" bottomline="true">
13977 <cell alignment="center" valignment="top" topline="true" leftline="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 Function
13992 \end_inset
13993 </cell>
13994 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13995 \begin_inset Text
13996
13997 \layout Standard
13998
13999 Description
14000 \end_inset
14001 </cell>
14002 </row>
14003 <row topline="true">
14004 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14005 \begin_inset Text
14006
14007 \layout Standard
14008
14009
14010 \family roman
14011 \series medium
14012 \shape up
14013 \size normal
14014 \emph off
14015 \bar no
14016 \noun off
14017 \color none
14018 _fsadd.c
14019 \end_inset
14020 </cell>
14021 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14022 \begin_inset Text
14023
14024 \layout Standard
14025
14026
14027 \family roman
14028 \series medium
14029 \shape up
14030 \size normal
14031 \emph off
14032 \bar no
14033 \noun off
14034 \color none
14035 add floating point numbers
14036 \end_inset
14037 </cell>
14038 </row>
14039 <row topline="true">
14040 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14041 \begin_inset Text
14042
14043 \layout Standard
14044
14045
14046 \family roman
14047 \series medium
14048 \shape up
14049 \size normal
14050 \emph off
14051 \bar no
14052 \noun off
14053 \color none
14054 _fssub.c
14055 \end_inset
14056 </cell>
14057 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14058 \begin_inset Text
14059
14060 \layout Standard
14061
14062
14063 \family roman
14064 \series medium
14065 \shape up
14066 \size normal
14067 \emph off
14068 \bar no
14069 \noun off
14070 \color none
14071 subtract floating point numbers
14072 \end_inset
14073 </cell>
14074 </row>
14075 <row topline="true">
14076 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14077 \begin_inset Text
14078
14079 \layout Standard
14080
14081
14082 \family roman
14083 \series medium
14084 \shape up
14085 \size normal
14086 \emph off
14087 \bar no
14088 \noun off
14089 \color none
14090 _fsdiv.c
14091 \end_inset
14092 </cell>
14093 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14094 \begin_inset Text
14095
14096 \layout Standard
14097
14098
14099 \family roman
14100 \series medium
14101 \shape up
14102 \size normal
14103 \emph off
14104 \bar no
14105 \noun off
14106 \color none
14107 divide floating point numbers
14108 \end_inset
14109 </cell>
14110 </row>
14111 <row topline="true">
14112 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14113 \begin_inset Text
14114
14115 \layout Standard
14116
14117
14118 \family roman
14119 \series medium
14120 \shape up
14121 \size normal
14122 \emph off
14123 \bar no
14124 \noun off
14125 \color none
14126 _fsmul.c
14127 \end_inset
14128 </cell>
14129 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14130 \begin_inset Text
14131
14132 \layout Standard
14133
14134
14135 \family roman
14136 \series medium
14137 \shape up
14138 \size normal
14139 \emph off
14140 \bar no
14141 \noun off
14142 \color none
14143 multiply floating point numbers
14144 \end_inset
14145 </cell>
14146 </row>
14147 <row topline="true">
14148 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14149 \begin_inset Text
14150
14151 \layout Standard
14152
14153
14154 \family roman
14155 \series medium
14156 \shape up
14157 \size normal
14158 \emph off
14159 \bar no
14160 \noun off
14161 \color none
14162 _fs2uchar.c
14163 \end_inset
14164 </cell>
14165 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14166 \begin_inset Text
14167
14168 \layout Standard
14169
14170
14171 \family roman
14172 \series medium
14173 \shape up
14174 \size normal
14175 \emph off
14176 \bar no
14177 \noun off
14178 \color none
14179 convert floating point to unsigned char
14180 \end_inset
14181 </cell>
14182 </row>
14183 <row topline="true">
14184 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14185 \begin_inset Text
14186
14187 \layout Standard
14188
14189
14190 \family roman
14191 \series medium
14192 \shape up
14193 \size normal
14194 \emph off
14195 \bar no
14196 \noun off
14197 \color none
14198 _fs2char.c
14199 \end_inset
14200 </cell>
14201 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14202 \begin_inset Text
14203
14204 \layout Standard
14205
14206
14207 \family roman
14208 \series medium
14209 \shape up
14210 \size normal
14211 \emph off
14212 \bar no
14213 \noun off
14214 \color none
14215 convert floating point to signed char
14216 \end_inset
14217 </cell>
14218 </row>
14219 <row topline="true">
14220 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14221 \begin_inset Text
14222
14223 \layout Standard
14224
14225
14226 \family roman
14227 \series medium
14228 \shape up
14229 \size normal
14230 \emph off
14231 \bar no
14232 \noun off
14233 \color none
14234 _fs2uint.c
14235 \end_inset
14236 </cell>
14237 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14238 \begin_inset Text
14239
14240 \layout Standard
14241
14242
14243 \family roman
14244 \series medium
14245 \shape up
14246 \size normal
14247 \emph off
14248 \bar no
14249 \noun off
14250 \color none
14251 convert floating point to unsigned int
14252 \end_inset
14253 </cell>
14254 </row>
14255 <row topline="true">
14256 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14257 \begin_inset Text
14258
14259 \layout Standard
14260
14261
14262 \family roman
14263 \series medium
14264 \shape up
14265 \size normal
14266 \emph off
14267 \bar no
14268 \noun off
14269 \color none
14270 _fs2int.c
14271 \end_inset
14272 </cell>
14273 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14274 \begin_inset Text
14275
14276 \layout Standard
14277
14278
14279 \family roman
14280 \series medium
14281 \shape up
14282 \size normal
14283 \emph off
14284 \bar no
14285 \noun off
14286 \color none
14287 convert floating point to signed int
14288 \end_inset
14289 </cell>
14290 </row>
14291 <row topline="true">
14292 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14293 \begin_inset Text
14294
14295 \layout Standard
14296
14297
14298 \family roman
14299 \series medium
14300 \shape up
14301 \size normal
14302 \emph off
14303 \bar no
14304 \noun off
14305 \color none
14306 _fs2ulong.
14307 \family default
14308 \series default
14309 \shape default
14310 \size default
14311 \emph default
14312 \bar default
14313 \noun default
14314 \color default
14315 c
14316 \end_inset
14317 </cell>
14318 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14319 \begin_inset Text
14320
14321 \layout Standard
14322
14323
14324 \family roman
14325 \series medium
14326 \shape up
14327 \size normal
14328 \emph off
14329 \bar no
14330 \noun off
14331 \color none
14332 convert floating point to unsigned long
14333 \end_inset
14334 </cell>
14335 </row>
14336 <row topline="true">
14337 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14338 \begin_inset Text
14339
14340 \layout Standard
14341
14342
14343 \family roman
14344 \series medium
14345 \shape up
14346 \size normal
14347 \emph off
14348 \bar no
14349 \noun off
14350 \color none
14351 _fs2long.c
14352 \end_inset
14353 </cell>
14354 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14355 \begin_inset Text
14356
14357 \layout Standard
14358
14359
14360 \family roman
14361 \series medium
14362 \shape up
14363 \size normal
14364 \emph off
14365 \bar no
14366 \noun off
14367 \color none
14368 convert floating point to signed long
14369 \end_inset
14370 </cell>
14371 </row>
14372 <row topline="true">
14373 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14374 \begin_inset Text
14375
14376 \layout Standard
14377
14378
14379 \family roman
14380 \series medium
14381 \shape up
14382 \size normal
14383 \emph off
14384 \bar no
14385 \noun off
14386 \color none
14387 _uchar2fs.c
14388 \end_inset
14389 </cell>
14390 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14391 \begin_inset Text
14392
14393 \layout Standard
14394
14395
14396 \family roman
14397 \series medium
14398 \shape up
14399 \size normal
14400 \emph off
14401 \bar no
14402 \noun off
14403 \color none
14404 convert unsigned char to floating point
14405 \end_inset
14406 </cell>
14407 </row>
14408 <row topline="true">
14409 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14410 \begin_inset Text
14411
14412 \layout Standard
14413
14414
14415 \family roman
14416 \series medium
14417 \shape up
14418 \size normal
14419 \emph off
14420 \bar no
14421 \noun off
14422 \color none
14423 _char2fs.c
14424 \end_inset
14425 </cell>
14426 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14427 \begin_inset Text
14428
14429 \layout Standard
14430
14431
14432 \family roman
14433 \series medium
14434 \shape up
14435 \size normal
14436 \emph off
14437 \bar no
14438 \noun off
14439 \color none
14440 convert char to floating point number
14441 \end_inset
14442 </cell>
14443 </row>
14444 <row topline="true">
14445 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14446 \begin_inset Text
14447
14448 \layout Standard
14449
14450
14451 \family roman
14452 \series medium
14453 \shape up
14454 \size normal
14455 \emph off
14456 \bar no
14457 \noun off
14458 \color none
14459 _uint2fs.c
14460 \end_inset
14461 </cell>
14462 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14463 \begin_inset Text
14464
14465 \layout Standard
14466
14467
14468 \family roman
14469 \series medium
14470 \shape up
14471 \size normal
14472 \emph off
14473 \bar no
14474 \noun off
14475 \color none
14476 convert unsigned int to floating point
14477 \end_inset
14478 </cell>
14479 </row>
14480 <row topline="true">
14481 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14482 \begin_inset Text
14483
14484 \layout Standard
14485
14486
14487 \family roman
14488 \series medium
14489 \shape up
14490 \size normal
14491 \emph off
14492 \bar no
14493 \noun off
14494 \color none
14495 _int2fs.c
14496 \end_inset
14497 </cell>
14498 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14499 \begin_inset Text
14500
14501 \layout Standard
14502
14503
14504 \family roman
14505 \series medium
14506 \shape up
14507 \size normal
14508 \emph off
14509 \bar no
14510 \noun off
14511 \color none
14512 convert int to floating point numbers
14513 \end_inset
14514 </cell>
14515 </row>
14516 <row topline="true">
14517 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14518 \begin_inset Text
14519
14520 \layout Standard
14521
14522
14523 \family roman
14524 \series medium
14525 \shape up
14526 \size normal
14527 \emph off
14528 \bar no
14529 \noun off
14530 \color none
14531 _ulong2fs.c
14532 \end_inset
14533 </cell>
14534 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14535 \begin_inset Text
14536
14537 \layout Standard
14538
14539
14540 \family roman
14541 \series medium
14542 \shape up
14543 \size normal
14544 \emph off
14545 \bar no
14546 \noun off
14547 \color none
14548 convert unsigned long to floating point number
14549 \end_inset
14550 </cell>
14551 </row>
14552 <row topline="true" bottomline="true">
14553 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14554 \begin_inset Text
14555
14556 \layout Standard
14557
14558
14559 \family roman
14560 \series medium
14561 \shape up
14562 \size normal
14563 \emph off
14564 \bar no
14565 \noun off
14566 \color none
14567 _long2fs.c
14568 \end_inset
14569 </cell>
14570 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14571 \begin_inset Text
14572
14573 \layout Standard
14574
14575
14576 \family roman
14577 \series medium
14578 \shape up
14579 \size normal
14580 \emph off
14581 \bar no
14582 \noun off
14583 \color none
14584 convert long to floating point number
14585 \end_inset
14586 </cell>
14587 </row>
14588 </lyxtabular>
14589
14590 \end_inset
14591
14592
14593 \newline
14594
14595 \layout Standard
14596
14597 These support routines are developed in ANSI-C so there is room for space
14598  and speed improvement
14599 \begin_inset Foot
14600 collapsed false
14601
14602 \layout Standard
14603
14604 The floating point routines for the mcs51 are implemented in assembler
14605 \end_inset
14606
14607 .
14608  Note if all these routines are used simultaneously the data space might
14609  overflow.
14610  For serious floating point usage the large model might be needed.
14611  Also notice that you don't have to call this routines directly.
14612  The compiler will use them automatically every time a floating point operation
14613  is required.
14614 \layout Section
14615
14616 Library Routines
14617 \begin_inset LatexCommand \index{Libraries}
14618
14619 \end_inset
14620
14621
14622 \layout Standard
14623
14624
14625 \emph on
14626 <pending: this is messy and incomplete - a little more information is in
14627  sdcc/doc/libdoc.txt
14628 \emph default
14629  >
14630 \layout Subsection
14631
14632 Compiler support routines (_gptrget, _mulint etc.)
14633 \layout Subsection
14634
14635 Stdclib functions (puts, printf, strcat etc.)
14636 \layout Subsubsection
14637
14638 <stdio.h>
14639 \layout Standard
14640
14641
14642 \begin_inset LatexCommand \index{<stdio.h>}
14643
14644 \end_inset
14645
14646 As usual on embedded systems you have to provide your own
14647 \family typewriter
14648 getchar()
14649 \begin_inset LatexCommand \index{getchar()}
14650
14651 \end_inset
14652
14653
14654 \family default
14655 and
14656 \family typewriter
14657 putchar()
14658 \begin_inset LatexCommand \index{putchar()}
14659
14660 \end_inset
14661
14662
14663 \family default
14664  routines.
14665  SDCC does not know whether the system connects to a serial line with or
14666  without handshake, LCD, keyboard or other device.
14667  You'll find examples for serial routines f.e.
14668  in sdcc/device/lib.
14669 \layout Standard
14670
14671 The default
14672 \family typewriter
14673  printf()
14674 \begin_inset LatexCommand \index{printf()}
14675
14676 \end_inset
14677
14678
14679 \family default
14680 implementation in
14681 \family typewriter
14682  printf_large.c
14683 \family default
14684  does not support float (except on ds390).
14685  To enable this recompile it with the option
14686 \emph on
14687 -
14688 \begin_inset ERT
14689 status Collapsed
14690
14691 \layout Standard
14692
14693 \backslash
14694 /
14695 \end_inset
14696
14697 DUSE_FLOATS=1
14698 \begin_inset LatexCommand \index{USE\_FLOATS}
14699
14700 \end_inset
14701
14702
14703 \emph default
14704  on the command line.
14705  Use
14706 \emph on
14707 -
14708 \begin_inset ERT
14709 status Collapsed
14710
14711 \layout Standard
14712
14713 \backslash
14714 /
14715 \end_inset
14716
14717 -model-large
14718 \begin_inset LatexCommand \index{-\/-model-large}
14719
14720 \end_inset
14721
14722
14723 \emph default
14724  for the mcs51 port, since this uses a lot of memory.
14725 \layout Standard
14726
14727 If you're short on memory you might want to use
14728 \family typewriter
14729 printf_small()
14730 \begin_inset LatexCommand \index{printf\_small()}
14731
14732 \end_inset
14733
14734
14735 \family default
14736
14737 \emph on
14738 instead
14739 \emph default
14740  of
14741 \family typewriter
14742  printf().
14743
14744 \family default
14745  For the mcs51 there additionally are assembly versions
14746 \family typewriter
14747 printf_tiny()
14748 \begin_inset LatexCommand \index{printf\_tiny() (mcs51)}
14749
14750 \end_inset
14751
14752
14753 \family default
14754  and
14755 \family typewriter
14756 printf_fast()
14757 \begin_inset LatexCommand \index{printf\_fast() (mcs51)}
14758
14759 \end_inset
14760
14761
14762 \family default
14763 and
14764 \family typewriter
14765  printf_fast_f()
14766 \begin_inset LatexCommand \index{printf\_fast\_f() (mcs51)}
14767
14768 \end_inset
14769
14770
14771 \family default
14772  which should fit the requirements of many embedded systems (printf_fast()
14773  can be customized by unsetting #defines to
14774 \emph on
14775 not
14776 \emph default
14777  support long variables and field widths).
14778 \layout Subsection
14779
14780 Math functions (sin, pow, sqrt etc.)
14781 \layout Subsection
14782
14783 Other libraries
14784 \layout Standard
14785
14786 Libraries
14787 \begin_inset LatexCommand \index{Libraries}
14788
14789 \end_inset
14790
14791  included in SDCC should have a license at least as liberal as the GNU Lesser
14792  General Public License
14793 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
14794
14795 \end_inset
14796
14797
14798 \emph on
14799 LGPL
14800 \emph default
14801 .
14802 \layout Comment
14803
14804 license statements for the libraries are missing.
14805  sdcc/device/lib/ser_ir.c
14806 \layout Comment
14807
14808 or _decdptr f.e.
14809  come with a GPL (as opposed to LGPL) License - this will not be liberal
14810  enough for many embedded programmers.
14811 \layout Standard
14812
14813 If you have ported some library or want to share experience about some code
14814  which f.e.
14815  falls into any of these categories Busses (I
14816 \begin_inset Formula $^{\textrm{2}}$
14817 \end_inset
14818
14819 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
14820  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
14821  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
14822 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
14823
14824 \end_inset
14825
14826 \SpecialChar ~
14827 would certainly like to hear about it.
14828  Programmers coding for embedded systems are not especially famous for being
14829  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
14830 e these references are very valuable.
14831  Let's help to create a climate where information is shared.
14832 \layout Section
14833
14834 Memory Models
14835 \layout Subsection
14836
14837 MCS51 Memory Models
14838 \begin_inset LatexCommand \index{Memory model}
14839
14840 \end_inset
14841
14842
14843 \begin_inset LatexCommand \index{MCS51 memory model}
14844
14845 \end_inset
14846
14847
14848 \layout Subsubsection
14849
14850 Small, Medium and Large
14851 \layout Standard
14852
14853 SDCC allows three memory models for MCS51 code,
14854 \shape slanted
14855 small, medium
14856 \shape default
14857  and
14858 \shape slanted
14859 large
14860 \shape default
14861 .
14862  Modules compiled with different memory models should
14863 \emph on
14864 never
14865 \emph default
14866  be combined together or the results would be unpredictable.
14867  The library routines supplied with the compiler are compiled as small,
14868  medium and large.
14869  The compiled library modules are contained in separate directories as small,
14870  medium and large so that you can link to the appropriate set.
14871 \layout Standard
14872
14873 When the medium or large model is used all variables declared without a
14874  storage class will be allocated into the external ram, this includes all
14875  parameters and local variables (for non-reentrant
14876 \begin_inset LatexCommand \index{reentrant}
14877
14878 \end_inset
14879
14880  functions).
14881  When the small model is used variables without storage class are allocated
14882  in the internal ram.
14883 \layout Standard
14884
14885 Judicious usage of the processor specific storage classes
14886 \begin_inset LatexCommand \index{Storage class}
14887
14888 \end_inset
14889
14890  and the 'reentrant' function type will yield much more efficient code,
14891  than using the large model.
14892  Several optimizations are disabled when the program is compiled using the
14893  large model, it is therefore recommended that the small model be used unless
14894  absolutely required.
14895 \layout Subsubsection
14896
14897 External Stack
14898 \begin_inset LatexCommand \label{sub:External-Stack}
14899
14900 \end_inset
14901
14902
14903 \begin_inset LatexCommand \index{stack}
14904
14905 \end_inset
14906
14907
14908 \begin_inset LatexCommand \index{External stack (mcs51)}
14909
14910 \end_inset
14911
14912
14913 \layout Standard
14914
14915 The external stack (-
14916 \begin_inset ERT
14917 status Collapsed
14918
14919 \layout Standard
14920
14921 \backslash
14922 /
14923 \end_inset
14924
14925 -xstack option
14926 \begin_inset LatexCommand \index{-\/-xstack}
14927
14928 \end_inset
14929
14930 ) is located in pdata
14931 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
14932
14933 \end_inset
14934
14935  memory (usually at the start of the external ram segment) and uses all
14936  unused space in pdata (max.
14937  256 bytes).
14938  When -
14939 \begin_inset ERT
14940 status Collapsed
14941
14942 \layout Standard
14943
14944 \backslash
14945 /
14946 \end_inset
14947
14948 -xstack option is used to compile the program, the parameters and local
14949  variables
14950 \begin_inset LatexCommand \index{local variables}
14951
14952 \end_inset
14953
14954  of all reentrant functions are allocated in this area.
14955  This option is provided for programs with large stack space requirements.
14956  When used with the -
14957 \begin_inset ERT
14958 status Collapsed
14959
14960 \layout Standard
14961
14962 \backslash
14963 /
14964 \end_inset
14965
14966 -stack-auto
14967 \begin_inset LatexCommand \index{-\/-stack-auto}
14968
14969 \end_inset
14970
14971  option, all parameters and local variables are allocated on the external
14972  stack (note: support libraries will need to be recompiled with the same
14973  options.
14974  There is a predefined target in the library makefile).
14975 \layout Standard
14976
14977 The compiler outputs the higher order address byte of the external ram segment
14978  into port P2
14979 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
14980
14981 \end_inset
14982
14983  (see also section
14984 \begin_inset LatexCommand \ref{sub:MCS51-variants}
14985
14986 \end_inset
14987
14988 ), therefore when using the External Stack option, this port
14989 \emph on
14990 may not
14991 \emph default
14992  be used by the application program.
14993 \layout Subsection
14994
14995 DS390 Memory Model
14996 \begin_inset LatexCommand \index{Memory model}
14997
14998 \end_inset
14999
15000
15001 \begin_inset LatexCommand \index{DS390 memory model}
15002
15003 \end_inset
15004
15005
15006 \layout Standard
15007
15008 The only model supported is Flat 24
15009 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
15010
15011 \end_inset
15012
15013 .
15014  This generates code for the 24 bit contiguous addressing mode of the Dallas
15015  DS80C390 part.
15016  In this mode, up to four meg of external RAM or code space can be directly
15017  addressed.
15018  See the data sheets at www.dalsemi.com for further information on this part.
15019 \newline
15020
15021 \newline
15022 Note that the compiler does not generate any code to place the processor
15023  into 24 bitmode (although
15024 \emph on
15025 tinibios
15026 \emph default
15027  in the ds390 libraries will do that for you).
15028  If you don't use
15029 \emph on
15030 tinibios
15031 \emph default
15032
15033 \begin_inset LatexCommand \index{Tinibios (DS390)}
15034
15035 \end_inset
15036
15037 , the boot loader or similar code must ensure that the processor is in 24
15038  bit contiguous addressing mode before calling the SDCC startup code.
15039 \newline
15040
15041 \newline
15042 Like the
15043 \emph on
15044 -
15045 \begin_inset ERT
15046 status Collapsed
15047
15048 \layout Standard
15049
15050 \backslash
15051 /
15052 \end_inset
15053
15054 -model-large
15055 \emph default
15056  option, variables will by default be placed into the XDATA segment.
15057
15058 \newline
15059
15060 \newline
15061 Segments may be placed anywhere in the 4 meg address space using the usual
15062  -
15063 \begin_inset ERT
15064 status Collapsed
15065
15066 \layout Standard
15067
15068 \backslash
15069 /
15070 \end_inset
15071
15072 -*-loc options.
15073  Note that if any segments are located above 64K, the -r flag must be passed
15074  to the linker to generate the proper segment relocations, and the Intel
15075  HEX output format must be used.
15076  The -r flag can be passed to the linker by using the option
15077 \emph on
15078 -Wl-r
15079 \emph default
15080  on the SDCC command line.
15081  However, currently the linker can not handle code segments > 64k.
15082 \layout Section
15083
15084 Pragmas
15085 \begin_inset LatexCommand \index{Pragmas}
15086
15087 \end_inset
15088
15089
15090 \layout Standard
15091
15092 SDCC supports the following #pragma directives:
15093 \layout Itemize
15094
15095 save
15096 \begin_inset LatexCommand \index{\#pragma save}
15097
15098 \end_inset
15099
15100  - this will save all current options to the save/restore stack.
15101  See #pragma\SpecialChar ~
15102 restore.
15103 \layout Itemize
15104
15105 restore
15106 \begin_inset LatexCommand \index{\#pragma restore}
15107
15108 \end_inset
15109
15110  - will restore saved options from the last save.
15111  saves & restores can be nested.
15112  SDCC uses a save/restore stack: save pushes current options to the stack,
15113  restore pulls current options from the stack.
15114  See #pragma\SpecialChar ~
15115 save.
15116 \newline
15117
15118 \layout Itemize
15119
15120 callee_saves
15121 \begin_inset LatexCommand \index{\#pragma callee\_saves}
15122
15123 \end_inset
15124
15125
15126 \begin_inset LatexCommand \index{function prologue}
15127
15128 \end_inset
15129
15130  function1[,function2[,function3...]] - The compiler by default uses a caller
15131  saves convention for register saving across function calls, however this
15132  can cause unnecessary register pushing & popping
15133 \begin_inset LatexCommand \index{push/pop}
15134
15135 \end_inset
15136
15137  when calling small functions from larger functions.
15138  This option can be used to switch off the register saving convention for
15139  the function names specified.
15140  The compiler will not save registers when calling these functions, extra
15141  code need to be manually inserted at the entry & exit for these functions
15142  to save & restore the registers used by these functions, this can SUBSTANTIALLY
15143  reduce code & improve run time performance of the generated code.
15144  In the future the compiler (with inter procedural analysis) may be able
15145  to determine the appropriate scheme to use for each function call.
15146  If -
15147 \begin_inset ERT
15148 status Collapsed
15149
15150 \layout Standard
15151
15152 \backslash
15153 /
15154 \end_inset
15155
15156 -callee-saves command line option is used, the function names specified
15157  in #pragma\SpecialChar ~
15158 callee_saves
15159 \begin_inset LatexCommand \index{\#pragma callee\_saves}
15160
15161 \end_inset
15162
15163  is appended to the list of functions specified in the command line.
15164 \layout Itemize
15165
15166 exclude
15167 \begin_inset LatexCommand \index{\#pragma exclude}
15168
15169 \end_inset
15170
15171  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
15172  of pairs of push/pop
15173 \begin_inset LatexCommand \index{push/pop}
15174
15175 \end_inset
15176
15177  instructions in
15178 \emph on
15179 I
15180 \emph default
15181 nterrupt
15182 \begin_inset LatexCommand \index{interrupt}
15183
15184 \end_inset
15185
15186
15187 \emph on
15188 S
15189 \emph default
15190 ervice
15191 \emph on
15192 R
15193 \emph default
15194 outines.
15195  The directive should be placed immediately before the ISR function definition
15196  and it affects ALL ISR functions following it.
15197  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
15198 exclude\SpecialChar ~
15199 none
15200 \begin_inset LatexCommand \index{\#pragma exclude}
15201
15202 \end_inset
15203
15204 .
15205  See also the related keyword _naked
15206 \begin_inset LatexCommand \index{\_naked}
15207
15208 \end_inset
15209
15210
15211 \begin_inset LatexCommand \index{\_\_naked}
15212
15213 \end_inset
15214
15215 .
15216 \layout Itemize
15217
15218 less_pedantic
15219 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
15220
15221 \end_inset
15222
15223  - the compiler will not warn you anymore for obvious mistakes, you'r on
15224  your own now ;-(
15225 \layout Itemize
15226
15227 disable_warning <nnnn>
15228 \begin_inset LatexCommand \index{\#pragma disable\_warning}
15229
15230 \end_inset
15231
15232  - the compiler will not warn you anymore about warning number <nnnn>.
15233 \layout Itemize
15234
15235 nogcse
15236 \begin_inset LatexCommand \index{\#pragma nogcse}
15237
15238 \end_inset
15239
15240  - will stop global common subexpression elimination.
15241 \layout Itemize
15242
15243 noinduction
15244 \begin_inset LatexCommand \index{\#pragma noinduction}
15245
15246 \end_inset
15247
15248  - will stop loop induction optimizations.
15249 \layout Itemize
15250
15251 noinvariant
15252 \begin_inset LatexCommand \index{\#pragma noinvariant}
15253
15254 \end_inset
15255
15256  - will not do loop invariant optimizations.
15257  For more details see Loop Invariants in section
15258 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
15259
15260 \end_inset
15261
15262 .
15263 \layout Itemize
15264
15265 noiv
15266 \begin_inset LatexCommand \index{\#pragma noiv}
15267
15268 \end_inset
15269
15270  - Do not generate interrupt
15271 \begin_inset LatexCommand \index{interrupt}
15272
15273 \end_inset
15274
15275  vector table entries for all ISR functions defined after the pragma.
15276  This is useful in cases where the interrupt vector table must be defined
15277  manually, or when there is a secondary, manually defined interrupt vector
15278  table (e.g.
15279  for the autovector feature of the Cypress EZ-USB FX2).
15280  More elegantly this can be achieved by obmitting the optional interrupt
15281  number after the interrupt keyword, see section
15282 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
15283
15284 \end_inset
15285
15286 \SpecialChar ~
15287 about interrupts.
15288 \layout Itemize
15289
15290 nojtbound
15291 \begin_inset LatexCommand \index{\#pragma nojtbound}
15292
15293 \end_inset
15294
15295  - will not generate code for boundary value checking, when switch statements
15296  are turned into jump-tables (dangerous).
15297  For more details see section
15298 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
15299
15300 \end_inset
15301
15302 .
15303 \layout Itemize
15304
15305 noloopreverse
15306 \begin_inset LatexCommand \index{\#pragma noloopreverse}
15307
15308 \end_inset
15309
15310  - Will not do loop reversal optimization
15311 \layout Itemize
15312
15313 nooverlay
15314 \begin_inset LatexCommand \index{\#pragma nooverlay}
15315
15316 \end_inset
15317
15318  - the compiler will not overlay the parameters and local variables of a
15319  function.
15320 \layout Itemize
15321
15322 stackauto
15323 \begin_inset LatexCommand \index{\#pragma stackauto}
15324
15325 \end_inset
15326
15327 - See option -
15328 \begin_inset ERT
15329 status Collapsed
15330
15331 \layout Standard
15332
15333 \backslash
15334 /
15335 \end_inset
15336
15337 -stack-auto
15338 \begin_inset LatexCommand \index{-\/-stack-auto}
15339
15340 \end_inset
15341
15342  and section
15343 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
15344
15345 \end_inset
15346
15347  Parameters and Local Variables.
15348 \layout Itemize
15349
15350 opt_code_speed
15351 \begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
15352
15353 \end_inset
15354
15355 - The compiler will optimize code generation towards fast code, possibly
15356  at the expense of code size.
15357 \layout Itemize
15358
15359 opt_code_size
15360 \begin_inset LatexCommand \index{\#pragma opt\_code\_size}
15361
15362 \end_inset
15363
15364 - The compiler will optimize code generation towards compact code, possibly
15365  at the expense of code speed.
15366 \layout Itemize
15367
15368 opt_code_balanced
15369 \begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
15370
15371 \end_inset
15372
15373 - The compiler will attempt to generate code that is both compact and fast,
15374  as long as meeting one goal is not a detriment to the other (this is the
15375  default).
15376
15377 \layout Itemize
15378
15379 std_sdcc89
15380 \begin_inset LatexCommand \index{\#pragma std\_sdcc89}
15381
15382 \end_inset
15383
15384 - Generally follow the C89 standard, but allow SDCC features that conflict
15385  with the standard (default).
15386 \layout Itemize
15387
15388 std_c89
15389 \begin_inset LatexCommand \index{\#pragma std\_c89}
15390
15391 \end_inset
15392
15393 - Follow the C89 standard and disable SDCC features that conflict with the
15394  standard.
15395 \layout Itemize
15396
15397 std_sdcc99
15398 \begin_inset LatexCommand \index{\#pragma std\_sdcc99}
15399
15400 \end_inset
15401
15402 - Generally follow the C99 standard, but allow SDCC features that conflict
15403  with the standard (incomplete support).
15404 \layout Itemize
15405
15406 std_c99
15407 \begin_inset LatexCommand \index{\#pragma std\_c99}
15408
15409 \end_inset
15410
15411 - Follow the C99 standard and disable SDCC features that conflict with the
15412  standard (incomplete support).
15413 \layout Itemize
15414
15415 codeseg <name>
15416 \begin_inset LatexCommand \index{\#pragma codeseg}
15417
15418 \end_inset
15419
15420 - Use this name (max.
15421  8 characters) for the code segment.
15422 \layout Itemize
15423
15424 constseg <name>
15425 \begin_inset LatexCommand \index{\#pragma constseg}
15426
15427 \end_inset
15428
15429 - Use this name (max.
15430  8 characters) for the const segment.
15431 \layout Standard
15432
15433 SDCPP supports the following #pragma directives:
15434 \layout Itemize
15435
15436 preproc_asm
15437 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
15438
15439 \end_inset
15440
15441  (+ | -) - switch _asm _endasm block preprocessing on / off.
15442  Default is on.
15443 \layout Standard
15444
15445 The pragma's are intended to be used to turn-on or off certain optimizations
15446  which might cause the compiler to generate extra stack / data space to
15447  store compiler generated temporary variables.
15448  This usually happens in large functions.
15449  Pragma directives should be used as shown in the following example, they
15450  are used to control options & optimizations for a given function; pragmas
15451  should be placed before and/or after a function, placing pragma's inside
15452  a function body could have unpredictable results.
15453 \layout Verse
15454
15455
15456 \family typewriter
15457 #pragma save
15458 \begin_inset LatexCommand \index{\#pragma save}
15459
15460 \end_inset
15461
15462  \SpecialChar ~
15463 \SpecialChar ~
15464 \SpecialChar ~
15465 \SpecialChar ~
15466 \SpecialChar ~
15467 \SpecialChar ~
15468 \SpecialChar ~
15469 /* save the current settings */
15470 \newline
15471 #pragma nogcse
15472 \begin_inset LatexCommand \index{\#pragma nogcse}
15473
15474 \end_inset
15475
15476  \SpecialChar ~
15477 \SpecialChar ~
15478 \SpecialChar ~
15479 \SpecialChar ~
15480 \SpecialChar ~
15481 /* turnoff global subexpression elimination */
15482 \newline
15483 #pragma noinduction
15484 \begin_inset LatexCommand \index{\#pragma noinduction}
15485
15486 \end_inset
15487
15488  /* turn off induction optimizations */
15489 \newline
15490 int foo ()
15491 \newline
15492 {
15493 \newline
15494 \SpecialChar ~
15495  \SpecialChar ~
15496  ...
15497
15498 \newline
15499 \SpecialChar ~
15500  \SpecialChar ~
15501  /* large code */
15502 \newline
15503 \SpecialChar ~
15504  \SpecialChar ~
15505  ...
15506
15507 \newline
15508 }
15509 \newline
15510 #pragma restore
15511 \begin_inset LatexCommand \index{\#pragma restore}
15512
15513 \end_inset
15514
15515  /* turn the optimizations back on */
15516 \layout Standard
15517
15518 The compiler will generate a warning message when extra space is allocated.
15519  It is strongly recommended that the save and restore pragma's be used when
15520  changing options for a function.
15521 \layout Section
15522
15523 Defines Created by the Compiler
15524 \layout Standard
15525
15526 The compiler creates the following #defines
15527 \begin_inset LatexCommand \index{\#defines}
15528
15529 \end_inset
15530
15531
15532 \begin_inset LatexCommand \index{Defines created by the compiler}
15533
15534 \end_inset
15535
15536 :
15537 \newline
15538
15539 \layout Standard
15540
15541
15542 \begin_inset  Tabular
15543 <lyxtabular version="3" rows="11" columns="2">
15544 <features>
15545 <column alignment="center" valignment="top" leftline="true" width="0">
15546 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15547 <row topline="true" bottomline="true">
15548 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15549 \begin_inset Text
15550
15551 \layout Standard
15552
15553
15554 \series bold
15555 #define
15556 \end_inset
15557 </cell>
15558 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15559 \begin_inset Text
15560
15561 \layout Standard
15562
15563
15564 \series bold
15565 Description
15566 \end_inset
15567 </cell>
15568 </row>
15569 <row topline="true">
15570 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15571 \begin_inset Text
15572
15573 \layout Standard
15574
15575 SDCC
15576 \begin_inset LatexCommand \index{SDCC}
15577
15578 \end_inset
15579
15580
15581 \end_inset
15582 </cell>
15583 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15584 \begin_inset Text
15585
15586 \layout Standard
15587
15588 this Symbol is always defined
15589 \end_inset
15590 </cell>
15591 </row>
15592 <row topline="true">
15593 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15594 \begin_inset Text
15595
15596 \layout Standard
15597
15598 SDCC_mcs51
15599 \begin_inset LatexCommand \index{SDCC\_mcs51}
15600
15601 \end_inset
15602
15603  or SDCC_ds390
15604 \begin_inset LatexCommand \index{SDCC\_ds390}
15605
15606 \end_inset
15607
15608  or SDCC_z80
15609 \begin_inset LatexCommand \index{SDCC\_z80}
15610
15611 \end_inset
15612
15613 , etc
15614 \end_inset
15615 </cell>
15616 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15617 \begin_inset Text
15618
15619 \layout Standard
15620
15621 depending on the model used (e.g.: -mds390
15622 \end_inset
15623 </cell>
15624 </row>
15625 <row topline="true">
15626 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15627 \begin_inset Text
15628
15629 \layout Standard
15630
15631 __mcs51
15632 \begin_inset LatexCommand \index{\_\_mcs51}
15633
15634 \end_inset
15635
15636 , __ds390
15637 \begin_inset LatexCommand \index{\_\_ds390}
15638
15639 \end_inset
15640
15641 , __hc08
15642 \begin_inset LatexCommand \index{\_\_hc08}
15643
15644 \end_inset
15645
15646 , __z80
15647 \begin_inset LatexCommand \index{\_\_z80}
15648
15649 \end_inset
15650
15651 , etc
15652 \end_inset
15653 </cell>
15654 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15655 \begin_inset Text
15656
15657 \layout Standard
15658
15659 depending on the model used (e.g.
15660  -mz80)
15661 \end_inset
15662 </cell>
15663 </row>
15664 <row topline="true">
15665 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15666 \begin_inset Text
15667
15668 \layout Standard
15669
15670 SDCC_STACK_AUTO
15671 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
15672
15673 \end_inset
15674
15675
15676 \end_inset
15677 </cell>
15678 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15679 \begin_inset Text
15680
15681 \layout Standard
15682
15683 when
15684 \emph on
15685 -
15686 \begin_inset ERT
15687 status Collapsed
15688
15689 \layout Standard
15690
15691 \backslash
15692 /
15693 \end_inset
15694
15695 -stack-auto
15696 \emph default
15697  option is used
15698 \end_inset
15699 </cell>
15700 </row>
15701 <row topline="true">
15702 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15703 \begin_inset Text
15704
15705 \layout Standard
15706
15707 SDCC_MODEL_SMALL
15708 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
15709
15710 \end_inset
15711
15712
15713 \end_inset
15714 </cell>
15715 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15716 \begin_inset Text
15717
15718 \layout Standard
15719
15720 when
15721 \emph on
15722 -
15723 \begin_inset ERT
15724 status Collapsed
15725
15726 \layout Standard
15727
15728 \backslash
15729 /
15730 \end_inset
15731
15732 -model-small
15733 \emph default
15734  is used
15735 \end_inset
15736 </cell>
15737 </row>
15738 <row topline="true">
15739 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15740 \begin_inset Text
15741
15742 \layout Standard
15743
15744 SDCC_MODEL_MEDIUM
15745 \begin_inset LatexCommand \index{SDCC\_MODEL\_MEDIUM}
15746
15747 \end_inset
15748
15749
15750 \end_inset
15751 </cell>
15752 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15753 \begin_inset Text
15754
15755 \layout Standard
15756
15757 when
15758 \emph on
15759 -
15760 \begin_inset ERT
15761 status Collapsed
15762
15763 \layout Standard
15764
15765 \backslash
15766 /
15767 \end_inset
15768
15769 -model-medium
15770 \emph default
15771  is used
15772 \end_inset
15773 </cell>
15774 </row>
15775 <row topline="true">
15776 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15777 \begin_inset Text
15778
15779 \layout Standard
15780
15781 SDCC_MODEL_LARGE
15782 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
15783
15784 \end_inset
15785
15786
15787 \end_inset
15788 </cell>
15789 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15790 \begin_inset Text
15791
15792 \layout Standard
15793
15794 when
15795 \emph on
15796 -
15797 \begin_inset ERT
15798 status Collapsed
15799
15800 \layout Standard
15801
15802 \backslash
15803 /
15804 \end_inset
15805
15806 -model-large
15807 \emph default
15808  is used
15809 \end_inset
15810 </cell>
15811 </row>
15812 <row topline="true">
15813 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15814 \begin_inset Text
15815
15816 \layout Standard
15817
15818 SDCC_USE_XSTACK
15819 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
15820
15821 \end_inset
15822
15823
15824 \end_inset
15825 </cell>
15826 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15827 \begin_inset Text
15828
15829 \layout Standard
15830
15831 when
15832 \emph on
15833 -
15834 \begin_inset ERT
15835 status Collapsed
15836
15837 \layout Standard
15838
15839 \backslash
15840 /
15841 \end_inset
15842
15843 -xstack
15844 \emph default
15845  option is used
15846 \end_inset
15847 </cell>
15848 </row>
15849 <row topline="true">
15850 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15851 \begin_inset Text
15852
15853 \layout Standard
15854
15855 SDCC_STACK_TENBIT
15856 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
15857
15858 \end_inset
15859
15860
15861 \end_inset
15862 </cell>
15863 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15864 \begin_inset Text
15865
15866 \layout Standard
15867
15868 when
15869 \emph on
15870 -mds390
15871 \emph default
15872  is used
15873 \end_inset
15874 </cell>
15875 </row>
15876 <row topline="true" bottomline="true">
15877 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15878 \begin_inset Text
15879
15880 \layout Standard
15881
15882 SDCC_MODEL_FLAT24
15883 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
15884
15885 \end_inset
15886
15887
15888 \end_inset
15889 </cell>
15890 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15891 \begin_inset Text
15892
15893 \layout Standard
15894
15895 when
15896 \emph on
15897 -mds390
15898 \emph default
15899  is used
15900 \end_inset
15901 </cell>
15902 </row>
15903 </lyxtabular>
15904
15905 \end_inset
15906
15907
15908 \layout Chapter
15909
15910 Notes on supported Processors
15911 \layout Section
15912
15913 MCS51 variants
15914 \begin_inset LatexCommand \label{sub:MCS51-variants}
15915
15916 \end_inset
15917
15918
15919 \begin_inset LatexCommand \index{MCS51 variants}
15920
15921 \end_inset
15922
15923
15924 \layout Standard
15925
15926 MCS51 processors are available from many vendors and come in many different
15927  flavours.
15928  While they might differ considerably in respect to Special Function Registers
15929  the core MCS51 is usually not modified or is kept compatible.
15930
15931 \layout Subsection
15932
15933 pdata access by SFR
15934 \layout Standard
15935
15936 With the upcome of devices with internal xdata and flash memory devices
15937  using port P2
15938 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
15939
15940 \end_inset
15941
15942  as dedicated I/O port is becoming more popular.
15943  Switching the high byte for pdata
15944 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
15945
15946 \end_inset
15947
15948  access which was formerly done by port P2 is then achieved by a Special
15949  Function Register
15950 \begin_inset LatexCommand \index{sfr}
15951
15952 \end_inset
15953
15954 .
15955  In well-established MCS51 tradition the address of this
15956 \emph on
15957 sfr
15958 \emph default
15959  is where the chip designers decided to put it.
15960  Needless to say that they didn't agree on a common name either.
15961  So that the startup code can correctly initialize xdata variables, you
15962  should define an sfr with the name _XPAGE
15963 \family typewriter
15964
15965 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
15966
15967 \end_inset
15968
15969
15970 \family default
15971  at the appropriate location if the default, port P2, is not used for this.
15972  Some examples are:
15973 \layout Verse
15974
15975
15976 \family typewriter
15977 sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
15978 \layout Verse
15979
15980
15981 \family typewriter
15982 sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
15983 \layout Verse
15984
15985
15986 \family typewriter
15987 sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
15988 \layout Standard
15989
15990 For more exotic implementations further customizations may be needed.
15991  See section
15992 \begin_inset LatexCommand \ref{sub:Startup-Code}
15993
15994 \end_inset
15995
15996  for other possibilities.
15997 \layout Subsection
15998
15999 Other Features available by SFR
16000 \layout Standard
16001
16002 Some MCS51 variants offer features like Double DPTR
16003 \begin_inset LatexCommand \index{DPTR}
16004
16005 \end_inset
16006
16007 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
16008  These are currently not used for the MCS51 port.
16009  If you absolutely need them you can fall back to inline assembly or submit
16010  a patch to SDCC.
16011 \layout Section
16012
16013 DS400 port
16014 \layout Standard
16015
16016 The DS80C400 microcontroller has a rich set of peripherals.
16017  In its built-in ROM library it includes functions to access some of the
16018  features, among them is a TCP stack with IP4 and IP6 support.
16019  Library headers (currently in beta status) and other files are provided
16020  at
16021 \size footnotesize
16022
16023 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
16024
16025 \end_inset
16026
16027 .
16028
16029 \layout Section
16030
16031 The Z80 and gbz80 port
16032 \layout Standard
16033
16034 SDCC can target both the Zilog
16035 \begin_inset LatexCommand \index{Z80}
16036
16037 \end_inset
16038
16039  and the Nintendo Gameboy's Z80-like gbz80
16040 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
16041
16042 \end_inset
16043
16044 .
16045  The Z80 port is passed through the same
16046 \emph on
16047 regressions tests
16048 \begin_inset LatexCommand \index{Regression test}
16049
16050 \end_inset
16051
16052
16053 \emph default
16054  as the MCS51 and DS390 ports, so floating point support, support for long
16055  variables and bitfield support is fine.
16056  See mailing lists and forums about interrupt routines.
16057 \layout Standard
16058
16059 As always, the code is the authoritative reference - see z80/ralloc.c and
16060  z80/gen.c.
16061  The stack
16062 \begin_inset LatexCommand \index{stack}
16063
16064 \end_inset
16065
16066  frame is similar to that generated by the IAR Z80 compiler.
16067  IX is used as the base pointer, HL and IY are used as a temporary registers,
16068  and BC and DE are available for holding variables.
16069  Return values
16070 \begin_inset LatexCommand \index{return value}
16071
16072 \end_inset
16073
16074  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
16075  bytes).
16076  The gbz80 port use the same set of registers for the return values, but
16077  in a different order of significance: E (one byte), DE (two bytes), or
16078  HLDE (four bytes).
16079 \layout Section
16080
16081 The HC08 port
16082 \layout Standard
16083
16084 The port to the Motorola HC08
16085 \begin_inset LatexCommand \index{HC08}
16086
16087 \end_inset
16088
16089  family has been added in October 2003, and is still undergoing some basic
16090  development.
16091  The code generator is complete, but the register allocation is still quite
16092  unoptimized.
16093  Some of the SDCC's standard C library functions have embedded non-HC08
16094  inline assembly and so are not yet usable.
16095 \newline
16096
16097 \newline
16098
16099 \layout Section
16100
16101 The PIC14 port
16102 \layout Standard
16103
16104 The 14bit PIC
16105 \begin_inset LatexCommand \index{PIC14}
16106
16107 \end_inset
16108
16109  port still requires a major effort from the development community.
16110  However it can work for very simple code.
16111 \layout Subsection
16112
16113 C code and 14bit PIC code page
16114 \begin_inset LatexCommand \index{code page (pic14)}
16115
16116 \end_inset
16117
16118  and RAM banks
16119 \begin_inset LatexCommand \index{RAM bank (pic14)}
16120
16121 \end_inset
16122
16123
16124 \layout Standard
16125
16126 The linker organizes allocation for the code page and RAM banks.
16127  It does not have intimate knowledge of the code flow.
16128  It will put all the code section of a single asm file into a single code
16129  page.
16130  In order to make use of multiple code pages, separate asm files must be
16131  used.
16132  The compiler treats all functions of a single C file as being in the same
16133  code page unless it is non static.
16134  The compiler treats all local variables of a single C file as being in
16135  the same RAM bank unless it is an extern.
16136 \newline
16137
16138 \newline
16139 To get the best follow these guide lines:
16140 \layout Enumerate
16141
16142 make local functions static, as non static functions require code page selection
16143  overhead.
16144 \layout Enumerate
16145
16146 Make local variables static as extern variables require RAM bank selection
16147  overhead.
16148 \layout Enumerate
16149
16150 For devices that have multiple code pages it is more efficient to use the
16151  same number of files as pages, i.e.
16152  for the 16F877 use 4 separate files and i.e.
16153  for the 16F874 use 2 separate files.
16154  This way the linker can put the code for each file into different code
16155  pages and the compiler can allocate reusable variables more efficiently
16156  and there's less page selection overhead.
16157  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
16158  instruction set) use 'unsigned char' whereever possible instead of 'int'.
16159 \layout Subsection
16160
16161 Creating a device include file
16162 \layout Standard
16163
16164 For generating a device include file use the support perl script inc2h.pl
16165  kept in directory support/script.
16166 \layout Subsection
16167
16168 Interrupt code
16169 \layout Standard
16170
16171 For the interrupt function, use the keyword 'interrupt'
16172 \begin_inset LatexCommand \index{interrupt}
16173
16174 \end_inset
16175
16176  with level number of 0 (PIC14 only has 1 interrupt so this number is only
16177  there to avoid a syntax error - it ought to be fixed).
16178  E.g.:
16179 \layout Verse
16180
16181
16182 \family typewriter
16183 void Intr(void) interrupt 0
16184 \newline
16185 {
16186 \newline
16187 \SpecialChar ~
16188 \SpecialChar ~
16189 T0IF = 0; /* Clear timer interrupt */
16190 \newline
16191 }
16192 \layout Subsection
16193
16194 Linking and assembling
16195 \layout Standard
16196
16197 For assembling you can use either GPUTILS'
16198 \begin_inset LatexCommand \index{gputils (pic tools)}
16199
16200 \end_inset
16201
16202  gpasm.exe or MPLAB's mpasmwin.exe.
16203  GPUTILS is available from
16204 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
16205
16206 \end_inset
16207
16208 .
16209  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
16210  If you use MPLAB and an interrupt function then the linker script file
16211  vectors section will need to be enlarged to link with mplink.
16212 \newline
16213
16214 \newline
16215 Here is a
16216 \family typewriter
16217 Makefile
16218 \family default
16219  using GPUTILS:
16220 \layout Verse
16221
16222
16223 \family typewriter
16224 .c.o:
16225 \newline
16226 \SpecialChar ~
16227 \SpecialChar ~
16228 \SpecialChar ~
16229 \SpecialChar ~
16230 \SpecialChar ~
16231 \SpecialChar ~
16232 \SpecialChar ~
16233 \SpecialChar ~
16234 sdcc -S -V -mpic14 -p16F877 $<
16235 \newline
16236 \SpecialChar ~
16237 \SpecialChar ~
16238 \SpecialChar ~
16239 \SpecialChar ~
16240 \SpecialChar ~
16241 \SpecialChar ~
16242 \SpecialChar ~
16243 \SpecialChar ~
16244 gpasm -c $*.asm
16245 \newline
16246
16247 \newline
16248 $(PRJ).hex: $(OBJS)
16249 \newline
16250 \SpecialChar ~
16251 \SpecialChar ~
16252 \SpecialChar ~
16253 \SpecialChar ~
16254 \SpecialChar ~
16255 \SpecialChar ~
16256 \SpecialChar ~
16257 \SpecialChar ~
16258 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS) libsdcc.lib
16259 \layout Standard
16260
16261 Here is a
16262 \family typewriter
16263 Makefile
16264 \family default
16265  using MPLAB:
16266 \layout Verse
16267
16268
16269 \family typewriter
16270 .c.o:
16271 \newline
16272 \SpecialChar ~
16273 \SpecialChar ~
16274 \SpecialChar ~
16275 \SpecialChar ~
16276 \SpecialChar ~
16277 \SpecialChar ~
16278 \SpecialChar ~
16279 \SpecialChar ~
16280 sdcc -S -V -mpic14 -p16F877 $<
16281 \newline
16282 \SpecialChar ~
16283 \SpecialChar ~
16284 \SpecialChar ~
16285 \SpecialChar ~
16286 \SpecialChar ~
16287 \SpecialChar ~
16288 \SpecialChar ~
16289 \SpecialChar ~
16290 mpasmwin /q /o $*.asm
16291 \newline
16292
16293 \newline
16294 $(PRJ).hex: $(OBJS)
16295 \newline
16296 \SpecialChar ~
16297 \SpecialChar ~
16298 \SpecialChar ~
16299 \SpecialChar ~
16300 \SpecialChar ~
16301 \SpecialChar ~
16302 \SpecialChar ~
16303 \SpecialChar ~
16304 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS) libsdcc.lib
16305 \layout Standard
16306
16307 Please note that indentations within a
16308 \family typewriter
16309  Makefile
16310 \family default
16311  have to be done with a tabulator character.
16312 \layout Subsection
16313
16314 Command-line options
16315 \layout Standard
16316
16317 Besides the switches common to all SDCC backends, the PIC14 port accepts
16318  the following options (for an updated list see sdcc -
16319 \begin_inset ERT
16320 status Collapsed
16321
16322 \layout Standard
16323
16324 \backslash
16325 /
16326 \end_inset
16327
16328 -help):
16329 \layout List
16330 \labelwidthstring 00.00.0000
16331
16332 -
16333 \begin_inset ERT
16334 status Collapsed
16335
16336 \layout Standard
16337
16338 \backslash
16339 /
16340 \end_inset
16341
16342 -debug-extra emit debug info in assembly output
16343 \layout List
16344 \labelwidthstring 00.00.0000
16345
16346 -
16347 \begin_inset ERT
16348 status Collapsed
16349
16350 \layout Standard
16351
16352 \backslash
16353 /
16354 \end_inset
16355
16356 -no-pcode-opt disable (slightly faulty) optimization on pCode
16357 \layout Subsection
16358
16359 The library
16360 \layout Subsubsection
16361
16362 error: missing definition for symbol
16363 \begin_inset Quotes sld
16364 \end_inset
16365
16366 __gptrget1
16367 \begin_inset Quotes srd
16368 \end_inset
16369
16370
16371 \layout Standard
16372
16373 The PIC14 port uses library routines to provide more complex operations
16374  like multiplication, division/modulus and (generic) pointer dereferencing.
16375  In order to add these routines to your project, you must link with PIC14's
16376
16377 \family typewriter
16378 libsdcc.lib
16379 \family default
16380 .
16381  For single source file projects this is done automatically, more complex
16382  projects must add
16383 \family typewriter
16384 libsdcc.lib
16385 \family default
16386  to the linker's arguments.
16387  Make sure you also add an include path for the library (using the -I switch
16388  to the linker)!
16389 \layout Subsubsection
16390
16391 Processor mismatch in file
16392 \begin_inset Quotes sld
16393 \end_inset
16394
16395 XXX
16396 \begin_inset Quotes srd
16397 \end_inset
16398
16399 .
16400 \layout Standard
16401
16402 This warning can usually be ignored due to the very good compatibility amongst
16403  14 bit PIC devices.
16404 \layout Standard
16405
16406 You might also consider recompiling the library for your specific device
16407  by changing the ARCH=p16f877 (default target) entry in
16408 \family typewriter
16409 device/lib/pic/Makefile.in
16410 \family default
16411  and
16412 \family typewriter
16413 device/lib/pic/Makefile
16414 \family default
16415  to reflect your device.
16416  This might even improve performance for smaller devices as unneccesary
16417  BANKSELs migth be removed.
16418 \layout Subsection
16419
16420 Known bugs
16421 \layout Subsubsection
16422
16423 initialized data
16424 \layout Standard
16425
16426 Currently, data can only be initialized if it resides in the source file
16427  together with
16428 \emph on
16429 main()
16430 \emph default
16431 .
16432  Data in other source files will silently
16433 \series bold
16434 not
16435 \series default
16436  be initialized.
16437 \layout Section
16438
16439 The PIC16
16440 \begin_inset LatexCommand \index{PIC16}
16441
16442 \end_inset
16443
16444  port
16445 \layout Standard
16446
16447 The PIC16
16448 \begin_inset LatexCommand \index{PIC16}
16449
16450 \end_inset
16451
16452  port is the portion of SDCC that is responsible to produce code for the
16453  Microchip
16454 \begin_inset LatexCommand \index{Microchip}
16455
16456 \end_inset
16457
16458 (TM) microcontrollers with 16 bit core.
16459  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
16460  Currently supported devices are:
16461 \layout Standard
16462 \align center
16463
16464 \begin_inset  Tabular
16465 <lyxtabular version="3" rows="4" columns="6">
16466 <features>
16467 <column alignment="center" valignment="top" leftline="true" width="0">
16468 <column alignment="center" valignment="top" leftline="true" width="0">
16469 <column alignment="center" valignment="top" leftline="true" width="0">
16470 <column alignment="center" valignment="top" leftline="true" width="0">
16471 <column alignment="center" valignment="top" leftline="true" width="0">
16472 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16473 <row topline="true">
16474 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16475 \begin_inset Text
16476
16477 \layout Standard
16478
16479 18F242
16480 \end_inset
16481 </cell>
16482 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16483 \begin_inset Text
16484
16485 \layout Standard
16486
16487 18F248
16488 \end_inset
16489 </cell>
16490 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16491 \begin_inset Text
16492
16493 \layout Standard
16494
16495 18F252
16496 \end_inset
16497 </cell>
16498 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16499 \begin_inset Text
16500
16501 \layout Standard
16502
16503 18F258
16504 \end_inset
16505 </cell>
16506 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16507 \begin_inset Text
16508
16509 \layout Standard
16510
16511 18F442
16512 \end_inset
16513 </cell>
16514 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16515 \begin_inset Text
16516
16517 \layout Standard
16518
16519 18F448
16520 \end_inset
16521 </cell>
16522 </row>
16523 <row topline="true">
16524 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16525 \begin_inset Text
16526
16527 \layout Standard
16528
16529 18F452
16530 \end_inset
16531 </cell>
16532 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16533 \begin_inset Text
16534
16535 \layout Standard
16536
16537 18F458
16538 \end_inset
16539 </cell>
16540 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16541 \begin_inset Text
16542
16543 \layout Standard
16544
16545 18F1220
16546 \end_inset
16547 </cell>
16548 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16549 \begin_inset Text
16550
16551 \layout Standard
16552
16553 18F2220
16554 \end_inset
16555 </cell>
16556 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16557 \begin_inset Text
16558
16559 \layout Standard
16560
16561 18F2550
16562 \end_inset
16563 </cell>
16564 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16565 \begin_inset Text
16566
16567 \layout Standard
16568
16569 18F4331
16570 \end_inset
16571 </cell>
16572 </row>
16573 <row topline="true">
16574 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16575 \begin_inset Text
16576
16577 \layout Standard
16578
16579 18F4455
16580 \end_inset
16581 </cell>
16582 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16583 \begin_inset Text
16584
16585 \layout Standard
16586
16587 18F6520
16588 \end_inset
16589 </cell>
16590 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16591 \begin_inset Text
16592
16593 \layout Standard
16594
16595 18F6620
16596 \end_inset
16597 </cell>
16598 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16599 \begin_inset Text
16600
16601 \layout Standard
16602
16603 18F6680
16604 \end_inset
16605 </cell>
16606 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16607 \begin_inset Text
16608
16609 \layout Standard
16610
16611 18F6720
16612 \end_inset
16613 </cell>
16614 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16615 \begin_inset Text
16616
16617 \layout Standard
16618
16619 18F8520
16620 \end_inset
16621 </cell>
16622 </row>
16623 <row topline="true" bottomline="true">
16624 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16625 \begin_inset Text
16626
16627 \layout Standard
16628
16629 18F8620
16630 \end_inset
16631 </cell>
16632 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16633 \begin_inset Text
16634
16635 \layout Standard
16636
16637 18F8680
16638 \end_inset
16639 </cell>
16640 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16641 \begin_inset Text
16642
16643 \layout Standard
16644
16645 18F8720
16646 \end_inset
16647 </cell>
16648 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16649 \begin_inset Text
16650
16651 \layout Standard
16652
16653 \end_inset
16654 </cell>
16655 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16656 \begin_inset Text
16657
16658 \layout Standard
16659
16660 \end_inset
16661 </cell>
16662 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16663 \begin_inset Text
16664
16665 \layout Standard
16666
16667 \end_inset
16668 </cell>
16669 </row>
16670 </lyxtabular>
16671
16672 \end_inset
16673
16674
16675 \layout Subsection
16676
16677 Global Options
16678 \layout Standard
16679
16680 PIC16 port supports the standard command line arguments as supposed, with
16681  the exception of certain cases that will be mentioned in the following
16682  list:
16683 \layout List
16684 \labelwidthstring 00.00.0000
16685
16686 -
16687 \begin_inset ERT
16688 status Collapsed
16689
16690 \layout Standard
16691
16692 \backslash
16693 /
16694 \end_inset
16695
16696 -callee-saves See -
16697 \begin_inset ERT
16698 status Collapsed
16699
16700 \layout Standard
16701
16702 \backslash
16703 /
16704 \end_inset
16705
16706 -all-callee-saves
16707 \layout List
16708 \labelwidthstring 00.00.0000
16709
16710 -
16711 \begin_inset ERT
16712 status Collapsed
16713
16714 \layout Standard
16715
16716 \backslash
16717 /
16718 \end_inset
16719
16720 -all-callee-saves All function arguments are passed on stack by default.
16721
16722 \emph on
16723 There is no need to specify this in the command line.
16724 \layout List
16725 \labelwidthstring 00.00.0000
16726
16727 -
16728 \begin_inset ERT
16729 status Collapsed
16730
16731 \layout Standard
16732
16733 \backslash
16734 /
16735 \end_inset
16736
16737 -fommit-frame-pointer Frame pointer will be omitted when the function uses
16738  no local variables.
16739 \layout Subsection
16740
16741 Port Specific Options
16742 \begin_inset LatexCommand \index{Options PIC16}
16743
16744 \end_inset
16745
16746
16747 \layout Standard
16748
16749 The port specific options appear after the global options in the sdcc --help
16750  output.
16751 \layout Subsubsection
16752
16753 General Options
16754 \layout Standard
16755
16756 General options enable certain port features and optimizations.
16757 \layout List
16758 \labelwidthstring 00.00.0000
16759
16760 -
16761 \begin_inset ERT
16762 status Collapsed
16763
16764 \layout Standard
16765
16766 \backslash
16767 /
16768 \end_inset
16769
16770 -stack-model=[model] Used in conjuction with the command above.
16771  Defines the stack model to be used, valid stack models are :
16772 \begin_deeper
16773 \layout List
16774 \labelwidthstring 00.00.0000
16775
16776
16777 \emph on
16778 small
16779 \emph default
16780  Selects small stack model.
16781  8 bit stack and frame pointers.
16782  Supports 256 bytes stack size.
16783 \layout List
16784 \labelwidthstring 00.00.0000
16785
16786
16787 \emph on
16788 large
16789 \emph default
16790  Selects large stack model.
16791  16 bit stack and frame pointers.
16792  Supports 65536 bytes stack size.
16793 \end_deeper
16794 \layout List
16795 \labelwidthstring 00.00.0000
16796
16797 -
16798 \begin_inset ERT
16799 status Collapsed
16800
16801 \layout Standard
16802
16803 \backslash
16804 /
16805 \end_inset
16806
16807 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
16808  unitialized data variables with [kword].
16809  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
16810 \layout List
16811 \labelwidthstring 00.00.0000
16812
16813 -
16814 \begin_inset ERT
16815 status Collapsed
16816
16817 \layout Standard
16818
16819 \backslash
16820 /
16821 \end_inset
16822
16823 -ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
16824  Useful for bootloaders.
16825 \layout List
16826 \labelwidthstring 00.00.0000
16827
16828 -
16829 \begin_inset ERT
16830 status Collapsed
16831
16832 \layout Standard
16833
16834 \backslash
16835 /
16836 \end_inset
16837
16838 -asm= sets the full path and name of an external assembler to call.
16839 \layout List
16840 \labelwidthstring 00.00.0000
16841
16842 -
16843 \begin_inset ERT
16844 status Collapsed
16845
16846 \layout Standard
16847
16848 \backslash
16849 /
16850 \end_inset
16851
16852 -link= sets the full path and name of an external linker to call.
16853 \layout List
16854 \labelwidthstring 00.00.0000
16855
16856 -
16857 \begin_inset ERT
16858 status Collapsed
16859
16860 \layout Standard
16861
16862 \backslash
16863 /
16864 \end_inset
16865
16866 -mplab-comp MPLAB compatibility option.
16867  Currently only suppresses special gpasm directives.
16868 \layout Subsubsection
16869
16870 Optimization Options
16871 \layout List
16872 \labelwidthstring 00.00.0000
16873
16874 -
16875 \begin_inset ERT
16876 status Collapsed
16877
16878 \layout Standard
16879
16880 \backslash
16881 /
16882 \end_inset
16883
16884 -optimize-goto Try to use (conditional) BRA instead of GOTO
16885 \layout List
16886 \labelwidthstring 00.00.0000
16887
16888 -
16889 \begin_inset ERT
16890 status Collapsed
16891
16892 \layout Standard
16893
16894 \backslash
16895 /
16896 \end_inset
16897
16898 -optimize-cmp Try to optimize some compares.
16899 \layout List
16900 \labelwidthstring 00.00.0000
16901
16902 -
16903 \begin_inset ERT
16904 status Collapsed
16905
16906 \layout Standard
16907
16908 \backslash
16909 /
16910 \end_inset
16911
16912 -optimize-df Analyze the dataflow of the generated code and improve it.
16913 \layout List
16914 \labelwidthstring 00.00.0000
16915
16916 -
16917 \begin_inset ERT
16918 status Collapsed
16919
16920 \layout Standard
16921
16922 \backslash
16923 /
16924 \end_inset
16925
16926 -obanksel=nn Set optimization level for inserting BANKSELs.
16927 \newline
16928
16929 \begin_deeper
16930 \layout List
16931 \labelwidthstring 00.00.0000
16932
16933 0 no optimization
16934 \layout List
16935 \labelwidthstring 00.00.0000
16936
16937 1 checks previous used register and if it is the same then does not emit
16938  BANKSEL, accounts only for labels.
16939 \layout List
16940 \labelwidthstring 00.00.0000
16941
16942 2 tries to check the location of (even different) symbols and removes BANKSELs
16943  if they are in the same bank.
16944
16945 \newline
16946
16947 \emph on
16948 Important: There might be problems if the linker script has data sections
16949  across bank borders!
16950 \end_deeper
16951 \layout Subsubsection
16952
16953 Linking Options
16954 \layout List
16955 \labelwidthstring 00.00.0000
16956
16957 -
16958 \begin_inset ERT
16959 status Collapsed
16960
16961 \layout Standard
16962
16963 \backslash
16964 /
16965 \end_inset
16966
16967 -nodefaultlibs do not link default libraries when linking
16968 \layout List
16969 \labelwidthstring 00.00.0000
16970
16971 -
16972 \begin_inset ERT
16973 status Collapsed
16974
16975 \layout Standard
16976
16977 \backslash
16978 /
16979 \end_inset
16980
16981 -no-crt Don't link the default run-time modules
16982 \layout List
16983 \labelwidthstring 00.00.0000
16984
16985 -
16986 \begin_inset ERT
16987 status Collapsed
16988
16989 \layout Standard
16990
16991 \backslash
16992 /
16993 \end_inset
16994
16995 -use-crt= Use a custom run-time module instead of the defaults.
16996 \layout Subsubsection
16997
16998 Debugging Options
16999 \layout Standard
17000
17001 Debugging options enable extra debugging information in the output files.
17002 \layout List
17003 \labelwidthstring 00.00.0000
17004
17005 -
17006 \begin_inset ERT
17007 status Collapsed
17008
17009 \layout Standard
17010
17011 \backslash
17012 /
17013 \end_inset
17014
17015 -debug-xtra Similar to -
17016 \begin_inset ERT
17017 status Collapsed
17018
17019 \layout Standard
17020
17021 \backslash
17022 /
17023 \end_inset
17024
17025 -debug
17026 \begin_inset LatexCommand \index{-\/-debug}
17027
17028 \end_inset
17029
17030 , but dumps more information.
17031 \layout List
17032 \labelwidthstring 00.00.0000
17033
17034 -
17035 \begin_inset ERT
17036 status Collapsed
17037
17038 \layout Standard
17039
17040 \backslash
17041 /
17042 \end_inset
17043
17044 -debug-ralloc Force register allocator to dump <source>.d file with debugging
17045  information.
17046  <source> is the name of the file compiled.
17047 \layout List
17048 \labelwidthstring 00.00.0000
17049
17050 -
17051 \begin_inset ERT
17052 status Collapsed
17053
17054 \layout Standard
17055
17056 \backslash
17057 /
17058 \end_inset
17059
17060 -pcode-verbose Enable pcode debugging information in translation.
17061 \layout List
17062 \labelwidthstring 00.00.0000
17063
17064 -
17065 \begin_inset ERT
17066 status Collapsed
17067
17068 \layout Standard
17069
17070 \backslash
17071 /
17072 \end_inset
17073
17074 -denable-peeps Force the usage of peepholes.
17075  Use with care.
17076 \layout List
17077 \labelwidthstring 00.00.0000
17078
17079 -
17080 \begin_inset ERT
17081 status Collapsed
17082
17083 \layout Standard
17084
17085 \backslash
17086 /
17087 \end_inset
17088
17089 -gstack Trace push/pops for stack pointer overflow
17090 \layout List
17091 \labelwidthstring 00.00.0000
17092
17093 -
17094 \begin_inset ERT
17095 status Collapsed
17096
17097 \layout Standard
17098
17099 \backslash
17100 /
17101 \end_inset
17102
17103 -call-tree dump call tree in .calltree file
17104 \layout Subsection
17105
17106 Enviromental Variables
17107 \layout Standard
17108
17109 There is a number of enviromental variables that can be used when running
17110  SDCC to enable certain optimizations or force a specific program behaviour.
17111  these variables are primarily for debugging purposes so they can be enabled/dis
17112 abled at will.
17113 \layout Standard
17114
17115 Currently there is only two such variables available:
17116 \layout List
17117 \labelwidthstring 00.00.0000
17118
17119 OPTIMIZE_BITFIELD_POINTER_GET when this variable exists reading of structure
17120  bitfields is optimized by directly loading FSR0 with the address of the
17121  bitfield structure.
17122  Normally SDCC will cast the bitfield structure to a bitfield pointer and
17123  then load FSR0.
17124  This step saves data ram and code space for functions that perform heavy
17125  use of bitfields.
17126  (ie.
17127  80 bytes of code space are saved when compiling malloc.c with this option).
17128
17129 \layout List
17130 \labelwidthstring 00.00.0000
17131
17132 NO_REG_OPT do not perform pCode registers optimization.
17133  This should be used for debugging purposes.
17134  In some where bugs in the pcode optimizer are found, users can benefit
17135  from temporarily disabling the optimizer until the bug is fixed.
17136 \layout Subsection
17137
17138 Preprocessor Macros
17139 \layout Standard
17140
17141 PIC16 port defines the following preprocessor macros while translating a
17142  source.
17143 \layout Standard
17144 \align center
17145
17146 \begin_inset  Tabular
17147 <lyxtabular version="3" rows="6" columns="2">
17148 <features>
17149 <column alignment="center" valignment="top" leftline="true" width="0">
17150 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17151 <row topline="true" bottomline="true">
17152 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17153 \begin_inset Text
17154
17155 \layout Standard
17156
17157 Macro
17158 \end_inset
17159 </cell>
17160 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17161 \begin_inset Text
17162
17163 \layout Standard
17164
17165 Description
17166 \end_inset
17167 </cell>
17168 </row>
17169 <row topline="true">
17170 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17171 \begin_inset Text
17172
17173 \layout Standard
17174
17175 SDCC_pic16
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 Port identification
17184 \end_inset
17185 </cell>
17186 </row>
17187 <row topline="true">
17188 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17189 \begin_inset Text
17190
17191 \layout Standard
17192
17193 _
17194 \begin_inset ERT
17195 status Collapsed
17196
17197 \layout Standard
17198
17199 \backslash
17200 /
17201 \end_inset
17202
17203 _pic16
17204 \end_inset
17205 </cell>
17206 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17207 \begin_inset Text
17208
17209 \layout Standard
17210
17211 Port identification (same as above)
17212 \end_inset
17213 </cell>
17214 </row>
17215 <row topline="true">
17216 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17217 \begin_inset Text
17218
17219 \layout Standard
17220
17221 pic18fxxxx
17222 \end_inset
17223 </cell>
17224 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17225 \begin_inset Text
17226
17227 \layout Standard
17228
17229 MCU Identification.
17230
17231 \emph on
17232 xxxx
17233 \emph default
17234  is the microcontrol identification number, i.e.
17235  452, 6620, etc
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 _
17246 \begin_inset ERT
17247 status Collapsed
17248
17249 \layout Standard
17250
17251 \backslash
17252 /
17253 \end_inset
17254
17255 _18Fxxxx
17256 \end_inset
17257 </cell>
17258 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17259 \begin_inset Text
17260
17261 \layout Standard
17262
17263 MCU Identification (same as above)
17264 \end_inset
17265 </cell>
17266 </row>
17267 <row topline="true" bottomline="true">
17268 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17269 \begin_inset Text
17270
17271 \layout Standard
17272
17273 STACK_MODEL_nnn
17274 \end_inset
17275 </cell>
17276 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17277 \begin_inset Text
17278
17279 \layout Standard
17280
17281 nnn = SMALL or LARGE respectively according to the stack model used
17282 \end_inset
17283 </cell>
17284 </row>
17285 </lyxtabular>
17286
17287 \end_inset
17288
17289
17290 \layout Standard
17291
17292 In addition the following macros are defined when calling assembler:
17293 \layout Standard
17294 \align center
17295
17296 \begin_inset  Tabular
17297 <lyxtabular version="3" rows="4" columns="2">
17298 <features>
17299 <column alignment="center" valignment="top" leftline="true" width="0">
17300 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17301 <row topline="true" bottomline="true">
17302 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17303 \begin_inset Text
17304
17305 \layout Standard
17306
17307 Macro
17308 \end_inset
17309 </cell>
17310 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17311 \begin_inset Text
17312
17313 \layout Standard
17314
17315 Description
17316 \end_inset
17317 </cell>
17318 </row>
17319 <row topline="true">
17320 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17321 \begin_inset Text
17322
17323 \layout Standard
17324
17325 __18Fxxxx
17326 \end_inset
17327 </cell>
17328 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17329 \begin_inset Text
17330
17331 \layout Standard
17332
17333 MCU Identification.
17334
17335 \emph on
17336 xxxx
17337 \emph default
17338  is the microcontrol identification number, i.e.
17339  452, 6620, etc
17340 \end_inset
17341 </cell>
17342 </row>
17343 <row topline="true">
17344 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17345 \begin_inset Text
17346
17347 \layout Standard
17348
17349 SDCC_MODEL_nnn
17350 \end_inset
17351 </cell>
17352 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17353 \begin_inset Text
17354
17355 \layout Standard
17356
17357 nnn = SMALL or LARGE respectively according to the memory model used for
17358  SDCC
17359 \end_inset
17360 </cell>
17361 </row>
17362 <row topline="true" bottomline="true">
17363 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17364 \begin_inset Text
17365
17366 \layout Standard
17367
17368 STACK_MODEL_nnn
17369 \end_inset
17370 </cell>
17371 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17372 \begin_inset Text
17373
17374 \layout Standard
17375
17376 nnn = SMALL or LARGE respectively according to the stack model used
17377 \end_inset
17378 </cell>
17379 </row>
17380 </lyxtabular>
17381
17382 \end_inset
17383
17384
17385 \layout Subsection
17386
17387 Directories
17388 \layout Standard
17389
17390 PIC16
17391 \begin_inset LatexCommand \index{PIC16}
17392
17393 \end_inset
17394
17395  port uses the following directories for searching header files and libraries.
17396 \layout Standard
17397 \align center
17398
17399 \begin_inset  Tabular
17400 <lyxtabular version="3" rows="3" columns="4">
17401 <features>
17402 <column alignment="center" valignment="top" leftline="true" width="0">
17403 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17404 <column alignment="center" valignment="top" width="0">
17405 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17406 <row topline="true" bottomline="true">
17407 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17408 \begin_inset Text
17409
17410 \layout Standard
17411
17412 Directory
17413 \end_inset
17414 </cell>
17415 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17416 \begin_inset Text
17417
17418 \layout Standard
17419
17420 Description
17421 \end_inset
17422 </cell>
17423 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17424 \begin_inset Text
17425
17426 \layout Standard
17427
17428 Target
17429 \end_inset
17430 </cell>
17431 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17432 \begin_inset Text
17433
17434 \layout Standard
17435
17436 Command prefix
17437 \end_inset
17438 </cell>
17439 </row>
17440 <row topline="true">
17441 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17442 \begin_inset Text
17443
17444 \layout Standard
17445
17446 PREFIX/sdcc/include/pic16
17447 \end_inset
17448 </cell>
17449 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17450 \begin_inset Text
17451
17452 \layout Standard
17453
17454 PIC16 specific headers
17455 \end_inset
17456 </cell>
17457 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17458 \begin_inset Text
17459
17460 \layout Standard
17461
17462 Compiler
17463 \end_inset
17464 </cell>
17465 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17466 \begin_inset Text
17467
17468 \layout Standard
17469
17470 -I
17471 \end_inset
17472 </cell>
17473 </row>
17474 <row topline="true" bottomline="true">
17475 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17476 \begin_inset Text
17477
17478 \layout Standard
17479
17480 PREFIX/sdcc/lib/pic16
17481 \end_inset
17482 </cell>
17483 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17484 \begin_inset Text
17485
17486 \layout Standard
17487
17488 PIC16 specific libraries
17489 \end_inset
17490 </cell>
17491 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17492 \begin_inset Text
17493
17494 \layout Standard
17495
17496 Linker
17497 \end_inset
17498 </cell>
17499 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17500 \begin_inset Text
17501
17502 \layout Standard
17503
17504 -L
17505 \end_inset
17506 </cell>
17507 </row>
17508 </lyxtabular>
17509
17510 \end_inset
17511
17512
17513 \layout Subsection
17514
17515 Pragmas
17516 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
17517
17518 \end_inset
17519
17520
17521 \layout Standard
17522
17523 PIC16 port currently supports the following pragmas:
17524 \layout List
17525 \labelwidthstring 00.00.0000
17526
17527 stack pragma stack forces the code generator to initialize the stack & frame
17528  pointers at a specific address.
17529  This is an adhoc solution for cases where no STACK directive is available
17530  in the linker script or gplink is not instructed to create a stack section.
17531 \newline
17532 The stack pragma should be used only once in a project.
17533  Multiple pragmas may result in indeterminate behaviour of the program.
17534 \begin_inset Foot
17535 collapsed false
17536
17537 \layout Standard
17538
17539 The old format (ie.
17540  #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
17541  cross page boundaries (or even exceed the available data RAM) and crash
17542  the program.
17543  Make sure that stack does not cross page boundaries when using the SMALL
17544  stack model.
17545 \end_inset
17546
17547
17548 \newline
17549 The format is as follows:
17550 \layout LyX-Code
17551
17552 #pragma stack bottom_address [stack_size]
17553 \layout Standard
17554
17555
17556 \emph on
17557 bottom_address
17558 \emph default
17559  is the lower bound of the stack section.
17560  The stack pointer initially will point at address (bottom_address+stack_size-1).
17561 \layout LyX-Code
17562
17563 Example:
17564 \layout LyX-Code
17565
17566 \layout LyX-Code
17567
17568 /* initializes stack of 100 bytes at RAM address 0x200 */
17569 \layout LyX-Code
17570
17571 #pragma stack 0x200 100
17572 \layout Standard
17573
17574 If the stack_size field is omitted then a stack is created with the default
17575  size of 64.
17576  This size might be enough for most programs, but its not enough for operations
17577  with deep function nesting or excessive stack usage.
17578 \layout List
17579 \labelwidthstring 00.00.0000
17580
17581 wparam
17582 \emph on
17583 This pragma is deprecated.
17584  Its use will cause a warning message to be issued.
17585 \emph default
17586
17587 \newline
17588
17589 \layout List
17590 \labelwidthstring 00.00.0000
17591
17592 code place a function symbol at static FLASH address
17593 \layout LyX-Code
17594
17595 Example:
17596 \layout LyX-Code
17597
17598 \layout LyX-Code
17599
17600 /* place function test_func at 0x4000 */
17601 \layout LyX-Code
17602
17603 #pragma code test_func 0x4000
17604 \layout LyX-Code
17605
17606 \layout List
17607 \labelwidthstring 00.00.0000
17608
17609 library instructs the linker to use a library module.
17610 \newline
17611 Usage:
17612 \layout LyX-Code
17613
17614 #pragma library module_name
17615 \layout Standard
17616
17617
17618 \emph on
17619 module_name
17620 \emph default
17621  can be any library or object file (including its path).
17622  Note that there are four reserved keywords which have special meaning.
17623  These are:
17624 \layout Standard
17625 \align center
17626
17627 \begin_inset  Tabular
17628 <lyxtabular version="3" rows="6" columns="3">
17629 <features>
17630 <column alignment="center" valignment="top" leftline="true" width="0">
17631 <column alignment="block" valignment="top" leftline="true" width="20page%">
17632 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
17633 <row topline="true" bottomline="true">
17634 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17635 \begin_inset Text
17636
17637 \layout Standard
17638
17639 Keyword
17640 \end_inset
17641 </cell>
17642 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17643 \begin_inset Text
17644
17645 \layout Standard
17646
17647 Description
17648 \end_inset
17649 </cell>
17650 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17651 \begin_inset Text
17652
17653 \layout Standard
17654
17655 Module to link
17656 \end_inset
17657 </cell>
17658 </row>
17659 <row topline="true">
17660 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17661 \begin_inset Text
17662
17663 \layout Standard
17664
17665
17666 \series bold
17667 ignore
17668 \end_inset
17669 </cell>
17670 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17671 \begin_inset Text
17672
17673 \layout Standard
17674
17675 ignore all library pragmas
17676 \end_inset
17677 </cell>
17678 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17679 \begin_inset Text
17680
17681 \layout Standard
17682
17683
17684 \emph on
17685 (none)
17686 \end_inset
17687 </cell>
17688 </row>
17689 <row topline="true">
17690 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17691 \begin_inset Text
17692
17693 \layout Standard
17694
17695
17696 \series bold
17697 c
17698 \end_inset
17699 </cell>
17700 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17701 \begin_inset Text
17702
17703 \layout Standard
17704
17705 link the C library
17706 \end_inset
17707 </cell>
17708 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17709 \begin_inset Text
17710
17711 \layout Standard
17712
17713
17714 \emph on
17715 libc18f
17716 \emph default
17717 .lib
17718 \end_inset
17719 </cell>
17720 </row>
17721 <row topline="true">
17722 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17723 \begin_inset Text
17724
17725 \layout Standard
17726
17727
17728 \series bold
17729 math
17730 \end_inset
17731 </cell>
17732 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17733 \begin_inset Text
17734
17735 \layout Standard
17736
17737 link the Math libarary
17738 \end_inset
17739 </cell>
17740 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17741 \begin_inset Text
17742
17743 \layout Standard
17744
17745
17746 \emph on
17747 libm18f
17748 \emph default
17749 .lib
17750 \end_inset
17751 </cell>
17752 </row>
17753 <row topline="true">
17754 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17755 \begin_inset Text
17756
17757 \layout Standard
17758
17759
17760 \series bold
17761 io
17762 \end_inset
17763 </cell>
17764 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17765 \begin_inset Text
17766
17767 \layout Standard
17768
17769 link the I/O library
17770 \end_inset
17771 </cell>
17772 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17773 \begin_inset Text
17774
17775 \layout Standard
17776
17777
17778 \emph on
17779 libio18f*
17780 \emph default
17781 .lib
17782 \end_inset
17783 </cell>
17784 </row>
17785 <row topline="true" bottomline="true">
17786 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17787 \begin_inset Text
17788
17789 \layout Standard
17790
17791
17792 \series bold
17793 debug
17794 \end_inset
17795 </cell>
17796 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17797 \begin_inset Text
17798
17799 \layout Standard
17800
17801 link the debug library
17802 \end_inset
17803 </cell>
17804 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17805 \begin_inset Text
17806
17807 \layout Standard
17808
17809
17810 \emph on
17811 libdebug
17812 \emph default
17813 .lib
17814 \end_inset
17815 </cell>
17816 </row>
17817 </lyxtabular>
17818
17819 \end_inset
17820
17821
17822 \newline
17823 * is the device number, i.e.
17824  452 for PIC18F452 MCU.
17825 \layout Standard
17826
17827 This feature allows for linking with specific libraries withoug having to
17828  explicit name them in the command line.
17829  Note that the
17830 \noun on
17831 ignore
17832 \noun default
17833  keyword will reject all modules specified by the library pragma.
17834 \layout List
17835 \labelwidthstring 00.00.0000
17836
17837 udata pragma udata instructs the compiler to emit code so that linker will
17838  place a variable at a specific memory bank
17839 \layout LyX-Code
17840
17841 Example:
17842 \layout LyX-Code
17843
17844 \layout LyX-Code
17845
17846 /* places variable foo at bank2 */
17847 \layout LyX-Code
17848
17849 #pragma udata bank2 foo
17850 \layout LyX-Code
17851
17852 char foo;
17853 \layout Standard
17854
17855 In order for this pragma to work extra SECTION directives should be added
17856  in the .lkr script.
17857  In the following example a sample .lkr file is shown:
17858 \layout LyX-Code
17859
17860 \layout LyX-Code
17861
17862 // Sample linker script for the PIC18F452 processor
17863 \layout LyX-Code
17864
17865 LIBPATH .
17866 \layout LyX-Code
17867
17868 CODEPAGE   NAME=vectors    START=0x0            END=0x29           PROTECTED
17869 \layout LyX-Code
17870
17871 CODEPAGE   NAME=page       START=0x2A           END=0x7FFF
17872 \layout LyX-Code
17873
17874 CODEPAGE   NAME=idlocs     START=0x200000       END=0x200007       PROTECTED
17875 \layout LyX-Code
17876
17877 CODEPAGE   NAME=config     START=0x300000       END=0x30000D       PROTECTED
17878 \layout LyX-Code
17879
17880 CODEPAGE   NAME=devid      START=0x3FFFFE       END=0x3FFFFF       PROTECTED
17881 \layout LyX-Code
17882
17883 CODEPAGE   NAME=eedata     START=0xF00000       END=0xF000FF       PROTECTED
17884 \layout LyX-Code
17885
17886 ACCESSBANK NAME=accessram  START=0x0            END=0x7F
17887 \layout LyX-Code
17888
17889 \layout LyX-Code
17890
17891 DATABANK   NAME=gpr0       START=0x80           END=0xFF
17892 \layout LyX-Code
17893
17894 DATABANK   NAME=gpr1       START=0x100          END=0x1FF
17895 \layout LyX-Code
17896
17897 DATABANK   NAME=gpr2       START=0x200          END=0x2FF
17898 \layout LyX-Code
17899
17900 DATABANK   NAME=gpr3       START=0x300          END=0x3FF
17901 \layout LyX-Code
17902
17903 DATABANK   NAME=gpr4       START=0x400          END=0x4FF
17904 \layout LyX-Code
17905
17906 DATABANK   NAME=gpr5       START=0x500          END=0x5FF
17907 \layout LyX-Code
17908
17909 ACCESSBANK NAME=accesssfr  START=0xF80          END=0xFFF          PROTECTED
17910 \layout LyX-Code
17911
17912 \layout LyX-Code
17913
17914 SECTION    NAME=CONFIG     ROM=config
17915 \layout LyX-Code
17916
17917 \layout LyX-Code
17918
17919 SECTION    NAME=bank0      RAM=gpr0       # these SECTION directives
17920 \layout LyX-Code
17921
17922 SECTION    NAME=bank1      RAM=gpr1       # should be added to link
17923 \layout LyX-Code
17924
17925 SECTION    NAME=bank2      RAM=gpr2       # section name 'bank?' with
17926 \layout LyX-Code
17927
17928 SECTION    NAME=bank3      RAM=gpr3       # a specific DATABANK name
17929 \layout LyX-Code
17930
17931 SECTION    NAME=bank4      RAM=gpr4
17932 \layout LyX-Code
17933
17934 SECTION    NAME=bank5      RAM=gpr5
17935 \layout Standard
17936
17937 The linker will recognise the section name set in the pragma statement and
17938  will position the variable at the memory bank set with the RAM field at
17939  the SECTION line in the linker script file.
17940 \layout Subsection
17941
17942 Header Files
17943 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
17944
17945 \end_inset
17946
17947
17948 \layout Standard
17949
17950 There is one main header file that can be included to the source files using
17951  the pic16 port.
17952  That file is the
17953 \series bold
17954 pic18fregs.h
17955 \series default
17956 .
17957  This header file contains the definitions for the processor special registers,
17958  so it is necessary if the source accesses them.
17959  It can be included by adding the following line in the beginning of the
17960  file:
17961 \layout LyX-Code
17962
17963 #include <pic18fregs.h>
17964 \layout Standard
17965
17966 The specific microcontroller is selected within the pic18fregs.h automatically,
17967  so the same source can be used with a variety of devices.
17968 \layout Subsection
17969
17970 Libraries
17971 \layout Standard
17972
17973 The libraries that PIC16
17974 \begin_inset LatexCommand \index{PIC16}
17975
17976 \end_inset
17977
17978  port depends on are the microcontroller device libraries which contain
17979  the symbol definitions for the microcontroller special function registers.
17980  These libraries have the format pic18fxxxx.lib, where
17981 \emph on
17982 xxxx
17983 \emph default
17984  is the microcontroller identification number.
17985  The specific library is selected automatically by the compiler at link
17986  stage according to the selected device.
17987 \layout Standard
17988
17989 Libraries are created with gplib which is part of the gputils package
17990 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
17991
17992 \end_inset
17993
17994 .
17995 \layout Subsubsection*
17996
17997 Building the libraries
17998 \layout Standard
17999
18000 Before using SDCC/pic16 there are some libraries that need to be compiled.
18001  This process is not done automatically by SDCC since not all users use
18002  SDCC for pic16 projects.
18003  So each user should compile the libraries separately.
18004 \layout Standard
18005
18006 The steps to compile the pic16 libraries under Linux are:
18007 \layout LyX-Code
18008
18009 cd device/lib/pic16
18010 \layout LyX-Code
18011
18012 ./configure
18013 \layout LyX-Code
18014
18015 make
18016 \layout LyX-Code
18017
18018 cd ..
18019 \layout LyX-Code
18020
18021 make model-pic16
18022 \layout LyX-Code
18023
18024 su -c 'make install'     # install the libraries, you need the root password
18025 \layout Standard
18026
18027 If you need to install the headers too, do:
18028 \layout LyX-Code
18029
18030 cd device/include
18031 \layout LyX-Code
18032
18033 su -c 'make install'     # install the headers, you need the root password
18034 \layout Standard
18035
18036 There exist a special target to build the I/O libraries.
18037  This target is not automatically build because it will build the I/O library
18038  for
18039 \emph on
18040 every
18041 \emph default
18042  supported device.
18043  This way building will take quite a lot of time.
18044  Users are advised to edit the
18045 \series bold
18046 device/lib/pic16/pics.build
18047 \series default
18048  file and then execute:
18049 \layout LyX-Code
18050
18051 make lib-io
18052 \layout Subsection
18053
18054 Memory Models
18055 \layout Standard
18056
18057 The following memory models are supported by the PIC16 port:
18058 \layout Itemize
18059
18060 small model
18061 \layout Itemize
18062
18063 large model
18064 \layout Standard
18065
18066 Memory model affects the default size of pointers within the source.
18067  The sizes are shown in the next table:
18068 \layout Standard
18069 \align center
18070
18071 \begin_inset  Tabular
18072 <lyxtabular version="3" rows="3" columns="3">
18073 <features>
18074 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18075 <column alignment="center" valignment="top" leftline="true" width="0">
18076 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18077 <row topline="true" bottomline="true">
18078 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18079 \begin_inset Text
18080
18081 \layout Standard
18082
18083 Pointer sizes according to memory model
18084 \end_inset
18085 </cell>
18086 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18087 \begin_inset Text
18088
18089 \layout Standard
18090
18091 small model
18092 \end_inset
18093 </cell>
18094 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18095 \begin_inset Text
18096
18097 \layout Standard
18098
18099 large model
18100 \end_inset
18101 </cell>
18102 </row>
18103 <row topline="true" bottomline="true">
18104 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18105 \begin_inset Text
18106
18107 \layout Standard
18108
18109 code pointers
18110 \end_inset
18111 </cell>
18112 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18113 \begin_inset Text
18114
18115 \layout Standard
18116
18117 16-bits
18118 \end_inset
18119 </cell>
18120 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18121 \begin_inset Text
18122
18123 \layout Standard
18124
18125 24-bits
18126 \end_inset
18127 </cell>
18128 </row>
18129 <row topline="true" bottomline="true">
18130 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18131 \begin_inset Text
18132
18133 \layout Standard
18134
18135 data pointers
18136 \end_inset
18137 </cell>
18138 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
18139 \begin_inset Text
18140
18141 \layout Standard
18142
18143 16-bits
18144 \end_inset
18145 </cell>
18146 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18147 \begin_inset Text
18148
18149 \layout Standard
18150
18151 16-bits
18152 \end_inset
18153 </cell>
18154 </row>
18155 </lyxtabular>
18156
18157 \end_inset
18158
18159
18160 \layout Standard
18161
18162 It is advisable that all sources within a project are compiled with the
18163  same memory model.
18164  If one wants to override the default memory model, this can be done by
18165  declaring a pointer as
18166 \series bold
18167 far
18168 \series default
18169  or
18170 \series bold
18171 near
18172 \series default
18173 .
18174  Far selects large memory model's pointers, while near selects small memory
18175  model's pointers.
18176 \layout Standard
18177
18178 The standard device libraries (see
18179 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
18180
18181 \end_inset
18182
18183 ) contain no reference to pointers, so they can be used with both memory
18184  models.
18185 \layout Subsection
18186
18187 Stack
18188 \layout Standard
18189
18190 The stack implementation for the PIC16 port uses two indirect registers,
18191  FSR1 and FSR2.
18192 \layout List
18193 \labelwidthstring 00.00.0000
18194
18195 FSR1 is assigned as stack pointer
18196 \layout List
18197 \labelwidthstring 00.00.0000
18198
18199 FSR2 is assigned as frame pointer
18200 \layout Standard
18201
18202 The following stack models are supported by the PIC16 port
18203 \layout Itemize
18204
18205
18206 \noun on
18207 small
18208 \noun default
18209  model
18210 \layout Itemize
18211
18212
18213 \noun on
18214 large
18215 \noun default
18216  model
18217 \layout Standard
18218
18219
18220 \noun on
18221 Small
18222 \noun default
18223  model means that only the FSRxL byte is used to access stack and frame,
18224  while
18225 \emph on
18226 \noun on
18227 large
18228 \emph default
18229 \noun default
18230  uses both FSRxL and FSRxH registers.
18231  The following table shows the stack/frame pointers sizes according to stack
18232  model and the maximum space they can address:
18233 \layout Standard
18234 \align center
18235
18236 \begin_inset  Tabular
18237 <lyxtabular version="3" rows="3" columns="3">
18238 <features>
18239 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18240 <column alignment="center" valignment="top" leftline="true" width="0">
18241 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18242 <row topline="true" bottomline="true">
18243 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18244 \begin_inset Text
18245
18246 \layout Standard
18247
18248 Stack & Frame pointer sizes according to stack model
18249 \end_inset
18250 </cell>
18251 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18252 \begin_inset Text
18253
18254 \layout Standard
18255
18256 small
18257 \end_inset
18258 </cell>
18259 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18260 \begin_inset Text
18261
18262 \layout Standard
18263
18264 large
18265 \end_inset
18266 </cell>
18267 </row>
18268 <row topline="true">
18269 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18270 \begin_inset Text
18271
18272 \layout Standard
18273
18274 Stack pointer FSR1
18275 \end_inset
18276 </cell>
18277 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18278 \begin_inset Text
18279
18280 \layout Standard
18281
18282 8-bits
18283 \end_inset
18284 </cell>
18285 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18286 \begin_inset Text
18287
18288 \layout Standard
18289
18290 16-bits
18291 \end_inset
18292 </cell>
18293 </row>
18294 <row topline="true" bottomline="true">
18295 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18296 \begin_inset Text
18297
18298 \layout Standard
18299
18300 Frame pointer FSR2
18301 \end_inset
18302 </cell>
18303 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18304 \begin_inset Text
18305
18306 \layout Standard
18307
18308 8-bits
18309 \end_inset
18310 </cell>
18311 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18312 \begin_inset Text
18313
18314 \layout Standard
18315
18316 16-bits
18317 \end_inset
18318 </cell>
18319 </row>
18320 </lyxtabular>
18321
18322 \end_inset
18323
18324
18325 \layout Standard
18326
18327
18328 \noun on
18329 Large
18330 \noun default
18331 stack model is currently not working properly throughout the code generator.
18332  So its use is not advised.
18333  Also there are some other points that need special care:
18334 \newline
18335
18336 \layout Enumerate
18337
18338 Do not create stack sections with size more than one physical bank (that
18339  is 256 bytes)
18340 \layout Enumerate
18341
18342 Stack sections should no cross physical bank limits (i.e.
18343  #pragma stack 0x50 0x100)
18344 \layout Standard
18345
18346 These limitations are caused by the fact that only FSRxL is modified when
18347  using SMALL stack model, so no more than 256 bytes of stack can be used.
18348  This problem will disappear after LARGE model is fully implemented.
18349 \layout Subsection
18350
18351 Functions
18352 \layout Standard
18353
18354 In addition to the standard SDCC function keywords, PIC16 port makes available
18355  two more:
18356 \layout List
18357 \labelwidthstring 00.00.0000
18358
18359 wparam Use the WREG to pass one byte of the first function argument.
18360  This improves speed but you may not use this for functions with arguments
18361  that are called via function pointers, otherwise the first byte of the
18362  first parameter will get lost.
18363  Usage:
18364 \layout LyX-Code
18365
18366 void func_wparam(int a) wparam
18367 \layout LyX-Code
18368
18369 {
18370 \layout LyX-Code
18371
18372     /* WREG hold the lower part of a */
18373 \layout LyX-Code
18374
18375     /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
18376  */
18377 \layout LyX-Code
18378
18379 ...
18380 \layout LyX-Code
18381
18382 }
18383 \layout Standard
18384
18385 This keyword replaces the deprecated wparam pragma.
18386 \layout List
18387 \labelwidthstring 00.00.0000
18388
18389 shadowregs When entering/exiting an ISR, it is possible to take advantage
18390  of the PIC18F hardware shadow registers which hold the values of WREG,
18391  STATUS and BSR registers.
18392  This can be done by adding the keyword
18393 \emph on
18394 shadowregs
18395 \emph default
18396  before the
18397 \emph on
18398 interrupt
18399 \emph default
18400  keyword in the function's header.
18401 \layout LyX-Code
18402
18403 void isr_shadow(void) shadowregs interrupt 1
18404 \layout LyX-Code
18405
18406 {
18407 \layout LyX-Code
18408
18409 ...
18410 \layout LyX-Code
18411
18412 }
18413 \layout Standard
18414
18415
18416 \emph on
18417 shadowregs
18418 \emph default
18419  instructs the code generator not to store/restore WREG, STATUS, BSR when
18420  entering/exiting the ISR.
18421 \layout Subsection
18422
18423 Function return values
18424 \layout Standard
18425
18426 Return values from functions are placed to the appropriate registers following
18427  a modified Microchip policy optimized for SDCC.
18428  The following table shows these registers:
18429 \layout Standard
18430 \align center
18431
18432 \begin_inset  Tabular
18433 <lyxtabular version="3" rows="6" columns="2">
18434 <features>
18435 <column alignment="center" valignment="top" leftline="true" width="0">
18436 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18437 <row topline="true" bottomline="true">
18438 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18439 \begin_inset Text
18440
18441 \layout Standard
18442
18443 size
18444 \end_inset
18445 </cell>
18446 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18447 \begin_inset Text
18448
18449 \layout Standard
18450
18451 destination register
18452 \end_inset
18453 </cell>
18454 </row>
18455 <row topline="true">
18456 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18457 \begin_inset Text
18458
18459 \layout Standard
18460
18461 8 bits
18462 \end_inset
18463 </cell>
18464 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18465 \begin_inset Text
18466
18467 \layout Standard
18468
18469 WREG
18470 \end_inset
18471 </cell>
18472 </row>
18473 <row topline="true">
18474 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18475 \begin_inset Text
18476
18477 \layout Standard
18478
18479 16 bits
18480 \end_inset
18481 </cell>
18482 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18483 \begin_inset Text
18484
18485 \layout Standard
18486
18487 PRODL:WREG
18488 \end_inset
18489 </cell>
18490 </row>
18491 <row topline="true">
18492 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18493 \begin_inset Text
18494
18495 \layout Standard
18496
18497 24 bits
18498 \end_inset
18499 </cell>
18500 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18501 \begin_inset Text
18502
18503 \layout Standard
18504
18505 PRODH:PRODL:WREG
18506 \end_inset
18507 </cell>
18508 </row>
18509 <row topline="true">
18510 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18511 \begin_inset Text
18512
18513 \layout Standard
18514
18515 32 bits
18516 \end_inset
18517 </cell>
18518 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18519 \begin_inset Text
18520
18521 \layout Standard
18522
18523 FSR0L:PRODH:PRODL:WREG
18524 \end_inset
18525 </cell>
18526 </row>
18527 <row topline="true" bottomline="true">
18528 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18529 \begin_inset Text
18530
18531 \layout Standard
18532
18533 >32 bits
18534 \end_inset
18535 </cell>
18536 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18537 \begin_inset Text
18538
18539 \layout Standard
18540
18541 on stack, FSR0 points to the beginning
18542 \end_inset
18543 </cell>
18544 </row>
18545 </lyxtabular>
18546
18547 \end_inset
18548
18549
18550 \layout Subsection
18551
18552 Interrupts
18553 \layout Standard
18554
18555 An interrupt servive routine (ISR) is declared using the
18556 \emph on
18557 interrupt
18558 \emph default
18559  keyword.
18560 \layout LyX-Code
18561
18562 void isr(void) interrupt
18563 \emph on
18564 n
18565 \layout LyX-Code
18566
18567 {
18568 \layout LyX-Code
18569
18570 ...
18571 \layout LyX-Code
18572
18573 }
18574 \layout Standard
18575
18576
18577 \emph on
18578 n
18579 \emph default
18580  is the interrupt number, which for PIC18F devices can be:
18581 \layout Standard
18582 \align center
18583
18584 \begin_inset  Tabular
18585 <lyxtabular version="3" rows="4" columns="3">
18586 <features>
18587 <column alignment="center" valignment="top" leftline="true" width="0">
18588 <column alignment="center" valignment="top" leftline="true" width="0">
18589 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18590 <row topline="true" bottomline="true">
18591 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18592 \begin_inset Text
18593
18594 \layout Standard
18595
18596
18597 \emph on
18598 n
18599 \end_inset
18600 </cell>
18601 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18602 \begin_inset Text
18603
18604 \layout Standard
18605
18606 Interrupt Vector
18607 \end_inset
18608 </cell>
18609 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18610 \begin_inset Text
18611
18612 \layout Standard
18613
18614 Interrupt Vector Address
18615 \end_inset
18616 </cell>
18617 </row>
18618 <row topline="true">
18619 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18620 \begin_inset Text
18621
18622 \layout Standard
18623
18624 0
18625 \end_inset
18626 </cell>
18627 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18628 \begin_inset Text
18629
18630 \layout Standard
18631
18632 RESET vector
18633 \end_inset
18634 </cell>
18635 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18636 \begin_inset Text
18637
18638 \layout Standard
18639
18640 0x000000
18641 \end_inset
18642 </cell>
18643 </row>
18644 <row topline="true">
18645 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18646 \begin_inset Text
18647
18648 \layout Standard
18649
18650
18651 \family roman
18652 \series medium
18653 \shape up
18654 \size normal
18655 \emph off
18656 \bar no
18657 \noun off
18658 \color none
18659 1
18660 \end_inset
18661 </cell>
18662 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18663 \begin_inset Text
18664
18665 \layout Standard
18666
18667
18668 \family roman
18669 \series medium
18670 \shape up
18671 \size normal
18672 \emph off
18673 \bar no
18674 \noun off
18675 \color none
18676 HIGH priority interrupts
18677 \end_inset
18678 </cell>
18679 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18680 \begin_inset Text
18681
18682 \layout Standard
18683
18684 0x000008
18685 \end_inset
18686 </cell>
18687 </row>
18688 <row topline="true" bottomline="true">
18689 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18690 \begin_inset Text
18691
18692 \layout Standard
18693
18694 2
18695 \end_inset
18696 </cell>
18697 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18698 \begin_inset Text
18699
18700 \layout Standard
18701
18702 LOW priority interrupts
18703 \end_inset
18704 </cell>
18705 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18706 \begin_inset Text
18707
18708 \layout Standard
18709
18710 0x000018
18711 \end_inset
18712 </cell>
18713 </row>
18714 </lyxtabular>
18715
18716 \end_inset
18717
18718
18719 \layout Standard
18720
18721 When generating assembly code for ISR the code generator places a
18722 \noun on
18723 goto
18724 \noun default
18725 instruction at the
18726 \emph on
18727 Interrupt Vector Address
18728 \emph default
18729  which points at the genetated ISR.
18730  This single GOTO instruction is part of an automatically generated
18731 \emph on
18732 interrupt entry point
18733 \emph default
18734  function.
18735  The actuall ISR code is placed as normally would in the code space.
18736  Upon interrupt request, the GOTO instruction is executed which jumps to
18737  the ISR code.
18738  When declaring interrupt functions as _naked this GOTO instruction is
18739 \series bold
18740 not
18741 \series default
18742  generated.
18743  The whole interrupt functions is therefore placed at the Interrupt Vector
18744  Address of the specific interrupt.
18745  This is not a problem for the LOW priority interrupts, but it is a problem
18746  for the RESET and the HIGH priority interrupts because code may be written
18747  at the next interrupt´s vector address and cause undeterminate program
18748  behaviour if that interrupt is raised.
18749 \begin_inset Foot
18750 collapsed false
18751
18752 \layout Standard
18753
18754 This is not a problem when
18755 \layout Enumerate
18756
18757 this is a HIGH interrupt ISR and LOW interrupts are
18758 \emph on
18759 disabled
18760 \emph default
18761  or not used.
18762 \layout Enumerate
18763
18764 when the ISR is small enough not to reach the next interrupt´s vector address.
18765 \end_inset
18766
18767
18768 \layout Standard
18769
18770
18771 \emph on
18772 n
18773 \emph default
18774  is possible to be omitted.
18775  This way a function is generated similar to an ISR, but it is not assigned
18776  to any interrupt.
18777 \layout Standard
18778
18779 When entering an interrupt, currently the PIC16
18780 \begin_inset LatexCommand \index{PIC16}
18781
18782 \end_inset
18783
18784  port automatically saves the following registers:
18785 \layout Itemize
18786
18787 WREG
18788 \layout Itemize
18789
18790 STATUS
18791 \layout Itemize
18792
18793 BSR
18794 \layout Itemize
18795
18796 PROD (PRODL and PRODH)
18797 \layout Itemize
18798
18799 FSR0 (FSR0L and FSR0H)
18800 \layout Standard
18801
18802 These registers are restored upon return from the interrupt routine.
18803 \begin_inset Foot
18804 collapsed false
18805
18806 \layout Standard
18807
18808 NOTE that when the _naked attribute is specified for an interrupt routine,
18809  then NO registers are stored or restored.
18810 \end_inset
18811
18812
18813 \layout Subsection
18814
18815 Generic Pointers
18816 \layout Standard
18817
18818 Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
18819  There are 3 types of generic pointers currently implemented data, code
18820  and eeprom pointers.
18821  They are differentiated by the value of the 7th and 6th bits of the upper
18822  byte:
18823 \layout Standard
18824 \align center
18825
18826 \begin_inset  Tabular
18827 <lyxtabular version="3" rows="5" columns="5">
18828 <features>
18829 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18830 <column alignment="center" valignment="top" width="0">
18831 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18832 <column alignment="center" valignment="top" width="0">
18833 <column alignment="left" valignment="top" rightline="true" width="0">
18834 <row topline="true" bottomline="true">
18835 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18836 \begin_inset Text
18837
18838 \layout Standard
18839
18840 pointer type
18841 \end_inset
18842 </cell>
18843 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18844 \begin_inset Text
18845
18846 \layout Standard
18847
18848 7th bit
18849 \end_inset
18850 </cell>
18851 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18852 \begin_inset Text
18853
18854 \layout Standard
18855
18856 6th bit
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 rest of the pointer
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 descrption
18873 \end_inset
18874 </cell>
18875 </row>
18876 <row topline="true" bottomline="true">
18877 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18878 \begin_inset Text
18879
18880 \layout Standard
18881
18882 data
18883 \end_inset
18884 </cell>
18885 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18886 \begin_inset Text
18887
18888 \layout Standard
18889
18890 1
18891 \end_inset
18892 </cell>
18893 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18894 \begin_inset Text
18895
18896 \layout Standard
18897
18898 0
18899 \end_inset
18900 </cell>
18901 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18902 \begin_inset Text
18903
18904 \layout Standard
18905
18906
18907 \family typewriter
18908 \shape slanted
18909 \emph on
18910 uuuuuu uuuuxxxx xxxxxxxx
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 a 12-bit data pointer in data RAM memory
18919 \end_inset
18920 </cell>
18921 </row>
18922 <row bottomline="true">
18923 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18924 \begin_inset Text
18925
18926 \layout Standard
18927
18928 code
18929 \end_inset
18930 </cell>
18931 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18932 \begin_inset Text
18933
18934 \layout Standard
18935
18936 0
18937 \end_inset
18938 </cell>
18939 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18940 \begin_inset Text
18941
18942 \layout Standard
18943
18944 0
18945 \end_inset
18946 </cell>
18947 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18948 \begin_inset Text
18949
18950 \layout Standard
18951
18952
18953 \family typewriter
18954 \shape slanted
18955 \emph on
18956 uxxxxx xxxxxxxx xxxxxxxx
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 a 21-bit code pointer in FLASH memory
18965 \end_inset
18966 </cell>
18967 </row>
18968 <row bottomline="true">
18969 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18970 \begin_inset Text
18971
18972 \layout Standard
18973
18974 eeprom
18975 \end_inset
18976 </cell>
18977 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18978 \begin_inset Text
18979
18980 \layout Standard
18981
18982 0
18983 \end_inset
18984 </cell>
18985 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18986 \begin_inset Text
18987
18988 \layout Standard
18989
18990 1
18991 \end_inset
18992 </cell>
18993 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18994 \begin_inset Text
18995
18996 \layout Standard
18997
18998
18999 \family typewriter
19000 \shape slanted
19001 \emph on
19002 uuuuuu uuuuuuxx xxxxxxxx
19003 \end_inset
19004 </cell>
19005 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19006 \begin_inset Text
19007
19008 \layout Standard
19009
19010 a 10-bit eeprom pointer in EEPROM memory
19011 \end_inset
19012 </cell>
19013 </row>
19014 <row bottomline="true">
19015 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19016 \begin_inset Text
19017
19018 \layout Standard
19019
19020 (unimplemented)
19021 \end_inset
19022 </cell>
19023 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19024 \begin_inset Text
19025
19026 \layout Standard
19027
19028 1
19029 \end_inset
19030 </cell>
19031 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19032 \begin_inset Text
19033
19034 \layout Standard
19035
19036 1
19037 \end_inset
19038 </cell>
19039 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19040 \begin_inset Text
19041
19042 \layout Standard
19043
19044
19045 \family typewriter
19046 \shape slanted
19047 \emph on
19048 xxxxxx xxxxxxxx xxxxxxxx
19049 \end_inset
19050 </cell>
19051 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19052 \begin_inset Text
19053
19054 \layout Standard
19055
19056 unimplemented pointer type
19057 \end_inset
19058 </cell>
19059 </row>
19060 </lyxtabular>
19061
19062 \end_inset
19063
19064
19065 \layout Standard
19066
19067 Generic pointer are read and written with a set of library functions which
19068  read/write 1, 2, 3, 4 bytes.
19069 \layout Subsection
19070
19071 PIC16 C Libraries
19072 \layout Subsubsection
19073
19074 Standard I/O Streams
19075 \layout Standard
19076
19077 In the
19078 \emph on
19079 stdio.h
19080 \emph default
19081  the type FILE is defined as:
19082 \layout LyX-Code
19083
19084 typedef char * FILE;
19085 \layout Standard
19086
19087 This type is the stream type implemented I/O in the PIC18F devices.
19088  Also the standard input and output streams are declared in stdio.h:
19089 \layout LyX-Code
19090
19091 extern FILE * stdin;
19092 \layout LyX-Code
19093
19094 extern FILE * stdout;
19095 \layout Standard
19096
19097 The FILE type is actually a generic pointer which defines one more type
19098  of generic pointers, the
19099 \emph on
19100 stream
19101 \emph default
19102 pointer.
19103  This new type has the format:
19104 \layout Standard
19105 \align center
19106
19107 \begin_inset  Tabular
19108 <lyxtabular version="3" rows="2" columns="7">
19109 <features>
19110 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19111 <column alignment="center" valignment="top" width="0">
19112 <column alignment="center" valignment="top" leftline="true" width="0">
19113 <column alignment="center" valignment="top" leftline="true" width="0">
19114 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19115 <column alignment="center" valignment="top" width="0">
19116 <column alignment="left" valignment="top" rightline="true" width="0">
19117 <row topline="true" bottomline="true">
19118 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19119 \begin_inset Text
19120
19121 \layout Standard
19122
19123 pointer type
19124 \end_inset
19125 </cell>
19126 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19127 \begin_inset Text
19128
19129 \layout Standard
19130
19131 <7:6>
19132 \end_inset
19133 </cell>
19134 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19135 \begin_inset Text
19136
19137 \layout Standard
19138
19139 <5>
19140 \end_inset
19141 </cell>
19142 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19143 \begin_inset Text
19144
19145 \layout Standard
19146
19147 <4>
19148 \end_inset
19149 </cell>
19150 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19151 \begin_inset Text
19152
19153 \layout Standard
19154
19155 <3:0>
19156 \end_inset
19157 </cell>
19158 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19159 \begin_inset Text
19160
19161 \layout Standard
19162
19163 rest of the pointer
19164 \end_inset
19165 </cell>
19166 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19167 \begin_inset Text
19168
19169 \layout Standard
19170
19171 descrption
19172 \end_inset
19173 </cell>
19174 </row>
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
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 00
19190 \end_inset
19191 </cell>
19192 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19193 \begin_inset Text
19194
19195 \layout Standard
19196
19197 1
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 0
19206 \end_inset
19207 </cell>
19208 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19209 \begin_inset Text
19210
19211 \layout Standard
19212
19213 nnnn
19214 \end_inset
19215 </cell>
19216 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19217 \begin_inset Text
19218
19219 \layout Standard
19220
19221
19222 \family typewriter
19223 \shape slanted
19224 \emph on
19225 uuuuuuuu uuuuuuuu
19226 \end_inset
19227 </cell>
19228 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19229 \begin_inset Text
19230
19231 \layout Standard
19232
19233 upper byte high nubble is 0x2n, the rest are zeroes
19234 \end_inset
19235 </cell>
19236 </row>
19237 </lyxtabular>
19238
19239 \end_inset
19240
19241
19242 \layout Standard
19243
19244 Currently implemented there are 3 types of streams defined:
19245 \layout Standard
19246 \align center
19247
19248 \begin_inset  Tabular
19249 <lyxtabular version="3" rows="4" columns="4">
19250 <features>
19251 <column alignment="center" valignment="top" leftline="true" width="0">
19252 <column alignment="center" valignment="top" leftline="true" width="0">
19253 <column alignment="center" valignment="top" leftline="true" width="0">
19254 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19255 <row topline="true" bottomline="true">
19256 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19257 \begin_inset Text
19258
19259 \layout Standard
19260
19261 stream type
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 value
19270 \end_inset
19271 </cell>
19272 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19273 \begin_inset Text
19274
19275 \layout Standard
19276
19277 module
19278 \end_inset
19279 </cell>
19280 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19281 \begin_inset Text
19282
19283 \layout Standard
19284
19285 description
19286 \end_inset
19287 </cell>
19288 </row>
19289 <row topline="true">
19290 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19291 \begin_inset Text
19292
19293 \layout Standard
19294
19295 STREAM_USART
19296 \end_inset
19297 </cell>
19298 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19299 \begin_inset Text
19300
19301 \layout Standard
19302
19303
19304 \family typewriter
19305 0x200000UL
19306 \end_inset
19307 </cell>
19308 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19309 \begin_inset Text
19310
19311 \layout Standard
19312
19313 USART
19314 \end_inset
19315 </cell>
19316 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19317 \begin_inset Text
19318
19319 \layout Standard
19320
19321 Writes/Reads characters via the USART peripheral
19322 \end_inset
19323 </cell>
19324 </row>
19325 <row topline="true">
19326 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19327 \begin_inset Text
19328
19329 \layout Standard
19330
19331 STREAM_MSSP
19332 \end_inset
19333 </cell>
19334 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19335 \begin_inset Text
19336
19337 \layout Standard
19338
19339
19340 \family typewriter
19341 0x210000UL
19342 \end_inset
19343 </cell>
19344 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19345 \begin_inset Text
19346
19347 \layout Standard
19348
19349 MSSP
19350 \end_inset
19351 </cell>
19352 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19353 \begin_inset Text
19354
19355 \layout Standard
19356
19357 Writes/Reads characters via the MSSP peripheral
19358 \end_inset
19359 </cell>
19360 </row>
19361 <row topline="true" bottomline="true">
19362 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19363 \begin_inset Text
19364
19365 \layout Standard
19366
19367 STREAM_USER
19368 \end_inset
19369 </cell>
19370 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19371 \begin_inset Text
19372
19373 \layout Standard
19374
19375
19376 \family typewriter
19377 0x2f0000UL
19378 \end_inset
19379 </cell>
19380 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19381 \begin_inset Text
19382
19383 \layout Standard
19384
19385 (none)
19386 \end_inset
19387 </cell>
19388 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19389 \begin_inset Text
19390
19391 \layout Standard
19392
19393 Writes/Reads characters via used defined functions
19394 \end_inset
19395 </cell>
19396 </row>
19397 </lyxtabular>
19398
19399 \end_inset
19400
19401
19402 \layout Standard
19403
19404 The stream identifiers are declared as macros in the stdio.h header.
19405 \layout Standard
19406
19407 In the libc library there exist the functions that are used to write to
19408  each of the above streams.
19409  These are
19410 \layout List
19411 \labelwidthstring 00.00.0000
19412
19413 _
19414 \begin_inset ERT
19415 status Collapsed
19416
19417 \layout Standard
19418
19419 \backslash
19420 /
19421 \end_inset
19422
19423 _stream_usart_putchar writes a character at the USART stream
19424 \layout List
19425 \labelwidthstring 00.00.0000
19426
19427 _
19428 \begin_inset ERT
19429 status Collapsed
19430
19431 \layout Standard
19432
19433 \backslash
19434 /
19435 \end_inset
19436
19437 _stream_mssp_putchar writes a character at the MSSP stream
19438 \layout List
19439 \labelwidthstring 00.00.0000
19440
19441 putchar dummy function.
19442  This writes a character to a user specified manner.
19443 \layout Standard
19444
19445 In order to increase performance
19446 \emph on
19447 putchar
19448 \emph default
19449 is declared in stdio.h as having its parameter in WREG (it has the wparam
19450  keyword).
19451  In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
19452  in a user-friendly way.
19453
19454 \emph on
19455 arg
19456 \emph default
19457  is the name of the variable that holds the character to print.
19458  An example follows:
19459 \layout LyX-Code
19460
19461 #include <pic18fregs.h>
19462 \newline
19463 #include <stdio.h>
19464 \newline
19465
19466 \newline
19467 PUTCHAR( c )
19468 \layout LyX-Code
19469
19470 {
19471 \layout LyX-Code
19472
19473     PORTA = c;    /* dump character c to PORTA */
19474 \layout LyX-Code
19475
19476 }
19477 \newline
19478
19479 \newline
19480 void main(void)
19481 \layout LyX-Code
19482
19483 {
19484 \layout LyX-Code
19485
19486     stdout = STREAM_USER;    /* this is not necessery, since stdout points
19487 \layout LyX-Code
19488
19489                               * by default to STREAM_USER */
19490 \layout LyX-Code
19491
19492     printf (¨This is a printf test
19493 \backslash
19494 n¨);
19495 \layout LyX-Code
19496
19497 }
19498 \layout LyX-Code
19499
19500 \layout Subsubsection
19501
19502 Printing functions
19503 \layout Standard
19504
19505 PIC16 contains an implementation of the printf-family of functions.
19506  There exist the following functions:
19507 \layout LyX-Code
19508
19509 extern unsigned int sprintf(char *buf, char *fmt, ...);
19510 \layout LyX-Code
19511
19512 extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
19513 \layout LyX-Code
19514
19515 \layout LyX-Code
19516
19517 extern unsigned int printf(char *fmt, ...);
19518 \layout LyX-Code
19519
19520 extern unsigned int vprintf(char *fmt, va_lista ap);
19521 \layout LyX-Code
19522
19523 \layout LyX-Code
19524
19525 extern unsigned int fprintf(FILE *fp, char *fmt, ...);
19526 \layout LyX-Code
19527
19528 extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
19529 \layout Standard
19530
19531 For sprintf and vsprintf
19532 \emph on
19533 buf
19534 \emph default
19535 should normally be a data pointer where the resulting string will be placed.
19536  No range checking is done so the user should allocate the necessery buffer.
19537  For fprintf and vfprintf
19538 \emph on
19539 fp
19540 \emph default
19541  should be a stream pointer (i.e.
19542  stdout, STREAM_MSSP, etc...).
19543 \layout Subsubsection
19544
19545 Signals
19546 \layout Standard
19547
19548 The PIC18F family of microcontrollers supports a number of interrupt sources.
19549  A list of these interrupts is shown in the following table:
19550 \layout Standard
19551 \align center
19552
19553 \begin_inset  Tabular
19554 <lyxtabular version="3" rows="11" columns="4">
19555 <features>
19556 <column alignment="left" valignment="top" leftline="true" width="0">
19557 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19558 <column alignment="left" valignment="top" leftline="true" width="0">
19559 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19560 <row topline="true" bottomline="true">
19561 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19562 \begin_inset Text
19563
19564 \layout Standard
19565
19566 signal name
19567 \end_inset
19568 </cell>
19569 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19570 \begin_inset Text
19571
19572 \layout Standard
19573
19574 description
19575 \end_inset
19576 </cell>
19577 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19578 \begin_inset Text
19579
19580 \layout Standard
19581
19582 signal name
19583 \end_inset
19584 </cell>
19585 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19586 \begin_inset Text
19587
19588 \layout Standard
19589
19590 descritpion
19591 \end_inset
19592 </cell>
19593 </row>
19594 <row topline="true">
19595 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19596 \begin_inset Text
19597
19598 \layout Standard
19599
19600 SIG_RB
19601 \end_inset
19602 </cell>
19603 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19604 \begin_inset Text
19605
19606 \layout Standard
19607
19608 PORTB change interrupt
19609 \end_inset
19610 </cell>
19611 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19612 \begin_inset Text
19613
19614 \layout Standard
19615
19616 SIG_EE
19617 \end_inset
19618 </cell>
19619 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19620 \begin_inset Text
19621
19622 \layout Standard
19623
19624 EEPROM/FLASH write complete interrupt
19625 \end_inset
19626 </cell>
19627 </row>
19628 <row topline="true">
19629 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19630 \begin_inset Text
19631
19632 \layout Standard
19633
19634 SIG_INT0
19635 \end_inset
19636 </cell>
19637 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19638 \begin_inset Text
19639
19640 \layout Standard
19641
19642 INT0 external interrupt
19643 \end_inset
19644 </cell>
19645 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19646 \begin_inset Text
19647
19648 \layout Standard
19649
19650 SIG_BCOL
19651 \end_inset
19652 </cell>
19653 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19654 \begin_inset Text
19655
19656 \layout Standard
19657
19658 Bus collision interrupt
19659 \end_inset
19660 </cell>
19661 </row>
19662 <row topline="true">
19663 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19664 \begin_inset Text
19665
19666 \layout Standard
19667
19668 SIG_INT1
19669 \end_inset
19670 </cell>
19671 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19672 \begin_inset Text
19673
19674 \layout Standard
19675
19676 INT1 external interrupt
19677 \end_inset
19678 </cell>
19679 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19680 \begin_inset Text
19681
19682 \layout Standard
19683
19684 SIG_LVD
19685 \end_inset
19686 </cell>
19687 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19688 \begin_inset Text
19689
19690 \layout Standard
19691
19692 Low voltage detect interrupt
19693 \end_inset
19694 </cell>
19695 </row>
19696 <row topline="true">
19697 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19698 \begin_inset Text
19699
19700 \layout Standard
19701
19702 SIG_INT2
19703 \end_inset
19704 </cell>
19705 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19706 \begin_inset Text
19707
19708 \layout Standard
19709
19710 INT2 external interrupt
19711 \end_inset
19712 </cell>
19713 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19714 \begin_inset Text
19715
19716 \layout Standard
19717
19718 SIG_PSP
19719 \end_inset
19720 </cell>
19721 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19722 \begin_inset Text
19723
19724 \layout Standard
19725
19726 Parallel slave port interrupt
19727 \end_inset
19728 </cell>
19729 </row>
19730 <row topline="true">
19731 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19732 \begin_inset Text
19733
19734 \layout Standard
19735
19736 SIG_CCP1
19737 \end_inset
19738 </cell>
19739 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19740 \begin_inset Text
19741
19742 \layout Standard
19743
19744 CCP1 module interrupt
19745 \end_inset
19746 </cell>
19747 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19748 \begin_inset Text
19749
19750 \layout Standard
19751
19752 SIG_AD
19753 \end_inset
19754 </cell>
19755 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19756 \begin_inset Text
19757
19758 \layout Standard
19759
19760 AD convertion complete interrupt
19761 \end_inset
19762 </cell>
19763 </row>
19764 <row topline="true">
19765 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19766 \begin_inset Text
19767
19768 \layout Standard
19769
19770 SIG_CCP2
19771 \end_inset
19772 </cell>
19773 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19774 \begin_inset Text
19775
19776 \layout Standard
19777
19778 CCP2 module interrupt
19779 \end_inset
19780 </cell>
19781 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19782 \begin_inset Text
19783
19784 \layout Standard
19785
19786 SIG_RC
19787 \end_inset
19788 </cell>
19789 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19790 \begin_inset Text
19791
19792 \layout Standard
19793
19794 USART receive interrupt
19795 \end_inset
19796 </cell>
19797 </row>
19798 <row topline="true">
19799 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19800 \begin_inset Text
19801
19802 \layout Standard
19803
19804 SIG_TMR0
19805 \end_inset
19806 </cell>
19807 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19808 \begin_inset Text
19809
19810 \layout Standard
19811
19812 TMR0 overflow interrupt
19813 \end_inset
19814 </cell>
19815 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19816 \begin_inset Text
19817
19818 \layout Standard
19819
19820 SIG_TX
19821 \end_inset
19822 </cell>
19823 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19824 \begin_inset Text
19825
19826 \layout Standard
19827
19828 USART transmit interrupt
19829 \end_inset
19830 </cell>
19831 </row>
19832 <row topline="true">
19833 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19834 \begin_inset Text
19835
19836 \layout Standard
19837
19838 SIG_TMR1
19839 \end_inset
19840 </cell>
19841 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19842 \begin_inset Text
19843
19844 \layout Standard
19845
19846 TMR1 overflow interrupt
19847 \end_inset
19848 </cell>
19849 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19850 \begin_inset Text
19851
19852 \layout Standard
19853
19854 SIG_MSSP
19855 \end_inset
19856 </cell>
19857 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19858 \begin_inset Text
19859
19860 \layout Standard
19861
19862 SSP receive/transmit interrupt
19863 \end_inset
19864 </cell>
19865 </row>
19866 <row topline="true">
19867 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19868 \begin_inset Text
19869
19870 \layout Standard
19871
19872 SIG_TMR2
19873 \end_inset
19874 </cell>
19875 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19876 \begin_inset Text
19877
19878 \layout Standard
19879
19880 TMR2 matches PR2 interrupt
19881 \end_inset
19882 </cell>
19883 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19884 \begin_inset Text
19885
19886 \layout Standard
19887
19888 \end_inset
19889 </cell>
19890 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19891 \begin_inset Text
19892
19893 \layout Standard
19894
19895 \end_inset
19896 </cell>
19897 </row>
19898 <row topline="true" bottomline="true">
19899 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19900 \begin_inset Text
19901
19902 \layout Standard
19903
19904 SIG_TMR3
19905 \end_inset
19906 </cell>
19907 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19908 \begin_inset Text
19909
19910 \layout Standard
19911
19912 TMR3 overflow interrupt
19913 \end_inset
19914 </cell>
19915 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19916 \begin_inset Text
19917
19918 \layout Standard
19919
19920 \end_inset
19921 </cell>
19922 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19923 \begin_inset Text
19924
19925 \layout Standard
19926
19927 \end_inset
19928 </cell>
19929 </row>
19930 </lyxtabular>
19931
19932 \end_inset
19933
19934
19935 \layout Standard
19936
19937 The prototypes for these names are defined in the header file
19938 \emph on
19939 signal.h
19940 \emph default
19941  .
19942 \layout Standard
19943
19944 In order to simplify signal handling, a number of macros is provided:
19945 \layout List
19946 \labelwidthstring 00.00.0000
19947
19948 DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
19949  high priority interrupts.
19950
19951 \emph on
19952 name
19953 \emph default
19954  is the function name to use.
19955 \layout List
19956 \labelwidthstring 00.00.0000
19957
19958 DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
19959  low priority interrupt.
19960
19961 \emph on
19962 name
19963 \emph default
19964  is the function name to use.
19965 \layout List
19966 \labelwidthstring 00.00.0000
19967
19968 DEF_HANDLER(sig,handler) define a handler for signal
19969 \emph on
19970 sig.
19971 \layout List
19972 \labelwidthstring 00.00.0000
19973
19974 END_DEF end the declaration of the dispatch table.
19975 \layout Standard
19976
19977 Additionally there are two more macros to simplify the declaration of the
19978  signal handler:
19979 \layout List
19980 \labelwidthstring 00.00.0000
19981
19982
19983 \series medium
19984 SIGHANDLER(handler)
19985 \series default
19986 this declares the function prototype for the
19987 \emph on
19988 handler
19989 \emph default
19990  function.
19991 \layout List
19992 \labelwidthstring 00.00.0000
19993
19994 SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
19995 \layout Standard
19996
19997 An example of using the macros above is shown below:
19998 \layout LyX-Code
19999
20000 #include <pic18fregs.h>
20001 \layout LyX-Code
20002
20003 #include <signal.h>
20004 \newline
20005
20006 \newline
20007 DEF_INTHIGH(high_int)
20008 \layout LyX-Code
20009
20010 DEF_HANDLER(SIG_TMR0, _tmr0_handler)
20011 \layout LyX-Code
20012
20013 DEF_HANDLER(SIG_BCOL, _bcol_handler)
20014 \layout LyX-Code
20015
20016 END_DEF
20017 \newline
20018
20019 \newline
20020 SIGHANDLER(_tmr0_handler)
20021 \layout LyX-Code
20022
20023 {
20024 \layout LyX-Code
20025
20026   /* action to be taken when timer 0 overflows */
20027 \layout LyX-Code
20028
20029 }
20030 \newline
20031
20032 \newline
20033 SIGHANDLERNAKED(_bcol_handler)
20034 \layout LyX-Code
20035
20036 {
20037 \layout LyX-Code
20038
20039   _asm
20040 \layout LyX-Code
20041
20042     /* action to be taken when bus collision occurs */
20043 \layout LyX-Code
20044
20045     retfie
20046 \layout LyX-Code
20047
20048  _endasm;
20049 \layout LyX-Code
20050
20051 }
20052 \layout Standard
20053
20054
20055 \series bold
20056 NOTES:
20057 \series default
20058  Special care should be taken when using the above scheme:
20059 \layout Itemize
20060
20061 do not place a colon (;) at the end of the DEF_* and END_DEF macros.
20062 \layout Itemize
20063
20064 when declaring SIGHANDLERNAKED handler never forget to use
20065 \emph on
20066 retfie
20067 \emph default
20068  for proper returning.
20069 \layout Subsection
20070
20071 PIC16 Port -- Tips
20072 \layout Standard
20073
20074 Here you can find some general tips for compiling programs with SDCC/pic16.
20075 \layout Subsubsection
20076
20077 Stack size
20078 \layout Standard
20079
20080 The default stack size (that is 64 bytes) probably is enough for many programs.
20081  One must take care that when there are many levels of function nesting,
20082  or there is excessive usage of stack, its size should be extended.
20083  An example of such a case is the printf/sprintf family of functions.
20084  If you encounter problems like not being able to print integers, then you
20085  need to set the stack size around the maximum (256 for small stack model).
20086  The following diagram shows what happens when calling printf to print an
20087  integer:
20088 \layout LyX-Code
20089
20090 printf () --> ltoa () --> ultoa () --> divschar ()
20091 \layout Standard
20092
20093 It is should be understood that stack is easily consumed when calling complicate
20094 d functions.
20095  Using command line arguments like -
20096 \begin_inset ERT
20097 status Collapsed
20098
20099 \layout Standard
20100
20101 \backslash
20102 /
20103 \end_inset
20104
20105 -fommit-frame-pointer might reduce stack usage by not creating unnecessery
20106  stack frames.
20107  Other ways to reduce stack usage may exist.
20108 \layout Chapter
20109
20110 Debugging with SDCDB
20111 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
20112
20113 \end_inset
20114
20115
20116 \begin_inset LatexCommand \index{sdcdb (debugger)}
20117
20118 \end_inset
20119
20120
20121 \layout Standard
20122
20123 SDCC is distributed with a source level debugger
20124 \begin_inset LatexCommand \index{Debugger}
20125
20126 \end_inset
20127
20128 .
20129  The debugger uses a command line interface, the command repertoire of the
20130  debugger has been kept as close to gdb
20131 \begin_inset LatexCommand \index{gdb}
20132
20133 \end_inset
20134
20135  (the GNU debugger) as possible.
20136  The configuration and build process is part of the standard compiler installati
20137 on, which also builds and installs the debugger in the target directory
20138  specified during configuration.
20139  The debugger allows you debug BOTH at the C source and at the ASM source
20140  level.
20141  Sdcdb is currently not available on Win32 platforms.
20142 \layout Section
20143
20144 Compiling for Debugging
20145 \layout Standard
20146
20147 The -
20148 \begin_inset ERT
20149 status Collapsed
20150
20151 \layout Standard
20152
20153 \backslash
20154 /
20155 \end_inset
20156
20157 -debug
20158 \begin_inset LatexCommand \index{-\/-debug}
20159
20160 \end_inset
20161
20162  option must be specified for all files for which debug information is to
20163  be generated.
20164  The complier generates a .adb file for each of these files.
20165  The linker creates the .cdb
20166 \begin_inset LatexCommand \index{<file>.cdb}
20167
20168 \end_inset
20169
20170  file from the .adb
20171 \begin_inset LatexCommand \index{<file>.adb}
20172
20173 \end_inset
20174
20175  files and the address information.
20176  This .cdb is used by the debugger.
20177 \layout Section
20178
20179 How the Debugger Works
20180 \layout Standard
20181
20182 When the -
20183 \begin_inset ERT
20184 status Collapsed
20185
20186 \layout Standard
20187
20188 \backslash
20189 /
20190 \end_inset
20191
20192 -debug option is specified the compiler generates extra symbol information
20193  some of which are put into the assembler source and some are put into the
20194  .adb file.
20195   Then the linker creates the .cdb file from the individual .adb files with
20196  the address information for the symbols.
20197  The debugger reads the symbolic information generated by the compiler &
20198  the address information generated by the linker.
20199  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
20200  execution is controlled by the debugger.
20201  When a command is issued for the debugger, it translates it into appropriate
20202  commands for the simulator.
20203 \layout Section
20204
20205 Starting the Debugger
20206 \layout Standard
20207
20208 The debugger can be started using the following command line.
20209  (Assume the file you are debugging has the file name foo).
20210 \newline
20211
20212 \newline
20213
20214 \family sans
20215 \series bold
20216 sdcdb foo
20217 \newline
20218
20219 \family default
20220 \series default
20221
20222 \newline
20223 The debugger will look for the following files.
20224 \layout Itemize
20225
20226 foo.c - the source file.
20227 \layout Itemize
20228
20229 foo.cdb - the debugger symbol information file.
20230 \layout Itemize
20231
20232 foo.ihx - the Intel hex format
20233 \begin_inset LatexCommand \index{Intel hex format}
20234
20235 \end_inset
20236
20237  object file.
20238 \layout Section
20239
20240 Command Line Options
20241 \layout Itemize
20242
20243 -
20244 \begin_inset ERT
20245 status Collapsed
20246
20247 \layout Standard
20248
20249 \backslash
20250 /
20251 \end_inset
20252
20253 -directory=<source file directory> this option can used to specify the directory
20254  search list.
20255  The debugger will look into the directory list specified for source, cdb
20256  & ihx files.
20257  The items in the directory list must be separated by ':', e.g.
20258  if the source files can be in the directories /home/src1 and /home/src2,
20259  the -
20260 \begin_inset ERT
20261 status Collapsed
20262
20263 \layout Standard
20264
20265 \backslash
20266 /
20267 \end_inset
20268
20269 -directory option should be -
20270 \begin_inset ERT
20271 status Collapsed
20272
20273 \layout Standard
20274
20275 \backslash
20276 /
20277 \end_inset
20278
20279 -directory=/home/src1:/home/src2.
20280  Note there can be no spaces in the option.
20281
20282 \layout Itemize
20283
20284 -cd <directory> - change to the <directory>.
20285 \layout Itemize
20286
20287 -fullname - used by GUI front ends.
20288 \layout Itemize
20289
20290 -cpu <cpu-type> - this argument is passed to the simulator please see the
20291  simulator docs for details.
20292 \layout Itemize
20293
20294 -X <Clock frequency > this options is passed to the simulator please see
20295  the simulator docs for details.
20296 \layout Itemize
20297
20298 -s <serial port file> passed to simulator see the simulator docs for details.
20299 \layout Itemize
20300
20301 -S <serial in,out> passed to simulator see the simulator docs for details.
20302 \layout Itemize
20303
20304 -k <port number> passed to simulator see the simulator docs for details.
20305 \layout Section
20306
20307 Debugger Commands
20308 \layout Standard
20309
20310 As mentioned earlier the command interface for the debugger has been deliberatel
20311 y kept as close the GNU debugger gdb, as possible.
20312  This will help the integration with existing graphical user interfaces
20313  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
20314  If you use a graphical user interface for the debugger you can skip this
20315  section.
20316 \layout Subsubsection*
20317
20318 break [line | file:line | function | file:function]
20319 \layout Standard
20320
20321 Set breakpoint at specified line or function:
20322 \newline
20323
20324 \newline
20325
20326 \family sans
20327 \series bold
20328 sdcdb>break 100
20329 \newline
20330 sdcdb>break foo.c:100
20331 \newline
20332 sdcdb>break funcfoo
20333 \newline
20334 sdcdb>break foo.c:funcfoo
20335 \layout Subsubsection*
20336
20337 clear [line | file:line | function | file:function ]
20338 \layout Standard
20339
20340 Clear breakpoint at specified line or function:
20341 \newline
20342
20343 \newline
20344
20345 \family sans
20346 \series bold
20347 sdcdb>clear 100
20348 \newline
20349 sdcdb>clear foo.c:100
20350 \newline
20351 sdcdb>clear funcfoo
20352 \newline
20353 sdcdb>clear foo.c:funcfoo
20354 \layout Subsubsection*
20355
20356 continue
20357 \layout Standard
20358
20359 Continue program being debugged, after breakpoint.
20360 \layout Subsubsection*
20361
20362 finish
20363 \layout Standard
20364
20365 Execute till the end of the current function.
20366 \layout Subsubsection*
20367
20368 delete [n]
20369 \layout Standard
20370
20371 Delete breakpoint number 'n'.
20372  If used without any option clear ALL user defined break points.
20373 \layout Subsubsection*
20374
20375 info [break | stack | frame | registers ]
20376 \layout Itemize
20377
20378 info break - list all breakpoints
20379 \layout Itemize
20380
20381 info stack - show the function call stack.
20382 \layout Itemize
20383
20384 info frame - show information about the current execution frame.
20385 \layout Itemize
20386
20387 info registers - show content of all registers.
20388 \layout Subsubsection*
20389
20390 step
20391 \layout Standard
20392
20393 Step program until it reaches a different source line.
20394  Note: pressing <return> repeats the last command.
20395 \layout Subsubsection*
20396
20397 next
20398 \layout Standard
20399
20400 Step program, proceeding through subroutine calls.
20401 \layout Subsubsection*
20402
20403 run
20404 \layout Standard
20405
20406 Start debugged program.
20407 \layout Subsubsection*
20408
20409 ptype variable
20410 \layout Standard
20411
20412 Print type information of the variable.
20413 \layout Subsubsection*
20414
20415 print variable
20416 \layout Standard
20417
20418 print value of variable.
20419 \layout Subsubsection*
20420
20421 file filename
20422 \layout Standard
20423
20424 load the given file name.
20425  Note this is an alternate method of loading file for debugging.
20426 \layout Subsubsection*
20427
20428 frame
20429 \layout Standard
20430
20431 print information about current frame.
20432 \layout Subsubsection*
20433
20434 set srcmode
20435 \layout Standard
20436
20437 Toggle between C source & assembly source.
20438 \layout Subsubsection*
20439
20440 ! simulator command
20441 \layout Standard
20442
20443 Send the string following '!' to the simulator, the simulator response is
20444  displayed.
20445  Note the debugger does not interpret the command being sent to the simulator,
20446  so if a command like 'go' is sent the debugger can loose its execution
20447  context and may display incorrect values.
20448 \layout Subsubsection*
20449
20450 quit
20451 \layout Standard
20452
20453 "Watch me now.
20454  Iam going Down.
20455  My name is Bobby Brown"
20456 \layout Section
20457
20458 Interfacing with DDD
20459 \layout Comment
20460
20461 The screenshot was converted from png to eps with:
20462 \begin_inset Quotes sld
20463 \end_inset
20464
20465 bmeps -c -e8f -p3 ddd_example.png >ddd_example.eps
20466 \begin_inset Quotes srd
20467 \end_inset
20468
20469  which produces a pretty compact eps file which is free from compression
20470  artifacts.
20471 \layout Comment
20472
20473 The screenshot was included in sdccman.lyx cvs version 1.120 but later removed
20474  as this broke the build system on Sourceforge (pdf-file was broken).
20475 \layout Standard
20476
20477 The .eps File
20478 \size footnotesize
20479
20480 \begin_inset LatexCommand \url{http://cvs.sourceforge.net/viewcvs.py/*checkout*/sdcc/sdcc/doc/figures/ddd_example.eps}
20481
20482 \end_inset
20483
20484
20485 \size default
20486  shows a screenshot of a debugging session with DDD
20487 \begin_inset LatexCommand \index{DDD (debugger)}
20488
20489 \end_inset
20490
20491  (Unix only) on a simulated 8032.
20492  The debugging session might not run as smoothly as the screenshot suggests.
20493  The debugger allows setting of breakpoints, displaying and changing variables,
20494  single stepping through C and assembler code.
20495
20496 \newline
20497 The source was compiled with
20498 \family sans
20499 \series bold
20500
20501 \newline
20502
20503 \newline
20504 sdcc -
20505 \family default
20506 \series default
20507
20508 \begin_inset ERT
20509 status Collapsed
20510
20511 \layout Standard
20512
20513 \backslash
20514 /
20515 \end_inset
20516
20517
20518 \family sans
20519 \series bold
20520 -debug ddd_example.c
20521 \family default
20522 \series default
20523
20524 \family sans
20525 \series bold
20526
20527 \newline
20528
20529 \family default
20530 \series default
20531
20532 \newline
20533 and DDD was invoked with
20534 \family sans
20535 \series bold
20536
20537 \newline
20538
20539 \newline
20540 ddd -debugger 'sdcdb -cpu 8032 ddd_example'
20541 \layout Section
20542
20543 Interfacing with XEmacs
20544 \begin_inset LatexCommand \index{XEmacs}
20545
20546 \end_inset
20547
20548
20549 \begin_inset LatexCommand \index{Emacs}
20550
20551 \end_inset
20552
20553
20554 \layout Standard
20555
20556 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
20557  sdcdb.el and sdcdbsrc.el.
20558  These two files can be found in the $(prefix)/bin directory after the installat
20559 ion is complete.
20560  These files need to be loaded into XEmacs for the interface to work.
20561  This can be done at XEmacs startup time by inserting the following into
20562  your '.xemacs' file (which can be found in your HOME directory):
20563 \newline
20564
20565 \newline
20566
20567 \family typewriter
20568 (load-file sdcdbsrc.el)
20569 \family default
20570
20571 \newline
20572
20573 \newline
20574 .xemacs is a lisp file so the () around the command is REQUIRED.
20575  The files can also be loaded dynamically while XEmacs is running, set the
20576  environment variable 'EMACSLOADPATH' to the installation bin directory
20577  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
20578  To start the interface enter the following command:
20579 \newline
20580
20581 \newline
20582
20583 \family sans
20584 \series bold
20585 ESC-x sdcdbsrc
20586 \family default
20587 \series default
20588
20589 \newline
20590
20591 \newline
20592 You will prompted to enter the file name to be debugged.
20593
20594 \newline
20595
20596 \newline
20597 The command line options that are passed to the simulator directly are bound
20598  to default values in the file sdcdbsrc.el.
20599  The variables are listed below, these values maybe changed as required.
20600 \layout Itemize
20601
20602 sdcdbsrc-cpu-type '51
20603 \layout Itemize
20604
20605 sdcdbsrc-frequency '11059200
20606 \layout Itemize
20607
20608 sdcdbsrc-serial nil
20609 \layout Standard
20610
20611 The following is a list of key mapping for the debugger interface.
20612 \layout Standard
20613
20614 \SpecialChar ~
20615
20616 \family typewriter
20617
20618 \newline
20619 ;;\SpecialChar ~
20620 Current Listing ::
20621 \newline
20622 ;;key\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 binding\SpecialChar ~
20637 \SpecialChar ~
20638 \SpecialChar ~
20639 \SpecialChar ~
20640 \SpecialChar ~
20641 \SpecialChar ~
20642 \SpecialChar ~
20643 \SpecialChar ~
20644 \SpecialChar ~
20645 \SpecialChar ~
20646 \SpecialChar ~
20647 \SpecialChar ~
20648 \SpecialChar ~
20649 \SpecialChar ~
20650 \SpecialChar ~
20651 \SpecialChar ~
20652 \SpecialChar ~
20653 \SpecialChar ~
20654 \SpecialChar ~
20655 \SpecialChar ~
20656 \SpecialChar ~
20657 \SpecialChar ~
20658 Comment
20659 \newline
20660 ;;---\SpecialChar ~
20661 \SpecialChar ~
20662 \SpecialChar ~
20663 \SpecialChar ~
20664 \SpecialChar ~
20665 \SpecialChar ~
20666 \SpecialChar ~
20667 \SpecialChar ~
20668 \SpecialChar ~
20669 \SpecialChar ~
20670 \SpecialChar ~
20671 \SpecialChar ~
20672 \SpecialChar ~
20673 \SpecialChar ~
20674 -------\SpecialChar ~
20675 \SpecialChar ~
20676 \SpecialChar ~
20677 \SpecialChar ~
20678 \SpecialChar ~
20679 \SpecialChar ~
20680 \SpecialChar ~
20681 \SpecialChar ~
20682 \SpecialChar ~
20683 \SpecialChar ~
20684 \SpecialChar ~
20685 \SpecialChar ~
20686 \SpecialChar ~
20687 \SpecialChar ~
20688 \SpecialChar ~
20689 \SpecialChar ~
20690 \SpecialChar ~
20691 \SpecialChar ~
20692 \SpecialChar ~
20693 \SpecialChar ~
20694 \SpecialChar ~
20695 \SpecialChar ~
20696 -------
20697 \newline
20698 ;;
20699 \newline
20700 ;;\SpecialChar ~
20701 n\SpecialChar ~
20702 \SpecialChar ~
20703 \SpecialChar ~
20704 \SpecialChar ~
20705 \SpecialChar ~
20706 \SpecialChar ~
20707 \SpecialChar ~
20708 \SpecialChar ~
20709 \SpecialChar ~
20710 \SpecialChar ~
20711 \SpecialChar ~
20712 \SpecialChar ~
20713 \SpecialChar ~
20714 \SpecialChar ~
20715 \SpecialChar ~
20716 sdcdb-next-from-src\SpecialChar ~
20717 \SpecialChar ~
20718 \SpecialChar ~
20719 \SpecialChar ~
20720 \SpecialChar ~
20721 \SpecialChar ~
20722 \SpecialChar ~
20723 \SpecialChar ~
20724 \SpecialChar ~
20725 \SpecialChar ~
20726 SDCDB next command
20727 \newline
20728 ;;\SpecialChar ~
20729 b\SpecialChar ~
20730 \SpecialChar ~
20731 \SpecialChar ~
20732 \SpecialChar ~
20733 \SpecialChar ~
20734 \SpecialChar ~
20735 \SpecialChar ~
20736 \SpecialChar ~
20737 \SpecialChar ~
20738 \SpecialChar ~
20739 \SpecialChar ~
20740 \SpecialChar ~
20741 \SpecialChar ~
20742 \SpecialChar ~
20743 \SpecialChar ~
20744 sdcdb-back-from-src\SpecialChar ~
20745 \SpecialChar ~
20746 \SpecialChar ~
20747 \SpecialChar ~
20748 \SpecialChar ~
20749 \SpecialChar ~
20750 \SpecialChar ~
20751 \SpecialChar ~
20752 \SpecialChar ~
20753 \SpecialChar ~
20754 SDCDB back command
20755 \newline
20756 ;;\SpecialChar ~
20757 c\SpecialChar ~
20758 \SpecialChar ~
20759 \SpecialChar ~
20760 \SpecialChar ~
20761 \SpecialChar ~
20762 \SpecialChar ~
20763 \SpecialChar ~
20764 \SpecialChar ~
20765 \SpecialChar ~
20766 \SpecialChar ~
20767 \SpecialChar ~
20768 \SpecialChar ~
20769 \SpecialChar ~
20770 \SpecialChar ~
20771 \SpecialChar ~
20772 sdcdb-cont-from-src\SpecialChar ~
20773 \SpecialChar ~
20774 \SpecialChar ~
20775 \SpecialChar ~
20776 \SpecialChar ~
20777 \SpecialChar ~
20778 \SpecialChar ~
20779 \SpecialChar ~
20780 \SpecialChar ~
20781 \SpecialChar ~
20782 SDCDB continue command
20783 \newline
20784 ;;\SpecialChar ~
20785 s\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 sdcdb-step-from-src\SpecialChar ~
20801 \SpecialChar ~
20802 \SpecialChar ~
20803 \SpecialChar ~
20804 \SpecialChar ~
20805 \SpecialChar ~
20806 \SpecialChar ~
20807 \SpecialChar ~
20808 \SpecialChar ~
20809 \SpecialChar ~
20810 SDCDB step command
20811 \newline
20812 ;;\SpecialChar ~
20813 ?\SpecialChar ~
20814 \SpecialChar ~
20815 \SpecialChar ~
20816 \SpecialChar ~
20817 \SpecialChar ~
20818 \SpecialChar ~
20819 \SpecialChar ~
20820 \SpecialChar ~
20821 \SpecialChar ~
20822 \SpecialChar ~
20823 \SpecialChar ~
20824 \SpecialChar ~
20825 \SpecialChar ~
20826 \SpecialChar ~
20827 \SpecialChar ~
20828 sdcdb-whatis-c-sexp\SpecialChar ~
20829 \SpecialChar ~
20830 \SpecialChar ~
20831 \SpecialChar ~
20832 \SpecialChar ~
20833 \SpecialChar ~
20834 \SpecialChar ~
20835 \SpecialChar ~
20836 \SpecialChar ~
20837 \SpecialChar ~
20838 SDCDB ptypecommand for data at
20839 \newline
20840 ;;\SpecialChar ~
20841 \SpecialChar ~
20842 \SpecialChar ~
20843 \SpecialChar ~
20844 \SpecialChar ~
20845 \SpecialChar ~
20846 \SpecialChar ~
20847 \SpecialChar ~
20848 \SpecialChar ~
20849 \SpecialChar ~
20850 \SpecialChar ~
20851 \SpecialChar ~
20852 \SpecialChar ~
20853 \SpecialChar ~
20854 \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 buffer point
20888 \newline
20889 ;;\SpecialChar ~
20890 x\SpecialChar ~
20891 \SpecialChar ~
20892 \SpecialChar ~
20893 \SpecialChar ~
20894 \SpecialChar ~
20895 \SpecialChar ~
20896 \SpecialChar ~
20897 \SpecialChar ~
20898 \SpecialChar ~
20899 \SpecialChar ~
20900 \SpecialChar ~
20901 \SpecialChar ~
20902 \SpecialChar ~
20903 \SpecialChar ~
20904 \SpecialChar ~
20905 sdcdbsrc-delete\SpecialChar ~
20906 \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 SDCDB Delete all breakpoints if no arg
20920 \newline
20921 ;;\SpecialChar ~
20922 \SpecialChar ~
20923 \SpecialChar ~
20924 \SpecialChar ~
20925 \SpecialChar ~
20926 \SpecialChar ~
20927 \SpecialChar ~
20928 \SpecialChar ~
20929 \SpecialChar ~
20930 \SpecialChar ~
20931 \SpecialChar ~
20932 \SpecialChar ~
20933 \SpecialChar ~
20934 \SpecialChar ~
20935 \SpecialChar ~
20936 \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 given or delete arg (C-u arg x)
20969 \newline
20970 ;;\SpecialChar ~
20971 m\SpecialChar ~
20972 \SpecialChar ~
20973 \SpecialChar ~
20974 \SpecialChar ~
20975 \SpecialChar ~
20976 \SpecialChar ~
20977 \SpecialChar ~
20978 \SpecialChar ~
20979 \SpecialChar ~
20980 \SpecialChar ~
20981 \SpecialChar ~
20982 \SpecialChar ~
20983 \SpecialChar ~
20984 \SpecialChar ~
20985 \SpecialChar ~
20986 sdcdbsrc-frame\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 SDCDB Display current frame if no arg,
21002 \newline
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 \SpecialChar ~
21020 \SpecialChar ~
21021 \SpecialChar ~
21022 \SpecialChar ~
21023 \SpecialChar ~
21024 \SpecialChar ~
21025 \SpecialChar ~
21026 \SpecialChar ~
21027 \SpecialChar ~
21028 \SpecialChar ~
21029 \SpecialChar ~
21030 \SpecialChar ~
21031 \SpecialChar ~
21032 \SpecialChar ~
21033 \SpecialChar ~
21034 \SpecialChar ~
21035 \SpecialChar ~
21036 \SpecialChar ~
21037 \SpecialChar ~
21038 \SpecialChar ~
21039 \SpecialChar ~
21040 \SpecialChar ~
21041 \SpecialChar ~
21042 \SpecialChar ~
21043 \SpecialChar ~
21044 \SpecialChar ~
21045 \SpecialChar ~
21046 \SpecialChar ~
21047 \SpecialChar ~
21048 \SpecialChar ~
21049 \SpecialChar ~
21050 given or display frame arg
21051 \newline
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 \SpecialChar ~
21066 \SpecialChar ~
21067 \SpecialChar ~
21068 \SpecialChar ~
21069 \SpecialChar ~
21070 \SpecialChar ~
21071 \SpecialChar ~
21072 \SpecialChar ~
21073 \SpecialChar ~
21074 \SpecialChar ~
21075 \SpecialChar ~
21076 \SpecialChar ~
21077 \SpecialChar ~
21078 \SpecialChar ~
21079 \SpecialChar ~
21080 \SpecialChar ~
21081 \SpecialChar ~
21082 \SpecialChar ~
21083 \SpecialChar ~
21084 \SpecialChar ~
21085 \SpecialChar ~
21086 \SpecialChar ~
21087 \SpecialChar ~
21088 \SpecialChar ~
21089 \SpecialChar ~
21090 \SpecialChar ~
21091 \SpecialChar ~
21092 \SpecialChar ~
21093 \SpecialChar ~
21094 \SpecialChar ~
21095 \SpecialChar ~
21096 \SpecialChar ~
21097 \SpecialChar ~
21098 \SpecialChar ~
21099 buffer point
21100 \newline
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 sdcdbsrc-goto-sdcdb\SpecialChar ~
21118 \SpecialChar ~
21119 \SpecialChar ~
21120 \SpecialChar ~
21121 \SpecialChar ~
21122 \SpecialChar ~
21123 \SpecialChar ~
21124 \SpecialChar ~
21125 \SpecialChar ~
21126 \SpecialChar ~
21127 Goto the SDCDB output buffer
21128 \newline
21129 ;;\SpecialChar ~
21130 p\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 \SpecialChar ~
21144 \SpecialChar ~
21145 sdcdb-print-c-sexp\SpecialChar ~
21146 \SpecialChar ~
21147 \SpecialChar ~
21148 \SpecialChar ~
21149 \SpecialChar ~
21150 \SpecialChar ~
21151 \SpecialChar ~
21152 \SpecialChar ~
21153 \SpecialChar ~
21154 \SpecialChar ~
21155 \SpecialChar ~
21156 SDCDB print command for data at
21157 \newline
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 \SpecialChar ~
21172 \SpecialChar ~
21173 \SpecialChar ~
21174 \SpecialChar ~
21175 \SpecialChar ~
21176 \SpecialChar ~
21177 \SpecialChar ~
21178 \SpecialChar ~
21179 \SpecialChar ~
21180 \SpecialChar ~
21181 \SpecialChar ~
21182 \SpecialChar ~
21183 \SpecialChar ~
21184 \SpecialChar ~
21185 \SpecialChar ~
21186 \SpecialChar ~
21187 \SpecialChar ~
21188 \SpecialChar ~
21189 \SpecialChar ~
21190 \SpecialChar ~
21191 \SpecialChar ~
21192 \SpecialChar ~
21193 \SpecialChar ~
21194 \SpecialChar ~
21195 \SpecialChar ~
21196 \SpecialChar ~
21197 \SpecialChar ~
21198 \SpecialChar ~
21199 \SpecialChar ~
21200 \SpecialChar ~
21201 \SpecialChar ~
21202 \SpecialChar ~
21203 \SpecialChar ~
21204 \SpecialChar ~
21205 buffer point
21206 \newline
21207 ;;\SpecialChar ~
21208 g\SpecialChar ~
21209 \SpecialChar ~
21210 \SpecialChar ~
21211 \SpecialChar ~
21212 \SpecialChar ~
21213 \SpecialChar ~
21214 \SpecialChar ~
21215 \SpecialChar ~
21216 \SpecialChar ~
21217 \SpecialChar ~
21218 \SpecialChar ~
21219 \SpecialChar ~
21220 \SpecialChar ~
21221 \SpecialChar ~
21222 \SpecialChar ~
21223 sdcdbsrc-goto-sdcdb\SpecialChar ~
21224 \SpecialChar ~
21225 \SpecialChar ~
21226 \SpecialChar ~
21227 \SpecialChar ~
21228 \SpecialChar ~
21229 \SpecialChar ~
21230 \SpecialChar ~
21231 \SpecialChar ~
21232 \SpecialChar ~
21233 Goto the SDCDB output buffer
21234 \newline
21235 ;;\SpecialChar ~
21236 t\SpecialChar ~
21237 \SpecialChar ~
21238 \SpecialChar ~
21239 \SpecialChar ~
21240 \SpecialChar ~
21241 \SpecialChar ~
21242 \SpecialChar ~
21243 \SpecialChar ~
21244 \SpecialChar ~
21245 \SpecialChar ~
21246 \SpecialChar ~
21247 \SpecialChar ~
21248 \SpecialChar ~
21249 \SpecialChar ~
21250 \SpecialChar ~
21251 sdcdbsrc-mode\SpecialChar ~
21252 \SpecialChar ~
21253 \SpecialChar ~
21254 \SpecialChar ~
21255 \SpecialChar ~
21256 \SpecialChar ~
21257 \SpecialChar ~
21258 \SpecialChar ~
21259 \SpecialChar ~
21260 \SpecialChar ~
21261 \SpecialChar ~
21262 \SpecialChar ~
21263 \SpecialChar ~
21264 \SpecialChar ~
21265 \SpecialChar ~
21266 \SpecialChar ~
21267 Toggles Sdcdbsrc mode (turns it off)
21268 \newline
21269 ;;
21270 \newline
21271 ;;\SpecialChar ~
21272 C-c\SpecialChar ~
21273 C-f\SpecialChar ~
21274 \SpecialChar ~
21275 \SpecialChar ~
21276 \SpecialChar ~
21277 \SpecialChar ~
21278 \SpecialChar ~
21279 \SpecialChar ~
21280 \SpecialChar ~
21281 \SpecialChar ~
21282 sdcdb-finish-from-src\SpecialChar ~
21283 \SpecialChar ~
21284 \SpecialChar ~
21285 \SpecialChar ~
21286 \SpecialChar ~
21287 \SpecialChar ~
21288 \SpecialChar ~
21289 \SpecialChar ~
21290 SDCDB finish command
21291 \newline
21292 ;;
21293 \newline
21294 ;;\SpecialChar ~
21295 C-x\SpecialChar ~
21296 SPC\SpecialChar ~
21297 \SpecialChar ~
21298 \SpecialChar ~
21299 \SpecialChar ~
21300 \SpecialChar ~
21301 \SpecialChar ~
21302 \SpecialChar ~
21303 \SpecialChar ~
21304 \SpecialChar ~
21305 sdcdb-break\SpecialChar ~
21306 \SpecialChar ~
21307 \SpecialChar ~
21308 \SpecialChar ~
21309 \SpecialChar ~
21310 \SpecialChar ~
21311 \SpecialChar ~
21312 \SpecialChar ~
21313 \SpecialChar ~
21314 \SpecialChar ~
21315 \SpecialChar ~
21316 \SpecialChar ~
21317 \SpecialChar ~
21318 \SpecialChar ~
21319 \SpecialChar ~
21320 \SpecialChar ~
21321 \SpecialChar ~
21322 \SpecialChar ~
21323 Set break for line with point
21324 \newline
21325 ;;\SpecialChar ~
21326 ESC\SpecialChar ~
21327 t\SpecialChar ~
21328 \SpecialChar ~
21329 \SpecialChar ~
21330 \SpecialChar ~
21331 \SpecialChar ~
21332 \SpecialChar ~
21333 \SpecialChar ~
21334 \SpecialChar ~
21335 \SpecialChar ~
21336 \SpecialChar ~
21337 \SpecialChar ~
21338 sdcdbsrc-mode\SpecialChar ~
21339 \SpecialChar ~
21340 \SpecialChar ~
21341 \SpecialChar ~
21342 \SpecialChar ~
21343 \SpecialChar ~
21344 \SpecialChar ~
21345 \SpecialChar ~
21346 \SpecialChar ~
21347 \SpecialChar ~
21348 \SpecialChar ~
21349 \SpecialChar ~
21350 \SpecialChar ~
21351 \SpecialChar ~
21352 \SpecialChar ~
21353 \SpecialChar ~
21354 Toggle Sdcdbsrc mode
21355 \newline
21356 ;;\SpecialChar ~
21357 ESC\SpecialChar ~
21358 m\SpecialChar ~
21359 \SpecialChar ~
21360 \SpecialChar ~
21361 \SpecialChar ~
21362 \SpecialChar ~
21363 \SpecialChar ~
21364 \SpecialChar ~
21365 \SpecialChar ~
21366 \SpecialChar ~
21367 \SpecialChar ~
21368 \SpecialChar ~
21369 sdcdbsrc-srcmode\SpecialChar ~
21370 \SpecialChar ~
21371 \SpecialChar ~
21372 \SpecialChar ~
21373 \SpecialChar ~
21374 \SpecialChar ~
21375 \SpecialChar ~
21376 \SpecialChar ~
21377 \SpecialChar ~
21378 \SpecialChar ~
21379 \SpecialChar ~
21380 \SpecialChar ~
21381 \SpecialChar ~
21382 Toggle list mode
21383 \newline
21384 ;;
21385 \newline
21386
21387 \layout Chapter
21388 \pagebreak_top
21389 TIPS
21390 \layout Standard
21391
21392 Here are a few guidelines that will help the compiler generate more efficient
21393  code, some of the tips are specific to this compiler others are generally
21394  good programming practice.
21395 \layout Itemize
21396
21397 Use the smallest data type to represent your data-value.
21398  If it is known in advance that the value is going to be less than 256 then
21399  use an 'unsigned char' instead of a 'short' or 'int'.
21400  Please note, that ANSI C requires both signed and unsigned chars to be
21401  promoted to 'signed int' before doing any operation.
21402  This promotion
21403 \begin_inset LatexCommand \index{type promotion}
21404
21405 \end_inset
21406
21407  can be omitted, if the result is the same.
21408  The effect of the promotion rules together with the sign-extension is often
21409  surprising:
21410 \begin_deeper
21411 \layout Verse
21412
21413
21414 \family typewriter
21415 unsigned char uc = 0xfe;
21416 \newline
21417 if (uc * uc < 0) /* this is true! */
21418 \newline
21419 {
21420 \newline
21421 \SpecialChar ~
21422 \SpecialChar ~
21423 \SpecialChar ~
21424 \SpecialChar ~
21425 ....
21426 \newline
21427 }
21428 \layout Standard
21429
21430
21431 \family typewriter
21432 uc * uc
21433 \family default
21434  is evaluated as
21435 \family typewriter
21436 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
21437 \family default
21438 .
21439
21440 \newline
21441 Another one:
21442 \layout Verse
21443
21444
21445 \family typewriter
21446 (unsigned char) -12 / (signed char) -3 = ...
21447 \layout Standard
21448
21449 No, the result is not 4:
21450 \layout Verse
21451
21452
21453 \family typewriter
21454 (int) (unsigned char) -12 / (int) (signed char) -3 =
21455 \newline
21456 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
21457 \newline
21458 (int) 0x00f4 / (int) 0xfffd =
21459 \newline
21460 (int) 0x00f4 / (int) 0xfffd =
21461 \newline
21462 (int) 244 / (int) -3 =
21463 \newline
21464 (int) -81 = (int) 0xffaf;
21465 \layout Standard
21466
21467 Don't complain, that gcc gives you a different result.
21468  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
21469  Therefore the results are different.
21470 \newline
21471 From
21472 \begin_inset Quotes sld
21473 \end_inset
21474
21475 comp.lang.c FAQ
21476 \begin_inset Quotes srd
21477 \end_inset
21478
21479 :
21480 \layout Quote
21481
21482 If well-defined overflow characteristics are important and negative values
21483  are not, or if you want to steer clear of sign-extension problems when
21484  manipulating bits or bytes, use one of the corresponding unsigned types.
21485  (Beware when mixing signed and unsigned values in expressions, though.)
21486 \newline
21487 Although character types (especially unsigned char) can be used as "tiny"
21488  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
21489 ble sign extension and increased code size.
21490 \end_deeper
21491 \layout Itemize
21492
21493 Use unsigned when it is known in advance that the value is not going to
21494  be negative.
21495  This helps especially if you are doing division or multiplication, bit-shifting
21496  or are using an array index.
21497 \layout Itemize
21498
21499 NEVER jump into a LOOP.
21500 \layout Itemize
21501
21502 Declare the variables to be local
21503 \begin_inset LatexCommand \index{local variables}
21504
21505 \end_inset
21506
21507  whenever possible, especially loop control variables (induction).
21508 \layout Itemize
21509
21510 Since the compiler does not always do implicit integral promotion, the programme
21511 r should do an explicit cast when integral promotion is required.
21512 \layout Itemize
21513
21514 Reducing the size of division, multiplication & modulus operations can reduce
21515  code size substantially.
21516  Take the following code for example.
21517 \begin_deeper
21518 \layout Verse
21519
21520
21521 \family typewriter
21522 foobar(unsigned int p1, unsigned char ch)
21523 \newline
21524 {
21525 \newline
21526 \SpecialChar ~
21527 \SpecialChar ~
21528 \SpecialChar ~
21529 \SpecialChar ~
21530 unsigned char ch1 = p1 % ch ;
21531 \newline
21532 \SpecialChar ~
21533 \SpecialChar ~
21534 \SpecialChar ~
21535 \SpecialChar ~
21536 ....
21537 \newline
21538 }
21539 \layout Standard
21540
21541 For the modulus operation the variable ch will be promoted to unsigned int
21542  first then the modulus operation will be performed (this will lead to a
21543  call to support routine _moduint()), and the result will be casted to a
21544  char.
21545  If the code is changed to
21546 \layout Verse
21547
21548
21549 \family typewriter
21550 foobar(unsigned int p1, unsigned char ch)
21551 \newline
21552 {
21553 \newline
21554 \SpecialChar ~
21555 \SpecialChar ~
21556 \SpecialChar ~
21557 \SpecialChar ~
21558 unsigned char ch1 = (unsigned char)p1 % ch ;
21559 \newline
21560 \SpecialChar ~
21561 \SpecialChar ~
21562 \SpecialChar ~
21563 \SpecialChar ~
21564 ....
21565 \newline
21566 }
21567 \layout Standard
21568
21569 It would substantially reduce the code generated (future versions of the
21570  compiler will be smart enough to detect such optimization opportunities).
21571 \end_deeper
21572 \layout Itemize
21573
21574 Have a look at the assembly listing to get a
21575 \begin_inset Quotes sld
21576 \end_inset
21577
21578 feeling
21579 \begin_inset Quotes srd
21580 \end_inset
21581
21582  for the code generation.
21583 \layout Section
21584
21585 Tools
21586 \begin_inset LatexCommand \index{Tools}
21587
21588 \end_inset
21589
21590  included in the distribution
21591 \layout Standard
21592 \align center
21593
21594 \begin_inset  Tabular
21595 <lyxtabular version="3" rows="12" columns="3">
21596 <features>
21597 <column alignment="center" valignment="top" leftline="true" width="0pt">
21598 <column alignment="center" valignment="top" leftline="true" width="0pt">
21599 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
21600 <row topline="true" bottomline="true">
21601 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21602 \begin_inset Text
21603
21604 \layout Standard
21605
21606 Name
21607 \end_inset
21608 </cell>
21609 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21610 \begin_inset Text
21611
21612 \layout Standard
21613
21614 Purpose
21615 \end_inset
21616 </cell>
21617 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21618 \begin_inset Text
21619
21620 \layout Standard
21621
21622 Directory
21623 \end_inset
21624 </cell>
21625 </row>
21626 <row topline="true">
21627 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21628 \begin_inset Text
21629
21630 \layout Standard
21631
21632 uCsim
21633 \end_inset
21634 </cell>
21635 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21636 \begin_inset Text
21637
21638 \layout Standard
21639
21640 Simulator for various architectures
21641 \end_inset
21642 </cell>
21643 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21644 \begin_inset Text
21645
21646 \layout Standard
21647
21648 sdcc/sim/ucsim
21649 \end_inset
21650 </cell>
21651 </row>
21652 <row topline="true">
21653 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21654 \begin_inset Text
21655
21656 \layout Standard
21657
21658 keil2sdcc.pl
21659 \end_inset
21660 </cell>
21661 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21662 \begin_inset Text
21663
21664 \layout Standard
21665
21666 header file conversion
21667 \end_inset
21668 </cell>
21669 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21670 \begin_inset Text
21671
21672 \layout Standard
21673
21674 sdcc/support/scripts
21675 \end_inset
21676 </cell>
21677 </row>
21678 <row topline="true">
21679 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21680 \begin_inset Text
21681
21682 \layout Standard
21683
21684 mh2h.c
21685 \end_inset
21686 </cell>
21687 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21688 \begin_inset Text
21689
21690 \layout Standard
21691
21692 header file conversion
21693 \end_inset
21694 </cell>
21695 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21696 \begin_inset Text
21697
21698 \layout Standard
21699
21700 sdcc/support/scripts
21701 \end_inset
21702 </cell>
21703 </row>
21704 <row topline="true">
21705 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21706 \begin_inset Text
21707
21708 \layout Standard
21709
21710 as-gbz80
21711 \end_inset
21712 </cell>
21713 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21714 \begin_inset Text
21715
21716 \layout Standard
21717
21718 Assembler
21719 \end_inset
21720 </cell>
21721 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21722 \begin_inset Text
21723
21724 \layout Standard
21725
21726
21727 \family roman
21728 \series medium
21729 \shape up
21730 \size normal
21731 \emph off
21732 \bar no
21733 \noun off
21734 \color none
21735 sdcc/bin
21736 \end_inset
21737 </cell>
21738 </row>
21739 <row topline="true">
21740 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21741 \begin_inset Text
21742
21743 \layout Standard
21744
21745 as-z80
21746 \end_inset
21747 </cell>
21748 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21749 \begin_inset Text
21750
21751 \layout Standard
21752
21753 Assembler
21754 \end_inset
21755 </cell>
21756 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21757 \begin_inset Text
21758
21759 \layout Standard
21760
21761
21762 \family roman
21763 \series medium
21764 \shape up
21765 \size normal
21766 \emph off
21767 \bar no
21768 \noun off
21769 \color none
21770 sdcc/bin
21771 \end_inset
21772 </cell>
21773 </row>
21774 <row topline="true">
21775 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21776 \begin_inset Text
21777
21778 \layout Standard
21779
21780 asx8051
21781 \end_inset
21782 </cell>
21783 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21784 \begin_inset Text
21785
21786 \layout Standard
21787
21788 Assembler
21789 \end_inset
21790 </cell>
21791 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21792 \begin_inset Text
21793
21794 \layout Standard
21795
21796
21797 \family roman
21798 \series medium
21799 \shape up
21800 \size normal
21801 \emph off
21802 \bar no
21803 \noun off
21804 \color none
21805 sdcc/bin
21806 \end_inset
21807 </cell>
21808 </row>
21809 <row topline="true">
21810 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21811 \begin_inset Text
21812
21813 \layout Standard
21814
21815 sdcdb
21816 \end_inset
21817 </cell>
21818 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21819 \begin_inset Text
21820
21821 \layout Standard
21822
21823 Simulator
21824 \end_inset
21825 </cell>
21826 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21827 \begin_inset Text
21828
21829 \layout Standard
21830
21831
21832 \family roman
21833 \series medium
21834 \shape up
21835 \size normal
21836 \emph off
21837 \bar no
21838 \noun off
21839 \color none
21840 sdcc/bin
21841 \end_inset
21842 </cell>
21843 </row>
21844 <row topline="true">
21845 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21846 \begin_inset Text
21847
21848 \layout Standard
21849
21850 aslink
21851 \end_inset
21852 </cell>
21853 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21854 \begin_inset Text
21855
21856 \layout Standard
21857
21858 Linker
21859 \end_inset
21860 </cell>
21861 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21862 \begin_inset Text
21863
21864 \layout Standard
21865
21866
21867 \family roman
21868 \series medium
21869 \shape up
21870 \size normal
21871 \emph off
21872 \bar no
21873 \noun off
21874 \color none
21875 sdcc/bin
21876 \end_inset
21877 </cell>
21878 </row>
21879 <row topline="true">
21880 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21881 \begin_inset Text
21882
21883 \layout Standard
21884
21885 link-z80
21886 \end_inset
21887 </cell>
21888 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21889 \begin_inset Text
21890
21891 \layout Standard
21892
21893 Linker
21894 \end_inset
21895 </cell>
21896 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21897 \begin_inset Text
21898
21899 \layout Standard
21900
21901
21902 \family roman
21903 \series medium
21904 \shape up
21905 \size normal
21906 \emph off
21907 \bar no
21908 \noun off
21909 \color none
21910 sdcc/bin
21911 \end_inset
21912 </cell>
21913 </row>
21914 <row topline="true">
21915 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21916 \begin_inset Text
21917
21918 \layout Standard
21919
21920 link-gbz80
21921 \end_inset
21922 </cell>
21923 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21924 \begin_inset Text
21925
21926 \layout Standard
21927
21928 Linker
21929 \end_inset
21930 </cell>
21931 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21932 \begin_inset Text
21933
21934 \layout Standard
21935
21936
21937 \family roman
21938 \series medium
21939 \shape up
21940 \size normal
21941 \emph off
21942 \bar no
21943 \noun off
21944 \color none
21945 sdcc/bin
21946 \end_inset
21947 </cell>
21948 </row>
21949 <row topline="true" bottomline="true">
21950 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21951 \begin_inset Text
21952
21953 \layout Standard
21954
21955 packihx
21956 \end_inset
21957 </cell>
21958 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21959 \begin_inset Text
21960
21961 \layout Standard
21962
21963 ihx packer
21964 \end_inset
21965 </cell>
21966 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21967 \begin_inset Text
21968
21969 \layout Standard
21970
21971
21972 \family roman
21973 \series medium
21974 \shape up
21975 \size normal
21976 \emph off
21977 \bar no
21978 \noun off
21979 \color none
21980 sdcc/bin
21981 \end_inset
21982 </cell>
21983 </row>
21984 </lyxtabular>
21985
21986 \end_inset
21987
21988
21989 \newline
21990
21991 \layout Section
21992
21993 Documentation
21994 \begin_inset LatexCommand \index{Documentation}
21995
21996 \end_inset
21997
21998  included in the distribution
21999 \layout Standard
22000 \align center
22001
22002 \begin_inset  Tabular
22003 <lyxtabular version="3" rows="10" columns="2">
22004 <features>
22005 <column alignment="left" valignment="top" leftline="true" width="0">
22006 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
22007 <row topline="true" bottomline="true">
22008 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22009 \begin_inset Text
22010
22011 \layout Standard
22012
22013 Subject / Title
22014 \end_inset
22015 </cell>
22016 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22017 \begin_inset Text
22018
22019 \layout Standard
22020
22021 Where to get / filename
22022 \end_inset
22023 </cell>
22024 </row>
22025 <row topline="true">
22026 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22027 \begin_inset Text
22028
22029 \layout Standard
22030
22031 SDCC Compiler User Guide
22032 \end_inset
22033 </cell>
22034 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22035 \begin_inset Text
22036
22037 \layout Standard
22038
22039 You're reading it right now
22040 \end_inset
22041 </cell>
22042 </row>
22043 <row topline="true">
22044 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22045 \begin_inset Text
22046
22047 \layout Standard
22048
22049 Changelog of SDCC
22050 \end_inset
22051 </cell>
22052 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22053 \begin_inset Text
22054
22055 \layout Standard
22056
22057 sdcc/Changelog
22058 \end_inset
22059 </cell>
22060 </row>
22061 <row topline="true">
22062 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22063 \begin_inset Text
22064
22065 \layout Standard
22066
22067 ASXXXX
22068 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
22069
22070 \end_inset
22071
22072
22073 \begin_inset LatexCommand \index{Assembler documentation}
22074
22075 \end_inset
22076
22077  Assemblers and ASLINK
22078 \begin_inset LatexCommand \index{aslink}
22079
22080 \end_inset
22081
22082
22083 \begin_inset LatexCommand \index{Linker documentation}
22084
22085 \end_inset
22086
22087  Relocating Linker
22088 \end_inset
22089 </cell>
22090 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22091 \begin_inset Text
22092
22093 \layout Standard
22094
22095 sdcc/as/doc/asxhtm.html
22096 \end_inset
22097 </cell>
22098 </row>
22099 <row topline="true">
22100 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22101 \begin_inset Text
22102
22103 \layout Standard
22104
22105 SDCC regression test
22106 \begin_inset LatexCommand \index{Regression test}
22107
22108 \end_inset
22109
22110
22111 \end_inset
22112 </cell>
22113 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22114 \begin_inset Text
22115
22116 \layout Standard
22117
22118 sdcc/doc/test_suite_spec.pdf
22119 \end_inset
22120 </cell>
22121 </row>
22122 <row topline="true">
22123 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22124 \begin_inset Text
22125
22126 \layout Standard
22127
22128 Various notes
22129 \end_inset
22130 </cell>
22131 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22132 \begin_inset Text
22133
22134 \layout Standard
22135
22136 sdcc/doc/*
22137 \end_inset
22138 </cell>
22139 </row>
22140 <row topline="true">
22141 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22142 \begin_inset Text
22143
22144 \layout Standard
22145
22146 Notes on debugging with sdcdb
22147 \begin_inset LatexCommand \index{sdcdb (debugger)}
22148
22149 \end_inset
22150
22151
22152 \end_inset
22153 </cell>
22154 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22155 \begin_inset Text
22156
22157 \layout Standard
22158
22159 sdcc/debugger/README
22160 \end_inset
22161 </cell>
22162 </row>
22163 <row topline="true">
22164 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22165 \begin_inset Text
22166
22167 \layout Standard
22168
22169 Software simulator for microcontrollers
22170 \end_inset
22171 </cell>
22172 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22173 \begin_inset Text
22174
22175 \layout Standard
22176
22177
22178 \family roman
22179 \series medium
22180 \shape up
22181 \size normal
22182 \emph off
22183 \bar no
22184 \noun off
22185 \color none
22186 sdcc/sim/ucsim/doc
22187 \family default
22188 \series default
22189 \shape default
22190 \size default
22191 \emph default
22192 \bar default
22193 \noun default
22194 \color default
22195 /index.html
22196 \end_inset
22197 </cell>
22198 </row>
22199 <row topline="true">
22200 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22201 \begin_inset Text
22202
22203 \layout Standard
22204
22205 Temporary notes on the pic16
22206 \begin_inset LatexCommand \index{PIC16}
22207
22208 \end_inset
22209
22210  port
22211 \end_inset
22212 </cell>
22213 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22214 \begin_inset Text
22215
22216 \layout Standard
22217
22218 sdcc/src/pic16/NOTES
22219 \end_inset
22220 </cell>
22221 </row>
22222 <row topline="true" bottomline="true">
22223 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22224 \begin_inset Text
22225
22226 \layout Standard
22227
22228 SDCC internal documentation (debugging file format)
22229 \end_inset
22230 </cell>
22231 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22232 \begin_inset Text
22233
22234 \layout Standard
22235
22236 sdcc/doc/
22237 \family roman
22238 \series medium
22239 \shape up
22240 \size normal
22241 \emph off
22242 \bar no
22243 \noun off
22244 \color none
22245 cdbfileformat.pd
22246 \family default
22247 \series default
22248 \shape default
22249 \size default
22250 \emph default
22251 \bar default
22252 \noun default
22253 \color default
22254 f
22255 \end_inset
22256 </cell>
22257 </row>
22258 </lyxtabular>
22259
22260 \end_inset
22261
22262
22263 \newline
22264
22265 \layout Section
22266
22267 Related open source tools
22268 \begin_inset LatexCommand \index{Related tools}
22269
22270 \end_inset
22271
22272
22273 \layout Standard
22274 \align center
22275
22276 \begin_inset  Tabular
22277 <lyxtabular version="3" rows="11" columns="3">
22278 <features>
22279 <column alignment="center" valignment="top" leftline="true" width="0pt">
22280 <column alignment="block" valignment="top" leftline="true" width="30line%">
22281 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
22282 <row topline="true" bottomline="true">
22283 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22284 \begin_inset Text
22285
22286 \layout Standard
22287
22288 Name
22289 \end_inset
22290 </cell>
22291 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22292 \begin_inset Text
22293
22294 \layout Standard
22295
22296 Purpose
22297 \end_inset
22298 </cell>
22299 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22300 \begin_inset Text
22301
22302 \layout Standard
22303
22304 Where to get
22305 \end_inset
22306 </cell>
22307 </row>
22308 <row topline="true">
22309 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22310 \begin_inset Text
22311
22312 \layout Standard
22313
22314 gpsim
22315 \begin_inset LatexCommand \index{gpsim (pic simulator)}
22316
22317 \end_inset
22318
22319
22320 \end_inset
22321 </cell>
22322 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22323 \begin_inset Text
22324
22325 \layout Standard
22326
22327 PIC simulator
22328 \end_inset
22329 </cell>
22330 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22331 \begin_inset Text
22332
22333 \layout Standard
22334
22335
22336 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
22337
22338 \end_inset
22339
22340
22341 \end_inset
22342 </cell>
22343 </row>
22344 <row topline="true">
22345 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22346 \begin_inset Text
22347
22348 \layout Standard
22349
22350 gputils
22351 \begin_inset LatexCommand \index{gputils (pic tools)}
22352
22353 \end_inset
22354
22355
22356 \end_inset
22357 </cell>
22358 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22359 \begin_inset Text
22360
22361 \layout Standard
22362
22363 GNU PIC utilities
22364 \end_inset
22365 </cell>
22366 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22367 \begin_inset Text
22368
22369 \layout Standard
22370
22371
22372 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
22373
22374 \end_inset
22375
22376
22377 \end_inset
22378 </cell>
22379 </row>
22380 <row topline="true">
22381 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22382 \begin_inset Text
22383
22384 \layout Standard
22385
22386 flP5
22387 \end_inset
22388 </cell>
22389 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22390 \begin_inset Text
22391
22392 \layout Standard
22393
22394 PIC programmer
22395 \end_inset
22396 </cell>
22397 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22398 \begin_inset Text
22399
22400 \layout Standard
22401
22402
22403 \begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/}
22404
22405 \end_inset
22406
22407
22408 \end_inset
22409 </cell>
22410 </row>
22411 <row topline="true">
22412 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22413 \begin_inset Text
22414
22415 \layout Standard
22416
22417 indent
22418 \begin_inset LatexCommand \index{indent (source formatting tool)}
22419
22420 \end_inset
22421
22422
22423 \end_inset
22424 </cell>
22425 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22426 \begin_inset Text
22427
22428 \layout Standard
22429
22430 Formats C source - Master of the white spaces
22431 \end_inset
22432 </cell>
22433 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22434 \begin_inset Text
22435
22436 \layout Standard
22437
22438
22439 \begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html}
22440
22441 \end_inset
22442
22443
22444 \end_inset
22445 </cell>
22446 </row>
22447 <row topline="true">
22448 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22449 \begin_inset Text
22450
22451 \layout Standard
22452
22453 srecord
22454 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
22455
22456 \end_inset
22457
22458
22459 \end_inset
22460 </cell>
22461 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22462 \begin_inset Text
22463
22464 \layout Standard
22465
22466 Object file conversion, checksumming, ...
22467 \end_inset
22468 </cell>
22469 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22470 \begin_inset Text
22471
22472 \layout Standard
22473
22474
22475 \begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord}
22476
22477 \end_inset
22478
22479
22480 \end_inset
22481 </cell>
22482 </row>
22483 <row topline="true">
22484 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22485 \begin_inset Text
22486
22487 \layout Standard
22488
22489 objdump
22490 \begin_inset LatexCommand \index{objdump (tool)}
22491
22492 \end_inset
22493
22494
22495 \end_inset
22496 </cell>
22497 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22498 \begin_inset Text
22499
22500 \layout Standard
22501
22502 Object file conversion, ...
22503 \end_inset
22504 </cell>
22505 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22506 \begin_inset Text
22507
22508 \layout Standard
22509
22510 Part of binutils (should be there anyway)
22511 \end_inset
22512 </cell>
22513 </row>
22514 <row topline="true">
22515 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22516 \begin_inset Text
22517
22518 \layout Standard
22519
22520 doxygen
22521 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
22522
22523 \end_inset
22524
22525
22526 \end_inset
22527 </cell>
22528 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22529 \begin_inset Text
22530
22531 \layout Standard
22532
22533 Source code documentation system
22534 \end_inset
22535 </cell>
22536 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22537 \begin_inset Text
22538
22539 \layout Standard
22540
22541
22542 \begin_inset LatexCommand \url{http://www.doxygen.org}
22543
22544 \end_inset
22545
22546
22547 \end_inset
22548 </cell>
22549 </row>
22550 <row topline="true">
22551 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22552 \begin_inset Text
22553
22554 \layout Standard
22555
22556 kdevelop
22557 \end_inset
22558 </cell>
22559 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22560 \begin_inset Text
22561
22562 \layout Standard
22563
22564 IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
22565 \end_inset
22566 </cell>
22567 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22568 \begin_inset Text
22569
22570 \layout Standard
22571
22572
22573 \begin_inset LatexCommand \url{http://www.kdevelop.org}
22574
22575 \end_inset
22576
22577
22578 \end_inset
22579 </cell>
22580 </row>
22581 <row topline="true">
22582 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22583 \begin_inset Text
22584
22585 \layout Standard
22586
22587 splint
22588 \begin_inset LatexCommand \index{splint (syntax checking tool)}
22589
22590 \end_inset
22591
22592
22593 \end_inset
22594 </cell>
22595 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22596 \begin_inset Text
22597
22598 \layout Standard
22599
22600 Statically checks c sources (see
22601 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
22602
22603 \end_inset
22604
22605 )
22606 \end_inset
22607 </cell>
22608 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22609 \begin_inset Text
22610
22611 \layout Standard
22612
22613
22614 \begin_inset LatexCommand \url{http://www.splint.org}
22615
22616 \end_inset
22617
22618
22619 \end_inset
22620 </cell>
22621 </row>
22622 <row topline="true" bottomline="true">
22623 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22624 \begin_inset Text
22625
22626 \layout Standard
22627
22628 ddd
22629 \begin_inset LatexCommand \index{ddd (debugger)}
22630
22631 \end_inset
22632
22633
22634 \end_inset
22635 </cell>
22636 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22637 \begin_inset Text
22638
22639 \layout Standard
22640
22641 Debugger, serves nicely as GUI to sdcdb
22642 \begin_inset LatexCommand \index{sdcdb (debugger)}
22643
22644 \end_inset
22645
22646  (Unix only)
22647 \end_inset
22648 </cell>
22649 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22650 \begin_inset Text
22651
22652 \layout Standard
22653
22654
22655 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
22656
22657 \end_inset
22658
22659
22660 \end_inset
22661 </cell>
22662 </row>
22663 </lyxtabular>
22664
22665 \end_inset
22666
22667
22668 \newline
22669
22670 \layout Section
22671
22672 Related documentation / recommended reading
22673 \layout Standard
22674 \align center
22675
22676 \begin_inset  Tabular
22677 <lyxtabular version="3" rows="6" columns="3">
22678 <features>
22679 <column alignment="center" valignment="top" leftline="true" width="0pt">
22680 <column alignment="block" valignment="top" leftline="true" width="30line%">
22681 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
22682 <row topline="true" bottomline="true">
22683 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22684 \begin_inset Text
22685
22686 \layout Standard
22687
22688 Name
22689 \end_inset
22690 </cell>
22691 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22692 \begin_inset Text
22693
22694 \layout Standard
22695
22696 Subject / Title
22697 \end_inset
22698 </cell>
22699 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22700 \begin_inset Text
22701
22702 \layout Standard
22703
22704 Where to get
22705 \end_inset
22706 </cell>
22707 </row>
22708 <row topline="true">
22709 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22710 \begin_inset Text
22711
22712 \layout Standard
22713
22714
22715 \family roman
22716 \series medium
22717 \shape up
22718 \size normal
22719 \emph off
22720 \bar no
22721 \noun off
22722 \color none
22723 c-refcard.pdf
22724 \end_inset
22725 </cell>
22726 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22727 \begin_inset Text
22728
22729 \layout Standard
22730
22731 C Reference Card
22732 \begin_inset LatexCommand \index{C Reference card}
22733
22734 \end_inset
22735
22736 , 2 pages
22737 \end_inset
22738 </cell>
22739 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22740 \begin_inset Text
22741
22742 \layout Standard
22743
22744
22745 \begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html}
22746
22747 \end_inset
22748
22749
22750 \end_inset
22751 </cell>
22752 </row>
22753 <row topline="true">
22754 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22755 \begin_inset Text
22756
22757 \layout Standard
22758
22759 c-faq
22760 \end_inset
22761 </cell>
22762 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22763 \begin_inset Text
22764
22765 \layout Standard
22766
22767 C-FAQ-list
22768 \end_inset
22769 </cell>
22770 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22771 \begin_inset Text
22772
22773 \layout Standard
22774
22775
22776 \begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
22777
22778 \end_inset
22779
22780
22781 \end_inset
22782 </cell>
22783 </row>
22784 <row topline="true">
22785 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22786 \begin_inset Text
22787
22788 \layout Standard
22789
22790 \end_inset
22791 </cell>
22792 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22793 \begin_inset Text
22794
22795 \layout Standard
22796
22797 Latest datasheet of the target CPU
22798 \end_inset
22799 </cell>
22800 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22801 \begin_inset Text
22802
22803 \layout Standard
22804
22805 vendor
22806 \end_inset
22807 </cell>
22808 </row>
22809 <row topline="true">
22810 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22811 \begin_inset Text
22812
22813 \layout Standard
22814
22815 \end_inset
22816 </cell>
22817 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22818 \begin_inset Text
22819
22820 \layout Standard
22821
22822 Revision history of datasheet
22823 \end_inset
22824 </cell>
22825 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22826 \begin_inset Text
22827
22828 \layout Standard
22829
22830 vendor
22831 \end_inset
22832 </cell>
22833 </row>
22834 <row topline="true" bottomline="true">
22835 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22836 \begin_inset Text
22837
22838 \layout Standard
22839
22840 S.
22841  S.
22842  Muchnick
22843 \end_inset
22844 </cell>
22845 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22846 \begin_inset Text
22847
22848 \layout Standard
22849
22850 Advanced Compiler Design and Implementation
22851 \end_inset
22852 </cell>
22853 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22854 \begin_inset Text
22855
22856 \layout Standard
22857
22858 bookstore (very dedicated, probably read other books first)
22859 \end_inset
22860 </cell>
22861 </row>
22862 </lyxtabular>
22863
22864 \end_inset
22865
22866
22867 \newline
22868
22869 \layout Section
22870
22871 Some Questions
22872 \layout Standard
22873
22874 Some questions answered, some pointers given - it might be time to in turn
22875  ask
22876 \emph on
22877 you
22878 \emph default
22879  some questions:
22880 \layout Itemize
22881
22882 can you solve your project with the selected microcontroller? Would you
22883  find out early or rather late that your target is too small/slow/whatever?
22884  Can you switch to a slightly better device if it doesn't fit?
22885 \layout Itemize
22886
22887 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
22888  and/or another programming language be more adequate? Would an operating
22889  system on the target device help?
22890 \layout Itemize
22891
22892 if you solved the problem, will the marketing department be happy?
22893 \layout Itemize
22894
22895 if the marketing department is happy, will customers be happy?
22896 \layout Itemize
22897
22898 if you're the project manager, marketing department and maybe even the customer
22899  in one person, have you tried to see the project from the outside?
22900 \layout Itemize
22901
22902 is the project done if you think it is done? Or is just that other interface/pro
22903 tocol/feature/configuration/option missing? How about website, manual(s),
22904  internationali(z|s)ation, packaging, labels, 2nd source for components,
22905  electromagnetic compatability/interference, documentation for production,
22906  production test software, update mechanism, patent issues?
22907 \layout Itemize
22908
22909 is your project adequately positioned in that magic triangle: fame, fortune,
22910  fun?
22911 \layout Standard
22912
22913 Maybe not all answers to these questions are known and some answers may
22914  even be
22915 \emph on
22916 no
22917 \emph default
22918 , nevertheless knowing these questions may help you to avoid burnout
22919 \begin_inset Foot
22920 collapsed false
22921
22922 \layout Standard
22923
22924 burnout is bad for electronic devices, programmers and motorcycle tyres
22925 \end_inset
22926
22927 .
22928  Chances are you didn't want to hear some of them...
22929 \layout Chapter
22930
22931 Support
22932 \begin_inset LatexCommand \index{Support}
22933
22934 \end_inset
22935
22936
22937 \layout Standard
22938
22939 SDCC has grown to be a large project.
22940  The compiler alone (without the preprocessor, assembler and linker) is
22941  well over 100,000 lines of code (blank stripped).
22942  The open source nature of this project is a key to its continued growth
22943  and support.
22944  You gain the benefit and support of many active software developers and
22945  end users.
22946  Is SDCC perfect? No, that's why we need your help.
22947  The developers take pride in fixing reported bugs.
22948  You can help by reporting the bugs and helping other SDCC users.
22949  There are lots of ways to contribute, and we encourage you to take part
22950  in making SDCC a great software package.
22951
22952 \layout Standard
22953
22954 The SDCC project is hosted on the SDCC sourceforge site at
22955 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
22956
22957 \end_inset
22958
22959 .
22960  You'll find the complete set of mailing lists
22961 \begin_inset LatexCommand \index{Mailing list(s)}
22962
22963 \end_inset
22964
22965 , forums, bug reporting system, patch submission
22966 \begin_inset LatexCommand \index{Patch submission}
22967
22968 \end_inset
22969
22970  system, download
22971 \begin_inset LatexCommand \index{download}
22972
22973 \end_inset
22974
22975  area and cvs code repository
22976 \begin_inset LatexCommand \index{cvs code repository}
22977
22978 \end_inset
22979
22980  there.
22981 \layout Section
22982
22983 Reporting Bugs
22984 \begin_inset LatexCommand \index{Bug reporting}
22985
22986 \end_inset
22987
22988
22989 \begin_inset LatexCommand \index{Reporting bugs}
22990
22991 \end_inset
22992
22993
22994 \layout Standard
22995
22996 The recommended way of reporting bugs is using the infrastructure of the
22997  sourceforge site.
22998  You can follow the status of bug reports there and have an overview about
22999  the known bugs.
23000 \layout Standard
23001
23002 Bug reports are automatically forwarded to the developer mailing list and
23003  will be fixed ASAP.
23004  When reporting a bug, it is very useful to include a small test program
23005  (the smaller the better) which reproduces the problem.
23006  If you can isolate the problem by looking at the generated assembly code,
23007  this can be very helpful.
23008  Compiling your program with the -
23009 \begin_inset ERT
23010 status Collapsed
23011
23012 \layout Standard
23013
23014 \backslash
23015 /
23016 \end_inset
23017
23018 -dumpall
23019 \begin_inset LatexCommand \index{-\/-dumpall}
23020
23021 \end_inset
23022
23023  option can sometimes be useful in locating optimization problems.
23024  When reporting a bug please maker sure you:
23025 \layout Enumerate
23026
23027 Attach the code you are compiling with SDCC.
23028
23029 \layout Enumerate
23030
23031 Specify the exact command you use to run SDCC, or attach your Makefile.
23032
23033 \layout Enumerate
23034
23035 Specify the SDCC version (type "
23036 \family sans
23037 \series bold
23038 sdcc -v
23039 \family default
23040 \series default
23041 "), your platform, and operating system.
23042
23043 \layout Enumerate
23044
23045 Provide an exact copy of any error message or incorrect output.
23046
23047 \layout Enumerate
23048
23049 Put something meaningful in the subject of your message.
23050 \layout Standard
23051
23052 Please attempt to include these 5 important parts, as applicable, in all
23053  requests for support or when reporting any problems or bugs with SDCC.
23054  Though this will make your message lengthy, it will greatly improve your
23055  chance that SDCC users and developers will be able to help you.
23056  Some SDCC developers are frustrated by bug reports without code provided
23057  that they can use to reproduce and ultimately fix the problem, so please
23058  be sure to provide sample code if you are reporting a bug!
23059 \layout Standard
23060
23061 Please have a short check that you are using a recent version of SDCC and
23062  the bug is not yet known.
23063  This is the link for reporting bugs:
23064 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
23065
23066 \end_inset
23067
23068 .
23069 \layout Section
23070
23071 Requesting Features
23072 \begin_inset LatexCommand \label{sub:Requesting-Features}
23073
23074 \end_inset
23075
23076
23077 \begin_inset LatexCommand \index{Feature request}
23078
23079 \end_inset
23080
23081
23082 \begin_inset LatexCommand \index{Requesting features}
23083
23084 \end_inset
23085
23086
23087 \layout Standard
23088
23089 Like bug reports feature requests are forwarded to the developer mailing
23090  list.
23091  This is the link for requesting features:
23092 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
23093
23094 \end_inset
23095
23096 .
23097 \layout Section
23098
23099 Submitting patches
23100 \layout Standard
23101
23102 Like bug reports contributed patches are forwarded to the developer mailing
23103  list.
23104  This is the link for submitting patches
23105 \begin_inset LatexCommand \index{Patch submission}
23106
23107 \end_inset
23108
23109 :
23110 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
23111
23112 \end_inset
23113
23114 .
23115 \layout Standard
23116
23117 You need to specify some parameters to the
23118 \family typewriter
23119 diff
23120 \family default
23121  command for the patches to be useful.
23122  If you modified more than one file a patch created f.e.
23123  with
23124 \family sans
23125 \series bold
23126
23127 \begin_inset Quotes sld
23128 \end_inset
23129
23130 diff -Naur unmodified_directory modified_directory >my_changes.patch
23131 \begin_inset Quotes srd
23132 \end_inset
23133
23134
23135 \family default
23136 \series default
23137  will be fine, otherwise
23138 \family sans
23139 \series bold
23140
23141 \begin_inset Quotes sld
23142 \end_inset
23143
23144 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
23145 \begin_inset Quotes srd
23146 \end_inset
23147
23148
23149 \series default
23150
23151 \family default
23152 will do.
23153 \layout Section
23154
23155 Getting Help
23156 \layout Standard
23157
23158 These links should take you directly to the
23159 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
23160
23161 \end_inset
23162
23163
23164 \begin_inset Foot
23165 collapsed false
23166
23167 \layout Standard
23168
23169 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
23170  automated messages (mid 2003)
23171 \end_inset
23172
23173  and the
23174 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
23175
23176 \end_inset
23177
23178 , lists
23179 \begin_inset LatexCommand \index{Mailing list(s)}
23180
23181 \end_inset
23182
23183  and forums are archived and searchable so if you are lucky someone already
23184  had a similar problem.
23185  While mails to the lists themselves are delivered promptly their web front
23186  end on sourceforge sometimes shows a severe time lag (up to several weeks),
23187  if you're seriously using SDCC please consider subscribing to the lists.
23188 \layout Section
23189
23190 ChangeLog
23191 \layout Standard
23192
23193 You can follow the status of the cvs version
23194 \begin_inset LatexCommand \index{version}
23195
23196 \end_inset
23197
23198  of SDCC by watching the Changelog
23199 \begin_inset LatexCommand \index{Changelog}
23200
23201 \end_inset
23202
23203  in the cvs-repository
23204 \newline
23205
23206 \size footnotesize
23207
23208 \begin_inset LatexCommand \htmlurl{http://cvs.sf.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
23209
23210 \end_inset
23211
23212 .
23213 \layout Section
23214
23215 Release policy
23216 \begin_inset LatexCommand \index{Release policy}
23217
23218 \end_inset
23219
23220
23221 \layout Standard
23222
23223 Historically there often were long delays between official releases and
23224  the sourceforge download area tends to get not updated at all.
23225  Excuses in the past might have referred to problems with live range analysis,
23226  but as this was fixed a while ago, the current problem is that another
23227  excuse has to be found.
23228  Kidding aside, we have to get better there! On the other hand there are
23229  daily snapshots available at
23230 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
23231
23232 \end_inset
23233
23234 , and you can always build the very last version (hopefully with many bugs
23235  fixed, and features added) from the source code available at
23236 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
23237
23238 \end_inset
23239
23240 .
23241 \layout Section
23242
23243 Examples
23244 \begin_inset LatexCommand \index{Examples}
23245
23246 \end_inset
23247
23248
23249 \layout Standard
23250
23251 You'll find some small examples in the directory
23252 \emph on
23253 sdcc/device/examples/.
23254
23255 \emph default
23256 More examples and libraries are available at
23257 \emph on
23258  The SDCC Open Knowledge Resource
23259 \begin_inset LatexCommand \url{http://sdccokr.dl9sec.de/}
23260
23261 \end_inset
23262
23263
23264 \emph default
23265 web site or at
23266 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
23267
23268 \end_inset
23269
23270 .
23271 \layout Comment
23272
23273 I did insert a reference to Paul's web site here although it seems rather
23274  dedicated to a specific 8032 board (I think it's okay because it f.e.
23275  shows LCD/Harddisc interface and has a free 8051 monitor.
23276  Independent 8032 board vendors face hard competition of heavily subsidized
23277  development boards anyway).
23278 \layout Comment
23279
23280 Maybe we should include some links to real world applications.
23281  Preferably pointer to pointers (one for each architecture) so this stays
23282  manageable here?
23283 \layout Section
23284
23285 Quality control
23286 \begin_inset LatexCommand \index{Quality control}
23287
23288 \end_inset
23289
23290
23291 \layout Standard
23292
23293 The compiler is passed through nightly compile and build checks.
23294  The so called
23295 \shape italic
23296 regression tests
23297 \shape default
23298
23299 \begin_inset LatexCommand \index{Regression test}
23300
23301 \end_inset
23302
23303  check that SDCC itself compiles flawlessly on several platforms and checks
23304  the quality of the code generated by SDCC by running the code through simulator
23305 s.
23306  There is a separate document
23307 \shape italic
23308 test_suite.pdf
23309 \begin_inset LatexCommand \index{Test suite}
23310
23311 \end_inset
23312
23313
23314 \shape default
23315  about this.
23316 \layout Standard
23317
23318 You'll find the test code in the directory
23319 \shape italic
23320 sdcc/support/regression
23321 \shape default
23322 .
23323  You can run these tests manually by running
23324 \family sans
23325 make
23326 \family default
23327  in this directory (or f.e.
23328
23329 \family sans
23330 \series bold
23331
23332 \begin_inset Quotes sld
23333 \end_inset
23334
23335 make test-mcs51
23336 \begin_inset Quotes srd
23337 \end_inset
23338
23339
23340 \family default
23341 \series default
23342  if you don't want to run the complete tests).
23343  The test code might also be interesting if you want to look for examples
23344 \begin_inset LatexCommand \index{Examples}
23345
23346 \end_inset
23347
23348  checking corner cases of SDCC or if you plan to submit patches
23349 \begin_inset LatexCommand \index{Patch submission}
23350
23351 \end_inset
23352
23353 .
23354 \layout Standard
23355
23356 The pic port uses a different set of regression tests, you'll find them
23357  in the directory
23358 \shape italic
23359 sdcc/src/regression
23360 \shape default
23361 .
23362 \layout Section
23363
23364 Use of SDCC in Education
23365 \layout Standard
23366
23367 In short:
23368 \emph on
23369 highly
23370 \emph default
23371  encouraged
23372 \begin_inset Foot
23373 collapsed false
23374
23375 \layout Standard
23376
23377 the phrase "use in education" might evoke the association "
23378 \emph on
23379 only
23380 \emph default
23381  fit for use in education".
23382  This connotation is not intended but nevertheless risked as the licensing
23383  of SDCC makes it difficult to offer educational discounts
23384 \end_inset
23385
23386 .
23387  If your rationales are to:
23388 \layout Enumerate
23389
23390 give students a chance to understand the
23391 \emph on
23392 complete
23393 \emph default
23394  steps of code generation
23395 \layout Enumerate
23396
23397 have a curriculum that can be extended for years.
23398  Then you could use an fpga board as target and your curriculum will seamlessly
23399  extend from logic synthesis (
23400 \begin_inset LatexCommand \url[http://www.opencores.org]{opencores.org}
23401
23402 \end_inset
23403
23404 ,
23405 \begin_inset LatexCommand \url[Oregano]{http://www.oregano.at/ip/ip01.htm}
23406
23407 \end_inset
23408
23409 ), over assembly programming, to C to FPGA compilers (
23410 \begin_inset LatexCommand \url[FPGAC]{http://sf.net/projects/fpgac}
23411
23412 \end_inset
23413
23414 ) and to C.
23415 \layout Enumerate
23416
23417 be able to insert excursions about skills like using a revision control
23418  system, submitting/applying patches, using a type-setting (as opposed to
23419  word-processing) engine LyX/LaTeX, using
23420 \begin_inset LatexCommand \url[SourceForge]{http://www.sf.net}
23421
23422 \end_inset
23423
23424 , following some
23425 \begin_inset LatexCommand \url[netiquette]{http://en.wikipedia.org/wiki/Netiquette}
23426
23427 \end_inset
23428
23429 , understanding BSD/LGPL/GPL/Proprietary licensing, growth models of Open
23430  Source Software, CPU simulation, compiler regression tests
23431 \begin_inset LatexCommand \index{Regression test}
23432
23433 \end_inset
23434
23435 .
23436
23437 \newline
23438 And if there should be a shortage of ideas then you can always point students
23439  to the ever-growing feature request list
23440 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
23441
23442 \end_inset
23443
23444 .
23445 \layout Enumerate
23446
23447 not tie students to a specific host platform and instead allow them to use
23448  a host platform of
23449 \emph on
23450 their
23451 \emph default
23452  choice (among them Alpha, i386, i386_64, MacOs, Mips, Sparc, Windows and
23453  eventually
23454 \begin_inset LatexCommand \url[OLPC]{http://wiki.laptop.org/wiki/One_Laptop_per_Child}
23455
23456 \end_inset
23457
23458 )
23459 \layout Enumerate
23460
23461 not encourage students to use illegal copies of educational software
23462 \layout Enumerate
23463
23464 be immune to licensing/availability/price changes of the chosen tool chain
23465 \layout Enumerate
23466
23467 be able to change to a new target platform without having to adopt a new
23468  tool chain
23469 \layout Enumerate
23470
23471 have complete control over and insight into the tool chain
23472 \layout Enumerate
23473
23474 make your students aware about the pros and cons of open source software
23475  development
23476 \layout Enumerate
23477
23478 give back to the public as you are probably at least partially publically
23479  funded
23480 \layout Enumerate
23481
23482 give students a chance to publically prove their skills and to possibly
23483  see a world wide impact
23484 \layout Standard
23485
23486 then SDCC is probably among the first choices.
23487  Well, probably SDCC might be the only choice.
23488 \layout Chapter
23489 \pagebreak_top
23490 SDCC Technical Data
23491 \layout Section
23492
23493 Optimizations
23494 \begin_inset LatexCommand \index{Optimizations}
23495
23496 \end_inset
23497
23498
23499 \layout Standard
23500
23501 SDCC performs a host of standard optimizations in addition to some MCU specific
23502  optimizations.
23503
23504 \layout Subsection
23505
23506 Sub-expression Elimination
23507 \begin_inset LatexCommand \index{Subexpression elimination}
23508
23509 \end_inset
23510
23511
23512 \layout Standard
23513
23514 The compiler does local and
23515 \emph on
23516 g
23517 \emph default
23518 lobal
23519 \emph on
23520 c
23521 \emph default
23522 ommon
23523 \emph on
23524 s
23525 \emph default
23526 ubexpression
23527 \emph on
23528 e
23529 \emph default
23530 limination, e.g.:
23531 \layout Verse
23532
23533
23534 \family typewriter
23535 i = x + y + 1;
23536 \newline
23537 j = x + y;
23538 \layout Standard
23539
23540 will be translated to
23541 \layout Verse
23542
23543
23544 \family typewriter
23545 iTemp = x + y;
23546 \newline
23547 i = iTemp + 1;
23548 \newline
23549 j = iTemp;
23550 \layout Standard
23551
23552 Some subexpressions are not as obvious as the above example, e.g.:
23553 \layout Verse
23554
23555
23556 \family typewriter
23557 a->b[i].c = 10;
23558 \newline
23559 a->b[i].d = 11;
23560 \layout Standard
23561
23562 In this case the address arithmetic a->b[i] will be computed only once;
23563  the equivalent code in C would be.
23564 \layout Verse
23565
23566
23567 \family typewriter
23568 iTemp = a->b[i];
23569 \newline
23570 iTemp.c = 10;
23571 \newline
23572 iTemp.d = 11;
23573 \layout Standard
23574
23575 The compiler will try to keep these temporary variables in registers.
23576 \layout Subsection
23577
23578 Dead-Code Elimination
23579 \begin_inset LatexCommand \index{Dead-code elimination}
23580
23581 \end_inset
23582
23583
23584 \layout Verse
23585
23586
23587 \family typewriter
23588 int global;
23589 \newline
23590
23591 \newline
23592 void f () {
23593 \newline
23594 \SpecialChar ~
23595 \SpecialChar ~
23596 int i;
23597 \newline
23598 \SpecialChar ~
23599 \SpecialChar ~
23600 i = 1; \SpecialChar ~
23601 \SpecialChar ~
23602 \SpecialChar ~
23603 \SpecialChar ~
23604 \SpecialChar ~
23605 /* dead store */
23606 \newline
23607 \SpecialChar ~
23608 \SpecialChar ~
23609 global = 1;\SpecialChar ~
23610 /* dead store */
23611 \newline
23612 \SpecialChar ~
23613 \SpecialChar ~
23614 global = 2;
23615 \newline
23616 \SpecialChar ~
23617 \SpecialChar ~
23618 return;
23619 \newline
23620 \SpecialChar ~
23621 \SpecialChar ~
23622 global = 3;\SpecialChar ~
23623 /* unreachable */
23624 \newline
23625 }
23626 \layout Standard
23627
23628 will be changed to
23629 \layout Verse
23630
23631
23632 \family typewriter
23633 int global;
23634 \newline
23635
23636 \newline
23637 void f () {
23638 \newline
23639 \SpecialChar ~
23640 \SpecialChar ~
23641 global = 2;
23642 \newline
23643 }
23644 \layout Subsection
23645
23646 Copy-Propagation
23647 \begin_inset LatexCommand \index{Copy propagation}
23648
23649 \end_inset
23650
23651
23652 \layout Verse
23653
23654
23655 \family typewriter
23656 int f() {
23657 \newline
23658 \SpecialChar ~
23659 \SpecialChar ~
23660 int i, j;
23661 \newline
23662 \SpecialChar ~
23663 \SpecialChar ~
23664 i = 10;
23665 \newline
23666 \SpecialChar ~
23667 \SpecialChar ~
23668 j = i;
23669 \newline
23670 \SpecialChar ~
23671 \SpecialChar ~
23672 return j;
23673 \newline
23674 }
23675 \layout Standard
23676
23677 will be changed to
23678 \layout Verse
23679
23680
23681 \family typewriter
23682 int f() {
23683 \newline
23684 \SpecialChar ~
23685 \SpecialChar ~
23686 int i, j;
23687 \newline
23688 \SpecialChar ~
23689 \SpecialChar ~
23690 i = 10;
23691 \newline
23692 \SpecialChar ~
23693 \SpecialChar ~
23694 j = 10;
23695 \newline
23696 \SpecialChar ~
23697 \SpecialChar ~
23698 return 10;
23699 \newline
23700 }
23701 \layout Standard
23702
23703 Note: the dead stores created by this copy propagation will be eliminated
23704  by dead-code elimination.
23705 \layout Subsection
23706
23707 Loop Optimizations
23708 \begin_inset LatexCommand \index{Loop optimization}
23709
23710 \end_inset
23711
23712
23713 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
23714
23715 \end_inset
23716
23717
23718 \layout Standard
23719
23720 Two types of loop optimizations are done by SDCC
23721 \emph on
23722 loop invariant
23723 \emph default
23724  lifting and
23725 \emph on
23726  strength reduction
23727 \emph default
23728  of loop induction variables.
23729  In addition to the strength reduction the optimizer marks the induction
23730  variables and the register allocator tries to keep the induction variables
23731  in registers for the duration of the loop.
23732  Because of this preference of the register allocator
23733 \begin_inset LatexCommand \index{Register allocation}
23734
23735 \end_inset
23736
23737 , loop induction optimization causes an increase in register pressure, which
23738  may cause unwanted spilling of other temporary variables into the stack
23739 \begin_inset LatexCommand \index{stack}
23740
23741 \end_inset
23742
23743  / data space.
23744  The compiler will generate a warning message when it is forced to allocate
23745  extra space either on the stack or data space.
23746  If this extra space allocation is undesirable then induction optimization
23747  can be eliminated either for the entire source file (with -
23748 \begin_inset ERT
23749 status Collapsed
23750
23751 \layout Standard
23752
23753 \backslash
23754 /
23755 \end_inset
23756
23757 -noinduction option) or for a given function only using #pragma\SpecialChar ~
23758 noinduction
23759 \begin_inset LatexCommand \index{\#pragma noinduction}
23760
23761 \end_inset
23762
23763 .
23764 \newline
23765
23766 \newline
23767 Loop Invariant:
23768 \layout Verse
23769
23770
23771 \family typewriter
23772 for (i = 0 ; i < 100 ; i ++)
23773 \newline
23774 \SpecialChar ~
23775 \SpecialChar ~
23776 \SpecialChar ~
23777 \SpecialChar ~
23778 f += k + l;
23779 \layout Standard
23780
23781 changed to
23782 \layout Verse
23783
23784
23785 \family typewriter
23786 itemp = k + l;
23787 \newline
23788 for (i = 0; i < 100; i++)
23789 \newline
23790 \SpecialChar ~
23791 \SpecialChar ~
23792 \SpecialChar ~
23793 \SpecialChar ~
23794 f += itemp;
23795 \layout Standard
23796
23797 As mentioned previously some loop invariants are not as apparent, all static
23798  address computations are also moved out of the loop.
23799 \newline
23800
23801 \newline
23802 Strength Reduction
23803 \begin_inset LatexCommand \index{Strength reduction}
23804
23805 \end_inset
23806
23807 , this optimization substitutes an expression by a cheaper expression:
23808 \layout Verse
23809
23810
23811 \family typewriter
23812 for (i=0;i < 100; i++)
23813 \newline
23814 \SpecialChar ~
23815 \SpecialChar ~
23816 \SpecialChar ~
23817 \SpecialChar ~
23818 ar[i*5] = i*3;
23819 \layout Standard
23820
23821 changed to
23822 \layout Verse
23823
23824
23825 \family typewriter
23826 itemp1 = 0;
23827 \newline
23828 itemp2 = 0;
23829 \newline
23830 for (i=0;i< 100;i++) {
23831 \newline
23832 \SpecialChar ~
23833 \SpecialChar ~
23834 \SpecialChar ~
23835 \SpecialChar ~
23836 ar[itemp1] = itemp2;
23837 \newline
23838 \SpecialChar ~
23839 \SpecialChar ~
23840 \SpecialChar ~
23841 \SpecialChar ~
23842 itemp1 += 5;
23843 \newline
23844 \SpecialChar ~
23845 \SpecialChar ~
23846 \SpecialChar ~
23847 \SpecialChar ~
23848 itemp2 += 3;
23849 \newline
23850 }
23851 \layout Standard
23852
23853 The more expensive multiplication
23854 \begin_inset LatexCommand \index{Multiplication}
23855
23856 \end_inset
23857
23858  is changed to a less expensive addition.
23859 \layout Subsection
23860
23861 Loop Reversing
23862 \begin_inset LatexCommand \index{Loop reversing}
23863
23864 \end_inset
23865
23866
23867 \layout Standard
23868
23869 This optimization is done to reduce the overhead of checking loop boundaries
23870  for every iteration.
23871  Some simple loops can be reversed and implemented using a
23872 \begin_inset Quotes eld
23873 \end_inset
23874
23875 decrement and jump if not zero
23876 \begin_inset Quotes erd
23877 \end_inset
23878
23879  instruction.
23880  SDCC checks for the following criterion to determine if a loop is reversible
23881  (note: more sophisticated compilers use data-dependency analysis to make
23882  this determination, SDCC uses a more simple minded analysis).
23883 \layout Itemize
23884
23885 The 'for' loop is of the form
23886 \newline
23887
23888 \newline
23889
23890 \family typewriter
23891 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
23892  += 1])
23893 \newline
23894 \SpecialChar ~
23895 \SpecialChar ~
23896 \SpecialChar ~
23897 \SpecialChar ~
23898 <for body>
23899 \layout Itemize
23900
23901 The <for body> does not contain
23902 \begin_inset Quotes eld
23903 \end_inset
23904
23905 continue
23906 \begin_inset Quotes erd
23907 \end_inset
23908
23909  or 'break
23910 \begin_inset Quotes erd
23911 \end_inset
23912
23913 .
23914 \layout Itemize
23915
23916 All goto's are contained within the loop.
23917 \layout Itemize
23918
23919 No function calls within the loop.
23920 \layout Itemize
23921
23922 The loop control variable <sym> is not assigned any value within the loop
23923 \layout Itemize
23924
23925 The loop control variable does NOT participate in any arithmetic operation
23926  within the loop.
23927 \layout Itemize
23928
23929 There are NO switch statements in the loop.
23930 \layout Subsection
23931
23932 Algebraic Simplifications
23933 \layout Standard
23934
23935 SDCC does numerous algebraic simplifications, the following is a small sub-set
23936  of these optimizations.
23937 \layout Verse
23938
23939
23940 \family typewriter
23941 i = j + 0;\SpecialChar ~
23942 \SpecialChar ~
23943 \SpecialChar ~
23944 \SpecialChar ~
23945  /* changed to: */\SpecialChar ~
23946 \SpecialChar ~
23947 \SpecialChar ~
23948 \SpecialChar ~
23949  i = j;
23950 \newline
23951 i /= 2;\SpecialChar ~
23952 \SpecialChar ~
23953 \SpecialChar ~
23954 \SpecialChar ~
23955 \SpecialChar ~
23956 \SpecialChar ~
23957 \SpecialChar ~
23958  /* changed to: */\SpecialChar ~
23959 \SpecialChar ~
23960 \SpecialChar ~
23961 \SpecialChar ~
23962  i >>= 1;
23963 \newline
23964 i = j - j;\SpecialChar ~
23965 \SpecialChar ~
23966 \SpecialChar ~
23967 \SpecialChar ~
23968  /* changed to: */\SpecialChar ~
23969 \SpecialChar ~
23970 \SpecialChar ~
23971 \SpecialChar ~
23972  i = 0;
23973 \newline
23974 i = j / 1;\SpecialChar ~
23975 \SpecialChar ~
23976 \SpecialChar ~
23977 \SpecialChar ~
23978  /* changed to: */\SpecialChar ~
23979 \SpecialChar ~
23980 \SpecialChar ~
23981 \SpecialChar ~
23982  i = j;
23983 \layout Standard
23984
23985 Note the subexpressions
23986 \begin_inset LatexCommand \index{Subexpression}
23987
23988 \end_inset
23989
23990  given above are generally introduced by macro expansions or as a result
23991  of copy/constant propagation.
23992 \layout Subsection
23993
23994 'switch' Statements
23995 \begin_inset LatexCommand \label{sub:'switch'-Statements}
23996
23997 \end_inset
23998
23999
24000 \begin_inset LatexCommand \index{switch statement}
24001
24002 \end_inset
24003
24004
24005 \layout Standard
24006
24007 SDCC can optimize switch statements to jump tables
24008 \begin_inset LatexCommand \index{jump tables}
24009
24010 \end_inset
24011
24012 .
24013  It makes the decision based on an estimate of the generated code size.
24014  SDCC is quite liberal in the requirements for jump table generation:
24015 \layout Itemize
24016
24017 The labels need not be in order, and the starting number need not be one
24018  or zero, the case labels are in numerical sequence or not too many case
24019  labels are missing.
24020 \begin_deeper
24021 \layout Verse
24022
24023
24024 \family typewriter
24025 switch(i) {\SpecialChar ~
24026 \SpecialChar ~
24027 \SpecialChar ~
24028 \SpecialChar ~
24029 \SpecialChar ~
24030 \SpecialChar ~
24031 \SpecialChar ~
24032 \SpecialChar ~
24033 \SpecialChar ~
24034 \SpecialChar ~
24035 \SpecialChar ~
24036 \SpecialChar ~
24037 \SpecialChar ~
24038 \SpecialChar ~
24039 \SpecialChar ~
24040 \SpecialChar ~
24041 \SpecialChar ~
24042 \SpecialChar ~
24043 \SpecialChar ~
24044 \SpecialChar ~
24045 \SpecialChar ~
24046 \SpecialChar ~
24047 \SpecialChar ~
24048 \SpecialChar ~
24049 \SpecialChar ~
24050 \SpecialChar ~
24051 switch (i) {
24052 \newline
24053 \SpecialChar ~
24054 \SpecialChar ~
24055 \SpecialChar ~
24056 case 4: ...\SpecialChar ~
24057 \SpecialChar ~
24058 \SpecialChar ~
24059 \SpecialChar ~
24060 \SpecialChar ~
24061 \SpecialChar ~
24062 \SpecialChar ~
24063 \SpecialChar ~
24064 \SpecialChar ~
24065 \SpecialChar ~
24066 \SpecialChar ~
24067 \SpecialChar ~
24068 \SpecialChar ~
24069 \SpecialChar ~
24070 \SpecialChar ~
24071 \SpecialChar ~
24072 \SpecialChar ~
24073 \SpecialChar ~
24074 \SpecialChar ~
24075 \SpecialChar ~
24076 \SpecialChar ~
24077 \SpecialChar ~
24078 \SpecialChar ~
24079 \SpecialChar ~
24080 \SpecialChar ~
24081 \SpecialChar ~
24082 case 0: ...
24083
24084 \newline
24085 \SpecialChar ~
24086 \SpecialChar ~
24087 \SpecialChar ~
24088 case 5: ...\SpecialChar ~
24089 \SpecialChar ~
24090 \SpecialChar ~
24091 \SpecialChar ~
24092 \SpecialChar ~
24093 \SpecialChar ~
24094 \SpecialChar ~
24095 \SpecialChar ~
24096 \SpecialChar ~
24097 \SpecialChar ~
24098 \SpecialChar ~
24099 \SpecialChar ~
24100 \SpecialChar ~
24101 \SpecialChar ~
24102 \SpecialChar ~
24103 \SpecialChar ~
24104 \SpecialChar ~
24105 \SpecialChar ~
24106 \SpecialChar ~
24107 \SpecialChar ~
24108 \SpecialChar ~
24109 \SpecialChar ~
24110 \SpecialChar ~
24111 \SpecialChar ~
24112 \SpecialChar ~
24113 \SpecialChar ~
24114 case 1: ...
24115
24116 \newline
24117 \SpecialChar ~
24118 \SpecialChar ~
24119 \SpecialChar ~
24120 case 3: ...\SpecialChar ~
24121 \SpecialChar ~
24122 \SpecialChar ~
24123 \SpecialChar ~
24124 \SpecialChar ~
24125 \SpecialChar ~
24126 \SpecialChar ~
24127 \SpecialChar ~
24128 \SpecialChar ~
24129 \SpecialChar ~
24130 \SpecialChar ~
24131 \SpecialChar ~
24132 \SpecialChar ~
24133 \SpecialChar ~
24134 \SpecialChar ~
24135 \SpecialChar ~
24136 \SpecialChar ~
24137 \SpecialChar ~
24138 \SpecialChar ~
24139 \SpecialChar ~
24140 \SpecialChar ~
24141 \SpecialChar ~
24142 \SpecialChar ~
24143 \SpecialChar ~
24144 \SpecialChar ~
24145 \SpecialChar ~
24146
24147 \newline
24148 \SpecialChar ~
24149 \SpecialChar ~
24150 \SpecialChar ~
24151 case 6: ...\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 \SpecialChar ~
24169 \SpecialChar ~
24170 \SpecialChar ~
24171 \SpecialChar ~
24172 \SpecialChar ~
24173 \SpecialChar ~
24174 \SpecialChar ~
24175 \SpecialChar ~
24176 \SpecialChar ~
24177 case 3: ...
24178
24179 \newline
24180 \SpecialChar ~
24181 \SpecialChar ~
24182 \SpecialChar ~
24183 case 7: ...\SpecialChar ~
24184 \SpecialChar ~
24185 \SpecialChar ~
24186 \SpecialChar ~
24187 \SpecialChar ~
24188 \SpecialChar ~
24189 \SpecialChar ~
24190 \SpecialChar ~
24191 \SpecialChar ~
24192 \SpecialChar ~
24193 \SpecialChar ~
24194 \SpecialChar ~
24195 \SpecialChar ~
24196 \SpecialChar ~
24197 \SpecialChar ~
24198 \SpecialChar ~
24199 \SpecialChar ~
24200 \SpecialChar ~
24201 \SpecialChar ~
24202 \SpecialChar ~
24203 \SpecialChar ~
24204 \SpecialChar ~
24205 \SpecialChar ~
24206 \SpecialChar ~
24207 \SpecialChar ~
24208 \SpecialChar ~
24209 case 4: ...
24210
24211 \newline
24212 \SpecialChar ~
24213 \SpecialChar ~
24214 \SpecialChar ~
24215 case 8: ...\SpecialChar ~
24216 \SpecialChar ~
24217 \SpecialChar ~
24218 \SpecialChar ~
24219 \SpecialChar ~
24220 \SpecialChar ~
24221 \SpecialChar ~
24222 \SpecialChar ~
24223 \SpecialChar ~
24224 \SpecialChar ~
24225 \SpecialChar ~
24226 \SpecialChar ~
24227 \SpecialChar ~
24228 \SpecialChar ~
24229 \SpecialChar ~
24230 \SpecialChar ~
24231 \SpecialChar ~
24232 \SpecialChar ~
24233 \SpecialChar ~
24234 \SpecialChar ~
24235 \SpecialChar ~
24236 \SpecialChar ~
24237 \SpecialChar ~
24238 \SpecialChar ~
24239 \SpecialChar ~
24240 \SpecialChar ~
24241 case 5: ...
24242
24243 \newline
24244 \SpecialChar ~
24245 \SpecialChar ~
24246 \SpecialChar ~
24247 case 9: ...\SpecialChar ~
24248 \SpecialChar ~
24249 \SpecialChar ~
24250 \SpecialChar ~
24251 \SpecialChar ~
24252 \SpecialChar ~
24253 \SpecialChar ~
24254 \SpecialChar ~
24255 \SpecialChar ~
24256 \SpecialChar ~
24257 \SpecialChar ~
24258 \SpecialChar ~
24259 \SpecialChar ~
24260 \SpecialChar ~
24261 \SpecialChar ~
24262 \SpecialChar ~
24263 \SpecialChar ~
24264 \SpecialChar ~
24265 \SpecialChar ~
24266 \SpecialChar ~
24267 \SpecialChar ~
24268 \SpecialChar ~
24269 \SpecialChar ~
24270 \SpecialChar ~
24271 \SpecialChar ~
24272 \SpecialChar ~
24273 case 6: ...
24274
24275 \newline
24276 \SpecialChar ~
24277 \SpecialChar ~
24278 \SpecialChar ~
24279 case 10: ...\SpecialChar ~
24280 \SpecialChar ~
24281 \SpecialChar ~
24282 \SpecialChar ~
24283 \SpecialChar ~
24284 \SpecialChar ~
24285 \SpecialChar ~
24286 \SpecialChar ~
24287 \SpecialChar ~
24288 \SpecialChar ~
24289 \SpecialChar ~
24290 \SpecialChar ~
24291 \SpecialChar ~
24292 \SpecialChar ~
24293 \SpecialChar ~
24294 \SpecialChar ~
24295 \SpecialChar ~
24296 \SpecialChar ~
24297 \SpecialChar ~
24298 \SpecialChar ~
24299 \SpecialChar ~
24300 \SpecialChar ~
24301 \SpecialChar ~
24302 \SpecialChar ~
24303 \SpecialChar ~
24304 case 7: ...
24305
24306 \newline
24307 \SpecialChar ~
24308 \SpecialChar ~
24309 \SpecialChar ~
24310 case 11: ...\SpecialChar ~
24311 \SpecialChar ~
24312 \SpecialChar ~
24313 \SpecialChar ~
24314 \SpecialChar ~
24315 \SpecialChar ~
24316 \SpecialChar ~
24317 \SpecialChar ~
24318 \SpecialChar ~
24319 \SpecialChar ~
24320 \SpecialChar ~
24321 \SpecialChar ~
24322 \SpecialChar ~
24323 \SpecialChar ~
24324 \SpecialChar ~
24325 \SpecialChar ~
24326 \SpecialChar ~
24327 \SpecialChar ~
24328 \SpecialChar ~
24329 \SpecialChar ~
24330 \SpecialChar ~
24331 \SpecialChar ~
24332 \SpecialChar ~
24333 \SpecialChar ~
24334 \SpecialChar ~
24335 case 8: ...
24336
24337 \newline
24338 }\SpecialChar ~
24339 \SpecialChar ~
24340 \SpecialChar ~
24341 \SpecialChar ~
24342 \SpecialChar ~
24343 \SpecialChar ~
24344 \SpecialChar ~
24345 \SpecialChar ~
24346 \SpecialChar ~
24347 \SpecialChar ~
24348 \SpecialChar ~
24349 \SpecialChar ~
24350 \SpecialChar ~
24351 \SpecialChar ~
24352 \SpecialChar ~
24353 \SpecialChar ~
24354 \SpecialChar ~
24355 \SpecialChar ~
24356 \SpecialChar ~
24357 \SpecialChar ~
24358 \SpecialChar ~
24359 \SpecialChar ~
24360 \SpecialChar ~
24361 \SpecialChar ~
24362 \SpecialChar ~
24363 \SpecialChar ~
24364 \SpecialChar ~
24365 \SpecialChar ~
24366 \SpecialChar ~
24367 \SpecialChar ~
24368 \SpecialChar ~
24369 \SpecialChar ~
24370 \SpecialChar ~
24371 \SpecialChar ~
24372 \SpecialChar ~
24373 \SpecialChar ~
24374 }
24375 \layout Standard
24376
24377 Both the above switch statements will be implemented using a jump-table.
24378  The example to the right side is slightly more efficient as the check for
24379  the lower boundary of the jump-table is not needed.
24380 \end_deeper
24381 \layout Itemize
24382
24383 The number of case labels is not larger than supported by the target architectur
24384 e.
24385 \layout Itemize
24386
24387 If the case labels are not in numerical sequence ('gaps' between cases)
24388  SDCC checks whether a jump table with additionally inserted dummy cases
24389  is still attractive.
24390
24391 \layout Itemize
24392
24393 If the starting number is not zero and a check for the lower boundary of
24394  the jump-table can thus be eliminated SDCC might insert dummy cases 0,
24395  ...
24396  .
24397 \layout Standard
24398
24399 Switch statements which have large gaps in the numeric sequence or those
24400  that have too many case labels can be split into more than one switch statement
24401  for efficient code generation, e.g.:
24402 \layout Verse
24403
24404
24405 \family typewriter
24406 switch (i) {
24407 \newline
24408 \SpecialChar ~
24409 \SpecialChar ~
24410 case 1: ...
24411
24412 \newline
24413 \SpecialChar ~
24414 \SpecialChar ~
24415 case 2: ...
24416
24417 \newline
24418 \SpecialChar ~
24419 \SpecialChar ~
24420 case 3: ...
24421
24422 \newline
24423 \SpecialChar ~
24424 \SpecialChar ~
24425 case 4: ...
24426
24427 \newline
24428 \SpecialChar ~
24429 \SpecialChar ~
24430 case 5: ...
24431
24432 \newline
24433 \SpecialChar ~
24434 \SpecialChar ~
24435 case 6: ...
24436
24437 \newline
24438 \SpecialChar ~
24439 \SpecialChar ~
24440 case 7: ...
24441
24442 \newline
24443 \SpecialChar ~
24444 \SpecialChar ~
24445 case 101: ...
24446
24447 \newline
24448 \SpecialChar ~
24449 \SpecialChar ~
24450 case 102: ...
24451
24452 \newline
24453 \SpecialChar ~
24454 \SpecialChar ~
24455 case 103: ...
24456
24457 \newline
24458 \SpecialChar ~
24459 \SpecialChar ~
24460 case 104: ...
24461
24462 \newline
24463 \SpecialChar ~
24464 \SpecialChar ~
24465 case 105: ...
24466
24467 \newline
24468 \SpecialChar ~
24469 \SpecialChar ~
24470 case 106: ...
24471
24472 \newline
24473 \SpecialChar ~
24474 \SpecialChar ~
24475 case 107: ...
24476
24477 \newline
24478 }
24479 \layout Standard
24480
24481 If the above switch statement is broken down into two switch statements
24482 \layout Verse
24483
24484
24485 \family typewriter
24486 switch (i) {
24487 \newline
24488 \SpecialChar ~
24489 \SpecialChar ~
24490 case 1: ...
24491
24492 \newline
24493 \SpecialChar ~
24494 \SpecialChar ~
24495 case 2: ...
24496
24497 \newline
24498 \SpecialChar ~
24499 \SpecialChar ~
24500 case 3: ...
24501
24502 \newline
24503 \SpecialChar ~
24504 \SpecialChar ~
24505 case 4: ...
24506
24507 \newline
24508 \SpecialChar ~
24509 \SpecialChar ~
24510 case 5: ...
24511
24512 \newline
24513 \SpecialChar ~
24514 \SpecialChar ~
24515 case 6: ...
24516
24517 \newline
24518 \SpecialChar ~
24519 \SpecialChar ~
24520 case 7: ...
24521
24522 \newline
24523 }
24524 \layout Standard
24525
24526 and
24527 \layout Verse
24528
24529
24530 \family typewriter
24531 switch (i) {
24532 \newline
24533 \SpecialChar ~
24534 \SpecialChar ~
24535 case 101: ...
24536
24537 \newline
24538 \SpecialChar ~
24539 \SpecialChar ~
24540 case 102: ...
24541
24542 \newline
24543 \SpecialChar ~
24544 \SpecialChar ~
24545 case 103: ...
24546
24547 \newline
24548 \SpecialChar ~
24549 \SpecialChar ~
24550 case 104: ...
24551
24552 \newline
24553 \SpecialChar ~
24554 \SpecialChar ~
24555 case 105: ...
24556
24557 \newline
24558 \SpecialChar ~
24559 \SpecialChar ~
24560 case 106: ...
24561
24562 \newline
24563 \SpecialChar ~
24564 \SpecialChar ~
24565 case 107: ...
24566
24567 \newline
24568 }
24569 \layout Standard
24570
24571 then both the switch statements will be implemented using jump-tables whereas
24572  the unmodified switch statement will not be.
24573 \layout Comment
24574
24575 There might be reasons which SDCC cannot know about to either favour or
24576  not favour jump tables.
24577  If the target system has to be as quick for the last switch case as for
24578  the first (pro jump table), or if the switch argument is known to be zero
24579  in the majority of the cases (contra jump table).
24580 \layout Standard
24581
24582 The pragma nojtbound
24583 \begin_inset LatexCommand \index{\#pragma nojtbound}
24584
24585 \end_inset
24586
24587  can be used to turn off checking the
24588 \emph on
24589 j
24590 \emph default
24591 ump
24592 \emph on
24593 t
24594 \emph default
24595 able
24596 \emph on
24597 bound
24598 \emph default
24599 aries.
24600  It has no effect if a default label is supplied.
24601  Use of this pragma is dangerous: if the switch
24602 \begin_inset LatexCommand \index{switch statement}
24603
24604 \end_inset
24605
24606  argument is not matched by a case statement the processor will happily
24607  jump into Nirvana.
24608 \layout Subsection
24609
24610 Bit-shifting Operations
24611 \begin_inset LatexCommand \index{Bit shifting}
24612
24613 \end_inset
24614
24615 .
24616 \layout Standard
24617
24618 Bit shifting is one of the most frequently used operation in embedded programmin
24619 g.
24620  SDCC tries to implement bit-shift operations in the most efficient way
24621  possible, e.g.:
24622 \layout Verse
24623
24624
24625 \family typewriter
24626 unsigned char i;
24627 \newline
24628 ...
24629
24630 \newline
24631 i >>= 4;
24632 \newline
24633 ...
24634 \layout Standard
24635
24636 generates the following code:
24637 \layout Verse
24638
24639
24640 \family typewriter
24641 mov\SpecialChar ~
24642  a,_i
24643 \newline
24644 swap a
24645 \newline
24646 anl\SpecialChar ~
24647  a,#0x0f
24648 \newline
24649 mov\SpecialChar ~
24650  _i,a
24651 \layout Standard
24652
24653 In general SDCC will never setup a loop if the shift count is known.
24654  Another example:
24655 \layout Verse
24656
24657
24658 \family typewriter
24659 unsigned int i;
24660 \newline
24661 ...
24662
24663 \newline
24664 i >>= 9;
24665 \newline
24666 ...
24667 \layout Standard
24668
24669 will generate:
24670 \layout Verse
24671
24672
24673 \family typewriter
24674 mov\SpecialChar ~
24675 \SpecialChar ~
24676 a,(_i + 1)
24677 \newline
24678 mov\SpecialChar ~
24679 \SpecialChar ~
24680 (_i + 1),#0x00
24681 \newline
24682 clr\SpecialChar ~
24683 \SpecialChar ~
24684 c
24685 \newline
24686 rrc\SpecialChar ~
24687 \SpecialChar ~
24688 a
24689 \newline
24690 mov\SpecialChar ~
24691 \SpecialChar ~
24692 _i,a
24693 \layout Subsection
24694
24695 Bit-rotation
24696 \begin_inset LatexCommand \index{Bit rotation}
24697
24698 \end_inset
24699
24700
24701 \layout Standard
24702
24703 A special case of the bit-shift operation is bit rotation
24704 \begin_inset LatexCommand \index{rotating bits}
24705
24706 \end_inset
24707
24708 , SDCC recognizes the following expression to be a left bit-rotation:
24709 \layout Verse
24710
24711
24712 \family typewriter
24713 \series bold
24714 unsigned
24715 \series default
24716 \SpecialChar ~
24717 \SpecialChar ~
24718 char i;\SpecialChar ~
24719 \SpecialChar ~
24720 \SpecialChar ~
24721 \SpecialChar ~
24722 \SpecialChar ~
24723 \SpecialChar ~
24724 \SpecialChar ~
24725 \SpecialChar ~
24726 \SpecialChar ~
24727 \SpecialChar ~
24728 \SpecialChar ~
24729 /* unsigned is needed for rotation */
24730 \newline
24731 ...
24732
24733 \newline
24734 i = ((i << 1) | (i >> 7));
24735 \family default
24736
24737 \newline
24738
24739 \family typewriter
24740 ...
24741 \layout Standard
24742
24743 will generate the following code:
24744 \layout Verse
24745
24746
24747 \family typewriter
24748 mov\SpecialChar ~
24749 \SpecialChar ~
24750 a,_i
24751 \newline
24752 rl\SpecialChar ~
24753 \SpecialChar ~
24754 \SpecialChar ~
24755 a
24756 \newline
24757 mov\SpecialChar ~
24758 \SpecialChar ~
24759 _i,a
24760 \layout Standard
24761
24762 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
24763 ns of this case will also be recognized as bit-rotation, i.e.:
24764 \layout Verse
24765
24766
24767 \family typewriter
24768 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
24769 \layout Subsection
24770
24771 Nibble and Byte Swapping
24772 \layout Standard
24773
24774 Other special cases of the bit-shift operations are nibble or byte swapping
24775 \begin_inset LatexCommand \index{swapping nibbles/bytes}
24776
24777 \end_inset
24778
24779 , SDCC recognizes the following expressions:
24780 \layout Verse
24781
24782
24783 \family typewriter
24784 \series bold
24785 unsigned
24786 \series default
24787 \SpecialChar ~
24788 \SpecialChar ~
24789 char i;
24790 \newline
24791
24792 \series bold
24793 unsigned
24794 \series default
24795 \SpecialChar ~
24796 \SpecialChar ~
24797 int j;
24798 \newline
24799 ...
24800
24801 \newline
24802 i = ((i << 4) | (i >> 4));
24803 \family default
24804
24805 \newline
24806
24807 \family typewriter
24808 j = ((j << 8) | (j >> 8));
24809 \layout Standard
24810
24811 and generates a swap instruction for the nibble swapping
24812 \begin_inset LatexCommand \index{Nibble swapping}
24813
24814 \end_inset
24815
24816  or move instructions for the byte swapping
24817 \begin_inset LatexCommand \index{Byte swapping}
24818
24819 \end_inset
24820
24821 .
24822  The
24823 \begin_inset Quotes sld
24824 \end_inset
24825
24826 j
24827 \begin_inset Quotes srd
24828 \end_inset
24829
24830  example can be used to convert from little to big-endian or vice versa.
24831  If you want to change the endianness of a
24832 \emph on
24833 signed
24834 \emph default
24835  integer you have to cast to
24836 \family typewriter
24837 (unsigned int)
24838 \family default
24839  first.
24840 \layout Standard
24841
24842 Note that SDCC stores numbers in little-endian
24843 \begin_inset Foot
24844 collapsed false
24845
24846 \layout Standard
24847
24848 Usually 8-bit processors don't care much about endianness.
24849  This is not the case for the standard 8051 which only has an instruction
24850  to increment its
24851 \emph on
24852 dptr
24853 \emph default
24854
24855 \begin_inset LatexCommand \index{DPTR}
24856
24857 \end_inset
24858
24859 -datapointer
24860 \emph on
24861
24862 \emph default
24863 so little-endian is the more efficient byte order.
24864 \end_inset
24865
24866
24867 \begin_inset LatexCommand \index{little-endian}
24868
24869 \end_inset
24870
24871
24872 \begin_inset LatexCommand \index{Endianness}
24873
24874 \end_inset
24875
24876  format (i.e.
24877  lowest order first).
24878 \layout Subsection
24879
24880 Highest Order Bit
24881 \begin_inset LatexCommand \index{Highest Order Bit}
24882
24883 \end_inset
24884
24885  / Any Order Bit
24886 \begin_inset LatexCommand \index{Any Order Bit}
24887
24888 \end_inset
24889
24890
24891 \layout Standard
24892
24893 It is frequently required to obtain the highest order bit of an integral
24894  type (long, int, short or char types).
24895  Also obtaining any other order bit is not uncommon.
24896  SDCC recognizes the following expressions to yield the highest order bit
24897  and generates optimized code for it, e.g.:
24898 \layout Verse
24899
24900
24901 \family typewriter
24902 unsigned int gint;
24903 \newline
24904
24905 \newline
24906 foo () {
24907 \newline
24908 \SpecialChar ~
24909 \SpecialChar ~
24910 unsigned char hob1, aob1;
24911 \newline
24912 \SpecialChar ~
24913 \SpecialChar ~
24914 bit hob2, hob3, aob2, aob3;
24915 \newline
24916 \SpecialChar ~
24917 \SpecialChar ~
24918 ...
24919
24920 \newline
24921 \SpecialChar ~
24922 \SpecialChar ~
24923 hob1 = (gint >> 15) & 1;
24924 \newline
24925 \SpecialChar ~
24926 \SpecialChar ~
24927 hob2 = (gint >> 15) & 1;
24928 \newline
24929 \SpecialChar ~
24930 \SpecialChar ~
24931 hob3 = gint & 0x8000;
24932 \newline
24933 \SpecialChar ~
24934 \SpecialChar ~
24935 aob1 = (gint >> 9) & 1;
24936 \newline
24937 \SpecialChar ~
24938 \SpecialChar ~
24939 aob2 = (gint >> 8) & 1;
24940 \newline
24941 \SpecialChar ~
24942 \SpecialChar ~
24943 aob3 = gint & 0x0800;
24944 \newline
24945 \SpecialChar ~
24946 \SpecialChar ~
24947 ..
24948
24949 \newline
24950 }
24951 \layout Standard
24952
24953 will generate the following code:
24954 \layout Verse
24955
24956
24957 \family typewriter
24958 \SpecialChar ~
24959 \SpecialChar ~
24960 \SpecialChar ~
24961 \SpecialChar ~
24962 \SpecialChar ~
24963 \SpecialChar ~
24964 \SpecialChar ~
24965 \SpecialChar ~
24966 \SpecialChar ~
24967 \SpecialChar ~
24968 \SpecialChar ~
24969 \SpecialChar ~
24970 \SpecialChar ~
24971 \SpecialChar ~
24972 \SpecialChar ~
24973 \SpecialChar ~
24974 \SpecialChar ~
24975 \SpecialChar ~
24976 \SpecialChar ~
24977 \SpecialChar ~
24978 \SpecialChar ~
24979 \SpecialChar ~
24980 \SpecialChar ~
24981 \SpecialChar ~
24982 \SpecialChar ~
24983  61 ;\SpecialChar ~
24984  hob.c 7
24985 \newline
24986 000A E5*01\SpecialChar ~
24987 \SpecialChar ~
24988 \SpecialChar ~
24989 \SpecialChar ~
24990 \SpecialChar ~
24991 \SpecialChar ~
24992 \SpecialChar ~
24993 \SpecialChar ~
24994 \SpecialChar ~
24995 \SpecialChar ~
24996 \SpecialChar ~
24997 \SpecialChar ~
24998 \SpecialChar ~
24999 \SpecialChar ~
25000 \SpecialChar ~
25001  62\SpecialChar ~
25002 \SpecialChar ~
25003 \SpecialChar ~
25004 \SpecialChar ~
25005 \SpecialChar ~
25006 \SpecialChar ~
25007 \SpecialChar ~
25008 \SpecialChar ~
25009  mov\SpecialChar ~
25010 \SpecialChar ~
25011  a,(_gint + 1)
25012 \newline
25013 000C 23\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 \SpecialChar ~
25030 \SpecialChar ~
25031  63\SpecialChar ~
25032 \SpecialChar ~
25033 \SpecialChar ~
25034 \SpecialChar ~
25035 \SpecialChar ~
25036 \SpecialChar ~
25037 \SpecialChar ~
25038 \SpecialChar ~
25039  rl\SpecialChar ~
25040 \SpecialChar ~
25041 \SpecialChar ~
25042  a
25043 \newline
25044 000D 54 01\SpecialChar ~
25045 \SpecialChar ~
25046 \SpecialChar ~
25047 \SpecialChar ~
25048 \SpecialChar ~
25049 \SpecialChar ~
25050 \SpecialChar ~
25051 \SpecialChar ~
25052 \SpecialChar ~
25053 \SpecialChar ~
25054 \SpecialChar ~
25055 \SpecialChar ~
25056 \SpecialChar ~
25057 \SpecialChar ~
25058 \SpecialChar ~
25059  64\SpecialChar ~
25060 \SpecialChar ~
25061 \SpecialChar ~
25062 \SpecialChar ~
25063 \SpecialChar ~
25064 \SpecialChar ~
25065 \SpecialChar ~
25066 \SpecialChar ~
25067  anl\SpecialChar ~
25068 \SpecialChar ~
25069  a,#0x01
25070 \newline
25071 000F F5*02\SpecialChar ~
25072 \SpecialChar ~
25073 \SpecialChar ~
25074 \SpecialChar ~
25075 \SpecialChar ~
25076 \SpecialChar ~
25077 \SpecialChar ~
25078 \SpecialChar ~
25079 \SpecialChar ~
25080 \SpecialChar ~
25081 \SpecialChar ~
25082 \SpecialChar ~
25083 \SpecialChar ~
25084 \SpecialChar ~
25085 \SpecialChar ~
25086  65\SpecialChar ~
25087 \SpecialChar ~
25088 \SpecialChar ~
25089 \SpecialChar ~
25090 \SpecialChar ~
25091 \SpecialChar ~
25092 \SpecialChar ~
25093 \SpecialChar ~
25094  mov\SpecialChar ~
25095 \SpecialChar ~
25096  _foo_hob1_1_1,a
25097 \newline
25098 \SpecialChar ~
25099 \SpecialChar ~
25100 \SpecialChar ~
25101 \SpecialChar ~
25102 \SpecialChar ~
25103 \SpecialChar ~
25104 \SpecialChar ~
25105 \SpecialChar ~
25106 \SpecialChar ~
25107 \SpecialChar ~
25108 \SpecialChar ~
25109 \SpecialChar ~
25110 \SpecialChar ~
25111 \SpecialChar ~
25112 \SpecialChar ~
25113 \SpecialChar ~
25114 \SpecialChar ~
25115 \SpecialChar ~
25116 \SpecialChar ~
25117 \SpecialChar ~
25118 \SpecialChar ~
25119 \SpecialChar ~
25120 \SpecialChar ~
25121 \SpecialChar ~
25122 \SpecialChar ~
25123  66 ;\SpecialChar ~
25124  hob.c 8
25125 \newline
25126 0011 E5*01\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  67\SpecialChar ~
25142 \SpecialChar ~
25143 \SpecialChar ~
25144 \SpecialChar ~
25145 \SpecialChar ~
25146 \SpecialChar ~
25147 \SpecialChar ~
25148 \SpecialChar ~
25149  mov\SpecialChar ~
25150 \SpecialChar ~
25151  a,(_gint + 1)
25152 \newline
25153 0013 33\SpecialChar ~
25154 \SpecialChar ~
25155 \SpecialChar ~
25156 \SpecialChar ~
25157 \SpecialChar ~
25158 \SpecialChar ~
25159 \SpecialChar ~
25160 \SpecialChar ~
25161 \SpecialChar ~
25162 \SpecialChar ~
25163 \SpecialChar ~
25164 \SpecialChar ~
25165 \SpecialChar ~
25166 \SpecialChar ~
25167 \SpecialChar ~
25168 \SpecialChar ~
25169 \SpecialChar ~
25170 \SpecialChar ~
25171  68\SpecialChar ~
25172 \SpecialChar ~
25173 \SpecialChar ~
25174 \SpecialChar ~
25175 \SpecialChar ~
25176 \SpecialChar ~
25177 \SpecialChar ~
25178 \SpecialChar ~
25179  rlc\SpecialChar ~
25180 \SpecialChar ~
25181  a
25182 \newline
25183 0014 92*00\SpecialChar ~
25184 \SpecialChar ~
25185 \SpecialChar ~
25186 \SpecialChar ~
25187 \SpecialChar ~
25188 \SpecialChar ~
25189 \SpecialChar ~
25190 \SpecialChar ~
25191 \SpecialChar ~
25192 \SpecialChar ~
25193 \SpecialChar ~
25194 \SpecialChar ~
25195 \SpecialChar ~
25196 \SpecialChar ~
25197 \SpecialChar ~
25198  69\SpecialChar ~
25199 \SpecialChar ~
25200 \SpecialChar ~
25201 \SpecialChar ~
25202 \SpecialChar ~
25203 \SpecialChar ~
25204 \SpecialChar ~
25205 \SpecialChar ~
25206  mov\SpecialChar ~
25207 \SpecialChar ~
25208  _foo_hob2_1_1,c
25209 \newline
25210 \SpecialChar ~
25211 \SpecialChar ~
25212 \SpecialChar ~
25213 \SpecialChar ~
25214 \SpecialChar ~
25215 \SpecialChar ~
25216 \SpecialChar ~
25217 \SpecialChar ~
25218 \SpecialChar ~
25219 \SpecialChar ~
25220 \SpecialChar ~
25221 \SpecialChar ~
25222 \SpecialChar ~
25223 \SpecialChar ~
25224 \SpecialChar ~
25225 \SpecialChar ~
25226 \SpecialChar ~
25227 \SpecialChar ~
25228 \SpecialChar ~
25229 \SpecialChar ~
25230 \SpecialChar ~
25231 \SpecialChar ~
25232 \SpecialChar ~
25233 \SpecialChar ~
25234 \SpecialChar ~
25235  66 ;\SpecialChar ~
25236  hob.c 9
25237 \newline
25238 0016 E5*01\SpecialChar ~
25239 \SpecialChar ~
25240 \SpecialChar ~
25241 \SpecialChar ~
25242 \SpecialChar ~
25243 \SpecialChar ~
25244 \SpecialChar ~
25245 \SpecialChar ~
25246 \SpecialChar ~
25247 \SpecialChar ~
25248 \SpecialChar ~
25249 \SpecialChar ~
25250 \SpecialChar ~
25251 \SpecialChar ~
25252 \SpecialChar ~
25253  67\SpecialChar ~
25254 \SpecialChar ~
25255 \SpecialChar ~
25256 \SpecialChar ~
25257 \SpecialChar ~
25258 \SpecialChar ~
25259 \SpecialChar ~
25260 \SpecialChar ~
25261  mov\SpecialChar ~
25262 \SpecialChar ~
25263  a,(_gint + 1)
25264 \newline
25265 0018 33\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 \SpecialChar ~
25282 \SpecialChar ~
25283  68\SpecialChar ~
25284 \SpecialChar ~
25285 \SpecialChar ~
25286 \SpecialChar ~
25287 \SpecialChar ~
25288 \SpecialChar ~
25289 \SpecialChar ~
25290 \SpecialChar ~
25291  rlc\SpecialChar ~
25292 \SpecialChar ~
25293  a
25294 \newline
25295 0019 92*01\SpecialChar ~
25296 \SpecialChar ~
25297 \SpecialChar ~
25298 \SpecialChar ~
25299 \SpecialChar ~
25300 \SpecialChar ~
25301 \SpecialChar ~
25302 \SpecialChar ~
25303 \SpecialChar ~
25304 \SpecialChar ~
25305 \SpecialChar ~
25306 \SpecialChar ~
25307 \SpecialChar ~
25308 \SpecialChar ~
25309 \SpecialChar ~
25310  69\SpecialChar ~
25311 \SpecialChar ~
25312 \SpecialChar ~
25313 \SpecialChar ~
25314 \SpecialChar ~
25315 \SpecialChar ~
25316 \SpecialChar ~
25317 \SpecialChar ~
25318  mov\SpecialChar ~
25319 \SpecialChar ~
25320  _foo_hob3_1_1,c
25321 \newline
25322 \SpecialChar ~
25323 \SpecialChar ~
25324 \SpecialChar ~
25325 \SpecialChar ~
25326 \SpecialChar ~
25327 \SpecialChar ~
25328 \SpecialChar ~
25329 \SpecialChar ~
25330 \SpecialChar ~
25331 \SpecialChar ~
25332 \SpecialChar ~
25333 \SpecialChar ~
25334 \SpecialChar ~
25335 \SpecialChar ~
25336 \SpecialChar ~
25337 \SpecialChar ~
25338 \SpecialChar ~
25339 \SpecialChar ~
25340 \SpecialChar ~
25341 \SpecialChar ~
25342 \SpecialChar ~
25343 \SpecialChar ~
25344 \SpecialChar ~
25345 \SpecialChar ~
25346 \SpecialChar ~
25347  70 ;\SpecialChar ~
25348  hob.c 10
25349 \newline
25350 001B E5*01\SpecialChar ~
25351 \SpecialChar ~
25352 \SpecialChar ~
25353 \SpecialChar ~
25354 \SpecialChar ~
25355 \SpecialChar ~
25356 \SpecialChar ~
25357 \SpecialChar ~
25358 \SpecialChar ~
25359 \SpecialChar ~
25360 \SpecialChar ~
25361 \SpecialChar ~
25362 \SpecialChar ~
25363 \SpecialChar ~
25364 \SpecialChar ~
25365  71\SpecialChar ~
25366 \SpecialChar ~
25367 \SpecialChar ~
25368 \SpecialChar ~
25369 \SpecialChar ~
25370 \SpecialChar ~
25371 \SpecialChar ~
25372 \SpecialChar ~
25373  mov\SpecialChar ~
25374 \SpecialChar ~
25375  a,(_gint + 1)
25376 \newline
25377 001D 03\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 \SpecialChar ~
25394 \SpecialChar ~
25395  72\SpecialChar ~
25396 \SpecialChar ~
25397 \SpecialChar ~
25398 \SpecialChar ~
25399 \SpecialChar ~
25400 \SpecialChar ~
25401 \SpecialChar ~
25402 \SpecialChar ~
25403  rr\SpecialChar ~
25404 \SpecialChar ~
25405 \SpecialChar ~
25406  a
25407 \newline
25408 001E 54 01\SpecialChar ~
25409 \SpecialChar ~
25410 \SpecialChar ~
25411 \SpecialChar ~
25412 \SpecialChar ~
25413 \SpecialChar ~
25414 \SpecialChar ~
25415 \SpecialChar ~
25416 \SpecialChar ~
25417 \SpecialChar ~
25418 \SpecialChar ~
25419 \SpecialChar ~
25420 \SpecialChar ~
25421 \SpecialChar ~
25422 \SpecialChar ~
25423  73\SpecialChar ~
25424 \SpecialChar ~
25425 \SpecialChar ~
25426 \SpecialChar ~
25427 \SpecialChar ~
25428 \SpecialChar ~
25429 \SpecialChar ~
25430 \SpecialChar ~
25431  anl\SpecialChar ~
25432 \SpecialChar ~
25433  a,#0x01
25434 \newline
25435 0020 F5*03\SpecialChar ~
25436 \SpecialChar ~
25437 \SpecialChar ~
25438 \SpecialChar ~
25439 \SpecialChar ~
25440 \SpecialChar ~
25441 \SpecialChar ~
25442 \SpecialChar ~
25443 \SpecialChar ~
25444 \SpecialChar ~
25445 \SpecialChar ~
25446 \SpecialChar ~
25447 \SpecialChar ~
25448 \SpecialChar ~
25449 \SpecialChar ~
25450  74\SpecialChar ~
25451 \SpecialChar ~
25452 \SpecialChar ~
25453 \SpecialChar ~
25454 \SpecialChar ~
25455 \SpecialChar ~
25456 \SpecialChar ~
25457 \SpecialChar ~
25458  mov\SpecialChar ~
25459 \SpecialChar ~
25460  _foo_aob1_1_1,a
25461 \newline
25462 \SpecialChar ~
25463 \SpecialChar ~
25464 \SpecialChar ~
25465 \SpecialChar ~
25466 \SpecialChar ~
25467 \SpecialChar ~
25468 \SpecialChar ~
25469 \SpecialChar ~
25470 \SpecialChar ~
25471 \SpecialChar ~
25472 \SpecialChar ~
25473 \SpecialChar ~
25474 \SpecialChar ~
25475 \SpecialChar ~
25476 \SpecialChar ~
25477 \SpecialChar ~
25478 \SpecialChar ~
25479 \SpecialChar ~
25480 \SpecialChar ~
25481 \SpecialChar ~
25482 \SpecialChar ~
25483 \SpecialChar ~
25484 \SpecialChar ~
25485 \SpecialChar ~
25486 \SpecialChar ~
25487  75 ;\SpecialChar ~
25488  hob.c 11
25489 \newline
25490 0022 E5*01\SpecialChar ~
25491 \SpecialChar ~
25492 \SpecialChar ~
25493 \SpecialChar ~
25494 \SpecialChar ~
25495 \SpecialChar ~
25496 \SpecialChar ~
25497 \SpecialChar ~
25498 \SpecialChar ~
25499 \SpecialChar ~
25500 \SpecialChar ~
25501 \SpecialChar ~
25502 \SpecialChar ~
25503 \SpecialChar ~
25504 \SpecialChar ~
25505  76\SpecialChar ~
25506 \SpecialChar ~
25507 \SpecialChar ~
25508 \SpecialChar ~
25509 \SpecialChar ~
25510 \SpecialChar ~
25511 \SpecialChar ~
25512 \SpecialChar ~
25513  mov\SpecialChar ~
25514 \SpecialChar ~
25515  a,(_gint + 1)
25516 \newline
25517 0024 13\SpecialChar ~
25518 \SpecialChar ~
25519 \SpecialChar ~
25520 \SpecialChar ~
25521 \SpecialChar ~
25522 \SpecialChar ~
25523 \SpecialChar ~
25524 \SpecialChar ~
25525 \SpecialChar ~
25526 \SpecialChar ~
25527 \SpecialChar ~
25528 \SpecialChar ~
25529 \SpecialChar ~
25530 \SpecialChar ~
25531 \SpecialChar ~
25532 \SpecialChar ~
25533 \SpecialChar ~
25534 \SpecialChar ~
25535  77\SpecialChar ~
25536 \SpecialChar ~
25537 \SpecialChar ~
25538 \SpecialChar ~
25539 \SpecialChar ~
25540 \SpecialChar ~
25541 \SpecialChar ~
25542 \SpecialChar ~
25543  rrc\SpecialChar ~
25544 \SpecialChar ~
25545  a
25546 \newline
25547 0025 92*02\SpecialChar ~
25548 \SpecialChar ~
25549 \SpecialChar ~
25550 \SpecialChar ~
25551 \SpecialChar ~
25552 \SpecialChar ~
25553 \SpecialChar ~
25554 \SpecialChar ~
25555 \SpecialChar ~
25556 \SpecialChar ~
25557 \SpecialChar ~
25558 \SpecialChar ~
25559 \SpecialChar ~
25560 \SpecialChar ~
25561 \SpecialChar ~
25562  78\SpecialChar ~
25563 \SpecialChar ~
25564 \SpecialChar ~
25565 \SpecialChar ~
25566 \SpecialChar ~
25567 \SpecialChar ~
25568 \SpecialChar ~
25569 \SpecialChar ~
25570  mov\SpecialChar ~
25571 \SpecialChar ~
25572  _foo_aob2_1_1,c
25573 \newline
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 \SpecialChar ~
25594 \SpecialChar ~
25595 \SpecialChar ~
25596 \SpecialChar ~
25597 \SpecialChar ~
25598 \SpecialChar ~
25599  79 ;\SpecialChar ~
25600  hob.c 12
25601 \newline
25602 0027 E5*01\SpecialChar ~
25603 \SpecialChar ~
25604 \SpecialChar ~
25605 \SpecialChar ~
25606 \SpecialChar ~
25607 \SpecialChar ~
25608 \SpecialChar ~
25609 \SpecialChar ~
25610 \SpecialChar ~
25611 \SpecialChar ~
25612 \SpecialChar ~
25613 \SpecialChar ~
25614 \SpecialChar ~
25615 \SpecialChar ~
25616 \SpecialChar ~
25617  80\SpecialChar ~
25618 \SpecialChar ~
25619 \SpecialChar ~
25620 \SpecialChar ~
25621 \SpecialChar ~
25622 \SpecialChar ~
25623 \SpecialChar ~
25624 \SpecialChar ~
25625  mov\SpecialChar ~
25626 \SpecialChar ~
25627  a,(_gint + 1)
25628 \newline
25629 0029 A2 E3\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  81\SpecialChar ~
25645 \SpecialChar ~
25646 \SpecialChar ~
25647 \SpecialChar ~
25648 \SpecialChar ~
25649 \SpecialChar ~
25650 \SpecialChar ~
25651 \SpecialChar ~
25652  mov\SpecialChar ~
25653 \SpecialChar ~
25654  c,acc[3]
25655 \newline
25656 002B 92*03\SpecialChar ~
25657 \SpecialChar ~
25658 \SpecialChar ~
25659 \SpecialChar ~
25660 \SpecialChar ~
25661 \SpecialChar ~
25662 \SpecialChar ~
25663 \SpecialChar ~
25664 \SpecialChar ~
25665 \SpecialChar ~
25666 \SpecialChar ~
25667 \SpecialChar ~
25668 \SpecialChar ~
25669 \SpecialChar ~
25670 \SpecialChar ~
25671  82\SpecialChar ~
25672 \SpecialChar ~
25673 \SpecialChar ~
25674 \SpecialChar ~
25675 \SpecialChar ~
25676 \SpecialChar ~
25677 \SpecialChar ~
25678 \SpecialChar ~
25679  mov\SpecialChar ~
25680 \SpecialChar ~
25681  _foo_aob3_1_1,c
25682 \layout Standard
25683
25684 Other variations of these cases however will
25685 \emph on
25686 not
25687 \emph default
25688  be recognized.
25689  They are standard C expressions, so I heartily recommend these be the only
25690  way to get the highest order bit, (it is portable).
25691  Of course it will be recognized even if it is embedded in other expressions,
25692  e.g.:
25693 \layout Verse
25694
25695
25696 \family typewriter
25697 xyz = gint + ((gint >> 15) & 1);
25698 \layout Standard
25699
25700 will still be recognized.
25701 \layout Subsection
25702
25703 Higher Order Byte
25704 \begin_inset LatexCommand \index{Higher Order Byte}
25705
25706 \end_inset
25707
25708  / Higher Order Word
25709 \begin_inset LatexCommand \index{Higher Order Word}
25710
25711 \end_inset
25712
25713
25714 \layout Standard
25715
25716 It is also frequently required to obtain a higher order byte or word of
25717  a larger integral type (long, int or short types).
25718  SDCC recognizes the following expressions to yield the higher order byte
25719  or word and generates optimized code for it, e.g.:
25720 \layout Verse
25721
25722
25723 \family typewriter
25724 unsigned int gint;
25725 \newline
25726 unsigned long int glong;
25727 \newline
25728
25729 \newline
25730 foo () {
25731 \newline
25732 \SpecialChar ~
25733 \SpecialChar ~
25734 unsigned char hob1, hob2;
25735 \newline
25736 \SpecialChar ~
25737 \SpecialChar ~
25738 unsigned int how1, how2;
25739 \newline
25740 \SpecialChar ~
25741 \SpecialChar ~
25742 ...
25743
25744 \newline
25745 \SpecialChar ~
25746 \SpecialChar ~
25747 hob1 = (gint >> 8) & 0xFF;
25748 \newline
25749 \SpecialChar ~
25750 \SpecialChar ~
25751 hob2 = glong >> 24;
25752 \newline
25753 \SpecialChar ~
25754 \SpecialChar ~
25755 how1 = (glong >> 16) & 0xFFFF;
25756 \newline
25757 \SpecialChar ~
25758 \SpecialChar ~
25759 how2 = glong >> 8;
25760 \newline
25761 \SpecialChar ~
25762 \SpecialChar ~
25763 ..
25764
25765 \newline
25766 }
25767 \layout Standard
25768
25769 will generate the following code:
25770 \layout Verse
25771
25772
25773 \family typewriter
25774 \SpecialChar ~
25775 \SpecialChar ~
25776 \SpecialChar ~
25777 \SpecialChar ~
25778 \SpecialChar ~
25779 \SpecialChar ~
25780 \SpecialChar ~
25781 \SpecialChar ~
25782 \SpecialChar ~
25783 \SpecialChar ~
25784 \SpecialChar ~
25785 \SpecialChar ~
25786 \SpecialChar ~
25787 \SpecialChar ~
25788 \SpecialChar ~
25789 \SpecialChar ~
25790 \SpecialChar ~
25791 \SpecialChar ~
25792 \SpecialChar ~
25793 \SpecialChar ~
25794 \SpecialChar ~
25795 \SpecialChar ~
25796 \SpecialChar ~
25797 \SpecialChar ~
25798 \SpecialChar ~
25799  91 ;\SpecialChar ~
25800  hob.c 15
25801 \newline
25802 0037 85*01*06\SpecialChar ~
25803 \SpecialChar ~
25804 \SpecialChar ~
25805 \SpecialChar ~
25806 \SpecialChar ~
25807 \SpecialChar ~
25808 \SpecialChar ~
25809 \SpecialChar ~
25810 \SpecialChar ~
25811 \SpecialChar ~
25812 \SpecialChar ~
25813 \SpecialChar ~
25814  92\SpecialChar ~
25815 \SpecialChar ~
25816 \SpecialChar ~
25817 \SpecialChar ~
25818 \SpecialChar ~
25819 \SpecialChar ~
25820 \SpecialChar ~
25821 \SpecialChar ~
25822  mov\SpecialChar ~
25823 \SpecialChar ~
25824  _foo_hob1_1_1,(_gint + 1)
25825 \newline
25826 \SpecialChar ~
25827 \SpecialChar ~
25828 \SpecialChar ~
25829 \SpecialChar ~
25830 \SpecialChar ~
25831 \SpecialChar ~
25832 \SpecialChar ~
25833 \SpecialChar ~
25834 \SpecialChar ~
25835 \SpecialChar ~
25836 \SpecialChar ~
25837 \SpecialChar ~
25838 \SpecialChar ~
25839 \SpecialChar ~
25840 \SpecialChar ~
25841 \SpecialChar ~
25842 \SpecialChar ~
25843 \SpecialChar ~
25844 \SpecialChar ~
25845 \SpecialChar ~
25846 \SpecialChar ~
25847 \SpecialChar ~
25848 \SpecialChar ~
25849 \SpecialChar ~
25850 \SpecialChar ~
25851  93 ;\SpecialChar ~
25852  hob.c 16
25853 \newline
25854 003A 85*05*07\SpecialChar ~
25855 \SpecialChar ~
25856 \SpecialChar ~
25857 \SpecialChar ~
25858 \SpecialChar ~
25859 \SpecialChar ~
25860 \SpecialChar ~
25861 \SpecialChar ~
25862 \SpecialChar ~
25863 \SpecialChar ~
25864 \SpecialChar ~
25865 \SpecialChar ~
25866  94\SpecialChar ~
25867 \SpecialChar ~
25868 \SpecialChar ~
25869 \SpecialChar ~
25870 \SpecialChar ~
25871 \SpecialChar ~
25872 \SpecialChar ~
25873 \SpecialChar ~
25874  mov\SpecialChar ~
25875 \SpecialChar ~
25876  _foo_hob2_1_1,(_glong + 3)
25877 \newline
25878 \SpecialChar ~
25879 \SpecialChar ~
25880 \SpecialChar ~
25881 \SpecialChar ~
25882 \SpecialChar ~
25883 \SpecialChar ~
25884 \SpecialChar ~
25885 \SpecialChar ~
25886 \SpecialChar ~
25887 \SpecialChar ~
25888 \SpecialChar ~
25889 \SpecialChar ~
25890 \SpecialChar ~
25891 \SpecialChar ~
25892 \SpecialChar ~
25893 \SpecialChar ~
25894 \SpecialChar ~
25895 \SpecialChar ~
25896 \SpecialChar ~
25897 \SpecialChar ~
25898 \SpecialChar ~
25899 \SpecialChar ~
25900 \SpecialChar ~
25901 \SpecialChar ~
25902 \SpecialChar ~
25903  95 ;\SpecialChar ~
25904  hob.c 17
25905 \newline
25906 003D 85*04*08\SpecialChar ~
25907 \SpecialChar ~
25908 \SpecialChar ~
25909 \SpecialChar ~
25910 \SpecialChar ~
25911 \SpecialChar ~
25912 \SpecialChar ~
25913 \SpecialChar ~
25914 \SpecialChar ~
25915 \SpecialChar ~
25916 \SpecialChar ~
25917 \SpecialChar ~
25918  96\SpecialChar ~
25919 \SpecialChar ~
25920 \SpecialChar ~
25921 \SpecialChar ~
25922 \SpecialChar ~
25923 \SpecialChar ~
25924 \SpecialChar ~
25925 \SpecialChar ~
25926  mov\SpecialChar ~
25927 \SpecialChar ~
25928  _foo_how1_1_1,(_glong + 2)
25929 \newline
25930 0040 85*05*09\SpecialChar ~
25931 \SpecialChar ~
25932 \SpecialChar ~
25933 \SpecialChar ~
25934 \SpecialChar ~
25935 \SpecialChar ~
25936 \SpecialChar ~
25937 \SpecialChar ~
25938 \SpecialChar ~
25939 \SpecialChar ~
25940 \SpecialChar ~
25941 \SpecialChar ~
25942  97\SpecialChar ~
25943 \SpecialChar ~
25944 \SpecialChar ~
25945 \SpecialChar ~
25946 \SpecialChar ~
25947 \SpecialChar ~
25948 \SpecialChar ~
25949 \SpecialChar ~
25950  mov\SpecialChar ~
25951 \SpecialChar ~
25952  (_foo_how1_1_1 + 1),(_glong + 3)
25953 \newline
25954 0043 85*03*0A\SpecialChar ~
25955 \SpecialChar ~
25956 \SpecialChar ~
25957 \SpecialChar ~
25958 \SpecialChar ~
25959 \SpecialChar ~
25960 \SpecialChar ~
25961 \SpecialChar ~
25962 \SpecialChar ~
25963 \SpecialChar ~
25964 \SpecialChar ~
25965 \SpecialChar ~
25966  98\SpecialChar ~
25967 \SpecialChar ~
25968 \SpecialChar ~
25969 \SpecialChar ~
25970 \SpecialChar ~
25971 \SpecialChar ~
25972 \SpecialChar ~
25973 \SpecialChar ~
25974  mov\SpecialChar ~
25975 \SpecialChar ~
25976  _foo_how2_1_1,(_glong + 1)
25977 \newline
25978 0046 85*04*0B\SpecialChar ~
25979 \SpecialChar ~
25980 \SpecialChar ~
25981 \SpecialChar ~
25982 \SpecialChar ~
25983 \SpecialChar ~
25984 \SpecialChar ~
25985 \SpecialChar ~
25986 \SpecialChar ~
25987 \SpecialChar ~
25988 \SpecialChar ~
25989 \SpecialChar ~
25990  99\SpecialChar ~
25991 \SpecialChar ~
25992 \SpecialChar ~
25993 \SpecialChar ~
25994 \SpecialChar ~
25995 \SpecialChar ~
25996 \SpecialChar ~
25997 \SpecialChar ~
25998  mov\SpecialChar ~
25999 \SpecialChar ~
26000  (_foo_how2_1_1 + 1),(_glong + 2)
26001 \layout Standard
26002
26003 Again, variations of these cases may
26004 \emph on
26005 not
26006 \emph default
26007  be recognized.
26008  They are standard C expressions, so I heartily recommend these be the only
26009  way to get the higher order byte/word, (it is portable).
26010  Of course it will be recognized even if it is embedded in other expressions,
26011  e.g.:
26012 \layout Verse
26013
26014
26015 \family typewriter
26016 xyz = gint + ((gint >> 8) & 0xFF);
26017 \layout Standard
26018
26019 will still be recognized.
26020 \layout Subsection
26021
26022 Peephole Optimizer
26023 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
26024
26025 \end_inset
26026
26027
26028 \begin_inset LatexCommand \index{Peephole optimizer}
26029
26030 \end_inset
26031
26032
26033 \layout Standard
26034
26035 The compiler uses a rule based, pattern matching and re-writing mechanism
26036  for peep-hole optimization.
26037  It is inspired by
26038 \emph on
26039 copt
26040 \emph default
26041  a peep-hole optimizer by Christopher W.
26042  Fraser (cwfraser\SpecialChar ~
26043 @\SpecialChar ~
26044 microsoft.com).
26045  A default set of rules are compiled into the compiler, additional rules
26046  may be added with the
26047 \emph on
26048 -
26049 \begin_inset ERT
26050 status Collapsed
26051
26052 \layout Standard
26053
26054 \backslash
26055 /
26056 \end_inset
26057
26058 -peep-file
26059 \begin_inset LatexCommand \index{-\/-peep-file}
26060
26061 \end_inset
26062
26063  <filename>
26064 \emph default
26065  option.
26066  The rule language is best illustrated with examples.
26067 \layout Verse
26068
26069
26070 \family typewriter
26071 replace {
26072 \newline
26073 \SpecialChar ~
26074 \SpecialChar ~
26075 mov %1,a
26076 \newline
26077 \SpecialChar ~
26078 \SpecialChar ~
26079 mov a,%1
26080 \newline
26081 } by {
26082 \newline
26083 \SpecialChar ~
26084 \SpecialChar ~
26085 mov %1,a
26086 \newline
26087 }
26088 \layout Standard
26089
26090 The above rule will change the following assembly
26091 \begin_inset LatexCommand \index{Assembler routines}
26092
26093 \end_inset
26094
26095  sequence:
26096 \layout Verse
26097
26098
26099 \family typewriter
26100 mov r1,a
26101 \newline
26102 mov a,r1
26103 \layout Standard
26104
26105 to
26106 \layout Verse
26107
26108
26109 \family typewriter
26110 mov r1,a
26111 \layout Standard
26112
26113 Note: All occurrences of a
26114 \emph on
26115 %n
26116 \emph default
26117  (pattern variable) must denote the same string.
26118  With the above rule, the assembly sequence:
26119 \layout Verse
26120
26121
26122 \family typewriter
26123 mov r1,a
26124 \newline
26125 mov a,r2
26126 \layout Standard
26127
26128 will remain unmodified.
26129 \newline
26130
26131 \newline
26132 Other special case optimizations may be added by the user (via
26133 \emph on
26134 -
26135 \begin_inset ERT
26136 status Collapsed
26137
26138 \layout Standard
26139
26140 \backslash
26141 /
26142 \end_inset
26143
26144 -peep-file option
26145 \emph default
26146 ).
26147  E.g.
26148  some variants of the 8051 MCU
26149 \begin_inset LatexCommand \index{MCS51 variants}
26150
26151 \end_inset
26152
26153  allow only
26154 \family typewriter
26155 ajmp
26156 \family default
26157  and
26158 \family typewriter
26159 acall
26160 \family default
26161 .
26162  The following two rules will change all
26163 \family typewriter
26164 ljmp
26165 \family default
26166  and
26167 \family typewriter
26168 lcall
26169 \family default
26170  to
26171 \family typewriter
26172 ajmp
26173 \family default
26174  and
26175 \family typewriter
26176 acall
26177 \layout Verse
26178
26179
26180 \family typewriter
26181 replace { lcall %1 } by { acall %1 }
26182 \newline
26183 replace { ljmp %1 } by { ajmp %1 }
26184 \layout Standard
26185
26186 The
26187 \emph on
26188 inline-assembler code
26189 \emph default
26190  is also passed through the peep hole optimizer, thus the peephole optimizer
26191  can also be used as an assembly level macro expander.
26192  The rules themselves are MCU dependent whereas the rule language infra-structur
26193 e is MCU independent.
26194  Peephole optimization rules for other MCU can be easily programmed using
26195  the rule language.
26196 \newline
26197
26198 \newline
26199 The syntax for a rule is as follows:
26200 \layout Verse
26201
26202
26203 \family typewriter
26204 rule := replace [ restart ] '{' <assembly sequence> '
26205 \backslash
26206 n'
26207 \newline
26208 \SpecialChar ~
26209  \SpecialChar ~
26210  \SpecialChar ~
26211  \SpecialChar ~
26212  \SpecialChar ~
26213  \SpecialChar ~
26214  \SpecialChar ~
26215  \SpecialChar ~
26216  \SpecialChar ~
26217  \SpecialChar ~
26218  \SpecialChar ~
26219  \SpecialChar ~
26220  \SpecialChar ~
26221  \SpecialChar ~
26222  '}' by '{' '
26223 \backslash
26224 n'
26225 \newline
26226 \SpecialChar ~
26227  \SpecialChar ~
26228  \SpecialChar ~
26229  \SpecialChar ~
26230  \SpecialChar ~
26231  \SpecialChar ~
26232  \SpecialChar ~
26233  \SpecialChar ~
26234  \SpecialChar ~
26235  \SpecialChar ~
26236  \SpecialChar ~
26237  \SpecialChar ~
26238  \SpecialChar ~
26239  \SpecialChar ~
26240  \SpecialChar ~
26241  \SpecialChar ~
26242  <assembly sequence> '
26243 \backslash
26244 n'
26245 \newline
26246 \SpecialChar ~
26247  \SpecialChar ~
26248  \SpecialChar ~
26249  \SpecialChar ~
26250  \SpecialChar ~
26251  \SpecialChar ~
26252  \SpecialChar ~
26253  \SpecialChar ~
26254  \SpecialChar ~
26255  \SpecialChar ~
26256  \SpecialChar ~
26257  \SpecialChar ~
26258  \SpecialChar ~
26259  \SpecialChar ~
26260  '}' [if <functionName> ] '
26261 \backslash
26262 n'
26263 \layout Standard
26264
26265 <assembly sequence> := assembly instruction (each instruction including
26266  labels must be on a separate line).
26267 \newline
26268
26269 \newline
26270 The optimizer will apply to the rules one by one from the top in the sequence
26271  of their appearance, it will terminate when all rules are exhausted.
26272  If the 'restart' option is specified, then the optimizer will start matching
26273  the rules again from the top, this option for a rule is expensive (performance)
26274 , it is intended to be used in situations where a transformation will trigger
26275  the same rule again.
26276  An example of this (not a good one, it has side effects) is the following
26277  rule:
26278 \layout Verse
26279
26280
26281 \family typewriter
26282 replace restart {
26283 \newline
26284 \SpecialChar ~
26285 \SpecialChar ~
26286 pop %1
26287 \newline
26288 \SpecialChar ~
26289 \SpecialChar ~
26290 push %1 } by {
26291 \newline
26292 \SpecialChar ~
26293 \SpecialChar ~
26294 ; nop
26295 \newline
26296 }
26297 \layout Standard
26298
26299 Note that the replace pattern cannot be a blank, but can be a comment line.
26300  Without the 'restart' option only the innermost 'pop' 'push' pair would
26301  be eliminated, i.e.:
26302 \layout Verse
26303
26304
26305 \family typewriter
26306 pop ar1
26307 \newline
26308 pop ar2
26309 \newline
26310 push ar2
26311 \newline
26312 push ar1
26313 \layout Standard
26314
26315 would result in:
26316 \layout Verse
26317
26318
26319 \family typewriter
26320 pop ar1
26321 \newline
26322 ; nop
26323 \newline
26324 push ar1
26325 \layout Standard
26326
26327
26328 \emph on
26329 with
26330 \emph default
26331  the restart option the rule will be applied again to the resulting code
26332  and then all the pop-push pairs will be eliminated to yield:
26333 \layout Verse
26334
26335
26336 \family typewriter
26337 ; nop
26338 \newline
26339 ; nop
26340 \layout Standard
26341
26342 A conditional function can be attached to a rule.
26343  Attaching rules are somewhat more involved, let me illustrate this with
26344  an example.
26345 \layout Verse
26346
26347
26348 \family typewriter
26349 replace {
26350 \newline
26351 \SpecialChar ~
26352  \SpecialChar ~
26353  \SpecialChar ~
26354 ljmp %5
26355 \newline
26356 %2:
26357 \newline
26358 } by {
26359 \newline
26360 \SpecialChar ~
26361  \SpecialChar ~
26362  \SpecialChar ~
26363 sjmp %5
26364 \newline
26365 %2:
26366 \newline
26367 } if labelInRange
26368 \layout Standard
26369
26370 The optimizer does a look-up of a function name table defined in function
26371
26372 \emph on
26373 callFuncByName
26374 \emph default
26375  in the source file SDCCpeeph.c, with the name
26376 \emph on
26377 labelInRange
26378 \emph default
26379 .
26380  If it finds a corresponding entry the function is called.
26381  Note there can be no parameters specified for these functions, in this
26382  case the use of
26383 \emph on
26384 %5
26385 \emph default
26386  is crucial, since the function
26387 \emph on
26388 labelInRange
26389 \emph default
26390  expects to find the label in that particular variable (the hash table containin
26391 g the variable bindings is passed as a parameter).
26392  If you want to code more such functions, take a close look at the function
26393  labelInRange and the calling mechanism in source file SDCCpeeph.c.
26394  Currently implemented are
26395 \emph on
26396 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
26397  24bitMode, portIsDS390, 24bitModeAndPortDS390
26398 \emph default
26399 and
26400 \emph on
26401  notVolatile
26402 \emph default
26403 .
26404 \layout Standard
26405
26406 I know this whole thing is a little kludgey, but maybe some day we will
26407  have some better means.
26408  If you are looking at this file, you will see the default rules that are
26409  compiled into the compiler, you can add your own rules in the default set
26410  there if you get tired of specifying the -
26411 \begin_inset ERT
26412 status Collapsed
26413
26414 \layout Standard
26415
26416 \backslash
26417 /
26418 \end_inset
26419
26420 -peep-file option.
26421 \layout Section
26422
26423 ANSI-Compliance
26424 \begin_inset LatexCommand \index{ANSI-compliance}
26425
26426 \end_inset
26427
26428
26429 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
26430
26431 \end_inset
26432
26433
26434 \layout Standard
26435
26436 Deviations from the compliance:
26437 \layout Itemize
26438
26439 functions are not reentrant
26440 \begin_inset LatexCommand \index{reentrant}
26441
26442 \end_inset
26443
26444  unless explicitly declared as such or the
26445 \series bold
26446 -
26447 \begin_inset ERT
26448 status Collapsed
26449
26450 \layout Standard
26451
26452 \backslash
26453 /
26454 \end_inset
26455
26456 -stack-auto
26457 \begin_inset LatexCommand \index{-\/-stack-auto}
26458
26459 \end_inset
26460
26461
26462 \series default
26463  command line option is specified.
26464 \layout Itemize
26465
26466 structures and unions cannot be assigned values directly, cannot be passed
26467  as function parameters or assigned to each other and cannot be a return
26468  value from a function, e.g.:
26469 \begin_deeper
26470 \layout Verse
26471
26472
26473 \family typewriter
26474 struct s { ...
26475  };
26476 \newline
26477 struct s s1, s2;
26478 \newline
26479 foo()
26480 \newline
26481 {
26482 \newline
26483 \SpecialChar ~
26484 \SpecialChar ~
26485 \SpecialChar ~
26486 \SpecialChar ~
26487 ...
26488
26489 \newline
26490 \SpecialChar ~
26491 \SpecialChar ~
26492 \SpecialChar ~
26493 \SpecialChar ~
26494 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
26495 \newline
26496 \SpecialChar ~
26497 \SpecialChar ~
26498 \SpecialChar ~
26499 \SpecialChar ~
26500 ...
26501
26502 \newline
26503 }
26504 \newline
26505 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
26506  */
26507 \newline
26508 {
26509 \newline
26510 \SpecialChar ~
26511 \SpecialChar ~
26512 \SpecialChar ~
26513 \SpecialChar ~
26514 struct s rets;
26515 \newline
26516 \SpecialChar ~
26517 \SpecialChar ~
26518 \SpecialChar ~
26519 \SpecialChar ~
26520 ...
26521
26522 \newline
26523 \SpecialChar ~
26524 \SpecialChar ~
26525 \SpecialChar ~
26526 \SpecialChar ~
26527 return rets;/* is invalid in SDCC although allowed in ANSI */
26528 \newline
26529 }
26530 \end_deeper
26531 \layout Itemize
26532
26533 initialization of structure arrays must be fully braced.
26534 \begin_deeper
26535 \layout Verse
26536
26537
26538 \family typewriter
26539 struct s { char x } a[] = {1, 2}; /* invalid in SDCC */
26540 \newline
26541 struct s { char x } a[] = {{1}, {2}}; /* OK */
26542 \end_deeper
26543 \layout Itemize
26544
26545 'long long
26546 \begin_inset LatexCommand \index{long long (not supported)}
26547
26548 \end_inset
26549
26550 ' (64 bit integers
26551 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
26552
26553 \end_inset
26554
26555 ) not supported.
26556 \layout Itemize
26557
26558 'double
26559 \begin_inset LatexCommand \index{double (not supported)}
26560
26561 \end_inset
26562
26563 ' precision floating point
26564 \begin_inset LatexCommand \index{Floating point support}
26565
26566 \end_inset
26567
26568 not supported.
26569 \layout Itemize
26570
26571 Old K&R style
26572 \begin_inset LatexCommand \index{K\&R style}
26573
26574 \end_inset
26575
26576  function declarations are NOT allowed.
26577 \begin_deeper
26578 \layout Verse
26579
26580
26581 \family typewriter
26582 foo(i,j) /* this old style of function declarations */
26583 \newline
26584 int i,j; /* are valid in ANSI but not valid in SDCC */
26585 \newline
26586 {
26587 \newline
26588 \SpecialChar ~
26589 \SpecialChar ~
26590 \SpecialChar ~
26591 \SpecialChar ~
26592 ...
26593
26594 \newline
26595 }
26596 \end_deeper
26597 \layout Itemize
26598
26599 Most enhancements in C99 are not supported, f.e.:
26600 \begin_deeper
26601 \layout Verse
26602
26603
26604 \family typewriter
26605 \series bold
26606 inline
26607 \series default
26608  int increment (int a) { return a+1; } /* is invalid in SDCC although allowed
26609  in C99 */
26610 \newline
26611 for (
26612 \series bold
26613 int
26614 \series default
26615  i=0; i<10; i++) /* is invalid in SDCC although allowed in C99 */
26616 \end_deeper
26617 \layout Itemize
26618
26619 Certain words that are valid identifiers in the standard may be reserved
26620  words in SDCC unless the
26621 \series bold
26622 -
26623 \begin_inset ERT
26624 status Collapsed
26625
26626 \layout Standard
26627
26628 \backslash
26629 /
26630 \end_inset
26631
26632 -std-c89
26633 \begin_inset LatexCommand \index{-\/-std-c89}
26634
26635 \end_inset
26636
26637  or -
26638 \begin_inset ERT
26639 status Collapsed
26640
26641 \layout Standard
26642
26643 \backslash
26644 /
26645 \end_inset
26646
26647 -std-c99
26648 \begin_inset LatexCommand \index{-\/-std-c99}
26649
26650 \end_inset
26651
26652
26653 \series default
26654  command line options are used.
26655  These may include (depending on the selected processor): 'at', 'banked',
26656  'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup
26657 t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs',
26658  'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and
26659  '_naked'.
26660  Compliant equivalents of these keywords are always available in a form
26661  that begin with two underscores
26662 \begin_inset LatexCommand \index{\_\_ (prefix for extended keywords)}
26663
26664 \end_inset
26665
26666 , f.e.
26667  '__data' instead of 'data'.
26668 \layout Section
26669
26670 Cyclomatic Complexity
26671 \begin_inset LatexCommand \index{Cyclomatic complexity}
26672
26673 \end_inset
26674
26675
26676 \layout Standard
26677
26678 Cyclomatic complexity of a function is defined as the number of independent
26679  paths the program can take during execution of the function.
26680  This is an important number since it defines the number test cases you
26681  have to generate to validate the function.
26682  The accepted industry standard for complexity number is 10, if the cyclomatic
26683  complexity reported by SDCC exceeds 10 you should think about simplification
26684  of the function logic.
26685  Note that the complexity level is not related to the number of lines of
26686  code in a function.
26687  Large functions can have low complexity, and small functions can have large
26688  complexity levels.
26689
26690 \newline
26691
26692 \newline
26693 SDCC uses the following formula to compute the complexity:
26694 \newline
26695
26696 \layout Standard
26697
26698 complexity = (number of edges in control flow graph) - (number of nodes
26699  in control flow graph) + 2;
26700 \newline
26701
26702 \newline
26703 Having said that the industry standard is 10, you should be aware that in
26704  some cases it be may unavoidable to have a complexity level of less than
26705  10.
26706  For example if you have switch statement with more than 10 case labels,
26707  each case label adds one to the complexity level.
26708  The complexity level is by no means an absolute measure of the algorithmic
26709  complexity of the function, it does however provide a good starting point
26710  for which functions you might look at for further optimization.
26711 \layout Section
26712
26713 Retargetting for other Processors
26714 \layout Standard
26715
26716 The issues for retargetting the compiler are far too numerous to be covered
26717  by this document.
26718  What follows is a brief description of each of the seven phases of the
26719  compiler and its MCU dependency.
26720 \layout Itemize
26721
26722 Parsing the source and building the annotated parse tree.
26723  This phase is largely MCU independent (except for the language extensions).
26724  Syntax & semantic checks are also done in this phase, along with some initial
26725  optimizations like back patching labels and the pattern matching optimizations
26726  like bit-rotation etc.
26727 \layout Itemize
26728
26729 The second phase involves generating an intermediate code which can be easy
26730  manipulated during the later phases.
26731  This phase is entirely MCU independent.
26732  The intermediate code generation assumes the target machine has unlimited
26733  number of registers, and designates them with the name iTemp.
26734  The compiler can be made to dump a human readable form of the code generated
26735  by using the -
26736 \begin_inset ERT
26737 status Collapsed
26738
26739 \layout Standard
26740
26741 \backslash
26742 /
26743 \end_inset
26744
26745 -dumpraw option.
26746 \layout Itemize
26747
26748 This phase does the bulk of the standard optimizations and is also MCU independe
26749 nt.
26750  This phase can be broken down into several sub-phases:
26751 \newline
26752
26753 \newline
26754 Break down intermediate code (iCode) into basic blocks.
26755 \newline
26756 Do control flow & data flow analysis on the basic blocks.
26757 \newline
26758 Do local common subexpression elimination, then global subexpression elimination
26759 \newline
26760 Dead code elimination
26761 \newline
26762 Loop optimizations
26763 \newline
26764 If loop optimizations caused any changes then do 'global subexpression eliminati
26765 on' and 'dead code elimination' again.
26766 \layout Itemize
26767
26768 This phase determines the live-ranges; by live range I mean those iTemp
26769  variables defined by the compiler that still survive after all the optimization
26770 s.
26771  Live range analysis
26772 \begin_inset LatexCommand \index{Live range analysis}
26773
26774 \end_inset
26775
26776  is essential for register allocation, since these computation determines
26777  which of these iTemps will be assigned to registers, and for how long.
26778 \layout Itemize
26779
26780 Phase five is register allocation.
26781  There are two parts to this process.
26782 \newline
26783
26784 \newline
26785 The first part I call 'register packing' (for lack of a better term).
26786  In this case several MCU specific expression folding is done to reduce
26787  register pressure.
26788 \newline
26789
26790 \newline
26791 The second part is more MCU independent and deals with allocating registers
26792  to the remaining live ranges.
26793  A lot of MCU specific code does creep into this phase because of the limited
26794  number of index registers available in the 8051.
26795 \layout Itemize
26796
26797 The Code generation phase is (unhappily), entirely MCU dependent and very
26798  little (if any at all) of this code can be reused for other MCU.
26799  However the scheme for allocating a homogenized assembler operand for each
26800  iCode operand may be reused.
26801 \layout Itemize
26802
26803 As mentioned in the optimization section the peep-hole optimizer is rule
26804  based system, which can reprogrammed for other MCUs.
26805 \layout Chapter
26806
26807 Compiler internals
26808 \begin_inset LatexCommand \index{Compiler internals}
26809
26810 \end_inset
26811
26812
26813 \layout Section
26814
26815 The anatomy of the compiler
26816 \begin_inset LatexCommand \label{sub:The-anatomy-of}
26817
26818 \end_inset
26819
26820
26821 \layout Standard
26822
26823
26824 \shape italic
26825 This is an excerpt from an article published in Circuit Cellar Magazine
26826  in
26827 \series bold
26828 August 2000
26829 \series default
26830 .
26831  It's a little outdated (the compiler is much more efficient now and user/develo
26832 per friendly), but pretty well exposes the guts of it all.
26833 \shape default
26834
26835 \newline
26836
26837 \newline
26838 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
26839  It is fairly easy to retarget for other 8-bit MCU.
26840  Here we take a look at some of the internals of the compiler.
26841
26842 \layout Paragraph*
26843
26844 Parsing
26845 \begin_inset LatexCommand \index{Parsing}
26846
26847 \end_inset
26848
26849
26850 \layout Standard
26851
26852 Parsing the input source file and creating an AST (Annotated Syntax Tree
26853 \begin_inset LatexCommand \index{Annotated syntax tree}
26854
26855 \end_inset
26856
26857 ).
26858  This phase also involves propagating types (annotating each node of the
26859  parse tree with type information) and semantic analysis.
26860  There are some MCU specific parsing rules.
26861  For example the storage classes, the extended storage classes are MCU specific
26862  while there may be a xdata storage class for 8051 there is no such storage
26863  class for z80 or Atmel AVR.
26864  SDCC allows MCU specific storage class extensions, i.e.
26865  xdata will be treated as a storage class specifier when parsing 8051 C
26866  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
26867  C code.
26868 \layout Paragraph*
26869
26870 Generating iCode
26871 \begin_inset LatexCommand \index{iCode}
26872
26873 \end_inset
26874
26875
26876 \layout Standard
26877
26878 Intermediate code generation.
26879  In this phase the AST is broken down into three-operand form (iCode).
26880  These three operand forms are represented as doubly linked lists.
26881  ICode is the term given to the intermediate form generated by the compiler.
26882  ICode example section shows some examples of iCode generated for some simple
26883  C source functions.
26884 \layout Paragraph*
26885
26886 Optimizations
26887 \begin_inset LatexCommand \index{Optimizations}
26888
26889 \end_inset
26890
26891 .
26892 \layout Standard
26893
26894 Bulk of the target independent optimizations is performed in this phase.
26895  The optimizations include constant propagation, common sub-expression eliminati
26896 on, loop invariant code movement, strength reduction of loop induction variables
26897  and dead-code elimination.
26898 \layout Paragraph*
26899
26900 Live range analysis
26901 \begin_inset LatexCommand \index{Live range analysis}
26902
26903 \end_inset
26904
26905
26906 \layout Standard
26907
26908 During intermediate code generation phase, the compiler assumes the target
26909  machine has infinite number of registers and generates a lot of temporary
26910  variables.
26911  The live range computation determines the lifetime of each of these compiler-ge
26912 nerated temporaries.
26913  A picture speaks a thousand words.
26914  ICode example sections show the live range annotations for each of the
26915  operand.
26916  It is important to note here, each iCode is assigned a number in the order
26917  of its execution in the function.
26918  The live ranges are computed in terms of these numbers.
26919  The from number is the number of the iCode which first defines the operand
26920  and the to number signifies the iCode which uses this operand last.
26921 \layout Paragraph*
26922
26923 Register Allocation
26924 \begin_inset LatexCommand \index{Register allocation}
26925
26926 \end_inset
26927
26928
26929 \layout Standard
26930
26931 The register allocation determines the type and number of registers needed
26932  by each operand.
26933  In most MCUs only a few registers can be used for indirect addressing.
26934  In case of 8051 for example the registers R0 & R1 can be used to indirectly
26935  address the internal ram and DPTR to indirectly address the external ram.
26936  The compiler will try to allocate the appropriate register to pointer variables
26937  if it can.
26938  ICode example section shows the operands annotated with the registers assigned
26939  to them.
26940  The compiler will try to keep operands in registers as much as possible;
26941  there are several schemes the compiler uses to do achieve this.
26942  When the compiler runs out of registers the compiler will check to see
26943  if there are any live operands which is not used or defined in the current
26944  basic block being processed, if there are any found then it will push that
26945  operand and use the registers in this block, the operand will then be popped
26946  at the end of the basic block.
26947
26948 \layout Standard
26949
26950 There are other MCU specific considerations in this phase.
26951  Some MCUs have an accumulator; very short-lived operands could be assigned
26952  to the accumulator instead of a general-purpose register.
26953 \layout Paragraph*
26954
26955 Code generation
26956 \layout Standard
26957
26958 Figure II gives a table of iCode operations supported by the compiler.
26959  The code generation involves translating these operations into corresponding
26960  assembly code for the processor.
26961  This sounds overly simple but that is the essence of code generation.
26962  Some of the iCode operations are generated on a MCU specific manner for
26963  example, the z80 port does not use registers to pass parameters so the
26964  SEND and RECV iCode operations will not be generated, and it also does
26965  not support JUMPTABLES.
26966
26967 \newline
26968
26969 \series bold
26970 \shape italic
26971 \color red
26972 <Where is Figure II?>
26973 \layout Comment
26974
26975 In the original article Figure II was announced to be downloadable on
26976 \shape italic
26977 Circuit Cellar
26978 \shape default
26979 's web site.
26980  Unfortunately it never seemed to have shown up there, so: where is Figure
26981  II?
26982 \layout Paragraph*
26983
26984 ICode Example
26985 \begin_inset LatexCommand \index{iCode}
26986
26987 \end_inset
26988
26989
26990 \layout Standard
26991
26992 This section shows some details of iCode.
26993  The example C code does not do anything useful; it is used as an example
26994  to illustrate the intermediate code generated by the compiler.
26995 \layout Verse
26996
26997
26998 \family typewriter
26999 1.\SpecialChar ~
27000 xdata int * p;
27001 \newline
27002 2.\SpecialChar ~
27003 int gint;
27004 \newline
27005 3.\SpecialChar ~
27006 /* This function does nothing useful.
27007  It is used
27008 \newline
27009 4.\SpecialChar ~
27010 \SpecialChar ~
27011 \SpecialChar ~
27012 \SpecialChar ~
27013 for the purpose of explaining iCode */
27014 \newline
27015 5.\SpecialChar ~
27016 short function (data int *x)
27017 \newline
27018 6.\SpecialChar ~
27019 {
27020 \newline
27021 7.\SpecialChar ~
27022 \SpecialChar ~
27023 \SpecialChar ~
27024 short i=10; \SpecialChar ~
27025 \SpecialChar ~
27026 /* dead initialization eliminated */
27027 \newline
27028 8.\SpecialChar ~
27029 \SpecialChar ~
27030 \SpecialChar ~
27031 short sum=10; /* dead initialization eliminated */
27032 \newline
27033 9.\SpecialChar ~
27034 \SpecialChar ~
27035 \SpecialChar ~
27036 short mul;
27037 \newline
27038 10.\SpecialChar ~
27039 \SpecialChar ~
27040 int j ;
27041 \newline
27042 11.\SpecialChar ~
27043 \SpecialChar ~
27044 while (*x) *x++ = *p++;
27045 \newline
27046 12.\SpecialChar ~
27047 \SpecialChar ~
27048 \SpecialChar ~
27049 \SpecialChar ~
27050 sum = 0 ;
27051 \newline
27052 13.\SpecialChar ~
27053 \SpecialChar ~
27054 mul = 0;
27055 \newline
27056 14.\SpecialChar ~
27057 \SpecialChar ~
27058 /* compiler detects i,j to be induction variables */
27059 \newline
27060 15.\SpecialChar ~
27061 \SpecialChar ~
27062 for (i = 0, j = 10 ; i < 10 ; i++, j
27063 \family default
27064 -
27065 \begin_inset ERT
27066 status Collapsed
27067
27068 \layout Standard
27069
27070 \backslash
27071 /
27072 \end_inset
27073
27074 -
27075 \family typewriter
27076 ) {
27077 \newline
27078 16.\SpecialChar ~
27079 \SpecialChar ~
27080 \SpecialChar ~
27081 \SpecialChar ~
27082 sum += i;
27083 \newline
27084 17.\SpecialChar ~
27085 \SpecialChar ~
27086 \SpecialChar ~
27087 \SpecialChar ~
27088 mul += i * 3; \SpecialChar ~
27089 \SpecialChar ~
27090 /* this multiplication remains */
27091 \newline
27092 18.\SpecialChar ~
27093 \SpecialChar ~
27094 \SpecialChar ~
27095 \SpecialChar ~
27096 gint += j * 3;\SpecialChar ~
27097 \SpecialChar ~
27098 /* this multiplication changed to addition */
27099 \newline
27100 19.\SpecialChar ~
27101 \SpecialChar ~
27102 }
27103 \newline
27104 20.\SpecialChar ~
27105 \SpecialChar ~
27106 return sum+mul;
27107 \newline
27108 21.\SpecialChar ~
27109 }
27110 \layout Standard
27111
27112 In addition to the operands each iCode contains information about the filename
27113  and line it corresponds to in the source file.
27114  The first field in the listing should be interpreted as follows:
27115 \newline
27116
27117 \shape italic
27118 \size footnotesize
27119 Filename(linenumber: iCode Execution sequence number : ICode hash table
27120  key : loop depth of the iCode).
27121 \shape default
27122 \size default
27123
27124 \newline
27125 Then follows the human readable form of the ICode operation.
27126  Each operand of this triplet form can be of three basic types a) compiler
27127  generated temporary b) user defined variable c) a constant value.
27128  Note that local variables and parameters are replaced by compiler generated
27129  temporaries.
27130  Live ranges
27131 \begin_inset LatexCommand \index{Live range analysis}
27132
27133 \end_inset
27134
27135  are computed only for temporaries (i.e.
27136  live ranges are not computed for global variables).
27137  Registers
27138 \begin_inset LatexCommand \index{Register allocation}
27139
27140 \end_inset
27141
27142  are allocated for temporaries only.
27143  Operands are formatted in the following manner:
27144 \newline
27145
27146 \shape italic
27147 \size footnotesize
27148 Operand Name [lr live-from : live-to ] { type information } [ registers
27149  allocated ].
27150 \shape default
27151 \size default
27152
27153 \newline
27154 As mentioned earlier the live ranges are computed in terms of the execution
27155  sequence number of the iCodes, for example
27156 \newline
27157 the iTemp0 is live from (i.e.
27158  first defined in iCode with execution sequence number 3, and is last used
27159  in the iCode with sequence number 5).
27160  For induction variables such as iTemp21 the live range computation extends
27161  the lifetime from the start to the end of the loop.
27162 \newline
27163 The register allocator used the live range information to allocate registers,
27164  the same registers may be used for different temporaries if their live
27165  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
27166  iTemp17 since their live ranges do not overlap.
27167  In addition the allocator also takes into consideration the type and usage
27168  of a temporary, for example itemp6 is a pointer to near space and is used
27169  as to fetch data from (i.e.
27170  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
27171  Some short lived temporaries are allocated to special registers which have
27172  meaning to the code generator e.g.
27173  iTemp13 is allocated to a pseudo register CC which tells the back end that
27174  the temporary is used only for a conditional jump the code generation makes
27175  use of this information to optimize a compare and jump ICode.
27176 \newline
27177 There are several loop optimizations
27178 \begin_inset LatexCommand \index{Loop optimization}
27179
27180 \end_inset
27181
27182  performed by the compiler.
27183  It can detect induction variables iTemp21(i) and iTemp23(j).
27184  Also note the compiler does selective strength reduction
27185 \begin_inset LatexCommand \index{Strength reduction}
27186
27187 \end_inset
27188
27189 , i.e.
27190  the multiplication of an induction variable in line 18 (gint = j * 3) is
27191  changed to addition, a new temporary iTemp17 is allocated and assigned
27192  a initial value, a constant 3 is then added for each iteration of the loop.
27193  The compiler does not change the multiplication
27194 \begin_inset LatexCommand \index{Multiplication}
27195
27196 \end_inset
27197
27198  in line 17 however since the processor does support an 8 * 8 bit multiplication.
27199 \newline
27200 Note the dead code elimination
27201 \begin_inset LatexCommand \index{Dead-code elimination}
27202
27203 \end_inset
27204
27205  optimization eliminated the dead assignments in line 7 & 8 to I and sum
27206  respectively.
27207 \newline
27208
27209 \layout Standard
27210
27211
27212 \size footnotesize
27213 Sample.c (5:1:0:0) _entry($9) :
27214 \layout Standard
27215
27216
27217 \size footnotesize
27218 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
27219 \layout Standard
27220
27221
27222 \size footnotesize
27223 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
27224 \layout Standard
27225
27226
27227 \size footnotesize
27228 Sample.c(11:4:53:0) preHeaderLbl0($11) :
27229 \layout Standard
27230
27231
27232 \size footnotesize
27233 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
27234  * int}[r2]
27235 \layout Standard
27236
27237
27238 \size footnotesize
27239 Sample.c(11:6:5:1) _whilecontinue_0($1) :
27240 \layout Standard
27241
27242
27243 \size footnotesize
27244 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
27245  int}[r0]]
27246 \layout Standard
27247
27248
27249 \size footnotesize
27250 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
27251 \layout Standard
27252
27253
27254 \size footnotesize
27255 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
27256  * int}
27257 \layout Standard
27258
27259
27260 \size footnotesize
27261 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
27262  {short}
27263 \layout Standard
27264
27265
27266 \size footnotesize
27267 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
27268  * int}[DPTR]]
27269 \layout Standard
27270
27271
27272 \size footnotesize
27273 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
27274 }[r2 r3]
27275 \layout Standard
27276
27277
27278 \size footnotesize
27279 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
27280  * int}[r0] + 0x2 {short}
27281 \layout Standard
27282
27283
27284 \size footnotesize
27285 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
27286 \layout Standard
27287
27288
27289 \size footnotesize
27290 Sample.c(11:17:21:0)_whilebreak_0($3) :
27291 \layout Standard
27292
27293
27294 \size footnotesize
27295 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
27296 \layout Standard
27297
27298
27299 \size footnotesize
27300 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
27301 \layout Standard
27302
27303
27304 \size footnotesize
27305 Sample.c(15:20:54:0)preHeaderLbl1($13) :
27306 \layout Standard
27307
27308
27309 \size footnotesize
27310 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
27311 \layout Standard
27312
27313
27314 \size footnotesize
27315 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
27316 \layout Standard
27317
27318
27319 \size footnotesize
27320 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
27321 \layout Standard
27322
27323
27324 \size footnotesize
27325 Sample.c(15:24:26:1)_forcond_0($4) :
27326 \layout Standard
27327
27328
27329 \size footnotesize
27330 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
27331  < 0xa {short}
27332 \layout Standard
27333
27334
27335 \size footnotesize
27336 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
27337 \layout Standard
27338
27339
27340 \size footnotesize
27341 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
27342  + ITemp21 [lr21:38]{short}[r4]
27343 \layout Standard
27344
27345
27346 \size footnotesize
27347 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
27348  * 0x3 {short}
27349 \layout Standard
27350
27351
27352 \size footnotesize
27353 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
27354  + iTemp15 [lr29:30]{short}[r1]
27355 \layout Standard
27356
27357
27358 \size footnotesize
27359 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
27360  r0]- 0x3 {short}
27361 \layout Standard
27362
27363
27364 \size footnotesize
27365 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
27366 int}[r7 r0]
27367 \layout Standard
27368
27369
27370 \size footnotesize
27371 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
27372  + 0x1 {short}
27373 \layout Standard
27374
27375
27376 \size footnotesize
27377 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
27378  r6]- 0x1 {short}
27379 \layout Standard
27380
27381
27382 \size footnotesize
27383 Sample.c(19:38:47:1) goto _forcond_0($4)
27384 \layout Standard
27385
27386
27387 \size footnotesize
27388 Sample.c(19:39:48:0)_forbreak_0($7) :
27389 \layout Standard
27390
27391
27392 \size footnotesize
27393 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
27394  + ITemp11 [lr19:40]{short}[r3]
27395 \layout Standard
27396
27397
27398 \size footnotesize
27399 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
27400 \layout Standard
27401
27402
27403 \size footnotesize
27404 Sample.c(20:42:51:0)_return($8) :
27405 \layout Standard
27406
27407
27408 \size footnotesize
27409 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
27410 \size default
27411
27412 \newline
27413
27414 \newline
27415 Finally the code generated for this function:
27416 \newline
27417
27418 \layout Standard
27419
27420
27421 \size footnotesize
27422 .area DSEG (DATA)
27423 \layout Standard
27424
27425
27426 \size footnotesize
27427 _p::
27428 \layout Standard
27429
27430
27431 \size footnotesize
27432 \SpecialChar ~
27433 \SpecialChar ~
27434 .ds 2
27435 \layout Standard
27436
27437
27438 \size footnotesize
27439 _gint::
27440 \layout Standard
27441
27442
27443 \size footnotesize
27444 \SpecialChar ~
27445 \SpecialChar ~
27446 .ds 2
27447 \layout Standard
27448
27449
27450 \size footnotesize
27451 ; sample.c 5
27452 \layout Standard
27453
27454
27455 \size footnotesize
27456 ; ----------------------------------------------
27457 \layout Standard
27458
27459
27460 \size footnotesize
27461 ; function function
27462 \layout Standard
27463
27464
27465 \size footnotesize
27466 ; ----------------------------------------------
27467 \layout Standard
27468
27469
27470 \size footnotesize
27471 _function:
27472 \layout Standard
27473
27474
27475 \size footnotesize
27476 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
27477 \layout Standard
27478
27479
27480 \size footnotesize
27481 \SpecialChar ~
27482 \SpecialChar ~
27483 mov r2,dpl
27484 \layout Standard
27485
27486
27487 \size footnotesize
27488 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
27489 \layout Standard
27490
27491
27492 \size footnotesize
27493 \SpecialChar ~
27494 \SpecialChar ~
27495 mov ar0,r2
27496 \layout Standard
27497
27498
27499 \size footnotesize
27500 ;_whilecontinue_0($1) :
27501 \layout Standard
27502
27503
27504 \size footnotesize
27505 00101$:
27506 \layout Standard
27507
27508
27509 \size footnotesize
27510 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
27511 \layout Standard
27512
27513
27514 \size footnotesize
27515 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
27516 \layout Standard
27517
27518
27519 \size footnotesize
27520 \SpecialChar ~
27521 \SpecialChar ~
27522 mov ar2,@r0
27523 \layout Standard
27524
27525
27526 \size footnotesize
27527 \SpecialChar ~
27528 \SpecialChar ~
27529 inc r0
27530 \layout Standard
27531
27532
27533 \size footnotesize
27534 \SpecialChar ~
27535 \SpecialChar ~
27536 mov ar3,@r0
27537 \layout Standard
27538
27539
27540 \size footnotesize
27541 \SpecialChar ~
27542 \SpecialChar ~
27543 dec r0
27544 \layout Standard
27545
27546
27547 \size footnotesize
27548 \SpecialChar ~
27549 \SpecialChar ~
27550 mov a,r2
27551 \layout Standard
27552
27553
27554 \size footnotesize
27555 \SpecialChar ~
27556 \SpecialChar ~
27557 orl a,r3
27558 \layout Standard
27559
27560
27561 \size footnotesize
27562 \SpecialChar ~
27563 \SpecialChar ~
27564 jz 00103$
27565 \layout Standard
27566
27567
27568 \size footnotesize
27569 00114$:
27570 \layout Standard
27571
27572
27573 \size footnotesize
27574 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
27575 \layout Standard
27576
27577
27578 \size footnotesize
27579 \SpecialChar ~
27580 \SpecialChar ~
27581 mov dpl,_p
27582 \layout Standard
27583
27584
27585 \size footnotesize
27586 \SpecialChar ~
27587 \SpecialChar ~
27588 mov dph,(_p + 1)
27589 \layout Standard
27590
27591
27592 \size footnotesize
27593 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
27594 \layout Standard
27595
27596
27597 \size footnotesize
27598 \SpecialChar ~
27599 \SpecialChar ~
27600 mov a,#0x02
27601 \layout Standard
27602
27603
27604 \size footnotesize
27605 \SpecialChar ~
27606 \SpecialChar ~
27607 add a,_p
27608 \layout Standard
27609
27610
27611 \size footnotesize
27612 \SpecialChar ~
27613 \SpecialChar ~
27614 mov _p,a
27615 \layout Standard
27616
27617
27618 \size footnotesize
27619 \SpecialChar ~
27620 \SpecialChar ~
27621 clr a
27622 \layout Standard
27623
27624
27625 \size footnotesize
27626 \SpecialChar ~
27627 \SpecialChar ~
27628 addc a,(_p + 1)
27629 \layout Standard
27630
27631
27632 \size footnotesize
27633 \SpecialChar ~
27634 \SpecialChar ~
27635 mov (_p + 1),a
27636 \layout Standard
27637
27638
27639 \size footnotesize
27640 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
27641 \layout Standard
27642
27643
27644 \size footnotesize
27645 \SpecialChar ~
27646 \SpecialChar ~
27647 movx a,@dptr
27648 \layout Standard
27649
27650
27651 \size footnotesize
27652 \SpecialChar ~
27653 \SpecialChar ~
27654 mov r2,a
27655 \layout Standard
27656
27657
27658 \size footnotesize
27659 \SpecialChar ~
27660 \SpecialChar ~
27661 inc dptr
27662 \layout Standard
27663
27664
27665 \size footnotesize
27666 \SpecialChar ~
27667 \SpecialChar ~
27668 movx a,@dptr
27669 \layout Standard
27670
27671
27672 \size footnotesize
27673 \SpecialChar ~
27674 \SpecialChar ~
27675 mov r3,a
27676 \layout Standard
27677
27678
27679 \size footnotesize
27680 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
27681 \layout Standard
27682
27683
27684 \size footnotesize
27685 \SpecialChar ~
27686 \SpecialChar ~
27687 mov @r0,ar2
27688 \layout Standard
27689
27690
27691 \size footnotesize
27692 \SpecialChar ~
27693 \SpecialChar ~
27694 inc r0
27695 \layout Standard
27696
27697
27698 \size footnotesize
27699 \SpecialChar ~
27700 \SpecialChar ~
27701 mov @r0,ar3
27702 \layout Standard
27703
27704
27705 \size footnotesize
27706 ; iTemp6 [lr5:16]{_near * int}[r0] =
27707 \layout Standard
27708
27709
27710 \size footnotesize
27711 ; iTemp6 [lr5:16]{_near * int}[r0] +
27712 \layout Standard
27713
27714
27715 \size footnotesize
27716 ; 0x2 {short}
27717 \layout Standard
27718
27719
27720 \size footnotesize
27721 \SpecialChar ~
27722 \SpecialChar ~
27723 inc r0
27724 \layout Standard
27725
27726
27727 \size footnotesize
27728 ; goto _whilecontinue_0($1)
27729 \layout Standard
27730
27731
27732 \size footnotesize
27733 \SpecialChar ~
27734 \SpecialChar ~
27735 sjmp 00101$
27736 \layout Standard
27737
27738
27739 \size footnotesize
27740 ; _whilebreak_0($3) :
27741 \layout Standard
27742
27743
27744 \size footnotesize
27745 00103$:
27746 \layout Standard
27747
27748
27749 \size footnotesize
27750 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
27751 \layout Standard
27752
27753
27754 \size footnotesize
27755 \SpecialChar ~
27756 \SpecialChar ~
27757 mov r2,#0x00
27758 \layout Standard
27759
27760
27761 \size footnotesize
27762 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
27763 \layout Standard
27764
27765
27766 \size footnotesize
27767 \SpecialChar ~
27768 \SpecialChar ~
27769 mov r3,#0x00
27770 \layout Standard
27771
27772
27773 \size footnotesize
27774 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
27775 \layout Standard
27776
27777
27778 \size footnotesize
27779 \SpecialChar ~
27780 \SpecialChar ~
27781 mov r4,#0x00
27782 \layout Standard
27783
27784
27785 \size footnotesize
27786 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
27787 \layout Standard
27788
27789
27790 \size footnotesize
27791 \SpecialChar ~
27792 \SpecialChar ~
27793 mov r5,#0x0A
27794 \layout Standard
27795
27796
27797 \size footnotesize
27798 \SpecialChar ~
27799 \SpecialChar ~
27800 mov r6,#0x00
27801 \layout Standard
27802
27803
27804 \size footnotesize
27805 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
27806 \layout Standard
27807
27808
27809 \size footnotesize
27810 \SpecialChar ~
27811 \SpecialChar ~
27812 mov r7,#0x1E
27813 \layout Standard
27814
27815
27816 \size footnotesize
27817 \SpecialChar ~
27818 \SpecialChar ~
27819 mov r0,#0x00
27820 \layout Standard
27821
27822
27823 \size footnotesize
27824 ; _forcond_0($4) :
27825 \layout Standard
27826
27827
27828 \size footnotesize
27829 00104$:
27830 \layout Standard
27831
27832
27833 \size footnotesize
27834 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
27835 \layout Standard
27836
27837
27838 \size footnotesize
27839 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
27840 \layout Standard
27841
27842
27843 \size footnotesize
27844 \SpecialChar ~
27845 \SpecialChar ~
27846 clr c
27847 \layout Standard
27848
27849
27850 \size footnotesize
27851 \SpecialChar ~
27852 \SpecialChar ~
27853 mov a,r4
27854 \layout Standard
27855
27856
27857 \size footnotesize
27858 \SpecialChar ~
27859 \SpecialChar ~
27860 xrl a,#0x80
27861 \layout Standard
27862
27863
27864 \size footnotesize
27865 \SpecialChar ~
27866 \SpecialChar ~
27867 subb a,#0x8a
27868 \layout Standard
27869
27870
27871 \size footnotesize
27872 \SpecialChar ~
27873 \SpecialChar ~
27874 jnc 00107$
27875 \layout Standard
27876
27877
27878 \size footnotesize
27879 00115$:
27880 \layout Standard
27881
27882
27883 \size footnotesize
27884 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
27885 \layout Standard
27886
27887
27888 \size footnotesize
27889 ; iTemp21 [lr21:38]{short}[r4]
27890 \layout Standard
27891
27892
27893 \size footnotesize
27894 \SpecialChar ~
27895 \SpecialChar ~
27896 mov a,r4
27897 \layout Standard
27898
27899
27900 \size footnotesize
27901 \SpecialChar ~
27902 \SpecialChar ~
27903 add a,r2
27904 \layout Standard
27905
27906
27907 \size footnotesize
27908 \SpecialChar ~
27909 \SpecialChar ~
27910 mov r2,a
27911 \layout Standard
27912
27913
27914 \size footnotesize
27915 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
27916 \layout Standard
27917
27918
27919 \size footnotesize
27920 \SpecialChar ~
27921 \SpecialChar ~
27922 mov b,#0x03
27923 \layout Standard
27924
27925
27926 \size footnotesize
27927 \SpecialChar ~
27928 \SpecialChar ~
27929 mov a,r4
27930 \layout Standard
27931
27932
27933 \size footnotesize
27934 \SpecialChar ~
27935 \SpecialChar ~
27936 mul ab
27937 \layout Standard
27938
27939
27940 \size footnotesize
27941 \SpecialChar ~
27942 \SpecialChar ~
27943 mov r1,a
27944 \layout Standard
27945
27946
27947 \size footnotesize
27948 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
27949 \layout Standard
27950
27951
27952 \size footnotesize
27953 ; iTemp15 [lr29:30]{short}[r1]
27954 \layout Standard
27955
27956
27957 \size footnotesize
27958 \SpecialChar ~
27959 \SpecialChar ~
27960 add a,r3
27961 \layout Standard
27962
27963
27964 \size footnotesize
27965 \SpecialChar ~
27966 \SpecialChar ~
27967 mov r3,a
27968 \layout Standard
27969
27970
27971 \size footnotesize
27972 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
27973 \layout Standard
27974
27975
27976 \size footnotesize
27977 \SpecialChar ~
27978 \SpecialChar ~
27979 mov a,r7
27980 \layout Standard
27981
27982
27983 \size footnotesize
27984 \SpecialChar ~
27985 \SpecialChar ~
27986 add a,#0xfd
27987 \layout Standard
27988
27989
27990 \size footnotesize
27991 \SpecialChar ~
27992 \SpecialChar ~
27993 mov r7,a
27994 \layout Standard
27995
27996
27997 \size footnotesize
27998 \SpecialChar ~
27999 \SpecialChar ~
28000 mov a,r0
28001 \layout Standard
28002
28003
28004 \size footnotesize
28005 \SpecialChar ~
28006 \SpecialChar ~
28007 addc a,#0xff
28008 \layout Standard
28009
28010
28011 \size footnotesize
28012 \SpecialChar ~
28013 \SpecialChar ~
28014 mov r0,a
28015 \layout Standard
28016
28017
28018 \size footnotesize
28019 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
28020 \layout Standard
28021
28022
28023 \size footnotesize
28024 \SpecialChar ~
28025 \SpecialChar ~
28026 mov a,r7
28027 \layout Standard
28028
28029
28030 \size footnotesize
28031 \SpecialChar ~
28032 \SpecialChar ~
28033 add a,_gint
28034 \layout Standard
28035
28036
28037 \size footnotesize
28038 \SpecialChar ~
28039 \SpecialChar ~
28040 mov _gint,a
28041 \layout Standard
28042
28043
28044 \size footnotesize
28045 \SpecialChar ~
28046 \SpecialChar ~
28047 mov a,r0
28048 \layout Standard
28049
28050
28051 \size footnotesize
28052 \SpecialChar ~
28053 \SpecialChar ~
28054 addc a,(_gint + 1)
28055 \layout Standard
28056
28057
28058 \size footnotesize
28059 \SpecialChar ~
28060 \SpecialChar ~
28061 mov (_gint + 1),a
28062 \layout Standard
28063
28064
28065 \size footnotesize
28066 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
28067 \layout Standard
28068
28069
28070 \size footnotesize
28071 \SpecialChar ~
28072 \SpecialChar ~
28073 inc r4
28074 \layout Standard
28075
28076
28077 \size footnotesize
28078 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
28079 \layout Standard
28080
28081
28082 \size footnotesize
28083 \SpecialChar ~
28084 \SpecialChar ~
28085 dec r5
28086 \layout Standard
28087
28088
28089 \size footnotesize
28090 \SpecialChar ~
28091 \SpecialChar ~
28092 cjne r5,#0xff,00104$
28093 \layout Standard
28094
28095
28096 \size footnotesize
28097 \SpecialChar ~
28098 \SpecialChar ~
28099 dec r6
28100 \layout Standard
28101
28102
28103 \size footnotesize
28104 ; goto _forcond_0($4)
28105 \layout Standard
28106
28107
28108 \size footnotesize
28109 \SpecialChar ~
28110 \SpecialChar ~
28111 sjmp 00104$
28112 \layout Standard
28113
28114
28115 \size footnotesize
28116 ; _forbreak_0($7) :
28117 \layout Standard
28118
28119
28120 \size footnotesize
28121 00107$:
28122 \layout Standard
28123
28124
28125 \size footnotesize
28126 ; ret iTemp24 [lr40:41]{short}
28127 \layout Standard
28128
28129
28130 \size footnotesize
28131 \SpecialChar ~
28132 \SpecialChar ~
28133 mov a,r3
28134 \layout Standard
28135
28136
28137 \size footnotesize
28138 \SpecialChar ~
28139 \SpecialChar ~
28140 add a,r2
28141 \layout Standard
28142
28143
28144 \size footnotesize
28145 \SpecialChar ~
28146 \SpecialChar ~
28147 mov dpl,a
28148 \layout Standard
28149
28150
28151 \size footnotesize
28152 ; _return($8) :
28153 \layout Standard
28154
28155
28156 \size footnotesize
28157 00108$:
28158 \layout Standard
28159
28160
28161 \size footnotesize
28162 \SpecialChar ~
28163 \SpecialChar ~
28164 ret
28165 \newline
28166
28167 \layout Section
28168
28169 A few words about basic block successors, predecessors and dominators
28170 \layout Standard
28171
28172 Successors are basic blocks
28173 \begin_inset LatexCommand \index{Basic blocks}
28174
28175 \end_inset
28176
28177  that might execute after this basic block.
28178 \newline
28179 Predecessors are basic blocks that might execute before reaching this basic
28180  block.
28181 \newline
28182 Dominators are basic blocks that WILL execute before reaching this basic
28183  block.
28184 \newline
28185
28186 \layout Standard
28187
28188 [basic block 1]
28189 \layout Standard
28190
28191 if (something)
28192 \layout Standard
28193
28194 \SpecialChar ~
28195 \SpecialChar ~
28196 \SpecialChar ~
28197 \SpecialChar ~
28198 [basic block 2]
28199 \layout Standard
28200
28201 else
28202 \layout Standard
28203
28204 \SpecialChar ~
28205 \SpecialChar ~
28206 \SpecialChar ~
28207 \SpecialChar ~
28208 [basic block 3]
28209 \layout Standard
28210
28211 [basic block 4]
28212 \newline
28213
28214 \layout Standard
28215
28216 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
28217 \layout Standard
28218
28219 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
28220 \layout Standard
28221
28222 c) domVect of [BB4] = BB1 ...
28223  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
28224  was executed.
28225 \layout Chapter
28226
28227 Acknowledgments
28228 \layout Standard
28229
28230
28231 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
28232
28233 \end_inset
28234
28235
28236 \newline
28237
28238 \newline
28239
28240 \emph on
28241 Thanks to all the other volunteer developers who have helped with coding,
28242  testing, web-page creation, distribution sets, etc.
28243  You know who you are :-)
28244 \emph default
28245
28246 \newline
28247
28248 \layout Standard
28249
28250 This document was initially written by Sandeep Dutta
28251 \layout Standard
28252
28253 All product names mentioned herein may be trademarks
28254 \begin_inset LatexCommand \index{Trademarks}
28255
28256 \end_inset
28257
28258  of their respective companies.
28259
28260 \layout Section*
28261
28262 Alphabetical index
28263 \layout Standard
28264
28265 To avoid confusion, the installation and building options for SDCC itself
28266  (chapter 2) are not part of the index.
28267 \layout Standard
28268
28269
28270 \begin_inset LatexCommand \printindex{}
28271
28272 \end_inset
28273
28274
28275 \the_end