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

   1 #LyX 1.3 created this file. For more info see http://www.lyx.org/
   2 \lyxformat 221
   3 \textclass book
   4 \begin_preamble
   5 \pdfoptionpdfminorversion=3
   6 \usepackage[
   7   pdftitle={SDCC Compiler User Guide},
   8   pdfauthor={SDCC development team},
   9   pdfsubject={installation, user manual},
  10   pdfkeywords={8032 8051 ansi c compiler CPU DS390
  11                embedded GPL HC08 manual mcs51 microcontroller PIC Z80},
  12   colorlinks=true,
  13   linkcolor=blue] {hyperref}
  14 %
  15 \sloppy
  16 \tolerance=500
  17 \emergencystretch=30pt
  18 %
  19 \date{}
  20 \end_preamble
  21 \language english
  22 \inputencoding default
  23 \fontscheme pslatex
  24 \graphics default
  25 \paperfontsize default
  26 \spacing single
  27 \papersize letterpaper
  28 \paperpackage a4
  29 \use_geometry 1
  30 \use_amsmath 0
  31 \use_natbib 0
  32 \use_numerical_citations 0
  33 \paperorientation portrait
  34 \leftmargin 30mm
  35 \topmargin 20mm
  36 \rightmargin 25mm
  37 \bottommargin 20mm
  38 \secnumdepth 3
  39 \tocdepth 3
  40 \paragraph_separation indent
  41 \defskip medskip
  42 \quotes_language swedish
  43 \quotes_times 2
  44 \papercolumns 1
  45 \papersides 1
  46 \paperpagestyle fancy
  47
  48 \layout Comment
  49
  50 Please note: double dashed longoptions (e.g.
  51  --version) are written this way: -
  52 \begin_inset ERT
  53 status Collapsed
  54
  55 \layout Standard
  56
  57 \backslash
  58 /
  59 \end_inset
  60
  61 -
  62 \layout Comment
  63
  64 Two resp.
  65  three consecutive dashes simply result in a long resp.
  66  extra long dash.
  67 \layout Comment
  68
  69 Architecture specific stuff (like memory models, code examples) should maybe
  70  later go
  71 \layout Comment
  72
  73 into seperate sections/chapters/appendices (it is hard to document PIC or
  74  Z80 in
  75 \layout Comment
  76
  77 a 8051 centered document) - for now simply add.
  78 \layout Title
  79
  80 SDCC Compiler User Guide
  81 \layout Date
  82
  83
  84 \size normal
  85 SDCC 2.5.4
  86 \size footnotesize
  87
  88 \newline
  89 $Date$
  90 \newline
  91 $Revision$
  92 \layout Comment
  93
  94 The above strings enclosed in $ are automatically updated by cvs
  95 \layout Standard
  96
  97
  98 \begin_inset LatexCommand \tableofcontents{}
  99
 100 \end_inset
 101
 102
 103 \layout Chapter
 104
 105 Introduction
 106 \layout Section
 107
 108 About SDCC
 109 \layout Standard
 110
 111
 112 \series bold
 113 SDCC
 114 \series default
 115  (
 116 \emph on
 117 S
 118 \emph default
 119 mall
 120 \emph on
 121 D
 122 \emph default
 123 evice
 124 \emph on
 125 C
 126 \emph default
 127
 128 \emph on
 129 C
 130 \emph default
 131 ompiler) is an open source, retargettable, optimizing ANSI-C compiler by
 132
 133 \series bold
 134 Sandeep Dutta
 135 \series default
 136  designed for 8 bit Microprocessors.
 137  The current version targets Intel MCS51 based Microprocessors (8031, 8032,
 138  8051, 8052
 139 \begin_inset LatexCommand \index{8031, 8032, 8051, 8052, mcs51 CPU}
 140
 141 \end_inset
 142
 143 , etc.), Dallas DS80C390 variants, Freescale (formerly Motorola) HC08 and
 144  Zilog Z80 based MCUs.
 145  It can be retargetted for other microprocessors, support for Microchip
 146  PIC, Atmel AVR is under development.
 147  The entire source code for the compiler is distributed under GPL.
 148  SDCC uses ASXXXX
 149 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
 150
 151 \end_inset
 152
 153  & ASLINK
 154 \begin_inset LatexCommand \index{aslink}
 155
 156 \end_inset
 157
 158 , an open source retargettable assembler & linker.
 159  SDCC has extensive language extensions suitable for utilizing various microcont
 160 rollers and underlying hardware effectively.
 161
 162 \newline
 163
 164 \newline
 165 In addition to the MCU specific optimizations SDCC also does a host of standard
 166  optimizations like:
 167 \layout Itemize
 168
 169 global sub expression elimination,
 170 \layout Itemize
 171
 172 loop optimizations (loop invariant, strength reduction of induction variables
 173  and loop reversing),
 174 \layout Itemize
 175
 176 constant folding & propagation,
 177 \layout Itemize
 178
 179 copy propagation,
 180 \layout Itemize
 181
 182 dead code elimination
 183 \layout Itemize
 184
 185 jump tables for
 186 \emph on
 187 switch
 188 \emph default
 189  statements.
 190 \layout Standard
 191
 192 For the back-end SDCC uses a global register allocation scheme which should
 193  be well suited for other 8 bit MCUs.
 194
 195 \newline
 196
 197 \newline
 198 The peep hole optimizer uses a rule based substitution mechanism which is
 199  MCU independent.
 200
 201 \newline
 202
 203 \newline
 204 Supported data-types are:
 205 \layout Itemize
 206
 207 char (8 bits, 1 byte),
 208 \layout Itemize
 209
 210 short and int (16 bits, 2 bytes),
 211 \layout Itemize
 212
 213 long (32 bit, 4 bytes)
 214 \layout Itemize
 215
 216 float (4 byte IEEE).
 217
 218 \layout Standard
 219
 220 The compiler also allows
 221 \emph on
 222 inline assembler code
 223 \emph default
 224  to be embedded anywhere in a function.
 225  In addition, routines developed in assembly can also be called.
 226 \newline
 227
 228 \newline
 229 SDCC also provides an option (-
 230 \begin_inset ERT
 231 status Collapsed
 232
 233 \layout Standard
 234
 235 \backslash
 236 /
 237 \end_inset
 238
 239 -cyclomatic) to report the relative complexity of a function.
 240  These functions can then be further optimized, or hand coded in assembly
 241  if needed.
 242
 243 \newline
 244
 245 \newline
 246 SDCC also comes with a companion source level debugger SDCDB, the debugger
 247  currently uses ucSim a freeware simulator for 8051 and other micro-controllers.
 248
 249 \newline
 250
 251 \newline
 252 The latest version can be downloaded from
 253 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
 254
 255 \end_inset
 256
 257 .
 258
 259 \series bold
 260
 261 \series default
 262 \emph on
 263 Please note: the compiler will probably always be some steps ahead of this
 264  documentation
 265 \series bold
 266 \emph default
 267
 268 \begin_inset LatexCommand \index{Status of documentation}
 269
 270 \end_inset
 271
 272
 273 \begin_inset Foot
 274 collapsed false
 275
 276 \layout Standard
 277
 278 Obviously this has pros and cons
 279 \end_inset
 280
 281 .
 282 \layout Section
 283
 284 Open Source
 285 \layout Standard
 286
 287 All packages used in this compiler system are
 288 \emph on
 289 open source
 290 \emph default
 291  and
 292 \emph on
 293 freeware
 294 \emph default
 295 ; source code for all the sub-packages (pre-processor, assemblers, linkers
 296  etc) is distributed with the package.
 297  This documentation is maintained using a freeware word processor (LyX).
 298 \newline
 299 This program is free software; you can redistribute it and/or modify it
 300  under the terms of the GNU General Public License
 301 \begin_inset LatexCommand \index{GNU General Public License, GPL}
 302
 303 \end_inset
 304
 305  as published by the Free Software Foundation; either version 2, or (at
 306  your option) any later version.
 307  This program is distributed in the hope that it will be useful, but WITHOUT
 308  ANY WARRANTY; without even the implied warranty
 309 \begin_inset LatexCommand \index{warranty}
 310
 311 \end_inset
 312
 313  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 314  See the GNU General Public License for more details.
 315  You should have received a copy of the GNU General Public License along
 316  with this program; if not, write to the Free Software Foundation, 59 Temple
 317  Place - Suite 330, Boston, MA 02111-1307, USA.
 318  In other words, you are welcome to use, share and improve this program.
 319  You are forbidden to forbid anyone else to use, share and improve what
 320  you give them.
 321  Help stamp out software-hoarding!
 322 \layout Section
 323
 324 Typographic conventions
 325 \begin_inset LatexCommand \index{Typographic conventions}
 326
 327 \end_inset
 328
 329
 330 \layout Standard
 331
 332 Throughout this manual, we will use the following convention.
 333  Commands you have to type in are printed in
 334 \family sans
 335 \series bold
 336 "sans serif"
 337 \series default
 338 .
 339
 340 \family default
 341  Code samples are printed in
 342 \family typewriter
 343 typewriter font.
 344
 345 \family default
 346  Interesting items and new terms are printed in
 347 \emph on
 348 italic.
 349 \layout Section
 350
 351 Compatibility with previous versions
 352 \begin_inset LatexCommand \index{Compatibility with previous versions}
 353
 354 \end_inset
 355
 356
 357 \layout Standard
 358
 359 This version has numerous bug fixes compared with the previous version.
 360  But we also introduced some incompatibilities with older versions.
 361  Not just for the fun of it, but to make the compiler more stable, efficient
 362  and ANSI compliant
 363 \begin_inset LatexCommand \index{ANSI-compliance}
 364
 365 \end_inset
 366
 367  (see section
 368 \begin_inset LatexCommand \ref{sub:ANSI-Compliance}
 369
 370 \end_inset
 371
 372  for ANSI-Compliance).
 373
 374 \newline
 375
 376 \layout Itemize
 377
 378 short is now equivalent to int (16 bits), it used to be equivalent to char
 379  (8 bits) which is not ANSI compliant.
 380 \layout Itemize
 381
 382 the default directory for gcc-builds where include, library and documentation
 383  files are stored is now in /usr/local/share.
 384 \layout Itemize
 385
 386 char type parameters to vararg functions are casted to int unless explicitly
 387  casted, e.g.:
 388 \newline
 389
 390 \family typewriter
 391 \SpecialChar ~
 392 \SpecialChar ~
 393 char a=3;
 394 \newline
 395 \SpecialChar ~
 396 \SpecialChar ~
 397 printf ("%d %c
 398 \backslash
 399 n", a, (char)a);
 400 \family default
 401
 402 \newline
 403  will push a as an int and as a char resp.
 404 \layout Itemize
 405
 406 option -
 407 \begin_inset ERT
 408 status Collapsed
 409
 410 \layout Standard
 411
 412 \backslash
 413 /
 414 \end_inset
 415
 416 -regextend has been removed.
 417 \layout Itemize
 418
 419 option -
 420 \begin_inset ERT
 421 status Collapsed
 422
 423 \layout Standard
 424
 425 \backslash
 426 /
 427 \end_inset
 428
 429 -noregparms has been removed.
 430 \layout Itemize
 431
 432 option -
 433 \begin_inset ERT
 434 status Collapsed
 435
 436 \layout Standard
 437
 438 \backslash
 439 /
 440 \end_inset
 441
 442 -stack-after-data has been removed.
 443 \layout Itemize
 444
 445 bit
 446 \begin_inset LatexCommand \index{bit}
 447
 448 \end_inset
 449
 450  and sbit
 451 \begin_inset LatexCommand \index{sbit}
 452
 453 \end_inset
 454
 455
 456 \begin_inset LatexCommand \index{\_\_sbit}
 457
 458 \end_inset
 459
 460  types now consistently behave like the C99 _Bool type with respect to type
 461  conversion
 462 \begin_inset LatexCommand \index{type conversion}
 463
 464 \end_inset
 465
 466
 467 \begin_inset LatexCommand \index{type promotion}
 468
 469 \end_inset
 470
 471 .
 472  The most common incompatibility resulting from this change is related to
 473  bit toggling
 474 \begin_inset LatexCommand \index{Bit toggling}
 475
 476 \end_inset
 477
 478  idioms, e.g.:
 479 \newline
 480
 481 \family typewriter
 482 \SpecialChar ~
 483 \SpecialChar ~
 484 bit b;
 485 \newline
 486 \SpecialChar ~
 487 \SpecialChar ~
 488 b = ~b; /* equivalent to b=1 instead of toggling b */
 489 \newline
 490 \SpecialChar ~
 491 \SpecialChar ~
 492 b = !b; /* toggles b */
 493 \newline
 494
 495 \family default
 496 In previous versions, both forms would have toggled the bit.
 497 \layout Standard
 498
 499
 500 \emph on
 501 <pending: more incompatibilities?>
 502 \layout Section
 503
 504 System Requirements
 505 \layout Standard
 506
 507 What do you need before you start installation of SDCC? A computer, and
 508  a desire to compute.
 509  The preferred method of installation is to compile SDCC from source using
 510  GNU gcc and make.
 511  For Windows some pre-compiled binary distributions are available for your
 512  convenience.
 513  You should have some experience with command line tools and compiler use.
 514 \layout Section
 515
 516 Other Resources
 517 \layout Standard
 518
 519 The SDCC home page at
 520 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
 521
 522 \end_inset
 523
 524  is a great place to find distribution sets.
 525  You can also find links to the user mailing lists that offer help or discuss
 526  SDCC with other SDCC users.
 527  Web links to other SDCC related sites can also be found here.
 528  This document can be found in the DOC directory of the source package as
 529  a text or HTML file.
 530  A pdf version of this document is available at
 531 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
 532
 533 \end_inset
 534
 535 .
 536  Some of the other tools (simulator and assembler) included with SDCC contain
 537  their own documentation and can be found in the source distribution.
 538  If you want the latest unreleased software, the complete source package
 539  is available directly by anonymous CVS on cvs.sdcc.sourceforge.net.
 540 \layout Section
 541
 542 Wishes for the future
 543 \layout Standard
 544
 545 There are (and always will be) some things that could be done.
 546  Here are some I can think of:
 547 \newline
 548
 549 \layout Standard
 550
 551
 552 \family typewriter
 553 char KernelFunction3(char p) at 0x340;
 554 \newline
 555
 556 \layout Standard
 557
 558
 559 \family typewriter
 560 better code banking
 561 \begin_inset LatexCommand \index{code banking (limited support)}
 562
 563 \end_inset
 564
 565  support for mcs51
 566 \newline
 567
 568 \newline
 569
 570 \family default
 571 If you can think of some more, please see the section
 572 \begin_inset LatexCommand \ref{sub:Requesting-Features}
 573
 574 \end_inset
 575
 576  about filing feature requests
 577 \begin_inset LatexCommand \index{Requesting features}
 578
 579 \end_inset
 580
 581
 582 \begin_inset LatexCommand \index{Feature request}
 583
 584 \end_inset
 585
 586 .
 587 \newline
 588
 589 \layout Chapter
 590
 591 Installing SDCC
 592 \begin_inset LatexCommand \index{Installation}
 593
 594 \end_inset
 595
 596
 597 \layout Standard
 598
 599 For most users it is sufficient to skip to either section
 600 \begin_inset LatexCommand \ref{sub:Building-SDCC-on-Linux}
 601
 602 \end_inset
 603
 604  or section
 605 \begin_inset LatexCommand \ref{sub:Windows-Install}
 606
 607 \end_inset
 608
 609 .
 610  More detailled instructions follow below.
 611 \layout Section
 612
 613 Configure Options
 614 \begin_inset LatexCommand \index{Options SDCC configuration}
 615
 616 \end_inset
 617
 618
 619 \layout Standard
 620
 621 The install paths, search paths and other options are defined when running
 622  'configure'.
 623  The defaults can be overridden by:
 624 \layout List
 625 \labelwidthstring 00.00.0000
 626
 627 -
 628 \begin_inset ERT
 629 status Collapsed
 630
 631 \layout Standard
 632
 633 \backslash
 634 /
 635 \end_inset
 636
 637 -prefix see table below
 638 \layout List
 639 \labelwidthstring 00.00.0000
 640
 641 -
 642 \begin_inset ERT
 643 status Collapsed
 644
 645 \layout Standard
 646
 647 \backslash
 648 /
 649 \end_inset
 650
 651 -exec_prefix see table below
 652 \layout List
 653 \labelwidthstring 00.00.0000
 654
 655 -
 656 \begin_inset ERT
 657 status Collapsed
 658
 659 \layout Standard
 660
 661 \backslash
 662 /
 663 \end_inset
 664
 665 -bindir see table below
 666 \layout List
 667 \labelwidthstring 00.00.0000
 668
 669 -
 670 \begin_inset ERT
 671 status Collapsed
 672
 673 \layout Standard
 674
 675 \backslash
 676 /
 677 \end_inset
 678
 679 -datadir see table below
 680 \layout List
 681 \labelwidthstring 00.00.0000
 682
 683 docdir environment variable, see table below
 684 \layout List
 685 \labelwidthstring 00.00.0000
 686
 687 include_dir_suffix environment variable, see table below
 688 \layout List
 689 \labelwidthstring 00.00.0000
 690
 691 lib_dir_suffix environment variable, see table below
 692 \layout List
 693 \labelwidthstring 00.00.0000
 694
 695 sdccconf_h_dir_separator environment variable, either / or
 696 \backslash
 697
 698 \backslash
 699  makes sense here.
 700  This character will only be used in sdccconf.h; don't forget it's a C-header,
 701  therefore a double-backslash is needed there.
 702 \layout List
 703 \labelwidthstring 00.00.0000
 704
 705 -
 706 \begin_inset ERT
 707 status Collapsed
 708
 709 \layout Standard
 710
 711 \backslash
 712 /
 713 \end_inset
 714
 715 -disable-mcs51-port Excludes the Intel mcs51 port
 716 \layout List
 717 \labelwidthstring 00.00.0000
 718
 719 -
 720 \begin_inset ERT
 721 status Collapsed
 722
 723 \layout Standard
 724
 725 \backslash
 726 /
 727 \end_inset
 728
 729 -disable-gbz80-port Excludes the Gameboy gbz80 port
 730 \layout List
 731 \labelwidthstring 00.00.0000
 732
 733 -
 734 \begin_inset ERT
 735 status Collapsed
 736
 737 \layout Standard
 738
 739 \backslash
 740 /
 741 \end_inset
 742
 743 -disable-z80-port Excludes the z80 port
 744 \layout List
 745 \labelwidthstring 00.00.0000
 746
 747 -
 748 \begin_inset ERT
 749 status Collapsed
 750
 751 \layout Standard
 752
 753 \backslash
 754 /
 755 \end_inset
 756
 757 -disable-avr-port Excludes the AVR port
 758 \layout List
 759 \labelwidthstring 00.00.0000
 760
 761 -
 762 \begin_inset ERT
 763 status Collapsed
 764
 765 \layout Standard
 766
 767 \backslash
 768 /
 769 \end_inset
 770
 771 -disable-ds390-port Excludes the DS390 port
 772 \layout List
 773 \labelwidthstring 00.00.0000
 774
 775 -
 776 \begin_inset ERT
 777 status Collapsed
 778
 779 \layout Standard
 780
 781 \backslash
 782 /
 783 \end_inset
 784
 785 -disable-hc08-port Excludes the HC08 port
 786 \layout List
 787 \labelwidthstring 00.00.0000
 788
 789 -
 790 \begin_inset ERT
 791 status Collapsed
 792
 793 \layout Standard
 794
 795 \backslash
 796 /
 797 \end_inset
 798
 799 -disable-pic-port Excludes the PIC port
 800 \layout List
 801 \labelwidthstring 00.00.0000
 802
 803 -
 804 \begin_inset ERT
 805 status Collapsed
 806
 807 \layout Standard
 808
 809 \backslash
 810 /
 811 \end_inset
 812
 813 -disable-xa51-port Excludes the XA51 port
 814 \layout List
 815 \labelwidthstring 00.00.0000
 816
 817 -
 818 \begin_inset ERT
 819 status Collapsed
 820
 821 \layout Standard
 822
 823 \backslash
 824 /
 825 \end_inset
 826
 827 -disable-ucsim Disables configuring and building of ucsim
 828 \layout List
 829 \labelwidthstring 00.00.0000
 830
 831 -
 832 \begin_inset ERT
 833 status Collapsed
 834
 835 \layout Standard
 836
 837 \backslash
 838 /
 839 \end_inset
 840
 841 -disable-device-lib-build Disables automatically building device libraries
 842 \layout List
 843 \labelwidthstring 00.00.0000
 844
 845 -
 846 \begin_inset ERT
 847 status Collapsed
 848
 849 \layout Standard
 850
 851 \backslash
 852 /
 853 \end_inset
 854
 855 -disable-packihx Disables building packihx
 856 \layout List
 857 \labelwidthstring 00.00.0000
 858
 859 -
 860 \begin_inset ERT
 861 status Collapsed
 862
 863 \layout Standard
 864
 865 \backslash
 866 /
 867 \end_inset
 868
 869 -enable-libgc Use the Bohem memory allocator.
 870  Lower runtime footprint.
 871 \layout Standard
 872
 873 Furthermore the environment variables CC, CFLAGS, ...
 874  the tools and their arguments can be influenced.
 875  Please see `configure -
 876 \begin_inset ERT
 877 status Collapsed
 878
 879 \layout Standard
 880
 881 \backslash
 882 /
 883 \end_inset
 884
 885 -help` and the man/info pages of `configure` for details.
 886 \newline
 887
 888 \newline
 889 The names of the standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB,
 890  STD_FP_LIB, STD_DS390_LIB, STD_XA51_LIB and the environment variables SDCC_DIR_
 891 NAME, SDCC_INCLUDE_NAME, SDCC_LIB_NAME are defined by `configure` too.
 892  At the moment it's not possible to change the default settings (it was
 893  simply never required).
 894 \newline
 895
 896 \newline
 897 These configure options are compiled into the binaries, and can only be
 898  changed by rerunning 'configure' and recompiling SDCC.
 899  The configure options are written in
 900 \emph on
 901 italics
 902 \emph default
 903  to distinguish them from run time environment variables (see section search
 904  paths).
 905 \newline
 906
 907 \newline
 908 The settings for
 909 \begin_inset Quotes sld
 910 \end_inset
 911
 912 Win32 builds
 913 \begin_inset Quotes srd
 914 \end_inset
 915
 916  are used by the SDCC team to build the official Win32 binaries.
 917  The SDCC team uses Mingw32 to build the official Windows binaries, because
 918  it's
 919 \layout Enumerate
 920
 921 open source,
 922 \layout Enumerate
 923
 924 a gcc compiler and last but not least
 925 \layout Enumerate
 926
 927 the binaries can be built by cross compiling on Sourceforge's compile farm.
 928 \layout Standard
 929
 930 See the examples, how to pass the Win32 settings to 'configure'.
 931  The other Win32 builds using Borland, VC or whatever don't use 'configure',
 932  but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
 933  for Win32.
 934 \newline
 935
 936 \newline
 937 These defaults are:
 938 \newline
 939
 940 \layout Standard
 941 \align center
 942
 943 \begin_inset  Tabular
 944 <lyxtabular version="3" rows="8" columns="3">
 945 <features>
 946 <column alignment="block" valignment="top" leftline="true" width="0in">
 947 <column alignment="block" valignment="top" leftline="true" width="0in">
 948 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
 949 <row topline="true" bottomline="true">
 950 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 951 \begin_inset Text
 952
 953 \layout Standard
 954
 955 Variable
 956 \end_inset
 957 </cell>
 958 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 959 \begin_inset Text
 960
 961 \layout Standard
 962
 963 default
 964 \end_inset
 965 </cell>
 966 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 967 \begin_inset Text
 968
 969 \layout Standard
 970
 971 Win32 builds
 972 \end_inset
 973 </cell>
 974 </row>
 975 <row topline="true">
 976 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 977 \begin_inset Text
 978
 979 \layout Standard
 980
 981
 982 \emph on
 983 PREFIX
 984 \end_inset
 985 </cell>
 986 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 987 \begin_inset Text
 988
 989 \layout Standard
 990
 991 /usr/local
 992 \end_inset
 993 </cell>
 994 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 995 \begin_inset Text
 996
 997 \layout Standard
 998
 999
1000 \backslash
1001 sdcc
1002 \end_inset
1003 </cell>
1004 </row>
1005 <row topline="true">
1006 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1007 \begin_inset Text
1008
1009 \layout Standard
1010
1011
1012 \emph on
1013 EXEC_PREFIX
1014 \end_inset
1015 </cell>
1016 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1017 \begin_inset Text
1018
1019 \layout Standard
1020
1021
1022 \emph on
1023 $PREFIX
1024 \end_inset
1025 </cell>
1026 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1027 \begin_inset Text
1028
1029 \layout Standard
1030
1031
1032 \emph on
1033 $PREFIX
1034 \end_inset
1035 </cell>
1036 </row>
1037 <row topline="true">
1038 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1039 \begin_inset Text
1040
1041 \layout Standard
1042
1043
1044 \emph on
1045 BINDIR
1046 \end_inset
1047 </cell>
1048 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1049 \begin_inset Text
1050
1051 \layout Standard
1052
1053
1054 \emph on
1055 $EXECPREFIX
1056 \emph default
1057 /bin
1058 \end_inset
1059 </cell>
1060 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1061 \begin_inset Text
1062
1063 \layout Standard
1064
1065
1066 \emph on
1067 $EXECPREFIX
1068 \emph default
1069
1070 \backslash
1071 bin
1072 \end_inset
1073 </cell>
1074 </row>
1075 <row topline="true">
1076 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1077 \begin_inset Text
1078
1079 \layout Standard
1080
1081
1082 \emph on
1083 DATADIR
1084 \end_inset
1085 </cell>
1086 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1087 \begin_inset Text
1088
1089 \layout Standard
1090
1091
1092 \emph on
1093 $PREFIX
1094 \emph default
1095 /share
1096 \end_inset
1097 </cell>
1098 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1099 \begin_inset Text
1100
1101 \layout Standard
1102
1103
1104 \emph on
1105 $PREFIX
1106 \end_inset
1107 </cell>
1108 </row>
1109 <row topline="true">
1110 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1111 \begin_inset Text
1112
1113 \layout Standard
1114
1115
1116 \emph on
1117 DOCDIR
1118 \end_inset
1119 </cell>
1120 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1121 \begin_inset Text
1122
1123 \layout Standard
1124
1125
1126 \emph on
1127 $DATADIR
1128 \emph default
1129 /sdcc/doc
1130 \end_inset
1131 </cell>
1132 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1133 \begin_inset Text
1134
1135 \layout Standard
1136
1137
1138 \emph on
1139 $DATADIR
1140 \emph default
1141
1142 \backslash
1143 doc
1144 \end_inset
1145 </cell>
1146 </row>
1147 <row topline="true">
1148 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1149 \begin_inset Text
1150
1151 \layout Standard
1152
1153
1154 \emph on
1155 INCLUDE_DIR_SUFFIX
1156 \end_inset
1157 </cell>
1158 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1159 \begin_inset Text
1160
1161 \layout Standard
1162
1163 sdcc/include
1164 \end_inset
1165 </cell>
1166 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1167 \begin_inset Text
1168
1169 \layout Standard
1170
1171 include
1172 \end_inset
1173 </cell>
1174 </row>
1175 <row topline="true" bottomline="true">
1176 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1177 \begin_inset Text
1178
1179 \layout Standard
1180
1181
1182 \emph on
1183 LIB_DIR_SUFFIX
1184 \end_inset
1185 </cell>
1186 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1187 \begin_inset Text
1188
1189 \layout Standard
1190
1191 sdcc/lib
1192 \end_inset
1193 </cell>
1194 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1195 \begin_inset Text
1196
1197 \layout Standard
1198
1199 lib
1200 \end_inset
1201 </cell>
1202 </row>
1203 </lyxtabular>
1204
1205 \end_inset
1206
1207
1208 \newline
1209
1210 \layout Standard
1211 \noindent
1212 'configure' also computes relative paths.
1213  This is needed for full relocatability of a binary package and to complete
1214  search paths (see section search paths below):
1215 \newline
1216
1217 \layout Standard
1218 \align center
1219
1220 \begin_inset  Tabular
1221 <lyxtabular version="3" rows="4" columns="3">
1222 <features>
1223 <column alignment="block" valignment="top" leftline="true" width="0in">
1224 <column alignment="block" valignment="top" leftline="true" width="0in">
1225 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1226 <row topline="true" bottomline="true">
1227 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1228 \begin_inset Text
1229
1230 \layout Standard
1231
1232 Variable (computed)
1233 \end_inset
1234 </cell>
1235 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1236 \begin_inset Text
1237
1238 \layout Standard
1239
1240 default
1241 \end_inset
1242 </cell>
1243 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1244 \begin_inset Text
1245
1246 \layout Standard
1247
1248 Win32 builds
1249 \end_inset
1250 </cell>
1251 </row>
1252 <row topline="true" bottomline="true">
1253 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1254 \begin_inset Text
1255
1256 \layout Standard
1257
1258
1259 \emph on
1260 BIN2DATA_DIR
1261 \end_inset
1262 </cell>
1263 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1264 \begin_inset Text
1265
1266 \layout Standard
1267
1268 ../share
1269 \end_inset
1270 </cell>
1271 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1272 \begin_inset Text
1273
1274 \layout Standard
1275
1276 ..
1277 \end_inset
1278 </cell>
1279 </row>
1280 <row bottomline="true">
1281 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1282 \begin_inset Text
1283
1284 \layout Standard
1285
1286
1287 \emph on
1288 PREFIX2BIN_DIR
1289 \end_inset
1290 </cell>
1291 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1292 \begin_inset Text
1293
1294 \layout Standard
1295
1296 bin
1297 \end_inset
1298 </cell>
1299 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1300 \begin_inset Text
1301
1302 \layout Standard
1303
1304 bin
1305 \end_inset
1306 </cell>
1307 </row>
1308 <row bottomline="true">
1309 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1310 \begin_inset Text
1311
1312 \layout Standard
1313
1314
1315 \emph on
1316 PREFIX2DATA_DIR
1317 \end_inset
1318 </cell>
1319 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1320 \begin_inset Text
1321
1322 \layout Standard
1323
1324 share/sdcc
1325 \end_inset
1326 </cell>
1327 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1328 \begin_inset Text
1329
1330 \layout Standard
1331
1332 \end_inset
1333 </cell>
1334 </row>
1335 </lyxtabular>
1336
1337 \end_inset
1338
1339
1340 \newline
1341
1342 \layout Standard
1343 \noindent
1344 Examples:
1345 \layout LyX-Code
1346
1347 ./configure
1348 \newline
1349 ./configure -
1350 \begin_inset ERT
1351 status Collapsed
1352
1353 \layout Standard
1354
1355 \backslash
1356 /
1357 \end_inset
1358
1359 -prefix=
1360 \begin_inset Quotes srd
1361 \end_inset
1362
1363 /usr/bin
1364 \begin_inset Quotes srd
1365 \end_inset
1366
1367  -
1368 \begin_inset ERT
1369 status Collapsed
1370
1371 \layout Standard
1372
1373 \backslash
1374 /
1375 \end_inset
1376
1377 -datadir=
1378 \begin_inset Quotes srd
1379 \end_inset
1380
1381 /usr/share
1382 \begin_inset Quotes srd
1383 \end_inset
1384
1385
1386 \newline
1387 ./configure -
1388 \begin_inset ERT
1389 status Collapsed
1390
1391 \layout Standard
1392
1393 \backslash
1394 /
1395 \end_inset
1396
1397 -disable-avr-port -
1398 \begin_inset ERT
1399 status Collapsed
1400
1401 \layout Standard
1402
1403 \backslash
1404 /
1405 \end_inset
1406
1407 -disable-xa51-port
1408 \layout Standard
1409
1410 To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw
1411 32'):
1412 \layout LyX-Code
1413
1414 ./configure
1415 \backslash
1416
1417 \newline
1418 CC=
1419 \begin_inset Quotes srd
1420 \end_inset
1421
1422 i586-mingw32msvc-gcc
1423 \begin_inset Quotes srd
1424 \end_inset
1425
1426  CXX=
1427 \begin_inset Quotes srd
1428 \end_inset
1429
1430 i586-mingw32msvc-g++
1431 \begin_inset Quotes srd
1432 \end_inset
1433
1434
1435 \backslash
1436
1437 \newline
1438 RANLIB=
1439 \begin_inset Quotes srd
1440 \end_inset
1441
1442 i586-mingw32msvc-ranlib
1443 \begin_inset Quotes srd
1444 \end_inset
1445
1446
1447 \backslash
1448
1449 \newline
1450 STRIP=
1451 \begin_inset Quotes srd
1452 \end_inset
1453
1454 i586-mingw32msvc-strip
1455 \begin_inset Quotes srd
1456 \end_inset
1457
1458
1459 \backslash
1460
1461 \newline
1462 -
1463 \begin_inset ERT
1464 status Collapsed
1465
1466 \layout Standard
1467
1468 \backslash
1469 /
1470 \end_inset
1471
1472 -prefix=
1473 \begin_inset Quotes srd
1474 \end_inset
1475
1476 /sdcc
1477 \begin_inset Quotes srd
1478 \end_inset
1479
1480
1481 \backslash
1482
1483 \newline
1484 -
1485 \begin_inset ERT
1486 status Collapsed
1487
1488 \layout Standard
1489
1490 \backslash
1491 /
1492 \end_inset
1493
1494 -datadir=
1495 \begin_inset Quotes srd
1496 \end_inset
1497
1498 /sdcc
1499 \begin_inset Quotes srd
1500 \end_inset
1501
1502
1503 \backslash
1504
1505 \newline
1506 docdir=
1507 \begin_inset Quotes srd
1508 \end_inset
1509
1510 /sdcc/doc
1511 \begin_inset Quotes srd
1512 \end_inset
1513
1514
1515 \backslash
1516
1517 \newline
1518 include_dir_suffix=
1519 \begin_inset Quotes srd
1520 \end_inset
1521
1522 include
1523 \begin_inset Quotes srd
1524 \end_inset
1525
1526
1527 \backslash
1528
1529 \newline
1530 lib_dir_suffix=
1531 \begin_inset Quotes srd
1532 \end_inset
1533
1534 lib
1535 \begin_inset Quotes srd
1536 \end_inset
1537
1538
1539 \backslash
1540
1541 \newline
1542 sdccconf_h_dir_separator=
1543 \begin_inset Quotes srd
1544 \end_inset
1545
1546
1547 \backslash
1548
1549 \backslash
1550
1551 \backslash
1552
1553 \backslash
1554
1555 \begin_inset Quotes srd
1556 \end_inset
1557
1558
1559 \backslash
1560
1561 \newline
1562 -
1563 \begin_inset ERT
1564 status Collapsed
1565
1566 \layout Standard
1567
1568 \backslash
1569 /
1570 \end_inset
1571
1572 -disable-device-lib-build
1573 \backslash
1574
1575 \newline
1576 -
1577 \begin_inset ERT
1578 status Collapsed
1579
1580 \layout Standard
1581
1582 \backslash
1583 /
1584 \end_inset
1585
1586 -disable-ucsim
1587 \backslash
1588
1589 \newline
1590 -
1591 \begin_inset ERT
1592 status Collapsed
1593
1594 \layout Standard
1595
1596 \backslash
1597 /
1598 \end_inset
1599
1600 -host=i586-mingw32msvc -
1601 \begin_inset ERT
1602 status Collapsed
1603
1604 \layout Standard
1605
1606 \backslash
1607 /
1608 \end_inset
1609
1610 -build=unknown-unknown-linux-gnu
1611 \layout Standard
1612
1613 To
1614 \begin_inset Quotes sld
1615 \end_inset
1616
1617 cross
1618 \begin_inset Quotes srd
1619 \end_inset
1620
1621 compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32
1622 ):
1623 \layout LyX-Code
1624
1625 ./configure -C
1626 \backslash
1627
1628 \newline
1629 CFLAGS=
1630 \begin_inset Quotes srd
1631 \end_inset
1632
1633 -mno-cygwin -O2
1634 \begin_inset Quotes srd
1635 \end_inset
1636
1637
1638 \backslash
1639
1640 \newline
1641 LDFLAGS=
1642 \begin_inset Quotes srd
1643 \end_inset
1644
1645 -mno-cygwin
1646 \begin_inset Quotes srd
1647 \end_inset
1648
1649
1650 \backslash
1651
1652 \newline
1653 -
1654 \begin_inset ERT
1655 status Collapsed
1656
1657 \layout Standard
1658
1659 \backslash
1660 /
1661 \end_inset
1662
1663 -prefix=
1664 \begin_inset Quotes srd
1665 \end_inset
1666
1667 /sdcc
1668 \begin_inset Quotes srd
1669 \end_inset
1670
1671
1672 \backslash
1673
1674 \newline
1675 -
1676 \begin_inset ERT
1677 status Collapsed
1678
1679 \layout Standard
1680
1681 \backslash
1682 /
1683 \end_inset
1684
1685 -datadir=
1686 \begin_inset Quotes srd
1687 \end_inset
1688
1689 /sdcc
1690 \begin_inset Quotes srd
1691 \end_inset
1692
1693
1694 \backslash
1695
1696 \newline
1697 docdir=
1698 \begin_inset Quotes srd
1699 \end_inset
1700
1701 /sdcc/doc
1702 \begin_inset Quotes srd
1703 \end_inset
1704
1705
1706 \backslash
1707
1708 \newline
1709 include_dir_suffix=
1710 \begin_inset Quotes srd
1711 \end_inset
1712
1713 include
1714 \begin_inset Quotes srd
1715 \end_inset
1716
1717
1718 \backslash
1719
1720 \newline
1721 lib_dir_suffix=
1722 \begin_inset Quotes srd
1723 \end_inset
1724
1725 lib
1726 \begin_inset Quotes srd
1727 \end_inset
1728
1729
1730 \backslash
1731
1732 \newline
1733 sdccconf_h_dir_separator=
1734 \begin_inset Quotes srd
1735 \end_inset
1736
1737
1738 \backslash
1739
1740 \backslash
1741
1742 \backslash
1743
1744 \backslash
1745
1746 \begin_inset Quotes srd
1747 \end_inset
1748
1749
1750 \backslash
1751
1752 \newline
1753 -
1754 \begin_inset ERT
1755 status Collapsed
1756
1757 \layout Standard
1758
1759 \backslash
1760 /
1761 \end_inset
1762
1763 -disable-ucsim
1764 \layout Standard
1765
1766 'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
1767  The option '-
1768 \begin_inset ERT
1769 status Collapsed
1770
1771 \layout Standard
1772
1773 \backslash
1774 /
1775 \end_inset
1776
1777 -C' turns on caching, which gives a little bit extra speed.
1778  However if options are changed, it can be necessary to delete the config.cache
1779  file.
1780 \layout Section
1781
1782 Install paths
1783 \begin_inset LatexCommand \label{sub:Install-paths}
1784
1785 \end_inset
1786
1787
1788 \begin_inset LatexCommand \index{Install paths}
1789
1790 \end_inset
1791
1792
1793 \layout Standard
1794 \added_space_top medskip \align center
1795
1796 \begin_inset  Tabular
1797 <lyxtabular version="3" rows="5" columns="4">
1798 <features>
1799 <column alignment="center" valignment="top" leftline="true" width="0">
1800 <column alignment="center" valignment="top" leftline="true" width="0">
1801 <column alignment="center" valignment="top" leftline="true" width="0">
1802 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
1803 <row topline="true" bottomline="true">
1804 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1805 \begin_inset Text
1806
1807 \layout Standard
1808
1809
1810 \series bold
1811 Description
1812 \end_inset
1813 </cell>
1814 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1815 \begin_inset Text
1816
1817 \layout Standard
1818
1819
1820 \series bold
1821 Path
1822 \end_inset
1823 </cell>
1824 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1825 \begin_inset Text
1826
1827 \layout Standard
1828
1829
1830 \series bold
1831 Default
1832 \end_inset
1833 </cell>
1834 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1835 \begin_inset Text
1836
1837 \layout Standard
1838
1839
1840 \series bold
1841 Win32 builds
1842 \end_inset
1843 </cell>
1844 </row>
1845 <row topline="true">
1846 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1847 \begin_inset Text
1848
1849 \layout Standard
1850
1851 Binary files*
1852 \end_inset
1853 </cell>
1854 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1855 \begin_inset Text
1856
1857 \layout Standard
1858
1859
1860 \emph on
1861 $EXEC_PREFIX
1862 \end_inset
1863 </cell>
1864 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1865 \begin_inset Text
1866
1867 \layout Standard
1868
1869 /usr/local/bin
1870 \end_inset
1871 </cell>
1872 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1873 \begin_inset Text
1874
1875 \layout Standard
1876
1877
1878 \backslash
1879 sdcc
1880 \backslash
1881 bin
1882 \end_inset
1883 </cell>
1884 </row>
1885 <row topline="true">
1886 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1887 \begin_inset Text
1888
1889 \layout Standard
1890
1891 Include files
1892 \end_inset
1893 </cell>
1894 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1895 \begin_inset Text
1896
1897 \layout Standard
1898
1899
1900 \emph on
1901 $DATADIR/ $INCLUDE_DIR_SUFFIX
1902 \end_inset
1903 </cell>
1904 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1905 \begin_inset Text
1906
1907 \layout Standard
1908
1909 /usr/local/share/sdcc/include
1910 \end_inset
1911 </cell>
1912 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1913 \begin_inset Text
1914
1915 \layout Standard
1916
1917
1918 \backslash
1919 sdcc
1920 \backslash
1921 include
1922 \end_inset
1923 </cell>
1924 </row>
1925 <row topline="true">
1926 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1927 \begin_inset Text
1928
1929 \layout Standard
1930
1931 Library file**
1932 \end_inset
1933 </cell>
1934 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1935 \begin_inset Text
1936
1937 \layout Standard
1938
1939
1940 \emph on
1941 $DATADIR/$LIB_DIR_SUFFIX
1942 \end_inset
1943 </cell>
1944 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1945 \begin_inset Text
1946
1947 \layout Standard
1948
1949 /usr/local/share/sdcc/lib
1950 \end_inset
1951 </cell>
1952 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1953 \begin_inset Text
1954
1955 \layout Standard
1956
1957
1958 \backslash
1959 sdcc
1960 \backslash
1961 lib
1962 \end_inset
1963 </cell>
1964 </row>
1965 <row topline="true" bottomline="true">
1966 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1967 \begin_inset Text
1968
1969 \layout Standard
1970
1971 Documentation
1972 \end_inset
1973 </cell>
1974 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1975 \begin_inset Text
1976
1977 \layout Standard
1978
1979
1980 \emph on
1981 $DOCDIR
1982 \end_inset
1983 </cell>
1984 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1985 \begin_inset Text
1986
1987 \layout Standard
1988
1989 /usr/local/share/sdcc/doc
1990 \end_inset
1991 </cell>
1992 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1993 \begin_inset Text
1994
1995 \layout Standard
1996
1997
1998 \backslash
1999 sdcc
2000 \backslash
2001 doc
2002 \end_inset
2003 </cell>
2004 </row>
2005 </lyxtabular>
2006
2007 \end_inset
2008
2009
2010 \layout Verse
2011
2012
2013 \size footnotesize
2014 *compiler, preprocessor, assembler, and linker
2015 \newline
2016 **the
2017 \shape italic
2018 model
2019 \shape default
2020  is auto-appended by the compiler, e.g.
2021  small, large, z80, ds390 etc
2022 \layout Standard
2023 \noindent
2024 The install paths can still be changed during `make install` with e.g.:
2025 \layout LyX-Code
2026
2027 make install prefix=$(HOME)/local/sdcc
2028 \layout Standard
2029
2030 Of course this doesn't change the search paths compiled into the binaries.
2031 \newline
2032
2033 \newline
2034 Moreover the install path can be changed by defining DESTDIR
2035 \begin_inset LatexCommand \index{DESTDIR}
2036
2037 \end_inset
2038
2039 :
2040 \layout LyX-Code
2041
2042 make install DESTDIR=$(HOME)/sdcc.rpm/
2043 \layout Standard
2044
2045 Please note that DESTDIR must have a trailing slash!
2046 \layout Section
2047
2048 Search Paths
2049 \begin_inset LatexCommand \label{sub:Search-Paths}
2050
2051 \end_inset
2052
2053
2054 \begin_inset LatexCommand \index{Search path}
2055
2056 \end_inset
2057
2058
2059 \layout Standard
2060
2061 Some search paths or parts of them are determined by configure variables
2062  (in
2063 \emph on
2064 italics
2065 \emph default
2066 , see section above).
2067  Further search paths are determined by environment variables during runtime.
2068
2069 \newline
2070 The paths searched when running the compiler are as follows (the first catch
2071  wins):
2072 \newline
2073
2074 \newline
2075 1.
2076  Binary files (preprocessor, assembler and linker)
2077 \newline
2078
2079 \layout Standard
2080 \align center
2081
2082 \begin_inset  Tabular
2083 <lyxtabular version="3" rows="4" columns="3">
2084 <features>
2085 <column alignment="block" valignment="top" leftline="true" width="0in">
2086 <column alignment="block" valignment="top" leftline="true" width="0in">
2087 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2088 <row topline="true" bottomline="true">
2089 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2090 \begin_inset Text
2091
2092 \layout Standard
2093
2094 Search path
2095 \end_inset
2096 </cell>
2097 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2098 \begin_inset Text
2099
2100 \layout Standard
2101
2102 default
2103 \end_inset
2104 </cell>
2105 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2106 \begin_inset Text
2107
2108 \layout Standard
2109
2110 Win32 builds
2111 \end_inset
2112 </cell>
2113 </row>
2114 <row topline="true">
2115 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2116 \begin_inset Text
2117
2118 \layout Standard
2119
2120 $SDCC_HOME/
2121 \emph on
2122 $PPREFIX2BIN_DIR
2123 \end_inset
2124 </cell>
2125 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2126 \begin_inset Text
2127
2128 \layout Standard
2129
2130 $SDCC_HOME/bin
2131 \end_inset
2132 </cell>
2133 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2134 \begin_inset Text
2135
2136 \layout Standard
2137
2138 $SDCC_HOME
2139 \backslash
2140 bin
2141 \end_inset
2142 </cell>
2143 </row>
2144 <row topline="true">
2145 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2146 \begin_inset Text
2147
2148 \layout Standard
2149
2150 Path of argv[0] (if available)
2151 \end_inset
2152 </cell>
2153 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2154 \begin_inset Text
2155
2156 \layout Standard
2157
2158 Path of argv[0]
2159 \end_inset
2160 </cell>
2161 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2162 \begin_inset Text
2163
2164 \layout Standard
2165
2166 Path of argv[0]
2167 \end_inset
2168 </cell>
2169 </row>
2170 <row topline="true" bottomline="true">
2171 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2172 \begin_inset Text
2173
2174 \layout Standard
2175
2176 $PATH
2177 \end_inset
2178 </cell>
2179 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2180 \begin_inset Text
2181
2182 \layout Standard
2183
2184 $PATH
2185 \end_inset
2186 </cell>
2187 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2188 \begin_inset Text
2189
2190 \layout Standard
2191
2192 $PATH
2193 \end_inset
2194 </cell>
2195 </row>
2196 </lyxtabular>
2197
2198 \end_inset
2199
2200
2201 \newline
2202
2203 \layout Standard
2204 \noindent
2205 2.
2206  Include files
2207 \newline
2208
2209 \layout Standard
2210 \align center
2211
2212 \begin_inset  Tabular
2213 <lyxtabular version="3" rows="6" columns="3">
2214 <features>
2215 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2216 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2217 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2218 <row topline="true" bottomline="true">
2219 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2220 \begin_inset Text
2221
2222 \layout Standard
2223
2224 Search path
2225 \end_inset
2226 </cell>
2227 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2228 \begin_inset Text
2229
2230 \layout Standard
2231
2232 default
2233 \end_inset
2234 </cell>
2235 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2236 \begin_inset Text
2237
2238 \layout Standard
2239
2240 Win32 builds
2241 \end_inset
2242 </cell>
2243 </row>
2244 <row topline="true">
2245 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2246 \begin_inset Text
2247
2248 \layout Standard
2249
2250 -
2251 \begin_inset ERT
2252 status Collapsed
2253
2254 \layout Standard
2255
2256 \backslash
2257 /
2258 \end_inset
2259
2260 -I dir
2261 \end_inset
2262 </cell>
2263 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2264 \begin_inset Text
2265
2266 \layout Standard
2267
2268 -
2269 \begin_inset ERT
2270 status Collapsed
2271
2272 \layout Standard
2273
2274 \backslash
2275 /
2276 \end_inset
2277
2278 -I dir
2279 \end_inset
2280 </cell>
2281 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2282 \begin_inset Text
2283
2284 \layout Standard
2285
2286 -
2287 \begin_inset ERT
2288 status Collapsed
2289
2290 \layout Standard
2291
2292 \backslash
2293 /
2294 \end_inset
2295
2296 -I dir
2297 \end_inset
2298 </cell>
2299 </row>
2300 <row topline="true">
2301 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2302 \begin_inset Text
2303
2304 \layout Standard
2305
2306 $SDCC_INCLUDE
2307 \end_inset
2308 </cell>
2309 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2310 \begin_inset Text
2311
2312 \layout Standard
2313
2314 $SDCC_INCLUDE
2315 \end_inset
2316 </cell>
2317 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2318 \begin_inset Text
2319
2320 \layout Standard
2321
2322 $SDCC_INCLUDE
2323 \end_inset
2324 </cell>
2325 </row>
2326 <row topline="true">
2327 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2328 \begin_inset Text
2329
2330 \layout Standard
2331
2332 $SDCC_HOME/
2333 \newline
2334
2335 \emph on
2336 $PREFIX2DATA_DIR/
2337 \newline
2338 $INCLUDE_DIR_SUFFIX
2339 \end_inset
2340 </cell>
2341 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2342 \begin_inset Text
2343
2344 \layout Standard
2345
2346 $SDCC_ HOME/
2347 \newline
2348 share/sdcc/
2349 \newline
2350 include
2351 \end_inset
2352 </cell>
2353 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2354 \begin_inset Text
2355
2356 \layout Standard
2357
2358 $SDCC_HOME
2359 \backslash
2360 include
2361 \end_inset
2362 </cell>
2363 </row>
2364 <row topline="true">
2365 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2366 \begin_inset Text
2367
2368 \layout Standard
2369
2370 path(argv[0])/
2371 \newline
2372
2373 \emph on
2374 $BIN2DATADIR/
2375 \emph default
2376
2377 \newline
2378
2379 \emph on
2380 $INCLUDE_DIR_SUFFIX
2381 \end_inset
2382 </cell>
2383 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2384 \begin_inset Text
2385
2386 \layout Standard
2387
2388 path(argv[0])/
2389 \newline
2390 ../sdcc/include
2391 \newline
2392 \SpecialChar ~
2393 \SpecialChar ~
2394 \SpecialChar ~
2395 \SpecialChar ~
2396 \SpecialChar ~
2397 \SpecialChar ~
2398 \SpecialChar ~
2399 \SpecialChar ~
2400 \SpecialChar ~
2401 \SpecialChar ~
2402 \SpecialChar ~
2403 \SpecialChar ~
2404 \SpecialChar ~
2405 \SpecialChar ~
2406 \SpecialChar ~
2407 \SpecialChar ~
2408 \SpecialChar ~
2409 \SpecialChar ~
2410 \SpecialChar ~
2411 \SpecialChar ~
2412 \SpecialChar ~
2413 \SpecialChar ~
2414 \SpecialChar ~
2415 \SpecialChar ~
2416 \SpecialChar ~
2417 \SpecialChar ~
2418 \SpecialChar ~
2419 \SpecialChar ~
2420 \SpecialChar ~
2421 \SpecialChar ~
2422 \SpecialChar ~
2423 \SpecialChar ~
2424 \SpecialChar ~
2425 \SpecialChar ~
2426 \SpecialChar ~
2427 \SpecialChar ~
2428 \SpecialChar ~
2429 \SpecialChar ~
2430
2431 \end_inset
2432 </cell>
2433 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2434 \begin_inset Text
2435
2436 \layout Standard
2437
2438 path(argv[0])
2439 \backslash
2440 ..
2441 \backslash
2442 include
2443 \end_inset
2444 </cell>
2445 </row>
2446 <row topline="true" bottomline="true">
2447 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2448 \begin_inset Text
2449
2450 \layout Standard
2451
2452
2453 \emph on
2454 $DATADIR/
2455 \emph default
2456
2457 \newline
2458
2459 \emph on
2460 $INCLUDE_DIR_SUFFIX
2461 \end_inset
2462 </cell>
2463 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2464 \begin_inset Text
2465
2466 \layout Standard
2467
2468 /usr/local/share/sdcc/
2469 \newline
2470 include
2471 \end_inset
2472 </cell>
2473 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2474 \begin_inset Text
2475
2476 \layout Standard
2477
2478 (not on Win32)
2479 \end_inset
2480 </cell>
2481 </row>
2482 </lyxtabular>
2483
2484 \end_inset
2485
2486
2487 \newline
2488
2489 \layout Standard
2490 \noindent
2491 The option -
2492 \begin_inset ERT
2493 status Collapsed
2494
2495 \layout Standard
2496
2497 \backslash
2498 /
2499 \end_inset
2500
2501 -nostdinc disables the last two search paths.
2502 \newline
2503
2504 \newline
2505 3.
2506  Library files
2507 \newline
2508
2509 \layout Standard
2510
2511 With the exception of
2512 \begin_inset Quotes sld
2513 \end_inset
2514
2515 -
2516 \begin_inset ERT
2517 status Collapsed
2518
2519 \layout Standard
2520
2521 \backslash
2522 /
2523 \end_inset
2524
2525 -L dir
2526 \begin_inset Quotes srd
2527 \end_inset
2528
2529  the
2530 \shape italic
2531 model
2532 \shape default
2533  is auto-appended by the compiler (e.g.
2534  small, large, z80, ds390 etc.).
2535
2536 \newline
2537
2538 \layout Standard
2539 \align center
2540
2541 \begin_inset  Tabular
2542 <lyxtabular version="3" rows="6" columns="3">
2543 <features>
2544 <column alignment="block" valignment="top" leftline="true" width="1.7in">
2545 <column alignment="block" valignment="top" leftline="true" width="1.2in">
2546 <column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
2547 <row topline="true" bottomline="true">
2548 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2549 \begin_inset Text
2550
2551 \layout Standard
2552
2553 Search path
2554 \end_inset
2555 </cell>
2556 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2557 \begin_inset Text
2558
2559 \layout Standard
2560
2561 default
2562 \end_inset
2563 </cell>
2564 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2565 \begin_inset Text
2566
2567 \layout Standard
2568
2569 Win32 builds
2570 \end_inset
2571 </cell>
2572 </row>
2573 <row topline="true">
2574 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2575 \begin_inset Text
2576
2577 \layout Standard
2578
2579 -
2580 \begin_inset ERT
2581 status Collapsed
2582
2583 \layout Standard
2584
2585 \backslash
2586 /
2587 \end_inset
2588
2589 -L dir
2590 \end_inset
2591 </cell>
2592 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2593 \begin_inset Text
2594
2595 \layout Standard
2596
2597 -
2598 \begin_inset ERT
2599 status Collapsed
2600
2601 \layout Standard
2602
2603 \backslash
2604 /
2605 \end_inset
2606
2607 -L dir
2608 \end_inset
2609 </cell>
2610 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2611 \begin_inset Text
2612
2613 \layout Standard
2614
2615 -
2616 \begin_inset ERT
2617 status Collapsed
2618
2619 \layout Standard
2620
2621 \backslash
2622 /
2623 \end_inset
2624
2625 -L dir
2626 \end_inset
2627 </cell>
2628 </row>
2629 <row topline="true">
2630 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2631 \begin_inset Text
2632
2633 \layout Standard
2634
2635 $SDCC_LIB/
2636 \newline
2637
2638 \emph on
2639 <model>
2640 \end_inset
2641 </cell>
2642 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2643 \begin_inset Text
2644
2645 \layout Standard
2646
2647 $SDCC_LIB/
2648 \newline
2649
2650 \emph on
2651 <model>
2652 \end_inset
2653 </cell>
2654 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2655 \begin_inset Text
2656
2657 \layout Standard
2658
2659 $SDCC_LIB
2660 \backslash
2661
2662 \newline
2663
2664 \emph on
2665 <model>
2666 \end_inset
2667 </cell>
2668 </row>
2669 <row topline="true">
2670 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2671 \begin_inset Text
2672
2673 \layout Standard
2674
2675 $SDCC_HOME/
2676 \newline
2677
2678 \emph on
2679 $PREFIX2DATA_DIR/
2680 \newline
2681 $LIB_DIR_SUFFIX/<model>
2682 \end_inset
2683 </cell>
2684 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2685 \begin_inset Text
2686
2687 \layout Standard
2688
2689 $SDCC_HOME/
2690 \newline
2691 share/sdcc/
2692 \newline
2693 lib/
2694 \emph on
2695 <model>
2696 \end_inset
2697 </cell>
2698 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2699 \begin_inset Text
2700
2701 \layout Standard
2702
2703 $SDCC_HOME
2704 \backslash
2705 lib
2706 \backslash
2707
2708 \emph on
2709
2710 \newline
2711 <model>
2712 \end_inset
2713 </cell>
2714 </row>
2715 <row topline="true">
2716 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2717 \begin_inset Text
2718
2719 \layout Standard
2720
2721 path(argv[0])/
2722 \newline
2723
2724 \emph on
2725 $BIN2DATADIR/
2726 \emph default
2727
2728 \newline
2729
2730 \emph on
2731 $LIB_DIR_SUFFIX/<model>
2732 \end_inset
2733 </cell>
2734 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2735 \begin_inset Text
2736
2737 \layout Standard
2738
2739 path(argv[0])/
2740 \newline
2741 ../sdcc/lib/
2742 \emph on
2743 <model>
2744 \newline
2745 \SpecialChar ~
2746 \SpecialChar ~
2747 \SpecialChar ~
2748 \SpecialChar ~
2749 \SpecialChar ~
2750 \SpecialChar ~
2751 \SpecialChar ~
2752 \SpecialChar ~
2753 \SpecialChar ~
2754 \SpecialChar ~
2755 \SpecialChar ~
2756 \SpecialChar ~
2757 \SpecialChar ~
2758 \SpecialChar ~
2759 \SpecialChar ~
2760 \SpecialChar ~
2761 \SpecialChar ~
2762 \SpecialChar ~
2763 \SpecialChar ~
2764 \SpecialChar ~
2765 \SpecialChar ~
2766 \SpecialChar ~
2767 \SpecialChar ~
2768 \SpecialChar ~
2769 \SpecialChar ~
2770 \SpecialChar ~
2771 \SpecialChar ~
2772 \SpecialChar ~
2773 \SpecialChar ~
2774 \SpecialChar ~
2775 \SpecialChar ~
2776 \SpecialChar ~
2777 \SpecialChar ~
2778 \SpecialChar ~
2779 \SpecialChar ~
2780 \SpecialChar ~
2781 \SpecialChar ~
2782 \SpecialChar ~
2783 \SpecialChar ~
2784
2785 \end_inset
2786 </cell>
2787 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2788 \begin_inset Text
2789
2790 \layout Standard
2791
2792 path(argv[0])
2793 \backslash
2794
2795 \newline
2796 ..
2797 \backslash
2798 lib
2799 \backslash
2800
2801 \emph on
2802 <model>
2803 \newline
2804 \SpecialChar ~
2805 \SpecialChar ~
2806 \SpecialChar ~
2807 \SpecialChar ~
2808 \SpecialChar ~
2809 \SpecialChar ~
2810 \SpecialChar ~
2811 \SpecialChar ~
2812 \SpecialChar ~
2813 \SpecialChar ~
2814 \SpecialChar ~
2815 \SpecialChar ~
2816 \SpecialChar ~
2817 \SpecialChar ~
2818 \SpecialChar ~
2819 \SpecialChar ~
2820 \SpecialChar ~
2821 \SpecialChar ~
2822 \SpecialChar ~
2823 \SpecialChar ~
2824 \SpecialChar ~
2825 \SpecialChar ~
2826 \SpecialChar ~
2827 \SpecialChar ~
2828 \SpecialChar ~
2829 \SpecialChar ~
2830 \SpecialChar ~
2831 \SpecialChar ~
2832 \SpecialChar ~
2833 \SpecialChar ~
2834 \SpecialChar ~
2835 \SpecialChar ~
2836 \SpecialChar ~
2837 \SpecialChar ~
2838 \SpecialChar ~
2839
2840 \end_inset
2841 </cell>
2842 </row>
2843 <row topline="true" bottomline="true">
2844 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2845 \begin_inset Text
2846
2847 \layout Standard
2848
2849
2850 \emph on
2851 $DATADIR/
2852 \newline
2853 $LIB_DIR_SUFFIX/<model>
2854 \end_inset
2855 </cell>
2856 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2857 \begin_inset Text
2858
2859 \layout Standard
2860
2861 /usr/local/share/sdcc/
2862 \newline
2863 lib/
2864 \emph on
2865 <model>
2866 \end_inset
2867 </cell>
2868 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2869 \begin_inset Text
2870
2871 \layout Standard
2872
2873 (not on Win32)
2874 \end_inset
2875 </cell>
2876 </row>
2877 </lyxtabular>
2878
2879 \end_inset
2880
2881
2882 \newline
2883
2884 \layout Comment
2885
2886 Don't delete any of the stray spaces in the table above without checking
2887  the HTML output (last line)!
2888 \layout Standard
2889
2890 \SpecialChar ~
2891
2892 \newline
2893 The option -
2894 \begin_inset ERT
2895 status Collapsed
2896
2897 \layout Standard
2898
2899 \backslash
2900 /
2901 \end_inset
2902
2903 -nostdlib disables the last two search paths.
2904 \layout Section
2905
2906 Building SDCC
2907 \begin_inset LatexCommand \index{Building SDCC}
2908
2909 \end_inset
2910
2911
2912 \layout Subsection
2913
2914 Building SDCC on Linux
2915 \begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux}
2916
2917 \end_inset
2918
2919
2920 \layout Enumerate
2921
2922
2923 \series medium
2924 Download the source package
2925 \series default
2926  either from the SDCC CVS repository or from the nightly snapshots
2927 \series medium
2928 , it will be named something like sdcc
2929 \series default
2930 .src
2931 \series medium
2932 .t
2933 \series default
2934 ar.
2935 \series medium
2936 gz
2937 \series default
2938
2939 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
2940
2941 \end_inset
2942
2943 .
2944 \layout Enumerate
2945
2946
2947 \series medium
2948 Bring up a command line terminal, such as xterm.
2949 \layout Enumerate
2950
2951
2952 \series medium
2953 Unpack the file using a command like:
2954 \family sans
2955 \series bold
2956 "tar -xvzf sdcc.src.tar.gz
2957 \family default
2958 \series default
2959 "
2960 \series medium
2961 , this will create a sub-directory called sdcc with all of the sources.
2962 \layout Enumerate
2963
2964 Change directory into the main SDCC directory, for example type:
2965 \family sans
2966 \series bold
2967 "cd sdcc
2968 \series default
2969 ".
2970 \layout Enumerate
2971
2972
2973 \series medium
2974 Type
2975 \family sans
2976 \series bold
2977 "./configure
2978 \family default
2979 \series default
2980 ".
2981  This configures the package for compilation on your system.
2982 \layout Enumerate
2983
2984
2985 \series medium
2986 Type
2987 \family sans
2988 \series bold
2989 "make
2990 \family default
2991 \series default
2992 "
2993 \series medium
2994 .
2995
2996 \series default
2997  All of the source packages will compile, this can take a while.
2998 \layout Enumerate
2999
3000
3001 \series medium
3002 Type
3003 \family sans
3004 \series bold
3005 "make install"
3006 \family default
3007 \series default
3008  as root
3009 \series medium
3010 .
3011
3012 \series default
3013  This copies the binary executables, the include files, the libraries and
3014  the documentation to the install directories.
3015  Proceed with section
3016 \begin_inset LatexCommand \ref{sec:Testing-the-SDCC}
3017
3018 \end_inset
3019
3020 .
3021 \layout Subsection
3022
3023 Building SDCC on OSX 2.x
3024 \layout Standard
3025
3026 Follow the instruction for Linux.
3027 \newline
3028
3029 \newline
3030 On OSX 2.x it was reported, that the default gcc (version 3.1 20020420 (prerelease
3031 )) fails to compile SDCC.
3032  Fortunately there's also gcc 2.9.x installed, which works fine.
3033  This compiler can be selected by running 'configure' with:
3034 \layout LyX-Code
3035
3036 ./configure CC=gcc2 CXX=g++2
3037 \layout Subsection
3038
3039 Cross compiling SDCC on Linux for Windows
3040 \layout Standard
3041
3042 With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
3043  See section 'Configure Options'.
3044 \layout Subsection
3045
3046 Building SDCC on Windows
3047 \layout Standard
3048
3049 With the exception of Cygwin the SDCC binaries uCsim and sdcdb can't be
3050  built on Windows.
3051  They use Unix-sockets, which are not available on Win32.
3052 \layout Subsection
3053
3054 Building SDCC using Cygwin and Mingw32
3055 \layout Standard
3056
3057 For building and installing a Cygwin executable follow the instructions
3058  for Linux.
3059 \newline
3060
3061 \newline
3062 On Cygwin a
3063 \begin_inset Quotes sld
3064 \end_inset
3065
3066 native
3067 \begin_inset Quotes srd
3068 \end_inset
3069
3070  Win32-binary can be built, which will not need the Cygwin-DLL.
3071  For the necessary 'configure' options see section 'configure options' or
3072  the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'.
3073 \newline
3074
3075 \newline
3076 In order to install Cygwin on Windows download setup.exe from
3077 \begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
3078
3079 \end_inset
3080
3081 .
3082  Run it, set the
3083 \begin_inset Quotes sld
3084 \end_inset
3085
3086 default text file type
3087 \begin_inset Quotes srd
3088 \end_inset
3089
3090  to
3091 \begin_inset Quotes sld
3092 \end_inset
3093
3094 unix
3095 \begin_inset Quotes srd
3096 \end_inset
3097
3098  and download/install at least the following packages.
3099  Some packages are selected by default, others will be automatically selected
3100  because of dependencies with the manually selected packages.
3101  Never deselect these packages!
3102 \layout Itemize
3103
3104 flex
3105 \layout Itemize
3106
3107 bison
3108 \layout Itemize
3109
3110 gcc ; version 3.x is fine, no need to use the old 2.9x
3111 \layout Itemize
3112
3113 binutils ; selected with gcc
3114 \layout Itemize
3115
3116 make
3117 \layout Itemize
3118
3119 rxvt ; a nice console, which makes life much easier under windoze (see below)
3120 \layout Itemize
3121
3122 man ; not really needed for building SDCC, but you'll miss it sooner or
3123  later
3124 \layout Itemize
3125
3126 less ; not really needed for building SDCC, but you'll miss it sooner or
3127  later
3128 \layout Itemize
3129
3130 cvs ; only if you use CVS access
3131 \layout Standard
3132
3133 If you want to develop something you'll need:
3134 \layout Itemize
3135
3136 python ; for the regression tests
3137 \layout Itemize
3138
3139 gdb ; the gnu debugger, together with the nice GUI
3140 \begin_inset Quotes sld
3141 \end_inset
3142
3143 insight
3144 \begin_inset Quotes srd
3145 \end_inset
3146
3147
3148 \layout Itemize
3149
3150 openssh ; to access the CF or commit changes
3151 \layout Itemize
3152
3153 autoconf and autoconf-devel ; if you want to fight with 'configure', don't
3154  use autoconf-stable!
3155 \layout Standard
3156
3157 rxvt is a nice console with history.
3158  Replace in your cygwin.bat the line
3159 \layout LyX-Code
3160
3161 bash -
3162 \begin_inset ERT
3163 status Collapsed
3164
3165 \layout Standard
3166
3167 \backslash
3168 /
3169 \end_inset
3170
3171 -login -i
3172 \layout Standard
3173
3174 with (one line):
3175 \layout LyX-Code
3176
3177 rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
3178 \layout LyX-Code
3179
3180      -bg black -fg white -geometry 100x65 -e bash -
3181 \begin_inset ERT
3182 status Collapsed
3183
3184 \layout Standard
3185
3186 \backslash
3187 /
3188 \end_inset
3189
3190 -login
3191 \layout Standard
3192
3193 Text selected with the mouse is automatically copied to the clipboard, pasting
3194  works with shift-insert.
3195 \newline
3196
3197 \newline
3198 The other good tip is to make sure you have no //c/-style paths anywhere,
3199  use /cygdrive/c/ instead.
3200  Using // invokes a network lookup which is very slow.
3201  If you think
3202 \begin_inset Quotes sld
3203 \end_inset
3204
3205 cygdrive
3206 \begin_inset Quotes srd
3207 \end_inset
3208
3209  is too long, you can change it with e.g.
3210 \layout LyX-Code
3211
3212 mount -s -u -c /mnt
3213 \layout Standard
3214
3215 SDCC sources use the unix line ending LF.
3216  Life is much easier, if you store the source tree on a drive which is mounted
3217  in binary mode.
3218  And use an editor which can handle LF-only line endings.
3219  Make sure not to commit files with windows line endings.
3220  The tabulator spacing
3221 \begin_inset LatexCommand \index{tabulator spacing (8 columns)}
3222
3223 \end_inset
3224
3225  used in the project is 8.
3226  Although a tabulator spacing of 8 is a sensible choice for programmers
3227  (it's a power of 2 and allows to display 8/16 bit signed variables without
3228  loosing columns) the plan is to move towards using only spaces in the source.
3229 \layout Subsection
3230
3231 Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
3232 \layout Standard
3233
3234
3235 \series medium
3236 Download the source package
3237 \series default
3238  either from the SDCC CVS repository or from the
3239 \begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
3240
3241 \end_inset
3242
3243
3244 \series medium
3245 , it will be named something like sdcc
3246 \series default
3247 .src
3248 \series medium
3249 .tgz.
3250
3251 \series default
3252  SDCC is distributed with all the projects, workspaces, and files you need
3253  to build it using Visual C++ 6.0/NET (except for sdcdb.exe which currently
3254  doesn't build under MSVC).
3255  The workspace name is 'sdcc.dsw'.
3256  Please note that as it is now, all the executables are created in a folder
3257  called sdcc
3258 \backslash
3259 bin_vc.
3260  Once built you need to copy the executables from sdcc
3261 \backslash
3262 bin_vc to sdcc
3263 \backslash
3264 bin before running SDCC.
3265
3266 \newline
3267
3268 \newline
3269 WARNING: Visual studio is very picky with line terminations; it expects
3270  the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings.
3271  When using the CVS repository it's easiest to configure the cvs client
3272  to convert automatically for you.
3273  If however you are getting a message such as "This makefile was not generated
3274  by Developer Studio etc.
3275  etc.
3276 \begin_inset Quotes srd
3277 \end_inset
3278
3279  when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
3280  need to convert the Unix style line endings to DOS style line endings.
3281  To do so you can use the
3282 \begin_inset Quotes sld
3283 \end_inset
3284
3285 unix2dos
3286 \begin_inset Quotes srd
3287 \end_inset
3288
3289  utility freely available on the internet.
3290  Doug Hawkins reported in the sdcc-user list that this works:
3291 \newline
3292
3293 \newline
3294 C:
3295 \backslash
3296 Programming
3297 \backslash
3298 SDCC> unix2dos sdcc.dsw
3299 \newline
3300 C:
3301 \backslash
3302 Programming
3303 \backslash
3304 SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
3305 \newline
3306
3307 \newline
3308 In order to build SDCC with MSVC you need win32 executables of bison.exe,
3309  flex.exe, and gawk.exe.
3310  One good place to get them is
3311 \begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
3312
3313 \end_inset
3314
3315
3316 \newline
3317
3318 \newline
3319 Download the file UnxUtils
3320 \begin_inset LatexCommand \index{UnxUtils}
3321
3322 \end_inset
3323
3324 .zip.
3325  Now you have to install the utilities and setup MSVC so it can locate the
3326  required programs.
3327  Here there are two alternatives (choose one!):
3328 \layout Enumerate
3329
3330 The easy way:
3331 \newline
3332
3333 \newline
3334 a) Extract UnxUtils.zip to your C:
3335 \backslash
3336  hard disk PRESERVING the original paths, otherwise bison won't work.
3337  (If you are using WinZip make certain that 'Use folder names' is selected)
3338 \newline
3339
3340 \newline
3341 b) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3342  in 'Show directories for:' select 'Executable files', and in the directories
3343  window add a new path: 'C:
3344 \backslash
3345 user
3346 \backslash
3347 local
3348 \backslash
3349 wbin', click ok.
3350 \newline
3351
3352 \newline
3353 (As a side effect, you get a bunch of Unix utilities that could be useful,
3354  such as diff and patch.)
3355 \layout Enumerate
3356
3357 A more compact way:
3358 \newline
3359
3360 \newline
3361 This one avoids extracting a bunch of files you may not use, but requires
3362  some extra work:
3363 \newline
3364
3365 \newline
3366 a) Create a directory were to put the tools needed, or use a directory already
3367  present.
3368  Say for example 'C:
3369 \backslash
3370 util'.
3371 \newline
3372
3373 \newline
3374 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
3375  to such directory WITHOUT preserving the original paths.
3376  (If you are using WinZip make certain that 'Use folder names' is not selected)
3377 \newline
3378
3379 \newline
3380 c) Rename bison.exe to '_bison.exe'.
3381 \newline
3382
3383 \newline
3384 d) Create a batch file 'bison.bat' in 'C:
3385 \backslash
3386 util
3387 \backslash
3388 ' and add these lines:
3389 \newline
3390 \SpecialChar ~
3391 \SpecialChar ~
3392 set BISON_SIMPLE=C:
3393 \backslash
3394 util
3395 \backslash
3396 bison.simple
3397 \newline
3398 \SpecialChar ~
3399 \SpecialChar ~
3400 set BISON_HAIRY=C:
3401 \backslash
3402 util
3403 \backslash
3404 bison.hairy
3405 \newline
3406 \SpecialChar ~
3407 \SpecialChar ~
3408 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
3409 \newline
3410
3411 \newline
3412 Steps 'c' and 'd' are needed because bison requires by default that the
3413  files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory,
3414  '/usr/local/share/' I think.
3415  So it is necessary to tell bison where those files are located if they
3416  are not in such directory.
3417  That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
3418 \newline
3419
3420 \newline
3421 e) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3422  in 'Show directories for:' select 'Executable files', and in the directories
3423  window add a new path: 'c:
3424 \backslash
3425 util', click ok.
3426  Note that you can use any other path instead of 'c:
3427 \backslash
3428 util', even the path where the Visual C++ tools are, probably: 'C:
3429 \backslash
3430 Program Files
3431 \backslash
3432 Microsoft Visual Studio
3433 \backslash
3434 Common
3435 \backslash
3436 Tools'.
3437  So you don't have to execute step 'e' :)
3438 \layout Standard
3439
3440 That is it.
3441  Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
3442  the executables from sdcc
3443 \backslash
3444 bin_vc to sdcc
3445 \backslash
3446 bin, and you can compile using SDCC.
3447 \layout Subsection
3448
3449 Building SDCC Using Borland
3450 \layout Enumerate
3451
3452 From the sdcc directory, run the command "make -f Makefile.bcc".
3453  This should regenerate all the .exe files in the bin directory except for
3454  sdcdb.exe (which currently doesn't build under Borland C++).
3455 \layout Enumerate
3456
3457 If you modify any source files and need to rebuild, be aware that the dependenci
3458 es may not be correctly calculated.
3459  The safest option is to delete all .obj files and run the build again.
3460  From a Cygwin BASH prompt, this can easily be done with the command (be
3461  sure you are in the sdcc directory):
3462 \newline
3463
3464 \newline
3465
3466 \family sans
3467 \series bold
3468 find .
3469
3470 \backslash
3471 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
3472 \backslash
3473 ) -print -exec rm {}
3474 \backslash
3475 ;
3476 \family default
3477 \series default
3478
3479 \newline
3480
3481 \newline
3482 or on Windows NT/2000/XP from the command prompt with the command:
3483 \newline
3484
3485 \family sans
3486 \series bold
3487
3488 \newline
3489 del /s *.obj *.lib *.rul
3490 \family default
3491 \series default
3492  from the sdcc directory.
3493 \layout Subsection
3494
3495 Windows Install Using a ZIP Package
3496 \layout Enumerate
3497
3498 Download the binary zip package from
3499 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3500
3501 \end_inset
3502
3503  and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
3504  This should unpack to a group of sub-directories.
3505  An example directory structure after unpacking the mingw32 package is:
3506  c:
3507 \backslash
3508 sdcc
3509 \backslash
3510 bin for the executables, c:
3511 \backslash
3512 sdcc
3513 \backslash
3514 include and c:
3515 \backslash
3516 sdcc
3517 \backslash
3518 lib for the include and libraries.
3519 \layout Enumerate
3520
3521 Adjust your environment variable PATH to include the location of the bin
3522  directory or start sdcc using the full path.
3523 \layout Subsection
3524
3525 Windows Install Using the Setup Program
3526 \begin_inset LatexCommand \label{sub:Windows-Install}
3527
3528 \end_inset
3529
3530
3531 \layout Standard
3532
3533 Download the setup program
3534 \emph on
3535 sdcc-x.y.z-setup.exe
3536 \emph default
3537  for an official release from
3538 \newline
3539
3540 \begin_inset LatexCommand \url{http://sf.net/project/showfiles.php?group_id=599}
3541
3542 \end_inset
3543
3544  or a setup program for one of the snapshots
3545 \emph on
3546 sdcc_yyyymmdd_setup.exe
3547 \emph default
3548  from
3549 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3550
3551 \end_inset
3552
3553  and execute it.
3554  A windows typical installer will guide you through the installation process.
3555 \layout Section
3556
3557 Building the Documentation
3558 \layout Standard
3559
3560 If the necessary tools (LyX, LaTeX, LaTeX2HTML) are installed it is as easy
3561  as changing into the doc directory and typing
3562 \family sans
3563 \series bold
3564
3565 \begin_inset Quotes srd
3566 \end_inset
3567
3568 make
3569 \begin_inset Quotes srd
3570 \end_inset
3571
3572
3573 \family default
3574 \series default
3575  there.
3576  You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
3577 x).
3578  Using LyX
3579 \begin_inset LatexCommand \url{http://www.lyx.org}
3580
3581 \end_inset
3582
3583  as editor this is straightforward.
3584  Prebuilt documentation in html and pdf format is available from
3585 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3586
3587 \end_inset
3588
3589 .
3590 \layout Section
3591
3592 Reading the Documentation
3593 \layout Standard
3594
3595 Currently reading the document in pdf format is recommended, as for unknown
3596  reason the hyperlinks are working there whereas in the html version they
3597  are not
3598 \begin_inset Foot
3599 collapsed false
3600
3601 \layout Standard
3602
3603 If you should know why please drop us a note
3604 \end_inset
3605
3606 .
3607
3608 \newline
3609 You'll find the pdf version
3610 \begin_inset LatexCommand \index{PDF version of this document}
3611
3612 \end_inset
3613
3614  at
3615 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.pdf}
3616
3617 \end_inset
3618
3619 .
3620
3621 \newline
3622 A html version
3623 \begin_inset LatexCommand \index{HTML version of this document}
3624
3625 \end_inset
3626
3627  should be online at
3628 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.html/index.html}
3629
3630 \end_inset
3631
3632 .
3633 \newline
3634 This documentation is in some aspects different from a commercial documentation:
3635
3636 \layout Itemize
3637
3638 It tries to document SDCC for several processor architectures in one document
3639  (commercially these probably would be separate documents/products).
3640  This document
3641 \begin_inset LatexCommand \index{Status of documentation}
3642
3643 \end_inset
3644
3645  currently matches SDCC for mcs51 and DS390 best and does give too few informati
3646 on about f.e.
3647  Z80, PIC14, PIC16 and HC08.
3648 \layout Itemize
3649
3650 There are many references pointing away from this documentation.
3651  Don't let this distract you.
3652  If there f.e.
3653  was a reference like
3654 \begin_inset LatexCommand \url{http://www.opencores.org}
3655
3656 \end_inset
3657
3658  together with a statement
3659 \begin_inset Quotes sld
3660 \end_inset
3661
3662 some processors which are targetted by SDCC can be implemented in a
3663 \emph on
3664 f
3665 \emph default
3666 ield
3667 \emph on
3668 p
3669 \emph default
3670 rogrammable
3671 \emph on
3672 g
3673 \emph default
3674 ate
3675 \emph on
3676 a
3677 \emph default
3678 rray
3679 \begin_inset LatexCommand \index{fpga (field programmable gate array)}
3680
3681 \end_inset
3682
3683
3684 \begin_inset Quotes srd
3685 \end_inset
3686
3687  we expect you to have a quick look there and come back.
3688  If you read this you are on the right track.
3689 \layout Itemize
3690
3691 Some sections attribute more space to problems, restrictions and warnings
3692  than to the solution.
3693 \layout Itemize
3694
3695 The installation section and the section about the debugger is intimidating.
3696 \layout Itemize
3697
3698 There are still lots of typos and there are more different writing styles
3699  than pictures.
3700 \layout Section
3701
3702 Testing the SDCC Compiler
3703 \begin_inset LatexCommand \label{sec:Testing-the-SDCC}
3704
3705 \end_inset
3706
3707
3708 \layout Standard
3709
3710 The first thing you should do after installing your SDCC compiler is to
3711  see if it runs.
3712  Type
3713 \family sans
3714 \series bold
3715 "sdcc -
3716 \begin_inset ERT
3717 status Collapsed
3718
3719 \layout Standard
3720
3721 \backslash
3722 /
3723 \end_inset
3724
3725 -version"
3726 \begin_inset LatexCommand \index{version}
3727
3728 \end_inset
3729
3730
3731 \family default
3732 \series default
3733  at the prompt, and the program should run and tell you the version.
3734  If it doesn't run, or gives a message about not finding sdcc program, then
3735  you need to check over your installation.
3736  Make sure that the sdcc bin directory is in your executable search path
3737  defined by the PATH environment setting (
3738 \series medium
3739 see
3740 \series default
3741 section
3742 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3743
3744 \end_inset
3745
3746 \SpecialChar ~
3747
3748 \series medium
3749 Install trouble-shooting for suggestions
3750 \series default
3751 ).
3752  Make sure that the sdcc program is in the bin folder, if not perhaps something
3753  did not install correctly.
3754 \newline
3755
3756 \newline
3757
3758 \series medium
3759 SDCC
3760 \series default
3761 is commonly installed as described in section
3762 \begin_inset Quotes sld
3763 \end_inset
3764
3765 Install and search paths
3766 \begin_inset Quotes srd
3767 \end_inset
3768
3769 .
3770 \newline
3771
3772 \newline
3773
3774 \series medium
3775 Make sure the compiler works on a very simple example.
3776  Type in the following test.c program using your favorite
3777 \series default
3778 ASCII
3779 \series medium
3780 editor:
3781 \layout Verse
3782
3783
3784 \family typewriter
3785 char test;
3786 \newline
3787
3788 \newline
3789 void main(void) {
3790 \newline
3791 \SpecialChar ~
3792 \SpecialChar ~
3793 \SpecialChar ~
3794 \SpecialChar ~
3795 test=0;
3796 \newline
3797 }
3798 \layout Standard
3799
3800
3801 \series medium
3802 Compile this using the following command:
3803 \family sans
3804 \series bold
3805 "sdcc -c test.c".
3806
3807 \family default
3808 \series default
3809
3810 \series medium
3811 If all goes well, the compiler will generate a test.asm and test.rel file.
3812  Congratulations, you've just compiled your first program with SDCC.
3813  We used the -c option to tell SDCC not to link the generated code, just
3814  to keep things simple for this step.
3815 \series default
3816
3817 \newline
3818
3819 \newline
3820
3821 \series medium
3822 The next step is to try it with the linker.
3823  Type in
3824 \family sans
3825 \series bold
3826 "sdcc test.c
3827 \family default
3828 \series default
3829 "
3830 \series medium
3831 .
3832  If all goes well the compiler will link with the libraries and produce
3833  a test.ihx output file.
3834  If this step fails
3835 \series default
3836
3837 \series medium
3838 (no test.ihx, and the linker generates warnings), then the problem is most
3839  likely that
3840 \series default
3841 SDCC
3842 \series medium
3843  cannot find the
3844 \series default
3845 /
3846 \series medium
3847 usr/local/share/sdcc/lib directory
3848 \series default
3849
3850 \series medium
3851 (see
3852 \series default
3853 section
3854 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3855
3856 \end_inset
3857
3858 \SpecialChar ~
3859
3860 \series medium
3861 Install trouble-shooting for suggestions).
3862 \series default
3863
3864 \newline
3865
3866 \newline
3867
3868 \series medium
3869 The final test is to ensure
3870 \series default
3871 SDCC
3872 \series medium
3873  can use the
3874 \series default
3875 standard
3876 \series medium
3877  header files and libraries.
3878  Edit test.c and change it to the following:
3879 \layout Verse
3880
3881
3882 \family typewriter
3883 #include <string.h>
3884 \newline
3885
3886 \newline
3887 char str1[10];
3888 \newline
3889
3890 \newline
3891 void main(void) {
3892 \newline
3893 \SpecialChar ~
3894 \SpecialChar ~
3895 strcpy(str1, "testing");
3896 \newline
3897 }
3898 \layout Standard
3899
3900
3901 \series medium
3902 Compile this by typing
3903 \family sans
3904 \series bold
3905 "sdcc test.c"
3906 \family default
3907 \series medium
3908 .
3909  This should generate a test.ihx output file, and it should give no warnings
3910  such as not finding the string.h file.
3911  If it cannot find the string.h file, then the problem is that
3912 \series default
3913 SDCC
3914 \series medium
3915  cannot find the /usr/local/share/sdcc/include directory
3916 \series default
3917
3918 \series medium
3919 (see the
3920 \series default
3921 section
3922 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3923
3924 \end_inset
3925
3926 \SpecialChar ~
3927
3928 \series medium
3929 Install trouble-shooting section for suggestions).
3930
3931 \series default
3932  Use option
3933 \series bold
3934 -
3935 \begin_inset ERT
3936 status Collapsed
3937
3938 \layout Standard
3939
3940 \backslash
3941 /
3942 \end_inset
3943
3944 -print-search-dirs
3945 \series default
3946
3947 \begin_inset LatexCommand \index{-\/-print-search-dirs}
3948
3949 \end_inset
3950
3951  to find exactly where SDCC is looking for the include and lib files.
3952 \layout Section
3953
3954 Install Trouble-shooting
3955 \begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
3956
3957 \end_inset
3958
3959
3960 \begin_inset LatexCommand \index{Install trouble-shooting}
3961
3962 \end_inset
3963
3964
3965 \layout Subsection
3966
3967 If SDCC does not build correctly
3968 \layout Standard
3969
3970 A thing to try is starting from scratch by unpacking the .tgz source package
3971  again in an empty directory.
3972  Configure it like:
3973 \newline
3974
3975 \newline
3976
3977 \family sans
3978 \series bold
3979 ./configure 2>&1 | tee configure.log
3980 \family default
3981 \series default
3982
3983 \newline
3984
3985 \newline
3986 and build it like:
3987 \newline
3988
3989 \newline
3990
3991 \family sans
3992 \series bold
3993 make 2>&1 | tee make.log
3994 \family default
3995 \series default
3996
3997 \newline
3998
3999 \newline
4000 If anything goes wrong, you can review the log files to locate the problem.
4001  Or a relevant part of this can be attached to an email that could be helpful
4002  when requesting help from the mailing list.
4003 \layout Subsection
4004
4005 What the
4006 \begin_inset Quotes sld
4007 \end_inset
4008
4009 ./configure
4010 \begin_inset Quotes srd
4011 \end_inset
4012
4013  does
4014 \layout Standard
4015
4016 The
4017 \begin_inset Quotes sld
4018 \end_inset
4019
4020 ./configure
4021 \begin_inset Quotes srd
4022 \end_inset
4023
4024  command is a script that analyzes your system and performs some configuration
4025  to ensure the source package compiles on your system.
4026  It will take a few minutes to run, and will compile a few tests to determine
4027  what compiler features are installed.
4028 \layout Subsection
4029
4030 What the
4031 \begin_inset Quotes sld
4032 \end_inset
4033
4034 make
4035 \begin_inset Quotes srd
4036 \end_inset
4037
4038  does
4039 \layout Standard
4040
4041 This runs the GNU make tool, which automatically compiles all the source
4042  packages into the final installed binary executables.
4043 \layout Subsection
4044
4045 What the
4046 \begin_inset Quotes sld
4047 \end_inset
4048
4049 make install
4050 \begin_inset Quotes erd
4051 \end_inset
4052
4053  command does.
4054 \layout Standard
4055
4056 This will install the compiler, other executables libraries and include
4057  files into the appropriate directories.
4058  See sections
4059 \begin_inset LatexCommand \ref{sub:Install-paths}
4060
4061 \end_inset
4062
4063 ,\SpecialChar ~
4064
4065 \begin_inset LatexCommand \ref{sub:Search-Paths}
4066
4067 \end_inset
4068
4069 \SpecialChar ~
4070 about install and search paths.
4071 \newline
4072 On most systems you will need super-user privileges to do this.
4073 \layout Section
4074
4075 Components of SDCC
4076 \layout Standard
4077
4078 SDCC is not just a compiler, but a collection of tools by various developers.
4079  These include linkers, assemblers, simulators and other components.
4080  Here is a summary of some of the components.
4081  Note that the included simulator and assembler have separate documentation
4082  which you can find in the source package in their respective directories.
4083  As SDCC grows to include support for other processors, other packages from
4084  various developers are included and may have their own sets of documentation.
4085 \newline
4086
4087 \newline
4088 You might want to look at the files which are installed in <installdir>.
4089  At the time of this writing, we find the following programs for gcc-builds:
4090 \newline
4091
4092 \newline
4093 In <installdir>/bin:
4094 \layout Itemize
4095
4096 sdcc - The compiler.
4097 \layout Itemize
4098
4099 sdcpp - The C preprocessor.
4100 \layout Itemize
4101
4102 asx8051 - The assembler for 8051 type processors.
4103 \layout Itemize
4104
4105 as-z80
4106 \series bold
4107 ,
4108 \series default
4109 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
4110 \layout Itemize
4111
4112 aslink -The linker for 8051 type processors.
4113 \layout Itemize
4114
4115 link-z80
4116 \series bold
4117 ,
4118 \series default
4119 link-gbz80 - The Z80 and GameBoy Z80 linkers.
4120 \layout Itemize
4121
4122 s51 - The ucSim 8051 simulator.
4123 \layout Itemize
4124
4125 sdcdb - The source debugger.
4126 \layout Itemize
4127
4128 packihx - A tool to pack (compress) Intel hex files.
4129 \layout Standard
4130
4131 In <installdir>/share/sdcc/include
4132 \layout Itemize
4133
4134 the include files
4135 \layout Standard
4136
4137 In <installdir>/share/sdcc/lib
4138 \layout Itemize
4139
4140 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
4141  relocatables.
4142 \layout Standard
4143
4144 In <installdir>/share/sdcc/doc
4145 \layout Itemize
4146
4147 the documentation
4148 \layout Standard
4149
4150 As development for other processors proceeds, this list will expand to include
4151  executables to support processors like AVR, PIC, etc.
4152 \layout Subsection
4153
4154 sdcc - The Compiler
4155 \layout Standard
4156
4157 This is the actual compiler, it in turn uses the c-preprocessor and invokes
4158  the assembler and linkage editor.
4159 \layout Subsection
4160
4161 sdcpp - The C-Preprocessor
4162 \layout Standard
4163
4164 The preprocessor
4165 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
4166
4167 \end_inset
4168
4169  is a modified version of the GNU preprocessor.
4170  The C preprocessor is used to pull in #include sources, process #ifdef
4171  statements, #defines and so on.
4172 \layout Subsection
4173
4174 as
4175 \emph on
4176 xxxx
4177 \emph default
4178 , aslink, link-
4179 \emph on
4180 xxx
4181 \emph default
4182  - The Assemblers and Linkage Editors
4183 \layout Standard
4184
4185 This is retargettable assembler & linkage editor, it was developed by Alan
4186  Baldwin.
4187  John Hartman created the version for 8051, and I (Sandeep) have made some
4188  enhancements and bug fixes for it to work properly with SDCC.
4189 \layout Subsection
4190
4191 s51 - The Simulator
4192 \layout Standard
4193
4194 S51
4195 \begin_inset LatexCommand \index{s51}
4196
4197 \end_inset
4198
4199  is a freeware, opensource simulator developed by Daniel Drotos.
4200  The simulator is built as part of the build process.
4201  For more information visit Daniel's web site at:
4202 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
4203
4204 \end_inset
4205
4206 .
4207  It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
4208  XA51 family.
4209 \layout Subsection
4210
4211 sdcdb - Source Level Debugger
4212 \layout Standard
4213
4214 Sdcdb
4215 \begin_inset LatexCommand \index{sdcdb (debugger)}
4216
4217 \end_inset
4218
4219  is the companion source level debugger.
4220  More about sdcdb in section
4221 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
4222
4223 \end_inset
4224
4225 .
4226  The current version of the debugger uses Daniel's Simulator S51
4227 \begin_inset LatexCommand \index{s51}
4228
4229 \end_inset
4230
4231 , but can be easily changed to use other simulators.
4232
4233 \layout Chapter
4234
4235 Using SDCC
4236 \layout Section
4237
4238 Compiling
4239 \layout Subsection
4240
4241 Single Source File Projects
4242 \layout Standard
4243
4244 For single source file 8051 projects the process is very simple.
4245  Compile your programs with the following command
4246 \family sans
4247 \series bold
4248 "sdcc sourcefile.c".
4249
4250 \family default
4251 \series default
4252  This will compile, assemble and link your source file.
4253  Output files are as follows:
4254 \layout Itemize
4255
4256 sourcefile.asm
4257 \begin_inset LatexCommand \index{<file>.asm}
4258
4259 \end_inset
4260
4261  - Assembler source
4262 \begin_inset LatexCommand \index{Assembler source}
4263
4264 \end_inset
4265
4266  file created by the compiler
4267 \layout Itemize
4268
4269 sourcefile.lst
4270 \begin_inset LatexCommand \index{<file>.lst}
4271
4272 \end_inset
4273
4274  - Assembler listing
4275 \begin_inset LatexCommand \index{Assembler listing}
4276
4277 \end_inset
4278
4279  file created by the Assembler
4280 \layout Itemize
4281
4282 sourcefile.rst
4283 \begin_inset LatexCommand \index{<file>.rst}
4284
4285 \end_inset
4286
4287  - Assembler listing
4288 \begin_inset LatexCommand \index{Assembler listing}
4289
4290 \end_inset
4291
4292  file updated with linkedit information, created by linkage editor
4293 \layout Itemize
4294
4295 sourcefile.sym
4296 \begin_inset LatexCommand \index{<file>.sym}
4297
4298 \end_inset
4299
4300  - symbol listing
4301 \begin_inset LatexCommand \index{Symbol listing}
4302
4303 \end_inset
4304
4305  for the sourcefile, created by the assembler
4306 \layout Itemize
4307
4308 sourcefile.rel
4309 \begin_inset LatexCommand \index{<file>.rel}
4310
4311 \end_inset
4312
4313  or sourcefile.o
4314 \begin_inset LatexCommand \index{<file>.o}
4315
4316 \end_inset
4317
4318  - Object file
4319 \begin_inset LatexCommand \index{Object file}
4320
4321 \end_inset
4322
4323  created by the assembler, input to Linkage editor
4324 \layout Itemize
4325
4326 sourcefile.map
4327 \begin_inset LatexCommand \index{<file>.map}
4328
4329 \end_inset
4330
4331  - The memory map
4332 \begin_inset LatexCommand \index{Memory map}
4333
4334 \end_inset
4335
4336  for the load module, created by the Linker
4337 \layout Itemize
4338
4339 sourcefile.mem
4340 \begin_inset LatexCommand \index{<file>.mem}
4341
4342 \end_inset
4343
4344  - A file with a summary of the memory usage
4345 \layout Itemize
4346
4347 sourcefile.ihx
4348 \begin_inset LatexCommand \index{<file>.ihx}
4349
4350 \end_inset
4351
4352  - The load module in Intel hex format
4353 \begin_inset LatexCommand \index{Intel hex format}
4354
4355 \end_inset
4356
4357  (you can select the Motorola S19 format
4358 \begin_inset LatexCommand \index{Motorola S19 format}
4359
4360 \end_inset
4361
4362  with -
4363 \begin_inset ERT
4364 status Collapsed
4365
4366 \layout Standard
4367
4368 \backslash
4369 /
4370 \end_inset
4371
4372 -out-fmt-s19
4373 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
4374
4375 \end_inset
4376
4377 .
4378  If you need another format you might want to use
4379 \family sans
4380 \shape italic
4381 objdump
4382 \family default
4383 \shape default
4384
4385 \begin_inset LatexCommand \index{objdump (tool)}
4386
4387 \end_inset
4388
4389  or
4390 \family sans
4391 \shape italic
4392  srecord
4393 \family default
4394 \shape default
4395
4396 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4397
4398 \end_inset
4399
4400 ).
4401  Both formats are documented in the documentation of srecord
4402 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4403
4404 \end_inset
4405
4406
4407 \layout Itemize
4408
4409 sourcefile.adb
4410 \begin_inset LatexCommand \index{<file>.adb}
4411
4412 \end_inset
4413
4414  - An intermediate file containing debug information needed to create the
4415  .cdb file (with -
4416 \begin_inset ERT
4417 status Open
4418
4419 \layout Standard
4420
4421 \backslash
4422 /
4423 \end_inset
4424
4425 -debug
4426 \begin_inset LatexCommand \index{-\/-debug}
4427
4428 \end_inset
4429
4430 )
4431 \layout Itemize
4432
4433 sourcefile.cdb
4434 \begin_inset LatexCommand \index{<file>.cdb}
4435
4436 \end_inset
4437
4438  - An optional file (with -
4439 \begin_inset ERT
4440 status Collapsed
4441
4442 \layout Standard
4443
4444 \backslash
4445 /
4446 \end_inset
4447
4448 -debug) containing debug information.
4449  The format is documented in cdbfileformat.pdf
4450 \layout Itemize
4451
4452 sourcefile.
4453  - (no extension)
4454 \begin_inset LatexCommand \index{<file> (no extension)}
4455
4456 \end_inset
4457
4458  An optional AOMF or AOMF51
4459 \begin_inset LatexCommand \index{AOMF, AOMF51}
4460
4461 \end_inset
4462
4463  file containing debug information (generated with option -
4464 \begin_inset ERT
4465 status Collapsed
4466
4467 \layout Standard
4468
4469 \backslash
4470 /
4471 \end_inset
4472
4473 -debug).
4474  The (Intel)
4475 \emph on
4476  a
4477 \emph default
4478 bsolute
4479 \emph on
4480 o
4481 \emph default
4482 bject
4483 \emph on
4484 m
4485 \emph default
4486 odule
4487 \emph on
4488 f
4489 \emph default
4490 ormat is commonly used by third party tools (debuggers
4491 \begin_inset LatexCommand \index{Debugger}
4492
4493 \end_inset
4494
4495 , simulators, emulators)
4496 \layout Itemize
4497
4498 sourcefile.dump*
4499 \begin_inset LatexCommand \index{<file>.dump*}
4500
4501 \end_inset
4502
4503  - Dump file to debug the compiler it self (generated with option -
4504 \begin_inset ERT
4505 status Collapsed
4506
4507 \layout Standard
4508
4509 \backslash
4510 /
4511 \end_inset
4512
4513 -dumpall) (see section
4514 \begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
4515
4516 \end_inset
4517
4518 \SpecialChar ~
4519  and section
4520 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
4521
4522 \end_inset
4523
4524 \SpecialChar ~
4525
4526 \begin_inset Quotes sld
4527 \end_inset
4528
4529 Anatomy of the compiler
4530 \begin_inset Quotes srd
4531 \end_inset
4532
4533 ).
4534 \layout Subsection
4535
4536 Projects with Multiple Source Files
4537 \layout Standard
4538
4539 SDCC can compile only ONE file at a time.
4540  Let us for example assume that you have a project containing the following
4541  files:
4542 \newline
4543
4544 \newline
4545 foo1.c (contains some functions)
4546 \newline
4547 foo2.c (contains some more functions)
4548 \newline
4549 foomain.c (contains more functions and the function main)
4550 \newline
4551
4552 \size footnotesize
4553
4554 \newline
4555
4556 \size default
4557 The first two files will need to be compiled separately with the commands:
4558 \size footnotesize
4559
4560 \size default
4561
4562 \newline
4563
4564 \newline
4565
4566 \family sans
4567 \series bold
4568 sdcc\SpecialChar ~
4569 -c\SpecialChar ~
4570 foo1.c
4571 \family default
4572 \series default
4573 \size footnotesize
4574
4575 \newline
4576
4577 \family sans
4578 \series bold
4579 \size default
4580 sdcc\SpecialChar ~
4581 -c\SpecialChar ~
4582 foo2.c
4583 \family default
4584 \series default
4585
4586 \newline
4587
4588 \newline
4589 Then compile the source file containing the
4590 \emph on
4591 main()
4592 \emph default
4593  function and link
4594 \begin_inset LatexCommand \index{Linker}
4595
4596 \end_inset
4597
4598  the files together with the following command:
4599 \newline
4600
4601 \newline
4602
4603 \family sans
4604 \series bold
4605 sdcc\SpecialChar ~
4606 foomain.c\SpecialChar ~
4607 foo1.rel\SpecialChar ~
4608 foo2.rel
4609 \family default
4610 \series default
4611
4612 \begin_inset LatexCommand \index{<file>.rel}
4613
4614 \end_inset
4615
4616
4617 \newline
4618
4619 \newline
4620 Alternatively,
4621 \emph on
4622 foomain.c
4623 \emph default
4624 can be separately compiled as well:
4625 \family sans
4626 \series bold
4627
4628 \newline
4629
4630 \newline
4631 sdcc\SpecialChar ~
4632 -c\SpecialChar ~
4633 foomain.c
4634 \newline
4635 sdcc foomain.rel foo1.rel foo2.rel
4636 \newline
4637
4638 \newline
4639
4640 \family default
4641 \series default
4642 The file containing the
4643 \emph on
4644 main()
4645 \emph default
4646  function
4647 \emph on
4648
4649 \emph default
4650 \noun on
4651 must
4652 \noun default
4653  be the
4654 \noun on
4655 first
4656 \noun default
4657  file specified in the command line, since the linkage editor processes
4658  file in the order they are presented to it.
4659  The linker is invoked from SDCC using a script file with extension .lnk
4660 \begin_inset LatexCommand \index{<file>.lnk}
4661
4662 \end_inset
4663
4664 .
4665  You can view this file to troubleshoot linking problems such as those arising
4666  from missing libraries.
4667 \layout Subsection
4668
4669 Projects with Additional Libraries
4670 \begin_inset LatexCommand \index{Libraries}
4671
4672 \end_inset
4673
4674
4675 \layout Standard
4676
4677 Some reusable routines may be compiled into a library, see the documentation
4678  for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
4679  for how to create a
4680 \emph on
4681 .lib
4682 \begin_inset LatexCommand \index{<file>.lib}
4683
4684 \end_inset
4685
4686
4687 \emph default
4688  library file.
4689  Libraries created in this manner can be included in the command line.
4690  Make sure you include the -L <library-path> option to tell the linker where
4691  to look for these files if they are not in the current directory.
4692  Here is an example, assuming you have the source file
4693 \emph on
4694 foomain.c
4695 \emph default
4696  and a library
4697 \emph on
4698  foolib.lib
4699 \emph default
4700  in the directory
4701 \emph on
4702 mylib
4703 \emph default
4704  (if that is not the same as your current project):
4705 \newline
4706
4707 \newline
4708
4709 \family sans
4710 \series bold
4711 sdcc foomain.c foolib.lib -L mylib
4712 \newline
4713
4714 \newline
4715
4716 \family default
4717 \series default
4718 Note here that
4719 \emph on
4720  mylib
4721 \emph default
4722  must be an absolute path name.
4723 \newline
4724
4725 \newline
4726 The most efficient way to use libraries is to keep separate modules in separate
4727  source files.
4728  The lib file now should name all the modules.rel
4729 \begin_inset LatexCommand \index{<file>.rel}
4730
4731 \end_inset
4732
4733  files.
4734  For an example see the standard library file
4735 \emph on
4736 libsdcc.lib
4737 \emph default
4738  in the directory <installdir>/share/lib/small.
4739 \layout Subsection
4740
4741 Using sdcclib to Create and Manage Libraries
4742 \begin_inset LatexCommand \index{sdcclib}
4743
4744 \end_inset
4745
4746
4747 \layout Standard
4748
4749 Alternatively, instead of having a .rel file for each entry on the library
4750  file as described in the preceding section, sdcclib can be used to embed
4751  all the modules belonging to such library in the library file itself.
4752  This results in a larger library file, but it greatly reduces the number
4753  of disk files accessed by the linker.
4754   Additionally, the packed library file contains an index of all include
4755  modules and symbols that significantly speeds up the linking process.
4756  To display a list of options supported by sdcclib type:
4757 \newline
4758
4759 \layout Standard
4760
4761
4762 \family sans
4763 \series bold
4764 sdcclib -?
4765 \begin_inset LatexCommand \index{sdcclib}
4766
4767 \end_inset
4768
4769
4770 \newline
4771
4772 \newline
4773
4774 \family default
4775 \series default
4776 To create a new library file, start by compiling all the required modules.
4777  For example:
4778 \newline
4779
4780 \layout Standard
4781
4782
4783 \family sans
4784 \series bold
4785 sdcc -c _divsint.c
4786 \layout Standard
4787
4788
4789 \family sans
4790 \series bold
4791 sdcc -c _divuint.c
4792 \layout Standard
4793
4794
4795 \family sans
4796 \series bold
4797 sdcc -c _modsint.c
4798 \layout Standard
4799
4800
4801 \family sans
4802 \series bold
4803 sdcc -c _moduint.c
4804 \layout Standard
4805
4806
4807 \family sans
4808 \series bold
4809 sdcc -c _mulint.c
4810 \newline
4811
4812 \layout Standard
4813
4814 This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
4815  and _mulint.rel.
4816  The next step is to add the .rel files to the library file:
4817 \newline
4818
4819 \layout Standard
4820
4821
4822 \family sans
4823 \series bold
4824 sdcclib libint.lib _divsint.rel
4825 \family default
4826
4827 \begin_inset LatexCommand \index{sdcclib}
4828
4829 \end_inset
4830
4831
4832 \layout Standard
4833
4834
4835 \family sans
4836 \series bold
4837 sdcclib libint.lib _divuint.rel
4838 \layout Standard
4839
4840
4841 \family sans
4842 \series bold
4843 sdcclib libint.lib _modsint.rel
4844 \layout Standard
4845
4846
4847 \family sans
4848 \series bold
4849 sdcclib libint.lib _moduint.rel
4850 \layout Standard
4851
4852
4853 \family sans
4854 \series bold
4855 sdcclib libint.lib _mulint.rel
4856 \series default
4857
4858 \newline
4859
4860 \layout Standard
4861
4862 If the file already exists in the library, it will be replaced.
4863  To see what modules and symbols are included in the library, options -s
4864  and -m are available.
4865  For example:
4866 \newline
4867
4868 \newline
4869
4870 \family sans
4871 \series bold
4872 sdcclib -s libint.lib
4873 \family default
4874
4875 \begin_inset LatexCommand \index{sdcclib}
4876
4877 \end_inset
4878
4879
4880 \newline
4881
4882 \family typewriter
4883 \series default
4884 _divsint.rel:
4885 \layout Standard
4886
4887
4888 \family typewriter
4889 __divsint_a_1_1
4890 \layout Standard
4891
4892
4893 \family typewriter
4894 __divsint_PARM_2
4895 \layout Standard
4896
4897
4898 \family typewriter
4899 __divsint
4900 \newline
4901 _divuint.rel:
4902 \layout Standard
4903
4904
4905 \family typewriter
4906 __divuint_a_1_1
4907 \layout Standard
4908
4909
4910 \family typewriter
4911 __divuint_PARM_2
4912 \layout Standard
4913
4914
4915 \family typewriter
4916 __divuint_reste_1_1
4917 \layout Standard
4918
4919
4920 \family typewriter
4921 __divuint_count_1_1
4922 \layout Standard
4923
4924
4925 \family typewriter
4926 __divuint
4927 \newline
4928 _modsint.rel:
4929 \layout Standard
4930
4931
4932 \family typewriter
4933 __modsint_a_1_1
4934 \layout Standard
4935
4936
4937 \family typewriter
4938 __modsint_PARM_2
4939 \layout Standard
4940
4941
4942 \family typewriter
4943 __modsint
4944 \newline
4945 _moduint.rel:
4946 \layout Standard
4947
4948
4949 \family typewriter
4950 __moduint_a_1_1
4951 \layout Standard
4952
4953
4954 \family typewriter
4955 __moduint_PARM_2
4956 \layout Standard
4957
4958
4959 \family typewriter
4960 __moduint_count_1_1
4961 \layout Standard
4962
4963
4964 \family typewriter
4965 __moduint
4966 \newline
4967 _mulint.rel:
4968 \layout Standard
4969
4970
4971 \family typewriter
4972 __mulint_PARM_2
4973 \layout Standard
4974
4975
4976 \family typewriter
4977 __mulint
4978 \family default
4979 \series bold
4980
4981 \newline
4982
4983 \layout Standard
4984
4985 If the source files are compiled using -
4986 \begin_inset ERT
4987 status Open
4988
4989 \layout Standard
4990
4991 \backslash
4992 /
4993 \end_inset
4994
4995 -debug
4996 \begin_inset LatexCommand \index{-\/-debug}
4997
4998 \end_inset
4999
5000 , the corresponding debug information file .adb will be include in the library
5001  file as well.
5002  The library files created with sdcclib are plain text files, so they can
5003  be viewed with a text editor.
5004  It is not recomended to modify a library file created with sdcclib using
5005  a text editor, as there are file indexes numbers located accross the file
5006  used by the linker to quickly locate the required module to link.
5007  Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
5008  it can be safely deleted, since all the information required for linking
5009  is embedded in the library file itself.
5010  Library files created using sdcclib are used as described in the preceding
5011  sections.
5012 \layout Section
5013
5014 Command Line Options
5015 \begin_inset LatexCommand \index{Command Line Options}
5016
5017 \end_inset
5018
5019
5020 \layout Subsection
5021
5022 Processor Selection Options
5023 \begin_inset LatexCommand \index{Options processor selection}
5024
5025 \end_inset
5026
5027
5028 \begin_inset LatexCommand \index{Processor selection options}
5029
5030 \end_inset
5031
5032
5033 \layout List
5034 \labelwidthstring 00.00.0000
5035
5036
5037 \series bold
5038 -mmcs51
5039 \begin_inset LatexCommand \index{-mmcs51}
5040
5041 \end_inset
5042
5043
5044 \series default
5045  Generate code for the Intel MCS51
5046 \begin_inset LatexCommand \index{MCS51}
5047
5048 \end_inset
5049
5050  family of processors.
5051  This is the default processor target.
5052 \layout List
5053 \labelwidthstring 00.00.0000
5054
5055
5056 \series bold
5057 -mds390
5058 \begin_inset LatexCommand \index{-mds390}
5059
5060 \end_inset
5061
5062
5063 \series default
5064  Generate code for the Dallas DS80C390
5065 \begin_inset LatexCommand \index{DS80C390}
5066
5067 \end_inset
5068
5069  processor.
5070 \layout List
5071 \labelwidthstring 00.00.0000
5072
5073
5074 \series bold
5075 -mds400
5076 \begin_inset LatexCommand \index{-mds400}
5077
5078 \end_inset
5079
5080
5081 \series default
5082  Generate code for the Dallas DS80C400
5083 \begin_inset LatexCommand \index{DS80C400}
5084
5085 \end_inset
5086
5087  processor.
5088 \layout List
5089 \labelwidthstring 00.00.0000
5090
5091
5092 \series bold
5093 -mhc08
5094 \begin_inset LatexCommand \index{-mhc08}
5095
5096 \end_inset
5097
5098
5099 \series default
5100  Generate code for the Freescale/Motorola HC08
5101 \begin_inset LatexCommand \index{HC08}
5102
5103 \end_inset
5104
5105  family of processors.
5106 \layout List
5107 \labelwidthstring 00.00.0000
5108
5109
5110 \series bold
5111 -mz80
5112 \begin_inset LatexCommand \index{-mz80}
5113
5114 \end_inset
5115
5116
5117 \series default
5118  Generate code for the Zilog Z80
5119 \begin_inset LatexCommand \index{Z80}
5120
5121 \end_inset
5122
5123  family of processors.
5124 \layout List
5125 \labelwidthstring 00.00.0000
5126
5127
5128 \series bold
5129 -mgbz80
5130 \begin_inset LatexCommand \index{-mgbz80}
5131
5132 \end_inset
5133
5134
5135 \series default
5136  Generate code for the GameBoy Z80
5137 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
5138
5139 \end_inset
5140
5141  processor (Not actively maintained).
5142 \layout List
5143 \labelwidthstring 00.00.0000
5144
5145
5146 \series bold
5147 -mavr
5148 \begin_inset LatexCommand \index{-mavr}
5149
5150 \end_inset
5151
5152
5153 \series default
5154  Generate code for the Atmel AVR
5155 \begin_inset LatexCommand \index{AVR}
5156
5157 \end_inset
5158
5159  processor (In development, not complete).
5160  AVR users should probably have a look at winavr
5161 \begin_inset LatexCommand \url{http://sourceforge.net/projects/winavr}
5162
5163 \end_inset
5164
5165  or
5166 \begin_inset LatexCommand \url{http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index}
5167
5168 \end_inset
5169
5170 .
5171 \layout Comment
5172
5173 I think it is fair to direct users there for now.
5174  Open source is also about avoiding unnecessary work .
5175  But I didn't find the 'official' link.
5176 \layout List
5177 \labelwidthstring 00.00.0000
5178
5179
5180 \series bold
5181 -mpic14
5182 \begin_inset LatexCommand \index{-mpic14}
5183
5184 \end_inset
5185
5186
5187 \series default
5188  Generate code for the Microchip PIC 14
5189 \begin_inset LatexCommand \index{PIC14}
5190
5191 \end_inset
5192
5193 -bit processors (p16f84 and variants.
5194  In development, not complete).
5195 \layout Comment
5196
5197 p16f627 p16f628 p16f84 p16f873 p16f877?
5198 \layout List
5199 \labelwidthstring 00.00.0000
5200
5201
5202 \series bold
5203 -mpic16
5204 \begin_inset LatexCommand \index{-mpic16}
5205
5206 \end_inset
5207
5208
5209 \series default
5210  Generate code for the Microchip PIC 16
5211 \begin_inset LatexCommand \index{PIC16}
5212
5213 \end_inset
5214
5215 -bit processors (p18f452 and variants.
5216  In development, not complete).
5217 \layout List
5218 \labelwidthstring 00.00.0000
5219
5220
5221 \series bold
5222 -mtlcs900h
5223 \series default
5224  Generate code for the Toshiba TLCS-900H
5225 \begin_inset LatexCommand \index{TLCS-900H}
5226
5227 \end_inset
5228
5229  processor (Not maintained, not complete).
5230 \layout List
5231 \labelwidthstring 00.00.0000
5232
5233
5234 \series bold
5235 -mxa51
5236 \begin_inset LatexCommand \index{-mxa51}
5237
5238 \end_inset
5239
5240
5241 \series default
5242  Generate code for the Phillips XA51
5243 \begin_inset LatexCommand \index{XA51}
5244
5245 \end_inset
5246
5247  processor (Not maintained, not complete).
5248 \layout Subsection
5249
5250 Preprocessor Options
5251 \begin_inset LatexCommand \index{Options preprocessor}
5252
5253 \end_inset
5254
5255
5256 \begin_inset LatexCommand \index{Preprocessor options}
5257
5258 \end_inset
5259
5260
5261 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5262
5263 \end_inset
5264
5265
5266 \layout List
5267 \labelwidthstring 00.00.0000
5268
5269
5270 \series bold
5271 -I<path>
5272 \begin_inset LatexCommand \index{-I<path>}
5273
5274 \end_inset
5275
5276
5277 \series default
5278  The additional location where the pre processor will look for <..h> or
5279 \begin_inset Quotes eld
5280 \end_inset
5281
5282 ..h
5283 \begin_inset Quotes erd
5284 \end_inset
5285
5286  files.
5287 \layout List
5288 \labelwidthstring 00.00.0000
5289
5290
5291 \series bold
5292 -D<macro[=value]>
5293 \begin_inset LatexCommand \index{-D<macro[=value]>}
5294
5295 \end_inset
5296
5297
5298 \series default
5299  Command line definition of macros.
5300  Passed to the preprocessor.
5301 \layout List
5302 \labelwidthstring 00.00.0000
5303
5304
5305 \series bold
5306 -M
5307 \begin_inset LatexCommand \index{-M}
5308
5309 \end_inset
5310
5311
5312 \series default
5313  Tell the preprocessor to output a rule suitable for make describing the
5314  dependencies of each object file.
5315  For each source file, the preprocessor outputs one make-rule whose target
5316  is the object file name for that source file and whose dependencies are
5317  all the files `#include'd in it.
5318  This rule may be a single line or may be continued with `
5319 \backslash
5320 '-newline if it is long.
5321  The list of rules is printed on standard output instead of the preprocessed
5322  C program.
5323  `-M' implies `-E
5324 \begin_inset LatexCommand \index{-E}
5325
5326 \end_inset
5327
5328 '.
5329 \layout List
5330 \labelwidthstring 00.00.0000
5331
5332
5333 \series bold
5334 -C
5335 \begin_inset LatexCommand \index{-C}
5336
5337 \end_inset
5338
5339
5340 \series default
5341  Tell the preprocessor not to discard comments.
5342  Used with the `-E' option.
5343 \layout List
5344 \labelwidthstring 00.00.0000
5345
5346
5347 \series bold
5348 -MM
5349 \begin_inset LatexCommand \index{-MM}
5350
5351 \end_inset
5352
5353
5354 \size large
5355 \bar under
5356
5357 \series default
5358 \size default
5359 \bar default
5360 Like `-M' but the output mentions only the user header files included with
5361  `#include
5362 \begin_inset Quotes eld
5363 \end_inset
5364
5365 file"'.
5366  System header files included with `#include <file>' are omitted.
5367 \layout List
5368 \labelwidthstring 00.00.0000
5369
5370
5371 \series bold
5372 -Aquestion(answer)
5373 \begin_inset LatexCommand \index{-Aquestion(answer)}
5374
5375 \end_inset
5376
5377
5378 \series default
5379  Assert the answer answer for question, in case it is tested with a preprocessor
5380  conditional such as `#if #question(answer)'.
5381  `-A-' disables the standard assertions that normally describe the target
5382  machine.
5383 \layout List
5384 \labelwidthstring 00.00.0000
5385
5386
5387 \series bold
5388 -Umacro
5389 \begin_inset LatexCommand \index{-Umacro}
5390
5391 \end_inset
5392
5393
5394 \series default
5395  Undefine macro macro.
5396  `-U' options are evaluated after all `-D' options, but before any `-include'
5397  and `-imacros' options.
5398 \layout List
5399 \labelwidthstring 00.00.0000
5400
5401
5402 \series bold
5403 -dM
5404 \begin_inset LatexCommand \index{-dM}
5405
5406 \end_inset
5407
5408
5409 \series default
5410  Tell the preprocessor to output only a list of the macro definitions that
5411  are in effect at the end of preprocessing.
5412  Used with the `-E' option.
5413 \layout List
5414 \labelwidthstring 00.00.0000
5415
5416
5417 \series bold
5418 -dD
5419 \begin_inset LatexCommand \index{-dD}
5420
5421 \end_inset
5422
5423
5424 \series default
5425  Tell the preprocessor to pass all macro definitions into the output, in
5426  their proper sequence in the rest of the output.
5427 \layout List
5428 \labelwidthstring 00.00.0000
5429
5430
5431 \series bold
5432 -dN
5433 \begin_inset LatexCommand \index{-dN}
5434
5435 \end_inset
5436
5437
5438 \size large
5439 \bar under
5440
5441 \series default
5442 \size default
5443 \bar default
5444 Like `-dD' except that the macro arguments and contents are omitted.
5445  Only `#define name' is included in the output.
5446 \layout List
5447 \labelwidthstring 00.00.0000
5448
5449
5450 \series bold
5451 -Wp\SpecialChar ~
5452 preprocessorOption[,preprocessorOption]
5453 \series default
5454
5455 \begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
5456
5457 \end_inset
5458
5459 ...
5460  Pass the preprocessorOption to the preprocessor
5461 \family typewriter
5462 sdcpp
5463 \family default
5464
5465 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5466
5467 \end_inset
5468
5469 .
5470  SDCC uses an adapted version of the preprocessor cpp of the GNU Compiler
5471  Collection (gcc), if you need more dedicated options please refer to the
5472  documentation at
5473 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
5474
5475 \end_inset
5476
5477 .
5478 \layout Subsection
5479
5480 Linker Options
5481 \begin_inset LatexCommand \index{Options linker}
5482
5483 \end_inset
5484
5485
5486 \begin_inset LatexCommand \index{Linker options}
5487
5488 \end_inset
5489
5490
5491 \layout List
5492 \labelwidthstring 00.00.0000
5493
5494
5495 \series bold
5496 -L\SpecialChar ~
5497 -
5498 \series default
5499
5500 \begin_inset ERT
5501 status Collapsed
5502
5503 \layout Standard
5504
5505 \backslash
5506 /
5507 \end_inset
5508
5509
5510 \series bold
5511 -lib-path
5512 \begin_inset LatexCommand \index{-\/-lib-path <path>}
5513
5514 \end_inset
5515
5516
5517 \begin_inset LatexCommand \index{-L -\/-lib-path}
5518
5519 \end_inset
5520
5521
5522 \series default
5523 \SpecialChar ~
5524 <absolute path to additional libraries> This option is passed to the linkage
5525  editor's additional libraries
5526 \begin_inset LatexCommand \index{Libraries}
5527
5528 \end_inset
5529
5530  search path.
5531  The path name must be absolute.
5532  Additional library files may be specified in the command line.
5533  See section Compiling programs for more details.
5534 \layout List
5535 \labelwidthstring 00.00.0000
5536
5537
5538 \series bold
5539 -
5540 \begin_inset ERT
5541 status Collapsed
5542
5543 \layout Standard
5544
5545 \backslash
5546 /
5547 \end_inset
5548
5549 -xram-loc
5550 \series default
5551
5552 \begin_inset LatexCommand \index{-\/-xram-loc <Value>}
5553
5554 \end_inset
5555
5556 \SpecialChar ~
5557 <Value> The start location of the external ram
5558 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
5559
5560 \end_inset
5561
5562 , default value is 0.
5563  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5564 \begin_inset ERT
5565 status Collapsed
5566
5567 \layout Standard
5568
5569 \backslash
5570 /
5571 \end_inset
5572
5573 -xram-loc 0x8000 or -
5574 \begin_inset ERT
5575 status Collapsed
5576
5577 \layout Standard
5578
5579 \backslash
5580 /
5581 \end_inset
5582
5583 -xram-loc 32768.
5584 \layout List
5585 \labelwidthstring 00.00.0000
5586
5587
5588 \series bold
5589 -
5590 \begin_inset ERT
5591 status Collapsed
5592
5593 \layout Standard
5594
5595 \backslash
5596 /
5597 \end_inset
5598
5599 -code-loc
5600 \series default
5601
5602 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
5603
5604 \end_inset
5605
5606 \SpecialChar ~
5607 <Value> The start location of the code
5608 \begin_inset LatexCommand \index{code}
5609
5610 \end_inset
5611
5612  segment, default value 0.
5613  Note when this option is used the interrupt vector table is also relocated
5614  to the given address.
5615  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5616 \begin_inset ERT
5617 status Collapsed
5618
5619 \layout Standard
5620
5621 \backslash
5622 /
5623 \end_inset
5624
5625 -code-loc 0x8000 or -
5626 \begin_inset ERT
5627 status Collapsed
5628
5629 \layout Standard
5630
5631 \backslash
5632 /
5633 \end_inset
5634
5635 -code-loc 32768.
5636 \layout List
5637 \labelwidthstring 00.00.0000
5638
5639
5640 \series bold
5641 -
5642 \begin_inset ERT
5643 status Collapsed
5644
5645 \layout Standard
5646
5647 \backslash
5648 /
5649 \end_inset
5650
5651 -stack-loc
5652 \series default
5653
5654 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
5655
5656 \end_inset
5657
5658 \SpecialChar ~
5659 <Value> By default the stack
5660 \begin_inset LatexCommand \index{stack}
5661
5662 \end_inset
5663
5664  is placed after the data segment.
5665  Using this option the stack can be placed anywhere in the internal memory
5666  space of the 8051.
5667  The value entered can be in Hexadecimal or Decimal format, e.g.
5668  -
5669 \begin_inset ERT
5670 status Collapsed
5671
5672 \layout Standard
5673
5674 \backslash
5675 /
5676 \end_inset
5677
5678 -stack-loc 0x20 or -
5679 \begin_inset ERT
5680 status Collapsed
5681
5682 \layout Standard
5683
5684 \backslash
5685 /
5686 \end_inset
5687
5688 -stack-loc 32.
5689  Since the sp register is incremented before a push or call, the initial
5690  sp will be set to one byte prior the provided value.
5691  The provided value should not overlap any other memory areas such as used
5692  register banks or the data segment and with enough space for the current
5693  application.
5694  The
5695 \series bold
5696 -
5697 \begin_inset ERT
5698 status Collapsed
5699
5700 \layout Standard
5701
5702 \backslash
5703 /
5704 \end_inset
5705
5706 -pack-iram
5707 \series default
5708 \SpecialChar ~
5709
5710 \begin_inset LatexCommand \index{-\/-pack-iram}
5711
5712 \end_inset
5713
5714  option (which is now a default setting) will override this setting, so
5715  you should also specify the
5716 \series bold
5717 -
5718 \begin_inset ERT
5719 status Collapsed
5720
5721 \layout Standard
5722
5723 \backslash
5724 /
5725 \end_inset
5726
5727 -no-pack-iram
5728 \series default
5729 \SpecialChar ~
5730
5731 \begin_inset LatexCommand \index{-\/-no-pack-iram}
5732
5733 \end_inset
5734
5735  option if you need to manually place the stack.
5736 \layout List
5737 \labelwidthstring 00.00.0000
5738
5739
5740 \series bold
5741 -
5742 \begin_inset ERT
5743 status Collapsed
5744
5745 \layout Standard
5746
5747 \backslash
5748 /
5749 \end_inset
5750
5751 -data-loc
5752 \series default
5753
5754 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
5755
5756 \end_inset
5757
5758 \SpecialChar ~
5759 <Value> The start location of the internal ram data
5760 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
5761
5762 \end_inset
5763
5764  segment.
5765  The value entered can be in Hexadecimal or Decimal format, eg.
5766  -
5767 \begin_inset ERT
5768 status Collapsed
5769
5770 \layout Standard
5771
5772 \backslash
5773 /
5774 \end_inset
5775
5776 -data-loc 0x20 or -
5777 \begin_inset ERT
5778 status Collapsed
5779
5780 \layout Standard
5781
5782 \backslash
5783 /
5784 \end_inset
5785
5786 -data-loc 32.
5787  (By default, the start location of the internal ram data segment  is set
5788  as low as possible in memory, taking into account the used register banks
5789  and the bit segment at address 0x20.
5790  For example if register banks 0 and 1 are used without bit variables, the
5791  data segment will be set, if -
5792 \begin_inset ERT
5793 status Collapsed
5794
5795 \layout Standard
5796
5797 \backslash
5798 /
5799 \end_inset
5800
5801 -data-loc is not used, to location 0x10.)
5802 \layout List
5803 \labelwidthstring 00.00.0000
5804
5805
5806 \series bold
5807 -
5808 \begin_inset ERT
5809 status Collapsed
5810
5811 \layout Standard
5812
5813 \backslash
5814 /
5815 \end_inset
5816
5817 -idata-loc
5818 \series default
5819
5820 \begin_inset LatexCommand \index{-\/-idata-loc <Value>}
5821
5822 \end_inset
5823
5824 \SpecialChar ~
5825 <Value> The start location of the indirectly addressable internal ram
5826 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
5827
5828 \end_inset
5829
5830  of the 8051, default value is 0x80.
5831  The value entered can be in Hexadecimal or Decimal format, eg.
5832  -
5833 \begin_inset ERT
5834 status Collapsed
5835
5836 \layout Standard
5837
5838 \backslash
5839 /
5840 \end_inset
5841
5842 -idata-loc 0x88 or -
5843 \begin_inset ERT
5844 status Collapsed
5845
5846 \layout Standard
5847
5848 \backslash
5849 /
5850 \end_inset
5851
5852 -idata-loc 136.
5853 \layout List
5854 \labelwidthstring 00.00.0000
5855
5856
5857 \series bold
5858 -
5859 \begin_inset ERT
5860 status Collapsed
5861
5862 \layout Standard
5863
5864 \backslash
5865 /
5866 \end_inset
5867
5868 -bit-loc
5869 \series default
5870 \SpecialChar ~
5871 <Value> The start location of the bit
5872 \begin_inset LatexCommand \index{bit}
5873
5874 \end_inset
5875
5876  addressable internal ram of the 8051.
5877  This is
5878 \emph on
5879 not
5880 \emph default
5881  implemented yet.
5882  Instead an option can be passed directly to the linker: -Wl\SpecialChar ~
5883 -bBSEG=<Value>.
5884 \layout List
5885 \labelwidthstring 00.00.0000
5886
5887
5888 \series bold
5889 -
5890 \begin_inset ERT
5891 status Collapsed
5892
5893 \layout Standard
5894
5895 \backslash
5896 /
5897 \end_inset
5898
5899 -out-fmt-ihx
5900 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
5901
5902 \end_inset
5903
5904
5905 \bar under
5906
5907 \series default
5908 \bar default
5909 The linker output (final object code) is in Intel Hex format.
5910 \begin_inset LatexCommand \index{Intel hex format}
5911
5912 \end_inset
5913
5914  This is the default option.
5915  The format itself is documented in the documentation of srecord
5916 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
5917
5918 \end_inset
5919
5920 .
5921 \layout List
5922 \labelwidthstring 00.00.0000
5923
5924
5925 \series bold
5926 -
5927 \begin_inset ERT
5928 status Collapsed
5929
5930 \layout Standard
5931
5932 \backslash
5933 /
5934 \end_inset
5935
5936 -out-fmt-s19
5937 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
5938
5939 \end_inset
5940
5941
5942 \bar under
5943
5944 \series default
5945 \bar default
5946 The linker output (final object code) is in Motorola S19 format
5947 \begin_inset LatexCommand \index{Motorola S19 format}
5948
5949 \end_inset
5950
5951 .
5952  The format itself is documented in the documentation of srecord.
5953 \layout List
5954 \labelwidthstring 00.00.0000
5955
5956
5957 \series bold
5958 -
5959 \begin_inset ERT
5960 status Collapsed
5961
5962 \layout Standard
5963
5964 \backslash
5965 /
5966 \end_inset
5967
5968 -out-fmt-elf
5969 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
5970
5971 \end_inset
5972
5973
5974 \bar under
5975
5976 \series default
5977 \bar default
5978 The linker output (final object code) is in ELF format
5979 \begin_inset LatexCommand \index{ELF format}
5980
5981 \end_inset
5982
5983 .
5984  (Currently only supported for the HC08 processors)
5985 \layout List
5986 \labelwidthstring 00.00.0000
5987
5988
5989 \series bold
5990 -Wl\SpecialChar ~
5991 linkOption[,linkOption]
5992 \series default
5993
5994 \begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
5995
5996 \end_inset
5997
5998 ...
5999  Pass the linkOption to the linker.
6000  See file sdcc/as/doc/asxhtm.html for more on linker options.
6001 \layout Subsection
6002
6003 MCS51 Options
6004 \begin_inset LatexCommand \index{Options MCS51}
6005
6006 \end_inset
6007
6008
6009 \begin_inset LatexCommand \index{MCS51 options}
6010
6011 \end_inset
6012
6013
6014 \layout List
6015 \labelwidthstring 00.00.0000
6016
6017
6018 \series bold
6019 -
6020 \begin_inset ERT
6021 status Collapsed
6022
6023 \layout Standard
6024
6025 \backslash
6026 /
6027 \end_inset
6028
6029 -model-small
6030 \begin_inset LatexCommand \index{-\/-model-small}
6031
6032 \end_inset
6033
6034
6035 \series default
6036 \size large
6037 \emph on
6038
6039 \size default
6040 \emph default
6041 Generate code for Small Model programs, see section Memory Models for more
6042  details.
6043  This is the default model.
6044 \layout List
6045 \labelwidthstring 00.00.0000
6046
6047
6048 \series bold
6049 -
6050 \begin_inset ERT
6051 status Collapsed
6052
6053 \layout Standard
6054
6055 \backslash
6056 /
6057 \end_inset
6058
6059 -model-medium
6060 \begin_inset LatexCommand \index{-\/-model-medium}
6061
6062 \end_inset
6063
6064
6065 \series default
6066  Generate code for Medium model programs, see section Memory Models for
6067  more details.
6068  If this option is used all source files in the project have to be compiled
6069  with this option.
6070  It must also be used when invoking the linker.
6071 \layout List
6072 \labelwidthstring 00.00.0000
6073
6074
6075 \series bold
6076 -
6077 \begin_inset ERT
6078 status Collapsed
6079
6080 \layout Standard
6081
6082 \backslash
6083 /
6084 \end_inset
6085
6086 -model-large
6087 \begin_inset LatexCommand \index{-\/-model-large}
6088
6089 \end_inset
6090
6091
6092 \series default
6093  Generate code for Large model programs, see section Memory Models for more
6094  details.
6095  If this option is used all source files in the project have to be compiled
6096  with this option.
6097  It must also be used when invoking the linker.
6098 \layout List
6099 \labelwidthstring 00.00.0000
6100
6101
6102 \series bold
6103 -
6104 \begin_inset ERT
6105 status Collapsed
6106
6107 \layout Standard
6108
6109 \backslash
6110 /
6111 \end_inset
6112
6113 -xstack
6114 \begin_inset LatexCommand \index{-\/-xstack}
6115
6116 \end_inset
6117
6118
6119 \series default
6120  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
6121  variables and passing parameters.
6122  See section
6123 \begin_inset LatexCommand \ref{sub:External-Stack}
6124
6125 \end_inset
6126
6127 \SpecialChar ~
6128  External Stack for more details.
6129 \layout List
6130 \labelwidthstring 00.00.0000
6131
6132
6133 \series bold
6134 -
6135 \begin_inset ERT
6136 status Collapsed
6137
6138 \layout Standard
6139
6140 \backslash
6141 /
6142 \end_inset
6143
6144 -iram-size
6145 \series default
6146 \SpecialChar ~
6147 <Value>
6148 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
6149
6150 \end_inset
6151
6152  Causes the linker to check if the internal ram usage is within limits of
6153  the given value.
6154 \layout List
6155 \labelwidthstring 00.00.0000
6156
6157
6158 \series bold
6159 -
6160 \begin_inset ERT
6161 status Collapsed
6162
6163 \layout Standard
6164
6165 \backslash
6166 /
6167 \end_inset
6168
6169 -xram-size
6170 \series default
6171 \SpecialChar ~
6172 <Value>
6173 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
6174
6175 \end_inset
6176
6177  Causes the linker to check if the external ram usage is within limits of
6178  the given value.
6179 \layout List
6180 \labelwidthstring 00.00.0000
6181
6182
6183 \series bold
6184 -
6185 \begin_inset ERT
6186 status Collapsed
6187
6188 \layout Standard
6189
6190 \backslash
6191 /
6192 \end_inset
6193
6194 -code-size
6195 \series default
6196 \SpecialChar ~
6197 <Value>
6198 \begin_inset LatexCommand \index{-\/-code-size <Value>}
6199
6200 \end_inset
6201
6202  Causes the linker to check if the code memory usage is within limits of
6203  the given value.
6204 \layout List
6205 \labelwidthstring 00.00.0000
6206
6207
6208 \series bold
6209 -
6210 \begin_inset ERT
6211 status Collapsed
6212
6213 \layout Standard
6214
6215 \backslash
6216 /
6217 \end_inset
6218
6219 -stack-size
6220 \series default
6221 \SpecialChar ~
6222 <Value>
6223 \begin_inset LatexCommand \index{-\/-stack-size <Value>}
6224
6225 \end_inset
6226
6227  Causes the linker to check if there is at minimum <Value> bytes for stack.
6228 \layout List
6229 \labelwidthstring 00.00.0000
6230
6231
6232 \series bold
6233 -
6234 \begin_inset ERT
6235 status Collapsed
6236
6237 \layout Standard
6238
6239 \backslash
6240 /
6241 \end_inset
6242
6243 -pack-iram
6244 \series default
6245 \SpecialChar ~
6246
6247 \begin_inset LatexCommand \index{-\/-pack-iram}
6248
6249 \end_inset
6250
6251  Causes the linker to use unused register banks for data variables and pack
6252  data, idata and stack together.
6253  This is the default now.
6254 \layout List
6255 \labelwidthstring 00.00.0000
6256
6257
6258 \series bold
6259 -
6260 \begin_inset ERT
6261 status Collapsed
6262
6263 \layout Standard
6264
6265 \backslash
6266 /
6267 \end_inset
6268
6269 -no-pack-iram
6270 \series default
6271 \SpecialChar ~
6272
6273 \begin_inset LatexCommand \index{-\/-no-pack-iram}
6274
6275 \end_inset
6276
6277  Causes the linker to use old style for allocating memory areas.
6278 \layout Subsection
6279
6280 DS390 / DS400 Options
6281 \begin_inset LatexCommand \index{Options DS390}
6282
6283 \end_inset
6284
6285
6286 \begin_inset LatexCommand \index{DS390 options}
6287
6288 \end_inset
6289
6290
6291 \layout List
6292 \labelwidthstring 00.00.0000
6293
6294
6295 \series bold
6296 -
6297 \begin_inset ERT
6298 status Collapsed
6299
6300 \layout Standard
6301
6302 \backslash
6303 /
6304 \end_inset
6305
6306 -model-flat24
6307 \series default
6308
6309 \begin_inset LatexCommand \index{-\/-model-flat24}
6310
6311 \end_inset
6312
6313
6314 \size large
6315 \emph on
6316
6317 \size default
6318 \emph default
6319 Generate 24-bit flat mode code.
6320  This is the one and only that the ds390 code generator supports right now
6321  and is default when using
6322 \emph on
6323 -mds390
6324 \emph default
6325 .
6326  See section Memory Models for more details.
6327 \layout List
6328 \labelwidthstring 00.00.0000
6329
6330
6331 \series bold
6332 -
6333 \begin_inset ERT
6334 status Collapsed
6335
6336 \layout Standard
6337
6338 \backslash
6339 /
6340 \end_inset
6341
6342 -protect-sp-update
6343 \begin_inset LatexCommand \index{-\/-protect-sp-update}
6344
6345 \end_inset
6346
6347
6348 \series default
6349  disable interrupts during ESP:SP updates.
6350 \layout List
6351 \labelwidthstring 00.00.0000
6352
6353
6354 \series bold
6355 -
6356 \begin_inset ERT
6357 status Collapsed
6358
6359 \layout Standard
6360
6361 \backslash
6362 /
6363 \end_inset
6364
6365 -stack-10bit
6366 \series default
6367
6368 \begin_inset LatexCommand \index{-\/-stack-10bit}
6369
6370 \end_inset
6371
6372  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
6373  This is the one and only that the ds390 code generator supports right now
6374  and is default when using
6375 \emph on
6376 -mds390
6377 \emph default
6378 .
6379  In this mode, the stack is located in the lower 1K of the internal RAM,
6380  which is mapped to 0x400000.
6381  Note that the support is incomplete, since it still uses a single byte
6382  as the stack pointer.
6383  This means that only the lower 256 bytes of the potential 1K stack space
6384  will actually be used.
6385  However, this does allow you to reclaim the precious 256 bytes of low RAM
6386  for use for the DATA and IDATA segments.
6387  The compiler will not generate any code to put the processor into 10 bit
6388  stack mode.
6389  It is important to ensure that the processor is in this mode before calling
6390  any re-entrant functions compiled with this option.
6391  In principle, this should work with the
6392 \emph on
6393 -
6394 \begin_inset ERT
6395 status Collapsed
6396
6397 \layout Standard
6398
6399 \backslash
6400 /
6401 \end_inset
6402
6403 -stack-auto
6404 \begin_inset LatexCommand \index{-\/-stack-auto}
6405
6406 \end_inset
6407
6408
6409 \emph default
6410  option, but that has not been tested.
6411  It is incompatible with the
6412 \emph on
6413 -
6414 \begin_inset ERT
6415 status Collapsed
6416
6417 \layout Standard
6418
6419 \backslash
6420 /
6421 \end_inset
6422
6423 -xstack
6424 \begin_inset LatexCommand \index{-\/-xstack}
6425
6426 \end_inset
6427
6428
6429 \emph default
6430  option.
6431  It also only makes sense if the processor is in 24 bit contiguous addressing
6432  mode (see the
6433 \emph on
6434 -
6435 \begin_inset ERT
6436 status Collapsed
6437
6438 \layout Standard
6439
6440 \backslash
6441 /
6442 \end_inset
6443
6444 -model-flat24 option
6445 \emph default
6446 ).
6447 \layout List
6448 \labelwidthstring 00.00.0000
6449
6450
6451 \series bold
6452 -
6453 \begin_inset ERT
6454 status Collapsed
6455
6456 \layout Standard
6457
6458 \backslash
6459 /
6460 \end_inset
6461
6462 -stack-probe
6463 \begin_inset LatexCommand \index{-\/-stack-probe}
6464
6465 \end_inset
6466
6467
6468 \series default
6469  insert call to function __stack_probe at each function prologue.
6470 \layout List
6471 \labelwidthstring 00.00.0000
6472
6473
6474 \series bold
6475 -
6476 \begin_inset ERT
6477 status Collapsed
6478
6479 \layout Standard
6480
6481 \backslash
6482 /
6483 \end_inset
6484
6485 -tini-libid
6486 \begin_inset LatexCommand \index{-\/-tini-libid}
6487
6488 \end_inset
6489
6490
6491 \series default
6492  <nnnn> LibraryID used in -mTININative.
6493
6494 \layout List
6495 \labelwidthstring 00.00.0000
6496
6497
6498 \series bold
6499 -
6500 \begin_inset ERT
6501 status Collapsed
6502
6503 \layout Standard
6504
6505 \backslash
6506 /
6507 \end_inset
6508
6509 -use-accelerator
6510 \begin_inset LatexCommand \index{-\/-use-accelerator}
6511
6512 \end_inset
6513
6514
6515 \series default
6516  generate code for DS390 Arithmetic Accelerator.
6517
6518 \layout Subsection
6519
6520 Z80 Options
6521 \begin_inset LatexCommand \index{Options Z80}
6522
6523 \end_inset
6524
6525
6526 \begin_inset LatexCommand \index{Z80 options}
6527
6528 \end_inset
6529
6530
6531 \layout List
6532 \labelwidthstring 00.00.0000
6533
6534
6535 \series bold
6536 -
6537 \begin_inset ERT
6538 status Collapsed
6539
6540 \layout Standard
6541
6542 \backslash
6543 /
6544 \end_inset
6545
6546 -callee-saves-bc
6547 \series default
6548
6549 \begin_inset LatexCommand \index{-\/-callee-saves-bc}
6550
6551 \end_inset
6552
6553
6554 \size large
6555 \emph on
6556
6557 \size default
6558 \emph default
6559 Force a called function to always save BC.
6560 \layout List
6561 \labelwidthstring 00.00.0000
6562
6563
6564 \series bold
6565 -
6566 \begin_inset ERT
6567 status Collapsed
6568
6569 \layout Standard
6570
6571 \backslash
6572 /
6573 \end_inset
6574
6575 -no-std-crt0
6576 \series default
6577
6578 \begin_inset LatexCommand \index{-\/-no-std-crt0}
6579
6580 \end_inset
6581
6582  When linking, skip the standard crt0.o object file.
6583  You must provide your own crt0.o for your system when linking.
6584
6585 \layout Subsection
6586
6587 Optimization Options
6588 \begin_inset LatexCommand \index{Options optimization}
6589
6590 \end_inset
6591
6592
6593 \begin_inset LatexCommand \index{Optimization options}
6594
6595 \end_inset
6596
6597
6598 \layout List
6599 \labelwidthstring 00.00.0000
6600
6601
6602 \series bold
6603 -
6604 \begin_inset ERT
6605 status Collapsed
6606
6607 \layout Standard
6608
6609 \backslash
6610 /
6611 \end_inset
6612
6613 -nogcse
6614 \begin_inset LatexCommand \index{-\/-nogcse}
6615
6616 \end_inset
6617
6618
6619 \series default
6620  Will not do global subexpression elimination, this option may be used when
6621  the compiler creates undesirably large stack/data spaces to store compiler
6622  temporaries (
6623 \emph on
6624 s
6625 \emph default
6626 pill
6627 \emph on
6628 loc
6629 \emph default
6630 ations, sloc
6631 \begin_inset LatexCommand \index{sloc (spill location)}
6632
6633 \end_inset
6634
6635 ).
6636  A warning message will be generated when this happens and the compiler
6637  will indicate the number of extra bytes it allocated.
6638  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6639 nogcse
6640 \begin_inset LatexCommand \index{\#pragma nogcse}
6641
6642 \end_inset
6643
6644  can be used to turn off global subexpression elimination
6645 \begin_inset LatexCommand \index{Subexpression elimination}
6646
6647 \end_inset
6648
6649  for a given function only.
6650 \layout List
6651 \labelwidthstring 00.00.0000
6652
6653
6654 \series bold
6655 -
6656 \begin_inset ERT
6657 status Collapsed
6658
6659 \layout Standard
6660
6661 \backslash
6662 /
6663 \end_inset
6664
6665 -noinvariant
6666 \begin_inset LatexCommand \index{-\/-noinvariant}
6667
6668 \end_inset
6669
6670
6671 \series default
6672  Will not do loop invariant optimizations, this may be turned off for reasons
6673  explained for the previous option.
6674  For more details of loop optimizations performed see Loop Invariants in
6675  section
6676 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
6677
6678 \end_inset
6679
6680 .
6681  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6682 noinvariant
6683 \begin_inset LatexCommand \index{\#pragma noinvariant}
6684
6685 \end_inset
6686
6687  can be used to turn off invariant optimizations for a given function only.
6688 \layout List
6689 \labelwidthstring 00.00.0000
6690
6691
6692 \series bold
6693 -
6694 \begin_inset ERT
6695 status Collapsed
6696
6697 \layout Standard
6698
6699 \backslash
6700 /
6701 \end_inset
6702
6703 -noinduction
6704 \begin_inset LatexCommand \index{-\/-noinduction}
6705
6706 \end_inset
6707
6708
6709 \series default
6710  Will not do loop induction optimizations, see section strength reduction
6711  for more details.
6712  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6713 noinduction
6714 \begin_inset LatexCommand \index{\#pragma noinduction}
6715
6716 \end_inset
6717
6718  can be used to turn off induction optimizations for a given function only.
6719 \layout List
6720 \labelwidthstring 00.00.0000
6721
6722
6723 \series bold
6724 -
6725 \begin_inset ERT
6726 status Collapsed
6727
6728 \layout Standard
6729
6730 \backslash
6731 /
6732 \end_inset
6733
6734 -nojtbound
6735 \begin_inset LatexCommand \index{-\/-nojtbound}
6736
6737 \end_inset
6738
6739
6740 \size large
6741 \bar under
6742
6743 \series default
6744 \size default
6745 \bar default
6746  Will not generate boundary condition check when switch statements
6747 \begin_inset LatexCommand \index{switch statement}
6748
6749 \end_inset
6750
6751  are implemented using jump-tables.
6752  See section
6753 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
6754
6755 \end_inset
6756
6757 \SpecialChar ~
6758 Switch Statements for more details.
6759  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6760 nojtbound
6761 \begin_inset LatexCommand \index{\#pragma nojtbound}
6762
6763 \end_inset
6764
6765  can be used to turn off boundary checking for jump tables for a given function
6766  only.
6767 \layout List
6768 \labelwidthstring 00.00.0000
6769
6770
6771 \series bold
6772 -
6773 \begin_inset ERT
6774 status Collapsed
6775
6776 \layout Standard
6777
6778 \backslash
6779 /
6780 \end_inset
6781
6782 -noloopreverse
6783 \begin_inset LatexCommand \index{-\/-noloopreverse}
6784
6785 \end_inset
6786
6787
6788 \series default
6789 \size large
6790
6791 \size default
6792 Will not do loop reversal
6793 \begin_inset LatexCommand \index{Loop reversing}
6794
6795 \end_inset
6796
6797 optimization.
6798 \layout List
6799 \labelwidthstring 00.00.0000
6800
6801 -
6802 \begin_inset ERT
6803 status Collapsed
6804
6805 \layout Standard
6806
6807 \backslash
6808 /
6809 \end_inset
6810
6811 -
6812 \series bold
6813 nolabelopt
6814 \series default
6815
6816 \begin_inset LatexCommand \index{-\/-nolabelopt }
6817
6818 \end_inset
6819
6820 Will not optimize labels (makes the dumpfiles more readable).
6821 \layout List
6822 \labelwidthstring 00.00.0000
6823
6824
6825 \series bold
6826 -
6827 \begin_inset ERT
6828 status Collapsed
6829
6830 \layout Standard
6831
6832 \backslash
6833 /
6834 \end_inset
6835
6836 -no-xinit-opt
6837 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
6838
6839 \end_inset
6840
6841
6842 \series default
6843  Will not memcpy initialized data from code space into xdata space.
6844  This saves a few bytes in code space if you don't have initialized data
6845 \begin_inset LatexCommand \index{Variable initialization}
6846
6847 \end_inset
6848
6849 .
6850 \layout List
6851 \labelwidthstring 00.00.0000
6852
6853
6854 \series bold
6855 -
6856 \begin_inset ERT
6857 status Collapsed
6858
6859 \layout Standard
6860
6861 \backslash
6862 /
6863 \end_inset
6864
6865 -nooverlay
6866 \begin_inset LatexCommand \index{-\/-nooverlay}
6867
6868 \end_inset
6869
6870
6871 \series default
6872   The compiler will not overlay parameters and local variables of any function,
6873  see section Parameters and local variables for more details.
6874 \layout List
6875 \labelwidthstring 00.00.0000
6876
6877
6878 \series bold
6879 -
6880 \begin_inset ERT
6881 status Collapsed
6882
6883 \layout Standard
6884
6885 \backslash
6886 /
6887 \end_inset
6888
6889 -no-peep
6890 \begin_inset LatexCommand \index{-\/-no-peep}
6891
6892 \end_inset
6893
6894
6895 \series default
6896  Disable peep-hole optimization.
6897 \layout List
6898 \labelwidthstring 00.00.0000
6899
6900
6901 \series bold
6902 -
6903 \begin_inset ERT
6904 status Collapsed
6905
6906 \layout Standard
6907
6908 \backslash
6909 /
6910 \end_inset
6911
6912 -peep-file
6913 \series default
6914
6915 \begin_inset LatexCommand \index{-\/-peep-file}
6916
6917 \end_inset
6918
6919 \SpecialChar ~
6920 <filename> This option can be used to use additional rules to be used by
6921  the peep hole optimizer.
6922  See section
6923 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
6924
6925 \end_inset
6926
6927 \SpecialChar ~
6928 Peep Hole optimizations for details on how to write these rules.
6929 \layout List
6930 \labelwidthstring 00.00.0000
6931
6932
6933 \series bold
6934 -
6935 \begin_inset ERT
6936 status Collapsed
6937
6938 \layout Standard
6939
6940 \backslash
6941 /
6942 \end_inset
6943
6944 -peep-asm
6945 \begin_inset LatexCommand \index{-\/-peep-asm}
6946
6947 \end_inset
6948
6949
6950 \series default
6951  Pass the inline assembler code through the peep hole optimizer.
6952  This can cause unexpected changes to inline assembler code, please go through
6953  the peephole optimizer
6954 \begin_inset LatexCommand \index{Peephole optimizer}
6955
6956 \end_inset
6957
6958  rules defined in the source file tree '<target>/peeph.def' before using
6959  this option.
6960 \layout List
6961 \labelwidthstring 00.00.0000
6962
6963
6964 \series bold
6965 -
6966 \begin_inset ERT
6967 status Collapsed
6968
6969 \layout Standard
6970
6971 \backslash
6972 /
6973 \end_inset
6974
6975 -opt-code-speed
6976 \begin_inset LatexCommand \index{-\/-opt-code-speed}
6977
6978 \end_inset
6979
6980
6981 \series default
6982  The compiler will optimize code generation towards fast code, possibly
6983  at the expense of code size.
6984 \layout List
6985 \labelwidthstring 00.00.0000
6986
6987
6988 \series bold
6989 -
6990 \begin_inset ERT
6991 status Collapsed
6992
6993 \layout Standard
6994
6995 \backslash
6996 /
6997 \end_inset
6998
6999 -opt-code-size
7000 \begin_inset LatexCommand \index{-\/-opt-code-size}
7001
7002 \end_inset
7003
7004
7005 \series default
7006  The compiler will optimize code generation towards compact code, possibly
7007  at the expense of code speed.
7008 \layout Subsection
7009
7010 Other Options
7011 \begin_inset LatexCommand \index{Options other}
7012
7013 \end_inset
7014
7015
7016 \layout List
7017 \labelwidthstring 00.00.0000
7018
7019
7020 \series bold
7021 -c\SpecialChar ~
7022 -
7023 \begin_inset ERT
7024 status Collapsed
7025
7026 \layout Standard
7027
7028 \backslash
7029 /
7030 \end_inset
7031
7032 -compile-only
7033 \begin_inset LatexCommand \index{-\/-compile-only}
7034
7035 \end_inset
7036
7037
7038 \begin_inset LatexCommand \index{-c -\/-compile-only}
7039
7040 \end_inset
7041
7042
7043 \series default
7044  will compile and assemble the source, but will not call the linkage editor.
7045 \layout List
7046 \labelwidthstring 00.00.0000
7047
7048
7049 \series bold
7050 -
7051 \series default
7052
7053 \begin_inset ERT
7054 status Collapsed
7055
7056 \layout Standard
7057
7058 \backslash
7059 /
7060 \end_inset
7061
7062
7063 \series bold
7064 -c1mode
7065 \begin_inset LatexCommand \index{-\/-c1mode}
7066
7067 \end_inset
7068
7069
7070 \series default
7071  reads the preprocessed source from standard input and compiles it.
7072  The file name for the assembler output must be specified using the -o option.
7073 \layout List
7074 \labelwidthstring 00.00.0000
7075
7076
7077 \series bold
7078 -E
7079 \begin_inset LatexCommand \index{-E}
7080
7081 \end_inset
7082
7083
7084 \series default
7085  Run only the C preprocessor.
7086  Preprocess all the C source files specified and output the results to standard
7087  output.
7088 \layout List
7089 \labelwidthstring 00.00.0000
7090
7091
7092 \series bold
7093 -o\SpecialChar ~
7094 <path/file>
7095 \begin_inset LatexCommand \index{-o <path/file>}
7096
7097 \end_inset
7098
7099
7100 \series default
7101 The output path resp.
7102  file where everything will be placed.
7103  If the parameter is a path, it must have a trailing slash (or backslash
7104  for the Windows binaries) to be recognized as a path.
7105
7106 \layout List
7107 \labelwidthstring 00.00.0000
7108
7109
7110 \series bold
7111 -
7112 \begin_inset ERT
7113 status Collapsed
7114
7115 \layout Standard
7116
7117 \backslash
7118 /
7119 \end_inset
7120
7121 -stack-auto
7122 \begin_inset LatexCommand \index{-\/-stack-auto}
7123
7124 \end_inset
7125
7126
7127 \series default
7128 \size large
7129 \emph on
7130
7131 \size default
7132 \emph default
7133 All functions in the source file will be compiled as
7134 \emph on
7135 reentrant
7136 \emph default
7137
7138 \begin_inset LatexCommand \index{reentrant}
7139
7140 \end_inset
7141
7142 , i.e.
7143  the parameters and local variables will be allocated on the stack
7144 \begin_inset LatexCommand \index{stack}
7145
7146 \end_inset
7147
7148 .
7149  See section
7150 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
7151
7152 \end_inset
7153
7154  Parameters and Local Variables for more details.
7155  If this option is used all source files in the project should be compiled
7156  with this option.
7157  It automatically implies --int-long-reent and --float-reent.
7158
7159 \layout List
7160 \labelwidthstring 00.00.0000
7161
7162
7163 \series bold
7164 -
7165 \begin_inset ERT
7166 status Collapsed
7167
7168 \layout Standard
7169
7170 \backslash
7171 /
7172 \end_inset
7173
7174 -callee-saves
7175 \begin_inset LatexCommand \index{-\/-callee-saves}
7176
7177 \end_inset
7178
7179  function1[,function2][,function3]....
7180
7181 \series default
7182  The compiler by default uses a caller saves convention for register saving
7183  across function calls, however this can cause unnecessary register pushing
7184  & popping when calling small functions from larger functions.
7185  This option can be used to switch the register saving convention for the
7186  function names specified.
7187  The compiler will not save registers when calling these functions, no extra
7188  code will be generated at the entry & exit (function prologue
7189 \series bold
7190
7191 \begin_inset LatexCommand \index{function prologue}
7192
7193 \end_inset
7194
7195
7196 \series default
7197  & epilogue
7198 \series bold
7199
7200 \begin_inset LatexCommand \index{function epilogue}
7201
7202 \end_inset
7203
7204
7205 \series default
7206 ) for these functions to save & restore the registers used by these functions,
7207  this can SUBSTANTIALLY reduce code & improve run time performance of the
7208  generated code.
7209  In the future the compiler (with inter procedural analysis) will be able
7210  to determine the appropriate scheme to use for each function call.
7211  DO NOT use this option for built-in functions such as _mulint..., if this
7212  option is used for a library function the appropriate library function
7213  needs to be recompiled with the same option.
7214  If the project consists of multiple source files then all the source file
7215  should be compiled with the same -
7216 \begin_inset ERT
7217 status Collapsed
7218
7219 \layout Standard
7220
7221 \backslash
7222 /
7223 \end_inset
7224
7225 -callee-saves option string.
7226  Also see #pragma\SpecialChar ~
7227 callee_saves
7228 \begin_inset LatexCommand \index{\#pragma callee\_saves}
7229
7230 \end_inset
7231
7232 .
7233 \layout List
7234 \labelwidthstring 00.00.0000
7235
7236
7237 \series bold
7238 -
7239 \begin_inset ERT
7240 status Collapsed
7241
7242 \layout Standard
7243
7244 \backslash
7245 /
7246 \end_inset
7247
7248 -debug
7249 \begin_inset LatexCommand \index{-\/-debug}
7250
7251 \end_inset
7252
7253
7254 \bar under
7255
7256 \series default
7257 \bar default
7258 When this option is used the compiler will generate debug information.
7259  The debug information collected in a file with .cdb extension can be used
7260  with the SDCDB.
7261  For more information see documentation for SDCDB.
7262  Another file with no extension contains debug information in AOMF or AOMF51
7263 \begin_inset LatexCommand \index{AOMF, AOMF51}
7264
7265 \end_inset
7266
7267  format which is commonly used by third party tools.
7268 \layout List
7269 \labelwidthstring 00.00.0000
7270
7271
7272 \series bold
7273 -S
7274 \begin_inset LatexCommand \index{-S}
7275
7276 \end_inset
7277
7278
7279 \size large
7280 \bar under
7281
7282 \series default
7283 \size default
7284 \bar default
7285 Stop after the stage of compilation proper; do not assemble.
7286  The output is an assembler code file for the input file specified.
7287 \layout List
7288 \labelwidthstring 00.00.0000
7289
7290
7291 \series bold
7292 -
7293 \begin_inset ERT
7294 status Collapsed
7295
7296 \layout Standard
7297
7298 \backslash
7299 /
7300 \end_inset
7301
7302 -int-long-reent
7303 \begin_inset LatexCommand \index{-\/-int-long-reent}
7304
7305 \end_inset
7306
7307
7308 \series default
7309  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
7310  Note by default these libraries are compiled as non-reentrant.
7311  See section Installation for more details.
7312 \layout List
7313 \labelwidthstring 00.00.0000
7314
7315
7316 \series bold
7317 -
7318 \begin_inset ERT
7319 status Collapsed
7320
7321 \layout Standard
7322
7323 \backslash
7324 /
7325 \end_inset
7326
7327 -cyclomatic
7328 \begin_inset LatexCommand \index{-\/-cyclomatic}
7329
7330 \end_inset
7331
7332
7333 \bar under
7334
7335 \series default
7336 \bar default
7337 This option will cause the compiler to generate an information message for
7338  each function in the source file.
7339  The message contains some
7340 \emph on
7341 important
7342 \emph default
7343  information about the function.
7344  The number of edges and nodes the compiler detected in the control flow
7345  graph of the function, and most importantly the
7346 \emph on
7347 cyclomatic complexity
7348 \begin_inset LatexCommand \index{Cyclomatic complexity}
7349
7350 \end_inset
7351
7352
7353 \emph default
7354  see section on Cyclomatic Complexity for more details.
7355 \layout List
7356 \labelwidthstring 00.00.0000
7357
7358
7359 \series bold
7360 -
7361 \begin_inset ERT
7362 status Collapsed
7363
7364 \layout Standard
7365
7366 \backslash
7367 /
7368 \end_inset
7369
7370 -float-reent
7371 \begin_inset LatexCommand \index{-\/-float-reent}
7372
7373 \end_inset
7374
7375
7376 \series default
7377  Floating point library is compiled as reentrant
7378 \begin_inset LatexCommand \index{reentrant}
7379
7380 \end_inset
7381
7382 .
7383  See section Installation for more details.
7384 \layout List
7385 \labelwidthstring 00.00.0000
7386
7387
7388 \series bold
7389 -
7390 \begin_inset ERT
7391 status Collapsed
7392
7393 \layout Standard
7394
7395 \backslash
7396 /
7397 \end_inset
7398
7399 -main-return
7400 \begin_inset LatexCommand \index{-\/-main-return}
7401
7402 \end_inset
7403
7404
7405 \series default
7406  This option can be used if the code generated is called by a monitor program
7407  or if the main routine includes an endless loop.
7408  This option might result in slightly smaller code and save two bytes of
7409  stack space.
7410  The return from the 'main'
7411 \begin_inset LatexCommand \index{main return}
7412
7413 \end_inset
7414
7415  function will return to the function calling main.
7416  The default setting is to lock up i.e.
7417  generate a '
7418 \family typewriter
7419 sjmp .
7420 \family default
7421 '.
7422 \layout List
7423 \labelwidthstring 00.00.0000
7424
7425
7426 \series bold
7427 -
7428 \begin_inset ERT
7429 status Collapsed
7430
7431 \layout Standard
7432
7433 \backslash
7434 /
7435 \end_inset
7436
7437 -nostdinc
7438 \begin_inset LatexCommand \index{-\/-nostdinc}
7439
7440 \end_inset
7441
7442
7443 \series default
7444  This will prevent the compiler from passing on the default include path
7445  to the preprocessor.
7446 \layout List
7447 \labelwidthstring 00.00.0000
7448
7449
7450 \series bold
7451 -
7452 \begin_inset ERT
7453 status Collapsed
7454
7455 \layout Standard
7456
7457 \backslash
7458 /
7459 \end_inset
7460
7461 -nostdlib
7462 \begin_inset LatexCommand \index{-\/-nostdlib}
7463
7464 \end_inset
7465
7466
7467 \series default
7468  This will prevent the compiler from passing on the default library
7469 \begin_inset LatexCommand \index{Libraries}
7470
7471 \end_inset
7472
7473  path to the linker.
7474 \layout List
7475 \labelwidthstring 00.00.0000
7476
7477
7478 \series bold
7479 -
7480 \begin_inset ERT
7481 status Collapsed
7482
7483 \layout Standard
7484
7485 \backslash
7486 /
7487 \end_inset
7488
7489 -verbose
7490 \begin_inset LatexCommand \index{-\/-verbose}
7491
7492 \end_inset
7493
7494
7495 \series default
7496  Shows the various actions the compiler is performing.
7497 \layout List
7498 \labelwidthstring 00.00.0000
7499
7500
7501 \series bold
7502 -V
7503 \begin_inset LatexCommand \index{-V}
7504
7505 \end_inset
7506
7507
7508 \series default
7509  Shows the actual commands the compiler is executing.
7510 \layout List
7511 \labelwidthstring 00.00.0000
7512
7513
7514 \series bold
7515 -
7516 \begin_inset ERT
7517 status Collapsed
7518
7519 \layout Standard
7520
7521 \backslash
7522 /
7523 \end_inset
7524
7525 -no-c-code-in-asm
7526 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
7527
7528 \end_inset
7529
7530
7531 \series default
7532  Hides your ugly and inefficient c-code from the asm file, so you can always
7533  blame the compiler :)
7534 \layout List
7535 \labelwidthstring 00.00.0000
7536
7537
7538 \series bold
7539 -
7540 \begin_inset ERT
7541 status Collapsed
7542
7543 \layout Standard
7544
7545 \backslash
7546 /
7547 \end_inset
7548
7549 -no-peep-comments
7550 \begin_inset LatexCommand \index{-\/-no-peep-comments}
7551
7552 \end_inset
7553
7554
7555 \series default
7556  Will not include peep-hole comments in the generated files.
7557 \layout List
7558 \labelwidthstring 00.00.0000
7559
7560
7561 \series bold
7562 -
7563 \begin_inset ERT
7564 status Collapsed
7565
7566 \layout Standard
7567
7568 \backslash
7569 /
7570 \end_inset
7571
7572 -i-code-in-asm
7573 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
7574
7575 \end_inset
7576
7577
7578 \series default
7579  Include i-codes in the asm file.
7580  Sounds like noise but is most helpful for debugging the compiler itself.
7581 \layout List
7582 \labelwidthstring 00.00.0000
7583
7584
7585 \series bold
7586 -
7587 \begin_inset ERT
7588 status Collapsed
7589
7590 \layout Standard
7591
7592 \backslash
7593 /
7594 \end_inset
7595
7596 -less-pedantic
7597 \begin_inset LatexCommand \index{-\/-less-pedantic}
7598
7599 \end_inset
7600
7601
7602 \series default
7603  Disable some of the more pedantic warnings
7604 \begin_inset LatexCommand \index{Warnings}
7605
7606 \end_inset
7607
7608  (jwk burps: please be more specific here, please!).
7609 \layout List
7610 \labelwidthstring 00.00.0000
7611
7612
7613 \series bold
7614 -
7615 \begin_inset ERT
7616 status Collapsed
7617
7618 \layout Standard
7619
7620 \backslash
7621 /
7622 \end_inset
7623
7624 -disable-warning\SpecialChar ~
7625 <nnnn>
7626 \begin_inset LatexCommand \index{-\/-disable-warning}
7627
7628 \end_inset
7629
7630
7631 \series default
7632  Disable specific warning with number <nnnn>.
7633 \layout List
7634 \labelwidthstring 00.00.0000
7635
7636
7637 \series bold
7638 -
7639 \begin_inset ERT
7640 status Collapsed
7641
7642 \layout Standard
7643
7644 \backslash
7645 /
7646 \end_inset
7647
7648 -print-search-dirs
7649 \begin_inset LatexCommand \index{-\/-print-search-dirs}
7650
7651 \end_inset
7652
7653
7654 \series default
7655  Display the directories in the compiler's search path
7656 \layout List
7657 \labelwidthstring 00.00.0000
7658
7659
7660 \series bold
7661 -
7662 \begin_inset ERT
7663 status Collapsed
7664
7665 \layout Standard
7666
7667 \backslash
7668 /
7669 \end_inset
7670
7671 -vc
7672 \begin_inset LatexCommand \index{-\/-vc}
7673
7674 \end_inset
7675
7676
7677 \series default
7678  Display errors and warnings using MSVC style, so you can use SDCC with
7679  visual studio.
7680 \layout List
7681 \labelwidthstring 00.00.0000
7682
7683
7684 \series bold
7685 -
7686 \begin_inset ERT
7687 status Collapsed
7688
7689 \layout Standard
7690
7691 \backslash
7692 /
7693 \end_inset
7694
7695 -use-stdout
7696 \begin_inset LatexCommand \index{-\/-use-stdout}
7697
7698 \end_inset
7699
7700
7701 \series default
7702  Send errors and warnings to stdout instead of stderr.
7703 \layout List
7704 \labelwidthstring 00.00.0000
7705
7706
7707 \series bold
7708 -Wa\SpecialChar ~
7709 asmOption[,asmOption]
7710 \series default
7711
7712 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
7713
7714 \end_inset
7715
7716 ...
7717  Pass the asmOption to the assembler
7718 \begin_inset LatexCommand \index{Options assembler}
7719
7720 \end_inset
7721
7722
7723 \begin_inset LatexCommand \index{Assembler options}
7724
7725 \end_inset
7726
7727 .
7728  See file sdcc/as/doc/asxhtm.html for assembler options.cd
7729 \layout List
7730 \labelwidthstring 00.00.0000
7731
7732
7733 \series bold
7734 -
7735 \begin_inset ERT
7736 status Collapsed
7737
7738 \layout Standard
7739
7740 \backslash
7741 /
7742 \end_inset
7743
7744 -std-sdcc89
7745 \begin_inset LatexCommand \index{-\/-std-sdcc89}
7746
7747 \end_inset
7748
7749
7750 \series default
7751  Generally follow the C89 standard, but allow SDCC features that conflict
7752  with the standard (default).
7753 \layout List
7754 \labelwidthstring 00.00.0000
7755
7756
7757 \series bold
7758 -
7759 \begin_inset ERT
7760 status Collapsed
7761
7762 \layout Standard
7763
7764 \backslash
7765 /
7766 \end_inset
7767
7768 -std-c89
7769 \begin_inset LatexCommand \index{-\/-std-c89}
7770
7771 \end_inset
7772
7773
7774 \series default
7775  Follow the C89 standard and disable SDCC features that conflict with the
7776  standard.
7777 \layout List
7778 \labelwidthstring 00.00.0000
7779
7780
7781 \series bold
7782 -
7783 \begin_inset ERT
7784 status Collapsed
7785
7786 \layout Standard
7787
7788 \backslash
7789 /
7790 \end_inset
7791
7792 -std-sdcc99
7793 \begin_inset LatexCommand \index{-\/-std-sdcc99}
7794
7795 \end_inset
7796
7797
7798 \series default
7799  Generally follow the C99 standard, but allow SDCC features that conflict
7800  with the standard (incomplete support).
7801 \layout List
7802 \labelwidthstring 00.00.0000
7803
7804
7805 \series bold
7806 -
7807 \begin_inset ERT
7808 status Collapsed
7809
7810 \layout Standard
7811
7812 \backslash
7813 /
7814 \end_inset
7815
7816 -std-c99
7817 \begin_inset LatexCommand \index{-\/-std-sdcc99}
7818
7819 \end_inset
7820
7821
7822 \series default
7823  Follow the C99 standard and disable SDCC features that conflict with the
7824  standard (incomplete support).
7825 \layout List
7826 \labelwidthstring 00.00.0000
7827
7828
7829 \series bold
7830 -
7831 \begin_inset ERT
7832 status Collapsed
7833
7834 \layout Standard
7835
7836 \backslash
7837 /
7838 \end_inset
7839
7840 -codeseg
7841 \series default
7842
7843 \begin_inset LatexCommand \index{-\/-codeseg <Value>}
7844
7845 \end_inset
7846
7847 \SpecialChar ~
7848 <Name> The name to be used for the code
7849 \begin_inset LatexCommand \index{code}
7850
7851 \end_inset
7852
7853  segment, default CSEG.
7854  This is useful if you need to tell the compiler to put the code in a special
7855  segment so you can later on tell the linker to put this segment in a special
7856  place in memory.
7857  Can be used for instance when using bank switching to put the code in a
7858  bank.
7859 \layout List
7860 \labelwidthstring 00.00.0000
7861
7862
7863 \series bold
7864 -
7865 \begin_inset ERT
7866 status Collapsed
7867
7868 \layout Standard
7869
7870 \backslash
7871 /
7872 \end_inset
7873
7874 -constseg
7875 \series default
7876
7877 \begin_inset LatexCommand \index{-\/-constseg <Value>}
7878
7879 \end_inset
7880
7881 \SpecialChar ~
7882 <Name> The name to be used for the const
7883 \begin_inset LatexCommand \index{code}
7884
7885 \end_inset
7886
7887  segment, default CONST.
7888  This is useful if you need to tell the compiler to put the const data in
7889  a special segment so you can later on tell the linker to put this segment
7890  in a special place in memory.
7891  Can be used for instance when using bank switching to put the const data
7892  in a bank.
7893 \layout List
7894 \labelwidthstring 00.00.0000
7895
7896
7897 \series bold
7898 more-pedantic
7899 \series default
7900  Actually this is
7901 \series bold
7902 \emph on
7903 not
7904 \series default
7905 \emph default
7906  a SDCC compiler option but if you want
7907 \emph on
7908 more
7909 \emph default
7910  warnings you can use a separate tool dedicated to syntax checking like
7911  splint
7912 \begin_inset LatexCommand \label{lyx:more-pedantic-SPLINT}
7913
7914 \end_inset
7915
7916
7917 \begin_inset LatexCommand \index{lint (syntax checking tool)}
7918
7919 \end_inset
7920
7921
7922 \begin_inset LatexCommand \url{http://www.splint.org}
7923
7924 \end_inset
7925
7926 .
7927  To make your source files parseable by splint you will have to include
7928
7929 \family sans
7930 lint.h
7931 \family default
7932
7933 \begin_inset LatexCommand \index{splint (syntax checking tool)}
7934
7935 \end_inset
7936
7937  in your source file and add brackets around extended keywords (like
7938 \family sans
7939
7940 \begin_inset Quotes sld
7941 \end_inset
7942
7943 __at\SpecialChar ~
7944
7945 \series bold
7946 (
7947 \series default
7948 0xab
7949 \series bold
7950 )
7951 \series default
7952
7953 \begin_inset Quotes srd
7954 \end_inset
7955
7956
7957 \family default
7958  and
7959 \family sans
7960
7961 \begin_inset Quotes sld
7962 \end_inset
7963
7964 __interrupt\SpecialChar ~
7965 (2)
7966 \begin_inset Quotes srd
7967 \end_inset
7968
7969
7970 \family default
7971 ).
7972
7973 \newline
7974 Splint has an excellent on line manual at
7975 \begin_inset LatexCommand \url{http://www.splint.org/manual/}
7976
7977 \end_inset
7978
7979  and it's capabilities go beyond pure syntax checking.
7980  You'll need to tell splint the location of SDCC's include files so a typical
7981  command line could look like this:
7982 \newline
7983
7984 \family sans
7985 splint\SpecialChar ~
7986 -I\SpecialChar ~
7987 /usr/local/share/sdcc/include/mcs51/\SpecialChar ~
7988 \SpecialChar ~
7989 myprogram.c
7990 \layout Subsection
7991
7992 Intermediate Dump Options
7993 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
7994
7995 \end_inset
7996
7997
7998 \begin_inset LatexCommand \index{Options intermediate dump}
7999
8000 \end_inset
8001
8002
8003 \begin_inset LatexCommand \index{Intermediate dump options}
8004
8005 \end_inset
8006
8007
8008 \layout Standard
8009
8010 The following options are provided for the purpose of retargetting and debugging
8011  the compiler.
8012  They provide a means to dump the intermediate code (iCode
8013 \begin_inset LatexCommand \index{iCode}
8014
8015 \end_inset
8016
8017 ) generated by the compiler in human readable form at various stages of
8018  the compilation process.
8019  More on iCodes see chapter
8020 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
8021
8022 \end_inset
8023
8024
8025 \begin_inset Quotes srd
8026 \end_inset
8027
8028 The anatomy of the compiler
8029 \begin_inset Quotes srd
8030 \end_inset
8031
8032 .
8033 \layout List
8034 \labelwidthstring 00.00.0000
8035
8036
8037 \series bold
8038 -
8039 \begin_inset ERT
8040 status Collapsed
8041
8042 \layout Standard
8043
8044 \backslash
8045 /
8046 \end_inset
8047
8048 -dumpraw
8049 \begin_inset LatexCommand \index{-\/-dumpraw}
8050
8051 \end_inset
8052
8053
8054 \series default
8055  This option will cause the compiler to dump the intermediate code into
8056  a file of named
8057 \emph on
8058 <source filename>.dumpraw
8059 \emph default
8060  just after the intermediate code has been generated for a function, i.e.
8061  before any optimizations are done.
8062  The basic blocks
8063 \begin_inset LatexCommand \index{Basic blocks}
8064
8065 \end_inset
8066
8067  at this stage ordered in the depth first number, so they may not be in
8068  sequence of execution.
8069 \layout List
8070 \labelwidthstring 00.00.0000
8071
8072
8073 \series bold
8074 -
8075 \begin_inset ERT
8076 status Collapsed
8077
8078 \layout Standard
8079
8080 \backslash
8081 /
8082 \end_inset
8083
8084 -dumpgcse
8085 \begin_inset LatexCommand \index{-\/-dumpgcse}
8086
8087 \end_inset
8088
8089
8090 \series default
8091  Will create a dump of iCode's, after global subexpression elimination
8092 \begin_inset LatexCommand \index{Global subexpression elimination}
8093
8094 \end_inset
8095
8096 , into a file named
8097 \emph on
8098 <source filename>.dumpgcse.
8099 \layout List
8100 \labelwidthstring 00.00.0000
8101
8102
8103 \series bold
8104 -
8105 \begin_inset ERT
8106 status Collapsed
8107
8108 \layout Standard
8109
8110 \backslash
8111 /
8112 \end_inset
8113
8114 -dumpdeadcode
8115 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
8116
8117 \end_inset
8118
8119
8120 \series default
8121  Will create a dump of iCode's, after deadcode elimination
8122 \begin_inset LatexCommand \index{Dead-code elimination}
8123
8124 \end_inset
8125
8126 , into a file named
8127 \emph on
8128 <source filename>.dumpdeadcode.
8129 \layout List
8130 \labelwidthstring 00.00.0000
8131
8132
8133 \series bold
8134 -
8135 \begin_inset ERT
8136 status Collapsed
8137
8138 \layout Standard
8139
8140 \backslash
8141 /
8142 \end_inset
8143
8144 -dumploop
8145 \begin_inset LatexCommand \index{-\/-dumploop}
8146
8147 \end_inset
8148
8149
8150 \series default
8151 \size large
8152
8153 \size default
8154 Will create a dump of iCode's, after loop optimizations
8155 \begin_inset LatexCommand \index{Loop optimization}
8156
8157 \end_inset
8158
8159 , into a file named
8160 \emph on
8161 <source filename>.dumploop.
8162 \layout List
8163 \labelwidthstring 00.00.0000
8164
8165
8166 \series bold
8167 -
8168 \begin_inset ERT
8169 status Collapsed
8170
8171 \layout Standard
8172
8173 \backslash
8174 /
8175 \end_inset
8176
8177 -dumprange
8178 \begin_inset LatexCommand \index{-\/-dumprange}
8179
8180 \end_inset
8181
8182
8183 \series default
8184 \size large
8185
8186 \size default
8187 Will create a dump of iCode's, after live range analysis
8188 \begin_inset LatexCommand \index{Live range analysis}
8189
8190 \end_inset
8191
8192 , into a file named
8193 \emph on
8194 <source filename>.dumprange.
8195 \layout List
8196 \labelwidthstring 00.00.0000
8197
8198
8199 \series bold
8200 -
8201 \begin_inset ERT
8202 status Collapsed
8203
8204 \layout Standard
8205
8206 \backslash
8207 /
8208 \end_inset
8209
8210 -dumlrange
8211 \begin_inset LatexCommand \index{-\/-dumlrange}
8212
8213 \end_inset
8214
8215
8216 \series default
8217  Will dump the life ranges
8218 \begin_inset LatexCommand \index{Live range analysis}
8219
8220 \end_inset
8221
8222  for all symbols.
8223 \layout List
8224 \labelwidthstring 00.00.0000
8225
8226
8227 \series bold
8228 -
8229 \begin_inset ERT
8230 status Collapsed
8231
8232 \layout Standard
8233
8234 \backslash
8235 /
8236 \end_inset
8237
8238 -dumpregassign
8239 \begin_inset LatexCommand \index{-\/-dumpregassign}
8240
8241 \end_inset
8242
8243
8244 \bar under
8245
8246 \series default
8247 \bar default
8248 Will create a dump of iCode's, after register assignment
8249 \begin_inset LatexCommand \index{Register assignment}
8250
8251 \end_inset
8252
8253 , into a file named
8254 \emph on
8255 <source filename>.dumprassgn.
8256 \layout List
8257 \labelwidthstring 00.00.0000
8258
8259
8260 \series bold
8261 -
8262 \begin_inset ERT
8263 status Collapsed
8264
8265 \layout Standard
8266
8267 \backslash
8268 /
8269 \end_inset
8270
8271 -dumplrange
8272 \begin_inset LatexCommand \index{-\/-dumplrange}
8273
8274 \end_inset
8275
8276
8277 \series default
8278  Will create a dump of the live ranges of iTemp's
8279 \layout List
8280 \labelwidthstring 00.00.0000
8281
8282
8283 \series bold
8284 -
8285 \begin_inset ERT
8286 status Collapsed
8287
8288 \layout Standard
8289
8290 \backslash
8291 /
8292 \end_inset
8293
8294 -dumpall
8295 \begin_inset LatexCommand \index{-\/-dumpall}
8296
8297 \end_inset
8298
8299
8300 \size large
8301 \bar under
8302
8303 \series default
8304 \size default
8305 \bar default
8306 Will cause all the above mentioned dumps to be created.
8307 \layout Subsection
8308
8309 Redirecting output on Windows Shells
8310 \layout Standard
8311
8312 By default SDCC writes it's error messages to
8313 \begin_inset Quotes sld
8314 \end_inset
8315
8316 standard error
8317 \begin_inset Quotes srd
8318 \end_inset
8319
8320 .
8321  To force all messages to
8322 \begin_inset Quotes sld
8323 \end_inset
8324
8325 standard output
8326 \begin_inset Quotes srd
8327 \end_inset
8328
8329  use
8330 \series bold
8331 -
8332 \series default
8333 \emph on
8334
8335 \begin_inset ERT
8336 status Collapsed
8337
8338 \layout Standard
8339
8340 \backslash
8341 /
8342 \end_inset
8343
8344
8345 \series bold
8346 \emph default
8347 -
8348 \series default
8349 use-stdout
8350 \begin_inset LatexCommand \index{-\/-use-stdout}
8351
8352 \end_inset
8353
8354 .
8355  Additionally, if you happen to have visual studio installed in your windows
8356  machine, you can use it to compile your sources using a custom build and
8357  the SDCC -
8358 \emph on
8359
8360 \begin_inset ERT
8361 status Collapsed
8362
8363 \layout Standard
8364
8365 \backslash
8366 /
8367 \end_inset
8368
8369
8370 \emph default
8371 -vc
8372 \begin_inset LatexCommand \index{-\/-vc}
8373
8374 \end_inset
8375
8376  option.
8377  Something like this should work:
8378 \newline
8379
8380 \newline
8381
8382 \series bold
8383 c:
8384 \backslash
8385 sdcc
8386 \backslash
8387 bin
8388 \backslash
8389 sdcc.exe -
8390 \series default
8391 \emph on
8392
8393 \begin_inset ERT
8394 status Collapsed
8395
8396 \layout Standard
8397
8398 \backslash
8399 /
8400 \end_inset
8401
8402
8403 \series bold
8404 \emph default
8405 -vc -
8406 \series default
8407 \emph on
8408
8409 \begin_inset ERT
8410 status Collapsed
8411
8412 \layout Standard
8413
8414 \backslash
8415 /
8416 \end_inset
8417
8418
8419 \series bold
8420 \emph default
8421 -model-large -c $(InputPath)
8422 \layout Section
8423
8424 Environment variables
8425 \begin_inset LatexCommand \index{Environment variables}
8426
8427 \end_inset
8428
8429
8430 \layout Standard
8431
8432 SDCC recognizes the following environment variables:
8433 \layout List
8434 \labelwidthstring 00.00.0000
8435
8436
8437 \series bold
8438 SDCC_LEAVE_SIGNALS
8439 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
8440
8441 \end_inset
8442
8443
8444 \series default
8445  SDCC installs a signal handler
8446 \begin_inset LatexCommand \index{signal handler}
8447
8448 \end_inset
8449
8450  to be able to delete temporary files after an user break (^C) or an exception.
8451  If this environment variable is set, SDCC won't install the signal handler
8452  in order to be able to debug SDCC.
8453 \layout List
8454 \labelwidthstring 00.00.0000
8455
8456
8457 \series bold
8458 TMP,\SpecialChar ~
8459 TEMP,\SpecialChar ~
8460 TMPDIR
8461 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
8462
8463 \end_inset
8464
8465
8466 \series default
8467  Path, where temporary files will be created.
8468  The order of the variables is the search order.
8469  In a standard *nix environment these variables are not set, and there's
8470  no need to set them.
8471  On Windows it's recommended to set one of them.
8472 \layout List
8473 \labelwidthstring 00.00.0000
8474
8475
8476 \series bold
8477 SDCC_HOME
8478 \begin_inset LatexCommand \index{SDCC\_HOME}
8479
8480 \end_inset
8481
8482
8483 \series default
8484  Path, see section
8485 \begin_inset LatexCommand \ref{sub:Install-paths}
8486
8487 \end_inset
8488
8489 \SpecialChar ~
8490
8491 \begin_inset Quotes sld
8492 \end_inset
8493
8494  Install Paths
8495 \begin_inset Quotes srd
8496 \end_inset
8497
8498 .
8499 \layout List
8500 \labelwidthstring 00.00.0000
8501
8502
8503 \series bold
8504 SDCC_INCLUDE
8505 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
8506
8507 \end_inset
8508
8509
8510 \series default
8511  Path, see section
8512 \begin_inset LatexCommand \ref{sub:Search-Paths}
8513
8514 \end_inset
8515
8516 \SpecialChar ~
8517
8518 \begin_inset Quotes sld
8519 \end_inset
8520
8521 Search Paths
8522 \begin_inset Quotes srd
8523 \end_inset
8524
8525 .
8526 \layout List
8527 \labelwidthstring 00.00.0000
8528
8529
8530 \series bold
8531 SDCC_LIB
8532 \begin_inset LatexCommand \index{SDCC\_LIB}
8533
8534 \end_inset
8535
8536
8537 \series default
8538  Path, see section
8539 \begin_inset LatexCommand \ref{sub:Search-Paths}
8540
8541 \end_inset
8542
8543 \SpecialChar ~
8544
8545 \begin_inset Quotes sld
8546 \end_inset
8547
8548 Search Paths
8549 \begin_inset Quotes srd
8550 \end_inset
8551
8552 ..
8553 \layout Standard
8554
8555 There are some more environment variables recognized by SDCC, but these
8556  are solely used for debugging purposes.
8557  They can change or disappear very quickly, and will never be documented.
8558 \layout Section
8559
8560 Storage Class Language Extensions
8561 \layout Subsection
8562
8563 MCS51/DS390 Storage Class
8564 \begin_inset LatexCommand \index{Storage class}
8565
8566 \end_inset
8567
8568  Language Extensions
8569 \layout Standard
8570
8571 In addition to the ANSI storage classes SDCC allows the following MCS51
8572  specific storage classes:
8573 \layout Subsubsection
8574
8575 data
8576 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
8577
8578 \end_inset
8579
8580
8581 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
8582
8583 \end_inset
8584
8585  / near
8586 \begin_inset LatexCommand \index{near (storage class)}
8587
8588 \end_inset
8589
8590
8591 \begin_inset LatexCommand \index{\_\_near (storage class)}
8592
8593 \end_inset
8594
8595
8596 \layout Standard
8597
8598 This is the
8599 \series bold
8600 default
8601 \series default
8602  storage class for the Small Memory model (
8603 \emph on
8604 data
8605 \emph default
8606  and
8607 \emph on
8608 near
8609 \emph default
8610  can be used synonymously).
8611  Variables declared with this storage class will be allocated in the directly
8612  addressable portion of the internal RAM of a 8051, e.g.:
8613 \layout Verse
8614
8615
8616 \family typewriter
8617 data unsigned char test_data;
8618 \layout Standard
8619
8620 Writing 0x01 to this variable generates the assembly code:
8621 \layout Verse
8622
8623
8624 \family typewriter
8625 75*00 01\SpecialChar ~
8626 \SpecialChar ~
8627 \SpecialChar ~
8628 mov\SpecialChar ~
8629 \SpecialChar ~
8630 _test_data,#0x01
8631 \layout Subsubsection
8632
8633 xdata
8634 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8635
8636 \end_inset
8637
8638
8639 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
8640
8641 \end_inset
8642
8643  / far
8644 \begin_inset LatexCommand \index{far (storage class)}
8645
8646 \end_inset
8647
8648
8649 \begin_inset LatexCommand \index{\_\_far (storage class)}
8650
8651 \end_inset
8652
8653
8654 \layout Standard
8655
8656 Variables declared with this storage class will be placed in the external
8657  RAM.
8658  This is the
8659 \series bold
8660 default
8661 \series default
8662  storage class for the Large Memory model, e.g.:
8663 \layout Verse
8664
8665
8666 \family typewriter
8667 xdata unsigned char test_xdata;
8668 \layout Standard
8669
8670 Writing 0x01 to this variable generates the assembly code:
8671 \layout Verse
8672
8673
8674 \family typewriter
8675 90s00r00\SpecialChar ~
8676 \SpecialChar ~
8677 \SpecialChar ~
8678 mov\SpecialChar ~
8679 \SpecialChar ~
8680 dptr,#_test_xdata
8681 \newline
8682 74\SpecialChar ~
8683 01\SpecialChar ~
8684 \SpecialChar ~
8685 \SpecialChar ~
8686 \SpecialChar ~
8687 \SpecialChar ~
8688 \SpecialChar ~
8689 mov\SpecialChar ~
8690 \SpecialChar ~
8691 a,#0x01
8692 \newline
8693 F0\SpecialChar ~
8694 \SpecialChar ~
8695 \SpecialChar ~
8696 \SpecialChar ~
8697 \SpecialChar ~
8698 \SpecialChar ~
8699 \SpecialChar ~
8700 \SpecialChar ~
8701 \SpecialChar ~
8702 movx\SpecialChar ~
8703 @dptr,a
8704 \layout Subsubsection
8705
8706 idata
8707 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
8708
8709 \end_inset
8710
8711
8712 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
8713
8714 \end_inset
8715
8716
8717 \layout Standard
8718
8719 Variables declared with this storage class will be allocated into the indirectly
8720  addressable portion of the internal ram of a 8051, e.g.:
8721 \layout Verse
8722
8723
8724 \family typewriter
8725 idata unsigned char test_idata;
8726 \layout Standard
8727
8728 Writing 0x01 to this variable generates the assembly code:
8729 \layout Verse
8730
8731
8732 \family typewriter
8733 78r00\SpecialChar ~
8734 \SpecialChar ~
8735 \SpecialChar ~
8736 \SpecialChar ~
8737 \SpecialChar ~
8738 \SpecialChar ~
8739 \SpecialChar ~
8740 mov\SpecialChar ~
8741 \SpecialChar ~
8742 r0,#_test_idata
8743 \newline
8744 76\SpecialChar ~
8745 01\SpecialChar ~
8746 \SpecialChar ~
8747 \SpecialChar ~
8748 \SpecialChar ~
8749 \SpecialChar ~
8750 \SpecialChar ~
8751 \SpecialChar ~
8752 mov\SpecialChar ~
8753 \SpecialChar ~
8754 @r0,#0x01
8755 \layout Standard
8756
8757 Please note, the first 128 byte of idata physically access the same RAM
8758  as the data memory.
8759  The original 8051 had 128 byte idata memory, nowadays most devices have
8760  256 byte idata memory.
8761  The stack
8762 \begin_inset LatexCommand \index{stack}
8763
8764 \end_inset
8765
8766  is located in idata memory.
8767 \layout Subsubsection
8768
8769 pdata
8770 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
8771
8772 \end_inset
8773
8774
8775 \begin_inset LatexCommand \index{\_\_pdata (mcs51, ds390 storage class)}
8776
8777 \end_inset
8778
8779
8780 \layout Standard
8781
8782 Paged xdata access is just as straightforward as using the other addressing
8783  modes of a 8051.
8784  It is typically located at the start of xdata and has a maximum size of
8785  256 bytes.
8786  The following example writes 0x01 to the pdata variable.
8787  Please note, pdata access physically accesses xdata memory.
8788  The high byte of the address is determined by port P2
8789 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
8790
8791 \end_inset
8792
8793 (or in case of some 8051 variants by a separate Special Function Register,
8794  see section
8795 \begin_inset LatexCommand \ref{sub:MCS51-variants}
8796
8797 \end_inset
8798
8799 ).
8800  This is the
8801 \series bold
8802 default
8803 \series default
8804  storage class for the Medium Memory model, e.g.:
8805 \layout Verse
8806
8807
8808 \family typewriter
8809 pdata unsigned char test_pdata;
8810 \layout Standard
8811
8812 Writing 0x01 to this variable generates the assembly code:
8813 \layout Verse
8814
8815
8816 \family typewriter
8817 78r00\SpecialChar ~
8818 \SpecialChar ~
8819 \SpecialChar ~
8820 \SpecialChar ~
8821 \SpecialChar ~
8822 \SpecialChar ~
8823 mov r0,#_test_pdata
8824 \newline
8825 74 01\SpecialChar ~
8826 \SpecialChar ~
8827 \SpecialChar ~
8828 \SpecialChar ~
8829 \SpecialChar ~
8830 \SpecialChar ~
8831 mov a,#0x01
8832 \newline
8833 F2\SpecialChar ~
8834 \SpecialChar ~
8835 \SpecialChar ~
8836 \SpecialChar ~
8837 \SpecialChar ~
8838 \SpecialChar ~
8839 \SpecialChar ~
8840 \SpecialChar ~
8841 \SpecialChar ~
8842 movx @r0,a
8843 \layout Standard
8844
8845 If the -
8846 \begin_inset ERT
8847 status Collapsed
8848
8849 \layout Standard
8850
8851 \backslash
8852 /
8853 \end_inset
8854
8855 -xstack
8856 \begin_inset LatexCommand \index{-\/-xstack}
8857
8858 \end_inset
8859
8860  option is used the pdata memory area is followed by the xstack memory area
8861  and the sum of their sizes is limited to 256 bytes.
8862 \layout Subsubsection
8863
8864 code
8865 \begin_inset LatexCommand \index{code}
8866
8867 \end_inset
8868
8869
8870 \begin_inset LatexCommand \index{\_\_code}
8871
8872 \end_inset
8873
8874
8875 \layout Standard
8876
8877 'Variables' declared with this storage class will be placed in the code
8878  memory:
8879 \layout Verse
8880
8881
8882 \family typewriter
8883 code unsigned char test_code;
8884 \layout Standard
8885
8886 Read access to this variable generates the assembly code:
8887 \layout Verse
8888
8889
8890 \family typewriter
8891 90s00r6F\SpecialChar ~
8892 \SpecialChar ~
8893 \SpecialChar ~
8894 mov dptr,#_test_code
8895 \newline
8896 E4\SpecialChar ~
8897 \SpecialChar ~
8898 \SpecialChar ~
8899 \SpecialChar ~
8900 \SpecialChar ~
8901 \SpecialChar ~
8902 \SpecialChar ~
8903 \SpecialChar ~
8904 \SpecialChar ~
8905 clr a
8906 \newline
8907 93\SpecialChar ~
8908 \SpecialChar ~
8909 \SpecialChar ~
8910 \SpecialChar ~
8911 \SpecialChar ~
8912 \SpecialChar ~
8913 \SpecialChar ~
8914 \SpecialChar ~
8915 \SpecialChar ~
8916 movc a,@a+dptr
8917 \layout Standard
8918
8919
8920 \family typewriter
8921 char
8922 \family default
8923  indexed arrays of characters in code memory can be accessed efficiently:
8924 \layout Verse
8925
8926
8927 \family typewriter
8928 code char test_array[] = {'c','h','e','a','p'};
8929 \layout Standard
8930
8931 Read access to this array using an 8-bit unsigned index generates the assembly
8932  code:
8933 \layout Verse
8934
8935
8936 \family typewriter
8937 E5*00\SpecialChar ~
8938 \SpecialChar ~
8939 \SpecialChar ~
8940 \SpecialChar ~
8941 \SpecialChar ~
8942 \SpecialChar ~
8943 mov a,_index
8944 \layout Verse
8945
8946
8947 \family typewriter
8948 90s00r41\SpecialChar ~
8949 \SpecialChar ~
8950 \SpecialChar ~
8951 mov dptr,#_test_array
8952 \layout Verse
8953
8954
8955 \family typewriter
8956 93\SpecialChar ~
8957 \SpecialChar ~
8958 \SpecialChar ~
8959 \SpecialChar ~
8960 \SpecialChar ~
8961 \SpecialChar ~
8962 \SpecialChar ~
8963 \SpecialChar ~
8964 \SpecialChar ~
8965 movc a,@a+dptr
8966 \layout Subsubsection
8967
8968 bit
8969 \begin_inset LatexCommand \index{bit}
8970
8971 \end_inset
8972
8973
8974 \begin_inset LatexCommand \index{\_\_bit}
8975
8976 \end_inset
8977
8978
8979 \layout Standard
8980
8981 This is a data-type and a storage class specifier.
8982  When a variable is declared as a bit, it is allocated into the bit addressable
8983  memory of 8051, e.g.:
8984 \layout Verse
8985
8986
8987 \family typewriter
8988 bit test_bit;
8989 \layout Standard
8990
8991 Writing 1 to this variable generates the assembly code:
8992 \layout Verse
8993
8994
8995 \family typewriter
8996 D2*00\SpecialChar ~
8997 \SpecialChar ~
8998 \SpecialChar ~
8999 \SpecialChar ~
9000 \SpecialChar ~
9001 \SpecialChar ~
9002 \SpecialChar ~
9003 setb\SpecialChar ~
9004 _test_bit
9005 \layout Standard
9006
9007 The bit addressable memory consists of 128 bits which are located from 0x20
9008  to 0x2f in data memory.
9009
9010 \newline
9011 Apart from this 8051 specific storage class most architectures support ANSI-C
9012  bitfields
9013 \begin_inset LatexCommand \index{bitfields}
9014
9015 \end_inset
9016
9017
9018 \begin_inset Foot
9019 collapsed false
9020
9021 \layout Standard
9022
9023 Not really meant as examples, but nevertheless showing what bitfields are
9024  about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
9025 \end_inset
9026
9027 .
9028  In accordance with ISO/IEC 9899 bits and bitfields without an explicit
9029  signed modifier are implemented as unsigned.
9030 \layout Subsubsection
9031
9032 sfr
9033 \begin_inset LatexCommand \index{sfr}
9034
9035 \end_inset
9036
9037
9038 \begin_inset LatexCommand \index{\_\_sfr}
9039
9040 \end_inset
9041
9042  / sfr16
9043 \begin_inset LatexCommand \index{sfr16}
9044
9045 \end_inset
9046
9047
9048 \begin_inset LatexCommand \index{\_\_sfr16}
9049
9050 \end_inset
9051
9052  / sfr32
9053 \begin_inset LatexCommand \index{sfr32}
9054
9055 \end_inset
9056
9057
9058 \begin_inset LatexCommand \index{\_\_sfr32}
9059
9060 \end_inset
9061
9062  / sbit
9063 \begin_inset LatexCommand \index{\_\_sbit}
9064
9065 \end_inset
9066
9067
9068 \layout Standard
9069
9070 Like the bit keyword,
9071 \emph on
9072 sfr / sfr16 / sfr32 / sbit
9073 \emph default
9074 signify both a data-type and storage class, they are used to describe the
9075
9076 \emph on
9077 s
9078 \emph default
9079 pecial
9080 \emph on
9081 f
9082 \emph default
9083 unction
9084 \emph on
9085 r
9086 \emph default
9087 egisters and
9088 \emph on
9089 s
9090 \emph default
9091 pecial
9092 \emph on
9093 bit
9094 \emph default
9095  variables of a 8051, eg:
9096 \layout Verse
9097
9098
9099 \family typewriter
9100 sfr at
9101 \begin_inset LatexCommand \index{at}
9102
9103 \end_inset
9104
9105
9106 \begin_inset LatexCommand \index{\_\_at}
9107
9108 \end_inset
9109
9110  0x80 P0;\SpecialChar ~
9111  /* special function register P0 at location 0x80 */
9112 \newline
9113 /* 16 bit special function register combination for timer 0 */
9114 \newline
9115 /* with the high byte at location 0x8C and the low byte at location 0x8A
9116  */
9117 \newline
9118 sfr16 at
9119 \begin_inset LatexCommand \index{at}
9120
9121 \end_inset
9122
9123
9124 \begin_inset LatexCommand \index{\_\_at}
9125
9126 \end_inset
9127
9128  0x8C8A TMR0;
9129 \newline
9130 sbit at 0xd7 CY; /* CY (Carry Flag
9131 \begin_inset LatexCommand \index{Flags}
9132
9133 \end_inset
9134
9135
9136 \begin_inset LatexCommand \index{Carry flag}
9137
9138 \end_inset
9139
9140 ) */
9141 \layout Standard
9142
9143 Special function registers which are located on an address dividable by
9144  8 are bit-addressable, an
9145 \emph on
9146  sbit
9147 \emph default
9148  addresses a specific bit within these sfr.
9149 \newline
9150 16 Bit and 32 bit special function register combinations which require a
9151  certain access order are better not declared using
9152 \emph on
9153 sfr16
9154 \emph default
9155  or
9156 \emph on
9157 sfr32.
9158
9159 \emph default
9160  Allthough SDCC usually accesses them Least Significant Byte (LSB) first,
9161  this is not guaranteed.
9162 \layout Subsubsection
9163
9164 Pointers
9165 \begin_inset LatexCommand \index{Pointer}
9166
9167 \end_inset
9168
9169  to MCS51/DS390 specific memory spaces
9170 \layout Standard
9171
9172 SDCC allows (via language extensions) pointers to explicitly point to any
9173  of the memory spaces
9174 \begin_inset LatexCommand \index{Memory model}
9175
9176 \end_inset
9177
9178  of the 8051.
9179  In addition to the explicit pointers, the compiler uses (by default) generic
9180  pointers which can be used to point to any of the memory spaces.
9181 \newline
9182
9183 \newline
9184 Pointer declaration examples:
9185 \layout Verse
9186
9187
9188 \family typewriter
9189 /* pointer physically in internal ram pointing to object in external ram
9190  */
9191 \newline
9192 xdata unsigned char * data p;
9193 \newline
9194
9195 \newline
9196 /* pointer physically in external ram pointing to object in internal ram
9197  */
9198 \newline
9199 data unsigned char * xdata p;
9200 \newline
9201
9202 \newline
9203 /* pointer physically in code rom pointing to data in xdata space */
9204 \newline
9205 xdata unsigned char * code p;
9206 \newline
9207
9208 \newline
9209 /* pointer physically in code space pointing to data in code space */
9210 \newline
9211 code unsigned char * code p;
9212 \newline
9213
9214 \newline
9215 /* the following is a generic pointer physically located in xdata space
9216  */
9217 \newline
9218 char * xdata p;
9219 \newline
9220
9221 \newline
9222 /* the following is a function pointer physically located in data space
9223  */
9224 \newline
9225 char (* data fp)(void);
9226 \layout Standard
9227
9228 Well you get the idea.
9229
9230 \newline
9231
9232 \newline
9233 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
9234 \emph on
9235 generic
9236 \emph default
9237  pointers.
9238
9239 \size small
9240
9241 \newline
9242
9243 \newline
9244
9245 \size default
9246 The highest order byte of the
9247 \emph on
9248 generic
9249 \emph default
9250  pointers contains the data space information.
9251  Assembler support routines are called whenever data is stored or retrieved
9252  using
9253 \emph on
9254 generic
9255 \emph default
9256  pointers.
9257  These are useful for developing reusable library
9258 \begin_inset LatexCommand \index{Libraries}
9259
9260 \end_inset
9261
9262  routines.
9263  Explicitly specifying the pointer type will generate the most efficient
9264  code.
9265 \layout Subsubsection
9266
9267 Notes on MCS51 memory
9268 \begin_inset LatexCommand \index{MCS51 memory}
9269
9270 \end_inset
9271
9272  layout
9273 \layout Standard
9274
9275 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
9276  RAM memory which is structured as follows:
9277 \newline
9278
9279 \newline
9280 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
9281
9282 \newline
9283 - Bytes 20-2F - 16 bytes to hold 128 bit
9284 \begin_inset LatexCommand \index{bit}
9285
9286 \end_inset
9287
9288  variables and,
9289 \newline
9290 - Bytes 30-7F - 80 bytes for general purpose use.
9291 \newline
9292
9293 \layout Standard
9294
9295 Additionally some members of the MCS51 family may have up to 128 bytes of
9296  additional, indirectly addressable, internal RAM memory (
9297 \emph on
9298 idata
9299 \emph default
9300
9301 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
9302
9303 \end_inset
9304
9305
9306 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
9307
9308 \end_inset
9309
9310 ).
9311  Furthermore, some chips may have some built in external memory (
9312 \emph on
9313 xdata
9314 \emph default
9315
9316 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9317
9318 \end_inset
9319
9320
9321 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9322
9323 \end_inset
9324
9325 ) which should not be confused with the internal, directly addressable RAM
9326  memory (
9327 \emph on
9328 data
9329 \emph default
9330
9331 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
9332
9333 \end_inset
9334
9335
9336 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
9337
9338 \end_inset
9339
9340 ).
9341  Sometimes this built in
9342 \emph on
9343 xdata
9344 \emph default
9345  memory has to be activated before using it (you can probably find this
9346  information on the datasheet of the microcontroller your are using, see
9347  also section
9348 \begin_inset LatexCommand \ref{sub:Startup-Code}
9349
9350 \end_inset
9351
9352 \SpecialChar ~
9353 Startup-Code).
9354 \layout Standard
9355
9356 Normally SDCC will only use the first bank
9357 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
9358
9359 \end_inset
9360
9361  of registers (register bank 0), but it is possible to specify that other
9362  banks of registers (keyword
9363 \emph on
9364 using
9365 \emph default
9366
9367 \emph on
9368
9369 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
9370
9371 \end_inset
9372
9373
9374 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
9375
9376 \end_inset
9377
9378
9379 \emph default
9380 ) should be used in interrupt
9381 \begin_inset LatexCommand \index{interrupt}
9382
9383 \end_inset
9384
9385
9386 \begin_inset LatexCommand \index{\_\_interrupt}
9387
9388 \end_inset
9389
9390  routines.
9391  By default, the compiler will place the stack after the last byte of allocated
9392  memory for variables.
9393  For example, if the first 2 banks of registers are used, and only four
9394  bytes are used for
9395 \emph on
9396 data
9397 \emph default
9398  variables, it will position the base of the internal stack at address 20
9399  (0x14).
9400  This implies that as the stack
9401 \begin_inset LatexCommand \index{stack}
9402
9403 \end_inset
9404
9405  grows, it will use up the remaining register banks, and the 16 bytes used
9406  by the 128 bit variables, and 80 bytes for general purpose use.
9407  If any bit variables are used, the data variables will be placed in unused
9408  register banks and after the byte holding the last bit variable.
9409  For example, if register banks 0 and 1 are used, and there are 9 bit variables
9410  (two bytes used),
9411 \emph on
9412 data
9413 \emph default
9414  variables will be placed starting from address 0x10 to 0x20 and continue
9415  at address 0x22.
9416  You can also use -
9417 \begin_inset ERT
9418 status Collapsed
9419
9420 \layout Standard
9421
9422 \backslash
9423 /
9424 \end_inset
9425
9426 -data-loc
9427 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
9428
9429 \end_inset
9430
9431  to specify the start address of the
9432 \emph on
9433 data
9434 \emph default
9435  and -
9436 \begin_inset ERT
9437 status Collapsed
9438
9439 \layout Standard
9440
9441 \backslash
9442 /
9443 \end_inset
9444
9445 -iram-size
9446 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
9447
9448 \end_inset
9449
9450  to specify the size of the total internal RAM (
9451 \emph on
9452 data
9453 \emph default
9454 +
9455 \emph on
9456 idata
9457 \emph default
9458 ).
9459
9460 \layout Standard
9461
9462 By default the 8051 linker will place the stack after the last byte of (i)data
9463  variables.
9464  Option -
9465 \begin_inset ERT
9466 status Collapsed
9467
9468 \layout Standard
9469
9470 \backslash
9471 /
9472 \end_inset
9473
9474 -stack-loc
9475 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
9476
9477 \end_inset
9478
9479  allows you to specify the start of the stack, i.e.
9480  you could start it after any data in the general purpose area.
9481  If your microcontroller has additional indirectly addressable internal
9482  RAM (
9483 \emph on
9484 idata
9485 \emph default
9486 ) you can place the stack on it.
9487  You may also need to use -
9488 \begin_inset ERT
9489 status Collapsed
9490
9491 \layout Standard
9492
9493 \backslash
9494 /
9495 \end_inset
9496
9497 -xdata-loc
9498 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
9499
9500 \end_inset
9501
9502  to set the start address of the external RAM (
9503 \emph on
9504 xdata
9505 \emph default
9506 ) and -
9507 \begin_inset ERT
9508 status Collapsed
9509
9510 \layout Standard
9511
9512 \backslash
9513 /
9514 \end_inset
9515
9516 -xram-size
9517 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
9518
9519 \end_inset
9520
9521  to specify its size.
9522  Same goes for the code memory, using -
9523 \begin_inset ERT
9524 status Collapsed
9525
9526 \layout Standard
9527
9528 \backslash
9529 /
9530 \end_inset
9531
9532 -code-loc
9533 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
9534
9535 \end_inset
9536
9537  and -
9538 \begin_inset ERT
9539 status Collapsed
9540
9541 \layout Standard
9542
9543 \backslash
9544 /
9545 \end_inset
9546
9547 -code-size
9548 \begin_inset LatexCommand \index{-\/-code-size <Value>}
9549
9550 \end_inset
9551
9552 .
9553  If in doubt, don't specify any options and see if the resulting memory
9554  layout is appropriate, then you can adjust it.
9555 \layout Standard
9556
9557 The linker generates two files with memory allocation information.
9558  The first, with extension .map
9559 \begin_inset LatexCommand \index{<file>.map}
9560
9561 \end_inset
9562
9563  shows all the variables and segments.
9564  The second with extension .mem
9565 \begin_inset LatexCommand \index{<file>.mem}
9566
9567 \end_inset
9568
9569  shows the final memory layout.
9570  The linker will complain either if memory segments overlap, there is not
9571  enough memory, or there is not enough space for stack.
9572  If you get any linking warnings and/or errors related to stack or segments
9573  allocation, take a look at either the .map or .mem files to find out what
9574  the problem is.
9575  The .mem file may even suggest a solution to the problem.
9576 \layout Subsection
9577
9578 Z80/Z180 Storage Class
9579 \begin_inset LatexCommand \index{Storage class}
9580
9581 \end_inset
9582
9583  Language Extensions
9584 \layout Subsubsection
9585
9586 sfr
9587 \begin_inset LatexCommand \index{sfr}
9588
9589 \end_inset
9590
9591
9592 \begin_inset LatexCommand \index{\_\_sfr}
9593
9594 \end_inset
9595
9596  (in/out to 8-bit addresses)
9597 \layout Standard
9598
9599 The Z80
9600 \begin_inset LatexCommand \index{Z80}
9601
9602 \end_inset
9603
9604  family has separate address spaces for memory and
9605 \emph on
9606 i
9607 \emph default
9608 nput/
9609 \emph on
9610 o
9611 \emph default
9612 utput memory.
9613  I/O memory
9614 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
9615
9616 \end_inset
9617
9618  is accessed with special instructions, e.g.:
9619 \layout Verse
9620
9621
9622 \family typewriter
9623 sfr at 0x78 IoPort;\SpecialChar ~
9624 \SpecialChar ~
9625 /* define a var in I/O space at 78h called IoPort */
9626
9627 \layout Standard
9628
9629 Writing 0x01 to this variable generates the assembly code:
9630 \layout Verse
9631
9632
9633 \family typewriter
9634 3E 01\SpecialChar ~
9635 \SpecialChar ~
9636 \SpecialChar ~
9637 \SpecialChar ~
9638 \SpecialChar ~
9639 \SpecialChar ~
9640 ld a,#0x01
9641 \newline
9642 D3 78\SpecialChar ~
9643 \SpecialChar ~
9644 \SpecialChar ~
9645 \SpecialChar ~
9646 \SpecialChar ~
9647 \SpecialChar ~
9648 out (_IoPort),a
9649 \layout Subsubsection
9650
9651 banked sfr
9652 \begin_inset LatexCommand \index{sfr}
9653
9654 \end_inset
9655
9656
9657 \begin_inset LatexCommand \index{\_\_sfr}
9658
9659 \end_inset
9660
9661  (in/out to 16-bit addresses)
9662 \layout Standard
9663
9664 The keyword
9665 \emph on
9666 banked
9667 \emph default
9668  is used to support 16 bit addresses in I/O memory e.g.:
9669 \layout Verse
9670
9671
9672 \family typewriter
9673 sfr banked at
9674 \begin_inset LatexCommand \index{at}
9675
9676 \end_inset
9677
9678
9679 \begin_inset LatexCommand \index{\_\_at}
9680
9681 \end_inset
9682
9683  0x123 IoPort;
9684 \layout Standard
9685
9686 Writing 0x01 to this variable generates the assembly code:
9687 \layout Verse
9688
9689
9690 \family typewriter
9691 01 23 01\SpecialChar ~
9692 \SpecialChar ~
9693 \SpecialChar ~
9694 ld bc,#_IoPort
9695 \newline
9696 3E 01\SpecialChar ~
9697 \SpecialChar ~
9698 \SpecialChar ~
9699 \SpecialChar ~
9700 \SpecialChar ~
9701 \SpecialChar ~
9702 ld a,#0x01
9703 \newline
9704 ED 79\SpecialChar ~
9705 \SpecialChar ~
9706 \SpecialChar ~
9707 \SpecialChar ~
9708 \SpecialChar ~
9709 \SpecialChar ~
9710 out (c),a
9711 \layout Subsubsection
9712
9713 sfr
9714 \begin_inset LatexCommand \index{sfr}
9715
9716 \end_inset
9717
9718
9719 \begin_inset LatexCommand \index{\_\_sfr}
9720
9721 \end_inset
9722
9723  (in0/out0 to 8 bit addresses on Z180
9724 \begin_inset LatexCommand \index{Z180}
9725
9726 \end_inset
9727
9728 /HD64180
9729 \begin_inset LatexCommand \index{HD64180}
9730
9731 \end_inset
9732
9733 )
9734 \layout Standard
9735
9736 The compiler option -
9737 \begin_inset ERT
9738 status Collapsed
9739
9740 \layout Standard
9741
9742 \backslash
9743 /
9744 \end_inset
9745
9746 -portmode=180 (80) and a compiler #pragma\SpecialChar ~
9747 portmode
9748 \begin_inset LatexCommand \index{\#pragma portmode}
9749
9750 \end_inset
9751
9752 =z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
9753 ns
9754 \family typewriter
9755 in0/out0
9756 \family default
9757  instead of
9758 \family typewriter
9759 in/out
9760 \family default
9761 .
9762  If you include the file z180.h this will be set automatically.
9763 \layout Subsection
9764
9765 HC08 Storage Class
9766 \begin_inset LatexCommand \index{Storage class}
9767
9768 \end_inset
9769
9770  Language Extensions
9771 \layout Subsubsection
9772
9773 data
9774 \begin_inset LatexCommand \index{data (hc08 storage class)}
9775
9776 \end_inset
9777
9778
9779 \begin_inset LatexCommand \index{\_\_data (hc08 storage class)}
9780
9781 \end_inset
9782
9783
9784 \layout Standard
9785
9786 The data storage class declares a variable that resides in the first 256
9787  bytes of memory (the direct page).
9788  The HC08 is most efficient at accessing variables (especially pointers)
9789  stored here.
9790 \layout Subsubsection
9791
9792 xdata
9793 \begin_inset LatexCommand \index{xdata (hc08 storage class)}
9794
9795 \end_inset
9796
9797
9798 \begin_inset LatexCommand \index{\_\_xdata (hc08 storage class)}
9799
9800 \end_inset
9801
9802
9803 \layout Standard
9804
9805 The xdata storage class declares a variable that can reside anywhere in
9806  memory.
9807  This is the default if no storage class is specified.
9808
9809 \layout Section
9810
9811 Absolute Addressing
9812 \begin_inset LatexCommand \index{Absolute addressing}
9813
9814 \end_inset
9815
9816
9817 \layout Standard
9818
9819 Data items can be assigned an absolute address with the
9820 \emph on
9821 at
9822 \begin_inset LatexCommand \index{at}
9823
9824 \end_inset
9825
9826
9827 \begin_inset LatexCommand \index{\_\_at}
9828
9829 \end_inset
9830
9831  <address>
9832 \emph default
9833  keyword, in addition to a storage class, e.g.:
9834 \layout Verse
9835
9836
9837 \family typewriter
9838 xdata
9839 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9840
9841 \end_inset
9842
9843
9844 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9845
9846 \end_inset
9847
9848  at
9849 \begin_inset LatexCommand \index{at}
9850
9851 \end_inset
9852
9853
9854 \begin_inset LatexCommand \index{\_\_at}
9855
9856 \end_inset
9857
9858  0x7ffe unsigned int chksum;
9859 \layout Standard
9860
9861 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
9862  of the external ram.
9863  The compiler does
9864 \emph on
9865 not
9866 \emph default
9867  reserve any space for variables declared in this way (they are implemented
9868  with an equate in the assembler).
9869  Thus it is left to the programmer to make sure there are no overlaps with
9870  other variables that are declared without the absolute address.
9871  The assembler listing file (.lst
9872 \begin_inset LatexCommand \index{<file>.lst}
9873
9874 \end_inset
9875
9876 ) and the linker output files (.rst
9877 \begin_inset LatexCommand \index{<file>.rst}
9878
9879 \end_inset
9880
9881 ) and (.map
9882 \begin_inset LatexCommand \index{<file>.map}
9883
9884 \end_inset
9885
9886 ) are good places to look for such overlaps.
9887  Variables with an absolute address are
9888 \emph on
9889 not
9890 \emph default
9891  initialized
9892 \begin_inset LatexCommand \index{Variable initialization}
9893
9894 \end_inset
9895
9896 .
9897 \layout Standard
9898
9899 In case of memory mapped I/O devices the keyword
9900 \emph on
9901 volatile
9902 \emph default
9903  has to be used to tell the compiler that accesses might not be removed:
9904 \layout Verse
9905
9906
9907 \family typewriter
9908 volatile
9909 \begin_inset LatexCommand \index{volatile}
9910
9911 \end_inset
9912
9913  xdata
9914 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9915
9916 \end_inset
9917
9918  at
9919 \begin_inset LatexCommand \index{at}
9920
9921 \end_inset
9922
9923  0x8000 unsigned char PORTA_8255;
9924 \layout Standard
9925
9926 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
9927 r) array
9928 \family typewriter
9929 \size footnotesize
9930
9931 \begin_inset LatexCommand \index{Aligned array}
9932
9933 \end_inset
9934
9935
9936 \family default
9937 \size default
9938  starts at a block (256 byte) boundary
9939 \begin_inset LatexCommand \index{block boundary}
9940
9941 \end_inset
9942
9943  (section
9944 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
9945
9946 \end_inset
9947
9948  has an example).
9949 \newline
9950 Absolute addresses can be specified for variables in all storage classes,
9951  e.g.:
9952 \layout Verse
9953
9954
9955 \family typewriter
9956 bit
9957 \begin_inset LatexCommand \index{bit}
9958
9959 \end_inset
9960
9961  at
9962 \begin_inset LatexCommand \index{at}
9963
9964 \end_inset
9965
9966  0x02 bvar;
9967 \layout Standard
9968
9969 The above example will allocate the variable at offset 0x02 in the bit-addressab
9970 le space.
9971  There is no real advantage to assigning absolute addresses to variables
9972  in this manner, unless you want strict control over all the variables allocated.
9973  One possible use would be to write hardware portable code.
9974  For example, if you have a routine that uses one or more of the microcontroller
9975  I/O pins, and such pins are different for two different hardwares, you
9976  can declare the I/O pins in your routine using:
9977 \layout Verse
9978
9979
9980 \family typewriter
9981 extern volatile
9982 \begin_inset LatexCommand \index{volatile}
9983
9984 \end_inset
9985
9986  bit MOSI;\SpecialChar ~
9987 \SpecialChar ~
9988 \SpecialChar ~
9989 \SpecialChar ~
9990 /* master out, slave in */
9991 \newline
9992 extern volatile bit MISO;\SpecialChar ~
9993 \SpecialChar ~
9994 \SpecialChar ~
9995 \SpecialChar ~
9996 /* master in, slave out */
9997 \newline
9998 extern volatile bit MCLK;\SpecialChar ~
9999 \SpecialChar ~
10000 \SpecialChar ~
10001 \SpecialChar ~
10002 /* master clock */
10003 \newline
10004
10005 \newline
10006 /* Input and Output of a byte on a 3-wire serial bus.
10007 \newline
10008 \SpecialChar ~
10009 \SpecialChar ~
10010 \SpecialChar ~
10011 If needed adapt polarity of clock, polarity of data and bit order
10012 \newline
10013 \SpecialChar ~
10014 */
10015 \newline
10016 unsigned char spi_io(unsigned char out_byte)
10017 \newline
10018 {
10019 \newline
10020 \SpecialChar ~
10021 \SpecialChar ~
10022 \SpecialChar ~
10023 \SpecialChar ~
10024 unsigned char i=8;
10025 \newline
10026 \SpecialChar ~
10027 \SpecialChar ~
10028 \SpecialChar ~
10029 \SpecialChar ~
10030 do {
10031 \newline
10032 \SpecialChar ~
10033 \SpecialChar ~
10034 \SpecialChar ~
10035 \SpecialChar ~
10036 \SpecialChar ~
10037 \SpecialChar ~
10038 \SpecialChar ~
10039 \SpecialChar ~
10040 MOSI = out_byte & 0x80;
10041 \newline
10042 \SpecialChar ~
10043 \SpecialChar ~
10044 \SpecialChar ~
10045 \SpecialChar ~
10046 \SpecialChar ~
10047 \SpecialChar ~
10048 \SpecialChar ~
10049 \SpecialChar ~
10050 out_byte <<= 1;
10051 \newline
10052 \SpecialChar ~
10053 \SpecialChar ~
10054 \SpecialChar ~
10055 \SpecialChar ~
10056 \SpecialChar ~
10057 \SpecialChar ~
10058 \SpecialChar ~
10059 \SpecialChar ~
10060 MCLK = 1;
10061 \newline
10062 \SpecialChar ~
10063 \SpecialChar ~
10064 \SpecialChar ~
10065 \SpecialChar ~
10066 \SpecialChar ~
10067 \SpecialChar ~
10068 \SpecialChar ~
10069 \SpecialChar ~
10070 /* _asm nop _endasm; */\SpecialChar ~
10071 \SpecialChar ~
10072 \SpecialChar ~
10073 \SpecialChar ~
10074 \SpecialChar ~
10075 \SpecialChar ~
10076 \SpecialChar ~
10077 \SpecialChar ~
10078 /* for slow peripherals */
10079 \newline
10080 \SpecialChar ~
10081 \SpecialChar ~
10082 \SpecialChar ~
10083 \SpecialChar ~
10084 \SpecialChar ~
10085 \SpecialChar ~
10086 \SpecialChar ~
10087 \SpecialChar ~
10088 if(MISO)
10089 \newline
10090 \SpecialChar ~
10091 \SpecialChar ~
10092 \SpecialChar ~
10093 \SpecialChar ~
10094 \SpecialChar ~
10095 \SpecialChar ~
10096 \SpecialChar ~
10097 \SpecialChar ~
10098 \SpecialChar ~
10099 \SpecialChar ~
10100 \SpecialChar ~
10101 \SpecialChar ~
10102 out_byte += 1;
10103 \newline
10104 \SpecialChar ~
10105 \SpecialChar ~
10106 \SpecialChar ~
10107 \SpecialChar ~
10108 \SpecialChar ~
10109 \SpecialChar ~
10110 \SpecialChar ~
10111 \SpecialChar ~
10112 MCLK = 0;
10113 \newline
10114 \SpecialChar ~
10115 \SpecialChar ~
10116 \SpecialChar ~
10117 \SpecialChar ~
10118 } while(--i);
10119 \newline
10120 \SpecialChar ~
10121 \SpecialChar ~
10122 \SpecialChar ~
10123 \SpecialChar ~
10124 return out_byte;
10125 \newline
10126 }
10127 \layout Standard
10128
10129 Then, someplace in the code for the first hardware you would use
10130 \layout Verse
10131
10132
10133 \family typewriter
10134 bit at
10135 \begin_inset LatexCommand \index{at}
10136
10137 \end_inset
10138
10139
10140 \begin_inset LatexCommand \index{\_\_at}
10141
10142 \end_inset
10143
10144  0x80 MOSI;\SpecialChar ~
10145 \SpecialChar ~
10146 \SpecialChar ~
10147 \SpecialChar ~
10148 /* I/O port 0, bit 0 */
10149 \newline
10150 bit at 0x81 MISO;\SpecialChar ~
10151 \SpecialChar ~
10152 \SpecialChar ~
10153 \SpecialChar ~
10154 /* I/O port 0, bit 1 */
10155 \newline
10156 bit at 0x82 MCLK;\SpecialChar ~
10157 \SpecialChar ~
10158 \SpecialChar ~
10159 \SpecialChar ~
10160 /* I/O port 0, bit 2 */
10161 \layout Standard
10162
10163 Similarly, for the second hardware you would use
10164 \layout Verse
10165
10166
10167 \family typewriter
10168 bit at 0x83 MOSI;\SpecialChar ~
10169 \SpecialChar ~
10170 \SpecialChar ~
10171 \SpecialChar ~
10172 /* I/O port 0, bit 3 */
10173 \newline
10174 bit at 0x91 MISO;\SpecialChar ~
10175 \SpecialChar ~
10176 \SpecialChar ~
10177 \SpecialChar ~
10178 /* I/O port 1, bit 1 */
10179 \newline
10180 bit
10181 \begin_inset LatexCommand \index{bit}
10182
10183 \end_inset
10184
10185  at 0x92 MCLK;\SpecialChar ~
10186 \SpecialChar ~
10187 \SpecialChar ~
10188 \SpecialChar ~
10189 /* I/O port 1, bit 2 */
10190 \layout Standard
10191
10192 and you can use the same hardware dependent routine without changes, as
10193  for example in a library.
10194  This is somehow similar to sbit, but only one absolute address has to be
10195  specified in the whole project.
10196 \layout Section
10197
10198 Parameters
10199 \begin_inset LatexCommand \index{Parameters}
10200
10201 \end_inset
10202
10203
10204 \begin_inset LatexCommand \index{function parameter}
10205
10206 \end_inset
10207
10208  & Local Variables
10209 \begin_inset LatexCommand \index{local variables}
10210
10211 \end_inset
10212
10213
10214 \begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
10215
10216 \end_inset
10217
10218
10219 \layout Standard
10220
10221 Automatic (local) variables and parameters to functions can either be placed
10222  on the stack or in data-space.
10223  The default action of the compiler is to place these variables in the internal
10224  RAM (for small model) or external RAM (for large model).
10225  This in fact makes them similar to
10226 \emph on
10227 static
10228 \begin_inset LatexCommand \index{static}
10229
10230 \end_inset
10231
10232
10233 \emph default
10234  so by default functions are non-reentrant
10235 \begin_inset LatexCommand \index{reentrant}
10236
10237 \end_inset
10238
10239 .
10240
10241 \newline
10242
10243 \newline
10244 They can be placed on the stack
10245 \begin_inset LatexCommand \index{stack}
10246
10247 \end_inset
10248
10249  by using the
10250 \emph on
10251  -
10252 \begin_inset ERT
10253 status Collapsed
10254
10255 \layout Standard
10256
10257 \backslash
10258 /
10259 \end_inset
10260
10261 -stack-auto
10262 \begin_inset LatexCommand \index{-\/-stack-auto}
10263
10264 \end_inset
10265
10266
10267 \emph default
10268  option, by using
10269 \emph on
10270 #pragma\SpecialChar ~
10271 stackauto
10272 \emph default
10273
10274 \begin_inset LatexCommand \index{\#pragma stackauto}
10275
10276 \end_inset
10277
10278  or by using the
10279 \emph on
10280 reentrant
10281 \begin_inset LatexCommand \index{reentrant}
10282
10283 \end_inset
10284
10285
10286 \emph default
10287  keyword in the function declaration, e.g.:
10288 \layout Verse
10289
10290
10291 \family typewriter
10292 unsigned char foo(char i) reentrant
10293 \newline
10294 {
10295 \newline
10296 \SpecialChar ~
10297 \SpecialChar ~
10298 \SpecialChar ~
10299 \SpecialChar ~
10300 ...
10301
10302 \newline
10303 }
10304 \layout Standard
10305
10306 Since stack space on 8051 is limited, the
10307 \emph on
10308 reentrant
10309 \emph default
10310 keyword or the
10311 \emph on
10312  -
10313 \begin_inset ERT
10314 status Collapsed
10315
10316 \layout Standard
10317
10318 \backslash
10319 /
10320 \end_inset
10321
10322 -stack-auto
10323 \emph default
10324  option should be used sparingly.
10325  Note that the reentrant keyword just means that the parameters & local
10326  variables will be allocated to the stack, it
10327 \emph on
10328 does not
10329 \emph default
10330  mean that the function is register bank
10331 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
10332
10333 \end_inset
10334
10335  independent.
10336 \newline
10337
10338 \newline
10339 Local variables
10340 \begin_inset LatexCommand \index{local variables}
10341
10342 \end_inset
10343
10344  can be assigned storage classes and absolute
10345 \begin_inset LatexCommand \index{Absolute addressing}
10346
10347 \end_inset
10348
10349  addresses, e.g.:
10350 \layout Verse
10351
10352
10353 \family typewriter
10354 unsigned char foo()
10355 \newline
10356 {
10357 \newline
10358 \SpecialChar ~
10359 \SpecialChar ~
10360 \SpecialChar ~
10361 \SpecialChar ~
10362 xdata unsigned char i;
10363 \newline
10364 \SpecialChar ~
10365 \SpecialChar ~
10366 \SpecialChar ~
10367 \SpecialChar ~
10368 bit bvar;
10369 \newline
10370 \SpecialChar ~
10371 \SpecialChar ~
10372 \SpecialChar ~
10373 \SpecialChar ~
10374 data at
10375 \begin_inset LatexCommand \index{at}
10376
10377 \end_inset
10378
10379  0x31 unsigned char j;
10380 \newline
10381 \SpecialChar ~
10382 \SpecialChar ~
10383 \SpecialChar ~
10384 \SpecialChar ~
10385 ...
10386
10387 \newline
10388 }
10389 \layout Standard
10390
10391 In the above example the variable
10392 \emph on
10393 i
10394 \emph default
10395  will be allocated in the external ram,
10396 \emph on
10397 bvar
10398 \emph default
10399  in bit addressable space and
10400 \emph on
10401  j
10402 \emph default
10403  in internal ram.
10404  When compiled with
10405 \emph on
10406 -
10407 \begin_inset ERT
10408 status Collapsed
10409
10410 \layout Standard
10411
10412 \backslash
10413 /
10414 \end_inset
10415
10416 -stack-auto
10417 \emph default
10418  or when a function is declared as
10419 \emph on
10420 reentrant
10421 \emph default
10422  this should only be done for static variables.
10423 \layout Standard
10424
10425 Parameters
10426 \begin_inset LatexCommand \index{function parameter}
10427
10428 \end_inset
10429
10430  however are not allowed any storage class
10431 \begin_inset LatexCommand \index{Storage class}
10432
10433 \end_inset
10434
10435 , (storage classes for parameters will be ignored), their allocation is
10436  governed by the memory model in use, and the reentrancy options.
10437 \layout Standard
10438
10439 It is however allowed to use bit parameters in reentrant functions and also
10440  non-static local bit variables are supported.
10441  Efficient use is limited to 8 semi-bitregisters in bit space.
10442  They are pushed and popped to stack as a single byte just like the normal
10443  registers.
10444 \layout Section
10445
10446 Overlaying
10447 \begin_inset LatexCommand \label{sub:Overlaying}
10448
10449 \end_inset
10450
10451
10452 \begin_inset LatexCommand \index{Overlaying}
10453
10454 \end_inset
10455
10456
10457 \layout Standard
10458
10459 For non-reentrant
10460 \begin_inset LatexCommand \index{reentrant}
10461
10462 \end_inset
10463
10464  functions SDCC will try to reduce internal ram space usage by overlaying
10465  parameters and local variables of a function (if possible).
10466  Parameters and local variables
10467 \begin_inset LatexCommand \index{local variables}
10468
10469 \end_inset
10470
10471  of a function will be allocated to an overlayable segment if the function
10472  has
10473 \emph on
10474 no other function calls and the function is non-reentrant and the memory
10475  model
10476 \begin_inset LatexCommand \index{Memory model}
10477
10478 \end_inset
10479
10480  is small.
10481
10482 \emph default
10483  If an explicit storage class
10484 \begin_inset LatexCommand \index{Storage class}
10485
10486 \end_inset
10487
10488  is specified for a local variable, it will NOT be overlayed.
10489 \layout Standard
10490
10491 Note that the compiler (not the linkage editor) makes the decision for overlayin
10492 g the data items.
10493  Functions that are called from an interrupt service routine should be preceded
10494  by a #pragma\SpecialChar ~
10495 nooverlay
10496 \begin_inset LatexCommand \index{\#pragma nooverlay}
10497
10498 \end_inset
10499
10500  if they are not reentrant.
10501 \layout Standard
10502
10503 Also note that the compiler does not do any processing of inline assembler
10504  code, so the compiler might incorrectly assign local variables and parameters
10505  of a function into the overlay segment if the inline assembler code calls
10506  other c-functions that might use the overlay.
10507  In that case the #pragma\SpecialChar ~
10508 nooverlay should be used.
10509 \layout Standard
10510
10511 Parameters and local variables of functions that contain 16 or 32 bit multiplica
10512 tion
10513 \begin_inset LatexCommand \index{Multiplication}
10514
10515 \end_inset
10516
10517  or division
10518 \begin_inset LatexCommand \index{Division}
10519
10520 \end_inset
10521
10522  will NOT be overlayed since these are implemented using external functions,
10523  e.g.:
10524 \layout Verse
10525
10526
10527 \family typewriter
10528 #pragma save
10529 \newline
10530 #pragma nooverlay
10531 \begin_inset LatexCommand \index{\#pragma nooverlay}
10532
10533 \end_inset
10534
10535
10536 \newline
10537 void set_error(unsigned char errcd)
10538 \newline
10539 {
10540 \newline
10541 \SpecialChar ~
10542 \SpecialChar ~
10543 \SpecialChar ~
10544 \SpecialChar ~
10545 P3 = errcd;
10546 \newline
10547 }
10548 \newline
10549 #pragma restore
10550 \newline
10551
10552 \newline
10553 void some_isr () interrupt
10554 \begin_inset LatexCommand \index{interrupt}
10555
10556 \end_inset
10557
10558  2
10559 \newline
10560 {
10561 \newline
10562 \SpecialChar ~
10563 \SpecialChar ~
10564 \SpecialChar ~
10565 \SpecialChar ~
10566 ...
10567 \newline
10568 \SpecialChar ~
10569 \SpecialChar ~
10570 \SpecialChar ~
10571 \SpecialChar ~
10572 set_error(10);
10573 \newline
10574 \SpecialChar ~
10575 \SpecialChar ~
10576 \SpecialChar ~
10577 \SpecialChar ~
10578 ...
10579
10580 \newline
10581 }
10582 \layout Standard
10583
10584 In the above example the parameter
10585 \emph on
10586 errcd
10587 \emph default
10588  for the function
10589 \emph on
10590 set_error
10591 \emph default
10592  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
10593 nooverlay was
10594  not present, this could cause unpredictable runtime behavior when called
10595  from an interrupt service routine.
10596  The #pragma\SpecialChar ~
10597 nooverlay ensures that the parameters and local variables for
10598  the function are NOT overlayed.
10599 \layout Section
10600
10601 Interrupt Service Routines
10602 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
10603
10604 \end_inset
10605
10606
10607 \layout Subsection
10608
10609 General Information
10610 \layout Standard
10611
10612 SDCC allows
10613 \emph on
10614 i
10615 \emph default
10616 nterrupt
10617 \emph on
10618 s
10619 \emph default
10620 ervice
10621 \emph on
10622 r
10623 \emph default
10624 outines to be coded in C, with some extended keywords.
10625 \layout Verse
10626
10627
10628 \family typewriter
10629 void timer_isr (void) interrupt 1 using 1
10630 \newline
10631 {
10632 \newline
10633 \SpecialChar ~
10634 \SpecialChar ~
10635 \SpecialChar ~
10636 \SpecialChar ~
10637 ...
10638
10639 \newline
10640 }
10641 \layout Standard
10642
10643 The optional number following the
10644 \emph on
10645 interrupt
10646 \begin_inset LatexCommand \index{interrupt}
10647
10648 \end_inset
10649
10650
10651 \begin_inset LatexCommand \index{\_\_interrupt}
10652
10653 \end_inset
10654
10655
10656 \emph default
10657  keyword is the interrupt number this routine will service.
10658  When present, the compiler will insert a call to this routine in the interrupt
10659  vector table for the interrupt number specified.
10660  If you have multiple source files in your project, interrupt service routines
10661  can be present in any of them, but a prototype of the isr MUST be present
10662  or included in the file that contains the function
10663 \emph on
10664 main
10665 \emph default
10666 .
10667  The optional
10668 \emph on
10669 using
10670 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10671
10672 \end_inset
10673
10674
10675 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
10676
10677 \end_inset
10678
10679
10680 \emph default
10681  keyword can be used to tell the compiler to use the specified register
10682  bank (8051 specific) when generating code for this function.
10683
10684 \newline
10685
10686 \layout Standard
10687
10688 Interrupt service routines open the door for some very interesting bugs:
10689 \newline
10690 If an interrupt service routine changes variables which are accessed by
10691  other functions these variables have to be declared
10692 \emph on
10693 volatile
10694 \emph default
10695
10696 \begin_inset LatexCommand \index{volatile}
10697
10698 \end_inset
10699
10700 .
10701
10702 \layout Standard
10703
10704 If the access to these variables is not
10705 \emph on
10706 atomic
10707 \begin_inset LatexCommand \index{atomic}
10708
10709 \end_inset
10710
10711
10712 \emph default
10713  (i.e.
10714  the processor needs more than one instruction for the access and could
10715  be interrupted while accessing the variable) the interrupt must be disabled
10716  during the access to avoid inconsistent data.
10717  Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
10718  and should be protected by disabling interrupts.
10719  You're not automatically on the safe side if you use 8 bit variables though.
10720  We need an example here: f.e.
10721  on the 8051 the harmless looking
10722 \begin_inset Quotes srd
10723 \end_inset
10724
10725
10726 \family typewriter
10727 flags\SpecialChar ~
10728 |=\SpecialChar ~
10729 0x80;
10730 \family default
10731
10732 \begin_inset Quotes sld
10733 \end_inset
10734
10735  is not atomic if
10736 \family typewriter
10737 flags
10738 \family default
10739  resides in xdata.
10740  Setting
10741 \begin_inset Quotes srd
10742 \end_inset
10743
10744
10745 \family typewriter
10746 flags\SpecialChar ~
10747 |=\SpecialChar ~
10748 0x40;
10749 \family default
10750
10751 \begin_inset Quotes sld
10752 \end_inset
10753
10754  from within an interrupt routine might get lost if the interrupt occurs
10755  at the wrong time.
10756
10757 \begin_inset Quotes sld
10758 \end_inset
10759
10760
10761 \family typewriter
10762 counter\SpecialChar ~
10763 +=\SpecialChar ~
10764 8;
10765 \family default
10766
10767 \begin_inset Quotes srd
10768 \end_inset
10769
10770  is not atomic on the 8051 even if
10771 \family typewriter
10772 counter
10773 \family default
10774  is located in data memory.
10775  Bugs like these are hard to reproduce and can cause a lot of trouble.
10776
10777 \layout Standard
10778
10779 The return address and the registers used in the interrupt service routine
10780  are saved on the stack
10781 \begin_inset LatexCommand \index{stack}
10782
10783 \end_inset
10784
10785  so there must be sufficient stack space.
10786  If there isn't variables or registers (or even the return address itself)
10787  will be corrupted.
10788  This
10789 \emph on
10790 stack overflow
10791 \emph default
10792
10793 \begin_inset LatexCommand \index{stack overflow}
10794
10795 \end_inset
10796
10797  is most likely to happen if the interrupt occurs during the
10798 \begin_inset Quotes sld
10799 \end_inset
10800
10801 deepest
10802 \begin_inset Quotes srd
10803 \end_inset
10804
10805  subroutine when the stack is already in use for f.e.
10806  many return addresses.
10807 \layout Standard
10808
10809 A special note here, int (16 bit) and long (32 bit) integer division
10810 \begin_inset LatexCommand \index{Division}
10811
10812 \end_inset
10813
10814 , multiplication
10815 \begin_inset LatexCommand \index{Multiplication}
10816
10817 \end_inset
10818
10819  & modulus
10820 \begin_inset LatexCommand \index{Modulus}
10821
10822 \end_inset
10823
10824  and floating-point
10825 \begin_inset LatexCommand \index{Floating point support}
10826
10827 \end_inset
10828
10829  operations are implemented using external support routines developed in
10830  ANSI-C.
10831  If an interrupt service routine needs to do any of these operations then
10832  the support routines (as mentioned in a following section) will have to
10833  be recompiled using the
10834 \emph on
10835  -
10836 \begin_inset ERT
10837 status Collapsed
10838
10839 \layout Standard
10840
10841 \backslash
10842 /
10843 \end_inset
10844
10845 -stack-auto
10846 \begin_inset LatexCommand \index{-\/-stack-auto}
10847
10848 \end_inset
10849
10850
10851 \emph default
10852  option and the source file will need to be compiled using the
10853 \emph on
10854 -
10855 \begin_inset ERT
10856 status Collapsed
10857
10858 \layout Standard
10859
10860 \backslash
10861 /
10862 \end_inset
10863
10864 -int-long-reent
10865 \emph default
10866
10867 \begin_inset LatexCommand \index{-\/-int-long-reent}
10868
10869 \end_inset
10870
10871  compiler option.
10872 \layout Standard
10873
10874 Calling other functions from an interrupt service routine is not recommended,
10875  avoid it if possible.
10876  Note that when some function is called from an interrupt service routine
10877  it should be preceded by a #pragma\SpecialChar ~
10878 nooverlay
10879 \begin_inset LatexCommand \index{\#pragma nooverlay}
10880
10881 \end_inset
10882
10883  if it is not reentrant.
10884  Furthermore nonreentrant functions should not be called from the main program
10885  while the interrupt service routine might be active.
10886
10887 \newline
10888
10889 \newline
10890 Also see section
10891 \begin_inset LatexCommand \ref{sub:Overlaying}
10892
10893 \end_inset
10894
10895 \SpecialChar ~
10896 about Overlaying and section
10897 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
10898
10899 \end_inset
10900
10901 \SpecialChar ~
10902 about Functions using private register banks.
10903 \layout Subsection
10904
10905 MCS51/DS390 Interrupt Service Routines
10906 \layout Standard
10907
10908 Interrupt numbers and the corresponding address & descriptions for the Standard
10909  8051/8052 are listed below.
10910  SDCC will automatically adjust the interrupt vector table to the maximum
10911  interrupt number specified.
10912 \newline
10913
10914 \layout Standard
10915 \align center
10916
10917 \begin_inset  Tabular
10918 <lyxtabular version="3" rows="7" columns="3">
10919 <features>
10920 <column alignment="center" valignment="top" leftline="true" width="0in">
10921 <column alignment="center" valignment="top" leftline="true" width="0in">
10922 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
10923 <row topline="true" bottomline="true">
10924 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10925 \begin_inset Text
10926
10927 \layout Standard
10928
10929 Interrupt #
10930 \end_inset
10931 </cell>
10932 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10933 \begin_inset Text
10934
10935 \layout Standard
10936
10937 Description
10938 \end_inset
10939 </cell>
10940 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10941 \begin_inset Text
10942
10943 \layout Standard
10944
10945 Vector Address
10946 \end_inset
10947 </cell>
10948 </row>
10949 <row topline="true">
10950 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10951 \begin_inset Text
10952
10953 \layout Standard
10954
10955 0
10956 \end_inset
10957 </cell>
10958 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10959 \begin_inset Text
10960
10961 \layout Standard
10962
10963 External 0
10964 \end_inset
10965 </cell>
10966 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10967 \begin_inset Text
10968
10969 \layout Standard
10970
10971 0x0003
10972 \end_inset
10973 </cell>
10974 </row>
10975 <row topline="true">
10976 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10977 \begin_inset Text
10978
10979 \layout Standard
10980
10981 1
10982 \end_inset
10983 </cell>
10984 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10985 \begin_inset Text
10986
10987 \layout Standard
10988
10989 Timer 0
10990 \end_inset
10991 </cell>
10992 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10993 \begin_inset Text
10994
10995 \layout Standard
10996
10997 0x000B
10998 \end_inset
10999 </cell>
11000 </row>
11001 <row topline="true">
11002 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11003 \begin_inset Text
11004
11005 \layout Standard
11006
11007 2
11008 \end_inset
11009 </cell>
11010 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11011 \begin_inset Text
11012
11013 \layout Standard
11014
11015 External 1
11016 \end_inset
11017 </cell>
11018 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11019 \begin_inset Text
11020
11021 \layout Standard
11022
11023 0x0013
11024 \end_inset
11025 </cell>
11026 </row>
11027 <row topline="true">
11028 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11029 \begin_inset Text
11030
11031 \layout Standard
11032
11033 3
11034 \end_inset
11035 </cell>
11036 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11037 \begin_inset Text
11038
11039 \layout Standard
11040
11041 Timer 1
11042 \end_inset
11043 </cell>
11044 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11045 \begin_inset Text
11046
11047 \layout Standard
11048
11049 0x001B
11050 \end_inset
11051 </cell>
11052 </row>
11053 <row topline="true">
11054 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11055 \begin_inset Text
11056
11057 \layout Standard
11058
11059 4
11060 \end_inset
11061 </cell>
11062 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11063 \begin_inset Text
11064
11065 \layout Standard
11066
11067 Serial
11068 \end_inset
11069 </cell>
11070 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11071 \begin_inset Text
11072
11073 \layout Standard
11074
11075 0x0023
11076 \end_inset
11077 </cell>
11078 </row>
11079 <row topline="true" bottomline="true">
11080 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11081 \begin_inset Text
11082
11083 \layout Standard
11084
11085 5
11086 \end_inset
11087 </cell>
11088 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11089 \begin_inset Text
11090
11091 \layout Standard
11092
11093 Timer 2 (8052)
11094 \end_inset
11095 </cell>
11096 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11097 \begin_inset Text
11098
11099 \layout Standard
11100
11101 0x002B
11102 \end_inset
11103 </cell>
11104 </row>
11105 </lyxtabular>
11106
11107 \end_inset
11108
11109
11110 \newline
11111
11112 \layout Standard
11113
11114 If the interrupt service routine is defined without
11115 \emph on
11116 using
11117 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11118
11119 \end_inset
11120
11121
11122 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11123
11124 \end_inset
11125
11126
11127 \emph default
11128  a register bank or with register bank 0 (
11129 \emph on
11130 using
11131 \emph default
11132  0), the compiler will save the registers used by itself on the stack upon
11133  entry and restore them at exit, however if such an interrupt service routine
11134  calls another function then the entire register bank will be saved on the
11135  stack.
11136  This scheme may be advantageous for small interrupt service routines which
11137  have low register usage.
11138 \layout Standard
11139
11140 If the interrupt service routine is defined to be using a specific register
11141  bank then only
11142 \emph on
11143 a, b, dptr
11144 \emph default
11145  & psw are saved and restored, if such an interrupt service routine calls
11146  another function (using another register bank) then the entire register
11147  bank of the called function will be saved on the stack.
11148  This scheme is recommended for larger interrupt service routines.
11149 \layout Subsection
11150
11151 HC08 Interrupt Service Routines
11152 \layout Standard
11153
11154 Since the number of interrupts available is chip specific and the interrupt
11155  vector table always ends at the last byte of memory, the interrupt numbers
11156  corresponds to the interrupt vectors in reverse order of address.
11157  For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
11158  2 will use the interrupt vector at 0xfffa, and so on.
11159  However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
11160  this way; instead see section
11161 \begin_inset LatexCommand \ref{sub:Startup-Code}
11162
11163 \end_inset
11164
11165  for details on customizing startup.
11166 \layout Subsection
11167
11168 Z80 Interrupt Service Routines
11169 \layout Standard
11170
11171 The Z80 uses several different methods for determining the correct interrupt
11172  vector depending on the hardware implementation.
11173  Therefore, SDCC ignores the optional interrupt number and does not attempt
11174  to generate an interrupt vector table.
11175 \layout Standard
11176
11177 By default, SDCC generates code for a maskable interrupt, which uses an
11178  RETI instruction to return from the interrupt.
11179  To write an interrupt handler for the non-maskable interrupt, which needs
11180  an RETN instruction instead, add the
11181 \emph on
11182 critical
11183 \emph default
11184  keyword:
11185 \layout Verse
11186
11187
11188 \family typewriter
11189 void nmi_isr (void) critical interrupt
11190 \newline
11191 {
11192 \newline
11193 \SpecialChar ~
11194 \SpecialChar ~
11195 \SpecialChar ~
11196 \SpecialChar ~
11197 ...
11198
11199 \newline
11200 }
11201 \layout Section
11202
11203 Enabling and Disabling Interrupts
11204 \layout Subsection
11205
11206 Critical Functions and Critical Statements
11207 \layout Standard
11208
11209 A special keyword may be associated with a block or a function declaring
11210  it as
11211 \emph on
11212 critical
11213 \emph default
11214 .
11215  SDCC will generate code to disable all interrupts
11216 \begin_inset LatexCommand \index{interrupt}
11217
11218 \end_inset
11219
11220  upon entry to a critical function and restore the interrupt enable to the
11221  previous state before returning.
11222  Nesting critical functions will need one additional byte on the stack
11223 \begin_inset LatexCommand \index{stack}
11224
11225 \end_inset
11226
11227  for each call.
11228 \layout Verse
11229
11230
11231 \family typewriter
11232 int foo () critical
11233 \begin_inset LatexCommand \index{critical}
11234
11235 \end_inset
11236
11237
11238 \begin_inset LatexCommand \index{\_\_critical}
11239
11240 \end_inset
11241
11242
11243 \newline
11244 {
11245 \newline
11246 \SpecialChar ~
11247 \SpecialChar ~
11248 \SpecialChar ~
11249 \SpecialChar ~
11250 ...
11251
11252 \newline
11253 \SpecialChar ~
11254 \SpecialChar ~
11255 \SpecialChar ~
11256 \SpecialChar ~
11257 ...
11258
11259 \newline
11260 }
11261 \layout Standard
11262
11263 The critical attribute maybe used with other attributes like
11264 \emph on
11265 reentrant.
11266 \emph default
11267
11268 \newline
11269 The keyword
11270 \emph on
11271 critical
11272 \emph default
11273  may also be used to disable interrupts more locally:
11274 \layout Verse
11275
11276
11277 \family typewriter
11278 critical{ i++; }
11279 \layout Standard
11280
11281 More than one statement could have been included in the block.
11282 \layout Subsection
11283
11284 Enabling and Disabling Interrupts directly
11285 \layout Standard
11286
11287 Interrupts
11288 \begin_inset LatexCommand \index{interrupt}
11289
11290 \end_inset
11291
11292  can also be disabled and enabled directly (8051):
11293 \layout Verse
11294
11295
11296 \family typewriter
11297 EA = 0;\SpecialChar ~
11298 \SpecialChar ~
11299 \SpecialChar ~
11300 \SpecialChar ~
11301 \SpecialChar ~
11302 \SpecialChar ~
11303 \SpecialChar ~
11304 \SpecialChar ~
11305 \SpecialChar ~
11306 \SpecialChar ~
11307 \SpecialChar ~
11308 \SpecialChar ~
11309 or:\SpecialChar ~
11310 \SpecialChar ~
11311 \SpecialChar ~
11312 \SpecialChar ~
11313 \SpecialChar ~
11314 \SpecialChar ~
11315 \SpecialChar ~
11316 \SpecialChar ~
11317 \SpecialChar ~
11318 \SpecialChar ~
11319 \SpecialChar ~
11320 EA_SAVE = EA;
11321 \layout Verse
11322
11323
11324 \family typewriter
11325 ...\SpecialChar ~
11326 \SpecialChar ~
11327 \SpecialChar ~
11328 \SpecialChar ~
11329 \SpecialChar ~
11330 \SpecialChar ~
11331 \SpecialChar ~
11332 \SpecialChar ~
11333 \SpecialChar ~
11334 \SpecialChar ~
11335 \SpecialChar ~
11336 \SpecialChar ~
11337 \SpecialChar ~
11338 \SpecialChar ~
11339 \SpecialChar ~
11340 \SpecialChar ~
11341 \SpecialChar ~
11342 \SpecialChar ~
11343 \SpecialChar ~
11344 \SpecialChar ~
11345 \SpecialChar ~
11346 \SpecialChar ~
11347 \SpecialChar ~
11348 \SpecialChar ~
11349 \SpecialChar ~
11350 \SpecialChar ~
11351 \SpecialChar ~
11352 \SpecialChar ~
11353 \SpecialChar ~
11354 \SpecialChar ~
11355 EA = 0;
11356 \layout Verse
11357
11358
11359 \family typewriter
11360 EA = 1;\SpecialChar ~
11361 \SpecialChar ~
11362 \SpecialChar ~
11363 \SpecialChar ~
11364 \SpecialChar ~
11365 \SpecialChar ~
11366 \SpecialChar ~
11367 \SpecialChar ~
11368 \SpecialChar ~
11369 \SpecialChar ~
11370 \SpecialChar ~
11371 \SpecialChar ~
11372 \SpecialChar ~
11373 \SpecialChar ~
11374 \SpecialChar ~
11375 \SpecialChar ~
11376 \SpecialChar ~
11377 \SpecialChar ~
11378 \SpecialChar ~
11379 \SpecialChar ~
11380 \SpecialChar ~
11381 \SpecialChar ~
11382 \SpecialChar ~
11383 \SpecialChar ~
11384 \SpecialChar ~
11385 \SpecialChar ~
11386 ...
11387 \layout Verse
11388
11389
11390 \family typewriter
11391 \SpecialChar ~
11392 \SpecialChar ~
11393 \SpecialChar ~
11394 \SpecialChar ~
11395 \SpecialChar ~
11396 \SpecialChar ~
11397 \SpecialChar ~
11398 \SpecialChar ~
11399 \SpecialChar ~
11400 \SpecialChar ~
11401 \SpecialChar ~
11402 \SpecialChar ~
11403 \SpecialChar ~
11404 \SpecialChar ~
11405 \SpecialChar ~
11406 \SpecialChar ~
11407 \SpecialChar ~
11408 \SpecialChar ~
11409 \SpecialChar ~
11410 \SpecialChar ~
11411 \SpecialChar ~
11412 \SpecialChar ~
11413 \SpecialChar ~
11414 \SpecialChar ~
11415 \SpecialChar ~
11416 \SpecialChar ~
11417 \SpecialChar ~
11418 \SpecialChar ~
11419 \SpecialChar ~
11420 \SpecialChar ~
11421 \SpecialChar ~
11422 \SpecialChar ~
11423 \SpecialChar ~
11424 EA = EA_SAVE;
11425 \layout Standard
11426
11427 On other architectures which have seperate opcodes for enabling and disabling
11428  interrupts you might want to make use of defines with inline assembly
11429 \begin_inset LatexCommand \index{Assembler routines}
11430
11431 \end_inset
11432
11433  (HC08):
11434 \layout Verse
11435
11436
11437 \family typewriter
11438 #define CLI _asm
11439 \begin_inset LatexCommand \index{\_asm}
11440
11441 \end_inset
11442
11443 \SpecialChar ~
11444 \SpecialChar ~
11445 cli\SpecialChar ~
11446 \SpecialChar ~
11447 _endasm
11448 \begin_inset LatexCommand \index{\_endasm}
11449
11450 \end_inset
11451
11452 ;
11453 \layout Verse
11454
11455
11456 \family typewriter
11457 #define SEI _asm\SpecialChar ~
11458 \SpecialChar ~
11459 sei\SpecialChar ~
11460 \SpecialChar ~
11461 _endasm;
11462 \layout Verse
11463
11464
11465 \family typewriter
11466 ...
11467 \layout Standard
11468
11469 Note: it is sometimes sufficient to disable only a specific interrupt source
11470  like f.e.
11471  a timer or serial interrupt by manipulating an
11472 \emph on
11473 interrupt mask
11474 \begin_inset LatexCommand \index{interrupt mask}
11475
11476 \end_inset
11477
11478
11479 \emph default
11480  register.
11481
11482 \layout Standard
11483
11484 Usually the time during which interrupts are disabled should be kept as
11485  short as possible.
11486  This minimizes both
11487 \emph on
11488 interrupt latency
11489 \emph default
11490
11491 \begin_inset LatexCommand \index{interrupt latency}
11492
11493 \end_inset
11494
11495  (the time between the occurrence of the interrupt and the execution of
11496  the first code in the interrupt routine) and
11497 \emph on
11498 interrupt jitter
11499 \emph default
11500
11501 \begin_inset LatexCommand \index{interrupt jitter}
11502
11503 \end_inset
11504
11505  (the difference between the shortest and the longest interrupt latency).
11506  These really are something different, f.e.
11507  a serial interrupt has to be served before its buffer overruns so it cares
11508  for the maximum interrupt latency, whereas it does not care about jitter.
11509  On a loudspeaker driven via a digital to analog converter which is fed
11510  by an interrupt a latency of a few milliseconds might be tolerable, whereas
11511  a much smaller jitter will be very audible.
11512 \layout Standard
11513
11514 You can reenable interrupts within an interrupt routine and on some architecture
11515 s you can make use of two (or more) levels of
11516 \emph on
11517 interrupt priorities
11518 \emph default
11519
11520 \begin_inset LatexCommand \index{interrupt priority}
11521
11522 \end_inset
11523
11524 .
11525  On some architectures which don't support interrupt priorities these can
11526  be implemented by manipulating the interrupt mask and reenabling interrupts
11527  within the interrupt routine.
11528  Check there is sufficient space on the stack
11529 \begin_inset LatexCommand \index{stack}
11530
11531 \end_inset
11532
11533  and don't add complexity unless you have to.
11534
11535 \layout Subsection
11536
11537 Semaphore
11538 \begin_inset LatexCommand \index{semaphore}
11539
11540 \end_inset
11541
11542  locking (mcs51/ds390)
11543 \layout Standard
11544
11545 Some architectures (mcs51/ds390) have an atomic
11546 \begin_inset LatexCommand \index{atomic}
11547
11548 \end_inset
11549
11550  bit test and
11551 \emph on
11552
11553 \emph default
11554 clear
11555 \emph on
11556
11557 \emph default
11558 instruction.
11559  These type of instructions are typically used in preemptive multitasking
11560  systems, where a routine f.e.
11561  claims the use of a data structure ('acquires a lock
11562 \begin_inset LatexCommand \index{lock}
11563
11564 \end_inset
11565
11566  on it'), makes some modifications and then releases the lock when the data
11567  structure is consistent again.
11568  The instruction may also be used if interrupt and non-interrupt code have
11569  to compete for a resource.
11570  With the atomic bit test and clear instruction interrupts
11571 \begin_inset LatexCommand \index{interrupt}
11572
11573 \end_inset
11574
11575  don't have to be disabled for the locking operation.
11576
11577 \layout Standard
11578
11579 SDCC generates this instruction if the source follows this pattern:
11580 \layout Verse
11581
11582
11583 \family typewriter
11584 volatile
11585 \begin_inset LatexCommand \index{volatile}
11586
11587 \end_inset
11588
11589  bit resource_is_free;
11590 \newline
11591
11592 \newline
11593 if (resource_is_free)
11594 \newline
11595 \SpecialChar ~
11596 \SpecialChar ~
11597 {
11598 \newline
11599 \SpecialChar ~
11600 \SpecialChar ~
11601 \SpecialChar ~
11602 \SpecialChar ~
11603 resource_is_free=0;
11604 \newline
11605 \SpecialChar ~
11606 \SpecialChar ~
11607 \SpecialChar ~
11608 \SpecialChar ~
11609 ...
11610
11611 \newline
11612 \SpecialChar ~
11613 \SpecialChar ~
11614 \SpecialChar ~
11615 \SpecialChar ~
11616 resource_is_free=1;
11617 \newline
11618 \SpecialChar ~
11619 \SpecialChar ~
11620 }
11621 \layout Standard
11622
11623 Note, mcs51 and ds390 support only an atomic
11624 \begin_inset LatexCommand \index{atomic}
11625
11626 \end_inset
11627
11628  bit test and
11629 \emph on
11630 clear
11631 \emph default
11632  instruction (as opposed to atomic bit test and
11633 \emph on
11634 set).
11635 \layout Section
11636
11637 Functions using private register banks
11638 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
11639
11640 \end_inset
11641
11642  (mcs51/ds390)
11643 \layout Standard
11644
11645 Some architectures have support for quickly changing register sets.
11646  SDCC supports this feature with the
11647 \emph on
11648 using
11649 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11650
11651 \end_inset
11652
11653
11654 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11655
11656 \end_inset
11657
11658
11659 \emph default
11660  attribute (which tells the compiler to use a register bank
11661 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
11662
11663 \end_inset
11664
11665  other than the default bank zero).
11666  It should only be applied to
11667 \emph on
11668 interrupt
11669 \begin_inset LatexCommand \index{interrupt}
11670
11671 \end_inset
11672
11673
11674 \emph default
11675  functions (see footnote below).
11676  This will in most circumstances make the generated ISR code more efficient
11677  since it will not have to save registers on the stack.
11678 \layout Standard
11679
11680 The
11681 \emph on
11682 using
11683 \emph default
11684  attribute will have no effect on the generated code for a
11685 \emph on
11686 non-interrupt
11687 \emph default
11688  function (but may occasionally be useful anyway
11689 \begin_inset Foot
11690 collapsed false
11691
11692 \layout Standard
11693
11694 possible exception: if a function is called ONLY from 'interrupt' functions
11695  using a particular bank, it can be declared with the same 'using' attribute
11696  as the calling 'interrupt' functions.
11697  For instance, if you have several ISRs using bank one, and all of them
11698  call memcpy(), it might make sense to create a specialized version of memcpy()
11699  'using 1', since this would prevent the ISR from having to save bank zero
11700  to the stack on entry and switch to bank zero before calling the function
11701 \end_inset
11702
11703 ).
11704 \newline
11705
11706 \emph on
11707 (pending: I don't think this has been done yet)
11708 \layout Standard
11709
11710 An
11711 \emph on
11712 interrupt
11713 \emph default
11714  function using a non-zero bank will assume that it can trash that register
11715  bank, and will not save it.
11716  Since high-priority interrupts
11717 \begin_inset LatexCommand \index{interrupts}
11718
11719 \end_inset
11720
11721
11722 \begin_inset LatexCommand \index{interrupt priority}
11723
11724 \end_inset
11725
11726  can interrupt low-priority ones on the 8051 and friends, this means that
11727  if a high-priority ISR
11728 \emph on
11729 using
11730 \emph default
11731  a particular bank occurs while processing a low-priority ISR
11732 \emph on
11733 using
11734 \emph default
11735  the same bank, terrible and bad things can happen.
11736  To prevent this, no single register bank should be
11737 \emph on
11738 used
11739 \emph default
11740  by both a high priority and a low priority ISR.
11741  This is probably most easily done by having all high priority ISRs use
11742  one bank and all low priority ISRs use another.
11743  If you have an ISR which can change priority at runtime, you're on your
11744  own: I suggest using the default bank zero and taking the small performance
11745  hit.
11746 \layout Standard
11747
11748 It is most efficient if your ISR calls no other functions.
11749  If your ISR must call other functions, it is most efficient if those functions
11750  use the same bank as the ISR (see note 1 below); the next best is if the
11751  called functions use bank zero.
11752  It is very inefficient to call a function using a different, non-zero bank
11753  from an ISR.
11754
11755 \layout Section
11756
11757 Startup Code
11758 \begin_inset LatexCommand \label{sub:Startup-Code}
11759
11760 \end_inset
11761
11762
11763 \begin_inset LatexCommand \index{Startup code}
11764
11765 \end_inset
11766
11767
11768 \layout Subsection
11769
11770 MCS51/DS390 Startup Code
11771 \layout Standard
11772
11773 The compiler inserts a call to the C routine
11774 \emph on
11775 _sdcc_external_startup()
11776 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
11777
11778 \end_inset
11779
11780
11781 \series bold
11782 \emph default
11783
11784 \series default
11785 at the start of the CODE area.
11786  This routine is in the runtime library
11787 \begin_inset LatexCommand \index{Runtime library}
11788
11789 \end_inset
11790
11791 .
11792  By default this routine returns 0, if this routine returns a non-zero value,
11793  the static & global variable initialization will be skipped and the function
11794  main will be invoked.
11795  Otherwise static & global variables will be initialized before the function
11796  main is invoked.
11797  You could add a
11798 \emph on
11799 _sdcc_external_startup()
11800 \emph default
11801  routine to your program to override the default if you need to setup hardware
11802  or perform some other critical operation prior to static & global variable
11803  initialization
11804 \begin_inset LatexCommand \index{Variable initialization}
11805
11806 \end_inset
11807
11808 .
11809  On some mcs51 variants xdata
11810 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
11811
11812 \end_inset
11813
11814  memory has to be explicitly enabled before it can be accessed or if the
11815  watchdog needs to be disabled, this is the place to do it.
11816  The startup code clears all internal data memory, 256 bytes by default,
11817  but from 0 to n-1 if
11818 \emph on
11819 -
11820 \begin_inset ERT
11821 status Collapsed
11822
11823 \layout Standard
11824
11825 \backslash
11826 /
11827 \end_inset
11828
11829 -iram-size
11830 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
11831
11832 \end_inset
11833
11834 n
11835 \emph default
11836  is used.
11837  (recommended for Chipcon CC1010).
11838 \layout Standard
11839
11840 See also the compiler option
11841 \emph on
11842 -
11843 \begin_inset ERT
11844 status Collapsed
11845
11846 \layout Standard
11847
11848 \backslash
11849 /
11850 \end_inset
11851
11852 -no-xinit
11853 \emph default
11854 -
11855 \emph on
11856 opt
11857 \emph default
11858
11859 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
11860
11861 \end_inset
11862
11863  and section
11864 \begin_inset LatexCommand \ref{sub:MCS51-variants}
11865
11866 \end_inset
11867
11868 \SpecialChar ~
11869 about MCS51-variants.
11870 \layout Subsection
11871
11872 HC08 Startup Code
11873 \layout Standard
11874
11875 The HC08 startup code follows the same scheme as the MCS51 startup code.
11876 \layout Subsection
11877
11878 Z80 Startup Code
11879 \layout Standard
11880
11881 On the Z80 the startup code is inserted by linking with crt0.o which is generated
11882  from sdcc/device/lib/z80/crt0.s.
11883  If you need a different startup code you can use the compiler option
11884 \emph on
11885 -
11886 \series bold
11887 \emph default
11888
11889 \begin_inset ERT
11890 status Collapsed
11891
11892 \layout Standard
11893
11894 \backslash
11895 /
11896 \end_inset
11897
11898
11899 \series default
11900 \emph on
11901 -no-std-crt0
11902 \emph default
11903
11904 \begin_inset LatexCommand \index{-\/-no-std-crt0}
11905
11906 \end_inset
11907
11908  and provide your own crt0.o.
11909
11910 \layout Section
11911
11912 Inline Assembler Code
11913 \begin_inset LatexCommand \index{Assembler routines}
11914
11915 \end_inset
11916
11917
11918 \layout Subsection
11919
11920 A Step by Step Introduction
11921 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
11922
11923 \end_inset
11924
11925
11926 \layout Standard
11927
11928 Starting from a small snippet of c-code this example shows for the MCS51
11929  how to use inline assembly, access variables, a function parameter and
11930  an array in xdata memory.
11931  The example uses an MCS51 here but is easily adapted for other architectures.
11932  This is a buffer routine which should be optimized:
11933 \layout Verse
11934
11935
11936 \family typewriter
11937 \size footnotesize
11938 unsigned char far
11939 \begin_inset LatexCommand \index{far (storage class)}
11940
11941 \end_inset
11942
11943
11944 \begin_inset LatexCommand \index{\_\_far (storage class)}
11945
11946 \end_inset
11947
11948  at
11949 \begin_inset LatexCommand \index{at}
11950
11951 \end_inset
11952
11953
11954 \begin_inset LatexCommand \index{\_\_at}
11955
11956 \end_inset
11957
11958  0x7f00 buf[0x100];
11959 \begin_inset LatexCommand \index{Aligned array}
11960
11961 \end_inset
11962
11963
11964 \newline
11965 unsigned char head,tail;
11966 \newline
11967
11968 \newline
11969 void to_buffer( unsigned char c )
11970 \newline
11971 {
11972 \newline
11973 \SpecialChar ~
11974 \SpecialChar ~
11975 \SpecialChar ~
11976 \SpecialChar ~
11977 if( head != tail-1 )
11978 \newline
11979 \SpecialChar ~
11980 \SpecialChar ~
11981 \SpecialChar ~
11982 \SpecialChar ~
11983 \SpecialChar ~
11984 \SpecialChar ~
11985 \SpecialChar ~
11986 \SpecialChar ~
11987 buf[ head++ ] = c;\SpecialChar ~
11988 \SpecialChar ~
11989 \SpecialChar ~
11990 \SpecialChar ~
11991 /* access to a 256 byte aligned array */
11992 \newline
11993 }
11994 \layout Standard
11995
11996 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
11997  then a corresponding buffer.asm file is generated.
11998  We define a new function
11999 \family typewriter
12000 to_buffer_asm()
12001 \family default
12002  in file buffer.c in which we cut and paste the generated code, removing
12003  unwanted comments and some ':'.
12004  Then add
12005 \begin_inset Quotes sld
12006 \end_inset
12007
12008 _asm
12009 \begin_inset Quotes srd
12010 \end_inset
12011
12012  and
12013 \begin_inset Quotes sld
12014 \end_inset
12015
12016 _endasm;
12017 \begin_inset Quotes srd
12018 \end_inset
12019
12020  to the beginning and the end of the function body:
12021 \layout Verse
12022
12023
12024 \family typewriter
12025 \size footnotesize
12026 /* With a cut and paste from the .asm file, we have something to start with.
12027 \newline
12028 \SpecialChar ~
12029 \SpecialChar ~
12030 \SpecialChar ~
12031 The function is not yet OK! (registers aren't saved) */
12032 \newline
12033 void to_buffer_asm( unsigned char c )
12034 \newline
12035 {
12036 \newline
12037 \SpecialChar ~
12038 \SpecialChar ~
12039 \SpecialChar ~
12040 \SpecialChar ~
12041 _asm
12042 \begin_inset LatexCommand \index{\_asm}
12043
12044 \end_inset
12045
12046
12047 \begin_inset LatexCommand \index{\_\_asm}
12048
12049 \end_inset
12050
12051
12052 \newline
12053 \SpecialChar ~
12054 \SpecialChar ~
12055 \SpecialChar ~
12056 \SpecialChar ~
12057 mov\SpecialChar ~
12058 \SpecialChar ~
12059 r2,dpl
12060 \newline
12061 ;buffer.c if( head != tail-1 )
12062 \newline
12063 \SpecialChar ~
12064 \SpecialChar ~
12065 \SpecialChar ~
12066 \SpecialChar ~
12067 mov\SpecialChar ~
12068 \SpecialChar ~
12069 a,_tail
12070 \newline
12071 \SpecialChar ~
12072 \SpecialChar ~
12073 \SpecialChar ~
12074 \SpecialChar ~
12075 dec\SpecialChar ~
12076 \SpecialChar ~
12077 a
12078 \newline
12079 \SpecialChar ~
12080 \SpecialChar ~
12081 \SpecialChar ~
12082 \SpecialChar ~
12083 mov\SpecialChar ~
12084 \SpecialChar ~
12085 r3,a
12086 \newline
12087 \SpecialChar ~
12088 \SpecialChar ~
12089 \SpecialChar ~
12090 \SpecialChar ~
12091 mov\SpecialChar ~
12092 \SpecialChar ~
12093 a,_head
12094 \newline
12095 \SpecialChar ~
12096 \SpecialChar ~
12097 \SpecialChar ~
12098 \SpecialChar ~
12099 cjne a,ar3,00106$
12100 \newline
12101 \SpecialChar ~
12102 \SpecialChar ~
12103 \SpecialChar ~
12104 \SpecialChar ~
12105 ret
12106 \newline
12107 00106$:
12108 \newline
12109 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
12110 \begin_inset LatexCommand \index{Aligned array}
12111
12112 \end_inset
12113
12114
12115 \newline
12116 \SpecialChar ~
12117 \SpecialChar ~
12118 \SpecialChar ~
12119 \SpecialChar ~
12120 mov\SpecialChar ~
12121 \SpecialChar ~
12122 r3,_head
12123 \newline
12124 \SpecialChar ~
12125 \SpecialChar ~
12126 \SpecialChar ~
12127 \SpecialChar ~
12128 inc\SpecialChar ~
12129 \SpecialChar ~
12130 _head
12131 \newline
12132 \SpecialChar ~
12133 \SpecialChar ~
12134 \SpecialChar ~
12135 \SpecialChar ~
12136 mov\SpecialChar ~
12137 \SpecialChar ~
12138 dpl,r3
12139 \newline
12140 \SpecialChar ~
12141 \SpecialChar ~
12142 \SpecialChar ~
12143 \SpecialChar ~
12144 mov\SpecialChar ~
12145 \SpecialChar ~
12146 dph,#(_buf >> 8)
12147 \newline
12148 \SpecialChar ~
12149 \SpecialChar ~
12150 \SpecialChar ~
12151 \SpecialChar ~
12152 mov\SpecialChar ~
12153 \SpecialChar ~
12154 a,r2
12155 \newline
12156 \SpecialChar ~
12157 \SpecialChar ~
12158 \SpecialChar ~
12159 \SpecialChar ~
12160 movx @dptr,a
12161 \newline
12162 00103$:
12163 \newline
12164 \SpecialChar ~
12165 \SpecialChar ~
12166 \SpecialChar ~
12167 \SpecialChar ~
12168 ret
12169 \newline
12170 \SpecialChar ~
12171 \SpecialChar ~
12172 \SpecialChar ~
12173 \SpecialChar ~
12174 _endasm
12175 \begin_inset LatexCommand \index{\_endasm}
12176
12177 \end_inset
12178
12179
12180 \begin_inset LatexCommand \index{\_\_endasm}
12181
12182 \end_inset
12183
12184 ;
12185 \newline
12186 }
12187 \layout Standard
12188
12189 The new file buffer.c should compile with only one warning about the unreferenced
12190  function argument 'c'.
12191  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
12192  (1) and finally have:
12193 \layout Verse
12194
12195
12196 \family typewriter
12197 \size footnotesize
12198 unsigned char far at 0x7f00 buf[0x100];
12199 \newline
12200 unsigned char head,tail;
12201 \newline
12202 #define USE_ASSEMBLY (1)
12203 \newline
12204
12205 \newline
12206 #if !USE_ASSEMBLY
12207 \newline
12208
12209 \newline
12210 void to_buffer( unsigned char c )
12211 \newline
12212 {
12213 \newline
12214 \SpecialChar ~
12215 \SpecialChar ~
12216 \SpecialChar ~
12217 \SpecialChar ~
12218 if( head != tail-1 )
12219 \newline
12220 \SpecialChar ~
12221 \SpecialChar ~
12222 \SpecialChar ~
12223 \SpecialChar ~
12224 \SpecialChar ~
12225 \SpecialChar ~
12226 \SpecialChar ~
12227 \SpecialChar ~
12228 buf[ head++ ] = c;
12229 \newline
12230 }
12231 \newline
12232
12233 \newline
12234 #else
12235 \newline
12236
12237 \newline
12238 void to_buffer( unsigned char c )
12239 \newline
12240 {
12241 \newline
12242 \SpecialChar ~
12243 \SpecialChar ~
12244 \SpecialChar ~
12245 \SpecialChar ~
12246 c; // to avoid warning: unreferenced function argument
12247 \newline
12248 \SpecialChar ~
12249 \SpecialChar ~
12250 \SpecialChar ~
12251 \SpecialChar ~
12252 _asm
12253 \begin_inset LatexCommand \index{\_asm}
12254
12255 \end_inset
12256
12257
12258 \begin_inset LatexCommand \index{\_\_asm}
12259
12260 \end_inset
12261
12262
12263 \newline
12264 \SpecialChar ~
12265 \SpecialChar ~
12266 \SpecialChar ~
12267 \SpecialChar ~
12268 \SpecialChar ~
12269 \SpecialChar ~
12270 \SpecialChar ~
12271 \SpecialChar ~
12272 ; save used registers here.
12273
12274 \newline
12275 \SpecialChar ~
12276 \SpecialChar ~
12277 \SpecialChar ~
12278 \SpecialChar ~
12279 \SpecialChar ~
12280 \SpecialChar ~
12281 \SpecialChar ~
12282 \SpecialChar ~
12283 ; If we were still using r2,r3 we would have to push them here.
12284
12285 \newline
12286 ; if( head != tail-1 )
12287 \newline
12288 \SpecialChar ~
12289 \SpecialChar ~
12290 \SpecialChar ~
12291 \SpecialChar ~
12292 \SpecialChar ~
12293 \SpecialChar ~
12294 \SpecialChar ~
12295 \SpecialChar ~
12296 mov\SpecialChar ~
12297  a,_tail
12298 \newline
12299 \SpecialChar ~
12300 \SpecialChar ~
12301 \SpecialChar ~
12302 \SpecialChar ~
12303 \SpecialChar ~
12304 \SpecialChar ~
12305 \SpecialChar ~
12306 \SpecialChar ~
12307 dec\SpecialChar ~
12308  a
12309 \newline
12310 \SpecialChar ~
12311 \SpecialChar ~
12312 \SpecialChar ~
12313 \SpecialChar ~
12314 \SpecialChar ~
12315 \SpecialChar ~
12316 \SpecialChar ~
12317 \SpecialChar ~
12318 xrl\SpecialChar ~
12319  a,_head
12320 \newline
12321 \SpecialChar ~
12322 \SpecialChar ~
12323 \SpecialChar ~
12324 \SpecialChar ~
12325 \SpecialChar ~
12326 \SpecialChar ~
12327 \SpecialChar ~
12328 \SpecialChar ~
12329 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
12330 \newline
12331 \SpecialChar ~
12332 \SpecialChar ~
12333 \SpecialChar ~
12334 \SpecialChar ~
12335 \SpecialChar ~
12336 \SpecialChar ~
12337 \SpecialChar ~
12338 \SpecialChar ~
12339 jz\SpecialChar ~
12340 \SpecialChar ~
12341  t_b_end$
12342 \newline
12343 \SpecialChar ~
12344 \SpecialChar ~
12345 \SpecialChar ~
12346 \SpecialChar ~
12347 \SpecialChar ~
12348 \SpecialChar ~
12349 \SpecialChar ~
12350 \SpecialChar ~
12351 ;
12352 \newline
12353 ; buf[ head++ ] = c;
12354 \newline
12355 \SpecialChar ~
12356 \SpecialChar ~
12357 \SpecialChar ~
12358 \SpecialChar ~
12359 \SpecialChar ~
12360 \SpecialChar ~
12361 \SpecialChar ~
12362 \SpecialChar ~
12363 mov\SpecialChar ~
12364  a,dpl \SpecialChar ~
12365 \SpecialChar ~
12366 \SpecialChar ~
12367 \SpecialChar ~
12368 \SpecialChar ~
12369 \SpecialChar ~
12370 \SpecialChar ~
12371 ; dpl holds lower byte of function argument
12372 \newline
12373 \SpecialChar ~
12374 \SpecialChar ~
12375 \SpecialChar ~
12376 \SpecialChar ~
12377 \SpecialChar ~
12378 \SpecialChar ~
12379 \SpecialChar ~
12380 \SpecialChar ~
12381 mov\SpecialChar ~
12382  dpl,_head \SpecialChar ~
12383 \SpecialChar ~
12384 \SpecialChar ~
12385 ; buf is 0x100 byte aligned so head can be used directly
12386 \newline
12387 \SpecialChar ~
12388 \SpecialChar ~
12389 \SpecialChar ~
12390 \SpecialChar ~
12391 \SpecialChar ~
12392 \SpecialChar ~
12393 \SpecialChar ~
12394 \SpecialChar ~
12395 mov\SpecialChar ~
12396  dph,#(_buf>>8)
12397 \newline
12398 \SpecialChar ~
12399 \SpecialChar ~
12400 \SpecialChar ~
12401 \SpecialChar ~
12402 \SpecialChar ~
12403 \SpecialChar ~
12404 \SpecialChar ~
12405 \SpecialChar ~
12406 movx @dptr,a
12407 \newline
12408 \SpecialChar ~
12409 \SpecialChar ~
12410 \SpecialChar ~
12411 \SpecialChar ~
12412 \SpecialChar ~
12413 \SpecialChar ~
12414 \SpecialChar ~
12415 \SpecialChar ~
12416 inc \SpecialChar ~
12417 _head
12418 \newline
12419 \SpecialChar ~
12420 \SpecialChar ~
12421 \SpecialChar ~
12422 \SpecialChar ~
12423 \SpecialChar ~
12424 \SpecialChar ~
12425 \SpecialChar ~
12426 \SpecialChar ~
12427 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
12428 \newline
12429 t_b_end$:
12430 \newline
12431 \SpecialChar ~
12432 \SpecialChar ~
12433 \SpecialChar ~
12434 \SpecialChar ~
12435 \SpecialChar ~
12436 \SpecialChar ~
12437 \SpecialChar ~
12438 \SpecialChar ~
12439 ; restore used registers here
12440 \newline
12441 \SpecialChar ~
12442 \SpecialChar ~
12443 \SpecialChar ~
12444 \SpecialChar ~
12445 _endasm
12446 \begin_inset LatexCommand \index{\_endasm}
12447
12448 \end_inset
12449
12450
12451 \begin_inset LatexCommand \index{\_\_endasm}
12452
12453 \end_inset
12454
12455 ;
12456 \newline
12457 }
12458 \newline
12459 #endif
12460 \layout Standard
12461
12462 The inline assembler code can contain any valid code understood by the assembler
12463 , this includes any assembler directives and comment lines
12464 \begin_inset Foot
12465 collapsed false
12466
12467 \layout Standard
12468
12469 The assembler does not like some characters like ':' or ''' in comments.
12470  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
12471 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
12472
12473 \end_inset
12474
12475
12476 \begin_inset LatexCommand \index{Assembler documentation}
12477
12478 \end_inset
12479
12480
12481 \end_inset
12482
12483 .
12484  The compiler does not do any validation of the code within the
12485 \family typewriter
12486 _asm
12487 \begin_inset LatexCommand \index{\_asm}
12488
12489 \end_inset
12490
12491
12492 \begin_inset LatexCommand \index{\_\_asm}
12493
12494 \end_inset
12495
12496  ...
12497  _endasm
12498 \size footnotesize
12499
12500 \begin_inset LatexCommand \index{\_endasm}
12501
12502 \end_inset
12503
12504
12505 \begin_inset LatexCommand \index{\_\_endasm}
12506
12507 \end_inset
12508
12509
12510 \size default
12511 ;
12512 \family default
12513  keyword pair.
12514  Specifically it will not know which registers are used and thus register
12515  pushing/popping
12516 \begin_inset LatexCommand \index{push/pop}
12517
12518 \end_inset
12519
12520  has to be done manually.
12521
12522 \layout Standard
12523
12524 It is recommended that each assembly instruction (including labels) be placed
12525  in a separate line (as the example shows).
12526  When the -
12527 \begin_inset ERT
12528 status Collapsed
12529
12530 \layout Standard
12531
12532 \backslash
12533 /
12534 \end_inset
12535
12536 -
12537 \emph on
12538 peep-asm
12539 \begin_inset LatexCommand \index{-\/-peep-asm}
12540
12541 \end_inset
12542
12543
12544 \emph default
12545  command line option is used, the inline assembler code will be passed through
12546  the peephole optimizer
12547 \begin_inset LatexCommand \index{Peephole optimizer}
12548
12549 \end_inset
12550
12551 .
12552  There are only a few (if any) cases where this option makes sense, it might
12553  cause some unexpected changes in the inline assembler code.
12554  Please go through the peephole optimizer rules defined in file
12555 \emph on
12556 SDCCpeeph.def
12557 \emph default
12558  before using this option.
12559 \layout Subsection
12560
12561 Naked Functions
12562 \begin_inset LatexCommand \label{sub:Naked-Functions}
12563
12564 \end_inset
12565
12566
12567 \begin_inset LatexCommand \index{Naked functions}
12568
12569 \end_inset
12570
12571
12572 \layout Standard
12573
12574 A special keyword may be associated with a function declaring it as
12575 \emph on
12576 _naked
12577 \begin_inset LatexCommand \index{\_naked}
12578
12579 \end_inset
12580
12581
12582 \begin_inset LatexCommand \index{\_\_naked}
12583
12584 \end_inset
12585
12586 .
12587
12588 \emph default
12589 The
12590 \emph on
12591 _naked
12592 \emph default
12593  function modifier attribute prevents the compiler from generating prologue
12594 \begin_inset LatexCommand \index{function prologue}
12595
12596 \end_inset
12597
12598  and epilogue
12599 \begin_inset LatexCommand \index{function epilogue}
12600
12601 \end_inset
12602
12603  code for that function.
12604  This means that the user is entirely responsible for such things as saving
12605  any registers that may need to be preserved, selecting the proper register
12606  bank, generating the
12607 \emph on
12608 return
12609 \emph default
12610  instruction at the end, etc.
12611  Practically, this means that the contents of the function must be written
12612  in inline assembler.
12613  This is particularly useful for interrupt functions, which can have a large
12614  (and often unnecessary) prologue/epilogue.
12615  For example, compare the code generated by these two functions:
12616 \layout Verse
12617
12618
12619 \family typewriter
12620 volatile
12621 \begin_inset LatexCommand \index{volatile}
12622
12623 \end_inset
12624
12625  data unsigned char counter;
12626 \newline
12627
12628 \newline
12629 void simpleInterrupt(void) interrupt
12630 \begin_inset LatexCommand \index{interrupt}
12631
12632 \end_inset
12633
12634
12635 \begin_inset LatexCommand \index{\_\_interrupt}
12636
12637 \end_inset
12638
12639  1
12640 \newline
12641 {
12642 \newline
12643 \SpecialChar ~
12644 \SpecialChar ~
12645 \SpecialChar ~
12646 \SpecialChar ~
12647 counter++;
12648 \newline
12649 }
12650 \newline
12651
12652 \newline
12653 void nakedInterrupt(void) interrupt 2 _naked
12654 \newline
12655 {
12656 \newline
12657 \SpecialChar ~
12658 \SpecialChar ~
12659 \SpecialChar ~
12660 \SpecialChar ~
12661 _asm
12662 \begin_inset LatexCommand \index{\_asm}
12663
12664 \end_inset
12665
12666
12667 \begin_inset LatexCommand \index{\_\_asm}
12668
12669 \end_inset
12670
12671
12672 \newline
12673 \SpecialChar ~
12674 \SpecialChar ~
12675 \SpecialChar ~
12676 \SpecialChar ~
12677 \SpecialChar ~
12678 \SpecialChar ~
12679 inc\SpecialChar ~
12680 \SpecialChar ~
12681 \SpecialChar ~
12682 \SpecialChar ~
12683 \SpecialChar ~
12684 _counter ; does not change flags, no need to save psw
12685 \newline
12686 \SpecialChar ~
12687 \SpecialChar ~
12688 \SpecialChar ~
12689 \SpecialChar ~
12690 \SpecialChar ~
12691 \SpecialChar ~
12692 reti\SpecialChar ~
12693 \SpecialChar ~
12694 \SpecialChar ~
12695 \SpecialChar ~
12696 ; MUST explicitly include ret or reti in _naked function.
12697 \newline
12698 \SpecialChar ~
12699 \SpecialChar ~
12700 \SpecialChar ~
12701 \SpecialChar ~
12702 _endasm
12703 \begin_inset LatexCommand \index{\_endasm}
12704
12705 \end_inset
12706
12707
12708 \begin_inset LatexCommand \index{\_\_endasm}
12709
12710 \end_inset
12711
12712 ;
12713 \newline
12714 }
12715 \layout Standard
12716
12717 For an 8051 target, the generated simpleInterrupt looks like:
12718 \layout Verse
12719
12720
12721 \family typewriter
12722 _simpleInterrupt:
12723 \newline
12724 \SpecialChar ~
12725 \SpecialChar ~
12726 \SpecialChar ~
12727 \SpecialChar ~
12728 push\SpecialChar ~
12729 \SpecialChar ~
12730 \SpecialChar ~
12731 \SpecialChar ~
12732 acc
12733 \newline
12734 \SpecialChar ~
12735 \SpecialChar ~
12736 \SpecialChar ~
12737 \SpecialChar ~
12738 push\SpecialChar ~
12739 \SpecialChar ~
12740 \SpecialChar ~
12741 \SpecialChar ~
12742 b
12743 \newline
12744 \SpecialChar ~
12745 \SpecialChar ~
12746 \SpecialChar ~
12747 \SpecialChar ~
12748 push\SpecialChar ~
12749 \SpecialChar ~
12750 \SpecialChar ~
12751 \SpecialChar ~
12752 dpl
12753 \newline
12754 \SpecialChar ~
12755 \SpecialChar ~
12756 \SpecialChar ~
12757 \SpecialChar ~
12758 push\SpecialChar ~
12759 \SpecialChar ~
12760 \SpecialChar ~
12761 \SpecialChar ~
12762 dph
12763 \newline
12764 \SpecialChar ~
12765 \SpecialChar ~
12766 \SpecialChar ~
12767 \SpecialChar ~
12768 push\SpecialChar ~
12769 \SpecialChar ~
12770 \SpecialChar ~
12771 \SpecialChar ~
12772 psw
12773 \newline
12774 \SpecialChar ~
12775 \SpecialChar ~
12776 \SpecialChar ~
12777 \SpecialChar ~
12778 mov\SpecialChar ~
12779 \SpecialChar ~
12780 \SpecialChar ~
12781 \SpecialChar ~
12782 \SpecialChar ~
12783 psw,#0x00
12784 \newline
12785 \SpecialChar ~
12786 \SpecialChar ~
12787 \SpecialChar ~
12788 \SpecialChar ~
12789 inc\SpecialChar ~
12790 \SpecialChar ~
12791 \SpecialChar ~
12792 \SpecialChar ~
12793 \SpecialChar ~
12794 _counter
12795 \newline
12796 \SpecialChar ~
12797 \SpecialChar ~
12798 \SpecialChar ~
12799 \SpecialChar ~
12800 pop\SpecialChar ~
12801 \SpecialChar ~
12802 \SpecialChar ~
12803 \SpecialChar ~
12804 \SpecialChar ~
12805 psw
12806 \newline
12807 \SpecialChar ~
12808 \SpecialChar ~
12809 \SpecialChar ~
12810 \SpecialChar ~
12811 pop\SpecialChar ~
12812 \SpecialChar ~
12813 \SpecialChar ~
12814 \SpecialChar ~
12815 \SpecialChar ~
12816 dph
12817 \newline
12818 \SpecialChar ~
12819 \SpecialChar ~
12820 \SpecialChar ~
12821 \SpecialChar ~
12822 pop\SpecialChar ~
12823 \SpecialChar ~
12824 \SpecialChar ~
12825 \SpecialChar ~
12826 \SpecialChar ~
12827 dpl
12828 \newline
12829 \SpecialChar ~
12830 \SpecialChar ~
12831 \SpecialChar ~
12832 \SpecialChar ~
12833 pop\SpecialChar ~
12834 \SpecialChar ~
12835 \SpecialChar ~
12836 \SpecialChar ~
12837 \SpecialChar ~
12838 b
12839 \newline
12840 \SpecialChar ~
12841 \SpecialChar ~
12842 \SpecialChar ~
12843 \SpecialChar ~
12844 pop\SpecialChar ~
12845 \SpecialChar ~
12846 \SpecialChar ~
12847 \SpecialChar ~
12848 \SpecialChar ~
12849 acc
12850 \newline
12851 \SpecialChar ~
12852 \SpecialChar ~
12853 \SpecialChar ~
12854 \SpecialChar ~
12855 reti
12856 \layout Standard
12857
12858 whereas nakedInterrupt looks like:
12859 \layout Verse
12860
12861
12862 \family typewriter
12863 _nakedInterrupt:
12864 \newline
12865 \SpecialChar ~
12866 \SpecialChar ~
12867 \SpecialChar ~
12868 \SpecialChar ~
12869 inc\SpecialChar ~
12870 \SpecialChar ~
12871 \SpecialChar ~
12872 \SpecialChar ~
12873 _counter ; does not change flags, no need to save psw
12874 \newline
12875 \SpecialChar ~
12876 \SpecialChar ~
12877 \SpecialChar ~
12878 \SpecialChar ~
12879 reti\SpecialChar ~
12880 \SpecialChar ~
12881 \SpecialChar ~
12882 \SpecialChar ~
12883 \SpecialChar ~
12884 \SpecialChar ~
12885 \SpecialChar ~
12886 \SpecialChar ~
12887 \SpecialChar ~
12888 \SpecialChar ~
12889 \SpecialChar ~
12890 \SpecialChar ~
12891 ; MUST explicitly include ret or reti in _naked function
12892 \layout Standard
12893
12894 The related directive #pragma exclude
12895 \begin_inset LatexCommand \index{\#pragma exclude}
12896
12897 \end_inset
12898
12899  allows a more fine grained control over pushing & popping
12900 \begin_inset LatexCommand \index{push/pop}
12901
12902 \end_inset
12903
12904  the registers.
12905 \layout Standard
12906
12907 While there is nothing preventing you from writing C code inside a
12908 \family typewriter
12909 _naked
12910 \family default
12911  function, there are many ways to shoot yourself in the foot doing this,
12912  and it is recommended that you stick to inline assembler.
12913 \layout Subsection
12914
12915 Use of Labels within Inline Assembler
12916 \layout Standard
12917
12918 SDCC allows the use of in-line assembler with a few restrictions regarding
12919  labels.
12920  In older versions of the compiler all labels defined within inline assembler
12921  code
12922 \emph on
12923 had to be
12924 \emph default
12925  of the form
12926 \emph on
12927 nnnnn$
12928 \emph default
12929  where nnnn is a number less than 100 (which implies a limit of utmost 100
12930  inline assembler labels
12931 \emph on
12932 per function
12933 \emph default
12934 \noun on
12935 )
12936 \noun default
12937 .
12938
12939 \layout Verse
12940
12941
12942 \family typewriter
12943 _asm
12944 \begin_inset LatexCommand \index{\_asm}
12945
12946 \end_inset
12947
12948
12949 \begin_inset LatexCommand \index{\_\_asm}
12950
12951 \end_inset
12952
12953
12954 \newline
12955 \SpecialChar ~
12956 \SpecialChar ~
12957 \SpecialChar ~
12958 \SpecialChar ~
12959 mov\SpecialChar ~
12960 \SpecialChar ~
12961 \SpecialChar ~
12962 \SpecialChar ~
12963 \SpecialChar ~
12964 b,#10
12965 \newline
12966 00001$:
12967 \newline
12968 \SpecialChar ~
12969 \SpecialChar ~
12970 \SpecialChar ~
12971 \SpecialChar ~
12972 djnz\SpecialChar ~
12973 \SpecialChar ~
12974 \SpecialChar ~
12975 \SpecialChar ~
12976 b,00001$
12977 \newline
12978 _endasm
12979 \begin_inset LatexCommand \index{\_endasm}
12980
12981 \end_inset
12982
12983
12984 \begin_inset LatexCommand \index{\_\_endasm}
12985
12986 \end_inset
12987
12988  ;
12989 \layout Standard
12990
12991 Inline assembler code cannot reference any C-Labels, however it can reference
12992  labels
12993 \begin_inset LatexCommand \index{Labels}
12994
12995 \end_inset
12996
12997  defined by the inline assembler, e.g.:
12998 \layout Verse
12999
13000
13001 \family typewriter
13002 foo() {
13003 \newline
13004 \SpecialChar ~
13005 \SpecialChar ~
13006 \SpecialChar ~
13007 \SpecialChar ~
13008 /* some c code */
13009 \newline
13010 \SpecialChar ~
13011 \SpecialChar ~
13012 \SpecialChar ~
13013 \SpecialChar ~
13014 _asm
13015 \newline
13016 \SpecialChar ~
13017 \SpecialChar ~
13018 \SpecialChar ~
13019 \SpecialChar ~
13020 \SpecialChar ~
13021 \SpecialChar ~
13022 ; some assembler code
13023 \newline
13024 \SpecialChar ~
13025 \SpecialChar ~
13026 \SpecialChar ~
13027 \SpecialChar ~
13028 \SpecialChar ~
13029 \SpecialChar ~
13030 ljmp $0003
13031 \newline
13032 \SpecialChar ~
13033 \SpecialChar ~
13034 \SpecialChar ~
13035 \SpecialChar ~
13036 _endasm;
13037 \newline
13038 \SpecialChar ~
13039 \SpecialChar ~
13040 \SpecialChar ~
13041 \SpecialChar ~
13042 /* some more c code */
13043 \newline
13044 clabel:\SpecialChar ~
13045 \SpecialChar ~
13046 /* inline assembler cannot reference this label */
13047 \newline
13048 \SpecialChar ~
13049 \SpecialChar ~
13050 \SpecialChar ~
13051 \SpecialChar ~
13052 _asm
13053 \newline
13054 \SpecialChar ~
13055 \SpecialChar ~
13056 \SpecialChar ~
13057 \SpecialChar ~
13058 $0003: ;label (can be referenced by inline assembler only)
13059 \newline
13060 \SpecialChar ~
13061 \SpecialChar ~
13062 \SpecialChar ~
13063 \SpecialChar ~
13064 _endasm
13065 \begin_inset LatexCommand \index{\_endasm}
13066
13067 \end_inset
13068
13069
13070 \begin_inset LatexCommand \index{\_\_endasm}
13071
13072 \end_inset
13073
13074  ;
13075 \newline
13076 \SpecialChar ~
13077 \SpecialChar ~
13078 \SpecialChar ~
13079 \SpecialChar ~
13080 /* some more c code */
13081 \newline
13082 }
13083 \layout Standard
13084
13085 In other words inline assembly code can access labels defined in inline
13086  assembly within the scope of the function.
13087  The same goes the other way, i.e.
13088  labels defines in inline assembly can not be accessed by C statements.
13089 \layout Section
13090
13091 Interfacing with Assembler Code
13092 \begin_inset LatexCommand \index{Assembler routines}
13093
13094 \end_inset
13095
13096
13097 \layout Subsection
13098
13099 Global Registers used for Parameter Passing
13100 \begin_inset LatexCommand \index{Parameter passing}
13101
13102 \end_inset
13103
13104
13105 \layout Standard
13106
13107 The compiler always uses the global registers
13108 \emph on
13109 DPL, DPH
13110 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
13111
13112 \end_inset
13113
13114
13115 \begin_inset LatexCommand \index{DPTR}
13116
13117 \end_inset
13118
13119 , B
13120 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
13121
13122 \end_inset
13123
13124
13125 \emph default
13126 and
13127 \emph on
13128  ACC
13129 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
13130
13131 \end_inset
13132
13133
13134 \emph default
13135  to pass the first parameter to a routine.
13136  The second parameter onwards is either allocated on the stack (for reentrant
13137  routines or if -
13138 \begin_inset ERT
13139 status Collapsed
13140
13141 \layout Standard
13142
13143 \backslash
13144 /
13145 \end_inset
13146
13147 -stack-auto is used) or in data / xdata memory (depending on the memory
13148  model).
13149
13150 \layout Subsection
13151
13152 Assembler Routine (non-reentrant)
13153 \layout Standard
13154
13155 In the following example
13156 \begin_inset LatexCommand \index{reentrant}
13157
13158 \end_inset
13159
13160
13161 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
13162
13163 \end_inset
13164
13165  the function c_func calls an assembler routine asm_func, which takes two
13166  parameters
13167 \begin_inset LatexCommand \index{function parameter}
13168
13169 \end_inset
13170
13171 .
13172 \layout Verse
13173
13174
13175 \family typewriter
13176 extern int asm_func(unsigned char, unsigned char);
13177 \newline
13178
13179 \newline
13180 int c_func (unsigned char i, unsigned char j)
13181 \newline
13182 {
13183 \newline
13184 \SpecialChar ~
13185 \SpecialChar ~
13186 \SpecialChar ~
13187 \SpecialChar ~
13188 return asm_func(i,j);
13189 \newline
13190 }
13191 \newline
13192
13193 \newline
13194 int main()
13195 \newline
13196 {
13197 \newline
13198 \SpecialChar ~
13199 \SpecialChar ~
13200 \SpecialChar ~
13201 \SpecialChar ~
13202 return c_func(10,9);
13203 \newline
13204 }
13205 \layout Standard
13206
13207 The corresponding assembler function is:
13208 \layout Verse
13209
13210
13211 \family typewriter
13212 .globl _asm_func_PARM_2
13213 \newline
13214 \SpecialChar ~
13215 \SpecialChar ~
13216 \SpecialChar ~
13217 \SpecialChar ~
13218 \SpecialChar ~
13219 \SpecialChar ~
13220 \SpecialChar ~
13221 \SpecialChar ~
13222 .globl _asm_func
13223 \newline
13224 \SpecialChar ~
13225 \SpecialChar ~
13226 \SpecialChar ~
13227 \SpecialChar ~
13228 \SpecialChar ~
13229 \SpecialChar ~
13230 \SpecialChar ~
13231 \SpecialChar ~
13232 .area OSEG
13233 \newline
13234 _asm_func_PARM_2:
13235 \newline
13236 \SpecialChar ~
13237 \SpecialChar ~
13238 \SpecialChar ~
13239 \SpecialChar ~
13240 \SpecialChar ~
13241 \SpecialChar ~
13242 \SpecialChar ~
13243 \SpecialChar ~
13244 .ds    1
13245 \newline
13246 \SpecialChar ~
13247 \SpecialChar ~
13248 \SpecialChar ~
13249 \SpecialChar ~
13250 \SpecialChar ~
13251 \SpecialChar ~
13252 \SpecialChar ~
13253 \SpecialChar ~
13254 .area CSEG
13255 \newline
13256 _asm_func:
13257 \newline
13258 \SpecialChar ~
13259 \SpecialChar ~
13260 \SpecialChar ~
13261 \SpecialChar ~
13262 \SpecialChar ~
13263 \SpecialChar ~
13264 \SpecialChar ~
13265 \SpecialChar ~
13266 mov\SpecialChar ~
13267 \SpecialChar ~
13268 \SpecialChar ~
13269 \SpecialChar ~
13270 a,dpl
13271 \newline
13272 \SpecialChar ~
13273 \SpecialChar ~
13274 \SpecialChar ~
13275 \SpecialChar ~
13276 \SpecialChar ~
13277 \SpecialChar ~
13278 \SpecialChar ~
13279 \SpecialChar ~
13280 add\SpecialChar ~
13281 \SpecialChar ~
13282 \SpecialChar ~
13283 \SpecialChar ~
13284 a,_asm_func_PARM_2
13285 \newline
13286 \SpecialChar ~
13287 \SpecialChar ~
13288 \SpecialChar ~
13289 \SpecialChar ~
13290 \SpecialChar ~
13291 \SpecialChar ~
13292 \SpecialChar ~
13293 \SpecialChar ~
13294 mov\SpecialChar ~
13295 \SpecialChar ~
13296 \SpecialChar ~
13297 \SpecialChar ~
13298 dpl,a
13299 \newline
13300 \SpecialChar ~
13301 \SpecialChar ~
13302 \SpecialChar ~
13303 \SpecialChar ~
13304 \SpecialChar ~
13305 \SpecialChar ~
13306 \SpecialChar ~
13307 \SpecialChar ~
13308 mov\SpecialChar ~
13309 \SpecialChar ~
13310 \SpecialChar ~
13311 \SpecialChar ~
13312 dph
13313 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
13314
13315 \end_inset
13316
13317 ,#0x00
13318 \newline
13319 \SpecialChar ~
13320 \SpecialChar ~
13321 \SpecialChar ~
13322 \SpecialChar ~
13323 \SpecialChar ~
13324 \SpecialChar ~
13325 \SpecialChar ~
13326 \SpecialChar ~
13327 ret
13328 \layout Standard
13329
13330 Note here that the return values
13331 \begin_inset LatexCommand \index{return value}
13332
13333 \end_inset
13334
13335  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
13336  two byte values.
13337  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
13338 b' & 'acc' for four byte values.
13339 \layout Standard
13340
13341 The parameter naming convention is _<function_name>_PARM_<n>, where n is
13342  the parameter number starting from 1, and counting from the left.
13343  The first parameter is passed in
13344 \begin_inset Quotes eld
13345 \end_inset
13346
13347 dpl
13348 \begin_inset Quotes erd
13349 \end_inset
13350
13351  for a one byte parameter,
13352 \begin_inset Quotes eld
13353 \end_inset
13354
13355 dptr
13356 \begin_inset Quotes erd
13357 \end_inset
13358
13359  for two bytes,
13360 \begin_inset Quotes eld
13361 \end_inset
13362
13363 b,dptr
13364 \begin_inset Quotes erd
13365 \end_inset
13366
13367  for three bytes and
13368 \begin_inset Quotes eld
13369 \end_inset
13370
13371 acc,b,dptr
13372 \begin_inset Quotes erd
13373 \end_inset
13374
13375  for a four bytes parameter.
13376  The variable name for the second parameter will be _<function_name>_PARM_2.
13377 \newline
13378
13379 \newline
13380 Assemble the assembler routine with the following command:
13381 \newline
13382
13383 \newline
13384
13385 \family sans
13386 \series bold
13387 asx8051 -losg asmfunc.asm
13388 \newline
13389
13390 \newline
13391
13392 \family default
13393 \series default
13394 Then compile and link the assembler routine to the C source file with the
13395  following command:
13396 \newline
13397
13398 \newline
13399
13400 \family sans
13401 \series bold
13402 sdcc cfunc.c asmfunc.rel
13403 \layout Subsection
13404
13405 Assembler Routine (reentrant)
13406 \layout Standard
13407
13408 In this case
13409 \begin_inset LatexCommand \index{reentrant}
13410
13411 \end_inset
13412
13413
13414 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
13415
13416 \end_inset
13417
13418  the second parameter
13419 \begin_inset LatexCommand \index{function parameter}
13420
13421 \end_inset
13422
13423  onwards will be passed on the stack, the parameters are pushed from right
13424  to left i.e.
13425  after the call the leftmost parameter will be on the top of the stack.
13426  Here is an example:
13427 \layout Verse
13428
13429
13430 \family typewriter
13431 extern int asm_func(unsigned char, unsigned char);
13432 \newline
13433
13434 \newline
13435 int c_func (unsigned char i, unsigned char j) reentrant
13436 \newline
13437 {
13438 \newline
13439 \SpecialChar ~
13440 \SpecialChar ~
13441 \SpecialChar ~
13442 \SpecialChar ~
13443 return asm_func(i,j);
13444 \newline
13445 }
13446 \newline
13447
13448 \newline
13449 int main()
13450 \newline
13451 {
13452 \newline
13453 \SpecialChar ~
13454 \SpecialChar ~
13455 \SpecialChar ~
13456 \SpecialChar ~
13457 return c_func(10,9);
13458 \newline
13459 }
13460 \layout Standard
13461
13462 The corresponding assembler routine is:
13463 \layout Verse
13464
13465
13466 \family typewriter
13467 .globl _asm_func
13468 \newline
13469 _asm_func:
13470 \newline
13471 \SpecialChar ~
13472 \SpecialChar ~
13473 \SpecialChar ~
13474 \SpecialChar ~
13475 push  _bp
13476 \newline
13477 \SpecialChar ~
13478 \SpecialChar ~
13479 \SpecialChar ~
13480 \SpecialChar ~
13481 mov _bp,sp
13482 \newline
13483 \SpecialChar ~
13484 \SpecialChar ~
13485 \SpecialChar ~
13486 \SpecialChar ~
13487 mov r2,dpl
13488 \newline
13489 \SpecialChar ~
13490 \SpecialChar ~
13491 \SpecialChar ~
13492 \SpecialChar ~
13493 mov a,_bp
13494 \newline
13495 \SpecialChar ~
13496 \SpecialChar ~
13497 \SpecialChar ~
13498 \SpecialChar ~
13499 add a,#0xfd
13500 \newline
13501 \SpecialChar ~
13502 \SpecialChar ~
13503 \SpecialChar ~
13504 \SpecialChar ~
13505 mov r0,a
13506 \newline
13507 \SpecialChar ~
13508 \SpecialChar ~
13509 \SpecialChar ~
13510 \SpecialChar ~
13511 add  a,#0xfc ;?
13512 \newline
13513 \SpecialChar ~
13514 \SpecialChar ~
13515 \SpecialChar ~
13516 \SpecialChar ~
13517 mov  r1,a
13518 \newline
13519 \SpecialChar ~
13520 \SpecialChar ~
13521 \SpecialChar ~
13522 \SpecialChar ~
13523 mov  a,@r0
13524 \newline
13525 \SpecialChar ~
13526 \SpecialChar ~
13527 \SpecialChar ~
13528 \SpecialChar ~
13529 add  a,r2 ;?
13530 \newline
13531 \SpecialChar ~
13532 \SpecialChar ~
13533 \SpecialChar ~
13534 \SpecialChar ~
13535 mov  dpl,a
13536 \newline
13537 \SpecialChar ~
13538 \SpecialChar ~
13539 \SpecialChar ~
13540 \SpecialChar ~
13541 mov  dph,#0x00
13542 \newline
13543 \SpecialChar ~
13544 \SpecialChar ~
13545 \SpecialChar ~
13546 \SpecialChar ~
13547 mov  sp,_bp
13548 \newline
13549 \SpecialChar ~
13550 \SpecialChar ~
13551 \SpecialChar ~
13552 \SpecialChar ~
13553 pop  _bp
13554 \newline
13555 \SpecialChar ~
13556 \SpecialChar ~
13557 \SpecialChar ~
13558 \SpecialChar ~
13559 ret
13560 \layout Standard
13561
13562 The compiling and linking procedure remains the same, however note the extra
13563  entry & exit linkage required for the assembler code, _bp is the stack
13564  frame pointer and is used to compute the offset into the stack for parameters
13565  and local variables.
13566 \layout Section
13567
13568 int (16 bit)
13569 \begin_inset LatexCommand \index{int (16 bit)}
13570
13571 \end_inset
13572
13573  and long (32 bit)
13574 \begin_inset LatexCommand \index{long (32 bit)}
13575
13576 \end_inset
13577
13578  Support
13579 \layout Standard
13580
13581 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
13582  multiplication and modulus operations are implemented by support routines.
13583  These support routines are all developed in ANSI-C to facilitate porting
13584  to other MCUs, although some model specific assembler optimizations are
13585  used.
13586  The following files contain the described routines, all of them can be
13587  found in <installdir>/share/sdcc/lib.
13588 \newline
13589
13590 \layout Standard
13591 \align center
13592
13593 \begin_inset  Tabular
13594 <lyxtabular version="3" rows="11" columns="2">
13595 <features>
13596 <column alignment="center" valignment="top" leftline="true" width="0">
13597 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
13598 <row topline="true" bottomline="true">
13599 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13600 \begin_inset Text
13601
13602 \layout Standard
13603
13604
13605 \series bold
13606 Function
13607 \end_inset
13608 </cell>
13609 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13610 \begin_inset Text
13611
13612 \layout Standard
13613
13614
13615 \series bold
13616 Description
13617 \end_inset
13618 </cell>
13619 </row>
13620 <row topline="true">
13621 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13622 \begin_inset Text
13623
13624 \layout Standard
13625
13626 _mulint.c
13627 \end_inset
13628 </cell>
13629 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13630 \begin_inset Text
13631
13632 \layout Standard
13633
13634 16 bit multiplication
13635 \end_inset
13636 </cell>
13637 </row>
13638 <row topline="true">
13639 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13640 \begin_inset Text
13641
13642 \layout Standard
13643
13644 _divsint.c
13645 \end_inset
13646 </cell>
13647 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13648 \begin_inset Text
13649
13650 \layout Standard
13651
13652  signed 16 bit division (calls _divuint)
13653 \end_inset
13654 </cell>
13655 </row>
13656 <row topline="true">
13657 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13658 \begin_inset Text
13659
13660 \layout Standard
13661
13662 _divuint.c
13663 \end_inset
13664 </cell>
13665 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13666 \begin_inset Text
13667
13668 \layout Standard
13669
13670  unsigned 16 bit division
13671 \end_inset
13672 </cell>
13673 </row>
13674 <row topline="true">
13675 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13676 \begin_inset Text
13677
13678 \layout Standard
13679
13680 _modsint.c
13681 \end_inset
13682 </cell>
13683 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13684 \begin_inset Text
13685
13686 \layout Standard
13687
13688 signed 16 bit modulus (calls _moduint)
13689 \end_inset
13690 </cell>
13691 </row>
13692 <row topline="true">
13693 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13694 \begin_inset Text
13695
13696 \layout Standard
13697
13698 _moduint.c
13699 \end_inset
13700 </cell>
13701 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13702 \begin_inset Text
13703
13704 \layout Standard
13705
13706 unsigned 16 bit modulus
13707 \end_inset
13708 </cell>
13709 </row>
13710 <row topline="true">
13711 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13712 \begin_inset Text
13713
13714 \layout Standard
13715
13716 _mullong.c
13717 \end_inset
13718 </cell>
13719 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13720 \begin_inset Text
13721
13722 \layout Standard
13723
13724 32 bit multiplication
13725 \end_inset
13726 </cell>
13727 </row>
13728 <row topline="true">
13729 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13730 \begin_inset Text
13731
13732 \layout Standard
13733
13734 _divslong.c
13735 \end_inset
13736 </cell>
13737 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13738 \begin_inset Text
13739
13740 \layout Standard
13741
13742  signed 32 division (calls _divulong)
13743 \end_inset
13744 </cell>
13745 </row>
13746 <row topline="true">
13747 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13748 \begin_inset Text
13749
13750 \layout Standard
13751
13752 _divulong.c
13753 \end_inset
13754 </cell>
13755 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13756 \begin_inset Text
13757
13758 \layout Standard
13759
13760 unsigned 32 division
13761 \end_inset
13762 </cell>
13763 </row>
13764 <row topline="true">
13765 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13766 \begin_inset Text
13767
13768 \layout Standard
13769
13770 _modslong.c
13771 \end_inset
13772 </cell>
13773 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13774 \begin_inset Text
13775
13776 \layout Standard
13777
13778  signed 32 bit modulus (calls _modulong)
13779 \end_inset
13780 </cell>
13781 </row>
13782 <row topline="true" bottomline="true">
13783 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13784 \begin_inset Text
13785
13786 \layout Standard
13787
13788 _modulong.c
13789 \end_inset
13790 </cell>
13791 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13792 \begin_inset Text
13793
13794 \layout Standard
13795
13796 unsigned 32 bit modulus
13797 \end_inset
13798 </cell>
13799 </row>
13800 </lyxtabular>
13801
13802 \end_inset
13803
13804
13805 \newline
13806
13807 \layout Standard
13808
13809 Since they are compiled as
13810 \emph on
13811 non-reentrant
13812 \emph default
13813
13814 \begin_inset LatexCommand \index{reentrant}
13815
13816 \end_inset
13817
13818 , interrupt
13819 \begin_inset LatexCommand \index{interrupt}
13820
13821 \end_inset
13822
13823  service routines should not do any of the above operations.
13824  If this is unavoidable then the above routines will need to be compiled
13825  with the
13826 \emph on
13827 -
13828 \begin_inset ERT
13829 status Collapsed
13830
13831 \layout Standard
13832
13833 \backslash
13834 /
13835 \end_inset
13836
13837 -stack-auto
13838 \begin_inset LatexCommand \index{-\/-stack-auto}
13839
13840 \end_inset
13841
13842
13843 \emph default
13844  option, after which the source program will have to be compiled with
13845 \emph on
13846 -
13847 \begin_inset ERT
13848 status Collapsed
13849
13850 \layout Standard
13851
13852 \backslash
13853 /
13854 \end_inset
13855
13856 -int-long-reent
13857 \begin_inset LatexCommand \index{-\/-int-long-reent}
13858
13859 \end_inset
13860
13861
13862 \emph default
13863  option.
13864  Notice that you don't have to call these routines directly.
13865  The compiler will use them automatically every time an integer operation
13866  is required.
13867 \layout Section
13868
13869 Floating Point Support
13870 \begin_inset LatexCommand \index{Floating point support}
13871
13872 \end_inset
13873
13874
13875 \layout Standard
13876
13877 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
13878  floating point support routines are derived from gcc's floatlib.c and consist
13879  of the following routines:
13880 \newline
13881
13882 \layout Standard
13883 \align center
13884
13885 \size footnotesize
13886
13887 \begin_inset  Tabular
13888 <lyxtabular version="3" rows="17" columns="2">
13889 <features>
13890 <column alignment="center" valignment="top" leftline="true" width="0">
13891 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
13892 <row topline="true" bottomline="true">
13893 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13894 \begin_inset Text
13895
13896 \layout Standard
13897
13898
13899 \family roman
13900 \series medium
13901 \shape up
13902 \size normal
13903 \emph off
13904 \bar no
13905 \noun off
13906 \color none
13907 Function
13908 \end_inset
13909 </cell>
13910 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13911 \begin_inset Text
13912
13913 \layout Standard
13914
13915 Description
13916 \end_inset
13917 </cell>
13918 </row>
13919 <row topline="true">
13920 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13921 \begin_inset Text
13922
13923 \layout Standard
13924
13925
13926 \family roman
13927 \series medium
13928 \shape up
13929 \size normal
13930 \emph off
13931 \bar no
13932 \noun off
13933 \color none
13934 _fsadd.c
13935 \end_inset
13936 </cell>
13937 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13938 \begin_inset Text
13939
13940 \layout Standard
13941
13942
13943 \family roman
13944 \series medium
13945 \shape up
13946 \size normal
13947 \emph off
13948 \bar no
13949 \noun off
13950 \color none
13951 add floating point numbers
13952 \end_inset
13953 </cell>
13954 </row>
13955 <row topline="true">
13956 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13957 \begin_inset Text
13958
13959 \layout Standard
13960
13961
13962 \family roman
13963 \series medium
13964 \shape up
13965 \size normal
13966 \emph off
13967 \bar no
13968 \noun off
13969 \color none
13970 _fssub.c
13971 \end_inset
13972 </cell>
13973 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13974 \begin_inset Text
13975
13976 \layout Standard
13977
13978
13979 \family roman
13980 \series medium
13981 \shape up
13982 \size normal
13983 \emph off
13984 \bar no
13985 \noun off
13986 \color none
13987 subtract floating point numbers
13988 \end_inset
13989 </cell>
13990 </row>
13991 <row topline="true">
13992 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13993 \begin_inset Text
13994
13995 \layout Standard
13996
13997
13998 \family roman
13999 \series medium
14000 \shape up
14001 \size normal
14002 \emph off
14003 \bar no
14004 \noun off
14005 \color none
14006 _fsdiv.c
14007 \end_inset
14008 </cell>
14009 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14010 \begin_inset Text
14011
14012 \layout Standard
14013
14014
14015 \family roman
14016 \series medium
14017 \shape up
14018 \size normal
14019 \emph off
14020 \bar no
14021 \noun off
14022 \color none
14023 divide floating point numbers
14024 \end_inset
14025 </cell>
14026 </row>
14027 <row topline="true">
14028 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14029 \begin_inset Text
14030
14031 \layout Standard
14032
14033
14034 \family roman
14035 \series medium
14036 \shape up
14037 \size normal
14038 \emph off
14039 \bar no
14040 \noun off
14041 \color none
14042 _fsmul.c
14043 \end_inset
14044 </cell>
14045 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14046 \begin_inset Text
14047
14048 \layout Standard
14049
14050
14051 \family roman
14052 \series medium
14053 \shape up
14054 \size normal
14055 \emph off
14056 \bar no
14057 \noun off
14058 \color none
14059 multiply floating point numbers
14060 \end_inset
14061 </cell>
14062 </row>
14063 <row topline="true">
14064 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14065 \begin_inset Text
14066
14067 \layout Standard
14068
14069
14070 \family roman
14071 \series medium
14072 \shape up
14073 \size normal
14074 \emph off
14075 \bar no
14076 \noun off
14077 \color none
14078 _fs2uchar.c
14079 \end_inset
14080 </cell>
14081 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14082 \begin_inset Text
14083
14084 \layout Standard
14085
14086
14087 \family roman
14088 \series medium
14089 \shape up
14090 \size normal
14091 \emph off
14092 \bar no
14093 \noun off
14094 \color none
14095 convert floating point to unsigned char
14096 \end_inset
14097 </cell>
14098 </row>
14099 <row topline="true">
14100 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14101 \begin_inset Text
14102
14103 \layout Standard
14104
14105
14106 \family roman
14107 \series medium
14108 \shape up
14109 \size normal
14110 \emph off
14111 \bar no
14112 \noun off
14113 \color none
14114 _fs2char.c
14115 \end_inset
14116 </cell>
14117 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14118 \begin_inset Text
14119
14120 \layout Standard
14121
14122
14123 \family roman
14124 \series medium
14125 \shape up
14126 \size normal
14127 \emph off
14128 \bar no
14129 \noun off
14130 \color none
14131 convert floating point to signed char
14132 \end_inset
14133 </cell>
14134 </row>
14135 <row topline="true">
14136 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14137 \begin_inset Text
14138
14139 \layout Standard
14140
14141
14142 \family roman
14143 \series medium
14144 \shape up
14145 \size normal
14146 \emph off
14147 \bar no
14148 \noun off
14149 \color none
14150 _fs2uint.c
14151 \end_inset
14152 </cell>
14153 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14154 \begin_inset Text
14155
14156 \layout Standard
14157
14158
14159 \family roman
14160 \series medium
14161 \shape up
14162 \size normal
14163 \emph off
14164 \bar no
14165 \noun off
14166 \color none
14167 convert floating point to unsigned int
14168 \end_inset
14169 </cell>
14170 </row>
14171 <row topline="true">
14172 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14173 \begin_inset Text
14174
14175 \layout Standard
14176
14177
14178 \family roman
14179 \series medium
14180 \shape up
14181 \size normal
14182 \emph off
14183 \bar no
14184 \noun off
14185 \color none
14186 _fs2int.c
14187 \end_inset
14188 </cell>
14189 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14190 \begin_inset Text
14191
14192 \layout Standard
14193
14194
14195 \family roman
14196 \series medium
14197 \shape up
14198 \size normal
14199 \emph off
14200 \bar no
14201 \noun off
14202 \color none
14203 convert floating point to signed int
14204 \end_inset
14205 </cell>
14206 </row>
14207 <row topline="true">
14208 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14209 \begin_inset Text
14210
14211 \layout Standard
14212
14213
14214 \family roman
14215 \series medium
14216 \shape up
14217 \size normal
14218 \emph off
14219 \bar no
14220 \noun off
14221 \color none
14222 _fs2ulong.
14223 \family default
14224 \series default
14225 \shape default
14226 \size default
14227 \emph default
14228 \bar default
14229 \noun default
14230 \color default
14231 c
14232 \end_inset
14233 </cell>
14234 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14235 \begin_inset Text
14236
14237 \layout Standard
14238
14239
14240 \family roman
14241 \series medium
14242 \shape up
14243 \size normal
14244 \emph off
14245 \bar no
14246 \noun off
14247 \color none
14248 convert floating point to unsigned long
14249 \end_inset
14250 </cell>
14251 </row>
14252 <row topline="true">
14253 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14254 \begin_inset Text
14255
14256 \layout Standard
14257
14258
14259 \family roman
14260 \series medium
14261 \shape up
14262 \size normal
14263 \emph off
14264 \bar no
14265 \noun off
14266 \color none
14267 _fs2long.c
14268 \end_inset
14269 </cell>
14270 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14271 \begin_inset Text
14272
14273 \layout Standard
14274
14275
14276 \family roman
14277 \series medium
14278 \shape up
14279 \size normal
14280 \emph off
14281 \bar no
14282 \noun off
14283 \color none
14284 convert floating point to signed long
14285 \end_inset
14286 </cell>
14287 </row>
14288 <row topline="true">
14289 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14290 \begin_inset Text
14291
14292 \layout Standard
14293
14294
14295 \family roman
14296 \series medium
14297 \shape up
14298 \size normal
14299 \emph off
14300 \bar no
14301 \noun off
14302 \color none
14303 _uchar2fs.c
14304 \end_inset
14305 </cell>
14306 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14307 \begin_inset Text
14308
14309 \layout Standard
14310
14311
14312 \family roman
14313 \series medium
14314 \shape up
14315 \size normal
14316 \emph off
14317 \bar no
14318 \noun off
14319 \color none
14320 convert unsigned char to floating point
14321 \end_inset
14322 </cell>
14323 </row>
14324 <row topline="true">
14325 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14326 \begin_inset Text
14327
14328 \layout Standard
14329
14330
14331 \family roman
14332 \series medium
14333 \shape up
14334 \size normal
14335 \emph off
14336 \bar no
14337 \noun off
14338 \color none
14339 _char2fs.c
14340 \end_inset
14341 </cell>
14342 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14343 \begin_inset Text
14344
14345 \layout Standard
14346
14347
14348 \family roman
14349 \series medium
14350 \shape up
14351 \size normal
14352 \emph off
14353 \bar no
14354 \noun off
14355 \color none
14356 convert char to floating point number
14357 \end_inset
14358 </cell>
14359 </row>
14360 <row topline="true">
14361 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14362 \begin_inset Text
14363
14364 \layout Standard
14365
14366
14367 \family roman
14368 \series medium
14369 \shape up
14370 \size normal
14371 \emph off
14372 \bar no
14373 \noun off
14374 \color none
14375 _uint2fs.c
14376 \end_inset
14377 </cell>
14378 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14379 \begin_inset Text
14380
14381 \layout Standard
14382
14383
14384 \family roman
14385 \series medium
14386 \shape up
14387 \size normal
14388 \emph off
14389 \bar no
14390 \noun off
14391 \color none
14392 convert unsigned int to floating point
14393 \end_inset
14394 </cell>
14395 </row>
14396 <row topline="true">
14397 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14398 \begin_inset Text
14399
14400 \layout Standard
14401
14402
14403 \family roman
14404 \series medium
14405 \shape up
14406 \size normal
14407 \emph off
14408 \bar no
14409 \noun off
14410 \color none
14411 _int2fs.c
14412 \end_inset
14413 </cell>
14414 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14415 \begin_inset Text
14416
14417 \layout Standard
14418
14419
14420 \family roman
14421 \series medium
14422 \shape up
14423 \size normal
14424 \emph off
14425 \bar no
14426 \noun off
14427 \color none
14428 convert int to floating point numbers
14429 \end_inset
14430 </cell>
14431 </row>
14432 <row topline="true">
14433 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14434 \begin_inset Text
14435
14436 \layout Standard
14437
14438
14439 \family roman
14440 \series medium
14441 \shape up
14442 \size normal
14443 \emph off
14444 \bar no
14445 \noun off
14446 \color none
14447 _ulong2fs.c
14448 \end_inset
14449 </cell>
14450 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14451 \begin_inset Text
14452
14453 \layout Standard
14454
14455
14456 \family roman
14457 \series medium
14458 \shape up
14459 \size normal
14460 \emph off
14461 \bar no
14462 \noun off
14463 \color none
14464 convert unsigned long to floating point number
14465 \end_inset
14466 </cell>
14467 </row>
14468 <row topline="true" bottomline="true">
14469 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14470 \begin_inset Text
14471
14472 \layout Standard
14473
14474
14475 \family roman
14476 \series medium
14477 \shape up
14478 \size normal
14479 \emph off
14480 \bar no
14481 \noun off
14482 \color none
14483 _long2fs.c
14484 \end_inset
14485 </cell>
14486 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14487 \begin_inset Text
14488
14489 \layout Standard
14490
14491
14492 \family roman
14493 \series medium
14494 \shape up
14495 \size normal
14496 \emph off
14497 \bar no
14498 \noun off
14499 \color none
14500 convert long to floating point number
14501 \end_inset
14502 </cell>
14503 </row>
14504 </lyxtabular>
14505
14506 \end_inset
14507
14508
14509 \newline
14510
14511 \layout Standard
14512
14513 These support routines are developed in ANSI-C so there is room for space
14514  and speed improvement
14515 \begin_inset Foot
14516 collapsed false
14517
14518 \layout Standard
14519
14520 The floating point routines for the mcs51 are implemented in assembler
14521 \end_inset
14522
14523 .
14524  Note if all these routines are used simultaneously the data space might
14525  overflow.
14526  For serious floating point usage the large model might be needed.
14527  Also notice that you don't have to call this routines directly.
14528  The compiler will use them automatically every time a floating point operation
14529  is required.
14530 \layout Section
14531
14532 Library Routines
14533 \begin_inset LatexCommand \index{Libraries}
14534
14535 \end_inset
14536
14537
14538 \layout Standard
14539
14540
14541 \emph on
14542 <pending: this is messy and incomplete - a little more information is in
14543  sdcc/doc/libdoc.txt
14544 \emph default
14545  >
14546 \layout Subsection
14547
14548 Compiler support routines (_gptrget, _mulint etc.)
14549 \layout Subsection
14550
14551 Stdclib functions (puts, printf, strcat etc.)
14552 \layout Subsubsection
14553
14554 <stdio.h>
14555 \layout Standard
14556
14557
14558 \begin_inset LatexCommand \index{<stdio.h>}
14559
14560 \end_inset
14561
14562 As usual on embedded systems you have to provide your own
14563 \family typewriter
14564 getchar()
14565 \begin_inset LatexCommand \index{getchar()}
14566
14567 \end_inset
14568
14569
14570 \family default
14571 and
14572 \family typewriter
14573 putchar()
14574 \begin_inset LatexCommand \index{putchar()}
14575
14576 \end_inset
14577
14578
14579 \family default
14580  routines.
14581  SDCC does not know whether the system connects to a serial line with or
14582  without handshake, LCD, keyboard or other device.
14583  You'll find examples for serial routines f.e.
14584  in sdcc/device/lib.
14585 \layout Standard
14586
14587 The default
14588 \family typewriter
14589  printf()
14590 \begin_inset LatexCommand \index{printf()}
14591
14592 \end_inset
14593
14594
14595 \family default
14596 implementation in
14597 \family typewriter
14598  printf_large.c
14599 \family default
14600  does not support float (except on ds390).
14601  To enable this recompile it with the option
14602 \emph on
14603 -
14604 \begin_inset ERT
14605 status Collapsed
14606
14607 \layout Standard
14608
14609 \backslash
14610 /
14611 \end_inset
14612
14613 DUSE_FLOATS=1
14614 \begin_inset LatexCommand \index{USE\_FLOATS}
14615
14616 \end_inset
14617
14618
14619 \emph default
14620  on the command line.
14621  Use
14622 \emph on
14623 -
14624 \begin_inset ERT
14625 status Collapsed
14626
14627 \layout Standard
14628
14629 \backslash
14630 /
14631 \end_inset
14632
14633 -model-large
14634 \begin_inset LatexCommand \index{-\/-model-large}
14635
14636 \end_inset
14637
14638
14639 \emph default
14640  for the mcs51 port, since this uses a lot of memory.
14641 \layout Standard
14642
14643 If you're short on memory you might want to use
14644 \family typewriter
14645 printf_small()
14646 \begin_inset LatexCommand \index{printf\_small()}
14647
14648 \end_inset
14649
14650
14651 \family default
14652
14653 \emph on
14654 instead
14655 \emph default
14656  of
14657 \family typewriter
14658  printf().
14659
14660 \family default
14661  For the mcs51 there additionally are assembly versions
14662 \family typewriter
14663 printf_tiny()
14664 \begin_inset LatexCommand \index{printf\_tiny() (mcs51)}
14665
14666 \end_inset
14667
14668
14669 \family default
14670  and
14671 \family typewriter
14672 printf_fast()
14673 \begin_inset LatexCommand \index{printf\_fast() (mcs51)}
14674
14675 \end_inset
14676
14677
14678 \family default
14679 and
14680 \family typewriter
14681  printf_fast_f()
14682 \begin_inset LatexCommand \index{printf\_fast\_f() (mcs51)}
14683
14684 \end_inset
14685
14686
14687 \family default
14688  which should fit the requirements of many embedded systems (printf_fast()
14689  can be customized by unsetting #defines to
14690 \emph on
14691 not
14692 \emph default
14693  support long variables and field widths).
14694 \layout Subsection
14695
14696 Math functions (sin, pow, sqrt etc.)
14697 \layout Subsection
14698
14699 Other libraries
14700 \layout Standard
14701
14702 Libraries
14703 \begin_inset LatexCommand \index{Libraries}
14704
14705 \end_inset
14706
14707  included in SDCC should have a license at least as liberal as the GNU Lesser
14708  General Public License
14709 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
14710
14711 \end_inset
14712
14713
14714 \emph on
14715 LGPL
14716 \emph default
14717 .
14718 \layout Comment
14719
14720 license statements for the libraries are missing.
14721  sdcc/device/lib/ser_ir.c
14722 \layout Comment
14723
14724 or _decdptr f.e.
14725  come with a GPL (as opposed to LGPL) License - this will not be liberal
14726  enough for many embedded programmers.
14727 \layout Standard
14728
14729 If you have ported some library or want to share experience about some code
14730  which f.e.
14731  falls into any of these categories Busses (I
14732 \begin_inset Formula $^{\textrm{2}}$
14733 \end_inset
14734
14735 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
14736  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
14737  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
14738 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
14739
14740 \end_inset
14741
14742 \SpecialChar ~
14743 would certainly like to hear about it.
14744  Programmers coding for embedded systems are not especially famous for being
14745  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
14746 e these references are very valuable.
14747  Let's help to create a climate where information is shared.
14748 \layout Section
14749
14750 Memory Models
14751 \layout Subsection
14752
14753 MCS51 Memory Models
14754 \begin_inset LatexCommand \index{Memory model}
14755
14756 \end_inset
14757
14758
14759 \begin_inset LatexCommand \index{MCS51 memory model}
14760
14761 \end_inset
14762
14763
14764 \layout Subsubsection
14765
14766 Small, Medium and Large
14767 \layout Standard
14768
14769 SDCC allows three memory models for MCS51 code,
14770 \shape slanted
14771 small, medium
14772 \shape default
14773  and
14774 \shape slanted
14775 large
14776 \shape default
14777 .
14778  Modules compiled with different memory models should
14779 \emph on
14780 never
14781 \emph default
14782  be combined together or the results would be unpredictable.
14783  The library routines supplied with the compiler are compiled as small,
14784  medium and large.
14785  The compiled library modules are contained in separate directories as small,
14786  medium and large so that you can link to the appropriate set.
14787 \layout Standard
14788
14789 When the medium or large model is used all variables declared without a
14790  storage class will be allocated into the external ram, this includes all
14791  parameters and local variables (for non-reentrant
14792 \begin_inset LatexCommand \index{reentrant}
14793
14794 \end_inset
14795
14796  functions).
14797  When the small model is used variables without storage class are allocated
14798  in the internal ram.
14799 \layout Standard
14800
14801 Judicious usage of the processor specific storage classes
14802 \begin_inset LatexCommand \index{Storage class}
14803
14804 \end_inset
14805
14806  and the 'reentrant' function type will yield much more efficient code,
14807  than using the large model.
14808  Several optimizations are disabled when the program is compiled using the
14809  large model, it is therefore recommended that the small model be used unless
14810  absolutely required.
14811 \layout Subsubsection
14812
14813 External Stack
14814 \begin_inset LatexCommand \label{sub:External-Stack}
14815
14816 \end_inset
14817
14818
14819 \begin_inset LatexCommand \index{stack}
14820
14821 \end_inset
14822
14823
14824 \begin_inset LatexCommand \index{External stack (mcs51)}
14825
14826 \end_inset
14827
14828
14829 \layout Standard
14830
14831 The external stack (-
14832 \begin_inset ERT
14833 status Collapsed
14834
14835 \layout Standard
14836
14837 \backslash
14838 /
14839 \end_inset
14840
14841 -xstack option
14842 \begin_inset LatexCommand \index{-\/-xstack}
14843
14844 \end_inset
14845
14846 ) is located in pdata
14847 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
14848
14849 \end_inset
14850
14851  memory (usually at the start of the external ram segment) and uses all
14852  unused space in pdata (max.
14853  256 bytes).
14854  When -
14855 \begin_inset ERT
14856 status Collapsed
14857
14858 \layout Standard
14859
14860 \backslash
14861 /
14862 \end_inset
14863
14864 -xstack option is used to compile the program, the parameters and local
14865  variables
14866 \begin_inset LatexCommand \index{local variables}
14867
14868 \end_inset
14869
14870  of all reentrant functions are allocated in this area.
14871  This option is provided for programs with large stack space requirements.
14872  When used with the -
14873 \begin_inset ERT
14874 status Collapsed
14875
14876 \layout Standard
14877
14878 \backslash
14879 /
14880 \end_inset
14881
14882 -stack-auto
14883 \begin_inset LatexCommand \index{-\/-stack-auto}
14884
14885 \end_inset
14886
14887  option, all parameters and local variables are allocated on the external
14888  stack (note: support libraries will need to be recompiled with the same
14889  options.
14890  There is a predefined target in the library makefile).
14891 \layout Standard
14892
14893 The compiler outputs the higher order address byte of the external ram segment
14894  into port P2
14895 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
14896
14897 \end_inset
14898
14899  (see also section
14900 \begin_inset LatexCommand \ref{sub:MCS51-variants}
14901
14902 \end_inset
14903
14904 ), therefore when using the External Stack option, this port
14905 \emph on
14906 may not
14907 \emph default
14908  be used by the application program.
14909 \layout Subsection
14910
14911 DS390 Memory Model
14912 \begin_inset LatexCommand \index{Memory model}
14913
14914 \end_inset
14915
14916
14917 \begin_inset LatexCommand \index{DS390 memory model}
14918
14919 \end_inset
14920
14921
14922 \layout Standard
14923
14924 The only model supported is Flat 24
14925 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
14926
14927 \end_inset
14928
14929 .
14930  This generates code for the 24 bit contiguous addressing mode of the Dallas
14931  DS80C390 part.
14932  In this mode, up to four meg of external RAM or code space can be directly
14933  addressed.
14934  See the data sheets at www.dalsemi.com for further information on this part.
14935 \newline
14936
14937 \newline
14938 Note that the compiler does not generate any code to place the processor
14939  into 24 bitmode (although
14940 \emph on
14941 tinibios
14942 \emph default
14943  in the ds390 libraries will do that for you).
14944  If you don't use
14945 \emph on
14946 tinibios
14947 \emph default
14948
14949 \begin_inset LatexCommand \index{Tinibios (DS390)}
14950
14951 \end_inset
14952
14953 , the boot loader or similar code must ensure that the processor is in 24
14954  bit contiguous addressing mode before calling the SDCC startup code.
14955 \newline
14956
14957 \newline
14958 Like the
14959 \emph on
14960 -
14961 \begin_inset ERT
14962 status Collapsed
14963
14964 \layout Standard
14965
14966 \backslash
14967 /
14968 \end_inset
14969
14970 -model-large
14971 \emph default
14972  option, variables will by default be placed into the XDATA segment.
14973
14974 \newline
14975
14976 \newline
14977 Segments may be placed anywhere in the 4 meg address space using the usual
14978  -
14979 \begin_inset ERT
14980 status Collapsed
14981
14982 \layout Standard
14983
14984 \backslash
14985 /
14986 \end_inset
14987
14988 -*-loc options.
14989  Note that if any segments are located above 64K, the -r flag must be passed
14990  to the linker to generate the proper segment relocations, and the Intel
14991  HEX output format must be used.
14992  The -r flag can be passed to the linker by using the option
14993 \emph on
14994 -Wl-r
14995 \emph default
14996  on the SDCC command line.
14997  However, currently the linker can not handle code segments > 64k.
14998 \layout Section
14999
15000 Pragmas
15001 \begin_inset LatexCommand \index{Pragmas}
15002
15003 \end_inset
15004
15005
15006 \layout Standard
15007
15008 SDCC supports the following #pragma directives:
15009 \layout Itemize
15010
15011 save
15012 \begin_inset LatexCommand \index{\#pragma save}
15013
15014 \end_inset
15015
15016  - this will save all current options to the save/restore stack.
15017  See #pragma\SpecialChar ~
15018 restore.
15019 \layout Itemize
15020
15021 restore
15022 \begin_inset LatexCommand \index{\#pragma restore}
15023
15024 \end_inset
15025
15026  - will restore saved options from the last save.
15027  saves & restores can be nested.
15028  SDCC uses a save/restore stack: save pushes current options to the stack,
15029  restore pulls current options from the stack.
15030  See #pragma\SpecialChar ~
15031 save.
15032 \newline
15033
15034 \layout Itemize
15035
15036 callee_saves
15037 \begin_inset LatexCommand \index{\#pragma callee\_saves}
15038
15039 \end_inset
15040
15041
15042 \begin_inset LatexCommand \index{function prologue}
15043
15044 \end_inset
15045
15046  function1[,function2[,function3...]] - The compiler by default uses a caller
15047  saves convention for register saving across function calls, however this
15048  can cause unnecessary register pushing & popping
15049 \begin_inset LatexCommand \index{push/pop}
15050
15051 \end_inset
15052
15053  when calling small functions from larger functions.
15054  This option can be used to switch off the register saving convention for
15055  the function names specified.
15056  The compiler will not save registers when calling these functions, extra
15057  code need to be manually inserted at the entry & exit for these functions
15058  to save & restore the registers used by these functions, this can SUBSTANTIALLY
15059  reduce code & improve run time performance of the generated code.
15060  In the future the compiler (with inter procedural analysis) may be able
15061  to determine the appropriate scheme to use for each function call.
15062  If -
15063 \begin_inset ERT
15064 status Collapsed
15065
15066 \layout Standard
15067
15068 \backslash
15069 /
15070 \end_inset
15071
15072 -callee-saves command line option is used, the function names specified
15073  in #pragma\SpecialChar ~
15074 callee_saves
15075 \begin_inset LatexCommand \index{\#pragma callee\_saves}
15076
15077 \end_inset
15078
15079  is appended to the list of functions specified in the command line.
15080 \layout Itemize
15081
15082 exclude
15083 \begin_inset LatexCommand \index{\#pragma exclude}
15084
15085 \end_inset
15086
15087  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
15088  of pairs of push/pop
15089 \begin_inset LatexCommand \index{push/pop}
15090
15091 \end_inset
15092
15093  instructions in
15094 \emph on
15095 I
15096 \emph default
15097 nterrupt
15098 \begin_inset LatexCommand \index{interrupt}
15099
15100 \end_inset
15101
15102
15103 \emph on
15104 S
15105 \emph default
15106 ervice
15107 \emph on
15108 R
15109 \emph default
15110 outines.
15111  The directive should be placed immediately before the ISR function definition
15112  and it affects ALL ISR functions following it.
15113  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
15114 exclude\SpecialChar ~
15115 none
15116 \begin_inset LatexCommand \index{\#pragma exclude}
15117
15118 \end_inset
15119
15120 .
15121  See also the related keyword _naked
15122 \begin_inset LatexCommand \index{\_naked}
15123
15124 \end_inset
15125
15126
15127 \begin_inset LatexCommand \index{\_\_naked}
15128
15129 \end_inset
15130
15131 .
15132 \layout Itemize
15133
15134 less_pedantic
15135 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
15136
15137 \end_inset
15138
15139  - the compiler will not warn you anymore for obvious mistakes, you'r on
15140  your own now ;-(
15141 \layout Itemize
15142
15143 disable_warning <nnnn>
15144 \begin_inset LatexCommand \index{\#pragma disable\_warning}
15145
15146 \end_inset
15147
15148  - the compiler will not warn you anymore about warning number <nnnn>.
15149 \layout Itemize
15150
15151 nogcse
15152 \begin_inset LatexCommand \index{\#pragma nogcse}
15153
15154 \end_inset
15155
15156  - will stop global common subexpression elimination.
15157 \layout Itemize
15158
15159 noinduction
15160 \begin_inset LatexCommand \index{\#pragma noinduction}
15161
15162 \end_inset
15163
15164  - will stop loop induction optimizations.
15165 \layout Itemize
15166
15167 noinvariant
15168 \begin_inset LatexCommand \index{\#pragma noinvariant}
15169
15170 \end_inset
15171
15172  - will not do loop invariant optimizations.
15173  For more details see Loop Invariants in section
15174 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
15175
15176 \end_inset
15177
15178 .
15179 \layout Itemize
15180
15181 noiv
15182 \begin_inset LatexCommand \index{\#pragma noiv}
15183
15184 \end_inset
15185
15186  - Do not generate interrupt
15187 \begin_inset LatexCommand \index{interrupt}
15188
15189 \end_inset
15190
15191  vector table entries for all ISR functions defined after the pragma.
15192  This is useful in cases where the interrupt vector table must be defined
15193  manually, or when there is a secondary, manually defined interrupt vector
15194  table (e.g.
15195  for the autovector feature of the Cypress EZ-USB FX2).
15196  More elegantly this can be achieved by obmitting the optional interrupt
15197  number after the interrupt keyword, see section
15198 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
15199
15200 \end_inset
15201
15202 \SpecialChar ~
15203 about interrupts.
15204 \layout Itemize
15205
15206 nojtbound
15207 \begin_inset LatexCommand \index{\#pragma nojtbound}
15208
15209 \end_inset
15210
15211  - will not generate code for boundary value checking, when switch statements
15212  are turned into jump-tables (dangerous).
15213  For more details see section
15214 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
15215
15216 \end_inset
15217
15218 .
15219 \layout Itemize
15220
15221 noloopreverse
15222 \begin_inset LatexCommand \index{\#pragma noloopreverse}
15223
15224 \end_inset
15225
15226  - Will not do loop reversal optimization
15227 \layout Itemize
15228
15229 nooverlay
15230 \begin_inset LatexCommand \index{\#pragma nooverlay}
15231
15232 \end_inset
15233
15234  - the compiler will not overlay the parameters and local variables of a
15235  function.
15236 \layout Itemize
15237
15238 stackauto
15239 \begin_inset LatexCommand \index{\#pragma stackauto}
15240
15241 \end_inset
15242
15243 - See option -
15244 \begin_inset ERT
15245 status Collapsed
15246
15247 \layout Standard
15248
15249 \backslash
15250 /
15251 \end_inset
15252
15253 -stack-auto
15254 \begin_inset LatexCommand \index{-\/-stack-auto}
15255
15256 \end_inset
15257
15258  and section
15259 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
15260
15261 \end_inset
15262
15263  Parameters and Local Variables.
15264 \layout Itemize
15265
15266 opt_code_speed
15267 \begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
15268
15269 \end_inset
15270
15271 - The compiler will optimize code generation towards fast code, possibly
15272  at the expense of code size.
15273 \layout Itemize
15274
15275 opt_code_size
15276 \begin_inset LatexCommand \index{\#pragma opt\_code\_size}
15277
15278 \end_inset
15279
15280 - The compiler will optimize code generation towards compact code, possibly
15281  at the expense of code speed.
15282 \layout Itemize
15283
15284 opt_code_balanced
15285 \begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
15286
15287 \end_inset
15288
15289 - The compiler will attempt to generate code that is both compact and fast,
15290  as long as meeting one goal is not a detriment to the other (this is the
15291  default).
15292
15293 \layout Itemize
15294
15295 std_sdcc89
15296 \begin_inset LatexCommand \index{\#pragma std\_sdcc89}
15297
15298 \end_inset
15299
15300 - Generally follow the C89 standard, but allow SDCC features that conflict
15301  with the standard (default).
15302 \layout Itemize
15303
15304 std_c89
15305 \begin_inset LatexCommand \index{\#pragma std\_c89}
15306
15307 \end_inset
15308
15309 - Follow the C89 standard and disable SDCC features that conflict with the
15310  standard.
15311 \layout Itemize
15312
15313 std_sdcc99
15314 \begin_inset LatexCommand \index{\#pragma std\_sdcc99}
15315
15316 \end_inset
15317
15318 - Generally follow the C99 standard, but allow SDCC features that conflict
15319  with the standard (incomplete support).
15320 \layout Itemize
15321
15322 std_c99
15323 \begin_inset LatexCommand \index{\#pragma std\_c99}
15324
15325 \end_inset
15326
15327 - Follow the C99 standard and disable SDCC features that conflict with the
15328  standard (incomplete support).
15329 \layout Itemize
15330
15331 codeseg <name>
15332 \begin_inset LatexCommand \index{\#pragma codeseg}
15333
15334 \end_inset
15335
15336 - Use this name (max.
15337  8 characters) for the code segment.
15338 \layout Itemize
15339
15340 constseg <name>
15341 \begin_inset LatexCommand \index{\#pragma constseg}
15342
15343 \end_inset
15344
15345 - Use this name (max.
15346  8 characters) for the const segment.
15347 \layout Standard
15348
15349 SDCPP supports the following #pragma directives:
15350 \layout Itemize
15351
15352 preproc_asm
15353 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
15354
15355 \end_inset
15356
15357  (+ | -) - switch _asm _endasm block preprocessing on / off.
15358  Default is on.
15359 \layout Standard
15360
15361 The pragma's are intended to be used to turn-on or off certain optimizations
15362  which might cause the compiler to generate extra stack / data space to
15363  store compiler generated temporary variables.
15364  This usually happens in large functions.
15365  Pragma directives should be used as shown in the following example, they
15366  are used to control options & optimizations for a given function; pragmas
15367  should be placed before and/or after a function, placing pragma's inside
15368  a function body could have unpredictable results.
15369 \layout Verse
15370
15371
15372 \family typewriter
15373 #pragma save
15374 \begin_inset LatexCommand \index{\#pragma save}
15375
15376 \end_inset
15377
15378  \SpecialChar ~
15379 \SpecialChar ~
15380 \SpecialChar ~
15381 \SpecialChar ~
15382 \SpecialChar ~
15383 \SpecialChar ~
15384 \SpecialChar ~
15385 /* save the current settings */
15386 \newline
15387 #pragma nogcse
15388 \begin_inset LatexCommand \index{\#pragma nogcse}
15389
15390 \end_inset
15391
15392  \SpecialChar ~
15393 \SpecialChar ~
15394 \SpecialChar ~
15395 \SpecialChar ~
15396 \SpecialChar ~
15397 /* turnoff global subexpression elimination */
15398 \newline
15399 #pragma noinduction
15400 \begin_inset LatexCommand \index{\#pragma noinduction}
15401
15402 \end_inset
15403
15404  /* turn off induction optimizations */
15405 \newline
15406 int foo ()
15407 \newline
15408 {
15409 \newline
15410 \SpecialChar ~
15411  \SpecialChar ~
15412  ...
15413
15414 \newline
15415 \SpecialChar ~
15416  \SpecialChar ~
15417  /* large code */
15418 \newline
15419 \SpecialChar ~
15420  \SpecialChar ~
15421  ...
15422
15423 \newline
15424 }
15425 \newline
15426 #pragma restore
15427 \begin_inset LatexCommand \index{\#pragma restore}
15428
15429 \end_inset
15430
15431  /* turn the optimizations back on */
15432 \layout Standard
15433
15434 The compiler will generate a warning message when extra space is allocated.
15435  It is strongly recommended that the save and restore pragma's be used when
15436  changing options for a function.
15437 \layout Section
15438
15439 Defines Created by the Compiler
15440 \layout Standard
15441
15442 The compiler creates the following #defines
15443 \begin_inset LatexCommand \index{\#defines}
15444
15445 \end_inset
15446
15447
15448 \begin_inset LatexCommand \index{Defines created by the compiler}
15449
15450 \end_inset
15451
15452 :
15453 \newline
15454
15455 \layout Standard
15456
15457
15458 \begin_inset  Tabular
15459 <lyxtabular version="3" rows="11" columns="2">
15460 <features>
15461 <column alignment="center" valignment="top" leftline="true" width="0">
15462 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15463 <row topline="true" bottomline="true">
15464 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15465 \begin_inset Text
15466
15467 \layout Standard
15468
15469
15470 \series bold
15471 #define
15472 \end_inset
15473 </cell>
15474 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15475 \begin_inset Text
15476
15477 \layout Standard
15478
15479
15480 \series bold
15481 Description
15482 \end_inset
15483 </cell>
15484 </row>
15485 <row topline="true">
15486 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15487 \begin_inset Text
15488
15489 \layout Standard
15490
15491 SDCC
15492 \begin_inset LatexCommand \index{SDCC}
15493
15494 \end_inset
15495
15496
15497 \end_inset
15498 </cell>
15499 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15500 \begin_inset Text
15501
15502 \layout Standard
15503
15504 this Symbol is always defined
15505 \end_inset
15506 </cell>
15507 </row>
15508 <row topline="true">
15509 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15510 \begin_inset Text
15511
15512 \layout Standard
15513
15514 SDCC_mcs51
15515 \begin_inset LatexCommand \index{SDCC\_mcs51}
15516
15517 \end_inset
15518
15519  or SDCC_ds390
15520 \begin_inset LatexCommand \index{SDCC\_ds390}
15521
15522 \end_inset
15523
15524  or SDCC_z80
15525 \begin_inset LatexCommand \index{SDCC\_z80}
15526
15527 \end_inset
15528
15529 , etc
15530 \end_inset
15531 </cell>
15532 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15533 \begin_inset Text
15534
15535 \layout Standard
15536
15537 depending on the model used (e.g.: -mds390
15538 \end_inset
15539 </cell>
15540 </row>
15541 <row topline="true">
15542 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15543 \begin_inset Text
15544
15545 \layout Standard
15546
15547 __mcs51
15548 \begin_inset LatexCommand \index{\_\_mcs51}
15549
15550 \end_inset
15551
15552 , __ds390
15553 \begin_inset LatexCommand \index{\_\_ds390}
15554
15555 \end_inset
15556
15557 , __hc08
15558 \begin_inset LatexCommand \index{\_\_hc08}
15559
15560 \end_inset
15561
15562 , __z80
15563 \begin_inset LatexCommand \index{\_\_z80}
15564
15565 \end_inset
15566
15567 , etc
15568 \end_inset
15569 </cell>
15570 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15571 \begin_inset Text
15572
15573 \layout Standard
15574
15575 depending on the model used (e.g.
15576  -mz80)
15577 \end_inset
15578 </cell>
15579 </row>
15580 <row topline="true">
15581 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15582 \begin_inset Text
15583
15584 \layout Standard
15585
15586 SDCC_STACK_AUTO
15587 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
15588
15589 \end_inset
15590
15591
15592 \end_inset
15593 </cell>
15594 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15595 \begin_inset Text
15596
15597 \layout Standard
15598
15599 when
15600 \emph on
15601 -
15602 \begin_inset ERT
15603 status Collapsed
15604
15605 \layout Standard
15606
15607 \backslash
15608 /
15609 \end_inset
15610
15611 -stack-auto
15612 \emph default
15613  option is used
15614 \end_inset
15615 </cell>
15616 </row>
15617 <row topline="true">
15618 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15619 \begin_inset Text
15620
15621 \layout Standard
15622
15623 SDCC_MODEL_SMALL
15624 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
15625
15626 \end_inset
15627
15628
15629 \end_inset
15630 </cell>
15631 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15632 \begin_inset Text
15633
15634 \layout Standard
15635
15636 when
15637 \emph on
15638 -
15639 \begin_inset ERT
15640 status Collapsed
15641
15642 \layout Standard
15643
15644 \backslash
15645 /
15646 \end_inset
15647
15648 -model-small
15649 \emph default
15650  is used
15651 \end_inset
15652 </cell>
15653 </row>
15654 <row topline="true">
15655 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15656 \begin_inset Text
15657
15658 \layout Standard
15659
15660 SDCC_MODEL_MEDIUM
15661 \begin_inset LatexCommand \index{SDCC\_MODEL\_MEDIUM}
15662
15663 \end_inset
15664
15665
15666 \end_inset
15667 </cell>
15668 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15669 \begin_inset Text
15670
15671 \layout Standard
15672
15673 when
15674 \emph on
15675 -
15676 \begin_inset ERT
15677 status Collapsed
15678
15679 \layout Standard
15680
15681 \backslash
15682 /
15683 \end_inset
15684
15685 -model-medium
15686 \emph default
15687  is used
15688 \end_inset
15689 </cell>
15690 </row>
15691 <row topline="true">
15692 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15693 \begin_inset Text
15694
15695 \layout Standard
15696
15697 SDCC_MODEL_LARGE
15698 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
15699
15700 \end_inset
15701
15702
15703 \end_inset
15704 </cell>
15705 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15706 \begin_inset Text
15707
15708 \layout Standard
15709
15710 when
15711 \emph on
15712 -
15713 \begin_inset ERT
15714 status Collapsed
15715
15716 \layout Standard
15717
15718 \backslash
15719 /
15720 \end_inset
15721
15722 -model-large
15723 \emph default
15724  is used
15725 \end_inset
15726 </cell>
15727 </row>
15728 <row topline="true">
15729 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15730 \begin_inset Text
15731
15732 \layout Standard
15733
15734 SDCC_USE_XSTACK
15735 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
15736
15737 \end_inset
15738
15739
15740 \end_inset
15741 </cell>
15742 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15743 \begin_inset Text
15744
15745 \layout Standard
15746
15747 when
15748 \emph on
15749 -
15750 \begin_inset ERT
15751 status Collapsed
15752
15753 \layout Standard
15754
15755 \backslash
15756 /
15757 \end_inset
15758
15759 -xstack
15760 \emph default
15761  option is used
15762 \end_inset
15763 </cell>
15764 </row>
15765 <row topline="true">
15766 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15767 \begin_inset Text
15768
15769 \layout Standard
15770
15771 SDCC_STACK_TENBIT
15772 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
15773
15774 \end_inset
15775
15776
15777 \end_inset
15778 </cell>
15779 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15780 \begin_inset Text
15781
15782 \layout Standard
15783
15784 when
15785 \emph on
15786 -mds390
15787 \emph default
15788  is used
15789 \end_inset
15790 </cell>
15791 </row>
15792 <row topline="true" bottomline="true">
15793 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15794 \begin_inset Text
15795
15796 \layout Standard
15797
15798 SDCC_MODEL_FLAT24
15799 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
15800
15801 \end_inset
15802
15803
15804 \end_inset
15805 </cell>
15806 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15807 \begin_inset Text
15808
15809 \layout Standard
15810
15811 when
15812 \emph on
15813 -mds390
15814 \emph default
15815  is used
15816 \end_inset
15817 </cell>
15818 </row>
15819 </lyxtabular>
15820
15821 \end_inset
15822
15823
15824 \layout Chapter
15825
15826 Notes on supported Processors
15827 \layout Section
15828
15829 MCS51 variants
15830 \begin_inset LatexCommand \label{sub:MCS51-variants}
15831
15832 \end_inset
15833
15834
15835 \begin_inset LatexCommand \index{MCS51 variants}
15836
15837 \end_inset
15838
15839
15840 \layout Standard
15841
15842 MCS51 processors are available from many vendors and come in many different
15843  flavours.
15844  While they might differ considerably in respect to Special Function Registers
15845  the core MCS51 is usually not modified or is kept compatible.
15846
15847 \layout Subsection
15848
15849 pdata access by SFR
15850 \layout Standard
15851
15852 With the upcome of devices with internal xdata and flash memory devices
15853  using port P2
15854 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
15855
15856 \end_inset
15857
15858  as dedicated I/O port is becoming more popular.
15859  Switching the high byte for pdata
15860 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
15861
15862 \end_inset
15863
15864  access which was formerly done by port P2 is then achieved by a Special
15865  Function Register
15866 \begin_inset LatexCommand \index{sfr}
15867
15868 \end_inset
15869
15870 .
15871  In well-established MCS51 tradition the address of this
15872 \emph on
15873 sfr
15874 \emph default
15875  is where the chip designers decided to put it.
15876  Needless to say that they didn't agree on a common name either.
15877  So that the startup code can correctly initialize xdata variables, you
15878  should define an sfr with the name _XPAGE
15879 \family typewriter
15880
15881 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
15882
15883 \end_inset
15884
15885
15886 \family default
15887  at the appropriate location if the default, port P2, is not used for this.
15888  Some examples are:
15889 \layout Verse
15890
15891
15892 \family typewriter
15893 sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
15894 \layout Verse
15895
15896
15897 \family typewriter
15898 sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
15899 \layout Verse
15900
15901
15902 \family typewriter
15903 sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
15904 \layout Standard
15905
15906 For more exotic implementations further customizations may be needed.
15907  See section
15908 \begin_inset LatexCommand \ref{sub:Startup-Code}
15909
15910 \end_inset
15911
15912  for other possibilities.
15913 \layout Subsection
15914
15915 Other Features available by SFR
15916 \layout Standard
15917
15918 Some MCS51 variants offer features like Double DPTR
15919 \begin_inset LatexCommand \index{DPTR}
15920
15921 \end_inset
15922
15923 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
15924  These are currently not used for the MCS51 port.
15925  If you absolutely need them you can fall back to inline assembly or submit
15926  a patch to SDCC.
15927 \layout Section
15928
15929 DS400 port
15930 \layout Standard
15931
15932 The DS80C400 microcontroller has a rich set of peripherals.
15933  In its built-in ROM library it includes functions to access some of the
15934  features, among them is a TCP stack with IP4 and IP6 support.
15935  Library headers (currently in beta status) and other files are provided
15936  at
15937 \size footnotesize
15938
15939 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
15940
15941 \end_inset
15942
15943 .
15944
15945 \layout Section
15946
15947 The Z80 and gbz80 port
15948 \layout Standard
15949
15950 SDCC can target both the Zilog
15951 \begin_inset LatexCommand \index{Z80}
15952
15953 \end_inset
15954
15955  and the Nintendo Gameboy's Z80-like gbz80
15956 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
15957
15958 \end_inset
15959
15960 .
15961  The Z80 port is passed through the same
15962 \emph on
15963 regressions tests
15964 \begin_inset LatexCommand \index{Regression test}
15965
15966 \end_inset
15967
15968
15969 \emph default
15970  as the MCS51 and DS390 ports, so floating point support, support for long
15971  variables and bitfield support is fine.
15972  See mailing lists and forums about interrupt routines.
15973 \layout Standard
15974
15975 As always, the code is the authoritative reference - see z80/ralloc.c and
15976  z80/gen.c.
15977  The stack
15978 \begin_inset LatexCommand \index{stack}
15979
15980 \end_inset
15981
15982  frame is similar to that generated by the IAR Z80 compiler.
15983  IX is used as the base pointer, HL and IY are used as a temporary registers,
15984  and BC and DE are available for holding variables.
15985  Return values
15986 \begin_inset LatexCommand \index{return value}
15987
15988 \end_inset
15989
15990  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
15991  bytes).
15992  The gbz80 port use the same set of registers for the return values, but
15993  in a different order of significance: E (one byte), DE (two bytes), or
15994  HLDE (four bytes).
15995 \layout Section
15996
15997 The HC08 port
15998 \layout Standard
15999
16000 The port to the Motorola HC08
16001 \begin_inset LatexCommand \index{HC08}
16002
16003 \end_inset
16004
16005  family has been added in October 2003, and is still undergoing some basic
16006  development.
16007  The code generator is complete, but the register allocation is still quite
16008  unoptimized.
16009  Some of the SDCC's standard C library functions have embedded non-HC08
16010  inline assembly and so are not yet usable.
16011 \newline
16012
16013 \newline
16014
16015 \layout Section
16016
16017 The PIC14 port
16018 \layout Standard
16019
16020 The 14bit PIC
16021 \begin_inset LatexCommand \index{PIC14}
16022
16023 \end_inset
16024
16025  port still requires a major effort from the development community.
16026  However it can work for very simple code.
16027 \layout Subsection
16028
16029 C code and 14bit PIC code page
16030 \begin_inset LatexCommand \index{code page (pic14)}
16031
16032 \end_inset
16033
16034  and RAM banks
16035 \begin_inset LatexCommand \index{RAM bank (pic14)}
16036
16037 \end_inset
16038
16039
16040 \layout Standard
16041
16042 The linker organizes allocation for the code page and RAM banks.
16043  It does not have intimate knowledge of the code flow.
16044  It will put all the code section of a single asm file into a single code
16045  page.
16046  In order to make use of multiple code pages, separate asm files must be
16047  used.
16048  The compiler treats all functions of a single C file as being in the same
16049  code page unless it is non static.
16050  The compiler treats all local variables of a single C file as being in
16051  the same RAM bank unless it is an extern.
16052 \newline
16053
16054 \newline
16055 To get the best follow these guide lines:
16056 \layout Enumerate
16057
16058 make local functions static, as non static functions require code page selection
16059  overhead.
16060 \layout Enumerate
16061
16062 Make local variables static as extern variables require RAM bank selection
16063  overhead.
16064 \layout Enumerate
16065
16066 For devices that have multiple code pages it is more efficient to use the
16067  same number of files as pages, i.e.
16068  for the 16F877 use 4 separate files and i.e.
16069  for the 16F874 use 2 separate files.
16070  This way the linker can put the code for each file into different code
16071  pages and the compiler can allocate reusable variables more efficiently
16072  and there's less page selection overhead.
16073  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
16074  instruction set) use 'unsigned char' whereever possible instead of 'int'.
16075 \layout Subsection
16076
16077 Creating a device include file
16078 \layout Standard
16079
16080 For generating a device include file use the support perl script inc2h.pl
16081  kept in directory support/script.
16082 \layout Subsection
16083
16084 Interrupt code
16085 \layout Standard
16086
16087 For the interrupt function, use the keyword 'interrupt'
16088 \begin_inset LatexCommand \index{interrupt}
16089
16090 \end_inset
16091
16092  with level number of 0 (PIC14 only has 1 interrupt so this number is only
16093  there to avoid a syntax error - it ought to be fixed).
16094  E.g.:
16095 \layout Verse
16096
16097
16098 \family typewriter
16099 void Intr(void) interrupt 0
16100 \newline
16101 {
16102 \newline
16103 \SpecialChar ~
16104 \SpecialChar ~
16105 T0IF = 0; /* Clear timer interrupt */
16106 \newline
16107 }
16108 \layout Subsection
16109
16110 Linking and assembling
16111 \layout Standard
16112
16113 For assembling you can use either GPUTILS'
16114 \begin_inset LatexCommand \index{gputils (pic tools)}
16115
16116 \end_inset
16117
16118  gpasm.exe or MPLAB's mpasmwin.exe.
16119  GPUTILS is available from
16120 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
16121
16122 \end_inset
16123
16124 .
16125  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
16126  If you use MPLAB and an interrupt function then the linker script file
16127  vectors section will need to be enlarged to link with mplink.
16128 \newline
16129
16130 \newline
16131 Here is a
16132 \family typewriter
16133 Makefile
16134 \family default
16135  using GPUTILS:
16136 \layout Verse
16137
16138
16139 \family typewriter
16140 .c.o:
16141 \newline
16142 \SpecialChar ~
16143 \SpecialChar ~
16144 \SpecialChar ~
16145 \SpecialChar ~
16146 \SpecialChar ~
16147 \SpecialChar ~
16148 \SpecialChar ~
16149 \SpecialChar ~
16150 sdcc -S -V -mpic14 -p16F877 $<
16151 \newline
16152 \SpecialChar ~
16153 \SpecialChar ~
16154 \SpecialChar ~
16155 \SpecialChar ~
16156 \SpecialChar ~
16157 \SpecialChar ~
16158 \SpecialChar ~
16159 \SpecialChar ~
16160 gpasm -c $*.asm
16161 \newline
16162
16163 \newline
16164 $(PRJ).hex: $(OBJS)
16165 \newline
16166 \SpecialChar ~
16167 \SpecialChar ~
16168 \SpecialChar ~
16169 \SpecialChar ~
16170 \SpecialChar ~
16171 \SpecialChar ~
16172 \SpecialChar ~
16173 \SpecialChar ~
16174 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS) libsdcc.lib
16175 \layout Standard
16176
16177 Here is a
16178 \family typewriter
16179 Makefile
16180 \family default
16181  using MPLAB:
16182 \layout Verse
16183
16184
16185 \family typewriter
16186 .c.o:
16187 \newline
16188 \SpecialChar ~
16189 \SpecialChar ~
16190 \SpecialChar ~
16191 \SpecialChar ~
16192 \SpecialChar ~
16193 \SpecialChar ~
16194 \SpecialChar ~
16195 \SpecialChar ~
16196 sdcc -S -V -mpic14 -p16F877 $<
16197 \newline
16198 \SpecialChar ~
16199 \SpecialChar ~
16200 \SpecialChar ~
16201 \SpecialChar ~
16202 \SpecialChar ~
16203 \SpecialChar ~
16204 \SpecialChar ~
16205 \SpecialChar ~
16206 mpasmwin /q /o $*.asm
16207 \newline
16208
16209 \newline
16210 $(PRJ).hex: $(OBJS)
16211 \newline
16212 \SpecialChar ~
16213 \SpecialChar ~
16214 \SpecialChar ~
16215 \SpecialChar ~
16216 \SpecialChar ~
16217 \SpecialChar ~
16218 \SpecialChar ~
16219 \SpecialChar ~
16220 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS) libsdcc.lib
16221 \layout Standard
16222
16223 Please note that indentations within a
16224 \family typewriter
16225  Makefile
16226 \family default
16227  have to be done with a tabulator character.
16228 \layout Subsection
16229
16230 Command-line options
16231 \layout Standard
16232
16233 Besides the switches common to all SDCC backends, the PIC14 port accepts
16234  the following options (for an updated list see sdcc -
16235 \begin_inset ERT
16236 status Collapsed
16237
16238 \layout Standard
16239
16240 \backslash
16241 /
16242 \end_inset
16243
16244 -help):
16245 \layout List
16246 \labelwidthstring 00.00.0000
16247
16248 -
16249 \begin_inset ERT
16250 status Collapsed
16251
16252 \layout Standard
16253
16254 \backslash
16255 /
16256 \end_inset
16257
16258 -debug-extra emit debug info in assembly output
16259 \layout List
16260 \labelwidthstring 00.00.0000
16261
16262 -
16263 \begin_inset ERT
16264 status Collapsed
16265
16266 \layout Standard
16267
16268 \backslash
16269 /
16270 \end_inset
16271
16272 -no-pcode-opt disable (slightly faulty) optimization on pCode
16273 \layout Subsection
16274
16275 The library
16276 \layout Subsubsection
16277
16278 error: missing definition for symbol
16279 \begin_inset Quotes sld
16280 \end_inset
16281
16282 __gptrget1
16283 \begin_inset Quotes srd
16284 \end_inset
16285
16286
16287 \layout Standard
16288
16289 The PIC14 port uses library routines to provide more complex operations
16290  like multiplication, division/modulus and (generic) pointer dereferencing.
16291  In order to add these routines to your project, you must link with PIC14's
16292
16293 \family typewriter
16294 libsdcc.lib
16295 \family default
16296 .
16297  For single source file projects this is done automatically, more complex
16298  projects must add
16299 \family typewriter
16300 libsdcc.lib
16301 \family default
16302  to the linker's arguments.
16303  Make sure you also add an include path for the library (using the -I switch
16304  to the linker)!
16305 \layout Subsubsection
16306
16307 Processor mismatch in file
16308 \begin_inset Quotes sld
16309 \end_inset
16310
16311 XXX
16312 \begin_inset Quotes srd
16313 \end_inset
16314
16315 .
16316 \layout Standard
16317
16318 This warning can usually be ignored due to the very good compatibility amongst
16319  14 bit PIC devices.
16320 \layout Standard
16321
16322 You might also consider recompiling the library for your specific device
16323  by changing the ARCH=p16f877 (default target) entry in
16324 \family typewriter
16325 device/lib/pic/Makefile.in
16326 \family default
16327  and
16328 \family typewriter
16329 device/lib/pic/Makefile
16330 \family default
16331  to reflect your device.
16332  This might even improve performance for smaller devices as unneccesary
16333  BANKSELs migth be removed.
16334 \layout Subsection
16335
16336 Known bugs
16337 \layout Subsubsection
16338
16339 initialized data
16340 \layout Standard
16341
16342 Currently, data can only be initialized if it resides in the source file
16343  together with
16344 \emph on
16345 main()
16346 \emph default
16347 .
16348  Data in other source files will silently
16349 \series bold
16350 not
16351 \series default
16352  be initialized.
16353 \layout Section
16354
16355 The PIC16
16356 \begin_inset LatexCommand \index{PIC16}
16357
16358 \end_inset
16359
16360  port
16361 \layout Standard
16362
16363 The PIC16
16364 \begin_inset LatexCommand \index{PIC16}
16365
16366 \end_inset
16367
16368  port is the portion of SDCC that is responsible to produce code for the
16369  Microchip
16370 \begin_inset LatexCommand \index{Microchip}
16371
16372 \end_inset
16373
16374 (TM) microcontrollers with 16 bit core.
16375  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
16376  Currently supported devices are:
16377 \layout Standard
16378 \align center
16379
16380 \begin_inset  Tabular
16381 <lyxtabular version="3" rows="4" columns="6">
16382 <features>
16383 <column alignment="center" valignment="top" leftline="true" width="0">
16384 <column alignment="center" valignment="top" leftline="true" width="0">
16385 <column alignment="center" valignment="top" leftline="true" width="0">
16386 <column alignment="center" valignment="top" leftline="true" width="0">
16387 <column alignment="center" valignment="top" leftline="true" width="0">
16388 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16389 <row topline="true">
16390 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16391 \begin_inset Text
16392
16393 \layout Standard
16394
16395 18F242
16396 \end_inset
16397 </cell>
16398 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16399 \begin_inset Text
16400
16401 \layout Standard
16402
16403 18F248
16404 \end_inset
16405 </cell>
16406 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16407 \begin_inset Text
16408
16409 \layout Standard
16410
16411 18F252
16412 \end_inset
16413 </cell>
16414 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16415 \begin_inset Text
16416
16417 \layout Standard
16418
16419 18F258
16420 \end_inset
16421 </cell>
16422 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16423 \begin_inset Text
16424
16425 \layout Standard
16426
16427 18F442
16428 \end_inset
16429 </cell>
16430 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16431 \begin_inset Text
16432
16433 \layout Standard
16434
16435 18F448
16436 \end_inset
16437 </cell>
16438 </row>
16439 <row topline="true">
16440 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16441 \begin_inset Text
16442
16443 \layout Standard
16444
16445 18F452
16446 \end_inset
16447 </cell>
16448 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16449 \begin_inset Text
16450
16451 \layout Standard
16452
16453 18F458
16454 \end_inset
16455 </cell>
16456 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16457 \begin_inset Text
16458
16459 \layout Standard
16460
16461 18F1220
16462 \end_inset
16463 </cell>
16464 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16465 \begin_inset Text
16466
16467 \layout Standard
16468
16469 18F2220
16470 \end_inset
16471 </cell>
16472 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16473 \begin_inset Text
16474
16475 \layout Standard
16476
16477 18F2550
16478 \end_inset
16479 </cell>
16480 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16481 \begin_inset Text
16482
16483 \layout Standard
16484
16485 18F4331
16486 \end_inset
16487 </cell>
16488 </row>
16489 <row topline="true">
16490 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16491 \begin_inset Text
16492
16493 \layout Standard
16494
16495 18F4455
16496 \end_inset
16497 </cell>
16498 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16499 \begin_inset Text
16500
16501 \layout Standard
16502
16503 18F6520
16504 \end_inset
16505 </cell>
16506 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16507 \begin_inset Text
16508
16509 \layout Standard
16510
16511 18F6620
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 18F6680
16520 \end_inset
16521 </cell>
16522 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16523 \begin_inset Text
16524
16525 \layout Standard
16526
16527 18F6720
16528 \end_inset
16529 </cell>
16530 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16531 \begin_inset Text
16532
16533 \layout Standard
16534
16535 18F8520
16536 \end_inset
16537 </cell>
16538 </row>
16539 <row topline="true" bottomline="true">
16540 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16541 \begin_inset Text
16542
16543 \layout Standard
16544
16545 18F8620
16546 \end_inset
16547 </cell>
16548 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16549 \begin_inset Text
16550
16551 \layout Standard
16552
16553 18F8680
16554 \end_inset
16555 </cell>
16556 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16557 \begin_inset Text
16558
16559 \layout Standard
16560
16561 18F8720
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 \end_inset
16570 </cell>
16571 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16572 \begin_inset Text
16573
16574 \layout Standard
16575
16576 \end_inset
16577 </cell>
16578 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16579 \begin_inset Text
16580
16581 \layout Standard
16582
16583 \end_inset
16584 </cell>
16585 </row>
16586 </lyxtabular>
16587
16588 \end_inset
16589
16590
16591 \layout Subsection
16592
16593 Global Options
16594 \layout Standard
16595
16596 PIC16 port supports the standard command line arguments as supposed, with
16597  the exception of certain cases that will be mentioned in the following
16598  list:
16599 \layout List
16600 \labelwidthstring 00.00.0000
16601
16602 -
16603 \begin_inset ERT
16604 status Collapsed
16605
16606 \layout Standard
16607
16608 \backslash
16609 /
16610 \end_inset
16611
16612 -callee-saves See -
16613 \begin_inset ERT
16614 status Collapsed
16615
16616 \layout Standard
16617
16618 \backslash
16619 /
16620 \end_inset
16621
16622 -all-callee-saves
16623 \layout List
16624 \labelwidthstring 00.00.0000
16625
16626 -
16627 \begin_inset ERT
16628 status Collapsed
16629
16630 \layout Standard
16631
16632 \backslash
16633 /
16634 \end_inset
16635
16636 -all-callee-saves All function arguments are passed on stack by default.
16637
16638 \emph on
16639 There is no need to specify this in the command line.
16640 \layout List
16641 \labelwidthstring 00.00.0000
16642
16643 -
16644 \begin_inset ERT
16645 status Collapsed
16646
16647 \layout Standard
16648
16649 \backslash
16650 /
16651 \end_inset
16652
16653 -fommit-frame-pointer Frame pointer will be omitted when the function uses
16654  no local variables.
16655 \layout Subsection
16656
16657 Port Specific Options
16658 \begin_inset LatexCommand \index{Options PIC16}
16659
16660 \end_inset
16661
16662
16663 \layout Standard
16664
16665 The port specific options appear after the global options in the sdcc --help
16666  output.
16667 \layout Subsubsection
16668
16669 General Options
16670 \layout Standard
16671
16672 General options enable certain port features and optimizations.
16673 \layout List
16674 \labelwidthstring 00.00.0000
16675
16676 -
16677 \begin_inset ERT
16678 status Collapsed
16679
16680 \layout Standard
16681
16682 \backslash
16683 /
16684 \end_inset
16685
16686 -stack-model=[model] Used in conjuction with the command above.
16687  Defines the stack model to be used, valid stack models are :
16688 \begin_deeper
16689 \layout List
16690 \labelwidthstring 00.00.0000
16691
16692
16693 \emph on
16694 small
16695 \emph default
16696  Selects small stack model.
16697  8 bit stack and frame pointers.
16698  Supports 256 bytes stack size.
16699 \layout List
16700 \labelwidthstring 00.00.0000
16701
16702
16703 \emph on
16704 large
16705 \emph default
16706  Selects large stack model.
16707  16 bit stack and frame pointers.
16708  Supports 65536 bytes stack size.
16709 \end_deeper
16710 \layout List
16711 \labelwidthstring 00.00.0000
16712
16713 -
16714 \begin_inset ERT
16715 status Collapsed
16716
16717 \layout Standard
16718
16719 \backslash
16720 /
16721 \end_inset
16722
16723 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
16724  unitialized data variables with [kword].
16725  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
16726 \layout List
16727 \labelwidthstring 00.00.0000
16728
16729 -
16730 \begin_inset ERT
16731 status Collapsed
16732
16733 \layout Standard
16734
16735 \backslash
16736 /
16737 \end_inset
16738
16739 -ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
16740  Useful for bootloaders.
16741 \layout List
16742 \labelwidthstring 00.00.0000
16743
16744 -
16745 \begin_inset ERT
16746 status Collapsed
16747
16748 \layout Standard
16749
16750 \backslash
16751 /
16752 \end_inset
16753
16754 -asm= sets the full path and name of an external assembler to call.
16755 \layout List
16756 \labelwidthstring 00.00.0000
16757
16758 -
16759 \begin_inset ERT
16760 status Collapsed
16761
16762 \layout Standard
16763
16764 \backslash
16765 /
16766 \end_inset
16767
16768 -link= sets the full path and name of an external linker to call.
16769 \layout List
16770 \labelwidthstring 00.00.0000
16771
16772 -
16773 \begin_inset ERT
16774 status Collapsed
16775
16776 \layout Standard
16777
16778 \backslash
16779 /
16780 \end_inset
16781
16782 -mplab-comp MPLAB compatibility option.
16783  Currently only suppresses special gpasm directives.
16784 \layout Subsubsection
16785
16786 Optimization Options
16787 \layout List
16788 \labelwidthstring 00.00.0000
16789
16790 -
16791 \begin_inset ERT
16792 status Collapsed
16793
16794 \layout Standard
16795
16796 \backslash
16797 /
16798 \end_inset
16799
16800 -optimize-goto Try to use (conditional) BRA instead of GOTO
16801 \layout List
16802 \labelwidthstring 00.00.0000
16803
16804 -
16805 \begin_inset ERT
16806 status Collapsed
16807
16808 \layout Standard
16809
16810 \backslash
16811 /
16812 \end_inset
16813
16814 -optimize-cmp Try to optimize some compares.
16815 \layout List
16816 \labelwidthstring 00.00.0000
16817
16818 -
16819 \begin_inset ERT
16820 status Collapsed
16821
16822 \layout Standard
16823
16824 \backslash
16825 /
16826 \end_inset
16827
16828 -optimize-df Analyze the dataflow of the generated code and improve it.
16829 \layout List
16830 \labelwidthstring 00.00.0000
16831
16832 -
16833 \begin_inset ERT
16834 status Collapsed
16835
16836 \layout Standard
16837
16838 \backslash
16839 /
16840 \end_inset
16841
16842 -obanksel=nn Set optimization level for inserting BANKSELs.
16843 \newline
16844
16845 \begin_deeper
16846 \layout List
16847 \labelwidthstring 00.00.0000
16848
16849 0 no optimization
16850 \layout List
16851 \labelwidthstring 00.00.0000
16852
16853 1 checks previous used register and if it is the same then does not emit
16854  BANKSEL, accounts only for labels.
16855 \layout List
16856 \labelwidthstring 00.00.0000
16857
16858 2 tries to check the location of (even different) symbols and removes BANKSELs
16859  if they are in the same bank.
16860
16861 \newline
16862
16863 \emph on
16864 Important: There might be problems if the linker script has data sections
16865  across bank borders!
16866 \end_deeper
16867 \layout Subsubsection
16868
16869 Linking Options
16870 \layout List
16871 \labelwidthstring 00.00.0000
16872
16873 -
16874 \begin_inset ERT
16875 status Collapsed
16876
16877 \layout Standard
16878
16879 \backslash
16880 /
16881 \end_inset
16882
16883 -nodefaultlibs do not link default libraries when linking
16884 \layout List
16885 \labelwidthstring 00.00.0000
16886
16887 -
16888 \begin_inset ERT
16889 status Collapsed
16890
16891 \layout Standard
16892
16893 \backslash
16894 /
16895 \end_inset
16896
16897 -no-crt Don't link the default run-time modules
16898 \layout List
16899 \labelwidthstring 00.00.0000
16900
16901 -
16902 \begin_inset ERT
16903 status Collapsed
16904
16905 \layout Standard
16906
16907 \backslash
16908 /
16909 \end_inset
16910
16911 -use-crt= Use a custom run-time module instead of the defaults.
16912 \layout Subsubsection
16913
16914 Debugging Options
16915 \layout Standard
16916
16917 Debugging options enable extra debugging information in the output files.
16918 \layout List
16919 \labelwidthstring 00.00.0000
16920
16921 -
16922 \begin_inset ERT
16923 status Collapsed
16924
16925 \layout Standard
16926
16927 \backslash
16928 /
16929 \end_inset
16930
16931 -debug-xtra Similar to -
16932 \begin_inset ERT
16933 status Collapsed
16934
16935 \layout Standard
16936
16937 \backslash
16938 /
16939 \end_inset
16940
16941 -debug
16942 \begin_inset LatexCommand \index{-\/-debug}
16943
16944 \end_inset
16945
16946 , but dumps more information.
16947 \layout List
16948 \labelwidthstring 00.00.0000
16949
16950 -
16951 \begin_inset ERT
16952 status Collapsed
16953
16954 \layout Standard
16955
16956 \backslash
16957 /
16958 \end_inset
16959
16960 -debug-ralloc Force register allocator to dump <source>.d file with debugging
16961  information.
16962  <source> is the name of the file compiled.
16963 \layout List
16964 \labelwidthstring 00.00.0000
16965
16966 -
16967 \begin_inset ERT
16968 status Collapsed
16969
16970 \layout Standard
16971
16972 \backslash
16973 /
16974 \end_inset
16975
16976 -pcode-verbose Enable pcode debugging information in translation.
16977 \layout List
16978 \labelwidthstring 00.00.0000
16979
16980 -
16981 \begin_inset ERT
16982 status Collapsed
16983
16984 \layout Standard
16985
16986 \backslash
16987 /
16988 \end_inset
16989
16990 -denable-peeps Force the usage of peepholes.
16991  Use with care.
16992 \layout List
16993 \labelwidthstring 00.00.0000
16994
16995 -
16996 \begin_inset ERT
16997 status Collapsed
16998
16999 \layout Standard
17000
17001 \backslash
17002 /
17003 \end_inset
17004
17005 -gstack Trace push/pops for stack pointer overflow
17006 \layout List
17007 \labelwidthstring 00.00.0000
17008
17009 -
17010 \begin_inset ERT
17011 status Collapsed
17012
17013 \layout Standard
17014
17015 \backslash
17016 /
17017 \end_inset
17018
17019 -call-tree dump call tree in .calltree file
17020 \layout Subsection
17021
17022 Enviromental Variables
17023 \layout Standard
17024
17025 There is a number of enviromental variables that can be used when running
17026  SDCC to enable certain optimizations or force a specific program behaviour.
17027  these variables are primarily for debugging purposes so they can be enabled/dis
17028 abled at will.
17029 \layout Standard
17030
17031 Currently there is only two such variables available:
17032 \layout List
17033 \labelwidthstring 00.00.0000
17034
17035 OPTIMIZE_BITFIELD_POINTER_GET when this variable exists reading of structure
17036  bitfields is optimized by directly loading FSR0 with the address of the
17037  bitfield structure.
17038  Normally SDCC will cast the bitfield structure to a bitfield pointer and
17039  then load FSR0.
17040  This step saves data ram and code space for functions that perform heavy
17041  use of bitfields.
17042  (ie.
17043  80 bytes of code space are saved when compiling malloc.c with this option).
17044
17045 \layout List
17046 \labelwidthstring 00.00.0000
17047
17048 NO_REG_OPT do not perform pCode registers optimization.
17049  This should be used for debugging purposes.
17050  In some where bugs in the pcode optimizer are found, users can benefit
17051  from temporarily disabling the optimizer until the bug is fixed.
17052 \layout Subsection
17053
17054 Preprocessor Macros
17055 \layout Standard
17056
17057 PIC16 port defines the following preprocessor macros while translating a
17058  source.
17059 \layout Standard
17060 \align center
17061
17062 \begin_inset  Tabular
17063 <lyxtabular version="3" rows="6" columns="2">
17064 <features>
17065 <column alignment="center" valignment="top" leftline="true" width="0">
17066 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17067 <row topline="true" bottomline="true">
17068 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17069 \begin_inset Text
17070
17071 \layout Standard
17072
17073 Macro
17074 \end_inset
17075 </cell>
17076 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17077 \begin_inset Text
17078
17079 \layout Standard
17080
17081 Description
17082 \end_inset
17083 </cell>
17084 </row>
17085 <row topline="true">
17086 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17087 \begin_inset Text
17088
17089 \layout Standard
17090
17091 SDCC_pic16
17092 \end_inset
17093 </cell>
17094 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17095 \begin_inset Text
17096
17097 \layout Standard
17098
17099 Port identification
17100 \end_inset
17101 </cell>
17102 </row>
17103 <row topline="true">
17104 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17105 \begin_inset Text
17106
17107 \layout Standard
17108
17109 _
17110 \begin_inset ERT
17111 status Collapsed
17112
17113 \layout Standard
17114
17115 \backslash
17116 /
17117 \end_inset
17118
17119 _pic16
17120 \end_inset
17121 </cell>
17122 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17123 \begin_inset Text
17124
17125 \layout Standard
17126
17127 Port identification (same as above)
17128 \end_inset
17129 </cell>
17130 </row>
17131 <row topline="true">
17132 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17133 \begin_inset Text
17134
17135 \layout Standard
17136
17137 pic18fxxxx
17138 \end_inset
17139 </cell>
17140 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17141 \begin_inset Text
17142
17143 \layout Standard
17144
17145 MCU Identification.
17146
17147 \emph on
17148 xxxx
17149 \emph default
17150  is the microcontrol identification number, i.e.
17151  452, 6620, etc
17152 \end_inset
17153 </cell>
17154 </row>
17155 <row topline="true">
17156 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17157 \begin_inset Text
17158
17159 \layout Standard
17160
17161 _
17162 \begin_inset ERT
17163 status Collapsed
17164
17165 \layout Standard
17166
17167 \backslash
17168 /
17169 \end_inset
17170
17171 _18Fxxxx
17172 \end_inset
17173 </cell>
17174 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17175 \begin_inset Text
17176
17177 \layout Standard
17178
17179 MCU Identification (same as above)
17180 \end_inset
17181 </cell>
17182 </row>
17183 <row topline="true" bottomline="true">
17184 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17185 \begin_inset Text
17186
17187 \layout Standard
17188
17189 STACK_MODEL_nnn
17190 \end_inset
17191 </cell>
17192 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17193 \begin_inset Text
17194
17195 \layout Standard
17196
17197 nnn = SMALL or LARGE respectively according to the stack model used
17198 \end_inset
17199 </cell>
17200 </row>
17201 </lyxtabular>
17202
17203 \end_inset
17204
17205
17206 \layout Standard
17207
17208 In addition the following macros are defined when calling assembler:
17209 \layout Standard
17210 \align center
17211
17212 \begin_inset  Tabular
17213 <lyxtabular version="3" rows="4" columns="2">
17214 <features>
17215 <column alignment="center" valignment="top" leftline="true" width="0">
17216 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17217 <row topline="true" bottomline="true">
17218 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17219 \begin_inset Text
17220
17221 \layout Standard
17222
17223 Macro
17224 \end_inset
17225 </cell>
17226 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17227 \begin_inset Text
17228
17229 \layout Standard
17230
17231 Description
17232 \end_inset
17233 </cell>
17234 </row>
17235 <row topline="true">
17236 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17237 \begin_inset Text
17238
17239 \layout Standard
17240
17241 __18Fxxxx
17242 \end_inset
17243 </cell>
17244 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17245 \begin_inset Text
17246
17247 \layout Standard
17248
17249 MCU Identification.
17250
17251 \emph on
17252 xxxx
17253 \emph default
17254  is the microcontrol identification number, i.e.
17255  452, 6620, etc
17256 \end_inset
17257 </cell>
17258 </row>
17259 <row topline="true">
17260 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17261 \begin_inset Text
17262
17263 \layout Standard
17264
17265 SDCC_MODEL_nnn
17266 \end_inset
17267 </cell>
17268 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17269 \begin_inset Text
17270
17271 \layout Standard
17272
17273 nnn = SMALL or LARGE respectively according to the memory model used for
17274  SDCC
17275 \end_inset
17276 </cell>
17277 </row>
17278 <row topline="true" bottomline="true">
17279 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17280 \begin_inset Text
17281
17282 \layout Standard
17283
17284 STACK_MODEL_nnn
17285 \end_inset
17286 </cell>
17287 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17288 \begin_inset Text
17289
17290 \layout Standard
17291
17292 nnn = SMALL or LARGE respectively according to the stack model used
17293 \end_inset
17294 </cell>
17295 </row>
17296 </lyxtabular>
17297
17298 \end_inset
17299
17300
17301 \layout Subsection
17302
17303 Directories
17304 \layout Standard
17305
17306 PIC16
17307 \begin_inset LatexCommand \index{PIC16}
17308
17309 \end_inset
17310
17311  port uses the following directories for searching header files and libraries.
17312 \layout Standard
17313 \align center
17314
17315 \begin_inset  Tabular
17316 <lyxtabular version="3" rows="3" columns="4">
17317 <features>
17318 <column alignment="center" valignment="top" leftline="true" width="0">
17319 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17320 <column alignment="center" valignment="top" width="0">
17321 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17322 <row topline="true" bottomline="true">
17323 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17324 \begin_inset Text
17325
17326 \layout Standard
17327
17328 Directory
17329 \end_inset
17330 </cell>
17331 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17332 \begin_inset Text
17333
17334 \layout Standard
17335
17336 Description
17337 \end_inset
17338 </cell>
17339 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17340 \begin_inset Text
17341
17342 \layout Standard
17343
17344 Target
17345 \end_inset
17346 </cell>
17347 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17348 \begin_inset Text
17349
17350 \layout Standard
17351
17352 Command prefix
17353 \end_inset
17354 </cell>
17355 </row>
17356 <row topline="true">
17357 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17358 \begin_inset Text
17359
17360 \layout Standard
17361
17362 PREFIX/sdcc/include/pic16
17363 \end_inset
17364 </cell>
17365 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17366 \begin_inset Text
17367
17368 \layout Standard
17369
17370 PIC16 specific headers
17371 \end_inset
17372 </cell>
17373 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17374 \begin_inset Text
17375
17376 \layout Standard
17377
17378 Compiler
17379 \end_inset
17380 </cell>
17381 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17382 \begin_inset Text
17383
17384 \layout Standard
17385
17386 -I
17387 \end_inset
17388 </cell>
17389 </row>
17390 <row topline="true" bottomline="true">
17391 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17392 \begin_inset Text
17393
17394 \layout Standard
17395
17396 PREFIX/sdcc/lib/pic16
17397 \end_inset
17398 </cell>
17399 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17400 \begin_inset Text
17401
17402 \layout Standard
17403
17404 PIC16 specific libraries
17405 \end_inset
17406 </cell>
17407 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17408 \begin_inset Text
17409
17410 \layout Standard
17411
17412 Linker
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 -L
17421 \end_inset
17422 </cell>
17423 </row>
17424 </lyxtabular>
17425
17426 \end_inset
17427
17428
17429 \layout Subsection
17430
17431 Pragmas
17432 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
17433
17434 \end_inset
17435
17436
17437 \layout Standard
17438
17439 PIC16 port currently supports the following pragmas:
17440 \layout List
17441 \labelwidthstring 00.00.0000
17442
17443 stack pragma stack forces the code generator to initialize the stack & frame
17444  pointers at a specific address.
17445  This is an adhoc solution for cases where no STACK directive is available
17446  in the linker script or gplink is not instructed to create a stack section.
17447 \newline
17448 The stack pragma should be used only once in a project.
17449  Multiple pragmas may result in indeterminate behaviour of the program.
17450 \begin_inset Foot
17451 collapsed false
17452
17453 \layout Standard
17454
17455 The old format (ie.
17456  #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
17457  cross page boundaries (or even exceed the available data RAM) and crash
17458  the program.
17459  Make sure that stack does not cross page boundaries when using the SMALL
17460  stack model.
17461 \end_inset
17462
17463
17464 \newline
17465 The format is as follows:
17466 \layout LyX-Code
17467
17468 #pragma stack bottom_address [stack_size]
17469 \layout Standard
17470
17471
17472 \emph on
17473 bottom_address
17474 \emph default
17475  is the lower bound of the stack section.
17476  The stack pointer initially will point at address (bottom_address+stack_size-1).
17477 \layout LyX-Code
17478
17479 Example:
17480 \layout LyX-Code
17481
17482 \layout LyX-Code
17483
17484 /* initializes stack of 100 bytes at RAM address 0x200 */
17485 \layout LyX-Code
17486
17487 #pragma stack 0x200 100
17488 \layout Standard
17489
17490 If the stack_size field is omitted then a stack is created with the default
17491  size of 64.
17492  This size might be enough for most programs, but its not enough for operations
17493  with deep function nesting or excessive stack usage.
17494 \layout List
17495 \labelwidthstring 00.00.0000
17496
17497 wparam
17498 \emph on
17499 This pragma is deprecated.
17500  Its use will cause a warning message to be issued.
17501 \emph default
17502
17503 \newline
17504
17505 \layout List
17506 \labelwidthstring 00.00.0000
17507
17508 code place a function symbol at static FLASH address
17509 \layout LyX-Code
17510
17511 Example:
17512 \layout LyX-Code
17513
17514 \layout LyX-Code
17515
17516 /* place function test_func at 0x4000 */
17517 \layout LyX-Code
17518
17519 #pragma code test_func 0x4000
17520 \layout LyX-Code
17521
17522 \layout List
17523 \labelwidthstring 00.00.0000
17524
17525 library instructs the linker to use a library module.
17526 \newline
17527 Usage:
17528 \layout LyX-Code
17529
17530 #pragma library module_name
17531 \layout Standard
17532
17533
17534 \emph on
17535 module_name
17536 \emph default
17537  can be any library or object file (including its path).
17538  Note that there are four reserved keywords which have special meaning.
17539  These are:
17540 \layout Standard
17541 \align center
17542
17543 \begin_inset  Tabular
17544 <lyxtabular version="3" rows="6" columns="3">
17545 <features>
17546 <column alignment="center" valignment="top" leftline="true" width="0">
17547 <column alignment="block" valignment="top" leftline="true" width="20page%">
17548 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
17549 <row topline="true" bottomline="true">
17550 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17551 \begin_inset Text
17552
17553 \layout Standard
17554
17555 Keyword
17556 \end_inset
17557 </cell>
17558 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17559 \begin_inset Text
17560
17561 \layout Standard
17562
17563 Description
17564 \end_inset
17565 </cell>
17566 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17567 \begin_inset Text
17568
17569 \layout Standard
17570
17571 Module to link
17572 \end_inset
17573 </cell>
17574 </row>
17575 <row topline="true">
17576 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17577 \begin_inset Text
17578
17579 \layout Standard
17580
17581
17582 \series bold
17583 ignore
17584 \end_inset
17585 </cell>
17586 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17587 \begin_inset Text
17588
17589 \layout Standard
17590
17591 ignore all library pragmas
17592 \end_inset
17593 </cell>
17594 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17595 \begin_inset Text
17596
17597 \layout Standard
17598
17599
17600 \emph on
17601 (none)
17602 \end_inset
17603 </cell>
17604 </row>
17605 <row topline="true">
17606 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17607 \begin_inset Text
17608
17609 \layout Standard
17610
17611
17612 \series bold
17613 c
17614 \end_inset
17615 </cell>
17616 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17617 \begin_inset Text
17618
17619 \layout Standard
17620
17621 link the C library
17622 \end_inset
17623 </cell>
17624 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17625 \begin_inset Text
17626
17627 \layout Standard
17628
17629
17630 \emph on
17631 libc18f
17632 \emph default
17633 .lib
17634 \end_inset
17635 </cell>
17636 </row>
17637 <row topline="true">
17638 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17639 \begin_inset Text
17640
17641 \layout Standard
17642
17643
17644 \series bold
17645 math
17646 \end_inset
17647 </cell>
17648 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17649 \begin_inset Text
17650
17651 \layout Standard
17652
17653 link the Math libarary
17654 \end_inset
17655 </cell>
17656 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17657 \begin_inset Text
17658
17659 \layout Standard
17660
17661
17662 \emph on
17663 libm18f
17664 \emph default
17665 .lib
17666 \end_inset
17667 </cell>
17668 </row>
17669 <row topline="true">
17670 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17671 \begin_inset Text
17672
17673 \layout Standard
17674
17675
17676 \series bold
17677 io
17678 \end_inset
17679 </cell>
17680 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17681 \begin_inset Text
17682
17683 \layout Standard
17684
17685 link the I/O library
17686 \end_inset
17687 </cell>
17688 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17689 \begin_inset Text
17690
17691 \layout Standard
17692
17693
17694 \emph on
17695 libio18f*
17696 \emph default
17697 .lib
17698 \end_inset
17699 </cell>
17700 </row>
17701 <row topline="true" bottomline="true">
17702 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17703 \begin_inset Text
17704
17705 \layout Standard
17706
17707
17708 \series bold
17709 debug
17710 \end_inset
17711 </cell>
17712 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17713 \begin_inset Text
17714
17715 \layout Standard
17716
17717 link the debug library
17718 \end_inset
17719 </cell>
17720 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17721 \begin_inset Text
17722
17723 \layout Standard
17724
17725
17726 \emph on
17727 libdebug
17728 \emph default
17729 .lib
17730 \end_inset
17731 </cell>
17732 </row>
17733 </lyxtabular>
17734
17735 \end_inset
17736
17737
17738 \newline
17739 * is the device number, i.e.
17740  452 for PIC18F452 MCU.
17741 \layout Standard
17742
17743 This feature allows for linking with specific libraries withoug having to
17744  explicit name them in the command line.
17745  Note that the
17746 \noun on
17747 ignore
17748 \noun default
17749  keyword will reject all modules specified by the library pragma.
17750 \layout List
17751 \labelwidthstring 00.00.0000
17752
17753 udata pragma udata instructs the compiler to emit code so that linker will
17754  place a variable at a specific memory bank
17755 \layout LyX-Code
17756
17757 Example:
17758 \layout LyX-Code
17759
17760 \layout LyX-Code
17761
17762 /* places variable foo at bank2 */
17763 \layout LyX-Code
17764
17765 #pragma udata bank2 foo
17766 \layout LyX-Code
17767
17768 char foo;
17769 \layout Standard
17770
17771 In order for this pragma to work extra SECTION directives should be added
17772  in the .lkr script.
17773  In the following example a sample .lkr file is shown:
17774 \layout LyX-Code
17775
17776 \layout LyX-Code
17777
17778 // Sample linker script for the PIC18F452 processor
17779 \layout LyX-Code
17780
17781 LIBPATH .
17782 \layout LyX-Code
17783
17784 CODEPAGE   NAME=vectors    START=0x0            END=0x29           PROTECTED
17785 \layout LyX-Code
17786
17787 CODEPAGE   NAME=page       START=0x2A           END=0x7FFF
17788 \layout LyX-Code
17789
17790 CODEPAGE   NAME=idlocs     START=0x200000       END=0x200007       PROTECTED
17791 \layout LyX-Code
17792
17793 CODEPAGE   NAME=config     START=0x300000       END=0x30000D       PROTECTED
17794 \layout LyX-Code
17795
17796 CODEPAGE   NAME=devid      START=0x3FFFFE       END=0x3FFFFF       PROTECTED
17797 \layout LyX-Code
17798
17799 CODEPAGE   NAME=eedata     START=0xF00000       END=0xF000FF       PROTECTED
17800 \layout LyX-Code
17801
17802 ACCESSBANK NAME=accessram  START=0x0            END=0x7F
17803 \layout LyX-Code
17804
17805 \layout LyX-Code
17806
17807 DATABANK   NAME=gpr0       START=0x80           END=0xFF
17808 \layout LyX-Code
17809
17810 DATABANK   NAME=gpr1       START=0x100          END=0x1FF
17811 \layout LyX-Code
17812
17813 DATABANK   NAME=gpr2       START=0x200          END=0x2FF
17814 \layout LyX-Code
17815
17816 DATABANK   NAME=gpr3       START=0x300          END=0x3FF
17817 \layout LyX-Code
17818
17819 DATABANK   NAME=gpr4       START=0x400          END=0x4FF
17820 \layout LyX-Code
17821
17822 DATABANK   NAME=gpr5       START=0x500          END=0x5FF
17823 \layout LyX-Code
17824
17825 ACCESSBANK NAME=accesssfr  START=0xF80          END=0xFFF          PROTECTED
17826 \layout LyX-Code
17827
17828 \layout LyX-Code
17829
17830 SECTION    NAME=CONFIG     ROM=config
17831 \layout LyX-Code
17832
17833 \layout LyX-Code
17834
17835 SECTION    NAME=bank0      RAM=gpr0       # these SECTION directives
17836 \layout LyX-Code
17837
17838 SECTION    NAME=bank1      RAM=gpr1       # should be added to link
17839 \layout LyX-Code
17840
17841 SECTION    NAME=bank2      RAM=gpr2       # section name 'bank?' with
17842 \layout LyX-Code
17843
17844 SECTION    NAME=bank3      RAM=gpr3       # a specific DATABANK name
17845 \layout LyX-Code
17846
17847 SECTION    NAME=bank4      RAM=gpr4
17848 \layout LyX-Code
17849
17850 SECTION    NAME=bank5      RAM=gpr5
17851 \layout Standard
17852
17853 The linker will recognise the section name set in the pragma statement and
17854  will position the variable at the memory bank set with the RAM field at
17855  the SECTION line in the linker script file.
17856 \layout Subsection
17857
17858 Header Files
17859 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
17860
17861 \end_inset
17862
17863
17864 \layout Standard
17865
17866 There is one main header file that can be included to the source files using
17867  the pic16 port.
17868  That file is the
17869 \series bold
17870 pic18fregs.h
17871 \series default
17872 .
17873  This header file contains the definitions for the processor special registers,
17874  so it is necessary if the source accesses them.
17875  It can be included by adding the following line in the beginning of the
17876  file:
17877 \layout LyX-Code
17878
17879 #include <pic18fregs.h>
17880 \layout Standard
17881
17882 The specific microcontroller is selected within the pic18fregs.h automatically,
17883  so the same source can be used with a variety of devices.
17884 \layout Subsection
17885
17886 Libraries
17887 \layout Standard
17888
17889 The libraries that PIC16
17890 \begin_inset LatexCommand \index{PIC16}
17891
17892 \end_inset
17893
17894  port depends on are the microcontroller device libraries which contain
17895  the symbol definitions for the microcontroller special function registers.
17896  These libraries have the format pic18fxxxx.lib, where
17897 \emph on
17898 xxxx
17899 \emph default
17900  is the microcontroller identification number.
17901  The specific library is selected automatically by the compiler at link
17902  stage according to the selected device.
17903 \layout Standard
17904
17905 Libraries are created with gplib which is part of the gputils package
17906 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
17907
17908 \end_inset
17909
17910 .
17911 \layout Subsubsection*
17912
17913 Building the libraries
17914 \layout Standard
17915
17916 Before using SDCC/pic16 there are some libraries that need to be compiled.
17917  This process is not done automatically by SDCC since not all users use
17918  SDCC for pic16 projects.
17919  So each user should compile the libraries separately.
17920 \layout Standard
17921
17922 The steps to compile the pic16 libraries under Linux are:
17923 \layout LyX-Code
17924
17925 cd device/lib/pic16
17926 \layout LyX-Code
17927
17928 ./configure
17929 \layout LyX-Code
17930
17931 make
17932 \layout LyX-Code
17933
17934 cd ..
17935 \layout LyX-Code
17936
17937 make model-pic16
17938 \layout LyX-Code
17939
17940 su -c 'make install'     # install the libraries, you need the root password
17941 \layout Standard
17942
17943 If you need to install the headers too, do:
17944 \layout LyX-Code
17945
17946 cd device/include
17947 \layout LyX-Code
17948
17949 su -c 'make install'     # install the headers, you need the root password
17950 \layout Standard
17951
17952 There exist a special target to build the I/O libraries.
17953  This target is not automatically build because it will build the I/O library
17954  for
17955 \emph on
17956 every
17957 \emph default
17958  supported device.
17959  This way building will take quite a lot of time.
17960  Users are advised to edit the
17961 \series bold
17962 device/lib/pic16/pics.build
17963 \series default
17964  file and then execute:
17965 \layout LyX-Code
17966
17967 make lib-io
17968 \layout Subsection
17969
17970 Memory Models
17971 \layout Standard
17972
17973 The following memory models are supported by the PIC16 port:
17974 \layout Itemize
17975
17976 small model
17977 \layout Itemize
17978
17979 large model
17980 \layout Standard
17981
17982 Memory model affects the default size of pointers within the source.
17983  The sizes are shown in the next table:
17984 \layout Standard
17985 \align center
17986
17987 \begin_inset  Tabular
17988 <lyxtabular version="3" rows="3" columns="3">
17989 <features>
17990 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17991 <column alignment="center" valignment="top" leftline="true" width="0">
17992 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17993 <row topline="true" bottomline="true">
17994 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17995 \begin_inset Text
17996
17997 \layout Standard
17998
17999 Pointer sizes according to memory model
18000 \end_inset
18001 </cell>
18002 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18003 \begin_inset Text
18004
18005 \layout Standard
18006
18007 small model
18008 \end_inset
18009 </cell>
18010 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18011 \begin_inset Text
18012
18013 \layout Standard
18014
18015 large model
18016 \end_inset
18017 </cell>
18018 </row>
18019 <row topline="true" bottomline="true">
18020 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18021 \begin_inset Text
18022
18023 \layout Standard
18024
18025 code pointers
18026 \end_inset
18027 </cell>
18028 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18029 \begin_inset Text
18030
18031 \layout Standard
18032
18033 16-bits
18034 \end_inset
18035 </cell>
18036 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18037 \begin_inset Text
18038
18039 \layout Standard
18040
18041 24-bits
18042 \end_inset
18043 </cell>
18044 </row>
18045 <row topline="true" bottomline="true">
18046 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18047 \begin_inset Text
18048
18049 \layout Standard
18050
18051 data pointers
18052 \end_inset
18053 </cell>
18054 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
18055 \begin_inset Text
18056
18057 \layout Standard
18058
18059 16-bits
18060 \end_inset
18061 </cell>
18062 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18063 \begin_inset Text
18064
18065 \layout Standard
18066
18067 16-bits
18068 \end_inset
18069 </cell>
18070 </row>
18071 </lyxtabular>
18072
18073 \end_inset
18074
18075
18076 \layout Standard
18077
18078 It is advisable that all sources within a project are compiled with the
18079  same memory model.
18080  If one wants to override the default memory model, this can be done by
18081  declaring a pointer as
18082 \series bold
18083 far
18084 \series default
18085  or
18086 \series bold
18087 near
18088 \series default
18089 .
18090  Far selects large memory model's pointers, while near selects small memory
18091  model's pointers.
18092 \layout Standard
18093
18094 The standard device libraries (see
18095 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
18096
18097 \end_inset
18098
18099 ) contain no reference to pointers, so they can be used with both memory
18100  models.
18101 \layout Subsection
18102
18103 Stack
18104 \layout Standard
18105
18106 The stack implementation for the PIC16 port uses two indirect registers,
18107  FSR1 and FSR2.
18108 \layout List
18109 \labelwidthstring 00.00.0000
18110
18111 FSR1 is assigned as stack pointer
18112 \layout List
18113 \labelwidthstring 00.00.0000
18114
18115 FSR2 is assigned as frame pointer
18116 \layout Standard
18117
18118 The following stack models are supported by the PIC16 port
18119 \layout Itemize
18120
18121
18122 \noun on
18123 small
18124 \noun default
18125  model
18126 \layout Itemize
18127
18128
18129 \noun on
18130 large
18131 \noun default
18132  model
18133 \layout Standard
18134
18135
18136 \noun on
18137 Small
18138 \noun default
18139  model means that only the FSRxL byte is used to access stack and frame,
18140  while
18141 \emph on
18142 \noun on
18143 large
18144 \emph default
18145 \noun default
18146  uses both FSRxL and FSRxH registers.
18147  The following table shows the stack/frame pointers sizes according to stack
18148  model and the maximum space they can address:
18149 \layout Standard
18150 \align center
18151
18152 \begin_inset  Tabular
18153 <lyxtabular version="3" rows="3" columns="3">
18154 <features>
18155 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18156 <column alignment="center" valignment="top" leftline="true" width="0">
18157 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18158 <row topline="true" bottomline="true">
18159 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18160 \begin_inset Text
18161
18162 \layout Standard
18163
18164 Stack & Frame pointer sizes according to stack model
18165 \end_inset
18166 </cell>
18167 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18168 \begin_inset Text
18169
18170 \layout Standard
18171
18172 small
18173 \end_inset
18174 </cell>
18175 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18176 \begin_inset Text
18177
18178 \layout Standard
18179
18180 large
18181 \end_inset
18182 </cell>
18183 </row>
18184 <row topline="true">
18185 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18186 \begin_inset Text
18187
18188 \layout Standard
18189
18190 Stack pointer FSR1
18191 \end_inset
18192 </cell>
18193 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18194 \begin_inset Text
18195
18196 \layout Standard
18197
18198 8-bits
18199 \end_inset
18200 </cell>
18201 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18202 \begin_inset Text
18203
18204 \layout Standard
18205
18206 16-bits
18207 \end_inset
18208 </cell>
18209 </row>
18210 <row topline="true" bottomline="true">
18211 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18212 \begin_inset Text
18213
18214 \layout Standard
18215
18216 Frame pointer FSR2
18217 \end_inset
18218 </cell>
18219 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18220 \begin_inset Text
18221
18222 \layout Standard
18223
18224 8-bits
18225 \end_inset
18226 </cell>
18227 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18228 \begin_inset Text
18229
18230 \layout Standard
18231
18232 16-bits
18233 \end_inset
18234 </cell>
18235 </row>
18236 </lyxtabular>
18237
18238 \end_inset
18239
18240
18241 \layout Standard
18242
18243
18244 \noun on
18245 Large
18246 \noun default
18247 stack model is currently not working properly throughout the code generator.
18248  So its use is not advised.
18249  Also there are some other points that need special care:
18250 \newline
18251
18252 \layout Enumerate
18253
18254 Do not create stack sections with size more than one physical bank (that
18255  is 256 bytes)
18256 \layout Enumerate
18257
18258 Stack sections should no cross physical bank limits (i.e.
18259  #pragma stack 0x50 0x100)
18260 \layout Standard
18261
18262 These limitations are caused by the fact that only FSRxL is modified when
18263  using SMALL stack model, so no more than 256 bytes of stack can be used.
18264  This problem will disappear after LARGE model is fully implemented.
18265 \layout Subsection
18266
18267 Functions
18268 \layout Standard
18269
18270 In addition to the standard SDCC function keywords, PIC16 port makes available
18271  two more:
18272 \layout List
18273 \labelwidthstring 00.00.0000
18274
18275 wparam Use the WREG to pass one byte of the first function argument.
18276  This improves speed but you may not use this for functions with arguments
18277  that are called via function pointers, otherwise the first byte of the
18278  first parameter will get lost.
18279  Usage:
18280 \layout LyX-Code
18281
18282 void func_wparam(int a) wparam
18283 \layout LyX-Code
18284
18285 {
18286 \layout LyX-Code
18287
18288     /* WREG hold the lower part of a */
18289 \layout LyX-Code
18290
18291     /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
18292  */
18293 \layout LyX-Code
18294
18295 ...
18296 \layout LyX-Code
18297
18298 }
18299 \layout Standard
18300
18301 This keyword replaces the deprecated wparam pragma.
18302 \layout List
18303 \labelwidthstring 00.00.0000
18304
18305 shadowregs When entering/exiting an ISR, it is possible to take advantage
18306  of the PIC18F hardware shadow registers which hold the values of WREG,
18307  STATUS and BSR registers.
18308  This can be done by adding the keyword
18309 \emph on
18310 shadowregs
18311 \emph default
18312  before the
18313 \emph on
18314 interrupt
18315 \emph default
18316  keyword in the function's header.
18317 \layout LyX-Code
18318
18319 void isr_shadow(void) shadowregs interrupt 1
18320 \layout LyX-Code
18321
18322 {
18323 \layout LyX-Code
18324
18325 ...
18326 \layout LyX-Code
18327
18328 }
18329 \layout Standard
18330
18331
18332 \emph on
18333 shadowregs
18334 \emph default
18335  instructs the code generator not to store/restore WREG, STATUS, BSR when
18336  entering/exiting the ISR.
18337 \layout Subsection
18338
18339 Function return values
18340 \layout Standard
18341
18342 Return values from functions are placed to the appropriate registers following
18343  a modified Microchip policy optimized for SDCC.
18344  The following table shows these registers:
18345 \layout Standard
18346 \align center
18347
18348 \begin_inset  Tabular
18349 <lyxtabular version="3" rows="6" columns="2">
18350 <features>
18351 <column alignment="center" valignment="top" leftline="true" width="0">
18352 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18353 <row topline="true" bottomline="true">
18354 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18355 \begin_inset Text
18356
18357 \layout Standard
18358
18359 size
18360 \end_inset
18361 </cell>
18362 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18363 \begin_inset Text
18364
18365 \layout Standard
18366
18367 destination register
18368 \end_inset
18369 </cell>
18370 </row>
18371 <row topline="true">
18372 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18373 \begin_inset Text
18374
18375 \layout Standard
18376
18377 8 bits
18378 \end_inset
18379 </cell>
18380 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18381 \begin_inset Text
18382
18383 \layout Standard
18384
18385 WREG
18386 \end_inset
18387 </cell>
18388 </row>
18389 <row topline="true">
18390 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18391 \begin_inset Text
18392
18393 \layout Standard
18394
18395 16 bits
18396 \end_inset
18397 </cell>
18398 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18399 \begin_inset Text
18400
18401 \layout Standard
18402
18403 PRODL:WREG
18404 \end_inset
18405 </cell>
18406 </row>
18407 <row topline="true">
18408 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18409 \begin_inset Text
18410
18411 \layout Standard
18412
18413 24 bits
18414 \end_inset
18415 </cell>
18416 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18417 \begin_inset Text
18418
18419 \layout Standard
18420
18421 PRODH:PRODL:WREG
18422 \end_inset
18423 </cell>
18424 </row>
18425 <row topline="true">
18426 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18427 \begin_inset Text
18428
18429 \layout Standard
18430
18431 32 bits
18432 \end_inset
18433 </cell>
18434 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18435 \begin_inset Text
18436
18437 \layout Standard
18438
18439 FSR0L:PRODH:PRODL:WREG
18440 \end_inset
18441 </cell>
18442 </row>
18443 <row topline="true" bottomline="true">
18444 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18445 \begin_inset Text
18446
18447 \layout Standard
18448
18449 >32 bits
18450 \end_inset
18451 </cell>
18452 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18453 \begin_inset Text
18454
18455 \layout Standard
18456
18457 on stack, FSR0 points to the beginning
18458 \end_inset
18459 </cell>
18460 </row>
18461 </lyxtabular>
18462
18463 \end_inset
18464
18465
18466 \layout Subsection
18467
18468 Interrupts
18469 \layout Standard
18470
18471 An interrupt servive routine (ISR) is declared using the
18472 \emph on
18473 interrupt
18474 \emph default
18475  keyword.
18476 \layout LyX-Code
18477
18478 void isr(void) interrupt
18479 \emph on
18480 n
18481 \layout LyX-Code
18482
18483 {
18484 \layout LyX-Code
18485
18486 ...
18487 \layout LyX-Code
18488
18489 }
18490 \layout Standard
18491
18492
18493 \emph on
18494 n
18495 \emph default
18496  is the interrupt number, which for PIC18F devices can be:
18497 \layout Standard
18498 \align center
18499
18500 \begin_inset  Tabular
18501 <lyxtabular version="3" rows="4" columns="3">
18502 <features>
18503 <column alignment="center" valignment="top" leftline="true" width="0">
18504 <column alignment="center" valignment="top" leftline="true" width="0">
18505 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18506 <row topline="true" bottomline="true">
18507 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18508 \begin_inset Text
18509
18510 \layout Standard
18511
18512
18513 \emph on
18514 n
18515 \end_inset
18516 </cell>
18517 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18518 \begin_inset Text
18519
18520 \layout Standard
18521
18522 Interrupt Vector
18523 \end_inset
18524 </cell>
18525 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18526 \begin_inset Text
18527
18528 \layout Standard
18529
18530 Interrupt Vector Address
18531 \end_inset
18532 </cell>
18533 </row>
18534 <row topline="true">
18535 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18536 \begin_inset Text
18537
18538 \layout Standard
18539
18540 0
18541 \end_inset
18542 </cell>
18543 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18544 \begin_inset Text
18545
18546 \layout Standard
18547
18548 RESET vector
18549 \end_inset
18550 </cell>
18551 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18552 \begin_inset Text
18553
18554 \layout Standard
18555
18556 0x000000
18557 \end_inset
18558 </cell>
18559 </row>
18560 <row topline="true">
18561 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18562 \begin_inset Text
18563
18564 \layout Standard
18565
18566
18567 \family roman
18568 \series medium
18569 \shape up
18570 \size normal
18571 \emph off
18572 \bar no
18573 \noun off
18574 \color none
18575 1
18576 \end_inset
18577 </cell>
18578 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18579 \begin_inset Text
18580
18581 \layout Standard
18582
18583
18584 \family roman
18585 \series medium
18586 \shape up
18587 \size normal
18588 \emph off
18589 \bar no
18590 \noun off
18591 \color none
18592 HIGH priority interrupts
18593 \end_inset
18594 </cell>
18595 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18596 \begin_inset Text
18597
18598 \layout Standard
18599
18600 0x000008
18601 \end_inset
18602 </cell>
18603 </row>
18604 <row topline="true" bottomline="true">
18605 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18606 \begin_inset Text
18607
18608 \layout Standard
18609
18610 2
18611 \end_inset
18612 </cell>
18613 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18614 \begin_inset Text
18615
18616 \layout Standard
18617
18618 LOW priority interrupts
18619 \end_inset
18620 </cell>
18621 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18622 \begin_inset Text
18623
18624 \layout Standard
18625
18626 0x000018
18627 \end_inset
18628 </cell>
18629 </row>
18630 </lyxtabular>
18631
18632 \end_inset
18633
18634
18635 \layout Standard
18636
18637 When generating assembly code for ISR the code generator places a
18638 \noun on
18639 goto
18640 \noun default
18641 instruction at the
18642 \emph on
18643 Interrupt Vector Address
18644 \emph default
18645  which points at the genetated ISR.
18646  This single GOTO instruction is part of an automatically generated
18647 \emph on
18648 interrupt entry point
18649 \emph default
18650  function.
18651  The actuall ISR code is placed as normally would in the code space.
18652  Upon interrupt request, the GOTO instruction is executed which jumps to
18653  the ISR code.
18654  When declaring interrupt functions as _naked this GOTO instruction is
18655 \series bold
18656 not
18657 \series default
18658  generated.
18659  The whole interrupt functions is therefore placed at the Interrupt Vector
18660  Address of the specific interrupt.
18661  This is not a problem for the LOW priority interrupts, but it is a problem
18662  for the RESET and the HIGH priority interrupts because code may be written
18663  at the next interrupt´s vector address and cause undeterminate program
18664  behaviour if that interrupt is raised.
18665 \begin_inset Foot
18666 collapsed false
18667
18668 \layout Standard
18669
18670 This is not a problem when
18671 \layout Enumerate
18672
18673 this is a HIGH interrupt ISR and LOW interrupts are
18674 \emph on
18675 disabled
18676 \emph default
18677  or not used.
18678 \layout Enumerate
18679
18680 when the ISR is small enough not to reach the next interrupt´s vector address.
18681 \end_inset
18682
18683
18684 \layout Standard
18685
18686
18687 \emph on
18688 n
18689 \emph default
18690  is possible to be omitted.
18691  This way a function is generated similar to an ISR, but it is not assigned
18692  to any interrupt.
18693 \layout Standard
18694
18695 When entering an interrupt, currently the PIC16
18696 \begin_inset LatexCommand \index{PIC16}
18697
18698 \end_inset
18699
18700  port automatically saves the following registers:
18701 \layout Itemize
18702
18703 WREG
18704 \layout Itemize
18705
18706 STATUS
18707 \layout Itemize
18708
18709 BSR
18710 \layout Itemize
18711
18712 PROD (PRODL and PRODH)
18713 \layout Itemize
18714
18715 FSR0 (FSR0L and FSR0H)
18716 \layout Standard
18717
18718 These registers are restored upon return from the interrupt routine.
18719 \begin_inset Foot
18720 collapsed false
18721
18722 \layout Standard
18723
18724 NOTE that when the _naked attribute is specified for an interrupt routine,
18725  then NO registers are stored or restored.
18726 \end_inset
18727
18728
18729 \layout Subsection
18730
18731 Generic Pointers
18732 \layout Standard
18733
18734 Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
18735  There are 3 types of generic pointers currently implemented data, code
18736  and eeprom pointers.
18737  They are differentiated by the value of the 7th and 6th bits of the upper
18738  byte:
18739 \layout Standard
18740 \align center
18741
18742 \begin_inset  Tabular
18743 <lyxtabular version="3" rows="5" columns="5">
18744 <features>
18745 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18746 <column alignment="center" valignment="top" width="0">
18747 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18748 <column alignment="center" valignment="top" width="0">
18749 <column alignment="left" valignment="top" rightline="true" width="0">
18750 <row topline="true" bottomline="true">
18751 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18752 \begin_inset Text
18753
18754 \layout Standard
18755
18756 pointer type
18757 \end_inset
18758 </cell>
18759 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18760 \begin_inset Text
18761
18762 \layout Standard
18763
18764 7th bit
18765 \end_inset
18766 </cell>
18767 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18768 \begin_inset Text
18769
18770 \layout Standard
18771
18772 6th bit
18773 \end_inset
18774 </cell>
18775 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18776 \begin_inset Text
18777
18778 \layout Standard
18779
18780 rest of the pointer
18781 \end_inset
18782 </cell>
18783 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18784 \begin_inset Text
18785
18786 \layout Standard
18787
18788 descrption
18789 \end_inset
18790 </cell>
18791 </row>
18792 <row topline="true" bottomline="true">
18793 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18794 \begin_inset Text
18795
18796 \layout Standard
18797
18798 data
18799 \end_inset
18800 </cell>
18801 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18802 \begin_inset Text
18803
18804 \layout Standard
18805
18806 1
18807 \end_inset
18808 </cell>
18809 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18810 \begin_inset Text
18811
18812 \layout Standard
18813
18814 0
18815 \end_inset
18816 </cell>
18817 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18818 \begin_inset Text
18819
18820 \layout Standard
18821
18822
18823 \family typewriter
18824 \shape slanted
18825 \emph on
18826 uuuuuu uuuuxxxx xxxxxxxx
18827 \end_inset
18828 </cell>
18829 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18830 \begin_inset Text
18831
18832 \layout Standard
18833
18834 a 12-bit data pointer in data RAM memory
18835 \end_inset
18836 </cell>
18837 </row>
18838 <row bottomline="true">
18839 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18840 \begin_inset Text
18841
18842 \layout Standard
18843
18844 code
18845 \end_inset
18846 </cell>
18847 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18848 \begin_inset Text
18849
18850 \layout Standard
18851
18852 0
18853 \end_inset
18854 </cell>
18855 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18856 \begin_inset Text
18857
18858 \layout Standard
18859
18860 0
18861 \end_inset
18862 </cell>
18863 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18864 \begin_inset Text
18865
18866 \layout Standard
18867
18868
18869 \family typewriter
18870 \shape slanted
18871 \emph on
18872 uxxxxx xxxxxxxx xxxxxxxx
18873 \end_inset
18874 </cell>
18875 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18876 \begin_inset Text
18877
18878 \layout Standard
18879
18880 a 21-bit code pointer in FLASH memory
18881 \end_inset
18882 </cell>
18883 </row>
18884 <row bottomline="true">
18885 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18886 \begin_inset Text
18887
18888 \layout Standard
18889
18890 eeprom
18891 \end_inset
18892 </cell>
18893 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18894 \begin_inset Text
18895
18896 \layout Standard
18897
18898 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 1
18907 \end_inset
18908 </cell>
18909 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18910 \begin_inset Text
18911
18912 \layout Standard
18913
18914
18915 \family typewriter
18916 \shape slanted
18917 \emph on
18918 uuuuuu uuuuuuxx xxxxxxxx
18919 \end_inset
18920 </cell>
18921 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18922 \begin_inset Text
18923
18924 \layout Standard
18925
18926 a 10-bit eeprom pointer in EEPROM memory
18927 \end_inset
18928 </cell>
18929 </row>
18930 <row bottomline="true">
18931 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18932 \begin_inset Text
18933
18934 \layout Standard
18935
18936 (unimplemented)
18937 \end_inset
18938 </cell>
18939 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18940 \begin_inset Text
18941
18942 \layout Standard
18943
18944 1
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 1
18953 \end_inset
18954 </cell>
18955 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18956 \begin_inset Text
18957
18958 \layout Standard
18959
18960
18961 \family typewriter
18962 \shape slanted
18963 \emph on
18964 xxxxxx xxxxxxxx xxxxxxxx
18965 \end_inset
18966 </cell>
18967 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18968 \begin_inset Text
18969
18970 \layout Standard
18971
18972 unimplemented pointer type
18973 \end_inset
18974 </cell>
18975 </row>
18976 </lyxtabular>
18977
18978 \end_inset
18979
18980
18981 \layout Standard
18982
18983 Generic pointer are read and written with a set of library functions which
18984  read/write 1, 2, 3, 4 bytes.
18985 \layout Subsection
18986
18987 PIC16 C Libraries
18988 \layout Subsubsection
18989
18990 Standard I/O Streams
18991 \layout Standard
18992
18993 In the
18994 \emph on
18995 stdio.h
18996 \emph default
18997  the type FILE is defined as:
18998 \layout LyX-Code
18999
19000 typedef char * FILE;
19001 \layout Standard
19002
19003 This type is the stream type implemented I/O in the PIC18F devices.
19004  Also the standard input and output streams are declared in stdio.h:
19005 \layout LyX-Code
19006
19007 extern FILE * stdin;
19008 \layout LyX-Code
19009
19010 extern FILE * stdout;
19011 \layout Standard
19012
19013 The FILE type is actually a generic pointer which defines one more type
19014  of generic pointers, the
19015 \emph on
19016 stream
19017 \emph default
19018 pointer.
19019  This new type has the format:
19020 \layout Standard
19021 \align center
19022
19023 \begin_inset  Tabular
19024 <lyxtabular version="3" rows="2" columns="7">
19025 <features>
19026 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19027 <column alignment="center" valignment="top" width="0">
19028 <column alignment="center" valignment="top" leftline="true" width="0">
19029 <column alignment="center" valignment="top" leftline="true" width="0">
19030 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19031 <column alignment="center" valignment="top" width="0">
19032 <column alignment="left" valignment="top" rightline="true" width="0">
19033 <row topline="true" bottomline="true">
19034 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19035 \begin_inset Text
19036
19037 \layout Standard
19038
19039 pointer type
19040 \end_inset
19041 </cell>
19042 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19043 \begin_inset Text
19044
19045 \layout Standard
19046
19047 <7:6>
19048 \end_inset
19049 </cell>
19050 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19051 \begin_inset Text
19052
19053 \layout Standard
19054
19055 <5>
19056 \end_inset
19057 </cell>
19058 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19059 \begin_inset Text
19060
19061 \layout Standard
19062
19063 <4>
19064 \end_inset
19065 </cell>
19066 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19067 \begin_inset Text
19068
19069 \layout Standard
19070
19071 <3:0>
19072 \end_inset
19073 </cell>
19074 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19075 \begin_inset Text
19076
19077 \layout Standard
19078
19079 rest of the pointer
19080 \end_inset
19081 </cell>
19082 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19083 \begin_inset Text
19084
19085 \layout Standard
19086
19087 descrption
19088 \end_inset
19089 </cell>
19090 </row>
19091 <row topline="true" bottomline="true">
19092 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19093 \begin_inset Text
19094
19095 \layout Standard
19096
19097 stream
19098 \end_inset
19099 </cell>
19100 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19101 \begin_inset Text
19102
19103 \layout Standard
19104
19105 00
19106 \end_inset
19107 </cell>
19108 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19109 \begin_inset Text
19110
19111 \layout Standard
19112
19113 1
19114 \end_inset
19115 </cell>
19116 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19117 \begin_inset Text
19118
19119 \layout Standard
19120
19121 0
19122 \end_inset
19123 </cell>
19124 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19125 \begin_inset Text
19126
19127 \layout Standard
19128
19129 nnnn
19130 \end_inset
19131 </cell>
19132 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19133 \begin_inset Text
19134
19135 \layout Standard
19136
19137
19138 \family typewriter
19139 \shape slanted
19140 \emph on
19141 uuuuuuuu uuuuuuuu
19142 \end_inset
19143 </cell>
19144 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19145 \begin_inset Text
19146
19147 \layout Standard
19148
19149 upper byte high nubble is 0x2n, the rest are zeroes
19150 \end_inset
19151 </cell>
19152 </row>
19153 </lyxtabular>
19154
19155 \end_inset
19156
19157
19158 \layout Standard
19159
19160 Currently implemented there are 3 types of streams defined:
19161 \layout Standard
19162 \align center
19163
19164 \begin_inset  Tabular
19165 <lyxtabular version="3" rows="4" columns="4">
19166 <features>
19167 <column alignment="center" valignment="top" leftline="true" width="0">
19168 <column alignment="center" valignment="top" leftline="true" width="0">
19169 <column alignment="center" valignment="top" leftline="true" width="0">
19170 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19171 <row topline="true" bottomline="true">
19172 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19173 \begin_inset Text
19174
19175 \layout Standard
19176
19177 stream type
19178 \end_inset
19179 </cell>
19180 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19181 \begin_inset Text
19182
19183 \layout Standard
19184
19185 value
19186 \end_inset
19187 </cell>
19188 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19189 \begin_inset Text
19190
19191 \layout Standard
19192
19193 module
19194 \end_inset
19195 </cell>
19196 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19197 \begin_inset Text
19198
19199 \layout Standard
19200
19201 description
19202 \end_inset
19203 </cell>
19204 </row>
19205 <row topline="true">
19206 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19207 \begin_inset Text
19208
19209 \layout Standard
19210
19211 STREAM_USART
19212 \end_inset
19213 </cell>
19214 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19215 \begin_inset Text
19216
19217 \layout Standard
19218
19219
19220 \family typewriter
19221 0x200000UL
19222 \end_inset
19223 </cell>
19224 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19225 \begin_inset Text
19226
19227 \layout Standard
19228
19229 USART
19230 \end_inset
19231 </cell>
19232 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19233 \begin_inset Text
19234
19235 \layout Standard
19236
19237 Writes/Reads characters via the USART peripheral
19238 \end_inset
19239 </cell>
19240 </row>
19241 <row topline="true">
19242 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19243 \begin_inset Text
19244
19245 \layout Standard
19246
19247 STREAM_MSSP
19248 \end_inset
19249 </cell>
19250 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19251 \begin_inset Text
19252
19253 \layout Standard
19254
19255
19256 \family typewriter
19257 0x210000UL
19258 \end_inset
19259 </cell>
19260 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19261 \begin_inset Text
19262
19263 \layout Standard
19264
19265 MSSP
19266 \end_inset
19267 </cell>
19268 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19269 \begin_inset Text
19270
19271 \layout Standard
19272
19273 Writes/Reads characters via the MSSP peripheral
19274 \end_inset
19275 </cell>
19276 </row>
19277 <row topline="true" bottomline="true">
19278 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19279 \begin_inset Text
19280
19281 \layout Standard
19282
19283 STREAM_USER
19284 \end_inset
19285 </cell>
19286 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19287 \begin_inset Text
19288
19289 \layout Standard
19290
19291
19292 \family typewriter
19293 0x2f0000UL
19294 \end_inset
19295 </cell>
19296 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19297 \begin_inset Text
19298
19299 \layout Standard
19300
19301 (none)
19302 \end_inset
19303 </cell>
19304 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19305 \begin_inset Text
19306
19307 \layout Standard
19308
19309 Writes/Reads characters via used defined functions
19310 \end_inset
19311 </cell>
19312 </row>
19313 </lyxtabular>
19314
19315 \end_inset
19316
19317
19318 \layout Standard
19319
19320 The stream identifiers are declared as macros in the stdio.h header.
19321 \layout Standard
19322
19323 In the libc library there exist the functions that are used to write to
19324  each of the above streams.
19325  These are
19326 \layout List
19327 \labelwidthstring 00.00.0000
19328
19329 _
19330 \begin_inset ERT
19331 status Collapsed
19332
19333 \layout Standard
19334
19335 \backslash
19336 /
19337 \end_inset
19338
19339 _stream_usart_putchar writes a character at the USART stream
19340 \layout List
19341 \labelwidthstring 00.00.0000
19342
19343 _
19344 \begin_inset ERT
19345 status Collapsed
19346
19347 \layout Standard
19348
19349 \backslash
19350 /
19351 \end_inset
19352
19353 _stream_mssp_putchar writes a character at the MSSP stream
19354 \layout List
19355 \labelwidthstring 00.00.0000
19356
19357 putchar dummy function.
19358  This writes a character to a user specified manner.
19359 \layout Standard
19360
19361 In order to increase performance
19362 \emph on
19363 putchar
19364 \emph default
19365 is declared in stdio.h as having its parameter in WREG (it has the wparam
19366  keyword).
19367  In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
19368  in a user-friendly way.
19369
19370 \emph on
19371 arg
19372 \emph default
19373  is the name of the variable that holds the character to print.
19374  An example follows:
19375 \layout LyX-Code
19376
19377 #include <pic18fregs.h>
19378 \newline
19379 #include <stdio.h>
19380 \newline
19381
19382 \newline
19383 PUTCHAR( c )
19384 \layout LyX-Code
19385
19386 {
19387 \layout LyX-Code
19388
19389     PORTA = c;    /* dump character c to PORTA */
19390 \layout LyX-Code
19391
19392 }
19393 \newline
19394
19395 \newline
19396 void main(void)
19397 \layout LyX-Code
19398
19399 {
19400 \layout LyX-Code
19401
19402     stdout = STREAM_USER;    /* this is not necessery, since stdout points
19403 \layout LyX-Code
19404
19405                               * by default to STREAM_USER */
19406 \layout LyX-Code
19407
19408     printf (¨This is a printf test
19409 \backslash
19410 n¨);
19411 \layout LyX-Code
19412
19413 }
19414 \layout LyX-Code
19415
19416 \layout Subsubsection
19417
19418 Printing functions
19419 \layout Standard
19420
19421 PIC16 contains an implementation of the printf-family of functions.
19422  There exist the following functions:
19423 \layout LyX-Code
19424
19425 extern unsigned int sprintf(char *buf, char *fmt, ...);
19426 \layout LyX-Code
19427
19428 extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
19429 \layout LyX-Code
19430
19431 \layout LyX-Code
19432
19433 extern unsigned int printf(char *fmt, ...);
19434 \layout LyX-Code
19435
19436 extern unsigned int vprintf(char *fmt, va_lista ap);
19437 \layout LyX-Code
19438
19439 \layout LyX-Code
19440
19441 extern unsigned int fprintf(FILE *fp, char *fmt, ...);
19442 \layout LyX-Code
19443
19444 extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
19445 \layout Standard
19446
19447 For sprintf and vsprintf
19448 \emph on
19449 buf
19450 \emph default
19451 should normally be a data pointer where the resulting string will be placed.
19452  No range checking is done so the user should allocate the necessery buffer.
19453  For fprintf and vfprintf
19454 \emph on
19455 fp
19456 \emph default
19457  should be a stream pointer (i.e.
19458  stdout, STREAM_MSSP, etc...).
19459 \layout Subsubsection
19460
19461 Signals
19462 \layout Standard
19463
19464 The PIC18F family of microcontrollers supports a number of interrupt sources.
19465  A list of these interrupts is shown in the following table:
19466 \layout Standard
19467 \align center
19468
19469 \begin_inset  Tabular
19470 <lyxtabular version="3" rows="11" columns="4">
19471 <features>
19472 <column alignment="left" valignment="top" leftline="true" width="0">
19473 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19474 <column alignment="left" valignment="top" leftline="true" width="0">
19475 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19476 <row topline="true" bottomline="true">
19477 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19478 \begin_inset Text
19479
19480 \layout Standard
19481
19482 signal name
19483 \end_inset
19484 </cell>
19485 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19486 \begin_inset Text
19487
19488 \layout Standard
19489
19490 description
19491 \end_inset
19492 </cell>
19493 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19494 \begin_inset Text
19495
19496 \layout Standard
19497
19498 signal name
19499 \end_inset
19500 </cell>
19501 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19502 \begin_inset Text
19503
19504 \layout Standard
19505
19506 descritpion
19507 \end_inset
19508 </cell>
19509 </row>
19510 <row topline="true">
19511 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19512 \begin_inset Text
19513
19514 \layout Standard
19515
19516 SIG_RB
19517 \end_inset
19518 </cell>
19519 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19520 \begin_inset Text
19521
19522 \layout Standard
19523
19524 PORTB change interrupt
19525 \end_inset
19526 </cell>
19527 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19528 \begin_inset Text
19529
19530 \layout Standard
19531
19532 SIG_EE
19533 \end_inset
19534 </cell>
19535 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19536 \begin_inset Text
19537
19538 \layout Standard
19539
19540 EEPROM/FLASH write complete interrupt
19541 \end_inset
19542 </cell>
19543 </row>
19544 <row topline="true">
19545 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19546 \begin_inset Text
19547
19548 \layout Standard
19549
19550 SIG_INT0
19551 \end_inset
19552 </cell>
19553 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19554 \begin_inset Text
19555
19556 \layout Standard
19557
19558 INT0 external interrupt
19559 \end_inset
19560 </cell>
19561 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19562 \begin_inset Text
19563
19564 \layout Standard
19565
19566 SIG_BCOL
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 Bus collision interrupt
19575 \end_inset
19576 </cell>
19577 </row>
19578 <row topline="true">
19579 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19580 \begin_inset Text
19581
19582 \layout Standard
19583
19584 SIG_INT1
19585 \end_inset
19586 </cell>
19587 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19588 \begin_inset Text
19589
19590 \layout Standard
19591
19592 INT1 external interrupt
19593 \end_inset
19594 </cell>
19595 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19596 \begin_inset Text
19597
19598 \layout Standard
19599
19600 SIG_LVD
19601 \end_inset
19602 </cell>
19603 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19604 \begin_inset Text
19605
19606 \layout Standard
19607
19608 Low voltage detect interrupt
19609 \end_inset
19610 </cell>
19611 </row>
19612 <row topline="true">
19613 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19614 \begin_inset Text
19615
19616 \layout Standard
19617
19618 SIG_INT2
19619 \end_inset
19620 </cell>
19621 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19622 \begin_inset Text
19623
19624 \layout Standard
19625
19626 INT2 external interrupt
19627 \end_inset
19628 </cell>
19629 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19630 \begin_inset Text
19631
19632 \layout Standard
19633
19634 SIG_PSP
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 Parallel slave port interrupt
19643 \end_inset
19644 </cell>
19645 </row>
19646 <row topline="true">
19647 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19648 \begin_inset Text
19649
19650 \layout Standard
19651
19652 SIG_CCP1
19653 \end_inset
19654 </cell>
19655 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19656 \begin_inset Text
19657
19658 \layout Standard
19659
19660 CCP1 module interrupt
19661 \end_inset
19662 </cell>
19663 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19664 \begin_inset Text
19665
19666 \layout Standard
19667
19668 SIG_AD
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 AD convertion complete interrupt
19677 \end_inset
19678 </cell>
19679 </row>
19680 <row topline="true">
19681 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19682 \begin_inset Text
19683
19684 \layout Standard
19685
19686 SIG_CCP2
19687 \end_inset
19688 </cell>
19689 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19690 \begin_inset Text
19691
19692 \layout Standard
19693
19694 CCP2 module interrupt
19695 \end_inset
19696 </cell>
19697 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19698 \begin_inset Text
19699
19700 \layout Standard
19701
19702 SIG_RC
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 USART receive interrupt
19711 \end_inset
19712 </cell>
19713 </row>
19714 <row topline="true">
19715 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19716 \begin_inset Text
19717
19718 \layout Standard
19719
19720 SIG_TMR0
19721 \end_inset
19722 </cell>
19723 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19724 \begin_inset Text
19725
19726 \layout Standard
19727
19728 TMR0 overflow interrupt
19729 \end_inset
19730 </cell>
19731 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19732 \begin_inset Text
19733
19734 \layout Standard
19735
19736 SIG_TX
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 USART transmit interrupt
19745 \end_inset
19746 </cell>
19747 </row>
19748 <row topline="true">
19749 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19750 \begin_inset Text
19751
19752 \layout Standard
19753
19754 SIG_TMR1
19755 \end_inset
19756 </cell>
19757 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19758 \begin_inset Text
19759
19760 \layout Standard
19761
19762 TMR1 overflow interrupt
19763 \end_inset
19764 </cell>
19765 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19766 \begin_inset Text
19767
19768 \layout Standard
19769
19770 SIG_MSSP
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 SSP receive/transmit interrupt
19779 \end_inset
19780 </cell>
19781 </row>
19782 <row topline="true">
19783 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19784 \begin_inset Text
19785
19786 \layout Standard
19787
19788 SIG_TMR2
19789 \end_inset
19790 </cell>
19791 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19792 \begin_inset Text
19793
19794 \layout Standard
19795
19796 TMR2 matches PR2 interrupt
19797 \end_inset
19798 </cell>
19799 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19800 \begin_inset Text
19801
19802 \layout Standard
19803
19804 \end_inset
19805 </cell>
19806 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19807 \begin_inset Text
19808
19809 \layout Standard
19810
19811 \end_inset
19812 </cell>
19813 </row>
19814 <row topline="true" bottomline="true">
19815 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19816 \begin_inset Text
19817
19818 \layout Standard
19819
19820 SIG_TMR3
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 TMR3 overflow interrupt
19829 \end_inset
19830 </cell>
19831 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19832 \begin_inset Text
19833
19834 \layout Standard
19835
19836 \end_inset
19837 </cell>
19838 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19839 \begin_inset Text
19840
19841 \layout Standard
19842
19843 \end_inset
19844 </cell>
19845 </row>
19846 </lyxtabular>
19847
19848 \end_inset
19849
19850
19851 \layout Standard
19852
19853 The prototypes for these names are defined in the header file
19854 \emph on
19855 signal.h
19856 \emph default
19857  .
19858 \layout Standard
19859
19860 In order to simplify signal handling, a number of macros is provided:
19861 \layout List
19862 \labelwidthstring 00.00.0000
19863
19864 DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
19865  high priority interrupts.
19866
19867 \emph on
19868 name
19869 \emph default
19870  is the function name to use.
19871 \layout List
19872 \labelwidthstring 00.00.0000
19873
19874 DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
19875  low priority interrupt.
19876
19877 \emph on
19878 name
19879 \emph default
19880  is the function name to use.
19881 \layout List
19882 \labelwidthstring 00.00.0000
19883
19884 DEF_HANDLER(sig,handler) define a handler for signal
19885 \emph on
19886 sig.
19887 \layout List
19888 \labelwidthstring 00.00.0000
19889
19890 END_DEF end the declaration of the dispatch table.
19891 \layout Standard
19892
19893 Additionally there are two more macros to simplify the declaration of the
19894  signal handler:
19895 \layout List
19896 \labelwidthstring 00.00.0000
19897
19898
19899 \series medium
19900 SIGHANDLER(handler)
19901 \series default
19902 this declares the function prototype for the
19903 \emph on
19904 handler
19905 \emph default
19906  function.
19907 \layout List
19908 \labelwidthstring 00.00.0000
19909
19910 SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
19911 \layout Standard
19912
19913 An example of using the macros above is shown below:
19914 \layout LyX-Code
19915
19916 #include <pic18fregs.h>
19917 \layout LyX-Code
19918
19919 #include <signal.h>
19920 \newline
19921
19922 \newline
19923 DEF_INTHIGH(high_int)
19924 \layout LyX-Code
19925
19926 DEF_HANDLER(SIG_TMR0, _tmr0_handler)
19927 \layout LyX-Code
19928
19929 DEF_HANDLER(SIG_BCOL, _bcol_handler)
19930 \layout LyX-Code
19931
19932 END_DEF
19933 \newline
19934
19935 \newline
19936 SIGHANDLER(_tmr0_handler)
19937 \layout LyX-Code
19938
19939 {
19940 \layout LyX-Code
19941
19942   /* action to be taken when timer 0 overflows */
19943 \layout LyX-Code
19944
19945 }
19946 \newline
19947
19948 \newline
19949 SIGHANDLERNAKED(_bcol_handler)
19950 \layout LyX-Code
19951
19952 {
19953 \layout LyX-Code
19954
19955   _asm
19956 \layout LyX-Code
19957
19958     /* action to be taken when bus collision occurs */
19959 \layout LyX-Code
19960
19961     retfie
19962 \layout LyX-Code
19963
19964  _endasm;
19965 \layout LyX-Code
19966
19967 }
19968 \layout Standard
19969
19970
19971 \series bold
19972 NOTES:
19973 \series default
19974  Special care should be taken when using the above scheme:
19975 \layout Itemize
19976
19977 do not place a colon (;) at the end of the DEF_* and END_DEF macros.
19978 \layout Itemize
19979
19980 when declaring SIGHANDLERNAKED handler never forget to use
19981 \emph on
19982 retfie
19983 \emph default
19984  for proper returning.
19985 \layout Subsection
19986
19987 PIC16 Port -- Tips
19988 \layout Standard
19989
19990 Here you can find some general tips for compiling programs with SDCC/pic16.
19991 \layout Subsubsection
19992
19993 Stack size
19994 \layout Standard
19995
19996 The default stack size (that is 64 bytes) probably is enough for many programs.
19997  One must take care that when there are many levels of function nesting,
19998  or there is excessive usage of stack, its size should be extended.
19999  An example of such a case is the printf/sprintf family of functions.
20000  If you encounter problems like not being able to print integers, then you
20001  need to set the stack size around the maximum (256 for small stack model).
20002  The following diagram shows what happens when calling printf to print an
20003  integer:
20004 \layout LyX-Code
20005
20006 printf () --> ltoa () --> ultoa () --> divschar ()
20007 \layout Standard
20008
20009 It is should be understood that stack is easily consumed when calling complicate
20010 d functions.
20011  Using command line arguments like -
20012 \begin_inset ERT
20013 status Collapsed
20014
20015 \layout Standard
20016
20017 \backslash
20018 /
20019 \end_inset
20020
20021 -fommit-frame-pointer might reduce stack usage by not creating unnecessery
20022  stack frames.
20023  Other ways to reduce stack usage may exist.
20024 \layout Chapter
20025
20026 Debugging with SDCDB
20027 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
20028
20029 \end_inset
20030
20031
20032 \begin_inset LatexCommand \index{sdcdb (debugger)}
20033
20034 \end_inset
20035
20036
20037 \layout Standard
20038
20039 SDCC is distributed with a source level debugger
20040 \begin_inset LatexCommand \index{Debugger}
20041
20042 \end_inset
20043
20044 .
20045  The debugger uses a command line interface, the command repertoire of the
20046  debugger has been kept as close to gdb
20047 \begin_inset LatexCommand \index{gdb}
20048
20049 \end_inset
20050
20051  (the GNU debugger) as possible.
20052  The configuration and build process is part of the standard compiler installati
20053 on, which also builds and installs the debugger in the target directory
20054  specified during configuration.
20055  The debugger allows you debug BOTH at the C source and at the ASM source
20056  level.
20057  Sdcdb is available on Unix platforms only.
20058 \layout Section
20059
20060 Compiling for Debugging
20061 \layout Standard
20062
20063 The -
20064 \begin_inset ERT
20065 status Collapsed
20066
20067 \layout Standard
20068
20069 \backslash
20070 /
20071 \end_inset
20072
20073 -debug
20074 \begin_inset LatexCommand \index{-\/-debug}
20075
20076 \end_inset
20077
20078  option must be specified for all files for which debug information is to
20079  be generated.
20080  The complier generates a .adb file for each of these files.
20081  The linker creates the .cdb
20082 \begin_inset LatexCommand \index{<file>.cdb}
20083
20084 \end_inset
20085
20086  file from the .adb
20087 \begin_inset LatexCommand \index{<file>.adb}
20088
20089 \end_inset
20090
20091  files and the address information.
20092  This .cdb is used by the debugger.
20093 \layout Section
20094
20095 How the Debugger Works
20096 \layout Standard
20097
20098 When the -
20099 \begin_inset ERT
20100 status Collapsed
20101
20102 \layout Standard
20103
20104 \backslash
20105 /
20106 \end_inset
20107
20108 -debug option is specified the compiler generates extra symbol information
20109  some of which are put into the assembler source and some are put into the
20110  .adb file.
20111   Then the linker creates the .cdb file from the individual .adb files with
20112  the address information for the symbols.
20113  The debugger reads the symbolic information generated by the compiler &
20114  the address information generated by the linker.
20115  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
20116  execution is controlled by the debugger.
20117  When a command is issued for the debugger, it translates it into appropriate
20118  commands for the simulator.
20119 \layout Section
20120
20121 Starting the Debugger
20122 \layout Standard
20123
20124 The debugger can be started using the following command line.
20125  (Assume the file you are debugging has the file name foo).
20126 \newline
20127
20128 \newline
20129
20130 \family sans
20131 \series bold
20132 sdcdb foo
20133 \newline
20134
20135 \family default
20136 \series default
20137
20138 \newline
20139 The debugger will look for the following files.
20140 \layout Itemize
20141
20142 foo.c - the source file.
20143 \layout Itemize
20144
20145 foo.cdb - the debugger symbol information file.
20146 \layout Itemize
20147
20148 foo.ihx - the Intel hex format
20149 \begin_inset LatexCommand \index{Intel hex format}
20150
20151 \end_inset
20152
20153  object file.
20154 \layout Section
20155
20156 Command Line Options
20157 \layout Itemize
20158
20159 -
20160 \begin_inset ERT
20161 status Collapsed
20162
20163 \layout Standard
20164
20165 \backslash
20166 /
20167 \end_inset
20168
20169 -directory=<source file directory> this option can used to specify the directory
20170  search list.
20171  The debugger will look into the directory list specified for source, cdb
20172  & ihx files.
20173  The items in the directory list must be separated by ':', e.g.
20174  if the source files can be in the directories /home/src1 and /home/src2,
20175  the -
20176 \begin_inset ERT
20177 status Collapsed
20178
20179 \layout Standard
20180
20181 \backslash
20182 /
20183 \end_inset
20184
20185 -directory option should be -
20186 \begin_inset ERT
20187 status Collapsed
20188
20189 \layout Standard
20190
20191 \backslash
20192 /
20193 \end_inset
20194
20195 -directory=/home/src1:/home/src2.
20196  Note there can be no spaces in the option.
20197
20198 \layout Itemize
20199
20200 -cd <directory> - change to the <directory>.
20201 \layout Itemize
20202
20203 -fullname - used by GUI front ends.
20204 \layout Itemize
20205
20206 -cpu <cpu-type> - this argument is passed to the simulator please see the
20207  simulator docs for details.
20208 \layout Itemize
20209
20210 -X <Clock frequency > this options is passed to the simulator please see
20211  the simulator docs for details.
20212 \layout Itemize
20213
20214 -s <serial port file> passed to simulator see the simulator docs for details.
20215 \layout Itemize
20216
20217 -S <serial in,out> passed to simulator see the simulator docs for details.
20218 \layout Itemize
20219
20220 -k <port number> passed to simulator see the simulator docs for details.
20221 \layout Section
20222
20223 Debugger Commands
20224 \layout Standard
20225
20226 As mentioned earlier the command interface for the debugger has been deliberatel
20227 y kept as close the GNU debugger gdb, as possible.
20228  This will help the integration with existing graphical user interfaces
20229  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
20230  If you use a graphical user interface for the debugger you can skip this
20231  section.
20232 \layout Subsubsection*
20233
20234 break [line | file:line | function | file:function]
20235 \layout Standard
20236
20237 Set breakpoint at specified line or function:
20238 \newline
20239
20240 \newline
20241
20242 \family sans
20243 \series bold
20244 sdcdb>break 100
20245 \newline
20246 sdcdb>break foo.c:100
20247 \newline
20248 sdcdb>break funcfoo
20249 \newline
20250 sdcdb>break foo.c:funcfoo
20251 \layout Subsubsection*
20252
20253 clear [line | file:line | function | file:function ]
20254 \layout Standard
20255
20256 Clear breakpoint at specified line or function:
20257 \newline
20258
20259 \newline
20260
20261 \family sans
20262 \series bold
20263 sdcdb>clear 100
20264 \newline
20265 sdcdb>clear foo.c:100
20266 \newline
20267 sdcdb>clear funcfoo
20268 \newline
20269 sdcdb>clear foo.c:funcfoo
20270 \layout Subsubsection*
20271
20272 continue
20273 \layout Standard
20274
20275 Continue program being debugged, after breakpoint.
20276 \layout Subsubsection*
20277
20278 finish
20279 \layout Standard
20280
20281 Execute till the end of the current function.
20282 \layout Subsubsection*
20283
20284 delete [n]
20285 \layout Standard
20286
20287 Delete breakpoint number 'n'.
20288  If used without any option clear ALL user defined break points.
20289 \layout Subsubsection*
20290
20291 info [break | stack | frame | registers ]
20292 \layout Itemize
20293
20294 info break - list all breakpoints
20295 \layout Itemize
20296
20297 info stack - show the function call stack.
20298 \layout Itemize
20299
20300 info frame - show information about the current execution frame.
20301 \layout Itemize
20302
20303 info registers - show content of all registers.
20304 \layout Subsubsection*
20305
20306 step
20307 \layout Standard
20308
20309 Step program until it reaches a different source line.
20310  Note: pressing <return> repeats the last command.
20311 \layout Subsubsection*
20312
20313 next
20314 \layout Standard
20315
20316 Step program, proceeding through subroutine calls.
20317 \layout Subsubsection*
20318
20319 run
20320 \layout Standard
20321
20322 Start debugged program.
20323 \layout Subsubsection*
20324
20325 ptype variable
20326 \layout Standard
20327
20328 Print type information of the variable.
20329 \layout Subsubsection*
20330
20331 print variable
20332 \layout Standard
20333
20334 print value of variable.
20335 \layout Subsubsection*
20336
20337 file filename
20338 \layout Standard
20339
20340 load the given file name.
20341  Note this is an alternate method of loading file for debugging.
20342 \layout Subsubsection*
20343
20344 frame
20345 \layout Standard
20346
20347 print information about current frame.
20348 \layout Subsubsection*
20349
20350 set srcmode
20351 \layout Standard
20352
20353 Toggle between C source & assembly source.
20354 \layout Subsubsection*
20355
20356 ! simulator command
20357 \layout Standard
20358
20359 Send the string following '!' to the simulator, the simulator response is
20360  displayed.
20361  Note the debugger does not interpret the command being sent to the simulator,
20362  so if a command like 'go' is sent the debugger can loose its execution
20363  context and may display incorrect values.
20364 \layout Subsubsection*
20365
20366 quit
20367 \layout Standard
20368
20369 "Watch me now.
20370  Iam going Down.
20371  My name is Bobby Brown"
20372 \layout Section
20373
20374 Interfacing with DDD
20375 \layout Comment
20376
20377 The screenshot was converted from png to eps with:
20378 \begin_inset Quotes sld
20379 \end_inset
20380
20381 bmeps -c -e8f -p3 ddd_example.png >ddd_example.eps
20382 \begin_inset Quotes srd
20383 \end_inset
20384
20385  which produces a pretty compact eps file which is free from compression
20386  artifacts.
20387 \layout Comment
20388
20389 The screenshot was included in sdccman.lyx cvs version 1.120 but later removed
20390  as this broke the build system on Sourceforge (pdf-file was broken).
20391 \layout Standard
20392
20393 The .eps File
20394 \size footnotesize
20395
20396 \begin_inset LatexCommand \url{http://cvs.sourceforge.net/viewcvs.py/*checkout*/sdcc/sdcc/doc/figures/ddd_example.eps}
20397
20398 \end_inset
20399
20400
20401 \size default
20402  shows a screenshot of a debugging session with DDD
20403 \begin_inset LatexCommand \index{DDD (debugger)}
20404
20405 \end_inset
20406
20407  (Unix only) on a simulated 8032.
20408  The debugging session might not run as smoothly as the screenshot suggests.
20409  The debugger allows setting of breakpoints, displaying and changing variables,
20410  single stepping through C and assembler code.
20411
20412 \newline
20413 The source was compiled with
20414 \family sans
20415 \series bold
20416
20417 \newline
20418
20419 \newline
20420 sdcc -
20421 \family default
20422 \series default
20423
20424 \begin_inset ERT
20425 status Collapsed
20426
20427 \layout Standard
20428
20429 \backslash
20430 /
20431 \end_inset
20432
20433
20434 \family sans
20435 \series bold
20436 -debug ddd_example.c
20437 \family default
20438 \series default
20439
20440 \family sans
20441 \series bold
20442
20443 \newline
20444
20445 \family default
20446 \series default
20447
20448 \newline
20449 and DDD was invoked with
20450 \family sans
20451 \series bold
20452
20453 \newline
20454
20455 \newline
20456 ddd -debugger 'sdcdb -cpu 8032 ddd_example'
20457 \layout Section
20458
20459 Interfacing with XEmacs
20460 \begin_inset LatexCommand \index{XEmacs}
20461
20462 \end_inset
20463
20464
20465 \begin_inset LatexCommand \index{Emacs}
20466
20467 \end_inset
20468
20469
20470 \layout Standard
20471
20472 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
20473  sdcdb.el and sdcdbsrc.el.
20474  These two files can be found in the $(prefix)/bin directory after the installat
20475 ion is complete.
20476  These files need to be loaded into XEmacs for the interface to work.
20477  This can be done at XEmacs startup time by inserting the following into
20478  your '.xemacs' file (which can be found in your HOME directory):
20479 \newline
20480
20481 \newline
20482
20483 \family typewriter
20484 (load-file sdcdbsrc.el)
20485 \family default
20486
20487 \newline
20488
20489 \newline
20490 .xemacs is a lisp file so the () around the command is REQUIRED.
20491  The files can also be loaded dynamically while XEmacs is running, set the
20492  environment variable 'EMACSLOADPATH' to the installation bin directory
20493  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
20494  To start the interface enter the following command:
20495 \newline
20496
20497 \newline
20498
20499 \family sans
20500 \series bold
20501 ESC-x sdcdbsrc
20502 \family default
20503 \series default
20504
20505 \newline
20506
20507 \newline
20508 You will prompted to enter the file name to be debugged.
20509
20510 \newline
20511
20512 \newline
20513 The command line options that are passed to the simulator directly are bound
20514  to default values in the file sdcdbsrc.el.
20515  The variables are listed below, these values maybe changed as required.
20516 \layout Itemize
20517
20518 sdcdbsrc-cpu-type '51
20519 \layout Itemize
20520
20521 sdcdbsrc-frequency '11059200
20522 \layout Itemize
20523
20524 sdcdbsrc-serial nil
20525 \layout Standard
20526
20527 The following is a list of key mapping for the debugger interface.
20528 \layout Standard
20529
20530 \SpecialChar ~
20531
20532 \family typewriter
20533
20534 \newline
20535 ;;\SpecialChar ~
20536 Current Listing ::
20537 \newline
20538 ;;key\SpecialChar ~
20539 \SpecialChar ~
20540 \SpecialChar ~
20541 \SpecialChar ~
20542 \SpecialChar ~
20543 \SpecialChar ~
20544 \SpecialChar ~
20545 \SpecialChar ~
20546 \SpecialChar ~
20547 \SpecialChar ~
20548 \SpecialChar ~
20549 \SpecialChar ~
20550 \SpecialChar ~
20551 \SpecialChar ~
20552 binding\SpecialChar ~
20553 \SpecialChar ~
20554 \SpecialChar ~
20555 \SpecialChar ~
20556 \SpecialChar ~
20557 \SpecialChar ~
20558 \SpecialChar ~
20559 \SpecialChar ~
20560 \SpecialChar ~
20561 \SpecialChar ~
20562 \SpecialChar ~
20563 \SpecialChar ~
20564 \SpecialChar ~
20565 \SpecialChar ~
20566 \SpecialChar ~
20567 \SpecialChar ~
20568 \SpecialChar ~
20569 \SpecialChar ~
20570 \SpecialChar ~
20571 \SpecialChar ~
20572 \SpecialChar ~
20573 \SpecialChar ~
20574 Comment
20575 \newline
20576 ;;---\SpecialChar ~
20577 \SpecialChar ~
20578 \SpecialChar ~
20579 \SpecialChar ~
20580 \SpecialChar ~
20581 \SpecialChar ~
20582 \SpecialChar ~
20583 \SpecialChar ~
20584 \SpecialChar ~
20585 \SpecialChar ~
20586 \SpecialChar ~
20587 \SpecialChar ~
20588 \SpecialChar ~
20589 \SpecialChar ~
20590 -------\SpecialChar ~
20591 \SpecialChar ~
20592 \SpecialChar ~
20593 \SpecialChar ~
20594 \SpecialChar ~
20595 \SpecialChar ~
20596 \SpecialChar ~
20597 \SpecialChar ~
20598 \SpecialChar ~
20599 \SpecialChar ~
20600 \SpecialChar ~
20601 \SpecialChar ~
20602 \SpecialChar ~
20603 \SpecialChar ~
20604 \SpecialChar ~
20605 \SpecialChar ~
20606 \SpecialChar ~
20607 \SpecialChar ~
20608 \SpecialChar ~
20609 \SpecialChar ~
20610 \SpecialChar ~
20611 \SpecialChar ~
20612 -------
20613 \newline
20614 ;;
20615 \newline
20616 ;;\SpecialChar ~
20617 n\SpecialChar ~
20618 \SpecialChar ~
20619 \SpecialChar ~
20620 \SpecialChar ~
20621 \SpecialChar ~
20622 \SpecialChar ~
20623 \SpecialChar ~
20624 \SpecialChar ~
20625 \SpecialChar ~
20626 \SpecialChar ~
20627 \SpecialChar ~
20628 \SpecialChar ~
20629 \SpecialChar ~
20630 \SpecialChar ~
20631 \SpecialChar ~
20632 sdcdb-next-from-src\SpecialChar ~
20633 \SpecialChar ~
20634 \SpecialChar ~
20635 \SpecialChar ~
20636 \SpecialChar ~
20637 \SpecialChar ~
20638 \SpecialChar ~
20639 \SpecialChar ~
20640 \SpecialChar ~
20641 \SpecialChar ~
20642 SDCDB next command
20643 \newline
20644 ;;\SpecialChar ~
20645 b\SpecialChar ~
20646 \SpecialChar ~
20647 \SpecialChar ~
20648 \SpecialChar ~
20649 \SpecialChar ~
20650 \SpecialChar ~
20651 \SpecialChar ~
20652 \SpecialChar ~
20653 \SpecialChar ~
20654 \SpecialChar ~
20655 \SpecialChar ~
20656 \SpecialChar ~
20657 \SpecialChar ~
20658 \SpecialChar ~
20659 \SpecialChar ~
20660 sdcdb-back-from-src\SpecialChar ~
20661 \SpecialChar ~
20662 \SpecialChar ~
20663 \SpecialChar ~
20664 \SpecialChar ~
20665 \SpecialChar ~
20666 \SpecialChar ~
20667 \SpecialChar ~
20668 \SpecialChar ~
20669 \SpecialChar ~
20670 SDCDB back command
20671 \newline
20672 ;;\SpecialChar ~
20673 c\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 sdcdb-cont-from-src\SpecialChar ~
20689 \SpecialChar ~
20690 \SpecialChar ~
20691 \SpecialChar ~
20692 \SpecialChar ~
20693 \SpecialChar ~
20694 \SpecialChar ~
20695 \SpecialChar ~
20696 \SpecialChar ~
20697 \SpecialChar ~
20698 SDCDB continue command
20699 \newline
20700 ;;\SpecialChar ~
20701 s\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-step-from-src\SpecialChar ~
20717 \SpecialChar ~
20718 \SpecialChar ~
20719 \SpecialChar ~
20720 \SpecialChar ~
20721 \SpecialChar ~
20722 \SpecialChar ~
20723 \SpecialChar ~
20724 \SpecialChar ~
20725 \SpecialChar ~
20726 SDCDB step command
20727 \newline
20728 ;;\SpecialChar ~
20729 ?\SpecialChar ~
20730 \SpecialChar ~
20731 \SpecialChar ~
20732 \SpecialChar ~
20733 \SpecialChar ~
20734 \SpecialChar ~
20735 \SpecialChar ~
20736 \SpecialChar ~
20737 \SpecialChar ~
20738 \SpecialChar ~
20739 \SpecialChar ~
20740 \SpecialChar ~
20741 \SpecialChar ~
20742 \SpecialChar ~
20743 \SpecialChar ~
20744 sdcdb-whatis-c-sexp\SpecialChar ~
20745 \SpecialChar ~
20746 \SpecialChar ~
20747 \SpecialChar ~
20748 \SpecialChar ~
20749 \SpecialChar ~
20750 \SpecialChar ~
20751 \SpecialChar ~
20752 \SpecialChar ~
20753 \SpecialChar ~
20754 SDCDB ptypecommand for data at
20755 \newline
20756 ;;\SpecialChar ~
20757 \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 \SpecialChar ~
20773 \SpecialChar ~
20774 \SpecialChar ~
20775 \SpecialChar ~
20776 \SpecialChar ~
20777 \SpecialChar ~
20778 \SpecialChar ~
20779 \SpecialChar ~
20780 \SpecialChar ~
20781 \SpecialChar ~
20782 \SpecialChar ~
20783 \SpecialChar ~
20784 \SpecialChar ~
20785 \SpecialChar ~
20786 \SpecialChar ~
20787 \SpecialChar ~
20788 \SpecialChar ~
20789 \SpecialChar ~
20790 \SpecialChar ~
20791 \SpecialChar ~
20792 \SpecialChar ~
20793 \SpecialChar ~
20794 \SpecialChar ~
20795 \SpecialChar ~
20796 \SpecialChar ~
20797 \SpecialChar ~
20798 \SpecialChar ~
20799 \SpecialChar ~
20800 \SpecialChar ~
20801 \SpecialChar ~
20802 \SpecialChar ~
20803 buffer point
20804 \newline
20805 ;;\SpecialChar ~
20806 x\SpecialChar ~
20807 \SpecialChar ~
20808 \SpecialChar ~
20809 \SpecialChar ~
20810 \SpecialChar ~
20811 \SpecialChar ~
20812 \SpecialChar ~
20813 \SpecialChar ~
20814 \SpecialChar ~
20815 \SpecialChar ~
20816 \SpecialChar ~
20817 \SpecialChar ~
20818 \SpecialChar ~
20819 \SpecialChar ~
20820 \SpecialChar ~
20821 sdcdbsrc-delete\SpecialChar ~
20822 \SpecialChar ~
20823 \SpecialChar ~
20824 \SpecialChar ~
20825 \SpecialChar ~
20826 \SpecialChar ~
20827 \SpecialChar ~
20828 \SpecialChar ~
20829 \SpecialChar ~
20830 \SpecialChar ~
20831 \SpecialChar ~
20832 \SpecialChar ~
20833 \SpecialChar ~
20834 \SpecialChar ~
20835 SDCDB Delete all breakpoints if no arg
20836 \newline
20837 ;;\SpecialChar ~
20838 \SpecialChar ~
20839 \SpecialChar ~
20840 \SpecialChar ~
20841 \SpecialChar ~
20842 \SpecialChar ~
20843 \SpecialChar ~
20844 \SpecialChar ~
20845 \SpecialChar ~
20846 \SpecialChar ~
20847 \SpecialChar ~
20848 \SpecialChar ~
20849 \SpecialChar ~
20850 \SpecialChar ~
20851 \SpecialChar ~
20852 \SpecialChar ~
20853 \SpecialChar ~
20854 \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 given or delete arg (C-u arg x)
20885 \newline
20886 ;;\SpecialChar ~
20887 m\SpecialChar ~
20888 \SpecialChar ~
20889 \SpecialChar ~
20890 \SpecialChar ~
20891 \SpecialChar ~
20892 \SpecialChar ~
20893 \SpecialChar ~
20894 \SpecialChar ~
20895 \SpecialChar ~
20896 \SpecialChar ~
20897 \SpecialChar ~
20898 \SpecialChar ~
20899 \SpecialChar ~
20900 \SpecialChar ~
20901 \SpecialChar ~
20902 sdcdbsrc-frame\SpecialChar ~
20903 \SpecialChar ~
20904 \SpecialChar ~
20905 \SpecialChar ~
20906 \SpecialChar ~
20907 \SpecialChar ~
20908 \SpecialChar ~
20909 \SpecialChar ~
20910 \SpecialChar ~
20911 \SpecialChar ~
20912 \SpecialChar ~
20913 \SpecialChar ~
20914 \SpecialChar ~
20915 \SpecialChar ~
20916 \SpecialChar ~
20917 SDCDB Display current frame if no arg,
20918 \newline
20919 ;;\SpecialChar ~
20920 \SpecialChar ~
20921 \SpecialChar ~
20922 \SpecialChar ~
20923 \SpecialChar ~
20924 \SpecialChar ~
20925 \SpecialChar ~
20926 \SpecialChar ~
20927 \SpecialChar ~
20928 \SpecialChar ~
20929 \SpecialChar ~
20930 \SpecialChar ~
20931 \SpecialChar ~
20932 \SpecialChar ~
20933 \SpecialChar ~
20934 \SpecialChar ~
20935 \SpecialChar ~
20936 \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 given or display frame arg
20967 \newline
20968 ;;\SpecialChar ~
20969 \SpecialChar ~
20970 \SpecialChar ~
20971 \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 \SpecialChar ~
20987 \SpecialChar ~
20988 \SpecialChar ~
20989 \SpecialChar ~
20990 \SpecialChar ~
20991 \SpecialChar ~
20992 \SpecialChar ~
20993 \SpecialChar ~
20994 \SpecialChar ~
20995 \SpecialChar ~
20996 \SpecialChar ~
20997 \SpecialChar ~
20998 \SpecialChar ~
20999 \SpecialChar ~
21000 \SpecialChar ~
21001 \SpecialChar ~
21002 \SpecialChar ~
21003 \SpecialChar ~
21004 \SpecialChar ~
21005 \SpecialChar ~
21006 \SpecialChar ~
21007 \SpecialChar ~
21008 \SpecialChar ~
21009 \SpecialChar ~
21010 \SpecialChar ~
21011 \SpecialChar ~
21012 \SpecialChar ~
21013 \SpecialChar ~
21014 \SpecialChar ~
21015 buffer point
21016 \newline
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 sdcdbsrc-goto-sdcdb\SpecialChar ~
21034 \SpecialChar ~
21035 \SpecialChar ~
21036 \SpecialChar ~
21037 \SpecialChar ~
21038 \SpecialChar ~
21039 \SpecialChar ~
21040 \SpecialChar ~
21041 \SpecialChar ~
21042 \SpecialChar ~
21043 Goto the SDCDB output buffer
21044 \newline
21045 ;;\SpecialChar ~
21046 p\SpecialChar ~
21047 \SpecialChar ~
21048 \SpecialChar ~
21049 \SpecialChar ~
21050 \SpecialChar ~
21051 \SpecialChar ~
21052 \SpecialChar ~
21053 \SpecialChar ~
21054 \SpecialChar ~
21055 \SpecialChar ~
21056 \SpecialChar ~
21057 \SpecialChar ~
21058 \SpecialChar ~
21059 \SpecialChar ~
21060 \SpecialChar ~
21061 sdcdb-print-c-sexp\SpecialChar ~
21062 \SpecialChar ~
21063 \SpecialChar ~
21064 \SpecialChar ~
21065 \SpecialChar ~
21066 \SpecialChar ~
21067 \SpecialChar ~
21068 \SpecialChar ~
21069 \SpecialChar ~
21070 \SpecialChar ~
21071 \SpecialChar ~
21072 SDCDB print command for data at
21073 \newline
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 \SpecialChar ~
21100 \SpecialChar ~
21101 \SpecialChar ~
21102 \SpecialChar ~
21103 \SpecialChar ~
21104 \SpecialChar ~
21105 \SpecialChar ~
21106 \SpecialChar ~
21107 \SpecialChar ~
21108 \SpecialChar ~
21109 \SpecialChar ~
21110 \SpecialChar ~
21111 \SpecialChar ~
21112 \SpecialChar ~
21113 \SpecialChar ~
21114 \SpecialChar ~
21115 \SpecialChar ~
21116 \SpecialChar ~
21117 \SpecialChar ~
21118 \SpecialChar ~
21119 \SpecialChar ~
21120 \SpecialChar ~
21121 buffer point
21122 \newline
21123 ;;\SpecialChar ~
21124 g\SpecialChar ~
21125 \SpecialChar ~
21126 \SpecialChar ~
21127 \SpecialChar ~
21128 \SpecialChar ~
21129 \SpecialChar ~
21130 \SpecialChar ~
21131 \SpecialChar ~
21132 \SpecialChar ~
21133 \SpecialChar ~
21134 \SpecialChar ~
21135 \SpecialChar ~
21136 \SpecialChar ~
21137 \SpecialChar ~
21138 \SpecialChar ~
21139 sdcdbsrc-goto-sdcdb\SpecialChar ~
21140 \SpecialChar ~
21141 \SpecialChar ~
21142 \SpecialChar ~
21143 \SpecialChar ~
21144 \SpecialChar ~
21145 \SpecialChar ~
21146 \SpecialChar ~
21147 \SpecialChar ~
21148 \SpecialChar ~
21149 Goto the SDCDB output buffer
21150 \newline
21151 ;;\SpecialChar ~
21152 t\SpecialChar ~
21153 \SpecialChar ~
21154 \SpecialChar ~
21155 \SpecialChar ~
21156 \SpecialChar ~
21157 \SpecialChar ~
21158 \SpecialChar ~
21159 \SpecialChar ~
21160 \SpecialChar ~
21161 \SpecialChar ~
21162 \SpecialChar ~
21163 \SpecialChar ~
21164 \SpecialChar ~
21165 \SpecialChar ~
21166 \SpecialChar ~
21167 sdcdbsrc-mode\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 Toggles Sdcdbsrc mode (turns it off)
21184 \newline
21185 ;;
21186 \newline
21187 ;;\SpecialChar ~
21188 C-c\SpecialChar ~
21189 C-f\SpecialChar ~
21190 \SpecialChar ~
21191 \SpecialChar ~
21192 \SpecialChar ~
21193 \SpecialChar ~
21194 \SpecialChar ~
21195 \SpecialChar ~
21196 \SpecialChar ~
21197 \SpecialChar ~
21198 sdcdb-finish-from-src\SpecialChar ~
21199 \SpecialChar ~
21200 \SpecialChar ~
21201 \SpecialChar ~
21202 \SpecialChar ~
21203 \SpecialChar ~
21204 \SpecialChar ~
21205 \SpecialChar ~
21206 SDCDB finish command
21207 \newline
21208 ;;
21209 \newline
21210 ;;\SpecialChar ~
21211 C-x\SpecialChar ~
21212 SPC\SpecialChar ~
21213 \SpecialChar ~
21214 \SpecialChar ~
21215 \SpecialChar ~
21216 \SpecialChar ~
21217 \SpecialChar ~
21218 \SpecialChar ~
21219 \SpecialChar ~
21220 \SpecialChar ~
21221 sdcdb-break\SpecialChar ~
21222 \SpecialChar ~
21223 \SpecialChar ~
21224 \SpecialChar ~
21225 \SpecialChar ~
21226 \SpecialChar ~
21227 \SpecialChar ~
21228 \SpecialChar ~
21229 \SpecialChar ~
21230 \SpecialChar ~
21231 \SpecialChar ~
21232 \SpecialChar ~
21233 \SpecialChar ~
21234 \SpecialChar ~
21235 \SpecialChar ~
21236 \SpecialChar ~
21237 \SpecialChar ~
21238 \SpecialChar ~
21239 Set break for line with point
21240 \newline
21241 ;;\SpecialChar ~
21242 ESC\SpecialChar ~
21243 t\SpecialChar ~
21244 \SpecialChar ~
21245 \SpecialChar ~
21246 \SpecialChar ~
21247 \SpecialChar ~
21248 \SpecialChar ~
21249 \SpecialChar ~
21250 \SpecialChar ~
21251 \SpecialChar ~
21252 \SpecialChar ~
21253 \SpecialChar ~
21254 sdcdbsrc-mode\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 \SpecialChar ~
21268 \SpecialChar ~
21269 \SpecialChar ~
21270 Toggle Sdcdbsrc mode
21271 \newline
21272 ;;\SpecialChar ~
21273 ESC\SpecialChar ~
21274 m\SpecialChar ~
21275 \SpecialChar ~
21276 \SpecialChar ~
21277 \SpecialChar ~
21278 \SpecialChar ~
21279 \SpecialChar ~
21280 \SpecialChar ~
21281 \SpecialChar ~
21282 \SpecialChar ~
21283 \SpecialChar ~
21284 \SpecialChar ~
21285 sdcdbsrc-srcmode\SpecialChar ~
21286 \SpecialChar ~
21287 \SpecialChar ~
21288 \SpecialChar ~
21289 \SpecialChar ~
21290 \SpecialChar ~
21291 \SpecialChar ~
21292 \SpecialChar ~
21293 \SpecialChar ~
21294 \SpecialChar ~
21295 \SpecialChar ~
21296 \SpecialChar ~
21297 \SpecialChar ~
21298 Toggle list mode
21299 \newline
21300 ;;
21301 \newline
21302
21303 \layout Chapter
21304 \pagebreak_top
21305 TIPS
21306 \layout Standard
21307
21308 Here are a few guidelines that will help the compiler generate more efficient
21309  code, some of the tips are specific to this compiler others are generally
21310  good programming practice.
21311 \layout Itemize
21312
21313 Use the smallest data type to represent your data-value.
21314  If it is known in advance that the value is going to be less than 256 then
21315  use an 'unsigned char' instead of a 'short' or 'int'.
21316  Please note, that ANSI C requires both signed and unsigned chars to be
21317  promoted to 'signed int' before doing any operation.
21318  This promotion
21319 \begin_inset LatexCommand \index{type promotion}
21320
21321 \end_inset
21322
21323  can be omitted, if the result is the same.
21324  The effect of the promotion rules together with the sign-extension is often
21325  surprising:
21326 \begin_deeper
21327 \layout Verse
21328
21329
21330 \family typewriter
21331 unsigned char uc = 0xfe;
21332 \newline
21333 if (uc * uc < 0) /* this is true! */
21334 \newline
21335 {
21336 \newline
21337 \SpecialChar ~
21338 \SpecialChar ~
21339 \SpecialChar ~
21340 \SpecialChar ~
21341 ....
21342 \newline
21343 }
21344 \layout Standard
21345
21346
21347 \family typewriter
21348 uc * uc
21349 \family default
21350  is evaluated as
21351 \family typewriter
21352 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
21353 \family default
21354 .
21355
21356 \newline
21357 Another one:
21358 \layout Verse
21359
21360
21361 \family typewriter
21362 (unsigned char) -12 / (signed char) -3 = ...
21363 \layout Standard
21364
21365 No, the result is not 4:
21366 \layout Verse
21367
21368
21369 \family typewriter
21370 (int) (unsigned char) -12 / (int) (signed char) -3 =
21371 \newline
21372 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
21373 \newline
21374 (int) 0x00f4 / (int) 0xfffd =
21375 \newline
21376 (int) 0x00f4 / (int) 0xfffd =
21377 \newline
21378 (int) 244 / (int) -3 =
21379 \newline
21380 (int) -81 = (int) 0xffaf;
21381 \layout Standard
21382
21383 Don't complain, that gcc gives you a different result.
21384  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
21385  Therefore the results are different.
21386 \newline
21387 From
21388 \begin_inset Quotes sld
21389 \end_inset
21390
21391 comp.lang.c FAQ
21392 \begin_inset Quotes srd
21393 \end_inset
21394
21395 :
21396 \layout Quote
21397
21398 If well-defined overflow characteristics are important and negative values
21399  are not, or if you want to steer clear of sign-extension problems when
21400  manipulating bits or bytes, use one of the corresponding unsigned types.
21401  (Beware when mixing signed and unsigned values in expressions, though.)
21402 \newline
21403 Although character types (especially unsigned char) can be used as "tiny"
21404  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
21405 ble sign extension and increased code size.
21406 \end_deeper
21407 \layout Itemize
21408
21409 Use unsigned when it is known in advance that the value is not going to
21410  be negative.
21411  This helps especially if you are doing division or multiplication, bit-shifting
21412  or are using an array index.
21413 \layout Itemize
21414
21415 NEVER jump into a LOOP.
21416 \layout Itemize
21417
21418 Declare the variables to be local
21419 \begin_inset LatexCommand \index{local variables}
21420
21421 \end_inset
21422
21423  whenever possible, especially loop control variables (induction).
21424 \layout Itemize
21425
21426 Since the compiler does not always do implicit integral promotion, the programme
21427 r should do an explicit cast when integral promotion is required.
21428 \layout Itemize
21429
21430 Reducing the size of division, multiplication & modulus operations can reduce
21431  code size substantially.
21432  Take the following code for example.
21433 \begin_deeper
21434 \layout Verse
21435
21436
21437 \family typewriter
21438 foobar(unsigned int p1, unsigned char ch)
21439 \newline
21440 {
21441 \newline
21442 \SpecialChar ~
21443 \SpecialChar ~
21444 \SpecialChar ~
21445 \SpecialChar ~
21446 unsigned char ch1 = p1 % ch ;
21447 \newline
21448 \SpecialChar ~
21449 \SpecialChar ~
21450 \SpecialChar ~
21451 \SpecialChar ~
21452 ....
21453 \newline
21454 }
21455 \layout Standard
21456
21457 For the modulus operation the variable ch will be promoted to unsigned int
21458  first then the modulus operation will be performed (this will lead to a
21459  call to support routine _moduint()), and the result will be casted to a
21460  char.
21461  If the code is changed to
21462 \layout Verse
21463
21464
21465 \family typewriter
21466 foobar(unsigned int p1, unsigned char ch)
21467 \newline
21468 {
21469 \newline
21470 \SpecialChar ~
21471 \SpecialChar ~
21472 \SpecialChar ~
21473 \SpecialChar ~
21474 unsigned char ch1 = (unsigned char)p1 % ch ;
21475 \newline
21476 \SpecialChar ~
21477 \SpecialChar ~
21478 \SpecialChar ~
21479 \SpecialChar ~
21480 ....
21481 \newline
21482 }
21483 \layout Standard
21484
21485 It would substantially reduce the code generated (future versions of the
21486  compiler will be smart enough to detect such optimization opportunities).
21487 \end_deeper
21488 \layout Itemize
21489
21490 Have a look at the assembly listing to get a
21491 \begin_inset Quotes sld
21492 \end_inset
21493
21494 feeling
21495 \begin_inset Quotes srd
21496 \end_inset
21497
21498  for the code generation.
21499 \layout Section
21500
21501 Tools
21502 \begin_inset LatexCommand \index{Tools}
21503
21504 \end_inset
21505
21506  included in the distribution
21507 \layout Standard
21508 \align center
21509
21510 \begin_inset  Tabular
21511 <lyxtabular version="3" rows="12" columns="3">
21512 <features>
21513 <column alignment="center" valignment="top" leftline="true" width="0pt">
21514 <column alignment="center" valignment="top" leftline="true" width="0pt">
21515 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
21516 <row topline="true" bottomline="true">
21517 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21518 \begin_inset Text
21519
21520 \layout Standard
21521
21522 Name
21523 \end_inset
21524 </cell>
21525 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21526 \begin_inset Text
21527
21528 \layout Standard
21529
21530 Purpose
21531 \end_inset
21532 </cell>
21533 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21534 \begin_inset Text
21535
21536 \layout Standard
21537
21538 Directory
21539 \end_inset
21540 </cell>
21541 </row>
21542 <row topline="true">
21543 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21544 \begin_inset Text
21545
21546 \layout Standard
21547
21548 uCsim
21549 \end_inset
21550 </cell>
21551 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21552 \begin_inset Text
21553
21554 \layout Standard
21555
21556 Simulator for various architectures
21557 \end_inset
21558 </cell>
21559 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21560 \begin_inset Text
21561
21562 \layout Standard
21563
21564 sdcc/sim/ucsim
21565 \end_inset
21566 </cell>
21567 </row>
21568 <row topline="true">
21569 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21570 \begin_inset Text
21571
21572 \layout Standard
21573
21574 keil2sdcc.pl
21575 \end_inset
21576 </cell>
21577 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21578 \begin_inset Text
21579
21580 \layout Standard
21581
21582 header file conversion
21583 \end_inset
21584 </cell>
21585 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21586 \begin_inset Text
21587
21588 \layout Standard
21589
21590 sdcc/support/scripts
21591 \end_inset
21592 </cell>
21593 </row>
21594 <row topline="true">
21595 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21596 \begin_inset Text
21597
21598 \layout Standard
21599
21600 mh2h.c
21601 \end_inset
21602 </cell>
21603 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21604 \begin_inset Text
21605
21606 \layout Standard
21607
21608 header file conversion
21609 \end_inset
21610 </cell>
21611 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21612 \begin_inset Text
21613
21614 \layout Standard
21615
21616 sdcc/support/scripts
21617 \end_inset
21618 </cell>
21619 </row>
21620 <row topline="true">
21621 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21622 \begin_inset Text
21623
21624 \layout Standard
21625
21626 as-gbz80
21627 \end_inset
21628 </cell>
21629 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21630 \begin_inset Text
21631
21632 \layout Standard
21633
21634 Assembler
21635 \end_inset
21636 </cell>
21637 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21638 \begin_inset Text
21639
21640 \layout Standard
21641
21642
21643 \family roman
21644 \series medium
21645 \shape up
21646 \size normal
21647 \emph off
21648 \bar no
21649 \noun off
21650 \color none
21651 sdcc/bin
21652 \end_inset
21653 </cell>
21654 </row>
21655 <row topline="true">
21656 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21657 \begin_inset Text
21658
21659 \layout Standard
21660
21661 as-z80
21662 \end_inset
21663 </cell>
21664 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21665 \begin_inset Text
21666
21667 \layout Standard
21668
21669 Assembler
21670 \end_inset
21671 </cell>
21672 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21673 \begin_inset Text
21674
21675 \layout Standard
21676
21677
21678 \family roman
21679 \series medium
21680 \shape up
21681 \size normal
21682 \emph off
21683 \bar no
21684 \noun off
21685 \color none
21686 sdcc/bin
21687 \end_inset
21688 </cell>
21689 </row>
21690 <row topline="true">
21691 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21692 \begin_inset Text
21693
21694 \layout Standard
21695
21696 asx8051
21697 \end_inset
21698 </cell>
21699 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21700 \begin_inset Text
21701
21702 \layout Standard
21703
21704 Assembler
21705 \end_inset
21706 </cell>
21707 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21708 \begin_inset Text
21709
21710 \layout Standard
21711
21712
21713 \family roman
21714 \series medium
21715 \shape up
21716 \size normal
21717 \emph off
21718 \bar no
21719 \noun off
21720 \color none
21721 sdcc/bin
21722 \end_inset
21723 </cell>
21724 </row>
21725 <row topline="true">
21726 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21727 \begin_inset Text
21728
21729 \layout Standard
21730
21731 sdcdb
21732 \end_inset
21733 </cell>
21734 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21735 \begin_inset Text
21736
21737 \layout Standard
21738
21739 Simulator
21740 \end_inset
21741 </cell>
21742 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21743 \begin_inset Text
21744
21745 \layout Standard
21746
21747
21748 \family roman
21749 \series medium
21750 \shape up
21751 \size normal
21752 \emph off
21753 \bar no
21754 \noun off
21755 \color none
21756 sdcc/bin
21757 \end_inset
21758 </cell>
21759 </row>
21760 <row topline="true">
21761 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21762 \begin_inset Text
21763
21764 \layout Standard
21765
21766 aslink
21767 \end_inset
21768 </cell>
21769 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21770 \begin_inset Text
21771
21772 \layout Standard
21773
21774 Linker
21775 \end_inset
21776 </cell>
21777 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21778 \begin_inset Text
21779
21780 \layout Standard
21781
21782
21783 \family roman
21784 \series medium
21785 \shape up
21786 \size normal
21787 \emph off
21788 \bar no
21789 \noun off
21790 \color none
21791 sdcc/bin
21792 \end_inset
21793 </cell>
21794 </row>
21795 <row topline="true">
21796 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21797 \begin_inset Text
21798
21799 \layout Standard
21800
21801 link-z80
21802 \end_inset
21803 </cell>
21804 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21805 \begin_inset Text
21806
21807 \layout Standard
21808
21809 Linker
21810 \end_inset
21811 </cell>
21812 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21813 \begin_inset Text
21814
21815 \layout Standard
21816
21817
21818 \family roman
21819 \series medium
21820 \shape up
21821 \size normal
21822 \emph off
21823 \bar no
21824 \noun off
21825 \color none
21826 sdcc/bin
21827 \end_inset
21828 </cell>
21829 </row>
21830 <row topline="true">
21831 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21832 \begin_inset Text
21833
21834 \layout Standard
21835
21836 link-gbz80
21837 \end_inset
21838 </cell>
21839 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21840 \begin_inset Text
21841
21842 \layout Standard
21843
21844 Linker
21845 \end_inset
21846 </cell>
21847 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21848 \begin_inset Text
21849
21850 \layout Standard
21851
21852
21853 \family roman
21854 \series medium
21855 \shape up
21856 \size normal
21857 \emph off
21858 \bar no
21859 \noun off
21860 \color none
21861 sdcc/bin
21862 \end_inset
21863 </cell>
21864 </row>
21865 <row topline="true" bottomline="true">
21866 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21867 \begin_inset Text
21868
21869 \layout Standard
21870
21871 packihx
21872 \end_inset
21873 </cell>
21874 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21875 \begin_inset Text
21876
21877 \layout Standard
21878
21879 ihx packer
21880 \end_inset
21881 </cell>
21882 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21883 \begin_inset Text
21884
21885 \layout Standard
21886
21887
21888 \family roman
21889 \series medium
21890 \shape up
21891 \size normal
21892 \emph off
21893 \bar no
21894 \noun off
21895 \color none
21896 sdcc/bin
21897 \end_inset
21898 </cell>
21899 </row>
21900 </lyxtabular>
21901
21902 \end_inset
21903
21904
21905 \newline
21906
21907 \layout Section
21908
21909 Documentation
21910 \begin_inset LatexCommand \index{Documentation}
21911
21912 \end_inset
21913
21914  included in the distribution
21915 \layout Standard
21916 \align center
21917
21918 \begin_inset  Tabular
21919 <lyxtabular version="3" rows="10" columns="2">
21920 <features>
21921 <column alignment="left" valignment="top" leftline="true" width="0">
21922 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
21923 <row topline="true" bottomline="true">
21924 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21925 \begin_inset Text
21926
21927 \layout Standard
21928
21929 Subject / Title
21930 \end_inset
21931 </cell>
21932 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21933 \begin_inset Text
21934
21935 \layout Standard
21936
21937 Where to get / filename
21938 \end_inset
21939 </cell>
21940 </row>
21941 <row topline="true">
21942 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21943 \begin_inset Text
21944
21945 \layout Standard
21946
21947 SDCC Compiler User Guide
21948 \end_inset
21949 </cell>
21950 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21951 \begin_inset Text
21952
21953 \layout Standard
21954
21955 You're reading it right now
21956 \end_inset
21957 </cell>
21958 </row>
21959 <row topline="true">
21960 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21961 \begin_inset Text
21962
21963 \layout Standard
21964
21965 Changelog of SDCC
21966 \end_inset
21967 </cell>
21968 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21969 \begin_inset Text
21970
21971 \layout Standard
21972
21973 sdcc/Changelog
21974 \end_inset
21975 </cell>
21976 </row>
21977 <row topline="true">
21978 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21979 \begin_inset Text
21980
21981 \layout Standard
21982
21983 ASXXXX
21984 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
21985
21986 \end_inset
21987
21988
21989 \begin_inset LatexCommand \index{Assembler documentation}
21990
21991 \end_inset
21992
21993  Assemblers and ASLINK
21994 \begin_inset LatexCommand \index{aslink}
21995
21996 \end_inset
21997
21998
21999 \begin_inset LatexCommand \index{Linker documentation}
22000
22001 \end_inset
22002
22003  Relocating Linker
22004 \end_inset
22005 </cell>
22006 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22007 \begin_inset Text
22008
22009 \layout Standard
22010
22011 sdcc/as/doc/asxhtm.html
22012 \end_inset
22013 </cell>
22014 </row>
22015 <row topline="true">
22016 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22017 \begin_inset Text
22018
22019 \layout Standard
22020
22021 SDCC regression test
22022 \begin_inset LatexCommand \index{Regression test}
22023
22024 \end_inset
22025
22026
22027 \end_inset
22028 </cell>
22029 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22030 \begin_inset Text
22031
22032 \layout Standard
22033
22034 sdcc/doc/test_suite_spec.pdf
22035 \end_inset
22036 </cell>
22037 </row>
22038 <row topline="true">
22039 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22040 \begin_inset Text
22041
22042 \layout Standard
22043
22044 Various notes
22045 \end_inset
22046 </cell>
22047 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22048 \begin_inset Text
22049
22050 \layout Standard
22051
22052 sdcc/doc/*
22053 \end_inset
22054 </cell>
22055 </row>
22056 <row topline="true">
22057 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22058 \begin_inset Text
22059
22060 \layout Standard
22061
22062 Notes on debugging with sdcdb
22063 \begin_inset LatexCommand \index{sdcdb (debugger)}
22064
22065 \end_inset
22066
22067
22068 \end_inset
22069 </cell>
22070 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22071 \begin_inset Text
22072
22073 \layout Standard
22074
22075 sdcc/debugger/README
22076 \end_inset
22077 </cell>
22078 </row>
22079 <row topline="true">
22080 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22081 \begin_inset Text
22082
22083 \layout Standard
22084
22085 Software simulator for microcontrollers
22086 \end_inset
22087 </cell>
22088 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22089 \begin_inset Text
22090
22091 \layout Standard
22092
22093
22094 \family roman
22095 \series medium
22096 \shape up
22097 \size normal
22098 \emph off
22099 \bar no
22100 \noun off
22101 \color none
22102 sdcc/sim/ucsim/doc
22103 \family default
22104 \series default
22105 \shape default
22106 \size default
22107 \emph default
22108 \bar default
22109 \noun default
22110 \color default
22111 /index.html
22112 \end_inset
22113 </cell>
22114 </row>
22115 <row topline="true">
22116 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22117 \begin_inset Text
22118
22119 \layout Standard
22120
22121 Temporary notes on the pic16
22122 \begin_inset LatexCommand \index{PIC16}
22123
22124 \end_inset
22125
22126  port
22127 \end_inset
22128 </cell>
22129 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22130 \begin_inset Text
22131
22132 \layout Standard
22133
22134 sdcc/src/pic16/NOTES
22135 \end_inset
22136 </cell>
22137 </row>
22138 <row topline="true" bottomline="true">
22139 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22140 \begin_inset Text
22141
22142 \layout Standard
22143
22144 SDCC internal documentation (debugging file format)
22145 \end_inset
22146 </cell>
22147 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22148 \begin_inset Text
22149
22150 \layout Standard
22151
22152 sdcc/doc/
22153 \family roman
22154 \series medium
22155 \shape up
22156 \size normal
22157 \emph off
22158 \bar no
22159 \noun off
22160 \color none
22161 cdbfileformat.pd
22162 \family default
22163 \series default
22164 \shape default
22165 \size default
22166 \emph default
22167 \bar default
22168 \noun default
22169 \color default
22170 f
22171 \end_inset
22172 </cell>
22173 </row>
22174 </lyxtabular>
22175
22176 \end_inset
22177
22178
22179 \newline
22180
22181 \layout Section
22182
22183 Related open source tools
22184 \begin_inset LatexCommand \index{Related tools}
22185
22186 \end_inset
22187
22188
22189 \layout Standard
22190 \align center
22191
22192 \begin_inset  Tabular
22193 <lyxtabular version="3" rows="11" columns="3">
22194 <features>
22195 <column alignment="center" valignment="top" leftline="true" width="0pt">
22196 <column alignment="block" valignment="top" leftline="true" width="30line%">
22197 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
22198 <row topline="true" bottomline="true">
22199 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22200 \begin_inset Text
22201
22202 \layout Standard
22203
22204 Name
22205 \end_inset
22206 </cell>
22207 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22208 \begin_inset Text
22209
22210 \layout Standard
22211
22212 Purpose
22213 \end_inset
22214 </cell>
22215 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22216 \begin_inset Text
22217
22218 \layout Standard
22219
22220 Where to get
22221 \end_inset
22222 </cell>
22223 </row>
22224 <row topline="true">
22225 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22226 \begin_inset Text
22227
22228 \layout Standard
22229
22230 gpsim
22231 \begin_inset LatexCommand \index{gpsim (pic simulator)}
22232
22233 \end_inset
22234
22235
22236 \end_inset
22237 </cell>
22238 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22239 \begin_inset Text
22240
22241 \layout Standard
22242
22243 PIC simulator
22244 \end_inset
22245 </cell>
22246 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22247 \begin_inset Text
22248
22249 \layout Standard
22250
22251
22252 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
22253
22254 \end_inset
22255
22256
22257 \end_inset
22258 </cell>
22259 </row>
22260 <row topline="true">
22261 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22262 \begin_inset Text
22263
22264 \layout Standard
22265
22266 gputils
22267 \begin_inset LatexCommand \index{gputils (pic tools)}
22268
22269 \end_inset
22270
22271
22272 \end_inset
22273 </cell>
22274 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22275 \begin_inset Text
22276
22277 \layout Standard
22278
22279 GNU PIC utilities
22280 \end_inset
22281 </cell>
22282 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22283 \begin_inset Text
22284
22285 \layout Standard
22286
22287
22288 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
22289
22290 \end_inset
22291
22292
22293 \end_inset
22294 </cell>
22295 </row>
22296 <row topline="true">
22297 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22298 \begin_inset Text
22299
22300 \layout Standard
22301
22302 flP5
22303 \end_inset
22304 </cell>
22305 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22306 \begin_inset Text
22307
22308 \layout Standard
22309
22310 PIC programmer
22311 \end_inset
22312 </cell>
22313 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22314 \begin_inset Text
22315
22316 \layout Standard
22317
22318
22319 \begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/}
22320
22321 \end_inset
22322
22323
22324 \end_inset
22325 </cell>
22326 </row>
22327 <row topline="true">
22328 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22329 \begin_inset Text
22330
22331 \layout Standard
22332
22333 indent
22334 \begin_inset LatexCommand \index{indent (source formatting tool)}
22335
22336 \end_inset
22337
22338
22339 \end_inset
22340 </cell>
22341 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22342 \begin_inset Text
22343
22344 \layout Standard
22345
22346 Formats C source - Master of the white spaces
22347 \end_inset
22348 </cell>
22349 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22350 \begin_inset Text
22351
22352 \layout Standard
22353
22354
22355 \begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html}
22356
22357 \end_inset
22358
22359
22360 \end_inset
22361 </cell>
22362 </row>
22363 <row topline="true">
22364 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22365 \begin_inset Text
22366
22367 \layout Standard
22368
22369 srecord
22370 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
22371
22372 \end_inset
22373
22374
22375 \end_inset
22376 </cell>
22377 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22378 \begin_inset Text
22379
22380 \layout Standard
22381
22382 Object file conversion, checksumming, ...
22383 \end_inset
22384 </cell>
22385 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22386 \begin_inset Text
22387
22388 \layout Standard
22389
22390
22391 \begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord}
22392
22393 \end_inset
22394
22395
22396 \end_inset
22397 </cell>
22398 </row>
22399 <row topline="true">
22400 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22401 \begin_inset Text
22402
22403 \layout Standard
22404
22405 objdump
22406 \begin_inset LatexCommand \index{objdump (tool)}
22407
22408 \end_inset
22409
22410
22411 \end_inset
22412 </cell>
22413 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22414 \begin_inset Text
22415
22416 \layout Standard
22417
22418 Object file conversion, ...
22419 \end_inset
22420 </cell>
22421 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22422 \begin_inset Text
22423
22424 \layout Standard
22425
22426 Part of binutils (should be there anyway)
22427 \end_inset
22428 </cell>
22429 </row>
22430 <row topline="true">
22431 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22432 \begin_inset Text
22433
22434 \layout Standard
22435
22436 doxygen
22437 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
22438
22439 \end_inset
22440
22441
22442 \end_inset
22443 </cell>
22444 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22445 \begin_inset Text
22446
22447 \layout Standard
22448
22449 Source code documentation system
22450 \end_inset
22451 </cell>
22452 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22453 \begin_inset Text
22454
22455 \layout Standard
22456
22457
22458 \begin_inset LatexCommand \url{http://www.doxygen.org}
22459
22460 \end_inset
22461
22462
22463 \end_inset
22464 </cell>
22465 </row>
22466 <row topline="true">
22467 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22468 \begin_inset Text
22469
22470 \layout Standard
22471
22472 kdevelop
22473 \end_inset
22474 </cell>
22475 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22476 \begin_inset Text
22477
22478 \layout Standard
22479
22480 IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
22481 \end_inset
22482 </cell>
22483 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22484 \begin_inset Text
22485
22486 \layout Standard
22487
22488
22489 \begin_inset LatexCommand \url{http://www.kdevelop.org}
22490
22491 \end_inset
22492
22493
22494 \end_inset
22495 </cell>
22496 </row>
22497 <row topline="true">
22498 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22499 \begin_inset Text
22500
22501 \layout Standard
22502
22503 splint
22504 \begin_inset LatexCommand \index{splint (syntax checking tool)}
22505
22506 \end_inset
22507
22508
22509 \end_inset
22510 </cell>
22511 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22512 \begin_inset Text
22513
22514 \layout Standard
22515
22516 Statically checks c sources (see
22517 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
22518
22519 \end_inset
22520
22521 )
22522 \end_inset
22523 </cell>
22524 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22525 \begin_inset Text
22526
22527 \layout Standard
22528
22529
22530 \begin_inset LatexCommand \url{http://www.splint.org}
22531
22532 \end_inset
22533
22534
22535 \end_inset
22536 </cell>
22537 </row>
22538 <row topline="true" bottomline="true">
22539 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22540 \begin_inset Text
22541
22542 \layout Standard
22543
22544 ddd
22545 \begin_inset LatexCommand \index{ddd (debugger)}
22546
22547 \end_inset
22548
22549
22550 \end_inset
22551 </cell>
22552 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22553 \begin_inset Text
22554
22555 \layout Standard
22556
22557 Debugger, serves nicely as GUI to sdcdb
22558 \begin_inset LatexCommand \index{sdcdb (debugger)}
22559
22560 \end_inset
22561
22562  (Unix only)
22563 \end_inset
22564 </cell>
22565 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22566 \begin_inset Text
22567
22568 \layout Standard
22569
22570
22571 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
22572
22573 \end_inset
22574
22575
22576 \end_inset
22577 </cell>
22578 </row>
22579 </lyxtabular>
22580
22581 \end_inset
22582
22583
22584 \newline
22585
22586 \layout Section
22587
22588 Related documentation / recommended reading
22589 \layout Standard
22590 \align center
22591
22592 \begin_inset  Tabular
22593 <lyxtabular version="3" rows="6" columns="3">
22594 <features>
22595 <column alignment="center" valignment="top" leftline="true" width="0pt">
22596 <column alignment="block" valignment="top" leftline="true" width="30line%">
22597 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
22598 <row topline="true" bottomline="true">
22599 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22600 \begin_inset Text
22601
22602 \layout Standard
22603
22604 Name
22605 \end_inset
22606 </cell>
22607 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22608 \begin_inset Text
22609
22610 \layout Standard
22611
22612 Subject / Title
22613 \end_inset
22614 </cell>
22615 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22616 \begin_inset Text
22617
22618 \layout Standard
22619
22620 Where to get
22621 \end_inset
22622 </cell>
22623 </row>
22624 <row topline="true">
22625 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22626 \begin_inset Text
22627
22628 \layout Standard
22629
22630
22631 \family roman
22632 \series medium
22633 \shape up
22634 \size normal
22635 \emph off
22636 \bar no
22637 \noun off
22638 \color none
22639 c-refcard.pdf
22640 \end_inset
22641 </cell>
22642 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22643 \begin_inset Text
22644
22645 \layout Standard
22646
22647 C Reference Card
22648 \begin_inset LatexCommand \index{C Reference card}
22649
22650 \end_inset
22651
22652 , 2 pages
22653 \end_inset
22654 </cell>
22655 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22656 \begin_inset Text
22657
22658 \layout Standard
22659
22660
22661 \begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html}
22662
22663 \end_inset
22664
22665
22666 \end_inset
22667 </cell>
22668 </row>
22669 <row topline="true">
22670 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22671 \begin_inset Text
22672
22673 \layout Standard
22674
22675 c-faq
22676 \end_inset
22677 </cell>
22678 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22679 \begin_inset Text
22680
22681 \layout Standard
22682
22683 C-FAQ-list
22684 \end_inset
22685 </cell>
22686 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22687 \begin_inset Text
22688
22689 \layout Standard
22690
22691
22692 \begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
22693
22694 \end_inset
22695
22696
22697 \end_inset
22698 </cell>
22699 </row>
22700 <row topline="true">
22701 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22702 \begin_inset Text
22703
22704 \layout Standard
22705
22706 \end_inset
22707 </cell>
22708 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22709 \begin_inset Text
22710
22711 \layout Standard
22712
22713 Latest datasheet of the target CPU
22714 \end_inset
22715 </cell>
22716 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22717 \begin_inset Text
22718
22719 \layout Standard
22720
22721 vendor
22722 \end_inset
22723 </cell>
22724 </row>
22725 <row topline="true">
22726 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22727 \begin_inset Text
22728
22729 \layout Standard
22730
22731 \end_inset
22732 </cell>
22733 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22734 \begin_inset Text
22735
22736 \layout Standard
22737
22738 Revision history of datasheet
22739 \end_inset
22740 </cell>
22741 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22742 \begin_inset Text
22743
22744 \layout Standard
22745
22746 vendor
22747 \end_inset
22748 </cell>
22749 </row>
22750 <row topline="true" bottomline="true">
22751 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22752 \begin_inset Text
22753
22754 \layout Standard
22755
22756 S.
22757  S.
22758  Muchnick
22759 \end_inset
22760 </cell>
22761 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22762 \begin_inset Text
22763
22764 \layout Standard
22765
22766 Advanced Compiler Design and Implementation
22767 \end_inset
22768 </cell>
22769 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22770 \begin_inset Text
22771
22772 \layout Standard
22773
22774 bookstore (very dedicated, probably read other books first)
22775 \end_inset
22776 </cell>
22777 </row>
22778 </lyxtabular>
22779
22780 \end_inset
22781
22782
22783 \newline
22784
22785 \layout Section
22786
22787 Some Questions
22788 \layout Standard
22789
22790 Some questions answered, some pointers given - it might be time to in turn
22791  ask
22792 \emph on
22793 you
22794 \emph default
22795  some questions:
22796 \layout Itemize
22797
22798 can you solve your project with the selected microcontroller? Would you
22799  find out early or rather late that your target is too small/slow/whatever?
22800  Can you switch to a slightly better device if it doesn't fit?
22801 \layout Itemize
22802
22803 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
22804  and/or another programming language be more adequate? Would an operating
22805  system on the target device help?
22806 \layout Itemize
22807
22808 if you solved the problem, will the marketing department be happy?
22809 \layout Itemize
22810
22811 if the marketing department is happy, will customers be happy?
22812 \layout Itemize
22813
22814 if you're the project manager, marketing department and maybe even the customer
22815  in one person, have you tried to see the project from the outside?
22816 \layout Itemize
22817
22818 is the project done if you think it is done? Or is just that other interface/pro
22819 tocol/feature/configuration/option missing? How about website, manual(s),
22820  internationali(z|s)ation, packaging, labels, 2nd source for components,
22821  electromagnetic compatability/interference, documentation for production,
22822  production test software, update mechanism, patent issues?
22823 \layout Itemize
22824
22825 is your project adequately positioned in that magic triangle: fame, fortune,
22826  fun?
22827 \layout Standard
22828
22829 Maybe not all answers to these questions are known and some answers may
22830  even be
22831 \emph on
22832 no
22833 \emph default
22834 , nevertheless knowing these questions may help you to avoid burnout
22835 \begin_inset Foot
22836 collapsed false
22837
22838 \layout Standard
22839
22840 burnout is bad for electronic devices, programmers and motorcycle tyres
22841 \end_inset
22842
22843 .
22844  Chances are you didn't want to hear some of them...
22845 \layout Chapter
22846
22847 Support
22848 \begin_inset LatexCommand \index{Support}
22849
22850 \end_inset
22851
22852
22853 \layout Standard
22854
22855 SDCC has grown to be a large project.
22856  The compiler alone (without the preprocessor, assembler and linker) is
22857  well over 100,000 lines of code (blank stripped).
22858  The open source nature of this project is a key to its continued growth
22859  and support.
22860  You gain the benefit and support of many active software developers and
22861  end users.
22862  Is SDCC perfect? No, that's why we need your help.
22863  The developers take pride in fixing reported bugs.
22864  You can help by reporting the bugs and helping other SDCC users.
22865  There are lots of ways to contribute, and we encourage you to take part
22866  in making SDCC a great software package.
22867
22868 \layout Standard
22869
22870 The SDCC project is hosted on the SDCC sourceforge site at
22871 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
22872
22873 \end_inset
22874
22875 .
22876  You'll find the complete set of mailing lists
22877 \begin_inset LatexCommand \index{Mailing list(s)}
22878
22879 \end_inset
22880
22881 , forums, bug reporting system, patch submission
22882 \begin_inset LatexCommand \index{Patch submission}
22883
22884 \end_inset
22885
22886  system, download
22887 \begin_inset LatexCommand \index{download}
22888
22889 \end_inset
22890
22891  area and cvs code repository
22892 \begin_inset LatexCommand \index{cvs code repository}
22893
22894 \end_inset
22895
22896  there.
22897 \layout Section
22898
22899 Reporting Bugs
22900 \begin_inset LatexCommand \index{Bug reporting}
22901
22902 \end_inset
22903
22904
22905 \begin_inset LatexCommand \index{Reporting bugs}
22906
22907 \end_inset
22908
22909
22910 \layout Standard
22911
22912 The recommended way of reporting bugs is using the infrastructure of the
22913  sourceforge site.
22914  You can follow the status of bug reports there and have an overview about
22915  the known bugs.
22916 \layout Standard
22917
22918 Bug reports are automatically forwarded to the developer mailing list and
22919  will be fixed ASAP.
22920  When reporting a bug, it is very useful to include a small test program
22921  (the smaller the better) which reproduces the problem.
22922  If you can isolate the problem by looking at the generated assembly code,
22923  this can be very helpful.
22924  Compiling your program with the -
22925 \begin_inset ERT
22926 status Collapsed
22927
22928 \layout Standard
22929
22930 \backslash
22931 /
22932 \end_inset
22933
22934 -dumpall
22935 \begin_inset LatexCommand \index{-\/-dumpall}
22936
22937 \end_inset
22938
22939  option can sometimes be useful in locating optimization problems.
22940  When reporting a bug please maker sure you:
22941 \layout Enumerate
22942
22943 Attach the code you are compiling with SDCC.
22944
22945 \layout Enumerate
22946
22947 Specify the exact command you use to run SDCC, or attach your Makefile.
22948
22949 \layout Enumerate
22950
22951 Specify the SDCC version (type "
22952 \family sans
22953 \series bold
22954 sdcc -v
22955 \family default
22956 \series default
22957 "), your platform, and operating system.
22958
22959 \layout Enumerate
22960
22961 Provide an exact copy of any error message or incorrect output.
22962
22963 \layout Enumerate
22964
22965 Put something meaningful in the subject of your message.
22966 \layout Standard
22967
22968 Please attempt to include these 5 important parts, as applicable, in all
22969  requests for support or when reporting any problems or bugs with SDCC.
22970  Though this will make your message lengthy, it will greatly improve your
22971  chance that SDCC users and developers will be able to help you.
22972  Some SDCC developers are frustrated by bug reports without code provided
22973  that they can use to reproduce and ultimately fix the problem, so please
22974  be sure to provide sample code if you are reporting a bug!
22975 \layout Standard
22976
22977 Please have a short check that you are using a recent version of SDCC and
22978  the bug is not yet known.
22979  This is the link for reporting bugs:
22980 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
22981
22982 \end_inset
22983
22984 .
22985 \layout Section
22986
22987 Requesting Features
22988 \begin_inset LatexCommand \label{sub:Requesting-Features}
22989
22990 \end_inset
22991
22992
22993 \begin_inset LatexCommand \index{Feature request}
22994
22995 \end_inset
22996
22997
22998 \begin_inset LatexCommand \index{Requesting features}
22999
23000 \end_inset
23001
23002
23003 \layout Standard
23004
23005 Like bug reports feature requests are forwarded to the developer mailing
23006  list.
23007  This is the link for requesting features:
23008 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
23009
23010 \end_inset
23011
23012 .
23013 \layout Section
23014
23015 Submitting patches
23016 \layout Standard
23017
23018 Like bug reports contributed patches are forwarded to the developer mailing
23019  list.
23020  This is the link for submitting patches
23021 \begin_inset LatexCommand \index{Patch submission}
23022
23023 \end_inset
23024
23025 :
23026 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
23027
23028 \end_inset
23029
23030 .
23031 \layout Standard
23032
23033 You need to specify some parameters to the
23034 \family typewriter
23035 diff
23036 \family default
23037  command for the patches to be useful.
23038  If you modified more than one file a patch created f.e.
23039  with
23040 \family sans
23041 \series bold
23042
23043 \begin_inset Quotes sld
23044 \end_inset
23045
23046 diff -Naur unmodified_directory modified_directory >my_changes.patch
23047 \begin_inset Quotes srd
23048 \end_inset
23049
23050
23051 \family default
23052 \series default
23053  will be fine, otherwise
23054 \family sans
23055 \series bold
23056
23057 \begin_inset Quotes sld
23058 \end_inset
23059
23060 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
23061 \begin_inset Quotes srd
23062 \end_inset
23063
23064
23065 \series default
23066
23067 \family default
23068 will do.
23069 \layout Section
23070
23071 Getting Help
23072 \layout Standard
23073
23074 These links should take you directly to the
23075 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
23076
23077 \end_inset
23078
23079
23080 \begin_inset Foot
23081 collapsed false
23082
23083 \layout Standard
23084
23085 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
23086  automated messages (mid 2003)
23087 \end_inset
23088
23089  and the
23090 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
23091
23092 \end_inset
23093
23094 , lists
23095 \begin_inset LatexCommand \index{Mailing list(s)}
23096
23097 \end_inset
23098
23099  and forums are archived and searchable so if you are lucky someone already
23100  had a similar problem.
23101  While mails to the lists themselves are delivered promptly their web front
23102  end on sourceforge sometimes shows a severe time lag (up to several weeks),
23103  if you're seriously using SDCC please consider subscribing to the lists.
23104 \layout Section
23105
23106 ChangeLog
23107 \layout Standard
23108
23109 You can follow the status of the cvs version
23110 \begin_inset LatexCommand \index{version}
23111
23112 \end_inset
23113
23114  of SDCC by watching the Changelog
23115 \begin_inset LatexCommand \index{Changelog}
23116
23117 \end_inset
23118
23119  in the cvs-repository
23120 \newline
23121
23122 \size footnotesize
23123
23124 \begin_inset LatexCommand \htmlurl{http://cvs.sf.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
23125
23126 \end_inset
23127
23128 .
23129 \layout Section
23130
23131 Release policy
23132 \begin_inset LatexCommand \index{Release policy}
23133
23134 \end_inset
23135
23136
23137 \layout Standard
23138
23139 Historically there often were long delays between official releases and
23140  the sourceforge download area tends to get not updated at all.
23141  Excuses in the past might have referred to problems with live range analysis,
23142  but as this was fixed a while ago, the current problem is that another
23143  excuse has to be found.
23144  Kidding aside, we have to get better there! On the other hand there are
23145  daily snapshots available at
23146 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
23147
23148 \end_inset
23149
23150 , and you can always build the very last version (hopefully with many bugs
23151  fixed, and features added) from the source code available at
23152 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
23153
23154 \end_inset
23155
23156 .
23157 \layout Section
23158
23159 Examples
23160 \begin_inset LatexCommand \index{Examples}
23161
23162 \end_inset
23163
23164
23165 \layout Standard
23166
23167 You'll find some small examples in the directory
23168 \emph on
23169 sdcc/device/examples/.
23170
23171 \emph default
23172 More examples and libraries are available at
23173 \emph on
23174  The SDCC Open Knowledge Resource
23175 \begin_inset LatexCommand \url{http://sdccokr.dl9sec.de/}
23176
23177 \end_inset
23178
23179
23180 \emph default
23181 web site or at
23182 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
23183
23184 \end_inset
23185
23186 .
23187 \layout Comment
23188
23189 I did insert a reference to Paul's web site here although it seems rather
23190  dedicated to a specific 8032 board (I think it's okay because it f.e.
23191  shows LCD/Harddisc interface and has a free 8051 monitor.
23192  Independent 8032 board vendors face hard competition of heavily subsidized
23193  development boards anyway).
23194 \layout Comment
23195
23196 Maybe we should include some links to real world applications.
23197  Preferably pointer to pointers (one for each architecture) so this stays
23198  manageable here?
23199 \layout Section
23200
23201 Quality control
23202 \begin_inset LatexCommand \index{Quality control}
23203
23204 \end_inset
23205
23206
23207 \layout Standard
23208
23209 The compiler is passed through nightly compile and build checks.
23210  The so called
23211 \shape italic
23212 regression tests
23213 \shape default
23214
23215 \begin_inset LatexCommand \index{Regression test}
23216
23217 \end_inset
23218
23219  check that SDCC itself compiles flawlessly on several platforms and checks
23220  the quality of the code generated by SDCC by running the code through simulator
23221 s.
23222  There is a separate document
23223 \shape italic
23224 test_suite.pdf
23225 \begin_inset LatexCommand \index{Test suite}
23226
23227 \end_inset
23228
23229
23230 \shape default
23231  about this.
23232 \layout Standard
23233
23234 You'll find the test code in the directory
23235 \shape italic
23236 sdcc/support/regression
23237 \shape default
23238 .
23239  You can run these tests manually by running
23240 \family sans
23241 make
23242 \family default
23243  in this directory (or f.e.
23244
23245 \family sans
23246 \series bold
23247
23248 \begin_inset Quotes sld
23249 \end_inset
23250
23251 make test-mcs51
23252 \begin_inset Quotes srd
23253 \end_inset
23254
23255
23256 \family default
23257 \series default
23258  if you don't want to run the complete tests).
23259  The test code might also be interesting if you want to look for examples
23260 \begin_inset LatexCommand \index{Examples}
23261
23262 \end_inset
23263
23264  checking corner cases of SDCC or if you plan to submit patches
23265 \begin_inset LatexCommand \index{Patch submission}
23266
23267 \end_inset
23268
23269 .
23270 \layout Standard
23271
23272 The pic port uses a different set of regression tests, you'll find them
23273  in the directory
23274 \shape italic
23275 sdcc/src/regression
23276 \shape default
23277 .
23278 \layout Chapter
23279 \pagebreak_top
23280 SDCC Technical Data
23281 \layout Section
23282
23283 Optimizations
23284 \begin_inset LatexCommand \index{Optimizations}
23285
23286 \end_inset
23287
23288
23289 \layout Standard
23290
23291 SDCC performs a host of standard optimizations in addition to some MCU specific
23292  optimizations.
23293
23294 \layout Subsection
23295
23296 Sub-expression Elimination
23297 \begin_inset LatexCommand \index{Subexpression elimination}
23298
23299 \end_inset
23300
23301
23302 \layout Standard
23303
23304 The compiler does local and
23305 \emph on
23306 g
23307 \emph default
23308 lobal
23309 \emph on
23310 c
23311 \emph default
23312 ommon
23313 \emph on
23314 s
23315 \emph default
23316 ubexpression
23317 \emph on
23318 e
23319 \emph default
23320 limination, e.g.:
23321 \layout Verse
23322
23323
23324 \family typewriter
23325 i = x + y + 1;
23326 \newline
23327 j = x + y;
23328 \layout Standard
23329
23330 will be translated to
23331 \layout Verse
23332
23333
23334 \family typewriter
23335 iTemp = x + y;
23336 \newline
23337 i = iTemp + 1;
23338 \newline
23339 j = iTemp;
23340 \layout Standard
23341
23342 Some subexpressions are not as obvious as the above example, e.g.:
23343 \layout Verse
23344
23345
23346 \family typewriter
23347 a->b[i].c = 10;
23348 \newline
23349 a->b[i].d = 11;
23350 \layout Standard
23351
23352 In this case the address arithmetic a->b[i] will be computed only once;
23353  the equivalent code in C would be.
23354 \layout Verse
23355
23356
23357 \family typewriter
23358 iTemp = a->b[i];
23359 \newline
23360 iTemp.c = 10;
23361 \newline
23362 iTemp.d = 11;
23363 \layout Standard
23364
23365 The compiler will try to keep these temporary variables in registers.
23366 \layout Subsection
23367
23368 Dead-Code Elimination
23369 \begin_inset LatexCommand \index{Dead-code elimination}
23370
23371 \end_inset
23372
23373
23374 \layout Verse
23375
23376
23377 \family typewriter
23378 int global;
23379 \newline
23380
23381 \newline
23382 void f () {
23383 \newline
23384 \SpecialChar ~
23385 \SpecialChar ~
23386 int i;
23387 \newline
23388 \SpecialChar ~
23389 \SpecialChar ~
23390 i = 1; \SpecialChar ~
23391 \SpecialChar ~
23392 \SpecialChar ~
23393 \SpecialChar ~
23394 \SpecialChar ~
23395 /* dead store */
23396 \newline
23397 \SpecialChar ~
23398 \SpecialChar ~
23399 global = 1;\SpecialChar ~
23400 /* dead store */
23401 \newline
23402 \SpecialChar ~
23403 \SpecialChar ~
23404 global = 2;
23405 \newline
23406 \SpecialChar ~
23407 \SpecialChar ~
23408 return;
23409 \newline
23410 \SpecialChar ~
23411 \SpecialChar ~
23412 global = 3;\SpecialChar ~
23413 /* unreachable */
23414 \newline
23415 }
23416 \layout Standard
23417
23418 will be changed to
23419 \layout Verse
23420
23421
23422 \family typewriter
23423 int global;
23424 \newline
23425
23426 \newline
23427 void f () {
23428 \newline
23429 \SpecialChar ~
23430 \SpecialChar ~
23431 global = 2;
23432 \newline
23433 }
23434 \layout Subsection
23435
23436 Copy-Propagation
23437 \begin_inset LatexCommand \index{Copy propagation}
23438
23439 \end_inset
23440
23441
23442 \layout Verse
23443
23444
23445 \family typewriter
23446 int f() {
23447 \newline
23448 \SpecialChar ~
23449 \SpecialChar ~
23450 int i, j;
23451 \newline
23452 \SpecialChar ~
23453 \SpecialChar ~
23454 i = 10;
23455 \newline
23456 \SpecialChar ~
23457 \SpecialChar ~
23458 j = i;
23459 \newline
23460 \SpecialChar ~
23461 \SpecialChar ~
23462 return j;
23463 \newline
23464 }
23465 \layout Standard
23466
23467 will be changed to
23468 \layout Verse
23469
23470
23471 \family typewriter
23472 int f() {
23473 \newline
23474 \SpecialChar ~
23475 \SpecialChar ~
23476 int i, j;
23477 \newline
23478 \SpecialChar ~
23479 \SpecialChar ~
23480 i = 10;
23481 \newline
23482 \SpecialChar ~
23483 \SpecialChar ~
23484 j = 10;
23485 \newline
23486 \SpecialChar ~
23487 \SpecialChar ~
23488 return 10;
23489 \newline
23490 }
23491 \layout Standard
23492
23493 Note: the dead stores created by this copy propagation will be eliminated
23494  by dead-code elimination.
23495 \layout Subsection
23496
23497 Loop Optimizations
23498 \begin_inset LatexCommand \index{Loop optimization}
23499
23500 \end_inset
23501
23502
23503 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
23504
23505 \end_inset
23506
23507
23508 \layout Standard
23509
23510 Two types of loop optimizations are done by SDCC
23511 \emph on
23512 loop invariant
23513 \emph default
23514  lifting and
23515 \emph on
23516  strength reduction
23517 \emph default
23518  of loop induction variables.
23519  In addition to the strength reduction the optimizer marks the induction
23520  variables and the register allocator tries to keep the induction variables
23521  in registers for the duration of the loop.
23522  Because of this preference of the register allocator
23523 \begin_inset LatexCommand \index{Register allocation}
23524
23525 \end_inset
23526
23527 , loop induction optimization causes an increase in register pressure, which
23528  may cause unwanted spilling of other temporary variables into the stack
23529 \begin_inset LatexCommand \index{stack}
23530
23531 \end_inset
23532
23533  / data space.
23534  The compiler will generate a warning message when it is forced to allocate
23535  extra space either on the stack or data space.
23536  If this extra space allocation is undesirable then induction optimization
23537  can be eliminated either for the entire source file (with -
23538 \begin_inset ERT
23539 status Collapsed
23540
23541 \layout Standard
23542
23543 \backslash
23544 /
23545 \end_inset
23546
23547 -noinduction option) or for a given function only using #pragma\SpecialChar ~
23548 noinduction
23549 \begin_inset LatexCommand \index{\#pragma noinduction}
23550
23551 \end_inset
23552
23553 .
23554 \newline
23555
23556 \newline
23557 Loop Invariant:
23558 \layout Verse
23559
23560
23561 \family typewriter
23562 for (i = 0 ; i < 100 ; i ++)
23563 \newline
23564 \SpecialChar ~
23565 \SpecialChar ~
23566 \SpecialChar ~
23567 \SpecialChar ~
23568 f += k + l;
23569 \layout Standard
23570
23571 changed to
23572 \layout Verse
23573
23574
23575 \family typewriter
23576 itemp = k + l;
23577 \newline
23578 for (i = 0; i < 100; i++)
23579 \newline
23580 \SpecialChar ~
23581 \SpecialChar ~
23582 \SpecialChar ~
23583 \SpecialChar ~
23584 f += itemp;
23585 \layout Standard
23586
23587 As mentioned previously some loop invariants are not as apparent, all static
23588  address computations are also moved out of the loop.
23589 \newline
23590
23591 \newline
23592 Strength Reduction
23593 \begin_inset LatexCommand \index{Strength reduction}
23594
23595 \end_inset
23596
23597 , this optimization substitutes an expression by a cheaper expression:
23598 \layout Verse
23599
23600
23601 \family typewriter
23602 for (i=0;i < 100; i++)
23603 \newline
23604 \SpecialChar ~
23605 \SpecialChar ~
23606 \SpecialChar ~
23607 \SpecialChar ~
23608 ar[i*5] = i*3;
23609 \layout Standard
23610
23611 changed to
23612 \layout Verse
23613
23614
23615 \family typewriter
23616 itemp1 = 0;
23617 \newline
23618 itemp2 = 0;
23619 \newline
23620 for (i=0;i< 100;i++) {
23621 \newline
23622 \SpecialChar ~
23623 \SpecialChar ~
23624 \SpecialChar ~
23625 \SpecialChar ~
23626 ar[itemp1] = itemp2;
23627 \newline
23628 \SpecialChar ~
23629 \SpecialChar ~
23630 \SpecialChar ~
23631 \SpecialChar ~
23632 itemp1 += 5;
23633 \newline
23634 \SpecialChar ~
23635 \SpecialChar ~
23636 \SpecialChar ~
23637 \SpecialChar ~
23638 itemp2 += 3;
23639 \newline
23640 }
23641 \layout Standard
23642
23643 The more expensive multiplication
23644 \begin_inset LatexCommand \index{Multiplication}
23645
23646 \end_inset
23647
23648  is changed to a less expensive addition.
23649 \layout Subsection
23650
23651 Loop Reversing
23652 \begin_inset LatexCommand \index{Loop reversing}
23653
23654 \end_inset
23655
23656
23657 \layout Standard
23658
23659 This optimization is done to reduce the overhead of checking loop boundaries
23660  for every iteration.
23661  Some simple loops can be reversed and implemented using a
23662 \begin_inset Quotes eld
23663 \end_inset
23664
23665 decrement and jump if not zero
23666 \begin_inset Quotes erd
23667 \end_inset
23668
23669  instruction.
23670  SDCC checks for the following criterion to determine if a loop is reversible
23671  (note: more sophisticated compilers use data-dependency analysis to make
23672  this determination, SDCC uses a more simple minded analysis).
23673 \layout Itemize
23674
23675 The 'for' loop is of the form
23676 \newline
23677
23678 \newline
23679
23680 \family typewriter
23681 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
23682  += 1])
23683 \newline
23684 \SpecialChar ~
23685 \SpecialChar ~
23686 \SpecialChar ~
23687 \SpecialChar ~
23688 <for body>
23689 \layout Itemize
23690
23691 The <for body> does not contain
23692 \begin_inset Quotes eld
23693 \end_inset
23694
23695 continue
23696 \begin_inset Quotes erd
23697 \end_inset
23698
23699  or 'break
23700 \begin_inset Quotes erd
23701 \end_inset
23702
23703 .
23704 \layout Itemize
23705
23706 All goto's are contained within the loop.
23707 \layout Itemize
23708
23709 No function calls within the loop.
23710 \layout Itemize
23711
23712 The loop control variable <sym> is not assigned any value within the loop
23713 \layout Itemize
23714
23715 The loop control variable does NOT participate in any arithmetic operation
23716  within the loop.
23717 \layout Itemize
23718
23719 There are NO switch statements in the loop.
23720 \layout Subsection
23721
23722 Algebraic Simplifications
23723 \layout Standard
23724
23725 SDCC does numerous algebraic simplifications, the following is a small sub-set
23726  of these optimizations.
23727 \layout Verse
23728
23729
23730 \family typewriter
23731 i = j + 0;\SpecialChar ~
23732 \SpecialChar ~
23733 \SpecialChar ~
23734 \SpecialChar ~
23735  /* changed to: */\SpecialChar ~
23736 \SpecialChar ~
23737 \SpecialChar ~
23738 \SpecialChar ~
23739  i = j;
23740 \newline
23741 i /= 2;\SpecialChar ~
23742 \SpecialChar ~
23743 \SpecialChar ~
23744 \SpecialChar ~
23745 \SpecialChar ~
23746 \SpecialChar ~
23747 \SpecialChar ~
23748  /* changed to: */\SpecialChar ~
23749 \SpecialChar ~
23750 \SpecialChar ~
23751 \SpecialChar ~
23752  i >>= 1;
23753 \newline
23754 i = j - j;\SpecialChar ~
23755 \SpecialChar ~
23756 \SpecialChar ~
23757 \SpecialChar ~
23758  /* changed to: */\SpecialChar ~
23759 \SpecialChar ~
23760 \SpecialChar ~
23761 \SpecialChar ~
23762  i = 0;
23763 \newline
23764 i = j / 1;\SpecialChar ~
23765 \SpecialChar ~
23766 \SpecialChar ~
23767 \SpecialChar ~
23768  /* changed to: */\SpecialChar ~
23769 \SpecialChar ~
23770 \SpecialChar ~
23771 \SpecialChar ~
23772  i = j;
23773 \layout Standard
23774
23775 Note the subexpressions
23776 \begin_inset LatexCommand \index{Subexpression}
23777
23778 \end_inset
23779
23780  given above are generally introduced by macro expansions or as a result
23781  of copy/constant propagation.
23782 \layout Subsection
23783
23784 'switch' Statements
23785 \begin_inset LatexCommand \label{sub:'switch'-Statements}
23786
23787 \end_inset
23788
23789
23790 \begin_inset LatexCommand \index{switch statement}
23791
23792 \end_inset
23793
23794
23795 \layout Standard
23796
23797 SDCC can optimize switch statements to jump tables
23798 \begin_inset LatexCommand \index{jump tables}
23799
23800 \end_inset
23801
23802 .
23803  It makes the decision based on an estimate of the generated code size.
23804  SDCC is quite liberal in the requirements for jump table generation:
23805 \layout Itemize
23806
23807 The labels need not be in order, and the starting number need not be one
23808  or zero, the case labels are in numerical sequence or not too many case
23809  labels are missing.
23810 \begin_deeper
23811 \layout Verse
23812
23813
23814 \family typewriter
23815 switch(i) {\SpecialChar ~
23816 \SpecialChar ~
23817 \SpecialChar ~
23818 \SpecialChar ~
23819 \SpecialChar ~
23820 \SpecialChar ~
23821 \SpecialChar ~
23822 \SpecialChar ~
23823 \SpecialChar ~
23824 \SpecialChar ~
23825 \SpecialChar ~
23826 \SpecialChar ~
23827 \SpecialChar ~
23828 \SpecialChar ~
23829 \SpecialChar ~
23830 \SpecialChar ~
23831 \SpecialChar ~
23832 \SpecialChar ~
23833 \SpecialChar ~
23834 \SpecialChar ~
23835 \SpecialChar ~
23836 \SpecialChar ~
23837 \SpecialChar ~
23838 \SpecialChar ~
23839 \SpecialChar ~
23840 \SpecialChar ~
23841 switch (i) {
23842 \newline
23843 \SpecialChar ~
23844 \SpecialChar ~
23845 \SpecialChar ~
23846 case 4: ...\SpecialChar ~
23847 \SpecialChar ~
23848 \SpecialChar ~
23849 \SpecialChar ~
23850 \SpecialChar ~
23851 \SpecialChar ~
23852 \SpecialChar ~
23853 \SpecialChar ~
23854 \SpecialChar ~
23855 \SpecialChar ~
23856 \SpecialChar ~
23857 \SpecialChar ~
23858 \SpecialChar ~
23859 \SpecialChar ~
23860 \SpecialChar ~
23861 \SpecialChar ~
23862 \SpecialChar ~
23863 \SpecialChar ~
23864 \SpecialChar ~
23865 \SpecialChar ~
23866 \SpecialChar ~
23867 \SpecialChar ~
23868 \SpecialChar ~
23869 \SpecialChar ~
23870 \SpecialChar ~
23871 \SpecialChar ~
23872 case 0: ...
23873
23874 \newline
23875 \SpecialChar ~
23876 \SpecialChar ~
23877 \SpecialChar ~
23878 case 5: ...\SpecialChar ~
23879 \SpecialChar ~
23880 \SpecialChar ~
23881 \SpecialChar ~
23882 \SpecialChar ~
23883 \SpecialChar ~
23884 \SpecialChar ~
23885 \SpecialChar ~
23886 \SpecialChar ~
23887 \SpecialChar ~
23888 \SpecialChar ~
23889 \SpecialChar ~
23890 \SpecialChar ~
23891 \SpecialChar ~
23892 \SpecialChar ~
23893 \SpecialChar ~
23894 \SpecialChar ~
23895 \SpecialChar ~
23896 \SpecialChar ~
23897 \SpecialChar ~
23898 \SpecialChar ~
23899 \SpecialChar ~
23900 \SpecialChar ~
23901 \SpecialChar ~
23902 \SpecialChar ~
23903 \SpecialChar ~
23904 case 1: ...
23905
23906 \newline
23907 \SpecialChar ~
23908 \SpecialChar ~
23909 \SpecialChar ~
23910 case 3: ...\SpecialChar ~
23911 \SpecialChar ~
23912 \SpecialChar ~
23913 \SpecialChar ~
23914 \SpecialChar ~
23915 \SpecialChar ~
23916 \SpecialChar ~
23917 \SpecialChar ~
23918 \SpecialChar ~
23919 \SpecialChar ~
23920 \SpecialChar ~
23921 \SpecialChar ~
23922 \SpecialChar ~
23923 \SpecialChar ~
23924 \SpecialChar ~
23925 \SpecialChar ~
23926 \SpecialChar ~
23927 \SpecialChar ~
23928 \SpecialChar ~
23929 \SpecialChar ~
23930 \SpecialChar ~
23931 \SpecialChar ~
23932 \SpecialChar ~
23933 \SpecialChar ~
23934 \SpecialChar ~
23935 \SpecialChar ~
23936
23937 \newline
23938 \SpecialChar ~
23939 \SpecialChar ~
23940 \SpecialChar ~
23941 case 6: ...\SpecialChar ~
23942 \SpecialChar ~
23943 \SpecialChar ~
23944 \SpecialChar ~
23945 \SpecialChar ~
23946 \SpecialChar ~
23947 \SpecialChar ~
23948 \SpecialChar ~
23949 \SpecialChar ~
23950 \SpecialChar ~
23951 \SpecialChar ~
23952 \SpecialChar ~
23953 \SpecialChar ~
23954 \SpecialChar ~
23955 \SpecialChar ~
23956 \SpecialChar ~
23957 \SpecialChar ~
23958 \SpecialChar ~
23959 \SpecialChar ~
23960 \SpecialChar ~
23961 \SpecialChar ~
23962 \SpecialChar ~
23963 \SpecialChar ~
23964 \SpecialChar ~
23965 \SpecialChar ~
23966 \SpecialChar ~
23967 case 3: ...
23968
23969 \newline
23970 \SpecialChar ~
23971 \SpecialChar ~
23972 \SpecialChar ~
23973 case 7: ...\SpecialChar ~
23974 \SpecialChar ~
23975 \SpecialChar ~
23976 \SpecialChar ~
23977 \SpecialChar ~
23978 \SpecialChar ~
23979 \SpecialChar ~
23980 \SpecialChar ~
23981 \SpecialChar ~
23982 \SpecialChar ~
23983 \SpecialChar ~
23984 \SpecialChar ~
23985 \SpecialChar ~
23986 \SpecialChar ~
23987 \SpecialChar ~
23988 \SpecialChar ~
23989 \SpecialChar ~
23990 \SpecialChar ~
23991 \SpecialChar ~
23992 \SpecialChar ~
23993 \SpecialChar ~
23994 \SpecialChar ~
23995 \SpecialChar ~
23996 \SpecialChar ~
23997 \SpecialChar ~
23998 \SpecialChar ~
23999 case 4: ...
24000
24001 \newline
24002 \SpecialChar ~
24003 \SpecialChar ~
24004 \SpecialChar ~
24005 case 8: ...\SpecialChar ~
24006 \SpecialChar ~
24007 \SpecialChar ~
24008 \SpecialChar ~
24009 \SpecialChar ~
24010 \SpecialChar ~
24011 \SpecialChar ~
24012 \SpecialChar ~
24013 \SpecialChar ~
24014 \SpecialChar ~
24015 \SpecialChar ~
24016 \SpecialChar ~
24017 \SpecialChar ~
24018 \SpecialChar ~
24019 \SpecialChar ~
24020 \SpecialChar ~
24021 \SpecialChar ~
24022 \SpecialChar ~
24023 \SpecialChar ~
24024 \SpecialChar ~
24025 \SpecialChar ~
24026 \SpecialChar ~
24027 \SpecialChar ~
24028 \SpecialChar ~
24029 \SpecialChar ~
24030 \SpecialChar ~
24031 case 5: ...
24032
24033 \newline
24034 \SpecialChar ~
24035 \SpecialChar ~
24036 \SpecialChar ~
24037 case 9: ...\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 \SpecialChar ~
24052 \SpecialChar ~
24053 \SpecialChar ~
24054 \SpecialChar ~
24055 \SpecialChar ~
24056 \SpecialChar ~
24057 \SpecialChar ~
24058 \SpecialChar ~
24059 \SpecialChar ~
24060 \SpecialChar ~
24061 \SpecialChar ~
24062 \SpecialChar ~
24063 case 6: ...
24064
24065 \newline
24066 \SpecialChar ~
24067 \SpecialChar ~
24068 \SpecialChar ~
24069 case 10: ...\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 \SpecialChar ~
24083 \SpecialChar ~
24084 \SpecialChar ~
24085 \SpecialChar ~
24086 \SpecialChar ~
24087 \SpecialChar ~
24088 \SpecialChar ~
24089 \SpecialChar ~
24090 \SpecialChar ~
24091 \SpecialChar ~
24092 \SpecialChar ~
24093 \SpecialChar ~
24094 case 7: ...
24095
24096 \newline
24097 \SpecialChar ~
24098 \SpecialChar ~
24099 \SpecialChar ~
24100 case 11: ...\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 \SpecialChar ~
24115 \SpecialChar ~
24116 \SpecialChar ~
24117 \SpecialChar ~
24118 \SpecialChar ~
24119 \SpecialChar ~
24120 \SpecialChar ~
24121 \SpecialChar ~
24122 \SpecialChar ~
24123 \SpecialChar ~
24124 \SpecialChar ~
24125 case 8: ...
24126
24127 \newline
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 \SpecialChar ~
24147 \SpecialChar ~
24148 \SpecialChar ~
24149 \SpecialChar ~
24150 \SpecialChar ~
24151 \SpecialChar ~
24152 \SpecialChar ~
24153 \SpecialChar ~
24154 \SpecialChar ~
24155 \SpecialChar ~
24156 \SpecialChar ~
24157 \SpecialChar ~
24158 \SpecialChar ~
24159 \SpecialChar ~
24160 \SpecialChar ~
24161 \SpecialChar ~
24162 \SpecialChar ~
24163 \SpecialChar ~
24164 }
24165 \layout Standard
24166
24167 Both the above switch statements will be implemented using a jump-table.
24168  The example to the right side is slightly more efficient as the check for
24169  the lower boundary of the jump-table is not needed.
24170 \end_deeper
24171 \layout Itemize
24172
24173 The number of case labels is not larger than supported by the target architectur
24174 e.
24175 \layout Itemize
24176
24177 If the case labels are not in numerical sequence ('gaps' between cases)
24178  SDCC checks whether a jump table with additionally inserted dummy cases
24179  is still attractive.
24180
24181 \layout Itemize
24182
24183 If the starting number is not zero and a check for the lower boundary of
24184  the jump-table can thus be eliminated SDCC might insert dummy cases 0,
24185  ...
24186  .
24187 \layout Standard
24188
24189 Switch statements which have large gaps in the numeric sequence or those
24190  that have too many case labels can be split into more than one switch statement
24191  for efficient code generation, e.g.:
24192 \layout Verse
24193
24194
24195 \family typewriter
24196 switch (i) {
24197 \newline
24198 \SpecialChar ~
24199 \SpecialChar ~
24200 case 1: ...
24201
24202 \newline
24203 \SpecialChar ~
24204 \SpecialChar ~
24205 case 2: ...
24206
24207 \newline
24208 \SpecialChar ~
24209 \SpecialChar ~
24210 case 3: ...
24211
24212 \newline
24213 \SpecialChar ~
24214 \SpecialChar ~
24215 case 4: ...
24216
24217 \newline
24218 \SpecialChar ~
24219 \SpecialChar ~
24220 case 5: ...
24221
24222 \newline
24223 \SpecialChar ~
24224 \SpecialChar ~
24225 case 6: ...
24226
24227 \newline
24228 \SpecialChar ~
24229 \SpecialChar ~
24230 case 7: ...
24231
24232 \newline
24233 \SpecialChar ~
24234 \SpecialChar ~
24235 case 101: ...
24236
24237 \newline
24238 \SpecialChar ~
24239 \SpecialChar ~
24240 case 102: ...
24241
24242 \newline
24243 \SpecialChar ~
24244 \SpecialChar ~
24245 case 103: ...
24246
24247 \newline
24248 \SpecialChar ~
24249 \SpecialChar ~
24250 case 104: ...
24251
24252 \newline
24253 \SpecialChar ~
24254 \SpecialChar ~
24255 case 105: ...
24256
24257 \newline
24258 \SpecialChar ~
24259 \SpecialChar ~
24260 case 106: ...
24261
24262 \newline
24263 \SpecialChar ~
24264 \SpecialChar ~
24265 case 107: ...
24266
24267 \newline
24268 }
24269 \layout Standard
24270
24271 If the above switch statement is broken down into two switch statements
24272 \layout Verse
24273
24274
24275 \family typewriter
24276 switch (i) {
24277 \newline
24278 \SpecialChar ~
24279 \SpecialChar ~
24280 case 1: ...
24281
24282 \newline
24283 \SpecialChar ~
24284 \SpecialChar ~
24285 case 2: ...
24286
24287 \newline
24288 \SpecialChar ~
24289 \SpecialChar ~
24290 case 3: ...
24291
24292 \newline
24293 \SpecialChar ~
24294 \SpecialChar ~
24295 case 4: ...
24296
24297 \newline
24298 \SpecialChar ~
24299 \SpecialChar ~
24300 case 5: ...
24301
24302 \newline
24303 \SpecialChar ~
24304 \SpecialChar ~
24305 case 6: ...
24306
24307 \newline
24308 \SpecialChar ~
24309 \SpecialChar ~
24310 case 7: ...
24311
24312 \newline
24313 }
24314 \layout Standard
24315
24316 and
24317 \layout Verse
24318
24319
24320 \family typewriter
24321 switch (i) {
24322 \newline
24323 \SpecialChar ~
24324 \SpecialChar ~
24325 case 101: ...
24326
24327 \newline
24328 \SpecialChar ~
24329 \SpecialChar ~
24330 case 102: ...
24331
24332 \newline
24333 \SpecialChar ~
24334 \SpecialChar ~
24335 case 103: ...
24336
24337 \newline
24338 \SpecialChar ~
24339 \SpecialChar ~
24340 case 104: ...
24341
24342 \newline
24343 \SpecialChar ~
24344 \SpecialChar ~
24345 case 105: ...
24346
24347 \newline
24348 \SpecialChar ~
24349 \SpecialChar ~
24350 case 106: ...
24351
24352 \newline
24353 \SpecialChar ~
24354 \SpecialChar ~
24355 case 107: ...
24356
24357 \newline
24358 }
24359 \layout Standard
24360
24361 then both the switch statements will be implemented using jump-tables whereas
24362  the unmodified switch statement will not be.
24363 \layout Comment
24364
24365 There might be reasons which SDCC cannot know about to either favour or
24366  not favour jump tables.
24367  If the target system has to be as quick for the last switch case as for
24368  the first (pro jump table), or if the switch argument is known to be zero
24369  in the majority of the cases (contra jump table).
24370 \layout Standard
24371
24372 The pragma nojtbound
24373 \begin_inset LatexCommand \index{\#pragma nojtbound}
24374
24375 \end_inset
24376
24377  can be used to turn off checking the
24378 \emph on
24379 j
24380 \emph default
24381 ump
24382 \emph on
24383 t
24384 \emph default
24385 able
24386 \emph on
24387 bound
24388 \emph default
24389 aries.
24390  It has no effect if a default label is supplied.
24391  Use of this pragma is dangerous: if the switch
24392 \begin_inset LatexCommand \index{switch statement}
24393
24394 \end_inset
24395
24396  argument is not matched by a case statement the processor will happily
24397  jump into Nirvana.
24398 \layout Subsection
24399
24400 Bit-shifting Operations
24401 \begin_inset LatexCommand \index{Bit shifting}
24402
24403 \end_inset
24404
24405 .
24406 \layout Standard
24407
24408 Bit shifting is one of the most frequently used operation in embedded programmin
24409 g.
24410  SDCC tries to implement bit-shift operations in the most efficient way
24411  possible, e.g.:
24412 \layout Verse
24413
24414
24415 \family typewriter
24416 unsigned char i;
24417 \newline
24418 ...
24419
24420 \newline
24421 i >>= 4;
24422 \newline
24423 ...
24424 \layout Standard
24425
24426 generates the following code:
24427 \layout Verse
24428
24429
24430 \family typewriter
24431 mov\SpecialChar ~
24432  a,_i
24433 \newline
24434 swap a
24435 \newline
24436 anl\SpecialChar ~
24437  a,#0x0f
24438 \newline
24439 mov\SpecialChar ~
24440  _i,a
24441 \layout Standard
24442
24443 In general SDCC will never setup a loop if the shift count is known.
24444  Another example:
24445 \layout Verse
24446
24447
24448 \family typewriter
24449 unsigned int i;
24450 \newline
24451 ...
24452
24453 \newline
24454 i >>= 9;
24455 \newline
24456 ...
24457 \layout Standard
24458
24459 will generate:
24460 \layout Verse
24461
24462
24463 \family typewriter
24464 mov\SpecialChar ~
24465 \SpecialChar ~
24466 a,(_i + 1)
24467 \newline
24468 mov\SpecialChar ~
24469 \SpecialChar ~
24470 (_i + 1),#0x00
24471 \newline
24472 clr\SpecialChar ~
24473 \SpecialChar ~
24474 c
24475 \newline
24476 rrc\SpecialChar ~
24477 \SpecialChar ~
24478 a
24479 \newline
24480 mov\SpecialChar ~
24481 \SpecialChar ~
24482 _i,a
24483 \layout Subsection
24484
24485 Bit-rotation
24486 \begin_inset LatexCommand \index{Bit rotation}
24487
24488 \end_inset
24489
24490
24491 \layout Standard
24492
24493 A special case of the bit-shift operation is bit rotation
24494 \begin_inset LatexCommand \index{rotating bits}
24495
24496 \end_inset
24497
24498 , SDCC recognizes the following expression to be a left bit-rotation:
24499 \layout Verse
24500
24501
24502 \family typewriter
24503 \series bold
24504 unsigned
24505 \series default
24506 \SpecialChar ~
24507 \SpecialChar ~
24508 char i;\SpecialChar ~
24509 \SpecialChar ~
24510 \SpecialChar ~
24511 \SpecialChar ~
24512 \SpecialChar ~
24513 \SpecialChar ~
24514 \SpecialChar ~
24515 \SpecialChar ~
24516 \SpecialChar ~
24517 \SpecialChar ~
24518 \SpecialChar ~
24519 /* unsigned is needed for rotation */
24520 \newline
24521 ...
24522
24523 \newline
24524 i = ((i << 1) | (i >> 7));
24525 \family default
24526
24527 \newline
24528
24529 \family typewriter
24530 ...
24531 \layout Standard
24532
24533 will generate the following code:
24534 \layout Verse
24535
24536
24537 \family typewriter
24538 mov\SpecialChar ~
24539 \SpecialChar ~
24540 a,_i
24541 \newline
24542 rl\SpecialChar ~
24543 \SpecialChar ~
24544 \SpecialChar ~
24545 a
24546 \newline
24547 mov\SpecialChar ~
24548 \SpecialChar ~
24549 _i,a
24550 \layout Standard
24551
24552 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
24553 ns of this case will also be recognized as bit-rotation, i.e.:
24554 \layout Verse
24555
24556
24557 \family typewriter
24558 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
24559 \layout Subsection
24560
24561 Nibble and Byte Swapping
24562 \layout Standard
24563
24564 Other special cases of the bit-shift operations are nibble or byte swapping
24565 \begin_inset LatexCommand \index{swapping nibbles/bytes}
24566
24567 \end_inset
24568
24569 , SDCC recognizes the following expressions:
24570 \layout Verse
24571
24572
24573 \family typewriter
24574 \series bold
24575 unsigned
24576 \series default
24577 \SpecialChar ~
24578 \SpecialChar ~
24579 char i;
24580 \newline
24581
24582 \series bold
24583 unsigned
24584 \series default
24585 \SpecialChar ~
24586 \SpecialChar ~
24587 int j;
24588 \newline
24589 ...
24590
24591 \newline
24592 i = ((i << 4) | (i >> 4));
24593 \family default
24594
24595 \newline
24596
24597 \family typewriter
24598 j = ((j << 8) | (j >> 8));
24599 \layout Standard
24600
24601 and generates a swap instruction for the nibble swapping
24602 \begin_inset LatexCommand \index{Nibble swapping}
24603
24604 \end_inset
24605
24606  or move instructions for the byte swapping
24607 \begin_inset LatexCommand \index{Byte swapping}
24608
24609 \end_inset
24610
24611 .
24612  The
24613 \begin_inset Quotes sld
24614 \end_inset
24615
24616 j
24617 \begin_inset Quotes srd
24618 \end_inset
24619
24620  example can be used to convert from little to big-endian or vice versa.
24621  If you want to change the endianness of a
24622 \emph on
24623 signed
24624 \emph default
24625  integer you have to cast to
24626 \family typewriter
24627 (unsigned int)
24628 \family default
24629  first.
24630 \layout Standard
24631
24632 Note that SDCC stores numbers in little-endian
24633 \begin_inset Foot
24634 collapsed false
24635
24636 \layout Standard
24637
24638 Usually 8-bit processors don't care much about endianness.
24639  This is not the case for the standard 8051 which only has an instruction
24640  to increment its
24641 \emph on
24642 dptr
24643 \emph default
24644
24645 \begin_inset LatexCommand \index{DPTR}
24646
24647 \end_inset
24648
24649 -datapointer
24650 \emph on
24651
24652 \emph default
24653 so little-endian is the more efficient byte order.
24654 \end_inset
24655
24656
24657 \begin_inset LatexCommand \index{little-endian}
24658
24659 \end_inset
24660
24661
24662 \begin_inset LatexCommand \index{Endianness}
24663
24664 \end_inset
24665
24666  format (i.e.
24667  lowest order first).
24668 \layout Subsection
24669
24670 Highest Order Bit
24671 \begin_inset LatexCommand \index{Highest Order Bit}
24672
24673 \end_inset
24674
24675  / Any Order Bit
24676 \begin_inset LatexCommand \index{Any Order Bit}
24677
24678 \end_inset
24679
24680
24681 \layout Standard
24682
24683 It is frequently required to obtain the highest order bit of an integral
24684  type (long, int, short or char types).
24685  Also obtaining any other order bit is not uncommon.
24686  SDCC recognizes the following expressions to yield the highest order bit
24687  and generates optimized code for it, e.g.:
24688 \layout Verse
24689
24690
24691 \family typewriter
24692 unsigned int gint;
24693 \newline
24694
24695 \newline
24696 foo () {
24697 \newline
24698 \SpecialChar ~
24699 \SpecialChar ~
24700 unsigned char hob1, aob1;
24701 \newline
24702 \SpecialChar ~
24703 \SpecialChar ~
24704 bit hob2, hob3, aob2, aob3;
24705 \newline
24706 \SpecialChar ~
24707 \SpecialChar ~
24708 ...
24709
24710 \newline
24711 \SpecialChar ~
24712 \SpecialChar ~
24713 hob1 = (gint >> 15) & 1;
24714 \newline
24715 \SpecialChar ~
24716 \SpecialChar ~
24717 hob2 = (gint >> 15) & 1;
24718 \newline
24719 \SpecialChar ~
24720 \SpecialChar ~
24721 hob3 = gint & 0x8000;
24722 \newline
24723 \SpecialChar ~
24724 \SpecialChar ~
24725 aob1 = (gint >> 9) & 1;
24726 \newline
24727 \SpecialChar ~
24728 \SpecialChar ~
24729 aob2 = (gint >> 8) & 1;
24730 \newline
24731 \SpecialChar ~
24732 \SpecialChar ~
24733 aob3 = gint & 0x0800;
24734 \newline
24735 \SpecialChar ~
24736 \SpecialChar ~
24737 ..
24738
24739 \newline
24740 }
24741 \layout Standard
24742
24743 will generate the following code:
24744 \layout Verse
24745
24746
24747 \family typewriter
24748 \SpecialChar ~
24749 \SpecialChar ~
24750 \SpecialChar ~
24751 \SpecialChar ~
24752 \SpecialChar ~
24753 \SpecialChar ~
24754 \SpecialChar ~
24755 \SpecialChar ~
24756 \SpecialChar ~
24757 \SpecialChar ~
24758 \SpecialChar ~
24759 \SpecialChar ~
24760 \SpecialChar ~
24761 \SpecialChar ~
24762 \SpecialChar ~
24763 \SpecialChar ~
24764 \SpecialChar ~
24765 \SpecialChar ~
24766 \SpecialChar ~
24767 \SpecialChar ~
24768 \SpecialChar ~
24769 \SpecialChar ~
24770 \SpecialChar ~
24771 \SpecialChar ~
24772 \SpecialChar ~
24773  61 ;\SpecialChar ~
24774  hob.c 7
24775 \newline
24776 000A E5*01\SpecialChar ~
24777 \SpecialChar ~
24778 \SpecialChar ~
24779 \SpecialChar ~
24780 \SpecialChar ~
24781 \SpecialChar ~
24782 \SpecialChar ~
24783 \SpecialChar ~
24784 \SpecialChar ~
24785 \SpecialChar ~
24786 \SpecialChar ~
24787 \SpecialChar ~
24788 \SpecialChar ~
24789 \SpecialChar ~
24790 \SpecialChar ~
24791  62\SpecialChar ~
24792 \SpecialChar ~
24793 \SpecialChar ~
24794 \SpecialChar ~
24795 \SpecialChar ~
24796 \SpecialChar ~
24797 \SpecialChar ~
24798 \SpecialChar ~
24799  mov\SpecialChar ~
24800 \SpecialChar ~
24801  a,(_gint + 1)
24802 \newline
24803 000C 23\SpecialChar ~
24804 \SpecialChar ~
24805 \SpecialChar ~
24806 \SpecialChar ~
24807 \SpecialChar ~
24808 \SpecialChar ~
24809 \SpecialChar ~
24810 \SpecialChar ~
24811 \SpecialChar ~
24812 \SpecialChar ~
24813 \SpecialChar ~
24814 \SpecialChar ~
24815 \SpecialChar ~
24816 \SpecialChar ~
24817 \SpecialChar ~
24818 \SpecialChar ~
24819 \SpecialChar ~
24820 \SpecialChar ~
24821  63\SpecialChar ~
24822 \SpecialChar ~
24823 \SpecialChar ~
24824 \SpecialChar ~
24825 \SpecialChar ~
24826 \SpecialChar ~
24827 \SpecialChar ~
24828 \SpecialChar ~
24829  rl\SpecialChar ~
24830 \SpecialChar ~
24831 \SpecialChar ~
24832  a
24833 \newline
24834 000D 54 01\SpecialChar ~
24835 \SpecialChar ~
24836 \SpecialChar ~
24837 \SpecialChar ~
24838 \SpecialChar ~
24839 \SpecialChar ~
24840 \SpecialChar ~
24841 \SpecialChar ~
24842 \SpecialChar ~
24843 \SpecialChar ~
24844 \SpecialChar ~
24845 \SpecialChar ~
24846 \SpecialChar ~
24847 \SpecialChar ~
24848 \SpecialChar ~
24849  64\SpecialChar ~
24850 \SpecialChar ~
24851 \SpecialChar ~
24852 \SpecialChar ~
24853 \SpecialChar ~
24854 \SpecialChar ~
24855 \SpecialChar ~
24856 \SpecialChar ~
24857  anl\SpecialChar ~
24858 \SpecialChar ~
24859  a,#0x01
24860 \newline
24861 000F F5*02\SpecialChar ~
24862 \SpecialChar ~
24863 \SpecialChar ~
24864 \SpecialChar ~
24865 \SpecialChar ~
24866 \SpecialChar ~
24867 \SpecialChar ~
24868 \SpecialChar ~
24869 \SpecialChar ~
24870 \SpecialChar ~
24871 \SpecialChar ~
24872 \SpecialChar ~
24873 \SpecialChar ~
24874 \SpecialChar ~
24875 \SpecialChar ~
24876  65\SpecialChar ~
24877 \SpecialChar ~
24878 \SpecialChar ~
24879 \SpecialChar ~
24880 \SpecialChar ~
24881 \SpecialChar ~
24882 \SpecialChar ~
24883 \SpecialChar ~
24884  mov\SpecialChar ~
24885 \SpecialChar ~
24886  _foo_hob1_1_1,a
24887 \newline
24888 \SpecialChar ~
24889 \SpecialChar ~
24890 \SpecialChar ~
24891 \SpecialChar ~
24892 \SpecialChar ~
24893 \SpecialChar ~
24894 \SpecialChar ~
24895 \SpecialChar ~
24896 \SpecialChar ~
24897 \SpecialChar ~
24898 \SpecialChar ~
24899 \SpecialChar ~
24900 \SpecialChar ~
24901 \SpecialChar ~
24902 \SpecialChar ~
24903 \SpecialChar ~
24904 \SpecialChar ~
24905 \SpecialChar ~
24906 \SpecialChar ~
24907 \SpecialChar ~
24908 \SpecialChar ~
24909 \SpecialChar ~
24910 \SpecialChar ~
24911 \SpecialChar ~
24912 \SpecialChar ~
24913  66 ;\SpecialChar ~
24914  hob.c 8
24915 \newline
24916 0011 E5*01\SpecialChar ~
24917 \SpecialChar ~
24918 \SpecialChar ~
24919 \SpecialChar ~
24920 \SpecialChar ~
24921 \SpecialChar ~
24922 \SpecialChar ~
24923 \SpecialChar ~
24924 \SpecialChar ~
24925 \SpecialChar ~
24926 \SpecialChar ~
24927 \SpecialChar ~
24928 \SpecialChar ~
24929 \SpecialChar ~
24930 \SpecialChar ~
24931  67\SpecialChar ~
24932 \SpecialChar ~
24933 \SpecialChar ~
24934 \SpecialChar ~
24935 \SpecialChar ~
24936 \SpecialChar ~
24937 \SpecialChar ~
24938 \SpecialChar ~
24939  mov\SpecialChar ~
24940 \SpecialChar ~
24941  a,(_gint + 1)
24942 \newline
24943 0013 33\SpecialChar ~
24944 \SpecialChar ~
24945 \SpecialChar ~
24946 \SpecialChar ~
24947 \SpecialChar ~
24948 \SpecialChar ~
24949 \SpecialChar ~
24950 \SpecialChar ~
24951 \SpecialChar ~
24952 \SpecialChar ~
24953 \SpecialChar ~
24954 \SpecialChar ~
24955 \SpecialChar ~
24956 \SpecialChar ~
24957 \SpecialChar ~
24958 \SpecialChar ~
24959 \SpecialChar ~
24960 \SpecialChar ~
24961  68\SpecialChar ~
24962 \SpecialChar ~
24963 \SpecialChar ~
24964 \SpecialChar ~
24965 \SpecialChar ~
24966 \SpecialChar ~
24967 \SpecialChar ~
24968 \SpecialChar ~
24969  rlc\SpecialChar ~
24970 \SpecialChar ~
24971  a
24972 \newline
24973 0014 92*00\SpecialChar ~
24974 \SpecialChar ~
24975 \SpecialChar ~
24976 \SpecialChar ~
24977 \SpecialChar ~
24978 \SpecialChar ~
24979 \SpecialChar ~
24980 \SpecialChar ~
24981 \SpecialChar ~
24982 \SpecialChar ~
24983 \SpecialChar ~
24984 \SpecialChar ~
24985 \SpecialChar ~
24986 \SpecialChar ~
24987 \SpecialChar ~
24988  69\SpecialChar ~
24989 \SpecialChar ~
24990 \SpecialChar ~
24991 \SpecialChar ~
24992 \SpecialChar ~
24993 \SpecialChar ~
24994 \SpecialChar ~
24995 \SpecialChar ~
24996  mov\SpecialChar ~
24997 \SpecialChar ~
24998  _foo_hob2_1_1,c
24999 \newline
25000 \SpecialChar ~
25001 \SpecialChar ~
25002 \SpecialChar ~
25003 \SpecialChar ~
25004 \SpecialChar ~
25005 \SpecialChar ~
25006 \SpecialChar ~
25007 \SpecialChar ~
25008 \SpecialChar ~
25009 \SpecialChar ~
25010 \SpecialChar ~
25011 \SpecialChar ~
25012 \SpecialChar ~
25013 \SpecialChar ~
25014 \SpecialChar ~
25015 \SpecialChar ~
25016 \SpecialChar ~
25017 \SpecialChar ~
25018 \SpecialChar ~
25019 \SpecialChar ~
25020 \SpecialChar ~
25021 \SpecialChar ~
25022 \SpecialChar ~
25023 \SpecialChar ~
25024 \SpecialChar ~
25025  66 ;\SpecialChar ~
25026  hob.c 9
25027 \newline
25028 0016 E5*01\SpecialChar ~
25029 \SpecialChar ~
25030 \SpecialChar ~
25031 \SpecialChar ~
25032 \SpecialChar ~
25033 \SpecialChar ~
25034 \SpecialChar ~
25035 \SpecialChar ~
25036 \SpecialChar ~
25037 \SpecialChar ~
25038 \SpecialChar ~
25039 \SpecialChar ~
25040 \SpecialChar ~
25041 \SpecialChar ~
25042 \SpecialChar ~
25043  67\SpecialChar ~
25044 \SpecialChar ~
25045 \SpecialChar ~
25046 \SpecialChar ~
25047 \SpecialChar ~
25048 \SpecialChar ~
25049 \SpecialChar ~
25050 \SpecialChar ~
25051  mov\SpecialChar ~
25052 \SpecialChar ~
25053  a,(_gint + 1)
25054 \newline
25055 0018 33\SpecialChar ~
25056 \SpecialChar ~
25057 \SpecialChar ~
25058 \SpecialChar ~
25059 \SpecialChar ~
25060 \SpecialChar ~
25061 \SpecialChar ~
25062 \SpecialChar ~
25063 \SpecialChar ~
25064 \SpecialChar ~
25065 \SpecialChar ~
25066 \SpecialChar ~
25067 \SpecialChar ~
25068 \SpecialChar ~
25069 \SpecialChar ~
25070 \SpecialChar ~
25071 \SpecialChar ~
25072 \SpecialChar ~
25073  68\SpecialChar ~
25074 \SpecialChar ~
25075 \SpecialChar ~
25076 \SpecialChar ~
25077 \SpecialChar ~
25078 \SpecialChar ~
25079 \SpecialChar ~
25080 \SpecialChar ~
25081  rlc\SpecialChar ~
25082 \SpecialChar ~
25083  a
25084 \newline
25085 0019 92*01\SpecialChar ~
25086 \SpecialChar ~
25087 \SpecialChar ~
25088 \SpecialChar ~
25089 \SpecialChar ~
25090 \SpecialChar ~
25091 \SpecialChar ~
25092 \SpecialChar ~
25093 \SpecialChar ~
25094 \SpecialChar ~
25095 \SpecialChar ~
25096 \SpecialChar ~
25097 \SpecialChar ~
25098 \SpecialChar ~
25099 \SpecialChar ~
25100  69\SpecialChar ~
25101 \SpecialChar ~
25102 \SpecialChar ~
25103 \SpecialChar ~
25104 \SpecialChar ~
25105 \SpecialChar ~
25106 \SpecialChar ~
25107 \SpecialChar ~
25108  mov\SpecialChar ~
25109 \SpecialChar ~
25110  _foo_hob3_1_1,c
25111 \newline
25112 \SpecialChar ~
25113 \SpecialChar ~
25114 \SpecialChar ~
25115 \SpecialChar ~
25116 \SpecialChar ~
25117 \SpecialChar ~
25118 \SpecialChar ~
25119 \SpecialChar ~
25120 \SpecialChar ~
25121 \SpecialChar ~
25122 \SpecialChar ~
25123 \SpecialChar ~
25124 \SpecialChar ~
25125 \SpecialChar ~
25126 \SpecialChar ~
25127 \SpecialChar ~
25128 \SpecialChar ~
25129 \SpecialChar ~
25130 \SpecialChar ~
25131 \SpecialChar ~
25132 \SpecialChar ~
25133 \SpecialChar ~
25134 \SpecialChar ~
25135 \SpecialChar ~
25136 \SpecialChar ~
25137  70 ;\SpecialChar ~
25138  hob.c 10
25139 \newline
25140 001B E5*01\SpecialChar ~
25141 \SpecialChar ~
25142 \SpecialChar ~
25143 \SpecialChar ~
25144 \SpecialChar ~
25145 \SpecialChar ~
25146 \SpecialChar ~
25147 \SpecialChar ~
25148 \SpecialChar ~
25149 \SpecialChar ~
25150 \SpecialChar ~
25151 \SpecialChar ~
25152 \SpecialChar ~
25153 \SpecialChar ~
25154 \SpecialChar ~
25155  71\SpecialChar ~
25156 \SpecialChar ~
25157 \SpecialChar ~
25158 \SpecialChar ~
25159 \SpecialChar ~
25160 \SpecialChar ~
25161 \SpecialChar ~
25162 \SpecialChar ~
25163  mov\SpecialChar ~
25164 \SpecialChar ~
25165  a,(_gint + 1)
25166 \newline
25167 001D 03\SpecialChar ~
25168 \SpecialChar ~
25169 \SpecialChar ~
25170 \SpecialChar ~
25171 \SpecialChar ~
25172 \SpecialChar ~
25173 \SpecialChar ~
25174 \SpecialChar ~
25175 \SpecialChar ~
25176 \SpecialChar ~
25177 \SpecialChar ~
25178 \SpecialChar ~
25179 \SpecialChar ~
25180 \SpecialChar ~
25181 \SpecialChar ~
25182 \SpecialChar ~
25183 \SpecialChar ~
25184 \SpecialChar ~
25185  72\SpecialChar ~
25186 \SpecialChar ~
25187 \SpecialChar ~
25188 \SpecialChar ~
25189 \SpecialChar ~
25190 \SpecialChar ~
25191 \SpecialChar ~
25192 \SpecialChar ~
25193  rr\SpecialChar ~
25194 \SpecialChar ~
25195 \SpecialChar ~
25196  a
25197 \newline
25198 001E 54 01\SpecialChar ~
25199 \SpecialChar ~
25200 \SpecialChar ~
25201 \SpecialChar ~
25202 \SpecialChar ~
25203 \SpecialChar ~
25204 \SpecialChar ~
25205 \SpecialChar ~
25206 \SpecialChar ~
25207 \SpecialChar ~
25208 \SpecialChar ~
25209 \SpecialChar ~
25210 \SpecialChar ~
25211 \SpecialChar ~
25212 \SpecialChar ~
25213  73\SpecialChar ~
25214 \SpecialChar ~
25215 \SpecialChar ~
25216 \SpecialChar ~
25217 \SpecialChar ~
25218 \SpecialChar ~
25219 \SpecialChar ~
25220 \SpecialChar ~
25221  anl\SpecialChar ~
25222 \SpecialChar ~
25223  a,#0x01
25224 \newline
25225 0020 F5*03\SpecialChar ~
25226 \SpecialChar ~
25227 \SpecialChar ~
25228 \SpecialChar ~
25229 \SpecialChar ~
25230 \SpecialChar ~
25231 \SpecialChar ~
25232 \SpecialChar ~
25233 \SpecialChar ~
25234 \SpecialChar ~
25235 \SpecialChar ~
25236 \SpecialChar ~
25237 \SpecialChar ~
25238 \SpecialChar ~
25239 \SpecialChar ~
25240  74\SpecialChar ~
25241 \SpecialChar ~
25242 \SpecialChar ~
25243 \SpecialChar ~
25244 \SpecialChar ~
25245 \SpecialChar ~
25246 \SpecialChar ~
25247 \SpecialChar ~
25248  mov\SpecialChar ~
25249 \SpecialChar ~
25250  _foo_aob1_1_1,a
25251 \newline
25252 \SpecialChar ~
25253 \SpecialChar ~
25254 \SpecialChar ~
25255 \SpecialChar ~
25256 \SpecialChar ~
25257 \SpecialChar ~
25258 \SpecialChar ~
25259 \SpecialChar ~
25260 \SpecialChar ~
25261 \SpecialChar ~
25262 \SpecialChar ~
25263 \SpecialChar ~
25264 \SpecialChar ~
25265 \SpecialChar ~
25266 \SpecialChar ~
25267 \SpecialChar ~
25268 \SpecialChar ~
25269 \SpecialChar ~
25270 \SpecialChar ~
25271 \SpecialChar ~
25272 \SpecialChar ~
25273 \SpecialChar ~
25274 \SpecialChar ~
25275 \SpecialChar ~
25276 \SpecialChar ~
25277  75 ;\SpecialChar ~
25278  hob.c 11
25279 \newline
25280 0022 E5*01\SpecialChar ~
25281 \SpecialChar ~
25282 \SpecialChar ~
25283 \SpecialChar ~
25284 \SpecialChar ~
25285 \SpecialChar ~
25286 \SpecialChar ~
25287 \SpecialChar ~
25288 \SpecialChar ~
25289 \SpecialChar ~
25290 \SpecialChar ~
25291 \SpecialChar ~
25292 \SpecialChar ~
25293 \SpecialChar ~
25294 \SpecialChar ~
25295  76\SpecialChar ~
25296 \SpecialChar ~
25297 \SpecialChar ~
25298 \SpecialChar ~
25299 \SpecialChar ~
25300 \SpecialChar ~
25301 \SpecialChar ~
25302 \SpecialChar ~
25303  mov\SpecialChar ~
25304 \SpecialChar ~
25305  a,(_gint + 1)
25306 \newline
25307 0024 13\SpecialChar ~
25308 \SpecialChar ~
25309 \SpecialChar ~
25310 \SpecialChar ~
25311 \SpecialChar ~
25312 \SpecialChar ~
25313 \SpecialChar ~
25314 \SpecialChar ~
25315 \SpecialChar ~
25316 \SpecialChar ~
25317 \SpecialChar ~
25318 \SpecialChar ~
25319 \SpecialChar ~
25320 \SpecialChar ~
25321 \SpecialChar ~
25322 \SpecialChar ~
25323 \SpecialChar ~
25324 \SpecialChar ~
25325  77\SpecialChar ~
25326 \SpecialChar ~
25327 \SpecialChar ~
25328 \SpecialChar ~
25329 \SpecialChar ~
25330 \SpecialChar ~
25331 \SpecialChar ~
25332 \SpecialChar ~
25333  rrc\SpecialChar ~
25334 \SpecialChar ~
25335  a
25336 \newline
25337 0025 92*02\SpecialChar ~
25338 \SpecialChar ~
25339 \SpecialChar ~
25340 \SpecialChar ~
25341 \SpecialChar ~
25342 \SpecialChar ~
25343 \SpecialChar ~
25344 \SpecialChar ~
25345 \SpecialChar ~
25346 \SpecialChar ~
25347 \SpecialChar ~
25348 \SpecialChar ~
25349 \SpecialChar ~
25350 \SpecialChar ~
25351 \SpecialChar ~
25352  78\SpecialChar ~
25353 \SpecialChar ~
25354 \SpecialChar ~
25355 \SpecialChar ~
25356 \SpecialChar ~
25357 \SpecialChar ~
25358 \SpecialChar ~
25359 \SpecialChar ~
25360  mov\SpecialChar ~
25361 \SpecialChar ~
25362  _foo_aob2_1_1,c
25363 \newline
25364 \SpecialChar ~
25365 \SpecialChar ~
25366 \SpecialChar ~
25367 \SpecialChar ~
25368 \SpecialChar ~
25369 \SpecialChar ~
25370 \SpecialChar ~
25371 \SpecialChar ~
25372 \SpecialChar ~
25373 \SpecialChar ~
25374 \SpecialChar ~
25375 \SpecialChar ~
25376 \SpecialChar ~
25377 \SpecialChar ~
25378 \SpecialChar ~
25379 \SpecialChar ~
25380 \SpecialChar ~
25381 \SpecialChar ~
25382 \SpecialChar ~
25383 \SpecialChar ~
25384 \SpecialChar ~
25385 \SpecialChar ~
25386 \SpecialChar ~
25387 \SpecialChar ~
25388 \SpecialChar ~
25389  79 ;\SpecialChar ~
25390  hob.c 12
25391 \newline
25392 0027 E5*01\SpecialChar ~
25393 \SpecialChar ~
25394 \SpecialChar ~
25395 \SpecialChar ~
25396 \SpecialChar ~
25397 \SpecialChar ~
25398 \SpecialChar ~
25399 \SpecialChar ~
25400 \SpecialChar ~
25401 \SpecialChar ~
25402 \SpecialChar ~
25403 \SpecialChar ~
25404 \SpecialChar ~
25405 \SpecialChar ~
25406 \SpecialChar ~
25407  80\SpecialChar ~
25408 \SpecialChar ~
25409 \SpecialChar ~
25410 \SpecialChar ~
25411 \SpecialChar ~
25412 \SpecialChar ~
25413 \SpecialChar ~
25414 \SpecialChar ~
25415  mov\SpecialChar ~
25416 \SpecialChar ~
25417  a,(_gint + 1)
25418 \newline
25419 0029 A2 E3\SpecialChar ~
25420 \SpecialChar ~
25421 \SpecialChar ~
25422 \SpecialChar ~
25423 \SpecialChar ~
25424 \SpecialChar ~
25425 \SpecialChar ~
25426 \SpecialChar ~
25427 \SpecialChar ~
25428 \SpecialChar ~
25429 \SpecialChar ~
25430 \SpecialChar ~
25431 \SpecialChar ~
25432 \SpecialChar ~
25433 \SpecialChar ~
25434  81\SpecialChar ~
25435 \SpecialChar ~
25436 \SpecialChar ~
25437 \SpecialChar ~
25438 \SpecialChar ~
25439 \SpecialChar ~
25440 \SpecialChar ~
25441 \SpecialChar ~
25442  mov\SpecialChar ~
25443 \SpecialChar ~
25444  c,acc[3]
25445 \newline
25446 002B 92*03\SpecialChar ~
25447 \SpecialChar ~
25448 \SpecialChar ~
25449 \SpecialChar ~
25450 \SpecialChar ~
25451 \SpecialChar ~
25452 \SpecialChar ~
25453 \SpecialChar ~
25454 \SpecialChar ~
25455 \SpecialChar ~
25456 \SpecialChar ~
25457 \SpecialChar ~
25458 \SpecialChar ~
25459 \SpecialChar ~
25460 \SpecialChar ~
25461  82\SpecialChar ~
25462 \SpecialChar ~
25463 \SpecialChar ~
25464 \SpecialChar ~
25465 \SpecialChar ~
25466 \SpecialChar ~
25467 \SpecialChar ~
25468 \SpecialChar ~
25469  mov\SpecialChar ~
25470 \SpecialChar ~
25471  _foo_aob3_1_1,c
25472 \layout Standard
25473
25474 Other variations of these cases however will
25475 \emph on
25476 not
25477 \emph default
25478  be recognized.
25479  They are standard C expressions, so I heartily recommend these be the only
25480  way to get the highest order bit, (it is portable).
25481  Of course it will be recognized even if it is embedded in other expressions,
25482  e.g.:
25483 \layout Verse
25484
25485
25486 \family typewriter
25487 xyz = gint + ((gint >> 15) & 1);
25488 \layout Standard
25489
25490 will still be recognized.
25491 \layout Subsection
25492
25493 Higher Order Byte
25494 \begin_inset LatexCommand \index{Higher Order Byte}
25495
25496 \end_inset
25497
25498  / Higher Order Word
25499 \begin_inset LatexCommand \index{Higher Order Word}
25500
25501 \end_inset
25502
25503
25504 \layout Standard
25505
25506 It is also frequently required to obtain a higher order byte or word of
25507  a larger integral type (long, int or short types).
25508  SDCC recognizes the following expressions to yield the higher order byte
25509  or word and generates optimized code for it, e.g.:
25510 \layout Verse
25511
25512
25513 \family typewriter
25514 unsigned int gint;
25515 \newline
25516 unsigned long int glong;
25517 \newline
25518
25519 \newline
25520 foo () {
25521 \newline
25522 \SpecialChar ~
25523 \SpecialChar ~
25524 unsigned char hob1, hob2;
25525 \newline
25526 \SpecialChar ~
25527 \SpecialChar ~
25528 unsigned int how1, how2;
25529 \newline
25530 \SpecialChar ~
25531 \SpecialChar ~
25532 ...
25533
25534 \newline
25535 \SpecialChar ~
25536 \SpecialChar ~
25537 hob1 = (gint >> 8) & 0xFF;
25538 \newline
25539 \SpecialChar ~
25540 \SpecialChar ~
25541 hob2 = glong >> 24;
25542 \newline
25543 \SpecialChar ~
25544 \SpecialChar ~
25545 how1 = (glong >> 16) & 0xFFFF;
25546 \newline
25547 \SpecialChar ~
25548 \SpecialChar ~
25549 how2 = glong >> 8;
25550 \newline
25551 \SpecialChar ~
25552 \SpecialChar ~
25553 ..
25554
25555 \newline
25556 }
25557 \layout Standard
25558
25559 will generate the following code:
25560 \layout Verse
25561
25562
25563 \family typewriter
25564 \SpecialChar ~
25565 \SpecialChar ~
25566 \SpecialChar ~
25567 \SpecialChar ~
25568 \SpecialChar ~
25569 \SpecialChar ~
25570 \SpecialChar ~
25571 \SpecialChar ~
25572 \SpecialChar ~
25573 \SpecialChar ~
25574 \SpecialChar ~
25575 \SpecialChar ~
25576 \SpecialChar ~
25577 \SpecialChar ~
25578 \SpecialChar ~
25579 \SpecialChar ~
25580 \SpecialChar ~
25581 \SpecialChar ~
25582 \SpecialChar ~
25583 \SpecialChar ~
25584 \SpecialChar ~
25585 \SpecialChar ~
25586 \SpecialChar ~
25587 \SpecialChar ~
25588 \SpecialChar ~
25589  91 ;\SpecialChar ~
25590  hob.c 15
25591 \newline
25592 0037 85*01*06\SpecialChar ~
25593 \SpecialChar ~
25594 \SpecialChar ~
25595 \SpecialChar ~
25596 \SpecialChar ~
25597 \SpecialChar ~
25598 \SpecialChar ~
25599 \SpecialChar ~
25600 \SpecialChar ~
25601 \SpecialChar ~
25602 \SpecialChar ~
25603 \SpecialChar ~
25604  92\SpecialChar ~
25605 \SpecialChar ~
25606 \SpecialChar ~
25607 \SpecialChar ~
25608 \SpecialChar ~
25609 \SpecialChar ~
25610 \SpecialChar ~
25611 \SpecialChar ~
25612  mov\SpecialChar ~
25613 \SpecialChar ~
25614  _foo_hob1_1_1,(_gint + 1)
25615 \newline
25616 \SpecialChar ~
25617 \SpecialChar ~
25618 \SpecialChar ~
25619 \SpecialChar ~
25620 \SpecialChar ~
25621 \SpecialChar ~
25622 \SpecialChar ~
25623 \SpecialChar ~
25624 \SpecialChar ~
25625 \SpecialChar ~
25626 \SpecialChar ~
25627 \SpecialChar ~
25628 \SpecialChar ~
25629 \SpecialChar ~
25630 \SpecialChar ~
25631 \SpecialChar ~
25632 \SpecialChar ~
25633 \SpecialChar ~
25634 \SpecialChar ~
25635 \SpecialChar ~
25636 \SpecialChar ~
25637 \SpecialChar ~
25638 \SpecialChar ~
25639 \SpecialChar ~
25640 \SpecialChar ~
25641  93 ;\SpecialChar ~
25642  hob.c 16
25643 \newline
25644 003A 85*05*07\SpecialChar ~
25645 \SpecialChar ~
25646 \SpecialChar ~
25647 \SpecialChar ~
25648 \SpecialChar ~
25649 \SpecialChar ~
25650 \SpecialChar ~
25651 \SpecialChar ~
25652 \SpecialChar ~
25653 \SpecialChar ~
25654 \SpecialChar ~
25655 \SpecialChar ~
25656  94\SpecialChar ~
25657 \SpecialChar ~
25658 \SpecialChar ~
25659 \SpecialChar ~
25660 \SpecialChar ~
25661 \SpecialChar ~
25662 \SpecialChar ~
25663 \SpecialChar ~
25664  mov\SpecialChar ~
25665 \SpecialChar ~
25666  _foo_hob2_1_1,(_glong + 3)
25667 \newline
25668 \SpecialChar ~
25669 \SpecialChar ~
25670 \SpecialChar ~
25671 \SpecialChar ~
25672 \SpecialChar ~
25673 \SpecialChar ~
25674 \SpecialChar ~
25675 \SpecialChar ~
25676 \SpecialChar ~
25677 \SpecialChar ~
25678 \SpecialChar ~
25679 \SpecialChar ~
25680 \SpecialChar ~
25681 \SpecialChar ~
25682 \SpecialChar ~
25683 \SpecialChar ~
25684 \SpecialChar ~
25685 \SpecialChar ~
25686 \SpecialChar ~
25687 \SpecialChar ~
25688 \SpecialChar ~
25689 \SpecialChar ~
25690 \SpecialChar ~
25691 \SpecialChar ~
25692 \SpecialChar ~
25693  95 ;\SpecialChar ~
25694  hob.c 17
25695 \newline
25696 003D 85*04*08\SpecialChar ~
25697 \SpecialChar ~
25698 \SpecialChar ~
25699 \SpecialChar ~
25700 \SpecialChar ~
25701 \SpecialChar ~
25702 \SpecialChar ~
25703 \SpecialChar ~
25704 \SpecialChar ~
25705 \SpecialChar ~
25706 \SpecialChar ~
25707 \SpecialChar ~
25708  96\SpecialChar ~
25709 \SpecialChar ~
25710 \SpecialChar ~
25711 \SpecialChar ~
25712 \SpecialChar ~
25713 \SpecialChar ~
25714 \SpecialChar ~
25715 \SpecialChar ~
25716  mov\SpecialChar ~
25717 \SpecialChar ~
25718  _foo_how1_1_1,(_glong + 2)
25719 \newline
25720 0040 85*05*09\SpecialChar ~
25721 \SpecialChar ~
25722 \SpecialChar ~
25723 \SpecialChar ~
25724 \SpecialChar ~
25725 \SpecialChar ~
25726 \SpecialChar ~
25727 \SpecialChar ~
25728 \SpecialChar ~
25729 \SpecialChar ~
25730 \SpecialChar ~
25731 \SpecialChar ~
25732  97\SpecialChar ~
25733 \SpecialChar ~
25734 \SpecialChar ~
25735 \SpecialChar ~
25736 \SpecialChar ~
25737 \SpecialChar ~
25738 \SpecialChar ~
25739 \SpecialChar ~
25740  mov\SpecialChar ~
25741 \SpecialChar ~
25742  (_foo_how1_1_1 + 1),(_glong + 3)
25743 \newline
25744 0043 85*03*0A\SpecialChar ~
25745 \SpecialChar ~
25746 \SpecialChar ~
25747 \SpecialChar ~
25748 \SpecialChar ~
25749 \SpecialChar ~
25750 \SpecialChar ~
25751 \SpecialChar ~
25752 \SpecialChar ~
25753 \SpecialChar ~
25754 \SpecialChar ~
25755 \SpecialChar ~
25756  98\SpecialChar ~
25757 \SpecialChar ~
25758 \SpecialChar ~
25759 \SpecialChar ~
25760 \SpecialChar ~
25761 \SpecialChar ~
25762 \SpecialChar ~
25763 \SpecialChar ~
25764  mov\SpecialChar ~
25765 \SpecialChar ~
25766  _foo_how2_1_1,(_glong + 1)
25767 \newline
25768 0046 85*04*0B\SpecialChar ~
25769 \SpecialChar ~
25770 \SpecialChar ~
25771 \SpecialChar ~
25772 \SpecialChar ~
25773 \SpecialChar ~
25774 \SpecialChar ~
25775 \SpecialChar ~
25776 \SpecialChar ~
25777 \SpecialChar ~
25778 \SpecialChar ~
25779 \SpecialChar ~
25780  99\SpecialChar ~
25781 \SpecialChar ~
25782 \SpecialChar ~
25783 \SpecialChar ~
25784 \SpecialChar ~
25785 \SpecialChar ~
25786 \SpecialChar ~
25787 \SpecialChar ~
25788  mov\SpecialChar ~
25789 \SpecialChar ~
25790  (_foo_how2_1_1 + 1),(_glong + 2)
25791 \layout Standard
25792
25793 Again, variations of these cases may
25794 \emph on
25795 not
25796 \emph default
25797  be recognized.
25798  They are standard C expressions, so I heartily recommend these be the only
25799  way to get the higher order byte/word, (it is portable).
25800  Of course it will be recognized even if it is embedded in other expressions,
25801  e.g.:
25802 \layout Verse
25803
25804
25805 \family typewriter
25806 xyz = gint + ((gint >> 8) & 0xFF);
25807 \layout Standard
25808
25809 will still be recognized.
25810 \layout Subsection
25811
25812 Peephole Optimizer
25813 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
25814
25815 \end_inset
25816
25817
25818 \begin_inset LatexCommand \index{Peephole optimizer}
25819
25820 \end_inset
25821
25822
25823 \layout Standard
25824
25825 The compiler uses a rule based, pattern matching and re-writing mechanism
25826  for peep-hole optimization.
25827  It is inspired by
25828 \emph on
25829 copt
25830 \emph default
25831  a peep-hole optimizer by Christopher W.
25832  Fraser (cwfraser\SpecialChar ~
25833 @\SpecialChar ~
25834 microsoft.com).
25835  A default set of rules are compiled into the compiler, additional rules
25836  may be added with the
25837 \emph on
25838 -
25839 \begin_inset ERT
25840 status Collapsed
25841
25842 \layout Standard
25843
25844 \backslash
25845 /
25846 \end_inset
25847
25848 -peep-file
25849 \begin_inset LatexCommand \index{-\/-peep-file}
25850
25851 \end_inset
25852
25853  <filename>
25854 \emph default
25855  option.
25856  The rule language is best illustrated with examples.
25857 \layout Verse
25858
25859
25860 \family typewriter
25861 replace {
25862 \newline
25863 \SpecialChar ~
25864 \SpecialChar ~
25865 mov %1,a
25866 \newline
25867 \SpecialChar ~
25868 \SpecialChar ~
25869 mov a,%1
25870 \newline
25871 } by {
25872 \newline
25873 \SpecialChar ~
25874 \SpecialChar ~
25875 mov %1,a
25876 \newline
25877 }
25878 \layout Standard
25879
25880 The above rule will change the following assembly
25881 \begin_inset LatexCommand \index{Assembler routines}
25882
25883 \end_inset
25884
25885  sequence:
25886 \layout Verse
25887
25888
25889 \family typewriter
25890 mov r1,a
25891 \newline
25892 mov a,r1
25893 \layout Standard
25894
25895 to
25896 \layout Verse
25897
25898
25899 \family typewriter
25900 mov r1,a
25901 \layout Standard
25902
25903 Note: All occurrences of a
25904 \emph on
25905 %n
25906 \emph default
25907  (pattern variable) must denote the same string.
25908  With the above rule, the assembly sequence:
25909 \layout Verse
25910
25911
25912 \family typewriter
25913 mov r1,a
25914 \newline
25915 mov a,r2
25916 \layout Standard
25917
25918 will remain unmodified.
25919 \newline
25920
25921 \newline
25922 Other special case optimizations may be added by the user (via
25923 \emph on
25924 -
25925 \begin_inset ERT
25926 status Collapsed
25927
25928 \layout Standard
25929
25930 \backslash
25931 /
25932 \end_inset
25933
25934 -peep-file option
25935 \emph default
25936 ).
25937  E.g.
25938  some variants of the 8051 MCU
25939 \begin_inset LatexCommand \index{MCS51 variants}
25940
25941 \end_inset
25942
25943  allow only
25944 \family typewriter
25945 ajmp
25946 \family default
25947  and
25948 \family typewriter
25949 acall
25950 \family default
25951 .
25952  The following two rules will change all
25953 \family typewriter
25954 ljmp
25955 \family default
25956  and
25957 \family typewriter
25958 lcall
25959 \family default
25960  to
25961 \family typewriter
25962 ajmp
25963 \family default
25964  and
25965 \family typewriter
25966 acall
25967 \layout Verse
25968
25969
25970 \family typewriter
25971 replace { lcall %1 } by { acall %1 }
25972 \newline
25973 replace { ljmp %1 } by { ajmp %1 }
25974 \layout Standard
25975
25976 The
25977 \emph on
25978 inline-assembler code
25979 \emph default
25980  is also passed through the peep hole optimizer, thus the peephole optimizer
25981  can also be used as an assembly level macro expander.
25982  The rules themselves are MCU dependent whereas the rule language infra-structur
25983 e is MCU independent.
25984  Peephole optimization rules for other MCU can be easily programmed using
25985  the rule language.
25986 \newline
25987
25988 \newline
25989 The syntax for a rule is as follows:
25990 \layout Verse
25991
25992
25993 \family typewriter
25994 rule := replace [ restart ] '{' <assembly sequence> '
25995 \backslash
25996 n'
25997 \newline
25998 \SpecialChar ~
25999  \SpecialChar ~
26000  \SpecialChar ~
26001  \SpecialChar ~
26002  \SpecialChar ~
26003  \SpecialChar ~
26004  \SpecialChar ~
26005  \SpecialChar ~
26006  \SpecialChar ~
26007  \SpecialChar ~
26008  \SpecialChar ~
26009  \SpecialChar ~
26010  \SpecialChar ~
26011  \SpecialChar ~
26012  '}' by '{' '
26013 \backslash
26014 n'
26015 \newline
26016 \SpecialChar ~
26017  \SpecialChar ~
26018  \SpecialChar ~
26019  \SpecialChar ~
26020  \SpecialChar ~
26021  \SpecialChar ~
26022  \SpecialChar ~
26023  \SpecialChar ~
26024  \SpecialChar ~
26025  \SpecialChar ~
26026  \SpecialChar ~
26027  \SpecialChar ~
26028  \SpecialChar ~
26029  \SpecialChar ~
26030  \SpecialChar ~
26031  \SpecialChar ~
26032  <assembly sequence> '
26033 \backslash
26034 n'
26035 \newline
26036 \SpecialChar ~
26037  \SpecialChar ~
26038  \SpecialChar ~
26039  \SpecialChar ~
26040  \SpecialChar ~
26041  \SpecialChar ~
26042  \SpecialChar ~
26043  \SpecialChar ~
26044  \SpecialChar ~
26045  \SpecialChar ~
26046  \SpecialChar ~
26047  \SpecialChar ~
26048  \SpecialChar ~
26049  \SpecialChar ~
26050  '}' [if <functionName> ] '
26051 \backslash
26052 n'
26053 \layout Standard
26054
26055 <assembly sequence> := assembly instruction (each instruction including
26056  labels must be on a separate line).
26057 \newline
26058
26059 \newline
26060 The optimizer will apply to the rules one by one from the top in the sequence
26061  of their appearance, it will terminate when all rules are exhausted.
26062  If the 'restart' option is specified, then the optimizer will start matching
26063  the rules again from the top, this option for a rule is expensive (performance)
26064 , it is intended to be used in situations where a transformation will trigger
26065  the same rule again.
26066  An example of this (not a good one, it has side effects) is the following
26067  rule:
26068 \layout Verse
26069
26070
26071 \family typewriter
26072 replace restart {
26073 \newline
26074 \SpecialChar ~
26075 \SpecialChar ~
26076 pop %1
26077 \newline
26078 \SpecialChar ~
26079 \SpecialChar ~
26080 push %1 } by {
26081 \newline
26082 \SpecialChar ~
26083 \SpecialChar ~
26084 ; nop
26085 \newline
26086 }
26087 \layout Standard
26088
26089 Note that the replace pattern cannot be a blank, but can be a comment line.
26090  Without the 'restart' option only the innermost 'pop' 'push' pair would
26091  be eliminated, i.e.:
26092 \layout Verse
26093
26094
26095 \family typewriter
26096 pop ar1
26097 \newline
26098 pop ar2
26099 \newline
26100 push ar2
26101 \newline
26102 push ar1
26103 \layout Standard
26104
26105 would result in:
26106 \layout Verse
26107
26108
26109 \family typewriter
26110 pop ar1
26111 \newline
26112 ; nop
26113 \newline
26114 push ar1
26115 \layout Standard
26116
26117
26118 \emph on
26119 with
26120 \emph default
26121  the restart option the rule will be applied again to the resulting code
26122  and then all the pop-push pairs will be eliminated to yield:
26123 \layout Verse
26124
26125
26126 \family typewriter
26127 ; nop
26128 \newline
26129 ; nop
26130 \layout Standard
26131
26132 A conditional function can be attached to a rule.
26133  Attaching rules are somewhat more involved, let me illustrate this with
26134  an example.
26135 \layout Verse
26136
26137
26138 \family typewriter
26139 replace {
26140 \newline
26141 \SpecialChar ~
26142  \SpecialChar ~
26143  \SpecialChar ~
26144 ljmp %5
26145 \newline
26146 %2:
26147 \newline
26148 } by {
26149 \newline
26150 \SpecialChar ~
26151  \SpecialChar ~
26152  \SpecialChar ~
26153 sjmp %5
26154 \newline
26155 %2:
26156 \newline
26157 } if labelInRange
26158 \layout Standard
26159
26160 The optimizer does a look-up of a function name table defined in function
26161
26162 \emph on
26163 callFuncByName
26164 \emph default
26165  in the source file SDCCpeeph.c, with the name
26166 \emph on
26167 labelInRange
26168 \emph default
26169 .
26170  If it finds a corresponding entry the function is called.
26171  Note there can be no parameters specified for these functions, in this
26172  case the use of
26173 \emph on
26174 %5
26175 \emph default
26176  is crucial, since the function
26177 \emph on
26178 labelInRange
26179 \emph default
26180  expects to find the label in that particular variable (the hash table containin
26181 g the variable bindings is passed as a parameter).
26182  If you want to code more such functions, take a close look at the function
26183  labelInRange and the calling mechanism in source file SDCCpeeph.c.
26184  Currently implemented are
26185 \emph on
26186 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
26187  24bitMode, portIsDS390, 24bitModeAndPortDS390
26188 \emph default
26189 and
26190 \emph on
26191  notVolatile
26192 \emph default
26193 .
26194 \layout Standard
26195
26196 I know this whole thing is a little kludgey, but maybe some day we will
26197  have some better means.
26198  If you are looking at this file, you will see the default rules that are
26199  compiled into the compiler, you can add your own rules in the default set
26200  there if you get tired of specifying the -
26201 \begin_inset ERT
26202 status Collapsed
26203
26204 \layout Standard
26205
26206 \backslash
26207 /
26208 \end_inset
26209
26210 -peep-file option.
26211 \layout Section
26212
26213 ANSI-Compliance
26214 \begin_inset LatexCommand \index{ANSI-compliance}
26215
26216 \end_inset
26217
26218
26219 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
26220
26221 \end_inset
26222
26223
26224 \layout Standard
26225
26226 Deviations from the compliance:
26227 \layout Itemize
26228
26229 functions are not reentrant
26230 \begin_inset LatexCommand \index{reentrant}
26231
26232 \end_inset
26233
26234  unless explicitly declared as such or the
26235 \series bold
26236 -
26237 \begin_inset ERT
26238 status Collapsed
26239
26240 \layout Standard
26241
26242 \backslash
26243 /
26244 \end_inset
26245
26246 -stack-auto
26247 \begin_inset LatexCommand \index{-\/-stack-auto}
26248
26249 \end_inset
26250
26251
26252 \series default
26253  command line option is specified.
26254 \layout Itemize
26255
26256 structures and unions cannot be assigned values directly, cannot be passed
26257  as function parameters or assigned to each other and cannot be a return
26258  value from a function, e.g.:
26259 \begin_deeper
26260 \layout Verse
26261
26262
26263 \family typewriter
26264 struct s { ...
26265  };
26266 \newline
26267 struct s s1, s2;
26268 \newline
26269 foo()
26270 \newline
26271 {
26272 \newline
26273 \SpecialChar ~
26274 \SpecialChar ~
26275 \SpecialChar ~
26276 \SpecialChar ~
26277 ...
26278
26279 \newline
26280 \SpecialChar ~
26281 \SpecialChar ~
26282 \SpecialChar ~
26283 \SpecialChar ~
26284 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
26285 \newline
26286 \SpecialChar ~
26287 \SpecialChar ~
26288 \SpecialChar ~
26289 \SpecialChar ~
26290 ...
26291
26292 \newline
26293 }
26294 \newline
26295 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
26296  */
26297 \newline
26298 {
26299 \newline
26300 \SpecialChar ~
26301 \SpecialChar ~
26302 \SpecialChar ~
26303 \SpecialChar ~
26304 struct s rets;
26305 \newline
26306 \SpecialChar ~
26307 \SpecialChar ~
26308 \SpecialChar ~
26309 \SpecialChar ~
26310 ...
26311
26312 \newline
26313 \SpecialChar ~
26314 \SpecialChar ~
26315 \SpecialChar ~
26316 \SpecialChar ~
26317 return rets;/* is invalid in SDCC although allowed in ANSI */
26318 \newline
26319 }
26320 \end_deeper
26321 \layout Itemize
26322
26323 initialization of structure arrays must be fully braced.
26324 \begin_deeper
26325 \layout Verse
26326
26327
26328 \family typewriter
26329 struct s { char x } a[] = {1, 2}; /* invalid in SDCC */
26330 \newline
26331 struct s { char x } a[] = {{1}, {2}}; /* OK */
26332 \end_deeper
26333 \layout Itemize
26334
26335 'long long
26336 \begin_inset LatexCommand \index{long long (not supported)}
26337
26338 \end_inset
26339
26340 ' (64 bit integers
26341 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
26342
26343 \end_inset
26344
26345 ) not supported.
26346 \layout Itemize
26347
26348 'double
26349 \begin_inset LatexCommand \index{double (not supported)}
26350
26351 \end_inset
26352
26353 ' precision floating point
26354 \begin_inset LatexCommand \index{Floating point support}
26355
26356 \end_inset
26357
26358 not supported.
26359 \layout Itemize
26360
26361 No support for setjmp
26362 \begin_inset LatexCommand \index{setjmp (not supported)}
26363
26364 \end_inset
26365
26366  and longjmp
26367 \begin_inset LatexCommand \index{longjmp (not supported)}
26368
26369 \end_inset
26370
26371  (for now).
26372 \layout Itemize
26373
26374 Old K&R style
26375 \begin_inset LatexCommand \index{K\&R style}
26376
26377 \end_inset
26378
26379  function declarations are NOT allowed.
26380 \begin_deeper
26381 \layout Verse
26382
26383
26384 \family typewriter
26385 foo(i,j) /* this old style of function declarations */
26386 \newline
26387 int i,j; /* are valid in ANSI but not valid in SDCC */
26388 \newline
26389 {
26390 \newline
26391 \SpecialChar ~
26392 \SpecialChar ~
26393 \SpecialChar ~
26394 \SpecialChar ~
26395 ...
26396
26397 \newline
26398 }
26399 \end_deeper
26400 \layout Itemize
26401
26402 Certain words that are valid identifiers in the standard may be reserved
26403  words in SDCC unless the
26404 \series bold
26405 -
26406 \begin_inset ERT
26407 status Collapsed
26408
26409 \layout Standard
26410
26411 \backslash
26412 /
26413 \end_inset
26414
26415 -std-c89
26416 \begin_inset LatexCommand \index{-\/-std-c89}
26417
26418 \end_inset
26419
26420  or -
26421 \begin_inset ERT
26422 status Collapsed
26423
26424 \layout Standard
26425
26426 \backslash
26427 /
26428 \end_inset
26429
26430 -std-c99
26431 \begin_inset LatexCommand \index{-\/-std-c99}
26432
26433 \end_inset
26434
26435
26436 \series default
26437  command line options are used.
26438  These may include (depending on the selected processor): 'at', 'banked',
26439  'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup
26440 t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs',
26441  'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and
26442  '_naked'.
26443  Compliant equivalents of these keywords are always available in a form
26444  that begin with two underscores
26445 \begin_inset LatexCommand \index{\_\_ (prefix for extended keywords)}
26446
26447 \end_inset
26448
26449 , f.e.
26450  '__data' instead of 'data'.
26451 \layout Section
26452
26453 Cyclomatic Complexity
26454 \begin_inset LatexCommand \index{Cyclomatic complexity}
26455
26456 \end_inset
26457
26458
26459 \layout Standard
26460
26461 Cyclomatic complexity of a function is defined as the number of independent
26462  paths the program can take during execution of the function.
26463  This is an important number since it defines the number test cases you
26464  have to generate to validate the function.
26465  The accepted industry standard for complexity number is 10, if the cyclomatic
26466  complexity reported by SDCC exceeds 10 you should think about simplification
26467  of the function logic.
26468  Note that the complexity level is not related to the number of lines of
26469  code in a function.
26470  Large functions can have low complexity, and small functions can have large
26471  complexity levels.
26472
26473 \newline
26474
26475 \newline
26476 SDCC uses the following formula to compute the complexity:
26477 \newline
26478
26479 \layout Standard
26480
26481 complexity = (number of edges in control flow graph) - (number of nodes
26482  in control flow graph) + 2;
26483 \newline
26484
26485 \newline
26486 Having said that the industry standard is 10, you should be aware that in
26487  some cases it be may unavoidable to have a complexity level of less than
26488  10.
26489  For example if you have switch statement with more than 10 case labels,
26490  each case label adds one to the complexity level.
26491  The complexity level is by no means an absolute measure of the algorithmic
26492  complexity of the function, it does however provide a good starting point
26493  for which functions you might look at for further optimization.
26494 \layout Section
26495
26496 Retargetting for other Processors
26497 \layout Standard
26498
26499 The issues for retargetting the compiler are far too numerous to be covered
26500  by this document.
26501  What follows is a brief description of each of the seven phases of the
26502  compiler and its MCU dependency.
26503 \layout Itemize
26504
26505 Parsing the source and building the annotated parse tree.
26506  This phase is largely MCU independent (except for the language extensions).
26507  Syntax & semantic checks are also done in this phase, along with some initial
26508  optimizations like back patching labels and the pattern matching optimizations
26509  like bit-rotation etc.
26510 \layout Itemize
26511
26512 The second phase involves generating an intermediate code which can be easy
26513  manipulated during the later phases.
26514  This phase is entirely MCU independent.
26515  The intermediate code generation assumes the target machine has unlimited
26516  number of registers, and designates them with the name iTemp.
26517  The compiler can be made to dump a human readable form of the code generated
26518  by using the -
26519 \begin_inset ERT
26520 status Collapsed
26521
26522 \layout Standard
26523
26524 \backslash
26525 /
26526 \end_inset
26527
26528 -dumpraw option.
26529 \layout Itemize
26530
26531 This phase does the bulk of the standard optimizations and is also MCU independe
26532 nt.
26533  This phase can be broken down into several sub-phases:
26534 \newline
26535
26536 \newline
26537 Break down intermediate code (iCode) into basic blocks.
26538 \newline
26539 Do control flow & data flow analysis on the basic blocks.
26540 \newline
26541 Do local common subexpression elimination, then global subexpression elimination
26542 \newline
26543 Dead code elimination
26544 \newline
26545 Loop optimizations
26546 \newline
26547 If loop optimizations caused any changes then do 'global subexpression eliminati
26548 on' and 'dead code elimination' again.
26549 \layout Itemize
26550
26551 This phase determines the live-ranges; by live range I mean those iTemp
26552  variables defined by the compiler that still survive after all the optimization
26553 s.
26554  Live range analysis
26555 \begin_inset LatexCommand \index{Live range analysis}
26556
26557 \end_inset
26558
26559  is essential for register allocation, since these computation determines
26560  which of these iTemps will be assigned to registers, and for how long.
26561 \layout Itemize
26562
26563 Phase five is register allocation.
26564  There are two parts to this process.
26565 \newline
26566
26567 \newline
26568 The first part I call 'register packing' (for lack of a better term).
26569  In this case several MCU specific expression folding is done to reduce
26570  register pressure.
26571 \newline
26572
26573 \newline
26574 The second part is more MCU independent and deals with allocating registers
26575  to the remaining live ranges.
26576  A lot of MCU specific code does creep into this phase because of the limited
26577  number of index registers available in the 8051.
26578 \layout Itemize
26579
26580 The Code generation phase is (unhappily), entirely MCU dependent and very
26581  little (if any at all) of this code can be reused for other MCU.
26582  However the scheme for allocating a homogenized assembler operand for each
26583  iCode operand may be reused.
26584 \layout Itemize
26585
26586 As mentioned in the optimization section the peep-hole optimizer is rule
26587  based system, which can reprogrammed for other MCUs.
26588 \layout Chapter
26589
26590 Compiler internals
26591 \begin_inset LatexCommand \index{Compiler internals}
26592
26593 \end_inset
26594
26595
26596 \layout Section
26597
26598 The anatomy of the compiler
26599 \begin_inset LatexCommand \label{sub:The-anatomy-of}
26600
26601 \end_inset
26602
26603
26604 \layout Standard
26605
26606
26607 \shape italic
26608 This is an excerpt from an article published in Circuit Cellar Magazine
26609  in
26610 \series bold
26611 August 2000
26612 \series default
26613 .
26614  It's a little outdated (the compiler is much more efficient now and user/develo
26615 per friendly), but pretty well exposes the guts of it all.
26616 \shape default
26617
26618 \newline
26619
26620 \newline
26621 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
26622  It is fairly easy to retarget for other 8-bit MCU.
26623  Here we take a look at some of the internals of the compiler.
26624
26625 \layout Paragraph*
26626
26627 Parsing
26628 \begin_inset LatexCommand \index{Parsing}
26629
26630 \end_inset
26631
26632
26633 \layout Standard
26634
26635 Parsing the input source file and creating an AST (Annotated Syntax Tree
26636 \begin_inset LatexCommand \index{Annotated syntax tree}
26637
26638 \end_inset
26639
26640 ).
26641  This phase also involves propagating types (annotating each node of the
26642  parse tree with type information) and semantic analysis.
26643  There are some MCU specific parsing rules.
26644  For example the storage classes, the extended storage classes are MCU specific
26645  while there may be a xdata storage class for 8051 there is no such storage
26646  class for z80 or Atmel AVR.
26647  SDCC allows MCU specific storage class extensions, i.e.
26648  xdata will be treated as a storage class specifier when parsing 8051 C
26649  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
26650  C code.
26651 \layout Paragraph*
26652
26653 Generating iCode
26654 \begin_inset LatexCommand \index{iCode}
26655
26656 \end_inset
26657
26658
26659 \layout Standard
26660
26661 Intermediate code generation.
26662  In this phase the AST is broken down into three-operand form (iCode).
26663  These three operand forms are represented as doubly linked lists.
26664  ICode is the term given to the intermediate form generated by the compiler.
26665  ICode example section shows some examples of iCode generated for some simple
26666  C source functions.
26667 \layout Paragraph*
26668
26669 Optimizations
26670 \begin_inset LatexCommand \index{Optimizations}
26671
26672 \end_inset
26673
26674 .
26675 \layout Standard
26676
26677 Bulk of the target independent optimizations is performed in this phase.
26678  The optimizations include constant propagation, common sub-expression eliminati
26679 on, loop invariant code movement, strength reduction of loop induction variables
26680  and dead-code elimination.
26681 \layout Paragraph*
26682
26683 Live range analysis
26684 \begin_inset LatexCommand \index{Live range analysis}
26685
26686 \end_inset
26687
26688
26689 \layout Standard
26690
26691 During intermediate code generation phase, the compiler assumes the target
26692  machine has infinite number of registers and generates a lot of temporary
26693  variables.
26694  The live range computation determines the lifetime of each of these compiler-ge
26695 nerated temporaries.
26696  A picture speaks a thousand words.
26697  ICode example sections show the live range annotations for each of the
26698  operand.
26699  It is important to note here, each iCode is assigned a number in the order
26700  of its execution in the function.
26701  The live ranges are computed in terms of these numbers.
26702  The from number is the number of the iCode which first defines the operand
26703  and the to number signifies the iCode which uses this operand last.
26704 \layout Paragraph*
26705
26706 Register Allocation
26707 \begin_inset LatexCommand \index{Register allocation}
26708
26709 \end_inset
26710
26711
26712 \layout Standard
26713
26714 The register allocation determines the type and number of registers needed
26715  by each operand.
26716  In most MCUs only a few registers can be used for indirect addressing.
26717  In case of 8051 for example the registers R0 & R1 can be used to indirectly
26718  address the internal ram and DPTR to indirectly address the external ram.
26719  The compiler will try to allocate the appropriate register to pointer variables
26720  if it can.
26721  ICode example section shows the operands annotated with the registers assigned
26722  to them.
26723  The compiler will try to keep operands in registers as much as possible;
26724  there are several schemes the compiler uses to do achieve this.
26725  When the compiler runs out of registers the compiler will check to see
26726  if there are any live operands which is not used or defined in the current
26727  basic block being processed, if there are any found then it will push that
26728  operand and use the registers in this block, the operand will then be popped
26729  at the end of the basic block.
26730
26731 \layout Standard
26732
26733 There are other MCU specific considerations in this phase.
26734  Some MCUs have an accumulator; very short-lived operands could be assigned
26735  to the accumulator instead of a general-purpose register.
26736 \layout Paragraph*
26737
26738 Code generation
26739 \layout Standard
26740
26741 Figure II gives a table of iCode operations supported by the compiler.
26742  The code generation involves translating these operations into corresponding
26743  assembly code for the processor.
26744  This sounds overly simple but that is the essence of code generation.
26745  Some of the iCode operations are generated on a MCU specific manner for
26746  example, the z80 port does not use registers to pass parameters so the
26747  SEND and RECV iCode operations will not be generated, and it also does
26748  not support JUMPTABLES.
26749
26750 \newline
26751
26752 \series bold
26753 \shape italic
26754 \color red
26755 <Where is Figure II?>
26756 \layout Comment
26757
26758 In the original article Figure II was announced to be downloadable on
26759 \shape italic
26760 Circuit Cellar
26761 \shape default
26762 's web site.
26763  Unfortunately it never seemed to have shown up there, so: where is Figure
26764  II?
26765 \layout Paragraph*
26766
26767 ICode Example
26768 \begin_inset LatexCommand \index{iCode}
26769
26770 \end_inset
26771
26772
26773 \layout Standard
26774
26775 This section shows some details of iCode.
26776  The example C code does not do anything useful; it is used as an example
26777  to illustrate the intermediate code generated by the compiler.
26778 \layout Verse
26779
26780
26781 \family typewriter
26782 1.\SpecialChar ~
26783 xdata int * p;
26784 \newline
26785 2.\SpecialChar ~
26786 int gint;
26787 \newline
26788 3.\SpecialChar ~
26789 /* This function does nothing useful.
26790  It is used
26791 \newline
26792 4.\SpecialChar ~
26793 \SpecialChar ~
26794 \SpecialChar ~
26795 \SpecialChar ~
26796 for the purpose of explaining iCode */
26797 \newline
26798 5.\SpecialChar ~
26799 short function (data int *x)
26800 \newline
26801 6.\SpecialChar ~
26802 {
26803 \newline
26804 7.\SpecialChar ~
26805 \SpecialChar ~
26806 \SpecialChar ~
26807 short i=10; \SpecialChar ~
26808 \SpecialChar ~
26809 /* dead initialization eliminated */
26810 \newline
26811 8.\SpecialChar ~
26812 \SpecialChar ~
26813 \SpecialChar ~
26814 short sum=10; /* dead initialization eliminated */
26815 \newline
26816 9.\SpecialChar ~
26817 \SpecialChar ~
26818 \SpecialChar ~
26819 short mul;
26820 \newline
26821 10.\SpecialChar ~
26822 \SpecialChar ~
26823 int j ;
26824 \newline
26825 11.\SpecialChar ~
26826 \SpecialChar ~
26827 while (*x) *x++ = *p++;
26828 \newline
26829 12.\SpecialChar ~
26830 \SpecialChar ~
26831 \SpecialChar ~
26832 \SpecialChar ~
26833 sum = 0 ;
26834 \newline
26835 13.\SpecialChar ~
26836 \SpecialChar ~
26837 mul = 0;
26838 \newline
26839 14.\SpecialChar ~
26840 \SpecialChar ~
26841 /* compiler detects i,j to be induction variables */
26842 \newline
26843 15.\SpecialChar ~
26844 \SpecialChar ~
26845 for (i = 0, j = 10 ; i < 10 ; i++, j
26846 \family default
26847 -
26848 \begin_inset ERT
26849 status Collapsed
26850
26851 \layout Standard
26852
26853 \backslash
26854 /
26855 \end_inset
26856
26857 -
26858 \family typewriter
26859 ) {
26860 \newline
26861 16.\SpecialChar ~
26862 \SpecialChar ~
26863 \SpecialChar ~
26864 \SpecialChar ~
26865 sum += i;
26866 \newline
26867 17.\SpecialChar ~
26868 \SpecialChar ~
26869 \SpecialChar ~
26870 \SpecialChar ~
26871 mul += i * 3; \SpecialChar ~
26872 \SpecialChar ~
26873 /* this multiplication remains */
26874 \newline
26875 18.\SpecialChar ~
26876 \SpecialChar ~
26877 \SpecialChar ~
26878 \SpecialChar ~
26879 gint += j * 3;\SpecialChar ~
26880 \SpecialChar ~
26881 /* this multiplication changed to addition */
26882 \newline
26883 19.\SpecialChar ~
26884 \SpecialChar ~
26885 }
26886 \newline
26887 20.\SpecialChar ~
26888 \SpecialChar ~
26889 return sum+mul;
26890 \newline
26891 21.\SpecialChar ~
26892 }
26893 \layout Standard
26894
26895 In addition to the operands each iCode contains information about the filename
26896  and line it corresponds to in the source file.
26897  The first field in the listing should be interpreted as follows:
26898 \newline
26899
26900 \shape italic
26901 \size footnotesize
26902 Filename(linenumber: iCode Execution sequence number : ICode hash table
26903  key : loop depth of the iCode).
26904 \shape default
26905 \size default
26906
26907 \newline
26908 Then follows the human readable form of the ICode operation.
26909  Each operand of this triplet form can be of three basic types a) compiler
26910  generated temporary b) user defined variable c) a constant value.
26911  Note that local variables and parameters are replaced by compiler generated
26912  temporaries.
26913  Live ranges
26914 \begin_inset LatexCommand \index{Live range analysis}
26915
26916 \end_inset
26917
26918  are computed only for temporaries (i.e.
26919  live ranges are not computed for global variables).
26920  Registers
26921 \begin_inset LatexCommand \index{Register allocation}
26922
26923 \end_inset
26924
26925  are allocated for temporaries only.
26926  Operands are formatted in the following manner:
26927 \newline
26928
26929 \shape italic
26930 \size footnotesize
26931 Operand Name [lr live-from : live-to ] { type information } [ registers
26932  allocated ].
26933 \shape default
26934 \size default
26935
26936 \newline
26937 As mentioned earlier the live ranges are computed in terms of the execution
26938  sequence number of the iCodes, for example
26939 \newline
26940 the iTemp0 is live from (i.e.
26941  first defined in iCode with execution sequence number 3, and is last used
26942  in the iCode with sequence number 5).
26943  For induction variables such as iTemp21 the live range computation extends
26944  the lifetime from the start to the end of the loop.
26945 \newline
26946 The register allocator used the live range information to allocate registers,
26947  the same registers may be used for different temporaries if their live
26948  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
26949  iTemp17 since their live ranges do not overlap.
26950  In addition the allocator also takes into consideration the type and usage
26951  of a temporary, for example itemp6 is a pointer to near space and is used
26952  as to fetch data from (i.e.
26953  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
26954  Some short lived temporaries are allocated to special registers which have
26955  meaning to the code generator e.g.
26956  iTemp13 is allocated to a pseudo register CC which tells the back end that
26957  the temporary is used only for a conditional jump the code generation makes
26958  use of this information to optimize a compare and jump ICode.
26959 \newline
26960 There are several loop optimizations
26961 \begin_inset LatexCommand \index{Loop optimization}
26962
26963 \end_inset
26964
26965  performed by the compiler.
26966  It can detect induction variables iTemp21(i) and iTemp23(j).
26967  Also note the compiler does selective strength reduction
26968 \begin_inset LatexCommand \index{Strength reduction}
26969
26970 \end_inset
26971
26972 , i.e.
26973  the multiplication of an induction variable in line 18 (gint = j * 3) is
26974  changed to addition, a new temporary iTemp17 is allocated and assigned
26975  a initial value, a constant 3 is then added for each iteration of the loop.
26976  The compiler does not change the multiplication
26977 \begin_inset LatexCommand \index{Multiplication}
26978
26979 \end_inset
26980
26981  in line 17 however since the processor does support an 8 * 8 bit multiplication.
26982 \newline
26983 Note the dead code elimination
26984 \begin_inset LatexCommand \index{Dead-code elimination}
26985
26986 \end_inset
26987
26988  optimization eliminated the dead assignments in line 7 & 8 to I and sum
26989  respectively.
26990 \newline
26991
26992 \layout Standard
26993
26994
26995 \size footnotesize
26996 Sample.c (5:1:0:0) _entry($9) :
26997 \layout Standard
26998
26999
27000 \size footnotesize
27001 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
27002 \layout Standard
27003
27004
27005 \size footnotesize
27006 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
27007 \layout Standard
27008
27009
27010 \size footnotesize
27011 Sample.c(11:4:53:0) preHeaderLbl0($11) :
27012 \layout Standard
27013
27014
27015 \size footnotesize
27016 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
27017  * int}[r2]
27018 \layout Standard
27019
27020
27021 \size footnotesize
27022 Sample.c(11:6:5:1) _whilecontinue_0($1) :
27023 \layout Standard
27024
27025
27026 \size footnotesize
27027 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
27028  int}[r0]]
27029 \layout Standard
27030
27031
27032 \size footnotesize
27033 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
27034 \layout Standard
27035
27036
27037 \size footnotesize
27038 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
27039  * int}
27040 \layout Standard
27041
27042
27043 \size footnotesize
27044 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
27045  {short}
27046 \layout Standard
27047
27048
27049 \size footnotesize
27050 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
27051  * int}[DPTR]]
27052 \layout Standard
27053
27054
27055 \size footnotesize
27056 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
27057 }[r2 r3]
27058 \layout Standard
27059
27060
27061 \size footnotesize
27062 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
27063  * int}[r0] + 0x2 {short}
27064 \layout Standard
27065
27066
27067 \size footnotesize
27068 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
27069 \layout Standard
27070
27071
27072 \size footnotesize
27073 Sample.c(11:17:21:0)_whilebreak_0($3) :
27074 \layout Standard
27075
27076
27077 \size footnotesize
27078 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
27079 \layout Standard
27080
27081
27082 \size footnotesize
27083 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
27084 \layout Standard
27085
27086
27087 \size footnotesize
27088 Sample.c(15:20:54:0)preHeaderLbl1($13) :
27089 \layout Standard
27090
27091
27092 \size footnotesize
27093 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
27094 \layout Standard
27095
27096
27097 \size footnotesize
27098 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
27099 \layout Standard
27100
27101
27102 \size footnotesize
27103 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
27104 \layout Standard
27105
27106
27107 \size footnotesize
27108 Sample.c(15:24:26:1)_forcond_0($4) :
27109 \layout Standard
27110
27111
27112 \size footnotesize
27113 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
27114  < 0xa {short}
27115 \layout Standard
27116
27117
27118 \size footnotesize
27119 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
27120 \layout Standard
27121
27122
27123 \size footnotesize
27124 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
27125  + ITemp21 [lr21:38]{short}[r4]
27126 \layout Standard
27127
27128
27129 \size footnotesize
27130 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
27131  * 0x3 {short}
27132 \layout Standard
27133
27134
27135 \size footnotesize
27136 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
27137  + iTemp15 [lr29:30]{short}[r1]
27138 \layout Standard
27139
27140
27141 \size footnotesize
27142 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
27143  r0]- 0x3 {short}
27144 \layout Standard
27145
27146
27147 \size footnotesize
27148 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
27149 int}[r7 r0]
27150 \layout Standard
27151
27152
27153 \size footnotesize
27154 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
27155  + 0x1 {short}
27156 \layout Standard
27157
27158
27159 \size footnotesize
27160 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
27161  r6]- 0x1 {short}
27162 \layout Standard
27163
27164
27165 \size footnotesize
27166 Sample.c(19:38:47:1) goto _forcond_0($4)
27167 \layout Standard
27168
27169
27170 \size footnotesize
27171 Sample.c(19:39:48:0)_forbreak_0($7) :
27172 \layout Standard
27173
27174
27175 \size footnotesize
27176 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
27177  + ITemp11 [lr19:40]{short}[r3]
27178 \layout Standard
27179
27180
27181 \size footnotesize
27182 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
27183 \layout Standard
27184
27185
27186 \size footnotesize
27187 Sample.c(20:42:51:0)_return($8) :
27188 \layout Standard
27189
27190
27191 \size footnotesize
27192 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
27193 \size default
27194
27195 \newline
27196
27197 \newline
27198 Finally the code generated for this function:
27199 \newline
27200
27201 \layout Standard
27202
27203
27204 \size footnotesize
27205 .area DSEG (DATA)
27206 \layout Standard
27207
27208
27209 \size footnotesize
27210 _p::
27211 \layout Standard
27212
27213
27214 \size footnotesize
27215 \SpecialChar ~
27216 \SpecialChar ~
27217 .ds 2
27218 \layout Standard
27219
27220
27221 \size footnotesize
27222 _gint::
27223 \layout Standard
27224
27225
27226 \size footnotesize
27227 \SpecialChar ~
27228 \SpecialChar ~
27229 .ds 2
27230 \layout Standard
27231
27232
27233 \size footnotesize
27234 ; sample.c 5
27235 \layout Standard
27236
27237
27238 \size footnotesize
27239 ; ----------------------------------------------
27240 \layout Standard
27241
27242
27243 \size footnotesize
27244 ; function function
27245 \layout Standard
27246
27247
27248 \size footnotesize
27249 ; ----------------------------------------------
27250 \layout Standard
27251
27252
27253 \size footnotesize
27254 _function:
27255 \layout Standard
27256
27257
27258 \size footnotesize
27259 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
27260 \layout Standard
27261
27262
27263 \size footnotesize
27264 \SpecialChar ~
27265 \SpecialChar ~
27266 mov r2,dpl
27267 \layout Standard
27268
27269
27270 \size footnotesize
27271 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
27272 \layout Standard
27273
27274
27275 \size footnotesize
27276 \SpecialChar ~
27277 \SpecialChar ~
27278 mov ar0,r2
27279 \layout Standard
27280
27281
27282 \size footnotesize
27283 ;_whilecontinue_0($1) :
27284 \layout Standard
27285
27286
27287 \size footnotesize
27288 00101$:
27289 \layout Standard
27290
27291
27292 \size footnotesize
27293 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
27294 \layout Standard
27295
27296
27297 \size footnotesize
27298 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
27299 \layout Standard
27300
27301
27302 \size footnotesize
27303 \SpecialChar ~
27304 \SpecialChar ~
27305 mov ar2,@r0
27306 \layout Standard
27307
27308
27309 \size footnotesize
27310 \SpecialChar ~
27311 \SpecialChar ~
27312 inc r0
27313 \layout Standard
27314
27315
27316 \size footnotesize
27317 \SpecialChar ~
27318 \SpecialChar ~
27319 mov ar3,@r0
27320 \layout Standard
27321
27322
27323 \size footnotesize
27324 \SpecialChar ~
27325 \SpecialChar ~
27326 dec r0
27327 \layout Standard
27328
27329
27330 \size footnotesize
27331 \SpecialChar ~
27332 \SpecialChar ~
27333 mov a,r2
27334 \layout Standard
27335
27336
27337 \size footnotesize
27338 \SpecialChar ~
27339 \SpecialChar ~
27340 orl a,r3
27341 \layout Standard
27342
27343
27344 \size footnotesize
27345 \SpecialChar ~
27346 \SpecialChar ~
27347 jz 00103$
27348 \layout Standard
27349
27350
27351 \size footnotesize
27352 00114$:
27353 \layout Standard
27354
27355
27356 \size footnotesize
27357 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
27358 \layout Standard
27359
27360
27361 \size footnotesize
27362 \SpecialChar ~
27363 \SpecialChar ~
27364 mov dpl,_p
27365 \layout Standard
27366
27367
27368 \size footnotesize
27369 \SpecialChar ~
27370 \SpecialChar ~
27371 mov dph,(_p + 1)
27372 \layout Standard
27373
27374
27375 \size footnotesize
27376 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
27377 \layout Standard
27378
27379
27380 \size footnotesize
27381 \SpecialChar ~
27382 \SpecialChar ~
27383 mov a,#0x02
27384 \layout Standard
27385
27386
27387 \size footnotesize
27388 \SpecialChar ~
27389 \SpecialChar ~
27390 add a,_p
27391 \layout Standard
27392
27393
27394 \size footnotesize
27395 \SpecialChar ~
27396 \SpecialChar ~
27397 mov _p,a
27398 \layout Standard
27399
27400
27401 \size footnotesize
27402 \SpecialChar ~
27403 \SpecialChar ~
27404 clr a
27405 \layout Standard
27406
27407
27408 \size footnotesize
27409 \SpecialChar ~
27410 \SpecialChar ~
27411 addc a,(_p + 1)
27412 \layout Standard
27413
27414
27415 \size footnotesize
27416 \SpecialChar ~
27417 \SpecialChar ~
27418 mov (_p + 1),a
27419 \layout Standard
27420
27421
27422 \size footnotesize
27423 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
27424 \layout Standard
27425
27426
27427 \size footnotesize
27428 \SpecialChar ~
27429 \SpecialChar ~
27430 movx a,@dptr
27431 \layout Standard
27432
27433
27434 \size footnotesize
27435 \SpecialChar ~
27436 \SpecialChar ~
27437 mov r2,a
27438 \layout Standard
27439
27440
27441 \size footnotesize
27442 \SpecialChar ~
27443 \SpecialChar ~
27444 inc dptr
27445 \layout Standard
27446
27447
27448 \size footnotesize
27449 \SpecialChar ~
27450 \SpecialChar ~
27451 movx a,@dptr
27452 \layout Standard
27453
27454
27455 \size footnotesize
27456 \SpecialChar ~
27457 \SpecialChar ~
27458 mov r3,a
27459 \layout Standard
27460
27461
27462 \size footnotesize
27463 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
27464 \layout Standard
27465
27466
27467 \size footnotesize
27468 \SpecialChar ~
27469 \SpecialChar ~
27470 mov @r0,ar2
27471 \layout Standard
27472
27473
27474 \size footnotesize
27475 \SpecialChar ~
27476 \SpecialChar ~
27477 inc r0
27478 \layout Standard
27479
27480
27481 \size footnotesize
27482 \SpecialChar ~
27483 \SpecialChar ~
27484 mov @r0,ar3
27485 \layout Standard
27486
27487
27488 \size footnotesize
27489 ; iTemp6 [lr5:16]{_near * int}[r0] =
27490 \layout Standard
27491
27492
27493 \size footnotesize
27494 ; iTemp6 [lr5:16]{_near * int}[r0] +
27495 \layout Standard
27496
27497
27498 \size footnotesize
27499 ; 0x2 {short}
27500 \layout Standard
27501
27502
27503 \size footnotesize
27504 \SpecialChar ~
27505 \SpecialChar ~
27506 inc r0
27507 \layout Standard
27508
27509
27510 \size footnotesize
27511 ; goto _whilecontinue_0($1)
27512 \layout Standard
27513
27514
27515 \size footnotesize
27516 \SpecialChar ~
27517 \SpecialChar ~
27518 sjmp 00101$
27519 \layout Standard
27520
27521
27522 \size footnotesize
27523 ; _whilebreak_0($3) :
27524 \layout Standard
27525
27526
27527 \size footnotesize
27528 00103$:
27529 \layout Standard
27530
27531
27532 \size footnotesize
27533 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
27534 \layout Standard
27535
27536
27537 \size footnotesize
27538 \SpecialChar ~
27539 \SpecialChar ~
27540 mov r2,#0x00
27541 \layout Standard
27542
27543
27544 \size footnotesize
27545 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
27546 \layout Standard
27547
27548
27549 \size footnotesize
27550 \SpecialChar ~
27551 \SpecialChar ~
27552 mov r3,#0x00
27553 \layout Standard
27554
27555
27556 \size footnotesize
27557 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
27558 \layout Standard
27559
27560
27561 \size footnotesize
27562 \SpecialChar ~
27563 \SpecialChar ~
27564 mov r4,#0x00
27565 \layout Standard
27566
27567
27568 \size footnotesize
27569 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
27570 \layout Standard
27571
27572
27573 \size footnotesize
27574 \SpecialChar ~
27575 \SpecialChar ~
27576 mov r5,#0x0A
27577 \layout Standard
27578
27579
27580 \size footnotesize
27581 \SpecialChar ~
27582 \SpecialChar ~
27583 mov r6,#0x00
27584 \layout Standard
27585
27586
27587 \size footnotesize
27588 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
27589 \layout Standard
27590
27591
27592 \size footnotesize
27593 \SpecialChar ~
27594 \SpecialChar ~
27595 mov r7,#0x1E
27596 \layout Standard
27597
27598
27599 \size footnotesize
27600 \SpecialChar ~
27601 \SpecialChar ~
27602 mov r0,#0x00
27603 \layout Standard
27604
27605
27606 \size footnotesize
27607 ; _forcond_0($4) :
27608 \layout Standard
27609
27610
27611 \size footnotesize
27612 00104$:
27613 \layout Standard
27614
27615
27616 \size footnotesize
27617 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
27618 \layout Standard
27619
27620
27621 \size footnotesize
27622 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
27623 \layout Standard
27624
27625
27626 \size footnotesize
27627 \SpecialChar ~
27628 \SpecialChar ~
27629 clr c
27630 \layout Standard
27631
27632
27633 \size footnotesize
27634 \SpecialChar ~
27635 \SpecialChar ~
27636 mov a,r4
27637 \layout Standard
27638
27639
27640 \size footnotesize
27641 \SpecialChar ~
27642 \SpecialChar ~
27643 xrl a,#0x80
27644 \layout Standard
27645
27646
27647 \size footnotesize
27648 \SpecialChar ~
27649 \SpecialChar ~
27650 subb a,#0x8a
27651 \layout Standard
27652
27653
27654 \size footnotesize
27655 \SpecialChar ~
27656 \SpecialChar ~
27657 jnc 00107$
27658 \layout Standard
27659
27660
27661 \size footnotesize
27662 00115$:
27663 \layout Standard
27664
27665
27666 \size footnotesize
27667 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
27668 \layout Standard
27669
27670
27671 \size footnotesize
27672 ; iTemp21 [lr21:38]{short}[r4]
27673 \layout Standard
27674
27675
27676 \size footnotesize
27677 \SpecialChar ~
27678 \SpecialChar ~
27679 mov a,r4
27680 \layout Standard
27681
27682
27683 \size footnotesize
27684 \SpecialChar ~
27685 \SpecialChar ~
27686 add a,r2
27687 \layout Standard
27688
27689
27690 \size footnotesize
27691 \SpecialChar ~
27692 \SpecialChar ~
27693 mov r2,a
27694 \layout Standard
27695
27696
27697 \size footnotesize
27698 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
27699 \layout Standard
27700
27701
27702 \size footnotesize
27703 \SpecialChar ~
27704 \SpecialChar ~
27705 mov b,#0x03
27706 \layout Standard
27707
27708
27709 \size footnotesize
27710 \SpecialChar ~
27711 \SpecialChar ~
27712 mov a,r4
27713 \layout Standard
27714
27715
27716 \size footnotesize
27717 \SpecialChar ~
27718 \SpecialChar ~
27719 mul ab
27720 \layout Standard
27721
27722
27723 \size footnotesize
27724 \SpecialChar ~
27725 \SpecialChar ~
27726 mov r1,a
27727 \layout Standard
27728
27729
27730 \size footnotesize
27731 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
27732 \layout Standard
27733
27734
27735 \size footnotesize
27736 ; iTemp15 [lr29:30]{short}[r1]
27737 \layout Standard
27738
27739
27740 \size footnotesize
27741 \SpecialChar ~
27742 \SpecialChar ~
27743 add a,r3
27744 \layout Standard
27745
27746
27747 \size footnotesize
27748 \SpecialChar ~
27749 \SpecialChar ~
27750 mov r3,a
27751 \layout Standard
27752
27753
27754 \size footnotesize
27755 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
27756 \layout Standard
27757
27758
27759 \size footnotesize
27760 \SpecialChar ~
27761 \SpecialChar ~
27762 mov a,r7
27763 \layout Standard
27764
27765
27766 \size footnotesize
27767 \SpecialChar ~
27768 \SpecialChar ~
27769 add a,#0xfd
27770 \layout Standard
27771
27772
27773 \size footnotesize
27774 \SpecialChar ~
27775 \SpecialChar ~
27776 mov r7,a
27777 \layout Standard
27778
27779
27780 \size footnotesize
27781 \SpecialChar ~
27782 \SpecialChar ~
27783 mov a,r0
27784 \layout Standard
27785
27786
27787 \size footnotesize
27788 \SpecialChar ~
27789 \SpecialChar ~
27790 addc a,#0xff
27791 \layout Standard
27792
27793
27794 \size footnotesize
27795 \SpecialChar ~
27796 \SpecialChar ~
27797 mov r0,a
27798 \layout Standard
27799
27800
27801 \size footnotesize
27802 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
27803 \layout Standard
27804
27805
27806 \size footnotesize
27807 \SpecialChar ~
27808 \SpecialChar ~
27809 mov a,r7
27810 \layout Standard
27811
27812
27813 \size footnotesize
27814 \SpecialChar ~
27815 \SpecialChar ~
27816 add a,_gint
27817 \layout Standard
27818
27819
27820 \size footnotesize
27821 \SpecialChar ~
27822 \SpecialChar ~
27823 mov _gint,a
27824 \layout Standard
27825
27826
27827 \size footnotesize
27828 \SpecialChar ~
27829 \SpecialChar ~
27830 mov a,r0
27831 \layout Standard
27832
27833
27834 \size footnotesize
27835 \SpecialChar ~
27836 \SpecialChar ~
27837 addc a,(_gint + 1)
27838 \layout Standard
27839
27840
27841 \size footnotesize
27842 \SpecialChar ~
27843 \SpecialChar ~
27844 mov (_gint + 1),a
27845 \layout Standard
27846
27847
27848 \size footnotesize
27849 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
27850 \layout Standard
27851
27852
27853 \size footnotesize
27854 \SpecialChar ~
27855 \SpecialChar ~
27856 inc r4
27857 \layout Standard
27858
27859
27860 \size footnotesize
27861 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
27862 \layout Standard
27863
27864
27865 \size footnotesize
27866 \SpecialChar ~
27867 \SpecialChar ~
27868 dec r5
27869 \layout Standard
27870
27871
27872 \size footnotesize
27873 \SpecialChar ~
27874 \SpecialChar ~
27875 cjne r5,#0xff,00104$
27876 \layout Standard
27877
27878
27879 \size footnotesize
27880 \SpecialChar ~
27881 \SpecialChar ~
27882 dec r6
27883 \layout Standard
27884
27885
27886 \size footnotesize
27887 ; goto _forcond_0($4)
27888 \layout Standard
27889
27890
27891 \size footnotesize
27892 \SpecialChar ~
27893 \SpecialChar ~
27894 sjmp 00104$
27895 \layout Standard
27896
27897
27898 \size footnotesize
27899 ; _forbreak_0($7) :
27900 \layout Standard
27901
27902
27903 \size footnotesize
27904 00107$:
27905 \layout Standard
27906
27907
27908 \size footnotesize
27909 ; ret iTemp24 [lr40:41]{short}
27910 \layout Standard
27911
27912
27913 \size footnotesize
27914 \SpecialChar ~
27915 \SpecialChar ~
27916 mov a,r3
27917 \layout Standard
27918
27919
27920 \size footnotesize
27921 \SpecialChar ~
27922 \SpecialChar ~
27923 add a,r2
27924 \layout Standard
27925
27926
27927 \size footnotesize
27928 \SpecialChar ~
27929 \SpecialChar ~
27930 mov dpl,a
27931 \layout Standard
27932
27933
27934 \size footnotesize
27935 ; _return($8) :
27936 \layout Standard
27937
27938
27939 \size footnotesize
27940 00108$:
27941 \layout Standard
27942
27943
27944 \size footnotesize
27945 \SpecialChar ~
27946 \SpecialChar ~
27947 ret
27948 \newline
27949
27950 \layout Section
27951
27952 A few words about basic block successors, predecessors and dominators
27953 \layout Standard
27954
27955 Successors are basic blocks
27956 \begin_inset LatexCommand \index{Basic blocks}
27957
27958 \end_inset
27959
27960  that might execute after this basic block.
27961 \newline
27962 Predecessors are basic blocks that might execute before reaching this basic
27963  block.
27964 \newline
27965 Dominators are basic blocks that WILL execute before reaching this basic
27966  block.
27967 \newline
27968
27969 \layout Standard
27970
27971 [basic block 1]
27972 \layout Standard
27973
27974 if (something)
27975 \layout Standard
27976
27977 \SpecialChar ~
27978 \SpecialChar ~
27979 \SpecialChar ~
27980 \SpecialChar ~
27981 [basic block 2]
27982 \layout Standard
27983
27984 else
27985 \layout Standard
27986
27987 \SpecialChar ~
27988 \SpecialChar ~
27989 \SpecialChar ~
27990 \SpecialChar ~
27991 [basic block 3]
27992 \layout Standard
27993
27994 [basic block 4]
27995 \newline
27996
27997 \layout Standard
27998
27999 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
28000 \layout Standard
28001
28002 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
28003 \layout Standard
28004
28005 c) domVect of [BB4] = BB1 ...
28006  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
28007  was executed.
28008 \layout Chapter
28009
28010 Acknowledgments
28011 \layout Standard
28012
28013
28014 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
28015
28016 \end_inset
28017
28018
28019 \newline
28020
28021 \newline
28022
28023 \emph on
28024 Thanks to all the other volunteer developers who have helped with coding,
28025  testing, web-page creation, distribution sets, etc.
28026  You know who you are :-)
28027 \emph default
28028
28029 \newline
28030
28031 \layout Standard
28032
28033 This document was initially written by Sandeep Dutta
28034 \layout Standard
28035
28036 All product names mentioned herein may be trademarks
28037 \begin_inset LatexCommand \index{Trademarks}
28038
28039 \end_inset
28040
28041  of their respective companies.
28042
28043 \layout Section*
28044
28045 Alphabetical index
28046 \layout Standard
28047
28048 To avoid confusion, the installation and building options for SDCC itself
28049  (chapter 2) are not part of the index.
28050 \layout Standard
28051
28052
28053 \begin_inset LatexCommand \printindex{}
28054
28055 \end_inset
28056
28057
28058 \the_end