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

   1 #LyX 1.3 created this file. For more info see http://www.lyx.org/
   2 \lyxformat 221
   3 \textclass book
   4 \begin_preamble
   5 \pdfoptionpdfminorversion=3
   6 \usepackage[
   7   pdftitle={SDCC Compiler User Guide},
   8   pdfauthor={SDCC development team},
   9   pdfsubject={installation, user manual},
  10   pdfkeywords={8032 8051 ansi c compiler CPU DS390
  11                embedded GPL HC08 manual mcs51 microcontroller PIC Z80},
  12   colorlinks=true,
  13   linkcolor=blue] {hyperref}
  14 %
  15 \sloppy
  16 \tolerance=500
  17 \emergencystretch=30pt
  18 %
  19 \date{}
  20 \end_preamble
  21 \language english
  22 \inputencoding default
  23 \fontscheme pslatex
  24 \graphics default
  25 \paperfontsize default
  26 \spacing single
  27 \papersize letterpaper
  28 \paperpackage a4
  29 \use_geometry 1
  30 \use_amsmath 0
  31 \use_natbib 0
  32 \use_numerical_citations 0
  33 \paperorientation portrait
  34 \leftmargin 30mm
  35 \topmargin 20mm
  36 \rightmargin 25mm
  37 \bottommargin 20mm
  38 \secnumdepth 3
  39 \tocdepth 3
  40 \paragraph_separation indent
  41 \defskip medskip
  42 \quotes_language swedish
  43 \quotes_times 2
  44 \papercolumns 1
  45 \papersides 1
  46 \paperpagestyle fancy
  47
  48 \layout Comment
  49
  50 Please note: double dashed longoptions (e.g.
  51  --version) are written this way: -
  52 \begin_inset ERT
  53 status Collapsed
  54
  55 \layout Standard
  56
  57 \backslash
  58 /
  59 \end_inset
  60
  61 -
  62 \layout Comment
  63
  64 Two resp.
  65  three consecutive dashes simply result in a long resp.
  66  extra long dash.
  67 \layout Comment
  68
  69 Architecture specific stuff (like memory models, code examples) should maybe
  70  later go
  71 \layout Comment
  72
  73 into seperate sections/chapters/appendices (it is hard to document PIC or
  74  Z80 in
  75 \layout Comment
  76
  77 a 8051 centered document) - for now simply add.
  78 \layout Title
  79
  80 SDCC Compiler User Guide
  81 \layout Date
  82
  83
  84 \size normal
  85 SDCC 2.5.5
  86 \size footnotesize
  87
  88 \newline
  89 $Date$
  90 \newline
  91 $Revision$
  92 \layout Comment
  93
  94 The above strings enclosed in $ are automatically updated by cvs
  95 \layout Standard
  96
  97
  98 \begin_inset LatexCommand \tableofcontents{}
  99
 100 \end_inset
 101
 102
 103 \layout Chapter
 104
 105 Introduction
 106 \layout Section
 107
 108 About SDCC
 109 \layout Standard
 110
 111
 112 \series bold
 113 SDCC
 114 \series default
 115  (
 116 \emph on
 117 S
 118 \emph default
 119 mall
 120 \emph on
 121 D
 122 \emph default
 123 evice
 124 \emph on
 125 C
 126 \emph default
 127
 128 \emph on
 129 C
 130 \emph default
 131 ompiler) is an open source, retargettable, optimizing ANSI-C compiler by
 132
 133 \series bold
 134 Sandeep Dutta
 135 \series default
 136  designed for 8 bit Microprocessors.
 137  The current version targets Intel MCS51 based Microprocessors (8031, 8032,
 138  8051, 8052
 139 \begin_inset LatexCommand \index{8031, 8032, 8051, 8052, mcs51 CPU}
 140
 141 \end_inset
 142
 143 , etc.), Dallas DS80C390 variants, Freescale (formerly Motorola) HC08 and
 144  Zilog Z80 based MCUs.
 145  It can be retargetted for other microprocessors, support for Microchip
 146  PIC, Atmel AVR is under development.
 147  The entire source code for the compiler is distributed under GPL.
 148  SDCC uses ASXXXX
 149 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
 150
 151 \end_inset
 152
 153  & ASLINK
 154 \begin_inset LatexCommand \index{aslink}
 155
 156 \end_inset
 157
 158 , an open source retargettable assembler & linker.
 159  SDCC has extensive language extensions suitable for utilizing various microcont
 160 rollers and underlying hardware effectively.
 161
 162 \newline
 163
 164 \newline
 165 In addition to the MCU specific optimizations SDCC also does a host of standard
 166  optimizations like:
 167 \layout Itemize
 168
 169 global sub expression elimination,
 170 \layout Itemize
 171
 172 loop optimizations (loop invariant, strength reduction of induction variables
 173  and loop reversing),
 174 \layout Itemize
 175
 176 constant folding & propagation,
 177 \layout Itemize
 178
 179 copy propagation,
 180 \layout Itemize
 181
 182 dead code elimination
 183 \layout Itemize
 184
 185 jump tables for
 186 \emph on
 187 switch
 188 \emph default
 189  statements.
 190 \layout Standard
 191
 192 For the back-end SDCC uses a global register allocation scheme which should
 193  be well suited for other 8 bit MCUs.
 194
 195 \newline
 196
 197 \newline
 198 The peep hole optimizer uses a rule based substitution mechanism which is
 199  MCU independent.
 200
 201 \newline
 202
 203 \newline
 204 Supported data-types are:
 205 \layout Itemize
 206
 207 char (8 bits, 1 byte),
 208 \layout Itemize
 209
 210 short and int (16 bits, 2 bytes),
 211 \layout Itemize
 212
 213 long (32 bit, 4 bytes)
 214 \layout Itemize
 215
 216 float (4 byte IEEE).
 217
 218 \layout Standard
 219
 220 The compiler also allows
 221 \emph on
 222 inline assembler code
 223 \emph default
 224  to be embedded anywhere in a function.
 225  In addition, routines developed in assembly can also be called.
 226 \newline
 227
 228 \newline
 229 SDCC also provides an option (-
 230 \begin_inset ERT
 231 status Collapsed
 232
 233 \layout Standard
 234
 235 \backslash
 236 /
 237 \end_inset
 238
 239 -cyclomatic) to report the relative complexity of a function.
 240  These functions can then be further optimized, or hand coded in assembly
 241  if needed.
 242
 243 \newline
 244
 245 \newline
 246 SDCC also comes with a companion source level debugger SDCDB, the debugger
 247  currently uses ucSim a freeware simulator for 8051 and other micro-controllers.
 248
 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-large
6060 \begin_inset LatexCommand \index{-\/-model-large}
6061
6062 \end_inset
6063
6064
6065 \series default
6066  Generate code for Large model programs, see section Memory Models for more
6067  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 -xstack
6087 \begin_inset LatexCommand \index{-\/-xstack}
6088
6089 \end_inset
6090
6091
6092 \series default
6093  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
6094  variables and passing parameters.
6095  See section
6096 \begin_inset LatexCommand \ref{sub:External-Stack}
6097
6098 \end_inset
6099
6100 \SpecialChar ~
6101  External Stack for more details.
6102 \layout List
6103 \labelwidthstring 00.00.0000
6104
6105
6106 \series bold
6107 -
6108 \begin_inset ERT
6109 status Collapsed
6110
6111 \layout Standard
6112
6113 \backslash
6114 /
6115 \end_inset
6116
6117 -iram-size
6118 \series default
6119 \SpecialChar ~
6120 <Value>
6121 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
6122
6123 \end_inset
6124
6125  Causes the linker to check if the internal ram usage is within limits of
6126  the given value.
6127 \layout List
6128 \labelwidthstring 00.00.0000
6129
6130
6131 \series bold
6132 -
6133 \begin_inset ERT
6134 status Collapsed
6135
6136 \layout Standard
6137
6138 \backslash
6139 /
6140 \end_inset
6141
6142 -xram-size
6143 \series default
6144 \SpecialChar ~
6145 <Value>
6146 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
6147
6148 \end_inset
6149
6150  Causes the linker to check if the external ram usage is within limits of
6151  the given value.
6152 \layout List
6153 \labelwidthstring 00.00.0000
6154
6155
6156 \series bold
6157 -
6158 \begin_inset ERT
6159 status Collapsed
6160
6161 \layout Standard
6162
6163 \backslash
6164 /
6165 \end_inset
6166
6167 -code-size
6168 \series default
6169 \SpecialChar ~
6170 <Value>
6171 \begin_inset LatexCommand \index{-\/-code-size <Value>}
6172
6173 \end_inset
6174
6175  Causes the linker to check if the code memory usage is within limits of
6176  the given value.
6177 \layout List
6178 \labelwidthstring 00.00.0000
6179
6180
6181 \series bold
6182 -
6183 \begin_inset ERT
6184 status Collapsed
6185
6186 \layout Standard
6187
6188 \backslash
6189 /
6190 \end_inset
6191
6192 -stack-size
6193 \series default
6194 \SpecialChar ~
6195 <Value>
6196 \begin_inset LatexCommand \index{-\/-stack-size <Value>}
6197
6198 \end_inset
6199
6200  Causes the linker to check if there is at minimum <Value> bytes for stack.
6201 \layout List
6202 \labelwidthstring 00.00.0000
6203
6204
6205 \series bold
6206 -
6207 \begin_inset ERT
6208 status Collapsed
6209
6210 \layout Standard
6211
6212 \backslash
6213 /
6214 \end_inset
6215
6216 -pack-iram
6217 \series default
6218 \SpecialChar ~
6219
6220 \begin_inset LatexCommand \index{-\/-pack-iram}
6221
6222 \end_inset
6223
6224  Causes the linker to use unused register banks for data variables and pack
6225  data, idata and stack together.
6226  This is the default now.
6227 \layout List
6228 \labelwidthstring 00.00.0000
6229
6230
6231 \series bold
6232 -
6233 \begin_inset ERT
6234 status Collapsed
6235
6236 \layout Standard
6237
6238 \backslash
6239 /
6240 \end_inset
6241
6242 -no-pack-iram
6243 \series default
6244 \SpecialChar ~
6245
6246 \begin_inset LatexCommand \index{-\/-no-pack-iram}
6247
6248 \end_inset
6249
6250  Causes the linker to use old style for allocating memory areas.
6251 \layout Subsection
6252
6253 DS390 / DS400 Options
6254 \begin_inset LatexCommand \index{Options DS390}
6255
6256 \end_inset
6257
6258
6259 \begin_inset LatexCommand \index{DS390 options}
6260
6261 \end_inset
6262
6263
6264 \layout List
6265 \labelwidthstring 00.00.0000
6266
6267
6268 \series bold
6269 -
6270 \begin_inset ERT
6271 status Collapsed
6272
6273 \layout Standard
6274
6275 \backslash
6276 /
6277 \end_inset
6278
6279 -model-flat24
6280 \series default
6281
6282 \begin_inset LatexCommand \index{-\/-model-flat24}
6283
6284 \end_inset
6285
6286
6287 \size large
6288 \emph on
6289
6290 \size default
6291 \emph default
6292 Generate 24-bit flat mode code.
6293  This is the one and only that the ds390 code generator supports right now
6294  and is default when using
6295 \emph on
6296 -mds390
6297 \emph default
6298 .
6299  See section Memory Models for more details.
6300 \layout List
6301 \labelwidthstring 00.00.0000
6302
6303
6304 \series bold
6305 -
6306 \begin_inset ERT
6307 status Collapsed
6308
6309 \layout Standard
6310
6311 \backslash
6312 /
6313 \end_inset
6314
6315 -protect-sp-update
6316 \begin_inset LatexCommand \index{-\/-protect-sp-update}
6317
6318 \end_inset
6319
6320
6321 \series default
6322  disable interrupts during ESP:SP updates.
6323 \layout List
6324 \labelwidthstring 00.00.0000
6325
6326
6327 \series bold
6328 -
6329 \begin_inset ERT
6330 status Collapsed
6331
6332 \layout Standard
6333
6334 \backslash
6335 /
6336 \end_inset
6337
6338 -stack-10bit
6339 \series default
6340
6341 \begin_inset LatexCommand \index{-\/-stack-10bit}
6342
6343 \end_inset
6344
6345  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
6346  This is the one and only that the ds390 code generator supports right now
6347  and is default when using
6348 \emph on
6349 -mds390
6350 \emph default
6351 .
6352  In this mode, the stack is located in the lower 1K of the internal RAM,
6353  which is mapped to 0x400000.
6354  Note that the support is incomplete, since it still uses a single byte
6355  as the stack pointer.
6356  This means that only the lower 256 bytes of the potential 1K stack space
6357  will actually be used.
6358  However, this does allow you to reclaim the precious 256 bytes of low RAM
6359  for use for the DATA and IDATA segments.
6360  The compiler will not generate any code to put the processor into 10 bit
6361  stack mode.
6362  It is important to ensure that the processor is in this mode before calling
6363  any re-entrant functions compiled with this option.
6364  In principle, this should work with the
6365 \emph on
6366 -
6367 \begin_inset ERT
6368 status Collapsed
6369
6370 \layout Standard
6371
6372 \backslash
6373 /
6374 \end_inset
6375
6376 -stack-auto
6377 \begin_inset LatexCommand \index{-\/-stack-auto}
6378
6379 \end_inset
6380
6381
6382 \emph default
6383  option, but that has not been tested.
6384  It is incompatible with the
6385 \emph on
6386 -
6387 \begin_inset ERT
6388 status Collapsed
6389
6390 \layout Standard
6391
6392 \backslash
6393 /
6394 \end_inset
6395
6396 -xstack
6397 \begin_inset LatexCommand \index{-\/-xstack}
6398
6399 \end_inset
6400
6401
6402 \emph default
6403  option.
6404  It also only makes sense if the processor is in 24 bit contiguous addressing
6405  mode (see the
6406 \emph on
6407 -
6408 \begin_inset ERT
6409 status Collapsed
6410
6411 \layout Standard
6412
6413 \backslash
6414 /
6415 \end_inset
6416
6417 -model-flat24 option
6418 \emph default
6419 ).
6420 \layout List
6421 \labelwidthstring 00.00.0000
6422
6423
6424 \series bold
6425 -
6426 \begin_inset ERT
6427 status Collapsed
6428
6429 \layout Standard
6430
6431 \backslash
6432 /
6433 \end_inset
6434
6435 -stack-probe
6436 \begin_inset LatexCommand \index{-\/-stack-probe}
6437
6438 \end_inset
6439
6440
6441 \series default
6442  insert call to function __stack_probe at each function prologue.
6443 \layout List
6444 \labelwidthstring 00.00.0000
6445
6446
6447 \series bold
6448 -
6449 \begin_inset ERT
6450 status Collapsed
6451
6452 \layout Standard
6453
6454 \backslash
6455 /
6456 \end_inset
6457
6458 -tini-libid
6459 \begin_inset LatexCommand \index{-\/-tini-libid}
6460
6461 \end_inset
6462
6463
6464 \series default
6465  <nnnn> LibraryID used in -mTININative.
6466
6467 \layout List
6468 \labelwidthstring 00.00.0000
6469
6470
6471 \series bold
6472 -
6473 \begin_inset ERT
6474 status Collapsed
6475
6476 \layout Standard
6477
6478 \backslash
6479 /
6480 \end_inset
6481
6482 -use-accelerator
6483 \begin_inset LatexCommand \index{-\/-use-accelerator}
6484
6485 \end_inset
6486
6487
6488 \series default
6489  generate code for DS390 Arithmetic Accelerator.
6490
6491 \layout Subsection
6492
6493 Z80 Options
6494 \begin_inset LatexCommand \index{Options Z80}
6495
6496 \end_inset
6497
6498
6499 \begin_inset LatexCommand \index{Z80 options}
6500
6501 \end_inset
6502
6503
6504 \layout List
6505 \labelwidthstring 00.00.0000
6506
6507
6508 \series bold
6509 -
6510 \begin_inset ERT
6511 status Collapsed
6512
6513 \layout Standard
6514
6515 \backslash
6516 /
6517 \end_inset
6518
6519 -callee-saves-bc
6520 \series default
6521
6522 \begin_inset LatexCommand \index{-\/-callee-saves-bc}
6523
6524 \end_inset
6525
6526
6527 \size large
6528 \emph on
6529
6530 \size default
6531 \emph default
6532 Force a called function to always save BC.
6533 \layout List
6534 \labelwidthstring 00.00.0000
6535
6536
6537 \series bold
6538 -
6539 \begin_inset ERT
6540 status Collapsed
6541
6542 \layout Standard
6543
6544 \backslash
6545 /
6546 \end_inset
6547
6548 -no-std-crt0
6549 \series default
6550
6551 \begin_inset LatexCommand \index{-\/-no-std-crt0}
6552
6553 \end_inset
6554
6555  When linking, skip the standard crt0.o object file.
6556  You must provide your own crt0.o for your system when linking.
6557
6558 \layout Subsection
6559
6560 Optimization Options
6561 \begin_inset LatexCommand \index{Options optimization}
6562
6563 \end_inset
6564
6565
6566 \begin_inset LatexCommand \index{Optimization options}
6567
6568 \end_inset
6569
6570
6571 \layout List
6572 \labelwidthstring 00.00.0000
6573
6574
6575 \series bold
6576 -
6577 \begin_inset ERT
6578 status Collapsed
6579
6580 \layout Standard
6581
6582 \backslash
6583 /
6584 \end_inset
6585
6586 -nogcse
6587 \begin_inset LatexCommand \index{-\/-nogcse}
6588
6589 \end_inset
6590
6591
6592 \series default
6593  Will not do global subexpression elimination, this option may be used when
6594  the compiler creates undesirably large stack/data spaces to store compiler
6595  temporaries (
6596 \emph on
6597 s
6598 \emph default
6599 pill
6600 \emph on
6601 loc
6602 \emph default
6603 ations, sloc
6604 \begin_inset LatexCommand \index{sloc (spill location)}
6605
6606 \end_inset
6607
6608 ).
6609  A warning message will be generated when this happens and the compiler
6610  will indicate the number of extra bytes it allocated.
6611  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6612 nogcse
6613 \begin_inset LatexCommand \index{\#pragma nogcse}
6614
6615 \end_inset
6616
6617  can be used to turn off global subexpression elimination
6618 \begin_inset LatexCommand \index{Subexpression elimination}
6619
6620 \end_inset
6621
6622  for a given function only.
6623 \layout List
6624 \labelwidthstring 00.00.0000
6625
6626
6627 \series bold
6628 -
6629 \begin_inset ERT
6630 status Collapsed
6631
6632 \layout Standard
6633
6634 \backslash
6635 /
6636 \end_inset
6637
6638 -noinvariant
6639 \begin_inset LatexCommand \index{-\/-noinvariant}
6640
6641 \end_inset
6642
6643
6644 \series default
6645  Will not do loop invariant optimizations, this may be turned off for reasons
6646  explained for the previous option.
6647  For more details of loop optimizations performed see Loop Invariants in
6648  section
6649 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
6650
6651 \end_inset
6652
6653 .
6654  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6655 noinvariant
6656 \begin_inset LatexCommand \index{\#pragma noinvariant}
6657
6658 \end_inset
6659
6660  can be used to turn off invariant optimizations for a given function only.
6661 \layout List
6662 \labelwidthstring 00.00.0000
6663
6664
6665 \series bold
6666 -
6667 \begin_inset ERT
6668 status Collapsed
6669
6670 \layout Standard
6671
6672 \backslash
6673 /
6674 \end_inset
6675
6676 -noinduction
6677 \begin_inset LatexCommand \index{-\/-noinduction}
6678
6679 \end_inset
6680
6681
6682 \series default
6683  Will not do loop induction optimizations, see section strength reduction
6684  for more details.
6685  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6686 noinduction
6687 \begin_inset LatexCommand \index{\#pragma noinduction}
6688
6689 \end_inset
6690
6691  can be used to turn off induction optimizations for a given function only.
6692 \layout List
6693 \labelwidthstring 00.00.0000
6694
6695
6696 \series bold
6697 -
6698 \begin_inset ERT
6699 status Collapsed
6700
6701 \layout Standard
6702
6703 \backslash
6704 /
6705 \end_inset
6706
6707 -nojtbound
6708 \begin_inset LatexCommand \index{-\/-nojtbound}
6709
6710 \end_inset
6711
6712
6713 \size large
6714 \bar under
6715
6716 \series default
6717 \size default
6718 \bar default
6719  Will not generate boundary condition check when switch statements
6720 \begin_inset LatexCommand \index{switch statement}
6721
6722 \end_inset
6723
6724  are implemented using jump-tables.
6725  See section
6726 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
6727
6728 \end_inset
6729
6730 \SpecialChar ~
6731 Switch Statements for more details.
6732  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6733 nojtbound
6734 \begin_inset LatexCommand \index{\#pragma nojtbound}
6735
6736 \end_inset
6737
6738  can be used to turn off boundary checking for jump tables for a given function
6739  only.
6740 \layout List
6741 \labelwidthstring 00.00.0000
6742
6743
6744 \series bold
6745 -
6746 \begin_inset ERT
6747 status Collapsed
6748
6749 \layout Standard
6750
6751 \backslash
6752 /
6753 \end_inset
6754
6755 -noloopreverse
6756 \begin_inset LatexCommand \index{-\/-noloopreverse}
6757
6758 \end_inset
6759
6760
6761 \series default
6762 \size large
6763
6764 \size default
6765 Will not do loop reversal
6766 \begin_inset LatexCommand \index{Loop reversing}
6767
6768 \end_inset
6769
6770 optimization.
6771 \layout List
6772 \labelwidthstring 00.00.0000
6773
6774 -
6775 \begin_inset ERT
6776 status Collapsed
6777
6778 \layout Standard
6779
6780 \backslash
6781 /
6782 \end_inset
6783
6784 -
6785 \series bold
6786 nolabelopt
6787 \series default
6788
6789 \begin_inset LatexCommand \index{-\/-nolabelopt }
6790
6791 \end_inset
6792
6793 Will not optimize labels (makes the dumpfiles more readable).
6794 \layout List
6795 \labelwidthstring 00.00.0000
6796
6797
6798 \series bold
6799 -
6800 \begin_inset ERT
6801 status Collapsed
6802
6803 \layout Standard
6804
6805 \backslash
6806 /
6807 \end_inset
6808
6809 -no-xinit-opt
6810 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
6811
6812 \end_inset
6813
6814
6815 \series default
6816  Will not memcpy initialized data from code space into xdata space.
6817  This saves a few bytes in code space if you don't have initialized data
6818 \begin_inset LatexCommand \index{Variable initialization}
6819
6820 \end_inset
6821
6822 .
6823 \layout List
6824 \labelwidthstring 00.00.0000
6825
6826
6827 \series bold
6828 -
6829 \begin_inset ERT
6830 status Collapsed
6831
6832 \layout Standard
6833
6834 \backslash
6835 /
6836 \end_inset
6837
6838 -nooverlay
6839 \begin_inset LatexCommand \index{-\/-nooverlay}
6840
6841 \end_inset
6842
6843
6844 \series default
6845   The compiler will not overlay parameters and local variables of any function,
6846  see section Parameters and local variables for more details.
6847 \layout List
6848 \labelwidthstring 00.00.0000
6849
6850
6851 \series bold
6852 -
6853 \begin_inset ERT
6854 status Collapsed
6855
6856 \layout Standard
6857
6858 \backslash
6859 /
6860 \end_inset
6861
6862 -no-peep
6863 \begin_inset LatexCommand \index{-\/-no-peep}
6864
6865 \end_inset
6866
6867
6868 \series default
6869  Disable peep-hole optimization.
6870 \layout List
6871 \labelwidthstring 00.00.0000
6872
6873
6874 \series bold
6875 -
6876 \begin_inset ERT
6877 status Collapsed
6878
6879 \layout Standard
6880
6881 \backslash
6882 /
6883 \end_inset
6884
6885 -peep-file
6886 \series default
6887
6888 \begin_inset LatexCommand \index{-\/-peep-file}
6889
6890 \end_inset
6891
6892 \SpecialChar ~
6893 <filename> This option can be used to use additional rules to be used by
6894  the peep hole optimizer.
6895  See section
6896 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
6897
6898 \end_inset
6899
6900 \SpecialChar ~
6901 Peep Hole optimizations for details on how to write these rules.
6902 \layout List
6903 \labelwidthstring 00.00.0000
6904
6905
6906 \series bold
6907 -
6908 \begin_inset ERT
6909 status Collapsed
6910
6911 \layout Standard
6912
6913 \backslash
6914 /
6915 \end_inset
6916
6917 -peep-asm
6918 \begin_inset LatexCommand \index{-\/-peep-asm}
6919
6920 \end_inset
6921
6922
6923 \series default
6924  Pass the inline assembler code through the peep hole optimizer.
6925  This can cause unexpected changes to inline assembler code, please go through
6926  the peephole optimizer
6927 \begin_inset LatexCommand \index{Peephole optimizer}
6928
6929 \end_inset
6930
6931  rules defined in the source file tree '<target>/peeph.def' before using
6932  this option.
6933 \layout List
6934 \labelwidthstring 00.00.0000
6935
6936
6937 \series bold
6938 -
6939 \begin_inset ERT
6940 status Collapsed
6941
6942 \layout Standard
6943
6944 \backslash
6945 /
6946 \end_inset
6947
6948 -opt-code-speed
6949 \begin_inset LatexCommand \index{-\/-opt-code-speed}
6950
6951 \end_inset
6952
6953
6954 \series default
6955  The compiler will optimize code generation towards fast code, possibly
6956  at the expense of code size.
6957 \layout List
6958 \labelwidthstring 00.00.0000
6959
6960
6961 \series bold
6962 -
6963 \begin_inset ERT
6964 status Collapsed
6965
6966 \layout Standard
6967
6968 \backslash
6969 /
6970 \end_inset
6971
6972 -opt-code-size
6973 \begin_inset LatexCommand \index{-\/-opt-code-size}
6974
6975 \end_inset
6976
6977
6978 \series default
6979  The compiler will optimize code generation towards compact code, possibly
6980  at the expense of code speed.
6981 \layout Subsection
6982
6983 Other Options
6984 \begin_inset LatexCommand \index{Options other}
6985
6986 \end_inset
6987
6988
6989 \layout List
6990 \labelwidthstring 00.00.0000
6991
6992
6993 \series bold
6994 -c\SpecialChar ~
6995 -
6996 \begin_inset ERT
6997 status Collapsed
6998
6999 \layout Standard
7000
7001 \backslash
7002 /
7003 \end_inset
7004
7005 -compile-only
7006 \begin_inset LatexCommand \index{-\/-compile-only}
7007
7008 \end_inset
7009
7010
7011 \begin_inset LatexCommand \index{-c -\/-compile-only}
7012
7013 \end_inset
7014
7015
7016 \series default
7017  will compile and assemble the source, but will not call the linkage editor.
7018 \layout List
7019 \labelwidthstring 00.00.0000
7020
7021
7022 \series bold
7023 -
7024 \series default
7025
7026 \begin_inset ERT
7027 status Collapsed
7028
7029 \layout Standard
7030
7031 \backslash
7032 /
7033 \end_inset
7034
7035
7036 \series bold
7037 -c1mode
7038 \begin_inset LatexCommand \index{-\/-c1mode}
7039
7040 \end_inset
7041
7042
7043 \series default
7044  reads the preprocessed source from standard input and compiles it.
7045  The file name for the assembler output must be specified using the -o option.
7046 \layout List
7047 \labelwidthstring 00.00.0000
7048
7049
7050 \series bold
7051 -E
7052 \begin_inset LatexCommand \index{-E}
7053
7054 \end_inset
7055
7056
7057 \series default
7058  Run only the C preprocessor.
7059  Preprocess all the C source files specified and output the results to standard
7060  output.
7061 \layout List
7062 \labelwidthstring 00.00.0000
7063
7064
7065 \series bold
7066 -o\SpecialChar ~
7067 <path/file>
7068 \begin_inset LatexCommand \index{-o <path/file>}
7069
7070 \end_inset
7071
7072
7073 \series default
7074 The output path resp.
7075  file where everything will be placed.
7076  If the parameter is a path, it must have a trailing slash (or backslash
7077  for the Windows binaries) to be recognized as a path.
7078
7079 \layout List
7080 \labelwidthstring 00.00.0000
7081
7082
7083 \series bold
7084 -
7085 \begin_inset ERT
7086 status Collapsed
7087
7088 \layout Standard
7089
7090 \backslash
7091 /
7092 \end_inset
7093
7094 -stack-auto
7095 \begin_inset LatexCommand \index{-\/-stack-auto}
7096
7097 \end_inset
7098
7099
7100 \series default
7101 \size large
7102 \emph on
7103
7104 \size default
7105 \emph default
7106 All functions in the source file will be compiled as
7107 \emph on
7108 reentrant
7109 \emph default
7110
7111 \begin_inset LatexCommand \index{reentrant}
7112
7113 \end_inset
7114
7115 , i.e.
7116  the parameters and local variables will be allocated on the stack
7117 \begin_inset LatexCommand \index{stack}
7118
7119 \end_inset
7120
7121 .
7122  See section
7123 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
7124
7125 \end_inset
7126
7127  Parameters and Local Variables for more details.
7128  If this option is used all source files in the project should be compiled
7129  with this option.
7130  It automatically implies --int-long-reent and --float-reent.
7131
7132 \layout List
7133 \labelwidthstring 00.00.0000
7134
7135
7136 \series bold
7137 -
7138 \begin_inset ERT
7139 status Collapsed
7140
7141 \layout Standard
7142
7143 \backslash
7144 /
7145 \end_inset
7146
7147 -callee-saves
7148 \begin_inset LatexCommand \index{-\/-callee-saves}
7149
7150 \end_inset
7151
7152  function1[,function2][,function3]....
7153
7154 \series default
7155  The compiler by default uses a caller saves convention for register saving
7156  across function calls, however this can cause unnecessary register pushing
7157  & popping when calling small functions from larger functions.
7158  This option can be used to switch the register saving convention for the
7159  function names specified.
7160  The compiler will not save registers when calling these functions, no extra
7161  code will be generated at the entry & exit (function prologue
7162 \series bold
7163
7164 \begin_inset LatexCommand \index{function prologue}
7165
7166 \end_inset
7167
7168
7169 \series default
7170  & epilogue
7171 \series bold
7172
7173 \begin_inset LatexCommand \index{function epilogue}
7174
7175 \end_inset
7176
7177
7178 \series default
7179 ) for these functions to save & restore the registers used by these functions,
7180  this can SUBSTANTIALLY reduce code & improve run time performance of the
7181  generated code.
7182  In the future the compiler (with inter procedural analysis) will be able
7183  to determine the appropriate scheme to use for each function call.
7184  DO NOT use this option for built-in functions such as _mulint..., if this
7185  option is used for a library function the appropriate library function
7186  needs to be recompiled with the same option.
7187  If the project consists of multiple source files then all the source file
7188  should be compiled with the same -
7189 \begin_inset ERT
7190 status Collapsed
7191
7192 \layout Standard
7193
7194 \backslash
7195 /
7196 \end_inset
7197
7198 -callee-saves option string.
7199  Also see #pragma\SpecialChar ~
7200 callee_saves
7201 \begin_inset LatexCommand \index{\#pragma callee\_saves}
7202
7203 \end_inset
7204
7205 .
7206 \layout List
7207 \labelwidthstring 00.00.0000
7208
7209
7210 \series bold
7211 -
7212 \begin_inset ERT
7213 status Collapsed
7214
7215 \layout Standard
7216
7217 \backslash
7218 /
7219 \end_inset
7220
7221 -debug
7222 \begin_inset LatexCommand \index{-\/-debug}
7223
7224 \end_inset
7225
7226
7227 \bar under
7228
7229 \series default
7230 \bar default
7231 When this option is used the compiler will generate debug information.
7232  The debug information collected in a file with .cdb extension can be used
7233  with the SDCDB.
7234  For more information see documentation for SDCDB.
7235  Another file with no extension contains debug information in AOMF or AOMF51
7236 \begin_inset LatexCommand \index{AOMF, AOMF51}
7237
7238 \end_inset
7239
7240  format which is commonly used by third party tools.
7241 \layout List
7242 \labelwidthstring 00.00.0000
7243
7244
7245 \series bold
7246 -S
7247 \begin_inset LatexCommand \index{-S}
7248
7249 \end_inset
7250
7251
7252 \size large
7253 \bar under
7254
7255 \series default
7256 \size default
7257 \bar default
7258 Stop after the stage of compilation proper; do not assemble.
7259  The output is an assembler code file for the input file specified.
7260 \layout List
7261 \labelwidthstring 00.00.0000
7262
7263
7264 \series bold
7265 -
7266 \begin_inset ERT
7267 status Collapsed
7268
7269 \layout Standard
7270
7271 \backslash
7272 /
7273 \end_inset
7274
7275 -int-long-reent
7276 \begin_inset LatexCommand \index{-\/-int-long-reent}
7277
7278 \end_inset
7279
7280
7281 \series default
7282  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
7283  Note by default these libraries are compiled as non-reentrant.
7284  See section Installation for more details.
7285 \layout List
7286 \labelwidthstring 00.00.0000
7287
7288
7289 \series bold
7290 -
7291 \begin_inset ERT
7292 status Collapsed
7293
7294 \layout Standard
7295
7296 \backslash
7297 /
7298 \end_inset
7299
7300 -cyclomatic
7301 \begin_inset LatexCommand \index{-\/-cyclomatic}
7302
7303 \end_inset
7304
7305
7306 \bar under
7307
7308 \series default
7309 \bar default
7310 This option will cause the compiler to generate an information message for
7311  each function in the source file.
7312  The message contains some
7313 \emph on
7314 important
7315 \emph default
7316  information about the function.
7317  The number of edges and nodes the compiler detected in the control flow
7318  graph of the function, and most importantly the
7319 \emph on
7320 cyclomatic complexity
7321 \begin_inset LatexCommand \index{Cyclomatic complexity}
7322
7323 \end_inset
7324
7325
7326 \emph default
7327  see section on Cyclomatic Complexity for more details.
7328 \layout List
7329 \labelwidthstring 00.00.0000
7330
7331
7332 \series bold
7333 -
7334 \begin_inset ERT
7335 status Collapsed
7336
7337 \layout Standard
7338
7339 \backslash
7340 /
7341 \end_inset
7342
7343 -float-reent
7344 \begin_inset LatexCommand \index{-\/-float-reent}
7345
7346 \end_inset
7347
7348
7349 \series default
7350  Floating point library is compiled as reentrant
7351 \begin_inset LatexCommand \index{reentrant}
7352
7353 \end_inset
7354
7355 .
7356  See section Installation for more details.
7357 \layout List
7358 \labelwidthstring 00.00.0000
7359
7360
7361 \series bold
7362 -
7363 \begin_inset ERT
7364 status Collapsed
7365
7366 \layout Standard
7367
7368 \backslash
7369 /
7370 \end_inset
7371
7372 -main-return
7373 \begin_inset LatexCommand \index{-\/-main-return}
7374
7375 \end_inset
7376
7377
7378 \series default
7379  This option can be used if the code generated is called by a monitor program
7380  or if the main routine includes an endless loop.
7381  This option might result in slightly smaller code and save two bytes of
7382  stack space.
7383  The return from the 'main'
7384 \begin_inset LatexCommand \index{main return}
7385
7386 \end_inset
7387
7388  function will return to the function calling main.
7389  The default setting is to lock up i.e.
7390  generate a '
7391 \family typewriter
7392 sjmp .
7393 \family default
7394 '.
7395 \layout List
7396 \labelwidthstring 00.00.0000
7397
7398
7399 \series bold
7400 -
7401 \begin_inset ERT
7402 status Collapsed
7403
7404 \layout Standard
7405
7406 \backslash
7407 /
7408 \end_inset
7409
7410 -nostdinc
7411 \begin_inset LatexCommand \index{-\/-nostdinc}
7412
7413 \end_inset
7414
7415
7416 \series default
7417  This will prevent the compiler from passing on the default include path
7418  to the preprocessor.
7419 \layout List
7420 \labelwidthstring 00.00.0000
7421
7422
7423 \series bold
7424 -
7425 \begin_inset ERT
7426 status Collapsed
7427
7428 \layout Standard
7429
7430 \backslash
7431 /
7432 \end_inset
7433
7434 -nostdlib
7435 \begin_inset LatexCommand \index{-\/-nostdlib}
7436
7437 \end_inset
7438
7439
7440 \series default
7441  This will prevent the compiler from passing on the default library
7442 \begin_inset LatexCommand \index{Libraries}
7443
7444 \end_inset
7445
7446  path to the linker.
7447 \layout List
7448 \labelwidthstring 00.00.0000
7449
7450
7451 \series bold
7452 -
7453 \begin_inset ERT
7454 status Collapsed
7455
7456 \layout Standard
7457
7458 \backslash
7459 /
7460 \end_inset
7461
7462 -verbose
7463 \begin_inset LatexCommand \index{-\/-verbose}
7464
7465 \end_inset
7466
7467
7468 \series default
7469  Shows the various actions the compiler is performing.
7470 \layout List
7471 \labelwidthstring 00.00.0000
7472
7473
7474 \series bold
7475 -V
7476 \begin_inset LatexCommand \index{-V}
7477
7478 \end_inset
7479
7480
7481 \series default
7482  Shows the actual commands the compiler is executing.
7483 \layout List
7484 \labelwidthstring 00.00.0000
7485
7486
7487 \series bold
7488 -
7489 \begin_inset ERT
7490 status Collapsed
7491
7492 \layout Standard
7493
7494 \backslash
7495 /
7496 \end_inset
7497
7498 -no-c-code-in-asm
7499 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
7500
7501 \end_inset
7502
7503
7504 \series default
7505  Hides your ugly and inefficient c-code from the asm file, so you can always
7506  blame the compiler :)
7507 \layout List
7508 \labelwidthstring 00.00.0000
7509
7510
7511 \series bold
7512 -
7513 \begin_inset ERT
7514 status Collapsed
7515
7516 \layout Standard
7517
7518 \backslash
7519 /
7520 \end_inset
7521
7522 -no-peep-comments
7523 \begin_inset LatexCommand \index{-\/-no-peep-comments}
7524
7525 \end_inset
7526
7527
7528 \series default
7529  Will not include peep-hole comments in the generated files.
7530 \layout List
7531 \labelwidthstring 00.00.0000
7532
7533
7534 \series bold
7535 -
7536 \begin_inset ERT
7537 status Collapsed
7538
7539 \layout Standard
7540
7541 \backslash
7542 /
7543 \end_inset
7544
7545 -i-code-in-asm
7546 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
7547
7548 \end_inset
7549
7550
7551 \series default
7552  Include i-codes in the asm file.
7553  Sounds like noise but is most helpful for debugging the compiler itself.
7554 \layout List
7555 \labelwidthstring 00.00.0000
7556
7557
7558 \series bold
7559 -
7560 \begin_inset ERT
7561 status Collapsed
7562
7563 \layout Standard
7564
7565 \backslash
7566 /
7567 \end_inset
7568
7569 -less-pedantic
7570 \begin_inset LatexCommand \index{-\/-less-pedantic}
7571
7572 \end_inset
7573
7574
7575 \series default
7576  Disable some of the more pedantic warnings
7577 \begin_inset LatexCommand \index{Warnings}
7578
7579 \end_inset
7580
7581  (jwk burps: please be more specific here, please!).
7582 \layout List
7583 \labelwidthstring 00.00.0000
7584
7585
7586 \series bold
7587 -
7588 \begin_inset ERT
7589 status Collapsed
7590
7591 \layout Standard
7592
7593 \backslash
7594 /
7595 \end_inset
7596
7597 -disable-warning\SpecialChar ~
7598 <nnnn>
7599 \begin_inset LatexCommand \index{-\/-disable-warning}
7600
7601 \end_inset
7602
7603
7604 \series default
7605  Disable specific warning with number <nnnn>.
7606 \layout List
7607 \labelwidthstring 00.00.0000
7608
7609
7610 \series bold
7611 -
7612 \begin_inset ERT
7613 status Collapsed
7614
7615 \layout Standard
7616
7617 \backslash
7618 /
7619 \end_inset
7620
7621 -print-search-dirs
7622 \begin_inset LatexCommand \index{-\/-print-search-dirs}
7623
7624 \end_inset
7625
7626
7627 \series default
7628  Display the directories in the compiler's search path
7629 \layout List
7630 \labelwidthstring 00.00.0000
7631
7632
7633 \series bold
7634 -
7635 \begin_inset ERT
7636 status Collapsed
7637
7638 \layout Standard
7639
7640 \backslash
7641 /
7642 \end_inset
7643
7644 -vc
7645 \begin_inset LatexCommand \index{-\/-vc}
7646
7647 \end_inset
7648
7649
7650 \series default
7651  Display errors and warnings using MSVC style, so you can use SDCC with
7652  visual studio.
7653 \layout List
7654 \labelwidthstring 00.00.0000
7655
7656
7657 \series bold
7658 -
7659 \begin_inset ERT
7660 status Collapsed
7661
7662 \layout Standard
7663
7664 \backslash
7665 /
7666 \end_inset
7667
7668 -use-stdout
7669 \begin_inset LatexCommand \index{-\/-use-stdout}
7670
7671 \end_inset
7672
7673
7674 \series default
7675  Send errors and warnings to stdout instead of stderr.
7676 \layout List
7677 \labelwidthstring 00.00.0000
7678
7679
7680 \series bold
7681 -Wa\SpecialChar ~
7682 asmOption[,asmOption]
7683 \series default
7684
7685 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
7686
7687 \end_inset
7688
7689 ...
7690  Pass the asmOption to the assembler
7691 \begin_inset LatexCommand \index{Options assembler}
7692
7693 \end_inset
7694
7695
7696 \begin_inset LatexCommand \index{Assembler options}
7697
7698 \end_inset
7699
7700 .
7701  See file sdcc/as/doc/asxhtm.html for assembler options.cd
7702 \layout List
7703 \labelwidthstring 00.00.0000
7704
7705
7706 \series bold
7707 -
7708 \begin_inset ERT
7709 status Collapsed
7710
7711 \layout Standard
7712
7713 \backslash
7714 /
7715 \end_inset
7716
7717 -std-sdcc89
7718 \begin_inset LatexCommand \index{-\/-std-sdcc89}
7719
7720 \end_inset
7721
7722
7723 \series default
7724  Generally follow the C89 standard, but allow SDCC features that conflict
7725  with the standard (default).
7726 \layout List
7727 \labelwidthstring 00.00.0000
7728
7729
7730 \series bold
7731 -
7732 \begin_inset ERT
7733 status Collapsed
7734
7735 \layout Standard
7736
7737 \backslash
7738 /
7739 \end_inset
7740
7741 -std-c89
7742 \begin_inset LatexCommand \index{-\/-std-c89}
7743
7744 \end_inset
7745
7746
7747 \series default
7748  Follow the C89 standard and disable SDCC features that conflict with the
7749  standard.
7750 \layout List
7751 \labelwidthstring 00.00.0000
7752
7753
7754 \series bold
7755 -
7756 \begin_inset ERT
7757 status Collapsed
7758
7759 \layout Standard
7760
7761 \backslash
7762 /
7763 \end_inset
7764
7765 -std-sdcc99
7766 \begin_inset LatexCommand \index{-\/-std-sdcc99}
7767
7768 \end_inset
7769
7770
7771 \series default
7772  Generally follow the C99 standard, but allow SDCC features that conflict
7773  with the standard (incomplete support).
7774 \layout List
7775 \labelwidthstring 00.00.0000
7776
7777
7778 \series bold
7779 -
7780 \begin_inset ERT
7781 status Collapsed
7782
7783 \layout Standard
7784
7785 \backslash
7786 /
7787 \end_inset
7788
7789 -std-c99
7790 \begin_inset LatexCommand \index{-\/-std-sdcc99}
7791
7792 \end_inset
7793
7794
7795 \series default
7796  Follow the C99 standard and disable SDCC features that conflict with the
7797  standard (incomplete support).
7798 \layout List
7799 \labelwidthstring 00.00.0000
7800
7801
7802 \series bold
7803 -
7804 \begin_inset ERT
7805 status Collapsed
7806
7807 \layout Standard
7808
7809 \backslash
7810 /
7811 \end_inset
7812
7813 -codeseg
7814 \series default
7815
7816 \begin_inset LatexCommand \index{-\/-codeseg <Value>}
7817
7818 \end_inset
7819
7820 \SpecialChar ~
7821 <Name> The name to be used for the code
7822 \begin_inset LatexCommand \index{code}
7823
7824 \end_inset
7825
7826  segment, default CSEG.
7827  This is useful if you need to tell the compiler to put the code in a special
7828  segment so you can later on tell the linker to put this segment in a special
7829  place in memory.
7830  Can be used for instance when using bank switching to put the code in a
7831  bank.
7832 \layout List
7833 \labelwidthstring 00.00.0000
7834
7835
7836 \series bold
7837 -
7838 \begin_inset ERT
7839 status Collapsed
7840
7841 \layout Standard
7842
7843 \backslash
7844 /
7845 \end_inset
7846
7847 -constseg
7848 \series default
7849
7850 \begin_inset LatexCommand \index{-\/-constseg <Value>}
7851
7852 \end_inset
7853
7854 \SpecialChar ~
7855 <Name> The name to be used for the const
7856 \begin_inset LatexCommand \index{code}
7857
7858 \end_inset
7859
7860  segment, default CONST.
7861  This is useful if you need to tell the compiler to put the const data in
7862  a special segment so you can later on tell the linker to put this segment
7863  in a special place in memory.
7864  Can be used for instance when using bank switching to put the const data
7865  in a bank.
7866 \layout List
7867 \labelwidthstring 00.00.0000
7868
7869
7870 \series bold
7871 more-pedantic
7872 \series default
7873  Actually this is
7874 \series bold
7875 \emph on
7876 not
7877 \series default
7878 \emph default
7879  a SDCC compiler option but if you want
7880 \emph on
7881 more
7882 \emph default
7883  warnings you can use a separate tool dedicated to syntax checking like
7884  splint
7885 \begin_inset LatexCommand \label{lyx:more-pedantic-SPLINT}
7886
7887 \end_inset
7888
7889
7890 \begin_inset LatexCommand \index{lint (syntax checking tool)}
7891
7892 \end_inset
7893
7894
7895 \begin_inset LatexCommand \url{http://www.splint.org}
7896
7897 \end_inset
7898
7899 .
7900  To make your source files parseable by splint you will have to include
7901
7902 \family sans
7903 lint.h
7904 \family default
7905
7906 \begin_inset LatexCommand \index{splint (syntax checking tool)}
7907
7908 \end_inset
7909
7910  in your source file and add brackets around extended keywords (like
7911 \family sans
7912
7913 \begin_inset Quotes sld
7914 \end_inset
7915
7916 __at\SpecialChar ~
7917
7918 \series bold
7919 (
7920 \series default
7921 0xab
7922 \series bold
7923 )
7924 \series default
7925
7926 \begin_inset Quotes srd
7927 \end_inset
7928
7929
7930 \family default
7931  and
7932 \family sans
7933
7934 \begin_inset Quotes sld
7935 \end_inset
7936
7937 __interrupt\SpecialChar ~
7938 (2)
7939 \begin_inset Quotes srd
7940 \end_inset
7941
7942
7943 \family default
7944 ).
7945
7946 \newline
7947 Splint has an excellent on line manual at
7948 \begin_inset LatexCommand \url{http://www.splint.org/manual/}
7949
7950 \end_inset
7951
7952  and it's capabilities go beyond pure syntax checking.
7953  You'll need to tell splint the location of SDCC's include files so a typical
7954  command line could look like this:
7955 \newline
7956
7957 \family sans
7958 splint\SpecialChar ~
7959 -I\SpecialChar ~
7960 /usr/local/share/sdcc/include/mcs51/\SpecialChar ~
7961 \SpecialChar ~
7962 myprogram.c
7963 \layout Subsection
7964
7965 Intermediate Dump Options
7966 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
7967
7968 \end_inset
7969
7970
7971 \begin_inset LatexCommand \index{Options intermediate dump}
7972
7973 \end_inset
7974
7975
7976 \begin_inset LatexCommand \index{Intermediate dump options}
7977
7978 \end_inset
7979
7980
7981 \layout Standard
7982
7983 The following options are provided for the purpose of retargetting and debugging
7984  the compiler.
7985  They provide a means to dump the intermediate code (iCode
7986 \begin_inset LatexCommand \index{iCode}
7987
7988 \end_inset
7989
7990 ) generated by the compiler in human readable form at various stages of
7991  the compilation process.
7992  More on iCodes see chapter
7993 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
7994
7995 \end_inset
7996
7997
7998 \begin_inset Quotes srd
7999 \end_inset
8000
8001 The anatomy of the compiler
8002 \begin_inset Quotes srd
8003 \end_inset
8004
8005 .
8006 \layout List
8007 \labelwidthstring 00.00.0000
8008
8009
8010 \series bold
8011 -
8012 \begin_inset ERT
8013 status Collapsed
8014
8015 \layout Standard
8016
8017 \backslash
8018 /
8019 \end_inset
8020
8021 -dumpraw
8022 \begin_inset LatexCommand \index{-\/-dumpraw}
8023
8024 \end_inset
8025
8026
8027 \series default
8028  This option will cause the compiler to dump the intermediate code into
8029  a file of named
8030 \emph on
8031 <source filename>.dumpraw
8032 \emph default
8033  just after the intermediate code has been generated for a function, i.e.
8034  before any optimizations are done.
8035  The basic blocks
8036 \begin_inset LatexCommand \index{Basic blocks}
8037
8038 \end_inset
8039
8040  at this stage ordered in the depth first number, so they may not be in
8041  sequence of execution.
8042 \layout List
8043 \labelwidthstring 00.00.0000
8044
8045
8046 \series bold
8047 -
8048 \begin_inset ERT
8049 status Collapsed
8050
8051 \layout Standard
8052
8053 \backslash
8054 /
8055 \end_inset
8056
8057 -dumpgcse
8058 \begin_inset LatexCommand \index{-\/-dumpgcse}
8059
8060 \end_inset
8061
8062
8063 \series default
8064  Will create a dump of iCode's, after global subexpression elimination
8065 \begin_inset LatexCommand \index{Global subexpression elimination}
8066
8067 \end_inset
8068
8069 , into a file named
8070 \emph on
8071 <source filename>.dumpgcse.
8072 \layout List
8073 \labelwidthstring 00.00.0000
8074
8075
8076 \series bold
8077 -
8078 \begin_inset ERT
8079 status Collapsed
8080
8081 \layout Standard
8082
8083 \backslash
8084 /
8085 \end_inset
8086
8087 -dumpdeadcode
8088 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
8089
8090 \end_inset
8091
8092
8093 \series default
8094  Will create a dump of iCode's, after deadcode elimination
8095 \begin_inset LatexCommand \index{Dead-code elimination}
8096
8097 \end_inset
8098
8099 , into a file named
8100 \emph on
8101 <source filename>.dumpdeadcode.
8102 \layout List
8103 \labelwidthstring 00.00.0000
8104
8105
8106 \series bold
8107 -
8108 \begin_inset ERT
8109 status Collapsed
8110
8111 \layout Standard
8112
8113 \backslash
8114 /
8115 \end_inset
8116
8117 -dumploop
8118 \begin_inset LatexCommand \index{-\/-dumploop}
8119
8120 \end_inset
8121
8122
8123 \series default
8124 \size large
8125
8126 \size default
8127 Will create a dump of iCode's, after loop optimizations
8128 \begin_inset LatexCommand \index{Loop optimization}
8129
8130 \end_inset
8131
8132 , into a file named
8133 \emph on
8134 <source filename>.dumploop.
8135 \layout List
8136 \labelwidthstring 00.00.0000
8137
8138
8139 \series bold
8140 -
8141 \begin_inset ERT
8142 status Collapsed
8143
8144 \layout Standard
8145
8146 \backslash
8147 /
8148 \end_inset
8149
8150 -dumprange
8151 \begin_inset LatexCommand \index{-\/-dumprange}
8152
8153 \end_inset
8154
8155
8156 \series default
8157 \size large
8158
8159 \size default
8160 Will create a dump of iCode's, after live range analysis
8161 \begin_inset LatexCommand \index{Live range analysis}
8162
8163 \end_inset
8164
8165 , into a file named
8166 \emph on
8167 <source filename>.dumprange.
8168 \layout List
8169 \labelwidthstring 00.00.0000
8170
8171
8172 \series bold
8173 -
8174 \begin_inset ERT
8175 status Collapsed
8176
8177 \layout Standard
8178
8179 \backslash
8180 /
8181 \end_inset
8182
8183 -dumlrange
8184 \begin_inset LatexCommand \index{-\/-dumlrange}
8185
8186 \end_inset
8187
8188
8189 \series default
8190  Will dump the life ranges
8191 \begin_inset LatexCommand \index{Live range analysis}
8192
8193 \end_inset
8194
8195  for all symbols.
8196 \layout List
8197 \labelwidthstring 00.00.0000
8198
8199
8200 \series bold
8201 -
8202 \begin_inset ERT
8203 status Collapsed
8204
8205 \layout Standard
8206
8207 \backslash
8208 /
8209 \end_inset
8210
8211 -dumpregassign
8212 \begin_inset LatexCommand \index{-\/-dumpregassign}
8213
8214 \end_inset
8215
8216
8217 \bar under
8218
8219 \series default
8220 \bar default
8221 Will create a dump of iCode's, after register assignment
8222 \begin_inset LatexCommand \index{Register assignment}
8223
8224 \end_inset
8225
8226 , into a file named
8227 \emph on
8228 <source filename>.dumprassgn.
8229 \layout List
8230 \labelwidthstring 00.00.0000
8231
8232
8233 \series bold
8234 -
8235 \begin_inset ERT
8236 status Collapsed
8237
8238 \layout Standard
8239
8240 \backslash
8241 /
8242 \end_inset
8243
8244 -dumplrange
8245 \begin_inset LatexCommand \index{-\/-dumplrange}
8246
8247 \end_inset
8248
8249
8250 \series default
8251  Will create a dump of the live ranges of iTemp's
8252 \layout List
8253 \labelwidthstring 00.00.0000
8254
8255
8256 \series bold
8257 -
8258 \begin_inset ERT
8259 status Collapsed
8260
8261 \layout Standard
8262
8263 \backslash
8264 /
8265 \end_inset
8266
8267 -dumpall
8268 \begin_inset LatexCommand \index{-\/-dumpall}
8269
8270 \end_inset
8271
8272
8273 \size large
8274 \bar under
8275
8276 \series default
8277 \size default
8278 \bar default
8279 Will cause all the above mentioned dumps to be created.
8280 \layout Subsection
8281
8282 Redirecting output on Windows Shells
8283 \layout Standard
8284
8285 By default SDCC writes it's error messages to
8286 \begin_inset Quotes sld
8287 \end_inset
8288
8289 standard error
8290 \begin_inset Quotes srd
8291 \end_inset
8292
8293 .
8294  To force all messages to
8295 \begin_inset Quotes sld
8296 \end_inset
8297
8298 standard output
8299 \begin_inset Quotes srd
8300 \end_inset
8301
8302  use
8303 \series bold
8304 -
8305 \series default
8306 \emph on
8307
8308 \begin_inset ERT
8309 status Collapsed
8310
8311 \layout Standard
8312
8313 \backslash
8314 /
8315 \end_inset
8316
8317
8318 \series bold
8319 \emph default
8320 -
8321 \series default
8322 use-stdout
8323 \begin_inset LatexCommand \index{-\/-use-stdout}
8324
8325 \end_inset
8326
8327 .
8328  Additionally, if you happen to have visual studio installed in your windows
8329  machine, you can use it to compile your sources using a custom build and
8330  the SDCC -
8331 \emph on
8332
8333 \begin_inset ERT
8334 status Collapsed
8335
8336 \layout Standard
8337
8338 \backslash
8339 /
8340 \end_inset
8341
8342
8343 \emph default
8344 -vc
8345 \begin_inset LatexCommand \index{-\/-vc}
8346
8347 \end_inset
8348
8349  option.
8350  Something like this should work:
8351 \newline
8352
8353 \newline
8354
8355 \series bold
8356 c:
8357 \backslash
8358 sdcc
8359 \backslash
8360 bin
8361 \backslash
8362 sdcc.exe -
8363 \series default
8364 \emph on
8365
8366 \begin_inset ERT
8367 status Collapsed
8368
8369 \layout Standard
8370
8371 \backslash
8372 /
8373 \end_inset
8374
8375
8376 \series bold
8377 \emph default
8378 -vc -
8379 \series default
8380 \emph on
8381
8382 \begin_inset ERT
8383 status Collapsed
8384
8385 \layout Standard
8386
8387 \backslash
8388 /
8389 \end_inset
8390
8391
8392 \series bold
8393 \emph default
8394 -model-large -c $(InputPath)
8395 \layout Section
8396
8397 Environment variables
8398 \begin_inset LatexCommand \index{Environment variables}
8399
8400 \end_inset
8401
8402
8403 \layout Standard
8404
8405 SDCC recognizes the following environment variables:
8406 \layout List
8407 \labelwidthstring 00.00.0000
8408
8409
8410 \series bold
8411 SDCC_LEAVE_SIGNALS
8412 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
8413
8414 \end_inset
8415
8416
8417 \series default
8418  SDCC installs a signal handler
8419 \begin_inset LatexCommand \index{signal handler}
8420
8421 \end_inset
8422
8423  to be able to delete temporary files after an user break (^C) or an exception.
8424  If this environment variable is set, SDCC won't install the signal handler
8425  in order to be able to debug SDCC.
8426 \layout List
8427 \labelwidthstring 00.00.0000
8428
8429
8430 \series bold
8431 TMP,\SpecialChar ~
8432 TEMP,\SpecialChar ~
8433 TMPDIR
8434 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
8435
8436 \end_inset
8437
8438
8439 \series default
8440  Path, where temporary files will be created.
8441  The order of the variables is the search order.
8442  In a standard *nix environment these variables are not set, and there's
8443  no need to set them.
8444  On Windows it's recommended to set one of them.
8445 \layout List
8446 \labelwidthstring 00.00.0000
8447
8448
8449 \series bold
8450 SDCC_HOME
8451 \begin_inset LatexCommand \index{SDCC\_HOME}
8452
8453 \end_inset
8454
8455
8456 \series default
8457  Path, see section
8458 \begin_inset LatexCommand \ref{sub:Install-paths}
8459
8460 \end_inset
8461
8462 \SpecialChar ~
8463
8464 \begin_inset Quotes sld
8465 \end_inset
8466
8467  Install Paths
8468 \begin_inset Quotes srd
8469 \end_inset
8470
8471 .
8472 \layout List
8473 \labelwidthstring 00.00.0000
8474
8475
8476 \series bold
8477 SDCC_INCLUDE
8478 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
8479
8480 \end_inset
8481
8482
8483 \series default
8484  Path, see section
8485 \begin_inset LatexCommand \ref{sub:Search-Paths}
8486
8487 \end_inset
8488
8489 \SpecialChar ~
8490
8491 \begin_inset Quotes sld
8492 \end_inset
8493
8494 Search 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_LIB
8505 \begin_inset LatexCommand \index{SDCC\_LIB}
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 Standard
8527
8528 There are some more environment variables recognized by SDCC, but these
8529  are solely used for debugging purposes.
8530  They can change or disappear very quickly, and will never be documented.
8531 \layout Section
8532
8533 Storage Class Language Extensions
8534 \layout Subsection
8535
8536 MCS51/DS390 Storage Class
8537 \begin_inset LatexCommand \index{Storage class}
8538
8539 \end_inset
8540
8541  Language Extensions
8542 \layout Standard
8543
8544 In addition to the ANSI storage classes SDCC allows the following MCS51
8545  specific storage classes:
8546 \layout Subsubsection
8547
8548 data
8549 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
8550
8551 \end_inset
8552
8553
8554 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
8555
8556 \end_inset
8557
8558  / near
8559 \begin_inset LatexCommand \index{near (storage class)}
8560
8561 \end_inset
8562
8563
8564 \begin_inset LatexCommand \index{\_\_near (storage class)}
8565
8566 \end_inset
8567
8568
8569 \layout Standard
8570
8571 This is the
8572 \series bold
8573 default
8574 \series default
8575  storage class for the Small Memory model (
8576 \emph on
8577 data
8578 \emph default
8579  and
8580 \emph on
8581 near
8582 \emph default
8583  can be used synonymously).
8584  Variables declared with this storage class will be allocated in the directly
8585  addressable portion of the internal RAM of a 8051, e.g.:
8586 \layout Verse
8587
8588
8589 \family typewriter
8590 data unsigned char test_data;
8591 \layout Standard
8592
8593 Writing 0x01 to this variable generates the assembly code:
8594 \layout Verse
8595
8596
8597 \family typewriter
8598 75*00 01\SpecialChar ~
8599 \SpecialChar ~
8600 \SpecialChar ~
8601 mov\SpecialChar ~
8602 \SpecialChar ~
8603 _test_data,#0x01
8604 \layout Subsubsection
8605
8606 xdata
8607 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8608
8609 \end_inset
8610
8611
8612 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
8613
8614 \end_inset
8615
8616  / far
8617 \begin_inset LatexCommand \index{far (storage class)}
8618
8619 \end_inset
8620
8621
8622 \begin_inset LatexCommand \index{\_\_far (storage class)}
8623
8624 \end_inset
8625
8626
8627 \layout Standard
8628
8629 Variables declared with this storage class will be placed in the external
8630  RAM.
8631  This is the
8632 \series bold
8633 default
8634 \series default
8635  storage class for the Large Memory model, e.g.:
8636 \layout Verse
8637
8638
8639 \family typewriter
8640 xdata unsigned char test_xdata;
8641 \layout Standard
8642
8643 Writing 0x01 to this variable generates the assembly code:
8644 \layout Verse
8645
8646
8647 \family typewriter
8648 90s00r00\SpecialChar ~
8649 \SpecialChar ~
8650 \SpecialChar ~
8651 mov\SpecialChar ~
8652 \SpecialChar ~
8653 dptr,#_test_xdata
8654 \newline
8655 74\SpecialChar ~
8656 01\SpecialChar ~
8657 \SpecialChar ~
8658 \SpecialChar ~
8659 \SpecialChar ~
8660 \SpecialChar ~
8661 \SpecialChar ~
8662 mov\SpecialChar ~
8663 \SpecialChar ~
8664 a,#0x01
8665 \newline
8666 F0\SpecialChar ~
8667 \SpecialChar ~
8668 \SpecialChar ~
8669 \SpecialChar ~
8670 \SpecialChar ~
8671 \SpecialChar ~
8672 \SpecialChar ~
8673 \SpecialChar ~
8674 \SpecialChar ~
8675 movx\SpecialChar ~
8676 @dptr,a
8677 \layout Subsubsection
8678
8679 idata
8680 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
8681
8682 \end_inset
8683
8684
8685 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
8686
8687 \end_inset
8688
8689
8690 \layout Standard
8691
8692 Variables declared with this storage class will be allocated into the indirectly
8693  addressable portion of the internal ram of a 8051, e.g.:
8694 \layout Verse
8695
8696
8697 \family typewriter
8698 idata unsigned char test_idata;
8699 \layout Standard
8700
8701 Writing 0x01 to this variable generates the assembly code:
8702 \layout Verse
8703
8704
8705 \family typewriter
8706 78r00\SpecialChar ~
8707 \SpecialChar ~
8708 \SpecialChar ~
8709 \SpecialChar ~
8710 \SpecialChar ~
8711 \SpecialChar ~
8712 \SpecialChar ~
8713 mov\SpecialChar ~
8714 \SpecialChar ~
8715 r0,#_test_idata
8716 \newline
8717 76\SpecialChar ~
8718 01\SpecialChar ~
8719 \SpecialChar ~
8720 \SpecialChar ~
8721 \SpecialChar ~
8722 \SpecialChar ~
8723 \SpecialChar ~
8724 \SpecialChar ~
8725 mov\SpecialChar ~
8726 \SpecialChar ~
8727 @r0,#0x01
8728 \layout Standard
8729
8730 Please note, the first 128 byte of idata physically access the same RAM
8731  as the data memory.
8732  The original 8051 had 128 byte idata memory, nowadays most devices have
8733  256 byte idata memory.
8734  The stack
8735 \begin_inset LatexCommand \index{stack}
8736
8737 \end_inset
8738
8739  is located in idata memory.
8740 \layout Subsubsection
8741
8742 pdata
8743 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
8744
8745 \end_inset
8746
8747
8748 \begin_inset LatexCommand \index{\_\_pdata (mcs51, ds390 storage class)}
8749
8750 \end_inset
8751
8752
8753 \layout Standard
8754
8755 Paged xdata access is just as straightforward as using the other addressing
8756  modes of a 8051.
8757  It is typically located at the start of xdata and has a maximum size of
8758  256 bytes.
8759  The following example writes 0x01 to the pdata variable.
8760  Please note, pdata access physically accesses xdata memory.
8761  The high byte of the address is determined by port P2
8762 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
8763
8764 \end_inset
8765
8766 (or in case of some 8051 variants by a separate Special Function Register,
8767  see section
8768 \begin_inset LatexCommand \ref{sub:MCS51-variants}
8769
8770 \end_inset
8771
8772 ).
8773 \layout Verse
8774
8775
8776 \family typewriter
8777 pdata unsigned char test_pdata;
8778 \layout Standard
8779
8780 Writing 0x01 to this variable generates the assembly code:
8781 \layout Verse
8782
8783
8784 \family typewriter
8785 78r00\SpecialChar ~
8786 \SpecialChar ~
8787 \SpecialChar ~
8788 \SpecialChar ~
8789 \SpecialChar ~
8790 \SpecialChar ~
8791 mov r0,#_test_pdata
8792 \newline
8793 74 01\SpecialChar ~
8794 \SpecialChar ~
8795 \SpecialChar ~
8796 \SpecialChar ~
8797 \SpecialChar ~
8798 \SpecialChar ~
8799 mov a,#0x01
8800 \newline
8801 F2\SpecialChar ~
8802 \SpecialChar ~
8803 \SpecialChar ~
8804 \SpecialChar ~
8805 \SpecialChar ~
8806 \SpecialChar ~
8807 \SpecialChar ~
8808 \SpecialChar ~
8809 \SpecialChar ~
8810 movx @r0,a
8811 \layout Standard
8812
8813 If the -
8814 \begin_inset ERT
8815 status Collapsed
8816
8817 \layout Standard
8818
8819 \backslash
8820 /
8821 \end_inset
8822
8823 -xstack
8824 \begin_inset LatexCommand \index{-\/-xstack}
8825
8826 \end_inset
8827
8828  option is used the pdata memory area is followed by the xstack memory area
8829  and the sum of their sizes is limited to 256 bytes.
8830 \layout Subsubsection
8831
8832 code
8833 \begin_inset LatexCommand \index{code}
8834
8835 \end_inset
8836
8837
8838 \begin_inset LatexCommand \index{\_\_code}
8839
8840 \end_inset
8841
8842
8843 \layout Standard
8844
8845 'Variables' declared with this storage class will be placed in the code
8846  memory:
8847 \layout Verse
8848
8849
8850 \family typewriter
8851 code unsigned char test_code;
8852 \layout Standard
8853
8854 Read access to this variable generates the assembly code:
8855 \layout Verse
8856
8857
8858 \family typewriter
8859 90s00r6F\SpecialChar ~
8860 \SpecialChar ~
8861 \SpecialChar ~
8862 mov dptr,#_test_code
8863 \newline
8864 E4\SpecialChar ~
8865 \SpecialChar ~
8866 \SpecialChar ~
8867 \SpecialChar ~
8868 \SpecialChar ~
8869 \SpecialChar ~
8870 \SpecialChar ~
8871 \SpecialChar ~
8872 \SpecialChar ~
8873 clr a
8874 \newline
8875 93\SpecialChar ~
8876 \SpecialChar ~
8877 \SpecialChar ~
8878 \SpecialChar ~
8879 \SpecialChar ~
8880 \SpecialChar ~
8881 \SpecialChar ~
8882 \SpecialChar ~
8883 \SpecialChar ~
8884 movc a,@a+dptr
8885 \layout Standard
8886
8887
8888 \family typewriter
8889 char
8890 \family default
8891  indexed arrays of characters in code memory can be accessed efficiently:
8892 \layout Verse
8893
8894
8895 \family typewriter
8896 code char test_array[] = {'c','h','e','a','p'};
8897 \layout Standard
8898
8899 Read access to this array using an 8-bit unsigned index generates the assembly
8900  code:
8901 \layout Verse
8902
8903
8904 \family typewriter
8905 E5*00\SpecialChar ~
8906 \SpecialChar ~
8907 \SpecialChar ~
8908 \SpecialChar ~
8909 \SpecialChar ~
8910 \SpecialChar ~
8911 mov a,_index
8912 \layout Verse
8913
8914
8915 \family typewriter
8916 90s00r41\SpecialChar ~
8917 \SpecialChar ~
8918 \SpecialChar ~
8919 mov dptr,#_test_array
8920 \layout Verse
8921
8922
8923 \family typewriter
8924 93\SpecialChar ~
8925 \SpecialChar ~
8926 \SpecialChar ~
8927 \SpecialChar ~
8928 \SpecialChar ~
8929 \SpecialChar ~
8930 \SpecialChar ~
8931 \SpecialChar ~
8932 \SpecialChar ~
8933 movc a,@a+dptr
8934 \layout Subsubsection
8935
8936 bit
8937 \begin_inset LatexCommand \index{bit}
8938
8939 \end_inset
8940
8941
8942 \begin_inset LatexCommand \index{\_\_bit}
8943
8944 \end_inset
8945
8946
8947 \layout Standard
8948
8949 This is a data-type and a storage class specifier.
8950  When a variable is declared as a bit, it is allocated into the bit addressable
8951  memory of 8051, e.g.:
8952 \layout Verse
8953
8954
8955 \family typewriter
8956 bit test_bit;
8957 \layout Standard
8958
8959 Writing 1 to this variable generates the assembly code:
8960 \layout Verse
8961
8962
8963 \family typewriter
8964 D2*00\SpecialChar ~
8965 \SpecialChar ~
8966 \SpecialChar ~
8967 \SpecialChar ~
8968 \SpecialChar ~
8969 \SpecialChar ~
8970 \SpecialChar ~
8971 setb\SpecialChar ~
8972 _test_bit
8973 \layout Standard
8974
8975 The bit addressable memory consists of 128 bits which are located from 0x20
8976  to 0x2f in data memory.
8977
8978 \newline
8979 Apart from this 8051 specific storage class most architectures support ANSI-C
8980  bitfields
8981 \begin_inset LatexCommand \index{bitfields}
8982
8983 \end_inset
8984
8985
8986 \begin_inset Foot
8987 collapsed false
8988
8989 \layout Standard
8990
8991 Not really meant as examples, but nevertheless showing what bitfields are
8992  about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
8993 \end_inset
8994
8995 .
8996  In accordance with ISO/IEC 9899 bits and bitfields without an explicit
8997  signed modifier are implemented as unsigned.
8998 \layout Subsubsection
8999
9000 sfr
9001 \begin_inset LatexCommand \index{sfr}
9002
9003 \end_inset
9004
9005
9006 \begin_inset LatexCommand \index{\_\_sfr}
9007
9008 \end_inset
9009
9010  / sfr16
9011 \begin_inset LatexCommand \index{sfr16}
9012
9013 \end_inset
9014
9015
9016 \begin_inset LatexCommand \index{\_\_sfr16}
9017
9018 \end_inset
9019
9020  / sfr32
9021 \begin_inset LatexCommand \index{sfr32}
9022
9023 \end_inset
9024
9025
9026 \begin_inset LatexCommand \index{\_\_sfr32}
9027
9028 \end_inset
9029
9030  / sbit
9031 \begin_inset LatexCommand \index{\_\_sbit}
9032
9033 \end_inset
9034
9035
9036 \layout Standard
9037
9038 Like the bit keyword,
9039 \emph on
9040 sfr / sfr16 / sfr32 / sbit
9041 \emph default
9042 signify both a data-type and storage class, they are used to describe the
9043
9044 \emph on
9045 s
9046 \emph default
9047 pecial
9048 \emph on
9049 f
9050 \emph default
9051 unction
9052 \emph on
9053 r
9054 \emph default
9055 egisters and
9056 \emph on
9057 s
9058 \emph default
9059 pecial
9060 \emph on
9061 bit
9062 \emph default
9063  variables of a 8051, eg:
9064 \layout Verse
9065
9066
9067 \family typewriter
9068 sfr at
9069 \begin_inset LatexCommand \index{at}
9070
9071 \end_inset
9072
9073
9074 \begin_inset LatexCommand \index{\_\_at}
9075
9076 \end_inset
9077
9078  0x80 P0;\SpecialChar ~
9079  /* special function register P0 at location 0x80 */
9080 \newline
9081 /* 16 bit special function register combination for timer 0 */
9082 \newline
9083 /* with the high byte at location 0x8C and the low byte at location 0x8A
9084  */
9085 \newline
9086 sfr16 at
9087 \begin_inset LatexCommand \index{at}
9088
9089 \end_inset
9090
9091
9092 \begin_inset LatexCommand \index{\_\_at}
9093
9094 \end_inset
9095
9096  0x8C8A TMR0;
9097 \newline
9098 sbit at 0xd7 CY; /* CY (Carry Flag
9099 \begin_inset LatexCommand \index{Flags}
9100
9101 \end_inset
9102
9103
9104 \begin_inset LatexCommand \index{Carry flag}
9105
9106 \end_inset
9107
9108 ) */
9109 \layout Standard
9110
9111 Special function registers which are located on an address dividable by
9112  8 are bit-addressable, an
9113 \emph on
9114  sbit
9115 \emph default
9116  addresses a specific bit within these sfr.
9117 \newline
9118 16 Bit and 32 bit special function register combinations which require a
9119  certain access order are better not declared using
9120 \emph on
9121 sfr16
9122 \emph default
9123  or
9124 \emph on
9125 sfr32.
9126
9127 \emph default
9128  Allthough SDCC usually accesses them Least Significant Byte (LSB) first,
9129  this is not guaranteed.
9130 \layout Subsubsection
9131
9132 Pointers
9133 \begin_inset LatexCommand \index{Pointer}
9134
9135 \end_inset
9136
9137  to MCS51/DS390 specific memory spaces
9138 \layout Standard
9139
9140 SDCC allows (via language extensions) pointers to explicitly point to any
9141  of the memory spaces
9142 \begin_inset LatexCommand \index{Memory model}
9143
9144 \end_inset
9145
9146  of the 8051.
9147  In addition to the explicit pointers, the compiler uses (by default) generic
9148  pointers which can be used to point to any of the memory spaces.
9149 \newline
9150
9151 \newline
9152 Pointer declaration examples:
9153 \layout Verse
9154
9155
9156 \family typewriter
9157 /* pointer physically in internal ram pointing to object in external ram
9158  */
9159 \newline
9160 xdata unsigned char * data p;
9161 \newline
9162
9163 \newline
9164 /* pointer physically in external ram pointing to object in internal ram
9165  */
9166 \newline
9167 data unsigned char * xdata p;
9168 \newline
9169
9170 \newline
9171 /* pointer physically in code rom pointing to data in xdata space */
9172 \newline
9173 xdata unsigned char * code p;
9174 \newline
9175
9176 \newline
9177 /* pointer physically in code space pointing to data in code space */
9178 \newline
9179 code unsigned char * code p;
9180 \newline
9181
9182 \newline
9183 /* the following is a generic pointer physically located in xdata space
9184  */
9185 \newline
9186 char * xdata p;
9187 \newline
9188
9189 \newline
9190 /* the following is a function pointer physically located in data space
9191  */
9192 \newline
9193 char (* data fp)(void);
9194 \layout Standard
9195
9196 Well you get the idea.
9197
9198 \newline
9199
9200 \newline
9201 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
9202 \emph on
9203 generic
9204 \emph default
9205  pointers.
9206
9207 \size small
9208
9209 \newline
9210
9211 \newline
9212
9213 \size default
9214 The highest order byte of the
9215 \emph on
9216 generic
9217 \emph default
9218  pointers contains the data space information.
9219  Assembler support routines are called whenever data is stored or retrieved
9220  using
9221 \emph on
9222 generic
9223 \emph default
9224  pointers.
9225  These are useful for developing reusable library
9226 \begin_inset LatexCommand \index{Libraries}
9227
9228 \end_inset
9229
9230  routines.
9231  Explicitly specifying the pointer type will generate the most efficient
9232  code.
9233 \layout Subsubsection
9234
9235 Notes on MCS51 memory
9236 \begin_inset LatexCommand \index{MCS51 memory}
9237
9238 \end_inset
9239
9240  layout
9241 \layout Standard
9242
9243 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
9244  RAM memory which is structured as follows:
9245 \newline
9246
9247 \newline
9248 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
9249
9250 \newline
9251 - Bytes 20-2F - 16 bytes to hold 128 bit
9252 \begin_inset LatexCommand \index{bit}
9253
9254 \end_inset
9255
9256  variables and,
9257 \newline
9258 - Bytes 30-7F - 80 bytes for general purpose use.
9259 \newline
9260
9261 \layout Standard
9262
9263 Additionally some members of the MCS51 family may have up to 128 bytes of
9264  additional, indirectly addressable, internal RAM memory (
9265 \emph on
9266 idata
9267 \emph default
9268
9269 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
9270
9271 \end_inset
9272
9273
9274 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
9275
9276 \end_inset
9277
9278 ).
9279  Furthermore, some chips may have some built in external memory (
9280 \emph on
9281 xdata
9282 \emph default
9283
9284 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9285
9286 \end_inset
9287
9288
9289 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9290
9291 \end_inset
9292
9293 ) which should not be confused with the internal, directly addressable RAM
9294  memory (
9295 \emph on
9296 data
9297 \emph default
9298
9299 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
9300
9301 \end_inset
9302
9303
9304 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
9305
9306 \end_inset
9307
9308 ).
9309  Sometimes this built in
9310 \emph on
9311 xdata
9312 \emph default
9313  memory has to be activated before using it (you can probably find this
9314  information on the datasheet of the microcontroller your are using, see
9315  also section
9316 \begin_inset LatexCommand \ref{sub:Startup-Code}
9317
9318 \end_inset
9319
9320 \SpecialChar ~
9321 Startup-Code).
9322 \layout Standard
9323
9324 Normally SDCC will only use the first bank
9325 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
9326
9327 \end_inset
9328
9329  of registers (register bank 0), but it is possible to specify that other
9330  banks of registers (keyword
9331 \emph on
9332 using
9333 \emph default
9334
9335 \emph on
9336
9337 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
9338
9339 \end_inset
9340
9341
9342 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
9343
9344 \end_inset
9345
9346
9347 \emph default
9348 ) should be used in interrupt
9349 \begin_inset LatexCommand \index{interrupt}
9350
9351 \end_inset
9352
9353
9354 \begin_inset LatexCommand \index{\_\_interrupt}
9355
9356 \end_inset
9357
9358  routines.
9359  By default, the compiler will place the stack after the last byte of allocated
9360  memory for variables.
9361  For example, if the first 2 banks of registers are used, and only four
9362  bytes are used for
9363 \emph on
9364 data
9365 \emph default
9366  variables, it will position the base of the internal stack at address 20
9367  (0x14).
9368  This implies that as the stack
9369 \begin_inset LatexCommand \index{stack}
9370
9371 \end_inset
9372
9373  grows, it will use up the remaining register banks, and the 16 bytes used
9374  by the 128 bit variables, and 80 bytes for general purpose use.
9375  If any bit variables are used, the data variables will be placed in unused
9376  register banks and after the byte holding the last bit variable.
9377  For example, if register banks 0 and 1 are used, and there are 9 bit variables
9378  (two bytes used),
9379 \emph on
9380 data
9381 \emph default
9382  variables will be placed starting from address 0x10 to 0x20 and continue
9383  at address 0x22.
9384  You can also use -
9385 \begin_inset ERT
9386 status Collapsed
9387
9388 \layout Standard
9389
9390 \backslash
9391 /
9392 \end_inset
9393
9394 -data-loc
9395 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
9396
9397 \end_inset
9398
9399  to specify the start address of the
9400 \emph on
9401 data
9402 \emph default
9403  and -
9404 \begin_inset ERT
9405 status Collapsed
9406
9407 \layout Standard
9408
9409 \backslash
9410 /
9411 \end_inset
9412
9413 -iram-size
9414 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
9415
9416 \end_inset
9417
9418  to specify the size of the total internal RAM (
9419 \emph on
9420 data
9421 \emph default
9422 +
9423 \emph on
9424 idata
9425 \emph default
9426 ).
9427
9428 \layout Standard
9429
9430 By default the 8051 linker will place the stack after the last byte of (i)data
9431  variables.
9432  Option -
9433 \begin_inset ERT
9434 status Collapsed
9435
9436 \layout Standard
9437
9438 \backslash
9439 /
9440 \end_inset
9441
9442 -stack-loc
9443 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
9444
9445 \end_inset
9446
9447  allows you to specify the start of the stack, i.e.
9448  you could start it after any data in the general purpose area.
9449  If your microcontroller has additional indirectly addressable internal
9450  RAM (
9451 \emph on
9452 idata
9453 \emph default
9454 ) you can place the stack on it.
9455  You may also need to use -
9456 \begin_inset ERT
9457 status Collapsed
9458
9459 \layout Standard
9460
9461 \backslash
9462 /
9463 \end_inset
9464
9465 -xdata-loc
9466 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
9467
9468 \end_inset
9469
9470  to set the start address of the external RAM (
9471 \emph on
9472 xdata
9473 \emph default
9474 ) and -
9475 \begin_inset ERT
9476 status Collapsed
9477
9478 \layout Standard
9479
9480 \backslash
9481 /
9482 \end_inset
9483
9484 -xram-size
9485 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
9486
9487 \end_inset
9488
9489  to specify its size.
9490  Same goes for the code memory, using -
9491 \begin_inset ERT
9492 status Collapsed
9493
9494 \layout Standard
9495
9496 \backslash
9497 /
9498 \end_inset
9499
9500 -code-loc
9501 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
9502
9503 \end_inset
9504
9505  and -
9506 \begin_inset ERT
9507 status Collapsed
9508
9509 \layout Standard
9510
9511 \backslash
9512 /
9513 \end_inset
9514
9515 -code-size
9516 \begin_inset LatexCommand \index{-\/-code-size <Value>}
9517
9518 \end_inset
9519
9520 .
9521  If in doubt, don't specify any options and see if the resulting memory
9522  layout is appropriate, then you can adjust it.
9523 \layout Standard
9524
9525 The linker generates two files with memory allocation information.
9526  The first, with extension .map
9527 \begin_inset LatexCommand \index{<file>.map}
9528
9529 \end_inset
9530
9531  shows all the variables and segments.
9532  The second with extension .mem
9533 \begin_inset LatexCommand \index{<file>.mem}
9534
9535 \end_inset
9536
9537  shows the final memory layout.
9538  The linker will complain either if memory segments overlap, there is not
9539  enough memory, or there is not enough space for stack.
9540  If you get any linking warnings and/or errors related to stack or segments
9541  allocation, take a look at either the .map or .mem files to find out what
9542  the problem is.
9543  The .mem file may even suggest a solution to the problem.
9544 \layout Subsection
9545
9546 Z80/Z180 Storage Class
9547 \begin_inset LatexCommand \index{Storage class}
9548
9549 \end_inset
9550
9551  Language Extensions
9552 \layout Subsubsection
9553
9554 sfr
9555 \begin_inset LatexCommand \index{sfr}
9556
9557 \end_inset
9558
9559
9560 \begin_inset LatexCommand \index{\_\_sfr}
9561
9562 \end_inset
9563
9564  (in/out to 8-bit addresses)
9565 \layout Standard
9566
9567 The Z80
9568 \begin_inset LatexCommand \index{Z80}
9569
9570 \end_inset
9571
9572  family has separate address spaces for memory and
9573 \emph on
9574 i
9575 \emph default
9576 nput/
9577 \emph on
9578 o
9579 \emph default
9580 utput memory.
9581  I/O memory
9582 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
9583
9584 \end_inset
9585
9586  is accessed with special instructions, e.g.:
9587 \layout Verse
9588
9589
9590 \family typewriter
9591 sfr at 0x78 IoPort;\SpecialChar ~
9592 \SpecialChar ~
9593 /* define a var in I/O space at 78h called IoPort */
9594
9595 \layout Standard
9596
9597 Writing 0x01 to this variable generates the assembly code:
9598 \layout Verse
9599
9600
9601 \family typewriter
9602 3E 01\SpecialChar ~
9603 \SpecialChar ~
9604 \SpecialChar ~
9605 \SpecialChar ~
9606 \SpecialChar ~
9607 \SpecialChar ~
9608 ld a,#0x01
9609 \newline
9610 D3 78\SpecialChar ~
9611 \SpecialChar ~
9612 \SpecialChar ~
9613 \SpecialChar ~
9614 \SpecialChar ~
9615 \SpecialChar ~
9616 out (_IoPort),a
9617 \layout Subsubsection
9618
9619 banked sfr
9620 \begin_inset LatexCommand \index{sfr}
9621
9622 \end_inset
9623
9624
9625 \begin_inset LatexCommand \index{\_\_sfr}
9626
9627 \end_inset
9628
9629  (in/out to 16-bit addresses)
9630 \layout Standard
9631
9632 The keyword
9633 \emph on
9634 banked
9635 \emph default
9636  is used to support 16 bit addresses in I/O memory e.g.:
9637 \layout Verse
9638
9639
9640 \family typewriter
9641 sfr banked at
9642 \begin_inset LatexCommand \index{at}
9643
9644 \end_inset
9645
9646
9647 \begin_inset LatexCommand \index{\_\_at}
9648
9649 \end_inset
9650
9651  0x123 IoPort;
9652 \layout Standard
9653
9654 Writing 0x01 to this variable generates the assembly code:
9655 \layout Verse
9656
9657
9658 \family typewriter
9659 01 23 01\SpecialChar ~
9660 \SpecialChar ~
9661 \SpecialChar ~
9662 ld bc,#_IoPort
9663 \newline
9664 3E 01\SpecialChar ~
9665 \SpecialChar ~
9666 \SpecialChar ~
9667 \SpecialChar ~
9668 \SpecialChar ~
9669 \SpecialChar ~
9670 ld a,#0x01
9671 \newline
9672 ED 79\SpecialChar ~
9673 \SpecialChar ~
9674 \SpecialChar ~
9675 \SpecialChar ~
9676 \SpecialChar ~
9677 \SpecialChar ~
9678 out (c),a
9679 \layout Subsubsection
9680
9681 sfr
9682 \begin_inset LatexCommand \index{sfr}
9683
9684 \end_inset
9685
9686
9687 \begin_inset LatexCommand \index{\_\_sfr}
9688
9689 \end_inset
9690
9691  (in0/out0 to 8 bit addresses on Z180
9692 \begin_inset LatexCommand \index{Z180}
9693
9694 \end_inset
9695
9696 /HD64180
9697 \begin_inset LatexCommand \index{HD64180}
9698
9699 \end_inset
9700
9701 )
9702 \layout Standard
9703
9704 The compiler option -
9705 \begin_inset ERT
9706 status Collapsed
9707
9708 \layout Standard
9709
9710 \backslash
9711 /
9712 \end_inset
9713
9714 -portmode=180 (80) and a compiler #pragma\SpecialChar ~
9715 portmode
9716 \begin_inset LatexCommand \index{\#pragma portmode}
9717
9718 \end_inset
9719
9720 =z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
9721 ns
9722 \family typewriter
9723 in0/out0
9724 \family default
9725  instead of
9726 \family typewriter
9727 in/out
9728 \family default
9729 .
9730  If you include the file z180.h this will be set automatically.
9731 \layout Subsection
9732
9733 HC08 Storage Class
9734 \begin_inset LatexCommand \index{Storage class}
9735
9736 \end_inset
9737
9738  Language Extensions
9739 \layout Subsubsection
9740
9741 data
9742 \begin_inset LatexCommand \index{data (hc08 storage class)}
9743
9744 \end_inset
9745
9746
9747 \begin_inset LatexCommand \index{\_\_data (hc08 storage class)}
9748
9749 \end_inset
9750
9751
9752 \layout Standard
9753
9754 The data storage class declares a variable that resides in the first 256
9755  bytes of memory (the direct page).
9756  The HC08 is most efficient at accessing variables (especially pointers)
9757  stored here.
9758 \layout Subsubsection
9759
9760 xdata
9761 \begin_inset LatexCommand \index{xdata (hc08 storage class)}
9762
9763 \end_inset
9764
9765
9766 \begin_inset LatexCommand \index{\_\_xdata (hc08 storage class)}
9767
9768 \end_inset
9769
9770
9771 \layout Standard
9772
9773 The xdata storage class declares a variable that can reside anywhere in
9774  memory.
9775  This is the default if no storage class is specified.
9776
9777 \layout Section
9778
9779 Absolute Addressing
9780 \begin_inset LatexCommand \index{Absolute addressing}
9781
9782 \end_inset
9783
9784
9785 \layout Standard
9786
9787 Data items can be assigned an absolute address with the
9788 \emph on
9789 at
9790 \begin_inset LatexCommand \index{at}
9791
9792 \end_inset
9793
9794
9795 \begin_inset LatexCommand \index{\_\_at}
9796
9797 \end_inset
9798
9799  <address>
9800 \emph default
9801  keyword, in addition to a storage class, e.g.:
9802 \layout Verse
9803
9804
9805 \family typewriter
9806 xdata
9807 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9808
9809 \end_inset
9810
9811
9812 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9813
9814 \end_inset
9815
9816  at
9817 \begin_inset LatexCommand \index{at}
9818
9819 \end_inset
9820
9821
9822 \begin_inset LatexCommand \index{\_\_at}
9823
9824 \end_inset
9825
9826  0x7ffe unsigned int chksum;
9827 \layout Standard
9828
9829 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
9830  of the external ram.
9831  The compiler does
9832 \emph on
9833 not
9834 \emph default
9835  reserve any space for variables declared in this way (they are implemented
9836  with an equate in the assembler).
9837  Thus it is left to the programmer to make sure there are no overlaps with
9838  other variables that are declared without the absolute address.
9839  The assembler listing file (.lst
9840 \begin_inset LatexCommand \index{<file>.lst}
9841
9842 \end_inset
9843
9844 ) and the linker output files (.rst
9845 \begin_inset LatexCommand \index{<file>.rst}
9846
9847 \end_inset
9848
9849 ) and (.map
9850 \begin_inset LatexCommand \index{<file>.map}
9851
9852 \end_inset
9853
9854 ) are good places to look for such overlaps.
9855  Variables with an absolute address are
9856 \emph on
9857 not
9858 \emph default
9859  initialized
9860 \begin_inset LatexCommand \index{Variable initialization}
9861
9862 \end_inset
9863
9864 .
9865 \layout Standard
9866
9867 In case of memory mapped I/O devices the keyword
9868 \emph on
9869 volatile
9870 \emph default
9871  has to be used to tell the compiler that accesses might not be removed:
9872 \layout Verse
9873
9874
9875 \family typewriter
9876 volatile
9877 \begin_inset LatexCommand \index{volatile}
9878
9879 \end_inset
9880
9881  xdata
9882 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9883
9884 \end_inset
9885
9886  at
9887 \begin_inset LatexCommand \index{at}
9888
9889 \end_inset
9890
9891  0x8000 unsigned char PORTA_8255;
9892 \layout Standard
9893
9894 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
9895 r) array
9896 \family typewriter
9897 \size footnotesize
9898
9899 \begin_inset LatexCommand \index{Aligned array}
9900
9901 \end_inset
9902
9903
9904 \family default
9905 \size default
9906  starts at a block (256 byte) boundary
9907 \begin_inset LatexCommand \index{block boundary}
9908
9909 \end_inset
9910
9911  (section
9912 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
9913
9914 \end_inset
9915
9916  has an example).
9917 \newline
9918 Absolute addresses can be specified for variables in all storage classes,
9919  e.g.:
9920 \layout Verse
9921
9922
9923 \family typewriter
9924 bit
9925 \begin_inset LatexCommand \index{bit}
9926
9927 \end_inset
9928
9929  at
9930 \begin_inset LatexCommand \index{at}
9931
9932 \end_inset
9933
9934  0x02 bvar;
9935 \layout Standard
9936
9937 The above example will allocate the variable at offset 0x02 in the bit-addressab
9938 le space.
9939  There is no real advantage to assigning absolute addresses to variables
9940  in this manner, unless you want strict control over all the variables allocated.
9941  One possible use would be to write hardware portable code.
9942  For example, if you have a routine that uses one or more of the microcontroller
9943  I/O pins, and such pins are different for two different hardwares, you
9944  can declare the I/O pins in your routine using:
9945 \layout Verse
9946
9947
9948 \family typewriter
9949 extern volatile
9950 \begin_inset LatexCommand \index{volatile}
9951
9952 \end_inset
9953
9954  bit MOSI;\SpecialChar ~
9955 \SpecialChar ~
9956 \SpecialChar ~
9957 \SpecialChar ~
9958 /* master out, slave in */
9959 \newline
9960 extern volatile bit MISO;\SpecialChar ~
9961 \SpecialChar ~
9962 \SpecialChar ~
9963 \SpecialChar ~
9964 /* master in, slave out */
9965 \newline
9966 extern volatile bit MCLK;\SpecialChar ~
9967 \SpecialChar ~
9968 \SpecialChar ~
9969 \SpecialChar ~
9970 /* master clock */
9971 \newline
9972
9973 \newline
9974 /* Input and Output of a byte on a 3-wire serial bus.
9975 \newline
9976 \SpecialChar ~
9977 \SpecialChar ~
9978 \SpecialChar ~
9979 If needed adapt polarity of clock, polarity of data and bit order
9980 \newline
9981 \SpecialChar ~
9982 */
9983 \newline
9984 unsigned char spi_io(unsigned char out_byte)
9985 \newline
9986 {
9987 \newline
9988 \SpecialChar ~
9989 \SpecialChar ~
9990 \SpecialChar ~
9991 \SpecialChar ~
9992 unsigned char i=8;
9993 \newline
9994 \SpecialChar ~
9995 \SpecialChar ~
9996 \SpecialChar ~
9997 \SpecialChar ~
9998 do {
9999 \newline
10000 \SpecialChar ~
10001 \SpecialChar ~
10002 \SpecialChar ~
10003 \SpecialChar ~
10004 \SpecialChar ~
10005 \SpecialChar ~
10006 \SpecialChar ~
10007 \SpecialChar ~
10008 MOSI = out_byte & 0x80;
10009 \newline
10010 \SpecialChar ~
10011 \SpecialChar ~
10012 \SpecialChar ~
10013 \SpecialChar ~
10014 \SpecialChar ~
10015 \SpecialChar ~
10016 \SpecialChar ~
10017 \SpecialChar ~
10018 out_byte <<= 1;
10019 \newline
10020 \SpecialChar ~
10021 \SpecialChar ~
10022 \SpecialChar ~
10023 \SpecialChar ~
10024 \SpecialChar ~
10025 \SpecialChar ~
10026 \SpecialChar ~
10027 \SpecialChar ~
10028 MCLK = 1;
10029 \newline
10030 \SpecialChar ~
10031 \SpecialChar ~
10032 \SpecialChar ~
10033 \SpecialChar ~
10034 \SpecialChar ~
10035 \SpecialChar ~
10036 \SpecialChar ~
10037 \SpecialChar ~
10038 /* _asm nop _endasm; */\SpecialChar ~
10039 \SpecialChar ~
10040 \SpecialChar ~
10041 \SpecialChar ~
10042 \SpecialChar ~
10043 \SpecialChar ~
10044 \SpecialChar ~
10045 \SpecialChar ~
10046 /* for slow peripherals */
10047 \newline
10048 \SpecialChar ~
10049 \SpecialChar ~
10050 \SpecialChar ~
10051 \SpecialChar ~
10052 \SpecialChar ~
10053 \SpecialChar ~
10054 \SpecialChar ~
10055 \SpecialChar ~
10056 if(MISO)
10057 \newline
10058 \SpecialChar ~
10059 \SpecialChar ~
10060 \SpecialChar ~
10061 \SpecialChar ~
10062 \SpecialChar ~
10063 \SpecialChar ~
10064 \SpecialChar ~
10065 \SpecialChar ~
10066 \SpecialChar ~
10067 \SpecialChar ~
10068 \SpecialChar ~
10069 \SpecialChar ~
10070 out_byte += 1;
10071 \newline
10072 \SpecialChar ~
10073 \SpecialChar ~
10074 \SpecialChar ~
10075 \SpecialChar ~
10076 \SpecialChar ~
10077 \SpecialChar ~
10078 \SpecialChar ~
10079 \SpecialChar ~
10080 MCLK = 0;
10081 \newline
10082 \SpecialChar ~
10083 \SpecialChar ~
10084 \SpecialChar ~
10085 \SpecialChar ~
10086 } while(--i);
10087 \newline
10088 \SpecialChar ~
10089 \SpecialChar ~
10090 \SpecialChar ~
10091 \SpecialChar ~
10092 return out_byte;
10093 \newline
10094 }
10095 \layout Standard
10096
10097 Then, someplace in the code for the first hardware you would use
10098 \layout Verse
10099
10100
10101 \family typewriter
10102 bit at
10103 \begin_inset LatexCommand \index{at}
10104
10105 \end_inset
10106
10107
10108 \begin_inset LatexCommand \index{\_\_at}
10109
10110 \end_inset
10111
10112  0x80 MOSI;\SpecialChar ~
10113 \SpecialChar ~
10114 \SpecialChar ~
10115 \SpecialChar ~
10116 /* I/O port 0, bit 0 */
10117 \newline
10118 bit at 0x81 MISO;\SpecialChar ~
10119 \SpecialChar ~
10120 \SpecialChar ~
10121 \SpecialChar ~
10122 /* I/O port 0, bit 1 */
10123 \newline
10124 bit at 0x82 MCLK;\SpecialChar ~
10125 \SpecialChar ~
10126 \SpecialChar ~
10127 \SpecialChar ~
10128 /* I/O port 0, bit 2 */
10129 \layout Standard
10130
10131 Similarly, for the second hardware you would use
10132 \layout Verse
10133
10134
10135 \family typewriter
10136 bit at 0x83 MOSI;\SpecialChar ~
10137 \SpecialChar ~
10138 \SpecialChar ~
10139 \SpecialChar ~
10140 /* I/O port 0, bit 3 */
10141 \newline
10142 bit at 0x91 MISO;\SpecialChar ~
10143 \SpecialChar ~
10144 \SpecialChar ~
10145 \SpecialChar ~
10146 /* I/O port 1, bit 1 */
10147 \newline
10148 bit
10149 \begin_inset LatexCommand \index{bit}
10150
10151 \end_inset
10152
10153  at 0x92 MCLK;\SpecialChar ~
10154 \SpecialChar ~
10155 \SpecialChar ~
10156 \SpecialChar ~
10157 /* I/O port 1, bit 2 */
10158 \layout Standard
10159
10160 and you can use the same hardware dependent routine without changes, as
10161  for example in a library.
10162  This is somehow similar to sbit, but only one absolute address has to be
10163  specified in the whole project.
10164 \layout Section
10165
10166 Parameters
10167 \begin_inset LatexCommand \index{Parameters}
10168
10169 \end_inset
10170
10171
10172 \begin_inset LatexCommand \index{function parameter}
10173
10174 \end_inset
10175
10176  & Local Variables
10177 \begin_inset LatexCommand \index{local variables}
10178
10179 \end_inset
10180
10181
10182 \begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
10183
10184 \end_inset
10185
10186
10187 \layout Standard
10188
10189 Automatic (local) variables and parameters to functions can either be placed
10190  on the stack or in data-space.
10191  The default action of the compiler is to place these variables in the internal
10192  RAM (for small model) or external RAM (for large model).
10193  This in fact makes them similar to
10194 \emph on
10195 static
10196 \begin_inset LatexCommand \index{static}
10197
10198 \end_inset
10199
10200
10201 \emph default
10202  so by default functions are non-reentrant
10203 \begin_inset LatexCommand \index{reentrant}
10204
10205 \end_inset
10206
10207 .
10208
10209 \newline
10210
10211 \newline
10212 They can be placed on the stack
10213 \begin_inset LatexCommand \index{stack}
10214
10215 \end_inset
10216
10217  by using the
10218 \emph on
10219  -
10220 \begin_inset ERT
10221 status Collapsed
10222
10223 \layout Standard
10224
10225 \backslash
10226 /
10227 \end_inset
10228
10229 -stack-auto
10230 \begin_inset LatexCommand \index{-\/-stack-auto}
10231
10232 \end_inset
10233
10234
10235 \emph default
10236  option, by using
10237 \emph on
10238 #pragma\SpecialChar ~
10239 stackauto
10240 \emph default
10241
10242 \begin_inset LatexCommand \index{\#pragma stackauto}
10243
10244 \end_inset
10245
10246  or by using the
10247 \emph on
10248 reentrant
10249 \begin_inset LatexCommand \index{reentrant}
10250
10251 \end_inset
10252
10253
10254 \emph default
10255  keyword in the function declaration, e.g.:
10256 \layout Verse
10257
10258
10259 \family typewriter
10260 unsigned char foo(char i) reentrant
10261 \newline
10262 {
10263 \newline
10264 \SpecialChar ~
10265 \SpecialChar ~
10266 \SpecialChar ~
10267 \SpecialChar ~
10268 ...
10269
10270 \newline
10271 }
10272 \layout Standard
10273
10274 Since stack space on 8051 is limited, the
10275 \emph on
10276 reentrant
10277 \emph default
10278 keyword or the
10279 \emph on
10280  -
10281 \begin_inset ERT
10282 status Collapsed
10283
10284 \layout Standard
10285
10286 \backslash
10287 /
10288 \end_inset
10289
10290 -stack-auto
10291 \emph default
10292  option should be used sparingly.
10293  Note that the reentrant keyword just means that the parameters & local
10294  variables will be allocated to the stack, it
10295 \emph on
10296 does not
10297 \emph default
10298  mean that the function is register bank
10299 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
10300
10301 \end_inset
10302
10303  independent.
10304 \newline
10305
10306 \newline
10307 Local variables
10308 \begin_inset LatexCommand \index{local variables}
10309
10310 \end_inset
10311
10312  can be assigned storage classes and absolute
10313 \begin_inset LatexCommand \index{Absolute addressing}
10314
10315 \end_inset
10316
10317  addresses, e.g.:
10318 \layout Verse
10319
10320
10321 \family typewriter
10322 unsigned char foo()
10323 \newline
10324 {
10325 \newline
10326 \SpecialChar ~
10327 \SpecialChar ~
10328 \SpecialChar ~
10329 \SpecialChar ~
10330 xdata unsigned char i;
10331 \newline
10332 \SpecialChar ~
10333 \SpecialChar ~
10334 \SpecialChar ~
10335 \SpecialChar ~
10336 bit bvar;
10337 \newline
10338 \SpecialChar ~
10339 \SpecialChar ~
10340 \SpecialChar ~
10341 \SpecialChar ~
10342 data at
10343 \begin_inset LatexCommand \index{at}
10344
10345 \end_inset
10346
10347  0x31 unsigned char j;
10348 \newline
10349 \SpecialChar ~
10350 \SpecialChar ~
10351 \SpecialChar ~
10352 \SpecialChar ~
10353 ...
10354
10355 \newline
10356 }
10357 \layout Standard
10358
10359 In the above example the variable
10360 \emph on
10361 i
10362 \emph default
10363  will be allocated in the external ram,
10364 \emph on
10365 bvar
10366 \emph default
10367  in bit addressable space and
10368 \emph on
10369  j
10370 \emph default
10371  in internal ram.
10372  When compiled with
10373 \emph on
10374 -
10375 \begin_inset ERT
10376 status Collapsed
10377
10378 \layout Standard
10379
10380 \backslash
10381 /
10382 \end_inset
10383
10384 -stack-auto
10385 \emph default
10386  or when a function is declared as
10387 \emph on
10388 reentrant
10389 \emph default
10390  this should only be done for static variables.
10391 \layout Standard
10392
10393 Parameters
10394 \begin_inset LatexCommand \index{function parameter}
10395
10396 \end_inset
10397
10398  however are not allowed any storage class
10399 \begin_inset LatexCommand \index{Storage class}
10400
10401 \end_inset
10402
10403 , (storage classes for parameters will be ignored), their allocation is
10404  governed by the memory model in use, and the reentrancy options.
10405 \layout Standard
10406
10407 It is however allowed to use bit parameters in reentrant functions and also
10408  non-static local bit variables are supported.
10409  Efficient use is limited to 8 semi-bitregisters in bit space.
10410  They are pushed and popped to stack as a single byte just like the normal
10411  registers.
10412 \layout Section
10413
10414 Overlaying
10415 \begin_inset LatexCommand \label{sub:Overlaying}
10416
10417 \end_inset
10418
10419
10420 \begin_inset LatexCommand \index{Overlaying}
10421
10422 \end_inset
10423
10424
10425 \layout Standard
10426
10427 For non-reentrant
10428 \begin_inset LatexCommand \index{reentrant}
10429
10430 \end_inset
10431
10432  functions SDCC will try to reduce internal ram space usage by overlaying
10433  parameters and local variables of a function (if possible).
10434  Parameters and local variables
10435 \begin_inset LatexCommand \index{local variables}
10436
10437 \end_inset
10438
10439  of a function will be allocated to an overlayable segment if the function
10440  has
10441 \emph on
10442 no other function calls and the function is non-reentrant and the memory
10443  model
10444 \begin_inset LatexCommand \index{Memory model}
10445
10446 \end_inset
10447
10448  is small.
10449
10450 \emph default
10451  If an explicit storage class
10452 \begin_inset LatexCommand \index{Storage class}
10453
10454 \end_inset
10455
10456  is specified for a local variable, it will NOT be overlayed.
10457 \layout Standard
10458
10459 Note that the compiler (not the linkage editor) makes the decision for overlayin
10460 g the data items.
10461  Functions that are called from an interrupt service routine should be preceded
10462  by a #pragma\SpecialChar ~
10463 nooverlay
10464 \begin_inset LatexCommand \index{\#pragma nooverlay}
10465
10466 \end_inset
10467
10468  if they are not reentrant.
10469 \layout Standard
10470
10471 Also note that the compiler does not do any processing of inline assembler
10472  code, so the compiler might incorrectly assign local variables and parameters
10473  of a function into the overlay segment if the inline assembler code calls
10474  other c-functions that might use the overlay.
10475  In that case the #pragma\SpecialChar ~
10476 nooverlay should be used.
10477 \layout Standard
10478
10479 Parameters and local variables of functions that contain 16 or 32 bit multiplica
10480 tion
10481 \begin_inset LatexCommand \index{Multiplication}
10482
10483 \end_inset
10484
10485  or division
10486 \begin_inset LatexCommand \index{Division}
10487
10488 \end_inset
10489
10490  will NOT be overlayed since these are implemented using external functions,
10491  e.g.:
10492 \layout Verse
10493
10494
10495 \family typewriter
10496 #pragma save
10497 \newline
10498 #pragma nooverlay
10499 \begin_inset LatexCommand \index{\#pragma nooverlay}
10500
10501 \end_inset
10502
10503
10504 \newline
10505 void set_error(unsigned char errcd)
10506 \newline
10507 {
10508 \newline
10509 \SpecialChar ~
10510 \SpecialChar ~
10511 \SpecialChar ~
10512 \SpecialChar ~
10513 P3 = errcd;
10514 \newline
10515 }
10516 \newline
10517 #pragma restore
10518 \newline
10519
10520 \newline
10521 void some_isr () interrupt
10522 \begin_inset LatexCommand \index{interrupt}
10523
10524 \end_inset
10525
10526  2
10527 \newline
10528 {
10529 \newline
10530 \SpecialChar ~
10531 \SpecialChar ~
10532 \SpecialChar ~
10533 \SpecialChar ~
10534 ...
10535 \newline
10536 \SpecialChar ~
10537 \SpecialChar ~
10538 \SpecialChar ~
10539 \SpecialChar ~
10540 set_error(10);
10541 \newline
10542 \SpecialChar ~
10543 \SpecialChar ~
10544 \SpecialChar ~
10545 \SpecialChar ~
10546 ...
10547
10548 \newline
10549 }
10550 \layout Standard
10551
10552 In the above example the parameter
10553 \emph on
10554 errcd
10555 \emph default
10556  for the function
10557 \emph on
10558 set_error
10559 \emph default
10560  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
10561 nooverlay was
10562  not present, this could cause unpredictable runtime behavior when called
10563  from an interrupt service routine.
10564  The #pragma\SpecialChar ~
10565 nooverlay ensures that the parameters and local variables for
10566  the function are NOT overlayed.
10567 \layout Section
10568
10569 Interrupt Service Routines
10570 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
10571
10572 \end_inset
10573
10574
10575 \layout Subsection
10576
10577 General Information
10578 \layout Standard
10579
10580 SDCC allows
10581 \emph on
10582 i
10583 \emph default
10584 nterrupt
10585 \emph on
10586 s
10587 \emph default
10588 ervice
10589 \emph on
10590 r
10591 \emph default
10592 outines to be coded in C, with some extended keywords.
10593 \layout Verse
10594
10595
10596 \family typewriter
10597 void timer_isr (void) interrupt 1 using 1
10598 \newline
10599 {
10600 \newline
10601 \SpecialChar ~
10602 \SpecialChar ~
10603 \SpecialChar ~
10604 \SpecialChar ~
10605 ...
10606
10607 \newline
10608 }
10609 \layout Standard
10610
10611 The optional number following the
10612 \emph on
10613 interrupt
10614 \begin_inset LatexCommand \index{interrupt}
10615
10616 \end_inset
10617
10618
10619 \begin_inset LatexCommand \index{\_\_interrupt}
10620
10621 \end_inset
10622
10623
10624 \emph default
10625  keyword is the interrupt number this routine will service.
10626  When present, the compiler will insert a call to this routine in the interrupt
10627  vector table for the interrupt number specified.
10628  If you have multiple source files in your project, interrupt service routines
10629  can be present in any of them, but a prototype of the isr MUST be present
10630  or included in the file that contains the function
10631 \emph on
10632 main
10633 \emph default
10634 .
10635  The optional
10636 \emph on
10637 using
10638 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10639
10640 \end_inset
10641
10642
10643 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
10644
10645 \end_inset
10646
10647
10648 \emph default
10649  keyword can be used to tell the compiler to use the specified register
10650  bank (8051 specific) when generating code for this function.
10651
10652 \newline
10653
10654 \layout Standard
10655
10656 Interrupt service routines open the door for some very interesting bugs:
10657 \newline
10658 If an interrupt service routine changes variables which are accessed by
10659  other functions these variables have to be declared
10660 \emph on
10661 volatile
10662 \emph default
10663
10664 \begin_inset LatexCommand \index{volatile}
10665
10666 \end_inset
10667
10668 .
10669
10670 \layout Standard
10671
10672 If the access to these variables is not
10673 \emph on
10674 atomic
10675 \begin_inset LatexCommand \index{atomic}
10676
10677 \end_inset
10678
10679
10680 \emph default
10681  (i.e.
10682  the processor needs more than one instruction for the access and could
10683  be interrupted while accessing the variable) the interrupt must be disabled
10684  during the access to avoid inconsistent data.
10685  Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
10686  and should be protected by disabling interrupts.
10687  You're not automatically on the safe side if you use 8 bit variables though.
10688  We need an example here: f.e.
10689  on the 8051 the harmless looking
10690 \begin_inset Quotes srd
10691 \end_inset
10692
10693
10694 \family typewriter
10695 flags\SpecialChar ~
10696 |=\SpecialChar ~
10697 0x80;
10698 \family default
10699
10700 \begin_inset Quotes sld
10701 \end_inset
10702
10703  is not atomic if
10704 \family typewriter
10705 flags
10706 \family default
10707  resides in xdata.
10708  Setting
10709 \begin_inset Quotes srd
10710 \end_inset
10711
10712
10713 \family typewriter
10714 flags\SpecialChar ~
10715 |=\SpecialChar ~
10716 0x40;
10717 \family default
10718
10719 \begin_inset Quotes sld
10720 \end_inset
10721
10722  from within an interrupt routine might get lost if the interrupt occurs
10723  at the wrong time.
10724
10725 \begin_inset Quotes sld
10726 \end_inset
10727
10728
10729 \family typewriter
10730 counter\SpecialChar ~
10731 +=\SpecialChar ~
10732 8;
10733 \family default
10734
10735 \begin_inset Quotes srd
10736 \end_inset
10737
10738  is not atomic on the 8051 even if
10739 \family typewriter
10740 counter
10741 \family default
10742  is located in data memory.
10743  Bugs like these are hard to reproduce and can cause a lot of trouble.
10744
10745 \layout Standard
10746
10747 The return address and the registers used in the interrupt service routine
10748  are saved on the stack
10749 \begin_inset LatexCommand \index{stack}
10750
10751 \end_inset
10752
10753  so there must be sufficient stack space.
10754  If there isn't variables or registers (or even the return address itself)
10755  will be corrupted.
10756  This
10757 \emph on
10758 stack overflow
10759 \emph default
10760
10761 \begin_inset LatexCommand \index{stack overflow}
10762
10763 \end_inset
10764
10765  is most likely to happen if the interrupt occurs during the
10766 \begin_inset Quotes sld
10767 \end_inset
10768
10769 deepest
10770 \begin_inset Quotes srd
10771 \end_inset
10772
10773  subroutine when the stack is already in use for f.e.
10774  many return addresses.
10775 \layout Standard
10776
10777 A special note here, int (16 bit) and long (32 bit) integer division
10778 \begin_inset LatexCommand \index{Division}
10779
10780 \end_inset
10781
10782 , multiplication
10783 \begin_inset LatexCommand \index{Multiplication}
10784
10785 \end_inset
10786
10787  & modulus
10788 \begin_inset LatexCommand \index{Modulus}
10789
10790 \end_inset
10791
10792  and floating-point
10793 \begin_inset LatexCommand \index{Floating point support}
10794
10795 \end_inset
10796
10797  operations are implemented using external support routines developed in
10798  ANSI-C.
10799  If an interrupt service routine needs to do any of these operations then
10800  the support routines (as mentioned in a following section) will have to
10801  be recompiled using the
10802 \emph on
10803  -
10804 \begin_inset ERT
10805 status Collapsed
10806
10807 \layout Standard
10808
10809 \backslash
10810 /
10811 \end_inset
10812
10813 -stack-auto
10814 \begin_inset LatexCommand \index{-\/-stack-auto}
10815
10816 \end_inset
10817
10818
10819 \emph default
10820  option and the source file will need to be compiled using the
10821 \emph on
10822 -
10823 \begin_inset ERT
10824 status Collapsed
10825
10826 \layout Standard
10827
10828 \backslash
10829 /
10830 \end_inset
10831
10832 -int-long-reent
10833 \emph default
10834
10835 \begin_inset LatexCommand \index{-\/-int-long-reent}
10836
10837 \end_inset
10838
10839  compiler option.
10840 \layout Standard
10841
10842 Calling other functions from an interrupt service routine is not recommended,
10843  avoid it if possible.
10844  Note that when some function is called from an interrupt service routine
10845  it should be preceded by a #pragma\SpecialChar ~
10846 nooverlay
10847 \begin_inset LatexCommand \index{\#pragma nooverlay}
10848
10849 \end_inset
10850
10851  if it is not reentrant.
10852  Furthermore nonreentrant functions should not be called from the main program
10853  while the interrupt service routine might be active.
10854
10855 \newline
10856
10857 \newline
10858 Also see section
10859 \begin_inset LatexCommand \ref{sub:Overlaying}
10860
10861 \end_inset
10862
10863 \SpecialChar ~
10864 about Overlaying and section
10865 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
10866
10867 \end_inset
10868
10869 \SpecialChar ~
10870 about Functions using private register banks.
10871 \layout Subsection
10872
10873 MCS51/DS390 Interrupt Service Routines
10874 \layout Standard
10875
10876 Interrupt numbers and the corresponding address & descriptions for the Standard
10877  8051/8052 are listed below.
10878  SDCC will automatically adjust the interrupt vector table to the maximum
10879  interrupt number specified.
10880 \newline
10881
10882 \layout Standard
10883 \align center
10884
10885 \begin_inset  Tabular
10886 <lyxtabular version="3" rows="7" columns="3">
10887 <features>
10888 <column alignment="center" valignment="top" leftline="true" width="0in">
10889 <column alignment="center" valignment="top" leftline="true" width="0in">
10890 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
10891 <row topline="true" bottomline="true">
10892 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10893 \begin_inset Text
10894
10895 \layout Standard
10896
10897 Interrupt #
10898 \end_inset
10899 </cell>
10900 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10901 \begin_inset Text
10902
10903 \layout Standard
10904
10905 Description
10906 \end_inset
10907 </cell>
10908 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10909 \begin_inset Text
10910
10911 \layout Standard
10912
10913 Vector Address
10914 \end_inset
10915 </cell>
10916 </row>
10917 <row topline="true">
10918 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10919 \begin_inset Text
10920
10921 \layout Standard
10922
10923 0
10924 \end_inset
10925 </cell>
10926 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10927 \begin_inset Text
10928
10929 \layout Standard
10930
10931 External 0
10932 \end_inset
10933 </cell>
10934 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10935 \begin_inset Text
10936
10937 \layout Standard
10938
10939 0x0003
10940 \end_inset
10941 </cell>
10942 </row>
10943 <row topline="true">
10944 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10945 \begin_inset Text
10946
10947 \layout Standard
10948
10949 1
10950 \end_inset
10951 </cell>
10952 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10953 \begin_inset Text
10954
10955 \layout Standard
10956
10957 Timer 0
10958 \end_inset
10959 </cell>
10960 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10961 \begin_inset Text
10962
10963 \layout Standard
10964
10965 0x000B
10966 \end_inset
10967 </cell>
10968 </row>
10969 <row topline="true">
10970 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10971 \begin_inset Text
10972
10973 \layout Standard
10974
10975 2
10976 \end_inset
10977 </cell>
10978 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10979 \begin_inset Text
10980
10981 \layout Standard
10982
10983 External 1
10984 \end_inset
10985 </cell>
10986 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10987 \begin_inset Text
10988
10989 \layout Standard
10990
10991 0x0013
10992 \end_inset
10993 </cell>
10994 </row>
10995 <row topline="true">
10996 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10997 \begin_inset Text
10998
10999 \layout Standard
11000
11001 3
11002 \end_inset
11003 </cell>
11004 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11005 \begin_inset Text
11006
11007 \layout Standard
11008
11009 Timer 1
11010 \end_inset
11011 </cell>
11012 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11013 \begin_inset Text
11014
11015 \layout Standard
11016
11017 0x001B
11018 \end_inset
11019 </cell>
11020 </row>
11021 <row topline="true">
11022 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11023 \begin_inset Text
11024
11025 \layout Standard
11026
11027 4
11028 \end_inset
11029 </cell>
11030 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11031 \begin_inset Text
11032
11033 \layout Standard
11034
11035 Serial
11036 \end_inset
11037 </cell>
11038 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11039 \begin_inset Text
11040
11041 \layout Standard
11042
11043 0x0023
11044 \end_inset
11045 </cell>
11046 </row>
11047 <row topline="true" bottomline="true">
11048 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11049 \begin_inset Text
11050
11051 \layout Standard
11052
11053 5
11054 \end_inset
11055 </cell>
11056 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11057 \begin_inset Text
11058
11059 \layout Standard
11060
11061 Timer 2 (8052)
11062 \end_inset
11063 </cell>
11064 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11065 \begin_inset Text
11066
11067 \layout Standard
11068
11069 0x002B
11070 \end_inset
11071 </cell>
11072 </row>
11073 </lyxtabular>
11074
11075 \end_inset
11076
11077
11078 \newline
11079
11080 \layout Standard
11081
11082 If the interrupt service routine is defined without
11083 \emph on
11084 using
11085 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11086
11087 \end_inset
11088
11089
11090 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11091
11092 \end_inset
11093
11094
11095 \emph default
11096  a register bank or with register bank 0 (
11097 \emph on
11098 using
11099 \emph default
11100  0), the compiler will save the registers used by itself on the stack upon
11101  entry and restore them at exit, however if such an interrupt service routine
11102  calls another function then the entire register bank will be saved on the
11103  stack.
11104  This scheme may be advantageous for small interrupt service routines which
11105  have low register usage.
11106 \layout Standard
11107
11108 If the interrupt service routine is defined to be using a specific register
11109  bank then only
11110 \emph on
11111 a, b, dptr
11112 \emph default
11113  & psw are saved and restored, if such an interrupt service routine calls
11114  another function (using another register bank) then the entire register
11115  bank of the called function will be saved on the stack.
11116  This scheme is recommended for larger interrupt service routines.
11117 \layout Subsection
11118
11119 HC08 Interrupt Service Routines
11120 \layout Standard
11121
11122 Since the number of interrupts available is chip specific and the interrupt
11123  vector table always ends at the last byte of memory, the interrupt numbers
11124  corresponds to the interrupt vectors in reverse order of address.
11125  For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
11126  2 will use the interrupt vector at 0xfffa, and so on.
11127  However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
11128  this way; instead see section
11129 \begin_inset LatexCommand \ref{sub:Startup-Code}
11130
11131 \end_inset
11132
11133  for details on customizing startup.
11134 \layout Subsection
11135
11136 Z80 Interrupt Service Routines
11137 \layout Standard
11138
11139 The Z80 uses several different methods for determining the correct interrupt
11140  vector depending on the hardware implementation.
11141  Therefore, SDCC ignores the optional interrupt number and does not attempt
11142  to generate an interrupt vector table.
11143 \layout Standard
11144
11145 By default, SDCC generates code for a maskable interrupt, which uses an
11146  RETI instruction to return from the interrupt.
11147  To write an interrupt handler for the non-maskable interrupt, which needs
11148  an RETN instruction instead, add the
11149 \emph on
11150 critical
11151 \emph default
11152  keyword:
11153 \layout Verse
11154
11155
11156 \family typewriter
11157 void nmi_isr (void) critical interrupt
11158 \newline
11159 {
11160 \newline
11161 \SpecialChar ~
11162 \SpecialChar ~
11163 \SpecialChar ~
11164 \SpecialChar ~
11165 ...
11166
11167 \newline
11168 }
11169 \layout Section
11170
11171 Enabling and Disabling Interrupts
11172 \layout Subsection
11173
11174 Critical Functions and Critical Statements
11175 \layout Standard
11176
11177 A special keyword may be associated with a block or a function declaring
11178  it as
11179 \emph on
11180 critical
11181 \emph default
11182 .
11183  SDCC will generate code to disable all interrupts
11184 \begin_inset LatexCommand \index{interrupt}
11185
11186 \end_inset
11187
11188  upon entry to a critical function and restore the interrupt enable to the
11189  previous state before returning.
11190  Nesting critical functions will need one additional byte on the stack
11191 \begin_inset LatexCommand \index{stack}
11192
11193 \end_inset
11194
11195  for each call.
11196 \layout Verse
11197
11198
11199 \family typewriter
11200 int foo () critical
11201 \begin_inset LatexCommand \index{critical}
11202
11203 \end_inset
11204
11205
11206 \begin_inset LatexCommand \index{\_\_critical}
11207
11208 \end_inset
11209
11210
11211 \newline
11212 {
11213 \newline
11214 \SpecialChar ~
11215 \SpecialChar ~
11216 \SpecialChar ~
11217 \SpecialChar ~
11218 ...
11219
11220 \newline
11221 \SpecialChar ~
11222 \SpecialChar ~
11223 \SpecialChar ~
11224 \SpecialChar ~
11225 ...
11226
11227 \newline
11228 }
11229 \layout Standard
11230
11231 The critical attribute maybe used with other attributes like
11232 \emph on
11233 reentrant.
11234 \emph default
11235
11236 \newline
11237 The keyword
11238 \emph on
11239 critical
11240 \emph default
11241  may also be used to disable interrupts more locally:
11242 \layout Verse
11243
11244
11245 \family typewriter
11246 critical{ i++; }
11247 \layout Standard
11248
11249 More than one statement could have been included in the block.
11250 \layout Subsection
11251
11252 Enabling and Disabling Interrupts directly
11253 \layout Standard
11254
11255 Interrupts
11256 \begin_inset LatexCommand \index{interrupt}
11257
11258 \end_inset
11259
11260  can also be disabled and enabled directly (8051):
11261 \layout Verse
11262
11263
11264 \family typewriter
11265 EA = 0;\SpecialChar ~
11266 \SpecialChar ~
11267 \SpecialChar ~
11268 \SpecialChar ~
11269 \SpecialChar ~
11270 \SpecialChar ~
11271 \SpecialChar ~
11272 \SpecialChar ~
11273 \SpecialChar ~
11274 \SpecialChar ~
11275 \SpecialChar ~
11276 \SpecialChar ~
11277 or:\SpecialChar ~
11278 \SpecialChar ~
11279 \SpecialChar ~
11280 \SpecialChar ~
11281 \SpecialChar ~
11282 \SpecialChar ~
11283 \SpecialChar ~
11284 \SpecialChar ~
11285 \SpecialChar ~
11286 \SpecialChar ~
11287 \SpecialChar ~
11288 EA_SAVE = EA;
11289 \layout Verse
11290
11291
11292 \family typewriter
11293 ...\SpecialChar ~
11294 \SpecialChar ~
11295 \SpecialChar ~
11296 \SpecialChar ~
11297 \SpecialChar ~
11298 \SpecialChar ~
11299 \SpecialChar ~
11300 \SpecialChar ~
11301 \SpecialChar ~
11302 \SpecialChar ~
11303 \SpecialChar ~
11304 \SpecialChar ~
11305 \SpecialChar ~
11306 \SpecialChar ~
11307 \SpecialChar ~
11308 \SpecialChar ~
11309 \SpecialChar ~
11310 \SpecialChar ~
11311 \SpecialChar ~
11312 \SpecialChar ~
11313 \SpecialChar ~
11314 \SpecialChar ~
11315 \SpecialChar ~
11316 \SpecialChar ~
11317 \SpecialChar ~
11318 \SpecialChar ~
11319 \SpecialChar ~
11320 \SpecialChar ~
11321 \SpecialChar ~
11322 \SpecialChar ~
11323 EA = 0;
11324 \layout Verse
11325
11326
11327 \family typewriter
11328 EA = 1;\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 ...
11355 \layout Verse
11356
11357
11358 \family typewriter
11359 \SpecialChar ~
11360 \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 \SpecialChar ~
11387 \SpecialChar ~
11388 \SpecialChar ~
11389 \SpecialChar ~
11390 \SpecialChar ~
11391 \SpecialChar ~
11392 EA = EA_SAVE;
11393 \layout Standard
11394
11395 On other architectures which have seperate opcodes for enabling and disabling
11396  interrupts you might want to make use of defines with inline assembly
11397 \begin_inset LatexCommand \index{Assembler routines}
11398
11399 \end_inset
11400
11401  (HC08):
11402 \layout Verse
11403
11404
11405 \family typewriter
11406 #define CLI _asm
11407 \begin_inset LatexCommand \index{\_asm}
11408
11409 \end_inset
11410
11411 \SpecialChar ~
11412 \SpecialChar ~
11413 cli\SpecialChar ~
11414 \SpecialChar ~
11415 _endasm
11416 \begin_inset LatexCommand \index{\_endasm}
11417
11418 \end_inset
11419
11420 ;
11421 \layout Verse
11422
11423
11424 \family typewriter
11425 #define SEI _asm\SpecialChar ~
11426 \SpecialChar ~
11427 sei\SpecialChar ~
11428 \SpecialChar ~
11429 _endasm;
11430 \layout Verse
11431
11432
11433 \family typewriter
11434 ...
11435 \layout Standard
11436
11437 Note: it is sometimes sufficient to disable only a specific interrupt source
11438  like f.e.
11439  a timer or serial interrupt by manipulating an
11440 \emph on
11441 interrupt mask
11442 \begin_inset LatexCommand \index{interrupt mask}
11443
11444 \end_inset
11445
11446
11447 \emph default
11448  register.
11449
11450 \layout Standard
11451
11452 Usually the time during which interrupts are disabled should be kept as
11453  short as possible.
11454  This minimizes both
11455 \emph on
11456 interrupt latency
11457 \emph default
11458
11459 \begin_inset LatexCommand \index{interrupt latency}
11460
11461 \end_inset
11462
11463  (the time between the occurrence of the interrupt and the execution of
11464  the first code in the interrupt routine) and
11465 \emph on
11466 interrupt jitter
11467 \emph default
11468
11469 \begin_inset LatexCommand \index{interrupt jitter}
11470
11471 \end_inset
11472
11473  (the difference between the shortest and the longest interrupt latency).
11474  These really are something different, f.e.
11475  a serial interrupt has to be served before its buffer overruns so it cares
11476  for the maximum interrupt latency, whereas it does not care about jitter.
11477  On a loudspeaker driven via a digital to analog converter which is fed
11478  by an interrupt a latency of a few milliseconds might be tolerable, whereas
11479  a much smaller jitter will be very audible.
11480 \layout Standard
11481
11482 You can reenable interrupts within an interrupt routine and on some architecture
11483 s you can make use of two (or more) levels of
11484 \emph on
11485 interrupt priorities
11486 \emph default
11487
11488 \begin_inset LatexCommand \index{interrupt priority}
11489
11490 \end_inset
11491
11492 .
11493  On some architectures which don't support interrupt priorities these can
11494  be implemented by manipulating the interrupt mask and reenabling interrupts
11495  within the interrupt routine.
11496  Check there is sufficient space on the stack
11497 \begin_inset LatexCommand \index{stack}
11498
11499 \end_inset
11500
11501  and don't add complexity unless you have to.
11502
11503 \layout Subsection
11504
11505 Semaphore
11506 \begin_inset LatexCommand \index{semaphore}
11507
11508 \end_inset
11509
11510  locking (mcs51/ds390)
11511 \layout Standard
11512
11513 Some architectures (mcs51/ds390) have an atomic
11514 \begin_inset LatexCommand \index{atomic}
11515
11516 \end_inset
11517
11518  bit test and
11519 \emph on
11520
11521 \emph default
11522 clear
11523 \emph on
11524
11525 \emph default
11526 instruction.
11527  These type of instructions are typically used in preemptive multitasking
11528  systems, where a routine f.e.
11529  claims the use of a data structure ('acquires a lock
11530 \begin_inset LatexCommand \index{lock}
11531
11532 \end_inset
11533
11534  on it'), makes some modifications and then releases the lock when the data
11535  structure is consistent again.
11536  The instruction may also be used if interrupt and non-interrupt code have
11537  to compete for a resource.
11538  With the atomic bit test and clear instruction interrupts
11539 \begin_inset LatexCommand \index{interrupt}
11540
11541 \end_inset
11542
11543  don't have to be disabled for the locking operation.
11544
11545 \layout Standard
11546
11547 SDCC generates this instruction if the source follows this pattern:
11548 \layout Verse
11549
11550
11551 \family typewriter
11552 volatile
11553 \begin_inset LatexCommand \index{volatile}
11554
11555 \end_inset
11556
11557  bit resource_is_free;
11558 \newline
11559
11560 \newline
11561 if (resource_is_free)
11562 \newline
11563 \SpecialChar ~
11564 \SpecialChar ~
11565 {
11566 \newline
11567 \SpecialChar ~
11568 \SpecialChar ~
11569 \SpecialChar ~
11570 \SpecialChar ~
11571 resource_is_free=0;
11572 \newline
11573 \SpecialChar ~
11574 \SpecialChar ~
11575 \SpecialChar ~
11576 \SpecialChar ~
11577 ...
11578
11579 \newline
11580 \SpecialChar ~
11581 \SpecialChar ~
11582 \SpecialChar ~
11583 \SpecialChar ~
11584 resource_is_free=1;
11585 \newline
11586 \SpecialChar ~
11587 \SpecialChar ~
11588 }
11589 \layout Standard
11590
11591 Note, mcs51 and ds390 support only an atomic
11592 \begin_inset LatexCommand \index{atomic}
11593
11594 \end_inset
11595
11596  bit test and
11597 \emph on
11598 clear
11599 \emph default
11600  instruction (as opposed to atomic bit test and
11601 \emph on
11602 set).
11603 \layout Section
11604
11605 Functions using private register banks
11606 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
11607
11608 \end_inset
11609
11610  (mcs51/ds390)
11611 \layout Standard
11612
11613 Some architectures have support for quickly changing register sets.
11614  SDCC supports this feature with the
11615 \emph on
11616 using
11617 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11618
11619 \end_inset
11620
11621
11622 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11623
11624 \end_inset
11625
11626
11627 \emph default
11628  attribute (which tells the compiler to use a register bank
11629 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
11630
11631 \end_inset
11632
11633  other than the default bank zero).
11634  It should only be applied to
11635 \emph on
11636 interrupt
11637 \begin_inset LatexCommand \index{interrupt}
11638
11639 \end_inset
11640
11641
11642 \emph default
11643  functions (see footnote below).
11644  This will in most circumstances make the generated ISR code more efficient
11645  since it will not have to save registers on the stack.
11646 \layout Standard
11647
11648 The
11649 \emph on
11650 using
11651 \emph default
11652  attribute will have no effect on the generated code for a
11653 \emph on
11654 non-interrupt
11655 \emph default
11656  function (but may occasionally be useful anyway
11657 \begin_inset Foot
11658 collapsed false
11659
11660 \layout Standard
11661
11662 possible exception: if a function is called ONLY from 'interrupt' functions
11663  using a particular bank, it can be declared with the same 'using' attribute
11664  as the calling 'interrupt' functions.
11665  For instance, if you have several ISRs using bank one, and all of them
11666  call memcpy(), it might make sense to create a specialized version of memcpy()
11667  'using 1', since this would prevent the ISR from having to save bank zero
11668  to the stack on entry and switch to bank zero before calling the function
11669 \end_inset
11670
11671 ).
11672 \newline
11673
11674 \emph on
11675 (pending: I don't think this has been done yet)
11676 \layout Standard
11677
11678 An
11679 \emph on
11680 interrupt
11681 \emph default
11682  function using a non-zero bank will assume that it can trash that register
11683  bank, and will not save it.
11684  Since high-priority interrupts
11685 \begin_inset LatexCommand \index{interrupts}
11686
11687 \end_inset
11688
11689
11690 \begin_inset LatexCommand \index{interrupt priority}
11691
11692 \end_inset
11693
11694  can interrupt low-priority ones on the 8051 and friends, this means that
11695  if a high-priority ISR
11696 \emph on
11697 using
11698 \emph default
11699  a particular bank occurs while processing a low-priority ISR
11700 \emph on
11701 using
11702 \emph default
11703  the same bank, terrible and bad things can happen.
11704  To prevent this, no single register bank should be
11705 \emph on
11706 used
11707 \emph default
11708  by both a high priority and a low priority ISR.
11709  This is probably most easily done by having all high priority ISRs use
11710  one bank and all low priority ISRs use another.
11711  If you have an ISR which can change priority at runtime, you're on your
11712  own: I suggest using the default bank zero and taking the small performance
11713  hit.
11714 \layout Standard
11715
11716 It is most efficient if your ISR calls no other functions.
11717  If your ISR must call other functions, it is most efficient if those functions
11718  use the same bank as the ISR (see note 1 below); the next best is if the
11719  called functions use bank zero.
11720  It is very inefficient to call a function using a different, non-zero bank
11721  from an ISR.
11722
11723 \layout Section
11724
11725 Startup Code
11726 \begin_inset LatexCommand \label{sub:Startup-Code}
11727
11728 \end_inset
11729
11730
11731 \begin_inset LatexCommand \index{Startup code}
11732
11733 \end_inset
11734
11735
11736 \layout Subsection
11737
11738 MCS51/DS390 Startup Code
11739 \layout Standard
11740
11741 The compiler inserts a call to the C routine
11742 \emph on
11743 _sdcc_external_startup()
11744 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
11745
11746 \end_inset
11747
11748
11749 \series bold
11750 \emph default
11751
11752 \series default
11753 at the start of the CODE area.
11754  This routine is in the runtime library
11755 \begin_inset LatexCommand \index{Runtime library}
11756
11757 \end_inset
11758
11759 .
11760  By default this routine returns 0, if this routine returns a non-zero value,
11761  the static & global variable initialization will be skipped and the function
11762  main will be invoked.
11763  Otherwise static & global variables will be initialized before the function
11764  main is invoked.
11765  You could add a
11766 \emph on
11767 _sdcc_external_startup()
11768 \emph default
11769  routine to your program to override the default if you need to setup hardware
11770  or perform some other critical operation prior to static & global variable
11771  initialization
11772 \begin_inset LatexCommand \index{Variable initialization}
11773
11774 \end_inset
11775
11776 .
11777  On some mcs51 variants xdata
11778 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
11779
11780 \end_inset
11781
11782  memory has to be explicitly enabled before it can be accessed or if the
11783  watchdog needs to be disabled, this is the place to do it.
11784  The startup code clears all internal data memory, 256 bytes by default,
11785  but from 0 to n-1 if
11786 \emph on
11787 -
11788 \begin_inset ERT
11789 status Collapsed
11790
11791 \layout Standard
11792
11793 \backslash
11794 /
11795 \end_inset
11796
11797 -iram-size
11798 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
11799
11800 \end_inset
11801
11802 n
11803 \emph default
11804  is used.
11805  (recommended for Chipcon CC1010).
11806 \layout Standard
11807
11808 See also the compiler option
11809 \emph on
11810 -
11811 \begin_inset ERT
11812 status Collapsed
11813
11814 \layout Standard
11815
11816 \backslash
11817 /
11818 \end_inset
11819
11820 -no-xinit
11821 \emph default
11822 -
11823 \emph on
11824 opt
11825 \emph default
11826
11827 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
11828
11829 \end_inset
11830
11831  and section
11832 \begin_inset LatexCommand \ref{sub:MCS51-variants}
11833
11834 \end_inset
11835
11836 \SpecialChar ~
11837 about MCS51-variants.
11838 \layout Subsection
11839
11840 HC08 Startup Code
11841 \layout Standard
11842
11843 The HC08 startup code follows the same scheme as the MCS51 startup code.
11844 \layout Subsection
11845
11846 Z80 Startup Code
11847 \layout Standard
11848
11849 On the Z80 the startup code is inserted by linking with crt0.o which is generated
11850  from sdcc/device/lib/z80/crt0.s.
11851  If you need a different startup code you can use the compiler option
11852 \emph on
11853 -
11854 \series bold
11855 \emph default
11856
11857 \begin_inset ERT
11858 status Collapsed
11859
11860 \layout Standard
11861
11862 \backslash
11863 /
11864 \end_inset
11865
11866
11867 \series default
11868 \emph on
11869 -no-std-crt0
11870 \emph default
11871
11872 \begin_inset LatexCommand \index{-\/-no-std-crt0}
11873
11874 \end_inset
11875
11876  and provide your own crt0.o.
11877
11878 \layout Section
11879
11880 Inline Assembler Code
11881 \begin_inset LatexCommand \index{Assembler routines}
11882
11883 \end_inset
11884
11885
11886 \layout Subsection
11887
11888 A Step by Step Introduction
11889 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
11890
11891 \end_inset
11892
11893
11894 \layout Standard
11895
11896 Starting from a small snippet of c-code this example shows for the MCS51
11897  how to use inline assembly, access variables, a function parameter and
11898  an array in xdata memory.
11899  The example uses an MCS51 here but is easily adapted for other architectures.
11900  This is a buffer routine which should be optimized:
11901 \layout Verse
11902
11903
11904 \family typewriter
11905 \size footnotesize
11906 unsigned char far
11907 \begin_inset LatexCommand \index{far (storage class)}
11908
11909 \end_inset
11910
11911
11912 \begin_inset LatexCommand \index{\_\_far (storage class)}
11913
11914 \end_inset
11915
11916  at
11917 \begin_inset LatexCommand \index{at}
11918
11919 \end_inset
11920
11921
11922 \begin_inset LatexCommand \index{\_\_at}
11923
11924 \end_inset
11925
11926  0x7f00 buf[0x100];
11927 \begin_inset LatexCommand \index{Aligned array}
11928
11929 \end_inset
11930
11931
11932 \newline
11933 unsigned char head,tail;
11934 \newline
11935
11936 \newline
11937 void to_buffer( unsigned char c )
11938 \newline
11939 {
11940 \newline
11941 \SpecialChar ~
11942 \SpecialChar ~
11943 \SpecialChar ~
11944 \SpecialChar ~
11945 if( head != tail-1 )
11946 \newline
11947 \SpecialChar ~
11948 \SpecialChar ~
11949 \SpecialChar ~
11950 \SpecialChar ~
11951 \SpecialChar ~
11952 \SpecialChar ~
11953 \SpecialChar ~
11954 \SpecialChar ~
11955 buf[ head++ ] = c;\SpecialChar ~
11956 \SpecialChar ~
11957 \SpecialChar ~
11958 \SpecialChar ~
11959 /* access to a 256 byte aligned array */
11960 \newline
11961 }
11962 \layout Standard
11963
11964 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
11965  then a corresponding buffer.asm file is generated.
11966  We define a new function
11967 \family typewriter
11968 to_buffer_asm()
11969 \family default
11970  in file buffer.c in which we cut and paste the generated code, removing
11971  unwanted comments and some ':'.
11972  Then add
11973 \begin_inset Quotes sld
11974 \end_inset
11975
11976 _asm
11977 \begin_inset Quotes srd
11978 \end_inset
11979
11980  and
11981 \begin_inset Quotes sld
11982 \end_inset
11983
11984 _endasm;
11985 \begin_inset Quotes srd
11986 \end_inset
11987
11988  to the beginning and the end of the function body:
11989 \layout Verse
11990
11991
11992 \family typewriter
11993 \size footnotesize
11994 /* With a cut and paste from the .asm file, we have something to start with.
11995 \newline
11996 \SpecialChar ~
11997 \SpecialChar ~
11998 \SpecialChar ~
11999 The function is not yet OK! (registers aren't saved) */
12000 \newline
12001 void to_buffer_asm( unsigned char c )
12002 \newline
12003 {
12004 \newline
12005 \SpecialChar ~
12006 \SpecialChar ~
12007 \SpecialChar ~
12008 \SpecialChar ~
12009 _asm
12010 \begin_inset LatexCommand \index{\_asm}
12011
12012 \end_inset
12013
12014
12015 \begin_inset LatexCommand \index{\_\_asm}
12016
12017 \end_inset
12018
12019
12020 \newline
12021 \SpecialChar ~
12022 \SpecialChar ~
12023 \SpecialChar ~
12024 \SpecialChar ~
12025 mov\SpecialChar ~
12026 \SpecialChar ~
12027 r2,dpl
12028 \newline
12029 ;buffer.c if( head != tail-1 )
12030 \newline
12031 \SpecialChar ~
12032 \SpecialChar ~
12033 \SpecialChar ~
12034 \SpecialChar ~
12035 mov\SpecialChar ~
12036 \SpecialChar ~
12037 a,_tail
12038 \newline
12039 \SpecialChar ~
12040 \SpecialChar ~
12041 \SpecialChar ~
12042 \SpecialChar ~
12043 dec\SpecialChar ~
12044 \SpecialChar ~
12045 a
12046 \newline
12047 \SpecialChar ~
12048 \SpecialChar ~
12049 \SpecialChar ~
12050 \SpecialChar ~
12051 mov\SpecialChar ~
12052 \SpecialChar ~
12053 r3,a
12054 \newline
12055 \SpecialChar ~
12056 \SpecialChar ~
12057 \SpecialChar ~
12058 \SpecialChar ~
12059 mov\SpecialChar ~
12060 \SpecialChar ~
12061 a,_head
12062 \newline
12063 \SpecialChar ~
12064 \SpecialChar ~
12065 \SpecialChar ~
12066 \SpecialChar ~
12067 cjne a,ar3,00106$
12068 \newline
12069 \SpecialChar ~
12070 \SpecialChar ~
12071 \SpecialChar ~
12072 \SpecialChar ~
12073 ret
12074 \newline
12075 00106$:
12076 \newline
12077 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
12078 \begin_inset LatexCommand \index{Aligned array}
12079
12080 \end_inset
12081
12082
12083 \newline
12084 \SpecialChar ~
12085 \SpecialChar ~
12086 \SpecialChar ~
12087 \SpecialChar ~
12088 mov\SpecialChar ~
12089 \SpecialChar ~
12090 r3,_head
12091 \newline
12092 \SpecialChar ~
12093 \SpecialChar ~
12094 \SpecialChar ~
12095 \SpecialChar ~
12096 inc\SpecialChar ~
12097 \SpecialChar ~
12098 _head
12099 \newline
12100 \SpecialChar ~
12101 \SpecialChar ~
12102 \SpecialChar ~
12103 \SpecialChar ~
12104 mov\SpecialChar ~
12105 \SpecialChar ~
12106 dpl,r3
12107 \newline
12108 \SpecialChar ~
12109 \SpecialChar ~
12110 \SpecialChar ~
12111 \SpecialChar ~
12112 mov\SpecialChar ~
12113 \SpecialChar ~
12114 dph,#(_buf >> 8)
12115 \newline
12116 \SpecialChar ~
12117 \SpecialChar ~
12118 \SpecialChar ~
12119 \SpecialChar ~
12120 mov\SpecialChar ~
12121 \SpecialChar ~
12122 a,r2
12123 \newline
12124 \SpecialChar ~
12125 \SpecialChar ~
12126 \SpecialChar ~
12127 \SpecialChar ~
12128 movx @dptr,a
12129 \newline
12130 00103$:
12131 \newline
12132 \SpecialChar ~
12133 \SpecialChar ~
12134 \SpecialChar ~
12135 \SpecialChar ~
12136 ret
12137 \newline
12138 \SpecialChar ~
12139 \SpecialChar ~
12140 \SpecialChar ~
12141 \SpecialChar ~
12142 _endasm
12143 \begin_inset LatexCommand \index{\_endasm}
12144
12145 \end_inset
12146
12147
12148 \begin_inset LatexCommand \index{\_\_endasm}
12149
12150 \end_inset
12151
12152 ;
12153 \newline
12154 }
12155 \layout Standard
12156
12157 The new file buffer.c should compile with only one warning about the unreferenced
12158  function argument 'c'.
12159  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
12160  (1) and finally have:
12161 \layout Verse
12162
12163
12164 \family typewriter
12165 \size footnotesize
12166 unsigned char far at 0x7f00 buf[0x100];
12167 \newline
12168 unsigned char head,tail;
12169 \newline
12170 #define USE_ASSEMBLY (1)
12171 \newline
12172
12173 \newline
12174 #if !USE_ASSEMBLY
12175 \newline
12176
12177 \newline
12178 void to_buffer( unsigned char c )
12179 \newline
12180 {
12181 \newline
12182 \SpecialChar ~
12183 \SpecialChar ~
12184 \SpecialChar ~
12185 \SpecialChar ~
12186 if( head != tail-1 )
12187 \newline
12188 \SpecialChar ~
12189 \SpecialChar ~
12190 \SpecialChar ~
12191 \SpecialChar ~
12192 \SpecialChar ~
12193 \SpecialChar ~
12194 \SpecialChar ~
12195 \SpecialChar ~
12196 buf[ head++ ] = c;
12197 \newline
12198 }
12199 \newline
12200
12201 \newline
12202 #else
12203 \newline
12204
12205 \newline
12206 void to_buffer( unsigned char c )
12207 \newline
12208 {
12209 \newline
12210 \SpecialChar ~
12211 \SpecialChar ~
12212 \SpecialChar ~
12213 \SpecialChar ~
12214 c; // to avoid warning: unreferenced function argument
12215 \newline
12216 \SpecialChar ~
12217 \SpecialChar ~
12218 \SpecialChar ~
12219 \SpecialChar ~
12220 _asm
12221 \begin_inset LatexCommand \index{\_asm}
12222
12223 \end_inset
12224
12225
12226 \begin_inset LatexCommand \index{\_\_asm}
12227
12228 \end_inset
12229
12230
12231 \newline
12232 \SpecialChar ~
12233 \SpecialChar ~
12234 \SpecialChar ~
12235 \SpecialChar ~
12236 \SpecialChar ~
12237 \SpecialChar ~
12238 \SpecialChar ~
12239 \SpecialChar ~
12240 ; save used registers here.
12241
12242 \newline
12243 \SpecialChar ~
12244 \SpecialChar ~
12245 \SpecialChar ~
12246 \SpecialChar ~
12247 \SpecialChar ~
12248 \SpecialChar ~
12249 \SpecialChar ~
12250 \SpecialChar ~
12251 ; If we were still using r2,r3 we would have to push them here.
12252
12253 \newline
12254 ; if( head != tail-1 )
12255 \newline
12256 \SpecialChar ~
12257 \SpecialChar ~
12258 \SpecialChar ~
12259 \SpecialChar ~
12260 \SpecialChar ~
12261 \SpecialChar ~
12262 \SpecialChar ~
12263 \SpecialChar ~
12264 mov\SpecialChar ~
12265  a,_tail
12266 \newline
12267 \SpecialChar ~
12268 \SpecialChar ~
12269 \SpecialChar ~
12270 \SpecialChar ~
12271 \SpecialChar ~
12272 \SpecialChar ~
12273 \SpecialChar ~
12274 \SpecialChar ~
12275 dec\SpecialChar ~
12276  a
12277 \newline
12278 \SpecialChar ~
12279 \SpecialChar ~
12280 \SpecialChar ~
12281 \SpecialChar ~
12282 \SpecialChar ~
12283 \SpecialChar ~
12284 \SpecialChar ~
12285 \SpecialChar ~
12286 xrl\SpecialChar ~
12287  a,_head
12288 \newline
12289 \SpecialChar ~
12290 \SpecialChar ~
12291 \SpecialChar ~
12292 \SpecialChar ~
12293 \SpecialChar ~
12294 \SpecialChar ~
12295 \SpecialChar ~
12296 \SpecialChar ~
12297 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
12298 \newline
12299 \SpecialChar ~
12300 \SpecialChar ~
12301 \SpecialChar ~
12302 \SpecialChar ~
12303 \SpecialChar ~
12304 \SpecialChar ~
12305 \SpecialChar ~
12306 \SpecialChar ~
12307 jz\SpecialChar ~
12308 \SpecialChar ~
12309  t_b_end$
12310 \newline
12311 \SpecialChar ~
12312 \SpecialChar ~
12313 \SpecialChar ~
12314 \SpecialChar ~
12315 \SpecialChar ~
12316 \SpecialChar ~
12317 \SpecialChar ~
12318 \SpecialChar ~
12319 ;
12320 \newline
12321 ; buf[ head++ ] = c;
12322 \newline
12323 \SpecialChar ~
12324 \SpecialChar ~
12325 \SpecialChar ~
12326 \SpecialChar ~
12327 \SpecialChar ~
12328 \SpecialChar ~
12329 \SpecialChar ~
12330 \SpecialChar ~
12331 mov\SpecialChar ~
12332  a,dpl \SpecialChar ~
12333 \SpecialChar ~
12334 \SpecialChar ~
12335 \SpecialChar ~
12336 \SpecialChar ~
12337 \SpecialChar ~
12338 \SpecialChar ~
12339 ; dpl holds lower byte of function argument
12340 \newline
12341 \SpecialChar ~
12342 \SpecialChar ~
12343 \SpecialChar ~
12344 \SpecialChar ~
12345 \SpecialChar ~
12346 \SpecialChar ~
12347 \SpecialChar ~
12348 \SpecialChar ~
12349 mov\SpecialChar ~
12350  dpl,_head \SpecialChar ~
12351 \SpecialChar ~
12352 \SpecialChar ~
12353 ; buf is 0x100 byte aligned so head can be used directly
12354 \newline
12355 \SpecialChar ~
12356 \SpecialChar ~
12357 \SpecialChar ~
12358 \SpecialChar ~
12359 \SpecialChar ~
12360 \SpecialChar ~
12361 \SpecialChar ~
12362 \SpecialChar ~
12363 mov\SpecialChar ~
12364  dph,#(_buf>>8)
12365 \newline
12366 \SpecialChar ~
12367 \SpecialChar ~
12368 \SpecialChar ~
12369 \SpecialChar ~
12370 \SpecialChar ~
12371 \SpecialChar ~
12372 \SpecialChar ~
12373 \SpecialChar ~
12374 movx @dptr,a
12375 \newline
12376 \SpecialChar ~
12377 \SpecialChar ~
12378 \SpecialChar ~
12379 \SpecialChar ~
12380 \SpecialChar ~
12381 \SpecialChar ~
12382 \SpecialChar ~
12383 \SpecialChar ~
12384 inc \SpecialChar ~
12385 _head
12386 \newline
12387 \SpecialChar ~
12388 \SpecialChar ~
12389 \SpecialChar ~
12390 \SpecialChar ~
12391 \SpecialChar ~
12392 \SpecialChar ~
12393 \SpecialChar ~
12394 \SpecialChar ~
12395 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
12396 \newline
12397 t_b_end$:
12398 \newline
12399 \SpecialChar ~
12400 \SpecialChar ~
12401 \SpecialChar ~
12402 \SpecialChar ~
12403 \SpecialChar ~
12404 \SpecialChar ~
12405 \SpecialChar ~
12406 \SpecialChar ~
12407 ; restore used registers here
12408 \newline
12409 \SpecialChar ~
12410 \SpecialChar ~
12411 \SpecialChar ~
12412 \SpecialChar ~
12413 _endasm
12414 \begin_inset LatexCommand \index{\_endasm}
12415
12416 \end_inset
12417
12418
12419 \begin_inset LatexCommand \index{\_\_endasm}
12420
12421 \end_inset
12422
12423 ;
12424 \newline
12425 }
12426 \newline
12427 #endif
12428 \layout Standard
12429
12430 The inline assembler code can contain any valid code understood by the assembler
12431 , this includes any assembler directives and comment lines
12432 \begin_inset Foot
12433 collapsed false
12434
12435 \layout Standard
12436
12437 The assembler does not like some characters like ':' or ''' in comments.
12438  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
12439 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
12440
12441 \end_inset
12442
12443
12444 \begin_inset LatexCommand \index{Assembler documentation}
12445
12446 \end_inset
12447
12448
12449 \end_inset
12450
12451 .
12452  The compiler does not do any validation of the code within the
12453 \family typewriter
12454 _asm
12455 \begin_inset LatexCommand \index{\_asm}
12456
12457 \end_inset
12458
12459
12460 \begin_inset LatexCommand \index{\_\_asm}
12461
12462 \end_inset
12463
12464  ...
12465  _endasm
12466 \size footnotesize
12467
12468 \begin_inset LatexCommand \index{\_endasm}
12469
12470 \end_inset
12471
12472
12473 \begin_inset LatexCommand \index{\_\_endasm}
12474
12475 \end_inset
12476
12477
12478 \size default
12479 ;
12480 \family default
12481  keyword pair.
12482  Specifically it will not know which registers are used and thus register
12483  pushing/popping
12484 \begin_inset LatexCommand \index{push/pop}
12485
12486 \end_inset
12487
12488  has to be done manually.
12489
12490 \layout Standard
12491
12492 It is recommended that each assembly instruction (including labels) be placed
12493  in a separate line (as the example shows).
12494  When the -
12495 \begin_inset ERT
12496 status Collapsed
12497
12498 \layout Standard
12499
12500 \backslash
12501 /
12502 \end_inset
12503
12504 -
12505 \emph on
12506 peep-asm
12507 \begin_inset LatexCommand \index{-\/-peep-asm}
12508
12509 \end_inset
12510
12511
12512 \emph default
12513  command line option is used, the inline assembler code will be passed through
12514  the peephole optimizer
12515 \begin_inset LatexCommand \index{Peephole optimizer}
12516
12517 \end_inset
12518
12519 .
12520  There are only a few (if any) cases where this option makes sense, it might
12521  cause some unexpected changes in the inline assembler code.
12522  Please go through the peephole optimizer rules defined in file
12523 \emph on
12524 SDCCpeeph.def
12525 \emph default
12526  before using this option.
12527 \layout Subsection
12528
12529 Naked Functions
12530 \begin_inset LatexCommand \label{sub:Naked-Functions}
12531
12532 \end_inset
12533
12534
12535 \begin_inset LatexCommand \index{Naked functions}
12536
12537 \end_inset
12538
12539
12540 \layout Standard
12541
12542 A special keyword may be associated with a function declaring it as
12543 \emph on
12544 _naked
12545 \begin_inset LatexCommand \index{\_naked}
12546
12547 \end_inset
12548
12549
12550 \begin_inset LatexCommand \index{\_\_naked}
12551
12552 \end_inset
12553
12554 .
12555
12556 \emph default
12557 The
12558 \emph on
12559 _naked
12560 \emph default
12561  function modifier attribute prevents the compiler from generating prologue
12562 \begin_inset LatexCommand \index{function prologue}
12563
12564 \end_inset
12565
12566  and epilogue
12567 \begin_inset LatexCommand \index{function epilogue}
12568
12569 \end_inset
12570
12571  code for that function.
12572  This means that the user is entirely responsible for such things as saving
12573  any registers that may need to be preserved, selecting the proper register
12574  bank, generating the
12575 \emph on
12576 return
12577 \emph default
12578  instruction at the end, etc.
12579  Practically, this means that the contents of the function must be written
12580  in inline assembler.
12581  This is particularly useful for interrupt functions, which can have a large
12582  (and often unnecessary) prologue/epilogue.
12583  For example, compare the code generated by these two functions:
12584 \layout Verse
12585
12586
12587 \family typewriter
12588 volatile
12589 \begin_inset LatexCommand \index{volatile}
12590
12591 \end_inset
12592
12593  data unsigned char counter;
12594 \newline
12595
12596 \newline
12597 void simpleInterrupt(void) interrupt
12598 \begin_inset LatexCommand \index{interrupt}
12599
12600 \end_inset
12601
12602
12603 \begin_inset LatexCommand \index{\_\_interrupt}
12604
12605 \end_inset
12606
12607  1
12608 \newline
12609 {
12610 \newline
12611 \SpecialChar ~
12612 \SpecialChar ~
12613 \SpecialChar ~
12614 \SpecialChar ~
12615 counter++;
12616 \newline
12617 }
12618 \newline
12619
12620 \newline
12621 void nakedInterrupt(void) interrupt 2 _naked
12622 \newline
12623 {
12624 \newline
12625 \SpecialChar ~
12626 \SpecialChar ~
12627 \SpecialChar ~
12628 \SpecialChar ~
12629 _asm
12630 \begin_inset LatexCommand \index{\_asm}
12631
12632 \end_inset
12633
12634
12635 \begin_inset LatexCommand \index{\_\_asm}
12636
12637 \end_inset
12638
12639
12640 \newline
12641 \SpecialChar ~
12642 \SpecialChar ~
12643 \SpecialChar ~
12644 \SpecialChar ~
12645 \SpecialChar ~
12646 \SpecialChar ~
12647 inc\SpecialChar ~
12648 \SpecialChar ~
12649 \SpecialChar ~
12650 \SpecialChar ~
12651 \SpecialChar ~
12652 _counter ; does not change flags, no need to save psw
12653 \newline
12654 \SpecialChar ~
12655 \SpecialChar ~
12656 \SpecialChar ~
12657 \SpecialChar ~
12658 \SpecialChar ~
12659 \SpecialChar ~
12660 reti\SpecialChar ~
12661 \SpecialChar ~
12662 \SpecialChar ~
12663 \SpecialChar ~
12664 ; MUST explicitly include ret or reti in _naked function.
12665 \newline
12666 \SpecialChar ~
12667 \SpecialChar ~
12668 \SpecialChar ~
12669 \SpecialChar ~
12670 _endasm
12671 \begin_inset LatexCommand \index{\_endasm}
12672
12673 \end_inset
12674
12675
12676 \begin_inset LatexCommand \index{\_\_endasm}
12677
12678 \end_inset
12679
12680 ;
12681 \newline
12682 }
12683 \layout Standard
12684
12685 For an 8051 target, the generated simpleInterrupt looks like:
12686 \layout Verse
12687
12688
12689 \family typewriter
12690 _simpleInterrupt:
12691 \newline
12692 \SpecialChar ~
12693 \SpecialChar ~
12694 \SpecialChar ~
12695 \SpecialChar ~
12696 push\SpecialChar ~
12697 \SpecialChar ~
12698 \SpecialChar ~
12699 \SpecialChar ~
12700 acc
12701 \newline
12702 \SpecialChar ~
12703 \SpecialChar ~
12704 \SpecialChar ~
12705 \SpecialChar ~
12706 push\SpecialChar ~
12707 \SpecialChar ~
12708 \SpecialChar ~
12709 \SpecialChar ~
12710 b
12711 \newline
12712 \SpecialChar ~
12713 \SpecialChar ~
12714 \SpecialChar ~
12715 \SpecialChar ~
12716 push\SpecialChar ~
12717 \SpecialChar ~
12718 \SpecialChar ~
12719 \SpecialChar ~
12720 dpl
12721 \newline
12722 \SpecialChar ~
12723 \SpecialChar ~
12724 \SpecialChar ~
12725 \SpecialChar ~
12726 push\SpecialChar ~
12727 \SpecialChar ~
12728 \SpecialChar ~
12729 \SpecialChar ~
12730 dph
12731 \newline
12732 \SpecialChar ~
12733 \SpecialChar ~
12734 \SpecialChar ~
12735 \SpecialChar ~
12736 push\SpecialChar ~
12737 \SpecialChar ~
12738 \SpecialChar ~
12739 \SpecialChar ~
12740 psw
12741 \newline
12742 \SpecialChar ~
12743 \SpecialChar ~
12744 \SpecialChar ~
12745 \SpecialChar ~
12746 mov\SpecialChar ~
12747 \SpecialChar ~
12748 \SpecialChar ~
12749 \SpecialChar ~
12750 \SpecialChar ~
12751 psw,#0x00
12752 \newline
12753 \SpecialChar ~
12754 \SpecialChar ~
12755 \SpecialChar ~
12756 \SpecialChar ~
12757 inc\SpecialChar ~
12758 \SpecialChar ~
12759 \SpecialChar ~
12760 \SpecialChar ~
12761 \SpecialChar ~
12762 _counter
12763 \newline
12764 \SpecialChar ~
12765 \SpecialChar ~
12766 \SpecialChar ~
12767 \SpecialChar ~
12768 pop\SpecialChar ~
12769 \SpecialChar ~
12770 \SpecialChar ~
12771 \SpecialChar ~
12772 \SpecialChar ~
12773 psw
12774 \newline
12775 \SpecialChar ~
12776 \SpecialChar ~
12777 \SpecialChar ~
12778 \SpecialChar ~
12779 pop\SpecialChar ~
12780 \SpecialChar ~
12781 \SpecialChar ~
12782 \SpecialChar ~
12783 \SpecialChar ~
12784 dph
12785 \newline
12786 \SpecialChar ~
12787 \SpecialChar ~
12788 \SpecialChar ~
12789 \SpecialChar ~
12790 pop\SpecialChar ~
12791 \SpecialChar ~
12792 \SpecialChar ~
12793 \SpecialChar ~
12794 \SpecialChar ~
12795 dpl
12796 \newline
12797 \SpecialChar ~
12798 \SpecialChar ~
12799 \SpecialChar ~
12800 \SpecialChar ~
12801 pop\SpecialChar ~
12802 \SpecialChar ~
12803 \SpecialChar ~
12804 \SpecialChar ~
12805 \SpecialChar ~
12806 b
12807 \newline
12808 \SpecialChar ~
12809 \SpecialChar ~
12810 \SpecialChar ~
12811 \SpecialChar ~
12812 pop\SpecialChar ~
12813 \SpecialChar ~
12814 \SpecialChar ~
12815 \SpecialChar ~
12816 \SpecialChar ~
12817 acc
12818 \newline
12819 \SpecialChar ~
12820 \SpecialChar ~
12821 \SpecialChar ~
12822 \SpecialChar ~
12823 reti
12824 \layout Standard
12825
12826 whereas nakedInterrupt looks like:
12827 \layout Verse
12828
12829
12830 \family typewriter
12831 _nakedInterrupt:
12832 \newline
12833 \SpecialChar ~
12834 \SpecialChar ~
12835 \SpecialChar ~
12836 \SpecialChar ~
12837 inc\SpecialChar ~
12838 \SpecialChar ~
12839 \SpecialChar ~
12840 \SpecialChar ~
12841 _counter ; does not change flags, no need to save psw
12842 \newline
12843 \SpecialChar ~
12844 \SpecialChar ~
12845 \SpecialChar ~
12846 \SpecialChar ~
12847 reti\SpecialChar ~
12848 \SpecialChar ~
12849 \SpecialChar ~
12850 \SpecialChar ~
12851 \SpecialChar ~
12852 \SpecialChar ~
12853 \SpecialChar ~
12854 \SpecialChar ~
12855 \SpecialChar ~
12856 \SpecialChar ~
12857 \SpecialChar ~
12858 \SpecialChar ~
12859 ; MUST explicitly include ret or reti in _naked function
12860 \layout Standard
12861
12862 The related directive #pragma exclude
12863 \begin_inset LatexCommand \index{\#pragma exclude}
12864
12865 \end_inset
12866
12867  allows a more fine grained control over pushing & popping
12868 \begin_inset LatexCommand \index{push/pop}
12869
12870 \end_inset
12871
12872  the registers.
12873 \layout Standard
12874
12875 While there is nothing preventing you from writing C code inside a
12876 \family typewriter
12877 _naked
12878 \family default
12879  function, there are many ways to shoot yourself in the foot doing this,
12880  and it is recommended that you stick to inline assembler.
12881 \layout Subsection
12882
12883 Use of Labels within Inline Assembler
12884 \layout Standard
12885
12886 SDCC allows the use of in-line assembler with a few restrictions regarding
12887  labels.
12888  In older versions of the compiler all labels defined within inline assembler
12889  code
12890 \emph on
12891 had to be
12892 \emph default
12893  of the form
12894 \emph on
12895 nnnnn$
12896 \emph default
12897  where nnnn is a number less than 100 (which implies a limit of utmost 100
12898  inline assembler labels
12899 \emph on
12900 per function
12901 \emph default
12902 \noun on
12903 )
12904 \noun default
12905 .
12906
12907 \layout Verse
12908
12909
12910 \family typewriter
12911 _asm
12912 \begin_inset LatexCommand \index{\_asm}
12913
12914 \end_inset
12915
12916
12917 \begin_inset LatexCommand \index{\_\_asm}
12918
12919 \end_inset
12920
12921
12922 \newline
12923 \SpecialChar ~
12924 \SpecialChar ~
12925 \SpecialChar ~
12926 \SpecialChar ~
12927 mov\SpecialChar ~
12928 \SpecialChar ~
12929 \SpecialChar ~
12930 \SpecialChar ~
12931 \SpecialChar ~
12932 b,#10
12933 \newline
12934 00001$:
12935 \newline
12936 \SpecialChar ~
12937 \SpecialChar ~
12938 \SpecialChar ~
12939 \SpecialChar ~
12940 djnz\SpecialChar ~
12941 \SpecialChar ~
12942 \SpecialChar ~
12943 \SpecialChar ~
12944 b,00001$
12945 \newline
12946 _endasm
12947 \begin_inset LatexCommand \index{\_endasm}
12948
12949 \end_inset
12950
12951
12952 \begin_inset LatexCommand \index{\_\_endasm}
12953
12954 \end_inset
12955
12956  ;
12957 \layout Standard
12958
12959 Inline assembler code cannot reference any C-Labels, however it can reference
12960  labels
12961 \begin_inset LatexCommand \index{Labels}
12962
12963 \end_inset
12964
12965  defined by the inline assembler, e.g.:
12966 \layout Verse
12967
12968
12969 \family typewriter
12970 foo() {
12971 \newline
12972 \SpecialChar ~
12973 \SpecialChar ~
12974 \SpecialChar ~
12975 \SpecialChar ~
12976 /* some c code */
12977 \newline
12978 \SpecialChar ~
12979 \SpecialChar ~
12980 \SpecialChar ~
12981 \SpecialChar ~
12982 _asm
12983 \newline
12984 \SpecialChar ~
12985 \SpecialChar ~
12986 \SpecialChar ~
12987 \SpecialChar ~
12988 \SpecialChar ~
12989 \SpecialChar ~
12990 ; some assembler code
12991 \newline
12992 \SpecialChar ~
12993 \SpecialChar ~
12994 \SpecialChar ~
12995 \SpecialChar ~
12996 \SpecialChar ~
12997 \SpecialChar ~
12998 ljmp $0003
12999 \newline
13000 \SpecialChar ~
13001 \SpecialChar ~
13002 \SpecialChar ~
13003 \SpecialChar ~
13004 _endasm;
13005 \newline
13006 \SpecialChar ~
13007 \SpecialChar ~
13008 \SpecialChar ~
13009 \SpecialChar ~
13010 /* some more c code */
13011 \newline
13012 clabel:\SpecialChar ~
13013 \SpecialChar ~
13014 /* inline assembler cannot reference this label */
13015 \newline
13016 \SpecialChar ~
13017 \SpecialChar ~
13018 \SpecialChar ~
13019 \SpecialChar ~
13020 _asm
13021 \newline
13022 \SpecialChar ~
13023 \SpecialChar ~
13024 \SpecialChar ~
13025 \SpecialChar ~
13026 $0003: ;label (can be referenced by inline assembler only)
13027 \newline
13028 \SpecialChar ~
13029 \SpecialChar ~
13030 \SpecialChar ~
13031 \SpecialChar ~
13032 _endasm
13033 \begin_inset LatexCommand \index{\_endasm}
13034
13035 \end_inset
13036
13037
13038 \begin_inset LatexCommand \index{\_\_endasm}
13039
13040 \end_inset
13041
13042  ;
13043 \newline
13044 \SpecialChar ~
13045 \SpecialChar ~
13046 \SpecialChar ~
13047 \SpecialChar ~
13048 /* some more c code */
13049 \newline
13050 }
13051 \layout Standard
13052
13053 In other words inline assembly code can access labels defined in inline
13054  assembly within the scope of the function.
13055  The same goes the other way, i.e.
13056  labels defines in inline assembly can not be accessed by C statements.
13057 \layout Section
13058
13059 Interfacing with Assembler Code
13060 \begin_inset LatexCommand \index{Assembler routines}
13061
13062 \end_inset
13063
13064
13065 \layout Subsection
13066
13067 Global Registers used for Parameter Passing
13068 \begin_inset LatexCommand \index{Parameter passing}
13069
13070 \end_inset
13071
13072
13073 \layout Standard
13074
13075 The compiler always uses the global registers
13076 \emph on
13077 DPL, DPH
13078 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
13079
13080 \end_inset
13081
13082
13083 \begin_inset LatexCommand \index{DPTR}
13084
13085 \end_inset
13086
13087 , B
13088 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
13089
13090 \end_inset
13091
13092
13093 \emph default
13094 and
13095 \emph on
13096  ACC
13097 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
13098
13099 \end_inset
13100
13101
13102 \emph default
13103  to pass the first parameter to a routine.
13104  The second parameter onwards is either allocated on the stack (for reentrant
13105  routines or if -
13106 \begin_inset ERT
13107 status Collapsed
13108
13109 \layout Standard
13110
13111 \backslash
13112 /
13113 \end_inset
13114
13115 -stack-auto is used) or in data / xdata memory (depending on the memory
13116  model).
13117
13118 \layout Subsection
13119
13120 Assembler Routine (non-reentrant)
13121 \layout Standard
13122
13123 In the following example
13124 \begin_inset LatexCommand \index{reentrant}
13125
13126 \end_inset
13127
13128
13129 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
13130
13131 \end_inset
13132
13133  the function c_func calls an assembler routine asm_func, which takes two
13134  parameters
13135 \begin_inset LatexCommand \index{function parameter}
13136
13137 \end_inset
13138
13139 .
13140 \layout Verse
13141
13142
13143 \family typewriter
13144 extern int asm_func(unsigned char, unsigned char);
13145 \newline
13146
13147 \newline
13148 int c_func (unsigned char i, unsigned char j)
13149 \newline
13150 {
13151 \newline
13152 \SpecialChar ~
13153 \SpecialChar ~
13154 \SpecialChar ~
13155 \SpecialChar ~
13156 return asm_func(i,j);
13157 \newline
13158 }
13159 \newline
13160
13161 \newline
13162 int main()
13163 \newline
13164 {
13165 \newline
13166 \SpecialChar ~
13167 \SpecialChar ~
13168 \SpecialChar ~
13169 \SpecialChar ~
13170 return c_func(10,9);
13171 \newline
13172 }
13173 \layout Standard
13174
13175 The corresponding assembler function is:
13176 \layout Verse
13177
13178
13179 \family typewriter
13180 .globl _asm_func_PARM_2
13181 \newline
13182 \SpecialChar ~
13183 \SpecialChar ~
13184 \SpecialChar ~
13185 \SpecialChar ~
13186 \SpecialChar ~
13187 \SpecialChar ~
13188 \SpecialChar ~
13189 \SpecialChar ~
13190 .globl _asm_func
13191 \newline
13192 \SpecialChar ~
13193 \SpecialChar ~
13194 \SpecialChar ~
13195 \SpecialChar ~
13196 \SpecialChar ~
13197 \SpecialChar ~
13198 \SpecialChar ~
13199 \SpecialChar ~
13200 .area OSEG
13201 \newline
13202 _asm_func_PARM_2:
13203 \newline
13204 \SpecialChar ~
13205 \SpecialChar ~
13206 \SpecialChar ~
13207 \SpecialChar ~
13208 \SpecialChar ~
13209 \SpecialChar ~
13210 \SpecialChar ~
13211 \SpecialChar ~
13212 .ds    1
13213 \newline
13214 \SpecialChar ~
13215 \SpecialChar ~
13216 \SpecialChar ~
13217 \SpecialChar ~
13218 \SpecialChar ~
13219 \SpecialChar ~
13220 \SpecialChar ~
13221 \SpecialChar ~
13222 .area CSEG
13223 \newline
13224 _asm_func:
13225 \newline
13226 \SpecialChar ~
13227 \SpecialChar ~
13228 \SpecialChar ~
13229 \SpecialChar ~
13230 \SpecialChar ~
13231 \SpecialChar ~
13232 \SpecialChar ~
13233 \SpecialChar ~
13234 mov\SpecialChar ~
13235 \SpecialChar ~
13236 \SpecialChar ~
13237 \SpecialChar ~
13238 a,dpl
13239 \newline
13240 \SpecialChar ~
13241 \SpecialChar ~
13242 \SpecialChar ~
13243 \SpecialChar ~
13244 \SpecialChar ~
13245 \SpecialChar ~
13246 \SpecialChar ~
13247 \SpecialChar ~
13248 add\SpecialChar ~
13249 \SpecialChar ~
13250 \SpecialChar ~
13251 \SpecialChar ~
13252 a,_asm_func_PARM_2
13253 \newline
13254 \SpecialChar ~
13255 \SpecialChar ~
13256 \SpecialChar ~
13257 \SpecialChar ~
13258 \SpecialChar ~
13259 \SpecialChar ~
13260 \SpecialChar ~
13261 \SpecialChar ~
13262 mov\SpecialChar ~
13263 \SpecialChar ~
13264 \SpecialChar ~
13265 \SpecialChar ~
13266 dpl,a
13267 \newline
13268 \SpecialChar ~
13269 \SpecialChar ~
13270 \SpecialChar ~
13271 \SpecialChar ~
13272 \SpecialChar ~
13273 \SpecialChar ~
13274 \SpecialChar ~
13275 \SpecialChar ~
13276 mov\SpecialChar ~
13277 \SpecialChar ~
13278 \SpecialChar ~
13279 \SpecialChar ~
13280 dph
13281 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
13282
13283 \end_inset
13284
13285 ,#0x00
13286 \newline
13287 \SpecialChar ~
13288 \SpecialChar ~
13289 \SpecialChar ~
13290 \SpecialChar ~
13291 \SpecialChar ~
13292 \SpecialChar ~
13293 \SpecialChar ~
13294 \SpecialChar ~
13295 ret
13296 \layout Standard
13297
13298 Note here that the return values
13299 \begin_inset LatexCommand \index{return value}
13300
13301 \end_inset
13302
13303  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
13304  two byte values.
13305  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
13306 b' & 'acc' for four byte values.
13307 \layout Standard
13308
13309 The parameter naming convention is _<function_name>_PARM_<n>, where n is
13310  the parameter number starting from 1, and counting from the left.
13311  The first parameter is passed in
13312 \begin_inset Quotes eld
13313 \end_inset
13314
13315 dpl
13316 \begin_inset Quotes erd
13317 \end_inset
13318
13319  for a one byte parameter,
13320 \begin_inset Quotes eld
13321 \end_inset
13322
13323 dptr
13324 \begin_inset Quotes erd
13325 \end_inset
13326
13327  for two bytes,
13328 \begin_inset Quotes eld
13329 \end_inset
13330
13331 b,dptr
13332 \begin_inset Quotes erd
13333 \end_inset
13334
13335  for three bytes and
13336 \begin_inset Quotes eld
13337 \end_inset
13338
13339 acc,b,dptr
13340 \begin_inset Quotes erd
13341 \end_inset
13342
13343  for a four bytes parameter.
13344  The variable name for the second parameter will be _<function_name>_PARM_2.
13345 \newline
13346
13347 \newline
13348 Assemble the assembler routine with the following command:
13349 \newline
13350
13351 \newline
13352
13353 \family sans
13354 \series bold
13355 asx8051 -losg asmfunc.asm
13356 \newline
13357
13358 \newline
13359
13360 \family default
13361 \series default
13362 Then compile and link the assembler routine to the C source file with the
13363  following command:
13364 \newline
13365
13366 \newline
13367
13368 \family sans
13369 \series bold
13370 sdcc cfunc.c asmfunc.rel
13371 \layout Subsection
13372
13373 Assembler Routine (reentrant)
13374 \layout Standard
13375
13376 In this case
13377 \begin_inset LatexCommand \index{reentrant}
13378
13379 \end_inset
13380
13381
13382 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
13383
13384 \end_inset
13385
13386  the second parameter
13387 \begin_inset LatexCommand \index{function parameter}
13388
13389 \end_inset
13390
13391  onwards will be passed on the stack, the parameters are pushed from right
13392  to left i.e.
13393  after the call the leftmost parameter will be on the top of the stack.
13394  Here is an example:
13395 \layout Verse
13396
13397
13398 \family typewriter
13399 extern int asm_func(unsigned char, unsigned char);
13400 \newline
13401
13402 \newline
13403 int c_func (unsigned char i, unsigned char j) reentrant
13404 \newline
13405 {
13406 \newline
13407 \SpecialChar ~
13408 \SpecialChar ~
13409 \SpecialChar ~
13410 \SpecialChar ~
13411 return asm_func(i,j);
13412 \newline
13413 }
13414 \newline
13415
13416 \newline
13417 int main()
13418 \newline
13419 {
13420 \newline
13421 \SpecialChar ~
13422 \SpecialChar ~
13423 \SpecialChar ~
13424 \SpecialChar ~
13425 return c_func(10,9);
13426 \newline
13427 }
13428 \layout Standard
13429
13430 The corresponding assembler routine is:
13431 \layout Verse
13432
13433
13434 \family typewriter
13435 .globl _asm_func
13436 \newline
13437 _asm_func:
13438 \newline
13439 \SpecialChar ~
13440 \SpecialChar ~
13441 \SpecialChar ~
13442 \SpecialChar ~
13443 push  _bp
13444 \newline
13445 \SpecialChar ~
13446 \SpecialChar ~
13447 \SpecialChar ~
13448 \SpecialChar ~
13449 mov _bp,sp
13450 \newline
13451 \SpecialChar ~
13452 \SpecialChar ~
13453 \SpecialChar ~
13454 \SpecialChar ~
13455 mov r2,dpl
13456 \newline
13457 \SpecialChar ~
13458 \SpecialChar ~
13459 \SpecialChar ~
13460 \SpecialChar ~
13461 mov a,_bp
13462 \newline
13463 \SpecialChar ~
13464 \SpecialChar ~
13465 \SpecialChar ~
13466 \SpecialChar ~
13467 add a,#0xfd
13468 \newline
13469 \SpecialChar ~
13470 \SpecialChar ~
13471 \SpecialChar ~
13472 \SpecialChar ~
13473 mov r0,a
13474 \newline
13475 \SpecialChar ~
13476 \SpecialChar ~
13477 \SpecialChar ~
13478 \SpecialChar ~
13479 add  a,#0xfc ;?
13480 \newline
13481 \SpecialChar ~
13482 \SpecialChar ~
13483 \SpecialChar ~
13484 \SpecialChar ~
13485 mov  r1,a
13486 \newline
13487 \SpecialChar ~
13488 \SpecialChar ~
13489 \SpecialChar ~
13490 \SpecialChar ~
13491 mov  a,@r0
13492 \newline
13493 \SpecialChar ~
13494 \SpecialChar ~
13495 \SpecialChar ~
13496 \SpecialChar ~
13497 add  a,r2 ;?
13498 \newline
13499 \SpecialChar ~
13500 \SpecialChar ~
13501 \SpecialChar ~
13502 \SpecialChar ~
13503 mov  dpl,a
13504 \newline
13505 \SpecialChar ~
13506 \SpecialChar ~
13507 \SpecialChar ~
13508 \SpecialChar ~
13509 mov  dph,#0x00
13510 \newline
13511 \SpecialChar ~
13512 \SpecialChar ~
13513 \SpecialChar ~
13514 \SpecialChar ~
13515 mov  sp,_bp
13516 \newline
13517 \SpecialChar ~
13518 \SpecialChar ~
13519 \SpecialChar ~
13520 \SpecialChar ~
13521 pop  _bp
13522 \newline
13523 \SpecialChar ~
13524 \SpecialChar ~
13525 \SpecialChar ~
13526 \SpecialChar ~
13527 ret
13528 \layout Standard
13529
13530 The compiling and linking procedure remains the same, however note the extra
13531  entry & exit linkage required for the assembler code, _bp is the stack
13532  frame pointer and is used to compute the offset into the stack for parameters
13533  and local variables.
13534 \layout Section
13535
13536 int (16 bit)
13537 \begin_inset LatexCommand \index{int (16 bit)}
13538
13539 \end_inset
13540
13541  and long (32 bit)
13542 \begin_inset LatexCommand \index{long (32 bit)}
13543
13544 \end_inset
13545
13546  Support
13547 \layout Standard
13548
13549 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
13550  multiplication and modulus operations are implemented by support routines.
13551  These support routines are all developed in ANSI-C to facilitate porting
13552  to other MCUs, although some model specific assembler optimizations are
13553  used.
13554  The following files contain the described routines, all of them can be
13555  found in <installdir>/share/sdcc/lib.
13556 \newline
13557
13558 \layout Standard
13559 \align center
13560
13561 \begin_inset  Tabular
13562 <lyxtabular version="3" rows="11" columns="2">
13563 <features>
13564 <column alignment="center" valignment="top" leftline="true" width="0">
13565 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
13566 <row topline="true" bottomline="true">
13567 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13568 \begin_inset Text
13569
13570 \layout Standard
13571
13572
13573 \series bold
13574 Function
13575 \end_inset
13576 </cell>
13577 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13578 \begin_inset Text
13579
13580 \layout Standard
13581
13582
13583 \series bold
13584 Description
13585 \end_inset
13586 </cell>
13587 </row>
13588 <row topline="true">
13589 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13590 \begin_inset Text
13591
13592 \layout Standard
13593
13594 _mulint.c
13595 \end_inset
13596 </cell>
13597 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13598 \begin_inset Text
13599
13600 \layout Standard
13601
13602 16 bit multiplication
13603 \end_inset
13604 </cell>
13605 </row>
13606 <row topline="true">
13607 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13608 \begin_inset Text
13609
13610 \layout Standard
13611
13612 _divsint.c
13613 \end_inset
13614 </cell>
13615 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13616 \begin_inset Text
13617
13618 \layout Standard
13619
13620  signed 16 bit division (calls _divuint)
13621 \end_inset
13622 </cell>
13623 </row>
13624 <row topline="true">
13625 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13626 \begin_inset Text
13627
13628 \layout Standard
13629
13630 _divuint.c
13631 \end_inset
13632 </cell>
13633 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13634 \begin_inset Text
13635
13636 \layout Standard
13637
13638  unsigned 16 bit division
13639 \end_inset
13640 </cell>
13641 </row>
13642 <row topline="true">
13643 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13644 \begin_inset Text
13645
13646 \layout Standard
13647
13648 _modsint.c
13649 \end_inset
13650 </cell>
13651 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13652 \begin_inset Text
13653
13654 \layout Standard
13655
13656 signed 16 bit modulus (calls _moduint)
13657 \end_inset
13658 </cell>
13659 </row>
13660 <row topline="true">
13661 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13662 \begin_inset Text
13663
13664 \layout Standard
13665
13666 _moduint.c
13667 \end_inset
13668 </cell>
13669 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13670 \begin_inset Text
13671
13672 \layout Standard
13673
13674 unsigned 16 bit modulus
13675 \end_inset
13676 </cell>
13677 </row>
13678 <row topline="true">
13679 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13680 \begin_inset Text
13681
13682 \layout Standard
13683
13684 _mullong.c
13685 \end_inset
13686 </cell>
13687 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13688 \begin_inset Text
13689
13690 \layout Standard
13691
13692 32 bit multiplication
13693 \end_inset
13694 </cell>
13695 </row>
13696 <row topline="true">
13697 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13698 \begin_inset Text
13699
13700 \layout Standard
13701
13702 _divslong.c
13703 \end_inset
13704 </cell>
13705 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13706 \begin_inset Text
13707
13708 \layout Standard
13709
13710  signed 32 division (calls _divulong)
13711 \end_inset
13712 </cell>
13713 </row>
13714 <row topline="true">
13715 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13716 \begin_inset Text
13717
13718 \layout Standard
13719
13720 _divulong.c
13721 \end_inset
13722 </cell>
13723 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13724 \begin_inset Text
13725
13726 \layout Standard
13727
13728 unsigned 32 division
13729 \end_inset
13730 </cell>
13731 </row>
13732 <row topline="true">
13733 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13734 \begin_inset Text
13735
13736 \layout Standard
13737
13738 _modslong.c
13739 \end_inset
13740 </cell>
13741 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13742 \begin_inset Text
13743
13744 \layout Standard
13745
13746  signed 32 bit modulus (calls _modulong)
13747 \end_inset
13748 </cell>
13749 </row>
13750 <row topline="true" bottomline="true">
13751 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13752 \begin_inset Text
13753
13754 \layout Standard
13755
13756 _modulong.c
13757 \end_inset
13758 </cell>
13759 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13760 \begin_inset Text
13761
13762 \layout Standard
13763
13764 unsigned 32 bit modulus
13765 \end_inset
13766 </cell>
13767 </row>
13768 </lyxtabular>
13769
13770 \end_inset
13771
13772
13773 \newline
13774
13775 \layout Standard
13776
13777 Since they are compiled as
13778 \emph on
13779 non-reentrant
13780 \emph default
13781
13782 \begin_inset LatexCommand \index{reentrant}
13783
13784 \end_inset
13785
13786 , interrupt
13787 \begin_inset LatexCommand \index{interrupt}
13788
13789 \end_inset
13790
13791  service routines should not do any of the above operations.
13792  If this is unavoidable then the above routines will need to be compiled
13793  with the
13794 \emph on
13795 -
13796 \begin_inset ERT
13797 status Collapsed
13798
13799 \layout Standard
13800
13801 \backslash
13802 /
13803 \end_inset
13804
13805 -stack-auto
13806 \begin_inset LatexCommand \index{-\/-stack-auto}
13807
13808 \end_inset
13809
13810
13811 \emph default
13812  option, after which the source program will have to be compiled with
13813 \emph on
13814 -
13815 \begin_inset ERT
13816 status Collapsed
13817
13818 \layout Standard
13819
13820 \backslash
13821 /
13822 \end_inset
13823
13824 -int-long-reent
13825 \begin_inset LatexCommand \index{-\/-int-long-reent}
13826
13827 \end_inset
13828
13829
13830 \emph default
13831  option.
13832  Notice that you don't have to call these routines directly.
13833  The compiler will use them automatically every time an integer operation
13834  is required.
13835 \layout Section
13836
13837 Floating Point Support
13838 \begin_inset LatexCommand \index{Floating point support}
13839
13840 \end_inset
13841
13842
13843 \layout Standard
13844
13845 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
13846  floating point support routines are derived from gcc's floatlib.c and consist
13847  of the following routines:
13848 \newline
13849
13850 \layout Standard
13851 \align center
13852
13853 \size footnotesize
13854
13855 \begin_inset  Tabular
13856 <lyxtabular version="3" rows="17" columns="2">
13857 <features>
13858 <column alignment="center" valignment="top" leftline="true" width="0">
13859 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
13860 <row topline="true" bottomline="true">
13861 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13862 \begin_inset Text
13863
13864 \layout Standard
13865
13866
13867 \family roman
13868 \series medium
13869 \shape up
13870 \size normal
13871 \emph off
13872 \bar no
13873 \noun off
13874 \color none
13875 Function
13876 \end_inset
13877 </cell>
13878 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13879 \begin_inset Text
13880
13881 \layout Standard
13882
13883 Description
13884 \end_inset
13885 </cell>
13886 </row>
13887 <row topline="true">
13888 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13889 \begin_inset Text
13890
13891 \layout Standard
13892
13893
13894 \family roman
13895 \series medium
13896 \shape up
13897 \size normal
13898 \emph off
13899 \bar no
13900 \noun off
13901 \color none
13902 _fsadd.c
13903 \end_inset
13904 </cell>
13905 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13906 \begin_inset Text
13907
13908 \layout Standard
13909
13910
13911 \family roman
13912 \series medium
13913 \shape up
13914 \size normal
13915 \emph off
13916 \bar no
13917 \noun off
13918 \color none
13919 add floating point numbers
13920 \end_inset
13921 </cell>
13922 </row>
13923 <row topline="true">
13924 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13925 \begin_inset Text
13926
13927 \layout Standard
13928
13929
13930 \family roman
13931 \series medium
13932 \shape up
13933 \size normal
13934 \emph off
13935 \bar no
13936 \noun off
13937 \color none
13938 _fssub.c
13939 \end_inset
13940 </cell>
13941 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13942 \begin_inset Text
13943
13944 \layout Standard
13945
13946
13947 \family roman
13948 \series medium
13949 \shape up
13950 \size normal
13951 \emph off
13952 \bar no
13953 \noun off
13954 \color none
13955 subtract floating point numbers
13956 \end_inset
13957 </cell>
13958 </row>
13959 <row topline="true">
13960 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13961 \begin_inset Text
13962
13963 \layout Standard
13964
13965
13966 \family roman
13967 \series medium
13968 \shape up
13969 \size normal
13970 \emph off
13971 \bar no
13972 \noun off
13973 \color none
13974 _fsdiv.c
13975 \end_inset
13976 </cell>
13977 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13978 \begin_inset Text
13979
13980 \layout Standard
13981
13982
13983 \family roman
13984 \series medium
13985 \shape up
13986 \size normal
13987 \emph off
13988 \bar no
13989 \noun off
13990 \color none
13991 divide floating point numbers
13992 \end_inset
13993 </cell>
13994 </row>
13995 <row topline="true">
13996 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13997 \begin_inset Text
13998
13999 \layout Standard
14000
14001
14002 \family roman
14003 \series medium
14004 \shape up
14005 \size normal
14006 \emph off
14007 \bar no
14008 \noun off
14009 \color none
14010 _fsmul.c
14011 \end_inset
14012 </cell>
14013 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14014 \begin_inset Text
14015
14016 \layout Standard
14017
14018
14019 \family roman
14020 \series medium
14021 \shape up
14022 \size normal
14023 \emph off
14024 \bar no
14025 \noun off
14026 \color none
14027 multiply floating point numbers
14028 \end_inset
14029 </cell>
14030 </row>
14031 <row topline="true">
14032 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14033 \begin_inset Text
14034
14035 \layout Standard
14036
14037
14038 \family roman
14039 \series medium
14040 \shape up
14041 \size normal
14042 \emph off
14043 \bar no
14044 \noun off
14045 \color none
14046 _fs2uchar.c
14047 \end_inset
14048 </cell>
14049 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14050 \begin_inset Text
14051
14052 \layout Standard
14053
14054
14055 \family roman
14056 \series medium
14057 \shape up
14058 \size normal
14059 \emph off
14060 \bar no
14061 \noun off
14062 \color none
14063 convert floating point to unsigned char
14064 \end_inset
14065 </cell>
14066 </row>
14067 <row topline="true">
14068 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14069 \begin_inset Text
14070
14071 \layout Standard
14072
14073
14074 \family roman
14075 \series medium
14076 \shape up
14077 \size normal
14078 \emph off
14079 \bar no
14080 \noun off
14081 \color none
14082 _fs2char.c
14083 \end_inset
14084 </cell>
14085 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14086 \begin_inset Text
14087
14088 \layout Standard
14089
14090
14091 \family roman
14092 \series medium
14093 \shape up
14094 \size normal
14095 \emph off
14096 \bar no
14097 \noun off
14098 \color none
14099 convert floating point to signed char
14100 \end_inset
14101 </cell>
14102 </row>
14103 <row topline="true">
14104 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14105 \begin_inset Text
14106
14107 \layout Standard
14108
14109
14110 \family roman
14111 \series medium
14112 \shape up
14113 \size normal
14114 \emph off
14115 \bar no
14116 \noun off
14117 \color none
14118 _fs2uint.c
14119 \end_inset
14120 </cell>
14121 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14122 \begin_inset Text
14123
14124 \layout Standard
14125
14126
14127 \family roman
14128 \series medium
14129 \shape up
14130 \size normal
14131 \emph off
14132 \bar no
14133 \noun off
14134 \color none
14135 convert floating point to unsigned int
14136 \end_inset
14137 </cell>
14138 </row>
14139 <row topline="true">
14140 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14141 \begin_inset Text
14142
14143 \layout Standard
14144
14145
14146 \family roman
14147 \series medium
14148 \shape up
14149 \size normal
14150 \emph off
14151 \bar no
14152 \noun off
14153 \color none
14154 _fs2int.c
14155 \end_inset
14156 </cell>
14157 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14158 \begin_inset Text
14159
14160 \layout Standard
14161
14162
14163 \family roman
14164 \series medium
14165 \shape up
14166 \size normal
14167 \emph off
14168 \bar no
14169 \noun off
14170 \color none
14171 convert floating point to signed int
14172 \end_inset
14173 </cell>
14174 </row>
14175 <row topline="true">
14176 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14177 \begin_inset Text
14178
14179 \layout Standard
14180
14181
14182 \family roman
14183 \series medium
14184 \shape up
14185 \size normal
14186 \emph off
14187 \bar no
14188 \noun off
14189 \color none
14190 _fs2ulong.
14191 \family default
14192 \series default
14193 \shape default
14194 \size default
14195 \emph default
14196 \bar default
14197 \noun default
14198 \color default
14199 c
14200 \end_inset
14201 </cell>
14202 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14203 \begin_inset Text
14204
14205 \layout Standard
14206
14207
14208 \family roman
14209 \series medium
14210 \shape up
14211 \size normal
14212 \emph off
14213 \bar no
14214 \noun off
14215 \color none
14216 convert floating point to unsigned long
14217 \end_inset
14218 </cell>
14219 </row>
14220 <row topline="true">
14221 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14222 \begin_inset Text
14223
14224 \layout Standard
14225
14226
14227 \family roman
14228 \series medium
14229 \shape up
14230 \size normal
14231 \emph off
14232 \bar no
14233 \noun off
14234 \color none
14235 _fs2long.c
14236 \end_inset
14237 </cell>
14238 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14239 \begin_inset Text
14240
14241 \layout Standard
14242
14243
14244 \family roman
14245 \series medium
14246 \shape up
14247 \size normal
14248 \emph off
14249 \bar no
14250 \noun off
14251 \color none
14252 convert floating point to signed long
14253 \end_inset
14254 </cell>
14255 </row>
14256 <row topline="true">
14257 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14258 \begin_inset Text
14259
14260 \layout Standard
14261
14262
14263 \family roman
14264 \series medium
14265 \shape up
14266 \size normal
14267 \emph off
14268 \bar no
14269 \noun off
14270 \color none
14271 _uchar2fs.c
14272 \end_inset
14273 </cell>
14274 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14275 \begin_inset Text
14276
14277 \layout Standard
14278
14279
14280 \family roman
14281 \series medium
14282 \shape up
14283 \size normal
14284 \emph off
14285 \bar no
14286 \noun off
14287 \color none
14288 convert unsigned char to floating point
14289 \end_inset
14290 </cell>
14291 </row>
14292 <row topline="true">
14293 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14294 \begin_inset Text
14295
14296 \layout Standard
14297
14298
14299 \family roman
14300 \series medium
14301 \shape up
14302 \size normal
14303 \emph off
14304 \bar no
14305 \noun off
14306 \color none
14307 _char2fs.c
14308 \end_inset
14309 </cell>
14310 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14311 \begin_inset Text
14312
14313 \layout Standard
14314
14315
14316 \family roman
14317 \series medium
14318 \shape up
14319 \size normal
14320 \emph off
14321 \bar no
14322 \noun off
14323 \color none
14324 convert char to floating point number
14325 \end_inset
14326 </cell>
14327 </row>
14328 <row topline="true">
14329 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14330 \begin_inset Text
14331
14332 \layout Standard
14333
14334
14335 \family roman
14336 \series medium
14337 \shape up
14338 \size normal
14339 \emph off
14340 \bar no
14341 \noun off
14342 \color none
14343 _uint2fs.c
14344 \end_inset
14345 </cell>
14346 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14347 \begin_inset Text
14348
14349 \layout Standard
14350
14351
14352 \family roman
14353 \series medium
14354 \shape up
14355 \size normal
14356 \emph off
14357 \bar no
14358 \noun off
14359 \color none
14360 convert unsigned int to floating point
14361 \end_inset
14362 </cell>
14363 </row>
14364 <row topline="true">
14365 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14366 \begin_inset Text
14367
14368 \layout Standard
14369
14370
14371 \family roman
14372 \series medium
14373 \shape up
14374 \size normal
14375 \emph off
14376 \bar no
14377 \noun off
14378 \color none
14379 _int2fs.c
14380 \end_inset
14381 </cell>
14382 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14383 \begin_inset Text
14384
14385 \layout Standard
14386
14387
14388 \family roman
14389 \series medium
14390 \shape up
14391 \size normal
14392 \emph off
14393 \bar no
14394 \noun off
14395 \color none
14396 convert int to floating point numbers
14397 \end_inset
14398 </cell>
14399 </row>
14400 <row topline="true">
14401 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14402 \begin_inset Text
14403
14404 \layout Standard
14405
14406
14407 \family roman
14408 \series medium
14409 \shape up
14410 \size normal
14411 \emph off
14412 \bar no
14413 \noun off
14414 \color none
14415 _ulong2fs.c
14416 \end_inset
14417 </cell>
14418 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14419 \begin_inset Text
14420
14421 \layout Standard
14422
14423
14424 \family roman
14425 \series medium
14426 \shape up
14427 \size normal
14428 \emph off
14429 \bar no
14430 \noun off
14431 \color none
14432 convert unsigned long to floating point number
14433 \end_inset
14434 </cell>
14435 </row>
14436 <row topline="true" bottomline="true">
14437 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14438 \begin_inset Text
14439
14440 \layout Standard
14441
14442
14443 \family roman
14444 \series medium
14445 \shape up
14446 \size normal
14447 \emph off
14448 \bar no
14449 \noun off
14450 \color none
14451 _long2fs.c
14452 \end_inset
14453 </cell>
14454 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14455 \begin_inset Text
14456
14457 \layout Standard
14458
14459
14460 \family roman
14461 \series medium
14462 \shape up
14463 \size normal
14464 \emph off
14465 \bar no
14466 \noun off
14467 \color none
14468 convert long to floating point number
14469 \end_inset
14470 </cell>
14471 </row>
14472 </lyxtabular>
14473
14474 \end_inset
14475
14476
14477 \newline
14478
14479 \layout Standard
14480
14481 These support routines are developed in ANSI-C so there is room for space
14482  and speed improvement
14483 \begin_inset Foot
14484 collapsed false
14485
14486 \layout Standard
14487
14488 The floating point routines for the mcs51 are implemented in assembler
14489 \end_inset
14490
14491 .
14492  Note if all these routines are used simultaneously the data space might
14493  overflow.
14494  For serious floating point usage the large model might be needed.
14495  Also notice that you don't have to call this routines directly.
14496  The compiler will use them automatically every time a floating point operation
14497  is required.
14498 \layout Section
14499
14500 Library Routines
14501 \begin_inset LatexCommand \index{Libraries}
14502
14503 \end_inset
14504
14505
14506 \layout Standard
14507
14508
14509 \emph on
14510 <pending: this is messy and incomplete - a little more information is in
14511  sdcc/doc/libdoc.txt
14512 \emph default
14513  >
14514 \layout Subsection
14515
14516 Compiler support routines (_gptrget, _mulint etc.)
14517 \layout Subsection
14518
14519 Stdclib functions (puts, printf, strcat etc.)
14520 \layout Subsubsection
14521
14522 <stdio.h>
14523 \layout Standard
14524
14525
14526 \begin_inset LatexCommand \index{<stdio.h>}
14527
14528 \end_inset
14529
14530 As usual on embedded systems you have to provide your own
14531 \family typewriter
14532 getchar()
14533 \begin_inset LatexCommand \index{getchar()}
14534
14535 \end_inset
14536
14537
14538 \family default
14539 and
14540 \family typewriter
14541 putchar()
14542 \begin_inset LatexCommand \index{putchar()}
14543
14544 \end_inset
14545
14546
14547 \family default
14548  routines.
14549  SDCC does not know whether the system connects to a serial line with or
14550  without handshake, LCD, keyboard or other device.
14551  You'll find examples for serial routines f.e.
14552  in sdcc/device/lib.
14553 \layout Standard
14554
14555 The default
14556 \family typewriter
14557  printf()
14558 \begin_inset LatexCommand \index{printf()}
14559
14560 \end_inset
14561
14562
14563 \family default
14564 implementation in
14565 \family typewriter
14566  printf_large.c
14567 \family default
14568  does not support float (except on ds390).
14569  To enable this recompile it with the option
14570 \emph on
14571 -
14572 \begin_inset ERT
14573 status Collapsed
14574
14575 \layout Standard
14576
14577 \backslash
14578 /
14579 \end_inset
14580
14581 DUSE_FLOATS=1
14582 \begin_inset LatexCommand \index{USE\_FLOATS}
14583
14584 \end_inset
14585
14586
14587 \emph default
14588  on the command line.
14589  Use
14590 \emph on
14591 -
14592 \begin_inset ERT
14593 status Collapsed
14594
14595 \layout Standard
14596
14597 \backslash
14598 /
14599 \end_inset
14600
14601 -model-large
14602 \begin_inset LatexCommand \index{-\/-model-large}
14603
14604 \end_inset
14605
14606
14607 \emph default
14608  for the mcs51 port, since this uses a lot of memory.
14609 \layout Standard
14610
14611 If you're short on memory you might want to use
14612 \family typewriter
14613 printf_small()
14614 \begin_inset LatexCommand \index{printf\_small()}
14615
14616 \end_inset
14617
14618
14619 \family default
14620
14621 \emph on
14622 instead
14623 \emph default
14624  of
14625 \family typewriter
14626  printf().
14627
14628 \family default
14629  For the mcs51 there additionally are assembly versions
14630 \family typewriter
14631 printf_tiny()
14632 \begin_inset LatexCommand \index{printf\_tiny() (mcs51)}
14633
14634 \end_inset
14635
14636
14637 \family default
14638  and
14639 \family typewriter
14640 printf_fast()
14641 \begin_inset LatexCommand \index{printf\_fast() (mcs51)}
14642
14643 \end_inset
14644
14645
14646 \family default
14647 and
14648 \family typewriter
14649  printf_fast_f()
14650 \begin_inset LatexCommand \index{printf\_fast\_f() (mcs51)}
14651
14652 \end_inset
14653
14654
14655 \family default
14656  which should fit the requirements of many embedded systems (printf_fast()
14657  can be customized by unsetting #defines to
14658 \emph on
14659 not
14660 \emph default
14661  support long variables and field widths).
14662 \layout Subsection
14663
14664 Math functions (sin, pow, sqrt etc.)
14665 \layout Subsection
14666
14667 Other libraries
14668 \layout Standard
14669
14670 Libraries
14671 \begin_inset LatexCommand \index{Libraries}
14672
14673 \end_inset
14674
14675  included in SDCC should have a license at least as liberal as the GNU Lesser
14676  General Public License
14677 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
14678
14679 \end_inset
14680
14681
14682 \emph on
14683 LGPL
14684 \emph default
14685 .
14686 \layout Comment
14687
14688 license statements for the libraries are missing.
14689  sdcc/device/lib/ser_ir.c
14690 \layout Comment
14691
14692 or _decdptr f.e.
14693  come with a GPL (as opposed to LGPL) License - this will not be liberal
14694  enough for many embedded programmers.
14695 \layout Standard
14696
14697 If you have ported some library or want to share experience about some code
14698  which f.e.
14699  falls into any of these categories Busses (I
14700 \begin_inset Formula $^{\textrm{2}}$
14701 \end_inset
14702
14703 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
14704  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
14705  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
14706 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
14707
14708 \end_inset
14709
14710 \SpecialChar ~
14711 would certainly like to hear about it.
14712  Programmers coding for embedded systems are not especially famous for being
14713  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
14714 e these references are very valuable.
14715  Let's help to create a climate where information is shared.
14716 \layout Section
14717
14718 Memory Models
14719 \layout Subsection
14720
14721 MCS51 Memory Models
14722 \begin_inset LatexCommand \index{Memory model}
14723
14724 \end_inset
14725
14726
14727 \begin_inset LatexCommand \index{MCS51 memory model}
14728
14729 \end_inset
14730
14731
14732 \layout Subsubsection
14733
14734 Small and Large
14735 \layout Standard
14736
14737 SDCC allows two memory models for MCS51 code,
14738 \shape slanted
14739 small
14740 \shape default
14741  and
14742 \shape slanted
14743 large
14744 \shape default
14745 .
14746  Modules compiled with different memory models should
14747 \emph on
14748 never
14749 \emph default
14750  be combined together or the results would be unpredictable.
14751  The library routines supplied with the compiler are compiled as both small
14752  and large.
14753  The compiled library modules are contained in separate directories as small
14754  and large so that you can link to either set.
14755
14756 \layout Standard
14757
14758 When the large model is used all variables declared without a storage class
14759  will be allocated into the external ram, this includes all parameters and
14760  local variables (for non-reentrant
14761 \begin_inset LatexCommand \index{reentrant}
14762
14763 \end_inset
14764
14765  functions).
14766  When the small model is used variables without storage class are allocated
14767  in the internal ram.
14768 \layout Standard
14769
14770 Judicious usage of the processor specific storage classes
14771 \begin_inset LatexCommand \index{Storage class}
14772
14773 \end_inset
14774
14775  and the 'reentrant' function type will yield much more efficient code,
14776  than using the large model.
14777  Several optimizations are disabled when the program is compiled using the
14778  large model, it is therefore recommended that the small model be used unless
14779  absolutely required.
14780 \layout Subsubsection
14781
14782 External Stack
14783 \begin_inset LatexCommand \label{sub:External-Stack}
14784
14785 \end_inset
14786
14787
14788 \begin_inset LatexCommand \index{stack}
14789
14790 \end_inset
14791
14792
14793 \begin_inset LatexCommand \index{External stack (mcs51)}
14794
14795 \end_inset
14796
14797
14798 \layout Standard
14799
14800 The external stack (-
14801 \begin_inset ERT
14802 status Collapsed
14803
14804 \layout Standard
14805
14806 \backslash
14807 /
14808 \end_inset
14809
14810 -xstack option
14811 \begin_inset LatexCommand \index{-\/-xstack}
14812
14813 \end_inset
14814
14815 ) is located in pdata
14816 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
14817
14818 \end_inset
14819
14820  memory (usually at the start of the external ram segment) and uses all
14821  unused space in pdata (max.
14822  256 bytes).
14823  When -
14824 \begin_inset ERT
14825 status Collapsed
14826
14827 \layout Standard
14828
14829 \backslash
14830 /
14831 \end_inset
14832
14833 -xstack option is used to compile the program, the parameters and local
14834  variables
14835 \begin_inset LatexCommand \index{local variables}
14836
14837 \end_inset
14838
14839  of all reentrant functions are allocated in this area.
14840  This option is provided for programs with large stack space requirements.
14841  When used with the -
14842 \begin_inset ERT
14843 status Collapsed
14844
14845 \layout Standard
14846
14847 \backslash
14848 /
14849 \end_inset
14850
14851 -stack-auto
14852 \begin_inset LatexCommand \index{-\/-stack-auto}
14853
14854 \end_inset
14855
14856  option, all parameters and local variables are allocated on the external
14857  stack (note: support libraries will need to be recompiled with the same
14858  options.
14859  There is a predefined target in the library makefile).
14860 \layout Standard
14861
14862 The compiler outputs the higher order address byte of the external ram segment
14863  into port P2
14864 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
14865
14866 \end_inset
14867
14868  (see also section
14869 \begin_inset LatexCommand \ref{sub:MCS51-variants}
14870
14871 \end_inset
14872
14873 ), therefore when using the External Stack option, this port
14874 \emph on
14875 may not
14876 \emph default
14877  be used by the application program.
14878 \layout Subsection
14879
14880 DS390 Memory Model
14881 \begin_inset LatexCommand \index{Memory model}
14882
14883 \end_inset
14884
14885
14886 \begin_inset LatexCommand \index{DS390 memory model}
14887
14888 \end_inset
14889
14890
14891 \layout Standard
14892
14893 The only model supported is Flat 24
14894 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
14895
14896 \end_inset
14897
14898 .
14899  This generates code for the 24 bit contiguous addressing mode of the Dallas
14900  DS80C390 part.
14901  In this mode, up to four meg of external RAM or code space can be directly
14902  addressed.
14903  See the data sheets at www.dalsemi.com for further information on this part.
14904 \newline
14905
14906 \newline
14907 Note that the compiler does not generate any code to place the processor
14908  into 24 bitmode (although
14909 \emph on
14910 tinibios
14911 \emph default
14912  in the ds390 libraries will do that for you).
14913  If you don't use
14914 \emph on
14915 tinibios
14916 \emph default
14917
14918 \begin_inset LatexCommand \index{Tinibios (DS390)}
14919
14920 \end_inset
14921
14922 , the boot loader or similar code must ensure that the processor is in 24
14923  bit contiguous addressing mode before calling the SDCC startup code.
14924 \newline
14925
14926 \newline
14927 Like the
14928 \emph on
14929 -
14930 \begin_inset ERT
14931 status Collapsed
14932
14933 \layout Standard
14934
14935 \backslash
14936 /
14937 \end_inset
14938
14939 -model-large
14940 \emph default
14941  option, variables will by default be placed into the XDATA segment.
14942
14943 \newline
14944
14945 \newline
14946 Segments may be placed anywhere in the 4 meg address space using the usual
14947  -
14948 \begin_inset ERT
14949 status Collapsed
14950
14951 \layout Standard
14952
14953 \backslash
14954 /
14955 \end_inset
14956
14957 -*-loc options.
14958  Note that if any segments are located above 64K, the -r flag must be passed
14959  to the linker to generate the proper segment relocations, and the Intel
14960  HEX output format must be used.
14961  The -r flag can be passed to the linker by using the option
14962 \emph on
14963 -Wl-r
14964 \emph default
14965  on the SDCC command line.
14966  However, currently the linker can not handle code segments > 64k.
14967 \layout Section
14968
14969 Pragmas
14970 \begin_inset LatexCommand \index{Pragmas}
14971
14972 \end_inset
14973
14974
14975 \layout Standard
14976
14977 SDCC supports the following #pragma directives:
14978 \layout Itemize
14979
14980 save
14981 \begin_inset LatexCommand \index{\#pragma save}
14982
14983 \end_inset
14984
14985  - this will save all current options to the save/restore stack.
14986  See #pragma\SpecialChar ~
14987 restore.
14988 \layout Itemize
14989
14990 restore
14991 \begin_inset LatexCommand \index{\#pragma restore}
14992
14993 \end_inset
14994
14995  - will restore saved options from the last save.
14996  saves & restores can be nested.
14997  SDCC uses a save/restore stack: save pushes current options to the stack,
14998  restore pulls current options from the stack.
14999  See #pragma\SpecialChar ~
15000 save.
15001 \newline
15002
15003 \layout Itemize
15004
15005 callee_saves
15006 \begin_inset LatexCommand \index{\#pragma callee\_saves}
15007
15008 \end_inset
15009
15010
15011 \begin_inset LatexCommand \index{function prologue}
15012
15013 \end_inset
15014
15015  function1[,function2[,function3...]] - The compiler by default uses a caller
15016  saves convention for register saving across function calls, however this
15017  can cause unnecessary register pushing & popping
15018 \begin_inset LatexCommand \index{push/pop}
15019
15020 \end_inset
15021
15022  when calling small functions from larger functions.
15023  This option can be used to switch off the register saving convention for
15024  the function names specified.
15025  The compiler will not save registers when calling these functions, extra
15026  code need to be manually inserted at the entry & exit for these functions
15027  to save & restore the registers used by these functions, this can SUBSTANTIALLY
15028  reduce code & improve run time performance of the generated code.
15029  In the future the compiler (with inter procedural analysis) may be able
15030  to determine the appropriate scheme to use for each function call.
15031  If -
15032 \begin_inset ERT
15033 status Collapsed
15034
15035 \layout Standard
15036
15037 \backslash
15038 /
15039 \end_inset
15040
15041 -callee-saves command line option is used, the function names specified
15042  in #pragma\SpecialChar ~
15043 callee_saves
15044 \begin_inset LatexCommand \index{\#pragma callee\_saves}
15045
15046 \end_inset
15047
15048  is appended to the list of functions specified in the command line.
15049 \layout Itemize
15050
15051 exclude
15052 \begin_inset LatexCommand \index{\#pragma exclude}
15053
15054 \end_inset
15055
15056  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
15057  of pairs of push/pop
15058 \begin_inset LatexCommand \index{push/pop}
15059
15060 \end_inset
15061
15062  instructions in
15063 \emph on
15064 I
15065 \emph default
15066 nterrupt
15067 \begin_inset LatexCommand \index{interrupt}
15068
15069 \end_inset
15070
15071
15072 \emph on
15073 S
15074 \emph default
15075 ervice
15076 \emph on
15077 R
15078 \emph default
15079 outines.
15080  The directive should be placed immediately before the ISR function definition
15081  and it affects ALL ISR functions following it.
15082  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
15083 exclude\SpecialChar ~
15084 none
15085 \begin_inset LatexCommand \index{\#pragma exclude}
15086
15087 \end_inset
15088
15089 .
15090  See also the related keyword _naked
15091 \begin_inset LatexCommand \index{\_naked}
15092
15093 \end_inset
15094
15095
15096 \begin_inset LatexCommand \index{\_\_naked}
15097
15098 \end_inset
15099
15100 .
15101 \layout Itemize
15102
15103 less_pedantic
15104 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
15105
15106 \end_inset
15107
15108  - the compiler will not warn you anymore for obvious mistakes, you'r on
15109  your own now ;-(
15110 \layout Itemize
15111
15112 disable_warning <nnnn>
15113 \begin_inset LatexCommand \index{\#pragma disable\_warning}
15114
15115 \end_inset
15116
15117  - the compiler will not warn you anymore about warning number <nnnn>.
15118 \layout Itemize
15119
15120 nogcse
15121 \begin_inset LatexCommand \index{\#pragma nogcse}
15122
15123 \end_inset
15124
15125  - will stop global common subexpression elimination.
15126 \layout Itemize
15127
15128 noinduction
15129 \begin_inset LatexCommand \index{\#pragma noinduction}
15130
15131 \end_inset
15132
15133  - will stop loop induction optimizations.
15134 \layout Itemize
15135
15136 noinvariant
15137 \begin_inset LatexCommand \index{\#pragma noinvariant}
15138
15139 \end_inset
15140
15141  - will not do loop invariant optimizations.
15142  For more details see Loop Invariants in section
15143 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
15144
15145 \end_inset
15146
15147 .
15148 \layout Itemize
15149
15150 noiv
15151 \begin_inset LatexCommand \index{\#pragma noiv}
15152
15153 \end_inset
15154
15155  - Do not generate interrupt
15156 \begin_inset LatexCommand \index{interrupt}
15157
15158 \end_inset
15159
15160  vector table entries for all ISR functions defined after the pragma.
15161  This is useful in cases where the interrupt vector table must be defined
15162  manually, or when there is a secondary, manually defined interrupt vector
15163  table (e.g.
15164  for the autovector feature of the Cypress EZ-USB FX2).
15165  More elegantly this can be achieved by obmitting the optional interrupt
15166  number after the interrupt keyword, see section
15167 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
15168
15169 \end_inset
15170
15171 \SpecialChar ~
15172 about interrupts.
15173 \layout Itemize
15174
15175 nojtbound
15176 \begin_inset LatexCommand \index{\#pragma nojtbound}
15177
15178 \end_inset
15179
15180  - will not generate code for boundary value checking, when switch statements
15181  are turned into jump-tables (dangerous).
15182  For more details see section
15183 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
15184
15185 \end_inset
15186
15187 .
15188 \layout Itemize
15189
15190 noloopreverse
15191 \begin_inset LatexCommand \index{\#pragma noloopreverse}
15192
15193 \end_inset
15194
15195  - Will not do loop reversal optimization
15196 \layout Itemize
15197
15198 nooverlay
15199 \begin_inset LatexCommand \index{\#pragma nooverlay}
15200
15201 \end_inset
15202
15203  - the compiler will not overlay the parameters and local variables of a
15204  function.
15205 \layout Itemize
15206
15207 stackauto
15208 \begin_inset LatexCommand \index{\#pragma stackauto}
15209
15210 \end_inset
15211
15212 - See option -
15213 \begin_inset ERT
15214 status Collapsed
15215
15216 \layout Standard
15217
15218 \backslash
15219 /
15220 \end_inset
15221
15222 -stack-auto
15223 \begin_inset LatexCommand \index{-\/-stack-auto}
15224
15225 \end_inset
15226
15227  and section
15228 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
15229
15230 \end_inset
15231
15232  Parameters and Local Variables.
15233 \layout Itemize
15234
15235 opt_code_speed
15236 \begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
15237
15238 \end_inset
15239
15240 - The compiler will optimize code generation towards fast code, possibly
15241  at the expense of code size.
15242 \layout Itemize
15243
15244 opt_code_size
15245 \begin_inset LatexCommand \index{\#pragma opt\_code\_size}
15246
15247 \end_inset
15248
15249 - The compiler will optimize code generation towards compact code, possibly
15250  at the expense of code speed.
15251 \layout Itemize
15252
15253 opt_code_balanced
15254 \begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
15255
15256 \end_inset
15257
15258 - The compiler will attempt to generate code that is both compact and fast,
15259  as long as meeting one goal is not a detriment to the other (this is the
15260  default).
15261
15262 \layout Itemize
15263
15264 std_sdcc89
15265 \begin_inset LatexCommand \index{\#pragma std\_sdcc89}
15266
15267 \end_inset
15268
15269 - Generally follow the C89 standard, but allow SDCC features that conflict
15270  with the standard (default).
15271 \layout Itemize
15272
15273 std_c89
15274 \begin_inset LatexCommand \index{\#pragma std\_c89}
15275
15276 \end_inset
15277
15278 - Follow the C89 standard and disable SDCC features that conflict with the
15279  standard.
15280 \layout Itemize
15281
15282 std_sdcc99
15283 \begin_inset LatexCommand \index{\#pragma std\_sdcc99}
15284
15285 \end_inset
15286
15287 - Generally follow the C99 standard, but allow SDCC features that conflict
15288  with the standard (incomplete support).
15289 \layout Itemize
15290
15291 std_c99
15292 \begin_inset LatexCommand \index{\#pragma std\_c99}
15293
15294 \end_inset
15295
15296 - Follow the C99 standard and disable SDCC features that conflict with the
15297  standard (incomplete support).
15298 \layout Itemize
15299
15300 codeseg <name>
15301 \begin_inset LatexCommand \index{\#pragma codeseg}
15302
15303 \end_inset
15304
15305 - Use this name (max.
15306  8 characters) for the code segment.
15307 \layout Itemize
15308
15309 constseg <name>
15310 \begin_inset LatexCommand \index{\#pragma constseg}
15311
15312 \end_inset
15313
15314 - Use this name (max.
15315  8 characters) for the const segment.
15316 \layout Standard
15317
15318 SDCPP supports the following #pragma directives:
15319 \layout Itemize
15320
15321 preproc_asm
15322 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
15323
15324 \end_inset
15325
15326  (+ | -) - switch _asm _endasm block preprocessing on / off.
15327  Default is on.
15328 \layout Standard
15329
15330 The pragma's are intended to be used to turn-on or off certain optimizations
15331  which might cause the compiler to generate extra stack / data space to
15332  store compiler generated temporary variables.
15333  This usually happens in large functions.
15334  Pragma directives should be used as shown in the following example, they
15335  are used to control options & optimizations for a given function; pragmas
15336  should be placed before and/or after a function, placing pragma's inside
15337  a function body could have unpredictable results.
15338 \layout Verse
15339
15340
15341 \family typewriter
15342 #pragma save
15343 \begin_inset LatexCommand \index{\#pragma save}
15344
15345 \end_inset
15346
15347  \SpecialChar ~
15348 \SpecialChar ~
15349 \SpecialChar ~
15350 \SpecialChar ~
15351 \SpecialChar ~
15352 \SpecialChar ~
15353 \SpecialChar ~
15354 /* save the current settings */
15355 \newline
15356 #pragma nogcse
15357 \begin_inset LatexCommand \index{\#pragma nogcse}
15358
15359 \end_inset
15360
15361  \SpecialChar ~
15362 \SpecialChar ~
15363 \SpecialChar ~
15364 \SpecialChar ~
15365 \SpecialChar ~
15366 /* turnoff global subexpression elimination */
15367 \newline
15368 #pragma noinduction
15369 \begin_inset LatexCommand \index{\#pragma noinduction}
15370
15371 \end_inset
15372
15373  /* turn off induction optimizations */
15374 \newline
15375 int foo ()
15376 \newline
15377 {
15378 \newline
15379 \SpecialChar ~
15380  \SpecialChar ~
15381  ...
15382
15383 \newline
15384 \SpecialChar ~
15385  \SpecialChar ~
15386  /* large code */
15387 \newline
15388 \SpecialChar ~
15389  \SpecialChar ~
15390  ...
15391
15392 \newline
15393 }
15394 \newline
15395 #pragma restore
15396 \begin_inset LatexCommand \index{\#pragma restore}
15397
15398 \end_inset
15399
15400  /* turn the optimizations back on */
15401 \layout Standard
15402
15403 The compiler will generate a warning message when extra space is allocated.
15404  It is strongly recommended that the save and restore pragma's be used when
15405  changing options for a function.
15406 \layout Section
15407
15408 Defines Created by the Compiler
15409 \layout Standard
15410
15411 The compiler creates the following #defines
15412 \begin_inset LatexCommand \index{\#defines}
15413
15414 \end_inset
15415
15416
15417 \begin_inset LatexCommand \index{Defines created by the compiler}
15418
15419 \end_inset
15420
15421 :
15422 \newline
15423
15424 \layout Standard
15425
15426
15427 \begin_inset  Tabular
15428 <lyxtabular version="3" rows="10" columns="2">
15429 <features>
15430 <column alignment="center" valignment="top" leftline="true" width="0">
15431 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15432 <row topline="true" bottomline="true">
15433 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15434 \begin_inset Text
15435
15436 \layout Standard
15437
15438
15439 \series bold
15440 #define
15441 \end_inset
15442 </cell>
15443 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15444 \begin_inset Text
15445
15446 \layout Standard
15447
15448
15449 \series bold
15450 Description
15451 \end_inset
15452 </cell>
15453 </row>
15454 <row topline="true">
15455 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15456 \begin_inset Text
15457
15458 \layout Standard
15459
15460 SDCC
15461 \begin_inset LatexCommand \index{SDCC}
15462
15463 \end_inset
15464
15465
15466 \end_inset
15467 </cell>
15468 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15469 \begin_inset Text
15470
15471 \layout Standard
15472
15473 this Symbol is always defined
15474 \end_inset
15475 </cell>
15476 </row>
15477 <row topline="true">
15478 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15479 \begin_inset Text
15480
15481 \layout Standard
15482
15483 SDCC_mcs51
15484 \begin_inset LatexCommand \index{SDCC\_mcs51}
15485
15486 \end_inset
15487
15488  or SDCC_ds390
15489 \begin_inset LatexCommand \index{SDCC\_ds390}
15490
15491 \end_inset
15492
15493  or SDCC_z80
15494 \begin_inset LatexCommand \index{SDCC\_z80}
15495
15496 \end_inset
15497
15498 , etc
15499 \end_inset
15500 </cell>
15501 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15502 \begin_inset Text
15503
15504 \layout Standard
15505
15506 depending on the model used (e.g.: -mds390
15507 \end_inset
15508 </cell>
15509 </row>
15510 <row topline="true">
15511 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15512 \begin_inset Text
15513
15514 \layout Standard
15515
15516 __mcs51
15517 \begin_inset LatexCommand \index{\_\_mcs51}
15518
15519 \end_inset
15520
15521 , __ds390
15522 \begin_inset LatexCommand \index{\_\_ds390}
15523
15524 \end_inset
15525
15526 , __hc08
15527 \begin_inset LatexCommand \index{\_\_hc08}
15528
15529 \end_inset
15530
15531 , __z80
15532 \begin_inset LatexCommand \index{\_\_z80}
15533
15534 \end_inset
15535
15536 , etc
15537 \end_inset
15538 </cell>
15539 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15540 \begin_inset Text
15541
15542 \layout Standard
15543
15544 depending on the model used (e.g.
15545  -mz80)
15546 \end_inset
15547 </cell>
15548 </row>
15549 <row topline="true">
15550 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15551 \begin_inset Text
15552
15553 \layout Standard
15554
15555 SDCC_STACK_AUTO
15556 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
15557
15558 \end_inset
15559
15560
15561 \end_inset
15562 </cell>
15563 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15564 \begin_inset Text
15565
15566 \layout Standard
15567
15568 when
15569 \emph on
15570 -
15571 \begin_inset ERT
15572 status Collapsed
15573
15574 \layout Standard
15575
15576 \backslash
15577 /
15578 \end_inset
15579
15580 -stack-auto
15581 \emph default
15582  option is used
15583 \end_inset
15584 </cell>
15585 </row>
15586 <row topline="true">
15587 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15588 \begin_inset Text
15589
15590 \layout Standard
15591
15592 SDCC_MODEL_SMALL
15593 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
15594
15595 \end_inset
15596
15597
15598 \end_inset
15599 </cell>
15600 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15601 \begin_inset Text
15602
15603 \layout Standard
15604
15605 when
15606 \emph on
15607 -
15608 \begin_inset ERT
15609 status Collapsed
15610
15611 \layout Standard
15612
15613 \backslash
15614 /
15615 \end_inset
15616
15617 -model-small
15618 \emph default
15619  is used
15620 \end_inset
15621 </cell>
15622 </row>
15623 <row topline="true">
15624 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15625 \begin_inset Text
15626
15627 \layout Standard
15628
15629 SDCC_MODEL_LARGE
15630 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
15631
15632 \end_inset
15633
15634
15635 \end_inset
15636 </cell>
15637 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15638 \begin_inset Text
15639
15640 \layout Standard
15641
15642 when
15643 \emph on
15644 -
15645 \begin_inset ERT
15646 status Collapsed
15647
15648 \layout Standard
15649
15650 \backslash
15651 /
15652 \end_inset
15653
15654 -model-large
15655 \emph default
15656  is used
15657 \end_inset
15658 </cell>
15659 </row>
15660 <row topline="true">
15661 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15662 \begin_inset Text
15663
15664 \layout Standard
15665
15666 SDCC_USE_XSTACK
15667 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
15668
15669 \end_inset
15670
15671
15672 \end_inset
15673 </cell>
15674 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15675 \begin_inset Text
15676
15677 \layout Standard
15678
15679 when
15680 \emph on
15681 -
15682 \begin_inset ERT
15683 status Collapsed
15684
15685 \layout Standard
15686
15687 \backslash
15688 /
15689 \end_inset
15690
15691 -xstack
15692 \emph default
15693  option is used
15694 \end_inset
15695 </cell>
15696 </row>
15697 <row topline="true">
15698 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15699 \begin_inset Text
15700
15701 \layout Standard
15702
15703 SDCC_STACK_TENBIT
15704 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
15705
15706 \end_inset
15707
15708
15709 \end_inset
15710 </cell>
15711 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15712 \begin_inset Text
15713
15714 \layout Standard
15715
15716 when
15717 \emph on
15718 -mds390
15719 \emph default
15720  is used
15721 \end_inset
15722 </cell>
15723 </row>
15724 <row topline="true" bottomline="true">
15725 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15726 \begin_inset Text
15727
15728 \layout Standard
15729
15730 SDCC_MODEL_FLAT24
15731 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
15732
15733 \end_inset
15734
15735
15736 \end_inset
15737 </cell>
15738 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15739 \begin_inset Text
15740
15741 \layout Standard
15742
15743 when
15744 \emph on
15745 -mds390
15746 \emph default
15747  is used
15748 \end_inset
15749 </cell>
15750 </row>
15751 </lyxtabular>
15752
15753 \end_inset
15754
15755
15756 \layout Chapter
15757
15758 Notes on supported Processors
15759 \layout Section
15760
15761 MCS51 variants
15762 \begin_inset LatexCommand \label{sub:MCS51-variants}
15763
15764 \end_inset
15765
15766
15767 \begin_inset LatexCommand \index{MCS51 variants}
15768
15769 \end_inset
15770
15771
15772 \layout Standard
15773
15774 MCS51 processors are available from many vendors and come in many different
15775  flavours.
15776  While they might differ considerably in respect to Special Function Registers
15777  the core MCS51 is usually not modified or is kept compatible.
15778
15779 \layout Subsection
15780
15781 pdata access by SFR
15782 \layout Standard
15783
15784 With the upcome of devices with internal xdata and flash memory devices
15785  using port P2
15786 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
15787
15788 \end_inset
15789
15790  as dedicated I/O port is becoming more popular.
15791  Switching the high byte for pdata
15792 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
15793
15794 \end_inset
15795
15796  access which was formerly done by port P2 is then achieved by a Special
15797  Function Register
15798 \begin_inset LatexCommand \index{sfr}
15799
15800 \end_inset
15801
15802 .
15803  In well-established MCS51 tradition the address of this
15804 \emph on
15805 sfr
15806 \emph default
15807  is where the chip designers decided to put it.
15808  Needless to say that they didn't agree on a common name either.
15809  So that the startup code can correctly initialize xdata variables, you
15810  should define an sfr with the name _XPAGE
15811 \family typewriter
15812
15813 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
15814
15815 \end_inset
15816
15817
15818 \family default
15819  at the appropriate location if the default, port P2, is not used for this.
15820  Some examples are:
15821 \layout Verse
15822
15823
15824 \family typewriter
15825 sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
15826 \layout Verse
15827
15828
15829 \family typewriter
15830 sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
15831 \layout Verse
15832
15833
15834 \family typewriter
15835 sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
15836 \layout Standard
15837
15838 For more exotic implementations further customizations may be needed.
15839  See section
15840 \begin_inset LatexCommand \ref{sub:Startup-Code}
15841
15842 \end_inset
15843
15844  for other possibilities.
15845 \layout Subsection
15846
15847 Other Features available by SFR
15848 \layout Standard
15849
15850 Some MCS51 variants offer features like Double DPTR
15851 \begin_inset LatexCommand \index{DPTR}
15852
15853 \end_inset
15854
15855 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
15856  These are currently not used for the MCS51 port.
15857  If you absolutely need them you can fall back to inline assembly or submit
15858  a patch to SDCC.
15859 \layout Section
15860
15861 DS400 port
15862 \layout Standard
15863
15864 The DS80C400 microcontroller has a rich set of peripherals.
15865  In its built-in ROM library it includes functions to access some of the
15866  features, among them is a TCP stack with IP4 and IP6 support.
15867  Library headers (currently in beta status) and other files are provided
15868  at
15869 \size footnotesize
15870
15871 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
15872
15873 \end_inset
15874
15875 .
15876
15877 \layout Section
15878
15879 The Z80 and gbz80 port
15880 \layout Standard
15881
15882 SDCC can target both the Zilog
15883 \begin_inset LatexCommand \index{Z80}
15884
15885 \end_inset
15886
15887  and the Nintendo Gameboy's Z80-like gbz80
15888 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
15889
15890 \end_inset
15891
15892 .
15893  The Z80 port is passed through the same
15894 \emph on
15895 regressions tests
15896 \begin_inset LatexCommand \index{Regression test}
15897
15898 \end_inset
15899
15900
15901 \emph default
15902  as the MCS51 and DS390 ports, so floating point support, support for long
15903  variables and bitfield support is fine.
15904  See mailing lists and forums about interrupt routines.
15905 \layout Standard
15906
15907 As always, the code is the authoritative reference - see z80/ralloc.c and
15908  z80/gen.c.
15909  The stack
15910 \begin_inset LatexCommand \index{stack}
15911
15912 \end_inset
15913
15914  frame is similar to that generated by the IAR Z80 compiler.
15915  IX is used as the base pointer, HL and IY are used as a temporary registers,
15916  and BC and DE are available for holding variables.
15917  Return values
15918 \begin_inset LatexCommand \index{return value}
15919
15920 \end_inset
15921
15922  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
15923  bytes).
15924  The gbz80 port use the same set of registers for the return values, but
15925  in a different order of significance: E (one byte), DE (two bytes), or
15926  HLDE (four bytes).
15927 \layout Section
15928
15929 The HC08 port
15930 \layout Standard
15931
15932 The port to the Motorola HC08
15933 \begin_inset LatexCommand \index{HC08}
15934
15935 \end_inset
15936
15937  family has been added in October 2003, and is still undergoing some basic
15938  development.
15939  The code generator is complete, but the register allocation is still quite
15940  unoptimized.
15941  Some of the SDCC's standard C library functions have embedded non-HC08
15942  inline assembly and so are not yet usable.
15943 \newline
15944
15945 \newline
15946
15947 \layout Section
15948
15949 The PIC14 port
15950 \layout Standard
15951
15952 The 14bit PIC
15953 \begin_inset LatexCommand \index{PIC14}
15954
15955 \end_inset
15956
15957  port still requires a major effort from the development community.
15958  However it can work for very simple code.
15959 \layout Subsection
15960
15961 C code and 14bit PIC code page
15962 \begin_inset LatexCommand \index{code page (pic14)}
15963
15964 \end_inset
15965
15966  and RAM banks
15967 \begin_inset LatexCommand \index{RAM bank (pic14)}
15968
15969 \end_inset
15970
15971
15972 \layout Standard
15973
15974 The linker organizes allocation for the code page and RAM banks.
15975  It does not have intimate knowledge of the code flow.
15976  It will put all the code section of a single asm file into a single code
15977  page.
15978  In order to make use of multiple code pages, separate asm files must be
15979  used.
15980  The compiler treats all functions of a single C file as being in the same
15981  code page unless it is non static.
15982  The compiler treats all local variables of a single C file as being in
15983  the same RAM bank unless it is an extern.
15984 \newline
15985
15986 \newline
15987 To get the best follow these guide lines:
15988 \layout Enumerate
15989
15990 make local functions static, as non static functions require code page selection
15991  overhead.
15992 \layout Enumerate
15993
15994 Make local variables static as extern variables require RAM bank selection
15995  overhead.
15996 \layout Enumerate
15997
15998 For devices that have multiple code pages it is more efficient to use the
15999  same number of files as pages, i.e.
16000  for the 16F877 use 4 separate files and i.e.
16001  for the 16F874 use 2 separate files.
16002  This way the linker can put the code for each file into different code
16003  pages and the compiler can allocate reusable variables more efficiently
16004  and there's less page selection overhead.
16005  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
16006  instruction set) use 'unsigned char' whereever possible instead of 'int'.
16007 \layout Subsection
16008
16009 Creating a device include file
16010 \layout Standard
16011
16012 For generating a device include file use the support perl script inc2h.pl
16013  kept in directory support/script.
16014 \layout Subsection
16015
16016 Interrupt code
16017 \layout Standard
16018
16019 For the interrupt function, use the keyword 'interrupt'
16020 \begin_inset LatexCommand \index{interrupt}
16021
16022 \end_inset
16023
16024  with level number of 0 (PIC14 only has 1 interrupt so this number is only
16025  there to avoid a syntax error - it ought to be fixed).
16026  E.g.:
16027 \layout Verse
16028
16029
16030 \family typewriter
16031 void Intr(void) interrupt 0
16032 \newline
16033 {
16034 \newline
16035 \SpecialChar ~
16036 \SpecialChar ~
16037 T0IF = 0; /* Clear timer interrupt */
16038 \newline
16039 }
16040 \layout Subsection
16041
16042 Linking and assembling
16043 \layout Standard
16044
16045 For assembling you can use either GPUTILS'
16046 \begin_inset LatexCommand \index{gputils (pic tools)}
16047
16048 \end_inset
16049
16050  gpasm.exe or MPLAB's mpasmwin.exe.
16051  GPUTILS is available from
16052 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
16053
16054 \end_inset
16055
16056 .
16057  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
16058  If you use MPLAB and an interrupt function then the linker script file
16059  vectors section will need to be enlarged to link with mplink.
16060 \newline
16061
16062 \newline
16063 Here is a
16064 \family typewriter
16065 Makefile
16066 \family default
16067  using GPUTILS:
16068 \layout Verse
16069
16070
16071 \family typewriter
16072 .c.o:
16073 \newline
16074 \SpecialChar ~
16075 \SpecialChar ~
16076 \SpecialChar ~
16077 \SpecialChar ~
16078 \SpecialChar ~
16079 \SpecialChar ~
16080 \SpecialChar ~
16081 \SpecialChar ~
16082 sdcc -S -V -mpic14 -p16F877 $<
16083 \newline
16084 \SpecialChar ~
16085 \SpecialChar ~
16086 \SpecialChar ~
16087 \SpecialChar ~
16088 \SpecialChar ~
16089 \SpecialChar ~
16090 \SpecialChar ~
16091 \SpecialChar ~
16092 gpasm -c $*.asm
16093 \newline
16094
16095 \newline
16096 $(PRJ).hex: $(OBJS)
16097 \newline
16098 \SpecialChar ~
16099 \SpecialChar ~
16100 \SpecialChar ~
16101 \SpecialChar ~
16102 \SpecialChar ~
16103 \SpecialChar ~
16104 \SpecialChar ~
16105 \SpecialChar ~
16106 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS) libsdcc.lib
16107 \layout Standard
16108
16109 Here is a
16110 \family typewriter
16111 Makefile
16112 \family default
16113  using MPLAB:
16114 \layout Verse
16115
16116
16117 \family typewriter
16118 .c.o:
16119 \newline
16120 \SpecialChar ~
16121 \SpecialChar ~
16122 \SpecialChar ~
16123 \SpecialChar ~
16124 \SpecialChar ~
16125 \SpecialChar ~
16126 \SpecialChar ~
16127 \SpecialChar ~
16128 sdcc -S -V -mpic14 -p16F877 $<
16129 \newline
16130 \SpecialChar ~
16131 \SpecialChar ~
16132 \SpecialChar ~
16133 \SpecialChar ~
16134 \SpecialChar ~
16135 \SpecialChar ~
16136 \SpecialChar ~
16137 \SpecialChar ~
16138 mpasmwin /q /o $*.asm
16139 \newline
16140
16141 \newline
16142 $(PRJ).hex: $(OBJS)
16143 \newline
16144 \SpecialChar ~
16145 \SpecialChar ~
16146 \SpecialChar ~
16147 \SpecialChar ~
16148 \SpecialChar ~
16149 \SpecialChar ~
16150 \SpecialChar ~
16151 \SpecialChar ~
16152 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS) libsdcc.lib
16153 \layout Standard
16154
16155 Please note that indentations within a
16156 \family typewriter
16157  Makefile
16158 \family default
16159  have to be done with a tabulator character.
16160 \layout Subsection
16161
16162 Command-line options
16163 \layout Standard
16164
16165 Besides the switches common to all SDCC backends, the PIC14 port accepts
16166  the following options (for an updated list see sdcc -
16167 \begin_inset ERT
16168 status Collapsed
16169
16170 \layout Standard
16171
16172 \backslash
16173 /
16174 \end_inset
16175
16176 -help):
16177 \layout List
16178 \labelwidthstring 00.00.0000
16179
16180 -
16181 \begin_inset ERT
16182 status Collapsed
16183
16184 \layout Standard
16185
16186 \backslash
16187 /
16188 \end_inset
16189
16190 -debug-extra emit debug info in assembly output
16191 \layout List
16192 \labelwidthstring 00.00.0000
16193
16194 -
16195 \begin_inset ERT
16196 status Collapsed
16197
16198 \layout Standard
16199
16200 \backslash
16201 /
16202 \end_inset
16203
16204 -no-pcode-opt disable (slightly faulty) optimization on pCode
16205 \layout Subsection
16206
16207 The library
16208 \layout Subsubsection
16209
16210 error: missing definition for symbol
16211 \begin_inset Quotes sld
16212 \end_inset
16213
16214 __gptrget1
16215 \begin_inset Quotes srd
16216 \end_inset
16217
16218
16219 \layout Standard
16220
16221 The PIC14 port uses library routines to provide more complex operations
16222  like multiplication, division/modulus and (generic) pointer dereferencing.
16223  In order to add these routines to your project, you must link with PIC14's
16224
16225 \family typewriter
16226 libsdcc.lib
16227 \family default
16228 .
16229  For single source file projects this is done automatically, more complex
16230  projects must add
16231 \family typewriter
16232 libsdcc.lib
16233 \family default
16234  to the linker's arguments.
16235  Make sure you also add an include path for the library (using the -I switch
16236  to the linker)!
16237 \layout Subsubsection
16238
16239 Processor mismatch in file
16240 \begin_inset Quotes sld
16241 \end_inset
16242
16243 XXX
16244 \begin_inset Quotes srd
16245 \end_inset
16246
16247 .
16248 \layout Standard
16249
16250 This warning can usually be ignored due to the very good compatibility amongst
16251  14 bit PIC devices.
16252 \layout Standard
16253
16254 You might also consider recompiling the library for your specific device
16255  by changing the ARCH=p16f877 (default target) entry in
16256 \family typewriter
16257 device/lib/pic/Makefile.in
16258 \family default
16259  and
16260 \family typewriter
16261 device/lib/pic/Makefile
16262 \family default
16263  to reflect your device.
16264  This might even improve performance for smaller devices as unneccesary
16265  BANKSELs migth be removed.
16266 \layout Subsection
16267
16268 Known bugs
16269 \layout Subsubsection
16270
16271 initialized data
16272 \layout Standard
16273
16274 Currently, data can only be initialized if it resides in the source file
16275  together with
16276 \emph on
16277 main()
16278 \emph default
16279 .
16280  Data in other source files will silently
16281 \series bold
16282 not
16283 \series default
16284  be initialized.
16285 \layout Section
16286
16287 The PIC16
16288 \begin_inset LatexCommand \index{PIC16}
16289
16290 \end_inset
16291
16292  port
16293 \layout Standard
16294
16295 The PIC16
16296 \begin_inset LatexCommand \index{PIC16}
16297
16298 \end_inset
16299
16300  port is the portion of SDCC that is responsible to produce code for the
16301  Microchip
16302 \begin_inset LatexCommand \index{Microchip}
16303
16304 \end_inset
16305
16306 (TM) microcontrollers with 16 bit core.
16307  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
16308  Currently supported devices are:
16309 \layout Standard
16310 \align center
16311
16312 \begin_inset  Tabular
16313 <lyxtabular version="3" rows="4" columns="6">
16314 <features>
16315 <column alignment="center" valignment="top" leftline="true" width="0">
16316 <column alignment="center" valignment="top" leftline="true" width="0">
16317 <column alignment="center" valignment="top" leftline="true" width="0">
16318 <column alignment="center" valignment="top" leftline="true" width="0">
16319 <column alignment="center" valignment="top" leftline="true" width="0">
16320 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16321 <row topline="true">
16322 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16323 \begin_inset Text
16324
16325 \layout Standard
16326
16327 18F242
16328 \end_inset
16329 </cell>
16330 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16331 \begin_inset Text
16332
16333 \layout Standard
16334
16335 18F248
16336 \end_inset
16337 </cell>
16338 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16339 \begin_inset Text
16340
16341 \layout Standard
16342
16343 18F252
16344 \end_inset
16345 </cell>
16346 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16347 \begin_inset Text
16348
16349 \layout Standard
16350
16351 18F258
16352 \end_inset
16353 </cell>
16354 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16355 \begin_inset Text
16356
16357 \layout Standard
16358
16359 18F442
16360 \end_inset
16361 </cell>
16362 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16363 \begin_inset Text
16364
16365 \layout Standard
16366
16367 18F448
16368 \end_inset
16369 </cell>
16370 </row>
16371 <row topline="true">
16372 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16373 \begin_inset Text
16374
16375 \layout Standard
16376
16377 18F452
16378 \end_inset
16379 </cell>
16380 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16381 \begin_inset Text
16382
16383 \layout Standard
16384
16385 18F458
16386 \end_inset
16387 </cell>
16388 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16389 \begin_inset Text
16390
16391 \layout Standard
16392
16393 18F1220
16394 \end_inset
16395 </cell>
16396 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16397 \begin_inset Text
16398
16399 \layout Standard
16400
16401 18F2220
16402 \end_inset
16403 </cell>
16404 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16405 \begin_inset Text
16406
16407 \layout Standard
16408
16409 18F2550
16410 \end_inset
16411 </cell>
16412 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16413 \begin_inset Text
16414
16415 \layout Standard
16416
16417 18F4331
16418 \end_inset
16419 </cell>
16420 </row>
16421 <row topline="true">
16422 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16423 \begin_inset Text
16424
16425 \layout Standard
16426
16427 18F4455
16428 \end_inset
16429 </cell>
16430 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16431 \begin_inset Text
16432
16433 \layout Standard
16434
16435 18F6520
16436 \end_inset
16437 </cell>
16438 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16439 \begin_inset Text
16440
16441 \layout Standard
16442
16443 18F6620
16444 \end_inset
16445 </cell>
16446 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16447 \begin_inset Text
16448
16449 \layout Standard
16450
16451 18F6680
16452 \end_inset
16453 </cell>
16454 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16455 \begin_inset Text
16456
16457 \layout Standard
16458
16459 18F6720
16460 \end_inset
16461 </cell>
16462 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16463 \begin_inset Text
16464
16465 \layout Standard
16466
16467 18F8520
16468 \end_inset
16469 </cell>
16470 </row>
16471 <row topline="true" bottomline="true">
16472 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16473 \begin_inset Text
16474
16475 \layout Standard
16476
16477 18F8620
16478 \end_inset
16479 </cell>
16480 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16481 \begin_inset Text
16482
16483 \layout Standard
16484
16485 18F8680
16486 \end_inset
16487 </cell>
16488 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16489 \begin_inset Text
16490
16491 \layout Standard
16492
16493 18F8720
16494 \end_inset
16495 </cell>
16496 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16497 \begin_inset Text
16498
16499 \layout Standard
16500
16501 \end_inset
16502 </cell>
16503 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16504 \begin_inset Text
16505
16506 \layout Standard
16507
16508 \end_inset
16509 </cell>
16510 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16511 \begin_inset Text
16512
16513 \layout Standard
16514
16515 \end_inset
16516 </cell>
16517 </row>
16518 </lyxtabular>
16519
16520 \end_inset
16521
16522
16523 \layout Subsection
16524
16525 Global Options
16526 \layout Standard
16527
16528 PIC16 port supports the standard command line arguments as supposed, with
16529  the exception of certain cases that will be mentioned in the following
16530  list:
16531 \layout List
16532 \labelwidthstring 00.00.0000
16533
16534 -
16535 \begin_inset ERT
16536 status Collapsed
16537
16538 \layout Standard
16539
16540 \backslash
16541 /
16542 \end_inset
16543
16544 -callee-saves See -
16545 \begin_inset ERT
16546 status Collapsed
16547
16548 \layout Standard
16549
16550 \backslash
16551 /
16552 \end_inset
16553
16554 -all-callee-saves
16555 \layout List
16556 \labelwidthstring 00.00.0000
16557
16558 -
16559 \begin_inset ERT
16560 status Collapsed
16561
16562 \layout Standard
16563
16564 \backslash
16565 /
16566 \end_inset
16567
16568 -all-callee-saves All function arguments are passed on stack by default.
16569
16570 \emph on
16571 There is no need to specify this in the command line.
16572 \layout List
16573 \labelwidthstring 00.00.0000
16574
16575 -
16576 \begin_inset ERT
16577 status Collapsed
16578
16579 \layout Standard
16580
16581 \backslash
16582 /
16583 \end_inset
16584
16585 -fommit-frame-pointer Frame pointer will be omitted when the function uses
16586  no local variables.
16587 \layout Subsection
16588
16589 Port Specific Options
16590 \begin_inset LatexCommand \index{Options PIC16}
16591
16592 \end_inset
16593
16594
16595 \layout Standard
16596
16597 The port specific options appear after the global options in the sdcc --help
16598  output.
16599 \layout Subsubsection
16600
16601 General Options
16602 \layout Standard
16603
16604 General options enable certain port features and optimizations.
16605 \layout List
16606 \labelwidthstring 00.00.0000
16607
16608 -
16609 \begin_inset ERT
16610 status Collapsed
16611
16612 \layout Standard
16613
16614 \backslash
16615 /
16616 \end_inset
16617
16618 -stack-model=[model] Used in conjuction with the command above.
16619  Defines the stack model to be used, valid stack models are :
16620 \begin_deeper
16621 \layout List
16622 \labelwidthstring 00.00.0000
16623
16624
16625 \emph on
16626 small
16627 \emph default
16628  Selects small stack model.
16629  8 bit stack and frame pointers.
16630  Supports 256 bytes stack size.
16631 \layout List
16632 \labelwidthstring 00.00.0000
16633
16634
16635 \emph on
16636 large
16637 \emph default
16638  Selects large stack model.
16639  16 bit stack and frame pointers.
16640  Supports 65536 bytes stack size.
16641 \end_deeper
16642 \layout List
16643 \labelwidthstring 00.00.0000
16644
16645 -
16646 \begin_inset ERT
16647 status Collapsed
16648
16649 \layout Standard
16650
16651 \backslash
16652 /
16653 \end_inset
16654
16655 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
16656  unitialized data variables with [kword].
16657  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
16658 \layout List
16659 \labelwidthstring 00.00.0000
16660
16661 -
16662 \begin_inset ERT
16663 status Collapsed
16664
16665 \layout Standard
16666
16667 \backslash
16668 /
16669 \end_inset
16670
16671 -ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
16672  Useful for bootloaders.
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 -asm= sets the full path and name of an external assembler to call.
16687 \layout List
16688 \labelwidthstring 00.00.0000
16689
16690 -
16691 \begin_inset ERT
16692 status Collapsed
16693
16694 \layout Standard
16695
16696 \backslash
16697 /
16698 \end_inset
16699
16700 -link= sets the full path and name of an external linker to call.
16701 \layout List
16702 \labelwidthstring 00.00.0000
16703
16704 -
16705 \begin_inset ERT
16706 status Collapsed
16707
16708 \layout Standard
16709
16710 \backslash
16711 /
16712 \end_inset
16713
16714 -mplab-comp MPLAB compatibility option.
16715  Currently only suppresses special gpasm directives.
16716 \layout Subsubsection
16717
16718 Optimization Options
16719 \layout List
16720 \labelwidthstring 00.00.0000
16721
16722 -
16723 \begin_inset ERT
16724 status Collapsed
16725
16726 \layout Standard
16727
16728 \backslash
16729 /
16730 \end_inset
16731
16732 -optimize-goto Try to use (conditional) BRA instead of GOTO
16733 \layout List
16734 \labelwidthstring 00.00.0000
16735
16736 -
16737 \begin_inset ERT
16738 status Collapsed
16739
16740 \layout Standard
16741
16742 \backslash
16743 /
16744 \end_inset
16745
16746 -optimize-cmp Try to optimize some compares.
16747 \layout List
16748 \labelwidthstring 00.00.0000
16749
16750 -
16751 \begin_inset ERT
16752 status Collapsed
16753
16754 \layout Standard
16755
16756 \backslash
16757 /
16758 \end_inset
16759
16760 -optimize-df Analyze the dataflow of the generated code and improve it.
16761 \layout List
16762 \labelwidthstring 00.00.0000
16763
16764 -
16765 \begin_inset ERT
16766 status Collapsed
16767
16768 \layout Standard
16769
16770 \backslash
16771 /
16772 \end_inset
16773
16774 -obanksel=nn Set optimization level for inserting BANKSELs.
16775 \newline
16776
16777 \begin_deeper
16778 \layout List
16779 \labelwidthstring 00.00.0000
16780
16781 0 no optimization
16782 \layout List
16783 \labelwidthstring 00.00.0000
16784
16785 1 checks previous used register and if it is the same then does not emit
16786  BANKSEL, accounts only for labels.
16787 \layout List
16788 \labelwidthstring 00.00.0000
16789
16790 2 tries to check the location of (even different) symbols and removes BANKSELs
16791  if they are in the same bank.
16792
16793 \newline
16794
16795 \emph on
16796 Important: There might be problems if the linker script has data sections
16797  across bank borders!
16798 \end_deeper
16799 \layout Subsubsection
16800
16801 Linking Options
16802 \layout List
16803 \labelwidthstring 00.00.0000
16804
16805 -
16806 \begin_inset ERT
16807 status Collapsed
16808
16809 \layout Standard
16810
16811 \backslash
16812 /
16813 \end_inset
16814
16815 -nodefaultlibs do not link default libraries when linking
16816 \layout List
16817 \labelwidthstring 00.00.0000
16818
16819 -
16820 \begin_inset ERT
16821 status Collapsed
16822
16823 \layout Standard
16824
16825 \backslash
16826 /
16827 \end_inset
16828
16829 -no-crt Don't link the default run-time modules
16830 \layout List
16831 \labelwidthstring 00.00.0000
16832
16833 -
16834 \begin_inset ERT
16835 status Collapsed
16836
16837 \layout Standard
16838
16839 \backslash
16840 /
16841 \end_inset
16842
16843 -use-crt= Use a custom run-time module instead of the defaults.
16844 \layout Subsubsection
16845
16846 Debugging Options
16847 \layout Standard
16848
16849 Debugging options enable extra debugging information in the output files.
16850 \layout List
16851 \labelwidthstring 00.00.0000
16852
16853 -
16854 \begin_inset ERT
16855 status Collapsed
16856
16857 \layout Standard
16858
16859 \backslash
16860 /
16861 \end_inset
16862
16863 -debug-xtra Similar to -
16864 \begin_inset ERT
16865 status Collapsed
16866
16867 \layout Standard
16868
16869 \backslash
16870 /
16871 \end_inset
16872
16873 -debug
16874 \begin_inset LatexCommand \index{-\/-debug}
16875
16876 \end_inset
16877
16878 , but dumps more information.
16879 \layout List
16880 \labelwidthstring 00.00.0000
16881
16882 -
16883 \begin_inset ERT
16884 status Collapsed
16885
16886 \layout Standard
16887
16888 \backslash
16889 /
16890 \end_inset
16891
16892 -debug-ralloc Force register allocator to dump <source>.d file with debugging
16893  information.
16894  <source> is the name of the file compiled.
16895 \layout List
16896 \labelwidthstring 00.00.0000
16897
16898 -
16899 \begin_inset ERT
16900 status Collapsed
16901
16902 \layout Standard
16903
16904 \backslash
16905 /
16906 \end_inset
16907
16908 -pcode-verbose Enable pcode debugging information in translation.
16909 \layout List
16910 \labelwidthstring 00.00.0000
16911
16912 -
16913 \begin_inset ERT
16914 status Collapsed
16915
16916 \layout Standard
16917
16918 \backslash
16919 /
16920 \end_inset
16921
16922 -denable-peeps Force the usage of peepholes.
16923  Use with care.
16924 \layout List
16925 \labelwidthstring 00.00.0000
16926
16927 -
16928 \begin_inset ERT
16929 status Collapsed
16930
16931 \layout Standard
16932
16933 \backslash
16934 /
16935 \end_inset
16936
16937 -gstack Trace push/pops for stack pointer overflow
16938 \layout List
16939 \labelwidthstring 00.00.0000
16940
16941 -
16942 \begin_inset ERT
16943 status Collapsed
16944
16945 \layout Standard
16946
16947 \backslash
16948 /
16949 \end_inset
16950
16951 -call-tree dump call tree in .calltree file
16952 \layout Subsection
16953
16954 Enviromental Variables
16955 \layout Standard
16956
16957 There is a number of enviromental variables that can be used when running
16958  SDCC to enable certain optimizations or force a specific program behaviour.
16959  these variables are primarily for debugging purposes so they can be enabled/dis
16960 abled at will.
16961 \layout Standard
16962
16963 Currently there is only two such variables available:
16964 \layout List
16965 \labelwidthstring 00.00.0000
16966
16967 OPTIMIZE_BITFIELD_POINTER_GET when this variable exists reading of structure
16968  bitfields is optimized by directly loading FSR0 with the address of the
16969  bitfield structure.
16970  Normally SDCC will cast the bitfield structure to a bitfield pointer and
16971  then load FSR0.
16972  This step saves data ram and code space for functions that perform heavy
16973  use of bitfields.
16974  (ie.
16975  80 bytes of code space are saved when compiling malloc.c with this option).
16976
16977 \layout List
16978 \labelwidthstring 00.00.0000
16979
16980 NO_REG_OPT do not perform pCode registers optimization.
16981  This should be used for debugging purposes.
16982  In some where bugs in the pcode optimizer are found, users can benefit
16983  from temporarily disabling the optimizer until the bug is fixed.
16984 \layout Subsection
16985
16986 Preprocessor Macros
16987 \layout Standard
16988
16989 PIC16 port defines the following preprocessor macros while translating a
16990  source.
16991 \layout Standard
16992 \align center
16993
16994 \begin_inset  Tabular
16995 <lyxtabular version="3" rows="6" columns="2">
16996 <features>
16997 <column alignment="center" valignment="top" leftline="true" width="0">
16998 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16999 <row topline="true" bottomline="true">
17000 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17001 \begin_inset Text
17002
17003 \layout Standard
17004
17005 Macro
17006 \end_inset
17007 </cell>
17008 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17009 \begin_inset Text
17010
17011 \layout Standard
17012
17013 Description
17014 \end_inset
17015 </cell>
17016 </row>
17017 <row topline="true">
17018 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17019 \begin_inset Text
17020
17021 \layout Standard
17022
17023 SDCC_pic16
17024 \end_inset
17025 </cell>
17026 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17027 \begin_inset Text
17028
17029 \layout Standard
17030
17031 Port identification
17032 \end_inset
17033 </cell>
17034 </row>
17035 <row topline="true">
17036 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17037 \begin_inset Text
17038
17039 \layout Standard
17040
17041 _
17042 \begin_inset ERT
17043 status Collapsed
17044
17045 \layout Standard
17046
17047 \backslash
17048 /
17049 \end_inset
17050
17051 _pic16
17052 \end_inset
17053 </cell>
17054 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17055 \begin_inset Text
17056
17057 \layout Standard
17058
17059 Port identification (same as above)
17060 \end_inset
17061 </cell>
17062 </row>
17063 <row topline="true">
17064 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17065 \begin_inset Text
17066
17067 \layout Standard
17068
17069 pic18fxxxx
17070 \end_inset
17071 </cell>
17072 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17073 \begin_inset Text
17074
17075 \layout Standard
17076
17077 MCU Identification.
17078
17079 \emph on
17080 xxxx
17081 \emph default
17082  is the microcontrol identification number, i.e.
17083  452, 6620, etc
17084 \end_inset
17085 </cell>
17086 </row>
17087 <row topline="true">
17088 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17089 \begin_inset Text
17090
17091 \layout Standard
17092
17093 _
17094 \begin_inset ERT
17095 status Collapsed
17096
17097 \layout Standard
17098
17099 \backslash
17100 /
17101 \end_inset
17102
17103 _18Fxxxx
17104 \end_inset
17105 </cell>
17106 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17107 \begin_inset Text
17108
17109 \layout Standard
17110
17111 MCU Identification (same as above)
17112 \end_inset
17113 </cell>
17114 </row>
17115 <row topline="true" bottomline="true">
17116 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17117 \begin_inset Text
17118
17119 \layout Standard
17120
17121 STACK_MODEL_nnn
17122 \end_inset
17123 </cell>
17124 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17125 \begin_inset Text
17126
17127 \layout Standard
17128
17129 nnn = SMALL or LARGE respectively according to the stack model used
17130 \end_inset
17131 </cell>
17132 </row>
17133 </lyxtabular>
17134
17135 \end_inset
17136
17137
17138 \layout Standard
17139
17140 In addition the following macros are defined when calling assembler:
17141 \layout Standard
17142 \align center
17143
17144 \begin_inset  Tabular
17145 <lyxtabular version="3" rows="4" columns="2">
17146 <features>
17147 <column alignment="center" valignment="top" leftline="true" width="0">
17148 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17149 <row topline="true" bottomline="true">
17150 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17151 \begin_inset Text
17152
17153 \layout Standard
17154
17155 Macro
17156 \end_inset
17157 </cell>
17158 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17159 \begin_inset Text
17160
17161 \layout Standard
17162
17163 Description
17164 \end_inset
17165 </cell>
17166 </row>
17167 <row topline="true">
17168 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17169 \begin_inset Text
17170
17171 \layout Standard
17172
17173 __18Fxxxx
17174 \end_inset
17175 </cell>
17176 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17177 \begin_inset Text
17178
17179 \layout Standard
17180
17181 MCU Identification.
17182
17183 \emph on
17184 xxxx
17185 \emph default
17186  is the microcontrol identification number, i.e.
17187  452, 6620, etc
17188 \end_inset
17189 </cell>
17190 </row>
17191 <row topline="true">
17192 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17193 \begin_inset Text
17194
17195 \layout Standard
17196
17197 SDCC_MODEL_nnn
17198 \end_inset
17199 </cell>
17200 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17201 \begin_inset Text
17202
17203 \layout Standard
17204
17205 nnn = SMALL or LARGE respectively according to the memory model used for
17206  SDCC
17207 \end_inset
17208 </cell>
17209 </row>
17210 <row topline="true" bottomline="true">
17211 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17212 \begin_inset Text
17213
17214 \layout Standard
17215
17216 STACK_MODEL_nnn
17217 \end_inset
17218 </cell>
17219 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17220 \begin_inset Text
17221
17222 \layout Standard
17223
17224 nnn = SMALL or LARGE respectively according to the stack model used
17225 \end_inset
17226 </cell>
17227 </row>
17228 </lyxtabular>
17229
17230 \end_inset
17231
17232
17233 \layout Subsection
17234
17235 Directories
17236 \layout Standard
17237
17238 PIC16
17239 \begin_inset LatexCommand \index{PIC16}
17240
17241 \end_inset
17242
17243  port uses the following directories for searching header files and libraries.
17244 \layout Standard
17245 \align center
17246
17247 \begin_inset  Tabular
17248 <lyxtabular version="3" rows="3" columns="4">
17249 <features>
17250 <column alignment="center" valignment="top" leftline="true" width="0">
17251 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17252 <column alignment="center" valignment="top" width="0">
17253 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17254 <row topline="true" bottomline="true">
17255 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17256 \begin_inset Text
17257
17258 \layout Standard
17259
17260 Directory
17261 \end_inset
17262 </cell>
17263 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17264 \begin_inset Text
17265
17266 \layout Standard
17267
17268 Description
17269 \end_inset
17270 </cell>
17271 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17272 \begin_inset Text
17273
17274 \layout Standard
17275
17276 Target
17277 \end_inset
17278 </cell>
17279 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17280 \begin_inset Text
17281
17282 \layout Standard
17283
17284 Command prefix
17285 \end_inset
17286 </cell>
17287 </row>
17288 <row topline="true">
17289 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17290 \begin_inset Text
17291
17292 \layout Standard
17293
17294 PREFIX/sdcc/include/pic16
17295 \end_inset
17296 </cell>
17297 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17298 \begin_inset Text
17299
17300 \layout Standard
17301
17302 PIC16 specific headers
17303 \end_inset
17304 </cell>
17305 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17306 \begin_inset Text
17307
17308 \layout Standard
17309
17310 Compiler
17311 \end_inset
17312 </cell>
17313 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17314 \begin_inset Text
17315
17316 \layout Standard
17317
17318 -I
17319 \end_inset
17320 </cell>
17321 </row>
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 PREFIX/sdcc/lib/pic16
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 PIC16 specific libraries
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 Linker
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 -L
17353 \end_inset
17354 </cell>
17355 </row>
17356 </lyxtabular>
17357
17358 \end_inset
17359
17360
17361 \layout Subsection
17362
17363 Pragmas
17364 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
17365
17366 \end_inset
17367
17368
17369 \layout Standard
17370
17371 PIC16 port currently supports the following pragmas:
17372 \layout List
17373 \labelwidthstring 00.00.0000
17374
17375 stack pragma stack forces the code generator to initialize the stack & frame
17376  pointers at a specific address.
17377  This is an adhoc solution for cases where no STACK directive is available
17378  in the linker script or gplink is not instructed to create a stack section.
17379 \newline
17380 The stack pragma should be used only once in a project.
17381  Multiple pragmas may result in indeterminate behaviour of the program.
17382 \begin_inset Foot
17383 collapsed false
17384
17385 \layout Standard
17386
17387 The old format (ie.
17388  #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
17389  cross page boundaries (or even exceed the available data RAM) and crash
17390  the program.
17391  Make sure that stack does not cross page boundaries when using the SMALL
17392  stack model.
17393 \end_inset
17394
17395
17396 \newline
17397 The format is as follows:
17398 \layout LyX-Code
17399
17400 #pragma stack bottom_address [stack_size]
17401 \layout Standard
17402
17403
17404 \emph on
17405 bottom_address
17406 \emph default
17407  is the lower bound of the stack section.
17408  The stack pointer initially will point at address (bottom_address+stack_size-1).
17409 \layout LyX-Code
17410
17411 Example:
17412 \layout LyX-Code
17413
17414 \layout LyX-Code
17415
17416 /* initializes stack of 100 bytes at RAM address 0x200 */
17417 \layout LyX-Code
17418
17419 #pragma stack 0x200 100
17420 \layout Standard
17421
17422 If the stack_size field is omitted then a stack is created with the default
17423  size of 64.
17424  This size might be enough for most programs, but its not enough for operations
17425  with deep function nesting or excessive stack usage.
17426 \layout List
17427 \labelwidthstring 00.00.0000
17428
17429 wparam
17430 \emph on
17431 This pragma is deprecated.
17432  Its use will cause a warning message to be issued.
17433 \emph default
17434
17435 \newline
17436
17437 \layout List
17438 \labelwidthstring 00.00.0000
17439
17440 code place a function symbol at static FLASH address
17441 \layout LyX-Code
17442
17443 Example:
17444 \layout LyX-Code
17445
17446 \layout LyX-Code
17447
17448 /* place function test_func at 0x4000 */
17449 \layout LyX-Code
17450
17451 #pragma code test_func 0x4000
17452 \layout LyX-Code
17453
17454 \layout List
17455 \labelwidthstring 00.00.0000
17456
17457 library instructs the linker to use a library module.
17458 \newline
17459 Usage:
17460 \layout LyX-Code
17461
17462 #pragma library module_name
17463 \layout Standard
17464
17465
17466 \emph on
17467 module_name
17468 \emph default
17469  can be any library or object file (including its path).
17470  Note that there are four reserved keywords which have special meaning.
17471  These are:
17472 \layout Standard
17473 \align center
17474
17475 \begin_inset  Tabular
17476 <lyxtabular version="3" rows="6" columns="3">
17477 <features>
17478 <column alignment="center" valignment="top" leftline="true" width="0">
17479 <column alignment="block" valignment="top" leftline="true" width="20page%">
17480 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
17481 <row topline="true" bottomline="true">
17482 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17483 \begin_inset Text
17484
17485 \layout Standard
17486
17487 Keyword
17488 \end_inset
17489 </cell>
17490 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17491 \begin_inset Text
17492
17493 \layout Standard
17494
17495 Description
17496 \end_inset
17497 </cell>
17498 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17499 \begin_inset Text
17500
17501 \layout Standard
17502
17503 Module to link
17504 \end_inset
17505 </cell>
17506 </row>
17507 <row topline="true">
17508 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17509 \begin_inset Text
17510
17511 \layout Standard
17512
17513
17514 \series bold
17515 ignore
17516 \end_inset
17517 </cell>
17518 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17519 \begin_inset Text
17520
17521 \layout Standard
17522
17523 ignore all library pragmas
17524 \end_inset
17525 </cell>
17526 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17527 \begin_inset Text
17528
17529 \layout Standard
17530
17531
17532 \emph on
17533 (none)
17534 \end_inset
17535 </cell>
17536 </row>
17537 <row topline="true">
17538 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17539 \begin_inset Text
17540
17541 \layout Standard
17542
17543
17544 \series bold
17545 c
17546 \end_inset
17547 </cell>
17548 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17549 \begin_inset Text
17550
17551 \layout Standard
17552
17553 link the C library
17554 \end_inset
17555 </cell>
17556 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17557 \begin_inset Text
17558
17559 \layout Standard
17560
17561
17562 \emph on
17563 libc18f
17564 \emph default
17565 .lib
17566 \end_inset
17567 </cell>
17568 </row>
17569 <row topline="true">
17570 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17571 \begin_inset Text
17572
17573 \layout Standard
17574
17575
17576 \series bold
17577 math
17578 \end_inset
17579 </cell>
17580 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17581 \begin_inset Text
17582
17583 \layout Standard
17584
17585 link the Math libarary
17586 \end_inset
17587 </cell>
17588 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17589 \begin_inset Text
17590
17591 \layout Standard
17592
17593
17594 \emph on
17595 libm18f
17596 \emph default
17597 .lib
17598 \end_inset
17599 </cell>
17600 </row>
17601 <row topline="true">
17602 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17603 \begin_inset Text
17604
17605 \layout Standard
17606
17607
17608 \series bold
17609 io
17610 \end_inset
17611 </cell>
17612 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17613 \begin_inset Text
17614
17615 \layout Standard
17616
17617 link the I/O library
17618 \end_inset
17619 </cell>
17620 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17621 \begin_inset Text
17622
17623 \layout Standard
17624
17625
17626 \emph on
17627 libio18f*
17628 \emph default
17629 .lib
17630 \end_inset
17631 </cell>
17632 </row>
17633 <row topline="true" bottomline="true">
17634 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17635 \begin_inset Text
17636
17637 \layout Standard
17638
17639
17640 \series bold
17641 debug
17642 \end_inset
17643 </cell>
17644 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17645 \begin_inset Text
17646
17647 \layout Standard
17648
17649 link the debug library
17650 \end_inset
17651 </cell>
17652 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17653 \begin_inset Text
17654
17655 \layout Standard
17656
17657
17658 \emph on
17659 libdebug
17660 \emph default
17661 .lib
17662 \end_inset
17663 </cell>
17664 </row>
17665 </lyxtabular>
17666
17667 \end_inset
17668
17669
17670 \newline
17671 * is the device number, i.e.
17672  452 for PIC18F452 MCU.
17673 \layout Standard
17674
17675 This feature allows for linking with specific libraries withoug having to
17676  explicit name them in the command line.
17677  Note that the
17678 \noun on
17679 ignore
17680 \noun default
17681  keyword will reject all modules specified by the library pragma.
17682 \layout List
17683 \labelwidthstring 00.00.0000
17684
17685 udata pragma udata instructs the compiler to emit code so that linker will
17686  place a variable at a specific memory bank
17687 \layout LyX-Code
17688
17689 Example:
17690 \layout LyX-Code
17691
17692 \layout LyX-Code
17693
17694 /* places variable foo at bank2 */
17695 \layout LyX-Code
17696
17697 #pragma udata bank2 foo
17698 \layout LyX-Code
17699
17700 char foo;
17701 \layout Standard
17702
17703 In order for this pragma to work extra SECTION directives should be added
17704  in the .lkr script.
17705  In the following example a sample .lkr file is shown:
17706 \layout LyX-Code
17707
17708 \layout LyX-Code
17709
17710 // Sample linker script for the PIC18F452 processor
17711 \layout LyX-Code
17712
17713 LIBPATH .
17714 \layout LyX-Code
17715
17716 CODEPAGE   NAME=vectors    START=0x0            END=0x29           PROTECTED
17717 \layout LyX-Code
17718
17719 CODEPAGE   NAME=page       START=0x2A           END=0x7FFF
17720 \layout LyX-Code
17721
17722 CODEPAGE   NAME=idlocs     START=0x200000       END=0x200007       PROTECTED
17723 \layout LyX-Code
17724
17725 CODEPAGE   NAME=config     START=0x300000       END=0x30000D       PROTECTED
17726 \layout LyX-Code
17727
17728 CODEPAGE   NAME=devid      START=0x3FFFFE       END=0x3FFFFF       PROTECTED
17729 \layout LyX-Code
17730
17731 CODEPAGE   NAME=eedata     START=0xF00000       END=0xF000FF       PROTECTED
17732 \layout LyX-Code
17733
17734 ACCESSBANK NAME=accessram  START=0x0            END=0x7F
17735 \layout LyX-Code
17736
17737 \layout LyX-Code
17738
17739 DATABANK   NAME=gpr0       START=0x80           END=0xFF
17740 \layout LyX-Code
17741
17742 DATABANK   NAME=gpr1       START=0x100          END=0x1FF
17743 \layout LyX-Code
17744
17745 DATABANK   NAME=gpr2       START=0x200          END=0x2FF
17746 \layout LyX-Code
17747
17748 DATABANK   NAME=gpr3       START=0x300          END=0x3FF
17749 \layout LyX-Code
17750
17751 DATABANK   NAME=gpr4       START=0x400          END=0x4FF
17752 \layout LyX-Code
17753
17754 DATABANK   NAME=gpr5       START=0x500          END=0x5FF
17755 \layout LyX-Code
17756
17757 ACCESSBANK NAME=accesssfr  START=0xF80          END=0xFFF          PROTECTED
17758 \layout LyX-Code
17759
17760 \layout LyX-Code
17761
17762 SECTION    NAME=CONFIG     ROM=config
17763 \layout LyX-Code
17764
17765 \layout LyX-Code
17766
17767 SECTION    NAME=bank0      RAM=gpr0       # these SECTION directives
17768 \layout LyX-Code
17769
17770 SECTION    NAME=bank1      RAM=gpr1       # should be added to link
17771 \layout LyX-Code
17772
17773 SECTION    NAME=bank2      RAM=gpr2       # section name 'bank?' with
17774 \layout LyX-Code
17775
17776 SECTION    NAME=bank3      RAM=gpr3       # a specific DATABANK name
17777 \layout LyX-Code
17778
17779 SECTION    NAME=bank4      RAM=gpr4
17780 \layout LyX-Code
17781
17782 SECTION    NAME=bank5      RAM=gpr5
17783 \layout Standard
17784
17785 The linker will recognise the section name set in the pragma statement and
17786  will position the variable at the memory bank set with the RAM field at
17787  the SECTION line in the linker script file.
17788 \layout Subsection
17789
17790 Header Files
17791 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
17792
17793 \end_inset
17794
17795
17796 \layout Standard
17797
17798 There is one main header file that can be included to the source files using
17799  the pic16 port.
17800  That file is the
17801 \series bold
17802 pic18fregs.h
17803 \series default
17804 .
17805  This header file contains the definitions for the processor special registers,
17806  so it is necessary if the source accesses them.
17807  It can be included by adding the following line in the beginning of the
17808  file:
17809 \layout LyX-Code
17810
17811 #include <pic18fregs.h>
17812 \layout Standard
17813
17814 The specific microcontroller is selected within the pic18fregs.h automatically,
17815  so the same source can be used with a variety of devices.
17816 \layout Subsection
17817
17818 Libraries
17819 \layout Standard
17820
17821 The libraries that PIC16
17822 \begin_inset LatexCommand \index{PIC16}
17823
17824 \end_inset
17825
17826  port depends on are the microcontroller device libraries which contain
17827  the symbol definitions for the microcontroller special function registers.
17828  These libraries have the format pic18fxxxx.lib, where
17829 \emph on
17830 xxxx
17831 \emph default
17832  is the microcontroller identification number.
17833  The specific library is selected automatically by the compiler at link
17834  stage according to the selected device.
17835 \layout Standard
17836
17837 Libraries are created with gplib which is part of the gputils package
17838 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
17839
17840 \end_inset
17841
17842 .
17843 \layout Subsubsection*
17844
17845 Building the libraries
17846 \layout Standard
17847
17848 Before using SDCC/pic16 there are some libraries that need to be compiled.
17849  This process is not done automatically by SDCC since not all users use
17850  SDCC for pic16 projects.
17851  So each user should compile the libraries separately.
17852 \layout Standard
17853
17854 The steps to compile the pic16 libraries under Linux are:
17855 \layout LyX-Code
17856
17857 cd device/lib/pic16
17858 \layout LyX-Code
17859
17860 ./configure
17861 \layout LyX-Code
17862
17863 make
17864 \layout LyX-Code
17865
17866 cd ..
17867 \layout LyX-Code
17868
17869 make model-pic16
17870 \layout LyX-Code
17871
17872 su -c 'make install'     # install the libraries, you need the root password
17873 \layout Standard
17874
17875 If you need to install the headers too, do:
17876 \layout LyX-Code
17877
17878 cd device/include
17879 \layout LyX-Code
17880
17881 su -c 'make install'     # install the headers, you need the root password
17882 \layout Standard
17883
17884 There exist a special target to build the I/O libraries.
17885  This target is not automatically build because it will build the I/O library
17886  for
17887 \emph on
17888 every
17889 \emph default
17890  supported device.
17891  This way building will take quite a lot of time.
17892  Users are advised to edit the
17893 \series bold
17894 device/lib/pic16/pics.build
17895 \series default
17896  file and then execute:
17897 \layout LyX-Code
17898
17899 make lib-io
17900 \layout Subsection
17901
17902 Memory Models
17903 \layout Standard
17904
17905 The following memory models are supported by the PIC16 port:
17906 \layout Itemize
17907
17908 small model
17909 \layout Itemize
17910
17911 large model
17912 \layout Standard
17913
17914 Memory model affects the default size of pointers within the source.
17915  The sizes are shown in the next table:
17916 \layout Standard
17917 \align center
17918
17919 \begin_inset  Tabular
17920 <lyxtabular version="3" rows="3" columns="3">
17921 <features>
17922 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17923 <column alignment="center" valignment="top" leftline="true" width="0">
17924 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17925 <row topline="true" bottomline="true">
17926 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17927 \begin_inset Text
17928
17929 \layout Standard
17930
17931 Pointer sizes according to memory model
17932 \end_inset
17933 </cell>
17934 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17935 \begin_inset Text
17936
17937 \layout Standard
17938
17939 small model
17940 \end_inset
17941 </cell>
17942 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17943 \begin_inset Text
17944
17945 \layout Standard
17946
17947 large model
17948 \end_inset
17949 </cell>
17950 </row>
17951 <row topline="true" bottomline="true">
17952 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17953 \begin_inset Text
17954
17955 \layout Standard
17956
17957 code pointers
17958 \end_inset
17959 </cell>
17960 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17961 \begin_inset Text
17962
17963 \layout Standard
17964
17965 16-bits
17966 \end_inset
17967 </cell>
17968 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17969 \begin_inset Text
17970
17971 \layout Standard
17972
17973 24-bits
17974 \end_inset
17975 </cell>
17976 </row>
17977 <row topline="true" bottomline="true">
17978 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17979 \begin_inset Text
17980
17981 \layout Standard
17982
17983 data pointers
17984 \end_inset
17985 </cell>
17986 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
17987 \begin_inset Text
17988
17989 \layout Standard
17990
17991 16-bits
17992 \end_inset
17993 </cell>
17994 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17995 \begin_inset Text
17996
17997 \layout Standard
17998
17999 16-bits
18000 \end_inset
18001 </cell>
18002 </row>
18003 </lyxtabular>
18004
18005 \end_inset
18006
18007
18008 \layout Standard
18009
18010 It is advisable that all sources within a project are compiled with the
18011  same memory model.
18012  If one wants to override the default memory model, this can be done by
18013  declaring a pointer as
18014 \series bold
18015 far
18016 \series default
18017  or
18018 \series bold
18019 near
18020 \series default
18021 .
18022  Far selects large memory model's pointers, while near selects small memory
18023  model's pointers.
18024 \layout Standard
18025
18026 The standard device libraries (see
18027 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
18028
18029 \end_inset
18030
18031 ) contain no reference to pointers, so they can be used with both memory
18032  models.
18033 \layout Subsection
18034
18035 Stack
18036 \layout Standard
18037
18038 The stack implementation for the PIC16 port uses two indirect registers,
18039  FSR1 and FSR2.
18040 \layout List
18041 \labelwidthstring 00.00.0000
18042
18043 FSR1 is assigned as stack pointer
18044 \layout List
18045 \labelwidthstring 00.00.0000
18046
18047 FSR2 is assigned as frame pointer
18048 \layout Standard
18049
18050 The following stack models are supported by the PIC16 port
18051 \layout Itemize
18052
18053
18054 \noun on
18055 small
18056 \noun default
18057  model
18058 \layout Itemize
18059
18060
18061 \noun on
18062 large
18063 \noun default
18064  model
18065 \layout Standard
18066
18067
18068 \noun on
18069 Small
18070 \noun default
18071  model means that only the FSRxL byte is used to access stack and frame,
18072  while
18073 \emph on
18074 \noun on
18075 large
18076 \emph default
18077 \noun default
18078  uses both FSRxL and FSRxH registers.
18079  The following table shows the stack/frame pointers sizes according to stack
18080  model and the maximum space they can address:
18081 \layout Standard
18082 \align center
18083
18084 \begin_inset  Tabular
18085 <lyxtabular version="3" rows="3" columns="3">
18086 <features>
18087 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18088 <column alignment="center" valignment="top" leftline="true" width="0">
18089 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18090 <row topline="true" bottomline="true">
18091 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18092 \begin_inset Text
18093
18094 \layout Standard
18095
18096 Stack & Frame pointer sizes according to stack model
18097 \end_inset
18098 </cell>
18099 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18100 \begin_inset Text
18101
18102 \layout Standard
18103
18104 small
18105 \end_inset
18106 </cell>
18107 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18108 \begin_inset Text
18109
18110 \layout Standard
18111
18112 large
18113 \end_inset
18114 </cell>
18115 </row>
18116 <row topline="true">
18117 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18118 \begin_inset Text
18119
18120 \layout Standard
18121
18122 Stack pointer FSR1
18123 \end_inset
18124 </cell>
18125 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18126 \begin_inset Text
18127
18128 \layout Standard
18129
18130 8-bits
18131 \end_inset
18132 </cell>
18133 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18134 \begin_inset Text
18135
18136 \layout Standard
18137
18138 16-bits
18139 \end_inset
18140 </cell>
18141 </row>
18142 <row topline="true" bottomline="true">
18143 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18144 \begin_inset Text
18145
18146 \layout Standard
18147
18148 Frame pointer FSR2
18149 \end_inset
18150 </cell>
18151 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18152 \begin_inset Text
18153
18154 \layout Standard
18155
18156 8-bits
18157 \end_inset
18158 </cell>
18159 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18160 \begin_inset Text
18161
18162 \layout Standard
18163
18164 16-bits
18165 \end_inset
18166 </cell>
18167 </row>
18168 </lyxtabular>
18169
18170 \end_inset
18171
18172
18173 \layout Standard
18174
18175
18176 \noun on
18177 Large
18178 \noun default
18179 stack model is currently not working properly throughout the code generator.
18180  So its use is not advised.
18181  Also there are some other points that need special care:
18182 \newline
18183
18184 \layout Enumerate
18185
18186 Do not create stack sections with size more than one physical bank (that
18187  is 256 bytes)
18188 \layout Enumerate
18189
18190 Stack sections should no cross physical bank limits (i.e.
18191  #pragma stack 0x50 0x100)
18192 \layout Standard
18193
18194 These limitations are caused by the fact that only FSRxL is modified when
18195  using SMALL stack model, so no more than 256 bytes of stack can be used.
18196  This problem will disappear after LARGE model is fully implemented.
18197 \layout Subsection
18198
18199 Functions
18200 \layout Standard
18201
18202 In addition to the standard SDCC function keywords, PIC16 port makes available
18203  two more:
18204 \layout List
18205 \labelwidthstring 00.00.0000
18206
18207 wparam Use the WREG to pass one byte of the first function argument.
18208  This improves speed but you may not use this for functions with arguments
18209  that are called via function pointers, otherwise the first byte of the
18210  first parameter will get lost.
18211  Usage:
18212 \layout LyX-Code
18213
18214 void func_wparam(int a) wparam
18215 \layout LyX-Code
18216
18217 {
18218 \layout LyX-Code
18219
18220     /* WREG hold the lower part of a */
18221 \layout LyX-Code
18222
18223     /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
18224  */
18225 \layout LyX-Code
18226
18227 ...
18228 \layout LyX-Code
18229
18230 }
18231 \layout Standard
18232
18233 This keyword replaces the deprecated wparam pragma.
18234 \layout List
18235 \labelwidthstring 00.00.0000
18236
18237 shadowregs When entering/exiting an ISR, it is possible to take advantage
18238  of the PIC18F hardware shadow registers which hold the values of WREG,
18239  STATUS and BSR registers.
18240  This can be done by adding the keyword
18241 \emph on
18242 shadowregs
18243 \emph default
18244  before the
18245 \emph on
18246 interrupt
18247 \emph default
18248  keyword in the function's header.
18249 \layout LyX-Code
18250
18251 void isr_shadow(void) shadowregs interrupt 1
18252 \layout LyX-Code
18253
18254 {
18255 \layout LyX-Code
18256
18257 ...
18258 \layout LyX-Code
18259
18260 }
18261 \layout Standard
18262
18263
18264 \emph on
18265 shadowregs
18266 \emph default
18267  instructs the code generator not to store/restore WREG, STATUS, BSR when
18268  entering/exiting the ISR.
18269 \layout Subsection
18270
18271 Function return values
18272 \layout Standard
18273
18274 Return values from functions are placed to the appropriate registers following
18275  a modified Microchip policy optimized for SDCC.
18276  The following table shows these registers:
18277 \layout Standard
18278 \align center
18279
18280 \begin_inset  Tabular
18281 <lyxtabular version="3" rows="6" columns="2">
18282 <features>
18283 <column alignment="center" valignment="top" leftline="true" width="0">
18284 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18285 <row topline="true" bottomline="true">
18286 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18287 \begin_inset Text
18288
18289 \layout Standard
18290
18291 size
18292 \end_inset
18293 </cell>
18294 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18295 \begin_inset Text
18296
18297 \layout Standard
18298
18299 destination register
18300 \end_inset
18301 </cell>
18302 </row>
18303 <row topline="true">
18304 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18305 \begin_inset Text
18306
18307 \layout Standard
18308
18309 8 bits
18310 \end_inset
18311 </cell>
18312 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18313 \begin_inset Text
18314
18315 \layout Standard
18316
18317 WREG
18318 \end_inset
18319 </cell>
18320 </row>
18321 <row topline="true">
18322 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18323 \begin_inset Text
18324
18325 \layout Standard
18326
18327 16 bits
18328 \end_inset
18329 </cell>
18330 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18331 \begin_inset Text
18332
18333 \layout Standard
18334
18335 PRODL:WREG
18336 \end_inset
18337 </cell>
18338 </row>
18339 <row topline="true">
18340 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18341 \begin_inset Text
18342
18343 \layout Standard
18344
18345 24 bits
18346 \end_inset
18347 </cell>
18348 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18349 \begin_inset Text
18350
18351 \layout Standard
18352
18353 PRODH:PRODL:WREG
18354 \end_inset
18355 </cell>
18356 </row>
18357 <row topline="true">
18358 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18359 \begin_inset Text
18360
18361 \layout Standard
18362
18363 32 bits
18364 \end_inset
18365 </cell>
18366 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18367 \begin_inset Text
18368
18369 \layout Standard
18370
18371 FSR0L:PRODH:PRODL:WREG
18372 \end_inset
18373 </cell>
18374 </row>
18375 <row topline="true" bottomline="true">
18376 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18377 \begin_inset Text
18378
18379 \layout Standard
18380
18381 >32 bits
18382 \end_inset
18383 </cell>
18384 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18385 \begin_inset Text
18386
18387 \layout Standard
18388
18389 on stack, FSR0 points to the beginning
18390 \end_inset
18391 </cell>
18392 </row>
18393 </lyxtabular>
18394
18395 \end_inset
18396
18397
18398 \layout Subsection
18399
18400 Interrupts
18401 \layout Standard
18402
18403 An interrupt servive routine (ISR) is declared using the
18404 \emph on
18405 interrupt
18406 \emph default
18407  keyword.
18408 \layout LyX-Code
18409
18410 void isr(void) interrupt
18411 \emph on
18412 n
18413 \layout LyX-Code
18414
18415 {
18416 \layout LyX-Code
18417
18418 ...
18419 \layout LyX-Code
18420
18421 }
18422 \layout Standard
18423
18424
18425 \emph on
18426 n
18427 \emph default
18428  is the interrupt number, which for PIC18F devices can be:
18429 \layout Standard
18430 \align center
18431
18432 \begin_inset  Tabular
18433 <lyxtabular version="3" rows="4" columns="3">
18434 <features>
18435 <column alignment="center" valignment="top" leftline="true" width="0">
18436 <column alignment="center" valignment="top" leftline="true" width="0">
18437 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18438 <row topline="true" bottomline="true">
18439 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18440 \begin_inset Text
18441
18442 \layout Standard
18443
18444
18445 \emph on
18446 n
18447 \end_inset
18448 </cell>
18449 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18450 \begin_inset Text
18451
18452 \layout Standard
18453
18454 Interrupt Vector
18455 \end_inset
18456 </cell>
18457 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18458 \begin_inset Text
18459
18460 \layout Standard
18461
18462 Interrupt Vector Address
18463 \end_inset
18464 </cell>
18465 </row>
18466 <row topline="true">
18467 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18468 \begin_inset Text
18469
18470 \layout Standard
18471
18472 0
18473 \end_inset
18474 </cell>
18475 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18476 \begin_inset Text
18477
18478 \layout Standard
18479
18480 RESET vector
18481 \end_inset
18482 </cell>
18483 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18484 \begin_inset Text
18485
18486 \layout Standard
18487
18488 0x000000
18489 \end_inset
18490 </cell>
18491 </row>
18492 <row topline="true">
18493 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18494 \begin_inset Text
18495
18496 \layout Standard
18497
18498
18499 \family roman
18500 \series medium
18501 \shape up
18502 \size normal
18503 \emph off
18504 \bar no
18505 \noun off
18506 \color none
18507 1
18508 \end_inset
18509 </cell>
18510 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18511 \begin_inset Text
18512
18513 \layout Standard
18514
18515
18516 \family roman
18517 \series medium
18518 \shape up
18519 \size normal
18520 \emph off
18521 \bar no
18522 \noun off
18523 \color none
18524 HIGH priority interrupts
18525 \end_inset
18526 </cell>
18527 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18528 \begin_inset Text
18529
18530 \layout Standard
18531
18532 0x000008
18533 \end_inset
18534 </cell>
18535 </row>
18536 <row topline="true" bottomline="true">
18537 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18538 \begin_inset Text
18539
18540 \layout Standard
18541
18542 2
18543 \end_inset
18544 </cell>
18545 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18546 \begin_inset Text
18547
18548 \layout Standard
18549
18550 LOW priority interrupts
18551 \end_inset
18552 </cell>
18553 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18554 \begin_inset Text
18555
18556 \layout Standard
18557
18558 0x000018
18559 \end_inset
18560 </cell>
18561 </row>
18562 </lyxtabular>
18563
18564 \end_inset
18565
18566
18567 \layout Standard
18568
18569 When generating assembly code for ISR the code generator places a
18570 \noun on
18571 goto
18572 \noun default
18573 instruction at the
18574 \emph on
18575 Interrupt Vector Address
18576 \emph default
18577  which points at the genetated ISR.
18578  This single GOTO instruction is part of an automatically generated
18579 \emph on
18580 interrupt entry point
18581 \emph default
18582  function.
18583  The actuall ISR code is placed as normally would in the code space.
18584  Upon interrupt request, the GOTO instruction is executed which jumps to
18585  the ISR code.
18586  When declaring interrupt functions as _naked this GOTO instruction is
18587 \series bold
18588 not
18589 \series default
18590  generated.
18591  The whole interrupt functions is therefore placed at the Interrupt Vector
18592  Address of the specific interrupt.
18593  This is not a problem for the LOW priority interrupts, but it is a problem
18594  for the RESET and the HIGH priority interrupts because code may be written
18595  at the next interrupt´s vector address and cause undeterminate program
18596  behaviour if that interrupt is raised.
18597 \begin_inset Foot
18598 collapsed false
18599
18600 \layout Standard
18601
18602 This is not a problem when
18603 \layout Enumerate
18604
18605 this is a HIGH interrupt ISR and LOW interrupts are
18606 \emph on
18607 disabled
18608 \emph default
18609  or not used.
18610 \layout Enumerate
18611
18612 when the ISR is small enough not to reach the next interrupt´s vector address.
18613 \end_inset
18614
18615
18616 \layout Standard
18617
18618
18619 \emph on
18620 n
18621 \emph default
18622  is possible to be omitted.
18623  This way a function is generated similar to an ISR, but it is not assigned
18624  to any interrupt.
18625 \layout Standard
18626
18627 When entering an interrupt, currently the PIC16
18628 \begin_inset LatexCommand \index{PIC16}
18629
18630 \end_inset
18631
18632  port automatically saves the following registers:
18633 \layout Itemize
18634
18635 WREG
18636 \layout Itemize
18637
18638 STATUS
18639 \layout Itemize
18640
18641 BSR
18642 \layout Itemize
18643
18644 PROD (PRODL and PRODH)
18645 \layout Itemize
18646
18647 FSR0 (FSR0L and FSR0H)
18648 \layout Standard
18649
18650 These registers are restored upon return from the interrupt routine.
18651 \begin_inset Foot
18652 collapsed false
18653
18654 \layout Standard
18655
18656 NOTE that when the _naked attribute is specified for an interrupt routine,
18657  then NO registers are stored or restored.
18658 \end_inset
18659
18660
18661 \layout Subsection
18662
18663 Generic Pointers
18664 \layout Standard
18665
18666 Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
18667  There are 3 types of generic pointers currently implemented data, code
18668  and eeprom pointers.
18669  They are differentiated by the value of the 7th and 6th bits of the upper
18670  byte:
18671 \layout Standard
18672 \align center
18673
18674 \begin_inset  Tabular
18675 <lyxtabular version="3" rows="5" columns="5">
18676 <features>
18677 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18678 <column alignment="center" valignment="top" width="0">
18679 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18680 <column alignment="center" valignment="top" width="0">
18681 <column alignment="left" valignment="top" rightline="true" width="0">
18682 <row topline="true" bottomline="true">
18683 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18684 \begin_inset Text
18685
18686 \layout Standard
18687
18688 pointer type
18689 \end_inset
18690 </cell>
18691 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18692 \begin_inset Text
18693
18694 \layout Standard
18695
18696 7th bit
18697 \end_inset
18698 </cell>
18699 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18700 \begin_inset Text
18701
18702 \layout Standard
18703
18704 6th bit
18705 \end_inset
18706 </cell>
18707 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18708 \begin_inset Text
18709
18710 \layout Standard
18711
18712 rest of the pointer
18713 \end_inset
18714 </cell>
18715 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18716 \begin_inset Text
18717
18718 \layout Standard
18719
18720 descrption
18721 \end_inset
18722 </cell>
18723 </row>
18724 <row topline="true" bottomline="true">
18725 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18726 \begin_inset Text
18727
18728 \layout Standard
18729
18730 data
18731 \end_inset
18732 </cell>
18733 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18734 \begin_inset Text
18735
18736 \layout Standard
18737
18738 1
18739 \end_inset
18740 </cell>
18741 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18742 \begin_inset Text
18743
18744 \layout Standard
18745
18746 0
18747 \end_inset
18748 </cell>
18749 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18750 \begin_inset Text
18751
18752 \layout Standard
18753
18754
18755 \family typewriter
18756 \shape slanted
18757 \emph on
18758 uuuuuu uuuuxxxx xxxxxxxx
18759 \end_inset
18760 </cell>
18761 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18762 \begin_inset Text
18763
18764 \layout Standard
18765
18766 a 12-bit data pointer in data RAM memory
18767 \end_inset
18768 </cell>
18769 </row>
18770 <row bottomline="true">
18771 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18772 \begin_inset Text
18773
18774 \layout Standard
18775
18776 code
18777 \end_inset
18778 </cell>
18779 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18780 \begin_inset Text
18781
18782 \layout Standard
18783
18784 0
18785 \end_inset
18786 </cell>
18787 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18788 \begin_inset Text
18789
18790 \layout Standard
18791
18792 0
18793 \end_inset
18794 </cell>
18795 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18796 \begin_inset Text
18797
18798 \layout Standard
18799
18800
18801 \family typewriter
18802 \shape slanted
18803 \emph on
18804 uxxxxx xxxxxxxx xxxxxxxx
18805 \end_inset
18806 </cell>
18807 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18808 \begin_inset Text
18809
18810 \layout Standard
18811
18812 a 21-bit code pointer in FLASH memory
18813 \end_inset
18814 </cell>
18815 </row>
18816 <row bottomline="true">
18817 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18818 \begin_inset Text
18819
18820 \layout Standard
18821
18822 eeprom
18823 \end_inset
18824 </cell>
18825 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18826 \begin_inset Text
18827
18828 \layout Standard
18829
18830 0
18831 \end_inset
18832 </cell>
18833 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18834 \begin_inset Text
18835
18836 \layout Standard
18837
18838 1
18839 \end_inset
18840 </cell>
18841 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18842 \begin_inset Text
18843
18844 \layout Standard
18845
18846
18847 \family typewriter
18848 \shape slanted
18849 \emph on
18850 uuuuuu uuuuuuxx xxxxxxxx
18851 \end_inset
18852 </cell>
18853 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18854 \begin_inset Text
18855
18856 \layout Standard
18857
18858 a 10-bit eeprom pointer in EEPROM memory
18859 \end_inset
18860 </cell>
18861 </row>
18862 <row bottomline="true">
18863 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18864 \begin_inset Text
18865
18866 \layout Standard
18867
18868 (unimplemented)
18869 \end_inset
18870 </cell>
18871 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18872 \begin_inset Text
18873
18874 \layout Standard
18875
18876 1
18877 \end_inset
18878 </cell>
18879 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18880 \begin_inset Text
18881
18882 \layout Standard
18883
18884 1
18885 \end_inset
18886 </cell>
18887 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18888 \begin_inset Text
18889
18890 \layout Standard
18891
18892
18893 \family typewriter
18894 \shape slanted
18895 \emph on
18896 xxxxxx xxxxxxxx xxxxxxxx
18897 \end_inset
18898 </cell>
18899 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18900 \begin_inset Text
18901
18902 \layout Standard
18903
18904 unimplemented pointer type
18905 \end_inset
18906 </cell>
18907 </row>
18908 </lyxtabular>
18909
18910 \end_inset
18911
18912
18913 \layout Standard
18914
18915 Generic pointer are read and written with a set of library functions which
18916  read/write 1, 2, 3, 4 bytes.
18917 \layout Subsection
18918
18919 PIC16 C Libraries
18920 \layout Subsubsection
18921
18922 Standard I/O Streams
18923 \layout Standard
18924
18925 In the
18926 \emph on
18927 stdio.h
18928 \emph default
18929  the type FILE is defined as:
18930 \layout LyX-Code
18931
18932 typedef char * FILE;
18933 \layout Standard
18934
18935 This type is the stream type implemented I/O in the PIC18F devices.
18936  Also the standard input and output streams are declared in stdio.h:
18937 \layout LyX-Code
18938
18939 extern FILE * stdin;
18940 \layout LyX-Code
18941
18942 extern FILE * stdout;
18943 \layout Standard
18944
18945 The FILE type is actually a generic pointer which defines one more type
18946  of generic pointers, the
18947 \emph on
18948 stream
18949 \emph default
18950 pointer.
18951  This new type has the format:
18952 \layout Standard
18953 \align center
18954
18955 \begin_inset  Tabular
18956 <lyxtabular version="3" rows="2" columns="7">
18957 <features>
18958 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18959 <column alignment="center" valignment="top" width="0">
18960 <column alignment="center" valignment="top" leftline="true" width="0">
18961 <column alignment="center" valignment="top" leftline="true" width="0">
18962 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18963 <column alignment="center" valignment="top" width="0">
18964 <column alignment="left" valignment="top" rightline="true" width="0">
18965 <row topline="true" bottomline="true">
18966 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18967 \begin_inset Text
18968
18969 \layout Standard
18970
18971 pointer type
18972 \end_inset
18973 </cell>
18974 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18975 \begin_inset Text
18976
18977 \layout Standard
18978
18979 <7:6>
18980 \end_inset
18981 </cell>
18982 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18983 \begin_inset Text
18984
18985 \layout Standard
18986
18987 <5>
18988 \end_inset
18989 </cell>
18990 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18991 \begin_inset Text
18992
18993 \layout Standard
18994
18995 <4>
18996 \end_inset
18997 </cell>
18998 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18999 \begin_inset Text
19000
19001 \layout Standard
19002
19003 <3:0>
19004 \end_inset
19005 </cell>
19006 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19007 \begin_inset Text
19008
19009 \layout Standard
19010
19011 rest of the pointer
19012 \end_inset
19013 </cell>
19014 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19015 \begin_inset Text
19016
19017 \layout Standard
19018
19019 descrption
19020 \end_inset
19021 </cell>
19022 </row>
19023 <row topline="true" bottomline="true">
19024 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19025 \begin_inset Text
19026
19027 \layout Standard
19028
19029 stream
19030 \end_inset
19031 </cell>
19032 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19033 \begin_inset Text
19034
19035 \layout Standard
19036
19037 00
19038 \end_inset
19039 </cell>
19040 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19041 \begin_inset Text
19042
19043 \layout Standard
19044
19045 1
19046 \end_inset
19047 </cell>
19048 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19049 \begin_inset Text
19050
19051 \layout Standard
19052
19053 0
19054 \end_inset
19055 </cell>
19056 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19057 \begin_inset Text
19058
19059 \layout Standard
19060
19061 nnnn
19062 \end_inset
19063 </cell>
19064 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19065 \begin_inset Text
19066
19067 \layout Standard
19068
19069
19070 \family typewriter
19071 \shape slanted
19072 \emph on
19073 uuuuuuuu uuuuuuuu
19074 \end_inset
19075 </cell>
19076 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19077 \begin_inset Text
19078
19079 \layout Standard
19080
19081 upper byte high nubble is 0x2n, the rest are zeroes
19082 \end_inset
19083 </cell>
19084 </row>
19085 </lyxtabular>
19086
19087 \end_inset
19088
19089
19090 \layout Standard
19091
19092 Currently implemented there are 3 types of streams defined:
19093 \layout Standard
19094 \align center
19095
19096 \begin_inset  Tabular
19097 <lyxtabular version="3" rows="4" columns="4">
19098 <features>
19099 <column alignment="center" valignment="top" leftline="true" width="0">
19100 <column alignment="center" valignment="top" leftline="true" width="0">
19101 <column alignment="center" valignment="top" leftline="true" width="0">
19102 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19103 <row topline="true" bottomline="true">
19104 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19105 \begin_inset Text
19106
19107 \layout Standard
19108
19109 stream type
19110 \end_inset
19111 </cell>
19112 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19113 \begin_inset Text
19114
19115 \layout Standard
19116
19117 value
19118 \end_inset
19119 </cell>
19120 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19121 \begin_inset Text
19122
19123 \layout Standard
19124
19125 module
19126 \end_inset
19127 </cell>
19128 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19129 \begin_inset Text
19130
19131 \layout Standard
19132
19133 description
19134 \end_inset
19135 </cell>
19136 </row>
19137 <row topline="true">
19138 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19139 \begin_inset Text
19140
19141 \layout Standard
19142
19143 STREAM_USART
19144 \end_inset
19145 </cell>
19146 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19147 \begin_inset Text
19148
19149 \layout Standard
19150
19151
19152 \family typewriter
19153 0x200000UL
19154 \end_inset
19155 </cell>
19156 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19157 \begin_inset Text
19158
19159 \layout Standard
19160
19161 USART
19162 \end_inset
19163 </cell>
19164 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19165 \begin_inset Text
19166
19167 \layout Standard
19168
19169 Writes/Reads characters via the USART peripheral
19170 \end_inset
19171 </cell>
19172 </row>
19173 <row topline="true">
19174 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19175 \begin_inset Text
19176
19177 \layout Standard
19178
19179 STREAM_MSSP
19180 \end_inset
19181 </cell>
19182 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19183 \begin_inset Text
19184
19185 \layout Standard
19186
19187
19188 \family typewriter
19189 0x210000UL
19190 \end_inset
19191 </cell>
19192 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19193 \begin_inset Text
19194
19195 \layout Standard
19196
19197 MSSP
19198 \end_inset
19199 </cell>
19200 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19201 \begin_inset Text
19202
19203 \layout Standard
19204
19205 Writes/Reads characters via the MSSP peripheral
19206 \end_inset
19207 </cell>
19208 </row>
19209 <row topline="true" bottomline="true">
19210 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19211 \begin_inset Text
19212
19213 \layout Standard
19214
19215 STREAM_USER
19216 \end_inset
19217 </cell>
19218 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19219 \begin_inset Text
19220
19221 \layout Standard
19222
19223
19224 \family typewriter
19225 0x2f0000UL
19226 \end_inset
19227 </cell>
19228 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19229 \begin_inset Text
19230
19231 \layout Standard
19232
19233 (none)
19234 \end_inset
19235 </cell>
19236 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19237 \begin_inset Text
19238
19239 \layout Standard
19240
19241 Writes/Reads characters via used defined functions
19242 \end_inset
19243 </cell>
19244 </row>
19245 </lyxtabular>
19246
19247 \end_inset
19248
19249
19250 \layout Standard
19251
19252 The stream identifiers are declared as macros in the stdio.h header.
19253 \layout Standard
19254
19255 In the libc library there exist the functions that are used to write to
19256  each of the above streams.
19257  These are
19258 \layout List
19259 \labelwidthstring 00.00.0000
19260
19261 _
19262 \begin_inset ERT
19263 status Collapsed
19264
19265 \layout Standard
19266
19267 \backslash
19268 /
19269 \end_inset
19270
19271 _stream_usart_putchar writes a character at the USART stream
19272 \layout List
19273 \labelwidthstring 00.00.0000
19274
19275 _
19276 \begin_inset ERT
19277 status Collapsed
19278
19279 \layout Standard
19280
19281 \backslash
19282 /
19283 \end_inset
19284
19285 _stream_mssp_putchar writes a character at the MSSP stream
19286 \layout List
19287 \labelwidthstring 00.00.0000
19288
19289 putchar dummy function.
19290  This writes a character to a user specified manner.
19291 \layout Standard
19292
19293 In order to increase performance
19294 \emph on
19295 putchar
19296 \emph default
19297 is declared in stdio.h as having its parameter in WREG (it has the wparam
19298  keyword).
19299  In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
19300  in a user-friendly way.
19301
19302 \emph on
19303 arg
19304 \emph default
19305  is the name of the variable that holds the character to print.
19306  An example follows:
19307 \layout LyX-Code
19308
19309 #include <pic18fregs.h>
19310 \newline
19311 #include <stdio.h>
19312 \newline
19313
19314 \newline
19315 PUTCHAR( c )
19316 \layout LyX-Code
19317
19318 {
19319 \layout LyX-Code
19320
19321     PORTA = c;    /* dump character c to PORTA */
19322 \layout LyX-Code
19323
19324 }
19325 \newline
19326
19327 \newline
19328 void main(void)
19329 \layout LyX-Code
19330
19331 {
19332 \layout LyX-Code
19333
19334     stdout = STREAM_USER;    /* this is not necessery, since stdout points
19335 \layout LyX-Code
19336
19337                               * by default to STREAM_USER */
19338 \layout LyX-Code
19339
19340     printf (¨This is a printf test
19341 \backslash
19342 n¨);
19343 \layout LyX-Code
19344
19345 }
19346 \layout LyX-Code
19347
19348 \layout Subsubsection
19349
19350 Printing functions
19351 \layout Standard
19352
19353 PIC16 contains an implementation of the printf-family of functions.
19354  There exist the following functions:
19355 \layout LyX-Code
19356
19357 extern unsigned int sprintf(char *buf, char *fmt, ...);
19358 \layout LyX-Code
19359
19360 extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
19361 \layout LyX-Code
19362
19363 \layout LyX-Code
19364
19365 extern unsigned int printf(char *fmt, ...);
19366 \layout LyX-Code
19367
19368 extern unsigned int vprintf(char *fmt, va_lista ap);
19369 \layout LyX-Code
19370
19371 \layout LyX-Code
19372
19373 extern unsigned int fprintf(FILE *fp, char *fmt, ...);
19374 \layout LyX-Code
19375
19376 extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
19377 \layout Standard
19378
19379 For sprintf and vsprintf
19380 \emph on
19381 buf
19382 \emph default
19383 should normally be a data pointer where the resulting string will be placed.
19384  No range checking is done so the user should allocate the necessery buffer.
19385  For fprintf and vfprintf
19386 \emph on
19387 fp
19388 \emph default
19389  should be a stream pointer (i.e.
19390  stdout, STREAM_MSSP, etc...).
19391 \layout Subsubsection
19392
19393 Signals
19394 \layout Standard
19395
19396 The PIC18F family of microcontrollers supports a number of interrupt sources.
19397  A list of these interrupts is shown in the following table:
19398 \layout Standard
19399 \align center
19400
19401 \begin_inset  Tabular
19402 <lyxtabular version="3" rows="11" columns="4">
19403 <features>
19404 <column alignment="left" valignment="top" leftline="true" width="0">
19405 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19406 <column alignment="left" valignment="top" leftline="true" width="0">
19407 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19408 <row topline="true" bottomline="true">
19409 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19410 \begin_inset Text
19411
19412 \layout Standard
19413
19414 signal name
19415 \end_inset
19416 </cell>
19417 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19418 \begin_inset Text
19419
19420 \layout Standard
19421
19422 description
19423 \end_inset
19424 </cell>
19425 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19426 \begin_inset Text
19427
19428 \layout Standard
19429
19430 signal name
19431 \end_inset
19432 </cell>
19433 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19434 \begin_inset Text
19435
19436 \layout Standard
19437
19438 descritpion
19439 \end_inset
19440 </cell>
19441 </row>
19442 <row topline="true">
19443 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19444 \begin_inset Text
19445
19446 \layout Standard
19447
19448 SIG_RB
19449 \end_inset
19450 </cell>
19451 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19452 \begin_inset Text
19453
19454 \layout Standard
19455
19456 PORTB change interrupt
19457 \end_inset
19458 </cell>
19459 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19460 \begin_inset Text
19461
19462 \layout Standard
19463
19464 SIG_EE
19465 \end_inset
19466 </cell>
19467 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19468 \begin_inset Text
19469
19470 \layout Standard
19471
19472 EEPROM/FLASH write complete interrupt
19473 \end_inset
19474 </cell>
19475 </row>
19476 <row topline="true">
19477 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19478 \begin_inset Text
19479
19480 \layout Standard
19481
19482 SIG_INT0
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 INT0 external interrupt
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 SIG_BCOL
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 Bus collision interrupt
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_INT1
19517 \end_inset
19518 </cell>
19519 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19520 \begin_inset Text
19521
19522 \layout Standard
19523
19524 INT1 external 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_LVD
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 Low voltage detect 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_INT2
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 INT2 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_PSP
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 Parallel slave port 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_CCP1
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 CCP1 module 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_AD
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 AD convertion complete 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_CCP2
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 CCP2 module 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_RC
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 USART receive 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_TMR0
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 TMR0 overflow 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_TX
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 USART transmit 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_TMR1
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 TMR1 overflow 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_MSSP
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 SSP receive/transmit 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_TMR2
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 TMR2 matches PR2 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 \end_inset
19737 </cell>
19738 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19739 \begin_inset Text
19740
19741 \layout Standard
19742
19743 \end_inset
19744 </cell>
19745 </row>
19746 <row topline="true" bottomline="true">
19747 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19748 \begin_inset Text
19749
19750 \layout Standard
19751
19752 SIG_TMR3
19753 \end_inset
19754 </cell>
19755 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19756 \begin_inset Text
19757
19758 \layout Standard
19759
19760 TMR3 overflow interrupt
19761 \end_inset
19762 </cell>
19763 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19764 \begin_inset Text
19765
19766 \layout Standard
19767
19768 \end_inset
19769 </cell>
19770 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19771 \begin_inset Text
19772
19773 \layout Standard
19774
19775 \end_inset
19776 </cell>
19777 </row>
19778 </lyxtabular>
19779
19780 \end_inset
19781
19782
19783 \layout Standard
19784
19785 The prototypes for these names are defined in the header file
19786 \emph on
19787 signal.h
19788 \emph default
19789  .
19790 \layout Standard
19791
19792 In order to simplify signal handling, a number of macros is provided:
19793 \layout List
19794 \labelwidthstring 00.00.0000
19795
19796 DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
19797  high priority interrupts.
19798
19799 \emph on
19800 name
19801 \emph default
19802  is the function name to use.
19803 \layout List
19804 \labelwidthstring 00.00.0000
19805
19806 DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
19807  low priority interrupt.
19808
19809 \emph on
19810 name
19811 \emph default
19812  is the function name to use.
19813 \layout List
19814 \labelwidthstring 00.00.0000
19815
19816 DEF_HANDLER(sig,handler) define a handler for signal
19817 \emph on
19818 sig.
19819 \layout List
19820 \labelwidthstring 00.00.0000
19821
19822 END_DEF end the declaration of the dispatch table.
19823 \layout Standard
19824
19825 Additionally there are two more macros to simplify the declaration of the
19826  signal handler:
19827 \layout List
19828 \labelwidthstring 00.00.0000
19829
19830
19831 \series medium
19832 SIGHANDLER(handler)
19833 \series default
19834 this declares the function prototype for the
19835 \emph on
19836 handler
19837 \emph default
19838  function.
19839 \layout List
19840 \labelwidthstring 00.00.0000
19841
19842 SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
19843 \layout Standard
19844
19845 An example of using the macros above is shown below:
19846 \layout LyX-Code
19847
19848 #include <pic18fregs.h>
19849 \layout LyX-Code
19850
19851 #include <signal.h>
19852 \newline
19853
19854 \newline
19855 DEF_INTHIGH(high_int)
19856 \layout LyX-Code
19857
19858 DEF_HANDLER(SIG_TMR0, _tmr0_handler)
19859 \layout LyX-Code
19860
19861 DEF_HANDLER(SIG_BCOL, _bcol_handler)
19862 \layout LyX-Code
19863
19864 END_DEF
19865 \newline
19866
19867 \newline
19868 SIGHANDLER(_tmr0_handler)
19869 \layout LyX-Code
19870
19871 {
19872 \layout LyX-Code
19873
19874   /* action to be taken when timer 0 overflows */
19875 \layout LyX-Code
19876
19877 }
19878 \newline
19879
19880 \newline
19881 SIGHANDLERNAKED(_bcol_handler)
19882 \layout LyX-Code
19883
19884 {
19885 \layout LyX-Code
19886
19887   _asm
19888 \layout LyX-Code
19889
19890     /* action to be taken when bus collision occurs */
19891 \layout LyX-Code
19892
19893     retfie
19894 \layout LyX-Code
19895
19896  _endasm;
19897 \layout LyX-Code
19898
19899 }
19900 \layout Standard
19901
19902
19903 \series bold
19904 NOTES:
19905 \series default
19906  Special care should be taken when using the above scheme:
19907 \layout Itemize
19908
19909 do not place a colon (;) at the end of the DEF_* and END_DEF macros.
19910 \layout Itemize
19911
19912 when declaring SIGHANDLERNAKED handler never forget to use
19913 \emph on
19914 retfie
19915 \emph default
19916  for proper returning.
19917 \layout Subsection
19918
19919 PIC16 Port -- Tips
19920 \layout Standard
19921
19922 Here you can find some general tips for compiling programs with SDCC/pic16.
19923 \layout Subsubsection
19924
19925 Stack size
19926 \layout Standard
19927
19928 The default stack size (that is 64 bytes) probably is enough for many programs.
19929  One must take care that when there are many levels of function nesting,
19930  or there is excessive usage of stack, its size should be extended.
19931  An example of such a case is the printf/sprintf family of functions.
19932  If you encounter problems like not being able to print integers, then you
19933  need to set the stack size around the maximum (256 for small stack model).
19934  The following diagram shows what happens when calling printf to print an
19935  integer:
19936 \layout LyX-Code
19937
19938 printf () --> ltoa () --> ultoa () --> divschar ()
19939 \layout Standard
19940
19941 It is should be understood that stack is easily consumed when calling complicate
19942 d functions.
19943  Using command line arguments like -
19944 \begin_inset ERT
19945 status Collapsed
19946
19947 \layout Standard
19948
19949 \backslash
19950 /
19951 \end_inset
19952
19953 -fommit-frame-pointer might reduce stack usage by not creating unnecessery
19954  stack frames.
19955  Other ways to reduce stack usage may exist.
19956 \layout Chapter
19957
19958 Debugging with SDCDB
19959 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
19960
19961 \end_inset
19962
19963
19964 \begin_inset LatexCommand \index{sdcdb (debugger)}
19965
19966 \end_inset
19967
19968
19969 \layout Standard
19970
19971 SDCC is distributed with a source level debugger
19972 \begin_inset LatexCommand \index{Debugger}
19973
19974 \end_inset
19975
19976 .
19977  The debugger uses a command line interface, the command repertoire of the
19978  debugger has been kept as close to gdb
19979 \begin_inset LatexCommand \index{gdb}
19980
19981 \end_inset
19982
19983  (the GNU debugger) as possible.
19984  The configuration and build process is part of the standard compiler installati
19985 on, which also builds and installs the debugger in the target directory
19986  specified during configuration.
19987  The debugger allows you debug BOTH at the C source and at the ASM source
19988  level.
19989  Sdcdb is available on Unix platforms only.
19990 \layout Section
19991
19992 Compiling for Debugging
19993 \layout Standard
19994
19995 The -
19996 \begin_inset ERT
19997 status Collapsed
19998
19999 \layout Standard
20000
20001 \backslash
20002 /
20003 \end_inset
20004
20005 -debug
20006 \begin_inset LatexCommand \index{-\/-debug}
20007
20008 \end_inset
20009
20010  option must be specified for all files for which debug information is to
20011  be generated.
20012  The complier generates a .adb file for each of these files.
20013  The linker creates the .cdb
20014 \begin_inset LatexCommand \index{<file>.cdb}
20015
20016 \end_inset
20017
20018  file from the .adb
20019 \begin_inset LatexCommand \index{<file>.adb}
20020
20021 \end_inset
20022
20023  files and the address information.
20024  This .cdb is used by the debugger.
20025 \layout Section
20026
20027 How the Debugger Works
20028 \layout Standard
20029
20030 When the -
20031 \begin_inset ERT
20032 status Collapsed
20033
20034 \layout Standard
20035
20036 \backslash
20037 /
20038 \end_inset
20039
20040 -debug option is specified the compiler generates extra symbol information
20041  some of which are put into the assembler source and some are put into the
20042  .adb file.
20043   Then the linker creates the .cdb file from the individual .adb files with
20044  the address information for the symbols.
20045  The debugger reads the symbolic information generated by the compiler &
20046  the address information generated by the linker.
20047  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
20048  execution is controlled by the debugger.
20049  When a command is issued for the debugger, it translates it into appropriate
20050  commands for the simulator.
20051 \layout Section
20052
20053 Starting the Debugger
20054 \layout Standard
20055
20056 The debugger can be started using the following command line.
20057  (Assume the file you are debugging has the file name foo).
20058 \newline
20059
20060 \newline
20061
20062 \family sans
20063 \series bold
20064 sdcdb foo
20065 \newline
20066
20067 \family default
20068 \series default
20069
20070 \newline
20071 The debugger will look for the following files.
20072 \layout Itemize
20073
20074 foo.c - the source file.
20075 \layout Itemize
20076
20077 foo.cdb - the debugger symbol information file.
20078 \layout Itemize
20079
20080 foo.ihx - the Intel hex format
20081 \begin_inset LatexCommand \index{Intel hex format}
20082
20083 \end_inset
20084
20085  object file.
20086 \layout Section
20087
20088 Command Line Options
20089 \layout Itemize
20090
20091 -
20092 \begin_inset ERT
20093 status Collapsed
20094
20095 \layout Standard
20096
20097 \backslash
20098 /
20099 \end_inset
20100
20101 -directory=<source file directory> this option can used to specify the directory
20102  search list.
20103  The debugger will look into the directory list specified for source, cdb
20104  & ihx files.
20105  The items in the directory list must be separated by ':', e.g.
20106  if the source files can be in the directories /home/src1 and /home/src2,
20107  the -
20108 \begin_inset ERT
20109 status Collapsed
20110
20111 \layout Standard
20112
20113 \backslash
20114 /
20115 \end_inset
20116
20117 -directory option should be -
20118 \begin_inset ERT
20119 status Collapsed
20120
20121 \layout Standard
20122
20123 \backslash
20124 /
20125 \end_inset
20126
20127 -directory=/home/src1:/home/src2.
20128  Note there can be no spaces in the option.
20129
20130 \layout Itemize
20131
20132 -cd <directory> - change to the <directory>.
20133 \layout Itemize
20134
20135 -fullname - used by GUI front ends.
20136 \layout Itemize
20137
20138 -cpu <cpu-type> - this argument is passed to the simulator please see the
20139  simulator docs for details.
20140 \layout Itemize
20141
20142 -X <Clock frequency > this options is passed to the simulator please see
20143  the simulator docs for details.
20144 \layout Itemize
20145
20146 -s <serial port file> passed to simulator see the simulator docs for details.
20147 \layout Itemize
20148
20149 -S <serial in,out> passed to simulator see the simulator docs for details.
20150 \layout Itemize
20151
20152 -k <port number> passed to simulator see the simulator docs for details.
20153 \layout Section
20154
20155 Debugger Commands
20156 \layout Standard
20157
20158 As mentioned earlier the command interface for the debugger has been deliberatel
20159 y kept as close the GNU debugger gdb, as possible.
20160  This will help the integration with existing graphical user interfaces
20161  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
20162  If you use a graphical user interface for the debugger you can skip this
20163  section.
20164 \layout Subsubsection*
20165
20166 break [line | file:line | function | file:function]
20167 \layout Standard
20168
20169 Set breakpoint at specified line or function:
20170 \newline
20171
20172 \newline
20173
20174 \family sans
20175 \series bold
20176 sdcdb>break 100
20177 \newline
20178 sdcdb>break foo.c:100
20179 \newline
20180 sdcdb>break funcfoo
20181 \newline
20182 sdcdb>break foo.c:funcfoo
20183 \layout Subsubsection*
20184
20185 clear [line | file:line | function | file:function ]
20186 \layout Standard
20187
20188 Clear breakpoint at specified line or function:
20189 \newline
20190
20191 \newline
20192
20193 \family sans
20194 \series bold
20195 sdcdb>clear 100
20196 \newline
20197 sdcdb>clear foo.c:100
20198 \newline
20199 sdcdb>clear funcfoo
20200 \newline
20201 sdcdb>clear foo.c:funcfoo
20202 \layout Subsubsection*
20203
20204 continue
20205 \layout Standard
20206
20207 Continue program being debugged, after breakpoint.
20208 \layout Subsubsection*
20209
20210 finish
20211 \layout Standard
20212
20213 Execute till the end of the current function.
20214 \layout Subsubsection*
20215
20216 delete [n]
20217 \layout Standard
20218
20219 Delete breakpoint number 'n'.
20220  If used without any option clear ALL user defined break points.
20221 \layout Subsubsection*
20222
20223 info [break | stack | frame | registers ]
20224 \layout Itemize
20225
20226 info break - list all breakpoints
20227 \layout Itemize
20228
20229 info stack - show the function call stack.
20230 \layout Itemize
20231
20232 info frame - show information about the current execution frame.
20233 \layout Itemize
20234
20235 info registers - show content of all registers.
20236 \layout Subsubsection*
20237
20238 step
20239 \layout Standard
20240
20241 Step program until it reaches a different source line.
20242  Note: pressing <return> repeats the last command.
20243 \layout Subsubsection*
20244
20245 next
20246 \layout Standard
20247
20248 Step program, proceeding through subroutine calls.
20249 \layout Subsubsection*
20250
20251 run
20252 \layout Standard
20253
20254 Start debugged program.
20255 \layout Subsubsection*
20256
20257 ptype variable
20258 \layout Standard
20259
20260 Print type information of the variable.
20261 \layout Subsubsection*
20262
20263 print variable
20264 \layout Standard
20265
20266 print value of variable.
20267 \layout Subsubsection*
20268
20269 file filename
20270 \layout Standard
20271
20272 load the given file name.
20273  Note this is an alternate method of loading file for debugging.
20274 \layout Subsubsection*
20275
20276 frame
20277 \layout Standard
20278
20279 print information about current frame.
20280 \layout Subsubsection*
20281
20282 set srcmode
20283 \layout Standard
20284
20285 Toggle between C source & assembly source.
20286 \layout Subsubsection*
20287
20288 ! simulator command
20289 \layout Standard
20290
20291 Send the string following '!' to the simulator, the simulator response is
20292  displayed.
20293  Note the debugger does not interpret the command being sent to the simulator,
20294  so if a command like 'go' is sent the debugger can loose its execution
20295  context and may display incorrect values.
20296 \layout Subsubsection*
20297
20298 quit
20299 \layout Standard
20300
20301 "Watch me now.
20302  Iam going Down.
20303  My name is Bobby Brown"
20304 \layout Section
20305
20306 Interfacing with DDD
20307 \layout Comment
20308
20309 The screenshot was converted from png to eps with:
20310 \begin_inset Quotes sld
20311 \end_inset
20312
20313 bmeps -c -e8f -p3 ddd_example.png >ddd_example.eps
20314 \begin_inset Quotes srd
20315 \end_inset
20316
20317  which produces a pretty compact eps file which is free from compression
20318  artifacts.
20319 \layout Comment
20320
20321 The screenshot was included in sdccman.lyx cvs version 1.120 but later removed
20322  as this broke the build system on Sourceforge (pdf-file was broken).
20323 \layout Standard
20324
20325 The .eps File
20326 \size footnotesize
20327
20328 \begin_inset LatexCommand \url{http://cvs.sourceforge.net/viewcvs.py/*checkout*/sdcc/sdcc/doc/figures/ddd_example.eps}
20329
20330 \end_inset
20331
20332
20333 \size default
20334  shows a screenshot of a debugging session with DDD
20335 \begin_inset LatexCommand \index{DDD (debugger)}
20336
20337 \end_inset
20338
20339  (Unix only) on a simulated 8032.
20340  The debugging session might not run as smoothly as the screenshot suggests.
20341  The debugger allows setting of breakpoints, displaying and changing variables,
20342  single stepping through C and assembler code.
20343
20344 \newline
20345 The source was compiled with
20346 \family sans
20347 \series bold
20348
20349 \newline
20350
20351 \newline
20352 sdcc -
20353 \family default
20354 \series default
20355
20356 \begin_inset ERT
20357 status Collapsed
20358
20359 \layout Standard
20360
20361 \backslash
20362 /
20363 \end_inset
20364
20365
20366 \family sans
20367 \series bold
20368 -debug ddd_example.c
20369 \family default
20370 \series default
20371
20372 \family sans
20373 \series bold
20374
20375 \newline
20376
20377 \family default
20378 \series default
20379
20380 \newline
20381 and DDD was invoked with
20382 \family sans
20383 \series bold
20384
20385 \newline
20386
20387 \newline
20388 ddd -debugger 'sdcdb -cpu 8032 ddd_example'
20389 \layout Section
20390
20391 Interfacing with XEmacs
20392 \begin_inset LatexCommand \index{XEmacs}
20393
20394 \end_inset
20395
20396
20397 \begin_inset LatexCommand \index{Emacs}
20398
20399 \end_inset
20400
20401
20402 \layout Standard
20403
20404 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
20405  sdcdb.el and sdcdbsrc.el.
20406  These two files can be found in the $(prefix)/bin directory after the installat
20407 ion is complete.
20408  These files need to be loaded into XEmacs for the interface to work.
20409  This can be done at XEmacs startup time by inserting the following into
20410  your '.xemacs' file (which can be found in your HOME directory):
20411 \newline
20412
20413 \newline
20414
20415 \family typewriter
20416 (load-file sdcdbsrc.el)
20417 \family default
20418
20419 \newline
20420
20421 \newline
20422 .xemacs is a lisp file so the () around the command is REQUIRED.
20423  The files can also be loaded dynamically while XEmacs is running, set the
20424  environment variable 'EMACSLOADPATH' to the installation bin directory
20425  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
20426  To start the interface enter the following command:
20427 \newline
20428
20429 \newline
20430
20431 \family sans
20432 \series bold
20433 ESC-x sdcdbsrc
20434 \family default
20435 \series default
20436
20437 \newline
20438
20439 \newline
20440 You will prompted to enter the file name to be debugged.
20441
20442 \newline
20443
20444 \newline
20445 The command line options that are passed to the simulator directly are bound
20446  to default values in the file sdcdbsrc.el.
20447  The variables are listed below, these values maybe changed as required.
20448 \layout Itemize
20449
20450 sdcdbsrc-cpu-type '51
20451 \layout Itemize
20452
20453 sdcdbsrc-frequency '11059200
20454 \layout Itemize
20455
20456 sdcdbsrc-serial nil
20457 \layout Standard
20458
20459 The following is a list of key mapping for the debugger interface.
20460 \layout Standard
20461
20462 \SpecialChar ~
20463
20464 \family typewriter
20465
20466 \newline
20467 ;;\SpecialChar ~
20468 Current Listing ::
20469 \newline
20470 ;;key\SpecialChar ~
20471 \SpecialChar ~
20472 \SpecialChar ~
20473 \SpecialChar ~
20474 \SpecialChar ~
20475 \SpecialChar ~
20476 \SpecialChar ~
20477 \SpecialChar ~
20478 \SpecialChar ~
20479 \SpecialChar ~
20480 \SpecialChar ~
20481 \SpecialChar ~
20482 \SpecialChar ~
20483 \SpecialChar ~
20484 binding\SpecialChar ~
20485 \SpecialChar ~
20486 \SpecialChar ~
20487 \SpecialChar ~
20488 \SpecialChar ~
20489 \SpecialChar ~
20490 \SpecialChar ~
20491 \SpecialChar ~
20492 \SpecialChar ~
20493 \SpecialChar ~
20494 \SpecialChar ~
20495 \SpecialChar ~
20496 \SpecialChar ~
20497 \SpecialChar ~
20498 \SpecialChar ~
20499 \SpecialChar ~
20500 \SpecialChar ~
20501 \SpecialChar ~
20502 \SpecialChar ~
20503 \SpecialChar ~
20504 \SpecialChar ~
20505 \SpecialChar ~
20506 Comment
20507 \newline
20508 ;;---\SpecialChar ~
20509 \SpecialChar ~
20510 \SpecialChar ~
20511 \SpecialChar ~
20512 \SpecialChar ~
20513 \SpecialChar ~
20514 \SpecialChar ~
20515 \SpecialChar ~
20516 \SpecialChar ~
20517 \SpecialChar ~
20518 \SpecialChar ~
20519 \SpecialChar ~
20520 \SpecialChar ~
20521 \SpecialChar ~
20522 -------\SpecialChar ~
20523 \SpecialChar ~
20524 \SpecialChar ~
20525 \SpecialChar ~
20526 \SpecialChar ~
20527 \SpecialChar ~
20528 \SpecialChar ~
20529 \SpecialChar ~
20530 \SpecialChar ~
20531 \SpecialChar ~
20532 \SpecialChar ~
20533 \SpecialChar ~
20534 \SpecialChar ~
20535 \SpecialChar ~
20536 \SpecialChar ~
20537 \SpecialChar ~
20538 \SpecialChar ~
20539 \SpecialChar ~
20540 \SpecialChar ~
20541 \SpecialChar ~
20542 \SpecialChar ~
20543 \SpecialChar ~
20544 -------
20545 \newline
20546 ;;
20547 \newline
20548 ;;\SpecialChar ~
20549 n\SpecialChar ~
20550 \SpecialChar ~
20551 \SpecialChar ~
20552 \SpecialChar ~
20553 \SpecialChar ~
20554 \SpecialChar ~
20555 \SpecialChar ~
20556 \SpecialChar ~
20557 \SpecialChar ~
20558 \SpecialChar ~
20559 \SpecialChar ~
20560 \SpecialChar ~
20561 \SpecialChar ~
20562 \SpecialChar ~
20563 \SpecialChar ~
20564 sdcdb-next-from-src\SpecialChar ~
20565 \SpecialChar ~
20566 \SpecialChar ~
20567 \SpecialChar ~
20568 \SpecialChar ~
20569 \SpecialChar ~
20570 \SpecialChar ~
20571 \SpecialChar ~
20572 \SpecialChar ~
20573 \SpecialChar ~
20574 SDCDB next command
20575 \newline
20576 ;;\SpecialChar ~
20577 b\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 sdcdb-back-from-src\SpecialChar ~
20593 \SpecialChar ~
20594 \SpecialChar ~
20595 \SpecialChar ~
20596 \SpecialChar ~
20597 \SpecialChar ~
20598 \SpecialChar ~
20599 \SpecialChar ~
20600 \SpecialChar ~
20601 \SpecialChar ~
20602 SDCDB back command
20603 \newline
20604 ;;\SpecialChar ~
20605 c\SpecialChar ~
20606 \SpecialChar ~
20607 \SpecialChar ~
20608 \SpecialChar ~
20609 \SpecialChar ~
20610 \SpecialChar ~
20611 \SpecialChar ~
20612 \SpecialChar ~
20613 \SpecialChar ~
20614 \SpecialChar ~
20615 \SpecialChar ~
20616 \SpecialChar ~
20617 \SpecialChar ~
20618 \SpecialChar ~
20619 \SpecialChar ~
20620 sdcdb-cont-from-src\SpecialChar ~
20621 \SpecialChar ~
20622 \SpecialChar ~
20623 \SpecialChar ~
20624 \SpecialChar ~
20625 \SpecialChar ~
20626 \SpecialChar ~
20627 \SpecialChar ~
20628 \SpecialChar ~
20629 \SpecialChar ~
20630 SDCDB continue command
20631 \newline
20632 ;;\SpecialChar ~
20633 s\SpecialChar ~
20634 \SpecialChar ~
20635 \SpecialChar ~
20636 \SpecialChar ~
20637 \SpecialChar ~
20638 \SpecialChar ~
20639 \SpecialChar ~
20640 \SpecialChar ~
20641 \SpecialChar ~
20642 \SpecialChar ~
20643 \SpecialChar ~
20644 \SpecialChar ~
20645 \SpecialChar ~
20646 \SpecialChar ~
20647 \SpecialChar ~
20648 sdcdb-step-from-src\SpecialChar ~
20649 \SpecialChar ~
20650 \SpecialChar ~
20651 \SpecialChar ~
20652 \SpecialChar ~
20653 \SpecialChar ~
20654 \SpecialChar ~
20655 \SpecialChar ~
20656 \SpecialChar ~
20657 \SpecialChar ~
20658 SDCDB step command
20659 \newline
20660 ;;\SpecialChar ~
20661 ?\SpecialChar ~
20662 \SpecialChar ~
20663 \SpecialChar ~
20664 \SpecialChar ~
20665 \SpecialChar ~
20666 \SpecialChar ~
20667 \SpecialChar ~
20668 \SpecialChar ~
20669 \SpecialChar ~
20670 \SpecialChar ~
20671 \SpecialChar ~
20672 \SpecialChar ~
20673 \SpecialChar ~
20674 \SpecialChar ~
20675 \SpecialChar ~
20676 sdcdb-whatis-c-sexp\SpecialChar ~
20677 \SpecialChar ~
20678 \SpecialChar ~
20679 \SpecialChar ~
20680 \SpecialChar ~
20681 \SpecialChar ~
20682 \SpecialChar ~
20683 \SpecialChar ~
20684 \SpecialChar ~
20685 \SpecialChar ~
20686 SDCDB ptypecommand for data at
20687 \newline
20688 ;;\SpecialChar ~
20689 \SpecialChar ~
20690 \SpecialChar ~
20691 \SpecialChar ~
20692 \SpecialChar ~
20693 \SpecialChar ~
20694 \SpecialChar ~
20695 \SpecialChar ~
20696 \SpecialChar ~
20697 \SpecialChar ~
20698 \SpecialChar ~
20699 \SpecialChar ~
20700 \SpecialChar ~
20701 \SpecialChar ~
20702 \SpecialChar ~
20703 \SpecialChar ~
20704 \SpecialChar ~
20705 \SpecialChar ~
20706 \SpecialChar ~
20707 \SpecialChar ~
20708 \SpecialChar ~
20709 \SpecialChar ~
20710 \SpecialChar ~
20711 \SpecialChar ~
20712 \SpecialChar ~
20713 \SpecialChar ~
20714 \SpecialChar ~
20715 \SpecialChar ~
20716 \SpecialChar ~
20717 \SpecialChar ~
20718 \SpecialChar ~
20719 \SpecialChar ~
20720 \SpecialChar ~
20721 \SpecialChar ~
20722 \SpecialChar ~
20723 \SpecialChar ~
20724 \SpecialChar ~
20725 \SpecialChar ~
20726 \SpecialChar ~
20727 \SpecialChar ~
20728 \SpecialChar ~
20729 \SpecialChar ~
20730 \SpecialChar ~
20731 \SpecialChar ~
20732 \SpecialChar ~
20733 \SpecialChar ~
20734 \SpecialChar ~
20735 buffer point
20736 \newline
20737 ;;\SpecialChar ~
20738 x\SpecialChar ~
20739 \SpecialChar ~
20740 \SpecialChar ~
20741 \SpecialChar ~
20742 \SpecialChar ~
20743 \SpecialChar ~
20744 \SpecialChar ~
20745 \SpecialChar ~
20746 \SpecialChar ~
20747 \SpecialChar ~
20748 \SpecialChar ~
20749 \SpecialChar ~
20750 \SpecialChar ~
20751 \SpecialChar ~
20752 \SpecialChar ~
20753 sdcdbsrc-delete\SpecialChar ~
20754 \SpecialChar ~
20755 \SpecialChar ~
20756 \SpecialChar ~
20757 \SpecialChar ~
20758 \SpecialChar ~
20759 \SpecialChar ~
20760 \SpecialChar ~
20761 \SpecialChar ~
20762 \SpecialChar ~
20763 \SpecialChar ~
20764 \SpecialChar ~
20765 \SpecialChar ~
20766 \SpecialChar ~
20767 SDCDB Delete all breakpoints if no arg
20768 \newline
20769 ;;\SpecialChar ~
20770 \SpecialChar ~
20771 \SpecialChar ~
20772 \SpecialChar ~
20773 \SpecialChar ~
20774 \SpecialChar ~
20775 \SpecialChar ~
20776 \SpecialChar ~
20777 \SpecialChar ~
20778 \SpecialChar ~
20779 \SpecialChar ~
20780 \SpecialChar ~
20781 \SpecialChar ~
20782 \SpecialChar ~
20783 \SpecialChar ~
20784 \SpecialChar ~
20785 \SpecialChar ~
20786 \SpecialChar ~
20787 \SpecialChar ~
20788 \SpecialChar ~
20789 \SpecialChar ~
20790 \SpecialChar ~
20791 \SpecialChar ~
20792 \SpecialChar ~
20793 \SpecialChar ~
20794 \SpecialChar ~
20795 \SpecialChar ~
20796 \SpecialChar ~
20797 \SpecialChar ~
20798 \SpecialChar ~
20799 \SpecialChar ~
20800 \SpecialChar ~
20801 \SpecialChar ~
20802 \SpecialChar ~
20803 \SpecialChar ~
20804 \SpecialChar ~
20805 \SpecialChar ~
20806 \SpecialChar ~
20807 \SpecialChar ~
20808 \SpecialChar ~
20809 \SpecialChar ~
20810 \SpecialChar ~
20811 \SpecialChar ~
20812 \SpecialChar ~
20813 \SpecialChar ~
20814 \SpecialChar ~
20815 \SpecialChar ~
20816 given or delete arg (C-u arg x)
20817 \newline
20818 ;;\SpecialChar ~
20819 m\SpecialChar ~
20820 \SpecialChar ~
20821 \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 sdcdbsrc-frame\SpecialChar ~
20835 \SpecialChar ~
20836 \SpecialChar ~
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 SDCDB Display current frame if no arg,
20850 \newline
20851 ;;\SpecialChar ~
20852 \SpecialChar ~
20853 \SpecialChar ~
20854 \SpecialChar ~
20855 \SpecialChar ~
20856 \SpecialChar ~
20857 \SpecialChar ~
20858 \SpecialChar ~
20859 \SpecialChar ~
20860 \SpecialChar ~
20861 \SpecialChar ~
20862 \SpecialChar ~
20863 \SpecialChar ~
20864 \SpecialChar ~
20865 \SpecialChar ~
20866 \SpecialChar ~
20867 \SpecialChar ~
20868 \SpecialChar ~
20869 \SpecialChar ~
20870 \SpecialChar ~
20871 \SpecialChar ~
20872 \SpecialChar ~
20873 \SpecialChar ~
20874 \SpecialChar ~
20875 \SpecialChar ~
20876 \SpecialChar ~
20877 \SpecialChar ~
20878 \SpecialChar ~
20879 \SpecialChar ~
20880 \SpecialChar ~
20881 \SpecialChar ~
20882 \SpecialChar ~
20883 \SpecialChar ~
20884 \SpecialChar ~
20885 \SpecialChar ~
20886 \SpecialChar ~
20887 \SpecialChar ~
20888 \SpecialChar ~
20889 \SpecialChar ~
20890 \SpecialChar ~
20891 \SpecialChar ~
20892 \SpecialChar ~
20893 \SpecialChar ~
20894 \SpecialChar ~
20895 \SpecialChar ~
20896 \SpecialChar ~
20897 \SpecialChar ~
20898 given or display frame arg
20899 \newline
20900 ;;\SpecialChar ~
20901 \SpecialChar ~
20902 \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 \SpecialChar ~
20918 \SpecialChar ~
20919 \SpecialChar ~
20920 \SpecialChar ~
20921 \SpecialChar ~
20922 \SpecialChar ~
20923 \SpecialChar ~
20924 \SpecialChar ~
20925 \SpecialChar ~
20926 \SpecialChar ~
20927 \SpecialChar ~
20928 \SpecialChar ~
20929 \SpecialChar ~
20930 \SpecialChar ~
20931 \SpecialChar ~
20932 \SpecialChar ~
20933 \SpecialChar ~
20934 \SpecialChar ~
20935 \SpecialChar ~
20936 \SpecialChar ~
20937 \SpecialChar ~
20938 \SpecialChar ~
20939 \SpecialChar ~
20940 \SpecialChar ~
20941 \SpecialChar ~
20942 \SpecialChar ~
20943 \SpecialChar ~
20944 \SpecialChar ~
20945 \SpecialChar ~
20946 \SpecialChar ~
20947 buffer point
20948 \newline
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 sdcdbsrc-goto-sdcdb\SpecialChar ~
20966 \SpecialChar ~
20967 \SpecialChar ~
20968 \SpecialChar ~
20969 \SpecialChar ~
20970 \SpecialChar ~
20971 \SpecialChar ~
20972 \SpecialChar ~
20973 \SpecialChar ~
20974 \SpecialChar ~
20975 Goto the SDCDB output buffer
20976 \newline
20977 ;;\SpecialChar ~
20978 p\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 sdcdb-print-c-sexp\SpecialChar ~
20994 \SpecialChar ~
20995 \SpecialChar ~
20996 \SpecialChar ~
20997 \SpecialChar ~
20998 \SpecialChar ~
20999 \SpecialChar ~
21000 \SpecialChar ~
21001 \SpecialChar ~
21002 \SpecialChar ~
21003 \SpecialChar ~
21004 SDCDB print command for data at
21005 \newline
21006 ;;\SpecialChar ~
21007 \SpecialChar ~
21008 \SpecialChar ~
21009 \SpecialChar ~
21010 \SpecialChar ~
21011 \SpecialChar ~
21012 \SpecialChar ~
21013 \SpecialChar ~
21014 \SpecialChar ~
21015 \SpecialChar ~
21016 \SpecialChar ~
21017 \SpecialChar ~
21018 \SpecialChar ~
21019 \SpecialChar ~
21020 \SpecialChar ~
21021 \SpecialChar ~
21022 \SpecialChar ~
21023 \SpecialChar ~
21024 \SpecialChar ~
21025 \SpecialChar ~
21026 \SpecialChar ~
21027 \SpecialChar ~
21028 \SpecialChar ~
21029 \SpecialChar ~
21030 \SpecialChar ~
21031 \SpecialChar ~
21032 \SpecialChar ~
21033 \SpecialChar ~
21034 \SpecialChar ~
21035 \SpecialChar ~
21036 \SpecialChar ~
21037 \SpecialChar ~
21038 \SpecialChar ~
21039 \SpecialChar ~
21040 \SpecialChar ~
21041 \SpecialChar ~
21042 \SpecialChar ~
21043 \SpecialChar ~
21044 \SpecialChar ~
21045 \SpecialChar ~
21046 \SpecialChar ~
21047 \SpecialChar ~
21048 \SpecialChar ~
21049 \SpecialChar ~
21050 \SpecialChar ~
21051 \SpecialChar ~
21052 \SpecialChar ~
21053 buffer point
21054 \newline
21055 ;;\SpecialChar ~
21056 g\SpecialChar ~
21057 \SpecialChar ~
21058 \SpecialChar ~
21059 \SpecialChar ~
21060 \SpecialChar ~
21061 \SpecialChar ~
21062 \SpecialChar ~
21063 \SpecialChar ~
21064 \SpecialChar ~
21065 \SpecialChar ~
21066 \SpecialChar ~
21067 \SpecialChar ~
21068 \SpecialChar ~
21069 \SpecialChar ~
21070 \SpecialChar ~
21071 sdcdbsrc-goto-sdcdb\SpecialChar ~
21072 \SpecialChar ~
21073 \SpecialChar ~
21074 \SpecialChar ~
21075 \SpecialChar ~
21076 \SpecialChar ~
21077 \SpecialChar ~
21078 \SpecialChar ~
21079 \SpecialChar ~
21080 \SpecialChar ~
21081 Goto the SDCDB output buffer
21082 \newline
21083 ;;\SpecialChar ~
21084 t\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 sdcdbsrc-mode\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 Toggles Sdcdbsrc mode (turns it off)
21116 \newline
21117 ;;
21118 \newline
21119 ;;\SpecialChar ~
21120 C-c\SpecialChar ~
21121 C-f\SpecialChar ~
21122 \SpecialChar ~
21123 \SpecialChar ~
21124 \SpecialChar ~
21125 \SpecialChar ~
21126 \SpecialChar ~
21127 \SpecialChar ~
21128 \SpecialChar ~
21129 \SpecialChar ~
21130 sdcdb-finish-from-src\SpecialChar ~
21131 \SpecialChar ~
21132 \SpecialChar ~
21133 \SpecialChar ~
21134 \SpecialChar ~
21135 \SpecialChar ~
21136 \SpecialChar ~
21137 \SpecialChar ~
21138 SDCDB finish command
21139 \newline
21140 ;;
21141 \newline
21142 ;;\SpecialChar ~
21143 C-x\SpecialChar ~
21144 SPC\SpecialChar ~
21145 \SpecialChar ~
21146 \SpecialChar ~
21147 \SpecialChar ~
21148 \SpecialChar ~
21149 \SpecialChar ~
21150 \SpecialChar ~
21151 \SpecialChar ~
21152 \SpecialChar ~
21153 sdcdb-break\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 \SpecialChar ~
21168 \SpecialChar ~
21169 \SpecialChar ~
21170 \SpecialChar ~
21171 Set break for line with point
21172 \newline
21173 ;;\SpecialChar ~
21174 ESC\SpecialChar ~
21175 t\SpecialChar ~
21176 \SpecialChar ~
21177 \SpecialChar ~
21178 \SpecialChar ~
21179 \SpecialChar ~
21180 \SpecialChar ~
21181 \SpecialChar ~
21182 \SpecialChar ~
21183 \SpecialChar ~
21184 \SpecialChar ~
21185 \SpecialChar ~
21186 sdcdbsrc-mode\SpecialChar ~
21187 \SpecialChar ~
21188 \SpecialChar ~
21189 \SpecialChar ~
21190 \SpecialChar ~
21191 \SpecialChar ~
21192 \SpecialChar ~
21193 \SpecialChar ~
21194 \SpecialChar ~
21195 \SpecialChar ~
21196 \SpecialChar ~
21197 \SpecialChar ~
21198 \SpecialChar ~
21199 \SpecialChar ~
21200 \SpecialChar ~
21201 \SpecialChar ~
21202 Toggle Sdcdbsrc mode
21203 \newline
21204 ;;\SpecialChar ~
21205 ESC\SpecialChar ~
21206 m\SpecialChar ~
21207 \SpecialChar ~
21208 \SpecialChar ~
21209 \SpecialChar ~
21210 \SpecialChar ~
21211 \SpecialChar ~
21212 \SpecialChar ~
21213 \SpecialChar ~
21214 \SpecialChar ~
21215 \SpecialChar ~
21216 \SpecialChar ~
21217 sdcdbsrc-srcmode\SpecialChar ~
21218 \SpecialChar ~
21219 \SpecialChar ~
21220 \SpecialChar ~
21221 \SpecialChar ~
21222 \SpecialChar ~
21223 \SpecialChar ~
21224 \SpecialChar ~
21225 \SpecialChar ~
21226 \SpecialChar ~
21227 \SpecialChar ~
21228 \SpecialChar ~
21229 \SpecialChar ~
21230 Toggle list mode
21231 \newline
21232 ;;
21233 \newline
21234
21235 \layout Chapter
21236 \pagebreak_top
21237 TIPS
21238 \layout Standard
21239
21240 Here are a few guidelines that will help the compiler generate more efficient
21241  code, some of the tips are specific to this compiler others are generally
21242  good programming practice.
21243 \layout Itemize
21244
21245 Use the smallest data type to represent your data-value.
21246  If it is known in advance that the value is going to be less than 256 then
21247  use an 'unsigned char' instead of a 'short' or 'int'.
21248  Please note, that ANSI C requires both signed and unsigned chars to be
21249  promoted to 'signed int' before doing any operation.
21250  This promotion
21251 \begin_inset LatexCommand \index{type promotion}
21252
21253 \end_inset
21254
21255  can be omitted, if the result is the same.
21256  The effect of the promotion rules together with the sign-extension is often
21257  surprising:
21258 \begin_deeper
21259 \layout Verse
21260
21261
21262 \family typewriter
21263 unsigned char uc = 0xfe;
21264 \newline
21265 if (uc * uc < 0) /* this is true! */
21266 \newline
21267 {
21268 \newline
21269 \SpecialChar ~
21270 \SpecialChar ~
21271 \SpecialChar ~
21272 \SpecialChar ~
21273 ....
21274 \newline
21275 }
21276 \layout Standard
21277
21278
21279 \family typewriter
21280 uc * uc
21281 \family default
21282  is evaluated as
21283 \family typewriter
21284 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
21285 \family default
21286 .
21287
21288 \newline
21289 Another one:
21290 \layout Verse
21291
21292
21293 \family typewriter
21294 (unsigned char) -12 / (signed char) -3 = ...
21295 \layout Standard
21296
21297 No, the result is not 4:
21298 \layout Verse
21299
21300
21301 \family typewriter
21302 (int) (unsigned char) -12 / (int) (signed char) -3 =
21303 \newline
21304 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
21305 \newline
21306 (int) 0x00f4 / (int) 0xfffd =
21307 \newline
21308 (int) 0x00f4 / (int) 0xfffd =
21309 \newline
21310 (int) 244 / (int) -3 =
21311 \newline
21312 (int) -81 = (int) 0xffaf;
21313 \layout Standard
21314
21315 Don't complain, that gcc gives you a different result.
21316  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
21317  Therefore the results are different.
21318 \newline
21319 From
21320 \begin_inset Quotes sld
21321 \end_inset
21322
21323 comp.lang.c FAQ
21324 \begin_inset Quotes srd
21325 \end_inset
21326
21327 :
21328 \layout Quote
21329
21330 If well-defined overflow characteristics are important and negative values
21331  are not, or if you want to steer clear of sign-extension problems when
21332  manipulating bits or bytes, use one of the corresponding unsigned types.
21333  (Beware when mixing signed and unsigned values in expressions, though.)
21334 \newline
21335 Although character types (especially unsigned char) can be used as "tiny"
21336  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
21337 ble sign extension and increased code size.
21338 \end_deeper
21339 \layout Itemize
21340
21341 Use unsigned when it is known in advance that the value is not going to
21342  be negative.
21343  This helps especially if you are doing division or multiplication, bit-shifting
21344  or are using an array index.
21345 \layout Itemize
21346
21347 NEVER jump into a LOOP.
21348 \layout Itemize
21349
21350 Declare the variables to be local
21351 \begin_inset LatexCommand \index{local variables}
21352
21353 \end_inset
21354
21355  whenever possible, especially loop control variables (induction).
21356 \layout Itemize
21357
21358 Since the compiler does not always do implicit integral promotion, the programme
21359 r should do an explicit cast when integral promotion is required.
21360 \layout Itemize
21361
21362 Reducing the size of division, multiplication & modulus operations can reduce
21363  code size substantially.
21364  Take the following code for example.
21365 \begin_deeper
21366 \layout Verse
21367
21368
21369 \family typewriter
21370 foobar(unsigned int p1, unsigned char ch)
21371 \newline
21372 {
21373 \newline
21374 \SpecialChar ~
21375 \SpecialChar ~
21376 \SpecialChar ~
21377 \SpecialChar ~
21378 unsigned char ch1 = p1 % ch ;
21379 \newline
21380 \SpecialChar ~
21381 \SpecialChar ~
21382 \SpecialChar ~
21383 \SpecialChar ~
21384 ....
21385 \newline
21386 }
21387 \layout Standard
21388
21389 For the modulus operation the variable ch will be promoted to unsigned int
21390  first then the modulus operation will be performed (this will lead to a
21391  call to support routine _moduint()), and the result will be casted to a
21392  char.
21393  If the code is changed to
21394 \layout Verse
21395
21396
21397 \family typewriter
21398 foobar(unsigned int p1, unsigned char ch)
21399 \newline
21400 {
21401 \newline
21402 \SpecialChar ~
21403 \SpecialChar ~
21404 \SpecialChar ~
21405 \SpecialChar ~
21406 unsigned char ch1 = (unsigned char)p1 % ch ;
21407 \newline
21408 \SpecialChar ~
21409 \SpecialChar ~
21410 \SpecialChar ~
21411 \SpecialChar ~
21412 ....
21413 \newline
21414 }
21415 \layout Standard
21416
21417 It would substantially reduce the code generated (future versions of the
21418  compiler will be smart enough to detect such optimization opportunities).
21419 \end_deeper
21420 \layout Itemize
21421
21422 Have a look at the assembly listing to get a
21423 \begin_inset Quotes sld
21424 \end_inset
21425
21426 feeling
21427 \begin_inset Quotes srd
21428 \end_inset
21429
21430  for the code generation.
21431 \layout Section
21432
21433 Tools
21434 \begin_inset LatexCommand \index{Tools}
21435
21436 \end_inset
21437
21438  included in the distribution
21439 \layout Standard
21440 \align center
21441
21442 \begin_inset  Tabular
21443 <lyxtabular version="3" rows="12" columns="3">
21444 <features>
21445 <column alignment="center" valignment="top" leftline="true" width="0pt">
21446 <column alignment="center" valignment="top" leftline="true" width="0pt">
21447 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
21448 <row topline="true" bottomline="true">
21449 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21450 \begin_inset Text
21451
21452 \layout Standard
21453
21454 Name
21455 \end_inset
21456 </cell>
21457 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21458 \begin_inset Text
21459
21460 \layout Standard
21461
21462 Purpose
21463 \end_inset
21464 </cell>
21465 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21466 \begin_inset Text
21467
21468 \layout Standard
21469
21470 Directory
21471 \end_inset
21472 </cell>
21473 </row>
21474 <row topline="true">
21475 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21476 \begin_inset Text
21477
21478 \layout Standard
21479
21480 uCsim
21481 \end_inset
21482 </cell>
21483 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21484 \begin_inset Text
21485
21486 \layout Standard
21487
21488 Simulator for various architectures
21489 \end_inset
21490 </cell>
21491 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21492 \begin_inset Text
21493
21494 \layout Standard
21495
21496 sdcc/sim/ucsim
21497 \end_inset
21498 </cell>
21499 </row>
21500 <row topline="true">
21501 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21502 \begin_inset Text
21503
21504 \layout Standard
21505
21506 keil2sdcc.pl
21507 \end_inset
21508 </cell>
21509 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21510 \begin_inset Text
21511
21512 \layout Standard
21513
21514 header file conversion
21515 \end_inset
21516 </cell>
21517 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21518 \begin_inset Text
21519
21520 \layout Standard
21521
21522 sdcc/support/scripts
21523 \end_inset
21524 </cell>
21525 </row>
21526 <row topline="true">
21527 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21528 \begin_inset Text
21529
21530 \layout Standard
21531
21532 mh2h.c
21533 \end_inset
21534 </cell>
21535 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21536 \begin_inset Text
21537
21538 \layout Standard
21539
21540 header file conversion
21541 \end_inset
21542 </cell>
21543 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21544 \begin_inset Text
21545
21546 \layout Standard
21547
21548 sdcc/support/scripts
21549 \end_inset
21550 </cell>
21551 </row>
21552 <row topline="true">
21553 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21554 \begin_inset Text
21555
21556 \layout Standard
21557
21558 as-gbz80
21559 \end_inset
21560 </cell>
21561 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21562 \begin_inset Text
21563
21564 \layout Standard
21565
21566 Assembler
21567 \end_inset
21568 </cell>
21569 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21570 \begin_inset Text
21571
21572 \layout Standard
21573
21574
21575 \family roman
21576 \series medium
21577 \shape up
21578 \size normal
21579 \emph off
21580 \bar no
21581 \noun off
21582 \color none
21583 sdcc/bin
21584 \end_inset
21585 </cell>
21586 </row>
21587 <row topline="true">
21588 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21589 \begin_inset Text
21590
21591 \layout Standard
21592
21593 as-z80
21594 \end_inset
21595 </cell>
21596 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21597 \begin_inset Text
21598
21599 \layout Standard
21600
21601 Assembler
21602 \end_inset
21603 </cell>
21604 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21605 \begin_inset Text
21606
21607 \layout Standard
21608
21609
21610 \family roman
21611 \series medium
21612 \shape up
21613 \size normal
21614 \emph off
21615 \bar no
21616 \noun off
21617 \color none
21618 sdcc/bin
21619 \end_inset
21620 </cell>
21621 </row>
21622 <row topline="true">
21623 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21624 \begin_inset Text
21625
21626 \layout Standard
21627
21628 asx8051
21629 \end_inset
21630 </cell>
21631 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21632 \begin_inset Text
21633
21634 \layout Standard
21635
21636 Assembler
21637 \end_inset
21638 </cell>
21639 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21640 \begin_inset Text
21641
21642 \layout Standard
21643
21644
21645 \family roman
21646 \series medium
21647 \shape up
21648 \size normal
21649 \emph off
21650 \bar no
21651 \noun off
21652 \color none
21653 sdcc/bin
21654 \end_inset
21655 </cell>
21656 </row>
21657 <row topline="true">
21658 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21659 \begin_inset Text
21660
21661 \layout Standard
21662
21663 sdcdb
21664 \end_inset
21665 </cell>
21666 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21667 \begin_inset Text
21668
21669 \layout Standard
21670
21671 Simulator
21672 \end_inset
21673 </cell>
21674 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21675 \begin_inset Text
21676
21677 \layout Standard
21678
21679
21680 \family roman
21681 \series medium
21682 \shape up
21683 \size normal
21684 \emph off
21685 \bar no
21686 \noun off
21687 \color none
21688 sdcc/bin
21689 \end_inset
21690 </cell>
21691 </row>
21692 <row topline="true">
21693 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21694 \begin_inset Text
21695
21696 \layout Standard
21697
21698 aslink
21699 \end_inset
21700 </cell>
21701 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21702 \begin_inset Text
21703
21704 \layout Standard
21705
21706 Linker
21707 \end_inset
21708 </cell>
21709 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21710 \begin_inset Text
21711
21712 \layout Standard
21713
21714
21715 \family roman
21716 \series medium
21717 \shape up
21718 \size normal
21719 \emph off
21720 \bar no
21721 \noun off
21722 \color none
21723 sdcc/bin
21724 \end_inset
21725 </cell>
21726 </row>
21727 <row topline="true">
21728 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21729 \begin_inset Text
21730
21731 \layout Standard
21732
21733 link-z80
21734 \end_inset
21735 </cell>
21736 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21737 \begin_inset Text
21738
21739 \layout Standard
21740
21741 Linker
21742 \end_inset
21743 </cell>
21744 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21745 \begin_inset Text
21746
21747 \layout Standard
21748
21749
21750 \family roman
21751 \series medium
21752 \shape up
21753 \size normal
21754 \emph off
21755 \bar no
21756 \noun off
21757 \color none
21758 sdcc/bin
21759 \end_inset
21760 </cell>
21761 </row>
21762 <row topline="true">
21763 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21764 \begin_inset Text
21765
21766 \layout Standard
21767
21768 link-gbz80
21769 \end_inset
21770 </cell>
21771 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21772 \begin_inset Text
21773
21774 \layout Standard
21775
21776 Linker
21777 \end_inset
21778 </cell>
21779 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21780 \begin_inset Text
21781
21782 \layout Standard
21783
21784
21785 \family roman
21786 \series medium
21787 \shape up
21788 \size normal
21789 \emph off
21790 \bar no
21791 \noun off
21792 \color none
21793 sdcc/bin
21794 \end_inset
21795 </cell>
21796 </row>
21797 <row topline="true" bottomline="true">
21798 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21799 \begin_inset Text
21800
21801 \layout Standard
21802
21803 packihx
21804 \end_inset
21805 </cell>
21806 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21807 \begin_inset Text
21808
21809 \layout Standard
21810
21811 ihx packer
21812 \end_inset
21813 </cell>
21814 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21815 \begin_inset Text
21816
21817 \layout Standard
21818
21819
21820 \family roman
21821 \series medium
21822 \shape up
21823 \size normal
21824 \emph off
21825 \bar no
21826 \noun off
21827 \color none
21828 sdcc/bin
21829 \end_inset
21830 </cell>
21831 </row>
21832 </lyxtabular>
21833
21834 \end_inset
21835
21836
21837 \newline
21838
21839 \layout Section
21840
21841 Documentation
21842 \begin_inset LatexCommand \index{Documentation}
21843
21844 \end_inset
21845
21846  included in the distribution
21847 \layout Standard
21848 \align center
21849
21850 \begin_inset  Tabular
21851 <lyxtabular version="3" rows="10" columns="2">
21852 <features>
21853 <column alignment="left" valignment="top" leftline="true" width="0">
21854 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
21855 <row topline="true" bottomline="true">
21856 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21857 \begin_inset Text
21858
21859 \layout Standard
21860
21861 Subject / Title
21862 \end_inset
21863 </cell>
21864 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21865 \begin_inset Text
21866
21867 \layout Standard
21868
21869 Where to get / filename
21870 \end_inset
21871 </cell>
21872 </row>
21873 <row topline="true">
21874 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21875 \begin_inset Text
21876
21877 \layout Standard
21878
21879 SDCC Compiler User Guide
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 You're reading it right now
21888 \end_inset
21889 </cell>
21890 </row>
21891 <row topline="true">
21892 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21893 \begin_inset Text
21894
21895 \layout Standard
21896
21897 Changelog of SDCC
21898 \end_inset
21899 </cell>
21900 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21901 \begin_inset Text
21902
21903 \layout Standard
21904
21905 sdcc/Changelog
21906 \end_inset
21907 </cell>
21908 </row>
21909 <row topline="true">
21910 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21911 \begin_inset Text
21912
21913 \layout Standard
21914
21915 ASXXXX
21916 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
21917
21918 \end_inset
21919
21920
21921 \begin_inset LatexCommand \index{Assembler documentation}
21922
21923 \end_inset
21924
21925  Assemblers and ASLINK
21926 \begin_inset LatexCommand \index{aslink}
21927
21928 \end_inset
21929
21930
21931 \begin_inset LatexCommand \index{Linker documentation}
21932
21933 \end_inset
21934
21935  Relocating Linker
21936 \end_inset
21937 </cell>
21938 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21939 \begin_inset Text
21940
21941 \layout Standard
21942
21943 sdcc/as/doc/asxhtm.html
21944 \end_inset
21945 </cell>
21946 </row>
21947 <row topline="true">
21948 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21949 \begin_inset Text
21950
21951 \layout Standard
21952
21953 SDCC regression test
21954 \begin_inset LatexCommand \index{Regression test}
21955
21956 \end_inset
21957
21958
21959 \end_inset
21960 </cell>
21961 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21962 \begin_inset Text
21963
21964 \layout Standard
21965
21966 sdcc/doc/test_suite_spec.pdf
21967 \end_inset
21968 </cell>
21969 </row>
21970 <row topline="true">
21971 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21972 \begin_inset Text
21973
21974 \layout Standard
21975
21976 Various notes
21977 \end_inset
21978 </cell>
21979 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21980 \begin_inset Text
21981
21982 \layout Standard
21983
21984 sdcc/doc/*
21985 \end_inset
21986 </cell>
21987 </row>
21988 <row topline="true">
21989 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21990 \begin_inset Text
21991
21992 \layout Standard
21993
21994 Notes on debugging with sdcdb
21995 \begin_inset LatexCommand \index{sdcdb (debugger)}
21996
21997 \end_inset
21998
21999
22000 \end_inset
22001 </cell>
22002 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22003 \begin_inset Text
22004
22005 \layout Standard
22006
22007 sdcc/debugger/README
22008 \end_inset
22009 </cell>
22010 </row>
22011 <row topline="true">
22012 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22013 \begin_inset Text
22014
22015 \layout Standard
22016
22017 Software simulator for microcontrollers
22018 \end_inset
22019 </cell>
22020 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22021 \begin_inset Text
22022
22023 \layout Standard
22024
22025
22026 \family roman
22027 \series medium
22028 \shape up
22029 \size normal
22030 \emph off
22031 \bar no
22032 \noun off
22033 \color none
22034 sdcc/sim/ucsim/doc
22035 \family default
22036 \series default
22037 \shape default
22038 \size default
22039 \emph default
22040 \bar default
22041 \noun default
22042 \color default
22043 /index.html
22044 \end_inset
22045 </cell>
22046 </row>
22047 <row topline="true">
22048 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22049 \begin_inset Text
22050
22051 \layout Standard
22052
22053 Temporary notes on the pic16
22054 \begin_inset LatexCommand \index{PIC16}
22055
22056 \end_inset
22057
22058  port
22059 \end_inset
22060 </cell>
22061 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22062 \begin_inset Text
22063
22064 \layout Standard
22065
22066 sdcc/src/pic16/NOTES
22067 \end_inset
22068 </cell>
22069 </row>
22070 <row topline="true" bottomline="true">
22071 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22072 \begin_inset Text
22073
22074 \layout Standard
22075
22076 SDCC internal documentation (debugging file format)
22077 \end_inset
22078 </cell>
22079 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22080 \begin_inset Text
22081
22082 \layout Standard
22083
22084 sdcc/doc/
22085 \family roman
22086 \series medium
22087 \shape up
22088 \size normal
22089 \emph off
22090 \bar no
22091 \noun off
22092 \color none
22093 cdbfileformat.pd
22094 \family default
22095 \series default
22096 \shape default
22097 \size default
22098 \emph default
22099 \bar default
22100 \noun default
22101 \color default
22102 f
22103 \end_inset
22104 </cell>
22105 </row>
22106 </lyxtabular>
22107
22108 \end_inset
22109
22110
22111 \newline
22112
22113 \layout Section
22114
22115 Related open source tools
22116 \begin_inset LatexCommand \index{Related tools}
22117
22118 \end_inset
22119
22120
22121 \layout Standard
22122 \align center
22123
22124 \begin_inset  Tabular
22125 <lyxtabular version="3" rows="11" columns="3">
22126 <features>
22127 <column alignment="center" valignment="top" leftline="true" width="0pt">
22128 <column alignment="block" valignment="top" leftline="true" width="30line%">
22129 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
22130 <row topline="true" bottomline="true">
22131 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22132 \begin_inset Text
22133
22134 \layout Standard
22135
22136 Name
22137 \end_inset
22138 </cell>
22139 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22140 \begin_inset Text
22141
22142 \layout Standard
22143
22144 Purpose
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 Where to get
22153 \end_inset
22154 </cell>
22155 </row>
22156 <row topline="true">
22157 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22158 \begin_inset Text
22159
22160 \layout Standard
22161
22162 gpsim
22163 \begin_inset LatexCommand \index{gpsim (pic simulator)}
22164
22165 \end_inset
22166
22167
22168 \end_inset
22169 </cell>
22170 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22171 \begin_inset Text
22172
22173 \layout Standard
22174
22175 PIC simulator
22176 \end_inset
22177 </cell>
22178 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22179 \begin_inset Text
22180
22181 \layout Standard
22182
22183
22184 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
22185
22186 \end_inset
22187
22188
22189 \end_inset
22190 </cell>
22191 </row>
22192 <row topline="true">
22193 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22194 \begin_inset Text
22195
22196 \layout Standard
22197
22198 gputils
22199 \begin_inset LatexCommand \index{gputils (pic tools)}
22200
22201 \end_inset
22202
22203
22204 \end_inset
22205 </cell>
22206 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22207 \begin_inset Text
22208
22209 \layout Standard
22210
22211 GNU PIC utilities
22212 \end_inset
22213 </cell>
22214 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22215 \begin_inset Text
22216
22217 \layout Standard
22218
22219
22220 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
22221
22222 \end_inset
22223
22224
22225 \end_inset
22226 </cell>
22227 </row>
22228 <row topline="true">
22229 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22230 \begin_inset Text
22231
22232 \layout Standard
22233
22234 flP5
22235 \end_inset
22236 </cell>
22237 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22238 \begin_inset Text
22239
22240 \layout Standard
22241
22242 PIC programmer
22243 \end_inset
22244 </cell>
22245 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22246 \begin_inset Text
22247
22248 \layout Standard
22249
22250
22251 \begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/}
22252
22253 \end_inset
22254
22255
22256 \end_inset
22257 </cell>
22258 </row>
22259 <row topline="true">
22260 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22261 \begin_inset Text
22262
22263 \layout Standard
22264
22265 indent
22266 \begin_inset LatexCommand \index{indent (source formatting tool)}
22267
22268 \end_inset
22269
22270
22271 \end_inset
22272 </cell>
22273 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22274 \begin_inset Text
22275
22276 \layout Standard
22277
22278 Formats C source - Master of the white spaces
22279 \end_inset
22280 </cell>
22281 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22282 \begin_inset Text
22283
22284 \layout Standard
22285
22286
22287 \begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html}
22288
22289 \end_inset
22290
22291
22292 \end_inset
22293 </cell>
22294 </row>
22295 <row topline="true">
22296 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22297 \begin_inset Text
22298
22299 \layout Standard
22300
22301 srecord
22302 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
22303
22304 \end_inset
22305
22306
22307 \end_inset
22308 </cell>
22309 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22310 \begin_inset Text
22311
22312 \layout Standard
22313
22314 Object file conversion, checksumming, ...
22315 \end_inset
22316 </cell>
22317 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22318 \begin_inset Text
22319
22320 \layout Standard
22321
22322
22323 \begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord}
22324
22325 \end_inset
22326
22327
22328 \end_inset
22329 </cell>
22330 </row>
22331 <row topline="true">
22332 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22333 \begin_inset Text
22334
22335 \layout Standard
22336
22337 objdump
22338 \begin_inset LatexCommand \index{objdump (tool)}
22339
22340 \end_inset
22341
22342
22343 \end_inset
22344 </cell>
22345 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22346 \begin_inset Text
22347
22348 \layout Standard
22349
22350 Object file conversion, ...
22351 \end_inset
22352 </cell>
22353 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22354 \begin_inset Text
22355
22356 \layout Standard
22357
22358 Part of binutils (should be there anyway)
22359 \end_inset
22360 </cell>
22361 </row>
22362 <row topline="true">
22363 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22364 \begin_inset Text
22365
22366 \layout Standard
22367
22368 doxygen
22369 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
22370
22371 \end_inset
22372
22373
22374 \end_inset
22375 </cell>
22376 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22377 \begin_inset Text
22378
22379 \layout Standard
22380
22381 Source code documentation system
22382 \end_inset
22383 </cell>
22384 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22385 \begin_inset Text
22386
22387 \layout Standard
22388
22389
22390 \begin_inset LatexCommand \url{http://www.doxygen.org}
22391
22392 \end_inset
22393
22394
22395 \end_inset
22396 </cell>
22397 </row>
22398 <row topline="true">
22399 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22400 \begin_inset Text
22401
22402 \layout Standard
22403
22404 kdevelop
22405 \end_inset
22406 </cell>
22407 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22408 \begin_inset Text
22409
22410 \layout Standard
22411
22412 IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
22413 \end_inset
22414 </cell>
22415 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22416 \begin_inset Text
22417
22418 \layout Standard
22419
22420
22421 \begin_inset LatexCommand \url{http://www.kdevelop.org}
22422
22423 \end_inset
22424
22425
22426 \end_inset
22427 </cell>
22428 </row>
22429 <row topline="true">
22430 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22431 \begin_inset Text
22432
22433 \layout Standard
22434
22435 splint
22436 \begin_inset LatexCommand \index{splint (syntax checking tool)}
22437
22438 \end_inset
22439
22440
22441 \end_inset
22442 </cell>
22443 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22444 \begin_inset Text
22445
22446 \layout Standard
22447
22448 Statically checks c sources (see
22449 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
22450
22451 \end_inset
22452
22453 )
22454 \end_inset
22455 </cell>
22456 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22457 \begin_inset Text
22458
22459 \layout Standard
22460
22461
22462 \begin_inset LatexCommand \url{http://www.splint.org}
22463
22464 \end_inset
22465
22466
22467 \end_inset
22468 </cell>
22469 </row>
22470 <row topline="true" bottomline="true">
22471 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22472 \begin_inset Text
22473
22474 \layout Standard
22475
22476 ddd
22477 \begin_inset LatexCommand \index{ddd (debugger)}
22478
22479 \end_inset
22480
22481
22482 \end_inset
22483 </cell>
22484 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22485 \begin_inset Text
22486
22487 \layout Standard
22488
22489 Debugger, serves nicely as GUI to sdcdb
22490 \begin_inset LatexCommand \index{sdcdb (debugger)}
22491
22492 \end_inset
22493
22494  (Unix only)
22495 \end_inset
22496 </cell>
22497 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22498 \begin_inset Text
22499
22500 \layout Standard
22501
22502
22503 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
22504
22505 \end_inset
22506
22507
22508 \end_inset
22509 </cell>
22510 </row>
22511 </lyxtabular>
22512
22513 \end_inset
22514
22515
22516 \newline
22517
22518 \layout Section
22519
22520 Related documentation / recommended reading
22521 \layout Standard
22522 \align center
22523
22524 \begin_inset  Tabular
22525 <lyxtabular version="3" rows="6" columns="3">
22526 <features>
22527 <column alignment="center" valignment="top" leftline="true" width="0pt">
22528 <column alignment="block" valignment="top" leftline="true" width="30line%">
22529 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
22530 <row topline="true" bottomline="true">
22531 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22532 \begin_inset Text
22533
22534 \layout Standard
22535
22536 Name
22537 \end_inset
22538 </cell>
22539 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22540 \begin_inset Text
22541
22542 \layout Standard
22543
22544 Subject / Title
22545 \end_inset
22546 </cell>
22547 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22548 \begin_inset Text
22549
22550 \layout Standard
22551
22552 Where to get
22553 \end_inset
22554 </cell>
22555 </row>
22556 <row topline="true">
22557 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22558 \begin_inset Text
22559
22560 \layout Standard
22561
22562
22563 \family roman
22564 \series medium
22565 \shape up
22566 \size normal
22567 \emph off
22568 \bar no
22569 \noun off
22570 \color none
22571 c-refcard.pdf
22572 \end_inset
22573 </cell>
22574 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22575 \begin_inset Text
22576
22577 \layout Standard
22578
22579 C Reference Card
22580 \begin_inset LatexCommand \index{C Reference card}
22581
22582 \end_inset
22583
22584 , 2 pages
22585 \end_inset
22586 </cell>
22587 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22588 \begin_inset Text
22589
22590 \layout Standard
22591
22592
22593 \begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html}
22594
22595 \end_inset
22596
22597
22598 \end_inset
22599 </cell>
22600 </row>
22601 <row topline="true">
22602 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22603 \begin_inset Text
22604
22605 \layout Standard
22606
22607 c-faq
22608 \end_inset
22609 </cell>
22610 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22611 \begin_inset Text
22612
22613 \layout Standard
22614
22615 C-FAQ-list
22616 \end_inset
22617 </cell>
22618 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22619 \begin_inset Text
22620
22621 \layout Standard
22622
22623
22624 \begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
22625
22626 \end_inset
22627
22628
22629 \end_inset
22630 </cell>
22631 </row>
22632 <row topline="true">
22633 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22634 \begin_inset Text
22635
22636 \layout Standard
22637
22638 \end_inset
22639 </cell>
22640 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22641 \begin_inset Text
22642
22643 \layout Standard
22644
22645 Latest datasheet of the target CPU
22646 \end_inset
22647 </cell>
22648 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22649 \begin_inset Text
22650
22651 \layout Standard
22652
22653 vendor
22654 \end_inset
22655 </cell>
22656 </row>
22657 <row topline="true">
22658 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22659 \begin_inset Text
22660
22661 \layout Standard
22662
22663 \end_inset
22664 </cell>
22665 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22666 \begin_inset Text
22667
22668 \layout Standard
22669
22670 Revision history of datasheet
22671 \end_inset
22672 </cell>
22673 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22674 \begin_inset Text
22675
22676 \layout Standard
22677
22678 vendor
22679 \end_inset
22680 </cell>
22681 </row>
22682 <row topline="true" bottomline="true">
22683 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22684 \begin_inset Text
22685
22686 \layout Standard
22687
22688 S.
22689  S.
22690  Muchnick
22691 \end_inset
22692 </cell>
22693 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22694 \begin_inset Text
22695
22696 \layout Standard
22697
22698 Advanced Compiler Design and Implementation
22699 \end_inset
22700 </cell>
22701 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22702 \begin_inset Text
22703
22704 \layout Standard
22705
22706 bookstore (very dedicated, probably read other books first)
22707 \end_inset
22708 </cell>
22709 </row>
22710 </lyxtabular>
22711
22712 \end_inset
22713
22714
22715 \newline
22716
22717 \layout Section
22718
22719 Some Questions
22720 \layout Standard
22721
22722 Some questions answered, some pointers given - it might be time to in turn
22723  ask
22724 \emph on
22725 you
22726 \emph default
22727  some questions:
22728 \layout Itemize
22729
22730 can you solve your project with the selected microcontroller? Would you
22731  find out early or rather late that your target is too small/slow/whatever?
22732  Can you switch to a slightly better device if it doesn't fit?
22733 \layout Itemize
22734
22735 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
22736  and/or another programming language be more adequate? Would an operating
22737  system on the target device help?
22738 \layout Itemize
22739
22740 if you solved the problem, will the marketing department be happy?
22741 \layout Itemize
22742
22743 if the marketing department is happy, will customers be happy?
22744 \layout Itemize
22745
22746 if you're the project manager, marketing department and maybe even the customer
22747  in one person, have you tried to see the project from the outside?
22748 \layout Itemize
22749
22750 is the project done if you think it is done? Or is just that other interface/pro
22751 tocol/feature/configuration/option missing? How about website, manual(s),
22752  internationali(z|s)ation, packaging, labels, 2nd source for components,
22753  electromagnetic compatability/interference, documentation for production,
22754  production test software, update mechanism, patent issues?
22755 \layout Itemize
22756
22757 is your project adequately positioned in that magic triangle: fame, fortune,
22758  fun?
22759 \layout Standard
22760
22761 Maybe not all answers to these questions are known and some answers may
22762  even be
22763 \emph on
22764 no
22765 \emph default
22766 , nevertheless knowing these questions may help you to avoid burnout
22767 \begin_inset Foot
22768 collapsed false
22769
22770 \layout Standard
22771
22772 burnout is bad for electronic devices, programmers and motorcycle tyres
22773 \end_inset
22774
22775 .
22776  Chances are you didn't want to hear some of them...
22777 \layout Chapter
22778
22779 Support
22780 \begin_inset LatexCommand \index{Support}
22781
22782 \end_inset
22783
22784
22785 \layout Standard
22786
22787 SDCC has grown to be a large project.
22788  The compiler alone (without the preprocessor, assembler and linker) is
22789  well over 100,000 lines of code (blank stripped).
22790  The open source nature of this project is a key to its continued growth
22791  and support.
22792  You gain the benefit and support of many active software developers and
22793  end users.
22794  Is SDCC perfect? No, that's why we need your help.
22795  The developers take pride in fixing reported bugs.
22796  You can help by reporting the bugs and helping other SDCC users.
22797  There are lots of ways to contribute, and we encourage you to take part
22798  in making SDCC a great software package.
22799
22800 \layout Standard
22801
22802 The SDCC project is hosted on the SDCC sourceforge site at
22803 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
22804
22805 \end_inset
22806
22807 .
22808  You'll find the complete set of mailing lists
22809 \begin_inset LatexCommand \index{Mailing list(s)}
22810
22811 \end_inset
22812
22813 , forums, bug reporting system, patch submission
22814 \begin_inset LatexCommand \index{Patch submission}
22815
22816 \end_inset
22817
22818  system, download
22819 \begin_inset LatexCommand \index{download}
22820
22821 \end_inset
22822
22823  area and cvs code repository
22824 \begin_inset LatexCommand \index{cvs code repository}
22825
22826 \end_inset
22827
22828  there.
22829 \layout Section
22830
22831 Reporting Bugs
22832 \begin_inset LatexCommand \index{Bug reporting}
22833
22834 \end_inset
22835
22836
22837 \begin_inset LatexCommand \index{Reporting bugs}
22838
22839 \end_inset
22840
22841
22842 \layout Standard
22843
22844 The recommended way of reporting bugs is using the infrastructure of the
22845  sourceforge site.
22846  You can follow the status of bug reports there and have an overview about
22847  the known bugs.
22848 \layout Standard
22849
22850 Bug reports are automatically forwarded to the developer mailing list and
22851  will be fixed ASAP.
22852  When reporting a bug, it is very useful to include a small test program
22853  (the smaller the better) which reproduces the problem.
22854  If you can isolate the problem by looking at the generated assembly code,
22855  this can be very helpful.
22856  Compiling your program with the -
22857 \begin_inset ERT
22858 status Collapsed
22859
22860 \layout Standard
22861
22862 \backslash
22863 /
22864 \end_inset
22865
22866 -dumpall
22867 \begin_inset LatexCommand \index{-\/-dumpall}
22868
22869 \end_inset
22870
22871  option can sometimes be useful in locating optimization problems.
22872  When reporting a bug please maker sure you:
22873 \layout Enumerate
22874
22875 Attach the code you are compiling with SDCC.
22876
22877 \layout Enumerate
22878
22879 Specify the exact command you use to run SDCC, or attach your Makefile.
22880
22881 \layout Enumerate
22882
22883 Specify the SDCC version (type "
22884 \family sans
22885 \series bold
22886 sdcc -v
22887 \family default
22888 \series default
22889 "), your platform, and operating system.
22890
22891 \layout Enumerate
22892
22893 Provide an exact copy of any error message or incorrect output.
22894
22895 \layout Enumerate
22896
22897 Put something meaningful in the subject of your message.
22898 \layout Standard
22899
22900 Please attempt to include these 5 important parts, as applicable, in all
22901  requests for support or when reporting any problems or bugs with SDCC.
22902  Though this will make your message lengthy, it will greatly improve your
22903  chance that SDCC users and developers will be able to help you.
22904  Some SDCC developers are frustrated by bug reports without code provided
22905  that they can use to reproduce and ultimately fix the problem, so please
22906  be sure to provide sample code if you are reporting a bug!
22907 \layout Standard
22908
22909 Please have a short check that you are using a recent version of SDCC and
22910  the bug is not yet known.
22911  This is the link for reporting bugs:
22912 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
22913
22914 \end_inset
22915
22916 .
22917 \layout Section
22918
22919 Requesting Features
22920 \begin_inset LatexCommand \label{sub:Requesting-Features}
22921
22922 \end_inset
22923
22924
22925 \begin_inset LatexCommand \index{Feature request}
22926
22927 \end_inset
22928
22929
22930 \begin_inset LatexCommand \index{Requesting features}
22931
22932 \end_inset
22933
22934
22935 \layout Standard
22936
22937 Like bug reports feature requests are forwarded to the developer mailing
22938  list.
22939  This is the link for requesting features:
22940 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
22941
22942 \end_inset
22943
22944 .
22945 \layout Section
22946
22947 Submitting patches
22948 \layout Standard
22949
22950 Like bug reports contributed patches are forwarded to the developer mailing
22951  list.
22952  This is the link for submitting patches
22953 \begin_inset LatexCommand \index{Patch submission}
22954
22955 \end_inset
22956
22957 :
22958 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
22959
22960 \end_inset
22961
22962 .
22963 \layout Standard
22964
22965 You need to specify some parameters to the
22966 \family typewriter
22967 diff
22968 \family default
22969  command for the patches to be useful.
22970  If you modified more than one file a patch created f.e.
22971  with
22972 \family sans
22973 \series bold
22974
22975 \begin_inset Quotes sld
22976 \end_inset
22977
22978 diff -Naur unmodified_directory modified_directory >my_changes.patch
22979 \begin_inset Quotes srd
22980 \end_inset
22981
22982
22983 \family default
22984 \series default
22985  will be fine, otherwise
22986 \family sans
22987 \series bold
22988
22989 \begin_inset Quotes sld
22990 \end_inset
22991
22992 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
22993 \begin_inset Quotes srd
22994 \end_inset
22995
22996
22997 \series default
22998
22999 \family default
23000 will do.
23001 \layout Section
23002
23003 Getting Help
23004 \layout Standard
23005
23006 These links should take you directly to the
23007 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
23008
23009 \end_inset
23010
23011
23012 \begin_inset Foot
23013 collapsed false
23014
23015 \layout Standard
23016
23017 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
23018  automated messages (mid 2003)
23019 \end_inset
23020
23021  and the
23022 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
23023
23024 \end_inset
23025
23026 , lists
23027 \begin_inset LatexCommand \index{Mailing list(s)}
23028
23029 \end_inset
23030
23031  and forums are archived and searchable so if you are lucky someone already
23032  had a similar problem.
23033  While mails to the lists themselves are delivered promptly their web front
23034  end on sourceforge sometimes shows a severe time lag (up to several weeks),
23035  if you're seriously using SDCC please consider subscribing to the lists.
23036 \layout Section
23037
23038 ChangeLog
23039 \layout Standard
23040
23041 You can follow the status of the cvs version
23042 \begin_inset LatexCommand \index{version}
23043
23044 \end_inset
23045
23046  of SDCC by watching the Changelog
23047 \begin_inset LatexCommand \index{Changelog}
23048
23049 \end_inset
23050
23051  in the cvs-repository
23052 \newline
23053
23054 \size footnotesize
23055
23056 \begin_inset LatexCommand \htmlurl{http://cvs.sf.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
23057
23058 \end_inset
23059
23060 .
23061 \layout Section
23062
23063 Release policy
23064 \begin_inset LatexCommand \index{Release policy}
23065
23066 \end_inset
23067
23068
23069 \layout Standard
23070
23071 Historically there often were long delays between official releases and
23072  the sourceforge download area tends to get not updated at all.
23073  Excuses in the past might have referred to problems with live range analysis,
23074  but as this was fixed a while ago, the current problem is that another
23075  excuse has to be found.
23076  Kidding aside, we have to get better there! On the other hand there are
23077  daily snapshots available at
23078 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
23079
23080 \end_inset
23081
23082 , and you can always build the very last version (hopefully with many bugs
23083  fixed, and features added) from the source code available at
23084 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
23085
23086 \end_inset
23087
23088 .
23089 \layout Section
23090
23091 Examples
23092 \begin_inset LatexCommand \index{Examples}
23093
23094 \end_inset
23095
23096
23097 \layout Standard
23098
23099 You'll find some small examples in the directory
23100 \emph on
23101 sdcc/device/examples/.
23102
23103 \emph default
23104 More examples and libraries are available at
23105 \emph on
23106  The SDCC Open Knowledge Resource
23107 \begin_inset LatexCommand \url{http://sdccokr.dl9sec.de/}
23108
23109 \end_inset
23110
23111
23112 \emph default
23113 web site or at
23114 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
23115
23116 \end_inset
23117
23118 .
23119 \layout Comment
23120
23121 I did insert a reference to Paul's web site here although it seems rather
23122  dedicated to a specific 8032 board (I think it's okay because it f.e.
23123  shows LCD/Harddisc interface and has a free 8051 monitor.
23124  Independent 8032 board vendors face hard competition of heavily subsidized
23125  development boards anyway).
23126 \layout Comment
23127
23128 Maybe we should include some links to real world applications.
23129  Preferably pointer to pointers (one for each architecture) so this stays
23130  manageable here?
23131 \layout Section
23132
23133 Quality control
23134 \begin_inset LatexCommand \index{Quality control}
23135
23136 \end_inset
23137
23138
23139 \layout Standard
23140
23141 The compiler is passed through nightly compile and build checks.
23142  The so called
23143 \shape italic
23144 regression tests
23145 \shape default
23146
23147 \begin_inset LatexCommand \index{Regression test}
23148
23149 \end_inset
23150
23151  check that SDCC itself compiles flawlessly on several platforms and checks
23152  the quality of the code generated by SDCC by running the code through simulator
23153 s.
23154  There is a separate document
23155 \shape italic
23156 test_suite.pdf
23157 \begin_inset LatexCommand \index{Test suite}
23158
23159 \end_inset
23160
23161
23162 \shape default
23163  about this.
23164 \layout Standard
23165
23166 You'll find the test code in the directory
23167 \shape italic
23168 sdcc/support/regression
23169 \shape default
23170 .
23171  You can run these tests manually by running
23172 \family sans
23173 make
23174 \family default
23175  in this directory (or f.e.
23176
23177 \family sans
23178 \series bold
23179
23180 \begin_inset Quotes sld
23181 \end_inset
23182
23183 make test-mcs51
23184 \begin_inset Quotes srd
23185 \end_inset
23186
23187
23188 \family default
23189 \series default
23190  if you don't want to run the complete tests).
23191  The test code might also be interesting if you want to look for examples
23192 \begin_inset LatexCommand \index{Examples}
23193
23194 \end_inset
23195
23196  checking corner cases of SDCC or if you plan to submit patches
23197 \begin_inset LatexCommand \index{Patch submission}
23198
23199 \end_inset
23200
23201 .
23202 \layout Standard
23203
23204 The pic port uses a different set of regression tests, you'll find them
23205  in the directory
23206 \shape italic
23207 sdcc/src/regression
23208 \shape default
23209 .
23210 \layout Chapter
23211 \pagebreak_top
23212 SDCC Technical Data
23213 \layout Section
23214
23215 Optimizations
23216 \begin_inset LatexCommand \index{Optimizations}
23217
23218 \end_inset
23219
23220
23221 \layout Standard
23222
23223 SDCC performs a host of standard optimizations in addition to some MCU specific
23224  optimizations.
23225
23226 \layout Subsection
23227
23228 Sub-expression Elimination
23229 \begin_inset LatexCommand \index{Subexpression elimination}
23230
23231 \end_inset
23232
23233
23234 \layout Standard
23235
23236 The compiler does local and
23237 \emph on
23238 g
23239 \emph default
23240 lobal
23241 \emph on
23242 c
23243 \emph default
23244 ommon
23245 \emph on
23246 s
23247 \emph default
23248 ubexpression
23249 \emph on
23250 e
23251 \emph default
23252 limination, e.g.:
23253 \layout Verse
23254
23255
23256 \family typewriter
23257 i = x + y + 1;
23258 \newline
23259 j = x + y;
23260 \layout Standard
23261
23262 will be translated to
23263 \layout Verse
23264
23265
23266 \family typewriter
23267 iTemp = x + y;
23268 \newline
23269 i = iTemp + 1;
23270 \newline
23271 j = iTemp;
23272 \layout Standard
23273
23274 Some subexpressions are not as obvious as the above example, e.g.:
23275 \layout Verse
23276
23277
23278 \family typewriter
23279 a->b[i].c = 10;
23280 \newline
23281 a->b[i].d = 11;
23282 \layout Standard
23283
23284 In this case the address arithmetic a->b[i] will be computed only once;
23285  the equivalent code in C would be.
23286 \layout Verse
23287
23288
23289 \family typewriter
23290 iTemp = a->b[i];
23291 \newline
23292 iTemp.c = 10;
23293 \newline
23294 iTemp.d = 11;
23295 \layout Standard
23296
23297 The compiler will try to keep these temporary variables in registers.
23298 \layout Subsection
23299
23300 Dead-Code Elimination
23301 \begin_inset LatexCommand \index{Dead-code elimination}
23302
23303 \end_inset
23304
23305
23306 \layout Verse
23307
23308
23309 \family typewriter
23310 int global;
23311 \newline
23312
23313 \newline
23314 void f () {
23315 \newline
23316 \SpecialChar ~
23317 \SpecialChar ~
23318 int i;
23319 \newline
23320 \SpecialChar ~
23321 \SpecialChar ~
23322 i = 1; \SpecialChar ~
23323 \SpecialChar ~
23324 \SpecialChar ~
23325 \SpecialChar ~
23326 \SpecialChar ~
23327 /* dead store */
23328 \newline
23329 \SpecialChar ~
23330 \SpecialChar ~
23331 global = 1;\SpecialChar ~
23332 /* dead store */
23333 \newline
23334 \SpecialChar ~
23335 \SpecialChar ~
23336 global = 2;
23337 \newline
23338 \SpecialChar ~
23339 \SpecialChar ~
23340 return;
23341 \newline
23342 \SpecialChar ~
23343 \SpecialChar ~
23344 global = 3;\SpecialChar ~
23345 /* unreachable */
23346 \newline
23347 }
23348 \layout Standard
23349
23350 will be changed to
23351 \layout Verse
23352
23353
23354 \family typewriter
23355 int global;
23356 \newline
23357
23358 \newline
23359 void f () {
23360 \newline
23361 \SpecialChar ~
23362 \SpecialChar ~
23363 global = 2;
23364 \newline
23365 }
23366 \layout Subsection
23367
23368 Copy-Propagation
23369 \begin_inset LatexCommand \index{Copy propagation}
23370
23371 \end_inset
23372
23373
23374 \layout Verse
23375
23376
23377 \family typewriter
23378 int f() {
23379 \newline
23380 \SpecialChar ~
23381 \SpecialChar ~
23382 int i, j;
23383 \newline
23384 \SpecialChar ~
23385 \SpecialChar ~
23386 i = 10;
23387 \newline
23388 \SpecialChar ~
23389 \SpecialChar ~
23390 j = i;
23391 \newline
23392 \SpecialChar ~
23393 \SpecialChar ~
23394 return j;
23395 \newline
23396 }
23397 \layout Standard
23398
23399 will be changed to
23400 \layout Verse
23401
23402
23403 \family typewriter
23404 int f() {
23405 \newline
23406 \SpecialChar ~
23407 \SpecialChar ~
23408 int i, j;
23409 \newline
23410 \SpecialChar ~
23411 \SpecialChar ~
23412 i = 10;
23413 \newline
23414 \SpecialChar ~
23415 \SpecialChar ~
23416 j = 10;
23417 \newline
23418 \SpecialChar ~
23419 \SpecialChar ~
23420 return 10;
23421 \newline
23422 }
23423 \layout Standard
23424
23425 Note: the dead stores created by this copy propagation will be eliminated
23426  by dead-code elimination.
23427 \layout Subsection
23428
23429 Loop Optimizations
23430 \begin_inset LatexCommand \index{Loop optimization}
23431
23432 \end_inset
23433
23434
23435 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
23436
23437 \end_inset
23438
23439
23440 \layout Standard
23441
23442 Two types of loop optimizations are done by SDCC
23443 \emph on
23444 loop invariant
23445 \emph default
23446  lifting and
23447 \emph on
23448  strength reduction
23449 \emph default
23450  of loop induction variables.
23451  In addition to the strength reduction the optimizer marks the induction
23452  variables and the register allocator tries to keep the induction variables
23453  in registers for the duration of the loop.
23454  Because of this preference of the register allocator
23455 \begin_inset LatexCommand \index{Register allocation}
23456
23457 \end_inset
23458
23459 , loop induction optimization causes an increase in register pressure, which
23460  may cause unwanted spilling of other temporary variables into the stack
23461 \begin_inset LatexCommand \index{stack}
23462
23463 \end_inset
23464
23465  / data space.
23466  The compiler will generate a warning message when it is forced to allocate
23467  extra space either on the stack or data space.
23468  If this extra space allocation is undesirable then induction optimization
23469  can be eliminated either for the entire source file (with -
23470 \begin_inset ERT
23471 status Collapsed
23472
23473 \layout Standard
23474
23475 \backslash
23476 /
23477 \end_inset
23478
23479 -noinduction option) or for a given function only using #pragma\SpecialChar ~
23480 noinduction
23481 \begin_inset LatexCommand \index{\#pragma noinduction}
23482
23483 \end_inset
23484
23485 .
23486 \newline
23487
23488 \newline
23489 Loop Invariant:
23490 \layout Verse
23491
23492
23493 \family typewriter
23494 for (i = 0 ; i < 100 ; i ++)
23495 \newline
23496 \SpecialChar ~
23497 \SpecialChar ~
23498 \SpecialChar ~
23499 \SpecialChar ~
23500 f += k + l;
23501 \layout Standard
23502
23503 changed to
23504 \layout Verse
23505
23506
23507 \family typewriter
23508 itemp = k + l;
23509 \newline
23510 for (i = 0; i < 100; i++)
23511 \newline
23512 \SpecialChar ~
23513 \SpecialChar ~
23514 \SpecialChar ~
23515 \SpecialChar ~
23516 f += itemp;
23517 \layout Standard
23518
23519 As mentioned previously some loop invariants are not as apparent, all static
23520  address computations are also moved out of the loop.
23521 \newline
23522
23523 \newline
23524 Strength Reduction
23525 \begin_inset LatexCommand \index{Strength reduction}
23526
23527 \end_inset
23528
23529 , this optimization substitutes an expression by a cheaper expression:
23530 \layout Verse
23531
23532
23533 \family typewriter
23534 for (i=0;i < 100; i++)
23535 \newline
23536 \SpecialChar ~
23537 \SpecialChar ~
23538 \SpecialChar ~
23539 \SpecialChar ~
23540 ar[i*5] = i*3;
23541 \layout Standard
23542
23543 changed to
23544 \layout Verse
23545
23546
23547 \family typewriter
23548 itemp1 = 0;
23549 \newline
23550 itemp2 = 0;
23551 \newline
23552 for (i=0;i< 100;i++) {
23553 \newline
23554 \SpecialChar ~
23555 \SpecialChar ~
23556 \SpecialChar ~
23557 \SpecialChar ~
23558 ar[itemp1] = itemp2;
23559 \newline
23560 \SpecialChar ~
23561 \SpecialChar ~
23562 \SpecialChar ~
23563 \SpecialChar ~
23564 itemp1 += 5;
23565 \newline
23566 \SpecialChar ~
23567 \SpecialChar ~
23568 \SpecialChar ~
23569 \SpecialChar ~
23570 itemp2 += 3;
23571 \newline
23572 }
23573 \layout Standard
23574
23575 The more expensive multiplication
23576 \begin_inset LatexCommand \index{Multiplication}
23577
23578 \end_inset
23579
23580  is changed to a less expensive addition.
23581 \layout Subsection
23582
23583 Loop Reversing
23584 \begin_inset LatexCommand \index{Loop reversing}
23585
23586 \end_inset
23587
23588
23589 \layout Standard
23590
23591 This optimization is done to reduce the overhead of checking loop boundaries
23592  for every iteration.
23593  Some simple loops can be reversed and implemented using a
23594 \begin_inset Quotes eld
23595 \end_inset
23596
23597 decrement and jump if not zero
23598 \begin_inset Quotes erd
23599 \end_inset
23600
23601  instruction.
23602  SDCC checks for the following criterion to determine if a loop is reversible
23603  (note: more sophisticated compilers use data-dependency analysis to make
23604  this determination, SDCC uses a more simple minded analysis).
23605 \layout Itemize
23606
23607 The 'for' loop is of the form
23608 \newline
23609
23610 \newline
23611
23612 \family typewriter
23613 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
23614  += 1])
23615 \newline
23616 \SpecialChar ~
23617 \SpecialChar ~
23618 \SpecialChar ~
23619 \SpecialChar ~
23620 <for body>
23621 \layout Itemize
23622
23623 The <for body> does not contain
23624 \begin_inset Quotes eld
23625 \end_inset
23626
23627 continue
23628 \begin_inset Quotes erd
23629 \end_inset
23630
23631  or 'break
23632 \begin_inset Quotes erd
23633 \end_inset
23634
23635 .
23636 \layout Itemize
23637
23638 All goto's are contained within the loop.
23639 \layout Itemize
23640
23641 No function calls within the loop.
23642 \layout Itemize
23643
23644 The loop control variable <sym> is not assigned any value within the loop
23645 \layout Itemize
23646
23647 The loop control variable does NOT participate in any arithmetic operation
23648  within the loop.
23649 \layout Itemize
23650
23651 There are NO switch statements in the loop.
23652 \layout Subsection
23653
23654 Algebraic Simplifications
23655 \layout Standard
23656
23657 SDCC does numerous algebraic simplifications, the following is a small sub-set
23658  of these optimizations.
23659 \layout Verse
23660
23661
23662 \family typewriter
23663 i = j + 0;\SpecialChar ~
23664 \SpecialChar ~
23665 \SpecialChar ~
23666 \SpecialChar ~
23667  /* changed to: */\SpecialChar ~
23668 \SpecialChar ~
23669 \SpecialChar ~
23670 \SpecialChar ~
23671  i = j;
23672 \newline
23673 i /= 2;\SpecialChar ~
23674 \SpecialChar ~
23675 \SpecialChar ~
23676 \SpecialChar ~
23677 \SpecialChar ~
23678 \SpecialChar ~
23679 \SpecialChar ~
23680  /* changed to: */\SpecialChar ~
23681 \SpecialChar ~
23682 \SpecialChar ~
23683 \SpecialChar ~
23684  i >>= 1;
23685 \newline
23686 i = j - j;\SpecialChar ~
23687 \SpecialChar ~
23688 \SpecialChar ~
23689 \SpecialChar ~
23690  /* changed to: */\SpecialChar ~
23691 \SpecialChar ~
23692 \SpecialChar ~
23693 \SpecialChar ~
23694  i = 0;
23695 \newline
23696 i = j / 1;\SpecialChar ~
23697 \SpecialChar ~
23698 \SpecialChar ~
23699 \SpecialChar ~
23700  /* changed to: */\SpecialChar ~
23701 \SpecialChar ~
23702 \SpecialChar ~
23703 \SpecialChar ~
23704  i = j;
23705 \layout Standard
23706
23707 Note the subexpressions
23708 \begin_inset LatexCommand \index{Subexpression}
23709
23710 \end_inset
23711
23712  given above are generally introduced by macro expansions or as a result
23713  of copy/constant propagation.
23714 \layout Subsection
23715
23716 'switch' Statements
23717 \begin_inset LatexCommand \label{sub:'switch'-Statements}
23718
23719 \end_inset
23720
23721
23722 \begin_inset LatexCommand \index{switch statement}
23723
23724 \end_inset
23725
23726
23727 \layout Standard
23728
23729 SDCC can optimize switch statements to jump tables
23730 \begin_inset LatexCommand \index{jump tables}
23731
23732 \end_inset
23733
23734 .
23735  It makes the decision based on an estimate of the generated code size.
23736  SDCC is quite liberal in the requirements for jump table generation:
23737 \layout Itemize
23738
23739 The labels need not be in order, and the starting number need not be one
23740  or zero, the case labels are in numerical sequence or not too many case
23741  labels are missing.
23742 \begin_deeper
23743 \layout Verse
23744
23745
23746 \family typewriter
23747 switch(i) {\SpecialChar ~
23748 \SpecialChar ~
23749 \SpecialChar ~
23750 \SpecialChar ~
23751 \SpecialChar ~
23752 \SpecialChar ~
23753 \SpecialChar ~
23754 \SpecialChar ~
23755 \SpecialChar ~
23756 \SpecialChar ~
23757 \SpecialChar ~
23758 \SpecialChar ~
23759 \SpecialChar ~
23760 \SpecialChar ~
23761 \SpecialChar ~
23762 \SpecialChar ~
23763 \SpecialChar ~
23764 \SpecialChar ~
23765 \SpecialChar ~
23766 \SpecialChar ~
23767 \SpecialChar ~
23768 \SpecialChar ~
23769 \SpecialChar ~
23770 \SpecialChar ~
23771 \SpecialChar ~
23772 \SpecialChar ~
23773 switch (i) {
23774 \newline
23775 \SpecialChar ~
23776 \SpecialChar ~
23777 \SpecialChar ~
23778 case 4: ...\SpecialChar ~
23779 \SpecialChar ~
23780 \SpecialChar ~
23781 \SpecialChar ~
23782 \SpecialChar ~
23783 \SpecialChar ~
23784 \SpecialChar ~
23785 \SpecialChar ~
23786 \SpecialChar ~
23787 \SpecialChar ~
23788 \SpecialChar ~
23789 \SpecialChar ~
23790 \SpecialChar ~
23791 \SpecialChar ~
23792 \SpecialChar ~
23793 \SpecialChar ~
23794 \SpecialChar ~
23795 \SpecialChar ~
23796 \SpecialChar ~
23797 \SpecialChar ~
23798 \SpecialChar ~
23799 \SpecialChar ~
23800 \SpecialChar ~
23801 \SpecialChar ~
23802 \SpecialChar ~
23803 \SpecialChar ~
23804 case 0: ...
23805
23806 \newline
23807 \SpecialChar ~
23808 \SpecialChar ~
23809 \SpecialChar ~
23810 case 5: ...\SpecialChar ~
23811 \SpecialChar ~
23812 \SpecialChar ~
23813 \SpecialChar ~
23814 \SpecialChar ~
23815 \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 case 1: ...
23837
23838 \newline
23839 \SpecialChar ~
23840 \SpecialChar ~
23841 \SpecialChar ~
23842 case 3: ...\SpecialChar ~
23843 \SpecialChar ~
23844 \SpecialChar ~
23845 \SpecialChar ~
23846 \SpecialChar ~
23847 \SpecialChar ~
23848 \SpecialChar ~
23849 \SpecialChar ~
23850 \SpecialChar ~
23851 \SpecialChar ~
23852 \SpecialChar ~
23853 \SpecialChar ~
23854 \SpecialChar ~
23855 \SpecialChar ~
23856 \SpecialChar ~
23857 \SpecialChar ~
23858 \SpecialChar ~
23859 \SpecialChar ~
23860 \SpecialChar ~
23861 \SpecialChar ~
23862 \SpecialChar ~
23863 \SpecialChar ~
23864 \SpecialChar ~
23865 \SpecialChar ~
23866 \SpecialChar ~
23867 \SpecialChar ~
23868
23869 \newline
23870 \SpecialChar ~
23871 \SpecialChar ~
23872 \SpecialChar ~
23873 case 6: ...\SpecialChar ~
23874 \SpecialChar ~
23875 \SpecialChar ~
23876 \SpecialChar ~
23877 \SpecialChar ~
23878 \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 case 3: ...
23900
23901 \newline
23902 \SpecialChar ~
23903 \SpecialChar ~
23904 \SpecialChar ~
23905 case 7: ...\SpecialChar ~
23906 \SpecialChar ~
23907 \SpecialChar ~
23908 \SpecialChar ~
23909 \SpecialChar ~
23910 \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 case 4: ...
23932
23933 \newline
23934 \SpecialChar ~
23935 \SpecialChar ~
23936 \SpecialChar ~
23937 case 8: ...\SpecialChar ~
23938 \SpecialChar ~
23939 \SpecialChar ~
23940 \SpecialChar ~
23941 \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 case 5: ...
23964
23965 \newline
23966 \SpecialChar ~
23967 \SpecialChar ~
23968 \SpecialChar ~
23969 case 9: ...\SpecialChar ~
23970 \SpecialChar ~
23971 \SpecialChar ~
23972 \SpecialChar ~
23973 \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 case 6: ...
23996
23997 \newline
23998 \SpecialChar ~
23999 \SpecialChar ~
24000 \SpecialChar ~
24001 case 10: ...\SpecialChar ~
24002 \SpecialChar ~
24003 \SpecialChar ~
24004 \SpecialChar ~
24005 \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 case 7: ...
24027
24028 \newline
24029 \SpecialChar ~
24030 \SpecialChar ~
24031 \SpecialChar ~
24032 case 11: ...\SpecialChar ~
24033 \SpecialChar ~
24034 \SpecialChar ~
24035 \SpecialChar ~
24036 \SpecialChar ~
24037 \SpecialChar ~
24038 \SpecialChar ~
24039 \SpecialChar ~
24040 \SpecialChar ~
24041 \SpecialChar ~
24042 \SpecialChar ~
24043 \SpecialChar ~
24044 \SpecialChar ~
24045 \SpecialChar ~
24046 \SpecialChar ~
24047 \SpecialChar ~
24048 \SpecialChar ~
24049 \SpecialChar ~
24050 \SpecialChar ~
24051 \SpecialChar ~
24052 \SpecialChar ~
24053 \SpecialChar ~
24054 \SpecialChar ~
24055 \SpecialChar ~
24056 \SpecialChar ~
24057 case 8: ...
24058
24059 \newline
24060 }\SpecialChar ~
24061 \SpecialChar ~
24062 \SpecialChar ~
24063 \SpecialChar ~
24064 \SpecialChar ~
24065 \SpecialChar ~
24066 \SpecialChar ~
24067 \SpecialChar ~
24068 \SpecialChar ~
24069 \SpecialChar ~
24070 \SpecialChar ~
24071 \SpecialChar ~
24072 \SpecialChar ~
24073 \SpecialChar ~
24074 \SpecialChar ~
24075 \SpecialChar ~
24076 \SpecialChar ~
24077 \SpecialChar ~
24078 \SpecialChar ~
24079 \SpecialChar ~
24080 \SpecialChar ~
24081 \SpecialChar ~
24082 \SpecialChar ~
24083 \SpecialChar ~
24084 \SpecialChar ~
24085 \SpecialChar ~
24086 \SpecialChar ~
24087 \SpecialChar ~
24088 \SpecialChar ~
24089 \SpecialChar ~
24090 \SpecialChar ~
24091 \SpecialChar ~
24092 \SpecialChar ~
24093 \SpecialChar ~
24094 \SpecialChar ~
24095 \SpecialChar ~
24096 }
24097 \layout Standard
24098
24099 Both the above switch statements will be implemented using a jump-table.
24100  The example to the right side is slightly more efficient as the check for
24101  the lower boundary of the jump-table is not needed.
24102 \end_deeper
24103 \layout Itemize
24104
24105 The number of case labels is not larger than supported by the target architectur
24106 e.
24107 \layout Itemize
24108
24109 If the case labels are not in numerical sequence ('gaps' between cases)
24110  SDCC checks whether a jump table with additionally inserted dummy cases
24111  is still attractive.
24112
24113 \layout Itemize
24114
24115 If the starting number is not zero and a check for the lower boundary of
24116  the jump-table can thus be eliminated SDCC might insert dummy cases 0,
24117  ...
24118  .
24119 \layout Standard
24120
24121 Switch statements which have large gaps in the numeric sequence or those
24122  that have too many case labels can be split into more than one switch statement
24123  for efficient code generation, e.g.:
24124 \layout Verse
24125
24126
24127 \family typewriter
24128 switch (i) {
24129 \newline
24130 \SpecialChar ~
24131 \SpecialChar ~
24132 case 1: ...
24133
24134 \newline
24135 \SpecialChar ~
24136 \SpecialChar ~
24137 case 2: ...
24138
24139 \newline
24140 \SpecialChar ~
24141 \SpecialChar ~
24142 case 3: ...
24143
24144 \newline
24145 \SpecialChar ~
24146 \SpecialChar ~
24147 case 4: ...
24148
24149 \newline
24150 \SpecialChar ~
24151 \SpecialChar ~
24152 case 5: ...
24153
24154 \newline
24155 \SpecialChar ~
24156 \SpecialChar ~
24157 case 6: ...
24158
24159 \newline
24160 \SpecialChar ~
24161 \SpecialChar ~
24162 case 7: ...
24163
24164 \newline
24165 \SpecialChar ~
24166 \SpecialChar ~
24167 case 101: ...
24168
24169 \newline
24170 \SpecialChar ~
24171 \SpecialChar ~
24172 case 102: ...
24173
24174 \newline
24175 \SpecialChar ~
24176 \SpecialChar ~
24177 case 103: ...
24178
24179 \newline
24180 \SpecialChar ~
24181 \SpecialChar ~
24182 case 104: ...
24183
24184 \newline
24185 \SpecialChar ~
24186 \SpecialChar ~
24187 case 105: ...
24188
24189 \newline
24190 \SpecialChar ~
24191 \SpecialChar ~
24192 case 106: ...
24193
24194 \newline
24195 \SpecialChar ~
24196 \SpecialChar ~
24197 case 107: ...
24198
24199 \newline
24200 }
24201 \layout Standard
24202
24203 If the above switch statement is broken down into two switch statements
24204 \layout Verse
24205
24206
24207 \family typewriter
24208 switch (i) {
24209 \newline
24210 \SpecialChar ~
24211 \SpecialChar ~
24212 case 1: ...
24213
24214 \newline
24215 \SpecialChar ~
24216 \SpecialChar ~
24217 case 2: ...
24218
24219 \newline
24220 \SpecialChar ~
24221 \SpecialChar ~
24222 case 3: ...
24223
24224 \newline
24225 \SpecialChar ~
24226 \SpecialChar ~
24227 case 4: ...
24228
24229 \newline
24230 \SpecialChar ~
24231 \SpecialChar ~
24232 case 5: ...
24233
24234 \newline
24235 \SpecialChar ~
24236 \SpecialChar ~
24237 case 6: ...
24238
24239 \newline
24240 \SpecialChar ~
24241 \SpecialChar ~
24242 case 7: ...
24243
24244 \newline
24245 }
24246 \layout Standard
24247
24248 and
24249 \layout Verse
24250
24251
24252 \family typewriter
24253 switch (i) {
24254 \newline
24255 \SpecialChar ~
24256 \SpecialChar ~
24257 case 101: ...
24258
24259 \newline
24260 \SpecialChar ~
24261 \SpecialChar ~
24262 case 102: ...
24263
24264 \newline
24265 \SpecialChar ~
24266 \SpecialChar ~
24267 case 103: ...
24268
24269 \newline
24270 \SpecialChar ~
24271 \SpecialChar ~
24272 case 104: ...
24273
24274 \newline
24275 \SpecialChar ~
24276 \SpecialChar ~
24277 case 105: ...
24278
24279 \newline
24280 \SpecialChar ~
24281 \SpecialChar ~
24282 case 106: ...
24283
24284 \newline
24285 \SpecialChar ~
24286 \SpecialChar ~
24287 case 107: ...
24288
24289 \newline
24290 }
24291 \layout Standard
24292
24293 then both the switch statements will be implemented using jump-tables whereas
24294  the unmodified switch statement will not be.
24295 \layout Comment
24296
24297 There might be reasons which SDCC cannot know about to either favour or
24298  not favour jump tables.
24299  If the target system has to be as quick for the last switch case as for
24300  the first (pro jump table), or if the switch argument is known to be zero
24301  in the majority of the cases (contra jump table).
24302 \layout Standard
24303
24304 The pragma nojtbound
24305 \begin_inset LatexCommand \index{\#pragma nojtbound}
24306
24307 \end_inset
24308
24309  can be used to turn off checking the
24310 \emph on
24311 j
24312 \emph default
24313 ump
24314 \emph on
24315 t
24316 \emph default
24317 able
24318 \emph on
24319 bound
24320 \emph default
24321 aries.
24322  It has no effect if a default label is supplied.
24323  Use of this pragma is dangerous: if the switch
24324 \begin_inset LatexCommand \index{switch statement}
24325
24326 \end_inset
24327
24328  argument is not matched by a case statement the processor will happily
24329  jump into Nirvana.
24330 \layout Subsection
24331
24332 Bit-shifting Operations
24333 \begin_inset LatexCommand \index{Bit shifting}
24334
24335 \end_inset
24336
24337 .
24338 \layout Standard
24339
24340 Bit shifting is one of the most frequently used operation in embedded programmin
24341 g.
24342  SDCC tries to implement bit-shift operations in the most efficient way
24343  possible, e.g.:
24344 \layout Verse
24345
24346
24347 \family typewriter
24348 unsigned char i;
24349 \newline
24350 ...
24351
24352 \newline
24353 i >>= 4;
24354 \newline
24355 ...
24356 \layout Standard
24357
24358 generates the following code:
24359 \layout Verse
24360
24361
24362 \family typewriter
24363 mov\SpecialChar ~
24364  a,_i
24365 \newline
24366 swap a
24367 \newline
24368 anl\SpecialChar ~
24369  a,#0x0f
24370 \newline
24371 mov\SpecialChar ~
24372  _i,a
24373 \layout Standard
24374
24375 In general SDCC will never setup a loop if the shift count is known.
24376  Another example:
24377 \layout Verse
24378
24379
24380 \family typewriter
24381 unsigned int i;
24382 \newline
24383 ...
24384
24385 \newline
24386 i >>= 9;
24387 \newline
24388 ...
24389 \layout Standard
24390
24391 will generate:
24392 \layout Verse
24393
24394
24395 \family typewriter
24396 mov\SpecialChar ~
24397 \SpecialChar ~
24398 a,(_i + 1)
24399 \newline
24400 mov\SpecialChar ~
24401 \SpecialChar ~
24402 (_i + 1),#0x00
24403 \newline
24404 clr\SpecialChar ~
24405 \SpecialChar ~
24406 c
24407 \newline
24408 rrc\SpecialChar ~
24409 \SpecialChar ~
24410 a
24411 \newline
24412 mov\SpecialChar ~
24413 \SpecialChar ~
24414 _i,a
24415 \layout Subsection
24416
24417 Bit-rotation
24418 \begin_inset LatexCommand \index{Bit rotation}
24419
24420 \end_inset
24421
24422
24423 \layout Standard
24424
24425 A special case of the bit-shift operation is bit rotation
24426 \begin_inset LatexCommand \index{rotating bits}
24427
24428 \end_inset
24429
24430 , SDCC recognizes the following expression to be a left bit-rotation:
24431 \layout Verse
24432
24433
24434 \family typewriter
24435 \series bold
24436 unsigned
24437 \series default
24438 \SpecialChar ~
24439 \SpecialChar ~
24440 char i;\SpecialChar ~
24441 \SpecialChar ~
24442 \SpecialChar ~
24443 \SpecialChar ~
24444 \SpecialChar ~
24445 \SpecialChar ~
24446 \SpecialChar ~
24447 \SpecialChar ~
24448 \SpecialChar ~
24449 \SpecialChar ~
24450 \SpecialChar ~
24451 /* unsigned is needed for rotation */
24452 \newline
24453 ...
24454
24455 \newline
24456 i = ((i << 1) | (i >> 7));
24457 \family default
24458
24459 \newline
24460
24461 \family typewriter
24462 ...
24463 \layout Standard
24464
24465 will generate the following code:
24466 \layout Verse
24467
24468
24469 \family typewriter
24470 mov\SpecialChar ~
24471 \SpecialChar ~
24472 a,_i
24473 \newline
24474 rl\SpecialChar ~
24475 \SpecialChar ~
24476 \SpecialChar ~
24477 a
24478 \newline
24479 mov\SpecialChar ~
24480 \SpecialChar ~
24481 _i,a
24482 \layout Standard
24483
24484 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
24485 ns of this case will also be recognized as bit-rotation, i.e.:
24486 \layout Verse
24487
24488
24489 \family typewriter
24490 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
24491 \layout Subsection
24492
24493 Nibble and Byte Swapping
24494 \layout Standard
24495
24496 Other special cases of the bit-shift operations are nibble or byte swapping
24497 \begin_inset LatexCommand \index{swapping nibbles/bytes}
24498
24499 \end_inset
24500
24501 , SDCC recognizes the following expressions:
24502 \layout Verse
24503
24504
24505 \family typewriter
24506 \series bold
24507 unsigned
24508 \series default
24509 \SpecialChar ~
24510 \SpecialChar ~
24511 char i;
24512 \newline
24513
24514 \series bold
24515 unsigned
24516 \series default
24517 \SpecialChar ~
24518 \SpecialChar ~
24519 int j;
24520 \newline
24521 ...
24522
24523 \newline
24524 i = ((i << 4) | (i >> 4));
24525 \family default
24526
24527 \newline
24528
24529 \family typewriter
24530 j = ((j << 8) | (j >> 8));
24531 \layout Standard
24532
24533 and generates a swap instruction for the nibble swapping
24534 \begin_inset LatexCommand \index{Nibble swapping}
24535
24536 \end_inset
24537
24538  or move instructions for the byte swapping
24539 \begin_inset LatexCommand \index{Byte swapping}
24540
24541 \end_inset
24542
24543 .
24544  The
24545 \begin_inset Quotes sld
24546 \end_inset
24547
24548 j
24549 \begin_inset Quotes srd
24550 \end_inset
24551
24552  example can be used to convert from little to big-endian or vice versa.
24553  If you want to change the endianness of a
24554 \emph on
24555 signed
24556 \emph default
24557  integer you have to cast to
24558 \family typewriter
24559 (unsigned int)
24560 \family default
24561  first.
24562 \layout Standard
24563
24564 Note that SDCC stores numbers in little-endian
24565 \begin_inset Foot
24566 collapsed false
24567
24568 \layout Standard
24569
24570 Usually 8-bit processors don't care much about endianness.
24571  This is not the case for the standard 8051 which only has an instruction
24572  to increment its
24573 \emph on
24574 dptr
24575 \emph default
24576
24577 \begin_inset LatexCommand \index{DPTR}
24578
24579 \end_inset
24580
24581 -datapointer
24582 \emph on
24583
24584 \emph default
24585 so little-endian is the more efficient byte order.
24586 \end_inset
24587
24588
24589 \begin_inset LatexCommand \index{little-endian}
24590
24591 \end_inset
24592
24593
24594 \begin_inset LatexCommand \index{Endianness}
24595
24596 \end_inset
24597
24598  format (i.e.
24599  lowest order first).
24600 \layout Subsection
24601
24602 Highest Order Bit
24603 \begin_inset LatexCommand \index{Highest Order Bit}
24604
24605 \end_inset
24606
24607  / Any Order Bit
24608 \begin_inset LatexCommand \index{Any Order Bit}
24609
24610 \end_inset
24611
24612
24613 \layout Standard
24614
24615 It is frequently required to obtain the highest order bit of an integral
24616  type (long, int, short or char types).
24617  Also obtaining any other order bit is not uncommon.
24618  SDCC recognizes the following expressions to yield the highest order bit
24619  and generates optimized code for it, e.g.:
24620 \layout Verse
24621
24622
24623 \family typewriter
24624 unsigned int gint;
24625 \newline
24626
24627 \newline
24628 foo () {
24629 \newline
24630 \SpecialChar ~
24631 \SpecialChar ~
24632 unsigned char hob1, aob1;
24633 \newline
24634 \SpecialChar ~
24635 \SpecialChar ~
24636 bit hob2, hob3, aob2, aob3;
24637 \newline
24638 \SpecialChar ~
24639 \SpecialChar ~
24640 ...
24641
24642 \newline
24643 \SpecialChar ~
24644 \SpecialChar ~
24645 hob1 = (gint >> 15) & 1;
24646 \newline
24647 \SpecialChar ~
24648 \SpecialChar ~
24649 hob2 = (gint >> 15) & 1;
24650 \newline
24651 \SpecialChar ~
24652 \SpecialChar ~
24653 hob3 = gint & 0x8000;
24654 \newline
24655 \SpecialChar ~
24656 \SpecialChar ~
24657 aob1 = (gint >> 9) & 1;
24658 \newline
24659 \SpecialChar ~
24660 \SpecialChar ~
24661 aob2 = (gint >> 8) & 1;
24662 \newline
24663 \SpecialChar ~
24664 \SpecialChar ~
24665 aob3 = gint & 0x0800;
24666 \newline
24667 \SpecialChar ~
24668 \SpecialChar ~
24669 ..
24670
24671 \newline
24672 }
24673 \layout Standard
24674
24675 will generate the following code:
24676 \layout Verse
24677
24678
24679 \family typewriter
24680 \SpecialChar ~
24681 \SpecialChar ~
24682 \SpecialChar ~
24683 \SpecialChar ~
24684 \SpecialChar ~
24685 \SpecialChar ~
24686 \SpecialChar ~
24687 \SpecialChar ~
24688 \SpecialChar ~
24689 \SpecialChar ~
24690 \SpecialChar ~
24691 \SpecialChar ~
24692 \SpecialChar ~
24693 \SpecialChar ~
24694 \SpecialChar ~
24695 \SpecialChar ~
24696 \SpecialChar ~
24697 \SpecialChar ~
24698 \SpecialChar ~
24699 \SpecialChar ~
24700 \SpecialChar ~
24701 \SpecialChar ~
24702 \SpecialChar ~
24703 \SpecialChar ~
24704 \SpecialChar ~
24705  61 ;\SpecialChar ~
24706  hob.c 7
24707 \newline
24708 000A E5*01\SpecialChar ~
24709 \SpecialChar ~
24710 \SpecialChar ~
24711 \SpecialChar ~
24712 \SpecialChar ~
24713 \SpecialChar ~
24714 \SpecialChar ~
24715 \SpecialChar ~
24716 \SpecialChar ~
24717 \SpecialChar ~
24718 \SpecialChar ~
24719 \SpecialChar ~
24720 \SpecialChar ~
24721 \SpecialChar ~
24722 \SpecialChar ~
24723  62\SpecialChar ~
24724 \SpecialChar ~
24725 \SpecialChar ~
24726 \SpecialChar ~
24727 \SpecialChar ~
24728 \SpecialChar ~
24729 \SpecialChar ~
24730 \SpecialChar ~
24731  mov\SpecialChar ~
24732 \SpecialChar ~
24733  a,(_gint + 1)
24734 \newline
24735 000C 23\SpecialChar ~
24736 \SpecialChar ~
24737 \SpecialChar ~
24738 \SpecialChar ~
24739 \SpecialChar ~
24740 \SpecialChar ~
24741 \SpecialChar ~
24742 \SpecialChar ~
24743 \SpecialChar ~
24744 \SpecialChar ~
24745 \SpecialChar ~
24746 \SpecialChar ~
24747 \SpecialChar ~
24748 \SpecialChar ~
24749 \SpecialChar ~
24750 \SpecialChar ~
24751 \SpecialChar ~
24752 \SpecialChar ~
24753  63\SpecialChar ~
24754 \SpecialChar ~
24755 \SpecialChar ~
24756 \SpecialChar ~
24757 \SpecialChar ~
24758 \SpecialChar ~
24759 \SpecialChar ~
24760 \SpecialChar ~
24761  rl\SpecialChar ~
24762 \SpecialChar ~
24763 \SpecialChar ~
24764  a
24765 \newline
24766 000D 54 01\SpecialChar ~
24767 \SpecialChar ~
24768 \SpecialChar ~
24769 \SpecialChar ~
24770 \SpecialChar ~
24771 \SpecialChar ~
24772 \SpecialChar ~
24773 \SpecialChar ~
24774 \SpecialChar ~
24775 \SpecialChar ~
24776 \SpecialChar ~
24777 \SpecialChar ~
24778 \SpecialChar ~
24779 \SpecialChar ~
24780 \SpecialChar ~
24781  64\SpecialChar ~
24782 \SpecialChar ~
24783 \SpecialChar ~
24784 \SpecialChar ~
24785 \SpecialChar ~
24786 \SpecialChar ~
24787 \SpecialChar ~
24788 \SpecialChar ~
24789  anl\SpecialChar ~
24790 \SpecialChar ~
24791  a,#0x01
24792 \newline
24793 000F F5*02\SpecialChar ~
24794 \SpecialChar ~
24795 \SpecialChar ~
24796 \SpecialChar ~
24797 \SpecialChar ~
24798 \SpecialChar ~
24799 \SpecialChar ~
24800 \SpecialChar ~
24801 \SpecialChar ~
24802 \SpecialChar ~
24803 \SpecialChar ~
24804 \SpecialChar ~
24805 \SpecialChar ~
24806 \SpecialChar ~
24807 \SpecialChar ~
24808  65\SpecialChar ~
24809 \SpecialChar ~
24810 \SpecialChar ~
24811 \SpecialChar ~
24812 \SpecialChar ~
24813 \SpecialChar ~
24814 \SpecialChar ~
24815 \SpecialChar ~
24816  mov\SpecialChar ~
24817 \SpecialChar ~
24818  _foo_hob1_1_1,a
24819 \newline
24820 \SpecialChar ~
24821 \SpecialChar ~
24822 \SpecialChar ~
24823 \SpecialChar ~
24824 \SpecialChar ~
24825 \SpecialChar ~
24826 \SpecialChar ~
24827 \SpecialChar ~
24828 \SpecialChar ~
24829 \SpecialChar ~
24830 \SpecialChar ~
24831 \SpecialChar ~
24832 \SpecialChar ~
24833 \SpecialChar ~
24834 \SpecialChar ~
24835 \SpecialChar ~
24836 \SpecialChar ~
24837 \SpecialChar ~
24838 \SpecialChar ~
24839 \SpecialChar ~
24840 \SpecialChar ~
24841 \SpecialChar ~
24842 \SpecialChar ~
24843 \SpecialChar ~
24844 \SpecialChar ~
24845  66 ;\SpecialChar ~
24846  hob.c 8
24847 \newline
24848 0011 E5*01\SpecialChar ~
24849 \SpecialChar ~
24850 \SpecialChar ~
24851 \SpecialChar ~
24852 \SpecialChar ~
24853 \SpecialChar ~
24854 \SpecialChar ~
24855 \SpecialChar ~
24856 \SpecialChar ~
24857 \SpecialChar ~
24858 \SpecialChar ~
24859 \SpecialChar ~
24860 \SpecialChar ~
24861 \SpecialChar ~
24862 \SpecialChar ~
24863  67\SpecialChar ~
24864 \SpecialChar ~
24865 \SpecialChar ~
24866 \SpecialChar ~
24867 \SpecialChar ~
24868 \SpecialChar ~
24869 \SpecialChar ~
24870 \SpecialChar ~
24871  mov\SpecialChar ~
24872 \SpecialChar ~
24873  a,(_gint + 1)
24874 \newline
24875 0013 33\SpecialChar ~
24876 \SpecialChar ~
24877 \SpecialChar ~
24878 \SpecialChar ~
24879 \SpecialChar ~
24880 \SpecialChar ~
24881 \SpecialChar ~
24882 \SpecialChar ~
24883 \SpecialChar ~
24884 \SpecialChar ~
24885 \SpecialChar ~
24886 \SpecialChar ~
24887 \SpecialChar ~
24888 \SpecialChar ~
24889 \SpecialChar ~
24890 \SpecialChar ~
24891 \SpecialChar ~
24892 \SpecialChar ~
24893  68\SpecialChar ~
24894 \SpecialChar ~
24895 \SpecialChar ~
24896 \SpecialChar ~
24897 \SpecialChar ~
24898 \SpecialChar ~
24899 \SpecialChar ~
24900 \SpecialChar ~
24901  rlc\SpecialChar ~
24902 \SpecialChar ~
24903  a
24904 \newline
24905 0014 92*00\SpecialChar ~
24906 \SpecialChar ~
24907 \SpecialChar ~
24908 \SpecialChar ~
24909 \SpecialChar ~
24910 \SpecialChar ~
24911 \SpecialChar ~
24912 \SpecialChar ~
24913 \SpecialChar ~
24914 \SpecialChar ~
24915 \SpecialChar ~
24916 \SpecialChar ~
24917 \SpecialChar ~
24918 \SpecialChar ~
24919 \SpecialChar ~
24920  69\SpecialChar ~
24921 \SpecialChar ~
24922 \SpecialChar ~
24923 \SpecialChar ~
24924 \SpecialChar ~
24925 \SpecialChar ~
24926 \SpecialChar ~
24927 \SpecialChar ~
24928  mov\SpecialChar ~
24929 \SpecialChar ~
24930  _foo_hob2_1_1,c
24931 \newline
24932 \SpecialChar ~
24933 \SpecialChar ~
24934 \SpecialChar ~
24935 \SpecialChar ~
24936 \SpecialChar ~
24937 \SpecialChar ~
24938 \SpecialChar ~
24939 \SpecialChar ~
24940 \SpecialChar ~
24941 \SpecialChar ~
24942 \SpecialChar ~
24943 \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  66 ;\SpecialChar ~
24958  hob.c 9
24959 \newline
24960 0016 E5*01\SpecialChar ~
24961 \SpecialChar ~
24962 \SpecialChar ~
24963 \SpecialChar ~
24964 \SpecialChar ~
24965 \SpecialChar ~
24966 \SpecialChar ~
24967 \SpecialChar ~
24968 \SpecialChar ~
24969 \SpecialChar ~
24970 \SpecialChar ~
24971 \SpecialChar ~
24972 \SpecialChar ~
24973 \SpecialChar ~
24974 \SpecialChar ~
24975  67\SpecialChar ~
24976 \SpecialChar ~
24977 \SpecialChar ~
24978 \SpecialChar ~
24979 \SpecialChar ~
24980 \SpecialChar ~
24981 \SpecialChar ~
24982 \SpecialChar ~
24983  mov\SpecialChar ~
24984 \SpecialChar ~
24985  a,(_gint + 1)
24986 \newline
24987 0018 33\SpecialChar ~
24988 \SpecialChar ~
24989 \SpecialChar ~
24990 \SpecialChar ~
24991 \SpecialChar ~
24992 \SpecialChar ~
24993 \SpecialChar ~
24994 \SpecialChar ~
24995 \SpecialChar ~
24996 \SpecialChar ~
24997 \SpecialChar ~
24998 \SpecialChar ~
24999 \SpecialChar ~
25000 \SpecialChar ~
25001 \SpecialChar ~
25002 \SpecialChar ~
25003 \SpecialChar ~
25004 \SpecialChar ~
25005  68\SpecialChar ~
25006 \SpecialChar ~
25007 \SpecialChar ~
25008 \SpecialChar ~
25009 \SpecialChar ~
25010 \SpecialChar ~
25011 \SpecialChar ~
25012 \SpecialChar ~
25013  rlc\SpecialChar ~
25014 \SpecialChar ~
25015  a
25016 \newline
25017 0019 92*01\SpecialChar ~
25018 \SpecialChar ~
25019 \SpecialChar ~
25020 \SpecialChar ~
25021 \SpecialChar ~
25022 \SpecialChar ~
25023 \SpecialChar ~
25024 \SpecialChar ~
25025 \SpecialChar ~
25026 \SpecialChar ~
25027 \SpecialChar ~
25028 \SpecialChar ~
25029 \SpecialChar ~
25030 \SpecialChar ~
25031 \SpecialChar ~
25032  69\SpecialChar ~
25033 \SpecialChar ~
25034 \SpecialChar ~
25035 \SpecialChar ~
25036 \SpecialChar ~
25037 \SpecialChar ~
25038 \SpecialChar ~
25039 \SpecialChar ~
25040  mov\SpecialChar ~
25041 \SpecialChar ~
25042  _foo_hob3_1_1,c
25043 \newline
25044 \SpecialChar ~
25045 \SpecialChar ~
25046 \SpecialChar ~
25047 \SpecialChar ~
25048 \SpecialChar ~
25049 \SpecialChar ~
25050 \SpecialChar ~
25051 \SpecialChar ~
25052 \SpecialChar ~
25053 \SpecialChar ~
25054 \SpecialChar ~
25055 \SpecialChar ~
25056 \SpecialChar ~
25057 \SpecialChar ~
25058 \SpecialChar ~
25059 \SpecialChar ~
25060 \SpecialChar ~
25061 \SpecialChar ~
25062 \SpecialChar ~
25063 \SpecialChar ~
25064 \SpecialChar ~
25065 \SpecialChar ~
25066 \SpecialChar ~
25067 \SpecialChar ~
25068 \SpecialChar ~
25069  70 ;\SpecialChar ~
25070  hob.c 10
25071 \newline
25072 001B E5*01\SpecialChar ~
25073 \SpecialChar ~
25074 \SpecialChar ~
25075 \SpecialChar ~
25076 \SpecialChar ~
25077 \SpecialChar ~
25078 \SpecialChar ~
25079 \SpecialChar ~
25080 \SpecialChar ~
25081 \SpecialChar ~
25082 \SpecialChar ~
25083 \SpecialChar ~
25084 \SpecialChar ~
25085 \SpecialChar ~
25086 \SpecialChar ~
25087  71\SpecialChar ~
25088 \SpecialChar ~
25089 \SpecialChar ~
25090 \SpecialChar ~
25091 \SpecialChar ~
25092 \SpecialChar ~
25093 \SpecialChar ~
25094 \SpecialChar ~
25095  mov\SpecialChar ~
25096 \SpecialChar ~
25097  a,(_gint + 1)
25098 \newline
25099 001D 03\SpecialChar ~
25100 \SpecialChar ~
25101 \SpecialChar ~
25102 \SpecialChar ~
25103 \SpecialChar ~
25104 \SpecialChar ~
25105 \SpecialChar ~
25106 \SpecialChar ~
25107 \SpecialChar ~
25108 \SpecialChar ~
25109 \SpecialChar ~
25110 \SpecialChar ~
25111 \SpecialChar ~
25112 \SpecialChar ~
25113 \SpecialChar ~
25114 \SpecialChar ~
25115 \SpecialChar ~
25116 \SpecialChar ~
25117  72\SpecialChar ~
25118 \SpecialChar ~
25119 \SpecialChar ~
25120 \SpecialChar ~
25121 \SpecialChar ~
25122 \SpecialChar ~
25123 \SpecialChar ~
25124 \SpecialChar ~
25125  rr\SpecialChar ~
25126 \SpecialChar ~
25127 \SpecialChar ~
25128  a
25129 \newline
25130 001E 54 01\SpecialChar ~
25131 \SpecialChar ~
25132 \SpecialChar ~
25133 \SpecialChar ~
25134 \SpecialChar ~
25135 \SpecialChar ~
25136 \SpecialChar ~
25137 \SpecialChar ~
25138 \SpecialChar ~
25139 \SpecialChar ~
25140 \SpecialChar ~
25141 \SpecialChar ~
25142 \SpecialChar ~
25143 \SpecialChar ~
25144 \SpecialChar ~
25145  73\SpecialChar ~
25146 \SpecialChar ~
25147 \SpecialChar ~
25148 \SpecialChar ~
25149 \SpecialChar ~
25150 \SpecialChar ~
25151 \SpecialChar ~
25152 \SpecialChar ~
25153  anl\SpecialChar ~
25154 \SpecialChar ~
25155  a,#0x01
25156 \newline
25157 0020 F5*03\SpecialChar ~
25158 \SpecialChar ~
25159 \SpecialChar ~
25160 \SpecialChar ~
25161 \SpecialChar ~
25162 \SpecialChar ~
25163 \SpecialChar ~
25164 \SpecialChar ~
25165 \SpecialChar ~
25166 \SpecialChar ~
25167 \SpecialChar ~
25168 \SpecialChar ~
25169 \SpecialChar ~
25170 \SpecialChar ~
25171 \SpecialChar ~
25172  74\SpecialChar ~
25173 \SpecialChar ~
25174 \SpecialChar ~
25175 \SpecialChar ~
25176 \SpecialChar ~
25177 \SpecialChar ~
25178 \SpecialChar ~
25179 \SpecialChar ~
25180  mov\SpecialChar ~
25181 \SpecialChar ~
25182  _foo_aob1_1_1,a
25183 \newline
25184 \SpecialChar ~
25185 \SpecialChar ~
25186 \SpecialChar ~
25187 \SpecialChar ~
25188 \SpecialChar ~
25189 \SpecialChar ~
25190 \SpecialChar ~
25191 \SpecialChar ~
25192 \SpecialChar ~
25193 \SpecialChar ~
25194 \SpecialChar ~
25195 \SpecialChar ~
25196 \SpecialChar ~
25197 \SpecialChar ~
25198 \SpecialChar ~
25199 \SpecialChar ~
25200 \SpecialChar ~
25201 \SpecialChar ~
25202 \SpecialChar ~
25203 \SpecialChar ~
25204 \SpecialChar ~
25205 \SpecialChar ~
25206 \SpecialChar ~
25207 \SpecialChar ~
25208 \SpecialChar ~
25209  75 ;\SpecialChar ~
25210  hob.c 11
25211 \newline
25212 0022 E5*01\SpecialChar ~
25213 \SpecialChar ~
25214 \SpecialChar ~
25215 \SpecialChar ~
25216 \SpecialChar ~
25217 \SpecialChar ~
25218 \SpecialChar ~
25219 \SpecialChar ~
25220 \SpecialChar ~
25221 \SpecialChar ~
25222 \SpecialChar ~
25223 \SpecialChar ~
25224 \SpecialChar ~
25225 \SpecialChar ~
25226 \SpecialChar ~
25227  76\SpecialChar ~
25228 \SpecialChar ~
25229 \SpecialChar ~
25230 \SpecialChar ~
25231 \SpecialChar ~
25232 \SpecialChar ~
25233 \SpecialChar ~
25234 \SpecialChar ~
25235  mov\SpecialChar ~
25236 \SpecialChar ~
25237  a,(_gint + 1)
25238 \newline
25239 0024 13\SpecialChar ~
25240 \SpecialChar ~
25241 \SpecialChar ~
25242 \SpecialChar ~
25243 \SpecialChar ~
25244 \SpecialChar ~
25245 \SpecialChar ~
25246 \SpecialChar ~
25247 \SpecialChar ~
25248 \SpecialChar ~
25249 \SpecialChar ~
25250 \SpecialChar ~
25251 \SpecialChar ~
25252 \SpecialChar ~
25253 \SpecialChar ~
25254 \SpecialChar ~
25255 \SpecialChar ~
25256 \SpecialChar ~
25257  77\SpecialChar ~
25258 \SpecialChar ~
25259 \SpecialChar ~
25260 \SpecialChar ~
25261 \SpecialChar ~
25262 \SpecialChar ~
25263 \SpecialChar ~
25264 \SpecialChar ~
25265  rrc\SpecialChar ~
25266 \SpecialChar ~
25267  a
25268 \newline
25269 0025 92*02\SpecialChar ~
25270 \SpecialChar ~
25271 \SpecialChar ~
25272 \SpecialChar ~
25273 \SpecialChar ~
25274 \SpecialChar ~
25275 \SpecialChar ~
25276 \SpecialChar ~
25277 \SpecialChar ~
25278 \SpecialChar ~
25279 \SpecialChar ~
25280 \SpecialChar ~
25281 \SpecialChar ~
25282 \SpecialChar ~
25283 \SpecialChar ~
25284  78\SpecialChar ~
25285 \SpecialChar ~
25286 \SpecialChar ~
25287 \SpecialChar ~
25288 \SpecialChar ~
25289 \SpecialChar ~
25290 \SpecialChar ~
25291 \SpecialChar ~
25292  mov\SpecialChar ~
25293 \SpecialChar ~
25294  _foo_aob2_1_1,c
25295 \newline
25296 \SpecialChar ~
25297 \SpecialChar ~
25298 \SpecialChar ~
25299 \SpecialChar ~
25300 \SpecialChar ~
25301 \SpecialChar ~
25302 \SpecialChar ~
25303 \SpecialChar ~
25304 \SpecialChar ~
25305 \SpecialChar ~
25306 \SpecialChar ~
25307 \SpecialChar ~
25308 \SpecialChar ~
25309 \SpecialChar ~
25310 \SpecialChar ~
25311 \SpecialChar ~
25312 \SpecialChar ~
25313 \SpecialChar ~
25314 \SpecialChar ~
25315 \SpecialChar ~
25316 \SpecialChar ~
25317 \SpecialChar ~
25318 \SpecialChar ~
25319 \SpecialChar ~
25320 \SpecialChar ~
25321  79 ;\SpecialChar ~
25322  hob.c 12
25323 \newline
25324 0027 E5*01\SpecialChar ~
25325 \SpecialChar ~
25326 \SpecialChar ~
25327 \SpecialChar ~
25328 \SpecialChar ~
25329 \SpecialChar ~
25330 \SpecialChar ~
25331 \SpecialChar ~
25332 \SpecialChar ~
25333 \SpecialChar ~
25334 \SpecialChar ~
25335 \SpecialChar ~
25336 \SpecialChar ~
25337 \SpecialChar ~
25338 \SpecialChar ~
25339  80\SpecialChar ~
25340 \SpecialChar ~
25341 \SpecialChar ~
25342 \SpecialChar ~
25343 \SpecialChar ~
25344 \SpecialChar ~
25345 \SpecialChar ~
25346 \SpecialChar ~
25347  mov\SpecialChar ~
25348 \SpecialChar ~
25349  a,(_gint + 1)
25350 \newline
25351 0029 A2 E3\SpecialChar ~
25352 \SpecialChar ~
25353 \SpecialChar ~
25354 \SpecialChar ~
25355 \SpecialChar ~
25356 \SpecialChar ~
25357 \SpecialChar ~
25358 \SpecialChar ~
25359 \SpecialChar ~
25360 \SpecialChar ~
25361 \SpecialChar ~
25362 \SpecialChar ~
25363 \SpecialChar ~
25364 \SpecialChar ~
25365 \SpecialChar ~
25366  81\SpecialChar ~
25367 \SpecialChar ~
25368 \SpecialChar ~
25369 \SpecialChar ~
25370 \SpecialChar ~
25371 \SpecialChar ~
25372 \SpecialChar ~
25373 \SpecialChar ~
25374  mov\SpecialChar ~
25375 \SpecialChar ~
25376  c,acc[3]
25377 \newline
25378 002B 92*03\SpecialChar ~
25379 \SpecialChar ~
25380 \SpecialChar ~
25381 \SpecialChar ~
25382 \SpecialChar ~
25383 \SpecialChar ~
25384 \SpecialChar ~
25385 \SpecialChar ~
25386 \SpecialChar ~
25387 \SpecialChar ~
25388 \SpecialChar ~
25389 \SpecialChar ~
25390 \SpecialChar ~
25391 \SpecialChar ~
25392 \SpecialChar ~
25393  82\SpecialChar ~
25394 \SpecialChar ~
25395 \SpecialChar ~
25396 \SpecialChar ~
25397 \SpecialChar ~
25398 \SpecialChar ~
25399 \SpecialChar ~
25400 \SpecialChar ~
25401  mov\SpecialChar ~
25402 \SpecialChar ~
25403  _foo_aob3_1_1,c
25404 \layout Standard
25405
25406 Other variations of these cases however will
25407 \emph on
25408 not
25409 \emph default
25410  be recognized.
25411  They are standard C expressions, so I heartily recommend these be the only
25412  way to get the highest order bit, (it is portable).
25413  Of course it will be recognized even if it is embedded in other expressions,
25414  e.g.:
25415 \layout Verse
25416
25417
25418 \family typewriter
25419 xyz = gint + ((gint >> 15) & 1);
25420 \layout Standard
25421
25422 will still be recognized.
25423 \layout Subsection
25424
25425 Higher Order Byte
25426 \begin_inset LatexCommand \index{Higher Order Byte}
25427
25428 \end_inset
25429
25430  / Higher Order Word
25431 \begin_inset LatexCommand \index{Higher Order Word}
25432
25433 \end_inset
25434
25435
25436 \layout Standard
25437
25438 It is also frequently required to obtain a higher order byte or word of
25439  a larger integral type (long, int or short types).
25440  SDCC recognizes the following expressions to yield the higher order byte
25441  or word and generates optimized code for it, e.g.:
25442 \layout Verse
25443
25444
25445 \family typewriter
25446 unsigned int gint;
25447 \newline
25448 unsigned long int glong;
25449 \newline
25450
25451 \newline
25452 foo () {
25453 \newline
25454 \SpecialChar ~
25455 \SpecialChar ~
25456 unsigned char hob1, hob2;
25457 \newline
25458 \SpecialChar ~
25459 \SpecialChar ~
25460 unsigned int how1, how2;
25461 \newline
25462 \SpecialChar ~
25463 \SpecialChar ~
25464 ...
25465
25466 \newline
25467 \SpecialChar ~
25468 \SpecialChar ~
25469 hob1 = (gint >> 8) & 0xFF;
25470 \newline
25471 \SpecialChar ~
25472 \SpecialChar ~
25473 hob2 = glong >> 24;
25474 \newline
25475 \SpecialChar ~
25476 \SpecialChar ~
25477 how1 = (glong >> 16) & 0xFFFF;
25478 \newline
25479 \SpecialChar ~
25480 \SpecialChar ~
25481 how2 = glong >> 8;
25482 \newline
25483 \SpecialChar ~
25484 \SpecialChar ~
25485 ..
25486
25487 \newline
25488 }
25489 \layout Standard
25490
25491 will generate the following code:
25492 \layout Verse
25493
25494
25495 \family typewriter
25496 \SpecialChar ~
25497 \SpecialChar ~
25498 \SpecialChar ~
25499 \SpecialChar ~
25500 \SpecialChar ~
25501 \SpecialChar ~
25502 \SpecialChar ~
25503 \SpecialChar ~
25504 \SpecialChar ~
25505 \SpecialChar ~
25506 \SpecialChar ~
25507 \SpecialChar ~
25508 \SpecialChar ~
25509 \SpecialChar ~
25510 \SpecialChar ~
25511 \SpecialChar ~
25512 \SpecialChar ~
25513 \SpecialChar ~
25514 \SpecialChar ~
25515 \SpecialChar ~
25516 \SpecialChar ~
25517 \SpecialChar ~
25518 \SpecialChar ~
25519 \SpecialChar ~
25520 \SpecialChar ~
25521  91 ;\SpecialChar ~
25522  hob.c 15
25523 \newline
25524 0037 85*01*06\SpecialChar ~
25525 \SpecialChar ~
25526 \SpecialChar ~
25527 \SpecialChar ~
25528 \SpecialChar ~
25529 \SpecialChar ~
25530 \SpecialChar ~
25531 \SpecialChar ~
25532 \SpecialChar ~
25533 \SpecialChar ~
25534 \SpecialChar ~
25535 \SpecialChar ~
25536  92\SpecialChar ~
25537 \SpecialChar ~
25538 \SpecialChar ~
25539 \SpecialChar ~
25540 \SpecialChar ~
25541 \SpecialChar ~
25542 \SpecialChar ~
25543 \SpecialChar ~
25544  mov\SpecialChar ~
25545 \SpecialChar ~
25546  _foo_hob1_1_1,(_gint + 1)
25547 \newline
25548 \SpecialChar ~
25549 \SpecialChar ~
25550 \SpecialChar ~
25551 \SpecialChar ~
25552 \SpecialChar ~
25553 \SpecialChar ~
25554 \SpecialChar ~
25555 \SpecialChar ~
25556 \SpecialChar ~
25557 \SpecialChar ~
25558 \SpecialChar ~
25559 \SpecialChar ~
25560 \SpecialChar ~
25561 \SpecialChar ~
25562 \SpecialChar ~
25563 \SpecialChar ~
25564 \SpecialChar ~
25565 \SpecialChar ~
25566 \SpecialChar ~
25567 \SpecialChar ~
25568 \SpecialChar ~
25569 \SpecialChar ~
25570 \SpecialChar ~
25571 \SpecialChar ~
25572 \SpecialChar ~
25573  93 ;\SpecialChar ~
25574  hob.c 16
25575 \newline
25576 003A 85*05*07\SpecialChar ~
25577 \SpecialChar ~
25578 \SpecialChar ~
25579 \SpecialChar ~
25580 \SpecialChar ~
25581 \SpecialChar ~
25582 \SpecialChar ~
25583 \SpecialChar ~
25584 \SpecialChar ~
25585 \SpecialChar ~
25586 \SpecialChar ~
25587 \SpecialChar ~
25588  94\SpecialChar ~
25589 \SpecialChar ~
25590 \SpecialChar ~
25591 \SpecialChar ~
25592 \SpecialChar ~
25593 \SpecialChar ~
25594 \SpecialChar ~
25595 \SpecialChar ~
25596  mov\SpecialChar ~
25597 \SpecialChar ~
25598  _foo_hob2_1_1,(_glong + 3)
25599 \newline
25600 \SpecialChar ~
25601 \SpecialChar ~
25602 \SpecialChar ~
25603 \SpecialChar ~
25604 \SpecialChar ~
25605 \SpecialChar ~
25606 \SpecialChar ~
25607 \SpecialChar ~
25608 \SpecialChar ~
25609 \SpecialChar ~
25610 \SpecialChar ~
25611 \SpecialChar ~
25612 \SpecialChar ~
25613 \SpecialChar ~
25614 \SpecialChar ~
25615 \SpecialChar ~
25616 \SpecialChar ~
25617 \SpecialChar ~
25618 \SpecialChar ~
25619 \SpecialChar ~
25620 \SpecialChar ~
25621 \SpecialChar ~
25622 \SpecialChar ~
25623 \SpecialChar ~
25624 \SpecialChar ~
25625  95 ;\SpecialChar ~
25626  hob.c 17
25627 \newline
25628 003D 85*04*08\SpecialChar ~
25629 \SpecialChar ~
25630 \SpecialChar ~
25631 \SpecialChar ~
25632 \SpecialChar ~
25633 \SpecialChar ~
25634 \SpecialChar ~
25635 \SpecialChar ~
25636 \SpecialChar ~
25637 \SpecialChar ~
25638 \SpecialChar ~
25639 \SpecialChar ~
25640  96\SpecialChar ~
25641 \SpecialChar ~
25642 \SpecialChar ~
25643 \SpecialChar ~
25644 \SpecialChar ~
25645 \SpecialChar ~
25646 \SpecialChar ~
25647 \SpecialChar ~
25648  mov\SpecialChar ~
25649 \SpecialChar ~
25650  _foo_how1_1_1,(_glong + 2)
25651 \newline
25652 0040 85*05*09\SpecialChar ~
25653 \SpecialChar ~
25654 \SpecialChar ~
25655 \SpecialChar ~
25656 \SpecialChar ~
25657 \SpecialChar ~
25658 \SpecialChar ~
25659 \SpecialChar ~
25660 \SpecialChar ~
25661 \SpecialChar ~
25662 \SpecialChar ~
25663 \SpecialChar ~
25664  97\SpecialChar ~
25665 \SpecialChar ~
25666 \SpecialChar ~
25667 \SpecialChar ~
25668 \SpecialChar ~
25669 \SpecialChar ~
25670 \SpecialChar ~
25671 \SpecialChar ~
25672  mov\SpecialChar ~
25673 \SpecialChar ~
25674  (_foo_how1_1_1 + 1),(_glong + 3)
25675 \newline
25676 0043 85*03*0A\SpecialChar ~
25677 \SpecialChar ~
25678 \SpecialChar ~
25679 \SpecialChar ~
25680 \SpecialChar ~
25681 \SpecialChar ~
25682 \SpecialChar ~
25683 \SpecialChar ~
25684 \SpecialChar ~
25685 \SpecialChar ~
25686 \SpecialChar ~
25687 \SpecialChar ~
25688  98\SpecialChar ~
25689 \SpecialChar ~
25690 \SpecialChar ~
25691 \SpecialChar ~
25692 \SpecialChar ~
25693 \SpecialChar ~
25694 \SpecialChar ~
25695 \SpecialChar ~
25696  mov\SpecialChar ~
25697 \SpecialChar ~
25698  _foo_how2_1_1,(_glong + 1)
25699 \newline
25700 0046 85*04*0B\SpecialChar ~
25701 \SpecialChar ~
25702 \SpecialChar ~
25703 \SpecialChar ~
25704 \SpecialChar ~
25705 \SpecialChar ~
25706 \SpecialChar ~
25707 \SpecialChar ~
25708 \SpecialChar ~
25709 \SpecialChar ~
25710 \SpecialChar ~
25711 \SpecialChar ~
25712  99\SpecialChar ~
25713 \SpecialChar ~
25714 \SpecialChar ~
25715 \SpecialChar ~
25716 \SpecialChar ~
25717 \SpecialChar ~
25718 \SpecialChar ~
25719 \SpecialChar ~
25720  mov\SpecialChar ~
25721 \SpecialChar ~
25722  (_foo_how2_1_1 + 1),(_glong + 2)
25723 \layout Standard
25724
25725 Again, variations of these cases may
25726 \emph on
25727 not
25728 \emph default
25729  be recognized.
25730  They are standard C expressions, so I heartily recommend these be the only
25731  way to get the highest order bit, (it is portable).
25732  Of course it will be recognized even if it is embedded in other expressions,
25733  e.g.:
25734 \layout Verse
25735
25736
25737 \family typewriter
25738 xyz = gint + ((gint >> 8) & 0xFF);
25739 \layout Standard
25740
25741 will still be recognized.
25742 \layout Subsection
25743
25744 Peephole Optimizer
25745 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
25746
25747 \end_inset
25748
25749
25750 \begin_inset LatexCommand \index{Peephole optimizer}
25751
25752 \end_inset
25753
25754
25755 \layout Standard
25756
25757 The compiler uses a rule based, pattern matching and re-writing mechanism
25758  for peep-hole optimization.
25759  It is inspired by
25760 \emph on
25761 copt
25762 \emph default
25763  a peep-hole optimizer by Christopher W.
25764  Fraser (cwfraser\SpecialChar ~
25765 @\SpecialChar ~
25766 microsoft.com).
25767  A default set of rules are compiled into the compiler, additional rules
25768  may be added with the
25769 \emph on
25770 -
25771 \begin_inset ERT
25772 status Collapsed
25773
25774 \layout Standard
25775
25776 \backslash
25777 /
25778 \end_inset
25779
25780 -peep-file
25781 \begin_inset LatexCommand \index{-\/-peep-file}
25782
25783 \end_inset
25784
25785  <filename>
25786 \emph default
25787  option.
25788  The rule language is best illustrated with examples.
25789 \layout Verse
25790
25791
25792 \family typewriter
25793 replace {
25794 \newline
25795 \SpecialChar ~
25796 \SpecialChar ~
25797 mov %1,a
25798 \newline
25799 \SpecialChar ~
25800 \SpecialChar ~
25801 mov a,%1
25802 \newline
25803 } by {
25804 \newline
25805 \SpecialChar ~
25806 \SpecialChar ~
25807 mov %1,a
25808 \newline
25809 }
25810 \layout Standard
25811
25812 The above rule will change the following assembly
25813 \begin_inset LatexCommand \index{Assembler routines}
25814
25815 \end_inset
25816
25817  sequence:
25818 \layout Verse
25819
25820
25821 \family typewriter
25822 mov r1,a
25823 \newline
25824 mov a,r1
25825 \layout Standard
25826
25827 to
25828 \layout Verse
25829
25830
25831 \family typewriter
25832 mov r1,a
25833 \layout Standard
25834
25835 Note: All occurrences of a
25836 \emph on
25837 %n
25838 \emph default
25839  (pattern variable) must denote the same string.
25840  With the above rule, the assembly sequence:
25841 \layout Verse
25842
25843
25844 \family typewriter
25845 mov r1,a
25846 \newline
25847 mov a,r2
25848 \layout Standard
25849
25850 will remain unmodified.
25851 \newline
25852
25853 \newline
25854 Other special case optimizations may be added by the user (via
25855 \emph on
25856 -
25857 \begin_inset ERT
25858 status Collapsed
25859
25860 \layout Standard
25861
25862 \backslash
25863 /
25864 \end_inset
25865
25866 -peep-file option
25867 \emph default
25868 ).
25869  E.g.
25870  some variants of the 8051 MCU
25871 \begin_inset LatexCommand \index{MCS51 variants}
25872
25873 \end_inset
25874
25875  allow only
25876 \family typewriter
25877 ajmp
25878 \family default
25879  and
25880 \family typewriter
25881 acall
25882 \family default
25883 .
25884  The following two rules will change all
25885 \family typewriter
25886 ljmp
25887 \family default
25888  and
25889 \family typewriter
25890 lcall
25891 \family default
25892  to
25893 \family typewriter
25894 ajmp
25895 \family default
25896  and
25897 \family typewriter
25898 acall
25899 \layout Verse
25900
25901
25902 \family typewriter
25903 replace { lcall %1 } by { acall %1 }
25904 \newline
25905 replace { ljmp %1 } by { ajmp %1 }
25906 \layout Standard
25907
25908 The
25909 \emph on
25910 inline-assembler code
25911 \emph default
25912  is also passed through the peep hole optimizer, thus the peephole optimizer
25913  can also be used as an assembly level macro expander.
25914  The rules themselves are MCU dependent whereas the rule language infra-structur
25915 e is MCU independent.
25916  Peephole optimization rules for other MCU can be easily programmed using
25917  the rule language.
25918 \newline
25919
25920 \newline
25921 The syntax for a rule is as follows:
25922 \layout Verse
25923
25924
25925 \family typewriter
25926 rule := replace [ restart ] '{' <assembly sequence> '
25927 \backslash
25928 n'
25929 \newline
25930 \SpecialChar ~
25931  \SpecialChar ~
25932  \SpecialChar ~
25933  \SpecialChar ~
25934  \SpecialChar ~
25935  \SpecialChar ~
25936  \SpecialChar ~
25937  \SpecialChar ~
25938  \SpecialChar ~
25939  \SpecialChar ~
25940  \SpecialChar ~
25941  \SpecialChar ~
25942  \SpecialChar ~
25943  \SpecialChar ~
25944  '}' by '{' '
25945 \backslash
25946 n'
25947 \newline
25948 \SpecialChar ~
25949  \SpecialChar ~
25950  \SpecialChar ~
25951  \SpecialChar ~
25952  \SpecialChar ~
25953  \SpecialChar ~
25954  \SpecialChar ~
25955  \SpecialChar ~
25956  \SpecialChar ~
25957  \SpecialChar ~
25958  \SpecialChar ~
25959  \SpecialChar ~
25960  \SpecialChar ~
25961  \SpecialChar ~
25962  \SpecialChar ~
25963  \SpecialChar ~
25964  <assembly sequence> '
25965 \backslash
25966 n'
25967 \newline
25968 \SpecialChar ~
25969  \SpecialChar ~
25970  \SpecialChar ~
25971  \SpecialChar ~
25972  \SpecialChar ~
25973  \SpecialChar ~
25974  \SpecialChar ~
25975  \SpecialChar ~
25976  \SpecialChar ~
25977  \SpecialChar ~
25978  \SpecialChar ~
25979  \SpecialChar ~
25980  \SpecialChar ~
25981  \SpecialChar ~
25982  '}' [if <functionName> ] '
25983 \backslash
25984 n'
25985 \layout Standard
25986
25987 <assembly sequence> := assembly instruction (each instruction including
25988  labels must be on a separate line).
25989 \newline
25990
25991 \newline
25992 The optimizer will apply to the rules one by one from the top in the sequence
25993  of their appearance, it will terminate when all rules are exhausted.
25994  If the 'restart' option is specified, then the optimizer will start matching
25995  the rules again from the top, this option for a rule is expensive (performance)
25996 , it is intended to be used in situations where a transformation will trigger
25997  the same rule again.
25998  An example of this (not a good one, it has side effects) is the following
25999  rule:
26000 \layout Verse
26001
26002
26003 \family typewriter
26004 replace restart {
26005 \newline
26006 \SpecialChar ~
26007 \SpecialChar ~
26008 pop %1
26009 \newline
26010 \SpecialChar ~
26011 \SpecialChar ~
26012 push %1 } by {
26013 \newline
26014 \SpecialChar ~
26015 \SpecialChar ~
26016 ; nop
26017 \newline
26018 }
26019 \layout Standard
26020
26021 Note that the replace pattern cannot be a blank, but can be a comment line.
26022  Without the 'restart' option only the innermost 'pop' 'push' pair would
26023  be eliminated, i.e.:
26024 \layout Verse
26025
26026
26027 \family typewriter
26028 pop ar1
26029 \newline
26030 pop ar2
26031 \newline
26032 push ar2
26033 \newline
26034 push ar1
26035 \layout Standard
26036
26037 would result in:
26038 \layout Verse
26039
26040
26041 \family typewriter
26042 pop ar1
26043 \newline
26044 ; nop
26045 \newline
26046 push ar1
26047 \layout Standard
26048
26049
26050 \emph on
26051 with
26052 \emph default
26053  the restart option the rule will be applied again to the resulting code
26054  and then all the pop-push pairs will be eliminated to yield:
26055 \layout Verse
26056
26057
26058 \family typewriter
26059 ; nop
26060 \newline
26061 ; nop
26062 \layout Standard
26063
26064 A conditional function can be attached to a rule.
26065  Attaching rules are somewhat more involved, let me illustrate this with
26066  an example.
26067 \layout Verse
26068
26069
26070 \family typewriter
26071 replace {
26072 \newline
26073 \SpecialChar ~
26074  \SpecialChar ~
26075  \SpecialChar ~
26076 ljmp %5
26077 \newline
26078 %2:
26079 \newline
26080 } by {
26081 \newline
26082 \SpecialChar ~
26083  \SpecialChar ~
26084  \SpecialChar ~
26085 sjmp %5
26086 \newline
26087 %2:
26088 \newline
26089 } if labelInRange
26090 \layout Standard
26091
26092 The optimizer does a look-up of a function name table defined in function
26093
26094 \emph on
26095 callFuncByName
26096 \emph default
26097  in the source file SDCCpeeph.c, with the name
26098 \emph on
26099 labelInRange
26100 \emph default
26101 .
26102  If it finds a corresponding entry the function is called.
26103  Note there can be no parameters specified for these functions, in this
26104  case the use of
26105 \emph on
26106 %5
26107 \emph default
26108  is crucial, since the function
26109 \emph on
26110 labelInRange
26111 \emph default
26112  expects to find the label in that particular variable (the hash table containin
26113 g the variable bindings is passed as a parameter).
26114  If you want to code more such functions, take a close look at the function
26115  labelInRange and the calling mechanism in source file SDCCpeeph.c.
26116  Currently implemented are
26117 \emph on
26118 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
26119  24bitMode, portIsDS390, 24bitModeAndPortDS390
26120 \emph default
26121 and
26122 \emph on
26123  notVolatile
26124 \emph default
26125 .
26126 \layout Standard
26127
26128 I know this whole thing is a little kludgey, but maybe some day we will
26129  have some better means.
26130  If you are looking at this file, you will see the default rules that are
26131  compiled into the compiler, you can add your own rules in the default set
26132  there if you get tired of specifying the -
26133 \begin_inset ERT
26134 status Collapsed
26135
26136 \layout Standard
26137
26138 \backslash
26139 /
26140 \end_inset
26141
26142 -peep-file option.
26143 \layout Section
26144
26145 ANSI-Compliance
26146 \begin_inset LatexCommand \index{ANSI-compliance}
26147
26148 \end_inset
26149
26150
26151 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
26152
26153 \end_inset
26154
26155
26156 \layout Standard
26157
26158 Deviations from the compliance:
26159 \layout Itemize
26160
26161 functions are not reentrant
26162 \begin_inset LatexCommand \index{reentrant}
26163
26164 \end_inset
26165
26166  unless explicitly declared as such or the
26167 \series bold
26168 -
26169 \begin_inset ERT
26170 status Collapsed
26171
26172 \layout Standard
26173
26174 \backslash
26175 /
26176 \end_inset
26177
26178 -stack-auto
26179 \begin_inset LatexCommand \index{-\/-stack-auto}
26180
26181 \end_inset
26182
26183
26184 \series default
26185  command line option is specified.
26186 \layout Itemize
26187
26188 structures and unions cannot be assigned values directly, cannot be passed
26189  as function parameters or assigned to each other and cannot be a return
26190  value from a function, e.g.:
26191 \begin_deeper
26192 \layout Verse
26193
26194
26195 \family typewriter
26196 struct s { ...
26197  };
26198 \newline
26199 struct s s1, s2;
26200 \newline
26201 foo()
26202 \newline
26203 {
26204 \newline
26205 \SpecialChar ~
26206 \SpecialChar ~
26207 \SpecialChar ~
26208 \SpecialChar ~
26209 ...
26210
26211 \newline
26212 \SpecialChar ~
26213 \SpecialChar ~
26214 \SpecialChar ~
26215 \SpecialChar ~
26216 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
26217 \newline
26218 \SpecialChar ~
26219 \SpecialChar ~
26220 \SpecialChar ~
26221 \SpecialChar ~
26222 ...
26223
26224 \newline
26225 }
26226 \newline
26227 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
26228  */
26229 \newline
26230 {
26231 \newline
26232 \SpecialChar ~
26233 \SpecialChar ~
26234 \SpecialChar ~
26235 \SpecialChar ~
26236 struct s rets;
26237 \newline
26238 \SpecialChar ~
26239 \SpecialChar ~
26240 \SpecialChar ~
26241 \SpecialChar ~
26242 ...
26243
26244 \newline
26245 \SpecialChar ~
26246 \SpecialChar ~
26247 \SpecialChar ~
26248 \SpecialChar ~
26249 return rets;/* is invalid in SDCC although allowed in ANSI */
26250 \newline
26251 }
26252 \end_deeper
26253 \layout Itemize
26254
26255 'long long
26256 \begin_inset LatexCommand \index{long long (not supported)}
26257
26258 \end_inset
26259
26260 ' (64 bit integers
26261 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
26262
26263 \end_inset
26264
26265 ) not supported.
26266 \layout Itemize
26267
26268 'double
26269 \begin_inset LatexCommand \index{double (not supported)}
26270
26271 \end_inset
26272
26273 ' precision floating point
26274 \begin_inset LatexCommand \index{Floating point support}
26275
26276 \end_inset
26277
26278 not supported.
26279 \layout Itemize
26280
26281 No support for setjmp
26282 \begin_inset LatexCommand \index{setjmp (not supported)}
26283
26284 \end_inset
26285
26286  and longjmp
26287 \begin_inset LatexCommand \index{longjmp (not supported)}
26288
26289 \end_inset
26290
26291  (for now).
26292 \layout Itemize
26293
26294 Old K&R style
26295 \begin_inset LatexCommand \index{K\&R style}
26296
26297 \end_inset
26298
26299  function declarations are NOT allowed.
26300 \begin_deeper
26301 \layout Verse
26302
26303
26304 \family typewriter
26305 foo(i,j) /* this old style of function declarations */
26306 \newline
26307 int i,j; /* are valid in ANSI but not valid in SDCC */
26308 \newline
26309 {
26310 \newline
26311 \SpecialChar ~
26312 \SpecialChar ~
26313 \SpecialChar ~
26314 \SpecialChar ~
26315 ...
26316
26317 \newline
26318 }
26319 \end_deeper
26320 \layout Itemize
26321
26322 Certain words that are valid identifiers in the standard may be reserved
26323  words in SDCC unless the
26324 \series bold
26325 -
26326 \begin_inset ERT
26327 status Collapsed
26328
26329 \layout Standard
26330
26331 \backslash
26332 /
26333 \end_inset
26334
26335 -std-c89
26336 \begin_inset LatexCommand \index{-\/-std-c89}
26337
26338 \end_inset
26339
26340  or -
26341 \begin_inset ERT
26342 status Collapsed
26343
26344 \layout Standard
26345
26346 \backslash
26347 /
26348 \end_inset
26349
26350 -std-c99
26351 \begin_inset LatexCommand \index{-\/-std-c99}
26352
26353 \end_inset
26354
26355
26356 \series default
26357  command line options are used.
26358  These may include (depending on the selected processor): 'at', 'banked',
26359  'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup
26360 t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs',
26361  'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and
26362  '_naked'.
26363  Compliant equivalents of these keywords are always available in a form
26364  that begin with two underscores
26365 \begin_inset LatexCommand \index{\_\_ (prefix for extended keywords)}
26366
26367 \end_inset
26368
26369 , f.e.
26370  '__data' instead of 'data'.
26371 \layout Section
26372
26373 Cyclomatic Complexity
26374 \begin_inset LatexCommand \index{Cyclomatic complexity}
26375
26376 \end_inset
26377
26378
26379 \layout Standard
26380
26381 Cyclomatic complexity of a function is defined as the number of independent
26382  paths the program can take during execution of the function.
26383  This is an important number since it defines the number test cases you
26384  have to generate to validate the function.
26385  The accepted industry standard for complexity number is 10, if the cyclomatic
26386  complexity reported by SDCC exceeds 10 you should think about simplification
26387  of the function logic.
26388  Note that the complexity level is not related to the number of lines of
26389  code in a function.
26390  Large functions can have low complexity, and small functions can have large
26391  complexity levels.
26392
26393 \newline
26394
26395 \newline
26396 SDCC uses the following formula to compute the complexity:
26397 \newline
26398
26399 \layout Standard
26400
26401 complexity = (number of edges in control flow graph) - (number of nodes
26402  in control flow graph) + 2;
26403 \newline
26404
26405 \newline
26406 Having said that the industry standard is 10, you should be aware that in
26407  some cases it be may unavoidable to have a complexity level of less than
26408  10.
26409  For example if you have switch statement with more than 10 case labels,
26410  each case label adds one to the complexity level.
26411  The complexity level is by no means an absolute measure of the algorithmic
26412  complexity of the function, it does however provide a good starting point
26413  for which functions you might look at for further optimization.
26414 \layout Section
26415
26416 Retargetting for other Processors
26417 \layout Standard
26418
26419 The issues for retargetting the compiler are far too numerous to be covered
26420  by this document.
26421  What follows is a brief description of each of the seven phases of the
26422  compiler and its MCU dependency.
26423 \layout Itemize
26424
26425 Parsing the source and building the annotated parse tree.
26426  This phase is largely MCU independent (except for the language extensions).
26427  Syntax & semantic checks are also done in this phase, along with some initial
26428  optimizations like back patching labels and the pattern matching optimizations
26429  like bit-rotation etc.
26430 \layout Itemize
26431
26432 The second phase involves generating an intermediate code which can be easy
26433  manipulated during the later phases.
26434  This phase is entirely MCU independent.
26435  The intermediate code generation assumes the target machine has unlimited
26436  number of registers, and designates them with the name iTemp.
26437  The compiler can be made to dump a human readable form of the code generated
26438  by using the -
26439 \begin_inset ERT
26440 status Collapsed
26441
26442 \layout Standard
26443
26444 \backslash
26445 /
26446 \end_inset
26447
26448 -dumpraw option.
26449 \layout Itemize
26450
26451 This phase does the bulk of the standard optimizations and is also MCU independe
26452 nt.
26453  This phase can be broken down into several sub-phases:
26454 \newline
26455
26456 \newline
26457 Break down intermediate code (iCode) into basic blocks.
26458 \newline
26459 Do control flow & data flow analysis on the basic blocks.
26460 \newline
26461 Do local common subexpression elimination, then global subexpression elimination
26462 \newline
26463 Dead code elimination
26464 \newline
26465 Loop optimizations
26466 \newline
26467 If loop optimizations caused any changes then do 'global subexpression eliminati
26468 on' and 'dead code elimination' again.
26469 \layout Itemize
26470
26471 This phase determines the live-ranges; by live range I mean those iTemp
26472  variables defined by the compiler that still survive after all the optimization
26473 s.
26474  Live range analysis
26475 \begin_inset LatexCommand \index{Live range analysis}
26476
26477 \end_inset
26478
26479  is essential for register allocation, since these computation determines
26480  which of these iTemps will be assigned to registers, and for how long.
26481 \layout Itemize
26482
26483 Phase five is register allocation.
26484  There are two parts to this process.
26485 \newline
26486
26487 \newline
26488 The first part I call 'register packing' (for lack of a better term).
26489  In this case several MCU specific expression folding is done to reduce
26490  register pressure.
26491 \newline
26492
26493 \newline
26494 The second part is more MCU independent and deals with allocating registers
26495  to the remaining live ranges.
26496  A lot of MCU specific code does creep into this phase because of the limited
26497  number of index registers available in the 8051.
26498 \layout Itemize
26499
26500 The Code generation phase is (unhappily), entirely MCU dependent and very
26501  little (if any at all) of this code can be reused for other MCU.
26502  However the scheme for allocating a homogenized assembler operand for each
26503  iCode operand may be reused.
26504 \layout Itemize
26505
26506 As mentioned in the optimization section the peep-hole optimizer is rule
26507  based system, which can reprogrammed for other MCUs.
26508 \layout Chapter
26509
26510 Compiler internals
26511 \begin_inset LatexCommand \index{Compiler internals}
26512
26513 \end_inset
26514
26515
26516 \layout Section
26517
26518 The anatomy of the compiler
26519 \begin_inset LatexCommand \label{sub:The-anatomy-of}
26520
26521 \end_inset
26522
26523
26524 \layout Standard
26525
26526
26527 \shape italic
26528 This is an excerpt from an article published in Circuit Cellar Magazine
26529  in
26530 \series bold
26531 August 2000
26532 \series default
26533 .
26534  It's a little outdated (the compiler is much more efficient now and user/develo
26535 per friendly), but pretty well exposes the guts of it all.
26536 \shape default
26537
26538 \newline
26539
26540 \newline
26541 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
26542  It is fairly easy to retarget for other 8-bit MCU.
26543  Here we take a look at some of the internals of the compiler.
26544
26545 \layout Paragraph*
26546
26547 Parsing
26548 \begin_inset LatexCommand \index{Parsing}
26549
26550 \end_inset
26551
26552
26553 \layout Standard
26554
26555 Parsing the input source file and creating an AST (Annotated Syntax Tree
26556 \begin_inset LatexCommand \index{Annotated syntax tree}
26557
26558 \end_inset
26559
26560 ).
26561  This phase also involves propagating types (annotating each node of the
26562  parse tree with type information) and semantic analysis.
26563  There are some MCU specific parsing rules.
26564  For example the storage classes, the extended storage classes are MCU specific
26565  while there may be a xdata storage class for 8051 there is no such storage
26566  class for z80 or Atmel AVR.
26567  SDCC allows MCU specific storage class extensions, i.e.
26568  xdata will be treated as a storage class specifier when parsing 8051 C
26569  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
26570  C code.
26571 \layout Paragraph*
26572
26573 Generating iCode
26574 \begin_inset LatexCommand \index{iCode}
26575
26576 \end_inset
26577
26578
26579 \layout Standard
26580
26581 Intermediate code generation.
26582  In this phase the AST is broken down into three-operand form (iCode).
26583  These three operand forms are represented as doubly linked lists.
26584  ICode is the term given to the intermediate form generated by the compiler.
26585  ICode example section shows some examples of iCode generated for some simple
26586  C source functions.
26587 \layout Paragraph*
26588
26589 Optimizations
26590 \begin_inset LatexCommand \index{Optimizations}
26591
26592 \end_inset
26593
26594 .
26595 \layout Standard
26596
26597 Bulk of the target independent optimizations is performed in this phase.
26598  The optimizations include constant propagation, common sub-expression eliminati
26599 on, loop invariant code movement, strength reduction of loop induction variables
26600  and dead-code elimination.
26601 \layout Paragraph*
26602
26603 Live range analysis
26604 \begin_inset LatexCommand \index{Live range analysis}
26605
26606 \end_inset
26607
26608
26609 \layout Standard
26610
26611 During intermediate code generation phase, the compiler assumes the target
26612  machine has infinite number of registers and generates a lot of temporary
26613  variables.
26614  The live range computation determines the lifetime of each of these compiler-ge
26615 nerated temporaries.
26616  A picture speaks a thousand words.
26617  ICode example sections show the live range annotations for each of the
26618  operand.
26619  It is important to note here, each iCode is assigned a number in the order
26620  of its execution in the function.
26621  The live ranges are computed in terms of these numbers.
26622  The from number is the number of the iCode which first defines the operand
26623  and the to number signifies the iCode which uses this operand last.
26624 \layout Paragraph*
26625
26626 Register Allocation
26627 \begin_inset LatexCommand \index{Register allocation}
26628
26629 \end_inset
26630
26631
26632 \layout Standard
26633
26634 The register allocation determines the type and number of registers needed
26635  by each operand.
26636  In most MCUs only a few registers can be used for indirect addressing.
26637  In case of 8051 for example the registers R0 & R1 can be used to indirectly
26638  address the internal ram and DPTR to indirectly address the external ram.
26639  The compiler will try to allocate the appropriate register to pointer variables
26640  if it can.
26641  ICode example section shows the operands annotated with the registers assigned
26642  to them.
26643  The compiler will try to keep operands in registers as much as possible;
26644  there are several schemes the compiler uses to do achieve this.
26645  When the compiler runs out of registers the compiler will check to see
26646  if there are any live operands which is not used or defined in the current
26647  basic block being processed, if there are any found then it will push that
26648  operand and use the registers in this block, the operand will then be popped
26649  at the end of the basic block.
26650
26651 \layout Standard
26652
26653 There are other MCU specific considerations in this phase.
26654  Some MCUs have an accumulator; very short-lived operands could be assigned
26655  to the accumulator instead of a general-purpose register.
26656 \layout Paragraph*
26657
26658 Code generation
26659 \layout Standard
26660
26661 Figure II gives a table of iCode operations supported by the compiler.
26662  The code generation involves translating these operations into corresponding
26663  assembly code for the processor.
26664  This sounds overly simple but that is the essence of code generation.
26665  Some of the iCode operations are generated on a MCU specific manner for
26666  example, the z80 port does not use registers to pass parameters so the
26667  SEND and RECV iCode operations will not be generated, and it also does
26668  not support JUMPTABLES.
26669
26670 \newline
26671
26672 \series bold
26673 \shape italic
26674 \color red
26675 <Where is Figure II?>
26676 \layout Comment
26677
26678 In the original article Figure II was announced to be downloadable on
26679 \shape italic
26680 Circuit Cellar
26681 \shape default
26682 's web site.
26683  Unfortunately it never seemed to have shown up there, so: where is Figure
26684  II?
26685 \layout Paragraph*
26686
26687 ICode Example
26688 \begin_inset LatexCommand \index{iCode}
26689
26690 \end_inset
26691
26692
26693 \layout Standard
26694
26695 This section shows some details of iCode.
26696  The example C code does not do anything useful; it is used as an example
26697  to illustrate the intermediate code generated by the compiler.
26698 \layout Verse
26699
26700
26701 \family typewriter
26702 1.\SpecialChar ~
26703 xdata int * p;
26704 \newline
26705 2.\SpecialChar ~
26706 int gint;
26707 \newline
26708 3.\SpecialChar ~
26709 /* This function does nothing useful.
26710  It is used
26711 \newline
26712 4.\SpecialChar ~
26713 \SpecialChar ~
26714 \SpecialChar ~
26715 \SpecialChar ~
26716 for the purpose of explaining iCode */
26717 \newline
26718 5.\SpecialChar ~
26719 short function (data int *x)
26720 \newline
26721 6.\SpecialChar ~
26722 {
26723 \newline
26724 7.\SpecialChar ~
26725 \SpecialChar ~
26726 \SpecialChar ~
26727 short i=10; \SpecialChar ~
26728 \SpecialChar ~
26729 /* dead initialization eliminated */
26730 \newline
26731 8.\SpecialChar ~
26732 \SpecialChar ~
26733 \SpecialChar ~
26734 short sum=10; /* dead initialization eliminated */
26735 \newline
26736 9.\SpecialChar ~
26737 \SpecialChar ~
26738 \SpecialChar ~
26739 short mul;
26740 \newline
26741 10.\SpecialChar ~
26742 \SpecialChar ~
26743 int j ;
26744 \newline
26745 11.\SpecialChar ~
26746 \SpecialChar ~
26747 while (*x) *x++ = *p++;
26748 \newline
26749 12.\SpecialChar ~
26750 \SpecialChar ~
26751 \SpecialChar ~
26752 \SpecialChar ~
26753 sum = 0 ;
26754 \newline
26755 13.\SpecialChar ~
26756 \SpecialChar ~
26757 mul = 0;
26758 \newline
26759 14.\SpecialChar ~
26760 \SpecialChar ~
26761 /* compiler detects i,j to be induction variables */
26762 \newline
26763 15.\SpecialChar ~
26764 \SpecialChar ~
26765 for (i = 0, j = 10 ; i < 10 ; i++, j
26766 \family default
26767 -
26768 \begin_inset ERT
26769 status Collapsed
26770
26771 \layout Standard
26772
26773 \backslash
26774 /
26775 \end_inset
26776
26777 -
26778 \family typewriter
26779 ) {
26780 \newline
26781 16.\SpecialChar ~
26782 \SpecialChar ~
26783 \SpecialChar ~
26784 \SpecialChar ~
26785 sum += i;
26786 \newline
26787 17.\SpecialChar ~
26788 \SpecialChar ~
26789 \SpecialChar ~
26790 \SpecialChar ~
26791 mul += i * 3; \SpecialChar ~
26792 \SpecialChar ~
26793 /* this multiplication remains */
26794 \newline
26795 18.\SpecialChar ~
26796 \SpecialChar ~
26797 \SpecialChar ~
26798 \SpecialChar ~
26799 gint += j * 3;\SpecialChar ~
26800 \SpecialChar ~
26801 /* this multiplication changed to addition */
26802 \newline
26803 19.\SpecialChar ~
26804 \SpecialChar ~
26805 }
26806 \newline
26807 20.\SpecialChar ~
26808 \SpecialChar ~
26809 return sum+mul;
26810 \newline
26811 21.\SpecialChar ~
26812 }
26813 \layout Standard
26814
26815 In addition to the operands each iCode contains information about the filename
26816  and line it corresponds to in the source file.
26817  The first field in the listing should be interpreted as follows:
26818 \newline
26819
26820 \shape italic
26821 \size footnotesize
26822 Filename(linenumber: iCode Execution sequence number : ICode hash table
26823  key : loop depth of the iCode).
26824 \shape default
26825 \size default
26826
26827 \newline
26828 Then follows the human readable form of the ICode operation.
26829  Each operand of this triplet form can be of three basic types a) compiler
26830  generated temporary b) user defined variable c) a constant value.
26831  Note that local variables and parameters are replaced by compiler generated
26832  temporaries.
26833  Live ranges
26834 \begin_inset LatexCommand \index{Live range analysis}
26835
26836 \end_inset
26837
26838  are computed only for temporaries (i.e.
26839  live ranges are not computed for global variables).
26840  Registers
26841 \begin_inset LatexCommand \index{Register allocation}
26842
26843 \end_inset
26844
26845  are allocated for temporaries only.
26846  Operands are formatted in the following manner:
26847 \newline
26848
26849 \shape italic
26850 \size footnotesize
26851 Operand Name [lr live-from : live-to ] { type information } [ registers
26852  allocated ].
26853 \shape default
26854 \size default
26855
26856 \newline
26857 As mentioned earlier the live ranges are computed in terms of the execution
26858  sequence number of the iCodes, for example
26859 \newline
26860 the iTemp0 is live from (i.e.
26861  first defined in iCode with execution sequence number 3, and is last used
26862  in the iCode with sequence number 5).
26863  For induction variables such as iTemp21 the live range computation extends
26864  the lifetime from the start to the end of the loop.
26865 \newline
26866 The register allocator used the live range information to allocate registers,
26867  the same registers may be used for different temporaries if their live
26868  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
26869  iTemp17 since their live ranges do not overlap.
26870  In addition the allocator also takes into consideration the type and usage
26871  of a temporary, for example itemp6 is a pointer to near space and is used
26872  as to fetch data from (i.e.
26873  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
26874  Some short lived temporaries are allocated to special registers which have
26875  meaning to the code generator e.g.
26876  iTemp13 is allocated to a pseudo register CC which tells the back end that
26877  the temporary is used only for a conditional jump the code generation makes
26878  use of this information to optimize a compare and jump ICode.
26879 \newline
26880 There are several loop optimizations
26881 \begin_inset LatexCommand \index{Loop optimization}
26882
26883 \end_inset
26884
26885  performed by the compiler.
26886  It can detect induction variables iTemp21(i) and iTemp23(j).
26887  Also note the compiler does selective strength reduction
26888 \begin_inset LatexCommand \index{Strength reduction}
26889
26890 \end_inset
26891
26892 , i.e.
26893  the multiplication of an induction variable in line 18 (gint = j * 3) is
26894  changed to addition, a new temporary iTemp17 is allocated and assigned
26895  a initial value, a constant 3 is then added for each iteration of the loop.
26896  The compiler does not change the multiplication
26897 \begin_inset LatexCommand \index{Multiplication}
26898
26899 \end_inset
26900
26901  in line 17 however since the processor does support an 8 * 8 bit multiplication.
26902 \newline
26903 Note the dead code elimination
26904 \begin_inset LatexCommand \index{Dead-code elimination}
26905
26906 \end_inset
26907
26908  optimization eliminated the dead assignments in line 7 & 8 to I and sum
26909  respectively.
26910 \newline
26911
26912 \layout Standard
26913
26914
26915 \size footnotesize
26916 Sample.c (5:1:0:0) _entry($9) :
26917 \layout Standard
26918
26919
26920 \size footnotesize
26921 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
26922 \layout Standard
26923
26924
26925 \size footnotesize
26926 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
26927 \layout Standard
26928
26929
26930 \size footnotesize
26931 Sample.c(11:4:53:0) preHeaderLbl0($11) :
26932 \layout Standard
26933
26934
26935 \size footnotesize
26936 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
26937  * int}[r2]
26938 \layout Standard
26939
26940
26941 \size footnotesize
26942 Sample.c(11:6:5:1) _whilecontinue_0($1) :
26943 \layout Standard
26944
26945
26946 \size footnotesize
26947 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
26948  int}[r0]]
26949 \layout Standard
26950
26951
26952 \size footnotesize
26953 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
26954 \layout Standard
26955
26956
26957 \size footnotesize
26958 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
26959  * int}
26960 \layout Standard
26961
26962
26963 \size footnotesize
26964 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
26965  {short}
26966 \layout Standard
26967
26968
26969 \size footnotesize
26970 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
26971  * int}[DPTR]]
26972 \layout Standard
26973
26974
26975 \size footnotesize
26976 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
26977 }[r2 r3]
26978 \layout Standard
26979
26980
26981 \size footnotesize
26982 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
26983  * int}[r0] + 0x2 {short}
26984 \layout Standard
26985
26986
26987 \size footnotesize
26988 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
26989 \layout Standard
26990
26991
26992 \size footnotesize
26993 Sample.c(11:17:21:0)_whilebreak_0($3) :
26994 \layout Standard
26995
26996
26997 \size footnotesize
26998 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
26999 \layout Standard
27000
27001
27002 \size footnotesize
27003 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
27004 \layout Standard
27005
27006
27007 \size footnotesize
27008 Sample.c(15:20:54:0)preHeaderLbl1($13) :
27009 \layout Standard
27010
27011
27012 \size footnotesize
27013 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
27014 \layout Standard
27015
27016
27017 \size footnotesize
27018 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
27019 \layout Standard
27020
27021
27022 \size footnotesize
27023 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
27024 \layout Standard
27025
27026
27027 \size footnotesize
27028 Sample.c(15:24:26:1)_forcond_0($4) :
27029 \layout Standard
27030
27031
27032 \size footnotesize
27033 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
27034  < 0xa {short}
27035 \layout Standard
27036
27037
27038 \size footnotesize
27039 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
27040 \layout Standard
27041
27042
27043 \size footnotesize
27044 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
27045  + ITemp21 [lr21:38]{short}[r4]
27046 \layout Standard
27047
27048
27049 \size footnotesize
27050 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
27051  * 0x3 {short}
27052 \layout Standard
27053
27054
27055 \size footnotesize
27056 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
27057  + iTemp15 [lr29:30]{short}[r1]
27058 \layout Standard
27059
27060
27061 \size footnotesize
27062 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
27063  r0]- 0x3 {short}
27064 \layout Standard
27065
27066
27067 \size footnotesize
27068 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
27069 int}[r7 r0]
27070 \layout Standard
27071
27072
27073 \size footnotesize
27074 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
27075  + 0x1 {short}
27076 \layout Standard
27077
27078
27079 \size footnotesize
27080 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
27081  r6]- 0x1 {short}
27082 \layout Standard
27083
27084
27085 \size footnotesize
27086 Sample.c(19:38:47:1) goto _forcond_0($4)
27087 \layout Standard
27088
27089
27090 \size footnotesize
27091 Sample.c(19:39:48:0)_forbreak_0($7) :
27092 \layout Standard
27093
27094
27095 \size footnotesize
27096 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
27097  + ITemp11 [lr19:40]{short}[r3]
27098 \layout Standard
27099
27100
27101 \size footnotesize
27102 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
27103 \layout Standard
27104
27105
27106 \size footnotesize
27107 Sample.c(20:42:51:0)_return($8) :
27108 \layout Standard
27109
27110
27111 \size footnotesize
27112 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
27113 \size default
27114
27115 \newline
27116
27117 \newline
27118 Finally the code generated for this function:
27119 \newline
27120
27121 \layout Standard
27122
27123
27124 \size footnotesize
27125 .area DSEG (DATA)
27126 \layout Standard
27127
27128
27129 \size footnotesize
27130 _p::
27131 \layout Standard
27132
27133
27134 \size footnotesize
27135 \SpecialChar ~
27136 \SpecialChar ~
27137 .ds 2
27138 \layout Standard
27139
27140
27141 \size footnotesize
27142 _gint::
27143 \layout Standard
27144
27145
27146 \size footnotesize
27147 \SpecialChar ~
27148 \SpecialChar ~
27149 .ds 2
27150 \layout Standard
27151
27152
27153 \size footnotesize
27154 ; sample.c 5
27155 \layout Standard
27156
27157
27158 \size footnotesize
27159 ; ----------------------------------------------
27160 \layout Standard
27161
27162
27163 \size footnotesize
27164 ; function function
27165 \layout Standard
27166
27167
27168 \size footnotesize
27169 ; ----------------------------------------------
27170 \layout Standard
27171
27172
27173 \size footnotesize
27174 _function:
27175 \layout Standard
27176
27177
27178 \size footnotesize
27179 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
27180 \layout Standard
27181
27182
27183 \size footnotesize
27184 \SpecialChar ~
27185 \SpecialChar ~
27186 mov r2,dpl
27187 \layout Standard
27188
27189
27190 \size footnotesize
27191 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
27192 \layout Standard
27193
27194
27195 \size footnotesize
27196 \SpecialChar ~
27197 \SpecialChar ~
27198 mov ar0,r2
27199 \layout Standard
27200
27201
27202 \size footnotesize
27203 ;_whilecontinue_0($1) :
27204 \layout Standard
27205
27206
27207 \size footnotesize
27208 00101$:
27209 \layout Standard
27210
27211
27212 \size footnotesize
27213 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
27214 \layout Standard
27215
27216
27217 \size footnotesize
27218 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
27219 \layout Standard
27220
27221
27222 \size footnotesize
27223 \SpecialChar ~
27224 \SpecialChar ~
27225 mov ar2,@r0
27226 \layout Standard
27227
27228
27229 \size footnotesize
27230 \SpecialChar ~
27231 \SpecialChar ~
27232 inc r0
27233 \layout Standard
27234
27235
27236 \size footnotesize
27237 \SpecialChar ~
27238 \SpecialChar ~
27239 mov ar3,@r0
27240 \layout Standard
27241
27242
27243 \size footnotesize
27244 \SpecialChar ~
27245 \SpecialChar ~
27246 dec r0
27247 \layout Standard
27248
27249
27250 \size footnotesize
27251 \SpecialChar ~
27252 \SpecialChar ~
27253 mov a,r2
27254 \layout Standard
27255
27256
27257 \size footnotesize
27258 \SpecialChar ~
27259 \SpecialChar ~
27260 orl a,r3
27261 \layout Standard
27262
27263
27264 \size footnotesize
27265 \SpecialChar ~
27266 \SpecialChar ~
27267 jz 00103$
27268 \layout Standard
27269
27270
27271 \size footnotesize
27272 00114$:
27273 \layout Standard
27274
27275
27276 \size footnotesize
27277 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
27278 \layout Standard
27279
27280
27281 \size footnotesize
27282 \SpecialChar ~
27283 \SpecialChar ~
27284 mov dpl,_p
27285 \layout Standard
27286
27287
27288 \size footnotesize
27289 \SpecialChar ~
27290 \SpecialChar ~
27291 mov dph,(_p + 1)
27292 \layout Standard
27293
27294
27295 \size footnotesize
27296 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
27297 \layout Standard
27298
27299
27300 \size footnotesize
27301 \SpecialChar ~
27302 \SpecialChar ~
27303 mov a,#0x02
27304 \layout Standard
27305
27306
27307 \size footnotesize
27308 \SpecialChar ~
27309 \SpecialChar ~
27310 add a,_p
27311 \layout Standard
27312
27313
27314 \size footnotesize
27315 \SpecialChar ~
27316 \SpecialChar ~
27317 mov _p,a
27318 \layout Standard
27319
27320
27321 \size footnotesize
27322 \SpecialChar ~
27323 \SpecialChar ~
27324 clr a
27325 \layout Standard
27326
27327
27328 \size footnotesize
27329 \SpecialChar ~
27330 \SpecialChar ~
27331 addc a,(_p + 1)
27332 \layout Standard
27333
27334
27335 \size footnotesize
27336 \SpecialChar ~
27337 \SpecialChar ~
27338 mov (_p + 1),a
27339 \layout Standard
27340
27341
27342 \size footnotesize
27343 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
27344 \layout Standard
27345
27346
27347 \size footnotesize
27348 \SpecialChar ~
27349 \SpecialChar ~
27350 movx a,@dptr
27351 \layout Standard
27352
27353
27354 \size footnotesize
27355 \SpecialChar ~
27356 \SpecialChar ~
27357 mov r2,a
27358 \layout Standard
27359
27360
27361 \size footnotesize
27362 \SpecialChar ~
27363 \SpecialChar ~
27364 inc dptr
27365 \layout Standard
27366
27367
27368 \size footnotesize
27369 \SpecialChar ~
27370 \SpecialChar ~
27371 movx a,@dptr
27372 \layout Standard
27373
27374
27375 \size footnotesize
27376 \SpecialChar ~
27377 \SpecialChar ~
27378 mov r3,a
27379 \layout Standard
27380
27381
27382 \size footnotesize
27383 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
27384 \layout Standard
27385
27386
27387 \size footnotesize
27388 \SpecialChar ~
27389 \SpecialChar ~
27390 mov @r0,ar2
27391 \layout Standard
27392
27393
27394 \size footnotesize
27395 \SpecialChar ~
27396 \SpecialChar ~
27397 inc r0
27398 \layout Standard
27399
27400
27401 \size footnotesize
27402 \SpecialChar ~
27403 \SpecialChar ~
27404 mov @r0,ar3
27405 \layout Standard
27406
27407
27408 \size footnotesize
27409 ; iTemp6 [lr5:16]{_near * int}[r0] =
27410 \layout Standard
27411
27412
27413 \size footnotesize
27414 ; iTemp6 [lr5:16]{_near * int}[r0] +
27415 \layout Standard
27416
27417
27418 \size footnotesize
27419 ; 0x2 {short}
27420 \layout Standard
27421
27422
27423 \size footnotesize
27424 \SpecialChar ~
27425 \SpecialChar ~
27426 inc r0
27427 \layout Standard
27428
27429
27430 \size footnotesize
27431 ; goto _whilecontinue_0($1)
27432 \layout Standard
27433
27434
27435 \size footnotesize
27436 \SpecialChar ~
27437 \SpecialChar ~
27438 sjmp 00101$
27439 \layout Standard
27440
27441
27442 \size footnotesize
27443 ; _whilebreak_0($3) :
27444 \layout Standard
27445
27446
27447 \size footnotesize
27448 00103$:
27449 \layout Standard
27450
27451
27452 \size footnotesize
27453 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
27454 \layout Standard
27455
27456
27457 \size footnotesize
27458 \SpecialChar ~
27459 \SpecialChar ~
27460 mov r2,#0x00
27461 \layout Standard
27462
27463
27464 \size footnotesize
27465 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
27466 \layout Standard
27467
27468
27469 \size footnotesize
27470 \SpecialChar ~
27471 \SpecialChar ~
27472 mov r3,#0x00
27473 \layout Standard
27474
27475
27476 \size footnotesize
27477 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
27478 \layout Standard
27479
27480
27481 \size footnotesize
27482 \SpecialChar ~
27483 \SpecialChar ~
27484 mov r4,#0x00
27485 \layout Standard
27486
27487
27488 \size footnotesize
27489 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
27490 \layout Standard
27491
27492
27493 \size footnotesize
27494 \SpecialChar ~
27495 \SpecialChar ~
27496 mov r5,#0x0A
27497 \layout Standard
27498
27499
27500 \size footnotesize
27501 \SpecialChar ~
27502 \SpecialChar ~
27503 mov r6,#0x00
27504 \layout Standard
27505
27506
27507 \size footnotesize
27508 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
27509 \layout Standard
27510
27511
27512 \size footnotesize
27513 \SpecialChar ~
27514 \SpecialChar ~
27515 mov r7,#0x1E
27516 \layout Standard
27517
27518
27519 \size footnotesize
27520 \SpecialChar ~
27521 \SpecialChar ~
27522 mov r0,#0x00
27523 \layout Standard
27524
27525
27526 \size footnotesize
27527 ; _forcond_0($4) :
27528 \layout Standard
27529
27530
27531 \size footnotesize
27532 00104$:
27533 \layout Standard
27534
27535
27536 \size footnotesize
27537 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
27538 \layout Standard
27539
27540
27541 \size footnotesize
27542 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
27543 \layout Standard
27544
27545
27546 \size footnotesize
27547 \SpecialChar ~
27548 \SpecialChar ~
27549 clr c
27550 \layout Standard
27551
27552
27553 \size footnotesize
27554 \SpecialChar ~
27555 \SpecialChar ~
27556 mov a,r4
27557 \layout Standard
27558
27559
27560 \size footnotesize
27561 \SpecialChar ~
27562 \SpecialChar ~
27563 xrl a,#0x80
27564 \layout Standard
27565
27566
27567 \size footnotesize
27568 \SpecialChar ~
27569 \SpecialChar ~
27570 subb a,#0x8a
27571 \layout Standard
27572
27573
27574 \size footnotesize
27575 \SpecialChar ~
27576 \SpecialChar ~
27577 jnc 00107$
27578 \layout Standard
27579
27580
27581 \size footnotesize
27582 00115$:
27583 \layout Standard
27584
27585
27586 \size footnotesize
27587 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
27588 \layout Standard
27589
27590
27591 \size footnotesize
27592 ; iTemp21 [lr21:38]{short}[r4]
27593 \layout Standard
27594
27595
27596 \size footnotesize
27597 \SpecialChar ~
27598 \SpecialChar ~
27599 mov a,r4
27600 \layout Standard
27601
27602
27603 \size footnotesize
27604 \SpecialChar ~
27605 \SpecialChar ~
27606 add a,r2
27607 \layout Standard
27608
27609
27610 \size footnotesize
27611 \SpecialChar ~
27612 \SpecialChar ~
27613 mov r2,a
27614 \layout Standard
27615
27616
27617 \size footnotesize
27618 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
27619 \layout Standard
27620
27621
27622 \size footnotesize
27623 \SpecialChar ~
27624 \SpecialChar ~
27625 mov b,#0x03
27626 \layout Standard
27627
27628
27629 \size footnotesize
27630 \SpecialChar ~
27631 \SpecialChar ~
27632 mov a,r4
27633 \layout Standard
27634
27635
27636 \size footnotesize
27637 \SpecialChar ~
27638 \SpecialChar ~
27639 mul ab
27640 \layout Standard
27641
27642
27643 \size footnotesize
27644 \SpecialChar ~
27645 \SpecialChar ~
27646 mov r1,a
27647 \layout Standard
27648
27649
27650 \size footnotesize
27651 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
27652 \layout Standard
27653
27654
27655 \size footnotesize
27656 ; iTemp15 [lr29:30]{short}[r1]
27657 \layout Standard
27658
27659
27660 \size footnotesize
27661 \SpecialChar ~
27662 \SpecialChar ~
27663 add a,r3
27664 \layout Standard
27665
27666
27667 \size footnotesize
27668 \SpecialChar ~
27669 \SpecialChar ~
27670 mov r3,a
27671 \layout Standard
27672
27673
27674 \size footnotesize
27675 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
27676 \layout Standard
27677
27678
27679 \size footnotesize
27680 \SpecialChar ~
27681 \SpecialChar ~
27682 mov a,r7
27683 \layout Standard
27684
27685
27686 \size footnotesize
27687 \SpecialChar ~
27688 \SpecialChar ~
27689 add a,#0xfd
27690 \layout Standard
27691
27692
27693 \size footnotesize
27694 \SpecialChar ~
27695 \SpecialChar ~
27696 mov r7,a
27697 \layout Standard
27698
27699
27700 \size footnotesize
27701 \SpecialChar ~
27702 \SpecialChar ~
27703 mov a,r0
27704 \layout Standard
27705
27706
27707 \size footnotesize
27708 \SpecialChar ~
27709 \SpecialChar ~
27710 addc a,#0xff
27711 \layout Standard
27712
27713
27714 \size footnotesize
27715 \SpecialChar ~
27716 \SpecialChar ~
27717 mov r0,a
27718 \layout Standard
27719
27720
27721 \size footnotesize
27722 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
27723 \layout Standard
27724
27725
27726 \size footnotesize
27727 \SpecialChar ~
27728 \SpecialChar ~
27729 mov a,r7
27730 \layout Standard
27731
27732
27733 \size footnotesize
27734 \SpecialChar ~
27735 \SpecialChar ~
27736 add a,_gint
27737 \layout Standard
27738
27739
27740 \size footnotesize
27741 \SpecialChar ~
27742 \SpecialChar ~
27743 mov _gint,a
27744 \layout Standard
27745
27746
27747 \size footnotesize
27748 \SpecialChar ~
27749 \SpecialChar ~
27750 mov a,r0
27751 \layout Standard
27752
27753
27754 \size footnotesize
27755 \SpecialChar ~
27756 \SpecialChar ~
27757 addc a,(_gint + 1)
27758 \layout Standard
27759
27760
27761 \size footnotesize
27762 \SpecialChar ~
27763 \SpecialChar ~
27764 mov (_gint + 1),a
27765 \layout Standard
27766
27767
27768 \size footnotesize
27769 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
27770 \layout Standard
27771
27772
27773 \size footnotesize
27774 \SpecialChar ~
27775 \SpecialChar ~
27776 inc r4
27777 \layout Standard
27778
27779
27780 \size footnotesize
27781 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
27782 \layout Standard
27783
27784
27785 \size footnotesize
27786 \SpecialChar ~
27787 \SpecialChar ~
27788 dec r5
27789 \layout Standard
27790
27791
27792 \size footnotesize
27793 \SpecialChar ~
27794 \SpecialChar ~
27795 cjne r5,#0xff,00104$
27796 \layout Standard
27797
27798
27799 \size footnotesize
27800 \SpecialChar ~
27801 \SpecialChar ~
27802 dec r6
27803 \layout Standard
27804
27805
27806 \size footnotesize
27807 ; goto _forcond_0($4)
27808 \layout Standard
27809
27810
27811 \size footnotesize
27812 \SpecialChar ~
27813 \SpecialChar ~
27814 sjmp 00104$
27815 \layout Standard
27816
27817
27818 \size footnotesize
27819 ; _forbreak_0($7) :
27820 \layout Standard
27821
27822
27823 \size footnotesize
27824 00107$:
27825 \layout Standard
27826
27827
27828 \size footnotesize
27829 ; ret iTemp24 [lr40:41]{short}
27830 \layout Standard
27831
27832
27833 \size footnotesize
27834 \SpecialChar ~
27835 \SpecialChar ~
27836 mov a,r3
27837 \layout Standard
27838
27839
27840 \size footnotesize
27841 \SpecialChar ~
27842 \SpecialChar ~
27843 add a,r2
27844 \layout Standard
27845
27846
27847 \size footnotesize
27848 \SpecialChar ~
27849 \SpecialChar ~
27850 mov dpl,a
27851 \layout Standard
27852
27853
27854 \size footnotesize
27855 ; _return($8) :
27856 \layout Standard
27857
27858
27859 \size footnotesize
27860 00108$:
27861 \layout Standard
27862
27863
27864 \size footnotesize
27865 \SpecialChar ~
27866 \SpecialChar ~
27867 ret
27868 \newline
27869
27870 \layout Section
27871
27872 A few words about basic block successors, predecessors and dominators
27873 \layout Standard
27874
27875 Successors are basic blocks
27876 \begin_inset LatexCommand \index{Basic blocks}
27877
27878 \end_inset
27879
27880  that might execute after this basic block.
27881 \newline
27882 Predecessors are basic blocks that might execute before reaching this basic
27883  block.
27884 \newline
27885 Dominators are basic blocks that WILL execute before reaching this basic
27886  block.
27887 \newline
27888
27889 \layout Standard
27890
27891 [basic block 1]
27892 \layout Standard
27893
27894 if (something)
27895 \layout Standard
27896
27897 \SpecialChar ~
27898 \SpecialChar ~
27899 \SpecialChar ~
27900 \SpecialChar ~
27901 [basic block 2]
27902 \layout Standard
27903
27904 else
27905 \layout Standard
27906
27907 \SpecialChar ~
27908 \SpecialChar ~
27909 \SpecialChar ~
27910 \SpecialChar ~
27911 [basic block 3]
27912 \layout Standard
27913
27914 [basic block 4]
27915 \newline
27916
27917 \layout Standard
27918
27919 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
27920 \layout Standard
27921
27922 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
27923 \layout Standard
27924
27925 c) domVect of [BB4] = BB1 ...
27926  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
27927  was executed.
27928 \layout Chapter
27929
27930 Acknowledgments
27931 \layout Standard
27932
27933
27934 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
27935
27936 \end_inset
27937
27938
27939 \newline
27940
27941 \newline
27942
27943 \emph on
27944 Thanks to all the other volunteer developers who have helped with coding,
27945  testing, web-page creation, distribution sets, etc.
27946  You know who you are :-)
27947 \emph default
27948
27949 \newline
27950
27951 \layout Standard
27952
27953 This document was initially written by Sandeep Dutta
27954 \layout Standard
27955
27956 All product names mentioned herein may be trademarks
27957 \begin_inset LatexCommand \index{Trademarks}
27958
27959 \end_inset
27960
27961  of their respective companies.
27962
27963 \layout Section*
27964
27965 Alphabetical index
27966 \layout Standard
27967
27968 To avoid confusion, the installation and building options for SDCC itself
27969  (chapter 2) are not part of the index.
27970 \layout Standard
27971
27972
27973 \begin_inset LatexCommand \printindex{}
27974
27975 \end_inset
27976
27977
27978 \the_end