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={68hc08 8032 8051 ansi c compiler CPU DS390                 embedded free Freescale GPL HC08 Intel manual Maxim mcs51 Microchip microcontroller open source PIC Z80 Zilog},
  11   pdfpagemode=UseOutlines,
  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.6
  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 Subversion
  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 Standard
 206
 207
 208 \begin_inset  Tabular
 209 <lyxtabular version="3" rows="8" columns="5">
 210 <features>
 211 <column alignment="center" valignment="top" leftline="true" width="0">
 212 <column alignment="center" valignment="top" leftline="true" width="0">
 213 <column alignment="center" valignment="top" leftline="true" width="0">
 214 <column alignment="center" valignment="top" leftline="true" width="0">
 215 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
 216 <row topline="true" bottomline="true">
 217 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 218 \begin_inset Text
 219
 220 \layout Standard
 221
 222 type
 223 \end_inset
 224 </cell>
 225 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 226 \begin_inset Text
 227
 228 \layout Standard
 229
 230 width
 231 \end_inset
 232 </cell>
 233 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 234 \begin_inset Text
 235
 236 \layout Standard
 237
 238 default
 239 \end_inset
 240 </cell>
 241 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 242 \begin_inset Text
 243
 244 \layout Standard
 245
 246 signed range
 247 \end_inset
 248 </cell>
 249 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 250 \begin_inset Text
 251
 252 \layout Standard
 253
 254 unsigned range
 255 \end_inset
 256 </cell>
 257 </row>
 258 <row topline="true">
 259 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 260 \begin_inset Text
 261
 262 \layout Standard
 263
 264 bool
 265 \end_inset
 266 </cell>
 267 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 268 \begin_inset Text
 269
 270 \layout Standard
 271
 272 1 bit
 273 \end_inset
 274 </cell>
 275 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 276 \begin_inset Text
 277
 278 \layout Standard
 279
 280 unsigned
 281 \end_inset
 282 </cell>
 283 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 284 \begin_inset Text
 285
 286 \layout Standard
 287
 288 -
 289 \end_inset
 290 </cell>
 291 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 292 \begin_inset Text
 293
 294 \layout Standard
 295
 296 0, 1
 297 \end_inset
 298 </cell>
 299 </row>
 300 <row topline="true">
 301 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 302 \begin_inset Text
 303
 304 \layout Standard
 305
 306 char
 307 \end_inset
 308 </cell>
 309 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 310 \begin_inset Text
 311
 312 \layout Standard
 313
 314 8 bits, 1 byte
 315 \end_inset
 316 </cell>
 317 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 318 \begin_inset Text
 319
 320 \layout Standard
 321
 322 signed
 323 \end_inset
 324 </cell>
 325 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 326 \begin_inset Text
 327
 328 \layout Standard
 329
 330 -128, +127
 331 \end_inset
 332 </cell>
 333 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 334 \begin_inset Text
 335
 336 \layout Standard
 337
 338 0, +255
 339 \end_inset
 340 </cell>
 341 </row>
 342 <row topline="true">
 343 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 344 \begin_inset Text
 345
 346 \layout Standard
 347
 348 short
 349 \end_inset
 350 </cell>
 351 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 352 \begin_inset Text
 353
 354 \layout Standard
 355
 356 16 bits, 2 bytes
 357 \end_inset
 358 </cell>
 359 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 360 \begin_inset Text
 361
 362 \layout Standard
 363
 364 signed
 365 \end_inset
 366 </cell>
 367 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 368 \begin_inset Text
 369
 370 \layout Standard
 371
 372 -32.768, +32.767
 373 \end_inset
 374 </cell>
 375 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 376 \begin_inset Text
 377
 378 \layout Standard
 379
 380 0, +65.535
 381 \end_inset
 382 </cell>
 383 </row>
 384 <row topline="true">
 385 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 386 \begin_inset Text
 387
 388 \layout Standard
 389
 390 int
 391 \end_inset
 392 </cell>
 393 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 394 \begin_inset Text
 395
 396 \layout Standard
 397
 398 16 bits, 2 bytes
 399 \end_inset
 400 </cell>
 401 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 402 \begin_inset Text
 403
 404 \layout Standard
 405
 406 signed
 407 \end_inset
 408 </cell>
 409 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 410 \begin_inset Text
 411
 412 \layout Standard
 413
 414 -32.768, +32.767
 415 \end_inset
 416 </cell>
 417 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 418 \begin_inset Text
 419
 420 \layout Standard
 421
 422 0, +65.535
 423 \end_inset
 424 </cell>
 425 </row>
 426 <row topline="true" bottomline="true">
 427 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 428 \begin_inset Text
 429
 430 \layout Standard
 431
 432 long
 433 \end_inset
 434 </cell>
 435 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 436 \begin_inset Text
 437
 438 \layout Standard
 439
 440 32 bits, 4 bytes
 441 \end_inset
 442 </cell>
 443 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 444 \begin_inset Text
 445
 446 \layout Standard
 447
 448 signed
 449 \end_inset
 450 </cell>
 451 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 452 \begin_inset Text
 453
 454 \layout Standard
 455
 456 -2.147.483.648, +2.147.483.647
 457 \end_inset
 458 </cell>
 459 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 460 \begin_inset Text
 461
 462 \layout Standard
 463
 464 0, +4.294.967.296
 465 \end_inset
 466 </cell>
 467 </row>
 468 <row topline="true" bottomline="true">
 469 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 470 \begin_inset Text
 471
 472 \layout Standard
 473
 474 float
 475 \end_inset
 476 </cell>
 477 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 478 \begin_inset Text
 479
 480 \layout Standard
 481
 482 4 bytes IEEE 754
 483 \end_inset
 484 </cell>
 485 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 486 \begin_inset Text
 487
 488 \layout Standard
 489
 490 signed
 491 \end_inset
 492 </cell>
 493 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 494 \begin_inset Text
 495
 496 \layout Standard
 497
 498 \end_inset
 499 </cell>
 500 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 501 \begin_inset Text
 502
 503 \layout Standard
 504
 505 \end_inset
 506 </cell>
 507 </row>
 508 <row topline="true" bottomline="true">
 509 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 510 \begin_inset Text
 511
 512 \layout Standard
 513
 514 pointer
 515 \end_inset
 516 </cell>
 517 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 518 \begin_inset Text
 519
 520 \layout Standard
 521
 522 1, 2, 3 or 4 bytes
 523 \end_inset
 524 </cell>
 525 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 526 \begin_inset Text
 527
 528 \layout Standard
 529
 530 generic
 531 \end_inset
 532 </cell>
 533 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 534 \begin_inset Text
 535
 536 \layout Standard
 537
 538 \end_inset
 539 </cell>
 540 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 541 \begin_inset Text
 542
 543 \layout Standard
 544
 545 \end_inset
 546 </cell>
 547 </row>
 548 </lyxtabular>
 549
 550 \end_inset
 551
 552
 553 \newline
 554 The compiler also allows
 555 \emph on
 556 inline assembler code
 557 \emph default
 558  to be embedded anywhere in a function.
 559  In addition, routines developed in assembly can also be called.
 560 \newline
 561
 562 \newline
 563 SDCC also provides an option (-
 564 \begin_inset ERT
 565 status Collapsed
 566
 567 \layout Standard
 568
 569 \backslash
 570 /
 571 \end_inset
 572
 573 -cyclomatic) to report the relative complexity of a function.
 574  These functions can then be further optimized, or hand coded in assembly
 575  if needed.
 576
 577 \newline
 578
 579 \newline
 580 SDCC also comes with a companion source level debugger SDCDB, the debugger
 581  currently uses ucSim a freeware simulator for 8051 and other micro-controllers.
 582  SDCDB and ucSim are currently not available on Win32 platforms.
 583
 584 \newline
 585
 586 \newline
 587 The latest version can be downloaded from
 588 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
 589
 590 \end_inset
 591
 592 .
 593
 594 \series bold
 595
 596 \series default
 597 \emph on
 598 Please note: the compiler will probably always be some steps ahead of this
 599  documentation
 600 \series bold
 601 \emph default
 602
 603 \begin_inset LatexCommand \index{Status of documentation}
 604
 605 \end_inset
 606
 607
 608 \begin_inset Foot
 609 collapsed false
 610
 611 \layout Standard
 612
 613 Obviously this has pros and cons
 614 \end_inset
 615
 616 .
 617 \layout Section
 618
 619 Open Source
 620 \layout Standard
 621
 622 All packages used in this compiler system are
 623 \emph on
 624 open source
 625 \emph default
 626  and
 627 \emph on
 628 freeware
 629 \emph default
 630 ; source code for all the sub-packages (pre-processor, assemblers, linkers
 631  etc) is distributed with the package.
 632  This documentation is maintained using a freeware word processor (LyX).
 633 \newline
 634 This program is free software; you can redistribute it and/or modify it
 635  under the terms of the GNU General Public License
 636 \begin_inset LatexCommand \index{GNU General Public License, GPL}
 637
 638 \end_inset
 639
 640  as published by the Free Software Foundation; either version 2, or (at
 641  your option) any later version.
 642  This program is distributed in the hope that it will be useful, but WITHOUT
 643  ANY WARRANTY; without even the implied warranty
 644 \begin_inset LatexCommand \index{warranty}
 645
 646 \end_inset
 647
 648  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 649  See the GNU General Public License for more details.
 650  You should have received a copy of the GNU General Public License along
 651  with this program; if not, write to the Free Software Foundation, 59 Temple
 652  Place - Suite 330, Boston, MA 02111-1307, USA.
 653  In other words, you are welcome to use, share and improve this program.
 654  You are forbidden to forbid anyone else to use, share and improve what
 655  you give them.
 656  Help stamp out software-hoarding!
 657 \layout Section
 658
 659 Typographic conventions
 660 \begin_inset LatexCommand \index{Typographic conventions}
 661
 662 \end_inset
 663
 664
 665 \layout Standard
 666
 667 Throughout this manual, we will use the following convention.
 668  Commands you have to type in are printed in
 669 \family sans
 670 \series bold
 671 "sans serif"
 672 \series default
 673 .
 674
 675 \family default
 676  Code samples are printed in
 677 \family typewriter
 678 typewriter font.
 679
 680 \family default
 681  Interesting items and new terms are printed in
 682 \emph on
 683 italic.
 684 \layout Section
 685
 686 Compatibility
 687 \begin_inset LatexCommand \label{sec:Compatibility-with-previous}
 688
 689 \end_inset
 690
 691  with previous versions
 692 \begin_inset LatexCommand \index{Compatibility with previous versions}
 693
 694 \end_inset
 695
 696
 697 \layout Standard
 698
 699 This version has numerous bug fixes compared with the previous version.
 700  But we also introduced some incompatibilities with older versions.
 701  Not just for the fun of it, but to make the compiler more stable, efficient
 702  and ANSI compliant
 703 \begin_inset LatexCommand \index{ANSI-compliance}
 704
 705 \end_inset
 706
 707  (see section
 708 \begin_inset LatexCommand \ref{sub:ANSI-Compliance}
 709
 710 \end_inset
 711
 712  for ANSI-Compliance).
 713
 714 \newline
 715
 716 \layout Itemize
 717
 718 short is now equivalent to int (16 bits), it used to be equivalent to char
 719  (8 bits) which is not ANSI compliant.
 720 \layout Itemize
 721
 722 the default directory for gcc-builds where include, library and documentation
 723  files are stored is now in /usr/local/share.
 724 \layout Itemize
 725
 726 char type parameters to vararg functions are casted to int unless explicitly
 727  casted, e.g.:
 728 \newline
 729
 730 \family typewriter
 731 \SpecialChar ~
 732 \SpecialChar ~
 733 char a=3;
 734 \newline
 735 \SpecialChar ~
 736 \SpecialChar ~
 737 printf ("%d %c
 738 \backslash
 739 n", a, (char)a);
 740 \family default
 741
 742 \newline
 743  will push a as an int and as a char resp.
 744 \layout Itemize
 745
 746 option -
 747 \begin_inset ERT
 748 status Collapsed
 749
 750 \layout Standard
 751
 752 \backslash
 753 /
 754 \end_inset
 755
 756 -regextend has been removed.
 757 \layout Itemize
 758
 759 option -
 760 \begin_inset ERT
 761 status Collapsed
 762
 763 \layout Standard
 764
 765 \backslash
 766 /
 767 \end_inset
 768
 769 -noregparms has been removed.
 770 \layout Itemize
 771
 772 option -
 773 \begin_inset ERT
 774 status Collapsed
 775
 776 \layout Standard
 777
 778 \backslash
 779 /
 780 \end_inset
 781
 782 -stack-after-data has been removed.
 783 \layout Itemize
 784
 785 bit
 786 \begin_inset LatexCommand \index{bit}
 787
 788 \end_inset
 789
 790  and sbit
 791 \begin_inset LatexCommand \index{sbit}
 792
 793 \end_inset
 794
 795
 796 \begin_inset LatexCommand \index{\_\_sbit}
 797
 798 \end_inset
 799
 800  types now consistently behave like the C99 _Bool type with respect to type
 801  conversion
 802 \begin_inset LatexCommand \index{type conversion}
 803
 804 \end_inset
 805
 806
 807 \begin_inset LatexCommand \index{type promotion}
 808
 809 \end_inset
 810
 811 .
 812  The most common incompatibility resulting from this change is related to
 813  bit toggling
 814 \begin_inset LatexCommand \index{Bit toggling}
 815
 816 \end_inset
 817
 818  idioms, e.g.:
 819 \newline
 820
 821 \family typewriter
 822 \SpecialChar ~
 823 \SpecialChar ~
 824 bit b;
 825 \newline
 826 \SpecialChar ~
 827 \SpecialChar ~
 828 b = ~b; /* equivalent to b=1 instead of toggling b */
 829 \begin_inset Marginal
 830 collapsed true
 831
 832 \layout Standard
 833
 834
 835 \series bold
 836 !
 837 \end_inset
 838
 839
 840 \newline
 841 \SpecialChar ~
 842 \SpecialChar ~
 843 b = !b; /* toggles b */
 844 \newline
 845
 846 \family default
 847 In previous versions, both forms would have toggled the bit.
 848 \layout Standard
 849
 850
 851 \emph on
 852 <pending: more incompatibilities?>
 853 \layout Section
 854
 855 System Requirements
 856 \layout Standard
 857
 858 What do you need before you start installation of SDCC? A computer, and
 859  a desire to compute.
 860  The preferred method of installation is to compile SDCC from source using
 861  GNU gcc and make.
 862  For Windows some pre-compiled binary distributions are available for your
 863  convenience.
 864  You should have some experience with command line tools and compiler use.
 865 \layout Section
 866
 867 Other Resources
 868 \layout Standard
 869
 870 The SDCC home page at
 871 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
 872
 873 \end_inset
 874
 875  is a great place to find distribution sets.
 876  You can also find links to the user mailing lists that offer help or discuss
 877  SDCC with other SDCC users.
 878  Web links to other SDCC related sites can also be found here.
 879  This document can be found in the DOC directory of the source package as
 880  a text or HTML file.
 881  A pdf version of this document is available at
 882 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
 883
 884 \end_inset
 885
 886 .
 887  Some of the other tools (simulator and assembler) included with SDCC contain
 888  their own documentation and can be found in the source distribution.
 889  If you want the latest unreleased software, the complete source package
 890  is available directly from Subversion on https://svn.sourceforge.net/svnroot/sdcc
 891 /trunk/sdcc.
 892 \layout Section
 893
 894 Wishes for the future
 895 \layout Standard
 896
 897 There are (and always will be) some things that could be done.
 898  Here are some I can think of:
 899 \newline
 900
 901 \layout Standard
 902
 903
 904 \family typewriter
 905 char KernelFunction3(char p) at 0x340;
 906 \newline
 907
 908 \layout Standard
 909
 910
 911 \family typewriter
 912 better code banking
 913 \begin_inset LatexCommand \index{code banking (limited support)}
 914
 915 \end_inset
 916
 917  support for mcs51
 918 \newline
 919
 920 \newline
 921
 922 \family default
 923 If you can think of some more, please see the section
 924 \begin_inset LatexCommand \ref{sub:Requesting-Features}
 925
 926 \end_inset
 927
 928  about filing feature requests
 929 \begin_inset LatexCommand \index{Requesting features}
 930
 931 \end_inset
 932
 933
 934 \begin_inset LatexCommand \index{Feature request}
 935
 936 \end_inset
 937
 938 .
 939 \newline
 940
 941 \layout Chapter
 942
 943 Installing SDCC
 944 \begin_inset LatexCommand \index{Installation}
 945
 946 \end_inset
 947
 948
 949 \layout Standard
 950
 951 For most users it is sufficient to skip to either section
 952 \begin_inset LatexCommand \ref{sub:Building-SDCC-on-Linux}
 953
 954 \end_inset
 955
 956  or section
 957 \begin_inset LatexCommand \ref{sub:Windows-Install}
 958
 959 \end_inset
 960
 961 .
 962  More detailled instructions follow below.
 963 \layout Section
 964
 965 Configure Options
 966 \begin_inset LatexCommand \index{Options SDCC configuration}
 967
 968 \end_inset
 969
 970
 971 \layout Standard
 972
 973 The install paths, search paths and other options are defined when running
 974  'configure'.
 975  The defaults can be overridden by:
 976 \layout List
 977 \labelwidthstring 00.00.0000
 978
 979 -
 980 \begin_inset ERT
 981 status Collapsed
 982
 983 \layout Standard
 984
 985 \backslash
 986 /
 987 \end_inset
 988
 989 -prefix see table below
 990 \layout List
 991 \labelwidthstring 00.00.0000
 992
 993 -
 994 \begin_inset ERT
 995 status Collapsed
 996
 997 \layout Standard
 998
 999 \backslash
1000 /
1001 \end_inset
1002
1003 -exec_prefix see table below
1004 \layout List
1005 \labelwidthstring 00.00.0000
1006
1007 -
1008 \begin_inset ERT
1009 status Collapsed
1010
1011 \layout Standard
1012
1013 \backslash
1014 /
1015 \end_inset
1016
1017 -bindir see table below
1018 \layout List
1019 \labelwidthstring 00.00.0000
1020
1021 -
1022 \begin_inset ERT
1023 status Collapsed
1024
1025 \layout Standard
1026
1027 \backslash
1028 /
1029 \end_inset
1030
1031 -datadir see table below
1032 \layout List
1033 \labelwidthstring 00.00.0000
1034
1035 docdir environment variable, see table below
1036 \layout List
1037 \labelwidthstring 00.00.0000
1038
1039 include_dir_suffix environment variable, see table below
1040 \layout List
1041 \labelwidthstring 00.00.0000
1042
1043 lib_dir_suffix environment variable, see table below
1044 \layout List
1045 \labelwidthstring 00.00.0000
1046
1047 sdccconf_h_dir_separator environment variable, either / or
1048 \backslash
1049
1050 \backslash
1051  makes sense here.
1052  This character will only be used in sdccconf.h; don't forget it's a C-header,
1053  therefore a double-backslash is needed there.
1054 \layout List
1055 \labelwidthstring 00.00.0000
1056
1057 -
1058 \begin_inset ERT
1059 status Collapsed
1060
1061 \layout Standard
1062
1063 \backslash
1064 /
1065 \end_inset
1066
1067 -disable-mcs51-port Excludes the Intel mcs51 port
1068 \layout List
1069 \labelwidthstring 00.00.0000
1070
1071 -
1072 \begin_inset ERT
1073 status Collapsed
1074
1075 \layout Standard
1076
1077 \backslash
1078 /
1079 \end_inset
1080
1081 -disable-gbz80-port Excludes the Gameboy gbz80 port
1082 \layout List
1083 \labelwidthstring 00.00.0000
1084
1085 -
1086 \begin_inset ERT
1087 status Collapsed
1088
1089 \layout Standard
1090
1091 \backslash
1092 /
1093 \end_inset
1094
1095 -disable-z80-port Excludes the z80 port
1096 \layout List
1097 \labelwidthstring 00.00.0000
1098
1099 -
1100 \begin_inset ERT
1101 status Collapsed
1102
1103 \layout Standard
1104
1105 \backslash
1106 /
1107 \end_inset
1108
1109 -disable-avr-port Excludes the AVR port
1110 \layout List
1111 \labelwidthstring 00.00.0000
1112
1113 -
1114 \begin_inset ERT
1115 status Collapsed
1116
1117 \layout Standard
1118
1119 \backslash
1120 /
1121 \end_inset
1122
1123 -disable-ds390-port Excludes the DS390 port
1124 \layout List
1125 \labelwidthstring 00.00.0000
1126
1127 -
1128 \begin_inset ERT
1129 status Collapsed
1130
1131 \layout Standard
1132
1133 \backslash
1134 /
1135 \end_inset
1136
1137 -disable-hc08-port Excludes the HC08 port
1138 \layout List
1139 \labelwidthstring 00.00.0000
1140
1141 -
1142 \begin_inset ERT
1143 status Collapsed
1144
1145 \layout Standard
1146
1147 \backslash
1148 /
1149 \end_inset
1150
1151 -disable-pic-port Excludes the PIC port
1152 \layout List
1153 \labelwidthstring 00.00.0000
1154
1155 -
1156 \begin_inset ERT
1157 status Collapsed
1158
1159 \layout Standard
1160
1161 \backslash
1162 /
1163 \end_inset
1164
1165 -disable-xa51-port Excludes the XA51 port
1166 \layout List
1167 \labelwidthstring 00.00.0000
1168
1169 -
1170 \begin_inset ERT
1171 status Collapsed
1172
1173 \layout Standard
1174
1175 \backslash
1176 /
1177 \end_inset
1178
1179 -disable-ucsim Disables configuring and building of ucsim
1180 \layout List
1181 \labelwidthstring 00.00.0000
1182
1183 -
1184 \begin_inset ERT
1185 status Collapsed
1186
1187 \layout Standard
1188
1189 \backslash
1190 /
1191 \end_inset
1192
1193 -disable-device-lib Disables automatically building device libraries
1194 \layout List
1195 \labelwidthstring 00.00.0000
1196
1197 -
1198 \begin_inset ERT
1199 status Collapsed
1200
1201 \layout Standard
1202
1203 \backslash
1204 /
1205 \end_inset
1206
1207 -disable-packihx Disables building packihx
1208 \layout List
1209 \labelwidthstring 00.00.0000
1210
1211 -
1212 \begin_inset ERT
1213 status Collapsed
1214
1215 \layout Standard
1216
1217 \backslash
1218 /
1219 \end_inset
1220
1221 -enable-doc Build pdf, html and txt files from the lyx sources
1222 \layout List
1223 \labelwidthstring 00.00.0000
1224
1225 -
1226 \begin_inset ERT
1227 status Collapsed
1228
1229 \layout Standard
1230
1231 \backslash
1232 /
1233 \end_inset
1234
1235 -enable-libgc Use the Bohem memory allocator.
1236  Lower runtime footprint.
1237 \layout Standard
1238
1239 Furthermore the environment variables CC, CFLAGS, ...
1240  the tools and their arguments can be influenced.
1241  Please see `configure -
1242 \begin_inset ERT
1243 status Collapsed
1244
1245 \layout Standard
1246
1247 \backslash
1248 /
1249 \end_inset
1250
1251 -help` and the man/info pages of `configure` for details.
1252 \newline
1253
1254 \newline
1255 The names of the standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB,
1256  STD_FP_LIB, STD_DS390_LIB, STD_XA51_LIB and the environment variables SDCC_DIR_
1257 NAME, SDCC_INCLUDE_NAME, SDCC_LIB_NAME are defined by `configure` too.
1258  At the moment it's not possible to change the default settings (it was
1259  simply never required).
1260 \newline
1261
1262 \newline
1263 These configure options are compiled into the binaries, and can only be
1264  changed by rerunning 'configure' and recompiling SDCC.
1265  The configure options are written in
1266 \emph on
1267 italics
1268 \emph default
1269  to distinguish them from run time environment variables (see section search
1270  paths).
1271 \newline
1272
1273 \newline
1274 The settings for
1275 \begin_inset Quotes sld
1276 \end_inset
1277
1278 Win32 builds
1279 \begin_inset Quotes srd
1280 \end_inset
1281
1282  are used by the SDCC team to build the official Win32 binaries.
1283  The SDCC team uses Mingw32 to build the official Windows binaries, because
1284  it's
1285 \layout Enumerate
1286
1287 open source,
1288 \layout Enumerate
1289
1290 a gcc compiler and last but not least
1291 \layout Enumerate
1292
1293 the binaries can be built by cross compiling on Sourceforge's compile farm.
1294 \layout Standard
1295
1296 See the examples, how to pass the Win32 settings to 'configure'.
1297  The other Win32 builds using Borland, VC or whatever don't use 'configure',
1298  but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
1299  for Win32.
1300 \newline
1301
1302 \newline
1303 These defaults are:
1304 \newline
1305
1306 \layout Standard
1307 \align center
1308
1309 \begin_inset  Tabular
1310 <lyxtabular version="3" rows="8" columns="3">
1311 <features>
1312 <column alignment="block" valignment="top" leftline="true" width="0in">
1313 <column alignment="block" valignment="top" leftline="true" width="0in">
1314 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1315 <row topline="true" bottomline="true">
1316 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1317 \begin_inset Text
1318
1319 \layout Standard
1320
1321 Variable
1322 \end_inset
1323 </cell>
1324 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1325 \begin_inset Text
1326
1327 \layout Standard
1328
1329 default
1330 \end_inset
1331 </cell>
1332 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1333 \begin_inset Text
1334
1335 \layout Standard
1336
1337 Win32 builds
1338 \end_inset
1339 </cell>
1340 </row>
1341 <row topline="true">
1342 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1343 \begin_inset Text
1344
1345 \layout Standard
1346
1347
1348 \emph on
1349 PREFIX
1350 \end_inset
1351 </cell>
1352 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1353 \begin_inset Text
1354
1355 \layout Standard
1356
1357 /usr/local
1358 \end_inset
1359 </cell>
1360 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1361 \begin_inset Text
1362
1363 \layout Standard
1364
1365
1366 \backslash
1367 sdcc
1368 \end_inset
1369 </cell>
1370 </row>
1371 <row topline="true">
1372 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1373 \begin_inset Text
1374
1375 \layout Standard
1376
1377
1378 \emph on
1379 EXEC_PREFIX
1380 \end_inset
1381 </cell>
1382 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1383 \begin_inset Text
1384
1385 \layout Standard
1386
1387
1388 \emph on
1389 $PREFIX
1390 \end_inset
1391 </cell>
1392 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1393 \begin_inset Text
1394
1395 \layout Standard
1396
1397
1398 \emph on
1399 $PREFIX
1400 \end_inset
1401 </cell>
1402 </row>
1403 <row topline="true">
1404 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1405 \begin_inset Text
1406
1407 \layout Standard
1408
1409
1410 \emph on
1411 BINDIR
1412 \end_inset
1413 </cell>
1414 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1415 \begin_inset Text
1416
1417 \layout Standard
1418
1419
1420 \emph on
1421 $EXECPREFIX
1422 \emph default
1423 /bin
1424 \end_inset
1425 </cell>
1426 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1427 \begin_inset Text
1428
1429 \layout Standard
1430
1431
1432 \emph on
1433 $EXECPREFIX
1434 \emph default
1435
1436 \backslash
1437 bin
1438 \end_inset
1439 </cell>
1440 </row>
1441 <row topline="true">
1442 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1443 \begin_inset Text
1444
1445 \layout Standard
1446
1447
1448 \emph on
1449 DATADIR
1450 \end_inset
1451 </cell>
1452 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1453 \begin_inset Text
1454
1455 \layout Standard
1456
1457
1458 \emph on
1459 $PREFIX
1460 \emph default
1461 /share
1462 \end_inset
1463 </cell>
1464 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1465 \begin_inset Text
1466
1467 \layout Standard
1468
1469
1470 \emph on
1471 $PREFIX
1472 \end_inset
1473 </cell>
1474 </row>
1475 <row topline="true">
1476 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1477 \begin_inset Text
1478
1479 \layout Standard
1480
1481
1482 \emph on
1483 DOCDIR
1484 \end_inset
1485 </cell>
1486 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1487 \begin_inset Text
1488
1489 \layout Standard
1490
1491
1492 \emph on
1493 $DATADIR
1494 \emph default
1495 /sdcc/doc
1496 \end_inset
1497 </cell>
1498 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1499 \begin_inset Text
1500
1501 \layout Standard
1502
1503
1504 \emph on
1505 $DATADIR
1506 \emph default
1507
1508 \backslash
1509 doc
1510 \end_inset
1511 </cell>
1512 </row>
1513 <row topline="true">
1514 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1515 \begin_inset Text
1516
1517 \layout Standard
1518
1519
1520 \emph on
1521 INCLUDE_DIR_SUFFIX
1522 \end_inset
1523 </cell>
1524 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1525 \begin_inset Text
1526
1527 \layout Standard
1528
1529 sdcc/include
1530 \end_inset
1531 </cell>
1532 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1533 \begin_inset Text
1534
1535 \layout Standard
1536
1537 include
1538 \end_inset
1539 </cell>
1540 </row>
1541 <row topline="true" bottomline="true">
1542 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1543 \begin_inset Text
1544
1545 \layout Standard
1546
1547
1548 \emph on
1549 LIB_DIR_SUFFIX
1550 \end_inset
1551 </cell>
1552 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1553 \begin_inset Text
1554
1555 \layout Standard
1556
1557 sdcc/lib
1558 \end_inset
1559 </cell>
1560 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1561 \begin_inset Text
1562
1563 \layout Standard
1564
1565 lib
1566 \end_inset
1567 </cell>
1568 </row>
1569 </lyxtabular>
1570
1571 \end_inset
1572
1573
1574 \newline
1575
1576 \layout Standard
1577 \noindent
1578 'configure' also computes relative paths.
1579  This is needed for full relocatability of a binary package and to complete
1580  search paths (see section search paths below):
1581 \newline
1582
1583 \layout Standard
1584 \align center
1585
1586 \begin_inset  Tabular
1587 <lyxtabular version="3" rows="4" columns="3">
1588 <features>
1589 <column alignment="block" valignment="top" leftline="true" width="0in">
1590 <column alignment="block" valignment="top" leftline="true" width="0in">
1591 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1592 <row topline="true" bottomline="true">
1593 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1594 \begin_inset Text
1595
1596 \layout Standard
1597
1598 Variable (computed)
1599 \end_inset
1600 </cell>
1601 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1602 \begin_inset Text
1603
1604 \layout Standard
1605
1606 default
1607 \end_inset
1608 </cell>
1609 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1610 \begin_inset Text
1611
1612 \layout Standard
1613
1614 Win32 builds
1615 \end_inset
1616 </cell>
1617 </row>
1618 <row topline="true" bottomline="true">
1619 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1620 \begin_inset Text
1621
1622 \layout Standard
1623
1624
1625 \emph on
1626 BIN2DATA_DIR
1627 \end_inset
1628 </cell>
1629 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1630 \begin_inset Text
1631
1632 \layout Standard
1633
1634 ../share
1635 \end_inset
1636 </cell>
1637 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1638 \begin_inset Text
1639
1640 \layout Standard
1641
1642 ..
1643 \end_inset
1644 </cell>
1645 </row>
1646 <row bottomline="true">
1647 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1648 \begin_inset Text
1649
1650 \layout Standard
1651
1652
1653 \emph on
1654 PREFIX2BIN_DIR
1655 \end_inset
1656 </cell>
1657 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1658 \begin_inset Text
1659
1660 \layout Standard
1661
1662 bin
1663 \end_inset
1664 </cell>
1665 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1666 \begin_inset Text
1667
1668 \layout Standard
1669
1670 bin
1671 \end_inset
1672 </cell>
1673 </row>
1674 <row bottomline="true">
1675 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1676 \begin_inset Text
1677
1678 \layout Standard
1679
1680
1681 \emph on
1682 PREFIX2DATA_DIR
1683 \end_inset
1684 </cell>
1685 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1686 \begin_inset Text
1687
1688 \layout Standard
1689
1690 share/sdcc
1691 \end_inset
1692 </cell>
1693 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1694 \begin_inset Text
1695
1696 \layout Standard
1697
1698 \end_inset
1699 </cell>
1700 </row>
1701 </lyxtabular>
1702
1703 \end_inset
1704
1705
1706 \newline
1707
1708 \layout Standard
1709 \noindent
1710 Examples:
1711 \layout LyX-Code
1712
1713 ./configure
1714 \newline
1715 ./configure -
1716 \begin_inset ERT
1717 status Collapsed
1718
1719 \layout Standard
1720
1721 \backslash
1722 /
1723 \end_inset
1724
1725 -prefix=
1726 \begin_inset Quotes srd
1727 \end_inset
1728
1729 /usr/bin
1730 \begin_inset Quotes srd
1731 \end_inset
1732
1733  -
1734 \begin_inset ERT
1735 status Collapsed
1736
1737 \layout Standard
1738
1739 \backslash
1740 /
1741 \end_inset
1742
1743 -datadir=
1744 \begin_inset Quotes srd
1745 \end_inset
1746
1747 /usr/share
1748 \begin_inset Quotes srd
1749 \end_inset
1750
1751
1752 \newline
1753 ./configure -
1754 \begin_inset ERT
1755 status Collapsed
1756
1757 \layout Standard
1758
1759 \backslash
1760 /
1761 \end_inset
1762
1763 -disable-avr-port -
1764 \begin_inset ERT
1765 status Collapsed
1766
1767 \layout Standard
1768
1769 \backslash
1770 /
1771 \end_inset
1772
1773 -disable-xa51-port
1774 \layout Standard
1775
1776 To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw
1777 32'):
1778 \layout LyX-Code
1779
1780 ./configure
1781 \backslash
1782
1783 \newline
1784 CC=
1785 \begin_inset Quotes srd
1786 \end_inset
1787
1788 i586-mingw32msvc-gcc
1789 \begin_inset Quotes srd
1790 \end_inset
1791
1792  CXX=
1793 \begin_inset Quotes srd
1794 \end_inset
1795
1796 i586-mingw32msvc-g++
1797 \begin_inset Quotes srd
1798 \end_inset
1799
1800
1801 \backslash
1802
1803 \newline
1804 RANLIB=
1805 \begin_inset Quotes srd
1806 \end_inset
1807
1808 i586-mingw32msvc-ranlib
1809 \begin_inset Quotes srd
1810 \end_inset
1811
1812
1813 \backslash
1814
1815 \newline
1816 STRIP=
1817 \begin_inset Quotes srd
1818 \end_inset
1819
1820 i586-mingw32msvc-strip
1821 \begin_inset Quotes srd
1822 \end_inset
1823
1824
1825 \backslash
1826
1827 \newline
1828 -
1829 \begin_inset ERT
1830 status Collapsed
1831
1832 \layout Standard
1833
1834 \backslash
1835 /
1836 \end_inset
1837
1838 -prefix=
1839 \begin_inset Quotes srd
1840 \end_inset
1841
1842 /sdcc
1843 \begin_inset Quotes srd
1844 \end_inset
1845
1846
1847 \backslash
1848
1849 \newline
1850 -
1851 \begin_inset ERT
1852 status Collapsed
1853
1854 \layout Standard
1855
1856 \backslash
1857 /
1858 \end_inset
1859
1860 -datadir=
1861 \begin_inset Quotes srd
1862 \end_inset
1863
1864 /sdcc
1865 \begin_inset Quotes srd
1866 \end_inset
1867
1868
1869 \backslash
1870
1871 \newline
1872 docdir=
1873 \begin_inset Quotes srd
1874 \end_inset
1875
1876 /sdcc/doc
1877 \begin_inset Quotes srd
1878 \end_inset
1879
1880
1881 \backslash
1882
1883 \newline
1884 include_dir_suffix=
1885 \begin_inset Quotes srd
1886 \end_inset
1887
1888 include
1889 \begin_inset Quotes srd
1890 \end_inset
1891
1892
1893 \backslash
1894
1895 \newline
1896 lib_dir_suffix=
1897 \begin_inset Quotes srd
1898 \end_inset
1899
1900 lib
1901 \begin_inset Quotes srd
1902 \end_inset
1903
1904
1905 \backslash
1906
1907 \newline
1908 sdccconf_h_dir_separator=
1909 \begin_inset Quotes srd
1910 \end_inset
1911
1912
1913 \backslash
1914
1915 \backslash
1916
1917 \backslash
1918
1919 \backslash
1920
1921 \begin_inset Quotes srd
1922 \end_inset
1923
1924
1925 \backslash
1926
1927 \newline
1928 -
1929 \begin_inset ERT
1930 status Collapsed
1931
1932 \layout Standard
1933
1934 \backslash
1935 /
1936 \end_inset
1937
1938 -disable-device-lib
1939 \backslash
1940
1941 \newline
1942 -
1943 \begin_inset ERT
1944 status Collapsed
1945
1946 \layout Standard
1947
1948 \backslash
1949 /
1950 \end_inset
1951
1952 -disable-ucsim
1953 \backslash
1954
1955 \newline
1956 -
1957 \begin_inset ERT
1958 status Collapsed
1959
1960 \layout Standard
1961
1962 \backslash
1963 /
1964 \end_inset
1965
1966 -host=i586-mingw32msvc -
1967 \begin_inset ERT
1968 status Collapsed
1969
1970 \layout Standard
1971
1972 \backslash
1973 /
1974 \end_inset
1975
1976 -build=unknown-unknown-linux-gnu
1977 \layout Standard
1978
1979 To
1980 \begin_inset Quotes sld
1981 \end_inset
1982
1983 cross
1984 \begin_inset Quotes srd
1985 \end_inset
1986
1987 compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32
1988 ):
1989 \layout LyX-Code
1990
1991 ./configure -C
1992 \backslash
1993
1994 \newline
1995 CFLAGS=
1996 \begin_inset Quotes srd
1997 \end_inset
1998
1999 -mno-cygwin -O2
2000 \begin_inset Quotes srd
2001 \end_inset
2002
2003
2004 \backslash
2005
2006 \newline
2007 LDFLAGS=
2008 \begin_inset Quotes srd
2009 \end_inset
2010
2011 -mno-cygwin
2012 \begin_inset Quotes srd
2013 \end_inset
2014
2015
2016 \backslash
2017
2018 \newline
2019 -
2020 \begin_inset ERT
2021 status Collapsed
2022
2023 \layout Standard
2024
2025 \backslash
2026 /
2027 \end_inset
2028
2029 -prefix=
2030 \begin_inset Quotes srd
2031 \end_inset
2032
2033 /sdcc
2034 \begin_inset Quotes srd
2035 \end_inset
2036
2037
2038 \backslash
2039
2040 \newline
2041 -
2042 \begin_inset ERT
2043 status Collapsed
2044
2045 \layout Standard
2046
2047 \backslash
2048 /
2049 \end_inset
2050
2051 -datadir=
2052 \begin_inset Quotes srd
2053 \end_inset
2054
2055 /sdcc
2056 \begin_inset Quotes srd
2057 \end_inset
2058
2059
2060 \backslash
2061
2062 \newline
2063 docdir=
2064 \begin_inset Quotes srd
2065 \end_inset
2066
2067 /sdcc/doc
2068 \begin_inset Quotes srd
2069 \end_inset
2070
2071
2072 \backslash
2073
2074 \newline
2075 include_dir_suffix=
2076 \begin_inset Quotes srd
2077 \end_inset
2078
2079 include
2080 \begin_inset Quotes srd
2081 \end_inset
2082
2083
2084 \backslash
2085
2086 \newline
2087 lib_dir_suffix=
2088 \begin_inset Quotes srd
2089 \end_inset
2090
2091 lib
2092 \begin_inset Quotes srd
2093 \end_inset
2094
2095
2096 \backslash
2097
2098 \newline
2099 sdccconf_h_dir_separator=
2100 \begin_inset Quotes srd
2101 \end_inset
2102
2103
2104 \backslash
2105
2106 \backslash
2107
2108 \backslash
2109
2110 \backslash
2111
2112 \begin_inset Quotes srd
2113 \end_inset
2114
2115
2116 \backslash
2117
2118 \newline
2119 -
2120 \begin_inset ERT
2121 status Collapsed
2122
2123 \layout Standard
2124
2125 \backslash
2126 /
2127 \end_inset
2128
2129 -disable-ucsim
2130 \layout Standard
2131
2132 'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
2133  The option '-
2134 \begin_inset ERT
2135 status Collapsed
2136
2137 \layout Standard
2138
2139 \backslash
2140 /
2141 \end_inset
2142
2143 -C' turns on caching, which gives a little bit extra speed.
2144  However if options are changed, it can be necessary to delete the config.cache
2145  file.
2146 \layout Section
2147
2148 Install paths
2149 \begin_inset LatexCommand \label{sub:Install-paths}
2150
2151 \end_inset
2152
2153
2154 \begin_inset LatexCommand \index{Install paths}
2155
2156 \end_inset
2157
2158
2159 \layout Standard
2160 \added_space_top medskip \align center
2161
2162 \begin_inset  Tabular
2163 <lyxtabular version="3" rows="5" columns="4">
2164 <features>
2165 <column alignment="left" valignment="top" leftline="true" width="0">
2166 <column alignment="left" valignment="top" leftline="true" width="0">
2167 <column alignment="left" valignment="top" leftline="true" width="0">
2168 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
2169 <row topline="true" bottomline="true">
2170 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2171 \begin_inset Text
2172
2173 \layout Standard
2174
2175
2176 \series bold
2177 Description
2178 \end_inset
2179 </cell>
2180 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2181 \begin_inset Text
2182
2183 \layout Standard
2184
2185
2186 \series bold
2187 Path
2188 \end_inset
2189 </cell>
2190 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2191 \begin_inset Text
2192
2193 \layout Standard
2194
2195
2196 \series bold
2197 Default
2198 \end_inset
2199 </cell>
2200 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2201 \begin_inset Text
2202
2203 \layout Standard
2204
2205
2206 \series bold
2207 Win32 builds
2208 \end_inset
2209 </cell>
2210 </row>
2211 <row topline="true">
2212 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2213 \begin_inset Text
2214
2215 \layout Standard
2216
2217 Binary files*
2218 \end_inset
2219 </cell>
2220 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2221 \begin_inset Text
2222
2223 \layout Standard
2224
2225
2226 \emph on
2227 $EXEC_PREFIX
2228 \end_inset
2229 </cell>
2230 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2231 \begin_inset Text
2232
2233 \layout Standard
2234
2235 /usr/local/bin
2236 \end_inset
2237 </cell>
2238 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2239 \begin_inset Text
2240
2241 \layout Standard
2242
2243
2244 \backslash
2245 sdcc
2246 \backslash
2247 bin
2248 \end_inset
2249 </cell>
2250 </row>
2251 <row topline="true">
2252 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2253 \begin_inset Text
2254
2255 \layout Standard
2256
2257 Include files
2258 \end_inset
2259 </cell>
2260 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2261 \begin_inset Text
2262
2263 \layout Standard
2264
2265
2266 \emph on
2267 $DATADIR/ $INCLUDE_DIR_SUFFIX
2268 \end_inset
2269 </cell>
2270 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2271 \begin_inset Text
2272
2273 \layout Standard
2274
2275 /usr/local/share/sdcc/include
2276 \end_inset
2277 </cell>
2278 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2279 \begin_inset Text
2280
2281 \layout Standard
2282
2283
2284 \backslash
2285 sdcc
2286 \backslash
2287 include
2288 \end_inset
2289 </cell>
2290 </row>
2291 <row topline="true">
2292 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2293 \begin_inset Text
2294
2295 \layout Standard
2296
2297 Library file**
2298 \end_inset
2299 </cell>
2300 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2301 \begin_inset Text
2302
2303 \layout Standard
2304
2305
2306 \emph on
2307 $DATADIR/$LIB_DIR_SUFFIX
2308 \end_inset
2309 </cell>
2310 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2311 \begin_inset Text
2312
2313 \layout Standard
2314
2315 /usr/local/share/sdcc/lib
2316 \end_inset
2317 </cell>
2318 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2319 \begin_inset Text
2320
2321 \layout Standard
2322
2323
2324 \backslash
2325 sdcc
2326 \backslash
2327 lib
2328 \end_inset
2329 </cell>
2330 </row>
2331 <row topline="true" bottomline="true">
2332 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2333 \begin_inset Text
2334
2335 \layout Standard
2336
2337 Documentation
2338 \end_inset
2339 </cell>
2340 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2341 \begin_inset Text
2342
2343 \layout Standard
2344
2345
2346 \emph on
2347 $DOCDIR
2348 \end_inset
2349 </cell>
2350 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2351 \begin_inset Text
2352
2353 \layout Standard
2354
2355 /usr/local/share/sdcc/doc
2356 \end_inset
2357 </cell>
2358 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2359 \begin_inset Text
2360
2361 \layout Standard
2362
2363
2364 \backslash
2365 sdcc
2366 \backslash
2367 doc
2368 \end_inset
2369 </cell>
2370 </row>
2371 </lyxtabular>
2372
2373 \end_inset
2374
2375
2376 \layout Verse
2377
2378
2379 \size footnotesize
2380 *compiler, preprocessor, assembler, and linker
2381 \newline
2382 **the
2383 \shape italic
2384 model
2385 \shape default
2386  is auto-appended by the compiler, e.g.
2387  small, large, z80, ds390 etc
2388 \layout Standard
2389 \noindent
2390 The install paths can still be changed during `make install` with e.g.:
2391 \layout LyX-Code
2392
2393 make install prefix=$(HOME)/local/sdcc
2394 \layout Standard
2395
2396 Of course this doesn't change the search paths compiled into the binaries.
2397 \newline
2398
2399 \newline
2400 Moreover the install path can be changed by defining DESTDIR
2401 \begin_inset LatexCommand \index{DESTDIR}
2402
2403 \end_inset
2404
2405 :
2406 \layout LyX-Code
2407
2408 make install DESTDIR=$(HOME)/sdcc.rpm/
2409 \layout Standard
2410
2411 Please note that DESTDIR must have a trailing slash!
2412 \layout Section
2413
2414 Search Paths
2415 \begin_inset LatexCommand \label{sub:Search-Paths}
2416
2417 \end_inset
2418
2419
2420 \begin_inset LatexCommand \index{Search path}
2421
2422 \end_inset
2423
2424
2425 \layout Standard
2426
2427 Some search paths or parts of them are determined by configure variables
2428  (in
2429 \emph on
2430 italics
2431 \emph default
2432 , see section above).
2433  Further search paths are determined by environment variables during runtime.
2434
2435 \newline
2436 The paths searched when running the compiler are as follows (the first catch
2437  wins):
2438 \newline
2439
2440 \newline
2441 1.
2442  Binary files (preprocessor, assembler and linker)
2443 \newline
2444
2445 \layout Standard
2446 \align center
2447
2448 \begin_inset  Tabular
2449 <lyxtabular version="3" rows="4" columns="3">
2450 <features>
2451 <column alignment="block" valignment="top" leftline="true" width="0in">
2452 <column alignment="block" valignment="top" leftline="true" width="0in">
2453 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2454 <row topline="true" bottomline="true">
2455 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2456 \begin_inset Text
2457
2458 \layout Standard
2459
2460 Search path
2461 \end_inset
2462 </cell>
2463 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2464 \begin_inset Text
2465
2466 \layout Standard
2467
2468 default
2469 \end_inset
2470 </cell>
2471 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2472 \begin_inset Text
2473
2474 \layout Standard
2475
2476 Win32 builds
2477 \end_inset
2478 </cell>
2479 </row>
2480 <row topline="true">
2481 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2482 \begin_inset Text
2483
2484 \layout Standard
2485
2486 $SDCC_HOME/
2487 \emph on
2488 $PPREFIX2BIN_DIR
2489 \end_inset
2490 </cell>
2491 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2492 \begin_inset Text
2493
2494 \layout Standard
2495
2496 $SDCC_HOME/bin
2497 \end_inset
2498 </cell>
2499 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2500 \begin_inset Text
2501
2502 \layout Standard
2503
2504 $SDCC_HOME
2505 \backslash
2506 bin
2507 \end_inset
2508 </cell>
2509 </row>
2510 <row topline="true">
2511 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2512 \begin_inset Text
2513
2514 \layout Standard
2515
2516 Path of argv[0] (if available)
2517 \end_inset
2518 </cell>
2519 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2520 \begin_inset Text
2521
2522 \layout Standard
2523
2524 Path of argv[0]
2525 \end_inset
2526 </cell>
2527 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2528 \begin_inset Text
2529
2530 \layout Standard
2531
2532 Path of argv[0]
2533 \end_inset
2534 </cell>
2535 </row>
2536 <row topline="true" bottomline="true">
2537 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2538 \begin_inset Text
2539
2540 \layout Standard
2541
2542 $PATH
2543 \end_inset
2544 </cell>
2545 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2546 \begin_inset Text
2547
2548 \layout Standard
2549
2550 $PATH
2551 \end_inset
2552 </cell>
2553 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2554 \begin_inset Text
2555
2556 \layout Standard
2557
2558 $PATH
2559 \end_inset
2560 </cell>
2561 </row>
2562 </lyxtabular>
2563
2564 \end_inset
2565
2566
2567 \newline
2568
2569 \layout Standard
2570 \noindent
2571 2.
2572  Include files
2573 \newline
2574
2575 \layout Standard
2576 \align center
2577
2578 \begin_inset  Tabular
2579 <lyxtabular version="3" rows="6" columns="3">
2580 <features>
2581 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2582 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2583 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2584 <row topline="true" bottomline="true">
2585 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2586 \begin_inset Text
2587
2588 \layout Standard
2589
2590 Search path
2591 \end_inset
2592 </cell>
2593 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2594 \begin_inset Text
2595
2596 \layout Standard
2597
2598 default
2599 \end_inset
2600 </cell>
2601 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2602 \begin_inset Text
2603
2604 \layout Standard
2605
2606 Win32 builds
2607 \end_inset
2608 </cell>
2609 </row>
2610 <row topline="true">
2611 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2612 \begin_inset Text
2613
2614 \layout Standard
2615
2616 -
2617 \begin_inset ERT
2618 status Collapsed
2619
2620 \layout Standard
2621
2622 \backslash
2623 /
2624 \end_inset
2625
2626 -I dir
2627 \end_inset
2628 </cell>
2629 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2630 \begin_inset Text
2631
2632 \layout Standard
2633
2634 -
2635 \begin_inset ERT
2636 status Collapsed
2637
2638 \layout Standard
2639
2640 \backslash
2641 /
2642 \end_inset
2643
2644 -I dir
2645 \end_inset
2646 </cell>
2647 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2648 \begin_inset Text
2649
2650 \layout Standard
2651
2652 -
2653 \begin_inset ERT
2654 status Collapsed
2655
2656 \layout Standard
2657
2658 \backslash
2659 /
2660 \end_inset
2661
2662 -I dir
2663 \end_inset
2664 </cell>
2665 </row>
2666 <row topline="true">
2667 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2668 \begin_inset Text
2669
2670 \layout Standard
2671
2672 $SDCC_INCLUDE
2673 \end_inset
2674 </cell>
2675 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2676 \begin_inset Text
2677
2678 \layout Standard
2679
2680 $SDCC_INCLUDE
2681 \end_inset
2682 </cell>
2683 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2684 \begin_inset Text
2685
2686 \layout Standard
2687
2688 $SDCC_INCLUDE
2689 \end_inset
2690 </cell>
2691 </row>
2692 <row topline="true">
2693 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2694 \begin_inset Text
2695
2696 \layout Standard
2697
2698 $SDCC_HOME/
2699 \newline
2700
2701 \emph on
2702 $PREFIX2DATA_DIR/
2703 \newline
2704 $INCLUDE_DIR_SUFFIX
2705 \end_inset
2706 </cell>
2707 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2708 \begin_inset Text
2709
2710 \layout Standard
2711
2712 $SDCC_ HOME/
2713 \newline
2714 share/sdcc/
2715 \newline
2716 include
2717 \end_inset
2718 </cell>
2719 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2720 \begin_inset Text
2721
2722 \layout Standard
2723
2724 $SDCC_HOME
2725 \backslash
2726 include
2727 \end_inset
2728 </cell>
2729 </row>
2730 <row topline="true">
2731 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2732 \begin_inset Text
2733
2734 \layout Standard
2735
2736 path(argv[0])/
2737 \newline
2738
2739 \emph on
2740 $BIN2DATADIR/
2741 \emph default
2742
2743 \newline
2744
2745 \emph on
2746 $INCLUDE_DIR_SUFFIX
2747 \end_inset
2748 </cell>
2749 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2750 \begin_inset Text
2751
2752 \layout Standard
2753
2754 path(argv[0])/
2755 \newline
2756 ../sdcc/include
2757 \newline
2758 \SpecialChar ~
2759 \SpecialChar ~
2760 \SpecialChar ~
2761 \SpecialChar ~
2762 \SpecialChar ~
2763 \SpecialChar ~
2764 \SpecialChar ~
2765 \SpecialChar ~
2766 \SpecialChar ~
2767 \SpecialChar ~
2768 \SpecialChar ~
2769 \SpecialChar ~
2770 \SpecialChar ~
2771 \SpecialChar ~
2772 \SpecialChar ~
2773 \SpecialChar ~
2774 \SpecialChar ~
2775 \SpecialChar ~
2776 \SpecialChar ~
2777 \SpecialChar ~
2778 \SpecialChar ~
2779 \SpecialChar ~
2780 \SpecialChar ~
2781 \SpecialChar ~
2782 \SpecialChar ~
2783 \SpecialChar ~
2784 \SpecialChar ~
2785 \SpecialChar ~
2786 \SpecialChar ~
2787 \SpecialChar ~
2788 \SpecialChar ~
2789 \SpecialChar ~
2790 \SpecialChar ~
2791 \SpecialChar ~
2792 \SpecialChar ~
2793 \SpecialChar ~
2794 \SpecialChar ~
2795 \SpecialChar ~
2796
2797 \end_inset
2798 </cell>
2799 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2800 \begin_inset Text
2801
2802 \layout Standard
2803
2804 path(argv[0])
2805 \backslash
2806 ..
2807 \backslash
2808 include
2809 \end_inset
2810 </cell>
2811 </row>
2812 <row topline="true" bottomline="true">
2813 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2814 \begin_inset Text
2815
2816 \layout Standard
2817
2818
2819 \emph on
2820 $DATADIR/
2821 \emph default
2822
2823 \newline
2824
2825 \emph on
2826 $INCLUDE_DIR_SUFFIX
2827 \end_inset
2828 </cell>
2829 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2830 \begin_inset Text
2831
2832 \layout Standard
2833
2834 /usr/local/share/sdcc/
2835 \newline
2836 include
2837 \end_inset
2838 </cell>
2839 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2840 \begin_inset Text
2841
2842 \layout Standard
2843
2844 (not on Win32)
2845 \end_inset
2846 </cell>
2847 </row>
2848 </lyxtabular>
2849
2850 \end_inset
2851
2852
2853 \newline
2854
2855 \layout Standard
2856 \noindent
2857 The option -
2858 \begin_inset ERT
2859 status Collapsed
2860
2861 \layout Standard
2862
2863 \backslash
2864 /
2865 \end_inset
2866
2867 -nostdinc disables the last two search paths.
2868 \newline
2869
2870 \newline
2871 3.
2872  Library files
2873 \newline
2874
2875 \layout Standard
2876
2877 With the exception of
2878 \begin_inset Quotes sld
2879 \end_inset
2880
2881 -
2882 \begin_inset ERT
2883 status Collapsed
2884
2885 \layout Standard
2886
2887 \backslash
2888 /
2889 \end_inset
2890
2891 -L dir
2892 \begin_inset Quotes srd
2893 \end_inset
2894
2895  the
2896 \shape italic
2897 model
2898 \shape default
2899  is auto-appended by the compiler (e.g.
2900  small, large, z80, ds390 etc.).
2901
2902 \newline
2903
2904 \layout Standard
2905 \align center
2906
2907 \begin_inset  Tabular
2908 <lyxtabular version="3" rows="6" columns="3">
2909 <features>
2910 <column alignment="block" valignment="top" leftline="true" width="1.7in">
2911 <column alignment="block" valignment="top" leftline="true" width="1.2in">
2912 <column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
2913 <row topline="true" bottomline="true">
2914 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2915 \begin_inset Text
2916
2917 \layout Standard
2918
2919 Search path
2920 \end_inset
2921 </cell>
2922 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2923 \begin_inset Text
2924
2925 \layout Standard
2926
2927 default
2928 \end_inset
2929 </cell>
2930 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2931 \begin_inset Text
2932
2933 \layout Standard
2934
2935 Win32 builds
2936 \end_inset
2937 </cell>
2938 </row>
2939 <row topline="true">
2940 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2941 \begin_inset Text
2942
2943 \layout Standard
2944
2945 -
2946 \begin_inset ERT
2947 status Collapsed
2948
2949 \layout Standard
2950
2951 \backslash
2952 /
2953 \end_inset
2954
2955 -L dir
2956 \end_inset
2957 </cell>
2958 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2959 \begin_inset Text
2960
2961 \layout Standard
2962
2963 -
2964 \begin_inset ERT
2965 status Collapsed
2966
2967 \layout Standard
2968
2969 \backslash
2970 /
2971 \end_inset
2972
2973 -L dir
2974 \end_inset
2975 </cell>
2976 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2977 \begin_inset Text
2978
2979 \layout Standard
2980
2981 -
2982 \begin_inset ERT
2983 status Collapsed
2984
2985 \layout Standard
2986
2987 \backslash
2988 /
2989 \end_inset
2990
2991 -L dir
2992 \end_inset
2993 </cell>
2994 </row>
2995 <row topline="true">
2996 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2997 \begin_inset Text
2998
2999 \layout Standard
3000
3001 $SDCC_LIB/
3002 \newline
3003
3004 \emph on
3005 <model>
3006 \end_inset
3007 </cell>
3008 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3009 \begin_inset Text
3010
3011 \layout Standard
3012
3013 $SDCC_LIB/
3014 \newline
3015
3016 \emph on
3017 <model>
3018 \end_inset
3019 </cell>
3020 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3021 \begin_inset Text
3022
3023 \layout Standard
3024
3025 $SDCC_LIB
3026 \backslash
3027
3028 \newline
3029
3030 \emph on
3031 <model>
3032 \end_inset
3033 </cell>
3034 </row>
3035 <row topline="true">
3036 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3037 \begin_inset Text
3038
3039 \layout Standard
3040
3041 $SDCC_HOME/
3042 \newline
3043
3044 \emph on
3045 $PREFIX2DATA_DIR/
3046 \newline
3047 $LIB_DIR_SUFFIX/<model>
3048 \end_inset
3049 </cell>
3050 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3051 \begin_inset Text
3052
3053 \layout Standard
3054
3055 $SDCC_HOME/
3056 \newline
3057 share/sdcc/
3058 \newline
3059 lib/
3060 \emph on
3061 <model>
3062 \end_inset
3063 </cell>
3064 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3065 \begin_inset Text
3066
3067 \layout Standard
3068
3069 $SDCC_HOME
3070 \backslash
3071 lib
3072 \backslash
3073
3074 \emph on
3075
3076 \newline
3077 <model>
3078 \end_inset
3079 </cell>
3080 </row>
3081 <row topline="true">
3082 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3083 \begin_inset Text
3084
3085 \layout Standard
3086
3087 path(argv[0])/
3088 \newline
3089
3090 \emph on
3091 $BIN2DATADIR/
3092 \emph default
3093
3094 \newline
3095
3096 \emph on
3097 $LIB_DIR_SUFFIX/<model>
3098 \end_inset
3099 </cell>
3100 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3101 \begin_inset Text
3102
3103 \layout Standard
3104
3105 path(argv[0])/
3106 \newline
3107 ../sdcc/lib/
3108 \emph on
3109 <model>
3110 \newline
3111 \SpecialChar ~
3112 \SpecialChar ~
3113 \SpecialChar ~
3114 \SpecialChar ~
3115 \SpecialChar ~
3116 \SpecialChar ~
3117 \SpecialChar ~
3118 \SpecialChar ~
3119 \SpecialChar ~
3120 \SpecialChar ~
3121 \SpecialChar ~
3122 \SpecialChar ~
3123 \SpecialChar ~
3124 \SpecialChar ~
3125 \SpecialChar ~
3126 \SpecialChar ~
3127 \SpecialChar ~
3128 \SpecialChar ~
3129 \SpecialChar ~
3130 \SpecialChar ~
3131 \SpecialChar ~
3132 \SpecialChar ~
3133 \SpecialChar ~
3134 \SpecialChar ~
3135 \SpecialChar ~
3136 \SpecialChar ~
3137 \SpecialChar ~
3138 \SpecialChar ~
3139 \SpecialChar ~
3140 \SpecialChar ~
3141 \SpecialChar ~
3142 \SpecialChar ~
3143 \SpecialChar ~
3144 \SpecialChar ~
3145 \SpecialChar ~
3146 \SpecialChar ~
3147 \SpecialChar ~
3148 \SpecialChar ~
3149 \SpecialChar ~
3150
3151 \end_inset
3152 </cell>
3153 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3154 \begin_inset Text
3155
3156 \layout Standard
3157
3158 path(argv[0])
3159 \backslash
3160
3161 \newline
3162 ..
3163 \backslash
3164 lib
3165 \backslash
3166
3167 \emph on
3168 <model>
3169 \newline
3170 \SpecialChar ~
3171 \SpecialChar ~
3172 \SpecialChar ~
3173 \SpecialChar ~
3174 \SpecialChar ~
3175 \SpecialChar ~
3176 \SpecialChar ~
3177 \SpecialChar ~
3178 \SpecialChar ~
3179 \SpecialChar ~
3180 \SpecialChar ~
3181 \SpecialChar ~
3182 \SpecialChar ~
3183 \SpecialChar ~
3184 \SpecialChar ~
3185 \SpecialChar ~
3186 \SpecialChar ~
3187 \SpecialChar ~
3188 \SpecialChar ~
3189 \SpecialChar ~
3190 \SpecialChar ~
3191 \SpecialChar ~
3192 \SpecialChar ~
3193 \SpecialChar ~
3194 \SpecialChar ~
3195 \SpecialChar ~
3196 \SpecialChar ~
3197 \SpecialChar ~
3198 \SpecialChar ~
3199 \SpecialChar ~
3200 \SpecialChar ~
3201 \SpecialChar ~
3202 \SpecialChar ~
3203 \SpecialChar ~
3204 \SpecialChar ~
3205
3206 \end_inset
3207 </cell>
3208 </row>
3209 <row topline="true" bottomline="true">
3210 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3211 \begin_inset Text
3212
3213 \layout Standard
3214
3215
3216 \emph on
3217 $DATADIR/
3218 \newline
3219 $LIB_DIR_SUFFIX/<model>
3220 \end_inset
3221 </cell>
3222 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3223 \begin_inset Text
3224
3225 \layout Standard
3226
3227 /usr/local/share/sdcc/
3228 \newline
3229 lib/
3230 \emph on
3231 <model>
3232 \end_inset
3233 </cell>
3234 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3235 \begin_inset Text
3236
3237 \layout Standard
3238
3239 (not on Win32)
3240 \end_inset
3241 </cell>
3242 </row>
3243 </lyxtabular>
3244
3245 \end_inset
3246
3247
3248 \newline
3249
3250 \layout Comment
3251
3252 Don't delete any of the stray spaces in the table above without checking
3253  the HTML output (last line)!
3254 \layout Standard
3255
3256 \SpecialChar ~
3257
3258 \newline
3259 The option -
3260 \begin_inset ERT
3261 status Collapsed
3262
3263 \layout Standard
3264
3265 \backslash
3266 /
3267 \end_inset
3268
3269 -nostdlib disables the last two search paths.
3270 \layout Section
3271
3272 Building SDCC
3273 \begin_inset LatexCommand \index{Building SDCC}
3274
3275 \end_inset
3276
3277
3278 \layout Subsection
3279
3280 Building SDCC on Linux
3281 \begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux}
3282
3283 \end_inset
3284
3285
3286 \layout Enumerate
3287
3288
3289 \series medium
3290 Download the source package
3291 \series default
3292  either from the SDCC Subversion repository or from the nightly snapshots
3293 \series medium
3294 , it will be named something like sdcc
3295 \series default
3296 .src
3297 \series medium
3298 .t
3299 \series default
3300 ar.
3301 \series medium
3302 gz
3303 \series default
3304
3305 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
3306
3307 \end_inset
3308
3309 .
3310 \layout Enumerate
3311
3312
3313 \series medium
3314 Bring up a command line terminal, such as xterm.
3315 \layout Enumerate
3316
3317
3318 \series medium
3319 Unpack the file using a command like:
3320 \family sans
3321 \series bold
3322 "tar -xvzf sdcc.src.tar.gz
3323 \family default
3324 \series default
3325 "
3326 \series medium
3327 , this will create a sub-directory called sdcc with all of the sources.
3328 \layout Enumerate
3329
3330 Change directory into the main SDCC directory, for example type:
3331 \family sans
3332 \series bold
3333 "cd sdcc
3334 \series default
3335 ".
3336 \layout Enumerate
3337
3338
3339 \series medium
3340 Type
3341 \family sans
3342 \series bold
3343 "./configure
3344 \family default
3345 \series default
3346 ".
3347  This configures the package for compilation on your system.
3348 \layout Enumerate
3349
3350
3351 \series medium
3352 Type
3353 \family sans
3354 \series bold
3355 "make
3356 \family default
3357 \series default
3358 "
3359 \series medium
3360 .
3361
3362 \series default
3363  All of the source packages will compile, this can take a while.
3364 \layout Enumerate
3365
3366
3367 \series medium
3368 Type
3369 \family sans
3370 \series bold
3371 "make install"
3372 \family default
3373 \series default
3374  as root
3375 \series medium
3376 .
3377
3378 \series default
3379  This copies the binary executables, the include files, the libraries and
3380  the documentation to the install directories.
3381  Proceed with section
3382 \begin_inset LatexCommand \ref{sec:Testing-the-SDCC}
3383
3384 \end_inset
3385
3386 .
3387 \layout Subsection
3388
3389 Building SDCC on OSX 2.x
3390 \layout Standard
3391
3392 Follow the instruction for Linux.
3393 \newline
3394
3395 \newline
3396 On OSX 2.x it was reported, that the default gcc (version 3.1 20020420 (prerelease
3397 )) fails to compile SDCC.
3398  Fortunately there's also gcc 2.9.x installed, which works fine.
3399  This compiler can be selected by running 'configure' with:
3400 \layout LyX-Code
3401
3402 ./configure CC=gcc2 CXX=g++2
3403 \layout Subsection
3404
3405 Cross compiling SDCC on Linux for Windows
3406 \layout Standard
3407
3408 With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
3409  See section 'Configure Options'.
3410 \layout Subsection
3411
3412 Building SDCC on Windows
3413 \layout Standard
3414
3415 With the exception of Cygwin the SDCC binaries uCsim and sdcdb can't be
3416  built on Windows.
3417  They use Unix-sockets, which are not available on Win32.
3418 \layout Subsection
3419
3420 Building SDCC using Cygwin and Mingw32
3421 \layout Standard
3422
3423 For building and installing a Cygwin executable follow the instructions
3424  for Linux.
3425 \newline
3426
3427 \newline
3428 On Cygwin a
3429 \begin_inset Quotes sld
3430 \end_inset
3431
3432 native
3433 \begin_inset Quotes srd
3434 \end_inset
3435
3436  Win32-binary can be built, which will not need the Cygwin-DLL.
3437  For the necessary 'configure' options see section 'configure options' or
3438  the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'.
3439 \newline
3440
3441 \newline
3442 In order to install Cygwin on Windows download setup.exe from
3443 \begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
3444
3445 \end_inset
3446
3447 .
3448  Run it, set the
3449 \begin_inset Quotes sld
3450 \end_inset
3451
3452 default text file type
3453 \begin_inset Quotes srd
3454 \end_inset
3455
3456  to
3457 \begin_inset Quotes sld
3458 \end_inset
3459
3460 unix
3461 \begin_inset Quotes srd
3462 \end_inset
3463
3464  and download/install at least the following packages.
3465  Some packages are selected by default, others will be automatically selected
3466  because of dependencies with the manually selected packages.
3467  Never deselect these packages!
3468 \layout Itemize
3469
3470 flex
3471 \layout Itemize
3472
3473 bison
3474 \layout Itemize
3475
3476 gcc ; version 3.x is fine, no need to use the old 2.9x
3477 \layout Itemize
3478
3479 binutils ; selected with gcc
3480 \layout Itemize
3481
3482 make
3483 \layout Itemize
3484
3485 rxvt ; a nice console, which makes life much easier under windoze (see below)
3486 \layout Itemize
3487
3488 man ; not really needed for building SDCC, but you'll miss it sooner or
3489  later
3490 \layout Itemize
3491
3492 less ; not really needed for building SDCC, but you'll miss it sooner or
3493  later
3494 \layout Itemize
3495
3496 svn ; only if you use Subversion access
3497 \layout Standard
3498
3499 If you want to develop something you'll need:
3500 \layout Itemize
3501
3502 python ; for the regression tests
3503 \layout Itemize
3504
3505 gdb ; the gnu debugger, together with the nice GUI
3506 \begin_inset Quotes sld
3507 \end_inset
3508
3509 insight
3510 \begin_inset Quotes srd
3511 \end_inset
3512
3513
3514 \layout Itemize
3515
3516 openssh ; to access the CF or commit changes
3517 \layout Itemize
3518
3519 autoconf and autoconf-devel ; if you want to fight with 'configure', don't
3520  use autoconf-stable!
3521 \layout Standard
3522
3523 rxvt is a nice console with history.
3524  Replace in your cygwin.bat the line
3525 \layout LyX-Code
3526
3527 bash -
3528 \begin_inset ERT
3529 status Collapsed
3530
3531 \layout Standard
3532
3533 \backslash
3534 /
3535 \end_inset
3536
3537 -login -i
3538 \layout Standard
3539
3540 with (one line):
3541 \layout LyX-Code
3542
3543 rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
3544 \layout LyX-Code
3545
3546      -bg black -fg white -geometry 100x65 -e bash -
3547 \begin_inset ERT
3548 status Collapsed
3549
3550 \layout Standard
3551
3552 \backslash
3553 /
3554 \end_inset
3555
3556 -login
3557 \layout Standard
3558
3559 Text selected with the mouse is automatically copied to the clipboard, pasting
3560  works with shift-insert.
3561 \newline
3562
3563 \newline
3564 The other good tip is to make sure you have no //c/-style paths anywhere,
3565  use /cygdrive/c/ instead.
3566  Using // invokes a network lookup which is very slow.
3567  If you think
3568 \begin_inset Quotes sld
3569 \end_inset
3570
3571 cygdrive
3572 \begin_inset Quotes srd
3573 \end_inset
3574
3575  is too long, you can change it with e.g.
3576 \layout LyX-Code
3577
3578 mount -s -u -c /mnt
3579 \layout Standard
3580
3581 SDCC sources use the unix line ending LF.
3582  Life is much easier, if you store the source tree on a drive which is mounted
3583  in binary mode.
3584  And use an editor which can handle LF-only line endings.
3585  Make sure not to commit files with windows line endings.
3586  The tabulator spacing
3587 \begin_inset LatexCommand \index{tabulator spacing (8 columns)}
3588
3589 \end_inset
3590
3591  used in the project is 8.
3592  Although a tabulator spacing of 8 is a sensible choice for programmers
3593  (it's a power of 2 and allows to display 8/16 bit signed variables without
3594  loosing columns) the plan is to move towards using only spaces in the source.
3595 \layout Subsection
3596
3597 Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
3598 \layout Standard
3599
3600
3601 \series medium
3602 Download the source package
3603 \series default
3604  either from the SDCC Subversion repository or from the
3605 \begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
3606
3607 \end_inset
3608
3609
3610 \series medium
3611 , it will be named something like sdcc
3612 \series default
3613 .src
3614 \series medium
3615 .tgz.
3616
3617 \series default
3618  SDCC is distributed with all the projects, workspaces, and files you need
3619  to build it using Visual C++ 6.0/NET (except for sdcdb.exe which currently
3620  doesn't build under MSVC).
3621  The workspace name is 'sdcc.dsw'.
3622  Please note that as it is now, all the executables are created in a folder
3623  called sdcc
3624 \backslash
3625 bin_vc.
3626  Once built you need to copy the executables from sdcc
3627 \backslash
3628 bin_vc to sdcc
3629 \backslash
3630 bin before running SDCC.
3631
3632 \newline
3633
3634 \newline
3635 WARNING: Visual studio is very picky with line terminations; it expects
3636  the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings.
3637  When using the Subversion repository it's easiest to configure the svn
3638  client to convert automatically for you.
3639  If however you are getting a message such as "This makefile was not generated
3640  by Developer Studio etc.
3641  etc.
3642 \begin_inset Quotes srd
3643 \end_inset
3644
3645  when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
3646  need to convert the Unix style line endings to DOS style line endings.
3647  To do so you can use the
3648 \begin_inset Quotes sld
3649 \end_inset
3650
3651 unix2dos
3652 \begin_inset Quotes srd
3653 \end_inset
3654
3655  utility freely available on the internet.
3656  Doug Hawkins reported in the sdcc-user list that this works:
3657 \newline
3658
3659 \newline
3660 C:
3661 \backslash
3662 Programming
3663 \backslash
3664 SDCC> unix2dos sdcc.dsw
3665 \newline
3666 C:
3667 \backslash
3668 Programming
3669 \backslash
3670 SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
3671 \newline
3672
3673 \newline
3674 In order to build SDCC with MSVC you need win32 executables of bison.exe,
3675  flex.exe, and gawk.exe.
3676  One good place to get them is
3677 \begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
3678
3679 \end_inset
3680
3681
3682 \newline
3683
3684 \newline
3685 Download the file UnxUtils
3686 \begin_inset LatexCommand \index{UnxUtils}
3687
3688 \end_inset
3689
3690 .zip.
3691  Now you have to install the utilities and setup MSVC so it can locate the
3692  required programs.
3693  Here there are two alternatives (choose one!):
3694 \layout Enumerate
3695
3696 The easy way:
3697 \newline
3698
3699 \newline
3700 a) Extract UnxUtils.zip to your C:
3701 \backslash
3702  hard disk PRESERVING the original paths, otherwise bison won't work.
3703  (If you are using WinZip make certain that 'Use folder names' is selected)
3704 \newline
3705
3706 \newline
3707 b) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3708  in 'Show directories for:' select 'Executable files', and in the directories
3709  window add a new path: 'C:
3710 \backslash
3711 user
3712 \backslash
3713 local
3714 \backslash
3715 wbin', click ok.
3716 \newline
3717
3718 \newline
3719 (As a side effect, you get a bunch of Unix utilities that could be useful,
3720  such as diff and patch.)
3721 \layout Enumerate
3722
3723 A more compact way:
3724 \newline
3725
3726 \newline
3727 This one avoids extracting a bunch of files you may not use, but requires
3728  some extra work:
3729 \newline
3730
3731 \newline
3732 a) Create a directory were to put the tools needed, or use a directory already
3733  present.
3734  Say for example 'C:
3735 \backslash
3736 util'.
3737 \newline
3738
3739 \newline
3740 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
3741  to such directory WITHOUT preserving the original paths.
3742  (If you are using WinZip make certain that 'Use folder names' is not selected)
3743 \newline
3744
3745 \newline
3746 c) Rename bison.exe to '_bison.exe'.
3747 \newline
3748
3749 \newline
3750 d) Create a batch file 'bison.bat' in 'C:
3751 \backslash
3752 util
3753 \backslash
3754 ' and add these lines:
3755 \newline
3756 \SpecialChar ~
3757 \SpecialChar ~
3758 set BISON_SIMPLE=C:
3759 \backslash
3760 util
3761 \backslash
3762 bison.simple
3763 \newline
3764 \SpecialChar ~
3765 \SpecialChar ~
3766 set BISON_HAIRY=C:
3767 \backslash
3768 util
3769 \backslash
3770 bison.hairy
3771 \newline
3772 \SpecialChar ~
3773 \SpecialChar ~
3774 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
3775 \newline
3776
3777 \newline
3778 Steps 'c' and 'd' are needed because bison requires by default that the
3779  files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory,
3780  '/usr/local/share/' I think.
3781  So it is necessary to tell bison where those files are located if they
3782  are not in such directory.
3783  That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
3784 \newline
3785
3786 \newline
3787 e) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3788  in 'Show directories for:' select 'Executable files', and in the directories
3789  window add a new path: 'c:
3790 \backslash
3791 util', click ok.
3792  Note that you can use any other path instead of 'c:
3793 \backslash
3794 util', even the path where the Visual C++ tools are, probably: 'C:
3795 \backslash
3796 Program Files
3797 \backslash
3798 Microsoft Visual Studio
3799 \backslash
3800 Common
3801 \backslash
3802 Tools'.
3803  So you don't have to execute step 'e' :)
3804 \layout Standard
3805
3806 That is it.
3807  Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
3808  the executables from sdcc
3809 \backslash
3810 bin_vc to sdcc
3811 \backslash
3812 bin, and you can compile using SDCC.
3813 \layout Subsection
3814
3815 Building SDCC Using Borland
3816 \layout Enumerate
3817
3818 From the sdcc directory, run the command "make -f Makefile.bcc".
3819  This should regenerate all the .exe files in the bin directory except for
3820  sdcdb.exe (which currently doesn't build under Borland C++).
3821 \layout Enumerate
3822
3823 If you modify any source files and need to rebuild, be aware that the dependenci
3824 es may not be correctly calculated.
3825  The safest option is to delete all .obj files and run the build again.
3826  From a Cygwin BASH prompt, this can easily be done with the command (be
3827  sure you are in the sdcc directory):
3828 \newline
3829
3830 \newline
3831
3832 \family sans
3833 \series bold
3834 find .
3835
3836 \backslash
3837 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
3838 \backslash
3839 ) -print -exec rm {}
3840 \backslash
3841 ;
3842 \family default
3843 \series default
3844
3845 \newline
3846
3847 \newline
3848 or on Windows NT/2000/XP from the command prompt with the command:
3849 \newline
3850
3851 \family sans
3852 \series bold
3853
3854 \newline
3855 del /s *.obj *.lib *.rul
3856 \family default
3857 \series default
3858  from the sdcc directory.
3859 \layout Subsection
3860
3861 Windows Install Using a ZIP Package
3862 \layout Enumerate
3863
3864 Download the binary zip package from
3865 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3866
3867 \end_inset
3868
3869  and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
3870  This should unpack to a group of sub-directories.
3871  An example directory structure after unpacking the mingw32 package is:
3872  c:
3873 \backslash
3874 sdcc
3875 \backslash
3876 bin for the executables, c:
3877 \backslash
3878 sdcc
3879 \backslash
3880 include and c:
3881 \backslash
3882 sdcc
3883 \backslash
3884 lib for the include and libraries.
3885 \layout Enumerate
3886
3887 Adjust your environment variable PATH to include the location of the bin
3888  directory or start sdcc using the full path.
3889 \layout Subsection
3890
3891 Windows Install Using the Setup Program
3892 \begin_inset LatexCommand \label{sub:Windows-Install}
3893
3894 \end_inset
3895
3896
3897 \layout Standard
3898
3899 Download the setup program
3900 \emph on
3901 sdcc-x.y.z-setup.exe
3902 \emph default
3903  for an official release from
3904 \newline
3905
3906 \begin_inset LatexCommand \url{http://sf.net/project/showfiles.php?group_id=599}
3907
3908 \end_inset
3909
3910  or a setup program for one of the snapshots
3911 \emph on
3912 sdcc-yyyymmdd-xxxx-setup.exe
3913 \emph default
3914  from
3915 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3916
3917 \end_inset
3918
3919  and execute it.
3920  A windows typical installer will guide you through the installation process.
3921 \layout Subsection
3922
3923 VPATH
3924 \begin_inset LatexCommand \index{VPATH}
3925
3926 \end_inset
3927
3928  feature
3929 \layout Standard
3930
3931 SDCC supports the VPATH feature provided by configure and make.
3932  It allows to separate the source and build trees.
3933  Here's an example:
3934 \layout Standard
3935
3936
3937 \family typewriter
3938 cd ~\SpecialChar ~
3939 \SpecialChar ~
3940 \SpecialChar ~
3941 \SpecialChar ~
3942 \SpecialChar ~
3943 \SpecialChar ~
3944 \SpecialChar ~
3945 \SpecialChar ~
3946 \SpecialChar ~
3947 \SpecialChar ~
3948 \SpecialChar ~
3949 \SpecialChar ~
3950 \SpecialChar ~
3951 \SpecialChar ~
3952 \SpecialChar ~
3953 \SpecialChar ~
3954 \SpecialChar ~
3955 \SpecialChar ~
3956 \SpecialChar ~
3957 \SpecialChar ~
3958 \SpecialChar ~
3959 # cd $HOME
3960 \layout Standard
3961
3962
3963 \family typewriter
3964 tar -xzf sdcc.src.tar.gz\SpecialChar ~
3965 # extract source to directory sdcc
3966 \layout Standard
3967
3968
3969 \family typewriter
3970 mkdir sdcc.build\SpecialChar ~
3971 \SpecialChar ~
3972 \SpecialChar ~
3973 \SpecialChar ~
3974 \SpecialChar ~
3975 \SpecialChar ~
3976 \SpecialChar ~
3977 \SpecialChar ~
3978 \SpecialChar ~
3979 # put output in sdcc.build
3980 \layout Standard
3981
3982
3983 \family typewriter
3984 cd sdcc.build
3985 \layout Standard
3986
3987
3988 \family typewriter
3989 ../sdcc/configure\SpecialChar ~
3990 \SpecialChar ~
3991 \SpecialChar ~
3992 \SpecialChar ~
3993 \SpecialChar ~
3994 \SpecialChar ~
3995 \SpecialChar ~
3996 \SpecialChar ~
3997 # configure is doing all the magic!
3998 \layout Standard
3999
4000
4001 \family typewriter
4002 make
4003 \layout Standard
4004 \noindent
4005 That's it!
4006 \series bold
4007 configure
4008 \series default
4009  will create the directory tree will all the necessary Makefiles in ~/sdcc.build.
4010  It automagically computes the variables srcdir, top_srcdir and top_buildir
4011  for each directory.
4012  After running
4013 \series bold
4014 make
4015 \series default
4016  the generated files will be in ~/sdcc.build, while the source files stay
4017  in ~/sdcc.
4018 \newline
4019 This is not only usefull for building different binaries, e.g.
4020  when cross compiling.
4021  It also gives you a much better overview in the source tree when all the
4022  generated files are not scattered between the source files.
4023  And the best thing is: if you want to change a file you can leave the original
4024  file untouched in the source directory.
4025  Simply copy it to the build directory, edit it, enter `make clean`, `rm
4026  Makefile.dep` and `make`.
4027
4028 \series bold
4029 make
4030 \series default
4031  will do the rest for you!
4032 \layout Section
4033
4034 Building the Documentation
4035 \layout Standard
4036
4037 Add -
4038 \begin_inset ERT
4039 status Collapsed
4040
4041 \layout Standard
4042
4043 \backslash
4044 /
4045 \end_inset
4046
4047 -enable-doc to the configure arguments to build the documentation together
4048  with all the other stuff.
4049  You will need several tools (LyX, LaTeX, LaTeX2HTML, pdflatex, dvipdf,
4050  dvips and makeindex) to get the job done.
4051  Another possibility is to change to the doc directory and to type
4052 \family sans
4053 \series bold
4054
4055 \begin_inset Quotes srd
4056 \end_inset
4057
4058 make
4059 \begin_inset Quotes srd
4060 \end_inset
4061
4062
4063 \family default
4064 \series default
4065  there.
4066  You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
4067 x).
4068  Using LyX
4069 \begin_inset LatexCommand \url{http://www.lyx.org}
4070
4071 \end_inset
4072
4073  as editor is straightforward.
4074  Prebuilt documentation in html and pdf format is available from
4075 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
4076
4077 \end_inset
4078
4079 .
4080 \layout Section
4081
4082 Reading the Documentation
4083 \layout Standard
4084
4085 Currently reading the document in pdf format is recommended, as for unknown
4086  reason the hyperlinks are working there whereas in the html version they
4087  are not
4088 \begin_inset Foot
4089 collapsed false
4090
4091 \layout Standard
4092
4093 If you should know why please drop us a note
4094 \end_inset
4095
4096 .
4097
4098 \newline
4099 You'll find the pdf version
4100 \begin_inset LatexCommand \index{PDF version of this document}
4101
4102 \end_inset
4103
4104  at
4105 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.pdf}
4106
4107 \end_inset
4108
4109 .
4110
4111 \newline
4112 A html version
4113 \begin_inset LatexCommand \index{HTML version of this document}
4114
4115 \end_inset
4116
4117  should be online at
4118 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.html/index.html}
4119
4120 \end_inset
4121
4122 .
4123 \newline
4124 This documentation is in some aspects different from a commercial documentation:
4125
4126 \layout Itemize
4127
4128 It tries to document SDCC for several processor architectures in one document
4129  (commercially these probably would be separate documents/products).
4130  This document
4131 \begin_inset LatexCommand \index{Status of documentation}
4132
4133 \end_inset
4134
4135  currently matches SDCC for mcs51 and DS390 best and does give too few informati
4136 on about f.e.
4137  Z80, PIC14, PIC16 and HC08.
4138 \layout Itemize
4139
4140 There are many references pointing away from this documentation.
4141  Don't let this distract you.
4142  If there f.e.
4143  was a reference like
4144 \begin_inset LatexCommand \url{http://www.opencores.org}
4145
4146 \end_inset
4147
4148  together with a statement
4149 \begin_inset Quotes sld
4150 \end_inset
4151
4152 some processors which are targetted by SDCC can be implemented in a
4153 \emph on
4154 f
4155 \emph default
4156 ield
4157 \emph on
4158 p
4159 \emph default
4160 rogrammable
4161 \emph on
4162 g
4163 \emph default
4164 ate
4165 \emph on
4166 a
4167 \emph default
4168 rray
4169 \begin_inset LatexCommand \index{FPGA (field programmable gate array)}
4170
4171 \end_inset
4172
4173
4174 \begin_inset Quotes srd
4175 \end_inset
4176
4177  or
4178 \begin_inset LatexCommand \url{http://sf.net/projects/fpgac}
4179
4180 \end_inset
4181
4182
4183 \begin_inset LatexCommand \index{FpgaC ((subset of) C to FPGA compiler)}
4184
4185 \end_inset
4186
4187
4188 \begin_inset Quotes sld
4189 \end_inset
4190
4191 have you ever heard of an open source compiler that compiles a subset of
4192  C for an FPGA?
4193 \begin_inset Quotes srd
4194 \end_inset
4195
4196  we expect you to have a quick look there and come back.
4197  If you read this you are on the right track.
4198 \layout Itemize
4199
4200 Some sections attribute more space to problems, restrictions and warnings
4201  than to the solution.
4202 \layout Itemize
4203
4204 The installation section and the section about the debugger is intimidating.
4205 \layout Itemize
4206
4207 There are still lots of typos and there are more different writing styles
4208  than pictures.
4209 \layout Section
4210
4211 Testing the SDCC Compiler
4212 \begin_inset LatexCommand \label{sec:Testing-the-SDCC}
4213
4214 \end_inset
4215
4216
4217 \layout Standard
4218
4219 The first thing you should do after installing your SDCC compiler is to
4220  see if it runs.
4221  Type
4222 \family sans
4223 \series bold
4224 "sdcc -
4225 \begin_inset ERT
4226 status Collapsed
4227
4228 \layout Standard
4229
4230 \backslash
4231 /
4232 \end_inset
4233
4234 -version"
4235 \begin_inset LatexCommand \index{version}
4236
4237 \end_inset
4238
4239
4240 \family default
4241 \series default
4242  at the prompt, and the program should run and output its version like:
4243
4244 \newline
4245
4246 \family typewriter
4247 SDCC : mcs51/z80/avr/ds390/pic16/pic14/ds400/hc08 2.5.6 #4169 (May 8 2006)
4248  (UNIX)
4249 \layout Standard
4250
4251 If it doesn't run, or gives a message about not finding sdcc program, then
4252  you need to check over your installation.
4253  Make sure that the sdcc bin directory is in your executable search path
4254  defined by the PATH environment setting (
4255 \series medium
4256 see
4257 \series default
4258 section
4259 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
4260
4261 \end_inset
4262
4263 \SpecialChar ~
4264
4265 \series medium
4266 Install trouble-shooting for suggestions
4267 \series default
4268 ).
4269  Make sure that the sdcc program is in the bin folder, if not perhaps something
4270  did not install correctly.
4271 \newline
4272
4273 \newline
4274
4275 \series medium
4276 SDCC
4277 \series default
4278 is commonly installed as described in section
4279 \begin_inset Quotes sld
4280 \end_inset
4281
4282 Install and search paths
4283 \begin_inset Quotes srd
4284 \end_inset
4285
4286 .
4287 \newline
4288
4289 \newline
4290
4291 \series medium
4292 Make sure the compiler works on a very simple example.
4293  Type in the following test.c program using your favorite
4294 \series default
4295 ASCII
4296 \series medium
4297 editor:
4298 \layout Verse
4299
4300
4301 \family typewriter
4302 char test;
4303 \newline
4304
4305 \newline
4306 void main(void) {
4307 \newline
4308 \SpecialChar ~
4309 \SpecialChar ~
4310 \SpecialChar ~
4311 \SpecialChar ~
4312 test=0;
4313 \newline
4314 }
4315 \layout Standard
4316
4317
4318 \series medium
4319 Compile this using the following command:
4320 \family sans
4321 \series bold
4322 "sdcc -c test.c".
4323
4324 \family default
4325 \series default
4326
4327 \series medium
4328 If all goes well, the compiler will generate a test.asm and test.rel file.
4329  Congratulations, you've just compiled your first program with SDCC.
4330  We used the -c option to tell SDCC not to link the generated code, just
4331  to keep things simple for this step.
4332 \series default
4333
4334 \newline
4335
4336 \newline
4337
4338 \series medium
4339 The next step is to try it with the linker.
4340  Type in
4341 \family sans
4342 \series bold
4343 "sdcc test.c
4344 \family default
4345 \series default
4346 "
4347 \series medium
4348 .
4349  If all goes well the compiler will link with the libraries and produce
4350  a test.ihx output file.
4351  If this step fails
4352 \series default
4353
4354 \series medium
4355 (no test.ihx, and the linker generates warnings), then the problem is most
4356  likely that
4357 \series default
4358 SDCC
4359 \series medium
4360  cannot find the
4361 \series default
4362 /
4363 \series medium
4364 usr/local/share/sdcc/lib directory
4365 \series default
4366
4367 \series medium
4368 (see
4369 \series default
4370 section
4371 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
4372
4373 \end_inset
4374
4375 \SpecialChar ~
4376
4377 \series medium
4378 Install trouble-shooting for suggestions).
4379 \series default
4380
4381 \newline
4382
4383 \newline
4384
4385 \series medium
4386 The final test is to ensure
4387 \series default
4388 SDCC
4389 \series medium
4390  can use the
4391 \series default
4392 standard
4393 \series medium
4394  header files and libraries.
4395  Edit test.c and change it to the following:
4396 \layout Verse
4397
4398
4399 \family typewriter
4400 #include <string.h>
4401 \newline
4402
4403 \newline
4404 char str1[10];
4405 \newline
4406
4407 \newline
4408 void main(void) {
4409 \newline
4410 \SpecialChar ~
4411 \SpecialChar ~
4412 strcpy(str1, "testing");
4413 \newline
4414 }
4415 \layout Standard
4416
4417
4418 \series medium
4419 Compile this by typing
4420 \family sans
4421 \series bold
4422 "sdcc test.c"
4423 \family default
4424 \series medium
4425 .
4426  This should generate a test.ihx output file, and it should give no warnings
4427  such as not finding the string.h file.
4428  If it cannot find the string.h file, then the problem is that
4429 \series default
4430 SDCC
4431 \series medium
4432  cannot find the /usr/local/share/sdcc/include directory
4433 \series default
4434
4435 \series medium
4436 (see the
4437 \series default
4438 section
4439 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
4440
4441 \end_inset
4442
4443 \SpecialChar ~
4444
4445 \series medium
4446 Install trouble-shooting section for suggestions).
4447
4448 \series default
4449  Use option
4450 \series bold
4451 -
4452 \begin_inset ERT
4453 status Collapsed
4454
4455 \layout Standard
4456
4457 \backslash
4458 /
4459 \end_inset
4460
4461 -print-search-dirs
4462 \series default
4463
4464 \begin_inset LatexCommand \index{-\/-print-search-dirs}
4465
4466 \end_inset
4467
4468  to find exactly where SDCC is looking for the include and lib files.
4469 \layout Section
4470
4471 Install Trouble-shooting
4472 \begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
4473
4474 \end_inset
4475
4476
4477 \begin_inset LatexCommand \index{Install trouble-shooting}
4478
4479 \end_inset
4480
4481
4482 \layout Subsection
4483
4484 If SDCC does not build correctly
4485 \layout Standard
4486
4487 A thing to try is starting from scratch by unpacking the .tgz source package
4488  again in an empty directory.
4489  Configure it like:
4490 \newline
4491
4492 \newline
4493
4494 \family sans
4495 \series bold
4496 ./configure 2>&1 | tee configure.log
4497 \family default
4498 \series default
4499
4500 \newline
4501
4502 \newline
4503 and build it like:
4504 \newline
4505
4506 \newline
4507
4508 \family sans
4509 \series bold
4510 make 2>&1 | tee make.log
4511 \family default
4512 \series default
4513
4514 \newline
4515
4516 \newline
4517 If anything goes wrong, you can review the log files to locate the problem.
4518  Or a relevant part of this can be attached to an email that could be helpful
4519  when requesting help from the mailing list.
4520 \layout Subsection
4521
4522 What the
4523 \begin_inset Quotes sld
4524 \end_inset
4525
4526 ./configure
4527 \begin_inset Quotes srd
4528 \end_inset
4529
4530  does
4531 \layout Standard
4532
4533 The
4534 \begin_inset Quotes sld
4535 \end_inset
4536
4537 ./configure
4538 \begin_inset Quotes srd
4539 \end_inset
4540
4541  command is a script that analyzes your system and performs some configuration
4542  to ensure the source package compiles on your system.
4543  It will take a few minutes to run, and will compile a few tests to determine
4544  what compiler features are installed.
4545 \layout Subsection
4546
4547 What the
4548 \begin_inset Quotes sld
4549 \end_inset
4550
4551 make
4552 \begin_inset Quotes srd
4553 \end_inset
4554
4555  does
4556 \layout Standard
4557
4558 This runs the GNU make tool, which automatically compiles all the source
4559  packages into the final installed binary executables.
4560 \layout Subsection
4561
4562 What the
4563 \begin_inset Quotes sld
4564 \end_inset
4565
4566 make install
4567 \begin_inset Quotes erd
4568 \end_inset
4569
4570  command does.
4571 \layout Standard
4572
4573 This will install the compiler, other executables libraries and include
4574  files into the appropriate directories.
4575  See sections
4576 \begin_inset LatexCommand \ref{sub:Install-paths}
4577
4578 \end_inset
4579
4580 ,\SpecialChar ~
4581
4582 \begin_inset LatexCommand \ref{sub:Search-Paths}
4583
4584 \end_inset
4585
4586 \SpecialChar ~
4587 about install and search paths.
4588 \newline
4589 On most systems you will need super-user privileges to do this.
4590 \layout Section
4591
4592 Components of SDCC
4593 \layout Standard
4594
4595 SDCC is not just a compiler, but a collection of tools by various developers.
4596  These include linkers, assemblers, simulators and other components.
4597  Here is a summary of some of the components.
4598  Note that the included simulator and assembler have separate documentation
4599  which you can find in the source package in their respective directories.
4600  As SDCC grows to include support for other processors, other packages from
4601  various developers are included and may have their own sets of documentation.
4602 \newline
4603
4604 \newline
4605 You might want to look at the files which are installed in <installdir>.
4606  At the time of this writing, we find the following programs for gcc-builds:
4607 \newline
4608
4609 \newline
4610 In <installdir>/bin:
4611 \layout Itemize
4612
4613 sdcc - The compiler.
4614 \layout Itemize
4615
4616 sdcpp - The C preprocessor.
4617 \layout Itemize
4618
4619 asx8051 - The assembler for 8051 type processors.
4620 \layout Itemize
4621
4622 as-z80
4623 \series bold
4624 ,
4625 \series default
4626 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
4627 \layout Itemize
4628
4629 aslink -The linker for 8051 type processors.
4630 \layout Itemize
4631
4632 link-z80
4633 \series bold
4634 ,
4635 \series default
4636 link-gbz80 - The Z80 and GameBoy Z80 linkers.
4637 \layout Itemize
4638
4639 s51 - The ucSim 8051 simulator.
4640  Not available on Win32 platforms.
4641 \layout Itemize
4642
4643 sdcdb - The source debugger.
4644  Not available on Win32 platforms.
4645 \layout Itemize
4646
4647 packihx - A tool to pack (compress) Intel hex files.
4648 \layout Standard
4649
4650 In <installdir>/share/sdcc/include
4651 \layout Itemize
4652
4653 the include files
4654 \layout Standard
4655
4656 In <installdir>/share/sdcc/lib
4657 \layout Itemize
4658
4659 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
4660  relocatables.
4661 \layout Standard
4662
4663 In <installdir>/share/sdcc/doc
4664 \layout Itemize
4665
4666 the documentation
4667 \layout Standard
4668
4669 As development for other processors proceeds, this list will expand to include
4670  executables to support processors like AVR, PIC, etc.
4671 \layout Subsection
4672
4673 sdcc - The Compiler
4674 \layout Standard
4675
4676 This is the actual compiler, it in turn uses the c-preprocessor and invokes
4677  the assembler and linkage editor.
4678 \layout Subsection
4679
4680 sdcpp - The C-Preprocessor
4681 \layout Standard
4682
4683 The preprocessor
4684 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
4685
4686 \end_inset
4687
4688  is a modified version of the GNU preprocessor.
4689  The C preprocessor is used to pull in #include sources, process #ifdef
4690  statements, #defines and so on.
4691 \layout Subsection
4692
4693 as
4694 \emph on
4695 xxxx
4696 \emph default
4697 , aslink, link-
4698 \emph on
4699 xxx
4700 \emph default
4701  - The Assemblers and Linkage Editors
4702 \layout Standard
4703
4704 This is retargettable assembler & linkage editor, it was developed by Alan
4705  Baldwin.
4706  John Hartman created the version for 8051, and I (Sandeep) have made some
4707  enhancements and bug fixes for it to work properly with SDCC.
4708 \layout Subsection
4709
4710 s51 - The Simulator
4711 \layout Standard
4712
4713 S51
4714 \begin_inset LatexCommand \index{s51}
4715
4716 \end_inset
4717
4718  is a freeware, opensource simulator developed by Daniel Drotos.
4719  The simulator is built as part of the build process.
4720  For more information visit Daniel's web site at:
4721 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
4722
4723 \end_inset
4724
4725 .
4726  It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
4727  XA51 family.
4728  S51 is currently not available on Win32 platfors.
4729 \layout Subsection
4730
4731 sdcdb - Source Level Debugger
4732 \layout Standard
4733
4734 Sdcdb
4735 \begin_inset LatexCommand \index{sdcdb (debugger)}
4736
4737 \end_inset
4738
4739  is the companion source level debugger.
4740  More about sdcdb in section
4741 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
4742
4743 \end_inset
4744
4745 .
4746  The current version of the debugger uses Daniel's Simulator S51
4747 \begin_inset LatexCommand \index{s51}
4748
4749 \end_inset
4750
4751 , but can be easily changed to use other simulators.
4752  Sdcdb is currently not available on Win32 platfors.
4753 \layout Chapter
4754
4755 Using SDCC
4756 \layout Section
4757
4758 Compiling
4759 \layout Subsection
4760
4761 Single Source File Projects
4762 \layout Standard
4763
4764 For single source file 8051 projects the process is very simple.
4765  Compile your programs with the following command
4766 \family sans
4767 \series bold
4768 "sdcc sourcefile.c".
4769
4770 \family default
4771 \series default
4772  This will compile, assemble and link your source file.
4773  Output files are as follows:
4774 \layout Itemize
4775
4776 sourcefile.asm
4777 \begin_inset LatexCommand \index{<file>.asm}
4778
4779 \end_inset
4780
4781  - Assembler source
4782 \begin_inset LatexCommand \index{Assembler source}
4783
4784 \end_inset
4785
4786  file created by the compiler
4787 \layout Itemize
4788
4789 sourcefile.lst
4790 \begin_inset LatexCommand \index{<file>.lst}
4791
4792 \end_inset
4793
4794  - Assembler listing
4795 \begin_inset LatexCommand \index{Assembler listing}
4796
4797 \end_inset
4798
4799  file created by the Assembler
4800 \layout Itemize
4801
4802 sourcefile.rst
4803 \begin_inset LatexCommand \index{<file>.rst}
4804
4805 \end_inset
4806
4807  - Assembler listing
4808 \begin_inset LatexCommand \index{Assembler listing}
4809
4810 \end_inset
4811
4812  file updated with linkedit information, created by linkage editor
4813 \layout Itemize
4814
4815 sourcefile.sym
4816 \begin_inset LatexCommand \index{<file>.sym}
4817
4818 \end_inset
4819
4820  - symbol listing
4821 \begin_inset LatexCommand \index{Symbol listing}
4822
4823 \end_inset
4824
4825  for the sourcefile, created by the assembler
4826 \layout Itemize
4827
4828 sourcefile.rel
4829 \begin_inset LatexCommand \index{<file>.rel}
4830
4831 \end_inset
4832
4833  or sourcefile.o
4834 \begin_inset LatexCommand \index{<file>.o}
4835
4836 \end_inset
4837
4838  - Object file
4839 \begin_inset LatexCommand \index{Object file}
4840
4841 \end_inset
4842
4843  created by the assembler, input to Linkage editor
4844 \layout Itemize
4845
4846 sourcefile.map
4847 \begin_inset LatexCommand \index{<file>.map}
4848
4849 \end_inset
4850
4851  - The memory map
4852 \begin_inset LatexCommand \index{Memory map}
4853
4854 \end_inset
4855
4856  for the load module, created by the Linker
4857 \layout Itemize
4858
4859 sourcefile.mem
4860 \begin_inset LatexCommand \index{<file>.mem}
4861
4862 \end_inset
4863
4864  - A file with a summary of the memory usage
4865 \layout Itemize
4866
4867 sourcefile.ihx
4868 \begin_inset LatexCommand \index{<file>.ihx}
4869
4870 \end_inset
4871
4872  - The load module in Intel hex format
4873 \begin_inset LatexCommand \index{Intel hex format}
4874
4875 \end_inset
4876
4877  (you can select the Motorola S19 format
4878 \begin_inset LatexCommand \index{Motorola S19 format}
4879
4880 \end_inset
4881
4882  with -
4883 \begin_inset ERT
4884 status Collapsed
4885
4886 \layout Standard
4887
4888 \backslash
4889 /
4890 \end_inset
4891
4892 -out-fmt-s19
4893 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
4894
4895 \end_inset
4896
4897 .
4898  If you need another format you might want to use
4899 \family sans
4900 \shape italic
4901 objdump
4902 \family default
4903 \shape default
4904
4905 \begin_inset LatexCommand \index{objdump (tool)}
4906
4907 \end_inset
4908
4909  or
4910 \family sans
4911 \shape italic
4912  srecord
4913 \family default
4914 \shape default
4915
4916 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4917
4918 \end_inset
4919
4920 ).
4921  Both formats are documented in the documentation of srecord
4922 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4923
4924 \end_inset
4925
4926
4927 \layout Itemize
4928
4929 sourcefile.adb
4930 \begin_inset LatexCommand \index{<file>.adb}
4931
4932 \end_inset
4933
4934  - An intermediate file containing debug information needed to create the
4935  .cdb file (with -
4936 \begin_inset ERT
4937 status Open
4938
4939 \layout Standard
4940
4941 \backslash
4942 /
4943 \end_inset
4944
4945 -debug
4946 \begin_inset LatexCommand \index{-\/-debug}
4947
4948 \end_inset
4949
4950 )
4951 \layout Itemize
4952
4953 sourcefile.cdb
4954 \begin_inset LatexCommand \index{<file>.cdb}
4955
4956 \end_inset
4957
4958  - An optional file (with -
4959 \begin_inset ERT
4960 status Collapsed
4961
4962 \layout Standard
4963
4964 \backslash
4965 /
4966 \end_inset
4967
4968 -debug) containing debug information.
4969  The format is documented in cdbfileformat.pdf
4970 \layout Itemize
4971
4972 sourcefile.
4973  - (no extension)
4974 \begin_inset LatexCommand \index{<file> (no extension)}
4975
4976 \end_inset
4977
4978  An optional AOMF or AOMF51
4979 \begin_inset LatexCommand \index{AOMF, AOMF51}
4980
4981 \end_inset
4982
4983
4984 \begin_inset LatexCommand \label{OMF file}
4985
4986 \end_inset
4987
4988 file containing debug information (generated with option -
4989 \begin_inset ERT
4990 status Collapsed
4991
4992 \layout Standard
4993
4994 \backslash
4995 /
4996 \end_inset
4997
4998 -debug).
4999  The (Intel)
5000 \emph on
5001  a
5002 \emph default
5003 bsolute
5004 \emph on
5005 o
5006 \emph default
5007 bject
5008 \emph on
5009 m
5010 \emph default
5011 odule
5012 \emph on
5013 f
5014 \emph default
5015 ormat is commonly used by third party tools (debuggers
5016 \begin_inset LatexCommand \index{Debugger}
5017
5018 \end_inset
5019
5020 , simulators, emulators)
5021 \layout Itemize
5022
5023 sourcefile.dump*
5024 \begin_inset LatexCommand \index{<file>.dump*}
5025
5026 \end_inset
5027
5028  - Dump file to debug the compiler it self (generated with option -
5029 \begin_inset ERT
5030 status Collapsed
5031
5032 \layout Standard
5033
5034 \backslash
5035 /
5036 \end_inset
5037
5038 -dumpall) (see section
5039 \begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
5040
5041 \end_inset
5042
5043 \SpecialChar ~
5044  and section
5045 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
5046
5047 \end_inset
5048
5049 \SpecialChar ~
5050
5051 \begin_inset Quotes sld
5052 \end_inset
5053
5054 Anatomy of the compiler
5055 \begin_inset Quotes srd
5056 \end_inset
5057
5058 ).
5059 \layout Subsection
5060
5061 Projects with Multiple Source Files
5062 \layout Standard
5063
5064 SDCC can compile only ONE file at a time.
5065  Let us for example assume that you have a project containing the following
5066  files:
5067 \newline
5068
5069 \newline
5070 foo1.c (contains some functions)
5071 \newline
5072 foo2.c (contains some more functions)
5073 \newline
5074 foomain.c (contains more functions and the function main)
5075 \newline
5076
5077 \size footnotesize
5078
5079 \newline
5080
5081 \size default
5082 The first two files will need to be compiled separately with the commands:
5083 \size footnotesize
5084
5085 \size default
5086
5087 \newline
5088
5089 \newline
5090
5091 \family sans
5092 \series bold
5093 sdcc\SpecialChar ~
5094 -c\SpecialChar ~
5095 foo1.c
5096 \family default
5097 \series default
5098 \size footnotesize
5099
5100 \newline
5101
5102 \family sans
5103 \series bold
5104 \size default
5105 sdcc\SpecialChar ~
5106 -c\SpecialChar ~
5107 foo2.c
5108 \family default
5109 \series default
5110
5111 \newline
5112
5113 \newline
5114 Then compile the source file containing the
5115 \emph on
5116 main()
5117 \emph default
5118  function and link
5119 \begin_inset LatexCommand \index{Linker}
5120
5121 \end_inset
5122
5123  the files together with the following command:
5124 \newline
5125
5126 \newline
5127
5128 \family sans
5129 \series bold
5130 sdcc\SpecialChar ~
5131 foomain.c\SpecialChar ~
5132 foo1.rel\SpecialChar ~
5133 foo2.rel
5134 \family default
5135 \series default
5136
5137 \begin_inset LatexCommand \index{<file>.rel}
5138
5139 \end_inset
5140
5141
5142 \newline
5143
5144 \newline
5145 Alternatively,
5146 \emph on
5147 foomain.c
5148 \emph default
5149 can be separately compiled as well:
5150 \family sans
5151 \series bold
5152
5153 \newline
5154
5155 \newline
5156 sdcc\SpecialChar ~
5157 -c\SpecialChar ~
5158 foomain.c
5159 \newline
5160 sdcc foomain.rel foo1.rel foo2.rel
5161 \newline
5162
5163 \newline
5164
5165 \family default
5166 \series default
5167 The file containing the
5168 \emph on
5169 main()
5170 \emph default
5171  function
5172 \emph on
5173
5174 \emph default
5175 \noun on
5176 must
5177 \noun default
5178  be the
5179 \noun on
5180 first
5181 \noun default
5182  file specified in the command line, since the linkage editor processes
5183  file in the order they are presented to it.
5184  The linker is invoked from SDCC using a script file with extension .lnk
5185 \begin_inset LatexCommand \index{<file>.lnk}
5186
5187 \end_inset
5188
5189 .
5190  You can view this file to troubleshoot linking problems such as those arising
5191  from missing libraries.
5192 \layout Subsection
5193
5194 Projects with Additional Libraries
5195 \begin_inset LatexCommand \index{Libraries}
5196
5197 \end_inset
5198
5199
5200 \layout Standard
5201
5202 Some reusable routines may be compiled into a library, see the documentation
5203  for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
5204  for how to create a
5205 \emph on
5206 .lib
5207 \begin_inset LatexCommand \index{<file>.lib}
5208
5209 \end_inset
5210
5211
5212 \emph default
5213  library file.
5214  Libraries created in this manner can be included in the command line.
5215  Make sure you include the -L <library-path> option to tell the linker where
5216  to look for these files if they are not in the current directory.
5217  Here is an example, assuming you have the source file
5218 \emph on
5219 foomain.c
5220 \emph default
5221  and a library
5222 \emph on
5223  foolib.lib
5224 \emph default
5225  in the directory
5226 \emph on
5227 mylib
5228 \emph default
5229  (if that is not the same as your current project):
5230 \newline
5231
5232 \newline
5233
5234 \family sans
5235 \series bold
5236 sdcc foomain.c foolib.lib -L mylib
5237 \newline
5238
5239 \newline
5240
5241 \family default
5242 \series default
5243 Note here that
5244 \emph on
5245  mylib
5246 \emph default
5247  must be an absolute path name.
5248 \newline
5249
5250 \newline
5251 The most efficient way to use libraries is to keep separate modules in separate
5252  source files.
5253  The lib file now should name all the modules.rel
5254 \begin_inset LatexCommand \index{<file>.rel}
5255
5256 \end_inset
5257
5258  files.
5259  For an example see the standard library file
5260 \emph on
5261 libsdcc.lib
5262 \emph default
5263  in the directory <installdir>/share/lib/small.
5264 \layout Subsection
5265
5266 Using sdcclib to Create and Manage Libraries
5267 \begin_inset LatexCommand \index{sdcclib}
5268
5269 \end_inset
5270
5271
5272 \layout Standard
5273
5274 Alternatively, instead of having a .rel file for each entry on the library
5275  file as described in the preceding section, sdcclib can be used to embed
5276  all the modules belonging to such library in the library file itself.
5277  This results in a larger library file, but it greatly reduces the number
5278  of disk files accessed by the linker.
5279   Additionally, the packed library file contains an index of all include
5280  modules and symbols that significantly speeds up the linking process.
5281  To display a list of options supported by sdcclib type:
5282 \newline
5283
5284 \layout Standard
5285
5286
5287 \family sans
5288 \series bold
5289 sdcclib -?
5290 \begin_inset LatexCommand \index{sdcclib}
5291
5292 \end_inset
5293
5294
5295 \newline
5296
5297 \newline
5298
5299 \family default
5300 \series default
5301 To create a new library file, start by compiling all the required modules.
5302  For example:
5303 \newline
5304
5305 \layout Standard
5306
5307
5308 \family sans
5309 \series bold
5310 sdcc -c _divsint.c
5311 \layout Standard
5312
5313
5314 \family sans
5315 \series bold
5316 sdcc -c _divuint.c
5317 \layout Standard
5318
5319
5320 \family sans
5321 \series bold
5322 sdcc -c _modsint.c
5323 \layout Standard
5324
5325
5326 \family sans
5327 \series bold
5328 sdcc -c _moduint.c
5329 \layout Standard
5330
5331
5332 \family sans
5333 \series bold
5334 sdcc -c _mulint.c
5335 \newline
5336
5337 \layout Standard
5338
5339 This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
5340  and _mulint.rel.
5341  The next step is to add the .rel files to the library file:
5342 \newline
5343
5344 \layout Standard
5345
5346
5347 \family sans
5348 \series bold
5349 sdcclib libint.lib _divsint.rel
5350 \family default
5351
5352 \begin_inset LatexCommand \index{sdcclib}
5353
5354 \end_inset
5355
5356
5357 \layout Standard
5358
5359
5360 \family sans
5361 \series bold
5362 sdcclib libint.lib _divuint.rel
5363 \layout Standard
5364
5365
5366 \family sans
5367 \series bold
5368 sdcclib libint.lib _modsint.rel
5369 \layout Standard
5370
5371
5372 \family sans
5373 \series bold
5374 sdcclib libint.lib _moduint.rel
5375 \layout Standard
5376
5377
5378 \family sans
5379 \series bold
5380 sdcclib libint.lib _mulint.rel
5381 \series default
5382
5383 \newline
5384
5385 \layout Standard
5386
5387 If the file already exists in the library, it will be replaced.
5388  To see what modules and symbols are included in the library, options -s
5389  and -m are available.
5390  For example:
5391 \newline
5392
5393 \newline
5394
5395 \family sans
5396 \series bold
5397 sdcclib -s libint.lib
5398 \family default
5399
5400 \begin_inset LatexCommand \index{sdcclib}
5401
5402 \end_inset
5403
5404
5405 \newline
5406
5407 \family typewriter
5408 \series default
5409 _divsint.rel:
5410 \layout Standard
5411
5412
5413 \family typewriter
5414 __divsint_a_1_1
5415 \layout Standard
5416
5417
5418 \family typewriter
5419 __divsint_PARM_2
5420 \layout Standard
5421
5422
5423 \family typewriter
5424 __divsint
5425 \newline
5426 _divuint.rel:
5427 \layout Standard
5428
5429
5430 \family typewriter
5431 __divuint_a_1_1
5432 \layout Standard
5433
5434
5435 \family typewriter
5436 __divuint_PARM_2
5437 \layout Standard
5438
5439
5440 \family typewriter
5441 __divuint_reste_1_1
5442 \layout Standard
5443
5444
5445 \family typewriter
5446 __divuint_count_1_1
5447 \layout Standard
5448
5449
5450 \family typewriter
5451 __divuint
5452 \newline
5453 _modsint.rel:
5454 \layout Standard
5455
5456
5457 \family typewriter
5458 __modsint_a_1_1
5459 \layout Standard
5460
5461
5462 \family typewriter
5463 __modsint_PARM_2
5464 \layout Standard
5465
5466
5467 \family typewriter
5468 __modsint
5469 \newline
5470 _moduint.rel:
5471 \layout Standard
5472
5473
5474 \family typewriter
5475 __moduint_a_1_1
5476 \layout Standard
5477
5478
5479 \family typewriter
5480 __moduint_PARM_2
5481 \layout Standard
5482
5483
5484 \family typewriter
5485 __moduint_count_1_1
5486 \layout Standard
5487
5488
5489 \family typewriter
5490 __moduint
5491 \newline
5492 _mulint.rel:
5493 \layout Standard
5494
5495
5496 \family typewriter
5497 __mulint_PARM_2
5498 \layout Standard
5499
5500
5501 \family typewriter
5502 __mulint
5503 \family default
5504 \series bold
5505
5506 \newline
5507
5508 \layout Standard
5509
5510 If the source files are compiled using -
5511 \begin_inset ERT
5512 status Open
5513
5514 \layout Standard
5515
5516 \backslash
5517 /
5518 \end_inset
5519
5520 -debug
5521 \begin_inset LatexCommand \index{-\/-debug}
5522
5523 \end_inset
5524
5525 , the corresponding debug information file .adb will be include in the library
5526  file as well.
5527  The library files created with sdcclib are plain text files, so they can
5528  be viewed with a text editor.
5529  It is not recomended to modify a library file created with sdcclib using
5530  a text editor, as there are file indexes numbers located accross the file
5531  used by the linker to quickly locate the required module to link.
5532  Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
5533  it can be safely deleted, since all the information required for linking
5534  is embedded in the library file itself.
5535  Library files created using sdcclib are used as described in the preceding
5536  sections.
5537 \layout Section
5538
5539 Command Line Options
5540 \begin_inset LatexCommand \index{Command Line Options}
5541
5542 \end_inset
5543
5544
5545 \layout Subsection
5546
5547 Processor Selection Options
5548 \begin_inset LatexCommand \index{Options processor selection}
5549
5550 \end_inset
5551
5552
5553 \begin_inset LatexCommand \index{Processor selection options}
5554
5555 \end_inset
5556
5557
5558 \layout List
5559 \labelwidthstring 00.00.0000
5560
5561
5562 \series bold
5563 -mmcs51
5564 \begin_inset LatexCommand \index{-mmcs51}
5565
5566 \end_inset
5567
5568
5569 \series default
5570  Generate code for the Intel MCS51
5571 \begin_inset LatexCommand \index{MCS51}
5572
5573 \end_inset
5574
5575  family of processors.
5576  This is the default processor target.
5577 \layout List
5578 \labelwidthstring 00.00.0000
5579
5580
5581 \series bold
5582 -mds390
5583 \begin_inset LatexCommand \index{-mds390}
5584
5585 \end_inset
5586
5587
5588 \series default
5589  Generate code for the Dallas DS80C390
5590 \begin_inset LatexCommand \index{DS80C390}
5591
5592 \end_inset
5593
5594  processor.
5595 \layout List
5596 \labelwidthstring 00.00.0000
5597
5598
5599 \series bold
5600 -mds400
5601 \begin_inset LatexCommand \index{-mds400}
5602
5603 \end_inset
5604
5605
5606 \series default
5607  Generate code for the Dallas DS80C400
5608 \begin_inset LatexCommand \index{DS80C400}
5609
5610 \end_inset
5611
5612  processor.
5613 \layout List
5614 \labelwidthstring 00.00.0000
5615
5616
5617 \series bold
5618 -mhc08
5619 \begin_inset LatexCommand \index{-mhc08}
5620
5621 \end_inset
5622
5623
5624 \series default
5625  Generate code for the Freescale/Motorola HC08
5626 \begin_inset LatexCommand \index{HC08}
5627
5628 \end_inset
5629
5630  family of processors.
5631 \layout List
5632 \labelwidthstring 00.00.0000
5633
5634
5635 \series bold
5636 -mz80
5637 \begin_inset LatexCommand \index{-mz80}
5638
5639 \end_inset
5640
5641
5642 \series default
5643  Generate code for the Zilog Z80
5644 \begin_inset LatexCommand \index{Z80}
5645
5646 \end_inset
5647
5648  family of processors.
5649 \layout List
5650 \labelwidthstring 00.00.0000
5651
5652
5653 \series bold
5654 -mgbz80
5655 \begin_inset LatexCommand \index{-mgbz80}
5656
5657 \end_inset
5658
5659
5660 \series default
5661  Generate code for the GameBoy Z80
5662 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
5663
5664 \end_inset
5665
5666  processor (Not actively maintained).
5667 \layout List
5668 \labelwidthstring 00.00.0000
5669
5670
5671 \series bold
5672 -mavr
5673 \begin_inset LatexCommand \index{-mavr}
5674
5675 \end_inset
5676
5677
5678 \series default
5679  Generate code for the Atmel AVR
5680 \begin_inset LatexCommand \index{AVR}
5681
5682 \end_inset
5683
5684  processor (In development, not complete).
5685  AVR users should probably have a look at winavr
5686 \begin_inset LatexCommand \url{http://sourceforge.net/projects/winavr}
5687
5688 \end_inset
5689
5690  or
5691 \begin_inset LatexCommand \url{http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index}
5692
5693 \end_inset
5694
5695 .
5696 \layout Comment
5697
5698 I think it is fair to direct users there for now.
5699  Open source is also about avoiding unnecessary work .
5700  But I didn't find the 'official' link.
5701 \layout List
5702 \labelwidthstring 00.00.0000
5703
5704
5705 \series bold
5706 -mpic14
5707 \begin_inset LatexCommand \index{-mpic14}
5708
5709 \end_inset
5710
5711
5712 \series default
5713  Generate code for the Microchip PIC 14
5714 \begin_inset LatexCommand \index{PIC14}
5715
5716 \end_inset
5717
5718 -bit processors (p16f84 and variants.
5719  In development, not complete).
5720 \layout Comment
5721
5722 p16f627 p16f628 p16f84 p16f873 p16f877?
5723 \layout List
5724 \labelwidthstring 00.00.0000
5725
5726
5727 \series bold
5728 -mpic16
5729 \begin_inset LatexCommand \index{-mpic16}
5730
5731 \end_inset
5732
5733
5734 \series default
5735  Generate code for the Microchip PIC 16
5736 \begin_inset LatexCommand \index{PIC16}
5737
5738 \end_inset
5739
5740 -bit processors (p18f452 and variants.
5741  In development, not complete).
5742 \layout List
5743 \labelwidthstring 00.00.0000
5744
5745
5746 \series bold
5747 -mtlcs900h
5748 \series default
5749  Generate code for the Toshiba TLCS-900H
5750 \begin_inset LatexCommand \index{TLCS-900H}
5751
5752 \end_inset
5753
5754  processor (Not maintained, not complete).
5755 \layout List
5756 \labelwidthstring 00.00.0000
5757
5758
5759 \series bold
5760 -mxa51
5761 \begin_inset LatexCommand \index{-mxa51}
5762
5763 \end_inset
5764
5765
5766 \series default
5767  Generate code for the Phillips XA51
5768 \begin_inset LatexCommand \index{XA51}
5769
5770 \end_inset
5771
5772  processor (Not maintained, not complete).
5773 \layout Subsection
5774
5775 Preprocessor Options
5776 \begin_inset LatexCommand \index{Options preprocessor}
5777
5778 \end_inset
5779
5780
5781 \begin_inset LatexCommand \index{Preprocessor options}
5782
5783 \end_inset
5784
5785
5786 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5787
5788 \end_inset
5789
5790
5791 \layout List
5792 \labelwidthstring 00.00.0000
5793
5794
5795 \series bold
5796 -I<path>
5797 \begin_inset LatexCommand \index{-I<path>}
5798
5799 \end_inset
5800
5801
5802 \series default
5803  The additional location where the pre processor will look for <..h> or
5804 \begin_inset Quotes eld
5805 \end_inset
5806
5807 ..h
5808 \begin_inset Quotes erd
5809 \end_inset
5810
5811  files.
5812 \layout List
5813 \labelwidthstring 00.00.0000
5814
5815
5816 \series bold
5817 -D<macro[=value]>
5818 \begin_inset LatexCommand \index{-D<macro[=value]>}
5819
5820 \end_inset
5821
5822
5823 \series default
5824  Command line definition of macros.
5825  Passed to the preprocessor.
5826 \layout List
5827 \labelwidthstring 00.00.0000
5828
5829
5830 \series bold
5831 -M
5832 \begin_inset LatexCommand \index{-M}
5833
5834 \end_inset
5835
5836
5837 \series default
5838  Tell the preprocessor to output a rule suitable for make describing the
5839  dependencies of each object file.
5840  For each source file, the preprocessor outputs one make-rule whose target
5841  is the object file name for that source file and whose dependencies are
5842  all the files `#include'd in it.
5843  This rule may be a single line or may be continued with `
5844 \backslash
5845 '-newline if it is long.
5846  The list of rules is printed on standard output instead of the preprocessed
5847  C program.
5848  `-M' implies `-E
5849 \begin_inset LatexCommand \index{-E}
5850
5851 \end_inset
5852
5853 '.
5854 \layout List
5855 \labelwidthstring 00.00.0000
5856
5857
5858 \series bold
5859 -C
5860 \begin_inset LatexCommand \index{-C}
5861
5862 \end_inset
5863
5864
5865 \series default
5866  Tell the preprocessor not to discard comments.
5867  Used with the `-E' option.
5868 \layout List
5869 \labelwidthstring 00.00.0000
5870
5871
5872 \series bold
5873 -MM
5874 \begin_inset LatexCommand \index{-MM}
5875
5876 \end_inset
5877
5878
5879 \size large
5880 \bar under
5881
5882 \series default
5883 \size default
5884 \bar default
5885 Like `-M' but the output mentions only the user header files included with
5886  `#include
5887 \begin_inset Quotes eld
5888 \end_inset
5889
5890 file"'.
5891  System header files included with `#include <file>' are omitted.
5892 \layout List
5893 \labelwidthstring 00.00.0000
5894
5895
5896 \series bold
5897 -Aquestion(answer)
5898 \begin_inset LatexCommand \index{-Aquestion(answer)}
5899
5900 \end_inset
5901
5902
5903 \series default
5904  Assert the answer answer for question, in case it is tested with a preprocessor
5905  conditional such as `#if #question(answer)'.
5906  `-A-' disables the standard assertions that normally describe the target
5907  machine.
5908 \layout List
5909 \labelwidthstring 00.00.0000
5910
5911
5912 \series bold
5913 -Umacro
5914 \begin_inset LatexCommand \index{-Umacro}
5915
5916 \end_inset
5917
5918
5919 \series default
5920  Undefine macro macro.
5921  `-U' options are evaluated after all `-D' options, but before any `-include'
5922  and `-imacros' options.
5923 \layout List
5924 \labelwidthstring 00.00.0000
5925
5926
5927 \series bold
5928 -dM
5929 \begin_inset LatexCommand \index{-dM}
5930
5931 \end_inset
5932
5933
5934 \series default
5935  Tell the preprocessor to output only a list of the macro definitions that
5936  are in effect at the end of preprocessing.
5937  Used with the `-E' option.
5938 \layout List
5939 \labelwidthstring 00.00.0000
5940
5941
5942 \series bold
5943 -dD
5944 \begin_inset LatexCommand \index{-dD}
5945
5946 \end_inset
5947
5948
5949 \series default
5950  Tell the preprocessor to pass all macro definitions into the output, in
5951  their proper sequence in the rest of the output.
5952 \layout List
5953 \labelwidthstring 00.00.0000
5954
5955
5956 \series bold
5957 -dN
5958 \begin_inset LatexCommand \index{-dN}
5959
5960 \end_inset
5961
5962
5963 \size large
5964 \bar under
5965
5966 \series default
5967 \size default
5968 \bar default
5969 Like `-dD' except that the macro arguments and contents are omitted.
5970  Only `#define name' is included in the output.
5971 \layout List
5972 \labelwidthstring 00.00.0000
5973
5974
5975 \series bold
5976 -Wp\SpecialChar ~
5977 preprocessorOption[,preprocessorOption]
5978 \series default
5979
5980 \begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
5981
5982 \end_inset
5983
5984 ...
5985  Pass the preprocessorOption to the preprocessor
5986 \family typewriter
5987 sdcpp
5988 \family default
5989
5990 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5991
5992 \end_inset
5993
5994 .
5995  SDCC uses an adapted version of the preprocessor cpp of the GNU Compiler
5996  Collection (gcc), if you need more dedicated options please refer to the
5997  documentation at
5998 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
5999
6000 \end_inset
6001
6002 .
6003 \layout Subsection
6004
6005 Linker Options
6006 \begin_inset LatexCommand \index{Options linker}
6007
6008 \end_inset
6009
6010
6011 \begin_inset LatexCommand \index{Linker options}
6012
6013 \end_inset
6014
6015
6016 \layout List
6017 \labelwidthstring 00.00.0000
6018
6019
6020 \series bold
6021 -L\SpecialChar ~
6022 -
6023 \series default
6024
6025 \begin_inset ERT
6026 status Collapsed
6027
6028 \layout Standard
6029
6030 \backslash
6031 /
6032 \end_inset
6033
6034
6035 \series bold
6036 -lib-path
6037 \begin_inset LatexCommand \index{-\/-lib-path <path>}
6038
6039 \end_inset
6040
6041
6042 \begin_inset LatexCommand \index{-L -\/-lib-path}
6043
6044 \end_inset
6045
6046
6047 \series default
6048 \SpecialChar ~
6049 <absolute path to additional libraries> This option is passed to the linkage
6050  editor's additional libraries
6051 \begin_inset LatexCommand \index{Libraries}
6052
6053 \end_inset
6054
6055  search path.
6056  The path name must be absolute.
6057  Additional library files may be specified in the command line.
6058  See section Compiling programs for more details.
6059 \layout List
6060 \labelwidthstring 00.00.0000
6061
6062
6063 \series bold
6064 -
6065 \begin_inset ERT
6066 status Collapsed
6067
6068 \layout Standard
6069
6070 \backslash
6071 /
6072 \end_inset
6073
6074 -xram-loc
6075 \series default
6076
6077 \begin_inset LatexCommand \index{-\/-xram-loc <Value>}
6078
6079 \end_inset
6080
6081 \SpecialChar ~
6082 <Value> The start location of the external ram
6083 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
6084
6085 \end_inset
6086
6087 , default value is 0.
6088  The value entered can be in Hexadecimal or Decimal format, e.g.: -
6089 \begin_inset ERT
6090 status Collapsed
6091
6092 \layout Standard
6093
6094 \backslash
6095 /
6096 \end_inset
6097
6098 -xram-loc 0x8000 or -
6099 \begin_inset ERT
6100 status Collapsed
6101
6102 \layout Standard
6103
6104 \backslash
6105 /
6106 \end_inset
6107
6108 -xram-loc 32768.
6109 \layout List
6110 \labelwidthstring 00.00.0000
6111
6112
6113 \series bold
6114 -
6115 \begin_inset ERT
6116 status Collapsed
6117
6118 \layout Standard
6119
6120 \backslash
6121 /
6122 \end_inset
6123
6124 -code-loc
6125 \series default
6126
6127 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
6128
6129 \end_inset
6130
6131 \SpecialChar ~
6132 <Value> The start location of the code
6133 \begin_inset LatexCommand \index{code}
6134
6135 \end_inset
6136
6137  segment, default value 0.
6138  Note when this option is used the interrupt vector table is also relocated
6139  to the given address.
6140  The value entered can be in Hexadecimal or Decimal format, e.g.: -
6141 \begin_inset ERT
6142 status Collapsed
6143
6144 \layout Standard
6145
6146 \backslash
6147 /
6148 \end_inset
6149
6150 -code-loc 0x8000 or -
6151 \begin_inset ERT
6152 status Collapsed
6153
6154 \layout Standard
6155
6156 \backslash
6157 /
6158 \end_inset
6159
6160 -code-loc 32768.
6161 \layout List
6162 \labelwidthstring 00.00.0000
6163
6164
6165 \series bold
6166 -
6167 \begin_inset ERT
6168 status Collapsed
6169
6170 \layout Standard
6171
6172 \backslash
6173 /
6174 \end_inset
6175
6176 -stack-loc
6177 \series default
6178
6179 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
6180
6181 \end_inset
6182
6183 \SpecialChar ~
6184 <Value> By default the stack
6185 \begin_inset LatexCommand \index{stack}
6186
6187 \end_inset
6188
6189  is placed after the data segment.
6190  Using this option the stack can be placed anywhere in the internal memory
6191  space of the 8051.
6192  The value entered can be in Hexadecimal or Decimal format, e.g.
6193  -
6194 \begin_inset ERT
6195 status Collapsed
6196
6197 \layout Standard
6198
6199 \backslash
6200 /
6201 \end_inset
6202
6203 -stack-loc 0x20 or -
6204 \begin_inset ERT
6205 status Collapsed
6206
6207 \layout Standard
6208
6209 \backslash
6210 /
6211 \end_inset
6212
6213 -stack-loc 32.
6214  Since the sp register is incremented before a push or call, the initial
6215  sp will be set to one byte prior the provided value.
6216  The provided value should not overlap any other memory areas such as used
6217  register banks or the data segment and with enough space for the current
6218  application.
6219  The
6220 \series bold
6221 -
6222 \begin_inset ERT
6223 status Collapsed
6224
6225 \layout Standard
6226
6227 \backslash
6228 /
6229 \end_inset
6230
6231 -pack-iram
6232 \series default
6233 \SpecialChar ~
6234
6235 \begin_inset LatexCommand \index{-\/-pack-iram}
6236
6237 \end_inset
6238
6239  option (which is now a default setting) will override this setting, so
6240  you should also specify the
6241 \series bold
6242 -
6243 \begin_inset ERT
6244 status Collapsed
6245
6246 \layout Standard
6247
6248 \backslash
6249 /
6250 \end_inset
6251
6252 -no-pack-iram
6253 \series default
6254 \SpecialChar ~
6255
6256 \begin_inset LatexCommand \index{-\/-no-pack-iram}
6257
6258 \end_inset
6259
6260  option if you need to manually place the stack.
6261 \layout List
6262 \labelwidthstring 00.00.0000
6263
6264
6265 \series bold
6266 -
6267 \begin_inset ERT
6268 status Collapsed
6269
6270 \layout Standard
6271
6272 \backslash
6273 /
6274 \end_inset
6275
6276 -xstack-loc
6277 \series default
6278
6279 \begin_inset LatexCommand \index{-\/-xstack-loc <Value>}
6280
6281 \end_inset
6282
6283 \SpecialChar ~
6284 <Value> By default the external stack
6285 \begin_inset LatexCommand \index{xstack}
6286
6287 \end_inset
6288
6289  is placed after the pdata segment.
6290  Using this option the xstack can be placed anywhere in the external memory
6291  space of the 8051.
6292  The value entered can be in Hexadecimal or Decimal format, e.g.
6293  -
6294 \begin_inset ERT
6295 status Collapsed
6296
6297 \layout Standard
6298
6299 \backslash
6300 /
6301 \end_inset
6302
6303 -xstack-loc 0x8000 or -
6304 \begin_inset ERT
6305 status Collapsed
6306
6307 \layout Standard
6308
6309 \backslash
6310 /
6311 \end_inset
6312
6313 -stack-loc 32768.
6314  The provided value should not overlap any other memory areas such as the
6315  pdata or xdata segment and with enough space for the current application.
6316 \layout List
6317 \labelwidthstring 00.00.0000
6318
6319
6320 \series bold
6321 -
6322 \begin_inset ERT
6323 status Collapsed
6324
6325 \layout Standard
6326
6327 \backslash
6328 /
6329 \end_inset
6330
6331 -data-loc
6332 \series default
6333
6334 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
6335
6336 \end_inset
6337
6338 \SpecialChar ~
6339 <Value> The start location of the internal ram data
6340 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
6341
6342 \end_inset
6343
6344  segment.
6345  The value entered can be in Hexadecimal or Decimal format, eg.
6346  -
6347 \begin_inset ERT
6348 status Collapsed
6349
6350 \layout Standard
6351
6352 \backslash
6353 /
6354 \end_inset
6355
6356 -data-loc 0x20 or -
6357 \begin_inset ERT
6358 status Collapsed
6359
6360 \layout Standard
6361
6362 \backslash
6363 /
6364 \end_inset
6365
6366 -data-loc 32.
6367  (By default, the start location of the internal ram data segment  is set
6368  as low as possible in memory, taking into account the used register banks
6369  and the bit segment at address 0x20.
6370  For example if register banks 0 and 1 are used without bit variables, the
6371  data segment will be set, if -
6372 \begin_inset ERT
6373 status Collapsed
6374
6375 \layout Standard
6376
6377 \backslash
6378 /
6379 \end_inset
6380
6381 -data-loc is not used, to location 0x10.)
6382 \layout List
6383 \labelwidthstring 00.00.0000
6384
6385
6386 \series bold
6387 -
6388 \begin_inset ERT
6389 status Collapsed
6390
6391 \layout Standard
6392
6393 \backslash
6394 /
6395 \end_inset
6396
6397 -idata-loc
6398 \series default
6399
6400 \begin_inset LatexCommand \index{-\/-idata-loc <Value>}
6401
6402 \end_inset
6403
6404 \SpecialChar ~
6405 <Value> The start location of the indirectly addressable internal ram
6406 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
6407
6408 \end_inset
6409
6410  of the 8051, default value is 0x80.
6411  The value entered can be in Hexadecimal or Decimal format, eg.
6412  -
6413 \begin_inset ERT
6414 status Collapsed
6415
6416 \layout Standard
6417
6418 \backslash
6419 /
6420 \end_inset
6421
6422 -idata-loc 0x88 or -
6423 \begin_inset ERT
6424 status Collapsed
6425
6426 \layout Standard
6427
6428 \backslash
6429 /
6430 \end_inset
6431
6432 -idata-loc 136.
6433 \layout List
6434 \labelwidthstring 00.00.0000
6435
6436
6437 \series bold
6438 -
6439 \begin_inset ERT
6440 status Collapsed
6441
6442 \layout Standard
6443
6444 \backslash
6445 /
6446 \end_inset
6447
6448 -bit-loc
6449 \series default
6450 \SpecialChar ~
6451 <Value> The start location of the bit
6452 \begin_inset LatexCommand \index{bit}
6453
6454 \end_inset
6455
6456  addressable internal ram of the 8051.
6457  This is
6458 \emph on
6459 not
6460 \emph default
6461  implemented yet.
6462  Instead an option can be passed directly to the linker: -Wl\SpecialChar ~
6463 -bBSEG=<Value>.
6464 \layout List
6465 \labelwidthstring 00.00.0000
6466
6467
6468 \series bold
6469 -
6470 \begin_inset ERT
6471 status Collapsed
6472
6473 \layout Standard
6474
6475 \backslash
6476 /
6477 \end_inset
6478
6479 -out-fmt-ihx
6480 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
6481
6482 \end_inset
6483
6484
6485 \bar under
6486
6487 \series default
6488 \bar default
6489 The linker output (final object code) is in Intel Hex format.
6490 \begin_inset LatexCommand \index{Intel hex format}
6491
6492 \end_inset
6493
6494  This is the default option.
6495  The format itself is documented in the documentation of srecord
6496 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
6497
6498 \end_inset
6499
6500 .
6501 \layout List
6502 \labelwidthstring 00.00.0000
6503
6504
6505 \series bold
6506 -
6507 \begin_inset ERT
6508 status Collapsed
6509
6510 \layout Standard
6511
6512 \backslash
6513 /
6514 \end_inset
6515
6516 -out-fmt-s19
6517 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
6518
6519 \end_inset
6520
6521
6522 \bar under
6523
6524 \series default
6525 \bar default
6526 The linker output (final object code) is in Motorola S19 format
6527 \begin_inset LatexCommand \index{Motorola S19 format}
6528
6529 \end_inset
6530
6531 .
6532  The format itself is documented in the documentation of srecord.
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 -out-fmt-elf
6549 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
6550
6551 \end_inset
6552
6553
6554 \bar under
6555
6556 \series default
6557 \bar default
6558 The linker output (final object code) is in ELF format
6559 \begin_inset LatexCommand \index{ELF format}
6560
6561 \end_inset
6562
6563 .
6564  (Currently only supported for the HC08 processors)
6565 \layout List
6566 \labelwidthstring 00.00.0000
6567
6568
6569 \series bold
6570 -Wl\SpecialChar ~
6571 linkOption[,linkOption]
6572 \series default
6573
6574 \begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
6575
6576 \end_inset
6577
6578 ...
6579  Pass the linkOption to the linker.
6580  See file sdcc/as/doc/asxhtm.html for more on linker options.
6581 \layout Subsection
6582
6583 MCS51 Options
6584 \begin_inset LatexCommand \index{Options MCS51}
6585
6586 \end_inset
6587
6588
6589 \begin_inset LatexCommand \index{MCS51 options}
6590
6591 \end_inset
6592
6593
6594 \layout List
6595 \labelwidthstring 00.00.0000
6596
6597
6598 \series bold
6599 -
6600 \begin_inset ERT
6601 status Collapsed
6602
6603 \layout Standard
6604
6605 \backslash
6606 /
6607 \end_inset
6608
6609 -model-small
6610 \begin_inset LatexCommand \index{-\/-model-small}
6611
6612 \end_inset
6613
6614
6615 \series default
6616 \size large
6617 \emph on
6618
6619 \size default
6620 \emph default
6621 Generate code for Small Model programs, see section Memory Models for more
6622  details.
6623  This is the default model.
6624 \layout List
6625 \labelwidthstring 00.00.0000
6626
6627
6628 \series bold
6629 -
6630 \begin_inset ERT
6631 status Collapsed
6632
6633 \layout Standard
6634
6635 \backslash
6636 /
6637 \end_inset
6638
6639 -model-medium
6640 \begin_inset LatexCommand \index{-\/-model-medium}
6641
6642 \end_inset
6643
6644
6645 \series default
6646  Generate code for Medium model programs, see section Memory Models for
6647  more details.
6648  If this option is used all source files in the project have to be compiled
6649  with this option.
6650  It must also be used when invoking the linker.
6651 \layout List
6652 \labelwidthstring 00.00.0000
6653
6654
6655 \series bold
6656 -
6657 \begin_inset ERT
6658 status Collapsed
6659
6660 \layout Standard
6661
6662 \backslash
6663 /
6664 \end_inset
6665
6666 -model-large
6667 \begin_inset LatexCommand \index{-\/-model-large}
6668
6669 \end_inset
6670
6671
6672 \series default
6673  Generate code for Large model programs, see section Memory Models for more
6674  details.
6675  If this option is used all source files in the project have to be compiled
6676  with this option.
6677  It must also be used when invoking the linker.
6678 \layout List
6679 \labelwidthstring 00.00.0000
6680
6681
6682 \series bold
6683 -
6684 \begin_inset ERT
6685 status Collapsed
6686
6687 \layout Standard
6688
6689 \backslash
6690 /
6691 \end_inset
6692
6693 -xstack
6694 \begin_inset LatexCommand \index{-\/-xstack}
6695
6696 \end_inset
6697
6698
6699 \series default
6700  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
6701  variables and passing parameters.
6702  See section
6703 \begin_inset LatexCommand \ref{sub:External-Stack}
6704
6705 \end_inset
6706
6707 \SpecialChar ~
6708  External Stack for more details.
6709 \layout List
6710 \labelwidthstring 00.00.0000
6711
6712
6713 \series bold
6714 -
6715 \begin_inset ERT
6716 status Collapsed
6717
6718 \layout Standard
6719
6720 \backslash
6721 /
6722 \end_inset
6723
6724 -iram-size
6725 \series default
6726 \SpecialChar ~
6727 <Value>
6728 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
6729
6730 \end_inset
6731
6732  Causes the linker to check if the internal ram usage is within limits of
6733  the given value.
6734 \layout List
6735 \labelwidthstring 00.00.0000
6736
6737
6738 \series bold
6739 -
6740 \begin_inset ERT
6741 status Collapsed
6742
6743 \layout Standard
6744
6745 \backslash
6746 /
6747 \end_inset
6748
6749 -xram-size
6750 \series default
6751 \SpecialChar ~
6752 <Value>
6753 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
6754
6755 \end_inset
6756
6757  Causes the linker to check if the external ram usage is within limits of
6758  the given value.
6759 \layout List
6760 \labelwidthstring 00.00.0000
6761
6762
6763 \series bold
6764 -
6765 \begin_inset ERT
6766 status Collapsed
6767
6768 \layout Standard
6769
6770 \backslash
6771 /
6772 \end_inset
6773
6774 -code-size
6775 \series default
6776 \SpecialChar ~
6777 <Value>
6778 \begin_inset LatexCommand \index{-\/-code-size <Value>}
6779
6780 \end_inset
6781
6782  Causes the linker to check if the code memory usage is within limits of
6783  the given value.
6784 \layout List
6785 \labelwidthstring 00.00.0000
6786
6787
6788 \series bold
6789 -
6790 \begin_inset ERT
6791 status Collapsed
6792
6793 \layout Standard
6794
6795 \backslash
6796 /
6797 \end_inset
6798
6799 -stack-size
6800 \series default
6801 \SpecialChar ~
6802 <Value>
6803 \begin_inset LatexCommand \index{-\/-stack-size <Value>}
6804
6805 \end_inset
6806
6807  Causes the linker to check if there is at minimum <Value> bytes for stack.
6808 \layout List
6809 \labelwidthstring 00.00.0000
6810
6811
6812 \series bold
6813 -
6814 \begin_inset ERT
6815 status Collapsed
6816
6817 \layout Standard
6818
6819 \backslash
6820 /
6821 \end_inset
6822
6823 -pack-iram
6824 \series default
6825 \SpecialChar ~
6826
6827 \begin_inset LatexCommand \index{-\/-pack-iram}
6828
6829 \end_inset
6830
6831  Causes the linker to use unused register banks for data variables and pack
6832  data, idata and stack together.
6833  This is the default now.
6834 \layout List
6835 \labelwidthstring 00.00.0000
6836
6837
6838 \series bold
6839 -
6840 \begin_inset ERT
6841 status Collapsed
6842
6843 \layout Standard
6844
6845 \backslash
6846 /
6847 \end_inset
6848
6849 -no-pack-iram
6850 \series default
6851 \SpecialChar ~
6852
6853 \begin_inset LatexCommand \index{-\/-no-pack-iram}
6854
6855 \end_inset
6856
6857  Causes the linker to use old style for allocating memory areas.
6858 \layout Subsection
6859
6860 DS390 / DS400 Options
6861 \begin_inset LatexCommand \index{Options DS390}
6862
6863 \end_inset
6864
6865
6866 \begin_inset LatexCommand \index{DS390 options}
6867
6868 \end_inset
6869
6870
6871 \layout List
6872 \labelwidthstring 00.00.0000
6873
6874
6875 \series bold
6876 -
6877 \begin_inset ERT
6878 status Collapsed
6879
6880 \layout Standard
6881
6882 \backslash
6883 /
6884 \end_inset
6885
6886 -model-flat24
6887 \series default
6888
6889 \begin_inset LatexCommand \index{-\/-model-flat24}
6890
6891 \end_inset
6892
6893
6894 \size large
6895 \emph on
6896
6897 \size default
6898 \emph default
6899 Generate 24-bit flat mode code.
6900  This is the one and only that the ds390 code generator supports right now
6901  and is default when using
6902 \emph on
6903 -mds390
6904 \emph default
6905 .
6906  See section Memory Models for more details.
6907 \layout List
6908 \labelwidthstring 00.00.0000
6909
6910
6911 \series bold
6912 -
6913 \begin_inset ERT
6914 status Collapsed
6915
6916 \layout Standard
6917
6918 \backslash
6919 /
6920 \end_inset
6921
6922 -protect-sp-update
6923 \begin_inset LatexCommand \index{-\/-protect-sp-update}
6924
6925 \end_inset
6926
6927
6928 \series default
6929  disable interrupts during ESP:SP updates.
6930 \layout List
6931 \labelwidthstring 00.00.0000
6932
6933
6934 \series bold
6935 -
6936 \begin_inset ERT
6937 status Collapsed
6938
6939 \layout Standard
6940
6941 \backslash
6942 /
6943 \end_inset
6944
6945 -stack-10bit
6946 \series default
6947
6948 \begin_inset LatexCommand \index{-\/-stack-10bit}
6949
6950 \end_inset
6951
6952  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
6953  This is the one and only that the ds390 code generator supports right now
6954  and is default when using
6955 \emph on
6956 -mds390
6957 \emph default
6958 .
6959  In this mode, the stack is located in the lower 1K of the internal RAM,
6960  which is mapped to 0x400000.
6961  Note that the support is incomplete, since it still uses a single byte
6962  as the stack pointer.
6963  This means that only the lower 256 bytes of the potential 1K stack space
6964  will actually be used.
6965  However, this does allow you to reclaim the precious 256 bytes of low RAM
6966  for use for the DATA and IDATA segments.
6967  The compiler will not generate any code to put the processor into 10 bit
6968  stack mode.
6969  It is important to ensure that the processor is in this mode before calling
6970  any re-entrant functions compiled with this option.
6971  In principle, this should work with the
6972 \emph on
6973 -
6974 \begin_inset ERT
6975 status Collapsed
6976
6977 \layout Standard
6978
6979 \backslash
6980 /
6981 \end_inset
6982
6983 -stack-auto
6984 \begin_inset LatexCommand \index{-\/-stack-auto}
6985
6986 \end_inset
6987
6988
6989 \emph default
6990  option, but that has not been tested.
6991  It is incompatible with the
6992 \emph on
6993 -
6994 \begin_inset ERT
6995 status Collapsed
6996
6997 \layout Standard
6998
6999 \backslash
7000 /
7001 \end_inset
7002
7003 -xstack
7004 \begin_inset LatexCommand \index{-\/-xstack}
7005
7006 \end_inset
7007
7008
7009 \emph default
7010  option.
7011  It also only makes sense if the processor is in 24 bit contiguous addressing
7012  mode (see the
7013 \emph on
7014 -
7015 \begin_inset ERT
7016 status Collapsed
7017
7018 \layout Standard
7019
7020 \backslash
7021 /
7022 \end_inset
7023
7024 -model-flat24 option
7025 \emph default
7026 ).
7027 \layout List
7028 \labelwidthstring 00.00.0000
7029
7030
7031 \series bold
7032 -
7033 \begin_inset ERT
7034 status Collapsed
7035
7036 \layout Standard
7037
7038 \backslash
7039 /
7040 \end_inset
7041
7042 -stack-probe
7043 \begin_inset LatexCommand \index{-\/-stack-probe}
7044
7045 \end_inset
7046
7047
7048 \series default
7049  insert call to function __stack_probe at each function prologue.
7050 \layout List
7051 \labelwidthstring 00.00.0000
7052
7053
7054 \series bold
7055 -
7056 \begin_inset ERT
7057 status Collapsed
7058
7059 \layout Standard
7060
7061 \backslash
7062 /
7063 \end_inset
7064
7065 -tini-libid
7066 \begin_inset LatexCommand \index{-\/-tini-libid}
7067
7068 \end_inset
7069
7070
7071 \series default
7072  <nnnn> LibraryID used in -mTININative.
7073
7074 \layout List
7075 \labelwidthstring 00.00.0000
7076
7077
7078 \series bold
7079 -
7080 \begin_inset ERT
7081 status Collapsed
7082
7083 \layout Standard
7084
7085 \backslash
7086 /
7087 \end_inset
7088
7089 -use-accelerator
7090 \begin_inset LatexCommand \index{-\/-use-accelerator}
7091
7092 \end_inset
7093
7094
7095 \series default
7096  generate code for DS390 Arithmetic Accelerator.
7097
7098 \layout Subsection
7099
7100 Z80 Options
7101 \begin_inset LatexCommand \index{Options Z80}
7102
7103 \end_inset
7104
7105
7106 \begin_inset LatexCommand \index{Z80 options}
7107
7108 \end_inset
7109
7110
7111 \layout List
7112 \labelwidthstring 00.00.0000
7113
7114
7115 \series bold
7116 -
7117 \begin_inset ERT
7118 status Collapsed
7119
7120 \layout Standard
7121
7122 \backslash
7123 /
7124 \end_inset
7125
7126 -callee-saves-bc
7127 \series default
7128
7129 \begin_inset LatexCommand \index{-\/-callee-saves-bc}
7130
7131 \end_inset
7132
7133
7134 \size large
7135 \emph on
7136
7137 \size default
7138 \emph default
7139 Force a called function to always save BC.
7140 \layout List
7141 \labelwidthstring 00.00.0000
7142
7143
7144 \series bold
7145 -
7146 \begin_inset ERT
7147 status Collapsed
7148
7149 \layout Standard
7150
7151 \backslash
7152 /
7153 \end_inset
7154
7155 -no-std-crt0
7156 \series default
7157
7158 \begin_inset LatexCommand \index{-\/-no-std-crt0}
7159
7160 \end_inset
7161
7162  When linking, skip the standard crt0.o object file.
7163  You must provide your own crt0.o for your system when linking.
7164
7165 \layout Subsection
7166
7167 Optimization Options
7168 \begin_inset LatexCommand \index{Options optimization}
7169
7170 \end_inset
7171
7172
7173 \begin_inset LatexCommand \index{Optimization options}
7174
7175 \end_inset
7176
7177
7178 \layout List
7179 \labelwidthstring 00.00.0000
7180
7181
7182 \series bold
7183 -
7184 \begin_inset ERT
7185 status Collapsed
7186
7187 \layout Standard
7188
7189 \backslash
7190 /
7191 \end_inset
7192
7193 -nogcse
7194 \begin_inset LatexCommand \index{-\/-nogcse}
7195
7196 \end_inset
7197
7198
7199 \series default
7200  Will not do global subexpression elimination, this option may be used when
7201  the compiler creates undesirably large stack/data spaces to store compiler
7202  temporaries (
7203 \emph on
7204 s
7205 \emph default
7206 pill
7207 \emph on
7208 loc
7209 \emph default
7210 ations, sloc
7211 \begin_inset LatexCommand \index{sloc (spill location)}
7212
7213 \end_inset
7214
7215 ).
7216  A warning message will be generated when this happens and the compiler
7217  will indicate the number of extra bytes it allocated.
7218  It is recommended that this option NOT be used, #pragma\SpecialChar ~
7219 nogcse
7220 \begin_inset LatexCommand \index{\#pragma nogcse}
7221
7222 \end_inset
7223
7224  can be used to turn off global subexpression elimination
7225 \begin_inset LatexCommand \index{Subexpression elimination}
7226
7227 \end_inset
7228
7229  for a given function only.
7230 \layout List
7231 \labelwidthstring 00.00.0000
7232
7233
7234 \series bold
7235 -
7236 \begin_inset ERT
7237 status Collapsed
7238
7239 \layout Standard
7240
7241 \backslash
7242 /
7243 \end_inset
7244
7245 -noinvariant
7246 \begin_inset LatexCommand \index{-\/-noinvariant}
7247
7248 \end_inset
7249
7250
7251 \series default
7252  Will not do loop invariant optimizations, this may be turned off for reasons
7253  explained for the previous option.
7254  For more details of loop optimizations performed see Loop Invariants in
7255  section
7256 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
7257
7258 \end_inset
7259
7260 .
7261  It is recommended that this option NOT be used, #pragma\SpecialChar ~
7262 noinvariant
7263 \begin_inset LatexCommand \index{\#pragma noinvariant}
7264
7265 \end_inset
7266
7267  can be used to turn off invariant optimizations for a given function only.
7268 \layout List
7269 \labelwidthstring 00.00.0000
7270
7271
7272 \series bold
7273 -
7274 \begin_inset ERT
7275 status Collapsed
7276
7277 \layout Standard
7278
7279 \backslash
7280 /
7281 \end_inset
7282
7283 -noinduction
7284 \begin_inset LatexCommand \index{-\/-noinduction}
7285
7286 \end_inset
7287
7288
7289 \series default
7290  Will not do loop induction optimizations, see section strength reduction
7291  for more details.
7292  It is recommended that this option is NOT used, #pragma\SpecialChar ~
7293 noinduction
7294 \begin_inset LatexCommand \index{\#pragma noinduction}
7295
7296 \end_inset
7297
7298  can be used to turn off induction optimizations for a given function only.
7299 \layout List
7300 \labelwidthstring 00.00.0000
7301
7302
7303 \series bold
7304 -
7305 \begin_inset ERT
7306 status Collapsed
7307
7308 \layout Standard
7309
7310 \backslash
7311 /
7312 \end_inset
7313
7314 -nojtbound
7315 \begin_inset LatexCommand \index{-\/-nojtbound}
7316
7317 \end_inset
7318
7319
7320 \size large
7321 \bar under
7322
7323 \series default
7324 \size default
7325 \bar default
7326  Will not generate boundary condition check when switch statements
7327 \begin_inset LatexCommand \index{switch statement}
7328
7329 \end_inset
7330
7331  are implemented using jump-tables.
7332  See section
7333 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
7334
7335 \end_inset
7336
7337 \SpecialChar ~
7338 Switch Statements for more details.
7339  It is recommended that this option is NOT used, #pragma\SpecialChar ~
7340 nojtbound
7341 \begin_inset LatexCommand \index{\#pragma nojtbound}
7342
7343 \end_inset
7344
7345  can be used to turn off boundary checking for jump tables for a given function
7346  only.
7347 \layout List
7348 \labelwidthstring 00.00.0000
7349
7350
7351 \series bold
7352 -
7353 \begin_inset ERT
7354 status Collapsed
7355
7356 \layout Standard
7357
7358 \backslash
7359 /
7360 \end_inset
7361
7362 -noloopreverse
7363 \begin_inset LatexCommand \index{-\/-noloopreverse}
7364
7365 \end_inset
7366
7367
7368 \series default
7369 \size large
7370
7371 \size default
7372 Will not do loop reversal
7373 \begin_inset LatexCommand \index{Loop reversing}
7374
7375 \end_inset
7376
7377 optimization.
7378 \layout List
7379 \labelwidthstring 00.00.0000
7380
7381 -
7382 \begin_inset ERT
7383 status Collapsed
7384
7385 \layout Standard
7386
7387 \backslash
7388 /
7389 \end_inset
7390
7391 -
7392 \series bold
7393 nolabelopt
7394 \series default
7395
7396 \begin_inset LatexCommand \index{-\/-nolabelopt }
7397
7398 \end_inset
7399
7400 Will not optimize labels (makes the dumpfiles more readable).
7401 \layout List
7402 \labelwidthstring 00.00.0000
7403
7404
7405 \series bold
7406 -
7407 \begin_inset ERT
7408 status Collapsed
7409
7410 \layout Standard
7411
7412 \backslash
7413 /
7414 \end_inset
7415
7416 -no-xinit-opt
7417 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
7418
7419 \end_inset
7420
7421
7422 \series default
7423  Will not memcpy initialized data from code space into xdata space.
7424  This saves a few bytes in code space if you don't have initialized data
7425 \begin_inset LatexCommand \index{Variable initialization}
7426
7427 \end_inset
7428
7429 .
7430 \layout List
7431 \labelwidthstring 00.00.0000
7432
7433
7434 \series bold
7435 -
7436 \begin_inset ERT
7437 status Collapsed
7438
7439 \layout Standard
7440
7441 \backslash
7442 /
7443 \end_inset
7444
7445 -nooverlay
7446 \begin_inset LatexCommand \index{-\/-nooverlay}
7447
7448 \end_inset
7449
7450
7451 \series default
7452   The compiler will not overlay parameters and local variables of any function,
7453  see section Parameters and local variables for more details.
7454 \layout List
7455 \labelwidthstring 00.00.0000
7456
7457
7458 \series bold
7459 -
7460 \begin_inset ERT
7461 status Collapsed
7462
7463 \layout Standard
7464
7465 \backslash
7466 /
7467 \end_inset
7468
7469 -no-peep
7470 \begin_inset LatexCommand \index{-\/-no-peep}
7471
7472 \end_inset
7473
7474
7475 \series default
7476  Disable peep-hole optimization with built-in rules.
7477 \layout List
7478 \labelwidthstring 00.00.0000
7479
7480
7481 \series bold
7482 -
7483 \begin_inset ERT
7484 status Collapsed
7485
7486 \layout Standard
7487
7488 \backslash
7489 /
7490 \end_inset
7491
7492 -peep-file
7493 \series default
7494
7495 \begin_inset LatexCommand \index{-\/-peep-file}
7496
7497 \end_inset
7498
7499 \SpecialChar ~
7500 <filename> This option can be used to use additional rules to be used by
7501  the peep hole optimizer.
7502  See section
7503 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
7504
7505 \end_inset
7506
7507 \SpecialChar ~
7508 Peep Hole optimizations for details on how to write these rules.
7509 \layout List
7510 \labelwidthstring 00.00.0000
7511
7512
7513 \series bold
7514 -
7515 \begin_inset ERT
7516 status Collapsed
7517
7518 \layout Standard
7519
7520 \backslash
7521 /
7522 \end_inset
7523
7524 -peep-asm
7525 \begin_inset LatexCommand \index{-\/-peep-asm}
7526
7527 \end_inset
7528
7529
7530 \series default
7531  Pass the inline assembler code through the peep hole optimizer.
7532  This can cause unexpected changes to inline assembler code, please go through
7533  the peephole optimizer
7534 \begin_inset LatexCommand \index{Peephole optimizer}
7535
7536 \end_inset
7537
7538  rules defined in the source file tree '<target>/peeph.def' before using
7539  this option.
7540 \layout List
7541 \labelwidthstring 00.00.0000
7542
7543
7544 \series bold
7545 -
7546 \begin_inset ERT
7547 status Collapsed
7548
7549 \layout Standard
7550
7551 \backslash
7552 /
7553 \end_inset
7554
7555 -opt-code-speed
7556 \begin_inset LatexCommand \index{-\/-opt-code-speed}
7557
7558 \end_inset
7559
7560
7561 \series default
7562  The compiler will optimize code generation towards fast code, possibly
7563  at the expense of code size.
7564 \layout List
7565 \labelwidthstring 00.00.0000
7566
7567
7568 \series bold
7569 -
7570 \begin_inset ERT
7571 status Collapsed
7572
7573 \layout Standard
7574
7575 \backslash
7576 /
7577 \end_inset
7578
7579 -opt-code-size
7580 \begin_inset LatexCommand \index{-\/-opt-code-size}
7581
7582 \end_inset
7583
7584
7585 \series default
7586  The compiler will optimize code generation towards compact code, possibly
7587  at the expense of code speed.
7588 \layout Subsection
7589
7590 Other Options
7591 \begin_inset LatexCommand \index{Options other}
7592
7593 \end_inset
7594
7595
7596 \layout List
7597 \labelwidthstring 00.00.0000
7598
7599
7600 \series bold
7601 -c\SpecialChar ~
7602 -
7603 \begin_inset ERT
7604 status Collapsed
7605
7606 \layout Standard
7607
7608 \backslash
7609 /
7610 \end_inset
7611
7612 -compile-only
7613 \begin_inset LatexCommand \index{-\/-compile-only}
7614
7615 \end_inset
7616
7617
7618 \begin_inset LatexCommand \index{-c -\/-compile-only}
7619
7620 \end_inset
7621
7622
7623 \series default
7624  will compile and assemble the source, but will not call the linkage editor.
7625 \layout List
7626 \labelwidthstring 00.00.0000
7627
7628
7629 \series bold
7630 -
7631 \series default
7632
7633 \begin_inset ERT
7634 status Collapsed
7635
7636 \layout Standard
7637
7638 \backslash
7639 /
7640 \end_inset
7641
7642
7643 \series bold
7644 -c1mode
7645 \begin_inset LatexCommand \index{-\/-c1mode}
7646
7647 \end_inset
7648
7649
7650 \series default
7651  reads the preprocessed source from standard input and compiles it.
7652  The file name for the assembler output must be specified using the -o option.
7653 \layout List
7654 \labelwidthstring 00.00.0000
7655
7656
7657 \series bold
7658 -E
7659 \begin_inset LatexCommand \index{-E}
7660
7661 \end_inset
7662
7663
7664 \series default
7665  Run only the C preprocessor.
7666  Preprocess all the C source files specified and output the results to standard
7667  output.
7668 \layout List
7669 \labelwidthstring 00.00.0000
7670
7671
7672 \series bold
7673 -o\SpecialChar ~
7674 <path/file>
7675 \begin_inset LatexCommand \index{-o <path/file>}
7676
7677 \end_inset
7678
7679
7680 \series default
7681 The output path resp.
7682  file where everything will be placed.
7683  If the parameter is a path, it must have a trailing slash (or backslash
7684  for the Windows binaries) to be recognized as a path.
7685
7686 \layout List
7687 \labelwidthstring 00.00.0000
7688
7689
7690 \series bold
7691 -
7692 \begin_inset ERT
7693 status Collapsed
7694
7695 \layout Standard
7696
7697 \backslash
7698 /
7699 \end_inset
7700
7701 -stack-auto
7702 \begin_inset LatexCommand \index{-\/-stack-auto}
7703
7704 \end_inset
7705
7706
7707 \series default
7708 \size large
7709 \emph on
7710
7711 \size default
7712 \emph default
7713 All functions in the source file will be compiled as
7714 \emph on
7715 reentrant
7716 \emph default
7717
7718 \begin_inset LatexCommand \index{reentrant}
7719
7720 \end_inset
7721
7722 , i.e.
7723  the parameters and local variables will be allocated on the stack
7724 \begin_inset LatexCommand \index{stack}
7725
7726 \end_inset
7727
7728 .
7729  See section
7730 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
7731
7732 \end_inset
7733
7734  Parameters and Local Variables for more details.
7735  If this option is used all source files in the project should be compiled
7736  with this option.
7737  It automatically implies --int-long-reent and --float-reent.
7738
7739 \layout List
7740 \labelwidthstring 00.00.0000
7741
7742
7743 \series bold
7744 -
7745 \begin_inset ERT
7746 status Collapsed
7747
7748 \layout Standard
7749
7750 \backslash
7751 /
7752 \end_inset
7753
7754 -callee-saves
7755 \begin_inset LatexCommand \index{-\/-callee-saves}
7756
7757 \end_inset
7758
7759  function1[,function2][,function3]....
7760
7761 \series default
7762  The compiler by default uses a caller saves convention for register saving
7763  across function calls, however this can cause unnecessary register pushing
7764  & popping when calling small functions from larger functions.
7765  This option can be used to switch the register saving convention for the
7766  function names specified.
7767  The compiler will not save registers when calling these functions, no extra
7768  code will be generated at the entry & exit (function prologue
7769 \series bold
7770
7771 \begin_inset LatexCommand \index{function prologue}
7772
7773 \end_inset
7774
7775
7776 \series default
7777  & epilogue
7778 \series bold
7779
7780 \begin_inset LatexCommand \index{function epilogue}
7781
7782 \end_inset
7783
7784
7785 \series default
7786 ) for these functions to save & restore the registers used by these functions,
7787  this can SUBSTANTIALLY reduce code & improve run time performance of the
7788  generated code.
7789  In the future the compiler (with inter procedural analysis) will be able
7790  to determine the appropriate scheme to use for each function call.
7791  DO NOT use this option for built-in functions such as _mulint..., if this
7792  option is used for a library function the appropriate library function
7793  needs to be recompiled with the same option.
7794  If the project consists of multiple source files then all the source file
7795  should be compiled with the same -
7796 \begin_inset ERT
7797 status Collapsed
7798
7799 \layout Standard
7800
7801 \backslash
7802 /
7803 \end_inset
7804
7805 -callee-saves option string.
7806  Also see #pragma\SpecialChar ~
7807 callee_saves
7808 \begin_inset LatexCommand \index{\#pragma callee\_saves}
7809
7810 \end_inset
7811
7812 .
7813 \layout List
7814 \labelwidthstring 00.00.0000
7815
7816
7817 \series bold
7818 -
7819 \begin_inset ERT
7820 status Collapsed
7821
7822 \layout Standard
7823
7824 \backslash
7825 /
7826 \end_inset
7827
7828 -debug
7829 \begin_inset LatexCommand \index{-\/-debug}
7830
7831 \end_inset
7832
7833
7834 \bar under
7835
7836 \series default
7837 \bar default
7838 When this option is used the compiler will generate debug information.
7839  The debug information collected in a file with .cdb extension can be used
7840  with the SDCDB.
7841  For more information see documentation for SDCDB.
7842  Another file with no extension contains debug information in AOMF or AOMF51
7843 \begin_inset LatexCommand \index{AOMF, AOMF51}
7844
7845 \end_inset
7846
7847  format which is commonly used by third party tools.
7848 \layout List
7849 \labelwidthstring 00.00.0000
7850
7851
7852 \series bold
7853 -S
7854 \begin_inset LatexCommand \index{-S}
7855
7856 \end_inset
7857
7858
7859 \size large
7860 \bar under
7861
7862 \series default
7863 \size default
7864 \bar default
7865 Stop after the stage of compilation proper; do not assemble.
7866  The output is an assembler code file for the input file specified.
7867 \layout List
7868 \labelwidthstring 00.00.0000
7869
7870
7871 \series bold
7872 -
7873 \begin_inset ERT
7874 status Collapsed
7875
7876 \layout Standard
7877
7878 \backslash
7879 /
7880 \end_inset
7881
7882 -int-long-reent
7883 \begin_inset LatexCommand \index{-\/-int-long-reent}
7884
7885 \end_inset
7886
7887
7888 \series default
7889  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
7890  Note by default these libraries are compiled as non-reentrant.
7891  See section Installation for more details.
7892 \layout List
7893 \labelwidthstring 00.00.0000
7894
7895
7896 \series bold
7897 -
7898 \begin_inset ERT
7899 status Collapsed
7900
7901 \layout Standard
7902
7903 \backslash
7904 /
7905 \end_inset
7906
7907 -cyclomatic
7908 \begin_inset LatexCommand \index{-\/-cyclomatic}
7909
7910 \end_inset
7911
7912
7913 \bar under
7914
7915 \series default
7916 \bar default
7917 This option will cause the compiler to generate an information message for
7918  each function in the source file.
7919  The message contains some
7920 \emph on
7921 important
7922 \emph default
7923  information about the function.
7924  The number of edges and nodes the compiler detected in the control flow
7925  graph of the function, and most importantly the
7926 \emph on
7927 cyclomatic complexity
7928 \begin_inset LatexCommand \index{Cyclomatic complexity}
7929
7930 \end_inset
7931
7932
7933 \emph default
7934  see section on Cyclomatic Complexity for more details.
7935 \layout List
7936 \labelwidthstring 00.00.0000
7937
7938
7939 \series bold
7940 -
7941 \begin_inset ERT
7942 status Collapsed
7943
7944 \layout Standard
7945
7946 \backslash
7947 /
7948 \end_inset
7949
7950 -float-reent
7951 \begin_inset LatexCommand \index{-\/-float-reent}
7952
7953 \end_inset
7954
7955
7956 \series default
7957  Floating point library is compiled as reentrant
7958 \begin_inset LatexCommand \index{reentrant}
7959
7960 \end_inset
7961
7962 .
7963  See section Installation for more details.
7964 \layout List
7965 \labelwidthstring 00.00.0000
7966
7967
7968 \series bold
7969 -
7970 \begin_inset ERT
7971 status Collapsed
7972
7973 \layout Standard
7974
7975 \backslash
7976 /
7977 \end_inset
7978
7979 -main-return
7980 \begin_inset LatexCommand \index{-\/-main-return}
7981
7982 \end_inset
7983
7984
7985 \series default
7986  This option can be used if the code generated is called by a monitor program
7987  or if the main routine includes an endless loop.
7988  This option might result in slightly smaller code and save two bytes of
7989  stack space.
7990  The return from the 'main'
7991 \begin_inset LatexCommand \index{main return}
7992
7993 \end_inset
7994
7995  function will return to the function calling main.
7996  The default setting is to lock up i.e.
7997  generate a '
7998 \family typewriter
7999 sjmp .
8000 \family default
8001 '.
8002 \layout List
8003 \labelwidthstring 00.00.0000
8004
8005
8006 \series bold
8007 -
8008 \begin_inset ERT
8009 status Collapsed
8010
8011 \layout Standard
8012
8013 \backslash
8014 /
8015 \end_inset
8016
8017 -nostdinc
8018 \begin_inset LatexCommand \index{-\/-nostdinc}
8019
8020 \end_inset
8021
8022
8023 \series default
8024  This will prevent the compiler from passing on the default include path
8025  to the preprocessor.
8026 \layout List
8027 \labelwidthstring 00.00.0000
8028
8029
8030 \series bold
8031 -
8032 \begin_inset ERT
8033 status Collapsed
8034
8035 \layout Standard
8036
8037 \backslash
8038 /
8039 \end_inset
8040
8041 -nostdlib
8042 \begin_inset LatexCommand \index{-\/-nostdlib}
8043
8044 \end_inset
8045
8046
8047 \series default
8048  This will prevent the compiler from passing on the default library
8049 \begin_inset LatexCommand \index{Libraries}
8050
8051 \end_inset
8052
8053  path to the linker.
8054 \layout List
8055 \labelwidthstring 00.00.0000
8056
8057
8058 \series bold
8059 -
8060 \begin_inset ERT
8061 status Collapsed
8062
8063 \layout Standard
8064
8065 \backslash
8066 /
8067 \end_inset
8068
8069 -verbose
8070 \begin_inset LatexCommand \index{-\/-verbose}
8071
8072 \end_inset
8073
8074
8075 \series default
8076  Shows the various actions the compiler is performing.
8077 \layout List
8078 \labelwidthstring 00.00.0000
8079
8080
8081 \series bold
8082 -V
8083 \begin_inset LatexCommand \index{-V}
8084
8085 \end_inset
8086
8087
8088 \series default
8089  Shows the actual commands the compiler is executing.
8090 \layout List
8091 \labelwidthstring 00.00.0000
8092
8093
8094 \series bold
8095 -
8096 \begin_inset ERT
8097 status Collapsed
8098
8099 \layout Standard
8100
8101 \backslash
8102 /
8103 \end_inset
8104
8105 -no-c-code-in-asm
8106 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
8107
8108 \end_inset
8109
8110
8111 \series default
8112  Hides your ugly and inefficient c-code from the asm file, so you can always
8113  blame the compiler :)
8114 \layout List
8115 \labelwidthstring 00.00.0000
8116
8117
8118 \series bold
8119 -
8120 \begin_inset ERT
8121 status Collapsed
8122
8123 \layout Standard
8124
8125 \backslash
8126 /
8127 \end_inset
8128
8129 -no-peep-comments
8130 \begin_inset LatexCommand \index{-\/-no-peep-comments}
8131
8132 \end_inset
8133
8134
8135 \series default
8136  Will not include peep-hole comments in the generated files.
8137 \layout List
8138 \labelwidthstring 00.00.0000
8139
8140
8141 \series bold
8142 -
8143 \begin_inset ERT
8144 status Collapsed
8145
8146 \layout Standard
8147
8148 \backslash
8149 /
8150 \end_inset
8151
8152 -i-code-in-asm
8153 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
8154
8155 \end_inset
8156
8157
8158 \series default
8159  Include i-codes in the asm file.
8160  Sounds like noise but is most helpful for debugging the compiler itself.
8161 \layout List
8162 \labelwidthstring 00.00.0000
8163
8164
8165 \series bold
8166 -
8167 \begin_inset ERT
8168 status Collapsed
8169
8170 \layout Standard
8171
8172 \backslash
8173 /
8174 \end_inset
8175
8176 -less-pedantic
8177 \begin_inset LatexCommand \index{-\/-less-pedantic}
8178
8179 \end_inset
8180
8181
8182 \series default
8183  Disable some of the more pedantic warnings
8184 \begin_inset LatexCommand \index{Warnings}
8185
8186 \end_inset
8187
8188  (jwk burps: please be more specific here, please!).
8189 \layout List
8190 \labelwidthstring 00.00.0000
8191
8192
8193 \series bold
8194 -
8195 \begin_inset ERT
8196 status Collapsed
8197
8198 \layout Standard
8199
8200 \backslash
8201 /
8202 \end_inset
8203
8204 -disable-warning\SpecialChar ~
8205 <nnnn>
8206 \begin_inset LatexCommand \index{-\/-disable-warning}
8207
8208 \end_inset
8209
8210
8211 \series default
8212  Disable specific warning with number <nnnn>.
8213 \layout List
8214 \labelwidthstring 00.00.0000
8215
8216
8217 \series bold
8218 -
8219 \begin_inset ERT
8220 status Collapsed
8221
8222 \layout Standard
8223
8224 \backslash
8225 /
8226 \end_inset
8227
8228 -print-search-dirs
8229 \begin_inset LatexCommand \index{-\/-print-search-dirs}
8230
8231 \end_inset
8232
8233
8234 \series default
8235  Display the directories in the compiler's search path
8236 \layout List
8237 \labelwidthstring 00.00.0000
8238
8239
8240 \series bold
8241 -
8242 \begin_inset ERT
8243 status Collapsed
8244
8245 \layout Standard
8246
8247 \backslash
8248 /
8249 \end_inset
8250
8251 -vc
8252 \begin_inset LatexCommand \index{-\/-vc}
8253
8254 \end_inset
8255
8256
8257 \series default
8258  Display errors and warnings using MSVC style, so you can use SDCC with
8259  visual studio.
8260 \layout List
8261 \labelwidthstring 00.00.0000
8262
8263
8264 \series bold
8265 -
8266 \begin_inset ERT
8267 status Collapsed
8268
8269 \layout Standard
8270
8271 \backslash
8272 /
8273 \end_inset
8274
8275 -use-stdout
8276 \begin_inset LatexCommand \index{-\/-use-stdout}
8277
8278 \end_inset
8279
8280
8281 \series default
8282  Send errors and warnings to stdout instead of stderr.
8283 \layout List
8284 \labelwidthstring 00.00.0000
8285
8286
8287 \series bold
8288 -Wa\SpecialChar ~
8289 asmOption[,asmOption]
8290 \series default
8291
8292 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
8293
8294 \end_inset
8295
8296 ...
8297  Pass the asmOption to the assembler
8298 \begin_inset LatexCommand \index{Options assembler}
8299
8300 \end_inset
8301
8302
8303 \begin_inset LatexCommand \index{Assembler options}
8304
8305 \end_inset
8306
8307 .
8308  See file sdcc/as/doc/asxhtm.html for assembler options.cd
8309 \layout List
8310 \labelwidthstring 00.00.0000
8311
8312
8313 \series bold
8314 -
8315 \begin_inset ERT
8316 status Collapsed
8317
8318 \layout Standard
8319
8320 \backslash
8321 /
8322 \end_inset
8323
8324 -std-sdcc89
8325 \begin_inset LatexCommand \index{-\/-std-sdcc89}
8326
8327 \end_inset
8328
8329
8330 \series default
8331  Generally follow the C89 standard, but allow SDCC features that conflict
8332  with the standard (default).
8333 \layout List
8334 \labelwidthstring 00.00.0000
8335
8336
8337 \series bold
8338 -
8339 \begin_inset ERT
8340 status Collapsed
8341
8342 \layout Standard
8343
8344 \backslash
8345 /
8346 \end_inset
8347
8348 -std-c89
8349 \begin_inset LatexCommand \index{-\/-std-c89}
8350
8351 \end_inset
8352
8353
8354 \series default
8355  Follow the C89 standard and disable SDCC features that conflict with the
8356  standard.
8357 \layout List
8358 \labelwidthstring 00.00.0000
8359
8360
8361 \series bold
8362 -
8363 \begin_inset ERT
8364 status Collapsed
8365
8366 \layout Standard
8367
8368 \backslash
8369 /
8370 \end_inset
8371
8372 -std-sdcc99
8373 \begin_inset LatexCommand \index{-\/-std-sdcc99}
8374
8375 \end_inset
8376
8377
8378 \series default
8379  Generally follow the C99 standard, but allow SDCC features that conflict
8380  with the standard (incomplete support).
8381 \layout List
8382 \labelwidthstring 00.00.0000
8383
8384
8385 \series bold
8386 -
8387 \begin_inset ERT
8388 status Collapsed
8389
8390 \layout Standard
8391
8392 \backslash
8393 /
8394 \end_inset
8395
8396 -std-c99
8397 \begin_inset LatexCommand \index{-\/-std-sdcc99}
8398
8399 \end_inset
8400
8401
8402 \series default
8403  Follow the C99 standard and disable SDCC features that conflict with the
8404  standard (incomplete support).
8405 \layout List
8406 \labelwidthstring 00.00.0000
8407
8408
8409 \series bold
8410 -
8411 \begin_inset ERT
8412 status Collapsed
8413
8414 \layout Standard
8415
8416 \backslash
8417 /
8418 \end_inset
8419
8420 -codeseg
8421 \series default
8422
8423 \begin_inset LatexCommand \index{-\/-codeseg <Value>}
8424
8425 \end_inset
8426
8427 \SpecialChar ~
8428 <Name> The name to be used for the code
8429 \begin_inset LatexCommand \index{code}
8430
8431 \end_inset
8432
8433  segment, default CSEG.
8434  This is useful if you need to tell the compiler to put the code in a special
8435  segment so you can later on tell the linker to put this segment in a special
8436  place in memory.
8437  Can be used for instance when using bank switching to put the code in a
8438  bank.
8439 \layout List
8440 \labelwidthstring 00.00.0000
8441
8442
8443 \series bold
8444 -
8445 \begin_inset ERT
8446 status Collapsed
8447
8448 \layout Standard
8449
8450 \backslash
8451 /
8452 \end_inset
8453
8454 -constseg
8455 \series default
8456
8457 \begin_inset LatexCommand \index{-\/-constseg <Value>}
8458
8459 \end_inset
8460
8461 \SpecialChar ~
8462 <Name> The name to be used for the const
8463 \begin_inset LatexCommand \index{code}
8464
8465 \end_inset
8466
8467  segment, default CONST.
8468  This is useful if you need to tell the compiler to put the const data in
8469  a special segment so you can later on tell the linker to put this segment
8470  in a special place in memory.
8471  Can be used for instance when using bank switching to put the const data
8472  in a bank.
8473 \layout List
8474 \labelwidthstring 00.00.0000
8475
8476
8477 \series bold
8478 more-pedantic
8479 \series default
8480  Actually this is
8481 \series bold
8482 \emph on
8483 not
8484 \series default
8485 \emph default
8486  a SDCC compiler option but if you want
8487 \emph on
8488 more
8489 \emph default
8490  warnings you can use a separate tool dedicated to syntax checking like
8491  splint
8492 \begin_inset LatexCommand \label{lyx:more-pedantic-SPLINT}
8493
8494 \end_inset
8495
8496
8497 \begin_inset LatexCommand \index{lint (syntax checking tool)}
8498
8499 \end_inset
8500
8501
8502 \begin_inset LatexCommand \url{http://www.splint.org}
8503
8504 \end_inset
8505
8506 .
8507  To make your source files parseable by splint you will have to include
8508
8509 \family sans
8510 lint.h
8511 \family default
8512
8513 \begin_inset LatexCommand \index{splint (syntax checking tool)}
8514
8515 \end_inset
8516
8517  in your source file and add brackets around extended keywords (like
8518 \family sans
8519
8520 \begin_inset Quotes sld
8521 \end_inset
8522
8523 __at\SpecialChar ~
8524
8525 \series bold
8526 (
8527 \series default
8528 0xab
8529 \series bold
8530 )
8531 \series default
8532
8533 \begin_inset Quotes srd
8534 \end_inset
8535
8536
8537 \family default
8538  and
8539 \family sans
8540
8541 \begin_inset Quotes sld
8542 \end_inset
8543
8544 __interrupt\SpecialChar ~
8545 (2)
8546 \begin_inset Quotes srd
8547 \end_inset
8548
8549
8550 \family default
8551 ).
8552
8553 \newline
8554 Splint has an excellent on line manual at
8555 \begin_inset LatexCommand \url{http://www.splint.org/manual/}
8556
8557 \end_inset
8558
8559  and it's capabilities go beyond pure syntax checking.
8560  You'll need to tell splint the location of SDCC's include files so a typical
8561  command line could look like this:
8562 \newline
8563
8564 \family sans
8565 splint\SpecialChar ~
8566 -I\SpecialChar ~
8567 /usr/local/share/sdcc/include/mcs51/\SpecialChar ~
8568 \SpecialChar ~
8569 myprogram.c
8570 \layout Subsection
8571
8572 Intermediate Dump Options
8573 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
8574
8575 \end_inset
8576
8577
8578 \begin_inset LatexCommand \index{Options intermediate dump}
8579
8580 \end_inset
8581
8582
8583 \begin_inset LatexCommand \index{Intermediate dump options}
8584
8585 \end_inset
8586
8587
8588 \layout Standard
8589
8590 The following options are provided for the purpose of retargetting and debugging
8591  the compiler.
8592  They provide a means to dump the intermediate code (iCode
8593 \begin_inset LatexCommand \index{iCode}
8594
8595 \end_inset
8596
8597 ) generated by the compiler in human readable form at various stages of
8598  the compilation process.
8599  More on iCodes see chapter
8600 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
8601
8602 \end_inset
8603
8604
8605 \begin_inset Quotes srd
8606 \end_inset
8607
8608 The anatomy of the compiler
8609 \begin_inset Quotes srd
8610 \end_inset
8611
8612 .
8613 \layout List
8614 \labelwidthstring 00.00.0000
8615
8616
8617 \series bold
8618 -
8619 \begin_inset ERT
8620 status Collapsed
8621
8622 \layout Standard
8623
8624 \backslash
8625 /
8626 \end_inset
8627
8628 -dumpraw
8629 \begin_inset LatexCommand \index{-\/-dumpraw}
8630
8631 \end_inset
8632
8633
8634 \series default
8635  This option will cause the compiler to dump the intermediate code into
8636  a file of named
8637 \emph on
8638 <source filename>.dumpraw
8639 \emph default
8640  just after the intermediate code has been generated for a function, i.e.
8641  before any optimizations are done.
8642  The basic blocks
8643 \begin_inset LatexCommand \index{Basic blocks}
8644
8645 \end_inset
8646
8647  at this stage ordered in the depth first number, so they may not be in
8648  sequence of execution.
8649 \layout List
8650 \labelwidthstring 00.00.0000
8651
8652
8653 \series bold
8654 -
8655 \begin_inset ERT
8656 status Collapsed
8657
8658 \layout Standard
8659
8660 \backslash
8661 /
8662 \end_inset
8663
8664 -dumpgcse
8665 \begin_inset LatexCommand \index{-\/-dumpgcse}
8666
8667 \end_inset
8668
8669
8670 \series default
8671  Will create a dump of iCode's, after global subexpression elimination
8672 \begin_inset LatexCommand \index{Global subexpression elimination}
8673
8674 \end_inset
8675
8676 , into a file named
8677 \emph on
8678 <source filename>.dumpgcse.
8679 \layout List
8680 \labelwidthstring 00.00.0000
8681
8682
8683 \series bold
8684 -
8685 \begin_inset ERT
8686 status Collapsed
8687
8688 \layout Standard
8689
8690 \backslash
8691 /
8692 \end_inset
8693
8694 -dumpdeadcode
8695 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
8696
8697 \end_inset
8698
8699
8700 \series default
8701  Will create a dump of iCode's, after deadcode elimination
8702 \begin_inset LatexCommand \index{Dead-code elimination}
8703
8704 \end_inset
8705
8706 , into a file named
8707 \emph on
8708 <source filename>.dumpdeadcode.
8709 \layout List
8710 \labelwidthstring 00.00.0000
8711
8712
8713 \series bold
8714 -
8715 \begin_inset ERT
8716 status Collapsed
8717
8718 \layout Standard
8719
8720 \backslash
8721 /
8722 \end_inset
8723
8724 -dumploop
8725 \begin_inset LatexCommand \index{-\/-dumploop}
8726
8727 \end_inset
8728
8729
8730 \series default
8731 \size large
8732
8733 \size default
8734 Will create a dump of iCode's, after loop optimizations
8735 \begin_inset LatexCommand \index{Loop optimization}
8736
8737 \end_inset
8738
8739 , into a file named
8740 \emph on
8741 <source filename>.dumploop.
8742 \layout List
8743 \labelwidthstring 00.00.0000
8744
8745
8746 \series bold
8747 -
8748 \begin_inset ERT
8749 status Collapsed
8750
8751 \layout Standard
8752
8753 \backslash
8754 /
8755 \end_inset
8756
8757 -dumprange
8758 \begin_inset LatexCommand \index{-\/-dumprange}
8759
8760 \end_inset
8761
8762
8763 \series default
8764 \size large
8765
8766 \size default
8767 Will create a dump of iCode's, after live range analysis
8768 \begin_inset LatexCommand \index{Live range analysis}
8769
8770 \end_inset
8771
8772 , into a file named
8773 \emph on
8774 <source filename>.dumprange.
8775 \layout List
8776 \labelwidthstring 00.00.0000
8777
8778
8779 \series bold
8780 -
8781 \begin_inset ERT
8782 status Collapsed
8783
8784 \layout Standard
8785
8786 \backslash
8787 /
8788 \end_inset
8789
8790 -dumlrange
8791 \begin_inset LatexCommand \index{-\/-dumlrange}
8792
8793 \end_inset
8794
8795
8796 \series default
8797  Will dump the life ranges
8798 \begin_inset LatexCommand \index{Live range analysis}
8799
8800 \end_inset
8801
8802  for all symbols.
8803 \layout List
8804 \labelwidthstring 00.00.0000
8805
8806
8807 \series bold
8808 -
8809 \begin_inset ERT
8810 status Collapsed
8811
8812 \layout Standard
8813
8814 \backslash
8815 /
8816 \end_inset
8817
8818 -dumpregassign
8819 \begin_inset LatexCommand \index{-\/-dumpregassign}
8820
8821 \end_inset
8822
8823
8824 \bar under
8825
8826 \series default
8827 \bar default
8828 Will create a dump of iCode's, after register assignment
8829 \begin_inset LatexCommand \index{Register assignment}
8830
8831 \end_inset
8832
8833 , into a file named
8834 \emph on
8835 <source filename>.dumprassgn.
8836 \layout List
8837 \labelwidthstring 00.00.0000
8838
8839
8840 \series bold
8841 -
8842 \begin_inset ERT
8843 status Collapsed
8844
8845 \layout Standard
8846
8847 \backslash
8848 /
8849 \end_inset
8850
8851 -dumplrange
8852 \begin_inset LatexCommand \index{-\/-dumplrange}
8853
8854 \end_inset
8855
8856
8857 \series default
8858  Will create a dump of the live ranges of iTemp's
8859 \layout List
8860 \labelwidthstring 00.00.0000
8861
8862
8863 \series bold
8864 -
8865 \begin_inset ERT
8866 status Collapsed
8867
8868 \layout Standard
8869
8870 \backslash
8871 /
8872 \end_inset
8873
8874 -dumpall
8875 \begin_inset LatexCommand \index{-\/-dumpall}
8876
8877 \end_inset
8878
8879
8880 \size large
8881 \bar under
8882
8883 \series default
8884 \size default
8885 \bar default
8886 Will cause all the above mentioned dumps to be created.
8887 \layout Subsection
8888
8889 Redirecting output on Windows Shells
8890 \layout Standard
8891
8892 By default SDCC writes it's error messages to
8893 \begin_inset Quotes sld
8894 \end_inset
8895
8896 standard error
8897 \begin_inset Quotes srd
8898 \end_inset
8899
8900 .
8901  To force all messages to
8902 \begin_inset Quotes sld
8903 \end_inset
8904
8905 standard output
8906 \begin_inset Quotes srd
8907 \end_inset
8908
8909  use
8910 \series bold
8911 -
8912 \series default
8913 \emph on
8914
8915 \begin_inset ERT
8916 status Collapsed
8917
8918 \layout Standard
8919
8920 \backslash
8921 /
8922 \end_inset
8923
8924
8925 \series bold
8926 \emph default
8927 -
8928 \series default
8929 use-stdout
8930 \begin_inset LatexCommand \index{-\/-use-stdout}
8931
8932 \end_inset
8933
8934 .
8935  Additionally, if you happen to have visual studio installed in your windows
8936  machine, you can use it to compile your sources using a custom build and
8937  the SDCC -
8938 \emph on
8939
8940 \begin_inset ERT
8941 status Collapsed
8942
8943 \layout Standard
8944
8945 \backslash
8946 /
8947 \end_inset
8948
8949
8950 \emph default
8951 -vc
8952 \begin_inset LatexCommand \index{-\/-vc}
8953
8954 \end_inset
8955
8956  option.
8957  Something like this should work:
8958 \newline
8959
8960 \newline
8961
8962 \series bold
8963 c:
8964 \backslash
8965 sdcc
8966 \backslash
8967 bin
8968 \backslash
8969 sdcc.exe -
8970 \series default
8971 \emph on
8972
8973 \begin_inset ERT
8974 status Collapsed
8975
8976 \layout Standard
8977
8978 \backslash
8979 /
8980 \end_inset
8981
8982
8983 \series bold
8984 \emph default
8985 -vc -
8986 \series default
8987 \emph on
8988
8989 \begin_inset ERT
8990 status Collapsed
8991
8992 \layout Standard
8993
8994 \backslash
8995 /
8996 \end_inset
8997
8998
8999 \series bold
9000 \emph default
9001 -model-large -c $(InputPath)
9002 \layout Section
9003
9004 Environment variables
9005 \begin_inset LatexCommand \index{Environment variables}
9006
9007 \end_inset
9008
9009
9010 \layout Standard
9011
9012 SDCC recognizes the following environment variables:
9013 \layout List
9014 \labelwidthstring 00.00.0000
9015
9016
9017 \series bold
9018 SDCC_LEAVE_SIGNALS
9019 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
9020
9021 \end_inset
9022
9023
9024 \series default
9025  SDCC installs a signal handler
9026 \begin_inset LatexCommand \index{signal handler}
9027
9028 \end_inset
9029
9030  to be able to delete temporary files after an user break (^C) or an exception.
9031  If this environment variable is set, SDCC won't install the signal handler
9032  in order to be able to debug SDCC.
9033 \layout List
9034 \labelwidthstring 00.00.0000
9035
9036
9037 \series bold
9038 TMP,\SpecialChar ~
9039 TEMP,\SpecialChar ~
9040 TMPDIR
9041 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
9042
9043 \end_inset
9044
9045
9046 \series default
9047  Path, where temporary files will be created.
9048  The order of the variables is the search order.
9049  In a standard *nix environment these variables are not set, and there's
9050  no need to set them.
9051  On Windows it's recommended to set one of them.
9052 \layout List
9053 \labelwidthstring 00.00.0000
9054
9055
9056 \series bold
9057 SDCC_HOME
9058 \begin_inset LatexCommand \index{SDCC\_HOME}
9059
9060 \end_inset
9061
9062
9063 \series default
9064  Path, see section
9065 \begin_inset LatexCommand \ref{sub:Install-paths}
9066
9067 \end_inset
9068
9069 \SpecialChar ~
9070
9071 \begin_inset Quotes sld
9072 \end_inset
9073
9074  Install Paths
9075 \begin_inset Quotes srd
9076 \end_inset
9077
9078 .
9079 \layout List
9080 \labelwidthstring 00.00.0000
9081
9082
9083 \series bold
9084 SDCC_INCLUDE
9085 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
9086
9087 \end_inset
9088
9089
9090 \series default
9091  Path, see section
9092 \begin_inset LatexCommand \ref{sub:Search-Paths}
9093
9094 \end_inset
9095
9096 \SpecialChar ~
9097
9098 \begin_inset Quotes sld
9099 \end_inset
9100
9101 Search Paths
9102 \begin_inset Quotes srd
9103 \end_inset
9104
9105 .
9106 \layout List
9107 \labelwidthstring 00.00.0000
9108
9109
9110 \series bold
9111 SDCC_LIB
9112 \begin_inset LatexCommand \index{SDCC\_LIB}
9113
9114 \end_inset
9115
9116
9117 \series default
9118  Path, see section
9119 \begin_inset LatexCommand \ref{sub:Search-Paths}
9120
9121 \end_inset
9122
9123 \SpecialChar ~
9124
9125 \begin_inset Quotes sld
9126 \end_inset
9127
9128 Search Paths
9129 \begin_inset Quotes srd
9130 \end_inset
9131
9132 ..
9133 \layout Standard
9134
9135 There are some more environment variables recognized by SDCC, but these
9136  are solely used for debugging purposes.
9137  They can change or disappear very quickly, and will never be documented.
9138 \layout Section
9139
9140 Storage Class Language Extensions
9141 \layout Subsection
9142
9143 MCS51/DS390 Storage Class
9144 \begin_inset LatexCommand \index{Storage class}
9145
9146 \end_inset
9147
9148  Language Extensions
9149 \layout Standard
9150
9151 In addition to the ANSI storage classes SDCC allows the following MCS51
9152  specific storage classes:
9153 \layout Subsubsection
9154
9155 data
9156 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
9157
9158 \end_inset
9159
9160
9161 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
9162
9163 \end_inset
9164
9165  / near
9166 \begin_inset LatexCommand \index{near (storage class)}
9167
9168 \end_inset
9169
9170
9171 \begin_inset LatexCommand \index{\_\_near (storage class)}
9172
9173 \end_inset
9174
9175
9176 \layout Standard
9177
9178 This is the
9179 \series bold
9180 default
9181 \series default
9182  storage class for the Small Memory model (
9183 \emph on
9184 data
9185 \emph default
9186  and
9187 \emph on
9188 near
9189 \emph default
9190  or the more ANSI-C compliant forms
9191 \emph on
9192 __data
9193 \emph default
9194  and
9195 \emph on
9196 __near
9197 \emph default
9198  can be used synonymously).
9199  Variables declared with this storage class will be allocated in the directly
9200  addressable portion of the internal RAM of a 8051, e.g.:
9201 \layout Verse
9202
9203
9204 \family typewriter
9205 __data unsigned char test_data;
9206 \layout Standard
9207
9208 Writing 0x01 to this variable generates the assembly code:
9209 \layout Verse
9210
9211
9212 \family typewriter
9213 75*00 01\SpecialChar ~
9214 \SpecialChar ~
9215 \SpecialChar ~
9216 mov\SpecialChar ~
9217 \SpecialChar ~
9218 _test_data,#0x01
9219 \layout Subsubsection
9220
9221 xdata
9222 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9223
9224 \end_inset
9225
9226
9227 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9228
9229 \end_inset
9230
9231  / far
9232 \begin_inset LatexCommand \index{far (storage class)}
9233
9234 \end_inset
9235
9236
9237 \begin_inset LatexCommand \index{\_\_far (storage class)}
9238
9239 \end_inset
9240
9241
9242 \layout Standard
9243
9244 Variables declared with this storage class will be placed in the external
9245  RAM.
9246  This is the
9247 \series bold
9248 default
9249 \series default
9250  storage class for the Large Memory model, e.g.:
9251 \layout Verse
9252
9253
9254 \family typewriter
9255 __xdata unsigned char test_xdata;
9256 \layout Standard
9257
9258 Writing 0x01 to this variable generates the assembly code:
9259 \layout Verse
9260
9261
9262 \family typewriter
9263 90s00r00\SpecialChar ~
9264 \SpecialChar ~
9265 \SpecialChar ~
9266 mov\SpecialChar ~
9267 \SpecialChar ~
9268 dptr,#_test_xdata
9269 \newline
9270 74\SpecialChar ~
9271 01\SpecialChar ~
9272 \SpecialChar ~
9273 \SpecialChar ~
9274 \SpecialChar ~
9275 \SpecialChar ~
9276 \SpecialChar ~
9277 mov\SpecialChar ~
9278 \SpecialChar ~
9279 a,#0x01
9280 \newline
9281 F0\SpecialChar ~
9282 \SpecialChar ~
9283 \SpecialChar ~
9284 \SpecialChar ~
9285 \SpecialChar ~
9286 \SpecialChar ~
9287 \SpecialChar ~
9288 \SpecialChar ~
9289 \SpecialChar ~
9290 movx\SpecialChar ~
9291 @dptr,a
9292 \layout Subsubsection
9293
9294 idata
9295 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
9296
9297 \end_inset
9298
9299
9300 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
9301
9302 \end_inset
9303
9304
9305 \layout Standard
9306
9307 Variables declared with this storage class will be allocated into the indirectly
9308  addressable portion of the internal ram of a 8051, e.g.:
9309 \layout Verse
9310
9311
9312 \family typewriter
9313 __idata unsigned char test_idata;
9314 \layout Standard
9315
9316 Writing 0x01 to this variable generates the assembly code:
9317 \layout Verse
9318
9319
9320 \family typewriter
9321 78r00\SpecialChar ~
9322 \SpecialChar ~
9323 \SpecialChar ~
9324 \SpecialChar ~
9325 \SpecialChar ~
9326 \SpecialChar ~
9327 \SpecialChar ~
9328 mov\SpecialChar ~
9329 \SpecialChar ~
9330 r0,#_test_idata
9331 \newline
9332 76\SpecialChar ~
9333 01\SpecialChar ~
9334 \SpecialChar ~
9335 \SpecialChar ~
9336 \SpecialChar ~
9337 \SpecialChar ~
9338 \SpecialChar ~
9339 \SpecialChar ~
9340 mov\SpecialChar ~
9341 \SpecialChar ~
9342 @r0,#0x01
9343 \layout Standard
9344
9345 Please note, the first 128 byte of idata physically access the same RAM
9346  as the data memory.
9347  The original 8051 had 128 byte idata memory, nowadays most devices have
9348  256 byte idata memory.
9349  The stack
9350 \begin_inset LatexCommand \index{stack}
9351
9352 \end_inset
9353
9354  is located in idata memory.
9355 \layout Subsubsection
9356
9357 pdata
9358 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
9359
9360 \end_inset
9361
9362
9363 \begin_inset LatexCommand \index{\_\_pdata (mcs51, ds390 storage class)}
9364
9365 \end_inset
9366
9367
9368 \layout Standard
9369
9370 Paged xdata access is just as straightforward as using the other addressing
9371  modes of a 8051.
9372  It is typically located at the start of xdata and has a maximum size of
9373  256 bytes.
9374  The following example writes 0x01 to the pdata variable.
9375  Please note, pdata access physically accesses xdata memory.
9376  The high byte of the address is determined by port P2
9377 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
9378
9379 \end_inset
9380
9381 (or in case of some 8051 variants by a separate Special Function Register,
9382  see section
9383 \begin_inset LatexCommand \ref{sub:MCS51-variants}
9384
9385 \end_inset
9386
9387 ).
9388  This is the
9389 \series bold
9390 default
9391 \series default
9392  storage class for the Medium Memory model, e.g.:
9393 \layout Verse
9394
9395
9396 \family typewriter
9397 __pdata unsigned char test_pdata;
9398 \layout Standard
9399
9400 Writing 0x01 to this variable generates the assembly code:
9401 \layout Verse
9402
9403
9404 \family typewriter
9405 78r00\SpecialChar ~
9406 \SpecialChar ~
9407 \SpecialChar ~
9408 \SpecialChar ~
9409 \SpecialChar ~
9410 \SpecialChar ~
9411 mov r0,#_test_pdata
9412 \newline
9413 74 01\SpecialChar ~
9414 \SpecialChar ~
9415 \SpecialChar ~
9416 \SpecialChar ~
9417 \SpecialChar ~
9418 \SpecialChar ~
9419 mov a,#0x01
9420 \newline
9421 F2\SpecialChar ~
9422 \SpecialChar ~
9423 \SpecialChar ~
9424 \SpecialChar ~
9425 \SpecialChar ~
9426 \SpecialChar ~
9427 \SpecialChar ~
9428 \SpecialChar ~
9429 \SpecialChar ~
9430 movx @r0,a
9431 \layout Standard
9432
9433 If the -
9434 \begin_inset ERT
9435 status Collapsed
9436
9437 \layout Standard
9438
9439 \backslash
9440 /
9441 \end_inset
9442
9443 -xstack
9444 \begin_inset LatexCommand \index{-\/-xstack}
9445
9446 \end_inset
9447
9448  option is used the pdata memory area is followed by the xstack memory area
9449  and the sum of their sizes is limited to 256 bytes.
9450 \layout Subsubsection
9451
9452 code
9453 \begin_inset LatexCommand \index{code}
9454
9455 \end_inset
9456
9457
9458 \begin_inset LatexCommand \index{\_\_code}
9459
9460 \end_inset
9461
9462
9463 \layout Standard
9464
9465 'Variables' declared with this storage class will be placed in the code
9466  memory:
9467 \layout Verse
9468
9469
9470 \family typewriter
9471 __code unsigned char test_code;
9472 \layout Standard
9473
9474 Read access to this variable generates the assembly code:
9475 \layout Verse
9476
9477
9478 \family typewriter
9479 90s00r6F\SpecialChar ~
9480 \SpecialChar ~
9481 \SpecialChar ~
9482 mov dptr,#_test_code
9483 \newline
9484 E4\SpecialChar ~
9485 \SpecialChar ~
9486 \SpecialChar ~
9487 \SpecialChar ~
9488 \SpecialChar ~
9489 \SpecialChar ~
9490 \SpecialChar ~
9491 \SpecialChar ~
9492 \SpecialChar ~
9493 clr a
9494 \newline
9495 93\SpecialChar ~
9496 \SpecialChar ~
9497 \SpecialChar ~
9498 \SpecialChar ~
9499 \SpecialChar ~
9500 \SpecialChar ~
9501 \SpecialChar ~
9502 \SpecialChar ~
9503 \SpecialChar ~
9504 movc a,@a+dptr
9505 \layout Standard
9506
9507
9508 \family typewriter
9509 char
9510 \family default
9511  indexed arrays of characters in code memory can be accessed efficiently:
9512 \layout Verse
9513
9514
9515 \family typewriter
9516 __code char test_array[] = {'c','h','e','a','p'};
9517 \layout Standard
9518
9519 Read access to this array using an 8-bit unsigned index generates the assembly
9520  code:
9521 \layout Verse
9522
9523
9524 \family typewriter
9525 E5*00\SpecialChar ~
9526 \SpecialChar ~
9527 \SpecialChar ~
9528 \SpecialChar ~
9529 \SpecialChar ~
9530 \SpecialChar ~
9531 mov a,_index
9532 \layout Verse
9533
9534
9535 \family typewriter
9536 90s00r41\SpecialChar ~
9537 \SpecialChar ~
9538 \SpecialChar ~
9539 mov dptr,#_test_array
9540 \layout Verse
9541
9542
9543 \family typewriter
9544 93\SpecialChar ~
9545 \SpecialChar ~
9546 \SpecialChar ~
9547 \SpecialChar ~
9548 \SpecialChar ~
9549 \SpecialChar ~
9550 \SpecialChar ~
9551 \SpecialChar ~
9552 \SpecialChar ~
9553 movc a,@a+dptr
9554 \layout Subsubsection
9555
9556 bit
9557 \begin_inset LatexCommand \index{bit}
9558
9559 \end_inset
9560
9561
9562 \begin_inset LatexCommand \index{\_\_bit}
9563
9564 \end_inset
9565
9566
9567 \layout Standard
9568
9569 This is a data-type and a storage class specifier.
9570  When a variable is declared as a bit, it is allocated into the bit addressable
9571  memory of 8051, e.g.:
9572 \layout Verse
9573
9574
9575 \family typewriter
9576 bit test_bit;
9577 \layout Standard
9578
9579 Writing 1 to this variable generates the assembly code:
9580 \layout Verse
9581
9582
9583 \family typewriter
9584 D2*00\SpecialChar ~
9585 \SpecialChar ~
9586 \SpecialChar ~
9587 \SpecialChar ~
9588 \SpecialChar ~
9589 \SpecialChar ~
9590 \SpecialChar ~
9591 setb\SpecialChar ~
9592 _test_bit
9593 \layout Standard
9594
9595 The bit addressable memory consists of 128 bits which are located from 0x20
9596  to 0x2f in data memory.
9597
9598 \newline
9599 Apart from this 8051 specific storage class most architectures support ANSI-C
9600  bitfields
9601 \begin_inset LatexCommand \index{bitfields}
9602
9603 \end_inset
9604
9605
9606 \begin_inset Foot
9607 collapsed false
9608
9609 \layout Standard
9610
9611 Not really meant as examples, but nevertheless showing what bitfields are
9612  about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
9613 \end_inset
9614
9615 .
9616  In accordance with ISO/IEC 9899 bits and bitfields without an explicit
9617  signed modifier are implemented as unsigned.
9618 \layout Subsubsection
9619
9620 sfr
9621 \begin_inset LatexCommand \index{sfr}
9622
9623 \end_inset
9624
9625
9626 \begin_inset LatexCommand \index{\_\_sfr}
9627
9628 \end_inset
9629
9630  / sfr16
9631 \begin_inset LatexCommand \index{sfr16}
9632
9633 \end_inset
9634
9635
9636 \begin_inset LatexCommand \index{\_\_sfr16}
9637
9638 \end_inset
9639
9640  / sfr32
9641 \begin_inset LatexCommand \index{sfr32}
9642
9643 \end_inset
9644
9645
9646 \begin_inset LatexCommand \index{\_\_sfr32}
9647
9648 \end_inset
9649
9650  / sbit
9651 \begin_inset LatexCommand \index{\_\_sbit}
9652
9653 \end_inset
9654
9655
9656 \layout Standard
9657
9658 Like the bit keyword,
9659 \emph on
9660 sfr / sfr16 / sfr32 / sbit
9661 \emph default
9662 signify both a data-type and storage class, they are used to describe the
9663
9664 \emph on
9665 s
9666 \emph default
9667 pecial
9668 \emph on
9669 f
9670 \emph default
9671 unction
9672 \emph on
9673 r
9674 \emph default
9675 egisters and
9676 \emph on
9677 s
9678 \emph default
9679 pecial
9680 \emph on
9681 bit
9682 \emph default
9683  variables of a 8051, eg:
9684 \layout Verse
9685
9686
9687 \family typewriter
9688 __sfr __at
9689 \begin_inset LatexCommand \index{at}
9690
9691 \end_inset
9692
9693
9694 \begin_inset LatexCommand \index{\_\_at}
9695
9696 \end_inset
9697
9698  (0x80) P0;\SpecialChar ~
9699  /* special function register P0 at location 0x80 */
9700 \newline
9701 /* 16 bit special function register combination for timer 0 */
9702 \newline
9703 /* with the high byte at location 0x8C and the low byte at location 0x8A
9704  */
9705 \newline
9706 __sfr16 __at
9707 \begin_inset LatexCommand \index{at}
9708
9709 \end_inset
9710
9711
9712 \begin_inset LatexCommand \index{\_\_at}
9713
9714 \end_inset
9715
9716  (0x8C8A) TMR0;
9717 \newline
9718 __sbit __at (0xd7) CY; /* CY (Carry Flag
9719 \begin_inset LatexCommand \index{Flags}
9720
9721 \end_inset
9722
9723
9724 \begin_inset LatexCommand \index{Carry flag}
9725
9726 \end_inset
9727
9728 ) */
9729 \layout Standard
9730
9731 Special function registers which are located on an address dividable by
9732  8 are bit-addressable, an
9733 \emph on
9734  sbit
9735 \emph default
9736  addresses a specific bit within these sfr.
9737 \newline
9738 16 Bit and 32 bit special function register combinations which require a
9739  certain access order are better not declared using
9740 \emph on
9741 sfr16
9742 \emph default
9743  or
9744 \emph on
9745 sfr32.
9746
9747 \emph default
9748  Allthough SDCC usually accesses them Least Significant Byte (LSB) first,
9749  this is not guaranteed.
9750 \layout Subsubsection
9751
9752 Pointers
9753 \begin_inset LatexCommand \index{Pointer}
9754
9755 \end_inset
9756
9757  to MCS51/DS390 specific memory spaces
9758 \layout Standard
9759
9760 SDCC allows (via language extensions) pointers to explicitly point to any
9761  of the memory spaces
9762 \begin_inset LatexCommand \index{Memory model}
9763
9764 \end_inset
9765
9766  of the 8051.
9767  In addition to the explicit pointers, the compiler uses (by default) generic
9768  pointers which can be used to point to any of the memory spaces.
9769 \newline
9770
9771 \newline
9772 Pointer declaration examples:
9773 \layout Verse
9774
9775
9776 \family typewriter
9777 /* pointer physically in internal ram pointing to object in external ram
9778  */
9779 \newline
9780 __xdata unsigned char * __data p;
9781 \newline
9782
9783 \newline
9784 /* pointer physically in external ram pointing to object in internal ram
9785  */
9786 \newline
9787 __data unsigned char * __xdata p;
9788 \newline
9789
9790 \newline
9791 /* pointer physically in code rom pointing to data in xdata space */
9792 \newline
9793 __xdata unsigned char * __code p;
9794 \newline
9795
9796 \newline
9797 /* pointer physically in code space pointing to data in code space */
9798 \newline
9799 __code unsigned char * __code p;
9800 \newline
9801
9802 \newline
9803 /* the following is a generic pointer physically located in xdata space
9804  */
9805 \newline
9806 char * __xdata p;
9807 \newline
9808
9809 \newline
9810 /* the following is a function pointer physically located in data space
9811  */
9812 \newline
9813 char (* __data fp)(void);
9814 \layout Standard
9815
9816 Well you get the idea.
9817
9818 \newline
9819
9820 \newline
9821 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
9822 \emph on
9823 generic
9824 \emph default
9825  pointers.
9826
9827 \size small
9828
9829 \newline
9830
9831 \newline
9832
9833 \size default
9834 The highest order byte of the
9835 \emph on
9836 generic
9837 \emph default
9838  pointers contains the data space information.
9839  Assembler support routines are called whenever data is stored or retrieved
9840  using
9841 \emph on
9842 generic
9843 \emph default
9844  pointers.
9845  These are useful for developing reusable library
9846 \begin_inset LatexCommand \index{Libraries}
9847
9848 \end_inset
9849
9850  routines.
9851  Explicitly specifying the pointer type will generate the most efficient
9852  code.
9853 \layout Subsubsection
9854
9855 Notes on MCS51 memory
9856 \begin_inset LatexCommand \index{MCS51 memory}
9857
9858 \end_inset
9859
9860  layout
9861 \layout Standard
9862
9863 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
9864  RAM memory which is structured as follows:
9865 \newline
9866
9867 \newline
9868 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
9869
9870 \newline
9871 - Bytes 20-2F - 16 bytes to hold 128 bit
9872 \begin_inset LatexCommand \index{bit}
9873
9874 \end_inset
9875
9876  variables and,
9877 \newline
9878 - Bytes 30-7F - 80 bytes for general purpose use.
9879 \newline
9880
9881 \layout Standard
9882
9883 Additionally some members of the MCS51 family may have up to 128 bytes of
9884  additional, indirectly addressable, internal RAM memory (
9885 \emph on
9886 idata
9887 \emph default
9888
9889 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
9890
9891 \end_inset
9892
9893
9894 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
9895
9896 \end_inset
9897
9898 ).
9899  Furthermore, some chips may have some built in external memory (
9900 \emph on
9901 xdata
9902 \emph default
9903
9904 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9905
9906 \end_inset
9907
9908
9909 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9910
9911 \end_inset
9912
9913 ) which should not be confused with the internal, directly addressable RAM
9914  memory (
9915 \emph on
9916 data
9917 \emph default
9918
9919 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
9920
9921 \end_inset
9922
9923
9924 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
9925
9926 \end_inset
9927
9928 ).
9929  Sometimes this built in
9930 \emph on
9931 xdata
9932 \emph default
9933  memory has to be activated before using it (you can probably find this
9934  information on the datasheet of the microcontroller your are using, see
9935  also section
9936 \begin_inset LatexCommand \ref{sub:Startup-Code}
9937
9938 \end_inset
9939
9940 \SpecialChar ~
9941 Startup-Code).
9942 \layout Standard
9943
9944 Normally SDCC will only use the first bank
9945 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
9946
9947 \end_inset
9948
9949  of registers (register bank 0), but it is possible to specify that other
9950  banks of registers (keyword
9951 \emph on
9952 using
9953 \emph default
9954
9955 \emph on
9956
9957 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
9958
9959 \end_inset
9960
9961
9962 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
9963
9964 \end_inset
9965
9966
9967 \emph default
9968 ) should be used in interrupt
9969 \begin_inset LatexCommand \index{interrupt}
9970
9971 \end_inset
9972
9973
9974 \begin_inset LatexCommand \index{\_\_interrupt}
9975
9976 \end_inset
9977
9978  routines.
9979  By default, the compiler will place the stack after the last byte of allocated
9980  memory for variables.
9981  For example, if the first 2 banks of registers are used, and only four
9982  bytes are used for
9983 \emph on
9984 data
9985 \emph default
9986  variables, it will position the base of the internal stack at address 20
9987  (0x14).
9988  This implies that as the stack
9989 \begin_inset LatexCommand \index{stack}
9990
9991 \end_inset
9992
9993  grows, it will use up the remaining register banks, and the 16 bytes used
9994  by the 128 bit variables, and 80 bytes for general purpose use.
9995  If any bit variables are used, the data variables will be placed in unused
9996  register banks and after the byte holding the last bit variable.
9997  For example, if register banks 0 and 1 are used, and there are 9 bit variables
9998  (two bytes used),
9999 \emph on
10000 data
10001 \emph default
10002  variables will be placed starting from address 0x10 to 0x20 and continue
10003  at address 0x22.
10004  You can also use -
10005 \begin_inset ERT
10006 status Collapsed
10007
10008 \layout Standard
10009
10010 \backslash
10011 /
10012 \end_inset
10013
10014 -data-loc
10015 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
10016
10017 \end_inset
10018
10019  to specify the start address of the
10020 \emph on
10021 data
10022 \emph default
10023  and -
10024 \begin_inset ERT
10025 status Collapsed
10026
10027 \layout Standard
10028
10029 \backslash
10030 /
10031 \end_inset
10032
10033 -iram-size
10034 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
10035
10036 \end_inset
10037
10038  to specify the size of the total internal RAM (
10039 \emph on
10040 data
10041 \emph default
10042 +
10043 \emph on
10044 idata
10045 \emph default
10046 ).
10047
10048 \newline
10049
10050 \layout Standard
10051
10052 By default the 8051 linker will place the stack after the last byte of (i)data
10053  variables.
10054  Option -
10055 \begin_inset ERT
10056 status Collapsed
10057
10058 \layout Standard
10059
10060 \backslash
10061 /
10062 \end_inset
10063
10064 -stack-loc
10065 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
10066
10067 \end_inset
10068
10069  allows you to specify the start of the stack, i.e.
10070  you could start it after any data in the general purpose area.
10071  If your microcontroller has additional indirectly addressable internal
10072  RAM (
10073 \emph on
10074 idata
10075 \emph default
10076 ) you can place the stack on it.
10077  You may also need to use -
10078 \begin_inset ERT
10079 status Collapsed
10080
10081 \layout Standard
10082
10083 \backslash
10084 /
10085 \end_inset
10086
10087 -xdata-loc
10088 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
10089
10090 \end_inset
10091
10092  to set the start address of the external RAM (
10093 \emph on
10094 xdata
10095 \emph default
10096 ) and -
10097 \begin_inset ERT
10098 status Collapsed
10099
10100 \layout Standard
10101
10102 \backslash
10103 /
10104 \end_inset
10105
10106 -xram-size
10107 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
10108
10109 \end_inset
10110
10111  to specify its size.
10112  Same goes for the code memory, using -
10113 \begin_inset ERT
10114 status Collapsed
10115
10116 \layout Standard
10117
10118 \backslash
10119 /
10120 \end_inset
10121
10122 -code-loc
10123 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
10124
10125 \end_inset
10126
10127  and -
10128 \begin_inset ERT
10129 status Collapsed
10130
10131 \layout Standard
10132
10133 \backslash
10134 /
10135 \end_inset
10136
10137 -code-size
10138 \begin_inset LatexCommand \index{-\/-code-size <Value>}
10139
10140 \end_inset
10141
10142 .
10143  If in doubt, don't specify any options and see if the resulting memory
10144  layout is appropriate, then you can adjust it.
10145 \layout Standard
10146
10147 The linker generates two files with memory allocation information.
10148  The first, with extension .map
10149 \begin_inset LatexCommand \index{<file>.map}
10150
10151 \end_inset
10152
10153  shows all the variables and segments.
10154  The second with extension .mem
10155 \begin_inset LatexCommand \index{<file>.mem}
10156
10157 \end_inset
10158
10159  shows the final memory layout.
10160  The linker will complain either if memory segments overlap, there is not
10161  enough memory, or there is not enough space for stack.
10162  If you get any linking warnings and/or errors related to stack or segments
10163  allocation, take a look at either the .map or .mem files to find out what
10164  the problem is.
10165  The .mem file may even suggest a solution to the problem.
10166 \layout Subsection
10167
10168 Z80/Z180 Storage Class
10169 \begin_inset LatexCommand \index{Storage class}
10170
10171 \end_inset
10172
10173  Language Extensions
10174 \layout Subsubsection
10175
10176 sfr
10177 \begin_inset LatexCommand \index{sfr}
10178
10179 \end_inset
10180
10181
10182 \begin_inset LatexCommand \index{\_\_sfr}
10183
10184 \end_inset
10185
10186  (in/out to 8-bit addresses)
10187 \layout Standard
10188
10189 The Z80
10190 \begin_inset LatexCommand \index{Z80}
10191
10192 \end_inset
10193
10194  family has separate address spaces for memory and
10195 \emph on
10196 i
10197 \emph default
10198 nput/
10199 \emph on
10200 o
10201 \emph default
10202 utput memory.
10203  I/O memory
10204 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
10205
10206 \end_inset
10207
10208  is accessed with special instructions, e.g.:
10209 \layout Verse
10210
10211
10212 \family typewriter
10213 sfr at 0x78 IoPort;\SpecialChar ~
10214 \SpecialChar ~
10215 /* define a var in I/O space at 78h called IoPort */
10216
10217 \layout Standard
10218
10219 Writing 0x01 to this variable generates the assembly code:
10220 \layout Verse
10221
10222
10223 \family typewriter
10224 3E 01\SpecialChar ~
10225 \SpecialChar ~
10226 \SpecialChar ~
10227 \SpecialChar ~
10228 \SpecialChar ~
10229 \SpecialChar ~
10230 ld a,#0x01
10231 \newline
10232 D3 78\SpecialChar ~
10233 \SpecialChar ~
10234 \SpecialChar ~
10235 \SpecialChar ~
10236 \SpecialChar ~
10237 \SpecialChar ~
10238 out (_IoPort),a
10239 \layout Subsubsection
10240
10241 banked sfr
10242 \begin_inset LatexCommand \index{sfr}
10243
10244 \end_inset
10245
10246
10247 \begin_inset LatexCommand \index{\_\_sfr}
10248
10249 \end_inset
10250
10251  (in/out to 16-bit addresses)
10252 \layout Standard
10253
10254 The keyword
10255 \emph on
10256 banked
10257 \emph default
10258  is used to support 16 bit addresses in I/O memory e.g.:
10259 \layout Verse
10260
10261
10262 \family typewriter
10263 sfr banked at
10264 \begin_inset LatexCommand \index{at}
10265
10266 \end_inset
10267
10268
10269 \begin_inset LatexCommand \index{\_\_at}
10270
10271 \end_inset
10272
10273  0x123 IoPort;
10274 \layout Standard
10275
10276 Writing 0x01 to this variable generates the assembly code:
10277 \layout Verse
10278
10279
10280 \family typewriter
10281 01 23 01\SpecialChar ~
10282 \SpecialChar ~
10283 \SpecialChar ~
10284 ld bc,#_IoPort
10285 \newline
10286 3E 01\SpecialChar ~
10287 \SpecialChar ~
10288 \SpecialChar ~
10289 \SpecialChar ~
10290 \SpecialChar ~
10291 \SpecialChar ~
10292 ld a,#0x01
10293 \newline
10294 ED 79\SpecialChar ~
10295 \SpecialChar ~
10296 \SpecialChar ~
10297 \SpecialChar ~
10298 \SpecialChar ~
10299 \SpecialChar ~
10300 out (c),a
10301 \layout Subsubsection
10302
10303 sfr
10304 \begin_inset LatexCommand \index{sfr}
10305
10306 \end_inset
10307
10308
10309 \begin_inset LatexCommand \index{\_\_sfr}
10310
10311 \end_inset
10312
10313  (in0/out0 to 8 bit addresses on Z180
10314 \begin_inset LatexCommand \index{Z180}
10315
10316 \end_inset
10317
10318 /HD64180
10319 \begin_inset LatexCommand \index{HD64180}
10320
10321 \end_inset
10322
10323 )
10324 \layout Standard
10325
10326 The compiler option -
10327 \begin_inset ERT
10328 status Collapsed
10329
10330 \layout Standard
10331
10332 \backslash
10333 /
10334 \end_inset
10335
10336 -portmode=180 (80) and a compiler #pragma\SpecialChar ~
10337 portmode
10338 \begin_inset LatexCommand \index{\#pragma portmode}
10339
10340 \end_inset
10341
10342 =z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
10343 ns
10344 \family typewriter
10345 in0/out0
10346 \family default
10347  instead of
10348 \family typewriter
10349 in/out
10350 \family default
10351 .
10352  If you include the file z180.h this will be set automatically.
10353 \layout Subsection
10354
10355 HC08 Storage Class
10356 \begin_inset LatexCommand \index{Storage class}
10357
10358 \end_inset
10359
10360  Language Extensions
10361 \layout Subsubsection
10362
10363 data
10364 \begin_inset LatexCommand \index{data (hc08 storage class)}
10365
10366 \end_inset
10367
10368
10369 \begin_inset LatexCommand \index{\_\_data (hc08 storage class)}
10370
10371 \end_inset
10372
10373
10374 \layout Standard
10375
10376 The data storage class declares a variable that resides in the first 256
10377  bytes of memory (the direct page).
10378  The HC08 is most efficient at accessing variables (especially pointers)
10379  stored here.
10380 \layout Subsubsection
10381
10382 xdata
10383 \begin_inset LatexCommand \index{xdata (hc08 storage class)}
10384
10385 \end_inset
10386
10387
10388 \begin_inset LatexCommand \index{\_\_xdata (hc08 storage class)}
10389
10390 \end_inset
10391
10392
10393 \layout Standard
10394
10395 The xdata storage class declares a variable that can reside anywhere in
10396  memory.
10397  This is the default if no storage class is specified.
10398
10399 \layout Section
10400
10401 Absolute Addressing
10402 \begin_inset LatexCommand \index{Absolute addressing}
10403
10404 \end_inset
10405
10406
10407 \layout Standard
10408
10409 Data items can be assigned an absolute address with the
10410 \emph on
10411 at
10412 \begin_inset LatexCommand \index{at}
10413
10414 \end_inset
10415
10416
10417 \begin_inset LatexCommand \index{\_\_at}
10418
10419 \end_inset
10420
10421  <address>
10422 \emph default
10423  keyword, in addition to a storage class, e.g.:
10424 \layout Verse
10425
10426
10427 \family typewriter
10428 xdata
10429 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
10430
10431 \end_inset
10432
10433
10434 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
10435
10436 \end_inset
10437
10438  at
10439 \begin_inset LatexCommand \index{at}
10440
10441 \end_inset
10442
10443
10444 \begin_inset LatexCommand \index{\_\_at}
10445
10446 \end_inset
10447
10448  (0x7ffe) unsigned int chksum;
10449 \layout Standard
10450
10451 or
10452 \layout Verse
10453
10454
10455 \family typewriter
10456 __xdata __at (0x7ffe) unsigned int chksum;
10457 \layout Standard
10458
10459 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
10460  of the external ram.
10461  The compiler does
10462 \emph on
10463 not
10464 \emph default
10465  reserve any space for variables declared in this way
10466 \begin_inset Marginal
10467 collapsed true
10468
10469 \layout Standard
10470
10471
10472 \series bold
10473 !
10474 \end_inset
10475
10476  (they are implemented with an equate in the assembler).
10477  Thus it is left to the programmer to make sure there are no overlaps with
10478  other variables that are declared without the absolute address.
10479  The assembler listing file (.lst
10480 \begin_inset LatexCommand \index{<file>.lst}
10481
10482 \end_inset
10483
10484 ) and the linker output files (.rst
10485 \begin_inset LatexCommand \index{<file>.rst}
10486
10487 \end_inset
10488
10489 ) and (.map
10490 \begin_inset LatexCommand \index{<file>.map}
10491
10492 \end_inset
10493
10494 ) are good places to look for such overlaps.
10495  Variables with an absolute address are
10496 \emph on
10497 not
10498 \begin_inset Marginal
10499 collapsed true
10500
10501 \layout Standard
10502
10503
10504 \series bold
10505 !
10506 \end_inset
10507
10508
10509 \emph default
10510  initialized
10511 \begin_inset LatexCommand \index{Variable initialization}
10512
10513 \end_inset
10514
10515 .
10516 \layout Standard
10517
10518 In case of memory mapped I/O devices the keyword
10519 \emph on
10520 volatile
10521 \emph default
10522  has to be used to tell the compiler that accesses might not be removed:
10523 \layout Verse
10524
10525
10526 \family typewriter
10527 volatile
10528 \begin_inset LatexCommand \index{volatile}
10529
10530 \end_inset
10531
10532  __xdata
10533 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
10534
10535 \end_inset
10536
10537  __at
10538 \begin_inset LatexCommand \index{at}
10539
10540 \end_inset
10541
10542  (0x8000) unsigned char PORTA_8255;
10543 \layout Standard
10544
10545 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
10546 r) array
10547 \family typewriter
10548 \size footnotesize
10549
10550 \begin_inset LatexCommand \index{Aligned array}
10551
10552 \end_inset
10553
10554
10555 \family default
10556 \size default
10557  starts at a block (256 byte) boundary
10558 \begin_inset LatexCommand \index{block boundary}
10559
10560 \end_inset
10561
10562  (section
10563 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
10564
10565 \end_inset
10566
10567  has an example).
10568 \newline
10569 Absolute addresses can be specified for variables in all storage classes,
10570  e.g.:
10571 \layout Verse
10572
10573
10574 \family typewriter
10575 bit
10576 \begin_inset LatexCommand \index{bit}
10577
10578 \end_inset
10579
10580  __at
10581 \begin_inset LatexCommand \index{at}
10582
10583 \end_inset
10584
10585  (0x02) bvar;
10586 \layout Standard
10587
10588 The above example will allocate the variable at offset 0x02 in the bit-addressab
10589 le space.
10590  There is no real advantage to assigning absolute addresses to variables
10591  in this manner, unless you want strict control over all the variables allocated.
10592  One possible use would be to write hardware portable code.
10593  For example, if you have a routine that uses one or more of the microcontroller
10594  I/O pins, and such pins are different for two different hardwares, you
10595  can declare the I/O pins in your routine using:
10596 \layout Verse
10597
10598
10599 \family typewriter
10600 extern volatile
10601 \begin_inset LatexCommand \index{volatile}
10602
10603 \end_inset
10604
10605  bit MOSI;\SpecialChar ~
10606 \SpecialChar ~
10607 \SpecialChar ~
10608 \SpecialChar ~
10609 /* master out, slave in */
10610 \newline
10611 extern volatile bit MISO;\SpecialChar ~
10612 \SpecialChar ~
10613 \SpecialChar ~
10614 \SpecialChar ~
10615 /* master in, slave out */
10616 \newline
10617 extern volatile bit MCLK;\SpecialChar ~
10618 \SpecialChar ~
10619 \SpecialChar ~
10620 \SpecialChar ~
10621 /* master clock */
10622 \newline
10623
10624 \newline
10625 /* Input and Output of a byte on a 3-wire serial bus.
10626 \newline
10627 \SpecialChar ~
10628 \SpecialChar ~
10629 \SpecialChar ~
10630 If needed adapt polarity of clock, polarity of data and bit order
10631 \newline
10632 \SpecialChar ~
10633 */
10634 \newline
10635 unsigned char spi_io(unsigned char out_byte)
10636 \newline
10637 {
10638 \newline
10639 \SpecialChar ~
10640 \SpecialChar ~
10641 \SpecialChar ~
10642 \SpecialChar ~
10643 unsigned char i=8;
10644 \newline
10645 \SpecialChar ~
10646 \SpecialChar ~
10647 \SpecialChar ~
10648 \SpecialChar ~
10649 do {
10650 \newline
10651 \SpecialChar ~
10652 \SpecialChar ~
10653 \SpecialChar ~
10654 \SpecialChar ~
10655 \SpecialChar ~
10656 \SpecialChar ~
10657 \SpecialChar ~
10658 \SpecialChar ~
10659 MOSI = out_byte & 0x80;
10660 \newline
10661 \SpecialChar ~
10662 \SpecialChar ~
10663 \SpecialChar ~
10664 \SpecialChar ~
10665 \SpecialChar ~
10666 \SpecialChar ~
10667 \SpecialChar ~
10668 \SpecialChar ~
10669 out_byte <<= 1;
10670 \newline
10671 \SpecialChar ~
10672 \SpecialChar ~
10673 \SpecialChar ~
10674 \SpecialChar ~
10675 \SpecialChar ~
10676 \SpecialChar ~
10677 \SpecialChar ~
10678 \SpecialChar ~
10679 MCLK = 1;
10680 \newline
10681 \SpecialChar ~
10682 \SpecialChar ~
10683 \SpecialChar ~
10684 \SpecialChar ~
10685 \SpecialChar ~
10686 \SpecialChar ~
10687 \SpecialChar ~
10688 \SpecialChar ~
10689 /* _asm nop _endasm; */\SpecialChar ~
10690 \SpecialChar ~
10691 \SpecialChar ~
10692 \SpecialChar ~
10693 \SpecialChar ~
10694 \SpecialChar ~
10695 \SpecialChar ~
10696 \SpecialChar ~
10697 /* for slow peripherals */
10698 \newline
10699 \SpecialChar ~
10700 \SpecialChar ~
10701 \SpecialChar ~
10702 \SpecialChar ~
10703 \SpecialChar ~
10704 \SpecialChar ~
10705 \SpecialChar ~
10706 \SpecialChar ~
10707 if(MISO)
10708 \newline
10709 \SpecialChar ~
10710 \SpecialChar ~
10711 \SpecialChar ~
10712 \SpecialChar ~
10713 \SpecialChar ~
10714 \SpecialChar ~
10715 \SpecialChar ~
10716 \SpecialChar ~
10717 \SpecialChar ~
10718 \SpecialChar ~
10719 \SpecialChar ~
10720 \SpecialChar ~
10721 out_byte += 1;
10722 \newline
10723 \SpecialChar ~
10724 \SpecialChar ~
10725 \SpecialChar ~
10726 \SpecialChar ~
10727 \SpecialChar ~
10728 \SpecialChar ~
10729 \SpecialChar ~
10730 \SpecialChar ~
10731 MCLK = 0;
10732 \newline
10733 \SpecialChar ~
10734 \SpecialChar ~
10735 \SpecialChar ~
10736 \SpecialChar ~
10737 } while(--i);
10738 \newline
10739 \SpecialChar ~
10740 \SpecialChar ~
10741 \SpecialChar ~
10742 \SpecialChar ~
10743 return out_byte;
10744 \newline
10745 }
10746 \layout Standard
10747
10748 Then, someplace in the code for the first hardware you would use
10749 \layout Verse
10750
10751
10752 \family typewriter
10753 bit __at
10754 \begin_inset LatexCommand \index{at}
10755
10756 \end_inset
10757
10758
10759 \begin_inset LatexCommand \index{\_\_at}
10760
10761 \end_inset
10762
10763  (0x80) MOSI;\SpecialChar ~
10764 \SpecialChar ~
10765 \SpecialChar ~
10766 \SpecialChar ~
10767 /* I/O port 0, bit 0 */
10768 \newline
10769 bit __at (0x81) MISO;\SpecialChar ~
10770 \SpecialChar ~
10771 \SpecialChar ~
10772 \SpecialChar ~
10773 /* I/O port 0, bit 1 */
10774 \newline
10775 bit __at (0x82) MCLK;\SpecialChar ~
10776 \SpecialChar ~
10777 \SpecialChar ~
10778 \SpecialChar ~
10779 /* I/O port 0, bit 2 */
10780 \layout Standard
10781
10782 Similarly, for the second hardware you would use
10783 \layout Verse
10784
10785
10786 \family typewriter
10787 bit __at (0x83) MOSI;\SpecialChar ~
10788 \SpecialChar ~
10789 \SpecialChar ~
10790 \SpecialChar ~
10791 /* I/O port 0, bit 3 */
10792 \newline
10793 bit __at (0x91) MISO;\SpecialChar ~
10794 \SpecialChar ~
10795 \SpecialChar ~
10796 \SpecialChar ~
10797 /* I/O port 1, bit 1 */
10798 \newline
10799 bit
10800 \begin_inset LatexCommand \index{bit}
10801
10802 \end_inset
10803
10804  __at (0x92) MCLK;\SpecialChar ~
10805 \SpecialChar ~
10806 \SpecialChar ~
10807 \SpecialChar ~
10808 /* I/O port 1, bit 2 */
10809 \layout Standard
10810
10811 and you can use the same hardware dependent routine without changes, as
10812  for example in a library.
10813  This is somehow similar to sbit, but only one absolute address has to be
10814  specified in the whole project.
10815 \layout Section
10816
10817 Parameters
10818 \begin_inset LatexCommand \index{Parameters}
10819
10820 \end_inset
10821
10822
10823 \begin_inset LatexCommand \index{function parameter}
10824
10825 \end_inset
10826
10827  & Local Variables
10828 \begin_inset LatexCommand \index{local variables}
10829
10830 \end_inset
10831
10832
10833 \begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
10834
10835 \end_inset
10836
10837
10838 \layout Standard
10839
10840 Automatic (local) variables and parameters to functions can either be placed
10841  on the stack or in data-space.
10842  The default action of the compiler is to place these variables in the internal
10843  RAM (for small model) or external RAM (for large model).
10844  This in fact makes them similar to
10845 \emph on
10846 static
10847 \begin_inset LatexCommand \index{static}
10848
10849 \end_inset
10850
10851
10852 \emph default
10853  so by default functions are non-reentrant
10854 \begin_inset LatexCommand \index{reentrant}
10855
10856 \end_inset
10857
10858 .
10859
10860 \newline
10861
10862 \newline
10863 They can be placed on the stack
10864 \begin_inset LatexCommand \index{stack}
10865
10866 \end_inset
10867
10868  by using the
10869 \emph on
10870  -
10871 \begin_inset ERT
10872 status Collapsed
10873
10874 \layout Standard
10875
10876 \backslash
10877 /
10878 \end_inset
10879
10880 -stack-auto
10881 \begin_inset LatexCommand \index{-\/-stack-auto}
10882
10883 \end_inset
10884
10885
10886 \emph default
10887  option, by using
10888 \emph on
10889 #pragma\SpecialChar ~
10890 stackauto
10891 \emph default
10892
10893 \begin_inset LatexCommand \index{\#pragma stackauto}
10894
10895 \end_inset
10896
10897  or by using the
10898 \emph on
10899 reentrant
10900 \begin_inset LatexCommand \index{reentrant}
10901
10902 \end_inset
10903
10904
10905 \emph default
10906  keyword in the function declaration, e.g.:
10907 \layout Verse
10908
10909
10910 \family typewriter
10911 unsigned char foo(char i) __reentrant
10912 \newline
10913 {
10914 \newline
10915 \SpecialChar ~
10916 \SpecialChar ~
10917 \SpecialChar ~
10918 \SpecialChar ~
10919 ...
10920
10921 \newline
10922 }
10923 \layout Standard
10924
10925 Since stack space on 8051 is limited, the
10926 \emph on
10927 reentrant
10928 \emph default
10929 keyword or the
10930 \emph on
10931  -
10932 \begin_inset ERT
10933 status Collapsed
10934
10935 \layout Standard
10936
10937 \backslash
10938 /
10939 \end_inset
10940
10941 -stack-auto
10942 \emph default
10943  option should be used sparingly.
10944  Note that the reentrant keyword just means that the parameters & local
10945  variables will be allocated to the stack, it
10946 \emph on
10947 does not
10948 \emph default
10949  mean that the function is register bank
10950 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
10951
10952 \end_inset
10953
10954  independent.
10955 \newline
10956
10957 \newline
10958 Local variables
10959 \begin_inset LatexCommand \index{local variables}
10960
10961 \end_inset
10962
10963  can be assigned storage classes and absolute
10964 \begin_inset LatexCommand \index{Absolute addressing}
10965
10966 \end_inset
10967
10968  addresses, e.g.:
10969 \layout Verse
10970
10971
10972 \family typewriter
10973 unsigned char foo()
10974 \newline
10975 {
10976 \newline
10977 \SpecialChar ~
10978 \SpecialChar ~
10979 \SpecialChar ~
10980 \SpecialChar ~
10981 xdata unsigned char i;
10982 \newline
10983 \SpecialChar ~
10984 \SpecialChar ~
10985 \SpecialChar ~
10986 \SpecialChar ~
10987 bit bvar;
10988 \newline
10989 \SpecialChar ~
10990 \SpecialChar ~
10991 \SpecialChar ~
10992 \SpecialChar ~
10993 data __at
10994 \begin_inset LatexCommand \index{at}
10995
10996 \end_inset
10997
10998  (0x31) unsigned char j;
10999 \newline
11000 \SpecialChar ~
11001 \SpecialChar ~
11002 \SpecialChar ~
11003 \SpecialChar ~
11004 ...
11005
11006 \newline
11007 }
11008 \layout Standard
11009
11010 In the above example the variable
11011 \emph on
11012 i
11013 \emph default
11014  will be allocated in the external ram,
11015 \emph on
11016 bvar
11017 \emph default
11018  in bit addressable space and
11019 \emph on
11020  j
11021 \emph default
11022  in internal ram.
11023  When compiled with
11024 \emph on
11025 -
11026 \begin_inset ERT
11027 status Collapsed
11028
11029 \layout Standard
11030
11031 \backslash
11032 /
11033 \end_inset
11034
11035 -stack-auto
11036 \emph default
11037  or when a function is declared as
11038 \emph on
11039 reentrant
11040 \emph default
11041  this should only be done for static variables.
11042 \layout Standard
11043
11044 Parameters
11045 \begin_inset LatexCommand \index{function parameter}
11046
11047 \end_inset
11048
11049  however are not allowed any storage class
11050 \begin_inset LatexCommand \index{Storage class}
11051
11052 \end_inset
11053
11054 , (storage classes for parameters will be ignored), their allocation is
11055  governed by the memory model in use, and the reentrancy options.
11056 \layout Standard
11057
11058 It is however allowed to use bit parameters in reentrant functions and also
11059  non-static local bit variables are supported.
11060  Efficient use is limited to 8 semi-bitregisters in bit space.
11061  They are pushed and popped to stack as a single byte just like the normal
11062  registers.
11063 \layout Section
11064
11065 Overlaying
11066 \begin_inset LatexCommand \label{sub:Overlaying}
11067
11068 \end_inset
11069
11070
11071 \begin_inset LatexCommand \index{Overlaying}
11072
11073 \end_inset
11074
11075
11076 \layout Standard
11077
11078 For non-reentrant
11079 \begin_inset LatexCommand \index{reentrant}
11080
11081 \end_inset
11082
11083  functions SDCC will try to reduce internal ram space usage by overlaying
11084  parameters and local variables of a function (if possible).
11085  Parameters and local variables
11086 \begin_inset LatexCommand \index{local variables}
11087
11088 \end_inset
11089
11090  of a function will be allocated to an overlayable segment if the function
11091  has
11092 \emph on
11093 no other function calls and the function is non-reentrant and the memory
11094  model
11095 \begin_inset LatexCommand \index{Memory model}
11096
11097 \end_inset
11098
11099  is small.
11100
11101 \emph default
11102  If an explicit storage class
11103 \begin_inset LatexCommand \index{Storage class}
11104
11105 \end_inset
11106
11107  is specified for a local variable, it will NOT be overlayed.
11108 \layout Standard
11109
11110 Note that the compiler (not the linkage editor) makes the decision for overlayin
11111 g the data items.
11112  Functions that are called from an interrupt service routine
11113 \begin_inset Marginal
11114 collapsed true
11115
11116 \layout Standard
11117
11118
11119 \series bold
11120 !
11121 \end_inset
11122
11123  should be preceded by a #pragma\SpecialChar ~
11124 nooverlay
11125 \begin_inset LatexCommand \index{\#pragma nooverlay}
11126
11127 \end_inset
11128
11129  if they are not reentrant.
11130 \layout Standard
11131
11132 Also note that the compiler does not do any processing of inline assembler
11133  code, so the compiler might incorrectly assign local variables and parameters
11134  of a function into the overlay segment if the inline assembler code calls
11135  other c-functions that might use the overlay.
11136  In that case the #pragma\SpecialChar ~
11137 nooverlay should be used.
11138 \layout Standard
11139
11140 Parameters and local variables of functions that contain 16 or 32 bit multiplica
11141 tion
11142 \begin_inset LatexCommand \index{Multiplication}
11143
11144 \end_inset
11145
11146  or division
11147 \begin_inset LatexCommand \index{Division}
11148
11149 \end_inset
11150
11151  will NOT be overlayed since these are implemented using external functions,
11152  e.g.:
11153 \layout Verse
11154
11155
11156 \family typewriter
11157 #pragma save
11158 \newline
11159 #pragma nooverlay
11160 \begin_inset LatexCommand \index{\#pragma nooverlay}
11161
11162 \end_inset
11163
11164
11165 \newline
11166 void set_error(unsigned char errcd)
11167 \newline
11168 {
11169 \newline
11170 \SpecialChar ~
11171 \SpecialChar ~
11172 \SpecialChar ~
11173 \SpecialChar ~
11174 P3 = errcd;
11175 \newline
11176 }
11177 \newline
11178 #pragma restore
11179 \newline
11180
11181 \newline
11182 void some_isr () __interrupt
11183 \begin_inset LatexCommand \index{interrupt}
11184
11185 \end_inset
11186
11187  (2)
11188 \newline
11189 {
11190 \newline
11191 \SpecialChar ~
11192 \SpecialChar ~
11193 \SpecialChar ~
11194 \SpecialChar ~
11195 ...
11196 \newline
11197 \SpecialChar ~
11198 \SpecialChar ~
11199 \SpecialChar ~
11200 \SpecialChar ~
11201 set_error(10);
11202 \newline
11203 \SpecialChar ~
11204 \SpecialChar ~
11205 \SpecialChar ~
11206 \SpecialChar ~
11207 ...
11208
11209 \newline
11210 }
11211 \layout Standard
11212
11213 In the above example the parameter
11214 \emph on
11215 errcd
11216 \emph default
11217  for the function
11218 \emph on
11219 set_error
11220 \emph default
11221  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
11222 nooverlay was
11223  not present, this could cause unpredictable runtime behavior when called
11224  from an interrupt service routine.
11225  The #pragma\SpecialChar ~
11226 nooverlay ensures that the parameters and local variables for
11227  the function are NOT overlayed.
11228 \layout Section
11229
11230 Interrupt Service Routines
11231 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
11232
11233 \end_inset
11234
11235
11236 \layout Subsection
11237
11238 General Information
11239 \layout Standard
11240
11241 SDCC allows
11242 \emph on
11243 i
11244 \emph default
11245 nterrupt
11246 \emph on
11247 s
11248 \emph default
11249 ervice
11250 \emph on
11251 r
11252 \emph default
11253 outines to be coded in C, with some extended keywords.
11254 \layout Verse
11255
11256
11257 \family typewriter
11258 void timer_isr (void) __interrupt (1) __using (1)
11259 \newline
11260 {
11261 \newline
11262 \SpecialChar ~
11263 \SpecialChar ~
11264 \SpecialChar ~
11265 \SpecialChar ~
11266 ...
11267
11268 \newline
11269 }
11270 \layout Standard
11271
11272 The optional number following the
11273 \emph on
11274 interrupt
11275 \begin_inset LatexCommand \index{interrupt}
11276
11277 \end_inset
11278
11279
11280 \begin_inset LatexCommand \index{\_\_interrupt}
11281
11282 \end_inset
11283
11284
11285 \emph default
11286  keyword is the interrupt number this routine will service.
11287  When present, the compiler will insert a call to this routine in the interrupt
11288  vector table for the interrupt number specified.
11289  If you have multiple source files in your project, interrupt service routines
11290  can be present in any of them, but a prototype of the isr MUST be present
11291  or included in the file that contains the function
11292 \emph on
11293 main
11294 \emph default
11295 .
11296  The optional
11297 \emph on
11298 using
11299 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11300
11301 \end_inset
11302
11303
11304 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11305
11306 \end_inset
11307
11308
11309 \emph default
11310  keyword can be used to tell the compiler to use the specified register
11311  bank (8051 specific) when generating code for this function.
11312
11313 \newline
11314
11315 \layout Standard
11316
11317 Interrupt service routines open the door for some very interesting bugs:
11318 \newline
11319 If an interrupt service routine changes variables which are accessed by
11320  other functions these variables have to be declared
11321 \emph on
11322 volatile
11323 \emph default
11324
11325 \begin_inset LatexCommand \index{volatile}
11326
11327 \end_inset
11328
11329 .
11330
11331 \layout Standard
11332
11333 If the access to these variables is not
11334 \emph on
11335 atomic
11336 \begin_inset LatexCommand \index{atomic}
11337
11338 \end_inset
11339
11340
11341 \emph default
11342  (i.e.
11343  the processor needs more than one instruction for the access and could
11344  be interrupted while accessing the variable) the interrupt must be disabled
11345  during the access to avoid inconsistent data.
11346  Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
11347  and should be protected by disabling interrupts.
11348  You're not automatically on the safe side if you use 8 bit variables though.
11349  We need an example here: f.e.
11350  on the 8051 the harmless looking
11351 \begin_inset Quotes srd
11352 \end_inset
11353
11354
11355 \family typewriter
11356 flags\SpecialChar ~
11357 |=\SpecialChar ~
11358 0x80;
11359 \family default
11360
11361 \begin_inset Quotes sld
11362 \end_inset
11363
11364  is not atomic if
11365 \family typewriter
11366 flags
11367 \family default
11368  resides in xdata.
11369  Setting
11370 \begin_inset Quotes srd
11371 \end_inset
11372
11373
11374 \family typewriter
11375 flags\SpecialChar ~
11376 |=\SpecialChar ~
11377 0x40;
11378 \family default
11379
11380 \begin_inset Quotes sld
11381 \end_inset
11382
11383  from within an interrupt routine might get lost if the interrupt occurs
11384  at the wrong time.
11385
11386 \begin_inset Quotes sld
11387 \end_inset
11388
11389
11390 \family typewriter
11391 counter\SpecialChar ~
11392 +=\SpecialChar ~
11393 8;
11394 \family default
11395
11396 \begin_inset Quotes srd
11397 \end_inset
11398
11399  is not atomic on the 8051 even if
11400 \family typewriter
11401 counter
11402 \family default
11403  is located in data memory.
11404  Bugs like these are hard to reproduce and can cause a lot of trouble.
11405
11406 \layout Standard
11407
11408 The return address and the registers used in the interrupt service routine
11409  are saved on the stack
11410 \begin_inset LatexCommand \index{stack}
11411
11412 \end_inset
11413
11414  so there must be sufficient stack space.
11415  If there isn't variables or registers (or even the return address itself)
11416  will be corrupted.
11417  This
11418 \emph on
11419 stack overflow
11420 \emph default
11421
11422 \begin_inset LatexCommand \index{stack overflow}
11423
11424 \end_inset
11425
11426  is most likely to happen if the interrupt occurs during the
11427 \begin_inset Quotes sld
11428 \end_inset
11429
11430 deepest
11431 \begin_inset Quotes srd
11432 \end_inset
11433
11434  subroutine when the stack is already in use for f.e.
11435  many return addresses.
11436 \layout Standard
11437
11438 A special note here, int (16 bit) and long (32 bit) integer division
11439 \begin_inset LatexCommand \index{Division}
11440
11441 \end_inset
11442
11443 , multiplication
11444 \begin_inset LatexCommand \index{Multiplication}
11445
11446 \end_inset
11447
11448  & modulus
11449 \begin_inset LatexCommand \index{Modulus}
11450
11451 \end_inset
11452
11453  and floating-point
11454 \begin_inset LatexCommand \index{Floating point support}
11455
11456 \end_inset
11457
11458  operations are implemented using external support routines developed in
11459  ANSI-C.
11460  If an interrupt service routine needs to do any of these operations then
11461  the support routines (as mentioned in a following section) will have to
11462  be recompiled using the
11463 \emph on
11464  -
11465 \begin_inset ERT
11466 status Collapsed
11467
11468 \layout Standard
11469
11470 \backslash
11471 /
11472 \end_inset
11473
11474 -stack-auto
11475 \begin_inset LatexCommand \index{-\/-stack-auto}
11476
11477 \end_inset
11478
11479
11480 \emph default
11481  option and the source file will need to be compiled using the
11482 \emph on
11483 -
11484 \begin_inset ERT
11485 status Collapsed
11486
11487 \layout Standard
11488
11489 \backslash
11490 /
11491 \end_inset
11492
11493 -int-long-reent
11494 \emph default
11495
11496 \begin_inset LatexCommand \index{-\/-int-long-reent}
11497
11498 \end_inset
11499
11500  compiler option.
11501  Note, the type promotion
11502 \begin_inset LatexCommand \index{type promotion}
11503
11504 \end_inset
11505
11506  required by ANSI C can cause 16 bit routines to be used without the programmer
11507  being aware of it.
11508
11509 \layout Standard
11510
11511 Calling other functions from an interrupt service routine is not recommended,
11512  avoid it if possible.
11513  Note that when some function is called from an interrupt service routine
11514  it should be preceded by a #pragma\SpecialChar ~
11515 nooverlay
11516 \begin_inset LatexCommand \index{\#pragma nooverlay}
11517
11518 \end_inset
11519
11520  if it is not reentrant.
11521  Furthermore nonreentrant functions should not be called from the main program
11522  while the interrupt service routine might be active.
11523  They also must not be called from low priority interrupt service routines
11524  while a high priority interrupt service routine might be active.
11525  You could use semaphores or make the function
11526 \emph on
11527  critical
11528 \emph default
11529  if all parameters are passed in registers.
11530 \newline
11531
11532 \newline
11533 Also see section
11534 \begin_inset LatexCommand \ref{sub:Overlaying}
11535
11536 \end_inset
11537
11538 \SpecialChar ~
11539 about Overlaying and section
11540 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
11541
11542 \end_inset
11543
11544 \SpecialChar ~
11545 about Functions using private register banks.
11546 \layout Subsection
11547
11548 MCS51/DS390 Interrupt Service Routines
11549 \layout Standard
11550
11551 Interrupt numbers and the corresponding address & descriptions for the Standard
11552  8051/8052 are listed below.
11553  SDCC will automatically adjust the interrupt vector table to the maximum
11554  interrupt number specified.
11555 \newline
11556
11557 \layout Standard
11558 \align center
11559
11560 \begin_inset  Tabular
11561 <lyxtabular version="3" rows="9" columns="3">
11562 <features>
11563 <column alignment="center" valignment="top" leftline="true" width="0in">
11564 <column alignment="left" valignment="top" leftline="true" width="0in">
11565 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
11566 <row topline="true" bottomline="true">
11567 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11568 \begin_inset Text
11569
11570 \layout Standard
11571
11572 Interrupt #
11573 \end_inset
11574 </cell>
11575 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11576 \begin_inset Text
11577
11578 \layout Standard
11579
11580 Description
11581 \end_inset
11582 </cell>
11583 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11584 \begin_inset Text
11585
11586 \layout Standard
11587
11588 Vector Address
11589 \end_inset
11590 </cell>
11591 </row>
11592 <row topline="true">
11593 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11594 \begin_inset Text
11595
11596 \layout Standard
11597
11598 0
11599 \end_inset
11600 </cell>
11601 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11602 \begin_inset Text
11603
11604 \layout Standard
11605
11606 External 0
11607 \end_inset
11608 </cell>
11609 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11610 \begin_inset Text
11611
11612 \layout Standard
11613
11614 0x0003
11615 \end_inset
11616 </cell>
11617 </row>
11618 <row topline="true">
11619 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11620 \begin_inset Text
11621
11622 \layout Standard
11623
11624 1
11625 \end_inset
11626 </cell>
11627 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11628 \begin_inset Text
11629
11630 \layout Standard
11631
11632 Timer 0
11633 \end_inset
11634 </cell>
11635 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11636 \begin_inset Text
11637
11638 \layout Standard
11639
11640 0x000b
11641 \end_inset
11642 </cell>
11643 </row>
11644 <row topline="true">
11645 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11646 \begin_inset Text
11647
11648 \layout Standard
11649
11650 2
11651 \end_inset
11652 </cell>
11653 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11654 \begin_inset Text
11655
11656 \layout Standard
11657
11658 External 1
11659 \end_inset
11660 </cell>
11661 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11662 \begin_inset Text
11663
11664 \layout Standard
11665
11666 0x0013
11667 \end_inset
11668 </cell>
11669 </row>
11670 <row topline="true">
11671 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11672 \begin_inset Text
11673
11674 \layout Standard
11675
11676 3
11677 \end_inset
11678 </cell>
11679 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11680 \begin_inset Text
11681
11682 \layout Standard
11683
11684 Timer 1
11685 \end_inset
11686 </cell>
11687 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11688 \begin_inset Text
11689
11690 \layout Standard
11691
11692 0x001b
11693 \end_inset
11694 </cell>
11695 </row>
11696 <row topline="true">
11697 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11698 \begin_inset Text
11699
11700 \layout Standard
11701
11702 4
11703 \end_inset
11704 </cell>
11705 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11706 \begin_inset Text
11707
11708 \layout Standard
11709
11710 Serial
11711 \end_inset
11712 </cell>
11713 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11714 \begin_inset Text
11715
11716 \layout Standard
11717
11718 0x0023
11719 \end_inset
11720 </cell>
11721 </row>
11722 <row topline="true">
11723 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11724 \begin_inset Text
11725
11726 \layout Standard
11727
11728 5
11729 \end_inset
11730 </cell>
11731 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11732 \begin_inset Text
11733
11734 \layout Standard
11735
11736 Timer 2 (8052)
11737 \end_inset
11738 </cell>
11739 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11740 \begin_inset Text
11741
11742 \layout Standard
11743
11744 0x002b
11745 \end_inset
11746 </cell>
11747 </row>
11748 <row topline="true">
11749 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11750 \begin_inset Text
11751
11752 \layout Standard
11753
11754 ...
11755 \end_inset
11756 </cell>
11757 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11758 \begin_inset Text
11759
11760 \layout Standard
11761
11762 \end_inset
11763 </cell>
11764 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11765 \begin_inset Text
11766
11767 \layout Standard
11768
11769 ...
11770 \end_inset
11771 </cell>
11772 </row>
11773 <row topline="true" bottomline="true">
11774 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11775 \begin_inset Text
11776
11777 \layout Standard
11778
11779 n
11780 \end_inset
11781 </cell>
11782 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11783 \begin_inset Text
11784
11785 \layout Standard
11786
11787 \end_inset
11788 </cell>
11789 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11790 \begin_inset Text
11791
11792 \layout Standard
11793
11794 0x0003 + 8*n
11795 \end_inset
11796 </cell>
11797 </row>
11798 </lyxtabular>
11799
11800 \end_inset
11801
11802
11803 \newline
11804
11805 \layout Standard
11806
11807 If the interrupt service routine is defined without
11808 \emph on
11809 using
11810 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11811
11812 \end_inset
11813
11814
11815 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11816
11817 \end_inset
11818
11819
11820 \emph default
11821  a register bank or with register bank 0 (
11822 \emph on
11823 using
11824 \emph default
11825  0), the compiler will save the registers used by itself on the stack upon
11826  entry and restore them at exit, however if such an interrupt service routine
11827  calls another function then the entire register bank will be saved on the
11828  stack.
11829  This scheme may be advantageous for small interrupt service routines which
11830  have low register usage.
11831 \layout Standard
11832
11833 If the interrupt service routine is defined to be using a specific register
11834  bank then only
11835 \emph on
11836 a, b, dptr
11837 \emph default
11838  & psw are saved and restored, if such an interrupt service routine calls
11839  another function (using another register bank) then the entire register
11840  bank of the called function will be saved on the stack.
11841  This scheme is recommended for larger interrupt service routines.
11842 \layout Subsection
11843
11844 HC08 Interrupt Service Routines
11845 \layout Standard
11846
11847 Since the number of interrupts available is chip specific and the interrupt
11848  vector table always ends at the last byte of memory, the interrupt numbers
11849  corresponds to the interrupt vectors in reverse order of address.
11850  For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
11851  2 will use the interrupt vector at 0xfffa, and so on.
11852  However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
11853  this way; instead see section
11854 \begin_inset LatexCommand \ref{sub:Startup-Code}
11855
11856 \end_inset
11857
11858  for details on customizing startup.
11859 \layout Subsection
11860
11861 Z80 Interrupt Service Routines
11862 \layout Standard
11863
11864 The Z80 uses several different methods for determining the correct interrupt
11865  vector depending on the hardware implementation.
11866  Therefore, SDCC ignores the optional interrupt number and does not attempt
11867  to generate an interrupt vector table.
11868 \layout Standard
11869
11870 By default, SDCC generates code for a maskable interrupt, which uses a RETI
11871  instruction to return from the interrupt.
11872  To write an interrupt handler for the non-maskable interrupt, which needs
11873  a RETN instruction instead, add the
11874 \emph on
11875 critical
11876 \emph default
11877  keyword:
11878 \layout Verse
11879
11880
11881 \family typewriter
11882 void nmi_isr (void) critical interrupt
11883 \newline
11884 {
11885 \newline
11886 \SpecialChar ~
11887 \SpecialChar ~
11888 \SpecialChar ~
11889 \SpecialChar ~
11890 ...
11891
11892 \newline
11893 }
11894 \layout Standard
11895
11896 However if you need to create a non-interruptable interrupt service routine
11897  you would also require the
11898 \emph on
11899 critical
11900 \emph default
11901  keyword.
11902  To distinguish between this and an nmi_isr you must provide an interrupt
11903  number.
11904 \layout Section
11905
11906 Enabling and Disabling Interrupts
11907 \layout Subsection
11908
11909 Critical Functions and Critical Statements
11910 \layout Standard
11911
11912 A special keyword may be associated with a block or a function declaring
11913  it as
11914 \emph on
11915 critical
11916 \emph default
11917 .
11918  SDCC will generate code to disable all interrupts
11919 \begin_inset LatexCommand \index{interrupt}
11920
11921 \end_inset
11922
11923  upon entry to a critical function and restore the interrupt enable to the
11924  previous state before returning.
11925  Nesting critical functions will need one additional byte on the stack
11926 \begin_inset LatexCommand \index{stack}
11927
11928 \end_inset
11929
11930  for each call.
11931 \layout Verse
11932
11933
11934 \family typewriter
11935 int foo () __critical
11936 \begin_inset LatexCommand \index{critical}
11937
11938 \end_inset
11939
11940
11941 \begin_inset LatexCommand \index{\_\_critical}
11942
11943 \end_inset
11944
11945
11946 \newline
11947 {
11948 \newline
11949 \SpecialChar ~
11950 \SpecialChar ~
11951 \SpecialChar ~
11952 \SpecialChar ~
11953 ...
11954
11955 \newline
11956 \SpecialChar ~
11957 \SpecialChar ~
11958 \SpecialChar ~
11959 \SpecialChar ~
11960 ...
11961
11962 \newline
11963 }
11964 \layout Standard
11965
11966 The critical attribute maybe used with other attributes like
11967 \emph on
11968 reentrant.
11969 \emph default
11970
11971 \newline
11972 The keyword
11973 \emph on
11974 critical
11975 \emph default
11976  may also be used to disable interrupts more locally:
11977 \layout Verse
11978
11979
11980 \family typewriter
11981 __critical{ i++; }
11982 \layout Standard
11983
11984 More than one statement could have been included in the block.
11985 \layout Subsection
11986
11987 Enabling and Disabling Interrupts directly
11988 \layout Standard
11989
11990 Interrupts
11991 \begin_inset LatexCommand \index{interrupt}
11992
11993 \end_inset
11994
11995  can also be disabled and enabled directly (8051):
11996 \layout Verse
11997
11998
11999 \family typewriter
12000 EA = 0;\SpecialChar ~
12001 \SpecialChar ~
12002 \SpecialChar ~
12003 \SpecialChar ~
12004 \SpecialChar ~
12005 \SpecialChar ~
12006 \SpecialChar ~
12007 \SpecialChar ~
12008 \SpecialChar ~
12009 \SpecialChar ~
12010 \SpecialChar ~
12011 \SpecialChar ~
12012 or:\SpecialChar ~
12013 \SpecialChar ~
12014 \SpecialChar ~
12015 \SpecialChar ~
12016 \SpecialChar ~
12017 \SpecialChar ~
12018 \SpecialChar ~
12019 \SpecialChar ~
12020 \SpecialChar ~
12021 \SpecialChar ~
12022 \SpecialChar ~
12023 EA_SAVE = EA;
12024 \layout Verse
12025
12026
12027 \family typewriter
12028 ...\SpecialChar ~
12029 \SpecialChar ~
12030 \SpecialChar ~
12031 \SpecialChar ~
12032 \SpecialChar ~
12033 \SpecialChar ~
12034 \SpecialChar ~
12035 \SpecialChar ~
12036 \SpecialChar ~
12037 \SpecialChar ~
12038 \SpecialChar ~
12039 \SpecialChar ~
12040 \SpecialChar ~
12041 \SpecialChar ~
12042 \SpecialChar ~
12043 \SpecialChar ~
12044 \SpecialChar ~
12045 \SpecialChar ~
12046 \SpecialChar ~
12047 \SpecialChar ~
12048 \SpecialChar ~
12049 \SpecialChar ~
12050 \SpecialChar ~
12051 \SpecialChar ~
12052 \SpecialChar ~
12053 \SpecialChar ~
12054 \SpecialChar ~
12055 \SpecialChar ~
12056 \SpecialChar ~
12057 \SpecialChar ~
12058 EA = 0;
12059 \layout Verse
12060
12061
12062 \family typewriter
12063 EA = 1;\SpecialChar ~
12064 \SpecialChar ~
12065 \SpecialChar ~
12066 \SpecialChar ~
12067 \SpecialChar ~
12068 \SpecialChar ~
12069 \SpecialChar ~
12070 \SpecialChar ~
12071 \SpecialChar ~
12072 \SpecialChar ~
12073 \SpecialChar ~
12074 \SpecialChar ~
12075 \SpecialChar ~
12076 \SpecialChar ~
12077 \SpecialChar ~
12078 \SpecialChar ~
12079 \SpecialChar ~
12080 \SpecialChar ~
12081 \SpecialChar ~
12082 \SpecialChar ~
12083 \SpecialChar ~
12084 \SpecialChar ~
12085 \SpecialChar ~
12086 \SpecialChar ~
12087 \SpecialChar ~
12088 \SpecialChar ~
12089 ...
12090 \layout Verse
12091
12092
12093 \family typewriter
12094 \SpecialChar ~
12095 \SpecialChar ~
12096 \SpecialChar ~
12097 \SpecialChar ~
12098 \SpecialChar ~
12099 \SpecialChar ~
12100 \SpecialChar ~
12101 \SpecialChar ~
12102 \SpecialChar ~
12103 \SpecialChar ~
12104 \SpecialChar ~
12105 \SpecialChar ~
12106 \SpecialChar ~
12107 \SpecialChar ~
12108 \SpecialChar ~
12109 \SpecialChar ~
12110 \SpecialChar ~
12111 \SpecialChar ~
12112 \SpecialChar ~
12113 \SpecialChar ~
12114 \SpecialChar ~
12115 \SpecialChar ~
12116 \SpecialChar ~
12117 \SpecialChar ~
12118 \SpecialChar ~
12119 \SpecialChar ~
12120 \SpecialChar ~
12121 \SpecialChar ~
12122 \SpecialChar ~
12123 \SpecialChar ~
12124 \SpecialChar ~
12125 \SpecialChar ~
12126 \SpecialChar ~
12127 EA = EA_SAVE;
12128 \layout Standard
12129
12130 On other architectures which have seperate opcodes for enabling and disabling
12131  interrupts you might want to make use of defines with inline assembly
12132 \begin_inset LatexCommand \index{Assembler routines}
12133
12134 \end_inset
12135
12136  (HC08):
12137 \layout Verse
12138
12139
12140 \family typewriter
12141 #define CLI _asm
12142 \begin_inset LatexCommand \index{\_asm}
12143
12144 \end_inset
12145
12146 \SpecialChar ~
12147 \SpecialChar ~
12148 cli\SpecialChar ~
12149 \SpecialChar ~
12150 _endasm
12151 \begin_inset LatexCommand \index{\_endasm}
12152
12153 \end_inset
12154
12155 ;
12156 \layout Verse
12157
12158
12159 \family typewriter
12160 #define SEI _asm\SpecialChar ~
12161 \SpecialChar ~
12162 sei\SpecialChar ~
12163 \SpecialChar ~
12164 _endasm;
12165 \layout Verse
12166
12167
12168 \family typewriter
12169 ...
12170 \layout Standard
12171
12172 Note: it is sometimes sufficient to disable only a specific interrupt source
12173  like f.e.
12174  a timer or serial interrupt by manipulating an
12175 \emph on
12176 interrupt mask
12177 \begin_inset LatexCommand \index{interrupt mask}
12178
12179 \end_inset
12180
12181
12182 \emph default
12183  register.
12184
12185 \layout Standard
12186
12187 Usually the time during which interrupts are disabled should be kept as
12188  short as possible.
12189  This minimizes both
12190 \emph on
12191 interrupt latency
12192 \emph default
12193
12194 \begin_inset LatexCommand \index{interrupt latency}
12195
12196 \end_inset
12197
12198  (the time between the occurrence of the interrupt and the execution of
12199  the first code in the interrupt routine) and
12200 \emph on
12201 interrupt jitter
12202 \emph default
12203
12204 \begin_inset LatexCommand \index{interrupt jitter}
12205
12206 \end_inset
12207
12208  (the difference between the shortest and the longest interrupt latency).
12209  These really are something different, f.e.
12210  a serial interrupt has to be served before its buffer overruns so it cares
12211  for the maximum interrupt latency, whereas it does not care about jitter.
12212  On a loudspeaker driven via a digital to analog converter which is fed
12213  by an interrupt a latency of a few milliseconds might be tolerable, whereas
12214  a much smaller jitter will be very audible.
12215 \layout Standard
12216
12217 You can reenable interrupts within an interrupt routine and on some architecture
12218 s you can make use of two (or more) levels of
12219 \emph on
12220 interrupt priorities
12221 \emph default
12222
12223 \begin_inset LatexCommand \index{interrupt priority}
12224
12225 \end_inset
12226
12227 .
12228  On some architectures which don't support interrupt priorities these can
12229  be implemented by manipulating the interrupt mask and reenabling interrupts
12230  within the interrupt routine.
12231  Check there is sufficient space on the stack
12232 \begin_inset LatexCommand \index{stack}
12233
12234 \end_inset
12235
12236  and don't add complexity unless you have to.
12237
12238 \layout Subsection
12239
12240 Semaphore
12241 \begin_inset LatexCommand \index{semaphore}
12242
12243 \end_inset
12244
12245  locking (mcs51/ds390)
12246 \layout Standard
12247
12248 Some architectures (mcs51/ds390) have an atomic
12249 \begin_inset LatexCommand \index{atomic}
12250
12251 \end_inset
12252
12253  bit test and
12254 \emph on
12255
12256 \emph default
12257 clear
12258 \emph on
12259
12260 \emph default
12261 instruction.
12262  These type of instructions are typically used in preemptive multitasking
12263  systems, where a routine f.e.
12264  claims the use of a data structure ('acquires a lock
12265 \begin_inset LatexCommand \index{lock}
12266
12267 \end_inset
12268
12269  on it'), makes some modifications and then releases the lock when the data
12270  structure is consistent again.
12271  The instruction may also be used if interrupt and non-interrupt code have
12272  to compete for a resource.
12273  With the atomic bit test and clear instruction interrupts
12274 \begin_inset LatexCommand \index{interrupt}
12275
12276 \end_inset
12277
12278  don't have to be disabled for the locking operation.
12279
12280 \layout Standard
12281
12282 SDCC generates this instruction if the source follows this pattern:
12283 \layout Verse
12284
12285
12286 \family typewriter
12287 volatile
12288 \begin_inset LatexCommand \index{volatile}
12289
12290 \end_inset
12291
12292  bit resource_is_free;
12293 \newline
12294
12295 \newline
12296 if (resource_is_free)
12297 \newline
12298 \SpecialChar ~
12299 \SpecialChar ~
12300 {
12301 \newline
12302 \SpecialChar ~
12303 \SpecialChar ~
12304 \SpecialChar ~
12305 \SpecialChar ~
12306 resource_is_free=0;
12307 \newline
12308 \SpecialChar ~
12309 \SpecialChar ~
12310 \SpecialChar ~
12311 \SpecialChar ~
12312 ...
12313
12314 \newline
12315 \SpecialChar ~
12316 \SpecialChar ~
12317 \SpecialChar ~
12318 \SpecialChar ~
12319 resource_is_free=1;
12320 \newline
12321 \SpecialChar ~
12322 \SpecialChar ~
12323 }
12324 \layout Standard
12325
12326 Note, mcs51 and ds390 support only an atomic
12327 \begin_inset LatexCommand \index{atomic}
12328
12329 \end_inset
12330
12331  bit test and
12332 \emph on
12333 clear
12334 \emph default
12335  instruction (as opposed to atomic bit test and
12336 \emph on
12337 set).
12338 \layout Section
12339
12340 Functions using private register banks
12341 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
12342
12343 \end_inset
12344
12345  (mcs51/ds390)
12346 \layout Standard
12347
12348 Some architectures have support for quickly changing register sets.
12349  SDCC supports this feature with the
12350 \emph on
12351 using
12352 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
12353
12354 \end_inset
12355
12356
12357 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
12358
12359 \end_inset
12360
12361
12362 \emph default
12363  attribute (which tells the compiler to use a register bank
12364 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
12365
12366 \end_inset
12367
12368  other than the default bank zero).
12369  It should only be applied to
12370 \emph on
12371 interrupt
12372 \begin_inset LatexCommand \index{interrupt}
12373
12374 \end_inset
12375
12376
12377 \emph default
12378  functions (see footnote below).
12379  This will in most circumstances make the generated ISR code more efficient
12380  since it will not have to save registers on the stack.
12381 \layout Standard
12382
12383 The
12384 \emph on
12385 using
12386 \emph default
12387  attribute will have no effect on the generated code for a
12388 \emph on
12389 non-interrupt
12390 \emph default
12391  function (but may occasionally be useful anyway
12392 \begin_inset Foot
12393 collapsed false
12394
12395 \layout Standard
12396
12397 possible exception: if a function is called ONLY from 'interrupt' functions
12398  using a particular bank, it can be declared with the same 'using' attribute
12399  as the calling 'interrupt' functions.
12400  For instance, if you have several ISRs using bank one, and all of them
12401  call memcpy(), it might make sense to create a specialized version of memcpy()
12402  'using 1', since this would prevent the ISR from having to save bank zero
12403  to the stack on entry and switch to bank zero before calling the function
12404 \end_inset
12405
12406 ).
12407 \newline
12408
12409 \emph on
12410 (pending: I don't think this has been done yet)
12411 \layout Standard
12412
12413 An
12414 \emph on
12415 interrupt
12416 \emph default
12417  function using a non-zero bank will assume that it can trash that register
12418  bank, and will not save it.
12419  Since high-priority interrupts
12420 \begin_inset LatexCommand \index{interrupts}
12421
12422 \end_inset
12423
12424
12425 \begin_inset LatexCommand \index{interrupt priority}
12426
12427 \end_inset
12428
12429  can interrupt low-priority ones on the 8051 and friends, this means that
12430  if a high-priority ISR
12431 \emph on
12432 using
12433 \emph default
12434  a particular bank occurs while processing a low-priority ISR
12435 \emph on
12436 using
12437 \emph default
12438  the same bank, terrible and bad things can happen.
12439  To prevent this, no single register bank should be
12440 \emph on
12441 used
12442 \emph default
12443  by both a high priority and a low priority ISR.
12444  This is probably most easily done by having all high priority ISRs use
12445  one bank and all low priority ISRs use another.
12446  If you have an ISR which can change priority at runtime, you're on your
12447  own: I suggest using the default bank zero and taking the small performance
12448  hit.
12449 \layout Standard
12450
12451 It is most efficient if your ISR calls no other functions.
12452  If your ISR must call other functions, it is most efficient if those functions
12453  use the same bank as the ISR (see note 1 below); the next best is if the
12454  called functions use bank zero.
12455  It is very inefficient to call a function using a different, non-zero bank
12456  from an ISR.
12457
12458 \layout Section
12459
12460 Startup Code
12461 \begin_inset LatexCommand \label{sub:Startup-Code}
12462
12463 \end_inset
12464
12465
12466 \begin_inset LatexCommand \index{Startup code}
12467
12468 \end_inset
12469
12470
12471 \layout Subsection
12472
12473 MCS51/DS390 Startup Code
12474 \layout Standard
12475
12476 The compiler inserts a call to the C routine
12477 \emph on
12478 _sdcc_external_startup()
12479 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
12480
12481 \end_inset
12482
12483
12484 \series bold
12485 \emph default
12486
12487 \series default
12488 at the start of the CODE area.
12489  This routine is in the runtime library
12490 \begin_inset LatexCommand \index{Runtime library}
12491
12492 \end_inset
12493
12494 .
12495  By default this routine returns 0, if this routine returns a non-zero value,
12496  the static & global variable initialization will be skipped and the function
12497  main will be invoked.
12498  Otherwise static & global variables will be initialized before the function
12499  main is invoked.
12500  You could add a
12501 \emph on
12502 _sdcc_external_startup()
12503 \emph default
12504  routine to your program to override the default if you need to setup hardware
12505  or perform some other critical operation prior to static & global variable
12506  initialization
12507 \begin_inset LatexCommand \index{Variable initialization}
12508
12509 \end_inset
12510
12511 .
12512  On some mcs51 variants xdata
12513 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
12514
12515 \end_inset
12516
12517  memory has to be explicitly enabled before it can be accessed or if the
12518  watchdog needs to be disabled, this is the place to do it.
12519  The startup code clears all internal data memory, 256 bytes by default,
12520  but from 0 to n-1 if
12521 \emph on
12522 -
12523 \begin_inset ERT
12524 status Collapsed
12525
12526 \layout Standard
12527
12528 \backslash
12529 /
12530 \end_inset
12531
12532 -iram-size
12533 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
12534
12535 \end_inset
12536
12537 n
12538 \emph default
12539  is used.
12540  (recommended for Chipcon CC1010).
12541 \layout Standard
12542
12543 See also the compiler option
12544 \emph on
12545 -
12546 \begin_inset ERT
12547 status Collapsed
12548
12549 \layout Standard
12550
12551 \backslash
12552 /
12553 \end_inset
12554
12555 -no-xinit
12556 \emph default
12557 -
12558 \emph on
12559 opt
12560 \emph default
12561
12562 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
12563
12564 \end_inset
12565
12566  and section
12567 \begin_inset LatexCommand \ref{sub:MCS51-variants}
12568
12569 \end_inset
12570
12571 \SpecialChar ~
12572 about MCS51-variants.
12573 \layout Subsection
12574
12575 HC08 Startup Code
12576 \layout Standard
12577
12578 The HC08 startup code follows the same scheme as the MCS51 startup code.
12579 \layout Subsection
12580
12581 Z80 Startup Code
12582 \layout Standard
12583
12584 On the Z80 the startup code is inserted by linking with crt0.o which is generated
12585  from sdcc/device/lib/z80/crt0.s.
12586  If you need a different startup code you can use the compiler option
12587 \emph on
12588 -
12589 \series bold
12590 \emph default
12591
12592 \begin_inset ERT
12593 status Collapsed
12594
12595 \layout Standard
12596
12597 \backslash
12598 /
12599 \end_inset
12600
12601
12602 \series default
12603 \emph on
12604 -no-std-crt0
12605 \emph default
12606
12607 \begin_inset LatexCommand \index{-\/-no-std-crt0}
12608
12609 \end_inset
12610
12611  and provide your own crt0.o.
12612
12613 \layout Section
12614
12615 Inline Assembler Code
12616 \begin_inset LatexCommand \index{Assembler routines}
12617
12618 \end_inset
12619
12620
12621 \layout Subsection
12622
12623 A Step by Step Introduction
12624 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
12625
12626 \end_inset
12627
12628
12629 \layout Standard
12630
12631 Starting from a small snippet of c-code this example shows for the MCS51
12632  how to use inline assembly, access variables, a function parameter and
12633  an array in xdata memory.
12634  The example uses an MCS51 here but is easily adapted for other architectures.
12635  This is a buffer routine which should be optimized:
12636 \layout Verse
12637
12638
12639 \family typewriter
12640 \size footnotesize
12641 unsigned char far
12642 \begin_inset LatexCommand \index{far (storage class)}
12643
12644 \end_inset
12645
12646
12647 \begin_inset LatexCommand \index{\_\_far (storage class)}
12648
12649 \end_inset
12650
12651  __at
12652 \begin_inset LatexCommand \index{at}
12653
12654 \end_inset
12655
12656
12657 \begin_inset LatexCommand \index{\_\_at}
12658
12659 \end_inset
12660
12661 (0x7f00) buf[0x100];
12662 \begin_inset LatexCommand \index{Aligned array}
12663
12664 \end_inset
12665
12666
12667 \newline
12668 unsigned char head, tail;
12669 \newline
12670
12671 \newline
12672 void to_buffer( unsigned char c )
12673 \newline
12674 {
12675 \newline
12676 \SpecialChar ~
12677 \SpecialChar ~
12678 \SpecialChar ~
12679 \SpecialChar ~
12680 if( head != (unsigned char)(tail-1) )\SpecialChar ~
12681 /* cast
12682 \series bold
12683 needed
12684 \series default
12685  to avoid promotion
12686 \begin_inset LatexCommand \index{promotion to signed int}
12687
12688 \end_inset
12689
12690
12691 \begin_inset LatexCommand \index{type promotion}
12692
12693 \end_inset
12694
12695  to integer */
12696 \begin_inset Marginal
12697 collapsed false
12698
12699 \layout Standard
12700
12701
12702 \series bold
12703 !
12704 \end_inset
12705
12706
12707 \newline
12708 \SpecialChar ~
12709 \SpecialChar ~
12710 \SpecialChar ~
12711 \SpecialChar ~
12712 \SpecialChar ~
12713 \SpecialChar ~
12714 \SpecialChar ~
12715 \SpecialChar ~
12716 buf[ head++ ] = c;\SpecialChar ~
12717 \SpecialChar ~
12718 \SpecialChar ~
12719 \SpecialChar ~
12720 \SpecialChar ~
12721 \SpecialChar ~
12722 \SpecialChar ~
12723 \SpecialChar ~
12724 \SpecialChar ~
12725 \SpecialChar ~
12726 \SpecialChar ~
12727 \SpecialChar ~
12728 \SpecialChar ~
12729 \SpecialChar ~
12730 \SpecialChar ~
12731 \SpecialChar ~
12732 /* access to a 256 byte aligned array */
12733 \newline
12734 }
12735 \layout Standard
12736
12737 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
12738  then a corresponding buffer.asm file is generated.
12739  We define a new function
12740 \family typewriter
12741 to_buffer_asm()
12742 \family default
12743  in file buffer.c in which we cut and paste the generated code, removing
12744  unwanted comments and some ':'.
12745  Then add
12746 \begin_inset Quotes sld
12747 \end_inset
12748
12749 _asm
12750 \begin_inset Quotes srd
12751 \end_inset
12752
12753  and
12754 \begin_inset Quotes sld
12755 \end_inset
12756
12757 _endasm;
12758 \begin_inset Quotes srd
12759 \end_inset
12760
12761  to the beginning and the end of the function body:
12762 \layout Verse
12763
12764
12765 \family typewriter
12766 \size footnotesize
12767 /* With a cut and paste from the .asm file, we have something to start with.
12768 \newline
12769 \SpecialChar ~
12770 \SpecialChar ~
12771 \SpecialChar ~
12772 The function is not yet OK! (registers aren't saved) */
12773 \newline
12774 void to_buffer_asm( unsigned char c )
12775 \newline
12776 {
12777 \newline
12778 \SpecialChar ~
12779 \SpecialChar ~
12780 \SpecialChar ~
12781 \SpecialChar ~
12782 _asm
12783 \begin_inset LatexCommand \index{\_asm}
12784
12785 \end_inset
12786
12787
12788 \begin_inset LatexCommand \index{\_\_asm}
12789
12790 \end_inset
12791
12792
12793 \newline
12794 \SpecialChar ~
12795 \SpecialChar ~
12796 \SpecialChar ~
12797 \SpecialChar ~
12798 mov\SpecialChar ~
12799 \SpecialChar ~
12800 r2,dpl
12801 \newline
12802 ;buffer.c if( head != (unsigned char)(tail-1) )
12803 \newline
12804 \SpecialChar ~
12805 \SpecialChar ~
12806 \SpecialChar ~
12807 \SpecialChar ~
12808 mov\SpecialChar ~
12809 \SpecialChar ~
12810 a,_tail
12811 \newline
12812 \SpecialChar ~
12813 \SpecialChar ~
12814 \SpecialChar ~
12815 \SpecialChar ~
12816 dec\SpecialChar ~
12817 \SpecialChar ~
12818 a
12819 \newline
12820 \SpecialChar ~
12821 \SpecialChar ~
12822 \SpecialChar ~
12823 \SpecialChar ~
12824 mov\SpecialChar ~
12825 \SpecialChar ~
12826 r3,a
12827 \newline
12828 \SpecialChar ~
12829 \SpecialChar ~
12830 \SpecialChar ~
12831 \SpecialChar ~
12832 mov\SpecialChar ~
12833 \SpecialChar ~
12834 a,_head
12835 \newline
12836 \SpecialChar ~
12837 \SpecialChar ~
12838 \SpecialChar ~
12839 \SpecialChar ~
12840 cjne a,ar3,00106$
12841 \newline
12842 \SpecialChar ~
12843 \SpecialChar ~
12844 \SpecialChar ~
12845 \SpecialChar ~
12846 ret
12847 \newline
12848 00106$:
12849 \newline
12850 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
12851 \begin_inset LatexCommand \index{Aligned array}
12852
12853 \end_inset
12854
12855
12856 \newline
12857 \SpecialChar ~
12858 \SpecialChar ~
12859 \SpecialChar ~
12860 \SpecialChar ~
12861 mov\SpecialChar ~
12862 \SpecialChar ~
12863 r3,_head
12864 \newline
12865 \SpecialChar ~
12866 \SpecialChar ~
12867 \SpecialChar ~
12868 \SpecialChar ~
12869 inc\SpecialChar ~
12870 \SpecialChar ~
12871 _head
12872 \newline
12873 \SpecialChar ~
12874 \SpecialChar ~
12875 \SpecialChar ~
12876 \SpecialChar ~
12877 mov\SpecialChar ~
12878 \SpecialChar ~
12879 dpl,r3
12880 \newline
12881 \SpecialChar ~
12882 \SpecialChar ~
12883 \SpecialChar ~
12884 \SpecialChar ~
12885 mov\SpecialChar ~
12886 \SpecialChar ~
12887 dph,#(_buf >> 8)
12888 \newline
12889 \SpecialChar ~
12890 \SpecialChar ~
12891 \SpecialChar ~
12892 \SpecialChar ~
12893 mov\SpecialChar ~
12894 \SpecialChar ~
12895 a,r2
12896 \newline
12897 \SpecialChar ~
12898 \SpecialChar ~
12899 \SpecialChar ~
12900 \SpecialChar ~
12901 movx @dptr,a
12902 \newline
12903 00103$:
12904 \newline
12905 \SpecialChar ~
12906 \SpecialChar ~
12907 \SpecialChar ~
12908 \SpecialChar ~
12909 ret
12910 \newline
12911 \SpecialChar ~
12912 \SpecialChar ~
12913 \SpecialChar ~
12914 \SpecialChar ~
12915 _endasm
12916 \begin_inset LatexCommand \index{\_endasm}
12917
12918 \end_inset
12919
12920
12921 \begin_inset LatexCommand \index{\_\_endasm}
12922
12923 \end_inset
12924
12925 ;
12926 \newline
12927 }
12928 \layout Standard
12929
12930 The new file buffer.c should compile with only one warning about the unreferenced
12931  function argument 'c'.
12932  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
12933  (1) and finally have:
12934 \layout Verse
12935
12936
12937 \family typewriter
12938 \size footnotesize
12939 unsigned char far __at(0x7f00) buf[0x100];
12940 \newline
12941 unsigned char head, tail;
12942 \newline
12943 #define USE_ASSEMBLY (1)
12944 \newline
12945
12946 \newline
12947 #if !USE_ASSEMBLY
12948 \newline
12949
12950 \newline
12951 void to_buffer( unsigned char c )
12952 \newline
12953 {
12954 \newline
12955 \SpecialChar ~
12956 \SpecialChar ~
12957 \SpecialChar ~
12958 \SpecialChar ~
12959 if( head != (unsigned char)(tail-1) )
12960 \newline
12961 \SpecialChar ~
12962 \SpecialChar ~
12963 \SpecialChar ~
12964 \SpecialChar ~
12965 \SpecialChar ~
12966 \SpecialChar ~
12967 \SpecialChar ~
12968 \SpecialChar ~
12969 buf[ head++ ] = c;
12970 \newline
12971 }
12972 \newline
12973
12974 \newline
12975 #else
12976 \newline
12977
12978 \newline
12979 void to_buffer( unsigned char c )
12980 \newline
12981 {
12982 \newline
12983 \SpecialChar ~
12984 \SpecialChar ~
12985 \SpecialChar ~
12986 \SpecialChar ~
12987 c; // to avoid warning: unreferenced function argument
12988 \newline
12989 \SpecialChar ~
12990 \SpecialChar ~
12991 \SpecialChar ~
12992 \SpecialChar ~
12993 _asm
12994 \begin_inset LatexCommand \index{\_asm}
12995
12996 \end_inset
12997
12998
12999 \begin_inset LatexCommand \index{\_\_asm}
13000
13001 \end_inset
13002
13003
13004 \newline
13005 \SpecialChar ~
13006 \SpecialChar ~
13007 \SpecialChar ~
13008 \SpecialChar ~
13009 \SpecialChar ~
13010 \SpecialChar ~
13011 \SpecialChar ~
13012 \SpecialChar ~
13013 ; save used registers here.
13014
13015 \newline
13016 \SpecialChar ~
13017 \SpecialChar ~
13018 \SpecialChar ~
13019 \SpecialChar ~
13020 \SpecialChar ~
13021 \SpecialChar ~
13022 \SpecialChar ~
13023 \SpecialChar ~
13024 ; If we were still using r2,r3 we would have to push them here.
13025
13026 \newline
13027 ; if( head != (unsigned char)(tail-1) )
13028 \newline
13029 \SpecialChar ~
13030 \SpecialChar ~
13031 \SpecialChar ~
13032 \SpecialChar ~
13033 \SpecialChar ~
13034 \SpecialChar ~
13035 \SpecialChar ~
13036 \SpecialChar ~
13037 mov\SpecialChar ~
13038  a,_tail
13039 \newline
13040 \SpecialChar ~
13041 \SpecialChar ~
13042 \SpecialChar ~
13043 \SpecialChar ~
13044 \SpecialChar ~
13045 \SpecialChar ~
13046 \SpecialChar ~
13047 \SpecialChar ~
13048 dec\SpecialChar ~
13049  a
13050 \newline
13051 \SpecialChar ~
13052 \SpecialChar ~
13053 \SpecialChar ~
13054 \SpecialChar ~
13055 \SpecialChar ~
13056 \SpecialChar ~
13057 \SpecialChar ~
13058 \SpecialChar ~
13059 xrl\SpecialChar ~
13060  a,_head
13061 \newline
13062 \SpecialChar ~
13063 \SpecialChar ~
13064 \SpecialChar ~
13065 \SpecialChar ~
13066 \SpecialChar ~
13067 \SpecialChar ~
13068 \SpecialChar ~
13069 \SpecialChar ~
13070 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
13071 \newline
13072 \SpecialChar ~
13073 \SpecialChar ~
13074 \SpecialChar ~
13075 \SpecialChar ~
13076 \SpecialChar ~
13077 \SpecialChar ~
13078 \SpecialChar ~
13079 \SpecialChar ~
13080 jz\SpecialChar ~
13081 \SpecialChar ~
13082  t_b_end$
13083 \newline
13084 \SpecialChar ~
13085 \SpecialChar ~
13086 \SpecialChar ~
13087 \SpecialChar ~
13088 \SpecialChar ~
13089 \SpecialChar ~
13090 \SpecialChar ~
13091 \SpecialChar ~
13092 ;
13093 \newline
13094 ; buf[ head++ ] = c;
13095 \newline
13096 \SpecialChar ~
13097 \SpecialChar ~
13098 \SpecialChar ~
13099 \SpecialChar ~
13100 \SpecialChar ~
13101 \SpecialChar ~
13102 \SpecialChar ~
13103 \SpecialChar ~
13104 mov\SpecialChar ~
13105  a,dpl \SpecialChar ~
13106 \SpecialChar ~
13107 \SpecialChar ~
13108 \SpecialChar ~
13109 \SpecialChar ~
13110 \SpecialChar ~
13111 \SpecialChar ~
13112 ; dpl holds lower byte of function argument
13113 \newline
13114 \SpecialChar ~
13115 \SpecialChar ~
13116 \SpecialChar ~
13117 \SpecialChar ~
13118 \SpecialChar ~
13119 \SpecialChar ~
13120 \SpecialChar ~
13121 \SpecialChar ~
13122 mov\SpecialChar ~
13123  dpl,_head \SpecialChar ~
13124 \SpecialChar ~
13125 \SpecialChar ~
13126 ; buf is 0x100 byte aligned so head can be used directly
13127 \newline
13128 \SpecialChar ~
13129 \SpecialChar ~
13130 \SpecialChar ~
13131 \SpecialChar ~
13132 \SpecialChar ~
13133 \SpecialChar ~
13134 \SpecialChar ~
13135 \SpecialChar ~
13136 mov\SpecialChar ~
13137  dph,#(_buf>>8)
13138 \newline
13139 \SpecialChar ~
13140 \SpecialChar ~
13141 \SpecialChar ~
13142 \SpecialChar ~
13143 \SpecialChar ~
13144 \SpecialChar ~
13145 \SpecialChar ~
13146 \SpecialChar ~
13147 movx @dptr,a
13148 \newline
13149 \SpecialChar ~
13150 \SpecialChar ~
13151 \SpecialChar ~
13152 \SpecialChar ~
13153 \SpecialChar ~
13154 \SpecialChar ~
13155 \SpecialChar ~
13156 \SpecialChar ~
13157 inc \SpecialChar ~
13158 _head
13159 \newline
13160 \SpecialChar ~
13161 \SpecialChar ~
13162 \SpecialChar ~
13163 \SpecialChar ~
13164 \SpecialChar ~
13165 \SpecialChar ~
13166 \SpecialChar ~
13167 \SpecialChar ~
13168 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
13169 \newline
13170 t_b_end$:
13171 \newline
13172 \SpecialChar ~
13173 \SpecialChar ~
13174 \SpecialChar ~
13175 \SpecialChar ~
13176 \SpecialChar ~
13177 \SpecialChar ~
13178 \SpecialChar ~
13179 \SpecialChar ~
13180 ; restore used registers here
13181 \newline
13182 \SpecialChar ~
13183 \SpecialChar ~
13184 \SpecialChar ~
13185 \SpecialChar ~
13186 _endasm
13187 \begin_inset LatexCommand \index{\_endasm}
13188
13189 \end_inset
13190
13191
13192 \begin_inset LatexCommand \index{\_\_endasm}
13193
13194 \end_inset
13195
13196 ;
13197 \newline
13198 }
13199 \newline
13200 #endif
13201 \layout Standard
13202
13203 The inline assembler code can contain any valid code understood by the assembler
13204 , this includes any assembler directives and comment lines
13205 \begin_inset Foot
13206 collapsed false
13207
13208 \layout Standard
13209
13210 The assembler does not like some characters like ':' or ''' in comments.
13211  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
13212 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
13213
13214 \end_inset
13215
13216
13217 \begin_inset LatexCommand \index{Assembler documentation}
13218
13219 \end_inset
13220
13221
13222 \end_inset
13223
13224 .
13225  The compiler does not do any validation of the code within the
13226 \family typewriter
13227 _asm
13228 \begin_inset LatexCommand \index{\_asm}
13229
13230 \end_inset
13231
13232
13233 \begin_inset LatexCommand \index{\_\_asm}
13234
13235 \end_inset
13236
13237  ...
13238  _endasm
13239 \size footnotesize
13240
13241 \begin_inset LatexCommand \index{\_endasm}
13242
13243 \end_inset
13244
13245
13246 \begin_inset LatexCommand \index{\_\_endasm}
13247
13248 \end_inset
13249
13250
13251 \size default
13252 ;
13253 \family default
13254  keyword pair.
13255  Specifically it will not know which registers are used and thus register
13256  pushing/popping
13257 \begin_inset LatexCommand \index{push/pop}
13258
13259 \end_inset
13260
13261  has to be done manually.
13262
13263 \layout Standard
13264
13265 It is recommended that each assembly instruction (including labels) be placed
13266  in a separate line (as the example shows).
13267  When the -
13268 \begin_inset ERT
13269 status Collapsed
13270
13271 \layout Standard
13272
13273 \backslash
13274 /
13275 \end_inset
13276
13277 -
13278 \emph on
13279 peep-asm
13280 \begin_inset LatexCommand \index{-\/-peep-asm}
13281
13282 \end_inset
13283
13284
13285 \emph default
13286  command line option is used, the inline assembler code will be passed through
13287  the peephole optimizer
13288 \begin_inset LatexCommand \index{Peephole optimizer}
13289
13290 \end_inset
13291
13292 .
13293  There are only a few (if any) cases where this option makes sense, it might
13294  cause some unexpected changes in the inline assembler code.
13295  Please go through the peephole optimizer rules defined in file
13296 \emph on
13297 SDCCpeeph.def
13298 \emph default
13299  before using this option.
13300 \layout Subsection
13301
13302 Naked Functions
13303 \begin_inset LatexCommand \label{sub:Naked-Functions}
13304
13305 \end_inset
13306
13307
13308 \begin_inset LatexCommand \index{Naked functions}
13309
13310 \end_inset
13311
13312
13313 \layout Standard
13314
13315 A special keyword may be associated with a function declaring it as
13316 \emph on
13317 _naked
13318 \begin_inset LatexCommand \index{\_naked}
13319
13320 \end_inset
13321
13322
13323 \begin_inset LatexCommand \index{\_\_naked}
13324
13325 \end_inset
13326
13327 .
13328
13329 \emph default
13330 The
13331 \emph on
13332 _naked
13333 \emph default
13334  function modifier attribute prevents the compiler from generating prologue
13335 \begin_inset LatexCommand \index{function prologue}
13336
13337 \end_inset
13338
13339  and epilogue
13340 \begin_inset LatexCommand \index{function epilogue}
13341
13342 \end_inset
13343
13344  code for that function.
13345  This means that the user is entirely responsible for such things as saving
13346  any registers that may need to be preserved, selecting the proper register
13347  bank, generating the
13348 \emph on
13349 return
13350 \emph default
13351  instruction at the end, etc.
13352  Practically, this means that the contents of the function must be written
13353  in inline assembler.
13354  This is particularly useful for interrupt functions, which can have a large
13355  (and often unnecessary) prologue/epilogue.
13356  For example, compare the code generated by these two functions:
13357 \layout Verse
13358
13359
13360 \family typewriter
13361 volatile
13362 \begin_inset LatexCommand \index{volatile}
13363
13364 \end_inset
13365
13366  data unsigned char counter;
13367 \newline
13368
13369 \newline
13370 void simpleInterrupt(void) __interrupt
13371 \begin_inset LatexCommand \index{interrupt}
13372
13373 \end_inset
13374
13375
13376 \begin_inset LatexCommand \index{\_\_interrupt}
13377
13378 \end_inset
13379
13380  (1)
13381 \newline
13382 {
13383 \newline
13384 \SpecialChar ~
13385 \SpecialChar ~
13386 \SpecialChar ~
13387 \SpecialChar ~
13388 counter++;
13389 \newline
13390 }
13391 \newline
13392
13393 \newline
13394 void nakedInterrupt(void) __interrupt (2) __naked
13395 \newline
13396 {
13397 \newline
13398 \SpecialChar ~
13399 \SpecialChar ~
13400 \SpecialChar ~
13401 \SpecialChar ~
13402 _asm
13403 \begin_inset LatexCommand \index{\_asm}
13404
13405 \end_inset
13406
13407
13408 \begin_inset LatexCommand \index{\_\_asm}
13409
13410 \end_inset
13411
13412
13413 \newline
13414 \SpecialChar ~
13415 \SpecialChar ~
13416 \SpecialChar ~
13417 \SpecialChar ~
13418 \SpecialChar ~
13419 \SpecialChar ~
13420 inc\SpecialChar ~
13421 \SpecialChar ~
13422 \SpecialChar ~
13423 \SpecialChar ~
13424 \SpecialChar ~
13425 _counter ; does not change flags, no need to save psw
13426 \newline
13427 \SpecialChar ~
13428 \SpecialChar ~
13429 \SpecialChar ~
13430 \SpecialChar ~
13431 \SpecialChar ~
13432 \SpecialChar ~
13433 reti\SpecialChar ~
13434 \SpecialChar ~
13435 \SpecialChar ~
13436 \SpecialChar ~
13437 ; MUST explicitly include ret or reti in _naked function.
13438 \newline
13439 \SpecialChar ~
13440 \SpecialChar ~
13441 \SpecialChar ~
13442 \SpecialChar ~
13443 _endasm
13444 \begin_inset LatexCommand \index{\_endasm}
13445
13446 \end_inset
13447
13448
13449 \begin_inset LatexCommand \index{\_\_endasm}
13450
13451 \end_inset
13452
13453 ;
13454 \newline
13455 }
13456 \layout Standard
13457
13458 For an 8051 target, the generated simpleInterrupt looks like:
13459 \layout Verse
13460
13461
13462 \family typewriter
13463 Note, this is an
13464 \series bold
13465 outdated
13466 \series default
13467  example, recent versions of SDCC generate
13468 \newline
13469 the same code for simpleInterrupt() and nakedInterrupt()!
13470 \newline
13471
13472 \newline
13473 _simpleInterrupt:
13474 \newline
13475 \SpecialChar ~
13476 \SpecialChar ~
13477 \SpecialChar ~
13478 \SpecialChar ~
13479 push\SpecialChar ~
13480 \SpecialChar ~
13481 \SpecialChar ~
13482 \SpecialChar ~
13483 acc
13484 \newline
13485 \SpecialChar ~
13486 \SpecialChar ~
13487 \SpecialChar ~
13488 \SpecialChar ~
13489 push\SpecialChar ~
13490 \SpecialChar ~
13491 \SpecialChar ~
13492 \SpecialChar ~
13493 b
13494 \newline
13495 \SpecialChar ~
13496 \SpecialChar ~
13497 \SpecialChar ~
13498 \SpecialChar ~
13499 push\SpecialChar ~
13500 \SpecialChar ~
13501 \SpecialChar ~
13502 \SpecialChar ~
13503 dpl
13504 \newline
13505 \SpecialChar ~
13506 \SpecialChar ~
13507 \SpecialChar ~
13508 \SpecialChar ~
13509 push\SpecialChar ~
13510 \SpecialChar ~
13511 \SpecialChar ~
13512 \SpecialChar ~
13513 dph
13514 \newline
13515 \SpecialChar ~
13516 \SpecialChar ~
13517 \SpecialChar ~
13518 \SpecialChar ~
13519 push\SpecialChar ~
13520 \SpecialChar ~
13521 \SpecialChar ~
13522 \SpecialChar ~
13523 psw
13524 \newline
13525 \SpecialChar ~
13526 \SpecialChar ~
13527 \SpecialChar ~
13528 \SpecialChar ~
13529 mov\SpecialChar ~
13530 \SpecialChar ~
13531 \SpecialChar ~
13532 \SpecialChar ~
13533 \SpecialChar ~
13534 psw,#0x00
13535 \newline
13536 \SpecialChar ~
13537 \SpecialChar ~
13538 \SpecialChar ~
13539 \SpecialChar ~
13540 inc\SpecialChar ~
13541 \SpecialChar ~
13542 \SpecialChar ~
13543 \SpecialChar ~
13544 \SpecialChar ~
13545 _counter
13546 \newline
13547 \SpecialChar ~
13548 \SpecialChar ~
13549 \SpecialChar ~
13550 \SpecialChar ~
13551 pop\SpecialChar ~
13552 \SpecialChar ~
13553 \SpecialChar ~
13554 \SpecialChar ~
13555 \SpecialChar ~
13556 psw
13557 \newline
13558 \SpecialChar ~
13559 \SpecialChar ~
13560 \SpecialChar ~
13561 \SpecialChar ~
13562 pop\SpecialChar ~
13563 \SpecialChar ~
13564 \SpecialChar ~
13565 \SpecialChar ~
13566 \SpecialChar ~
13567 dph
13568 \newline
13569 \SpecialChar ~
13570 \SpecialChar ~
13571 \SpecialChar ~
13572 \SpecialChar ~
13573 pop\SpecialChar ~
13574 \SpecialChar ~
13575 \SpecialChar ~
13576 \SpecialChar ~
13577 \SpecialChar ~
13578 dpl
13579 \newline
13580 \SpecialChar ~
13581 \SpecialChar ~
13582 \SpecialChar ~
13583 \SpecialChar ~
13584 pop\SpecialChar ~
13585 \SpecialChar ~
13586 \SpecialChar ~
13587 \SpecialChar ~
13588 \SpecialChar ~
13589 b
13590 \newline
13591 \SpecialChar ~
13592 \SpecialChar ~
13593 \SpecialChar ~
13594 \SpecialChar ~
13595 pop\SpecialChar ~
13596 \SpecialChar ~
13597 \SpecialChar ~
13598 \SpecialChar ~
13599 \SpecialChar ~
13600 acc
13601 \newline
13602 \SpecialChar ~
13603 \SpecialChar ~
13604 \SpecialChar ~
13605 \SpecialChar ~
13606 reti
13607 \layout Standard
13608
13609 whereas nakedInterrupt looks like:
13610 \layout Verse
13611
13612
13613 \family typewriter
13614 _nakedInterrupt:
13615 \newline
13616 \SpecialChar ~
13617 \SpecialChar ~
13618 \SpecialChar ~
13619 \SpecialChar ~
13620 inc\SpecialChar ~
13621 \SpecialChar ~
13622 \SpecialChar ~
13623 \SpecialChar ~
13624 _counter ; does not change flags, no need to save psw
13625 \newline
13626 \SpecialChar ~
13627 \SpecialChar ~
13628 \SpecialChar ~
13629 \SpecialChar ~
13630 reti\SpecialChar ~
13631 \SpecialChar ~
13632 \SpecialChar ~
13633 \SpecialChar ~
13634 \SpecialChar ~
13635 \SpecialChar ~
13636 \SpecialChar ~
13637 \SpecialChar ~
13638 \SpecialChar ~
13639 \SpecialChar ~
13640 \SpecialChar ~
13641 \SpecialChar ~
13642 ; MUST explicitly include ret or reti in _naked function
13643 \layout Standard
13644
13645 The related directive #pragma exclude
13646 \begin_inset LatexCommand \index{\#pragma exclude}
13647
13648 \end_inset
13649
13650  allows a more fine grained control over pushing & popping
13651 \begin_inset LatexCommand \index{push/pop}
13652
13653 \end_inset
13654
13655  the registers.
13656 \layout Standard
13657
13658 While there is nothing preventing you from writing C code inside a
13659 \family typewriter
13660 _naked
13661 \family default
13662  function, there are many ways to shoot yourself in the foot doing this,
13663  and it is recommended that you stick to inline assembler.
13664 \layout Subsection
13665
13666 Use of Labels within Inline Assembler
13667 \layout Standard
13668
13669 SDCC allows the use of in-line assembler with a few restrictions regarding
13670  labels.
13671  In older versions of the compiler all labels defined within inline assembler
13672  code
13673 \emph on
13674 had to be
13675 \emph default
13676  of the form
13677 \emph on
13678 nnnnn$
13679 \emph default
13680  where nnnn is a number less than 100 (which implies a limit of utmost 100
13681  inline assembler labels
13682 \emph on
13683 per function
13684 \emph default
13685 \noun on
13686 )
13687 \noun default
13688 .
13689
13690 \layout Verse
13691
13692
13693 \family typewriter
13694 _asm
13695 \begin_inset LatexCommand \index{\_asm}
13696
13697 \end_inset
13698
13699
13700 \begin_inset LatexCommand \index{\_\_asm}
13701
13702 \end_inset
13703
13704
13705 \newline
13706 \SpecialChar ~
13707 \SpecialChar ~
13708 \SpecialChar ~
13709 \SpecialChar ~
13710 mov\SpecialChar ~
13711 \SpecialChar ~
13712 \SpecialChar ~
13713 \SpecialChar ~
13714 \SpecialChar ~
13715 b,#10
13716 \newline
13717 00001$:
13718 \newline
13719 \SpecialChar ~
13720 \SpecialChar ~
13721 \SpecialChar ~
13722 \SpecialChar ~
13723 djnz\SpecialChar ~
13724 \SpecialChar ~
13725 \SpecialChar ~
13726 \SpecialChar ~
13727 b,00001$
13728 \newline
13729 _endasm
13730 \begin_inset LatexCommand \index{\_endasm}
13731
13732 \end_inset
13733
13734
13735 \begin_inset LatexCommand \index{\_\_endasm}
13736
13737 \end_inset
13738
13739  ;
13740 \layout Standard
13741
13742 Inline assembler code cannot reference any C-Labels, however it can reference
13743  labels
13744 \begin_inset LatexCommand \index{Labels}
13745
13746 \end_inset
13747
13748  defined by the inline assembler, e.g.:
13749 \layout Verse
13750
13751
13752 \family typewriter
13753 foo() {
13754 \newline
13755 \SpecialChar ~
13756 \SpecialChar ~
13757 \SpecialChar ~
13758 \SpecialChar ~
13759 /* some c code */
13760 \newline
13761 \SpecialChar ~
13762 \SpecialChar ~
13763 \SpecialChar ~
13764 \SpecialChar ~
13765 _asm
13766 \newline
13767 \SpecialChar ~
13768 \SpecialChar ~
13769 \SpecialChar ~
13770 \SpecialChar ~
13771 \SpecialChar ~
13772 \SpecialChar ~
13773 ; some assembler code
13774 \newline
13775 \SpecialChar ~
13776 \SpecialChar ~
13777 \SpecialChar ~
13778 \SpecialChar ~
13779 \SpecialChar ~
13780 \SpecialChar ~
13781 ljmp $0003
13782 \newline
13783 \SpecialChar ~
13784 \SpecialChar ~
13785 \SpecialChar ~
13786 \SpecialChar ~
13787 _endasm;
13788 \newline
13789 \SpecialChar ~
13790 \SpecialChar ~
13791 \SpecialChar ~
13792 \SpecialChar ~
13793 /* some more c code */
13794 \newline
13795 clabel:\SpecialChar ~
13796 \SpecialChar ~
13797 /* inline assembler cannot reference this label */
13798 \newline
13799 \SpecialChar ~
13800 \SpecialChar ~
13801 \SpecialChar ~
13802 \SpecialChar ~
13803 _asm
13804 \newline
13805 \SpecialChar ~
13806 \SpecialChar ~
13807 \SpecialChar ~
13808 \SpecialChar ~
13809 $0003: ;label (can be referenced by inline assembler only)
13810 \newline
13811 \SpecialChar ~
13812 \SpecialChar ~
13813 \SpecialChar ~
13814 \SpecialChar ~
13815 _endasm
13816 \begin_inset LatexCommand \index{\_endasm}
13817
13818 \end_inset
13819
13820
13821 \begin_inset LatexCommand \index{\_\_endasm}
13822
13823 \end_inset
13824
13825  ;
13826 \newline
13827 \SpecialChar ~
13828 \SpecialChar ~
13829 \SpecialChar ~
13830 \SpecialChar ~
13831 /* some more c code */
13832 \newline
13833 }
13834 \layout Standard
13835
13836 In other words inline assembly code can access labels defined in inline
13837  assembly within the scope of the function.
13838  The same goes the other way, i.e.
13839  labels defines in inline assembly can not be accessed by C statements.
13840 \layout Section
13841
13842 Interfacing with Assembler Code
13843 \begin_inset LatexCommand \index{Assembler routines}
13844
13845 \end_inset
13846
13847
13848 \layout Subsection
13849
13850 Global Registers used for Parameter Passing
13851 \begin_inset LatexCommand \index{Parameter passing}
13852
13853 \end_inset
13854
13855
13856 \layout Standard
13857
13858 The compiler always uses the global registers
13859 \emph on
13860 DPL, DPH
13861 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
13862
13863 \end_inset
13864
13865
13866 \begin_inset LatexCommand \index{DPTR}
13867
13868 \end_inset
13869
13870 , B
13871 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
13872
13873 \end_inset
13874
13875
13876 \emph default
13877 and
13878 \emph on
13879  ACC
13880 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
13881
13882 \end_inset
13883
13884
13885 \emph default
13886  to pass the first parameter to a routine.
13887  The second parameter onwards is either allocated on the stack (for reentrant
13888  routines or if -
13889 \begin_inset ERT
13890 status Collapsed
13891
13892 \layout Standard
13893
13894 \backslash
13895 /
13896 \end_inset
13897
13898 -stack-auto is used) or in data / xdata memory (depending on the memory
13899  model).
13900
13901 \layout Subsection
13902
13903 Assembler Routine (non-reentrant)
13904 \layout Standard
13905
13906 In the following example
13907 \begin_inset LatexCommand \index{reentrant}
13908
13909 \end_inset
13910
13911
13912 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
13913
13914 \end_inset
13915
13916  the function c_func calls an assembler routine asm_func, which takes two
13917  parameters
13918 \begin_inset LatexCommand \index{function parameter}
13919
13920 \end_inset
13921
13922 .
13923 \layout Verse
13924
13925
13926 \family typewriter
13927 extern int asm_func(unsigned char, unsigned char);
13928 \newline
13929
13930 \newline
13931 int c_func (unsigned char i, unsigned char j)
13932 \newline
13933 {
13934 \newline
13935 \SpecialChar ~
13936 \SpecialChar ~
13937 \SpecialChar ~
13938 \SpecialChar ~
13939 return asm_func(i,j);
13940 \newline
13941 }
13942 \newline
13943
13944 \newline
13945 int main()
13946 \newline
13947 {
13948 \newline
13949 \SpecialChar ~
13950 \SpecialChar ~
13951 \SpecialChar ~
13952 \SpecialChar ~
13953 return c_func(10,9);
13954 \newline
13955 }
13956 \layout Standard
13957
13958 The corresponding assembler function is:
13959 \layout Verse
13960
13961
13962 \family typewriter
13963 .globl _asm_func_PARM_2
13964 \newline
13965 \SpecialChar ~
13966 \SpecialChar ~
13967 \SpecialChar ~
13968 \SpecialChar ~
13969 \SpecialChar ~
13970 \SpecialChar ~
13971 \SpecialChar ~
13972 \SpecialChar ~
13973 .globl _asm_func
13974 \newline
13975 \SpecialChar ~
13976 \SpecialChar ~
13977 \SpecialChar ~
13978 \SpecialChar ~
13979 \SpecialChar ~
13980 \SpecialChar ~
13981 \SpecialChar ~
13982 \SpecialChar ~
13983 .area OSEG
13984 \newline
13985 _asm_func_PARM_2:
13986 \newline
13987 \SpecialChar ~
13988 \SpecialChar ~
13989 \SpecialChar ~
13990 \SpecialChar ~
13991 \SpecialChar ~
13992 \SpecialChar ~
13993 \SpecialChar ~
13994 \SpecialChar ~
13995 .ds    1
13996 \newline
13997 \SpecialChar ~
13998 \SpecialChar ~
13999 \SpecialChar ~
14000 \SpecialChar ~
14001 \SpecialChar ~
14002 \SpecialChar ~
14003 \SpecialChar ~
14004 \SpecialChar ~
14005 .area CSEG
14006 \newline
14007 _asm_func:
14008 \newline
14009 \SpecialChar ~
14010 \SpecialChar ~
14011 \SpecialChar ~
14012 \SpecialChar ~
14013 \SpecialChar ~
14014 \SpecialChar ~
14015 \SpecialChar ~
14016 \SpecialChar ~
14017 mov\SpecialChar ~
14018 \SpecialChar ~
14019 \SpecialChar ~
14020 \SpecialChar ~
14021 a,dpl
14022 \newline
14023 \SpecialChar ~
14024 \SpecialChar ~
14025 \SpecialChar ~
14026 \SpecialChar ~
14027 \SpecialChar ~
14028 \SpecialChar ~
14029 \SpecialChar ~
14030 \SpecialChar ~
14031 add\SpecialChar ~
14032 \SpecialChar ~
14033 \SpecialChar ~
14034 \SpecialChar ~
14035 a,_asm_func_PARM_2
14036 \newline
14037 \SpecialChar ~
14038 \SpecialChar ~
14039 \SpecialChar ~
14040 \SpecialChar ~
14041 \SpecialChar ~
14042 \SpecialChar ~
14043 \SpecialChar ~
14044 \SpecialChar ~
14045 mov\SpecialChar ~
14046 \SpecialChar ~
14047 \SpecialChar ~
14048 \SpecialChar ~
14049 dpl,a
14050 \newline
14051 \SpecialChar ~
14052 \SpecialChar ~
14053 \SpecialChar ~
14054 \SpecialChar ~
14055 \SpecialChar ~
14056 \SpecialChar ~
14057 \SpecialChar ~
14058 \SpecialChar ~
14059 mov\SpecialChar ~
14060 \SpecialChar ~
14061 \SpecialChar ~
14062 \SpecialChar ~
14063 dph
14064 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
14065
14066 \end_inset
14067
14068 ,#0x00
14069 \newline
14070 \SpecialChar ~
14071 \SpecialChar ~
14072 \SpecialChar ~
14073 \SpecialChar ~
14074 \SpecialChar ~
14075 \SpecialChar ~
14076 \SpecialChar ~
14077 \SpecialChar ~
14078 ret
14079 \layout Standard
14080
14081 Note here that the return values
14082 \begin_inset LatexCommand \index{return value}
14083
14084 \end_inset
14085
14086  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
14087  two byte values.
14088  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
14089 b' & 'acc' for four byte values.
14090 \layout Standard
14091
14092 The parameter naming convention is _<function_name>_PARM_<n>, where n is
14093  the parameter number starting from 1, and counting from the left.
14094  The first parameter is passed in
14095 \begin_inset Quotes eld
14096 \end_inset
14097
14098 dpl
14099 \begin_inset Quotes erd
14100 \end_inset
14101
14102  for a one byte parameter,
14103 \begin_inset Quotes eld
14104 \end_inset
14105
14106 dptr
14107 \begin_inset Quotes erd
14108 \end_inset
14109
14110  for two bytes,
14111 \begin_inset Quotes eld
14112 \end_inset
14113
14114 b,dptr
14115 \begin_inset Quotes erd
14116 \end_inset
14117
14118  for three bytes and
14119 \begin_inset Quotes eld
14120 \end_inset
14121
14122 acc,b,dptr
14123 \begin_inset Quotes erd
14124 \end_inset
14125
14126  for a four bytes parameter.
14127  The variable name for the second parameter will be _<function_name>_PARM_2.
14128 \newline
14129
14130 \newline
14131 Assemble the assembler routine with the following command:
14132 \newline
14133
14134 \newline
14135
14136 \family sans
14137 \series bold
14138 asx8051 -losg asmfunc.asm
14139 \newline
14140
14141 \newline
14142
14143 \family default
14144 \series default
14145 Then compile and link the assembler routine to the C source file with the
14146  following command:
14147 \newline
14148
14149 \newline
14150
14151 \family sans
14152 \series bold
14153 sdcc cfunc.c asmfunc.rel
14154 \layout Subsection
14155
14156 Assembler Routine (reentrant)
14157 \layout Standard
14158
14159 In this case
14160 \begin_inset LatexCommand \index{reentrant}
14161
14162 \end_inset
14163
14164
14165 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
14166
14167 \end_inset
14168
14169  the second parameter
14170 \begin_inset LatexCommand \index{function parameter}
14171
14172 \end_inset
14173
14174  onwards will be passed on the stack, the parameters are pushed from right
14175  to left i.e.
14176  after the call the leftmost parameter will be on the top of the stack.
14177  Here is an example:
14178 \layout Verse
14179
14180
14181 \family typewriter
14182 extern int asm_func(unsigned char, unsigned char);
14183 \newline
14184
14185 \newline
14186 int c_func (unsigned char i, unsigned char j) reentrant
14187 \newline
14188 {
14189 \newline
14190 \SpecialChar ~
14191 \SpecialChar ~
14192 \SpecialChar ~
14193 \SpecialChar ~
14194 return asm_func(i,j);
14195 \newline
14196 }
14197 \newline
14198
14199 \newline
14200 int main()
14201 \newline
14202 {
14203 \newline
14204 \SpecialChar ~
14205 \SpecialChar ~
14206 \SpecialChar ~
14207 \SpecialChar ~
14208 return c_func(10,9);
14209 \newline
14210 }
14211 \layout Standard
14212
14213 The corresponding assembler routine is:
14214 \layout Verse
14215
14216
14217 \family typewriter
14218 .globl _asm_func
14219 \newline
14220 _asm_func:
14221 \newline
14222 \SpecialChar ~
14223 \SpecialChar ~
14224 \SpecialChar ~
14225 \SpecialChar ~
14226 push  _bp
14227 \newline
14228 \SpecialChar ~
14229 \SpecialChar ~
14230 \SpecialChar ~
14231 \SpecialChar ~
14232 mov _bp,sp
14233 \newline
14234 \SpecialChar ~
14235 \SpecialChar ~
14236 \SpecialChar ~
14237 \SpecialChar ~
14238 mov r2,dpl
14239 \newline
14240 \SpecialChar ~
14241 \SpecialChar ~
14242 \SpecialChar ~
14243 \SpecialChar ~
14244 mov a,_bp
14245 \newline
14246 \SpecialChar ~
14247 \SpecialChar ~
14248 \SpecialChar ~
14249 \SpecialChar ~
14250 add a,#0xfd
14251 \newline
14252 \SpecialChar ~
14253 \SpecialChar ~
14254 \SpecialChar ~
14255 \SpecialChar ~
14256 mov r0,a
14257 \newline
14258 \SpecialChar ~
14259 \SpecialChar ~
14260 \SpecialChar ~
14261 \SpecialChar ~
14262 add  a,#0xfc ;?
14263 \newline
14264 \SpecialChar ~
14265 \SpecialChar ~
14266 \SpecialChar ~
14267 \SpecialChar ~
14268 mov  r1,a
14269 \newline
14270 \SpecialChar ~
14271 \SpecialChar ~
14272 \SpecialChar ~
14273 \SpecialChar ~
14274 mov  a,@r0
14275 \newline
14276 \SpecialChar ~
14277 \SpecialChar ~
14278 \SpecialChar ~
14279 \SpecialChar ~
14280 add  a,r2 ;?
14281 \newline
14282 \SpecialChar ~
14283 \SpecialChar ~
14284 \SpecialChar ~
14285 \SpecialChar ~
14286 mov  dpl,a
14287 \newline
14288 \SpecialChar ~
14289 \SpecialChar ~
14290 \SpecialChar ~
14291 \SpecialChar ~
14292 mov  dph,#0x00
14293 \newline
14294 \SpecialChar ~
14295 \SpecialChar ~
14296 \SpecialChar ~
14297 \SpecialChar ~
14298 mov  sp,_bp
14299 \newline
14300 \SpecialChar ~
14301 \SpecialChar ~
14302 \SpecialChar ~
14303 \SpecialChar ~
14304 pop  _bp
14305 \newline
14306 \SpecialChar ~
14307 \SpecialChar ~
14308 \SpecialChar ~
14309 \SpecialChar ~
14310 ret
14311 \layout Standard
14312
14313 The compiling and linking procedure remains the same, however note the extra
14314  entry & exit linkage required for the assembler code, _bp is the stack
14315  frame pointer and is used to compute the offset into the stack for parameters
14316  and local variables.
14317 \layout Section
14318
14319 int (16 bit)
14320 \begin_inset LatexCommand \index{int (16 bit)}
14321
14322 \end_inset
14323
14324  and long (32 bit)
14325 \begin_inset LatexCommand \index{long (32 bit)}
14326
14327 \end_inset
14328
14329  Support
14330 \layout Standard
14331
14332 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
14333  multiplication and modulus operations are implemented by support routines.
14334  These support routines are all developed in ANSI-C to facilitate porting
14335  to other MCUs, although some model specific assembler optimizations are
14336  used.
14337  The following files contain the described routines, all of them can be
14338  found in <installdir>/share/sdcc/lib.
14339 \newline
14340
14341 \layout Standard
14342 \align center
14343
14344 \begin_inset  Tabular
14345 <lyxtabular version="3" rows="11" columns="2">
14346 <features>
14347 <column alignment="left" valignment="top" leftline="true" width="0">
14348 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
14349 <row topline="true" bottomline="true">
14350 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14351 \begin_inset Text
14352
14353 \layout Standard
14354
14355
14356 \series bold
14357 Function
14358 \end_inset
14359 </cell>
14360 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14361 \begin_inset Text
14362
14363 \layout Standard
14364
14365
14366 \series bold
14367 Description
14368 \end_inset
14369 </cell>
14370 </row>
14371 <row topline="true">
14372 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14373 \begin_inset Text
14374
14375 \layout Standard
14376
14377 _mulint.c
14378 \end_inset
14379 </cell>
14380 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14381 \begin_inset Text
14382
14383 \layout Standard
14384
14385 16 bit multiplication
14386 \end_inset
14387 </cell>
14388 </row>
14389 <row topline="true">
14390 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14391 \begin_inset Text
14392
14393 \layout Standard
14394
14395 _divsint.c
14396 \end_inset
14397 </cell>
14398 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14399 \begin_inset Text
14400
14401 \layout Standard
14402
14403  signed 16 bit division (calls _divuint)
14404 \end_inset
14405 </cell>
14406 </row>
14407 <row topline="true">
14408 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14409 \begin_inset Text
14410
14411 \layout Standard
14412
14413 _divuint.c
14414 \end_inset
14415 </cell>
14416 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14417 \begin_inset Text
14418
14419 \layout Standard
14420
14421  unsigned 16 bit division
14422 \end_inset
14423 </cell>
14424 </row>
14425 <row topline="true">
14426 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14427 \begin_inset Text
14428
14429 \layout Standard
14430
14431 _modsint.c
14432 \end_inset
14433 </cell>
14434 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14435 \begin_inset Text
14436
14437 \layout Standard
14438
14439 signed 16 bit modulus (calls _moduint)
14440 \end_inset
14441 </cell>
14442 </row>
14443 <row topline="true">
14444 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14445 \begin_inset Text
14446
14447 \layout Standard
14448
14449 _moduint.c
14450 \end_inset
14451 </cell>
14452 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14453 \begin_inset Text
14454
14455 \layout Standard
14456
14457 unsigned 16 bit modulus
14458 \end_inset
14459 </cell>
14460 </row>
14461 <row topline="true">
14462 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14463 \begin_inset Text
14464
14465 \layout Standard
14466
14467 _mullong.c
14468 \end_inset
14469 </cell>
14470 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14471 \begin_inset Text
14472
14473 \layout Standard
14474
14475 32 bit multiplication
14476 \end_inset
14477 </cell>
14478 </row>
14479 <row topline="true">
14480 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14481 \begin_inset Text
14482
14483 \layout Standard
14484
14485 _divslong.c
14486 \end_inset
14487 </cell>
14488 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14489 \begin_inset Text
14490
14491 \layout Standard
14492
14493  signed 32 division (calls _divulong)
14494 \end_inset
14495 </cell>
14496 </row>
14497 <row topline="true">
14498 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14499 \begin_inset Text
14500
14501 \layout Standard
14502
14503 _divulong.c
14504 \end_inset
14505 </cell>
14506 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14507 \begin_inset Text
14508
14509 \layout Standard
14510
14511 unsigned 32 division
14512 \end_inset
14513 </cell>
14514 </row>
14515 <row topline="true">
14516 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14517 \begin_inset Text
14518
14519 \layout Standard
14520
14521 _modslong.c
14522 \end_inset
14523 </cell>
14524 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14525 \begin_inset Text
14526
14527 \layout Standard
14528
14529  signed 32 bit modulus (calls _modulong)
14530 \end_inset
14531 </cell>
14532 </row>
14533 <row topline="true" bottomline="true">
14534 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14535 \begin_inset Text
14536
14537 \layout Standard
14538
14539 _modulong.c
14540 \end_inset
14541 </cell>
14542 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14543 \begin_inset Text
14544
14545 \layout Standard
14546
14547 unsigned 32 bit modulus
14548 \end_inset
14549 </cell>
14550 </row>
14551 </lyxtabular>
14552
14553 \end_inset
14554
14555
14556 \newline
14557
14558 \layout Standard
14559
14560 Since they are compiled as
14561 \emph on
14562 non-reentrant
14563 \emph default
14564
14565 \begin_inset LatexCommand \index{reentrant}
14566
14567 \end_inset
14568
14569 , interrupt
14570 \begin_inset LatexCommand \index{interrupt}
14571
14572 \end_inset
14573
14574  service routines should not do any of the above operations.
14575  If this is unavoidable then the above routines will need to be compiled
14576  with the
14577 \emph on
14578 -
14579 \begin_inset ERT
14580 status Collapsed
14581
14582 \layout Standard
14583
14584 \backslash
14585 /
14586 \end_inset
14587
14588 -stack-auto
14589 \begin_inset LatexCommand \index{-\/-stack-auto}
14590
14591 \end_inset
14592
14593
14594 \emph default
14595  option, after which the source program will have to be compiled with
14596 \emph on
14597 -
14598 \begin_inset ERT
14599 status Collapsed
14600
14601 \layout Standard
14602
14603 \backslash
14604 /
14605 \end_inset
14606
14607 -int-long-reent
14608 \begin_inset LatexCommand \index{-\/-int-long-reent}
14609
14610 \end_inset
14611
14612
14613 \emph default
14614  option.
14615  Notice that you don't have to call these routines directly.
14616  The compiler will use them automatically every time an integer operation
14617  is required.
14618 \layout Section
14619
14620 Floating Point Support
14621 \begin_inset LatexCommand \index{Floating point support}
14622
14623 \end_inset
14624
14625
14626 \layout Standard
14627
14628 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
14629  floating point support routines are derived from gcc's floatlib.c and consist
14630  of the following routines:
14631 \newline
14632
14633 \layout Standard
14634 \align center
14635
14636 \size footnotesize
14637
14638 \begin_inset  Tabular
14639 <lyxtabular version="3" rows="17" columns="2">
14640 <features>
14641 <column alignment="left" valignment="top" leftline="true" width="0">
14642 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
14643 <row topline="true" bottomline="true">
14644 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14645 \begin_inset Text
14646
14647 \layout Standard
14648
14649
14650 \family roman
14651 \series medium
14652 \shape up
14653 \size normal
14654 \emph off
14655 \bar no
14656 \noun off
14657 \color none
14658 Function
14659 \end_inset
14660 </cell>
14661 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14662 \begin_inset Text
14663
14664 \layout Standard
14665
14666 Description
14667 \end_inset
14668 </cell>
14669 </row>
14670 <row topline="true">
14671 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14672 \begin_inset Text
14673
14674 \layout Standard
14675
14676
14677 \family roman
14678 \series medium
14679 \shape up
14680 \size normal
14681 \emph off
14682 \bar no
14683 \noun off
14684 \color none
14685 _fsadd.c
14686 \end_inset
14687 </cell>
14688 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14689 \begin_inset Text
14690
14691 \layout Standard
14692
14693
14694 \family roman
14695 \series medium
14696 \shape up
14697 \size normal
14698 \emph off
14699 \bar no
14700 \noun off
14701 \color none
14702 add floating point numbers
14703 \end_inset
14704 </cell>
14705 </row>
14706 <row topline="true">
14707 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14708 \begin_inset Text
14709
14710 \layout Standard
14711
14712
14713 \family roman
14714 \series medium
14715 \shape up
14716 \size normal
14717 \emph off
14718 \bar no
14719 \noun off
14720 \color none
14721 _fssub.c
14722 \end_inset
14723 </cell>
14724 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14725 \begin_inset Text
14726
14727 \layout Standard
14728
14729
14730 \family roman
14731 \series medium
14732 \shape up
14733 \size normal
14734 \emph off
14735 \bar no
14736 \noun off
14737 \color none
14738 subtract floating point numbers
14739 \end_inset
14740 </cell>
14741 </row>
14742 <row topline="true">
14743 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14744 \begin_inset Text
14745
14746 \layout Standard
14747
14748
14749 \family roman
14750 \series medium
14751 \shape up
14752 \size normal
14753 \emph off
14754 \bar no
14755 \noun off
14756 \color none
14757 _fsdiv.c
14758 \end_inset
14759 </cell>
14760 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14761 \begin_inset Text
14762
14763 \layout Standard
14764
14765
14766 \family roman
14767 \series medium
14768 \shape up
14769 \size normal
14770 \emph off
14771 \bar no
14772 \noun off
14773 \color none
14774 divide floating point numbers
14775 \end_inset
14776 </cell>
14777 </row>
14778 <row topline="true">
14779 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14780 \begin_inset Text
14781
14782 \layout Standard
14783
14784
14785 \family roman
14786 \series medium
14787 \shape up
14788 \size normal
14789 \emph off
14790 \bar no
14791 \noun off
14792 \color none
14793 _fsmul.c
14794 \end_inset
14795 </cell>
14796 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14797 \begin_inset Text
14798
14799 \layout Standard
14800
14801
14802 \family roman
14803 \series medium
14804 \shape up
14805 \size normal
14806 \emph off
14807 \bar no
14808 \noun off
14809 \color none
14810 multiply floating point numbers
14811 \end_inset
14812 </cell>
14813 </row>
14814 <row topline="true">
14815 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14816 \begin_inset Text
14817
14818 \layout Standard
14819
14820
14821 \family roman
14822 \series medium
14823 \shape up
14824 \size normal
14825 \emph off
14826 \bar no
14827 \noun off
14828 \color none
14829 _fs2uchar.c
14830 \end_inset
14831 </cell>
14832 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14833 \begin_inset Text
14834
14835 \layout Standard
14836
14837
14838 \family roman
14839 \series medium
14840 \shape up
14841 \size normal
14842 \emph off
14843 \bar no
14844 \noun off
14845 \color none
14846 convert floating point to unsigned char
14847 \end_inset
14848 </cell>
14849 </row>
14850 <row topline="true">
14851 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14852 \begin_inset Text
14853
14854 \layout Standard
14855
14856
14857 \family roman
14858 \series medium
14859 \shape up
14860 \size normal
14861 \emph off
14862 \bar no
14863 \noun off
14864 \color none
14865 _fs2char.c
14866 \end_inset
14867 </cell>
14868 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14869 \begin_inset Text
14870
14871 \layout Standard
14872
14873
14874 \family roman
14875 \series medium
14876 \shape up
14877 \size normal
14878 \emph off
14879 \bar no
14880 \noun off
14881 \color none
14882 convert floating point to signed char
14883 \end_inset
14884 </cell>
14885 </row>
14886 <row topline="true">
14887 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14888 \begin_inset Text
14889
14890 \layout Standard
14891
14892
14893 \family roman
14894 \series medium
14895 \shape up
14896 \size normal
14897 \emph off
14898 \bar no
14899 \noun off
14900 \color none
14901 _fs2uint.c
14902 \end_inset
14903 </cell>
14904 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14905 \begin_inset Text
14906
14907 \layout Standard
14908
14909
14910 \family roman
14911 \series medium
14912 \shape up
14913 \size normal
14914 \emph off
14915 \bar no
14916 \noun off
14917 \color none
14918 convert floating point to unsigned int
14919 \end_inset
14920 </cell>
14921 </row>
14922 <row topline="true">
14923 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14924 \begin_inset Text
14925
14926 \layout Standard
14927
14928
14929 \family roman
14930 \series medium
14931 \shape up
14932 \size normal
14933 \emph off
14934 \bar no
14935 \noun off
14936 \color none
14937 _fs2int.c
14938 \end_inset
14939 </cell>
14940 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14941 \begin_inset Text
14942
14943 \layout Standard
14944
14945
14946 \family roman
14947 \series medium
14948 \shape up
14949 \size normal
14950 \emph off
14951 \bar no
14952 \noun off
14953 \color none
14954 convert floating point to signed int
14955 \end_inset
14956 </cell>
14957 </row>
14958 <row topline="true">
14959 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14960 \begin_inset Text
14961
14962 \layout Standard
14963
14964
14965 \family roman
14966 \series medium
14967 \shape up
14968 \size normal
14969 \emph off
14970 \bar no
14971 \noun off
14972 \color none
14973 _fs2ulong.
14974 \family default
14975 \series default
14976 \shape default
14977 \size default
14978 \emph default
14979 \bar default
14980 \noun default
14981 \color default
14982 c
14983 \end_inset
14984 </cell>
14985 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14986 \begin_inset Text
14987
14988 \layout Standard
14989
14990
14991 \family roman
14992 \series medium
14993 \shape up
14994 \size normal
14995 \emph off
14996 \bar no
14997 \noun off
14998 \color none
14999 convert floating point to unsigned long
15000 \end_inset
15001 </cell>
15002 </row>
15003 <row topline="true">
15004 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15005 \begin_inset Text
15006
15007 \layout Standard
15008
15009
15010 \family roman
15011 \series medium
15012 \shape up
15013 \size normal
15014 \emph off
15015 \bar no
15016 \noun off
15017 \color none
15018 _fs2long.c
15019 \end_inset
15020 </cell>
15021 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15022 \begin_inset Text
15023
15024 \layout Standard
15025
15026
15027 \family roman
15028 \series medium
15029 \shape up
15030 \size normal
15031 \emph off
15032 \bar no
15033 \noun off
15034 \color none
15035 convert floating point to signed long
15036 \end_inset
15037 </cell>
15038 </row>
15039 <row topline="true">
15040 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15041 \begin_inset Text
15042
15043 \layout Standard
15044
15045
15046 \family roman
15047 \series medium
15048 \shape up
15049 \size normal
15050 \emph off
15051 \bar no
15052 \noun off
15053 \color none
15054 _uchar2fs.c
15055 \end_inset
15056 </cell>
15057 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15058 \begin_inset Text
15059
15060 \layout Standard
15061
15062
15063 \family roman
15064 \series medium
15065 \shape up
15066 \size normal
15067 \emph off
15068 \bar no
15069 \noun off
15070 \color none
15071 convert unsigned char to floating point
15072 \end_inset
15073 </cell>
15074 </row>
15075 <row topline="true">
15076 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15077 \begin_inset Text
15078
15079 \layout Standard
15080
15081
15082 \family roman
15083 \series medium
15084 \shape up
15085 \size normal
15086 \emph off
15087 \bar no
15088 \noun off
15089 \color none
15090 _char2fs.c
15091 \end_inset
15092 </cell>
15093 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15094 \begin_inset Text
15095
15096 \layout Standard
15097
15098
15099 \family roman
15100 \series medium
15101 \shape up
15102 \size normal
15103 \emph off
15104 \bar no
15105 \noun off
15106 \color none
15107 convert char to floating point number
15108 \end_inset
15109 </cell>
15110 </row>
15111 <row topline="true">
15112 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15113 \begin_inset Text
15114
15115 \layout Standard
15116
15117
15118 \family roman
15119 \series medium
15120 \shape up
15121 \size normal
15122 \emph off
15123 \bar no
15124 \noun off
15125 \color none
15126 _uint2fs.c
15127 \end_inset
15128 </cell>
15129 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15130 \begin_inset Text
15131
15132 \layout Standard
15133
15134
15135 \family roman
15136 \series medium
15137 \shape up
15138 \size normal
15139 \emph off
15140 \bar no
15141 \noun off
15142 \color none
15143 convert unsigned int to floating point
15144 \end_inset
15145 </cell>
15146 </row>
15147 <row topline="true">
15148 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15149 \begin_inset Text
15150
15151 \layout Standard
15152
15153
15154 \family roman
15155 \series medium
15156 \shape up
15157 \size normal
15158 \emph off
15159 \bar no
15160 \noun off
15161 \color none
15162 _int2fs.c
15163 \end_inset
15164 </cell>
15165 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15166 \begin_inset Text
15167
15168 \layout Standard
15169
15170
15171 \family roman
15172 \series medium
15173 \shape up
15174 \size normal
15175 \emph off
15176 \bar no
15177 \noun off
15178 \color none
15179 convert int to floating point numbers
15180 \end_inset
15181 </cell>
15182 </row>
15183 <row topline="true">
15184 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15185 \begin_inset Text
15186
15187 \layout Standard
15188
15189
15190 \family roman
15191 \series medium
15192 \shape up
15193 \size normal
15194 \emph off
15195 \bar no
15196 \noun off
15197 \color none
15198 _ulong2fs.c
15199 \end_inset
15200 </cell>
15201 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15202 \begin_inset Text
15203
15204 \layout Standard
15205
15206
15207 \family roman
15208 \series medium
15209 \shape up
15210 \size normal
15211 \emph off
15212 \bar no
15213 \noun off
15214 \color none
15215 convert unsigned long to floating point number
15216 \end_inset
15217 </cell>
15218 </row>
15219 <row topline="true" bottomline="true">
15220 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15221 \begin_inset Text
15222
15223 \layout Standard
15224
15225
15226 \family roman
15227 \series medium
15228 \shape up
15229 \size normal
15230 \emph off
15231 \bar no
15232 \noun off
15233 \color none
15234 _long2fs.c
15235 \end_inset
15236 </cell>
15237 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15238 \begin_inset Text
15239
15240 \layout Standard
15241
15242
15243 \family roman
15244 \series medium
15245 \shape up
15246 \size normal
15247 \emph off
15248 \bar no
15249 \noun off
15250 \color none
15251 convert long to floating point number
15252 \end_inset
15253 </cell>
15254 </row>
15255 </lyxtabular>
15256
15257 \end_inset
15258
15259
15260 \newline
15261
15262 \layout Standard
15263
15264 These support routines are developed in ANSI-C so there is room for space
15265  and speed improvement
15266 \begin_inset Foot
15267 collapsed false
15268
15269 \layout Standard
15270
15271 These floating point routines (
15272 \emph on
15273 not
15274 \emph default
15275  sinf(), cosf(), ...) for the mcs51 are implemented in assembler.
15276
15277 \end_inset
15278
15279 .
15280  Note if all these routines are used simultaneously the data space might
15281  overflow.
15282  For serious floating point usage the large model might be needed.
15283  Also notice that you don't have to call this routines directly.
15284  The compiler will use them automatically every time a floating point operation
15285  is required.
15286 \layout Section
15287
15288 Library Routines
15289 \begin_inset LatexCommand \index{Libraries}
15290
15291 \end_inset
15292
15293
15294 \layout Standard
15295
15296
15297 \emph on
15298 <pending: this is messy and incomplete - a little more information is in
15299  sdcc/doc/libdoc.txt
15300 \emph default
15301  >
15302 \layout Subsection
15303
15304 Compiler support routines (_gptrget, _mulint etc.)
15305 \layout Subsection
15306
15307 Stdclib functions (puts, printf, strcat etc.)
15308 \layout Subsubsection
15309
15310 <stdio.h>
15311 \layout Standard
15312
15313
15314 \begin_inset LatexCommand \index{<stdio.h>}
15315
15316 \end_inset
15317
15318 As usual on embedded systems you have to provide your own
15319 \family typewriter
15320 getchar()
15321 \begin_inset LatexCommand \index{getchar()}
15322
15323 \end_inset
15324
15325
15326 \family default
15327 and
15328 \family typewriter
15329 putchar()
15330 \begin_inset LatexCommand \index{putchar()}
15331
15332 \end_inset
15333
15334
15335 \family default
15336  routines.
15337  SDCC does not know whether the system connects to a serial line with or
15338  without handshake, LCD, keyboard or other device.
15339  And whether a
15340 \family typewriter
15341 lf
15342 \family default
15343  to
15344 \family typewriter
15345 crlf
15346 \family default
15347  conversion within
15348 \family typewriter
15349 putchar()
15350 \family default
15351  is intended.
15352  You'll find examples for serial routines f.e.
15353  in sdcc/device/lib.
15354 \layout Standard
15355
15356 The default
15357 \family typewriter
15358  printf()
15359 \begin_inset LatexCommand \index{printf()}
15360
15361 \end_inset
15362
15363
15364 \family default
15365 implementation in
15366 \family typewriter
15367  printf_large.c
15368 \family default
15369  does not support float (except on ds390).
15370  To enable this recompile it with the option
15371 \emph on
15372 -
15373 \begin_inset ERT
15374 status Collapsed
15375
15376 \layout Standard
15377
15378 \backslash
15379 /
15380 \end_inset
15381
15382 DUSE_FLOATS=1
15383 \begin_inset LatexCommand \index{USE\_FLOATS}
15384
15385 \end_inset
15386
15387
15388 \emph default
15389  on the command line.
15390  Use
15391 \emph on
15392  -
15393 \begin_inset ERT
15394 status Collapsed
15395
15396 \layout Standard
15397
15398 \backslash
15399 /
15400 \end_inset
15401
15402 -model-large
15403 \begin_inset LatexCommand \index{-\/-model-large}
15404
15405 \end_inset
15406
15407
15408 \emph default
15409  for the mcs51 port, since this uses a lot of memory.
15410 \layout Standard
15411
15412 If you're short on memory you might want to use
15413 \family typewriter
15414 printf_small()
15415 \begin_inset LatexCommand \index{printf\_small()}
15416
15417 \end_inset
15418
15419
15420 \family default
15421
15422 \emph on
15423 instead
15424 \emph default
15425  of
15426 \family typewriter
15427  printf().
15428
15429 \family default
15430  For the mcs51 there additionally are assembly versions
15431 \family typewriter
15432 printf_tiny()
15433 \begin_inset LatexCommand \index{printf\_tiny() (mcs51)}
15434
15435 \end_inset
15436
15437
15438 \family default
15439  (subset of printf using less than 270 bytes) and
15440 \family typewriter
15441 printf_fast()
15442 \begin_inset LatexCommand \index{printf\_fast() (mcs51)}
15443
15444 \end_inset
15445
15446
15447 \family default
15448 and
15449 \family typewriter
15450  printf_fast_f()
15451 \begin_inset LatexCommand \index{printf\_fast\_f() (mcs51)}
15452
15453 \end_inset
15454
15455
15456 \family default
15457  (floating-point aware version of printf_fast) which should fit the requirements
15458  of many embedded systems (printf_fast() can be customized by unsetting
15459  #defines to
15460 \emph on
15461 not
15462 \emph default
15463  support long variables and field widths).
15464 \layout Subsection
15465
15466 Math functions (sinf, powf, sqrtf etc.)
15467 \layout Subsubsection
15468
15469 <math.h>
15470 \layout Standard
15471
15472 See definitions in file <math.h>.
15473 \layout Subsection
15474
15475 Other libraries
15476 \layout Standard
15477
15478 Libraries
15479 \begin_inset LatexCommand \index{Libraries}
15480
15481 \end_inset
15482
15483  included in SDCC should have a license at least as liberal as the GNU Lesser
15484  General Public License
15485 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
15486
15487 \end_inset
15488
15489
15490 \emph on
15491 LGPL
15492 \emph default
15493 .
15494 \layout Comment
15495
15496 license statements for the libraries are missing.
15497  sdcc/device/lib/ser_ir.c
15498 \layout Comment
15499
15500 or _decdptr f.e.
15501  come with a GPL (as opposed to LGPL) License - this will not be liberal
15502  enough for many embedded programmers.
15503 \layout Standard
15504
15505 If you have ported some library or want to share experience about some code
15506  which f.e.
15507  falls into any of these categories Busses (I
15508 \begin_inset Formula $^{\textrm{2}}$
15509 \end_inset
15510
15511 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
15512  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
15513  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
15514 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
15515
15516 \end_inset
15517
15518 \SpecialChar ~
15519 would certainly like to hear about it.
15520  Programmers coding for embedded systems are not especially famous for being
15521  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
15522 e these references are very valuable.
15523  Let's help to create a climate where information is shared.
15524 \layout Section
15525
15526 Memory Models
15527 \layout Subsection
15528
15529 MCS51 Memory Models
15530 \begin_inset LatexCommand \index{Memory model}
15531
15532 \end_inset
15533
15534
15535 \begin_inset LatexCommand \index{MCS51 memory model}
15536
15537 \end_inset
15538
15539
15540 \layout Subsubsection
15541
15542 Small, Medium and Large
15543 \layout Standard
15544
15545 SDCC allows three memory models for MCS51 code,
15546 \shape slanted
15547 small, medium
15548 \shape default
15549  and
15550 \shape slanted
15551 large
15552 \shape default
15553 .
15554  Modules compiled with different memory models should
15555 \emph on
15556 never
15557 \emph default
15558  be combined together or the results would be unpredictable.
15559  The library routines supplied with the compiler are compiled as small,
15560  medium and large.
15561  The compiled library modules are contained in separate directories as small,
15562  medium and large so that you can link to the appropriate set.
15563 \layout Standard
15564
15565 When the medium or large model is used all variables declared without a
15566  storage class will be allocated into the external ram, this includes all
15567  parameters and local variables (for non-reentrant
15568 \begin_inset LatexCommand \index{reentrant}
15569
15570 \end_inset
15571
15572  functions).
15573  When the small model is used variables without storage class are allocated
15574  in the internal ram.
15575 \layout Standard
15576
15577 Judicious usage of the processor specific storage classes
15578 \begin_inset LatexCommand \index{Storage class}
15579
15580 \end_inset
15581
15582  and the 'reentrant' function type will yield much more efficient code,
15583  than using the large model.
15584  Several optimizations are disabled when the program is compiled using the
15585  large model, it is therefore recommended that the small model be used unless
15586  absolutely required.
15587 \layout Subsubsection
15588
15589 External Stack
15590 \begin_inset LatexCommand \label{sub:External-Stack}
15591
15592 \end_inset
15593
15594
15595 \begin_inset LatexCommand \index{stack}
15596
15597 \end_inset
15598
15599
15600 \begin_inset LatexCommand \index{External stack (mcs51)}
15601
15602 \end_inset
15603
15604
15605 \layout Standard
15606
15607 The external stack (-
15608 \begin_inset ERT
15609 status Collapsed
15610
15611 \layout Standard
15612
15613 \backslash
15614 /
15615 \end_inset
15616
15617 -xstack option
15618 \begin_inset LatexCommand \index{-\/-xstack}
15619
15620 \end_inset
15621
15622 ) is located in pdata
15623 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
15624
15625 \end_inset
15626
15627  memory (usually at the start of the external ram segment) and uses all
15628  unused space in pdata (max.
15629  256 bytes).
15630  When -
15631 \begin_inset ERT
15632 status Collapsed
15633
15634 \layout Standard
15635
15636 \backslash
15637 /
15638 \end_inset
15639
15640 -xstack option is used to compile the program, the parameters and local
15641  variables
15642 \begin_inset LatexCommand \index{local variables}
15643
15644 \end_inset
15645
15646  of all reentrant functions are allocated in this area.
15647  This option is provided for programs with large stack space requirements.
15648  When used with the -
15649 \begin_inset ERT
15650 status Collapsed
15651
15652 \layout Standard
15653
15654 \backslash
15655 /
15656 \end_inset
15657
15658 -stack-auto
15659 \begin_inset LatexCommand \index{-\/-stack-auto}
15660
15661 \end_inset
15662
15663  option, all parameters and local variables are allocated on the external
15664  stack (note: support libraries will need to be recompiled with the same
15665  options.
15666  There is a predefined target in the library makefile).
15667 \layout Standard
15668
15669 The compiler outputs the higher order address byte of the external ram segment
15670  into port P2
15671 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
15672
15673 \end_inset
15674
15675  (see also section
15676 \begin_inset LatexCommand \ref{sub:MCS51-variants}
15677
15678 \end_inset
15679
15680 ), therefore when using the External Stack option, this port
15681 \emph on
15682 may not
15683 \emph default
15684  be used by the application program.
15685 \layout Subsection
15686
15687 DS390 Memory Model
15688 \begin_inset LatexCommand \index{Memory model}
15689
15690 \end_inset
15691
15692
15693 \begin_inset LatexCommand \index{DS390 memory model}
15694
15695 \end_inset
15696
15697
15698 \layout Standard
15699
15700 The only model supported is Flat 24
15701 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
15702
15703 \end_inset
15704
15705 .
15706  This generates code for the 24 bit contiguous addressing mode of the Dallas
15707  DS80C390 part.
15708  In this mode, up to four meg of external RAM or code space can be directly
15709  addressed.
15710  See the data sheets at www.dalsemi.com for further information on this part.
15711 \newline
15712
15713 \newline
15714 Note that the compiler does not generate any code to place the processor
15715  into 24 bitmode (although
15716 \emph on
15717 tinibios
15718 \emph default
15719  in the ds390 libraries will do that for you).
15720  If you don't use
15721 \emph on
15722 tinibios
15723 \emph default
15724
15725 \begin_inset LatexCommand \index{Tinibios (DS390)}
15726
15727 \end_inset
15728
15729 , the boot loader or similar code must ensure that the processor is in 24
15730  bit contiguous addressing mode before calling the SDCC startup code.
15731 \newline
15732
15733 \newline
15734 Like the
15735 \emph on
15736 -
15737 \begin_inset ERT
15738 status Collapsed
15739
15740 \layout Standard
15741
15742 \backslash
15743 /
15744 \end_inset
15745
15746 -model-large
15747 \emph default
15748  option, variables will by default be placed into the XDATA segment.
15749
15750 \newline
15751
15752 \newline
15753 Segments may be placed anywhere in the 4 meg address space using the usual
15754  -
15755 \begin_inset ERT
15756 status Collapsed
15757
15758 \layout Standard
15759
15760 \backslash
15761 /
15762 \end_inset
15763
15764 -*-loc options.
15765  Note that if any segments are located above 64K, the -r flag must be passed
15766  to the linker to generate the proper segment relocations, and the Intel
15767  HEX output format must be used.
15768  The -r flag can be passed to the linker by using the option
15769 \emph on
15770 -Wl-r
15771 \emph default
15772  on the SDCC command line.
15773  However, currently the linker can not handle code segments > 64k.
15774 \layout Section
15775
15776 Pragmas
15777 \begin_inset LatexCommand \index{Pragmas}
15778
15779 \end_inset
15780
15781
15782 \layout Standard
15783
15784 SDCC supports the following #pragma directives:
15785 \layout Itemize
15786
15787 save
15788 \begin_inset LatexCommand \index{\#pragma save}
15789
15790 \end_inset
15791
15792  - this will save all current options to the save/restore stack.
15793  See #pragma\SpecialChar ~
15794 restore.
15795 \layout Itemize
15796
15797 restore
15798 \begin_inset LatexCommand \index{\#pragma restore}
15799
15800 \end_inset
15801
15802  - will restore saved options from the last save.
15803  saves & restores can be nested.
15804  SDCC uses a save/restore stack: save pushes current options to the stack,
15805  restore pulls current options from the stack.
15806  See #pragma\SpecialChar ~
15807 save.
15808 \newline
15809
15810 \layout Itemize
15811
15812 callee_saves
15813 \begin_inset LatexCommand \index{\#pragma callee\_saves}
15814
15815 \end_inset
15816
15817
15818 \begin_inset LatexCommand \index{function prologue}
15819
15820 \end_inset
15821
15822  function1[,function2[,function3...]] - The compiler by default uses a caller
15823  saves convention for register saving across function calls, however this
15824  can cause unnecessary register pushing & popping
15825 \begin_inset LatexCommand \index{push/pop}
15826
15827 \end_inset
15828
15829  when calling small functions from larger functions.
15830  This option can be used to switch off the register saving convention for
15831  the function names specified.
15832  The compiler will not save registers when calling these functions, extra
15833  code need to be manually inserted at the entry & exit for these functions
15834  to save & restore the registers used by these functions, this can SUBSTANTIALLY
15835  reduce code & improve run time performance of the generated code.
15836  In the future the compiler (with inter procedural analysis) may be able
15837  to determine the appropriate scheme to use for each function call.
15838  If -
15839 \begin_inset ERT
15840 status Collapsed
15841
15842 \layout Standard
15843
15844 \backslash
15845 /
15846 \end_inset
15847
15848 -callee-saves command line option is used, the function names specified
15849  in #pragma\SpecialChar ~
15850 callee_saves
15851 \begin_inset LatexCommand \index{\#pragma callee\_saves}
15852
15853 \end_inset
15854
15855  is appended to the list of functions specified in the command line.
15856 \layout Itemize
15857
15858 exclude
15859 \begin_inset LatexCommand \index{\#pragma exclude}
15860
15861 \end_inset
15862
15863  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
15864  of pairs of push/pop
15865 \begin_inset LatexCommand \index{push/pop}
15866
15867 \end_inset
15868
15869  instructions in
15870 \emph on
15871 I
15872 \emph default
15873 nterrupt
15874 \begin_inset LatexCommand \index{interrupt}
15875
15876 \end_inset
15877
15878
15879 \emph on
15880 S
15881 \emph default
15882 ervice
15883 \emph on
15884 R
15885 \emph default
15886 outines.
15887  The directive should be placed immediately before the ISR function definition
15888  and it affects ALL ISR functions following it.
15889  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
15890 exclude\SpecialChar ~
15891 none
15892 \begin_inset LatexCommand \index{\#pragma exclude}
15893
15894 \end_inset
15895
15896 .
15897  See also the related keyword _naked
15898 \begin_inset LatexCommand \index{\_naked}
15899
15900 \end_inset
15901
15902
15903 \begin_inset LatexCommand \index{\_\_naked}
15904
15905 \end_inset
15906
15907 .
15908 \layout Itemize
15909
15910 less_pedantic
15911 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
15912
15913 \end_inset
15914
15915  - the compiler will not warn you anymore for obvious mistakes, you'r on
15916  your own now ;-(
15917 \layout Itemize
15918
15919 disable_warning <nnnn>
15920 \begin_inset LatexCommand \index{\#pragma disable\_warning}
15921
15922 \end_inset
15923
15924  - the compiler will not warn you anymore about warning number <nnnn>.
15925 \layout Itemize
15926
15927 nogcse
15928 \begin_inset LatexCommand \index{\#pragma nogcse}
15929
15930 \end_inset
15931
15932  - will stop global common subexpression elimination.
15933 \layout Itemize
15934
15935 noinduction
15936 \begin_inset LatexCommand \index{\#pragma noinduction}
15937
15938 \end_inset
15939
15940  - will stop loop induction optimizations.
15941 \layout Itemize
15942
15943 noinvariant
15944 \begin_inset LatexCommand \index{\#pragma noinvariant}
15945
15946 \end_inset
15947
15948  - will not do loop invariant optimizations.
15949  For more details see Loop Invariants in section
15950 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
15951
15952 \end_inset
15953
15954 .
15955 \layout Itemize
15956
15957 noiv
15958 \begin_inset LatexCommand \index{\#pragma noiv}
15959
15960 \end_inset
15961
15962  - Do not generate interrupt
15963 \begin_inset LatexCommand \index{interrupt}
15964
15965 \end_inset
15966
15967  vector table entries for all ISR functions defined after the pragma.
15968  This is useful in cases where the interrupt vector table must be defined
15969  manually, or when there is a secondary, manually defined interrupt vector
15970  table (e.g.
15971  for the autovector feature of the Cypress EZ-USB FX2).
15972  More elegantly this can be achieved by obmitting the optional interrupt
15973  number after the interrupt keyword, see section
15974 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
15975
15976 \end_inset
15977
15978 \SpecialChar ~
15979 about interrupts.
15980 \layout Itemize
15981
15982 nojtbound
15983 \begin_inset LatexCommand \index{\#pragma nojtbound}
15984
15985 \end_inset
15986
15987  - will not generate code for boundary value checking, when switch statements
15988  are turned into jump-tables (dangerous).
15989  For more details see section
15990 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
15991
15992 \end_inset
15993
15994 .
15995 \layout Itemize
15996
15997 noloopreverse
15998 \begin_inset LatexCommand \index{\#pragma noloopreverse}
15999
16000 \end_inset
16001
16002  - Will not do loop reversal optimization
16003 \layout Itemize
16004
16005 nooverlay
16006 \begin_inset LatexCommand \index{\#pragma nooverlay}
16007
16008 \end_inset
16009
16010  - the compiler will not overlay the parameters and local variables of a
16011  function.
16012 \layout Itemize
16013
16014 stackauto
16015 \begin_inset LatexCommand \index{\#pragma stackauto}
16016
16017 \end_inset
16018
16019 - See option -
16020 \begin_inset ERT
16021 status Collapsed
16022
16023 \layout Standard
16024
16025 \backslash
16026 /
16027 \end_inset
16028
16029 -stack-auto
16030 \begin_inset LatexCommand \index{-\/-stack-auto}
16031
16032 \end_inset
16033
16034  and section
16035 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
16036
16037 \end_inset
16038
16039  Parameters and Local Variables.
16040 \layout Itemize
16041
16042 opt_code_speed
16043 \begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
16044
16045 \end_inset
16046
16047 - The compiler will optimize code generation towards fast code, possibly
16048  at the expense of code size.
16049 \layout Itemize
16050
16051 opt_code_size
16052 \begin_inset LatexCommand \index{\#pragma opt\_code\_size}
16053
16054 \end_inset
16055
16056 - The compiler will optimize code generation towards compact code, possibly
16057  at the expense of code speed.
16058 \layout Itemize
16059
16060 opt_code_balanced
16061 \begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
16062
16063 \end_inset
16064
16065 - The compiler will attempt to generate code that is both compact and fast,
16066  as long as meeting one goal is not a detriment to the other (this is the
16067  default).
16068
16069 \layout Itemize
16070
16071 std_sdcc89
16072 \begin_inset LatexCommand \index{\#pragma std\_sdcc89}
16073
16074 \end_inset
16075
16076 - Generally follow the C89 standard, but allow SDCC features that conflict
16077  with the standard (default).
16078 \layout Itemize
16079
16080 std_c89
16081 \begin_inset LatexCommand \index{\#pragma std\_c89}
16082
16083 \end_inset
16084
16085 - Follow the C89 standard and disable SDCC features that conflict with the
16086  standard.
16087 \layout Itemize
16088
16089 std_sdcc99
16090 \begin_inset LatexCommand \index{\#pragma std\_sdcc99}
16091
16092 \end_inset
16093
16094 - Generally follow the C99 standard, but allow SDCC features that conflict
16095  with the standard (incomplete support).
16096 \layout Itemize
16097
16098 std_c99
16099 \begin_inset LatexCommand \index{\#pragma std\_c99}
16100
16101 \end_inset
16102
16103 - Follow the C99 standard and disable SDCC features that conflict with the
16104  standard (incomplete support).
16105 \layout Itemize
16106
16107 codeseg <name>
16108 \begin_inset LatexCommand \index{\#pragma codeseg}
16109
16110 \end_inset
16111
16112 - Use this name (max.
16113  8 characters) for the code segment.
16114  See option -
16115 \begin_inset ERT
16116 status Collapsed
16117
16118 \layout Standard
16119
16120 \backslash
16121 /
16122 \end_inset
16123
16124 -codeseg.
16125 \layout Itemize
16126
16127 constseg <name>
16128 \begin_inset LatexCommand \index{\#pragma constseg}
16129
16130 \end_inset
16131
16132 - Use this name (max.
16133  8 characters) for the const segment.
16134  See option -
16135 \begin_inset ERT
16136 status Collapsed
16137
16138 \layout Standard
16139
16140 \backslash
16141 /
16142 \end_inset
16143
16144 -constseg.
16145 \layout Standard
16146
16147 SDCPP supports the following #pragma directives:
16148 \layout Itemize
16149
16150 preproc_asm
16151 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
16152
16153 \end_inset
16154
16155  (+ | -) - switch _asm _endasm block preprocessing on / off.
16156  Default is on.
16157 \layout Standard
16158
16159 The pragma's are intended to be used to turn-on or off certain optimizations
16160  which might cause the compiler to generate extra stack / data space to
16161  store compiler generated temporary variables.
16162  This usually happens in large functions.
16163  Pragma directives should be used as shown in the following example, they
16164  are used to control options & optimizations for a given function; pragmas
16165  should be placed before and/or after a function, placing pragma's inside
16166  a function body could have unpredictable results.
16167 \layout Verse
16168
16169
16170 \family typewriter
16171 #pragma save
16172 \begin_inset LatexCommand \index{\#pragma save}
16173
16174 \end_inset
16175
16176  \SpecialChar ~
16177 \SpecialChar ~
16178 \SpecialChar ~
16179 \SpecialChar ~
16180 \SpecialChar ~
16181 \SpecialChar ~
16182 \SpecialChar ~
16183 /* save the current settings */
16184 \newline
16185 #pragma nogcse
16186 \begin_inset LatexCommand \index{\#pragma nogcse}
16187
16188 \end_inset
16189
16190  \SpecialChar ~
16191 \SpecialChar ~
16192 \SpecialChar ~
16193 \SpecialChar ~
16194 \SpecialChar ~
16195 /* turnoff global subexpression elimination */
16196 \newline
16197 #pragma noinduction
16198 \begin_inset LatexCommand \index{\#pragma noinduction}
16199
16200 \end_inset
16201
16202  /* turn off induction optimizations */
16203 \newline
16204 int foo ()
16205 \newline
16206 {
16207 \newline
16208 \SpecialChar ~
16209  \SpecialChar ~
16210  ...
16211
16212 \newline
16213 \SpecialChar ~
16214  \SpecialChar ~
16215  /* large code */
16216 \newline
16217 \SpecialChar ~
16218  \SpecialChar ~
16219  ...
16220
16221 \newline
16222 }
16223 \newline
16224 #pragma restore
16225 \begin_inset LatexCommand \index{\#pragma restore}
16226
16227 \end_inset
16228
16229  /* turn the optimizations back on */
16230 \layout Standard
16231
16232 The compiler will generate a warning message when extra space is allocated.
16233  It is strongly recommended that the save and restore pragma's be used when
16234  changing options for a function.
16235 \layout Section
16236
16237 Defines Created by the Compiler
16238 \layout Standard
16239
16240 The compiler creates the following #defines
16241 \begin_inset LatexCommand \index{\#defines}
16242
16243 \end_inset
16244
16245
16246 \begin_inset LatexCommand \index{Defines created by the compiler}
16247
16248 \end_inset
16249
16250 :
16251 \newline
16252
16253 \layout Standard
16254
16255
16256 \begin_inset  Tabular
16257 <lyxtabular version="3" rows="11" columns="2">
16258 <features>
16259 <column alignment="left" valignment="top" leftline="true" width="0">
16260 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
16261 <row topline="true" bottomline="true">
16262 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16263 \begin_inset Text
16264
16265 \layout Standard
16266
16267
16268 \series bold
16269 #define
16270 \end_inset
16271 </cell>
16272 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16273 \begin_inset Text
16274
16275 \layout Standard
16276
16277
16278 \series bold
16279 Description
16280 \end_inset
16281 </cell>
16282 </row>
16283 <row topline="true">
16284 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16285 \begin_inset Text
16286
16287 \layout Standard
16288
16289 SDCC
16290 \begin_inset LatexCommand \index{SDCC}
16291
16292 \end_inset
16293
16294
16295 \end_inset
16296 </cell>
16297 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16298 \begin_inset Text
16299
16300 \layout Standard
16301
16302 Always defined.
16303  Since version 2.5.6 the version number as an int (ex.
16304  256)
16305 \end_inset
16306 </cell>
16307 </row>
16308 <row topline="true">
16309 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16310 \begin_inset Text
16311
16312 \layout Standard
16313
16314 SDCC_mcs51
16315 \begin_inset LatexCommand \index{SDCC\_mcs51}
16316
16317 \end_inset
16318
16319  or SDCC_ds390
16320 \begin_inset LatexCommand \index{SDCC\_ds390}
16321
16322 \end_inset
16323
16324  or SDCC_z80
16325 \begin_inset LatexCommand \index{SDCC\_z80}
16326
16327 \end_inset
16328
16329 , etc
16330 \end_inset
16331 </cell>
16332 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16333 \begin_inset Text
16334
16335 \layout Standard
16336
16337 depending on the model used (e.g.: -mds390
16338 \end_inset
16339 </cell>
16340 </row>
16341 <row topline="true">
16342 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16343 \begin_inset Text
16344
16345 \layout Standard
16346
16347 __mcs51
16348 \begin_inset LatexCommand \index{\_\_mcs51}
16349
16350 \end_inset
16351
16352 , __ds390
16353 \begin_inset LatexCommand \index{\_\_ds390}
16354
16355 \end_inset
16356
16357 , __hc08
16358 \begin_inset LatexCommand \index{\_\_hc08}
16359
16360 \end_inset
16361
16362 , __z80
16363 \begin_inset LatexCommand \index{\_\_z80}
16364
16365 \end_inset
16366
16367 , etc
16368 \end_inset
16369 </cell>
16370 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16371 \begin_inset Text
16372
16373 \layout Standard
16374
16375 depending on the model used (e.g.
16376  -mz80)
16377 \end_inset
16378 </cell>
16379 </row>
16380 <row topline="true">
16381 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16382 \begin_inset Text
16383
16384 \layout Standard
16385
16386 SDCC_STACK_AUTO
16387 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
16388
16389 \end_inset
16390
16391
16392 \end_inset
16393 </cell>
16394 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16395 \begin_inset Text
16396
16397 \layout Standard
16398
16399 when
16400 \emph on
16401 -
16402 \begin_inset ERT
16403 status Collapsed
16404
16405 \layout Standard
16406
16407 \backslash
16408 /
16409 \end_inset
16410
16411 -stack-auto
16412 \emph default
16413  option is used
16414 \end_inset
16415 </cell>
16416 </row>
16417 <row topline="true">
16418 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16419 \begin_inset Text
16420
16421 \layout Standard
16422
16423 SDCC_MODEL_SMALL
16424 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
16425
16426 \end_inset
16427
16428
16429 \end_inset
16430 </cell>
16431 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16432 \begin_inset Text
16433
16434 \layout Standard
16435
16436 when
16437 \emph on
16438 -
16439 \begin_inset ERT
16440 status Collapsed
16441
16442 \layout Standard
16443
16444 \backslash
16445 /
16446 \end_inset
16447
16448 -model-small
16449 \emph default
16450  is used
16451 \end_inset
16452 </cell>
16453 </row>
16454 <row topline="true">
16455 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16456 \begin_inset Text
16457
16458 \layout Standard
16459
16460 SDCC_MODEL_MEDIUM
16461 \begin_inset LatexCommand \index{SDCC\_MODEL\_MEDIUM}
16462
16463 \end_inset
16464
16465
16466 \end_inset
16467 </cell>
16468 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16469 \begin_inset Text
16470
16471 \layout Standard
16472
16473 when
16474 \emph on
16475 -
16476 \begin_inset ERT
16477 status Collapsed
16478
16479 \layout Standard
16480
16481 \backslash
16482 /
16483 \end_inset
16484
16485 -model-medium
16486 \emph default
16487  is used
16488 \end_inset
16489 </cell>
16490 </row>
16491 <row topline="true">
16492 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16493 \begin_inset Text
16494
16495 \layout Standard
16496
16497 SDCC_MODEL_LARGE
16498 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
16499
16500 \end_inset
16501
16502
16503 \end_inset
16504 </cell>
16505 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16506 \begin_inset Text
16507
16508 \layout Standard
16509
16510 when
16511 \emph on
16512 -
16513 \begin_inset ERT
16514 status Collapsed
16515
16516 \layout Standard
16517
16518 \backslash
16519 /
16520 \end_inset
16521
16522 -model-large
16523 \emph default
16524  is used
16525 \end_inset
16526 </cell>
16527 </row>
16528 <row topline="true">
16529 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16530 \begin_inset Text
16531
16532 \layout Standard
16533
16534 SDCC_USE_XSTACK
16535 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
16536
16537 \end_inset
16538
16539
16540 \end_inset
16541 </cell>
16542 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16543 \begin_inset Text
16544
16545 \layout Standard
16546
16547 when
16548 \emph on
16549 -
16550 \begin_inset ERT
16551 status Collapsed
16552
16553 \layout Standard
16554
16555 \backslash
16556 /
16557 \end_inset
16558
16559 -xstack
16560 \emph default
16561  option is used
16562 \end_inset
16563 </cell>
16564 </row>
16565 <row topline="true">
16566 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16567 \begin_inset Text
16568
16569 \layout Standard
16570
16571 SDCC_STACK_TENBIT
16572 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
16573
16574 \end_inset
16575
16576
16577 \end_inset
16578 </cell>
16579 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16580 \begin_inset Text
16581
16582 \layout Standard
16583
16584 when
16585 \emph on
16586 -mds390
16587 \emph default
16588  is used
16589 \end_inset
16590 </cell>
16591 </row>
16592 <row topline="true" bottomline="true">
16593 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16594 \begin_inset Text
16595
16596 \layout Standard
16597
16598 SDCC_MODEL_FLAT24
16599 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
16600
16601 \end_inset
16602
16603
16604 \end_inset
16605 </cell>
16606 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16607 \begin_inset Text
16608
16609 \layout Standard
16610
16611 when
16612 \emph on
16613 -mds390
16614 \emph default
16615  is used
16616 \end_inset
16617 </cell>
16618 </row>
16619 </lyxtabular>
16620
16621 \end_inset
16622
16623
16624 \layout Chapter
16625
16626 Notes on supported Processors
16627 \layout Section
16628
16629 MCS51 variants
16630 \begin_inset LatexCommand \label{sub:MCS51-variants}
16631
16632 \end_inset
16633
16634
16635 \begin_inset LatexCommand \index{MCS51 variants}
16636
16637 \end_inset
16638
16639
16640 \layout Standard
16641
16642 MCS51 processors are available from many vendors and come in many different
16643  flavours.
16644  While they might differ considerably in respect to Special Function Registers
16645  the core MCS51 is usually not modified or is kept compatible.
16646
16647 \layout Subsection
16648
16649 pdata access by SFR
16650 \layout Standard
16651
16652 With the upcome of devices with internal xdata and flash memory devices
16653  using port P2
16654 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
16655
16656 \end_inset
16657
16658  as dedicated I/O port is becoming more popular.
16659  Switching the high byte for pdata
16660 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
16661
16662 \end_inset
16663
16664  access which was formerly done by port P2 is then achieved by a Special
16665  Function Register
16666 \begin_inset LatexCommand \index{sfr}
16667
16668 \end_inset
16669
16670 .
16671  In well-established MCS51 tradition the address of this
16672 \emph on
16673 sfr
16674 \emph default
16675  is where the chip designers decided to put it.
16676  Needless to say that they didn't agree on a common name either.
16677  So that the startup code can correctly initialize xdata variables, you
16678  should define an sfr with the name _XPAGE
16679 \family typewriter
16680
16681 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
16682
16683 \end_inset
16684
16685
16686 \family default
16687  at the appropriate location if the default, port P2, is not used for this.
16688  Some examples are:
16689 \layout Verse
16690
16691
16692 \family typewriter
16693 sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
16694 \layout Verse
16695
16696
16697 \family typewriter
16698 sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
16699 \layout Verse
16700
16701
16702 \family typewriter
16703 sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
16704 \layout Standard
16705
16706 For more exotic implementations further customizations may be needed.
16707  See section
16708 \begin_inset LatexCommand \ref{sub:Startup-Code}
16709
16710 \end_inset
16711
16712  for other possibilities.
16713 \layout Subsection
16714
16715 Other Features available by SFR
16716 \layout Standard
16717
16718 Some MCS51 variants offer features like Double DPTR
16719 \begin_inset LatexCommand \index{DPTR}
16720
16721 \end_inset
16722
16723 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
16724  These are currently not used for the MCS51 port.
16725  If you absolutely need them you can fall back to inline assembly or submit
16726  a patch to SDCC.
16727 \layout Section
16728
16729 DS400 port
16730 \layout Standard
16731
16732 The DS80C400 microcontroller has a rich set of peripherals.
16733  In its built-in ROM library it includes functions to access some of the
16734  features, among them is a TCP stack with IP4 and IP6 support.
16735  Library headers (currently in beta status) and other files are provided
16736  at
16737 \size footnotesize
16738
16739 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
16740
16741 \end_inset
16742
16743 .
16744
16745 \layout Section
16746
16747 The Z80 and gbz80 port
16748 \layout Standard
16749
16750 SDCC can target both the Zilog
16751 \begin_inset LatexCommand \index{Z80}
16752
16753 \end_inset
16754
16755  and the Nintendo Gameboy's Z80-like gbz80
16756 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
16757
16758 \end_inset
16759
16760 .
16761  The Z80 port is passed through the same
16762 \emph on
16763 regressions tests
16764 \begin_inset LatexCommand \index{Regression test}
16765
16766 \end_inset
16767
16768
16769 \emph default
16770  as the MCS51 and DS390 ports, so floating point support, support for long
16771  variables and bitfield support is fine.
16772  See mailing lists and forums about interrupt routines.
16773 \layout Standard
16774
16775 As always, the code is the authoritative reference - see z80/ralloc.c and
16776  z80/gen.c.
16777  The stack
16778 \begin_inset LatexCommand \index{stack}
16779
16780 \end_inset
16781
16782  frame is similar to that generated by the IAR Z80 compiler.
16783  IX is used as the base pointer, HL and IY are used as a temporary registers,
16784  and BC and DE are available for holding variables.
16785  Return values
16786 \begin_inset LatexCommand \index{return value}
16787
16788 \end_inset
16789
16790  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
16791  bytes).
16792  The gbz80 port use the same set of registers for the return values, but
16793  in a different order of significance: E (one byte), DE (two bytes), or
16794  HLDE (four bytes).
16795 \layout Section
16796
16797 The HC08 port
16798 \layout Standard
16799
16800 The port to the Motorola HC08
16801 \begin_inset LatexCommand \index{HC08}
16802
16803 \end_inset
16804
16805  family has been added in October 2003, and is still undergoing some basic
16806  development.
16807  The code generator is complete, but the register allocation is still quite
16808  unoptimized.
16809  Some of the SDCC's standard C library functions have embedded non-HC08
16810  inline assembly and so are not yet usable.
16811 \newline
16812
16813 \newline
16814
16815 \layout Section
16816
16817 The PIC14 port
16818 \layout Standard
16819
16820 The 14bit PIC
16821 \begin_inset LatexCommand \index{PIC14}
16822
16823 \end_inset
16824
16825  port still requires a major effort from the development community.
16826  However it can work for very simple code.
16827 \layout Subsection
16828
16829 C code and 14bit PIC code page
16830 \begin_inset LatexCommand \index{code page (pic14)}
16831
16832 \end_inset
16833
16834  and RAM banks
16835 \begin_inset LatexCommand \index{RAM bank (pic14)}
16836
16837 \end_inset
16838
16839
16840 \layout Standard
16841
16842 The linker organizes allocation for the code page and RAM banks.
16843  It does not have intimate knowledge of the code flow.
16844  It will put all the code section of a single asm file into a single code
16845  page.
16846  In order to make use of multiple code pages, separate asm files must be
16847  used.
16848  The compiler treats all functions of a single C file as being in the same
16849  code page unless it is non static.
16850  The compiler treats all local variables of a single C file as being in
16851  the same RAM bank unless it is an extern.
16852 \newline
16853
16854 \newline
16855 To get the best follow these guide lines:
16856 \layout Enumerate
16857
16858 make local functions static, as non static functions require code page selection
16859  overhead.
16860 \layout Enumerate
16861
16862 Make local variables static as extern variables require RAM bank selection
16863  overhead.
16864 \layout Enumerate
16865
16866 For devices that have multiple code pages it is more efficient to use the
16867  same number of files as pages, i.e.
16868  for the 16F877 use 4 separate files and i.e.
16869  for the 16F874 use 2 separate files.
16870  This way the linker can put the code for each file into different code
16871  pages and the compiler can allocate reusable variables more efficiently
16872  and there's less page selection overhead.
16873  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
16874  instruction set) use 'unsigned char' whereever possible instead of 'int'.
16875 \layout Subsection
16876
16877 Creating a device include file
16878 \layout Standard
16879
16880 For generating a device include file use the support perl script inc2h.pl
16881  kept in directory support/script.
16882 \layout Subsection
16883
16884 Interrupt code
16885 \layout Standard
16886
16887 For the interrupt function, use the keyword 'interrupt'
16888 \begin_inset LatexCommand \index{interrupt}
16889
16890 \end_inset
16891
16892  with level number of 0 (PIC14 only has 1 interrupt so this number is only
16893  there to avoid a syntax error - it ought to be fixed).
16894  E.g.:
16895 \layout Verse
16896
16897
16898 \family typewriter
16899 void Intr(void) interrupt 0
16900 \newline
16901 {
16902 \newline
16903 \SpecialChar ~
16904 \SpecialChar ~
16905 T0IF = 0; /* Clear timer interrupt */
16906 \newline
16907 }
16908 \layout Subsection
16909
16910 Linking and assembling
16911 \layout Standard
16912
16913 For assembling you can use either GPUTILS'
16914 \begin_inset LatexCommand \index{gputils (pic tools)}
16915
16916 \end_inset
16917
16918  gpasm.exe or MPLAB's mpasmwin.exe.
16919  GPUTILS is available from
16920 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
16921
16922 \end_inset
16923
16924 .
16925  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
16926  If you use MPLAB and an interrupt function then the linker script file
16927  vectors section will need to be enlarged to link with mplink.
16928 \newline
16929
16930 \newline
16931 Here is a
16932 \family typewriter
16933 Makefile
16934 \family default
16935  using GPUTILS:
16936 \layout Verse
16937
16938
16939 \family typewriter
16940 .c.o:
16941 \newline
16942 \SpecialChar ~
16943 \SpecialChar ~
16944 \SpecialChar ~
16945 \SpecialChar ~
16946 \SpecialChar ~
16947 \SpecialChar ~
16948 \SpecialChar ~
16949 \SpecialChar ~
16950 sdcc -S -V -mpic14 -p16F877 $<
16951 \newline
16952 \SpecialChar ~
16953 \SpecialChar ~
16954 \SpecialChar ~
16955 \SpecialChar ~
16956 \SpecialChar ~
16957 \SpecialChar ~
16958 \SpecialChar ~
16959 \SpecialChar ~
16960 gpasm -c $*.asm
16961 \newline
16962
16963 \newline
16964 $(PRJ).hex: $(OBJS)
16965 \newline
16966 \SpecialChar ~
16967 \SpecialChar ~
16968 \SpecialChar ~
16969 \SpecialChar ~
16970 \SpecialChar ~
16971 \SpecialChar ~
16972 \SpecialChar ~
16973 \SpecialChar ~
16974 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS) libsdcc.lib
16975 \layout Standard
16976
16977 Here is a
16978 \family typewriter
16979 Makefile
16980 \family default
16981  using MPLAB:
16982 \layout Verse
16983
16984
16985 \family typewriter
16986 .c.o:
16987 \newline
16988 \SpecialChar ~
16989 \SpecialChar ~
16990 \SpecialChar ~
16991 \SpecialChar ~
16992 \SpecialChar ~
16993 \SpecialChar ~
16994 \SpecialChar ~
16995 \SpecialChar ~
16996 sdcc -S -V -mpic14 -p16F877 $<
16997 \newline
16998 \SpecialChar ~
16999 \SpecialChar ~
17000 \SpecialChar ~
17001 \SpecialChar ~
17002 \SpecialChar ~
17003 \SpecialChar ~
17004 \SpecialChar ~
17005 \SpecialChar ~
17006 mpasmwin /q /o $*.asm
17007 \newline
17008
17009 \newline
17010 $(PRJ).hex: $(OBJS)
17011 \newline
17012 \SpecialChar ~
17013 \SpecialChar ~
17014 \SpecialChar ~
17015 \SpecialChar ~
17016 \SpecialChar ~
17017 \SpecialChar ~
17018 \SpecialChar ~
17019 \SpecialChar ~
17020 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS) libsdcc.lib
17021 \layout Standard
17022
17023 Please note that indentations within a
17024 \family typewriter
17025  Makefile
17026 \family default
17027  have to be done with a tabulator character.
17028 \layout Subsection
17029
17030 Command-line options
17031 \layout Standard
17032
17033 Besides the switches common to all SDCC backends, the PIC14 port accepts
17034  the following options (for an updated list see sdcc -
17035 \begin_inset ERT
17036 status Collapsed
17037
17038 \layout Standard
17039
17040 \backslash
17041 /
17042 \end_inset
17043
17044 -help):
17045 \layout List
17046 \labelwidthstring 00.00.0000
17047
17048 -
17049 \begin_inset ERT
17050 status Collapsed
17051
17052 \layout Standard
17053
17054 \backslash
17055 /
17056 \end_inset
17057
17058 -debug-extra emit debug info in assembly output
17059 \layout List
17060 \labelwidthstring 00.00.0000
17061
17062 -
17063 \begin_inset ERT
17064 status Collapsed
17065
17066 \layout Standard
17067
17068 \backslash
17069 /
17070 \end_inset
17071
17072 -no-pcode-opt disable (slightly faulty) optimization on pCode
17073 \layout Subsection
17074
17075 The library
17076 \layout Subsubsection
17077
17078 error: missing definition for symbol
17079 \begin_inset Quotes sld
17080 \end_inset
17081
17082 __gptrget1
17083 \begin_inset Quotes srd
17084 \end_inset
17085
17086
17087 \layout Standard
17088
17089 The PIC14 port uses library routines to provide more complex operations
17090  like multiplication, division/modulus and (generic) pointer dereferencing.
17091  In order to add these routines to your project, you must link with PIC14's
17092
17093 \family typewriter
17094 libsdcc.lib
17095 \family default
17096 .
17097  For single source file projects this is done automatically, more complex
17098  projects must add
17099 \family typewriter
17100 libsdcc.lib
17101 \family default
17102  to the linker's arguments.
17103  Make sure you also add an include path for the library (using the -I switch
17104  to the linker)!
17105 \layout Subsubsection
17106
17107 Processor mismatch in file
17108 \begin_inset Quotes sld
17109 \end_inset
17110
17111 XXX
17112 \begin_inset Quotes srd
17113 \end_inset
17114
17115 .
17116 \layout Standard
17117
17118 This warning can usually be ignored due to the very good compatibility amongst
17119  14 bit PIC devices.
17120 \layout Standard
17121
17122 You might also consider recompiling the library for your specific device
17123  by changing the ARCH=p16f877 (default target) entry in
17124 \family typewriter
17125 device/lib/pic/Makefile.in
17126 \family default
17127  and
17128 \family typewriter
17129 device/lib/pic/Makefile
17130 \family default
17131  to reflect your device.
17132  This might even improve performance for smaller devices as unneccesary
17133  BANKSELs migth be removed.
17134 \layout Subsection
17135
17136 Known bugs
17137 \layout Subsubsection
17138
17139 initialized data
17140 \layout Standard
17141
17142 Currently, data can only be initialized if it resides in the source file
17143  together with
17144 \emph on
17145 main()
17146 \emph default
17147 .
17148  Data in other source files will silently
17149 \series bold
17150 not
17151 \series default
17152  be initialized.
17153 \layout Section
17154
17155 The PIC16
17156 \begin_inset LatexCommand \index{PIC16}
17157
17158 \end_inset
17159
17160  port
17161 \layout Standard
17162
17163 The PIC16
17164 \begin_inset LatexCommand \index{PIC16}
17165
17166 \end_inset
17167
17168  port is the portion of SDCC that is responsible to produce code for the
17169  Microchip
17170 \begin_inset LatexCommand \index{Microchip}
17171
17172 \end_inset
17173
17174 (TM) microcontrollers with 16 bit core.
17175  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
17176  Currently supported devices are:
17177 \layout Standard
17178 \align center
17179
17180 \begin_inset  Tabular
17181 <lyxtabular version="3" rows="4" columns="6">
17182 <features>
17183 <column alignment="center" valignment="top" leftline="true" width="0">
17184 <column alignment="center" valignment="top" leftline="true" width="0">
17185 <column alignment="center" valignment="top" leftline="true" width="0">
17186 <column alignment="center" valignment="top" leftline="true" width="0">
17187 <column alignment="center" valignment="top" leftline="true" width="0">
17188 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17189 <row topline="true">
17190 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17191 \begin_inset Text
17192
17193 \layout Standard
17194
17195 18F242
17196 \end_inset
17197 </cell>
17198 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17199 \begin_inset Text
17200
17201 \layout Standard
17202
17203 18F248
17204 \end_inset
17205 </cell>
17206 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17207 \begin_inset Text
17208
17209 \layout Standard
17210
17211 18F252
17212 \end_inset
17213 </cell>
17214 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17215 \begin_inset Text
17216
17217 \layout Standard
17218
17219 18F258
17220 \end_inset
17221 </cell>
17222 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17223 \begin_inset Text
17224
17225 \layout Standard
17226
17227 18F442
17228 \end_inset
17229 </cell>
17230 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17231 \begin_inset Text
17232
17233 \layout Standard
17234
17235 18F448
17236 \end_inset
17237 </cell>
17238 </row>
17239 <row topline="true">
17240 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17241 \begin_inset Text
17242
17243 \layout Standard
17244
17245 18F452
17246 \end_inset
17247 </cell>
17248 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17249 \begin_inset Text
17250
17251 \layout Standard
17252
17253 18F458
17254 \end_inset
17255 </cell>
17256 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17257 \begin_inset Text
17258
17259 \layout Standard
17260
17261 18F1220
17262 \end_inset
17263 </cell>
17264 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17265 \begin_inset Text
17266
17267 \layout Standard
17268
17269 18F2220
17270 \end_inset
17271 </cell>
17272 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17273 \begin_inset Text
17274
17275 \layout Standard
17276
17277 18F2550
17278 \end_inset
17279 </cell>
17280 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17281 \begin_inset Text
17282
17283 \layout Standard
17284
17285 18F4331
17286 \end_inset
17287 </cell>
17288 </row>
17289 <row topline="true">
17290 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17291 \begin_inset Text
17292
17293 \layout Standard
17294
17295 18F4455
17296 \end_inset
17297 </cell>
17298 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17299 \begin_inset Text
17300
17301 \layout Standard
17302
17303 18F6520
17304 \end_inset
17305 </cell>
17306 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17307 \begin_inset Text
17308
17309 \layout Standard
17310
17311 18F6620
17312 \end_inset
17313 </cell>
17314 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17315 \begin_inset Text
17316
17317 \layout Standard
17318
17319 18F6680
17320 \end_inset
17321 </cell>
17322 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17323 \begin_inset Text
17324
17325 \layout Standard
17326
17327 18F6720
17328 \end_inset
17329 </cell>
17330 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17331 \begin_inset Text
17332
17333 \layout Standard
17334
17335 18F8520
17336 \end_inset
17337 </cell>
17338 </row>
17339 <row topline="true" bottomline="true">
17340 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17341 \begin_inset Text
17342
17343 \layout Standard
17344
17345 18F8620
17346 \end_inset
17347 </cell>
17348 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17349 \begin_inset Text
17350
17351 \layout Standard
17352
17353 18F8680
17354 \end_inset
17355 </cell>
17356 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17357 \begin_inset Text
17358
17359 \layout Standard
17360
17361 18F8720
17362 \end_inset
17363 </cell>
17364 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17365 \begin_inset Text
17366
17367 \layout Standard
17368
17369 \end_inset
17370 </cell>
17371 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17372 \begin_inset Text
17373
17374 \layout Standard
17375
17376 \end_inset
17377 </cell>
17378 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17379 \begin_inset Text
17380
17381 \layout Standard
17382
17383 \end_inset
17384 </cell>
17385 </row>
17386 </lyxtabular>
17387
17388 \end_inset
17389
17390
17391 \layout Subsection
17392
17393 Global Options
17394 \layout Standard
17395
17396 PIC16 port supports the standard command line arguments as supposed, with
17397  the exception of certain cases that will be mentioned in the following
17398  list:
17399 \layout List
17400 \labelwidthstring 00.00.0000
17401
17402 -
17403 \begin_inset ERT
17404 status Collapsed
17405
17406 \layout Standard
17407
17408 \backslash
17409 /
17410 \end_inset
17411
17412 -callee-saves See -
17413 \begin_inset ERT
17414 status Collapsed
17415
17416 \layout Standard
17417
17418 \backslash
17419 /
17420 \end_inset
17421
17422 -all-callee-saves
17423 \layout List
17424 \labelwidthstring 00.00.0000
17425
17426 -
17427 \begin_inset ERT
17428 status Collapsed
17429
17430 \layout Standard
17431
17432 \backslash
17433 /
17434 \end_inset
17435
17436 -all-callee-saves All function arguments are passed on stack by default.
17437
17438 \emph on
17439 There is no need to specify this in the command line.
17440 \layout List
17441 \labelwidthstring 00.00.0000
17442
17443 -
17444 \begin_inset ERT
17445 status Collapsed
17446
17447 \layout Standard
17448
17449 \backslash
17450 /
17451 \end_inset
17452
17453 -fommit-frame-pointer Frame pointer will be omitted when the function uses
17454  no local variables.
17455 \layout Subsection
17456
17457 Port Specific Options
17458 \begin_inset LatexCommand \index{Options PIC16}
17459
17460 \end_inset
17461
17462
17463 \layout Standard
17464
17465 The port specific options appear after the global options in the sdcc --help
17466  output.
17467 \layout Subsubsection
17468
17469 General Options
17470 \layout Standard
17471
17472 General options enable certain port features and optimizations.
17473 \layout List
17474 \labelwidthstring 00.00.0000
17475
17476 -
17477 \begin_inset ERT
17478 status Collapsed
17479
17480 \layout Standard
17481
17482 \backslash
17483 /
17484 \end_inset
17485
17486 -stack-model=[model] Used in conjuction with the command above.
17487  Defines the stack model to be used, valid stack models are :
17488 \begin_deeper
17489 \layout List
17490 \labelwidthstring 00.00.0000
17491
17492
17493 \emph on
17494 small
17495 \emph default
17496  Selects small stack model.
17497  8 bit stack and frame pointers.
17498  Supports 256 bytes stack size.
17499 \layout List
17500 \labelwidthstring 00.00.0000
17501
17502
17503 \emph on
17504 large
17505 \emph default
17506  Selects large stack model.
17507  16 bit stack and frame pointers.
17508  Supports 65536 bytes stack size.
17509 \end_deeper
17510 \layout List
17511 \labelwidthstring 00.00.0000
17512
17513 -
17514 \begin_inset ERT
17515 status Collapsed
17516
17517 \layout Standard
17518
17519 \backslash
17520 /
17521 \end_inset
17522
17523 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
17524  unitialized data variables with [kword].
17525  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
17526 \layout List
17527 \labelwidthstring 00.00.0000
17528
17529 -
17530 \begin_inset ERT
17531 status Collapsed
17532
17533 \layout Standard
17534
17535 \backslash
17536 /
17537 \end_inset
17538
17539 -ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
17540  Useful for bootloaders.
17541 \layout List
17542 \labelwidthstring 00.00.0000
17543
17544 -
17545 \begin_inset ERT
17546 status Collapsed
17547
17548 \layout Standard
17549
17550 \backslash
17551 /
17552 \end_inset
17553
17554 -asm= sets the full path and name of an external assembler to call.
17555 \layout List
17556 \labelwidthstring 00.00.0000
17557
17558 -
17559 \begin_inset ERT
17560 status Collapsed
17561
17562 \layout Standard
17563
17564 \backslash
17565 /
17566 \end_inset
17567
17568 -link= sets the full path and name of an external linker to call.
17569 \layout List
17570 \labelwidthstring 00.00.0000
17571
17572 -
17573 \begin_inset ERT
17574 status Collapsed
17575
17576 \layout Standard
17577
17578 \backslash
17579 /
17580 \end_inset
17581
17582 -mplab-comp MPLAB compatibility option.
17583  Currently only suppresses special gpasm directives.
17584 \layout Subsubsection
17585
17586 Optimization Options
17587 \layout List
17588 \labelwidthstring 00.00.0000
17589
17590 -
17591 \begin_inset ERT
17592 status Collapsed
17593
17594 \layout Standard
17595
17596 \backslash
17597 /
17598 \end_inset
17599
17600 -optimize-goto Try to use (conditional) BRA instead of GOTO
17601 \layout List
17602 \labelwidthstring 00.00.0000
17603
17604 -
17605 \begin_inset ERT
17606 status Collapsed
17607
17608 \layout Standard
17609
17610 \backslash
17611 /
17612 \end_inset
17613
17614 -optimize-cmp Try to optimize some compares.
17615 \layout List
17616 \labelwidthstring 00.00.0000
17617
17618 -
17619 \begin_inset ERT
17620 status Collapsed
17621
17622 \layout Standard
17623
17624 \backslash
17625 /
17626 \end_inset
17627
17628 -optimize-df Analyze the dataflow of the generated code and improve it.
17629 \layout List
17630 \labelwidthstring 00.00.0000
17631
17632 -
17633 \begin_inset ERT
17634 status Collapsed
17635
17636 \layout Standard
17637
17638 \backslash
17639 /
17640 \end_inset
17641
17642 -obanksel=nn Set optimization level for inserting BANKSELs.
17643 \newline
17644
17645 \begin_deeper
17646 \layout List
17647 \labelwidthstring 00.00.0000
17648
17649 0 no optimization
17650 \layout List
17651 \labelwidthstring 00.00.0000
17652
17653 1 checks previous used register and if it is the same then does not emit
17654  BANKSEL, accounts only for labels.
17655 \layout List
17656 \labelwidthstring 00.00.0000
17657
17658 2 tries to check the location of (even different) symbols and removes BANKSELs
17659  if they are in the same bank.
17660
17661 \newline
17662
17663 \emph on
17664 Important: There might be problems if the linker script has data sections
17665  across bank borders!
17666 \end_deeper
17667 \layout Subsubsection
17668
17669 Linking Options
17670 \layout List
17671 \labelwidthstring 00.00.0000
17672
17673 -
17674 \begin_inset ERT
17675 status Collapsed
17676
17677 \layout Standard
17678
17679 \backslash
17680 /
17681 \end_inset
17682
17683 -nodefaultlibs do not link default libraries when linking
17684 \layout List
17685 \labelwidthstring 00.00.0000
17686
17687 -
17688 \begin_inset ERT
17689 status Collapsed
17690
17691 \layout Standard
17692
17693 \backslash
17694 /
17695 \end_inset
17696
17697 -no-crt Don't link the default run-time modules
17698 \layout List
17699 \labelwidthstring 00.00.0000
17700
17701 -
17702 \begin_inset ERT
17703 status Collapsed
17704
17705 \layout Standard
17706
17707 \backslash
17708 /
17709 \end_inset
17710
17711 -use-crt= Use a custom run-time module instead of the defaults.
17712 \layout Subsubsection
17713
17714 Debugging Options
17715 \layout Standard
17716
17717 Debugging options enable extra debugging information in the output files.
17718 \layout List
17719 \labelwidthstring 00.00.0000
17720
17721 -
17722 \begin_inset ERT
17723 status Collapsed
17724
17725 \layout Standard
17726
17727 \backslash
17728 /
17729 \end_inset
17730
17731 -debug-xtra Similar to -
17732 \begin_inset ERT
17733 status Collapsed
17734
17735 \layout Standard
17736
17737 \backslash
17738 /
17739 \end_inset
17740
17741 -debug
17742 \begin_inset LatexCommand \index{-\/-debug}
17743
17744 \end_inset
17745
17746 , but dumps more information.
17747 \layout List
17748 \labelwidthstring 00.00.0000
17749
17750 -
17751 \begin_inset ERT
17752 status Collapsed
17753
17754 \layout Standard
17755
17756 \backslash
17757 /
17758 \end_inset
17759
17760 -debug-ralloc Force register allocator to dump <source>.d file with debugging
17761  information.
17762  <source> is the name of the file compiled.
17763 \layout List
17764 \labelwidthstring 00.00.0000
17765
17766 -
17767 \begin_inset ERT
17768 status Collapsed
17769
17770 \layout Standard
17771
17772 \backslash
17773 /
17774 \end_inset
17775
17776 -pcode-verbose Enable pcode debugging information in translation.
17777 \layout List
17778 \labelwidthstring 00.00.0000
17779
17780 -
17781 \begin_inset ERT
17782 status Collapsed
17783
17784 \layout Standard
17785
17786 \backslash
17787 /
17788 \end_inset
17789
17790 -denable-peeps Force the usage of peepholes.
17791  Use with care.
17792 \layout List
17793 \labelwidthstring 00.00.0000
17794
17795 -
17796 \begin_inset ERT
17797 status Collapsed
17798
17799 \layout Standard
17800
17801 \backslash
17802 /
17803 \end_inset
17804
17805 -gstack Trace push/pops for stack pointer overflow
17806 \layout List
17807 \labelwidthstring 00.00.0000
17808
17809 -
17810 \begin_inset ERT
17811 status Collapsed
17812
17813 \layout Standard
17814
17815 \backslash
17816 /
17817 \end_inset
17818
17819 -call-tree dump call tree in .calltree file
17820 \layout Subsection
17821
17822 Enviromental Variables
17823 \layout Standard
17824
17825 There is a number of enviromental variables that can be used when running
17826  SDCC to enable certain optimizations or force a specific program behaviour.
17827  these variables are primarily for debugging purposes so they can be enabled/dis
17828 abled at will.
17829 \layout Standard
17830
17831 Currently there is only two such variables available:
17832 \layout List
17833 \labelwidthstring 00.00.0000
17834
17835 OPTIMIZE_BITFIELD_POINTER_GET when this variable exists reading of structure
17836  bitfields is optimized by directly loading FSR0 with the address of the
17837  bitfield structure.
17838  Normally SDCC will cast the bitfield structure to a bitfield pointer and
17839  then load FSR0.
17840  This step saves data ram and code space for functions that perform heavy
17841  use of bitfields.
17842  (ie.
17843  80 bytes of code space are saved when compiling malloc.c with this option).
17844
17845 \layout List
17846 \labelwidthstring 00.00.0000
17847
17848 NO_REG_OPT do not perform pCode registers optimization.
17849  This should be used for debugging purposes.
17850  In some where bugs in the pcode optimizer are found, users can benefit
17851  from temporarily disabling the optimizer until the bug is fixed.
17852 \layout Subsection
17853
17854 Preprocessor Macros
17855 \layout Standard
17856
17857 PIC16 port defines the following preprocessor macros while translating a
17858  source.
17859 \layout Standard
17860 \align center
17861
17862 \begin_inset  Tabular
17863 <lyxtabular version="3" rows="6" columns="2">
17864 <features>
17865 <column alignment="center" valignment="top" leftline="true" width="0">
17866 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17867 <row topline="true" bottomline="true">
17868 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17869 \begin_inset Text
17870
17871 \layout Standard
17872
17873 Macro
17874 \end_inset
17875 </cell>
17876 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17877 \begin_inset Text
17878
17879 \layout Standard
17880
17881 Description
17882 \end_inset
17883 </cell>
17884 </row>
17885 <row topline="true">
17886 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17887 \begin_inset Text
17888
17889 \layout Standard
17890
17891 SDCC_pic16
17892 \end_inset
17893 </cell>
17894 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17895 \begin_inset Text
17896
17897 \layout Standard
17898
17899 Port identification
17900 \end_inset
17901 </cell>
17902 </row>
17903 <row topline="true">
17904 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17905 \begin_inset Text
17906
17907 \layout Standard
17908
17909 _
17910 \begin_inset ERT
17911 status Collapsed
17912
17913 \layout Standard
17914
17915 \backslash
17916 /
17917 \end_inset
17918
17919 _pic16
17920 \end_inset
17921 </cell>
17922 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17923 \begin_inset Text
17924
17925 \layout Standard
17926
17927 Port identification (same as above)
17928 \end_inset
17929 </cell>
17930 </row>
17931 <row topline="true">
17932 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17933 \begin_inset Text
17934
17935 \layout Standard
17936
17937 pic18fxxxx
17938 \end_inset
17939 </cell>
17940 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17941 \begin_inset Text
17942
17943 \layout Standard
17944
17945 MCU Identification.
17946
17947 \emph on
17948 xxxx
17949 \emph default
17950  is the microcontrol identification number, i.e.
17951  452, 6620, etc
17952 \end_inset
17953 </cell>
17954 </row>
17955 <row topline="true">
17956 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17957 \begin_inset Text
17958
17959 \layout Standard
17960
17961 _
17962 \begin_inset ERT
17963 status Collapsed
17964
17965 \layout Standard
17966
17967 \backslash
17968 /
17969 \end_inset
17970
17971 _18Fxxxx
17972 \end_inset
17973 </cell>
17974 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17975 \begin_inset Text
17976
17977 \layout Standard
17978
17979 MCU Identification (same as above)
17980 \end_inset
17981 </cell>
17982 </row>
17983 <row topline="true" bottomline="true">
17984 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17985 \begin_inset Text
17986
17987 \layout Standard
17988
17989 STACK_MODEL_nnn
17990 \end_inset
17991 </cell>
17992 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17993 \begin_inset Text
17994
17995 \layout Standard
17996
17997 nnn = SMALL or LARGE respectively according to the stack model used
17998 \end_inset
17999 </cell>
18000 </row>
18001 </lyxtabular>
18002
18003 \end_inset
18004
18005
18006 \layout Standard
18007
18008 In addition the following macros are defined when calling assembler:
18009 \layout Standard
18010 \align center
18011
18012 \begin_inset  Tabular
18013 <lyxtabular version="3" rows="4" columns="2">
18014 <features>
18015 <column alignment="center" valignment="top" leftline="true" width="0">
18016 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18017 <row topline="true" bottomline="true">
18018 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18019 \begin_inset Text
18020
18021 \layout Standard
18022
18023 Macro
18024 \end_inset
18025 </cell>
18026 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18027 \begin_inset Text
18028
18029 \layout Standard
18030
18031 Description
18032 \end_inset
18033 </cell>
18034 </row>
18035 <row topline="true">
18036 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18037 \begin_inset Text
18038
18039 \layout Standard
18040
18041 __18Fxxxx
18042 \end_inset
18043 </cell>
18044 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18045 \begin_inset Text
18046
18047 \layout Standard
18048
18049 MCU Identification.
18050
18051 \emph on
18052 xxxx
18053 \emph default
18054  is the microcontrol identification number, i.e.
18055  452, 6620, etc
18056 \end_inset
18057 </cell>
18058 </row>
18059 <row topline="true">
18060 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18061 \begin_inset Text
18062
18063 \layout Standard
18064
18065 SDCC_MODEL_nnn
18066 \end_inset
18067 </cell>
18068 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18069 \begin_inset Text
18070
18071 \layout Standard
18072
18073 nnn = SMALL or LARGE respectively according to the memory model used for
18074  SDCC
18075 \end_inset
18076 </cell>
18077 </row>
18078 <row topline="true" bottomline="true">
18079 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18080 \begin_inset Text
18081
18082 \layout Standard
18083
18084 STACK_MODEL_nnn
18085 \end_inset
18086 </cell>
18087 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18088 \begin_inset Text
18089
18090 \layout Standard
18091
18092 nnn = SMALL or LARGE respectively according to the stack model used
18093 \end_inset
18094 </cell>
18095 </row>
18096 </lyxtabular>
18097
18098 \end_inset
18099
18100
18101 \layout Subsection
18102
18103 Directories
18104 \layout Standard
18105
18106 PIC16
18107 \begin_inset LatexCommand \index{PIC16}
18108
18109 \end_inset
18110
18111  port uses the following directories for searching header files and libraries.
18112 \layout Standard
18113 \align center
18114
18115 \begin_inset  Tabular
18116 <lyxtabular version="3" rows="3" columns="4">
18117 <features>
18118 <column alignment="center" valignment="top" leftline="true" width="0">
18119 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18120 <column alignment="center" valignment="top" width="0">
18121 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18122 <row topline="true" bottomline="true">
18123 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18124 \begin_inset Text
18125
18126 \layout Standard
18127
18128 Directory
18129 \end_inset
18130 </cell>
18131 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18132 \begin_inset Text
18133
18134 \layout Standard
18135
18136 Description
18137 \end_inset
18138 </cell>
18139 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18140 \begin_inset Text
18141
18142 \layout Standard
18143
18144 Target
18145 \end_inset
18146 </cell>
18147 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18148 \begin_inset Text
18149
18150 \layout Standard
18151
18152 Command prefix
18153 \end_inset
18154 </cell>
18155 </row>
18156 <row topline="true">
18157 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18158 \begin_inset Text
18159
18160 \layout Standard
18161
18162 PREFIX/sdcc/include/pic16
18163 \end_inset
18164 </cell>
18165 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18166 \begin_inset Text
18167
18168 \layout Standard
18169
18170 PIC16 specific headers
18171 \end_inset
18172 </cell>
18173 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18174 \begin_inset Text
18175
18176 \layout Standard
18177
18178 Compiler
18179 \end_inset
18180 </cell>
18181 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18182 \begin_inset Text
18183
18184 \layout Standard
18185
18186 -I
18187 \end_inset
18188 </cell>
18189 </row>
18190 <row topline="true" bottomline="true">
18191 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18192 \begin_inset Text
18193
18194 \layout Standard
18195
18196 PREFIX/sdcc/lib/pic16
18197 \end_inset
18198 </cell>
18199 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18200 \begin_inset Text
18201
18202 \layout Standard
18203
18204 PIC16 specific libraries
18205 \end_inset
18206 </cell>
18207 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18208 \begin_inset Text
18209
18210 \layout Standard
18211
18212 Linker
18213 \end_inset
18214 </cell>
18215 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18216 \begin_inset Text
18217
18218 \layout Standard
18219
18220 -L
18221 \end_inset
18222 </cell>
18223 </row>
18224 </lyxtabular>
18225
18226 \end_inset
18227
18228
18229 \layout Subsection
18230
18231 Pragmas
18232 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
18233
18234 \end_inset
18235
18236
18237 \layout Standard
18238
18239 PIC16 port currently supports the following pragmas:
18240 \layout List
18241 \labelwidthstring 00.00.0000
18242
18243 stack pragma stack forces the code generator to initialize the stack & frame
18244  pointers at a specific address.
18245  This is an adhoc solution for cases where no STACK directive is available
18246  in the linker script or gplink is not instructed to create a stack section.
18247 \newline
18248 The stack pragma should be used only once in a project.
18249  Multiple pragmas may result in indeterminate behaviour of the program.
18250 \begin_inset Foot
18251 collapsed false
18252
18253 \layout Standard
18254
18255 The old format (ie.
18256  #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
18257  cross page boundaries (or even exceed the available data RAM) and crash
18258  the program.
18259  Make sure that stack does not cross page boundaries when using the SMALL
18260  stack model.
18261 \end_inset
18262
18263
18264 \newline
18265 The format is as follows:
18266 \layout LyX-Code
18267
18268 #pragma stack bottom_address [stack_size]
18269 \layout Standard
18270
18271
18272 \emph on
18273 bottom_address
18274 \emph default
18275  is the lower bound of the stack section.
18276  The stack pointer initially will point at address (bottom_address+stack_size-1).
18277 \layout LyX-Code
18278
18279 Example:
18280 \layout LyX-Code
18281
18282 \layout LyX-Code
18283
18284 /* initializes stack of 100 bytes at RAM address 0x200 */
18285 \layout LyX-Code
18286
18287 #pragma stack 0x200 100
18288 \layout Standard
18289
18290 If the stack_size field is omitted then a stack is created with the default
18291  size of 64.
18292  This size might be enough for most programs, but its not enough for operations
18293  with deep function nesting or excessive stack usage.
18294 \layout List
18295 \labelwidthstring 00.00.0000
18296
18297 wparam
18298 \emph on
18299 This pragma is deprecated.
18300  Its use will cause a warning message to be issued.
18301 \emph default
18302
18303 \newline
18304
18305 \layout List
18306 \labelwidthstring 00.00.0000
18307
18308 code place a function symbol at static FLASH address
18309 \layout LyX-Code
18310
18311 Example:
18312 \layout LyX-Code
18313
18314 \layout LyX-Code
18315
18316 /* place function test_func at 0x4000 */
18317 \layout LyX-Code
18318
18319 #pragma code test_func 0x4000
18320 \layout LyX-Code
18321
18322 \layout List
18323 \labelwidthstring 00.00.0000
18324
18325 library instructs the linker to use a library module.
18326 \newline
18327 Usage:
18328 \layout LyX-Code
18329
18330 #pragma library module_name
18331 \layout Standard
18332
18333
18334 \emph on
18335 module_name
18336 \emph default
18337  can be any library or object file (including its path).
18338  Note that there are four reserved keywords which have special meaning.
18339  These are:
18340 \layout Standard
18341 \align center
18342
18343 \begin_inset  Tabular
18344 <lyxtabular version="3" rows="6" columns="3">
18345 <features>
18346 <column alignment="center" valignment="top" leftline="true" width="0">
18347 <column alignment="block" valignment="top" leftline="true" width="20page%">
18348 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
18349 <row topline="true" bottomline="true">
18350 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18351 \begin_inset Text
18352
18353 \layout Standard
18354
18355 Keyword
18356 \end_inset
18357 </cell>
18358 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18359 \begin_inset Text
18360
18361 \layout Standard
18362
18363 Description
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 Module to link
18372 \end_inset
18373 </cell>
18374 </row>
18375 <row topline="true">
18376 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18377 \begin_inset Text
18378
18379 \layout Standard
18380
18381
18382 \series bold
18383 ignore
18384 \end_inset
18385 </cell>
18386 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18387 \begin_inset Text
18388
18389 \layout Standard
18390
18391 ignore all library pragmas
18392 \end_inset
18393 </cell>
18394 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18395 \begin_inset Text
18396
18397 \layout Standard
18398
18399
18400 \emph on
18401 (none)
18402 \end_inset
18403 </cell>
18404 </row>
18405 <row topline="true">
18406 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18407 \begin_inset Text
18408
18409 \layout Standard
18410
18411
18412 \series bold
18413 c
18414 \end_inset
18415 </cell>
18416 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18417 \begin_inset Text
18418
18419 \layout Standard
18420
18421 link the C library
18422 \end_inset
18423 </cell>
18424 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18425 \begin_inset Text
18426
18427 \layout Standard
18428
18429
18430 \emph on
18431 libc18f
18432 \emph default
18433 .lib
18434 \end_inset
18435 </cell>
18436 </row>
18437 <row topline="true">
18438 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18439 \begin_inset Text
18440
18441 \layout Standard
18442
18443
18444 \series bold
18445 math
18446 \end_inset
18447 </cell>
18448 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18449 \begin_inset Text
18450
18451 \layout Standard
18452
18453 link the Math libarary
18454 \end_inset
18455 </cell>
18456 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18457 \begin_inset Text
18458
18459 \layout Standard
18460
18461
18462 \emph on
18463 libm18f
18464 \emph default
18465 .lib
18466 \end_inset
18467 </cell>
18468 </row>
18469 <row topline="true">
18470 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18471 \begin_inset Text
18472
18473 \layout Standard
18474
18475
18476 \series bold
18477 io
18478 \end_inset
18479 </cell>
18480 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18481 \begin_inset Text
18482
18483 \layout Standard
18484
18485 link the I/O library
18486 \end_inset
18487 </cell>
18488 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18489 \begin_inset Text
18490
18491 \layout Standard
18492
18493
18494 \emph on
18495 libio18f*
18496 \emph default
18497 .lib
18498 \end_inset
18499 </cell>
18500 </row>
18501 <row topline="true" bottomline="true">
18502 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18503 \begin_inset Text
18504
18505 \layout Standard
18506
18507
18508 \series bold
18509 debug
18510 \end_inset
18511 </cell>
18512 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18513 \begin_inset Text
18514
18515 \layout Standard
18516
18517 link the debug library
18518 \end_inset
18519 </cell>
18520 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18521 \begin_inset Text
18522
18523 \layout Standard
18524
18525
18526 \emph on
18527 libdebug
18528 \emph default
18529 .lib
18530 \end_inset
18531 </cell>
18532 </row>
18533 </lyxtabular>
18534
18535 \end_inset
18536
18537
18538 \newline
18539 * is the device number, i.e.
18540  452 for PIC18F452 MCU.
18541 \layout Standard
18542
18543 This feature allows for linking with specific libraries withoug having to
18544  explicit name them in the command line.
18545  Note that the
18546 \noun on
18547 ignore
18548 \noun default
18549  keyword will reject all modules specified by the library pragma.
18550 \layout List
18551 \labelwidthstring 00.00.0000
18552
18553 udata pragma udata instructs the compiler to emit code so that linker will
18554  place a variable at a specific memory bank
18555 \layout LyX-Code
18556
18557 Example:
18558 \layout LyX-Code
18559
18560 \layout LyX-Code
18561
18562 /* places variable foo at bank2 */
18563 \layout LyX-Code
18564
18565 #pragma udata bank2 foo
18566 \layout LyX-Code
18567
18568 char foo;
18569 \layout Standard
18570
18571 In order for this pragma to work extra SECTION directives should be added
18572  in the .lkr script.
18573  In the following example a sample .lkr file is shown:
18574 \layout LyX-Code
18575
18576 \layout LyX-Code
18577
18578 // Sample linker script for the PIC18F452 processor
18579 \layout LyX-Code
18580
18581 LIBPATH .
18582 \layout LyX-Code
18583
18584 CODEPAGE   NAME=vectors    START=0x0            END=0x29           PROTECTED
18585 \layout LyX-Code
18586
18587 CODEPAGE   NAME=page       START=0x2A           END=0x7FFF
18588 \layout LyX-Code
18589
18590 CODEPAGE   NAME=idlocs     START=0x200000       END=0x200007       PROTECTED
18591 \layout LyX-Code
18592
18593 CODEPAGE   NAME=config     START=0x300000       END=0x30000D       PROTECTED
18594 \layout LyX-Code
18595
18596 CODEPAGE   NAME=devid      START=0x3FFFFE       END=0x3FFFFF       PROTECTED
18597 \layout LyX-Code
18598
18599 CODEPAGE   NAME=eedata     START=0xF00000       END=0xF000FF       PROTECTED
18600 \layout LyX-Code
18601
18602 ACCESSBANK NAME=accessram  START=0x0            END=0x7F
18603 \layout LyX-Code
18604
18605 \layout LyX-Code
18606
18607 DATABANK   NAME=gpr0       START=0x80           END=0xFF
18608 \layout LyX-Code
18609
18610 DATABANK   NAME=gpr1       START=0x100          END=0x1FF
18611 \layout LyX-Code
18612
18613 DATABANK   NAME=gpr2       START=0x200          END=0x2FF
18614 \layout LyX-Code
18615
18616 DATABANK   NAME=gpr3       START=0x300          END=0x3FF
18617 \layout LyX-Code
18618
18619 DATABANK   NAME=gpr4       START=0x400          END=0x4FF
18620 \layout LyX-Code
18621
18622 DATABANK   NAME=gpr5       START=0x500          END=0x5FF
18623 \layout LyX-Code
18624
18625 ACCESSBANK NAME=accesssfr  START=0xF80          END=0xFFF          PROTECTED
18626 \layout LyX-Code
18627
18628 \layout LyX-Code
18629
18630 SECTION    NAME=CONFIG     ROM=config
18631 \layout LyX-Code
18632
18633 \layout LyX-Code
18634
18635 SECTION    NAME=bank0      RAM=gpr0       # these SECTION directives
18636 \layout LyX-Code
18637
18638 SECTION    NAME=bank1      RAM=gpr1       # should be added to link
18639 \layout LyX-Code
18640
18641 SECTION    NAME=bank2      RAM=gpr2       # section name 'bank?' with
18642 \layout LyX-Code
18643
18644 SECTION    NAME=bank3      RAM=gpr3       # a specific DATABANK name
18645 \layout LyX-Code
18646
18647 SECTION    NAME=bank4      RAM=gpr4
18648 \layout LyX-Code
18649
18650 SECTION    NAME=bank5      RAM=gpr5
18651 \layout Standard
18652
18653 The linker will recognise the section name set in the pragma statement and
18654  will position the variable at the memory bank set with the RAM field at
18655  the SECTION line in the linker script file.
18656 \layout Subsection
18657
18658 Header Files
18659 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
18660
18661 \end_inset
18662
18663
18664 \layout Standard
18665
18666 There is one main header file that can be included to the source files using
18667  the pic16 port.
18668  That file is the
18669 \series bold
18670 pic18fregs.h
18671 \series default
18672 .
18673  This header file contains the definitions for the processor special registers,
18674  so it is necessary if the source accesses them.
18675  It can be included by adding the following line in the beginning of the
18676  file:
18677 \layout LyX-Code
18678
18679 #include <pic18fregs.h>
18680 \layout Standard
18681
18682 The specific microcontroller is selected within the pic18fregs.h automatically,
18683  so the same source can be used with a variety of devices.
18684 \layout Subsection
18685
18686 Libraries
18687 \layout Standard
18688
18689 The libraries that PIC16
18690 \begin_inset LatexCommand \index{PIC16}
18691
18692 \end_inset
18693
18694  port depends on are the microcontroller device libraries which contain
18695  the symbol definitions for the microcontroller special function registers.
18696  These libraries have the format pic18fxxxx.lib, where
18697 \emph on
18698 xxxx
18699 \emph default
18700  is the microcontroller identification number.
18701  The specific library is selected automatically by the compiler at link
18702  stage according to the selected device.
18703 \layout Standard
18704
18705 Libraries are created with gplib which is part of the gputils package
18706 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
18707
18708 \end_inset
18709
18710 .
18711 \layout Subsubsection*
18712
18713 Building the libraries
18714 \layout Standard
18715
18716 Before using SDCC/pic16 there are some libraries that need to be compiled.
18717  This process is not done automatically by SDCC since not all users use
18718  SDCC for pic16 projects.
18719  So each user should compile the libraries separately.
18720 \layout Standard
18721
18722 The steps to compile the pic16 libraries under Linux are:
18723 \layout LyX-Code
18724
18725 cd device/lib/pic16
18726 \layout LyX-Code
18727
18728 ./configure
18729 \layout LyX-Code
18730
18731 make
18732 \layout LyX-Code
18733
18734 cd ..
18735 \layout LyX-Code
18736
18737 make model-pic16
18738 \layout LyX-Code
18739
18740 su -c 'make install'     # install the libraries, you need the root password
18741 \layout Standard
18742
18743 If you need to install the headers too, do:
18744 \layout LyX-Code
18745
18746 cd device/include
18747 \layout LyX-Code
18748
18749 su -c 'make install'     # install the headers, you need the root password
18750 \layout Standard
18751
18752 There exist a special target to build the I/O libraries.
18753  This target is not automatically build because it will build the I/O library
18754  for
18755 \emph on
18756 every
18757 \emph default
18758  supported device.
18759  This way building will take quite a lot of time.
18760  Users are advised to edit the
18761 \series bold
18762 device/lib/pic16/pics.build
18763 \series default
18764  file and then execute:
18765 \layout LyX-Code
18766
18767 make lib-io
18768 \layout Subsection
18769
18770 Memory Models
18771 \layout Standard
18772
18773 The following memory models are supported by the PIC16 port:
18774 \layout Itemize
18775
18776 small model
18777 \layout Itemize
18778
18779 large model
18780 \layout Standard
18781
18782 Memory model affects the default size of pointers within the source.
18783  The sizes are shown in the next table:
18784 \layout Standard
18785 \align center
18786
18787 \begin_inset  Tabular
18788 <lyxtabular version="3" rows="3" columns="3">
18789 <features>
18790 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18791 <column alignment="center" valignment="top" leftline="true" width="0">
18792 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18793 <row topline="true" bottomline="true">
18794 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18795 \begin_inset Text
18796
18797 \layout Standard
18798
18799 Pointer sizes according to memory model
18800 \end_inset
18801 </cell>
18802 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18803 \begin_inset Text
18804
18805 \layout Standard
18806
18807 small model
18808 \end_inset
18809 </cell>
18810 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18811 \begin_inset Text
18812
18813 \layout Standard
18814
18815 large model
18816 \end_inset
18817 </cell>
18818 </row>
18819 <row topline="true" bottomline="true">
18820 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18821 \begin_inset Text
18822
18823 \layout Standard
18824
18825 code pointers
18826 \end_inset
18827 </cell>
18828 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18829 \begin_inset Text
18830
18831 \layout Standard
18832
18833 16-bits
18834 \end_inset
18835 </cell>
18836 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18837 \begin_inset Text
18838
18839 \layout Standard
18840
18841 24-bits
18842 \end_inset
18843 </cell>
18844 </row>
18845 <row topline="true" bottomline="true">
18846 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18847 \begin_inset Text
18848
18849 \layout Standard
18850
18851 data pointers
18852 \end_inset
18853 </cell>
18854 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
18855 \begin_inset Text
18856
18857 \layout Standard
18858
18859 16-bits
18860 \end_inset
18861 </cell>
18862 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18863 \begin_inset Text
18864
18865 \layout Standard
18866
18867 16-bits
18868 \end_inset
18869 </cell>
18870 </row>
18871 </lyxtabular>
18872
18873 \end_inset
18874
18875
18876 \layout Standard
18877
18878 It is advisable that all sources within a project are compiled with the
18879  same memory model.
18880  If one wants to override the default memory model, this can be done by
18881  declaring a pointer as
18882 \series bold
18883 far
18884 \series default
18885  or
18886 \series bold
18887 near
18888 \series default
18889 .
18890  Far selects large memory model's pointers, while near selects small memory
18891  model's pointers.
18892 \layout Standard
18893
18894 The standard device libraries (see
18895 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
18896
18897 \end_inset
18898
18899 ) contain no reference to pointers, so they can be used with both memory
18900  models.
18901 \layout Subsection
18902
18903 Stack
18904 \layout Standard
18905
18906 The stack implementation for the PIC16 port uses two indirect registers,
18907  FSR1 and FSR2.
18908 \layout List
18909 \labelwidthstring 00.00.0000
18910
18911 FSR1 is assigned as stack pointer
18912 \layout List
18913 \labelwidthstring 00.00.0000
18914
18915 FSR2 is assigned as frame pointer
18916 \layout Standard
18917
18918 The following stack models are supported by the PIC16 port
18919 \layout Itemize
18920
18921
18922 \noun on
18923 small
18924 \noun default
18925  model
18926 \layout Itemize
18927
18928
18929 \noun on
18930 large
18931 \noun default
18932  model
18933 \layout Standard
18934
18935
18936 \noun on
18937 Small
18938 \noun default
18939  model means that only the FSRxL byte is used to access stack and frame,
18940  while
18941 \emph on
18942 \noun on
18943 large
18944 \emph default
18945 \noun default
18946  uses both FSRxL and FSRxH registers.
18947  The following table shows the stack/frame pointers sizes according to stack
18948  model and the maximum space they can address:
18949 \layout Standard
18950 \align center
18951
18952 \begin_inset  Tabular
18953 <lyxtabular version="3" rows="3" columns="3">
18954 <features>
18955 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18956 <column alignment="center" valignment="top" leftline="true" width="0">
18957 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18958 <row topline="true" bottomline="true">
18959 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18960 \begin_inset Text
18961
18962 \layout Standard
18963
18964 Stack & Frame pointer sizes according to stack model
18965 \end_inset
18966 </cell>
18967 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18968 \begin_inset Text
18969
18970 \layout Standard
18971
18972 small
18973 \end_inset
18974 </cell>
18975 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18976 \begin_inset Text
18977
18978 \layout Standard
18979
18980 large
18981 \end_inset
18982 </cell>
18983 </row>
18984 <row topline="true">
18985 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18986 \begin_inset Text
18987
18988 \layout Standard
18989
18990 Stack pointer FSR1
18991 \end_inset
18992 </cell>
18993 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18994 \begin_inset Text
18995
18996 \layout Standard
18997
18998 8-bits
18999 \end_inset
19000 </cell>
19001 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19002 \begin_inset Text
19003
19004 \layout Standard
19005
19006 16-bits
19007 \end_inset
19008 </cell>
19009 </row>
19010 <row topline="true" bottomline="true">
19011 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19012 \begin_inset Text
19013
19014 \layout Standard
19015
19016 Frame pointer FSR2
19017 \end_inset
19018 </cell>
19019 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19020 \begin_inset Text
19021
19022 \layout Standard
19023
19024 8-bits
19025 \end_inset
19026 </cell>
19027 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19028 \begin_inset Text
19029
19030 \layout Standard
19031
19032 16-bits
19033 \end_inset
19034 </cell>
19035 </row>
19036 </lyxtabular>
19037
19038 \end_inset
19039
19040
19041 \layout Standard
19042
19043
19044 \noun on
19045 Large
19046 \noun default
19047 stack model is currently not working properly throughout the code generator.
19048  So its use is not advised.
19049  Also there are some other points that need special care:
19050 \newline
19051
19052 \layout Enumerate
19053
19054 Do not create stack sections with size more than one physical bank (that
19055  is 256 bytes)
19056 \layout Enumerate
19057
19058 Stack sections should no cross physical bank limits (i.e.
19059  #pragma stack 0x50 0x100)
19060 \layout Standard
19061
19062 These limitations are caused by the fact that only FSRxL is modified when
19063  using SMALL stack model, so no more than 256 bytes of stack can be used.
19064  This problem will disappear after LARGE model is fully implemented.
19065 \layout Subsection
19066
19067 Functions
19068 \layout Standard
19069
19070 In addition to the standard SDCC function keywords, PIC16 port makes available
19071  two more:
19072 \layout List
19073 \labelwidthstring 00.00.0000
19074
19075 wparam Use the WREG to pass one byte of the first function argument.
19076  This improves speed but you may not use this for functions with arguments
19077  that are called via function pointers, otherwise the first byte of the
19078  first parameter will get lost.
19079  Usage:
19080 \layout LyX-Code
19081
19082 void func_wparam(int a) wparam
19083 \layout LyX-Code
19084
19085 {
19086 \layout LyX-Code
19087
19088     /* WREG hold the lower part of a */
19089 \layout LyX-Code
19090
19091     /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
19092  */
19093 \layout LyX-Code
19094
19095 ...
19096 \layout LyX-Code
19097
19098 }
19099 \layout Standard
19100
19101 This keyword replaces the deprecated wparam pragma.
19102 \layout List
19103 \labelwidthstring 00.00.0000
19104
19105 shadowregs When entering/exiting an ISR, it is possible to take advantage
19106  of the PIC18F hardware shadow registers which hold the values of WREG,
19107  STATUS and BSR registers.
19108  This can be done by adding the keyword
19109 \emph on
19110 shadowregs
19111 \emph default
19112  before the
19113 \emph on
19114 interrupt
19115 \emph default
19116  keyword in the function's header.
19117 \layout LyX-Code
19118
19119 void isr_shadow(void) shadowregs interrupt 1
19120 \layout LyX-Code
19121
19122 {
19123 \layout LyX-Code
19124
19125 ...
19126 \layout LyX-Code
19127
19128 }
19129 \layout Standard
19130
19131
19132 \emph on
19133 shadowregs
19134 \emph default
19135  instructs the code generator not to store/restore WREG, STATUS, BSR when
19136  entering/exiting the ISR.
19137 \layout Subsection
19138
19139 Function return values
19140 \layout Standard
19141
19142 Return values from functions are placed to the appropriate registers following
19143  a modified Microchip policy optimized for SDCC.
19144  The following table shows these registers:
19145 \layout Standard
19146 \align center
19147
19148 \begin_inset  Tabular
19149 <lyxtabular version="3" rows="6" columns="2">
19150 <features>
19151 <column alignment="center" valignment="top" leftline="true" width="0">
19152 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19153 <row topline="true" bottomline="true">
19154 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19155 \begin_inset Text
19156
19157 \layout Standard
19158
19159 size
19160 \end_inset
19161 </cell>
19162 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19163 \begin_inset Text
19164
19165 \layout Standard
19166
19167 destination register
19168 \end_inset
19169 </cell>
19170 </row>
19171 <row topline="true">
19172 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19173 \begin_inset Text
19174
19175 \layout Standard
19176
19177 8 bits
19178 \end_inset
19179 </cell>
19180 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19181 \begin_inset Text
19182
19183 \layout Standard
19184
19185 WREG
19186 \end_inset
19187 </cell>
19188 </row>
19189 <row topline="true">
19190 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19191 \begin_inset Text
19192
19193 \layout Standard
19194
19195 16 bits
19196 \end_inset
19197 </cell>
19198 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19199 \begin_inset Text
19200
19201 \layout Standard
19202
19203 PRODL:WREG
19204 \end_inset
19205 </cell>
19206 </row>
19207 <row topline="true">
19208 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19209 \begin_inset Text
19210
19211 \layout Standard
19212
19213 24 bits
19214 \end_inset
19215 </cell>
19216 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19217 \begin_inset Text
19218
19219 \layout Standard
19220
19221 PRODH:PRODL:WREG
19222 \end_inset
19223 </cell>
19224 </row>
19225 <row topline="true">
19226 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19227 \begin_inset Text
19228
19229 \layout Standard
19230
19231 32 bits
19232 \end_inset
19233 </cell>
19234 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19235 \begin_inset Text
19236
19237 \layout Standard
19238
19239 FSR0L:PRODH:PRODL:WREG
19240 \end_inset
19241 </cell>
19242 </row>
19243 <row topline="true" bottomline="true">
19244 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19245 \begin_inset Text
19246
19247 \layout Standard
19248
19249 >32 bits
19250 \end_inset
19251 </cell>
19252 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19253 \begin_inset Text
19254
19255 \layout Standard
19256
19257 on stack, FSR0 points to the beginning
19258 \end_inset
19259 </cell>
19260 </row>
19261 </lyxtabular>
19262
19263 \end_inset
19264
19265
19266 \layout Subsection
19267
19268 Interrupts
19269 \layout Standard
19270
19271 An interrupt servive routine (ISR) is declared using the
19272 \emph on
19273 interrupt
19274 \emph default
19275  keyword.
19276 \layout LyX-Code
19277
19278 void isr(void) interrupt
19279 \emph on
19280 n
19281 \layout LyX-Code
19282
19283 {
19284 \layout LyX-Code
19285
19286 ...
19287 \layout LyX-Code
19288
19289 }
19290 \layout Standard
19291
19292
19293 \emph on
19294 n
19295 \emph default
19296  is the interrupt number, which for PIC18F devices can be:
19297 \layout Standard
19298 \align center
19299
19300 \begin_inset  Tabular
19301 <lyxtabular version="3" rows="4" columns="3">
19302 <features>
19303 <column alignment="center" valignment="top" leftline="true" width="0">
19304 <column alignment="center" valignment="top" leftline="true" width="0">
19305 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19306 <row topline="true" bottomline="true">
19307 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19308 \begin_inset Text
19309
19310 \layout Standard
19311
19312
19313 \emph on
19314 n
19315 \end_inset
19316 </cell>
19317 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19318 \begin_inset Text
19319
19320 \layout Standard
19321
19322 Interrupt Vector
19323 \end_inset
19324 </cell>
19325 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19326 \begin_inset Text
19327
19328 \layout Standard
19329
19330 Interrupt Vector Address
19331 \end_inset
19332 </cell>
19333 </row>
19334 <row topline="true">
19335 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19336 \begin_inset Text
19337
19338 \layout Standard
19339
19340 0
19341 \end_inset
19342 </cell>
19343 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19344 \begin_inset Text
19345
19346 \layout Standard
19347
19348 RESET vector
19349 \end_inset
19350 </cell>
19351 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19352 \begin_inset Text
19353
19354 \layout Standard
19355
19356 0x000000
19357 \end_inset
19358 </cell>
19359 </row>
19360 <row topline="true">
19361 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19362 \begin_inset Text
19363
19364 \layout Standard
19365
19366
19367 \family roman
19368 \series medium
19369 \shape up
19370 \size normal
19371 \emph off
19372 \bar no
19373 \noun off
19374 \color none
19375 1
19376 \end_inset
19377 </cell>
19378 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19379 \begin_inset Text
19380
19381 \layout Standard
19382
19383
19384 \family roman
19385 \series medium
19386 \shape up
19387 \size normal
19388 \emph off
19389 \bar no
19390 \noun off
19391 \color none
19392 HIGH priority interrupts
19393 \end_inset
19394 </cell>
19395 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19396 \begin_inset Text
19397
19398 \layout Standard
19399
19400 0x000008
19401 \end_inset
19402 </cell>
19403 </row>
19404 <row topline="true" bottomline="true">
19405 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19406 \begin_inset Text
19407
19408 \layout Standard
19409
19410 2
19411 \end_inset
19412 </cell>
19413 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19414 \begin_inset Text
19415
19416 \layout Standard
19417
19418 LOW priority interrupts
19419 \end_inset
19420 </cell>
19421 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19422 \begin_inset Text
19423
19424 \layout Standard
19425
19426 0x000018
19427 \end_inset
19428 </cell>
19429 </row>
19430 </lyxtabular>
19431
19432 \end_inset
19433
19434
19435 \layout Standard
19436
19437 When generating assembly code for ISR the code generator places a
19438 \noun on
19439 goto
19440 \noun default
19441 instruction at the
19442 \emph on
19443 Interrupt Vector Address
19444 \emph default
19445  which points at the genetated ISR.
19446  This single GOTO instruction is part of an automatically generated
19447 \emph on
19448 interrupt entry point
19449 \emph default
19450  function.
19451  The actuall ISR code is placed as normally would in the code space.
19452  Upon interrupt request, the GOTO instruction is executed which jumps to
19453  the ISR code.
19454  When declaring interrupt functions as _naked this GOTO instruction is
19455 \series bold
19456 not
19457 \series default
19458  generated.
19459  The whole interrupt functions is therefore placed at the Interrupt Vector
19460  Address of the specific interrupt.
19461  This is not a problem for the LOW priority interrupts, but it is a problem
19462  for the RESET and the HIGH priority interrupts because code may be written
19463  at the next interrupt´s vector address and cause undeterminate program
19464  behaviour if that interrupt is raised.
19465 \begin_inset Foot
19466 collapsed false
19467
19468 \layout Standard
19469
19470 This is not a problem when
19471 \layout Enumerate
19472
19473 this is a HIGH interrupt ISR and LOW interrupts are
19474 \emph on
19475 disabled
19476 \emph default
19477  or not used.
19478 \layout Enumerate
19479
19480 when the ISR is small enough not to reach the next interrupt´s vector address.
19481 \end_inset
19482
19483
19484 \layout Standard
19485
19486
19487 \emph on
19488 n
19489 \emph default
19490  is possible to be omitted.
19491  This way a function is generated similar to an ISR, but it is not assigned
19492  to any interrupt.
19493 \layout Standard
19494
19495 When entering an interrupt, currently the PIC16
19496 \begin_inset LatexCommand \index{PIC16}
19497
19498 \end_inset
19499
19500  port automatically saves the following registers:
19501 \layout Itemize
19502
19503 WREG
19504 \layout Itemize
19505
19506 STATUS
19507 \layout Itemize
19508
19509 BSR
19510 \layout Itemize
19511
19512 PROD (PRODL and PRODH)
19513 \layout Itemize
19514
19515 FSR0 (FSR0L and FSR0H)
19516 \layout Standard
19517
19518 These registers are restored upon return from the interrupt routine.
19519 \begin_inset Foot
19520 collapsed false
19521
19522 \layout Standard
19523
19524 NOTE that when the _naked attribute is specified for an interrupt routine,
19525  then NO registers are stored or restored.
19526 \end_inset
19527
19528
19529 \layout Subsection
19530
19531 Generic Pointers
19532 \layout Standard
19533
19534 Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
19535  There are 3 types of generic pointers currently implemented data, code
19536  and eeprom pointers.
19537  They are differentiated by the value of the 7th and 6th bits of the upper
19538  byte:
19539 \layout Standard
19540 \align center
19541
19542 \begin_inset  Tabular
19543 <lyxtabular version="3" rows="5" columns="5">
19544 <features>
19545 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19546 <column alignment="center" valignment="top" width="0">
19547 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19548 <column alignment="center" valignment="top" width="0">
19549 <column alignment="left" valignment="top" rightline="true" width="0">
19550 <row topline="true" bottomline="true">
19551 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19552 \begin_inset Text
19553
19554 \layout Standard
19555
19556 pointer type
19557 \end_inset
19558 </cell>
19559 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19560 \begin_inset Text
19561
19562 \layout Standard
19563
19564 7th bit
19565 \end_inset
19566 </cell>
19567 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19568 \begin_inset Text
19569
19570 \layout Standard
19571
19572 6th bit
19573 \end_inset
19574 </cell>
19575 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19576 \begin_inset Text
19577
19578 \layout Standard
19579
19580 rest of the pointer
19581 \end_inset
19582 </cell>
19583 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19584 \begin_inset Text
19585
19586 \layout Standard
19587
19588 descrption
19589 \end_inset
19590 </cell>
19591 </row>
19592 <row topline="true" bottomline="true">
19593 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19594 \begin_inset Text
19595
19596 \layout Standard
19597
19598 data
19599 \end_inset
19600 </cell>
19601 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19602 \begin_inset Text
19603
19604 \layout Standard
19605
19606 1
19607 \end_inset
19608 </cell>
19609 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19610 \begin_inset Text
19611
19612 \layout Standard
19613
19614 0
19615 \end_inset
19616 </cell>
19617 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19618 \begin_inset Text
19619
19620 \layout Standard
19621
19622
19623 \family typewriter
19624 \shape slanted
19625 \emph on
19626 uuuuuu uuuuxxxx xxxxxxxx
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 a 12-bit data pointer in data RAM memory
19635 \end_inset
19636 </cell>
19637 </row>
19638 <row bottomline="true">
19639 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19640 \begin_inset Text
19641
19642 \layout Standard
19643
19644 code
19645 \end_inset
19646 </cell>
19647 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19648 \begin_inset Text
19649
19650 \layout Standard
19651
19652 0
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 0
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
19669 \family typewriter
19670 \shape slanted
19671 \emph on
19672 uxxxxx xxxxxxxx xxxxxxxx
19673 \end_inset
19674 </cell>
19675 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19676 \begin_inset Text
19677
19678 \layout Standard
19679
19680 a 21-bit code pointer in FLASH memory
19681 \end_inset
19682 </cell>
19683 </row>
19684 <row bottomline="true">
19685 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19686 \begin_inset Text
19687
19688 \layout Standard
19689
19690 eeprom
19691 \end_inset
19692 </cell>
19693 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19694 \begin_inset Text
19695
19696 \layout Standard
19697
19698 0
19699 \end_inset
19700 </cell>
19701 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19702 \begin_inset Text
19703
19704 \layout Standard
19705
19706 1
19707 \end_inset
19708 </cell>
19709 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19710 \begin_inset Text
19711
19712 \layout Standard
19713
19714
19715 \family typewriter
19716 \shape slanted
19717 \emph on
19718 uuuuuu uuuuuuxx xxxxxxxx
19719 \end_inset
19720 </cell>
19721 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19722 \begin_inset Text
19723
19724 \layout Standard
19725
19726 a 10-bit eeprom pointer in EEPROM memory
19727 \end_inset
19728 </cell>
19729 </row>
19730 <row bottomline="true">
19731 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19732 \begin_inset Text
19733
19734 \layout Standard
19735
19736 (unimplemented)
19737 \end_inset
19738 </cell>
19739 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19740 \begin_inset Text
19741
19742 \layout Standard
19743
19744 1
19745 \end_inset
19746 </cell>
19747 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19748 \begin_inset Text
19749
19750 \layout Standard
19751
19752 1
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
19761 \family typewriter
19762 \shape slanted
19763 \emph on
19764 xxxxxx xxxxxxxx xxxxxxxx
19765 \end_inset
19766 </cell>
19767 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19768 \begin_inset Text
19769
19770 \layout Standard
19771
19772 unimplemented pointer type
19773 \end_inset
19774 </cell>
19775 </row>
19776 </lyxtabular>
19777
19778 \end_inset
19779
19780
19781 \layout Standard
19782
19783 Generic pointer are read and written with a set of library functions which
19784  read/write 1, 2, 3, 4 bytes.
19785 \layout Subsection
19786
19787 PIC16 C Libraries
19788 \layout Subsubsection
19789
19790 Standard I/O Streams
19791 \layout Standard
19792
19793 In the
19794 \emph on
19795 stdio.h
19796 \emph default
19797  the type FILE is defined as:
19798 \layout LyX-Code
19799
19800 typedef char * FILE;
19801 \layout Standard
19802
19803 This type is the stream type implemented I/O in the PIC18F devices.
19804  Also the standard input and output streams are declared in stdio.h:
19805 \layout LyX-Code
19806
19807 extern FILE * stdin;
19808 \layout LyX-Code
19809
19810 extern FILE * stdout;
19811 \layout Standard
19812
19813 The FILE type is actually a generic pointer which defines one more type
19814  of generic pointers, the
19815 \emph on
19816 stream
19817 \emph default
19818 pointer.
19819  This new type has the format:
19820 \layout Standard
19821 \align center
19822
19823 \begin_inset  Tabular
19824 <lyxtabular version="3" rows="2" columns="7">
19825 <features>
19826 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19827 <column alignment="center" valignment="top" width="0">
19828 <column alignment="center" valignment="top" leftline="true" width="0">
19829 <column alignment="center" valignment="top" leftline="true" width="0">
19830 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19831 <column alignment="center" valignment="top" width="0">
19832 <column alignment="left" valignment="top" rightline="true" width="0">
19833 <row topline="true" bottomline="true">
19834 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19835 \begin_inset Text
19836
19837 \layout Standard
19838
19839 pointer type
19840 \end_inset
19841 </cell>
19842 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19843 \begin_inset Text
19844
19845 \layout Standard
19846
19847 <7:6>
19848 \end_inset
19849 </cell>
19850 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19851 \begin_inset Text
19852
19853 \layout Standard
19854
19855 <5>
19856 \end_inset
19857 </cell>
19858 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19859 \begin_inset Text
19860
19861 \layout Standard
19862
19863 <4>
19864 \end_inset
19865 </cell>
19866 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19867 \begin_inset Text
19868
19869 \layout Standard
19870
19871 <3:0>
19872 \end_inset
19873 </cell>
19874 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19875 \begin_inset Text
19876
19877 \layout Standard
19878
19879 rest of the pointer
19880 \end_inset
19881 </cell>
19882 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19883 \begin_inset Text
19884
19885 \layout Standard
19886
19887 descrption
19888 \end_inset
19889 </cell>
19890 </row>
19891 <row topline="true" bottomline="true">
19892 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19893 \begin_inset Text
19894
19895 \layout Standard
19896
19897 stream
19898 \end_inset
19899 </cell>
19900 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19901 \begin_inset Text
19902
19903 \layout Standard
19904
19905 00
19906 \end_inset
19907 </cell>
19908 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19909 \begin_inset Text
19910
19911 \layout Standard
19912
19913 1
19914 \end_inset
19915 </cell>
19916 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19917 \begin_inset Text
19918
19919 \layout Standard
19920
19921 0
19922 \end_inset
19923 </cell>
19924 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19925 \begin_inset Text
19926
19927 \layout Standard
19928
19929 nnnn
19930 \end_inset
19931 </cell>
19932 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19933 \begin_inset Text
19934
19935 \layout Standard
19936
19937
19938 \family typewriter
19939 \shape slanted
19940 \emph on
19941 uuuuuuuu uuuuuuuu
19942 \end_inset
19943 </cell>
19944 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19945 \begin_inset Text
19946
19947 \layout Standard
19948
19949 upper byte high nubble is 0x2n, the rest are zeroes
19950 \end_inset
19951 </cell>
19952 </row>
19953 </lyxtabular>
19954
19955 \end_inset
19956
19957
19958 \layout Standard
19959
19960 Currently implemented there are 3 types of streams defined:
19961 \layout Standard
19962 \align center
19963
19964 \begin_inset  Tabular
19965 <lyxtabular version="3" rows="4" columns="4">
19966 <features>
19967 <column alignment="center" valignment="top" leftline="true" width="0">
19968 <column alignment="center" valignment="top" leftline="true" width="0">
19969 <column alignment="center" valignment="top" leftline="true" width="0">
19970 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19971 <row topline="true" bottomline="true">
19972 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19973 \begin_inset Text
19974
19975 \layout Standard
19976
19977 stream type
19978 \end_inset
19979 </cell>
19980 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19981 \begin_inset Text
19982
19983 \layout Standard
19984
19985 value
19986 \end_inset
19987 </cell>
19988 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19989 \begin_inset Text
19990
19991 \layout Standard
19992
19993 module
19994 \end_inset
19995 </cell>
19996 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19997 \begin_inset Text
19998
19999 \layout Standard
20000
20001 description
20002 \end_inset
20003 </cell>
20004 </row>
20005 <row topline="true">
20006 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20007 \begin_inset Text
20008
20009 \layout Standard
20010
20011 STREAM_USART
20012 \end_inset
20013 </cell>
20014 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20015 \begin_inset Text
20016
20017 \layout Standard
20018
20019
20020 \family typewriter
20021 0x200000UL
20022 \end_inset
20023 </cell>
20024 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20025 \begin_inset Text
20026
20027 \layout Standard
20028
20029 USART
20030 \end_inset
20031 </cell>
20032 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20033 \begin_inset Text
20034
20035 \layout Standard
20036
20037 Writes/Reads characters via the USART peripheral
20038 \end_inset
20039 </cell>
20040 </row>
20041 <row topline="true">
20042 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20043 \begin_inset Text
20044
20045 \layout Standard
20046
20047 STREAM_MSSP
20048 \end_inset
20049 </cell>
20050 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20051 \begin_inset Text
20052
20053 \layout Standard
20054
20055
20056 \family typewriter
20057 0x210000UL
20058 \end_inset
20059 </cell>
20060 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20061 \begin_inset Text
20062
20063 \layout Standard
20064
20065 MSSP
20066 \end_inset
20067 </cell>
20068 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20069 \begin_inset Text
20070
20071 \layout Standard
20072
20073 Writes/Reads characters via the MSSP peripheral
20074 \end_inset
20075 </cell>
20076 </row>
20077 <row topline="true" bottomline="true">
20078 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20079 \begin_inset Text
20080
20081 \layout Standard
20082
20083 STREAM_USER
20084 \end_inset
20085 </cell>
20086 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20087 \begin_inset Text
20088
20089 \layout Standard
20090
20091
20092 \family typewriter
20093 0x2f0000UL
20094 \end_inset
20095 </cell>
20096 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20097 \begin_inset Text
20098
20099 \layout Standard
20100
20101 (none)
20102 \end_inset
20103 </cell>
20104 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20105 \begin_inset Text
20106
20107 \layout Standard
20108
20109 Writes/Reads characters via used defined functions
20110 \end_inset
20111 </cell>
20112 </row>
20113 </lyxtabular>
20114
20115 \end_inset
20116
20117
20118 \layout Standard
20119
20120 The stream identifiers are declared as macros in the stdio.h header.
20121 \layout Standard
20122
20123 In the libc library there exist the functions that are used to write to
20124  each of the above streams.
20125  These are
20126 \layout List
20127 \labelwidthstring 00.00.0000
20128
20129 _
20130 \begin_inset ERT
20131 status Collapsed
20132
20133 \layout Standard
20134
20135 \backslash
20136 /
20137 \end_inset
20138
20139 _stream_usart_putchar writes a character at the USART stream
20140 \layout List
20141 \labelwidthstring 00.00.0000
20142
20143 _
20144 \begin_inset ERT
20145 status Collapsed
20146
20147 \layout Standard
20148
20149 \backslash
20150 /
20151 \end_inset
20152
20153 _stream_mssp_putchar writes a character at the MSSP stream
20154 \layout List
20155 \labelwidthstring 00.00.0000
20156
20157 putchar dummy function.
20158  This writes a character to a user specified manner.
20159 \layout Standard
20160
20161 In order to increase performance
20162 \emph on
20163 putchar
20164 \emph default
20165 is declared in stdio.h as having its parameter in WREG (it has the wparam
20166  keyword).
20167  In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
20168  in a user-friendly way.
20169
20170 \emph on
20171 arg
20172 \emph default
20173  is the name of the variable that holds the character to print.
20174  An example follows:
20175 \layout LyX-Code
20176
20177 #include <pic18fregs.h>
20178 \newline
20179 #include <stdio.h>
20180 \newline
20181
20182 \newline
20183 PUTCHAR( c )
20184 \layout LyX-Code
20185
20186 {
20187 \layout LyX-Code
20188
20189     PORTA = c;    /* dump character c to PORTA */
20190 \layout LyX-Code
20191
20192 }
20193 \newline
20194
20195 \newline
20196 void main(void)
20197 \layout LyX-Code
20198
20199 {
20200 \layout LyX-Code
20201
20202     stdout = STREAM_USER;    /* this is not necessery, since stdout points
20203 \layout LyX-Code
20204
20205                               * by default to STREAM_USER */
20206 \layout LyX-Code
20207
20208     printf (¨This is a printf test
20209 \backslash
20210 n¨);
20211 \layout LyX-Code
20212
20213 }
20214 \layout LyX-Code
20215
20216 \layout Subsubsection
20217
20218 Printing functions
20219 \layout Standard
20220
20221 PIC16 contains an implementation of the printf-family of functions.
20222  There exist the following functions:
20223 \layout LyX-Code
20224
20225 extern unsigned int sprintf(char *buf, char *fmt, ...);
20226 \layout LyX-Code
20227
20228 extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
20229 \layout LyX-Code
20230
20231 \layout LyX-Code
20232
20233 extern unsigned int printf(char *fmt, ...);
20234 \layout LyX-Code
20235
20236 extern unsigned int vprintf(char *fmt, va_lista ap);
20237 \layout LyX-Code
20238
20239 \layout LyX-Code
20240
20241 extern unsigned int fprintf(FILE *fp, char *fmt, ...);
20242 \layout LyX-Code
20243
20244 extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
20245 \layout Standard
20246
20247 For sprintf and vsprintf
20248 \emph on
20249 buf
20250 \emph default
20251 should normally be a data pointer where the resulting string will be placed.
20252  No range checking is done so the user should allocate the necessery buffer.
20253  For fprintf and vfprintf
20254 \emph on
20255 fp
20256 \emph default
20257  should be a stream pointer (i.e.
20258  stdout, STREAM_MSSP, etc...).
20259 \layout Subsubsection
20260
20261 Signals
20262 \layout Standard
20263
20264 The PIC18F family of microcontrollers supports a number of interrupt sources.
20265  A list of these interrupts is shown in the following table:
20266 \layout Standard
20267 \align center
20268
20269 \begin_inset  Tabular
20270 <lyxtabular version="3" rows="11" columns="4">
20271 <features>
20272 <column alignment="left" valignment="top" leftline="true" width="0">
20273 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20274 <column alignment="left" valignment="top" leftline="true" width="0">
20275 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20276 <row topline="true" bottomline="true">
20277 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20278 \begin_inset Text
20279
20280 \layout Standard
20281
20282 signal name
20283 \end_inset
20284 </cell>
20285 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20286 \begin_inset Text
20287
20288 \layout Standard
20289
20290 description
20291 \end_inset
20292 </cell>
20293 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20294 \begin_inset Text
20295
20296 \layout Standard
20297
20298 signal name
20299 \end_inset
20300 </cell>
20301 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20302 \begin_inset Text
20303
20304 \layout Standard
20305
20306 descritpion
20307 \end_inset
20308 </cell>
20309 </row>
20310 <row topline="true">
20311 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20312 \begin_inset Text
20313
20314 \layout Standard
20315
20316 SIG_RB
20317 \end_inset
20318 </cell>
20319 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20320 \begin_inset Text
20321
20322 \layout Standard
20323
20324 PORTB change interrupt
20325 \end_inset
20326 </cell>
20327 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20328 \begin_inset Text
20329
20330 \layout Standard
20331
20332 SIG_EE
20333 \end_inset
20334 </cell>
20335 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20336 \begin_inset Text
20337
20338 \layout Standard
20339
20340 EEPROM/FLASH write complete interrupt
20341 \end_inset
20342 </cell>
20343 </row>
20344 <row topline="true">
20345 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20346 \begin_inset Text
20347
20348 \layout Standard
20349
20350 SIG_INT0
20351 \end_inset
20352 </cell>
20353 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20354 \begin_inset Text
20355
20356 \layout Standard
20357
20358 INT0 external interrupt
20359 \end_inset
20360 </cell>
20361 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20362 \begin_inset Text
20363
20364 \layout Standard
20365
20366 SIG_BCOL
20367 \end_inset
20368 </cell>
20369 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20370 \begin_inset Text
20371
20372 \layout Standard
20373
20374 Bus collision interrupt
20375 \end_inset
20376 </cell>
20377 </row>
20378 <row topline="true">
20379 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20380 \begin_inset Text
20381
20382 \layout Standard
20383
20384 SIG_INT1
20385 \end_inset
20386 </cell>
20387 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20388 \begin_inset Text
20389
20390 \layout Standard
20391
20392 INT1 external interrupt
20393 \end_inset
20394 </cell>
20395 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20396 \begin_inset Text
20397
20398 \layout Standard
20399
20400 SIG_LVD
20401 \end_inset
20402 </cell>
20403 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20404 \begin_inset Text
20405
20406 \layout Standard
20407
20408 Low voltage detect interrupt
20409 \end_inset
20410 </cell>
20411 </row>
20412 <row topline="true">
20413 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20414 \begin_inset Text
20415
20416 \layout Standard
20417
20418 SIG_INT2
20419 \end_inset
20420 </cell>
20421 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20422 \begin_inset Text
20423
20424 \layout Standard
20425
20426 INT2 external interrupt
20427 \end_inset
20428 </cell>
20429 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20430 \begin_inset Text
20431
20432 \layout Standard
20433
20434 SIG_PSP
20435 \end_inset
20436 </cell>
20437 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20438 \begin_inset Text
20439
20440 \layout Standard
20441
20442 Parallel slave port interrupt
20443 \end_inset
20444 </cell>
20445 </row>
20446 <row topline="true">
20447 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20448 \begin_inset Text
20449
20450 \layout Standard
20451
20452 SIG_CCP1
20453 \end_inset
20454 </cell>
20455 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20456 \begin_inset Text
20457
20458 \layout Standard
20459
20460 CCP1 module interrupt
20461 \end_inset
20462 </cell>
20463 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20464 \begin_inset Text
20465
20466 \layout Standard
20467
20468 SIG_AD
20469 \end_inset
20470 </cell>
20471 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20472 \begin_inset Text
20473
20474 \layout Standard
20475
20476 AD convertion complete interrupt
20477 \end_inset
20478 </cell>
20479 </row>
20480 <row topline="true">
20481 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20482 \begin_inset Text
20483
20484 \layout Standard
20485
20486 SIG_CCP2
20487 \end_inset
20488 </cell>
20489 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20490 \begin_inset Text
20491
20492 \layout Standard
20493
20494 CCP2 module interrupt
20495 \end_inset
20496 </cell>
20497 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20498 \begin_inset Text
20499
20500 \layout Standard
20501
20502 SIG_RC
20503 \end_inset
20504 </cell>
20505 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20506 \begin_inset Text
20507
20508 \layout Standard
20509
20510 USART receive interrupt
20511 \end_inset
20512 </cell>
20513 </row>
20514 <row topline="true">
20515 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20516 \begin_inset Text
20517
20518 \layout Standard
20519
20520 SIG_TMR0
20521 \end_inset
20522 </cell>
20523 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20524 \begin_inset Text
20525
20526 \layout Standard
20527
20528 TMR0 overflow interrupt
20529 \end_inset
20530 </cell>
20531 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20532 \begin_inset Text
20533
20534 \layout Standard
20535
20536 SIG_TX
20537 \end_inset
20538 </cell>
20539 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20540 \begin_inset Text
20541
20542 \layout Standard
20543
20544 USART transmit interrupt
20545 \end_inset
20546 </cell>
20547 </row>
20548 <row topline="true">
20549 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20550 \begin_inset Text
20551
20552 \layout Standard
20553
20554 SIG_TMR1
20555 \end_inset
20556 </cell>
20557 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20558 \begin_inset Text
20559
20560 \layout Standard
20561
20562 TMR1 overflow interrupt
20563 \end_inset
20564 </cell>
20565 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20566 \begin_inset Text
20567
20568 \layout Standard
20569
20570 SIG_MSSP
20571 \end_inset
20572 </cell>
20573 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20574 \begin_inset Text
20575
20576 \layout Standard
20577
20578 SSP receive/transmit interrupt
20579 \end_inset
20580 </cell>
20581 </row>
20582 <row topline="true">
20583 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20584 \begin_inset Text
20585
20586 \layout Standard
20587
20588 SIG_TMR2
20589 \end_inset
20590 </cell>
20591 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20592 \begin_inset Text
20593
20594 \layout Standard
20595
20596 TMR2 matches PR2 interrupt
20597 \end_inset
20598 </cell>
20599 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20600 \begin_inset Text
20601
20602 \layout Standard
20603
20604 \end_inset
20605 </cell>
20606 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20607 \begin_inset Text
20608
20609 \layout Standard
20610
20611 \end_inset
20612 </cell>
20613 </row>
20614 <row topline="true" bottomline="true">
20615 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20616 \begin_inset Text
20617
20618 \layout Standard
20619
20620 SIG_TMR3
20621 \end_inset
20622 </cell>
20623 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20624 \begin_inset Text
20625
20626 \layout Standard
20627
20628 TMR3 overflow interrupt
20629 \end_inset
20630 </cell>
20631 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20632 \begin_inset Text
20633
20634 \layout Standard
20635
20636 \end_inset
20637 </cell>
20638 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20639 \begin_inset Text
20640
20641 \layout Standard
20642
20643 \end_inset
20644 </cell>
20645 </row>
20646 </lyxtabular>
20647
20648 \end_inset
20649
20650
20651 \layout Standard
20652
20653 The prototypes for these names are defined in the header file
20654 \emph on
20655 signal.h
20656 \emph default
20657  .
20658 \layout Standard
20659
20660 In order to simplify signal handling, a number of macros is provided:
20661 \layout List
20662 \labelwidthstring 00.00.0000
20663
20664 DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
20665  high priority interrupts.
20666
20667 \emph on
20668 name
20669 \emph default
20670  is the function name to use.
20671 \layout List
20672 \labelwidthstring 00.00.0000
20673
20674 DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
20675  low priority interrupt.
20676
20677 \emph on
20678 name
20679 \emph default
20680  is the function name to use.
20681 \layout List
20682 \labelwidthstring 00.00.0000
20683
20684 DEF_HANDLER(sig,handler) define a handler for signal
20685 \emph on
20686 sig.
20687 \layout List
20688 \labelwidthstring 00.00.0000
20689
20690 END_DEF end the declaration of the dispatch table.
20691 \layout Standard
20692
20693 Additionally there are two more macros to simplify the declaration of the
20694  signal handler:
20695 \layout List
20696 \labelwidthstring 00.00.0000
20697
20698
20699 \series medium
20700 SIGHANDLER(handler)
20701 \series default
20702 this declares the function prototype for the
20703 \emph on
20704 handler
20705 \emph default
20706  function.
20707 \layout List
20708 \labelwidthstring 00.00.0000
20709
20710 SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
20711 \layout Standard
20712
20713 An example of using the macros above is shown below:
20714 \layout LyX-Code
20715
20716 #include <pic18fregs.h>
20717 \layout LyX-Code
20718
20719 #include <signal.h>
20720 \newline
20721
20722 \newline
20723 DEF_INTHIGH(high_int)
20724 \layout LyX-Code
20725
20726 DEF_HANDLER(SIG_TMR0, _tmr0_handler)
20727 \layout LyX-Code
20728
20729 DEF_HANDLER(SIG_BCOL, _bcol_handler)
20730 \layout LyX-Code
20731
20732 END_DEF
20733 \newline
20734
20735 \newline
20736 SIGHANDLER(_tmr0_handler)
20737 \layout LyX-Code
20738
20739 {
20740 \layout LyX-Code
20741
20742   /* action to be taken when timer 0 overflows */
20743 \layout LyX-Code
20744
20745 }
20746 \newline
20747
20748 \newline
20749 SIGHANDLERNAKED(_bcol_handler)
20750 \layout LyX-Code
20751
20752 {
20753 \layout LyX-Code
20754
20755   _asm
20756 \layout LyX-Code
20757
20758     /* action to be taken when bus collision occurs */
20759 \layout LyX-Code
20760
20761     retfie
20762 \layout LyX-Code
20763
20764  _endasm;
20765 \layout LyX-Code
20766
20767 }
20768 \layout Standard
20769
20770
20771 \series bold
20772 NOTES:
20773 \series default
20774  Special care should be taken when using the above scheme:
20775 \layout Itemize
20776
20777 do not place a colon (;) at the end of the DEF_* and END_DEF macros.
20778 \layout Itemize
20779
20780 when declaring SIGHANDLERNAKED handler never forget to use
20781 \emph on
20782 retfie
20783 \emph default
20784  for proper returning.
20785 \layout Subsection
20786
20787 PIC16 Port -- Tips
20788 \layout Standard
20789
20790 Here you can find some general tips for compiling programs with SDCC/pic16.
20791 \layout Subsubsection
20792
20793 Stack size
20794 \layout Standard
20795
20796 The default stack size (that is 64 bytes) probably is enough for many programs.
20797  One must take care that when there are many levels of function nesting,
20798  or there is excessive usage of stack, its size should be extended.
20799  An example of such a case is the printf/sprintf family of functions.
20800  If you encounter problems like not being able to print integers, then you
20801  need to set the stack size around the maximum (256 for small stack model).
20802  The following diagram shows what happens when calling printf to print an
20803  integer:
20804 \layout LyX-Code
20805
20806 printf () --> ltoa () --> ultoa () --> divschar ()
20807 \layout Standard
20808
20809 It is should be understood that stack is easily consumed when calling complicate
20810 d functions.
20811  Using command line arguments like -
20812 \begin_inset ERT
20813 status Collapsed
20814
20815 \layout Standard
20816
20817 \backslash
20818 /
20819 \end_inset
20820
20821 -fommit-frame-pointer might reduce stack usage by not creating unnecessery
20822  stack frames.
20823  Other ways to reduce stack usage may exist.
20824 \layout Chapter
20825
20826 Debugging
20827 \layout Standard
20828
20829 There are several approaches to debugging your code.
20830  This chapter is meant to show your options and to give detail on some of
20831  them:
20832 \newline
20833
20834 \newline
20835 When writing your code:
20836 \layout Itemize
20837
20838 write your code with debugging in mind (avoid duplicating code, put conceptually
20839  similar variables into structs, use structured code, have strategic points
20840  within your code where all variables are consistent, ...)
20841 \layout Itemize
20842
20843 run a syntax-checking tool like splint
20844 \begin_inset LatexCommand \index{splint (syntax checking tool)}
20845
20846 \end_inset
20847
20848
20849 \begin_inset LatexCommand \index{lint (syntax checking tool)}
20850
20851 \end_inset
20852
20853  (see -
20854 \begin_inset ERT
20855 status Collapsed
20856
20857 \layout Standard
20858
20859 \backslash
20860 /
20861 \end_inset
20862
20863 -more-pedantic
20864 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
20865
20866 \end_inset
20867
20868 ) over the code.
20869 \layout Itemize
20870
20871 for the high level code use a C-compiler (like f.e.
20872  GCC) to compile run and debug the code on your host.
20873  See (see -
20874 \begin_inset ERT
20875 status Collapsed
20876
20877 \layout Standard
20878
20879 \backslash
20880 /
20881 \end_inset
20882
20883 -more-pedantic
20884 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
20885
20886 \end_inset
20887
20888  ) on howto handle syntax extensions like __xdata, __at(), ...
20889
20890 \layout Itemize
20891
20892 use another C-compiler to compile code for your target.
20893  Always an option but not recommended:) And not very likely to help you.
20894  If you seriously consider walking this path you should at least occasionally
20895  check portability of your code.
20896  Most commercial compiler vendors will offer an evaluation version so you
20897  can test compile your code or snippets of your code.
20898 \layout Standard
20899
20900 Debugging on a simulator:
20901 \layout Itemize
20902
20903 there is a separate section about SDCDB (section
20904 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
20905
20906 \end_inset
20907
20908 ) below.
20909 \layout Itemize
20910
20911 or (8051 specific) use a freeware/commercial simulator which interfaces
20912  to the AOMF
20913 \begin_inset LatexCommand \index{AOMF, AOMF51}
20914
20915 \end_inset
20916
20917  file (see
20918 \begin_inset LatexCommand \ref{OMF file}
20919
20920 \end_inset
20921
20922 ) optionally generated by SDCC.
20923 \layout Standard
20924
20925 Debugging On-target:
20926 \layout Itemize
20927
20928 use a MCU port pin to serially output debug data to the RS232 port of your
20929  host.
20930  You'll probably want some level shifting device typically involving a MAX232
20931  or similar IC.
20932  If the hardware serial port of the MCU is not available search for 'Software
20933  UART' in your favourite search machine.
20934 \layout Itemize
20935
20936 use an on-target monitor.
20937  In this context a monitor is a small program which usually accepts commands
20938  via a serial line and allows to set program counter, to single step through
20939  a program and read/write memory locations.
20940  For the 8051 a good example of a monitor with a very liberal licence is
20941  paulmon (
20942 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/paulmon2.html}
20943
20944 \end_inset
20945
20946 ).
20947 \layout Itemize
20948
20949 toggle MCU port pins at strategic points within your code and use an oscilloscop
20950 e.
20951  A
20952 \emph on
20953 digital oscilloscope
20954 \emph default
20955
20956 \begin_inset LatexCommand \index{oscilloscope}
20957
20958 \end_inset
20959
20960  with deep trace memory is really helpful especially if you have to debug
20961  a realtime application.
20962  If you need to monitor more pins than your oscilloscope provides you can
20963  sometimes get away with a small R-2R network.
20964  On a single channel oscilloscope you could f.e.
20965  monitor 2 push-pull driven pins by connecting one via a 10\SpecialChar ~
20966 k
20967 \begin_inset Formula $\Omega$
20968 \end_inset
20969
20970  resistor and the other one by a 5\SpecialChar ~
20971 k
20972 \begin_inset Formula $\Omega$
20973 \end_inset
20974
20975  resistor to the oscilloscope probe (check output drive capability of the
20976  pins you want to monitor).
20977  If you need to monitor many more pins a
20978 \emph on
20979 logic analyzer
20980 \emph default
20981  will be handy.
20982 \layout Itemize
20983
20984 use an ICE (
20985 \emph on
20986 i
20987 \emph default
20988 n
20989 \emph on
20990 c
20991 \emph default
20992 ircuit
20993 \emph on
20994 e
20995 \emph default
20996 mulator
20997 \begin_inset LatexCommand \index{ICE (in circuit emulator)}
20998
20999 \end_inset
21000
21001 ).
21002  Usually very expensive.
21003  And very nice to have too.
21004  And usually locks you (for years...) to the devices the ICE can emulate.
21005
21006 \layout Itemize
21007
21008 use a remote debugger.
21009  In most 8-bit systems the symbol information is not available on the target,
21010  and a complete debugger is too bulky for the target system.
21011  Therefore usually a debugger on the host system connects to an on-target
21012  debugging stub which accepts only primitive commands.
21013
21014 \newline
21015 Terms to enter into your favourite search engine could be 'remote debugging',
21016  'gdb stub' or 'inferior debugger'.
21017  (is there one?)
21018 \layout Itemize
21019
21020 use an on target hardware debugger.
21021  Some of the more modern MCUs include hardware support for setting break
21022  points and monitoring/changing variables by using dedicated hardware pins.
21023  This facility doesn't require additional code to run on the target and
21024
21025 \emph on
21026 usually
21027 \emph default
21028  doesn't affect runtime behaviour until a breakpoint is hit.
21029  For the mcs51 most hardware debuggers use the AOMF
21030 \begin_inset LatexCommand \index{AOMF, AOMF51}
21031
21032 \end_inset
21033
21034  file (see
21035 \begin_inset LatexCommand \ref{OMF file}
21036
21037 \end_inset
21038
21039 ) as input file.
21040
21041 \layout Standard
21042
21043 Last not least:
21044 \layout Itemize
21045
21046 if you are not familiar with any of the following terms you're likely to
21047  run into problems rather sooner than later:
21048 \emph on
21049 volatile
21050 \emph default
21051 ,
21052 \emph on
21053 atomic
21054 \emph default
21055 ,
21056 \emph on
21057 memory map
21058 \emph default
21059 ,
21060 \emph on
21061 overlay
21062 \emph default
21063 .
21064  As an embedded programmer you
21065 \emph on
21066 have
21067 \emph default
21068  to know them so why not look them up
21069 \emph on
21070 before
21071 \emph default
21072  you have problems?)
21073 \layout Itemize
21074
21075 tell someone else about your problem (actually this is a surprisingly effective
21076  means to hunt down the bug even if the listener is not familiar with your
21077  environment).
21078  As 'failure to communicate' is probably one of the job-induced deformations
21079  of an embedded programmer this is highly encouraged.
21080 \layout Section
21081
21082 Debugging with SDCDB
21083 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
21084
21085 \end_inset
21086
21087
21088 \begin_inset LatexCommand \index{sdcdb (debugger)}
21089
21090 \end_inset
21091
21092
21093 \layout Standard
21094
21095 SDCC is distributed with a source level debugger
21096 \begin_inset LatexCommand \index{Debugger}
21097
21098 \end_inset
21099
21100 .
21101  The debugger uses a command line interface, the command repertoire of the
21102  debugger has been kept as close to gdb
21103 \begin_inset LatexCommand \index{gdb}
21104
21105 \end_inset
21106
21107  (the GNU debugger) as possible.
21108  The configuration and build process is part of the standard compiler installati
21109 on, which also builds and installs the debugger in the target directory
21110  specified during configuration.
21111  The debugger allows you debug BOTH at the C source and at the ASM source
21112  level.
21113  Sdcdb is currently not available on Win32 platforms.
21114 \layout Subsection
21115
21116 Compiling for Debugging
21117 \layout Standard
21118
21119 The -
21120 \begin_inset ERT
21121 status Collapsed
21122
21123 \layout Standard
21124
21125 \backslash
21126 /
21127 \end_inset
21128
21129 -debug
21130 \begin_inset LatexCommand \index{-\/-debug}
21131
21132 \end_inset
21133
21134  option must be specified for all files for which debug information is to
21135  be generated.
21136  The compiler generates a .adb file for each of these files.
21137  The linker creates the .cdb
21138 \begin_inset LatexCommand \index{<file>.cdb}
21139
21140 \end_inset
21141
21142  file from the .adb
21143 \begin_inset LatexCommand \index{<file>.adb}
21144
21145 \end_inset
21146
21147  files and the address information.
21148  This .cdb is used by the debugger.
21149 \layout Subsection
21150
21151 How the Debugger Works
21152 \layout Standard
21153
21154 When the -
21155 \begin_inset ERT
21156 status Collapsed
21157
21158 \layout Standard
21159
21160 \backslash
21161 /
21162 \end_inset
21163
21164 -debug option is specified the compiler generates extra symbol information
21165  some of which are put into the assembler source and some are put into the
21166  .adb file.
21167  Then the linker creates the .cdb file from the individual .adb files with
21168  the address information for the symbols.
21169  The debugger reads the symbolic information generated by the compiler &
21170  the address information generated by the linker.
21171  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
21172  execution is controlled by the debugger.
21173  When a command is issued for the debugger, it translates it into appropriate
21174  commands for the simulator.
21175  (Currently sdcdb only connects to the simulator but
21176 \emph on
21177 newcdb
21178 \emph default
21179  at
21180 \begin_inset LatexCommand \url{http://ec2drv.sf.net/}
21181
21182 \end_inset
21183
21184  is an effort to connect directly to the hardware.)
21185 \layout Subsection
21186
21187 Starting the Debugger SDCDB
21188 \layout Standard
21189
21190 The debugger can be started using the following command line.
21191  (Assume the file you are debugging has the file name foo).
21192 \newline
21193
21194 \newline
21195
21196 \family sans
21197 \series bold
21198 sdcdb foo
21199 \newline
21200
21201 \family default
21202 \series default
21203
21204 \newline
21205 The debugger will look for the following files.
21206 \layout Itemize
21207
21208 foo.c - the source file.
21209 \layout Itemize
21210
21211 foo.cdb - the debugger symbol information file.
21212 \layout Itemize
21213
21214 foo.ihx - the Intel hex format
21215 \begin_inset LatexCommand \index{Intel hex format}
21216
21217 \end_inset
21218
21219  object file.
21220 \layout Subsection
21221
21222 SDCDB Command Line Options
21223 \layout Itemize
21224
21225 -
21226 \begin_inset ERT
21227 status Collapsed
21228
21229 \layout Standard
21230
21231 \backslash
21232 /
21233 \end_inset
21234
21235 -directory=<source file directory> this option can used to specify the directory
21236  search list.
21237  The debugger will look into the directory list specified for source, cdb
21238  & ihx files.
21239  The items in the directory list must be separated by ':', e.g.
21240  if the source files can be in the directories /home/src1 and /home/src2,
21241  the -
21242 \begin_inset ERT
21243 status Collapsed
21244
21245 \layout Standard
21246
21247 \backslash
21248 /
21249 \end_inset
21250
21251 -directory option should be -
21252 \begin_inset ERT
21253 status Collapsed
21254
21255 \layout Standard
21256
21257 \backslash
21258 /
21259 \end_inset
21260
21261 -directory=/home/src1:/home/src2.
21262  Note there can be no spaces in the option.
21263
21264 \layout Itemize
21265
21266 -cd <directory> - change to the <directory>.
21267 \layout Itemize
21268
21269 -fullname - used by GUI front ends.
21270 \layout Itemize
21271
21272 -cpu <cpu-type> - this argument is passed to the simulator please see the
21273  simulator docs for details.
21274 \layout Itemize
21275
21276 -X <Clock frequency > this options is passed to the simulator please see
21277  the simulator docs for details.
21278 \layout Itemize
21279
21280 -s <serial port file> passed to simulator see the simulator docs for details.
21281 \layout Itemize
21282
21283 -S <serial in,out> passed to simulator see the simulator docs for details.
21284 \layout Itemize
21285
21286 -k <port number> passed to simulator see the simulator docs for details.
21287 \layout Subsection
21288
21289 SDCDB Debugger Commands
21290 \layout Standard
21291
21292 As mentioned earlier the command interface for the debugger has been deliberatel
21293 y kept as close the GNU debugger gdb, as possible.
21294  This will help the integration with existing graphical user interfaces
21295  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
21296  If you use a graphical user interface for the debugger you can skip this
21297  section.
21298 \layout Subsubsection*
21299
21300 break [line | file:line | function | file:function]
21301 \layout Standard
21302
21303 Set breakpoint at specified line or function:
21304 \newline
21305
21306 \newline
21307
21308 \family sans
21309 \series bold
21310 sdcdb>break 100
21311 \newline
21312 sdcdb>break foo.c:100
21313 \newline
21314 sdcdb>break funcfoo
21315 \newline
21316 sdcdb>break foo.c:funcfoo
21317 \layout Subsubsection*
21318
21319 clear [line | file:line | function | file:function ]
21320 \layout Standard
21321
21322 Clear breakpoint at specified line or function:
21323 \newline
21324
21325 \newline
21326
21327 \family sans
21328 \series bold
21329 sdcdb>clear 100
21330 \newline
21331 sdcdb>clear foo.c:100
21332 \newline
21333 sdcdb>clear funcfoo
21334 \newline
21335 sdcdb>clear foo.c:funcfoo
21336 \layout Subsubsection*
21337
21338 continue
21339 \layout Standard
21340
21341 Continue program being debugged, after breakpoint.
21342 \layout Subsubsection*
21343
21344 finish
21345 \layout Standard
21346
21347 Execute till the end of the current function.
21348 \layout Subsubsection*
21349
21350 delete [n]
21351 \layout Standard
21352
21353 Delete breakpoint number 'n'.
21354  If used without any option clear ALL user defined break points.
21355 \layout Subsubsection*
21356
21357 info [break | stack | frame | registers ]
21358 \layout Itemize
21359
21360 info break - list all breakpoints
21361 \layout Itemize
21362
21363 info stack - show the function call stack.
21364 \layout Itemize
21365
21366 info frame - show information about the current execution frame.
21367 \layout Itemize
21368
21369 info registers - show content of all registers.
21370 \layout Subsubsection*
21371
21372 step
21373 \layout Standard
21374
21375 Step program until it reaches a different source line.
21376  Note: pressing <return> repeats the last command.
21377 \layout Subsubsection*
21378
21379 next
21380 \layout Standard
21381
21382 Step program, proceeding through subroutine calls.
21383 \layout Subsubsection*
21384
21385 run
21386 \layout Standard
21387
21388 Start debugged program.
21389 \layout Subsubsection*
21390
21391 ptype variable
21392 \layout Standard
21393
21394 Print type information of the variable.
21395 \layout Subsubsection*
21396
21397 print variable
21398 \layout Standard
21399
21400 print value of variable.
21401 \layout Subsubsection*
21402
21403 file filename
21404 \layout Standard
21405
21406 load the given file name.
21407  Note this is an alternate method of loading file for debugging.
21408 \layout Subsubsection*
21409
21410 frame
21411 \layout Standard
21412
21413 print information about current frame.
21414 \layout Subsubsection*
21415
21416 set srcmode
21417 \layout Standard
21418
21419 Toggle between C source & assembly source.
21420 \layout Subsubsection*
21421
21422 ! simulator command
21423 \layout Standard
21424
21425 Send the string following '!' to the simulator, the simulator response is
21426  displayed.
21427  Note the debugger does not interpret the command being sent to the simulator,
21428  so if a command like 'go' is sent the debugger can loose its execution
21429  context and may display incorrect values.
21430 \layout Subsubsection*
21431
21432 quit
21433 \layout Standard
21434
21435 "Watch me now.
21436  Iam going Down.
21437  My name is Bobby Brown"
21438 \layout Subsection
21439
21440 Interfacing SDCDB with DDD
21441 \layout Comment
21442
21443 The screenshot was converted from png to eps with:
21444 \begin_inset Quotes sld
21445 \end_inset
21446
21447 bmeps -c -e8f -p3 ddd_example.png >ddd_example.eps
21448 \begin_inset Quotes srd
21449 \end_inset
21450
21451  which produces a pretty compact eps file which is free from compression
21452  artifacts.
21453 \layout Comment
21454
21455 The screenshot was included in sdccman.lyx cvs version 1.120 but later removed
21456  as this broke the build system on Sourceforge (pdf-file was broken).
21457 \layout Standard
21458
21459 The .eps File
21460 \size footnotesize
21461
21462 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/doc/figures/ddd_example.eps}
21463
21464 \end_inset
21465
21466
21467 \size default
21468  shows a screenshot of a debugging session with DDD
21469 \begin_inset LatexCommand \index{DDD (debugger)}
21470
21471 \end_inset
21472
21473  (Unix only) on a simulated 8032.
21474  The debugging session might not run as smoothly as the screenshot suggests.
21475  The debugger allows setting of breakpoints, displaying and changing variables,
21476  single stepping through C and assembler code.
21477
21478 \newline
21479 The source was compiled with
21480 \family sans
21481 \series bold
21482
21483 \newline
21484
21485 \newline
21486 sdcc -
21487 \family default
21488 \series default
21489
21490 \begin_inset ERT
21491 status Collapsed
21492
21493 \layout Standard
21494
21495 \backslash
21496 /
21497 \end_inset
21498
21499
21500 \family sans
21501 \series bold
21502 -debug ddd_example.c
21503 \family default
21504 \series default
21505
21506 \family sans
21507 \series bold
21508
21509 \newline
21510
21511 \family default
21512 \series default
21513
21514 \newline
21515 and DDD was invoked with
21516 \family sans
21517 \series bold
21518
21519 \newline
21520
21521 \newline
21522 ddd -debugger 'sdcdb -cpu 8032 ddd_example'
21523 \layout Subsection
21524
21525 Interfacing SDCDB with XEmacs
21526 \begin_inset LatexCommand \index{XEmacs}
21527
21528 \end_inset
21529
21530
21531 \begin_inset LatexCommand \index{Emacs}
21532
21533 \end_inset
21534
21535
21536 \layout Standard
21537
21538 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
21539  sdcdb.el and sdcdbsrc.el.
21540  These two files can be found in the $(prefix)/bin directory after the installat
21541 ion is complete.
21542  These files need to be loaded into XEmacs for the interface to work.
21543  This can be done at XEmacs startup time by inserting the following into
21544  your '.xemacs' file (which can be found in your HOME directory):
21545 \newline
21546
21547 \newline
21548
21549 \family typewriter
21550 (load-file sdcdbsrc.el)
21551 \family default
21552
21553 \newline
21554
21555 \newline
21556 .xemacs is a lisp file so the () around the command is REQUIRED.
21557  The files can also be loaded dynamically while XEmacs is running, set the
21558  environment variable 'EMACSLOADPATH' to the installation bin directory
21559  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
21560  To start the interface enter the following command:
21561 \newline
21562
21563 \newline
21564
21565 \family sans
21566 \series bold
21567 ESC-x sdcdbsrc
21568 \family default
21569 \series default
21570
21571 \newline
21572
21573 \newline
21574 You will prompted to enter the file name to be debugged.
21575
21576 \newline
21577
21578 \newline
21579 The command line options that are passed to the simulator directly are bound
21580  to default values in the file sdcdbsrc.el.
21581  The variables are listed below, these values maybe changed as required.
21582 \layout Itemize
21583
21584 sdcdbsrc-cpu-type '51
21585 \layout Itemize
21586
21587 sdcdbsrc-frequency '11059200
21588 \layout Itemize
21589
21590 sdcdbsrc-serial nil
21591 \layout Standard
21592
21593 The following is a list of key mapping for the debugger interface.
21594 \layout Standard
21595
21596 \SpecialChar ~
21597
21598 \family typewriter
21599
21600 \newline
21601 ;;\SpecialChar ~
21602 Current Listing ::
21603 \newline
21604 ;;key\SpecialChar ~
21605 \SpecialChar ~
21606 \SpecialChar ~
21607 \SpecialChar ~
21608 \SpecialChar ~
21609 \SpecialChar ~
21610 \SpecialChar ~
21611 \SpecialChar ~
21612 \SpecialChar ~
21613 \SpecialChar ~
21614 \SpecialChar ~
21615 \SpecialChar ~
21616 \SpecialChar ~
21617 \SpecialChar ~
21618 binding\SpecialChar ~
21619 \SpecialChar ~
21620 \SpecialChar ~
21621 \SpecialChar ~
21622 \SpecialChar ~
21623 \SpecialChar ~
21624 \SpecialChar ~
21625 \SpecialChar ~
21626 \SpecialChar ~
21627 \SpecialChar ~
21628 \SpecialChar ~
21629 \SpecialChar ~
21630 \SpecialChar ~
21631 \SpecialChar ~
21632 \SpecialChar ~
21633 \SpecialChar ~
21634 \SpecialChar ~
21635 \SpecialChar ~
21636 \SpecialChar ~
21637 \SpecialChar ~
21638 \SpecialChar ~
21639 \SpecialChar ~
21640 Comment
21641 \newline
21642 ;;---\SpecialChar ~
21643 \SpecialChar ~
21644 \SpecialChar ~
21645 \SpecialChar ~
21646 \SpecialChar ~
21647 \SpecialChar ~
21648 \SpecialChar ~
21649 \SpecialChar ~
21650 \SpecialChar ~
21651 \SpecialChar ~
21652 \SpecialChar ~
21653 \SpecialChar ~
21654 \SpecialChar ~
21655 \SpecialChar ~
21656 -------\SpecialChar ~
21657 \SpecialChar ~
21658 \SpecialChar ~
21659 \SpecialChar ~
21660 \SpecialChar ~
21661 \SpecialChar ~
21662 \SpecialChar ~
21663 \SpecialChar ~
21664 \SpecialChar ~
21665 \SpecialChar ~
21666 \SpecialChar ~
21667 \SpecialChar ~
21668 \SpecialChar ~
21669 \SpecialChar ~
21670 \SpecialChar ~
21671 \SpecialChar ~
21672 \SpecialChar ~
21673 \SpecialChar ~
21674 \SpecialChar ~
21675 \SpecialChar ~
21676 \SpecialChar ~
21677 \SpecialChar ~
21678 -------
21679 \newline
21680 ;;
21681 \newline
21682 ;;\SpecialChar ~
21683 n\SpecialChar ~
21684 \SpecialChar ~
21685 \SpecialChar ~
21686 \SpecialChar ~
21687 \SpecialChar ~
21688 \SpecialChar ~
21689 \SpecialChar ~
21690 \SpecialChar ~
21691 \SpecialChar ~
21692 \SpecialChar ~
21693 \SpecialChar ~
21694 \SpecialChar ~
21695 \SpecialChar ~
21696 \SpecialChar ~
21697 \SpecialChar ~
21698 sdcdb-next-from-src\SpecialChar ~
21699 \SpecialChar ~
21700 \SpecialChar ~
21701 \SpecialChar ~
21702 \SpecialChar ~
21703 \SpecialChar ~
21704 \SpecialChar ~
21705 \SpecialChar ~
21706 \SpecialChar ~
21707 \SpecialChar ~
21708 SDCDB next command
21709 \newline
21710 ;;\SpecialChar ~
21711 b\SpecialChar ~
21712 \SpecialChar ~
21713 \SpecialChar ~
21714 \SpecialChar ~
21715 \SpecialChar ~
21716 \SpecialChar ~
21717 \SpecialChar ~
21718 \SpecialChar ~
21719 \SpecialChar ~
21720 \SpecialChar ~
21721 \SpecialChar ~
21722 \SpecialChar ~
21723 \SpecialChar ~
21724 \SpecialChar ~
21725 \SpecialChar ~
21726 sdcdb-back-from-src\SpecialChar ~
21727 \SpecialChar ~
21728 \SpecialChar ~
21729 \SpecialChar ~
21730 \SpecialChar ~
21731 \SpecialChar ~
21732 \SpecialChar ~
21733 \SpecialChar ~
21734 \SpecialChar ~
21735 \SpecialChar ~
21736 SDCDB back command
21737 \newline
21738 ;;\SpecialChar ~
21739 c\SpecialChar ~
21740 \SpecialChar ~
21741 \SpecialChar ~
21742 \SpecialChar ~
21743 \SpecialChar ~
21744 \SpecialChar ~
21745 \SpecialChar ~
21746 \SpecialChar ~
21747 \SpecialChar ~
21748 \SpecialChar ~
21749 \SpecialChar ~
21750 \SpecialChar ~
21751 \SpecialChar ~
21752 \SpecialChar ~
21753 \SpecialChar ~
21754 sdcdb-cont-from-src\SpecialChar ~
21755 \SpecialChar ~
21756 \SpecialChar ~
21757 \SpecialChar ~
21758 \SpecialChar ~
21759 \SpecialChar ~
21760 \SpecialChar ~
21761 \SpecialChar ~
21762 \SpecialChar ~
21763 \SpecialChar ~
21764 SDCDB continue command
21765 \newline
21766 ;;\SpecialChar ~
21767 s\SpecialChar ~
21768 \SpecialChar ~
21769 \SpecialChar ~
21770 \SpecialChar ~
21771 \SpecialChar ~
21772 \SpecialChar ~
21773 \SpecialChar ~
21774 \SpecialChar ~
21775 \SpecialChar ~
21776 \SpecialChar ~
21777 \SpecialChar ~
21778 \SpecialChar ~
21779 \SpecialChar ~
21780 \SpecialChar ~
21781 \SpecialChar ~
21782 sdcdb-step-from-src\SpecialChar ~
21783 \SpecialChar ~
21784 \SpecialChar ~
21785 \SpecialChar ~
21786 \SpecialChar ~
21787 \SpecialChar ~
21788 \SpecialChar ~
21789 \SpecialChar ~
21790 \SpecialChar ~
21791 \SpecialChar ~
21792 SDCDB step command
21793 \newline
21794 ;;\SpecialChar ~
21795 ?\SpecialChar ~
21796 \SpecialChar ~
21797 \SpecialChar ~
21798 \SpecialChar ~
21799 \SpecialChar ~
21800 \SpecialChar ~
21801 \SpecialChar ~
21802 \SpecialChar ~
21803 \SpecialChar ~
21804 \SpecialChar ~
21805 \SpecialChar ~
21806 \SpecialChar ~
21807 \SpecialChar ~
21808 \SpecialChar ~
21809 \SpecialChar ~
21810 sdcdb-whatis-c-sexp\SpecialChar ~
21811 \SpecialChar ~
21812 \SpecialChar ~
21813 \SpecialChar ~
21814 \SpecialChar ~
21815 \SpecialChar ~
21816 \SpecialChar ~
21817 \SpecialChar ~
21818 \SpecialChar ~
21819 \SpecialChar ~
21820 SDCDB ptypecommand for data at
21821 \newline
21822 ;;\SpecialChar ~
21823 \SpecialChar ~
21824 \SpecialChar ~
21825 \SpecialChar ~
21826 \SpecialChar ~
21827 \SpecialChar ~
21828 \SpecialChar ~
21829 \SpecialChar ~
21830 \SpecialChar ~
21831 \SpecialChar ~
21832 \SpecialChar ~
21833 \SpecialChar ~
21834 \SpecialChar ~
21835 \SpecialChar ~
21836 \SpecialChar ~
21837 \SpecialChar ~
21838 \SpecialChar ~
21839 \SpecialChar ~
21840 \SpecialChar ~
21841 \SpecialChar ~
21842 \SpecialChar ~
21843 \SpecialChar ~
21844 \SpecialChar ~
21845 \SpecialChar ~
21846 \SpecialChar ~
21847 \SpecialChar ~
21848 \SpecialChar ~
21849 \SpecialChar ~
21850 \SpecialChar ~
21851 \SpecialChar ~
21852 \SpecialChar ~
21853 \SpecialChar ~
21854 \SpecialChar ~
21855 \SpecialChar ~
21856 \SpecialChar ~
21857 \SpecialChar ~
21858 \SpecialChar ~
21859 \SpecialChar ~
21860 \SpecialChar ~
21861 \SpecialChar ~
21862 \SpecialChar ~
21863 \SpecialChar ~
21864 \SpecialChar ~
21865 \SpecialChar ~
21866 \SpecialChar ~
21867 \SpecialChar ~
21868 \SpecialChar ~
21869 buffer point
21870 \newline
21871 ;;\SpecialChar ~
21872 x\SpecialChar ~
21873 \SpecialChar ~
21874 \SpecialChar ~
21875 \SpecialChar ~
21876 \SpecialChar ~
21877 \SpecialChar ~
21878 \SpecialChar ~
21879 \SpecialChar ~
21880 \SpecialChar ~
21881 \SpecialChar ~
21882 \SpecialChar ~
21883 \SpecialChar ~
21884 \SpecialChar ~
21885 \SpecialChar ~
21886 \SpecialChar ~
21887 sdcdbsrc-delete\SpecialChar ~
21888 \SpecialChar ~
21889 \SpecialChar ~
21890 \SpecialChar ~
21891 \SpecialChar ~
21892 \SpecialChar ~
21893 \SpecialChar ~
21894 \SpecialChar ~
21895 \SpecialChar ~
21896 \SpecialChar ~
21897 \SpecialChar ~
21898 \SpecialChar ~
21899 \SpecialChar ~
21900 \SpecialChar ~
21901 SDCDB Delete all breakpoints if no arg
21902 \newline
21903 ;;\SpecialChar ~
21904 \SpecialChar ~
21905 \SpecialChar ~
21906 \SpecialChar ~
21907 \SpecialChar ~
21908 \SpecialChar ~
21909 \SpecialChar ~
21910 \SpecialChar ~
21911 \SpecialChar ~
21912 \SpecialChar ~
21913 \SpecialChar ~
21914 \SpecialChar ~
21915 \SpecialChar ~
21916 \SpecialChar ~
21917 \SpecialChar ~
21918 \SpecialChar ~
21919 \SpecialChar ~
21920 \SpecialChar ~
21921 \SpecialChar ~
21922 \SpecialChar ~
21923 \SpecialChar ~
21924 \SpecialChar ~
21925 \SpecialChar ~
21926 \SpecialChar ~
21927 \SpecialChar ~
21928 \SpecialChar ~
21929 \SpecialChar ~
21930 \SpecialChar ~
21931 \SpecialChar ~
21932 \SpecialChar ~
21933 \SpecialChar ~
21934 \SpecialChar ~
21935 \SpecialChar ~
21936 \SpecialChar ~
21937 \SpecialChar ~
21938 \SpecialChar ~
21939 \SpecialChar ~
21940 \SpecialChar ~
21941 \SpecialChar ~
21942 \SpecialChar ~
21943 \SpecialChar ~
21944 \SpecialChar ~
21945 \SpecialChar ~
21946 \SpecialChar ~
21947 \SpecialChar ~
21948 \SpecialChar ~
21949 \SpecialChar ~
21950 given or delete arg (C-u arg x)
21951 \newline
21952 ;;\SpecialChar ~
21953 m\SpecialChar ~
21954 \SpecialChar ~
21955 \SpecialChar ~
21956 \SpecialChar ~
21957 \SpecialChar ~
21958 \SpecialChar ~
21959 \SpecialChar ~
21960 \SpecialChar ~
21961 \SpecialChar ~
21962 \SpecialChar ~
21963 \SpecialChar ~
21964 \SpecialChar ~
21965 \SpecialChar ~
21966 \SpecialChar ~
21967 \SpecialChar ~
21968 sdcdbsrc-frame\SpecialChar ~
21969 \SpecialChar ~
21970 \SpecialChar ~
21971 \SpecialChar ~
21972 \SpecialChar ~
21973 \SpecialChar ~
21974 \SpecialChar ~
21975 \SpecialChar ~
21976 \SpecialChar ~
21977 \SpecialChar ~
21978 \SpecialChar ~
21979 \SpecialChar ~
21980 \SpecialChar ~
21981 \SpecialChar ~
21982 \SpecialChar ~
21983 SDCDB Display current frame if no arg,
21984 \newline
21985 ;;\SpecialChar ~
21986 \SpecialChar ~
21987 \SpecialChar ~
21988 \SpecialChar ~
21989 \SpecialChar ~
21990 \SpecialChar ~
21991 \SpecialChar ~
21992 \SpecialChar ~
21993 \SpecialChar ~
21994 \SpecialChar ~
21995 \SpecialChar ~
21996 \SpecialChar ~
21997 \SpecialChar ~
21998 \SpecialChar ~
21999 \SpecialChar ~
22000 \SpecialChar ~
22001 \SpecialChar ~
22002 \SpecialChar ~
22003 \SpecialChar ~
22004 \SpecialChar ~
22005 \SpecialChar ~
22006 \SpecialChar ~
22007 \SpecialChar ~
22008 \SpecialChar ~
22009 \SpecialChar ~
22010 \SpecialChar ~
22011 \SpecialChar ~
22012 \SpecialChar ~
22013 \SpecialChar ~
22014 \SpecialChar ~
22015 \SpecialChar ~
22016 \SpecialChar ~
22017 \SpecialChar ~
22018 \SpecialChar ~
22019 \SpecialChar ~
22020 \SpecialChar ~
22021 \SpecialChar ~
22022 \SpecialChar ~
22023 \SpecialChar ~
22024 \SpecialChar ~
22025 \SpecialChar ~
22026 \SpecialChar ~
22027 \SpecialChar ~
22028 \SpecialChar ~
22029 \SpecialChar ~
22030 \SpecialChar ~
22031 \SpecialChar ~
22032 given or display frame arg
22033 \newline
22034 ;;\SpecialChar ~
22035 \SpecialChar ~
22036 \SpecialChar ~
22037 \SpecialChar ~
22038 \SpecialChar ~
22039 \SpecialChar ~
22040 \SpecialChar ~
22041 \SpecialChar ~
22042 \SpecialChar ~
22043 \SpecialChar ~
22044 \SpecialChar ~
22045 \SpecialChar ~
22046 \SpecialChar ~
22047 \SpecialChar ~
22048 \SpecialChar ~
22049 \SpecialChar ~
22050 \SpecialChar ~
22051 \SpecialChar ~
22052 \SpecialChar ~
22053 \SpecialChar ~
22054 \SpecialChar ~
22055 \SpecialChar ~
22056 \SpecialChar ~
22057 \SpecialChar ~
22058 \SpecialChar ~
22059 \SpecialChar ~
22060 \SpecialChar ~
22061 \SpecialChar ~
22062 \SpecialChar ~
22063 \SpecialChar ~
22064 \SpecialChar ~
22065 \SpecialChar ~
22066 \SpecialChar ~
22067 \SpecialChar ~
22068 \SpecialChar ~
22069 \SpecialChar ~
22070 \SpecialChar ~
22071 \SpecialChar ~
22072 \SpecialChar ~
22073 \SpecialChar ~
22074 \SpecialChar ~
22075 \SpecialChar ~
22076 \SpecialChar ~
22077 \SpecialChar ~
22078 \SpecialChar ~
22079 \SpecialChar ~
22080 \SpecialChar ~
22081 buffer point
22082 \newline
22083 ;;\SpecialChar ~
22084 !\SpecialChar ~
22085 \SpecialChar ~
22086 \SpecialChar ~
22087 \SpecialChar ~
22088 \SpecialChar ~
22089 \SpecialChar ~
22090 \SpecialChar ~
22091 \SpecialChar ~
22092 \SpecialChar ~
22093 \SpecialChar ~
22094 \SpecialChar ~
22095 \SpecialChar ~
22096 \SpecialChar ~
22097 \SpecialChar ~
22098 \SpecialChar ~
22099 sdcdbsrc-goto-sdcdb\SpecialChar ~
22100 \SpecialChar ~
22101 \SpecialChar ~
22102 \SpecialChar ~
22103 \SpecialChar ~
22104 \SpecialChar ~
22105 \SpecialChar ~
22106 \SpecialChar ~
22107 \SpecialChar ~
22108 \SpecialChar ~
22109 Goto the SDCDB output buffer
22110 \newline
22111 ;;\SpecialChar ~
22112 p\SpecialChar ~
22113 \SpecialChar ~
22114 \SpecialChar ~
22115 \SpecialChar ~
22116 \SpecialChar ~
22117 \SpecialChar ~
22118 \SpecialChar ~
22119 \SpecialChar ~
22120 \SpecialChar ~
22121 \SpecialChar ~
22122 \SpecialChar ~
22123 \SpecialChar ~
22124 \SpecialChar ~
22125 \SpecialChar ~
22126 \SpecialChar ~
22127 sdcdb-print-c-sexp\SpecialChar ~
22128 \SpecialChar ~
22129 \SpecialChar ~
22130 \SpecialChar ~
22131 \SpecialChar ~
22132 \SpecialChar ~
22133 \SpecialChar ~
22134 \SpecialChar ~
22135 \SpecialChar ~
22136 \SpecialChar ~
22137 \SpecialChar ~
22138 SDCDB print command for data at
22139 \newline
22140 ;;\SpecialChar ~
22141 \SpecialChar ~
22142 \SpecialChar ~
22143 \SpecialChar ~
22144 \SpecialChar ~
22145 \SpecialChar ~
22146 \SpecialChar ~
22147 \SpecialChar ~
22148 \SpecialChar ~
22149 \SpecialChar ~
22150 \SpecialChar ~
22151 \SpecialChar ~
22152 \SpecialChar ~
22153 \SpecialChar ~
22154 \SpecialChar ~
22155 \SpecialChar ~
22156 \SpecialChar ~
22157 \SpecialChar ~
22158 \SpecialChar ~
22159 \SpecialChar ~
22160 \SpecialChar ~
22161 \SpecialChar ~
22162 \SpecialChar ~
22163 \SpecialChar ~
22164 \SpecialChar ~
22165 \SpecialChar ~
22166 \SpecialChar ~
22167 \SpecialChar ~
22168 \SpecialChar ~
22169 \SpecialChar ~
22170 \SpecialChar ~
22171 \SpecialChar ~
22172 \SpecialChar ~
22173 \SpecialChar ~
22174 \SpecialChar ~
22175 \SpecialChar ~
22176 \SpecialChar ~
22177 \SpecialChar ~
22178 \SpecialChar ~
22179 \SpecialChar ~
22180 \SpecialChar ~
22181 \SpecialChar ~
22182 \SpecialChar ~
22183 \SpecialChar ~
22184 \SpecialChar ~
22185 \SpecialChar ~
22186 \SpecialChar ~
22187 buffer point
22188 \newline
22189 ;;\SpecialChar ~
22190 g\SpecialChar ~
22191 \SpecialChar ~
22192 \SpecialChar ~
22193 \SpecialChar ~
22194 \SpecialChar ~
22195 \SpecialChar ~
22196 \SpecialChar ~
22197 \SpecialChar ~
22198 \SpecialChar ~
22199 \SpecialChar ~
22200 \SpecialChar ~
22201 \SpecialChar ~
22202 \SpecialChar ~
22203 \SpecialChar ~
22204 \SpecialChar ~
22205 sdcdbsrc-goto-sdcdb\SpecialChar ~
22206 \SpecialChar ~
22207 \SpecialChar ~
22208 \SpecialChar ~
22209 \SpecialChar ~
22210 \SpecialChar ~
22211 \SpecialChar ~
22212 \SpecialChar ~
22213 \SpecialChar ~
22214 \SpecialChar ~
22215 Goto the SDCDB output buffer
22216 \newline
22217 ;;\SpecialChar ~
22218 t\SpecialChar ~
22219 \SpecialChar ~
22220 \SpecialChar ~
22221 \SpecialChar ~
22222 \SpecialChar ~
22223 \SpecialChar ~
22224 \SpecialChar ~
22225 \SpecialChar ~
22226 \SpecialChar ~
22227 \SpecialChar ~
22228 \SpecialChar ~
22229 \SpecialChar ~
22230 \SpecialChar ~
22231 \SpecialChar ~
22232 \SpecialChar ~
22233 sdcdbsrc-mode\SpecialChar ~
22234 \SpecialChar ~
22235 \SpecialChar ~
22236 \SpecialChar ~
22237 \SpecialChar ~
22238 \SpecialChar ~
22239 \SpecialChar ~
22240 \SpecialChar ~
22241 \SpecialChar ~
22242 \SpecialChar ~
22243 \SpecialChar ~
22244 \SpecialChar ~
22245 \SpecialChar ~
22246 \SpecialChar ~
22247 \SpecialChar ~
22248 \SpecialChar ~
22249 Toggles Sdcdbsrc mode (turns it off)
22250 \newline
22251 ;;
22252 \newline
22253 ;;\SpecialChar ~
22254 C-c\SpecialChar ~
22255 C-f\SpecialChar ~
22256 \SpecialChar ~
22257 \SpecialChar ~
22258 \SpecialChar ~
22259 \SpecialChar ~
22260 \SpecialChar ~
22261 \SpecialChar ~
22262 \SpecialChar ~
22263 \SpecialChar ~
22264 sdcdb-finish-from-src\SpecialChar ~
22265 \SpecialChar ~
22266 \SpecialChar ~
22267 \SpecialChar ~
22268 \SpecialChar ~
22269 \SpecialChar ~
22270 \SpecialChar ~
22271 \SpecialChar ~
22272 SDCDB finish command
22273 \newline
22274 ;;
22275 \newline
22276 ;;\SpecialChar ~
22277 C-x\SpecialChar ~
22278 SPC\SpecialChar ~
22279 \SpecialChar ~
22280 \SpecialChar ~
22281 \SpecialChar ~
22282 \SpecialChar ~
22283 \SpecialChar ~
22284 \SpecialChar ~
22285 \SpecialChar ~
22286 \SpecialChar ~
22287 sdcdb-break\SpecialChar ~
22288 \SpecialChar ~
22289 \SpecialChar ~
22290 \SpecialChar ~
22291 \SpecialChar ~
22292 \SpecialChar ~
22293 \SpecialChar ~
22294 \SpecialChar ~
22295 \SpecialChar ~
22296 \SpecialChar ~
22297 \SpecialChar ~
22298 \SpecialChar ~
22299 \SpecialChar ~
22300 \SpecialChar ~
22301 \SpecialChar ~
22302 \SpecialChar ~
22303 \SpecialChar ~
22304 \SpecialChar ~
22305 Set break for line with point
22306 \newline
22307 ;;\SpecialChar ~
22308 ESC\SpecialChar ~
22309 t\SpecialChar ~
22310 \SpecialChar ~
22311 \SpecialChar ~
22312 \SpecialChar ~
22313 \SpecialChar ~
22314 \SpecialChar ~
22315 \SpecialChar ~
22316 \SpecialChar ~
22317 \SpecialChar ~
22318 \SpecialChar ~
22319 \SpecialChar ~
22320 sdcdbsrc-mode\SpecialChar ~
22321 \SpecialChar ~
22322 \SpecialChar ~
22323 \SpecialChar ~
22324 \SpecialChar ~
22325 \SpecialChar ~
22326 \SpecialChar ~
22327 \SpecialChar ~
22328 \SpecialChar ~
22329 \SpecialChar ~
22330 \SpecialChar ~
22331 \SpecialChar ~
22332 \SpecialChar ~
22333 \SpecialChar ~
22334 \SpecialChar ~
22335 \SpecialChar ~
22336 Toggle Sdcdbsrc mode
22337 \newline
22338 ;;\SpecialChar ~
22339 ESC\SpecialChar ~
22340 m\SpecialChar ~
22341 \SpecialChar ~
22342 \SpecialChar ~
22343 \SpecialChar ~
22344 \SpecialChar ~
22345 \SpecialChar ~
22346 \SpecialChar ~
22347 \SpecialChar ~
22348 \SpecialChar ~
22349 \SpecialChar ~
22350 \SpecialChar ~
22351 sdcdbsrc-srcmode\SpecialChar ~
22352 \SpecialChar ~
22353 \SpecialChar ~
22354 \SpecialChar ~
22355 \SpecialChar ~
22356 \SpecialChar ~
22357 \SpecialChar ~
22358 \SpecialChar ~
22359 \SpecialChar ~
22360 \SpecialChar ~
22361 \SpecialChar ~
22362 \SpecialChar ~
22363 \SpecialChar ~
22364 Toggle list mode
22365 \newline
22366 ;;
22367 \newline
22368
22369 \layout Chapter
22370 \pagebreak_top
22371 TIPS
22372 \layout Standard
22373
22374 Here are a few guidelines that will help the compiler generate more efficient
22375  code, some of the tips are specific to this compiler others are generally
22376  good programming practice.
22377 \layout Itemize
22378
22379 Use the smallest data type to represent your data-value.
22380  If it is known in advance that the value is going to be less than 256 then
22381  use an 'unsigned char' instead of a 'short' or 'int'.
22382  Please note, that ANSI C requires both signed and unsigned chars to be
22383  promoted to 'signed int'
22384 \begin_inset LatexCommand \index{promotion to signed int}
22385
22386 \end_inset
22387
22388  before doing any operation.
22389  This promotion
22390 \begin_inset LatexCommand \index{type promotion}
22391
22392 \end_inset
22393
22394
22395 \begin_inset LatexCommand \label{type promotion}
22396
22397 \end_inset
22398
22399  can be omitted, if the result is the same.
22400  The effect of the promotion rules together with the sign-extension is often
22401  surprising:
22402 \begin_deeper
22403 \layout Verse
22404
22405
22406 \family typewriter
22407 unsigned char uc = 0xfe;
22408 \newline
22409 if (uc * uc < 0) /* this is true! */
22410 \newline
22411 {
22412 \newline
22413 \SpecialChar ~
22414 \SpecialChar ~
22415 \SpecialChar ~
22416 \SpecialChar ~
22417 ....
22418 \newline
22419 }
22420 \layout Standard
22421
22422
22423 \family typewriter
22424 uc * uc
22425 \family default
22426  is evaluated as
22427 \family typewriter
22428 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
22429 \family default
22430 .
22431
22432 \newline
22433 Another one:
22434 \layout Verse
22435
22436
22437 \family typewriter
22438 (unsigned char) -12 / (signed char) -3 = ...
22439 \layout Standard
22440
22441 No, the result is not 4:
22442 \layout Verse
22443
22444
22445 \family typewriter
22446 (int) (unsigned char) -12 / (int) (signed char) -3 =
22447 \newline
22448 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
22449 \newline
22450 (int) 0x00f4 / (int) 0xfffd =
22451 \newline
22452 (int) 0x00f4 / (int) 0xfffd =
22453 \newline
22454 (int) 244 / (int) -3 =
22455 \newline
22456 (int) -81 = (int) 0xffaf;
22457 \layout Standard
22458
22459 Don't complain, that gcc gives you a different result.
22460  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
22461  Therefore the results are different.
22462 \newline
22463 From
22464 \begin_inset Quotes sld
22465 \end_inset
22466
22467 comp.lang.c FAQ
22468 \begin_inset Quotes srd
22469 \end_inset
22470
22471 :
22472 \layout Quote
22473
22474 If well-defined overflow characteristics are important and negative values
22475  are not, or if you want to steer clear of sign-extension problems when
22476  manipulating bits or bytes, use one of the corresponding unsigned types.
22477  (Beware when mixing signed and unsigned values in expressions, though.)
22478 \newline
22479 Although character types (especially unsigned char) can be used as "tiny"
22480  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
22481 ble sign extension and increased code size.
22482 \end_deeper
22483 \layout Itemize
22484
22485 Use unsigned when it is known in advance that the value is not going to
22486  be negative.
22487  This helps especially if you are doing division or multiplication, bit-shifting
22488  or are using an array index.
22489 \layout Itemize
22490
22491 NEVER jump into a LOOP.
22492 \layout Itemize
22493
22494 Declare the variables to be local
22495 \begin_inset LatexCommand \index{local variables}
22496
22497 \end_inset
22498
22499  whenever possible, especially loop control variables (induction).
22500 \layout Itemize
22501
22502 Since the compiler does not always do implicit integral promotion, the programme
22503 r should do an explicit cast when integral promotion is required.
22504 \layout Itemize
22505
22506 Reducing the size of division, multiplication & modulus operations can reduce
22507  code size substantially.
22508  Take the following code for example.
22509 \begin_deeper
22510 \layout Verse
22511
22512
22513 \family typewriter
22514 foobar(unsigned int p1, unsigned char ch)
22515 \newline
22516 {
22517 \newline
22518 \SpecialChar ~
22519 \SpecialChar ~
22520 \SpecialChar ~
22521 \SpecialChar ~
22522 unsigned char ch1 = p1 % ch ;
22523 \newline
22524 \SpecialChar ~
22525 \SpecialChar ~
22526 \SpecialChar ~
22527 \SpecialChar ~
22528 ....
22529 \newline
22530 }
22531 \layout Standard
22532
22533 For the modulus operation the variable ch will be promoted to unsigned int
22534  first then the modulus operation will be performed (this will lead to a
22535  call to support routine _moduint()), and the result will be casted to a
22536  char.
22537  If the code is changed to
22538 \layout Verse
22539
22540
22541 \family typewriter
22542 foobar(unsigned int p1, unsigned char ch)
22543 \newline
22544 {
22545 \newline
22546 \SpecialChar ~
22547 \SpecialChar ~
22548 \SpecialChar ~
22549 \SpecialChar ~
22550 unsigned char ch1 = (unsigned char)p1 % ch ;
22551 \newline
22552 \SpecialChar ~
22553 \SpecialChar ~
22554 \SpecialChar ~
22555 \SpecialChar ~
22556 ....
22557 \newline
22558 }
22559 \layout Standard
22560
22561 It would substantially reduce the code generated (future versions of the
22562  compiler will be smart enough to detect such optimization opportunities).
22563 \end_deeper
22564 \layout Itemize
22565
22566 Have a look at the assembly listing to get a
22567 \begin_inset Quotes sld
22568 \end_inset
22569
22570 feeling
22571 \begin_inset Quotes srd
22572 \end_inset
22573
22574  for the code generation.
22575 \layout Section
22576
22577 Porting code from or to other compilers
22578 \layout Itemize
22579
22580 check whether endianness of the compilers differs and adapt where needed.
22581 \layout Itemize
22582
22583 check the device specific header files for compiler specific syntax.
22584  Eventually include the file <compiler.h
22585 \begin_inset LatexCommand \index{compiler.h (include file)}
22586
22587 \end_inset
22588
22589 > to allow using common header files.
22590 \layout Itemize
22591
22592 check whether the startup code contains the correct initialization (watchdog,
22593  peripherals).
22594 \layout Itemize
22595
22596 check whether the sizes of short, int, long match.
22597 \layout Itemize
22598
22599 check if some 16 or 32 bit hardware registers require a specific addressing
22600  order (least significant or most significant byte first) and adapt if needed
22601  (
22602 \emph on
22603 first
22604 \emph default
22605  and
22606 \emph on
22607 last
22608 \emph default
22609  relate to time and not to lower/upper memory location here, so this is
22610
22611 \emph on
22612 not
22613 \emph default
22614  the same as endianness).check whether the keyword
22615 \emph on
22616 volatile
22617 \emph default
22618  is used where needed.
22619  The compilers might differ in their optimization characteristics (as different
22620  versions of the same compiler might also use more clever optimizations
22621  this is good idea anyway).
22622 \layout Itemize
22623
22624 check that the compilers are not told to supress warnings.
22625 \layout Itemize
22626
22627 check and convert compiler specific extensions (interrupts, memory areas,
22628  pragmas etc.).
22629 \layout Itemize
22630
22631 check for differences in type promotion (especially check for math operations
22632  on char variables and for the use of the ~\SpecialChar ~
22633 operator on bit variables.
22634  See
22635 \begin_inset LatexCommand \ref{type promotion}
22636
22637 \end_inset
22638
22639  and
22640 \begin_inset LatexCommand \ref{sec:Compatibility-with-previous}
22641
22642 \end_inset
22643
22644 ).
22645 \layout Itemize
22646
22647 check the assembly code generated for interrupt routines (f.e.
22648  for calls to possibly non-reentrant library functions).
22649 \layout Itemize
22650
22651 check whether timing loops result in proper timing (or preferably consider
22652  a rewrite of the code with timer based delays instead).
22653 \layout Itemize
22654
22655 check for differences in printf parameters (some compilers push (va_arg)
22656  char variables as integers others as char).
22657 \layout Itemize
22658
22659 check the resulting memory layout.
22660 \layout Section
22661
22662 Tools
22663 \begin_inset LatexCommand \index{Tools}
22664
22665 \end_inset
22666
22667  included in the distribution
22668 \layout Standard
22669 \align center
22670
22671 \begin_inset  Tabular
22672 <lyxtabular version="3" rows="12" columns="3">
22673 <features>
22674 <column alignment="left" valignment="top" leftline="true" width="0pt">
22675 <column alignment="left" valignment="top" leftline="true" width="0pt">
22676 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
22677 <row topline="true" bottomline="true">
22678 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22679 \begin_inset Text
22680
22681 \layout Standard
22682
22683 Name
22684 \end_inset
22685 </cell>
22686 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22687 \begin_inset Text
22688
22689 \layout Standard
22690
22691 Purpose
22692 \end_inset
22693 </cell>
22694 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22695 \begin_inset Text
22696
22697 \layout Standard
22698
22699 Directory
22700 \end_inset
22701 </cell>
22702 </row>
22703 <row topline="true">
22704 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22705 \begin_inset Text
22706
22707 \layout Standard
22708
22709 uCsim
22710 \end_inset
22711 </cell>
22712 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22713 \begin_inset Text
22714
22715 \layout Standard
22716
22717 Simulator for various architectures
22718 \end_inset
22719 </cell>
22720 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22721 \begin_inset Text
22722
22723 \layout Standard
22724
22725 sdcc/sim/ucsim
22726 \end_inset
22727 </cell>
22728 </row>
22729 <row topline="true">
22730 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22731 \begin_inset Text
22732
22733 \layout Standard
22734
22735 keil2sdcc.pl
22736 \end_inset
22737 </cell>
22738 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22739 \begin_inset Text
22740
22741 \layout Standard
22742
22743 header file conversion
22744 \end_inset
22745 </cell>
22746 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22747 \begin_inset Text
22748
22749 \layout Standard
22750
22751 sdcc/support/scripts
22752 \end_inset
22753 </cell>
22754 </row>
22755 <row topline="true">
22756 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22757 \begin_inset Text
22758
22759 \layout Standard
22760
22761 mh2h.c
22762 \end_inset
22763 </cell>
22764 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22765 \begin_inset Text
22766
22767 \layout Standard
22768
22769 header file conversion
22770 \end_inset
22771 </cell>
22772 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22773 \begin_inset Text
22774
22775 \layout Standard
22776
22777 sdcc/support/scripts
22778 \end_inset
22779 </cell>
22780 </row>
22781 <row topline="true">
22782 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22783 \begin_inset Text
22784
22785 \layout Standard
22786
22787 as-gbz80
22788 \end_inset
22789 </cell>
22790 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22791 \begin_inset Text
22792
22793 \layout Standard
22794
22795 Assembler
22796 \end_inset
22797 </cell>
22798 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22799 \begin_inset Text
22800
22801 \layout Standard
22802
22803
22804 \family roman
22805 \series medium
22806 \shape up
22807 \size normal
22808 \emph off
22809 \bar no
22810 \noun off
22811 \color none
22812 sdcc/bin
22813 \end_inset
22814 </cell>
22815 </row>
22816 <row topline="true">
22817 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22818 \begin_inset Text
22819
22820 \layout Standard
22821
22822 as-z80
22823 \end_inset
22824 </cell>
22825 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22826 \begin_inset Text
22827
22828 \layout Standard
22829
22830 Assembler
22831 \end_inset
22832 </cell>
22833 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22834 \begin_inset Text
22835
22836 \layout Standard
22837
22838
22839 \family roman
22840 \series medium
22841 \shape up
22842 \size normal
22843 \emph off
22844 \bar no
22845 \noun off
22846 \color none
22847 sdcc/bin
22848 \end_inset
22849 </cell>
22850 </row>
22851 <row topline="true">
22852 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22853 \begin_inset Text
22854
22855 \layout Standard
22856
22857 asx8051
22858 \end_inset
22859 </cell>
22860 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22861 \begin_inset Text
22862
22863 \layout Standard
22864
22865 Assembler
22866 \end_inset
22867 </cell>
22868 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22869 \begin_inset Text
22870
22871 \layout Standard
22872
22873
22874 \family roman
22875 \series medium
22876 \shape up
22877 \size normal
22878 \emph off
22879 \bar no
22880 \noun off
22881 \color none
22882 sdcc/bin
22883 \end_inset
22884 </cell>
22885 </row>
22886 <row topline="true">
22887 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22888 \begin_inset Text
22889
22890 \layout Standard
22891
22892 sdcdb
22893 \end_inset
22894 </cell>
22895 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22896 \begin_inset Text
22897
22898 \layout Standard
22899
22900 Simulator
22901 \end_inset
22902 </cell>
22903 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22904 \begin_inset Text
22905
22906 \layout Standard
22907
22908
22909 \family roman
22910 \series medium
22911 \shape up
22912 \size normal
22913 \emph off
22914 \bar no
22915 \noun off
22916 \color none
22917 sdcc/bin
22918 \end_inset
22919 </cell>
22920 </row>
22921 <row topline="true">
22922 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22923 \begin_inset Text
22924
22925 \layout Standard
22926
22927 aslink
22928 \end_inset
22929 </cell>
22930 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22931 \begin_inset Text
22932
22933 \layout Standard
22934
22935 Linker
22936 \end_inset
22937 </cell>
22938 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22939 \begin_inset Text
22940
22941 \layout Standard
22942
22943
22944 \family roman
22945 \series medium
22946 \shape up
22947 \size normal
22948 \emph off
22949 \bar no
22950 \noun off
22951 \color none
22952 sdcc/bin
22953 \end_inset
22954 </cell>
22955 </row>
22956 <row topline="true">
22957 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22958 \begin_inset Text
22959
22960 \layout Standard
22961
22962 link-z80
22963 \end_inset
22964 </cell>
22965 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22966 \begin_inset Text
22967
22968 \layout Standard
22969
22970 Linker
22971 \end_inset
22972 </cell>
22973 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22974 \begin_inset Text
22975
22976 \layout Standard
22977
22978
22979 \family roman
22980 \series medium
22981 \shape up
22982 \size normal
22983 \emph off
22984 \bar no
22985 \noun off
22986 \color none
22987 sdcc/bin
22988 \end_inset
22989 </cell>
22990 </row>
22991 <row topline="true">
22992 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22993 \begin_inset Text
22994
22995 \layout Standard
22996
22997 link-gbz80
22998 \end_inset
22999 </cell>
23000 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23001 \begin_inset Text
23002
23003 \layout Standard
23004
23005 Linker
23006 \end_inset
23007 </cell>
23008 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23009 \begin_inset Text
23010
23011 \layout Standard
23012
23013
23014 \family roman
23015 \series medium
23016 \shape up
23017 \size normal
23018 \emph off
23019 \bar no
23020 \noun off
23021 \color none
23022 sdcc/bin
23023 \end_inset
23024 </cell>
23025 </row>
23026 <row topline="true" bottomline="true">
23027 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23028 \begin_inset Text
23029
23030 \layout Standard
23031
23032 packihx
23033 \end_inset
23034 </cell>
23035 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23036 \begin_inset Text
23037
23038 \layout Standard
23039
23040 ihx packer
23041 \end_inset
23042 </cell>
23043 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23044 \begin_inset Text
23045
23046 \layout Standard
23047
23048
23049 \family roman
23050 \series medium
23051 \shape up
23052 \size normal
23053 \emph off
23054 \bar no
23055 \noun off
23056 \color none
23057 sdcc/bin
23058 \end_inset
23059 </cell>
23060 </row>
23061 </lyxtabular>
23062
23063 \end_inset
23064
23065
23066 \newline
23067
23068 \layout Section
23069
23070 Documentation
23071 \begin_inset LatexCommand \index{Documentation}
23072
23073 \end_inset
23074
23075  included in the distribution
23076 \layout Standard
23077 \align center
23078
23079 \begin_inset  Tabular
23080 <lyxtabular version="3" rows="10" columns="2">
23081 <features>
23082 <column alignment="left" valignment="top" leftline="true" width="0">
23083 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
23084 <row topline="true" bottomline="true">
23085 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23086 \begin_inset Text
23087
23088 \layout Standard
23089
23090 Subject / Title
23091 \end_inset
23092 </cell>
23093 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23094 \begin_inset Text
23095
23096 \layout Standard
23097
23098 Where to get / filename
23099 \end_inset
23100 </cell>
23101 </row>
23102 <row topline="true">
23103 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23104 \begin_inset Text
23105
23106 \layout Standard
23107
23108 SDCC Compiler User Guide
23109 \end_inset
23110 </cell>
23111 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23112 \begin_inset Text
23113
23114 \layout Standard
23115
23116 You're reading it right now
23117 \end_inset
23118 </cell>
23119 </row>
23120 <row topline="true">
23121 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23122 \begin_inset Text
23123
23124 \layout Standard
23125
23126 Changelog of SDCC
23127 \end_inset
23128 </cell>
23129 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23130 \begin_inset Text
23131
23132 \layout Standard
23133
23134 sdcc/Changelog
23135 \end_inset
23136 </cell>
23137 </row>
23138 <row topline="true">
23139 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23140 \begin_inset Text
23141
23142 \layout Standard
23143
23144 ASXXXX
23145 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
23146
23147 \end_inset
23148
23149
23150 \begin_inset LatexCommand \index{Assembler documentation}
23151
23152 \end_inset
23153
23154  Assemblers and ASLINK
23155 \begin_inset LatexCommand \index{aslink}
23156
23157 \end_inset
23158
23159
23160 \begin_inset LatexCommand \index{Linker documentation}
23161
23162 \end_inset
23163
23164  Relocating Linker
23165 \end_inset
23166 </cell>
23167 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23168 \begin_inset Text
23169
23170 \layout Standard
23171
23172 sdcc/as/doc/asxhtm.html
23173 \end_inset
23174 </cell>
23175 </row>
23176 <row topline="true">
23177 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23178 \begin_inset Text
23179
23180 \layout Standard
23181
23182 SDCC regression test
23183 \begin_inset LatexCommand \index{Regression test}
23184
23185 \end_inset
23186
23187
23188 \end_inset
23189 </cell>
23190 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23191 \begin_inset Text
23192
23193 \layout Standard
23194
23195 sdcc/doc/test_suite_spec.pdf
23196 \end_inset
23197 </cell>
23198 </row>
23199 <row topline="true">
23200 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23201 \begin_inset Text
23202
23203 \layout Standard
23204
23205 Various notes
23206 \end_inset
23207 </cell>
23208 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23209 \begin_inset Text
23210
23211 \layout Standard
23212
23213 sdcc/doc/*
23214 \end_inset
23215 </cell>
23216 </row>
23217 <row topline="true">
23218 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23219 \begin_inset Text
23220
23221 \layout Standard
23222
23223 Notes on debugging with sdcdb
23224 \begin_inset LatexCommand \index{sdcdb (debugger)}
23225
23226 \end_inset
23227
23228
23229 \end_inset
23230 </cell>
23231 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23232 \begin_inset Text
23233
23234 \layout Standard
23235
23236 sdcc/debugger/README
23237 \end_inset
23238 </cell>
23239 </row>
23240 <row topline="true">
23241 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23242 \begin_inset Text
23243
23244 \layout Standard
23245
23246 Software simulator for microcontrollers
23247 \end_inset
23248 </cell>
23249 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23250 \begin_inset Text
23251
23252 \layout Standard
23253
23254
23255 \family roman
23256 \series medium
23257 \shape up
23258 \size normal
23259 \emph off
23260 \bar no
23261 \noun off
23262 \color none
23263 sdcc/sim/ucsim/doc
23264 \family default
23265 \series default
23266 \shape default
23267 \size default
23268 \emph default
23269 \bar default
23270 \noun default
23271 \color default
23272 /index.html
23273 \end_inset
23274 </cell>
23275 </row>
23276 <row topline="true">
23277 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23278 \begin_inset Text
23279
23280 \layout Standard
23281
23282 Temporary notes on the pic16
23283 \begin_inset LatexCommand \index{PIC16}
23284
23285 \end_inset
23286
23287  port
23288 \end_inset
23289 </cell>
23290 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23291 \begin_inset Text
23292
23293 \layout Standard
23294
23295 sdcc/src/pic16/NOTES
23296 \end_inset
23297 </cell>
23298 </row>
23299 <row topline="true" bottomline="true">
23300 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23301 \begin_inset Text
23302
23303 \layout Standard
23304
23305 SDCC internal documentation (debugging file format)
23306 \end_inset
23307 </cell>
23308 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23309 \begin_inset Text
23310
23311 \layout Standard
23312
23313 sdcc/doc/
23314 \family roman
23315 \series medium
23316 \shape up
23317 \size normal
23318 \emph off
23319 \bar no
23320 \noun off
23321 \color none
23322 cdbfileformat.pd
23323 \family default
23324 \series default
23325 \shape default
23326 \size default
23327 \emph default
23328 \bar default
23329 \noun default
23330 \color default
23331 f
23332 \end_inset
23333 </cell>
23334 </row>
23335 </lyxtabular>
23336
23337 \end_inset
23338
23339
23340 \newline
23341
23342 \layout Section
23343
23344 Related open source tools
23345 \begin_inset LatexCommand \index{Related tools}
23346
23347 \end_inset
23348
23349
23350 \layout Standard
23351 \align center
23352
23353 \begin_inset  Tabular
23354 <lyxtabular version="3" rows="13" columns="3">
23355 <features>
23356 <column alignment="left" valignment="top" leftline="true" width="0pt">
23357 <column alignment="block" valignment="top" leftline="true" width="30line%">
23358 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
23359 <row topline="true" bottomline="true">
23360 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23361 \begin_inset Text
23362
23363 \layout Standard
23364
23365 Name
23366 \end_inset
23367 </cell>
23368 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23369 \begin_inset Text
23370
23371 \layout Standard
23372
23373 Purpose
23374 \end_inset
23375 </cell>
23376 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23377 \begin_inset Text
23378
23379 \layout Standard
23380
23381 Where to get
23382 \end_inset
23383 </cell>
23384 </row>
23385 <row topline="true">
23386 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23387 \begin_inset Text
23388
23389 \layout Standard
23390
23391 gpsim
23392 \begin_inset LatexCommand \index{gpsim (pic simulator)}
23393
23394 \end_inset
23395
23396
23397 \end_inset
23398 </cell>
23399 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23400 \begin_inset Text
23401
23402 \layout Standard
23403
23404 PIC simulator
23405 \end_inset
23406 </cell>
23407 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23408 \begin_inset Text
23409
23410 \layout Standard
23411
23412
23413 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
23414
23415 \end_inset
23416
23417
23418 \end_inset
23419 </cell>
23420 </row>
23421 <row topline="true">
23422 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23423 \begin_inset Text
23424
23425 \layout Standard
23426
23427 gputils
23428 \begin_inset LatexCommand \index{gputils (pic tools)}
23429
23430 \end_inset
23431
23432
23433 \end_inset
23434 </cell>
23435 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23436 \begin_inset Text
23437
23438 \layout Standard
23439
23440 GNU PIC utilities
23441 \end_inset
23442 </cell>
23443 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23444 \begin_inset Text
23445
23446 \layout Standard
23447
23448
23449 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
23450
23451 \end_inset
23452
23453
23454 \end_inset
23455 </cell>
23456 </row>
23457 <row topline="true">
23458 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23459 \begin_inset Text
23460
23461 \layout Standard
23462
23463 flP5
23464 \end_inset
23465 </cell>
23466 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23467 \begin_inset Text
23468
23469 \layout Standard
23470
23471 PIC programmer
23472 \end_inset
23473 </cell>
23474 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23475 \begin_inset Text
23476
23477 \layout Standard
23478
23479
23480 \begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/}
23481
23482 \end_inset
23483
23484
23485 \end_inset
23486 </cell>
23487 </row>
23488 <row topline="true">
23489 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23490 \begin_inset Text
23491
23492 \layout Standard
23493
23494 ec2drv/newcdb
23495 \end_inset
23496 </cell>
23497 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23498 \begin_inset Text
23499
23500 \layout Standard
23501
23502 Tools for Silicon Laboratories JTAG debug adapter, partly based on sdcdb
23503  (Unix only)
23504 \end_inset
23505 </cell>
23506 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23507 \begin_inset Text
23508
23509 \layout Standard
23510
23511
23512 \begin_inset LatexCommand \url{http://sourceforge.net/projects/ec2drv}
23513
23514 \end_inset
23515
23516
23517 \end_inset
23518 </cell>
23519 </row>
23520 <row topline="true">
23521 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23522 \begin_inset Text
23523
23524 \layout Standard
23525
23526 indent
23527 \begin_inset LatexCommand \index{indent (source formatting tool)}
23528
23529 \end_inset
23530
23531
23532 \end_inset
23533 </cell>
23534 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23535 \begin_inset Text
23536
23537 \layout Standard
23538
23539 Formats C source - Master of the white spaces
23540 \end_inset
23541 </cell>
23542 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23543 \begin_inset Text
23544
23545 \layout Standard
23546
23547
23548 \begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html}
23549
23550 \end_inset
23551
23552
23553 \end_inset
23554 </cell>
23555 </row>
23556 <row topline="true">
23557 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23558 \begin_inset Text
23559
23560 \layout Standard
23561
23562 srecord
23563 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
23564
23565 \end_inset
23566
23567
23568 \end_inset
23569 </cell>
23570 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23571 \begin_inset Text
23572
23573 \layout Standard
23574
23575 Object file conversion, checksumming, ...
23576 \end_inset
23577 </cell>
23578 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23579 \begin_inset Text
23580
23581 \layout Standard
23582
23583
23584 \begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord}
23585
23586 \end_inset
23587
23588
23589 \end_inset
23590 </cell>
23591 </row>
23592 <row topline="true">
23593 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23594 \begin_inset Text
23595
23596 \layout Standard
23597
23598 objdump
23599 \begin_inset LatexCommand \index{objdump (tool)}
23600
23601 \end_inset
23602
23603
23604 \end_inset
23605 </cell>
23606 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23607 \begin_inset Text
23608
23609 \layout Standard
23610
23611 Object file conversion, ...
23612 \end_inset
23613 </cell>
23614 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23615 \begin_inset Text
23616
23617 \layout Standard
23618
23619 Part of binutils (should be there anyway)
23620 \end_inset
23621 </cell>
23622 </row>
23623 <row topline="true">
23624 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23625 \begin_inset Text
23626
23627 \layout Standard
23628
23629 doxygen
23630 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
23631
23632 \end_inset
23633
23634
23635 \end_inset
23636 </cell>
23637 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23638 \begin_inset Text
23639
23640 \layout Standard
23641
23642 Source code documentation system
23643 \end_inset
23644 </cell>
23645 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23646 \begin_inset Text
23647
23648 \layout Standard
23649
23650
23651 \begin_inset LatexCommand \url{http://www.doxygen.org}
23652
23653 \end_inset
23654
23655
23656 \end_inset
23657 </cell>
23658 </row>
23659 <row topline="true">
23660 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23661 \begin_inset Text
23662
23663 \layout Standard
23664
23665 kdevelop
23666 \end_inset
23667 </cell>
23668 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23669 \begin_inset Text
23670
23671 \layout Standard
23672
23673 IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
23674 \end_inset
23675 </cell>
23676 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23677 \begin_inset Text
23678
23679 \layout Standard
23680
23681
23682 \begin_inset LatexCommand \url{http://www.kdevelop.org}
23683
23684 \end_inset
23685
23686
23687 \end_inset
23688 </cell>
23689 </row>
23690 <row topline="true">
23691 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23692 \begin_inset Text
23693
23694 \layout Standard
23695
23696 paulmon
23697 \end_inset
23698 </cell>
23699 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23700 \begin_inset Text
23701
23702 \layout Standard
23703
23704 8051 monitor (hex up-/download, single step, disassemble)
23705 \end_inset
23706 </cell>
23707 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23708 \begin_inset Text
23709
23710 \layout Standard
23711
23712
23713 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/paulmon2.html}
23714
23715 \end_inset
23716
23717
23718 \end_inset
23719 </cell>
23720 </row>
23721 <row topline="true">
23722 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23723 \begin_inset Text
23724
23725 \layout Standard
23726
23727 splint
23728 \begin_inset LatexCommand \index{splint (syntax checking tool)}
23729
23730 \end_inset
23731
23732
23733 \end_inset
23734 </cell>
23735 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23736 \begin_inset Text
23737
23738 \layout Standard
23739
23740 Statically checks c sources (see
23741 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
23742
23743 \end_inset
23744
23745 )
23746 \end_inset
23747 </cell>
23748 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23749 \begin_inset Text
23750
23751 \layout Standard
23752
23753
23754 \begin_inset LatexCommand \url{http://www.splint.org}
23755
23756 \end_inset
23757
23758
23759 \end_inset
23760 </cell>
23761 </row>
23762 <row topline="true" bottomline="true">
23763 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23764 \begin_inset Text
23765
23766 \layout Standard
23767
23768 ddd
23769 \begin_inset LatexCommand \index{ddd (debugger)}
23770
23771 \end_inset
23772
23773
23774 \end_inset
23775 </cell>
23776 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23777 \begin_inset Text
23778
23779 \layout Standard
23780
23781 Debugger, serves nicely as GUI to sdcdb
23782 \begin_inset LatexCommand \index{sdcdb (debugger)}
23783
23784 \end_inset
23785
23786  (Unix only)
23787 \end_inset
23788 </cell>
23789 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23790 \begin_inset Text
23791
23792 \layout Standard
23793
23794
23795 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
23796
23797 \end_inset
23798
23799
23800 \end_inset
23801 </cell>
23802 </row>
23803 </lyxtabular>
23804
23805 \end_inset
23806
23807
23808 \newline
23809
23810 \layout Section
23811
23812 Related documentation / recommended reading
23813 \layout Standard
23814 \align center
23815
23816 \begin_inset  Tabular
23817 <lyxtabular version="3" rows="6" columns="3">
23818 <features>
23819 <column alignment="center" valignment="top" leftline="true" width="0pt">
23820 <column alignment="block" valignment="top" leftline="true" width="30line%">
23821 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
23822 <row topline="true" bottomline="true">
23823 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23824 \begin_inset Text
23825
23826 \layout Standard
23827
23828 Name
23829 \end_inset
23830 </cell>
23831 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23832 \begin_inset Text
23833
23834 \layout Standard
23835
23836 Subject / Title
23837 \end_inset
23838 </cell>
23839 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23840 \begin_inset Text
23841
23842 \layout Standard
23843
23844 Where to get
23845 \end_inset
23846 </cell>
23847 </row>
23848 <row topline="true">
23849 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23850 \begin_inset Text
23851
23852 \layout Standard
23853
23854
23855 \family roman
23856 \series medium
23857 \shape up
23858 \size normal
23859 \emph off
23860 \bar no
23861 \noun off
23862 \color none
23863 c-refcard.pdf
23864 \end_inset
23865 </cell>
23866 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23867 \begin_inset Text
23868
23869 \layout Standard
23870
23871 C Reference Card
23872 \begin_inset LatexCommand \index{C Reference card}
23873
23874 \end_inset
23875
23876 , 2 pages
23877 \end_inset
23878 </cell>
23879 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23880 \begin_inset Text
23881
23882 \layout Standard
23883
23884
23885 \begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html}
23886
23887 \end_inset
23888
23889
23890 \end_inset
23891 </cell>
23892 </row>
23893 <row topline="true">
23894 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23895 \begin_inset Text
23896
23897 \layout Standard
23898
23899 c-faq
23900 \end_inset
23901 </cell>
23902 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23903 \begin_inset Text
23904
23905 \layout Standard
23906
23907 C-FAQ-list
23908 \end_inset
23909 </cell>
23910 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23911 \begin_inset Text
23912
23913 \layout Standard
23914
23915
23916 \begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
23917
23918 \end_inset
23919
23920
23921 \end_inset
23922 </cell>
23923 </row>
23924 <row topline="true">
23925 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23926 \begin_inset Text
23927
23928 \layout Standard
23929
23930 \end_inset
23931 </cell>
23932 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23933 \begin_inset Text
23934
23935 \layout Standard
23936
23937 Latest datasheet of the target CPU
23938 \end_inset
23939 </cell>
23940 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23941 \begin_inset Text
23942
23943 \layout Standard
23944
23945 vendor
23946 \end_inset
23947 </cell>
23948 </row>
23949 <row topline="true">
23950 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23951 \begin_inset Text
23952
23953 \layout Standard
23954
23955 \end_inset
23956 </cell>
23957 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23958 \begin_inset Text
23959
23960 \layout Standard
23961
23962 Revision history of datasheet
23963 \end_inset
23964 </cell>
23965 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23966 \begin_inset Text
23967
23968 \layout Standard
23969
23970 vendor
23971 \end_inset
23972 </cell>
23973 </row>
23974 <row topline="true" bottomline="true">
23975 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23976 \begin_inset Text
23977
23978 \layout Standard
23979
23980 S.
23981  S.
23982  Muchnick
23983 \end_inset
23984 </cell>
23985 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23986 \begin_inset Text
23987
23988 \layout Standard
23989
23990 Advanced Compiler Design and Implementation
23991 \end_inset
23992 </cell>
23993 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23994 \begin_inset Text
23995
23996 \layout Standard
23997
23998 bookstore (very dedicated, probably read other books first)
23999 \end_inset
24000 </cell>
24001 </row>
24002 </lyxtabular>
24003
24004 \end_inset
24005
24006
24007 \newline
24008
24009 \layout Section
24010
24011 Some Questions
24012 \layout Standard
24013
24014 Some questions answered, some pointers given - it might be time to in turn
24015  ask
24016 \emph on
24017 you
24018 \emph default
24019  some questions:
24020 \layout Itemize
24021
24022 can you solve your project with the selected microcontroller? Would you
24023  find out early or rather late that your target is too small/slow/whatever?
24024  Can you switch to a slightly better device if it doesn't fit?
24025 \layout Itemize
24026
24027 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
24028  and/or another programming language be more adequate? Would an operating
24029  system on the target device help?
24030 \layout Itemize
24031
24032 if you solved the problem, will the marketing department be happy?
24033 \layout Itemize
24034
24035 if the marketing department is happy, will customers be happy?
24036 \layout Itemize
24037
24038 if you're the project manager, marketing department and maybe even the customer
24039  in one person, have you tried to see the project from the outside?
24040 \layout Itemize
24041
24042 is the project done if you think it is done? Or is just that other interface/pro
24043 tocol/feature/configuration/option missing? How about website, manual(s),
24044  internationali(z|s)ation, packaging, labels, 2nd source for components,
24045  electromagnetic compatability/interference, documentation for production,
24046  production test software, update mechanism, patent issues?
24047 \layout Itemize
24048
24049 is your project adequately positioned in that magic triangle: fame, fortune,
24050  fun?
24051 \layout Standard
24052
24053 Maybe not all answers to these questions are known and some answers may
24054  even be
24055 \emph on
24056 no
24057 \emph default
24058 , nevertheless knowing these questions may help you to avoid burnout
24059 \begin_inset Foot
24060 collapsed false
24061
24062 \layout Standard
24063
24064 burnout is bad for electronic devices, programmers and motorcycle tyres
24065 \end_inset
24066
24067 .
24068  Chances are you didn't want to hear some of them...
24069 \layout Chapter
24070
24071 Support
24072 \begin_inset LatexCommand \index{Support}
24073
24074 \end_inset
24075
24076
24077 \layout Standard
24078
24079 SDCC has grown to be a large project.
24080  The compiler alone (without the preprocessor, assembler and linker) is
24081  well over 100,000 lines of code (blank stripped).
24082  The open source nature of this project is a key to its continued growth
24083  and support.
24084  You gain the benefit and support of many active software developers and
24085  end users.
24086  Is SDCC perfect? No, that's why we need your help.
24087  The developers take pride in fixing reported bugs.
24088  You can help by reporting the bugs and helping other SDCC users.
24089  There are lots of ways to contribute, and we encourage you to take part
24090  in making SDCC a great software package.
24091
24092 \layout Standard
24093
24094 The SDCC project is hosted on the SDCC sourceforge site at
24095 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
24096
24097 \end_inset
24098
24099 .
24100  You'll find the complete set of mailing lists
24101 \begin_inset LatexCommand \index{Mailing list(s)}
24102
24103 \end_inset
24104
24105 , forums, bug reporting system, patch submission
24106 \begin_inset LatexCommand \index{Patch submission}
24107
24108 \end_inset
24109
24110  system, download
24111 \begin_inset LatexCommand \index{download}
24112
24113 \end_inset
24114
24115  area and Subversion code repository
24116 \begin_inset LatexCommand \index{Subversion code repository}
24117
24118 \end_inset
24119
24120  there.
24121 \layout Section
24122
24123 Reporting Bugs
24124 \begin_inset LatexCommand \index{Bug reporting}
24125
24126 \end_inset
24127
24128
24129 \begin_inset LatexCommand \index{Reporting bugs}
24130
24131 \end_inset
24132
24133
24134 \layout Standard
24135
24136 The recommended way of reporting bugs is using the infrastructure of the
24137  sourceforge site.
24138  You can follow the status of bug reports there and have an overview about
24139  the known bugs.
24140 \layout Standard
24141
24142 Bug reports are automatically forwarded to the developer mailing list and
24143  will be fixed ASAP.
24144  When reporting a bug, it is very useful to include a small test program
24145  (the smaller the better) which reproduces the problem.
24146  If you can isolate the problem by looking at the generated assembly code,
24147  this can be very helpful.
24148  Compiling your program with the -
24149 \begin_inset ERT
24150 status Collapsed
24151
24152 \layout Standard
24153
24154 \backslash
24155 /
24156 \end_inset
24157
24158 -dumpall
24159 \begin_inset LatexCommand \index{-\/-dumpall}
24160
24161 \end_inset
24162
24163  option can sometimes be useful in locating optimization problems.
24164  When reporting a bug please maker sure you:
24165 \layout Enumerate
24166
24167 Attach the code you are compiling with SDCC.
24168
24169 \layout Enumerate
24170
24171 Specify the exact command you use to run SDCC, or attach your Makefile.
24172
24173 \layout Enumerate
24174
24175 Specify the SDCC version (type "
24176 \family sans
24177 \series bold
24178 sdcc -v
24179 \family default
24180 \series default
24181 "), your platform, and operating system.
24182
24183 \layout Enumerate
24184
24185 Provide an exact copy of any error message or incorrect output.
24186
24187 \layout Enumerate
24188
24189 Put something meaningful in the subject of your message.
24190 \layout Standard
24191
24192 Please attempt to include these 5 important parts, as applicable, in all
24193  requests for support or when reporting any problems or bugs with SDCC.
24194  Though this will make your message lengthy, it will greatly improve your
24195  chance that SDCC users and developers will be able to help you.
24196  Some SDCC developers are frustrated by bug reports without code provided
24197  that they can use to reproduce and ultimately fix the problem, so please
24198  be sure to provide sample code if you are reporting a bug!
24199 \layout Standard
24200
24201 Please have a short check that you are using a recent version of SDCC and
24202  the bug is not yet known.
24203  This is the link for reporting bugs:
24204 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
24205
24206 \end_inset
24207
24208 .
24209 \layout Section
24210
24211 Requesting Features
24212 \begin_inset LatexCommand \label{sub:Requesting-Features}
24213
24214 \end_inset
24215
24216
24217 \begin_inset LatexCommand \index{Feature request}
24218
24219 \end_inset
24220
24221
24222 \begin_inset LatexCommand \index{Requesting features}
24223
24224 \end_inset
24225
24226
24227 \layout Standard
24228
24229 Like bug reports feature requests are forwarded to the developer mailing
24230  list.
24231  This is the link for requesting features:
24232 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
24233
24234 \end_inset
24235
24236 .
24237 \layout Section
24238
24239 Submitting patches
24240 \layout Standard
24241
24242 Like bug reports contributed patches are forwarded to the developer mailing
24243  list.
24244  This is the link for submitting patches
24245 \begin_inset LatexCommand \index{Patch submission}
24246
24247 \end_inset
24248
24249 :
24250 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
24251
24252 \end_inset
24253
24254 .
24255 \layout Standard
24256
24257 You need to specify some parameters to the
24258 \family typewriter
24259 diff
24260 \family default
24261  command for the patches to be useful.
24262  If you modified more than one file a patch created f.e.
24263  with
24264 \family sans
24265 \series bold
24266
24267 \begin_inset Quotes sld
24268 \end_inset
24269
24270 diff -Naur unmodified_directory modified_directory >my_changes.patch
24271 \begin_inset Quotes srd
24272 \end_inset
24273
24274
24275 \family default
24276 \series default
24277  will be fine, otherwise
24278 \family sans
24279 \series bold
24280
24281 \begin_inset Quotes sld
24282 \end_inset
24283
24284 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
24285 \begin_inset Quotes srd
24286 \end_inset
24287
24288
24289 \series default
24290
24291 \family default
24292 will do.
24293 \layout Section
24294
24295 Getting Help
24296 \layout Standard
24297
24298 These links should take you directly to the
24299 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
24300
24301 \end_inset
24302
24303
24304 \begin_inset Foot
24305 collapsed false
24306
24307 \layout Standard
24308
24309 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
24310  automated messages (mid 2003)
24311 \end_inset
24312
24313  and the
24314 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
24315
24316 \end_inset
24317
24318 , lists
24319 \begin_inset LatexCommand \index{Mailing list(s)}
24320
24321 \end_inset
24322
24323  and forums are archived and searchable so if you are lucky someone already
24324  had a similar problem.
24325  While mails to the lists themselves are delivered promptly their web front
24326  end on sourceforge sometimes shows a severe time lag (up to several weeks),
24327  if you're seriously using SDCC please consider subscribing to the lists.
24328 \layout Section
24329
24330 ChangeLog
24331 \layout Standard
24332
24333 You can follow the status of the Subversion version
24334 \begin_inset LatexCommand \index{version}
24335
24336 \end_inset
24337
24338  of SDCC by watching the Changelog
24339 \begin_inset LatexCommand \index{Changelog}
24340
24341 \end_inset
24342
24343  in the Subversion repository
24344 \size footnotesize
24345
24346 \begin_inset LatexCommand \htmlurl{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/ChangeLog}
24347
24348 \end_inset
24349
24350 .
24351 \layout Section
24352
24353 Subversion Source Code Repository
24354 \layout Standard
24355
24356 The output of
24357 \family sans
24358 \series bold
24359 sdcc --version
24360 \family default
24361 \series default
24362  or the filenames of the snapshot versions of SDCC include date and its
24363  Subversion
24364 \begin_inset LatexCommand \index{Subversion}
24365
24366 \end_inset
24367
24368  number.
24369  Subversion allows to download the source of recent or previous versions
24370
24371 \begin_inset LatexCommand \url{http://sourceforge.net/svn/?group_id=599}
24372
24373 \end_inset
24374
24375  (by number or by date).
24376  An on-line source code browser and detailled instructions are also available
24377  there.
24378  SDCC versions starting from 1999 up to now are available (currently the
24379  versions prior to the conversion from cvs to Subversion (April 2006) are
24380  either by accessible by Subversion or by cvs).
24381 \layout Section
24382
24383 Release policy
24384 \begin_inset LatexCommand \index{Release policy}
24385
24386 \end_inset
24387
24388
24389 \layout Standard
24390
24391 Historically there often were long delays between official releases and
24392  the sourceforge download area tends to get not updated at all.
24393  Excuses in the past might have referred to problems with live range analysis,
24394  but as this was fixed a while ago, the current problem is that another
24395  excuse has to be found.
24396  Kidding aside, we have to get better there! On the other hand there are
24397  daily snapshots available at
24398 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
24399
24400 \end_inset
24401
24402 , and you can always build the very last version (hopefully with many bugs
24403  fixed, and features added) from the source code available at
24404 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
24405
24406 \end_inset
24407
24408 .
24409 \layout Section
24410
24411 Examples
24412 \begin_inset LatexCommand \index{Examples}
24413
24414 \end_inset
24415
24416
24417 \layout Standard
24418
24419 You'll find some small examples in the directory
24420 \emph on
24421 sdcc/device/examples/.
24422
24423 \emph default
24424 More examples and libraries are available at
24425 \emph on
24426  The SDCC Open Knowledge Resource
24427 \begin_inset LatexCommand \url{http://sdccokr.dl9sec.de/}
24428
24429 \end_inset
24430
24431
24432 \emph default
24433 web site or at
24434 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
24435
24436 \end_inset
24437
24438 .
24439 \layout Comment
24440
24441 I did insert a reference to Paul's web site here although it seems rather
24442  dedicated to a specific 8032 board (I think it's okay because it f.e.
24443  shows LCD/Harddisc interface and has a free 8051 monitor.
24444  Independent 8032 board vendors face hard competition of heavily subsidized
24445  development boards anyway).
24446 \layout Comment
24447
24448 Maybe we should include some links to real world applications.
24449  Preferably pointer to pointers (one for each architecture) so this stays
24450  manageable here?
24451 \layout Section
24452
24453 Quality control
24454 \begin_inset LatexCommand \index{Quality control}
24455
24456 \end_inset
24457
24458
24459 \layout Standard
24460
24461 The compiler is passed through nightly compile and build checks.
24462  The so called
24463 \shape italic
24464 regression tests
24465 \shape default
24466
24467 \begin_inset LatexCommand \index{Regression test}
24468
24469 \end_inset
24470
24471  check that SDCC itself compiles flawlessly on several platforms and checks
24472  the quality of the code generated by SDCC by running the code through simulator
24473 s.
24474  There is a separate document
24475 \shape italic
24476 test_suite.pdf
24477 \begin_inset LatexCommand \index{Test suite}
24478
24479 \end_inset
24480
24481
24482 \shape default
24483  about this.
24484 \layout Standard
24485
24486 You'll find the test code in the directory
24487 \shape italic
24488 sdcc/support/regression
24489 \shape default
24490 .
24491  You can run these tests manually by running
24492 \family sans
24493 make
24494 \family default
24495  in this directory (or f.e.
24496
24497 \family sans
24498 \series bold
24499
24500 \begin_inset Quotes sld
24501 \end_inset
24502
24503 make test-mcs51
24504 \begin_inset Quotes srd
24505 \end_inset
24506
24507
24508 \family default
24509 \series default
24510  if you don't want to run the complete tests).
24511  The test code might also be interesting if you want to look for examples
24512 \begin_inset LatexCommand \index{Examples}
24513
24514 \end_inset
24515
24516  checking corner cases of SDCC or if you plan to submit patches
24517 \begin_inset LatexCommand \index{Patch submission}
24518
24519 \end_inset
24520
24521 .
24522 \layout Standard
24523
24524 The pic port uses a different set of regression tests, you'll find them
24525  in the directory
24526 \shape italic
24527 sdcc/src/regression
24528 \shape default
24529 .
24530 \layout Section
24531
24532 Use of SDCC in Education
24533 \layout Standard
24534
24535 In short:
24536 \emph on
24537 highly
24538 \emph default
24539  encouraged
24540 \begin_inset Foot
24541 collapsed false
24542
24543 \layout Standard
24544
24545 the phrase "use in education" might evoke the association "
24546 \emph on
24547 only
24548 \emph default
24549  fit for use in education".
24550  This connotation is not intended but nevertheless risked as the licensing
24551  of SDCC makes it difficult to offer educational discounts
24552 \end_inset
24553
24554 .
24555  If your rationales are to:
24556 \layout Enumerate
24557
24558 give students a chance to understand the
24559 \emph on
24560 complete
24561 \emph default
24562  steps of code generation
24563 \layout Enumerate
24564
24565 have a curriculum that can be extended for years.
24566  Then you could use an fpga board as target and your curriculum will seamlessly
24567  extend from logic synthesis (
24568 \begin_inset LatexCommand \url[http://www.opencores.org]{opencores.org}
24569
24570 \end_inset
24571
24572 ,
24573 \begin_inset LatexCommand \url[Oregano]{http://www.oregano.at/ip/ip01.htm}
24574
24575 \end_inset
24576
24577 ), over assembly programming, to C to FPGA compilers (
24578 \begin_inset LatexCommand \url[FPGAC]{http://sf.net/projects/fpgac}
24579
24580 \end_inset
24581
24582 ) and to C.
24583 \layout Enumerate
24584
24585 be able to insert excursions about skills like using a revision control
24586  system, submitting/applying patches, using a type-setting (as opposed to
24587  word-processing) engine LyX/LaTeX, using
24588 \begin_inset LatexCommand \url[SourceForge]{http://www.sf.net}
24589
24590 \end_inset
24591
24592 , following some
24593 \begin_inset LatexCommand \url[netiquette]{http://en.wikipedia.org/wiki/Netiquette}
24594
24595 \end_inset
24596
24597 , understanding BSD/LGPL/GPL/Proprietary licensing, growth models of Open
24598  Source Software, CPU simulation, compiler regression tests
24599 \begin_inset LatexCommand \index{Regression test}
24600
24601 \end_inset
24602
24603 .
24604
24605 \newline
24606 And if there should be a shortage of ideas then you can always point students
24607  to the ever-growing feature request list
24608 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
24609
24610 \end_inset
24611
24612 .
24613 \layout Enumerate
24614
24615 not tie students to a specific host platform and instead allow them to use
24616  a host platform of
24617 \emph on
24618 their
24619 \emph default
24620  choice (among them Alpha, i386, i386_64, MacOs, Mips, Sparc, Windows and
24621  eventually
24622 \begin_inset LatexCommand \url[OLPC]{http://wiki.laptop.org/wiki/One_Laptop_per_Child}
24623
24624 \end_inset
24625
24626 )
24627 \layout Enumerate
24628
24629 not encourage students to use illegal copies of educational software
24630 \layout Enumerate
24631
24632 be immune to licensing/availability/price changes of the chosen tool chain
24633 \layout Enumerate
24634
24635 be able to change to a new target platform without having to adopt a new
24636  tool chain
24637 \layout Enumerate
24638
24639 have complete control over and insight into the tool chain
24640 \layout Enumerate
24641
24642 make your students aware about the pros and cons of open source software
24643  development
24644 \layout Enumerate
24645
24646 give back to the public as you are probably at least partially publically
24647  funded
24648 \layout Enumerate
24649
24650 give students a chance to publically prove their skills and to possibly
24651  see a world wide impact
24652 \layout Standard
24653
24654 then SDCC is probably among the first choices.
24655  Well, probably SDCC might be the only choice.
24656 \layout Chapter
24657 \pagebreak_top
24658 SDCC Technical Data
24659 \layout Section
24660
24661 Optimizations
24662 \begin_inset LatexCommand \index{Optimizations}
24663
24664 \end_inset
24665
24666
24667 \layout Standard
24668
24669 SDCC performs a host of standard optimizations in addition to some MCU specific
24670  optimizations.
24671
24672 \layout Subsection
24673
24674 Sub-expression Elimination
24675 \begin_inset LatexCommand \index{Subexpression elimination}
24676
24677 \end_inset
24678
24679
24680 \layout Standard
24681
24682 The compiler does local and
24683 \emph on
24684 g
24685 \emph default
24686 lobal
24687 \emph on
24688 c
24689 \emph default
24690 ommon
24691 \emph on
24692 s
24693 \emph default
24694 ubexpression
24695 \emph on
24696 e
24697 \emph default
24698 limination, e.g.:
24699 \layout Verse
24700
24701
24702 \family typewriter
24703 i = x + y + 1;
24704 \newline
24705 j = x + y;
24706 \layout Standard
24707
24708 will be translated to
24709 \layout Verse
24710
24711
24712 \family typewriter
24713 iTemp = x + y;
24714 \newline
24715 i = iTemp + 1;
24716 \newline
24717 j = iTemp;
24718 \layout Standard
24719
24720 Some subexpressions are not as obvious as the above example, e.g.:
24721 \layout Verse
24722
24723
24724 \family typewriter
24725 a->b[i].c = 10;
24726 \newline
24727 a->b[i].d = 11;
24728 \layout Standard
24729
24730 In this case the address arithmetic a->b[i] will be computed only once;
24731  the equivalent code in C would be.
24732 \layout Verse
24733
24734
24735 \family typewriter
24736 iTemp = a->b[i];
24737 \newline
24738 iTemp.c = 10;
24739 \newline
24740 iTemp.d = 11;
24741 \layout Standard
24742
24743 The compiler will try to keep these temporary variables in registers.
24744 \layout Subsection
24745
24746 Dead-Code Elimination
24747 \begin_inset LatexCommand \index{Dead-code elimination}
24748
24749 \end_inset
24750
24751
24752 \layout Verse
24753
24754
24755 \family typewriter
24756 int global;
24757 \newline
24758
24759 \newline
24760 void f () {
24761 \newline
24762 \SpecialChar ~
24763 \SpecialChar ~
24764 int i;
24765 \newline
24766 \SpecialChar ~
24767 \SpecialChar ~
24768 i = 1; \SpecialChar ~
24769 \SpecialChar ~
24770 \SpecialChar ~
24771 \SpecialChar ~
24772 \SpecialChar ~
24773 /* dead store */
24774 \newline
24775 \SpecialChar ~
24776 \SpecialChar ~
24777 global = 1;\SpecialChar ~
24778 /* dead store */
24779 \newline
24780 \SpecialChar ~
24781 \SpecialChar ~
24782 global = 2;
24783 \newline
24784 \SpecialChar ~
24785 \SpecialChar ~
24786 return;
24787 \newline
24788 \SpecialChar ~
24789 \SpecialChar ~
24790 global = 3;\SpecialChar ~
24791 /* unreachable */
24792 \newline
24793 }
24794 \layout Standard
24795
24796 will be changed to
24797 \layout Verse
24798
24799
24800 \family typewriter
24801 int global;
24802 \newline
24803
24804 \newline
24805 void f () {
24806 \newline
24807 \SpecialChar ~
24808 \SpecialChar ~
24809 global = 2;
24810 \newline
24811 }
24812 \layout Subsection
24813
24814 Copy-Propagation
24815 \begin_inset LatexCommand \index{Copy propagation}
24816
24817 \end_inset
24818
24819
24820 \layout Verse
24821
24822
24823 \family typewriter
24824 int f() {
24825 \newline
24826 \SpecialChar ~
24827 \SpecialChar ~
24828 int i, j;
24829 \newline
24830 \SpecialChar ~
24831 \SpecialChar ~
24832 i = 10;
24833 \newline
24834 \SpecialChar ~
24835 \SpecialChar ~
24836 j = i;
24837 \newline
24838 \SpecialChar ~
24839 \SpecialChar ~
24840 return j;
24841 \newline
24842 }
24843 \layout Standard
24844
24845 will be changed to
24846 \layout Verse
24847
24848
24849 \family typewriter
24850 int f() {
24851 \newline
24852 \SpecialChar ~
24853 \SpecialChar ~
24854 int i, j;
24855 \newline
24856 \SpecialChar ~
24857 \SpecialChar ~
24858 i = 10;
24859 \newline
24860 \SpecialChar ~
24861 \SpecialChar ~
24862 j = 10;
24863 \newline
24864 \SpecialChar ~
24865 \SpecialChar ~
24866 return 10;
24867 \newline
24868 }
24869 \layout Standard
24870
24871 Note: the dead stores created by this copy propagation will be eliminated
24872  by dead-code elimination.
24873 \layout Subsection
24874
24875 Loop Optimizations
24876 \begin_inset LatexCommand \index{Loop optimization}
24877
24878 \end_inset
24879
24880
24881 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
24882
24883 \end_inset
24884
24885
24886 \layout Standard
24887
24888 Two types of loop optimizations are done by SDCC
24889 \emph on
24890 loop invariant
24891 \emph default
24892  lifting and
24893 \emph on
24894  strength reduction
24895 \emph default
24896  of loop induction variables.
24897  In addition to the strength reduction the optimizer marks the induction
24898  variables and the register allocator tries to keep the induction variables
24899  in registers for the duration of the loop.
24900  Because of this preference of the register allocator
24901 \begin_inset LatexCommand \index{Register allocation}
24902
24903 \end_inset
24904
24905 , loop induction optimization causes an increase in register pressure, which
24906  may cause unwanted spilling of other temporary variables into the stack
24907 \begin_inset LatexCommand \index{stack}
24908
24909 \end_inset
24910
24911  / data space.
24912  The compiler will generate a warning message when it is forced to allocate
24913  extra space either on the stack or data space.
24914  If this extra space allocation is undesirable then induction optimization
24915  can be eliminated either for the entire source file (with -
24916 \begin_inset ERT
24917 status Collapsed
24918
24919 \layout Standard
24920
24921 \backslash
24922 /
24923 \end_inset
24924
24925 -noinduction option) or for a given function only using #pragma\SpecialChar ~
24926 noinduction
24927 \begin_inset LatexCommand \index{\#pragma noinduction}
24928
24929 \end_inset
24930
24931 .
24932 \newline
24933
24934 \newline
24935 Loop Invariant:
24936 \layout Verse
24937
24938
24939 \family typewriter
24940 for (i = 0 ; i < 100 ; i ++)
24941 \newline
24942 \SpecialChar ~
24943 \SpecialChar ~
24944 \SpecialChar ~
24945 \SpecialChar ~
24946 f += k + l;
24947 \layout Standard
24948
24949 changed to
24950 \layout Verse
24951
24952
24953 \family typewriter
24954 itemp = k + l;
24955 \newline
24956 for (i = 0; i < 100; i++)
24957 \newline
24958 \SpecialChar ~
24959 \SpecialChar ~
24960 \SpecialChar ~
24961 \SpecialChar ~
24962 f += itemp;
24963 \layout Standard
24964
24965 As mentioned previously some loop invariants are not as apparent, all static
24966  address computations are also moved out of the loop.
24967 \newline
24968
24969 \newline
24970 Strength Reduction
24971 \begin_inset LatexCommand \index{Strength reduction}
24972
24973 \end_inset
24974
24975 , this optimization substitutes an expression by a cheaper expression:
24976 \layout Verse
24977
24978
24979 \family typewriter
24980 for (i=0;i < 100; i++)
24981 \newline
24982 \SpecialChar ~
24983 \SpecialChar ~
24984 \SpecialChar ~
24985 \SpecialChar ~
24986 ar[i*5] = i*3;
24987 \layout Standard
24988
24989 changed to
24990 \layout Verse
24991
24992
24993 \family typewriter
24994 itemp1 = 0;
24995 \newline
24996 itemp2 = 0;
24997 \newline
24998 for (i=0;i< 100;i++) {
24999 \newline
25000 \SpecialChar ~
25001 \SpecialChar ~
25002 \SpecialChar ~
25003 \SpecialChar ~
25004 ar[itemp1] = itemp2;
25005 \newline
25006 \SpecialChar ~
25007 \SpecialChar ~
25008 \SpecialChar ~
25009 \SpecialChar ~
25010 itemp1 += 5;
25011 \newline
25012 \SpecialChar ~
25013 \SpecialChar ~
25014 \SpecialChar ~
25015 \SpecialChar ~
25016 itemp2 += 3;
25017 \newline
25018 }
25019 \layout Standard
25020
25021 The more expensive multiplication
25022 \begin_inset LatexCommand \index{Multiplication}
25023
25024 \end_inset
25025
25026  is changed to a less expensive addition.
25027 \layout Subsection
25028
25029 Loop Reversing
25030 \begin_inset LatexCommand \index{Loop reversing}
25031
25032 \end_inset
25033
25034
25035 \layout Standard
25036
25037 This optimization is done to reduce the overhead of checking loop boundaries
25038  for every iteration.
25039  Some simple loops can be reversed and implemented using a
25040 \begin_inset Quotes eld
25041 \end_inset
25042
25043 decrement and jump if not zero
25044 \begin_inset Quotes erd
25045 \end_inset
25046
25047  instruction.
25048  SDCC checks for the following criterion to determine if a loop is reversible
25049  (note: more sophisticated compilers use data-dependency analysis to make
25050  this determination, SDCC uses a more simple minded analysis).
25051 \layout Itemize
25052
25053 The 'for' loop is of the form
25054 \newline
25055
25056 \newline
25057
25058 \family typewriter
25059 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
25060  += 1])
25061 \newline
25062 \SpecialChar ~
25063 \SpecialChar ~
25064 \SpecialChar ~
25065 \SpecialChar ~
25066 <for body>
25067 \layout Itemize
25068
25069 The <for body> does not contain
25070 \begin_inset Quotes eld
25071 \end_inset
25072
25073 continue
25074 \begin_inset Quotes erd
25075 \end_inset
25076
25077  or 'break
25078 \begin_inset Quotes erd
25079 \end_inset
25080
25081 .
25082 \layout Itemize
25083
25084 All goto's are contained within the loop.
25085 \layout Itemize
25086
25087 No function calls within the loop.
25088 \layout Itemize
25089
25090 The loop control variable <sym> is not assigned any value within the loop
25091 \layout Itemize
25092
25093 The loop control variable does NOT participate in any arithmetic operation
25094  within the loop.
25095 \layout Itemize
25096
25097 There are NO switch statements in the loop.
25098 \layout Subsection
25099
25100 Algebraic Simplifications
25101 \layout Standard
25102
25103 SDCC does numerous algebraic simplifications, the following is a small sub-set
25104  of these optimizations.
25105 \layout Verse
25106
25107
25108 \family typewriter
25109 i = j + 0;\SpecialChar ~
25110 \SpecialChar ~
25111 \SpecialChar ~
25112 \SpecialChar ~
25113  /* changed to: */\SpecialChar ~
25114 \SpecialChar ~
25115 \SpecialChar ~
25116 \SpecialChar ~
25117  i = j;
25118 \newline
25119 i /= 2;\SpecialChar ~
25120 \SpecialChar ~
25121 \SpecialChar ~
25122 \SpecialChar ~
25123 \SpecialChar ~
25124 \SpecialChar ~
25125 \SpecialChar ~
25126  /* changed to: */\SpecialChar ~
25127 \SpecialChar ~
25128 \SpecialChar ~
25129 \SpecialChar ~
25130  i >>= 1;
25131 \newline
25132 i = j - j;\SpecialChar ~
25133 \SpecialChar ~
25134 \SpecialChar ~
25135 \SpecialChar ~
25136  /* changed to: */\SpecialChar ~
25137 \SpecialChar ~
25138 \SpecialChar ~
25139 \SpecialChar ~
25140  i = 0;
25141 \newline
25142 i = j / 1;\SpecialChar ~
25143 \SpecialChar ~
25144 \SpecialChar ~
25145 \SpecialChar ~
25146  /* changed to: */\SpecialChar ~
25147 \SpecialChar ~
25148 \SpecialChar ~
25149 \SpecialChar ~
25150  i = j;
25151 \layout Standard
25152
25153 Note the subexpressions
25154 \begin_inset LatexCommand \index{Subexpression}
25155
25156 \end_inset
25157
25158  given above are generally introduced by macro expansions or as a result
25159  of copy/constant propagation.
25160 \layout Subsection
25161
25162 'switch' Statements
25163 \begin_inset LatexCommand \label{sub:'switch'-Statements}
25164
25165 \end_inset
25166
25167
25168 \begin_inset LatexCommand \index{switch statement}
25169
25170 \end_inset
25171
25172
25173 \layout Standard
25174
25175 SDCC can optimize switch statements to jump tables
25176 \begin_inset LatexCommand \index{jump tables}
25177
25178 \end_inset
25179
25180 .
25181  It makes the decision based on an estimate of the generated code size.
25182  SDCC is quite liberal in the requirements for jump table generation:
25183 \layout Itemize
25184
25185 The labels need not be in order, and the starting number need not be one
25186  or zero, the case labels are in numerical sequence or not too many case
25187  labels are missing.
25188 \begin_deeper
25189 \layout Verse
25190
25191
25192 \family typewriter
25193 switch(i) {\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 \SpecialChar ~
25210 \SpecialChar ~
25211 \SpecialChar ~
25212 \SpecialChar ~
25213 \SpecialChar ~
25214 \SpecialChar ~
25215 \SpecialChar ~
25216 \SpecialChar ~
25217 \SpecialChar ~
25218 \SpecialChar ~
25219 switch (i) {
25220 \newline
25221 \SpecialChar ~
25222 \SpecialChar ~
25223 \SpecialChar ~
25224 case 4: ...\SpecialChar ~
25225 \SpecialChar ~
25226 \SpecialChar ~
25227 \SpecialChar ~
25228 \SpecialChar ~
25229 \SpecialChar ~
25230 \SpecialChar ~
25231 \SpecialChar ~
25232 \SpecialChar ~
25233 \SpecialChar ~
25234 \SpecialChar ~
25235 \SpecialChar ~
25236 \SpecialChar ~
25237 \SpecialChar ~
25238 \SpecialChar ~
25239 \SpecialChar ~
25240 \SpecialChar ~
25241 \SpecialChar ~
25242 \SpecialChar ~
25243 \SpecialChar ~
25244 \SpecialChar ~
25245 \SpecialChar ~
25246 \SpecialChar ~
25247 \SpecialChar ~
25248 \SpecialChar ~
25249 \SpecialChar ~
25250 case 0: ...
25251
25252 \newline
25253 \SpecialChar ~
25254 \SpecialChar ~
25255 \SpecialChar ~
25256 case 5: ...\SpecialChar ~
25257 \SpecialChar ~
25258 \SpecialChar ~
25259 \SpecialChar ~
25260 \SpecialChar ~
25261 \SpecialChar ~
25262 \SpecialChar ~
25263 \SpecialChar ~
25264 \SpecialChar ~
25265 \SpecialChar ~
25266 \SpecialChar ~
25267 \SpecialChar ~
25268 \SpecialChar ~
25269 \SpecialChar ~
25270 \SpecialChar ~
25271 \SpecialChar ~
25272 \SpecialChar ~
25273 \SpecialChar ~
25274 \SpecialChar ~
25275 \SpecialChar ~
25276 \SpecialChar ~
25277 \SpecialChar ~
25278 \SpecialChar ~
25279 \SpecialChar ~
25280 \SpecialChar ~
25281 \SpecialChar ~
25282 case 1: ...
25283
25284 \newline
25285 \SpecialChar ~
25286 \SpecialChar ~
25287 \SpecialChar ~
25288 case 3: ...\SpecialChar ~
25289 \SpecialChar ~
25290 \SpecialChar ~
25291 \SpecialChar ~
25292 \SpecialChar ~
25293 \SpecialChar ~
25294 \SpecialChar ~
25295 \SpecialChar ~
25296 \SpecialChar ~
25297 \SpecialChar ~
25298 \SpecialChar ~
25299 \SpecialChar ~
25300 \SpecialChar ~
25301 \SpecialChar ~
25302 \SpecialChar ~
25303 \SpecialChar ~
25304 \SpecialChar ~
25305 \SpecialChar ~
25306 \SpecialChar ~
25307 \SpecialChar ~
25308 \SpecialChar ~
25309 \SpecialChar ~
25310 \SpecialChar ~
25311 \SpecialChar ~
25312 \SpecialChar ~
25313 \SpecialChar ~
25314
25315 \newline
25316 \SpecialChar ~
25317 \SpecialChar ~
25318 \SpecialChar ~
25319 case 6: ...\SpecialChar ~
25320 \SpecialChar ~
25321 \SpecialChar ~
25322 \SpecialChar ~
25323 \SpecialChar ~
25324 \SpecialChar ~
25325 \SpecialChar ~
25326 \SpecialChar ~
25327 \SpecialChar ~
25328 \SpecialChar ~
25329 \SpecialChar ~
25330 \SpecialChar ~
25331 \SpecialChar ~
25332 \SpecialChar ~
25333 \SpecialChar ~
25334 \SpecialChar ~
25335 \SpecialChar ~
25336 \SpecialChar ~
25337 \SpecialChar ~
25338 \SpecialChar ~
25339 \SpecialChar ~
25340 \SpecialChar ~
25341 \SpecialChar ~
25342 \SpecialChar ~
25343 \SpecialChar ~
25344 \SpecialChar ~
25345 case 3: ...
25346
25347 \newline
25348 \SpecialChar ~
25349 \SpecialChar ~
25350 \SpecialChar ~
25351 case 7: ...\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 \SpecialChar ~
25367 \SpecialChar ~
25368 \SpecialChar ~
25369 \SpecialChar ~
25370 \SpecialChar ~
25371 \SpecialChar ~
25372 \SpecialChar ~
25373 \SpecialChar ~
25374 \SpecialChar ~
25375 \SpecialChar ~
25376 \SpecialChar ~
25377 case 4: ...
25378
25379 \newline
25380 \SpecialChar ~
25381 \SpecialChar ~
25382 \SpecialChar ~
25383 case 8: ...\SpecialChar ~
25384 \SpecialChar ~
25385 \SpecialChar ~
25386 \SpecialChar ~
25387 \SpecialChar ~
25388 \SpecialChar ~
25389 \SpecialChar ~
25390 \SpecialChar ~
25391 \SpecialChar ~
25392 \SpecialChar ~
25393 \SpecialChar ~
25394 \SpecialChar ~
25395 \SpecialChar ~
25396 \SpecialChar ~
25397 \SpecialChar ~
25398 \SpecialChar ~
25399 \SpecialChar ~
25400 \SpecialChar ~
25401 \SpecialChar ~
25402 \SpecialChar ~
25403 \SpecialChar ~
25404 \SpecialChar ~
25405 \SpecialChar ~
25406 \SpecialChar ~
25407 \SpecialChar ~
25408 \SpecialChar ~
25409 case 5: ...
25410
25411 \newline
25412 \SpecialChar ~
25413 \SpecialChar ~
25414 \SpecialChar ~
25415 case 9: ...\SpecialChar ~
25416 \SpecialChar ~
25417 \SpecialChar ~
25418 \SpecialChar ~
25419 \SpecialChar ~
25420 \SpecialChar ~
25421 \SpecialChar ~
25422 \SpecialChar ~
25423 \SpecialChar ~
25424 \SpecialChar ~
25425 \SpecialChar ~
25426 \SpecialChar ~
25427 \SpecialChar ~
25428 \SpecialChar ~
25429 \SpecialChar ~
25430 \SpecialChar ~
25431 \SpecialChar ~
25432 \SpecialChar ~
25433 \SpecialChar ~
25434 \SpecialChar ~
25435 \SpecialChar ~
25436 \SpecialChar ~
25437 \SpecialChar ~
25438 \SpecialChar ~
25439 \SpecialChar ~
25440 \SpecialChar ~
25441 case 6: ...
25442
25443 \newline
25444 \SpecialChar ~
25445 \SpecialChar ~
25446 \SpecialChar ~
25447 case 10: ...\SpecialChar ~
25448 \SpecialChar ~
25449 \SpecialChar ~
25450 \SpecialChar ~
25451 \SpecialChar ~
25452 \SpecialChar ~
25453 \SpecialChar ~
25454 \SpecialChar ~
25455 \SpecialChar ~
25456 \SpecialChar ~
25457 \SpecialChar ~
25458 \SpecialChar ~
25459 \SpecialChar ~
25460 \SpecialChar ~
25461 \SpecialChar ~
25462 \SpecialChar ~
25463 \SpecialChar ~
25464 \SpecialChar ~
25465 \SpecialChar ~
25466 \SpecialChar ~
25467 \SpecialChar ~
25468 \SpecialChar ~
25469 \SpecialChar ~
25470 \SpecialChar ~
25471 \SpecialChar ~
25472 case 7: ...
25473
25474 \newline
25475 \SpecialChar ~
25476 \SpecialChar ~
25477 \SpecialChar ~
25478 case 11: ...\SpecialChar ~
25479 \SpecialChar ~
25480 \SpecialChar ~
25481 \SpecialChar ~
25482 \SpecialChar ~
25483 \SpecialChar ~
25484 \SpecialChar ~
25485 \SpecialChar ~
25486 \SpecialChar ~
25487 \SpecialChar ~
25488 \SpecialChar ~
25489 \SpecialChar ~
25490 \SpecialChar ~
25491 \SpecialChar ~
25492 \SpecialChar ~
25493 \SpecialChar ~
25494 \SpecialChar ~
25495 \SpecialChar ~
25496 \SpecialChar ~
25497 \SpecialChar ~
25498 \SpecialChar ~
25499 \SpecialChar ~
25500 \SpecialChar ~
25501 \SpecialChar ~
25502 \SpecialChar ~
25503 case 8: ...
25504
25505 \newline
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 \SpecialChar ~
25522 \SpecialChar ~
25523 \SpecialChar ~
25524 \SpecialChar ~
25525 \SpecialChar ~
25526 \SpecialChar ~
25527 \SpecialChar ~
25528 \SpecialChar ~
25529 \SpecialChar ~
25530 \SpecialChar ~
25531 \SpecialChar ~
25532 \SpecialChar ~
25533 \SpecialChar ~
25534 \SpecialChar ~
25535 \SpecialChar ~
25536 \SpecialChar ~
25537 \SpecialChar ~
25538 \SpecialChar ~
25539 \SpecialChar ~
25540 \SpecialChar ~
25541 \SpecialChar ~
25542 }
25543 \layout Standard
25544
25545 Both the above switch statements will be implemented using a jump-table.
25546  The example to the right side is slightly more efficient as the check for
25547  the lower boundary of the jump-table is not needed.
25548 \end_deeper
25549 \layout Itemize
25550
25551 The number of case labels is not larger than supported by the target architectur
25552 e.
25553 \layout Itemize
25554
25555 If the case labels are not in numerical sequence ('gaps' between cases)
25556  SDCC checks whether a jump table with additionally inserted dummy cases
25557  is still attractive.
25558
25559 \layout Itemize
25560
25561 If the starting number is not zero and a check for the lower boundary of
25562  the jump-table can thus be eliminated SDCC might insert dummy cases 0,
25563  ...
25564  .
25565 \layout Standard
25566
25567 Switch statements which have large gaps in the numeric sequence or those
25568  that have too many case labels can be split into more than one switch statement
25569  for efficient code generation, e.g.:
25570 \layout Verse
25571
25572
25573 \family typewriter
25574 switch (i) {
25575 \newline
25576 \SpecialChar ~
25577 \SpecialChar ~
25578 case 1: ...
25579
25580 \newline
25581 \SpecialChar ~
25582 \SpecialChar ~
25583 case 2: ...
25584
25585 \newline
25586 \SpecialChar ~
25587 \SpecialChar ~
25588 case 3: ...
25589
25590 \newline
25591 \SpecialChar ~
25592 \SpecialChar ~
25593 case 4: ...
25594
25595 \newline
25596 \SpecialChar ~
25597 \SpecialChar ~
25598 case 5: ...
25599
25600 \newline
25601 \SpecialChar ~
25602 \SpecialChar ~
25603 case 6: ...
25604
25605 \newline
25606 \SpecialChar ~
25607 \SpecialChar ~
25608 case 7: ...
25609
25610 \newline
25611 \SpecialChar ~
25612 \SpecialChar ~
25613 case 101: ...
25614
25615 \newline
25616 \SpecialChar ~
25617 \SpecialChar ~
25618 case 102: ...
25619
25620 \newline
25621 \SpecialChar ~
25622 \SpecialChar ~
25623 case 103: ...
25624
25625 \newline
25626 \SpecialChar ~
25627 \SpecialChar ~
25628 case 104: ...
25629
25630 \newline
25631 \SpecialChar ~
25632 \SpecialChar ~
25633 case 105: ...
25634
25635 \newline
25636 \SpecialChar ~
25637 \SpecialChar ~
25638 case 106: ...
25639
25640 \newline
25641 \SpecialChar ~
25642 \SpecialChar ~
25643 case 107: ...
25644
25645 \newline
25646 }
25647 \layout Standard
25648
25649 If the above switch statement is broken down into two switch statements
25650 \layout Verse
25651
25652
25653 \family typewriter
25654 switch (i) {
25655 \newline
25656 \SpecialChar ~
25657 \SpecialChar ~
25658 case 1: ...
25659
25660 \newline
25661 \SpecialChar ~
25662 \SpecialChar ~
25663 case 2: ...
25664
25665 \newline
25666 \SpecialChar ~
25667 \SpecialChar ~
25668 case 3: ...
25669
25670 \newline
25671 \SpecialChar ~
25672 \SpecialChar ~
25673 case 4: ...
25674
25675 \newline
25676 \SpecialChar ~
25677 \SpecialChar ~
25678 case 5: ...
25679
25680 \newline
25681 \SpecialChar ~
25682 \SpecialChar ~
25683 case 6: ...
25684
25685 \newline
25686 \SpecialChar ~
25687 \SpecialChar ~
25688 case 7: ...
25689
25690 \newline
25691 }
25692 \layout Standard
25693
25694 and
25695 \layout Verse
25696
25697
25698 \family typewriter
25699 switch (i) {
25700 \newline
25701 \SpecialChar ~
25702 \SpecialChar ~
25703 case 101: ...
25704
25705 \newline
25706 \SpecialChar ~
25707 \SpecialChar ~
25708 case 102: ...
25709
25710 \newline
25711 \SpecialChar ~
25712 \SpecialChar ~
25713 case 103: ...
25714
25715 \newline
25716 \SpecialChar ~
25717 \SpecialChar ~
25718 case 104: ...
25719
25720 \newline
25721 \SpecialChar ~
25722 \SpecialChar ~
25723 case 105: ...
25724
25725 \newline
25726 \SpecialChar ~
25727 \SpecialChar ~
25728 case 106: ...
25729
25730 \newline
25731 \SpecialChar ~
25732 \SpecialChar ~
25733 case 107: ...
25734
25735 \newline
25736 }
25737 \layout Standard
25738
25739 then both the switch statements will be implemented using jump-tables whereas
25740  the unmodified switch statement will not be.
25741 \layout Comment
25742
25743 There might be reasons which SDCC cannot know about to either favour or
25744  not favour jump tables.
25745  If the target system has to be as quick for the last switch case as for
25746  the first (pro jump table), or if the switch argument is known to be zero
25747  in the majority of the cases (contra jump table).
25748 \layout Standard
25749
25750 The pragma nojtbound
25751 \begin_inset LatexCommand \index{\#pragma nojtbound}
25752
25753 \end_inset
25754
25755  can be used to turn off checking the
25756 \emph on
25757 j
25758 \emph default
25759 ump
25760 \emph on
25761 t
25762 \emph default
25763 able
25764 \emph on
25765 bound
25766 \emph default
25767 aries.
25768  It has no effect if a default label is supplied.
25769  Use of this pragma is dangerous: if the switch
25770 \begin_inset LatexCommand \index{switch statement}
25771
25772 \end_inset
25773
25774  argument is not matched by a case statement the processor will happily
25775  jump into Nirvana.
25776 \layout Subsection
25777
25778 Bit-shifting Operations
25779 \begin_inset LatexCommand \index{Bit shifting}
25780
25781 \end_inset
25782
25783 .
25784 \layout Standard
25785
25786 Bit shifting is one of the most frequently used operation in embedded programmin
25787 g.
25788  SDCC tries to implement bit-shift operations in the most efficient way
25789  possible, e.g.:
25790 \layout Verse
25791
25792
25793 \family typewriter
25794 unsigned char i;
25795 \newline
25796 ...
25797
25798 \newline
25799 i >>= 4;
25800 \newline
25801 ...
25802 \layout Standard
25803
25804 generates the following code:
25805 \layout Verse
25806
25807
25808 \family typewriter
25809 mov\SpecialChar ~
25810  a,_i
25811 \newline
25812 swap a
25813 \newline
25814 anl\SpecialChar ~
25815  a,#0x0f
25816 \newline
25817 mov\SpecialChar ~
25818  _i,a
25819 \layout Standard
25820
25821 In general SDCC will never setup a loop if the shift count is known.
25822  Another example:
25823 \layout Verse
25824
25825
25826 \family typewriter
25827 unsigned int i;
25828 \newline
25829 ...
25830
25831 \newline
25832 i >>= 9;
25833 \newline
25834 ...
25835 \layout Standard
25836
25837 will generate:
25838 \layout Verse
25839
25840
25841 \family typewriter
25842 mov\SpecialChar ~
25843 \SpecialChar ~
25844 a,(_i + 1)
25845 \newline
25846 mov\SpecialChar ~
25847 \SpecialChar ~
25848 (_i + 1),#0x00
25849 \newline
25850 clr\SpecialChar ~
25851 \SpecialChar ~
25852 c
25853 \newline
25854 rrc\SpecialChar ~
25855 \SpecialChar ~
25856 a
25857 \newline
25858 mov\SpecialChar ~
25859 \SpecialChar ~
25860 _i,a
25861 \layout Subsection
25862
25863 Bit-rotation
25864 \begin_inset LatexCommand \index{Bit rotation}
25865
25866 \end_inset
25867
25868
25869 \layout Standard
25870
25871 A special case of the bit-shift operation is bit rotation
25872 \begin_inset LatexCommand \index{rotating bits}
25873
25874 \end_inset
25875
25876 , SDCC recognizes the following expression to be a left bit-rotation:
25877 \layout Verse
25878
25879
25880 \family typewriter
25881 \series bold
25882 unsigned
25883 \series default
25884 \SpecialChar ~
25885 \SpecialChar ~
25886 char i;\SpecialChar ~
25887 \SpecialChar ~
25888 \SpecialChar ~
25889 \SpecialChar ~
25890 \SpecialChar ~
25891 \SpecialChar ~
25892 \SpecialChar ~
25893 \SpecialChar ~
25894 \SpecialChar ~
25895 \SpecialChar ~
25896 \SpecialChar ~
25897 /* unsigned is needed for rotation */
25898 \newline
25899 ...
25900
25901 \newline
25902 i = ((i << 1) | (i >> 7));
25903 \family default
25904
25905 \newline
25906
25907 \family typewriter
25908 ...
25909 \layout Standard
25910
25911 will generate the following code:
25912 \layout Verse
25913
25914
25915 \family typewriter
25916 mov\SpecialChar ~
25917 \SpecialChar ~
25918 a,_i
25919 \newline
25920 rl\SpecialChar ~
25921 \SpecialChar ~
25922 \SpecialChar ~
25923 a
25924 \newline
25925 mov\SpecialChar ~
25926 \SpecialChar ~
25927 _i,a
25928 \layout Standard
25929
25930 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
25931 ns of this case will also be recognized as bit-rotation, i.e.:
25932 \layout Verse
25933
25934
25935 \family typewriter
25936 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
25937 \layout Subsection
25938
25939 Nibble and Byte Swapping
25940 \layout Standard
25941
25942 Other special cases of the bit-shift operations are nibble or byte swapping
25943 \begin_inset LatexCommand \index{swapping nibbles/bytes}
25944
25945 \end_inset
25946
25947 , SDCC recognizes the following expressions:
25948 \layout Verse
25949
25950
25951 \family typewriter
25952 \series bold
25953 unsigned
25954 \series default
25955 \SpecialChar ~
25956 \SpecialChar ~
25957 char i;
25958 \newline
25959
25960 \series bold
25961 unsigned
25962 \series default
25963 \SpecialChar ~
25964 \SpecialChar ~
25965 int j;
25966 \newline
25967 ...
25968
25969 \newline
25970 i = ((i << 4) | (i >> 4));
25971 \family default
25972
25973 \newline
25974
25975 \family typewriter
25976 j = ((j << 8) | (j >> 8));
25977 \layout Standard
25978
25979 and generates a swap instruction for the nibble swapping
25980 \begin_inset LatexCommand \index{Nibble swapping}
25981
25982 \end_inset
25983
25984  or move instructions for the byte swapping
25985 \begin_inset LatexCommand \index{Byte swapping}
25986
25987 \end_inset
25988
25989 .
25990  The
25991 \begin_inset Quotes sld
25992 \end_inset
25993
25994 j
25995 \begin_inset Quotes srd
25996 \end_inset
25997
25998  example can be used to convert from little to big-endian or vice versa.
25999  If you want to change the endianness of a
26000 \emph on
26001 signed
26002 \emph default
26003  integer you have to cast to
26004 \family typewriter
26005 (unsigned int)
26006 \family default
26007  first.
26008 \layout Standard
26009
26010 Note that SDCC stores numbers in little-endian
26011 \begin_inset Foot
26012 collapsed false
26013
26014 \layout Standard
26015
26016 Usually 8-bit processors don't care much about endianness.
26017  This is not the case for the standard 8051 which only has an instruction
26018  to increment its
26019 \emph on
26020 dptr
26021 \emph default
26022
26023 \begin_inset LatexCommand \index{DPTR}
26024
26025 \end_inset
26026
26027 -datapointer
26028 \emph on
26029
26030 \emph default
26031 so little-endian is the more efficient byte order.
26032 \end_inset
26033
26034
26035 \begin_inset LatexCommand \index{little-endian}
26036
26037 \end_inset
26038
26039
26040 \begin_inset LatexCommand \index{Endianness}
26041
26042 \end_inset
26043
26044  format (i.e.
26045  lowest order first).
26046 \layout Subsection
26047
26048 Highest Order Bit
26049 \begin_inset LatexCommand \index{Highest Order Bit}
26050
26051 \end_inset
26052
26053  / Any Order Bit
26054 \begin_inset LatexCommand \index{Any Order Bit}
26055
26056 \end_inset
26057
26058
26059 \layout Standard
26060
26061 It is frequently required to obtain the highest order bit of an integral
26062  type (long, int, short or char types).
26063  Also obtaining any other order bit is not uncommon.
26064  SDCC recognizes the following expressions to yield the highest order bit
26065  and generates optimized code for it, e.g.:
26066 \layout Verse
26067
26068
26069 \family typewriter
26070 unsigned int gint;
26071 \newline
26072
26073 \newline
26074 foo () {
26075 \newline
26076 \SpecialChar ~
26077 \SpecialChar ~
26078 unsigned char hob1, aob1;
26079 \newline
26080 \SpecialChar ~
26081 \SpecialChar ~
26082 bit hob2, hob3, aob2, aob3;
26083 \newline
26084 \SpecialChar ~
26085 \SpecialChar ~
26086 ...
26087
26088 \newline
26089 \SpecialChar ~
26090 \SpecialChar ~
26091 hob1 = (gint >> 15) & 1;
26092 \newline
26093 \SpecialChar ~
26094 \SpecialChar ~
26095 hob2 = (gint >> 15) & 1;
26096 \newline
26097 \SpecialChar ~
26098 \SpecialChar ~
26099 hob3 = gint & 0x8000;
26100 \newline
26101 \SpecialChar ~
26102 \SpecialChar ~
26103 aob1 = (gint >> 9) & 1;
26104 \newline
26105 \SpecialChar ~
26106 \SpecialChar ~
26107 aob2 = (gint >> 8) & 1;
26108 \newline
26109 \SpecialChar ~
26110 \SpecialChar ~
26111 aob3 = gint & 0x0800;
26112 \newline
26113 \SpecialChar ~
26114 \SpecialChar ~
26115 ..
26116
26117 \newline
26118 }
26119 \layout Standard
26120
26121 will generate the following code:
26122 \layout Verse
26123
26124
26125 \family typewriter
26126 \SpecialChar ~
26127 \SpecialChar ~
26128 \SpecialChar ~
26129 \SpecialChar ~
26130 \SpecialChar ~
26131 \SpecialChar ~
26132 \SpecialChar ~
26133 \SpecialChar ~
26134 \SpecialChar ~
26135 \SpecialChar ~
26136 \SpecialChar ~
26137 \SpecialChar ~
26138 \SpecialChar ~
26139 \SpecialChar ~
26140 \SpecialChar ~
26141 \SpecialChar ~
26142 \SpecialChar ~
26143 \SpecialChar ~
26144 \SpecialChar ~
26145 \SpecialChar ~
26146 \SpecialChar ~
26147 \SpecialChar ~
26148 \SpecialChar ~
26149 \SpecialChar ~
26150 \SpecialChar ~
26151  61 ;\SpecialChar ~
26152  hob.c 7
26153 \newline
26154 000A E5*01\SpecialChar ~
26155 \SpecialChar ~
26156 \SpecialChar ~
26157 \SpecialChar ~
26158 \SpecialChar ~
26159 \SpecialChar ~
26160 \SpecialChar ~
26161 \SpecialChar ~
26162 \SpecialChar ~
26163 \SpecialChar ~
26164 \SpecialChar ~
26165 \SpecialChar ~
26166 \SpecialChar ~
26167 \SpecialChar ~
26168 \SpecialChar ~
26169  62\SpecialChar ~
26170 \SpecialChar ~
26171 \SpecialChar ~
26172 \SpecialChar ~
26173 \SpecialChar ~
26174 \SpecialChar ~
26175 \SpecialChar ~
26176 \SpecialChar ~
26177  mov\SpecialChar ~
26178 \SpecialChar ~
26179  a,(_gint + 1)
26180 \newline
26181 000C 23\SpecialChar ~
26182 \SpecialChar ~
26183 \SpecialChar ~
26184 \SpecialChar ~
26185 \SpecialChar ~
26186 \SpecialChar ~
26187 \SpecialChar ~
26188 \SpecialChar ~
26189 \SpecialChar ~
26190 \SpecialChar ~
26191 \SpecialChar ~
26192 \SpecialChar ~
26193 \SpecialChar ~
26194 \SpecialChar ~
26195 \SpecialChar ~
26196 \SpecialChar ~
26197 \SpecialChar ~
26198 \SpecialChar ~
26199  63\SpecialChar ~
26200 \SpecialChar ~
26201 \SpecialChar ~
26202 \SpecialChar ~
26203 \SpecialChar ~
26204 \SpecialChar ~
26205 \SpecialChar ~
26206 \SpecialChar ~
26207  rl\SpecialChar ~
26208 \SpecialChar ~
26209 \SpecialChar ~
26210  a
26211 \newline
26212 000D 54 01\SpecialChar ~
26213 \SpecialChar ~
26214 \SpecialChar ~
26215 \SpecialChar ~
26216 \SpecialChar ~
26217 \SpecialChar ~
26218 \SpecialChar ~
26219 \SpecialChar ~
26220 \SpecialChar ~
26221 \SpecialChar ~
26222 \SpecialChar ~
26223 \SpecialChar ~
26224 \SpecialChar ~
26225 \SpecialChar ~
26226 \SpecialChar ~
26227  64\SpecialChar ~
26228 \SpecialChar ~
26229 \SpecialChar ~
26230 \SpecialChar ~
26231 \SpecialChar ~
26232 \SpecialChar ~
26233 \SpecialChar ~
26234 \SpecialChar ~
26235  anl\SpecialChar ~
26236 \SpecialChar ~
26237  a,#0x01
26238 \newline
26239 000F F5*02\SpecialChar ~
26240 \SpecialChar ~
26241 \SpecialChar ~
26242 \SpecialChar ~
26243 \SpecialChar ~
26244 \SpecialChar ~
26245 \SpecialChar ~
26246 \SpecialChar ~
26247 \SpecialChar ~
26248 \SpecialChar ~
26249 \SpecialChar ~
26250 \SpecialChar ~
26251 \SpecialChar ~
26252 \SpecialChar ~
26253 \SpecialChar ~
26254  65\SpecialChar ~
26255 \SpecialChar ~
26256 \SpecialChar ~
26257 \SpecialChar ~
26258 \SpecialChar ~
26259 \SpecialChar ~
26260 \SpecialChar ~
26261 \SpecialChar ~
26262  mov\SpecialChar ~
26263 \SpecialChar ~
26264  _foo_hob1_1_1,a
26265 \newline
26266 \SpecialChar ~
26267 \SpecialChar ~
26268 \SpecialChar ~
26269 \SpecialChar ~
26270 \SpecialChar ~
26271 \SpecialChar ~
26272 \SpecialChar ~
26273 \SpecialChar ~
26274 \SpecialChar ~
26275 \SpecialChar ~
26276 \SpecialChar ~
26277 \SpecialChar ~
26278 \SpecialChar ~
26279 \SpecialChar ~
26280 \SpecialChar ~
26281 \SpecialChar ~
26282 \SpecialChar ~
26283 \SpecialChar ~
26284 \SpecialChar ~
26285 \SpecialChar ~
26286 \SpecialChar ~
26287 \SpecialChar ~
26288 \SpecialChar ~
26289 \SpecialChar ~
26290 \SpecialChar ~
26291  66 ;\SpecialChar ~
26292  hob.c 8
26293 \newline
26294 0011 E5*01\SpecialChar ~
26295 \SpecialChar ~
26296 \SpecialChar ~
26297 \SpecialChar ~
26298 \SpecialChar ~
26299 \SpecialChar ~
26300 \SpecialChar ~
26301 \SpecialChar ~
26302 \SpecialChar ~
26303 \SpecialChar ~
26304 \SpecialChar ~
26305 \SpecialChar ~
26306 \SpecialChar ~
26307 \SpecialChar ~
26308 \SpecialChar ~
26309  67\SpecialChar ~
26310 \SpecialChar ~
26311 \SpecialChar ~
26312 \SpecialChar ~
26313 \SpecialChar ~
26314 \SpecialChar ~
26315 \SpecialChar ~
26316 \SpecialChar ~
26317  mov\SpecialChar ~
26318 \SpecialChar ~
26319  a,(_gint + 1)
26320 \newline
26321 0013 33\SpecialChar ~
26322 \SpecialChar ~
26323 \SpecialChar ~
26324 \SpecialChar ~
26325 \SpecialChar ~
26326 \SpecialChar ~
26327 \SpecialChar ~
26328 \SpecialChar ~
26329 \SpecialChar ~
26330 \SpecialChar ~
26331 \SpecialChar ~
26332 \SpecialChar ~
26333 \SpecialChar ~
26334 \SpecialChar ~
26335 \SpecialChar ~
26336 \SpecialChar ~
26337 \SpecialChar ~
26338 \SpecialChar ~
26339  68\SpecialChar ~
26340 \SpecialChar ~
26341 \SpecialChar ~
26342 \SpecialChar ~
26343 \SpecialChar ~
26344 \SpecialChar ~
26345 \SpecialChar ~
26346 \SpecialChar ~
26347  rlc\SpecialChar ~
26348 \SpecialChar ~
26349  a
26350 \newline
26351 0014 92*00\SpecialChar ~
26352 \SpecialChar ~
26353 \SpecialChar ~
26354 \SpecialChar ~
26355 \SpecialChar ~
26356 \SpecialChar ~
26357 \SpecialChar ~
26358 \SpecialChar ~
26359 \SpecialChar ~
26360 \SpecialChar ~
26361 \SpecialChar ~
26362 \SpecialChar ~
26363 \SpecialChar ~
26364 \SpecialChar ~
26365 \SpecialChar ~
26366  69\SpecialChar ~
26367 \SpecialChar ~
26368 \SpecialChar ~
26369 \SpecialChar ~
26370 \SpecialChar ~
26371 \SpecialChar ~
26372 \SpecialChar ~
26373 \SpecialChar ~
26374  mov\SpecialChar ~
26375 \SpecialChar ~
26376  _foo_hob2_1_1,c
26377 \newline
26378 \SpecialChar ~
26379 \SpecialChar ~
26380 \SpecialChar ~
26381 \SpecialChar ~
26382 \SpecialChar ~
26383 \SpecialChar ~
26384 \SpecialChar ~
26385 \SpecialChar ~
26386 \SpecialChar ~
26387 \SpecialChar ~
26388 \SpecialChar ~
26389 \SpecialChar ~
26390 \SpecialChar ~
26391 \SpecialChar ~
26392 \SpecialChar ~
26393 \SpecialChar ~
26394 \SpecialChar ~
26395 \SpecialChar ~
26396 \SpecialChar ~
26397 \SpecialChar ~
26398 \SpecialChar ~
26399 \SpecialChar ~
26400 \SpecialChar ~
26401 \SpecialChar ~
26402 \SpecialChar ~
26403  66 ;\SpecialChar ~
26404  hob.c 9
26405 \newline
26406 0016 E5*01\SpecialChar ~
26407 \SpecialChar ~
26408 \SpecialChar ~
26409 \SpecialChar ~
26410 \SpecialChar ~
26411 \SpecialChar ~
26412 \SpecialChar ~
26413 \SpecialChar ~
26414 \SpecialChar ~
26415 \SpecialChar ~
26416 \SpecialChar ~
26417 \SpecialChar ~
26418 \SpecialChar ~
26419 \SpecialChar ~
26420 \SpecialChar ~
26421  67\SpecialChar ~
26422 \SpecialChar ~
26423 \SpecialChar ~
26424 \SpecialChar ~
26425 \SpecialChar ~
26426 \SpecialChar ~
26427 \SpecialChar ~
26428 \SpecialChar ~
26429  mov\SpecialChar ~
26430 \SpecialChar ~
26431  a,(_gint + 1)
26432 \newline
26433 0018 33\SpecialChar ~
26434 \SpecialChar ~
26435 \SpecialChar ~
26436 \SpecialChar ~
26437 \SpecialChar ~
26438 \SpecialChar ~
26439 \SpecialChar ~
26440 \SpecialChar ~
26441 \SpecialChar ~
26442 \SpecialChar ~
26443 \SpecialChar ~
26444 \SpecialChar ~
26445 \SpecialChar ~
26446 \SpecialChar ~
26447 \SpecialChar ~
26448 \SpecialChar ~
26449 \SpecialChar ~
26450 \SpecialChar ~
26451  68\SpecialChar ~
26452 \SpecialChar ~
26453 \SpecialChar ~
26454 \SpecialChar ~
26455 \SpecialChar ~
26456 \SpecialChar ~
26457 \SpecialChar ~
26458 \SpecialChar ~
26459  rlc\SpecialChar ~
26460 \SpecialChar ~
26461  a
26462 \newline
26463 0019 92*01\SpecialChar ~
26464 \SpecialChar ~
26465 \SpecialChar ~
26466 \SpecialChar ~
26467 \SpecialChar ~
26468 \SpecialChar ~
26469 \SpecialChar ~
26470 \SpecialChar ~
26471 \SpecialChar ~
26472 \SpecialChar ~
26473 \SpecialChar ~
26474 \SpecialChar ~
26475 \SpecialChar ~
26476 \SpecialChar ~
26477 \SpecialChar ~
26478  69\SpecialChar ~
26479 \SpecialChar ~
26480 \SpecialChar ~
26481 \SpecialChar ~
26482 \SpecialChar ~
26483 \SpecialChar ~
26484 \SpecialChar ~
26485 \SpecialChar ~
26486  mov\SpecialChar ~
26487 \SpecialChar ~
26488  _foo_hob3_1_1,c
26489 \newline
26490 \SpecialChar ~
26491 \SpecialChar ~
26492 \SpecialChar ~
26493 \SpecialChar ~
26494 \SpecialChar ~
26495 \SpecialChar ~
26496 \SpecialChar ~
26497 \SpecialChar ~
26498 \SpecialChar ~
26499 \SpecialChar ~
26500 \SpecialChar ~
26501 \SpecialChar ~
26502 \SpecialChar ~
26503 \SpecialChar ~
26504 \SpecialChar ~
26505 \SpecialChar ~
26506 \SpecialChar ~
26507 \SpecialChar ~
26508 \SpecialChar ~
26509 \SpecialChar ~
26510 \SpecialChar ~
26511 \SpecialChar ~
26512 \SpecialChar ~
26513 \SpecialChar ~
26514 \SpecialChar ~
26515  70 ;\SpecialChar ~
26516  hob.c 10
26517 \newline
26518 001B E5*01\SpecialChar ~
26519 \SpecialChar ~
26520 \SpecialChar ~
26521 \SpecialChar ~
26522 \SpecialChar ~
26523 \SpecialChar ~
26524 \SpecialChar ~
26525 \SpecialChar ~
26526 \SpecialChar ~
26527 \SpecialChar ~
26528 \SpecialChar ~
26529 \SpecialChar ~
26530 \SpecialChar ~
26531 \SpecialChar ~
26532 \SpecialChar ~
26533  71\SpecialChar ~
26534 \SpecialChar ~
26535 \SpecialChar ~
26536 \SpecialChar ~
26537 \SpecialChar ~
26538 \SpecialChar ~
26539 \SpecialChar ~
26540 \SpecialChar ~
26541  mov\SpecialChar ~
26542 \SpecialChar ~
26543  a,(_gint + 1)
26544 \newline
26545 001D 03\SpecialChar ~
26546 \SpecialChar ~
26547 \SpecialChar ~
26548 \SpecialChar ~
26549 \SpecialChar ~
26550 \SpecialChar ~
26551 \SpecialChar ~
26552 \SpecialChar ~
26553 \SpecialChar ~
26554 \SpecialChar ~
26555 \SpecialChar ~
26556 \SpecialChar ~
26557 \SpecialChar ~
26558 \SpecialChar ~
26559 \SpecialChar ~
26560 \SpecialChar ~
26561 \SpecialChar ~
26562 \SpecialChar ~
26563  72\SpecialChar ~
26564 \SpecialChar ~
26565 \SpecialChar ~
26566 \SpecialChar ~
26567 \SpecialChar ~
26568 \SpecialChar ~
26569 \SpecialChar ~
26570 \SpecialChar ~
26571  rr\SpecialChar ~
26572 \SpecialChar ~
26573 \SpecialChar ~
26574  a
26575 \newline
26576 001E 54 01\SpecialChar ~
26577 \SpecialChar ~
26578 \SpecialChar ~
26579 \SpecialChar ~
26580 \SpecialChar ~
26581 \SpecialChar ~
26582 \SpecialChar ~
26583 \SpecialChar ~
26584 \SpecialChar ~
26585 \SpecialChar ~
26586 \SpecialChar ~
26587 \SpecialChar ~
26588 \SpecialChar ~
26589 \SpecialChar ~
26590 \SpecialChar ~
26591  73\SpecialChar ~
26592 \SpecialChar ~
26593 \SpecialChar ~
26594 \SpecialChar ~
26595 \SpecialChar ~
26596 \SpecialChar ~
26597 \SpecialChar ~
26598 \SpecialChar ~
26599  anl\SpecialChar ~
26600 \SpecialChar ~
26601  a,#0x01
26602 \newline
26603 0020 F5*03\SpecialChar ~
26604 \SpecialChar ~
26605 \SpecialChar ~
26606 \SpecialChar ~
26607 \SpecialChar ~
26608 \SpecialChar ~
26609 \SpecialChar ~
26610 \SpecialChar ~
26611 \SpecialChar ~
26612 \SpecialChar ~
26613 \SpecialChar ~
26614 \SpecialChar ~
26615 \SpecialChar ~
26616 \SpecialChar ~
26617 \SpecialChar ~
26618  74\SpecialChar ~
26619 \SpecialChar ~
26620 \SpecialChar ~
26621 \SpecialChar ~
26622 \SpecialChar ~
26623 \SpecialChar ~
26624 \SpecialChar ~
26625 \SpecialChar ~
26626  mov\SpecialChar ~
26627 \SpecialChar ~
26628  _foo_aob1_1_1,a
26629 \newline
26630 \SpecialChar ~
26631 \SpecialChar ~
26632 \SpecialChar ~
26633 \SpecialChar ~
26634 \SpecialChar ~
26635 \SpecialChar ~
26636 \SpecialChar ~
26637 \SpecialChar ~
26638 \SpecialChar ~
26639 \SpecialChar ~
26640 \SpecialChar ~
26641 \SpecialChar ~
26642 \SpecialChar ~
26643 \SpecialChar ~
26644 \SpecialChar ~
26645 \SpecialChar ~
26646 \SpecialChar ~
26647 \SpecialChar ~
26648 \SpecialChar ~
26649 \SpecialChar ~
26650 \SpecialChar ~
26651 \SpecialChar ~
26652 \SpecialChar ~
26653 \SpecialChar ~
26654 \SpecialChar ~
26655  75 ;\SpecialChar ~
26656  hob.c 11
26657 \newline
26658 0022 E5*01\SpecialChar ~
26659 \SpecialChar ~
26660 \SpecialChar ~
26661 \SpecialChar ~
26662 \SpecialChar ~
26663 \SpecialChar ~
26664 \SpecialChar ~
26665 \SpecialChar ~
26666 \SpecialChar ~
26667 \SpecialChar ~
26668 \SpecialChar ~
26669 \SpecialChar ~
26670 \SpecialChar ~
26671 \SpecialChar ~
26672 \SpecialChar ~
26673  76\SpecialChar ~
26674 \SpecialChar ~
26675 \SpecialChar ~
26676 \SpecialChar ~
26677 \SpecialChar ~
26678 \SpecialChar ~
26679 \SpecialChar ~
26680 \SpecialChar ~
26681  mov\SpecialChar ~
26682 \SpecialChar ~
26683  a,(_gint + 1)
26684 \newline
26685 0024 13\SpecialChar ~
26686 \SpecialChar ~
26687 \SpecialChar ~
26688 \SpecialChar ~
26689 \SpecialChar ~
26690 \SpecialChar ~
26691 \SpecialChar ~
26692 \SpecialChar ~
26693 \SpecialChar ~
26694 \SpecialChar ~
26695 \SpecialChar ~
26696 \SpecialChar ~
26697 \SpecialChar ~
26698 \SpecialChar ~
26699 \SpecialChar ~
26700 \SpecialChar ~
26701 \SpecialChar ~
26702 \SpecialChar ~
26703  77\SpecialChar ~
26704 \SpecialChar ~
26705 \SpecialChar ~
26706 \SpecialChar ~
26707 \SpecialChar ~
26708 \SpecialChar ~
26709 \SpecialChar ~
26710 \SpecialChar ~
26711  rrc\SpecialChar ~
26712 \SpecialChar ~
26713  a
26714 \newline
26715 0025 92*02\SpecialChar ~
26716 \SpecialChar ~
26717 \SpecialChar ~
26718 \SpecialChar ~
26719 \SpecialChar ~
26720 \SpecialChar ~
26721 \SpecialChar ~
26722 \SpecialChar ~
26723 \SpecialChar ~
26724 \SpecialChar ~
26725 \SpecialChar ~
26726 \SpecialChar ~
26727 \SpecialChar ~
26728 \SpecialChar ~
26729 \SpecialChar ~
26730  78\SpecialChar ~
26731 \SpecialChar ~
26732 \SpecialChar ~
26733 \SpecialChar ~
26734 \SpecialChar ~
26735 \SpecialChar ~
26736 \SpecialChar ~
26737 \SpecialChar ~
26738  mov\SpecialChar ~
26739 \SpecialChar ~
26740  _foo_aob2_1_1,c
26741 \newline
26742 \SpecialChar ~
26743 \SpecialChar ~
26744 \SpecialChar ~
26745 \SpecialChar ~
26746 \SpecialChar ~
26747 \SpecialChar ~
26748 \SpecialChar ~
26749 \SpecialChar ~
26750 \SpecialChar ~
26751 \SpecialChar ~
26752 \SpecialChar ~
26753 \SpecialChar ~
26754 \SpecialChar ~
26755 \SpecialChar ~
26756 \SpecialChar ~
26757 \SpecialChar ~
26758 \SpecialChar ~
26759 \SpecialChar ~
26760 \SpecialChar ~
26761 \SpecialChar ~
26762 \SpecialChar ~
26763 \SpecialChar ~
26764 \SpecialChar ~
26765 \SpecialChar ~
26766 \SpecialChar ~
26767  79 ;\SpecialChar ~
26768  hob.c 12
26769 \newline
26770 0027 E5*01\SpecialChar ~
26771 \SpecialChar ~
26772 \SpecialChar ~
26773 \SpecialChar ~
26774 \SpecialChar ~
26775 \SpecialChar ~
26776 \SpecialChar ~
26777 \SpecialChar ~
26778 \SpecialChar ~
26779 \SpecialChar ~
26780 \SpecialChar ~
26781 \SpecialChar ~
26782 \SpecialChar ~
26783 \SpecialChar ~
26784 \SpecialChar ~
26785  80\SpecialChar ~
26786 \SpecialChar ~
26787 \SpecialChar ~
26788 \SpecialChar ~
26789 \SpecialChar ~
26790 \SpecialChar ~
26791 \SpecialChar ~
26792 \SpecialChar ~
26793  mov\SpecialChar ~
26794 \SpecialChar ~
26795  a,(_gint + 1)
26796 \newline
26797 0029 A2 E3\SpecialChar ~
26798 \SpecialChar ~
26799 \SpecialChar ~
26800 \SpecialChar ~
26801 \SpecialChar ~
26802 \SpecialChar ~
26803 \SpecialChar ~
26804 \SpecialChar ~
26805 \SpecialChar ~
26806 \SpecialChar ~
26807 \SpecialChar ~
26808 \SpecialChar ~
26809 \SpecialChar ~
26810 \SpecialChar ~
26811 \SpecialChar ~
26812  81\SpecialChar ~
26813 \SpecialChar ~
26814 \SpecialChar ~
26815 \SpecialChar ~
26816 \SpecialChar ~
26817 \SpecialChar ~
26818 \SpecialChar ~
26819 \SpecialChar ~
26820  mov\SpecialChar ~
26821 \SpecialChar ~
26822  c,acc[3]
26823 \newline
26824 002B 92*03\SpecialChar ~
26825 \SpecialChar ~
26826 \SpecialChar ~
26827 \SpecialChar ~
26828 \SpecialChar ~
26829 \SpecialChar ~
26830 \SpecialChar ~
26831 \SpecialChar ~
26832 \SpecialChar ~
26833 \SpecialChar ~
26834 \SpecialChar ~
26835 \SpecialChar ~
26836 \SpecialChar ~
26837 \SpecialChar ~
26838 \SpecialChar ~
26839  82\SpecialChar ~
26840 \SpecialChar ~
26841 \SpecialChar ~
26842 \SpecialChar ~
26843 \SpecialChar ~
26844 \SpecialChar ~
26845 \SpecialChar ~
26846 \SpecialChar ~
26847  mov\SpecialChar ~
26848 \SpecialChar ~
26849  _foo_aob3_1_1,c
26850 \layout Standard
26851
26852 Other variations of these cases however will
26853 \emph on
26854 not
26855 \emph default
26856  be recognized.
26857  They are standard C expressions, so I heartily recommend these be the only
26858  way to get the highest order bit, (it is portable).
26859  Of course it will be recognized even if it is embedded in other expressions,
26860  e.g.:
26861 \layout Verse
26862
26863
26864 \family typewriter
26865 xyz = gint + ((gint >> 15) & 1);
26866 \layout Standard
26867
26868 will still be recognized.
26869 \layout Subsection
26870
26871 Higher Order Byte
26872 \begin_inset LatexCommand \index{Higher Order Byte}
26873
26874 \end_inset
26875
26876  / Higher Order Word
26877 \begin_inset LatexCommand \index{Higher Order Word}
26878
26879 \end_inset
26880
26881
26882 \layout Standard
26883
26884 It is also frequently required to obtain a higher order byte or word of
26885  a larger integral type (long, int or short types).
26886  SDCC recognizes the following expressions to yield the higher order byte
26887  or word and generates optimized code for it, e.g.:
26888 \layout Verse
26889
26890
26891 \family typewriter
26892 unsigned int gint;
26893 \newline
26894 unsigned long int glong;
26895 \newline
26896
26897 \newline
26898 foo () {
26899 \newline
26900 \SpecialChar ~
26901 \SpecialChar ~
26902 unsigned char hob1, hob2;
26903 \newline
26904 \SpecialChar ~
26905 \SpecialChar ~
26906 unsigned int how1, how2;
26907 \newline
26908 \SpecialChar ~
26909 \SpecialChar ~
26910 ...
26911
26912 \newline
26913 \SpecialChar ~
26914 \SpecialChar ~
26915 hob1 = (gint >> 8) & 0xFF;
26916 \newline
26917 \SpecialChar ~
26918 \SpecialChar ~
26919 hob2 = glong >> 24;
26920 \newline
26921 \SpecialChar ~
26922 \SpecialChar ~
26923 how1 = (glong >> 16) & 0xFFFF;
26924 \newline
26925 \SpecialChar ~
26926 \SpecialChar ~
26927 how2 = glong >> 8;
26928 \newline
26929 \SpecialChar ~
26930 \SpecialChar ~
26931 ..
26932
26933 \newline
26934 }
26935 \layout Standard
26936
26937 will generate the following code:
26938 \layout Verse
26939
26940
26941 \family typewriter
26942 \SpecialChar ~
26943 \SpecialChar ~
26944 \SpecialChar ~
26945 \SpecialChar ~
26946 \SpecialChar ~
26947 \SpecialChar ~
26948 \SpecialChar ~
26949 \SpecialChar ~
26950 \SpecialChar ~
26951 \SpecialChar ~
26952 \SpecialChar ~
26953 \SpecialChar ~
26954 \SpecialChar ~
26955 \SpecialChar ~
26956 \SpecialChar ~
26957 \SpecialChar ~
26958 \SpecialChar ~
26959 \SpecialChar ~
26960 \SpecialChar ~
26961 \SpecialChar ~
26962 \SpecialChar ~
26963 \SpecialChar ~
26964 \SpecialChar ~
26965 \SpecialChar ~
26966 \SpecialChar ~
26967  91 ;\SpecialChar ~
26968  hob.c 15
26969 \newline
26970 0037 85*01*06\SpecialChar ~
26971 \SpecialChar ~
26972 \SpecialChar ~
26973 \SpecialChar ~
26974 \SpecialChar ~
26975 \SpecialChar ~
26976 \SpecialChar ~
26977 \SpecialChar ~
26978 \SpecialChar ~
26979 \SpecialChar ~
26980 \SpecialChar ~
26981 \SpecialChar ~
26982  92\SpecialChar ~
26983 \SpecialChar ~
26984 \SpecialChar ~
26985 \SpecialChar ~
26986 \SpecialChar ~
26987 \SpecialChar ~
26988 \SpecialChar ~
26989 \SpecialChar ~
26990  mov\SpecialChar ~
26991 \SpecialChar ~
26992  _foo_hob1_1_1,(_gint + 1)
26993 \newline
26994 \SpecialChar ~
26995 \SpecialChar ~
26996 \SpecialChar ~
26997 \SpecialChar ~
26998 \SpecialChar ~
26999 \SpecialChar ~
27000 \SpecialChar ~
27001 \SpecialChar ~
27002 \SpecialChar ~
27003 \SpecialChar ~
27004 \SpecialChar ~
27005 \SpecialChar ~
27006 \SpecialChar ~
27007 \SpecialChar ~
27008 \SpecialChar ~
27009 \SpecialChar ~
27010 \SpecialChar ~
27011 \SpecialChar ~
27012 \SpecialChar ~
27013 \SpecialChar ~
27014 \SpecialChar ~
27015 \SpecialChar ~
27016 \SpecialChar ~
27017 \SpecialChar ~
27018 \SpecialChar ~
27019  93 ;\SpecialChar ~
27020  hob.c 16
27021 \newline
27022 003A 85*05*07\SpecialChar ~
27023 \SpecialChar ~
27024 \SpecialChar ~
27025 \SpecialChar ~
27026 \SpecialChar ~
27027 \SpecialChar ~
27028 \SpecialChar ~
27029 \SpecialChar ~
27030 \SpecialChar ~
27031 \SpecialChar ~
27032 \SpecialChar ~
27033 \SpecialChar ~
27034  94\SpecialChar ~
27035 \SpecialChar ~
27036 \SpecialChar ~
27037 \SpecialChar ~
27038 \SpecialChar ~
27039 \SpecialChar ~
27040 \SpecialChar ~
27041 \SpecialChar ~
27042  mov\SpecialChar ~
27043 \SpecialChar ~
27044  _foo_hob2_1_1,(_glong + 3)
27045 \newline
27046 \SpecialChar ~
27047 \SpecialChar ~
27048 \SpecialChar ~
27049 \SpecialChar ~
27050 \SpecialChar ~
27051 \SpecialChar ~
27052 \SpecialChar ~
27053 \SpecialChar ~
27054 \SpecialChar ~
27055 \SpecialChar ~
27056 \SpecialChar ~
27057 \SpecialChar ~
27058 \SpecialChar ~
27059 \SpecialChar ~
27060 \SpecialChar ~
27061 \SpecialChar ~
27062 \SpecialChar ~
27063 \SpecialChar ~
27064 \SpecialChar ~
27065 \SpecialChar ~
27066 \SpecialChar ~
27067 \SpecialChar ~
27068 \SpecialChar ~
27069 \SpecialChar ~
27070 \SpecialChar ~
27071  95 ;\SpecialChar ~
27072  hob.c 17
27073 \newline
27074 003D 85*04*08\SpecialChar ~
27075 \SpecialChar ~
27076 \SpecialChar ~
27077 \SpecialChar ~
27078 \SpecialChar ~
27079 \SpecialChar ~
27080 \SpecialChar ~
27081 \SpecialChar ~
27082 \SpecialChar ~
27083 \SpecialChar ~
27084 \SpecialChar ~
27085 \SpecialChar ~
27086  96\SpecialChar ~
27087 \SpecialChar ~
27088 \SpecialChar ~
27089 \SpecialChar ~
27090 \SpecialChar ~
27091 \SpecialChar ~
27092 \SpecialChar ~
27093 \SpecialChar ~
27094  mov\SpecialChar ~
27095 \SpecialChar ~
27096  _foo_how1_1_1,(_glong + 2)
27097 \newline
27098 0040 85*05*09\SpecialChar ~
27099 \SpecialChar ~
27100 \SpecialChar ~
27101 \SpecialChar ~
27102 \SpecialChar ~
27103 \SpecialChar ~
27104 \SpecialChar ~
27105 \SpecialChar ~
27106 \SpecialChar ~
27107 \SpecialChar ~
27108 \SpecialChar ~
27109 \SpecialChar ~
27110  97\SpecialChar ~
27111 \SpecialChar ~
27112 \SpecialChar ~
27113 \SpecialChar ~
27114 \SpecialChar ~
27115 \SpecialChar ~
27116 \SpecialChar ~
27117 \SpecialChar ~
27118  mov\SpecialChar ~
27119 \SpecialChar ~
27120  (_foo_how1_1_1 + 1),(_glong + 3)
27121 \newline
27122 0043 85*03*0A\SpecialChar ~
27123 \SpecialChar ~
27124 \SpecialChar ~
27125 \SpecialChar ~
27126 \SpecialChar ~
27127 \SpecialChar ~
27128 \SpecialChar ~
27129 \SpecialChar ~
27130 \SpecialChar ~
27131 \SpecialChar ~
27132 \SpecialChar ~
27133 \SpecialChar ~
27134  98\SpecialChar ~
27135 \SpecialChar ~
27136 \SpecialChar ~
27137 \SpecialChar ~
27138 \SpecialChar ~
27139 \SpecialChar ~
27140 \SpecialChar ~
27141 \SpecialChar ~
27142  mov\SpecialChar ~
27143 \SpecialChar ~
27144  _foo_how2_1_1,(_glong + 1)
27145 \newline
27146 0046 85*04*0B\SpecialChar ~
27147 \SpecialChar ~
27148 \SpecialChar ~
27149 \SpecialChar ~
27150 \SpecialChar ~
27151 \SpecialChar ~
27152 \SpecialChar ~
27153 \SpecialChar ~
27154 \SpecialChar ~
27155 \SpecialChar ~
27156 \SpecialChar ~
27157 \SpecialChar ~
27158  99\SpecialChar ~
27159 \SpecialChar ~
27160 \SpecialChar ~
27161 \SpecialChar ~
27162 \SpecialChar ~
27163 \SpecialChar ~
27164 \SpecialChar ~
27165 \SpecialChar ~
27166  mov\SpecialChar ~
27167 \SpecialChar ~
27168  (_foo_how2_1_1 + 1),(_glong + 2)
27169 \layout Standard
27170
27171 Again, variations of these cases may
27172 \emph on
27173 not
27174 \emph default
27175  be recognized.
27176  They are standard C expressions, so I heartily recommend these be the only
27177  way to get the higher order byte/word, (it is portable).
27178  Of course it will be recognized even if it is embedded in other expressions,
27179  e.g.:
27180 \layout Verse
27181
27182
27183 \family typewriter
27184 xyz = gint + ((gint >> 8) & 0xFF);
27185 \layout Standard
27186
27187 will still be recognized.
27188 \layout Subsection
27189
27190 Peephole Optimizer
27191 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
27192
27193 \end_inset
27194
27195
27196 \begin_inset LatexCommand \index{Peephole optimizer}
27197
27198 \end_inset
27199
27200
27201 \layout Standard
27202
27203 The compiler uses a rule based, pattern matching and re-writing mechanism
27204  for peep-hole optimization.
27205  It is inspired by
27206 \emph on
27207 copt
27208 \emph default
27209  a peep-hole optimizer by Christopher W.
27210  Fraser (cwfraser\SpecialChar ~
27211 @\SpecialChar ~
27212 microsoft.com).
27213  A default set of rules are compiled into the compiler, additional rules
27214  may be added with the
27215 \emph on
27216 -
27217 \begin_inset ERT
27218 status Collapsed
27219
27220 \layout Standard
27221
27222 \backslash
27223 /
27224 \end_inset
27225
27226 -peep-file
27227 \begin_inset LatexCommand \index{-\/-peep-file}
27228
27229 \end_inset
27230
27231  <filename>
27232 \emph default
27233  option.
27234  The rule language is best illustrated with examples.
27235 \layout Verse
27236
27237
27238 \family typewriter
27239 replace {
27240 \newline
27241 \SpecialChar ~
27242 \SpecialChar ~
27243 mov %1,a
27244 \newline
27245 \SpecialChar ~
27246 \SpecialChar ~
27247 mov a,%1
27248 \newline
27249 } by {
27250 \newline
27251 \SpecialChar ~
27252 \SpecialChar ~
27253 mov %1,a
27254 \newline
27255 }
27256 \layout Standard
27257
27258 The above rule will change the following assembly
27259 \begin_inset LatexCommand \index{Assembler routines}
27260
27261 \end_inset
27262
27263  sequence:
27264 \layout Verse
27265
27266
27267 \family typewriter
27268 mov r1,a
27269 \newline
27270 mov a,r1
27271 \layout Standard
27272
27273 to
27274 \layout Verse
27275
27276
27277 \family typewriter
27278 mov r1,a
27279 \layout Standard
27280
27281 Note: All occurrences of a
27282 \emph on
27283 %n
27284 \emph default
27285  (pattern variable) must denote the same string.
27286  With the above rule, the assembly sequence:
27287 \layout Verse
27288
27289
27290 \family typewriter
27291 mov r1,a
27292 \newline
27293 mov a,r2
27294 \layout Standard
27295
27296 will remain unmodified.
27297 \newline
27298
27299 \newline
27300 Other special case optimizations may be added by the user (via
27301 \emph on
27302 -
27303 \begin_inset ERT
27304 status Collapsed
27305
27306 \layout Standard
27307
27308 \backslash
27309 /
27310 \end_inset
27311
27312 -peep-file option
27313 \emph default
27314 ).
27315  E.g.
27316  some variants of the 8051 MCU
27317 \begin_inset LatexCommand \index{MCS51 variants}
27318
27319 \end_inset
27320
27321  allow only
27322 \family typewriter
27323 ajmp
27324 \family default
27325  and
27326 \family typewriter
27327 acall
27328 \family default
27329 .
27330  The following two rules will change all
27331 \family typewriter
27332 ljmp
27333 \family default
27334  and
27335 \family typewriter
27336 lcall
27337 \family default
27338  to
27339 \family typewriter
27340 ajmp
27341 \family default
27342  and
27343 \family typewriter
27344 acall
27345 \layout Verse
27346
27347
27348 \family typewriter
27349 replace { lcall %1 } by { acall %1 }
27350 \newline
27351 replace { ljmp %1 } by { ajmp %1 }
27352 \layout Standard
27353
27354 The
27355 \emph on
27356 inline-assembler code
27357 \emph default
27358  is also passed through the peep hole optimizer, thus the peephole optimizer
27359  can also be used as an assembly level macro expander.
27360  The rules themselves are MCU dependent whereas the rule language infra-structur
27361 e is MCU independent.
27362  Peephole optimization rules for other MCU can be easily programmed using
27363  the rule language.
27364 \newline
27365
27366 \newline
27367 The syntax for a rule is as follows:
27368 \layout Verse
27369
27370
27371 \family typewriter
27372 rule := replace [ restart ] '{' <assembly sequence> '
27373 \backslash
27374 n'
27375 \newline
27376 \SpecialChar ~
27377  \SpecialChar ~
27378  \SpecialChar ~
27379  \SpecialChar ~
27380  \SpecialChar ~
27381  \SpecialChar ~
27382  \SpecialChar ~
27383  \SpecialChar ~
27384  \SpecialChar ~
27385  \SpecialChar ~
27386  \SpecialChar ~
27387  \SpecialChar ~
27388  \SpecialChar ~
27389  \SpecialChar ~
27390  '}' by '{' '
27391 \backslash
27392 n'
27393 \newline
27394 \SpecialChar ~
27395  \SpecialChar ~
27396  \SpecialChar ~
27397  \SpecialChar ~
27398  \SpecialChar ~
27399  \SpecialChar ~
27400  \SpecialChar ~
27401  \SpecialChar ~
27402  \SpecialChar ~
27403  \SpecialChar ~
27404  \SpecialChar ~
27405  \SpecialChar ~
27406  \SpecialChar ~
27407  \SpecialChar ~
27408  \SpecialChar ~
27409  \SpecialChar ~
27410  <assembly sequence> '
27411 \backslash
27412 n'
27413 \newline
27414 \SpecialChar ~
27415  \SpecialChar ~
27416  \SpecialChar ~
27417  \SpecialChar ~
27418  \SpecialChar ~
27419  \SpecialChar ~
27420  \SpecialChar ~
27421  \SpecialChar ~
27422  \SpecialChar ~
27423  \SpecialChar ~
27424  \SpecialChar ~
27425  \SpecialChar ~
27426  \SpecialChar ~
27427  \SpecialChar ~
27428  '}' [if <functionName> ] '
27429 \backslash
27430 n'
27431 \layout Standard
27432
27433 <assembly sequence> := assembly instruction (each instruction including
27434  labels must be on a separate line).
27435 \newline
27436
27437 \newline
27438 The optimizer will apply to the rules one by one from the top in the sequence
27439  of their appearance, it will terminate when all rules are exhausted.
27440  If the 'restart' option is specified, then the optimizer will start matching
27441  the rules again from the top, this option for a rule is expensive (performance)
27442 , it is intended to be used in situations where a transformation will trigger
27443  the same rule again.
27444  An example of this (not a good one, it has side effects) is the following
27445  rule:
27446 \layout Verse
27447
27448
27449 \family typewriter
27450 replace restart {
27451 \newline
27452 \SpecialChar ~
27453 \SpecialChar ~
27454 pop %1
27455 \newline
27456 \SpecialChar ~
27457 \SpecialChar ~
27458 push %1 } by {
27459 \newline
27460 \SpecialChar ~
27461 \SpecialChar ~
27462 ; nop
27463 \newline
27464 }
27465 \layout Standard
27466
27467 Note that the replace pattern cannot be a blank, but can be a comment line.
27468  Without the 'restart' option only the innermost 'pop' 'push' pair would
27469  be eliminated, i.e.:
27470 \layout Verse
27471
27472
27473 \family typewriter
27474 pop ar1
27475 \newline
27476 pop ar2
27477 \newline
27478 push ar2
27479 \newline
27480 push ar1
27481 \layout Standard
27482
27483 would result in:
27484 \layout Verse
27485
27486
27487 \family typewriter
27488 pop ar1
27489 \newline
27490 ; nop
27491 \newline
27492 push ar1
27493 \layout Standard
27494
27495
27496 \emph on
27497 with
27498 \emph default
27499  the restart option the rule will be applied again to the resulting code
27500  and then all the pop-push pairs will be eliminated to yield:
27501 \layout Verse
27502
27503
27504 \family typewriter
27505 ; nop
27506 \newline
27507 ; nop
27508 \layout Standard
27509
27510 A conditional function can be attached to a rule.
27511  Attaching rules are somewhat more involved, let me illustrate this with
27512  an example.
27513 \layout Verse
27514
27515
27516 \family typewriter
27517 replace {
27518 \newline
27519 \SpecialChar ~
27520  \SpecialChar ~
27521  \SpecialChar ~
27522 ljmp %5
27523 \newline
27524 %2:
27525 \newline
27526 } by {
27527 \newline
27528 \SpecialChar ~
27529  \SpecialChar ~
27530  \SpecialChar ~
27531 sjmp %5
27532 \newline
27533 %2:
27534 \newline
27535 } if labelInRange
27536 \layout Standard
27537
27538 The optimizer does a look-up of a function name table defined in function
27539
27540 \emph on
27541 callFuncByName
27542 \emph default
27543  in the source file SDCCpeeph.c, with the name
27544 \emph on
27545 labelInRange
27546 \emph default
27547 .
27548  If it finds a corresponding entry the function is called.
27549  Note there can be no parameters specified for these functions, in this
27550  case the use of
27551 \emph on
27552 %5
27553 \emph default
27554  is crucial, since the function
27555 \emph on
27556 labelInRange
27557 \emph default
27558  expects to find the label in that particular variable (the hash table containin
27559 g the variable bindings is passed as a parameter).
27560  If you want to code more such functions, take a close look at the function
27561  labelInRange and the calling mechanism in source file SDCCpeeph.c.
27562  Currently implemented are
27563 \emph on
27564 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
27565  24bitMode, portIsDS390, 24bitModeAndPortDS390
27566 \emph default
27567 and
27568 \emph on
27569  notVolatile
27570 \emph default
27571 .
27572 \layout Standard
27573
27574 I know this whole thing is a little kludgey, but maybe some day we will
27575  have some better means.
27576  If you are looking at this file, you will see the default rules that are
27577  compiled into the compiler, you can add your own rules in the default set
27578  there if you get tired of specifying the -
27579 \begin_inset ERT
27580 status Collapsed
27581
27582 \layout Standard
27583
27584 \backslash
27585 /
27586 \end_inset
27587
27588 -peep-file option.
27589 \layout Section
27590
27591 ANSI-Compliance
27592 \begin_inset LatexCommand \index{ANSI-compliance}
27593
27594 \end_inset
27595
27596
27597 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
27598
27599 \end_inset
27600
27601
27602 \layout Standard
27603
27604 Deviations from the compliance:
27605 \layout Itemize
27606
27607 functions are not reentrant
27608 \begin_inset LatexCommand \index{reentrant}
27609
27610 \end_inset
27611
27612  unless explicitly declared as such or the
27613 \series bold
27614 -
27615 \begin_inset ERT
27616 status Collapsed
27617
27618 \layout Standard
27619
27620 \backslash
27621 /
27622 \end_inset
27623
27624 -stack-auto
27625 \begin_inset LatexCommand \index{-\/-stack-auto}
27626
27627 \end_inset
27628
27629
27630 \series default
27631  command line option is specified.
27632 \layout Itemize
27633
27634 structures and unions cannot be assigned values directly, cannot be passed
27635  as function parameters or assigned to each other and cannot be a return
27636  value from a function, e.g.:
27637 \begin_deeper
27638 \layout Verse
27639
27640
27641 \family typewriter
27642 struct s { ...
27643  };
27644 \newline
27645 struct s s1, s2;
27646 \newline
27647 foo()
27648 \newline
27649 {
27650 \newline
27651 \SpecialChar ~
27652 \SpecialChar ~
27653 \SpecialChar ~
27654 \SpecialChar ~
27655 ...
27656
27657 \newline
27658 \SpecialChar ~
27659 \SpecialChar ~
27660 \SpecialChar ~
27661 \SpecialChar ~
27662 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
27663 \newline
27664 \SpecialChar ~
27665 \SpecialChar ~
27666 \SpecialChar ~
27667 \SpecialChar ~
27668 ...
27669
27670 \newline
27671 }
27672 \newline
27673 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
27674  */
27675 \newline
27676 {
27677 \newline
27678 \SpecialChar ~
27679 \SpecialChar ~
27680 \SpecialChar ~
27681 \SpecialChar ~
27682 struct s rets;
27683 \newline
27684 \SpecialChar ~
27685 \SpecialChar ~
27686 \SpecialChar ~
27687 \SpecialChar ~
27688 ...
27689
27690 \newline
27691 \SpecialChar ~
27692 \SpecialChar ~
27693 \SpecialChar ~
27694 \SpecialChar ~
27695 return rets;/* is invalid in SDCC although allowed in ANSI */
27696 \newline
27697 }
27698 \end_deeper
27699 \layout Itemize
27700
27701 initialization of structure arrays must be fully braced.
27702 \begin_deeper
27703 \layout Verse
27704
27705
27706 \family typewriter
27707 struct s { char x } a[] = {1, 2}; /* invalid in SDCC */
27708 \newline
27709 struct s { char x } a[] = {{1}, {2}}; /* OK */
27710 \end_deeper
27711 \layout Itemize
27712
27713 'long long
27714 \begin_inset LatexCommand \index{long long (not supported)}
27715
27716 \end_inset
27717
27718 ' (64 bit integers
27719 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
27720
27721 \end_inset
27722
27723 ) not supported.
27724 \layout Itemize
27725
27726 'double
27727 \begin_inset LatexCommand \index{double (not supported)}
27728
27729 \end_inset
27730
27731 ' precision floating point
27732 \begin_inset LatexCommand \index{Floating point support}
27733
27734 \end_inset
27735
27736 not supported.
27737 \layout Itemize
27738
27739 Old K&R style
27740 \begin_inset LatexCommand \index{K\&R style}
27741
27742 \end_inset
27743
27744  function declarations are NOT allowed.
27745 \begin_deeper
27746 \layout Verse
27747
27748
27749 \family typewriter
27750 foo(i,j) /* this old style of function declarations */
27751 \newline
27752 int i,j; /* are valid in ANSI but not valid in SDCC */
27753 \newline
27754 {
27755 \newline
27756 \SpecialChar ~
27757 \SpecialChar ~
27758 \SpecialChar ~
27759 \SpecialChar ~
27760 ...
27761
27762 \newline
27763 }
27764 \end_deeper
27765 \layout Itemize
27766
27767 Most enhancements in C99 are not supported, f.e.:
27768 \begin_deeper
27769 \layout Verse
27770
27771
27772 \family typewriter
27773 \series bold
27774 inline
27775 \series default
27776  int increment (int a) { return a+1; } /* is invalid in SDCC although allowed
27777  in C99 */
27778 \newline
27779 for (
27780 \series bold
27781 int
27782 \series default
27783  i=0; i<10; i++) /* is invalid in SDCC although allowed in C99 */
27784 \end_deeper
27785 \layout Itemize
27786
27787 Certain words that are valid identifiers in the standard may be reserved
27788  words in SDCC unless the
27789 \series bold
27790 -
27791 \begin_inset ERT
27792 status Collapsed
27793
27794 \layout Standard
27795
27796 \backslash
27797 /
27798 \end_inset
27799
27800 -std-c89
27801 \begin_inset LatexCommand \index{-\/-std-c89}
27802
27803 \end_inset
27804
27805  or -
27806 \begin_inset ERT
27807 status Collapsed
27808
27809 \layout Standard
27810
27811 \backslash
27812 /
27813 \end_inset
27814
27815 -std-c99
27816 \begin_inset LatexCommand \index{-\/-std-c99}
27817
27818 \end_inset
27819
27820
27821 \series default
27822  command line options are used.
27823  These may include (depending on the selected processor): 'at', 'banked',
27824  'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup
27825 t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs',
27826  'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and
27827  '_naked'.
27828  Compliant equivalents of these keywords are always available in a form
27829  that begin with two underscores
27830 \begin_inset LatexCommand \index{\_\_ (prefix for extended keywords)}
27831
27832 \end_inset
27833
27834 , f.e.
27835  '__data' instead of 'data'.
27836 \layout Section
27837
27838 Cyclomatic Complexity
27839 \begin_inset LatexCommand \index{Cyclomatic complexity}
27840
27841 \end_inset
27842
27843
27844 \layout Standard
27845
27846 Cyclomatic complexity of a function is defined as the number of independent
27847  paths the program can take during execution of the function.
27848  This is an important number since it defines the number test cases you
27849  have to generate to validate the function.
27850  The accepted industry standard for complexity number is 10, if the cyclomatic
27851  complexity reported by SDCC exceeds 10 you should think about simplification
27852  of the function logic.
27853  Note that the complexity level is not related to the number of lines of
27854  code in a function.
27855  Large functions can have low complexity, and small functions can have large
27856  complexity levels.
27857
27858 \newline
27859
27860 \newline
27861 SDCC uses the following formula to compute the complexity:
27862 \newline
27863
27864 \layout Standard
27865
27866 complexity = (number of edges in control flow graph) - (number of nodes
27867  in control flow graph) + 2;
27868 \newline
27869
27870 \newline
27871 Having said that the industry standard is 10, you should be aware that in
27872  some cases it be may unavoidable to have a complexity level of less than
27873  10.
27874  For example if you have switch statement with more than 10 case labels,
27875  each case label adds one to the complexity level.
27876  The complexity level is by no means an absolute measure of the algorithmic
27877  complexity of the function, it does however provide a good starting point
27878  for which functions you might look at for further optimization.
27879 \layout Section
27880
27881 Retargetting for other Processors
27882 \layout Standard
27883
27884 The issues for retargetting the compiler are far too numerous to be covered
27885  by this document.
27886  What follows is a brief description of each of the seven phases of the
27887  compiler and its MCU dependency.
27888 \layout Itemize
27889
27890 Parsing the source and building the annotated parse tree.
27891  This phase is largely MCU independent (except for the language extensions).
27892  Syntax & semantic checks are also done in this phase, along with some initial
27893  optimizations like back patching labels and the pattern matching optimizations
27894  like bit-rotation etc.
27895 \layout Itemize
27896
27897 The second phase involves generating an intermediate code which can be easy
27898  manipulated during the later phases.
27899  This phase is entirely MCU independent.
27900  The intermediate code generation assumes the target machine has unlimited
27901  number of registers, and designates them with the name iTemp.
27902  The compiler can be made to dump a human readable form of the code generated
27903  by using the -
27904 \begin_inset ERT
27905 status Collapsed
27906
27907 \layout Standard
27908
27909 \backslash
27910 /
27911 \end_inset
27912
27913 -dumpraw option.
27914 \layout Itemize
27915
27916 This phase does the bulk of the standard optimizations and is also MCU independe
27917 nt.
27918  This phase can be broken down into several sub-phases:
27919 \newline
27920
27921 \newline
27922 Break down intermediate code (iCode) into basic blocks.
27923 \newline
27924 Do control flow & data flow analysis on the basic blocks.
27925 \newline
27926 Do local common subexpression elimination, then global subexpression elimination
27927 \newline
27928 Dead code elimination
27929 \newline
27930 Loop optimizations
27931 \newline
27932 If loop optimizations caused any changes then do 'global subexpression eliminati
27933 on' and 'dead code elimination' again.
27934 \layout Itemize
27935
27936 This phase determines the live-ranges; by live range I mean those iTemp
27937  variables defined by the compiler that still survive after all the optimization
27938 s.
27939  Live range analysis
27940 \begin_inset LatexCommand \index{Live range analysis}
27941
27942 \end_inset
27943
27944  is essential for register allocation, since these computation determines
27945  which of these iTemps will be assigned to registers, and for how long.
27946 \layout Itemize
27947
27948 Phase five is register allocation.
27949  There are two parts to this process.
27950 \newline
27951
27952 \newline
27953 The first part I call 'register packing' (for lack of a better term).
27954  In this case several MCU specific expression folding is done to reduce
27955  register pressure.
27956 \newline
27957
27958 \newline
27959 The second part is more MCU independent and deals with allocating registers
27960  to the remaining live ranges.
27961  A lot of MCU specific code does creep into this phase because of the limited
27962  number of index registers available in the 8051.
27963 \layout Itemize
27964
27965 The Code generation phase is (unhappily), entirely MCU dependent and very
27966  little (if any at all) of this code can be reused for other MCU.
27967  However the scheme for allocating a homogenized assembler operand for each
27968  iCode operand may be reused.
27969 \layout Itemize
27970
27971 As mentioned in the optimization section the peep-hole optimizer is rule
27972  based system, which can reprogrammed for other MCUs.
27973 \layout Chapter
27974
27975 Compiler internals
27976 \begin_inset LatexCommand \index{Compiler internals}
27977
27978 \end_inset
27979
27980
27981 \layout Section
27982
27983 The anatomy of the compiler
27984 \begin_inset LatexCommand \label{sub:The-anatomy-of}
27985
27986 \end_inset
27987
27988
27989 \layout Standard
27990
27991
27992 \shape italic
27993 This is an excerpt from an article published in Circuit Cellar Magazine
27994  in
27995 \series bold
27996 August 2000
27997 \series default
27998 .
27999  It's a little outdated (the compiler is much more efficient now and user/develo
28000 per friendly), but pretty well exposes the guts of it all.
28001 \shape default
28002
28003 \newline
28004
28005 \newline
28006 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
28007  It is fairly easy to retarget for other 8-bit MCU.
28008  Here we take a look at some of the internals of the compiler.
28009
28010 \layout Paragraph*
28011
28012 Parsing
28013 \begin_inset LatexCommand \index{Parsing}
28014
28015 \end_inset
28016
28017
28018 \layout Standard
28019
28020 Parsing the input source file and creating an AST (Annotated Syntax Tree
28021 \begin_inset LatexCommand \index{Annotated syntax tree}
28022
28023 \end_inset
28024
28025 ).
28026  This phase also involves propagating types (annotating each node of the
28027  parse tree with type information) and semantic analysis.
28028  There are some MCU specific parsing rules.
28029  For example the storage classes, the extended storage classes are MCU specific
28030  while there may be a xdata storage class for 8051 there is no such storage
28031  class for z80 or Atmel AVR.
28032  SDCC allows MCU specific storage class extensions, i.e.
28033  xdata will be treated as a storage class specifier when parsing 8051 C
28034  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
28035  C code.
28036 \layout Paragraph*
28037
28038 Generating iCode
28039 \begin_inset LatexCommand \index{iCode}
28040
28041 \end_inset
28042
28043
28044 \layout Standard
28045
28046 Intermediate code generation.
28047  In this phase the AST is broken down into three-operand form (iCode).
28048  These three operand forms are represented as doubly linked lists.
28049  ICode is the term given to the intermediate form generated by the compiler.
28050  ICode example section shows some examples of iCode generated for some simple
28051  C source functions.
28052 \layout Paragraph*
28053
28054 Optimizations
28055 \begin_inset LatexCommand \index{Optimizations}
28056
28057 \end_inset
28058
28059 .
28060 \layout Standard
28061
28062 Bulk of the target independent optimizations is performed in this phase.
28063  The optimizations include constant propagation, common sub-expression eliminati
28064 on, loop invariant code movement, strength reduction of loop induction variables
28065  and dead-code elimination.
28066 \layout Paragraph*
28067
28068 Live range analysis
28069 \begin_inset LatexCommand \index{Live range analysis}
28070
28071 \end_inset
28072
28073
28074 \layout Standard
28075
28076 During intermediate code generation phase, the compiler assumes the target
28077  machine has infinite number of registers and generates a lot of temporary
28078  variables.
28079  The live range computation determines the lifetime of each of these compiler-ge
28080 nerated temporaries.
28081  A picture speaks a thousand words.
28082  ICode example sections show the live range annotations for each of the
28083  operand.
28084  It is important to note here, each iCode is assigned a number in the order
28085  of its execution in the function.
28086  The live ranges are computed in terms of these numbers.
28087  The from number is the number of the iCode which first defines the operand
28088  and the to number signifies the iCode which uses this operand last.
28089 \layout Paragraph*
28090
28091 Register Allocation
28092 \begin_inset LatexCommand \index{Register allocation}
28093
28094 \end_inset
28095
28096
28097 \layout Standard
28098
28099 The register allocation determines the type and number of registers needed
28100  by each operand.
28101  In most MCUs only a few registers can be used for indirect addressing.
28102  In case of 8051 for example the registers R0 & R1 can be used to indirectly
28103  address the internal ram and DPTR to indirectly address the external ram.
28104  The compiler will try to allocate the appropriate register to pointer variables
28105  if it can.
28106  ICode example section shows the operands annotated with the registers assigned
28107  to them.
28108  The compiler will try to keep operands in registers as much as possible;
28109  there are several schemes the compiler uses to do achieve this.
28110  When the compiler runs out of registers the compiler will check to see
28111  if there are any live operands which is not used or defined in the current
28112  basic block being processed, if there are any found then it will push that
28113  operand and use the registers in this block, the operand will then be popped
28114  at the end of the basic block.
28115
28116 \layout Standard
28117
28118 There are other MCU specific considerations in this phase.
28119  Some MCUs have an accumulator; very short-lived operands could be assigned
28120  to the accumulator instead of a general-purpose register.
28121 \layout Paragraph*
28122
28123 Code generation
28124 \layout Standard
28125
28126 Figure II gives a table of iCode operations supported by the compiler.
28127  The code generation involves translating these operations into corresponding
28128  assembly code for the processor.
28129  This sounds overly simple but that is the essence of code generation.
28130  Some of the iCode operations are generated on a MCU specific manner for
28131  example, the z80 port does not use registers to pass parameters so the
28132  SEND and RECV iCode operations will not be generated, and it also does
28133  not support JUMPTABLES.
28134
28135 \newline
28136
28137 \series bold
28138 \shape italic
28139 \color red
28140 <Where is Figure II?>
28141 \layout Comment
28142
28143 In the original article Figure II was announced to be downloadable on
28144 \shape italic
28145 Circuit Cellar
28146 \shape default
28147 's web site.
28148  Unfortunately it never seemed to have shown up there, so: where is Figure
28149  II?
28150 \layout Paragraph*
28151
28152 ICode Example
28153 \begin_inset LatexCommand \index{iCode}
28154
28155 \end_inset
28156
28157
28158 \layout Standard
28159
28160 This section shows some details of iCode.
28161  The example C code does not do anything useful; it is used as an example
28162  to illustrate the intermediate code generated by the compiler.
28163 \layout Verse
28164
28165
28166 \family typewriter
28167 1.\SpecialChar ~
28168 xdata int * p;
28169 \newline
28170 2.\SpecialChar ~
28171 int gint;
28172 \newline
28173 3.\SpecialChar ~
28174 /* This function does nothing useful.
28175  It is used
28176 \newline
28177 4.\SpecialChar ~
28178 \SpecialChar ~
28179 \SpecialChar ~
28180 \SpecialChar ~
28181 for the purpose of explaining iCode */
28182 \newline
28183 5.\SpecialChar ~
28184 short function (data int *x)
28185 \newline
28186 6.\SpecialChar ~
28187 {
28188 \newline
28189 7.\SpecialChar ~
28190 \SpecialChar ~
28191 \SpecialChar ~
28192 short i=10; \SpecialChar ~
28193 \SpecialChar ~
28194 /* dead initialization eliminated */
28195 \newline
28196 8.\SpecialChar ~
28197 \SpecialChar ~
28198 \SpecialChar ~
28199 short sum=10; /* dead initialization eliminated */
28200 \newline
28201 9.\SpecialChar ~
28202 \SpecialChar ~
28203 \SpecialChar ~
28204 short mul;
28205 \newline
28206 10.\SpecialChar ~
28207 \SpecialChar ~
28208 int j ;
28209 \newline
28210 11.\SpecialChar ~
28211 \SpecialChar ~
28212 while (*x) *x++ = *p++;
28213 \newline
28214 12.\SpecialChar ~
28215 \SpecialChar ~
28216 \SpecialChar ~
28217 \SpecialChar ~
28218 sum = 0 ;
28219 \newline
28220 13.\SpecialChar ~
28221 \SpecialChar ~
28222 mul = 0;
28223 \newline
28224 14.\SpecialChar ~
28225 \SpecialChar ~
28226 /* compiler detects i,j to be induction variables */
28227 \newline
28228 15.\SpecialChar ~
28229 \SpecialChar ~
28230 for (i = 0, j = 10 ; i < 10 ; i++, j
28231 \family default
28232 -
28233 \begin_inset ERT
28234 status Collapsed
28235
28236 \layout Standard
28237
28238 \backslash
28239 /
28240 \end_inset
28241
28242 -
28243 \family typewriter
28244 ) {
28245 \newline
28246 16.\SpecialChar ~
28247 \SpecialChar ~
28248 \SpecialChar ~
28249 \SpecialChar ~
28250 sum += i;
28251 \newline
28252 17.\SpecialChar ~
28253 \SpecialChar ~
28254 \SpecialChar ~
28255 \SpecialChar ~
28256 mul += i * 3; \SpecialChar ~
28257 \SpecialChar ~
28258 /* this multiplication remains */
28259 \newline
28260 18.\SpecialChar ~
28261 \SpecialChar ~
28262 \SpecialChar ~
28263 \SpecialChar ~
28264 gint += j * 3;\SpecialChar ~
28265 \SpecialChar ~
28266 /* this multiplication changed to addition */
28267 \newline
28268 19.\SpecialChar ~
28269 \SpecialChar ~
28270 }
28271 \newline
28272 20.\SpecialChar ~
28273 \SpecialChar ~
28274 return sum+mul;
28275 \newline
28276 21.\SpecialChar ~
28277 }
28278 \layout Standard
28279
28280 In addition to the operands each iCode contains information about the filename
28281  and line it corresponds to in the source file.
28282  The first field in the listing should be interpreted as follows:
28283 \newline
28284
28285 \shape italic
28286 \size footnotesize
28287 Filename(linenumber: iCode Execution sequence number : ICode hash table
28288  key : loop depth of the iCode).
28289 \shape default
28290 \size default
28291
28292 \newline
28293 Then follows the human readable form of the ICode operation.
28294  Each operand of this triplet form can be of three basic types a) compiler
28295  generated temporary b) user defined variable c) a constant value.
28296  Note that local variables and parameters are replaced by compiler generated
28297  temporaries.
28298  Live ranges
28299 \begin_inset LatexCommand \index{Live range analysis}
28300
28301 \end_inset
28302
28303  are computed only for temporaries (i.e.
28304  live ranges are not computed for global variables).
28305  Registers
28306 \begin_inset LatexCommand \index{Register allocation}
28307
28308 \end_inset
28309
28310  are allocated for temporaries only.
28311  Operands are formatted in the following manner:
28312 \newline
28313
28314 \shape italic
28315 \size footnotesize
28316 Operand Name [lr live-from : live-to ] { type information } [ registers
28317  allocated ].
28318 \shape default
28319 \size default
28320
28321 \newline
28322 As mentioned earlier the live ranges are computed in terms of the execution
28323  sequence number of the iCodes, for example
28324 \newline
28325 the iTemp0 is live from (i.e.
28326  first defined in iCode with execution sequence number 3, and is last used
28327  in the iCode with sequence number 5).
28328  For induction variables such as iTemp21 the live range computation extends
28329  the lifetime from the start to the end of the loop.
28330 \newline
28331 The register allocator used the live range information to allocate registers,
28332  the same registers may be used for different temporaries if their live
28333  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
28334  iTemp17 since their live ranges do not overlap.
28335  In addition the allocator also takes into consideration the type and usage
28336  of a temporary, for example itemp6 is a pointer to near space and is used
28337  as to fetch data from (i.e.
28338  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
28339  Some short lived temporaries are allocated to special registers which have
28340  meaning to the code generator e.g.
28341  iTemp13 is allocated to a pseudo register CC which tells the back end that
28342  the temporary is used only for a conditional jump the code generation makes
28343  use of this information to optimize a compare and jump ICode.
28344 \newline
28345 There are several loop optimizations
28346 \begin_inset LatexCommand \index{Loop optimization}
28347
28348 \end_inset
28349
28350  performed by the compiler.
28351  It can detect induction variables iTemp21(i) and iTemp23(j).
28352  Also note the compiler does selective strength reduction
28353 \begin_inset LatexCommand \index{Strength reduction}
28354
28355 \end_inset
28356
28357 , i.e.
28358  the multiplication of an induction variable in line 18 (gint = j * 3) is
28359  changed to addition, a new temporary iTemp17 is allocated and assigned
28360  a initial value, a constant 3 is then added for each iteration of the loop.
28361  The compiler does not change the multiplication
28362 \begin_inset LatexCommand \index{Multiplication}
28363
28364 \end_inset
28365
28366  in line 17 however since the processor does support an 8 * 8 bit multiplication.
28367 \newline
28368 Note the dead code elimination
28369 \begin_inset LatexCommand \index{Dead-code elimination}
28370
28371 \end_inset
28372
28373  optimization eliminated the dead assignments in line 7 & 8 to I and sum
28374  respectively.
28375 \newline
28376
28377 \layout Standard
28378
28379
28380 \size footnotesize
28381 Sample.c (5:1:0:0) _entry($9) :
28382 \layout Standard
28383
28384
28385 \size footnotesize
28386 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
28387 \layout Standard
28388
28389
28390 \size footnotesize
28391 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
28392 \layout Standard
28393
28394
28395 \size footnotesize
28396 Sample.c(11:4:53:0) preHeaderLbl0($11) :
28397 \layout Standard
28398
28399
28400 \size footnotesize
28401 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
28402  * int}[r2]
28403 \layout Standard
28404
28405
28406 \size footnotesize
28407 Sample.c(11:6:5:1) _whilecontinue_0($1) :
28408 \layout Standard
28409
28410
28411 \size footnotesize
28412 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
28413  int}[r0]]
28414 \layout Standard
28415
28416
28417 \size footnotesize
28418 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
28419 \layout Standard
28420
28421
28422 \size footnotesize
28423 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
28424  * int}
28425 \layout Standard
28426
28427
28428 \size footnotesize
28429 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
28430  {short}
28431 \layout Standard
28432
28433
28434 \size footnotesize
28435 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
28436  * int}[DPTR]]
28437 \layout Standard
28438
28439
28440 \size footnotesize
28441 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
28442 }[r2 r3]
28443 \layout Standard
28444
28445
28446 \size footnotesize
28447 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
28448  * int}[r0] + 0x2 {short}
28449 \layout Standard
28450
28451
28452 \size footnotesize
28453 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
28454 \layout Standard
28455
28456
28457 \size footnotesize
28458 Sample.c(11:17:21:0)_whilebreak_0($3) :
28459 \layout Standard
28460
28461
28462 \size footnotesize
28463 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
28464 \layout Standard
28465
28466
28467 \size footnotesize
28468 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
28469 \layout Standard
28470
28471
28472 \size footnotesize
28473 Sample.c(15:20:54:0)preHeaderLbl1($13) :
28474 \layout Standard
28475
28476
28477 \size footnotesize
28478 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
28479 \layout Standard
28480
28481
28482 \size footnotesize
28483 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
28484 \layout Standard
28485
28486
28487 \size footnotesize
28488 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
28489 \layout Standard
28490
28491
28492 \size footnotesize
28493 Sample.c(15:24:26:1)_forcond_0($4) :
28494 \layout Standard
28495
28496
28497 \size footnotesize
28498 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
28499  < 0xa {short}
28500 \layout Standard
28501
28502
28503 \size footnotesize
28504 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
28505 \layout Standard
28506
28507
28508 \size footnotesize
28509 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
28510  + ITemp21 [lr21:38]{short}[r4]
28511 \layout Standard
28512
28513
28514 \size footnotesize
28515 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
28516  * 0x3 {short}
28517 \layout Standard
28518
28519
28520 \size footnotesize
28521 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
28522  + iTemp15 [lr29:30]{short}[r1]
28523 \layout Standard
28524
28525
28526 \size footnotesize
28527 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
28528  r0]- 0x3 {short}
28529 \layout Standard
28530
28531
28532 \size footnotesize
28533 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
28534 int}[r7 r0]
28535 \layout Standard
28536
28537
28538 \size footnotesize
28539 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
28540  + 0x1 {short}
28541 \layout Standard
28542
28543
28544 \size footnotesize
28545 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
28546  r6]- 0x1 {short}
28547 \layout Standard
28548
28549
28550 \size footnotesize
28551 Sample.c(19:38:47:1) goto _forcond_0($4)
28552 \layout Standard
28553
28554
28555 \size footnotesize
28556 Sample.c(19:39:48:0)_forbreak_0($7) :
28557 \layout Standard
28558
28559
28560 \size footnotesize
28561 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
28562  + ITemp11 [lr19:40]{short}[r3]
28563 \layout Standard
28564
28565
28566 \size footnotesize
28567 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
28568 \layout Standard
28569
28570
28571 \size footnotesize
28572 Sample.c(20:42:51:0)_return($8) :
28573 \layout Standard
28574
28575
28576 \size footnotesize
28577 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
28578 \size default
28579
28580 \newline
28581
28582 \newline
28583 Finally the code generated for this function:
28584 \newline
28585
28586 \layout Standard
28587
28588
28589 \size footnotesize
28590 .area DSEG (DATA)
28591 \layout Standard
28592
28593
28594 \size footnotesize
28595 _p::
28596 \layout Standard
28597
28598
28599 \size footnotesize
28600 \SpecialChar ~
28601 \SpecialChar ~
28602 .ds 2
28603 \layout Standard
28604
28605
28606 \size footnotesize
28607 _gint::
28608 \layout Standard
28609
28610
28611 \size footnotesize
28612 \SpecialChar ~
28613 \SpecialChar ~
28614 .ds 2
28615 \layout Standard
28616
28617
28618 \size footnotesize
28619 ; sample.c 5
28620 \layout Standard
28621
28622
28623 \size footnotesize
28624 ; ----------------------------------------------
28625 \layout Standard
28626
28627
28628 \size footnotesize
28629 ; function function
28630 \layout Standard
28631
28632
28633 \size footnotesize
28634 ; ----------------------------------------------
28635 \layout Standard
28636
28637
28638 \size footnotesize
28639 _function:
28640 \layout Standard
28641
28642
28643 \size footnotesize
28644 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
28645 \layout Standard
28646
28647
28648 \size footnotesize
28649 \SpecialChar ~
28650 \SpecialChar ~
28651 mov r2,dpl
28652 \layout Standard
28653
28654
28655 \size footnotesize
28656 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
28657 \layout Standard
28658
28659
28660 \size footnotesize
28661 \SpecialChar ~
28662 \SpecialChar ~
28663 mov ar0,r2
28664 \layout Standard
28665
28666
28667 \size footnotesize
28668 ;_whilecontinue_0($1) :
28669 \layout Standard
28670
28671
28672 \size footnotesize
28673 00101$:
28674 \layout Standard
28675
28676
28677 \size footnotesize
28678 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
28679 \layout Standard
28680
28681
28682 \size footnotesize
28683 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
28684 \layout Standard
28685
28686
28687 \size footnotesize
28688 \SpecialChar ~
28689 \SpecialChar ~
28690 mov ar2,@r0
28691 \layout Standard
28692
28693
28694 \size footnotesize
28695 \SpecialChar ~
28696 \SpecialChar ~
28697 inc r0
28698 \layout Standard
28699
28700
28701 \size footnotesize
28702 \SpecialChar ~
28703 \SpecialChar ~
28704 mov ar3,@r0
28705 \layout Standard
28706
28707
28708 \size footnotesize
28709 \SpecialChar ~
28710 \SpecialChar ~
28711 dec r0
28712 \layout Standard
28713
28714
28715 \size footnotesize
28716 \SpecialChar ~
28717 \SpecialChar ~
28718 mov a,r2
28719 \layout Standard
28720
28721
28722 \size footnotesize
28723 \SpecialChar ~
28724 \SpecialChar ~
28725 orl a,r3
28726 \layout Standard
28727
28728
28729 \size footnotesize
28730 \SpecialChar ~
28731 \SpecialChar ~
28732 jz 00103$
28733 \layout Standard
28734
28735
28736 \size footnotesize
28737 00114$:
28738 \layout Standard
28739
28740
28741 \size footnotesize
28742 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
28743 \layout Standard
28744
28745
28746 \size footnotesize
28747 \SpecialChar ~
28748 \SpecialChar ~
28749 mov dpl,_p
28750 \layout Standard
28751
28752
28753 \size footnotesize
28754 \SpecialChar ~
28755 \SpecialChar ~
28756 mov dph,(_p + 1)
28757 \layout Standard
28758
28759
28760 \size footnotesize
28761 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
28762 \layout Standard
28763
28764
28765 \size footnotesize
28766 \SpecialChar ~
28767 \SpecialChar ~
28768 mov a,#0x02
28769 \layout Standard
28770
28771
28772 \size footnotesize
28773 \SpecialChar ~
28774 \SpecialChar ~
28775 add a,_p
28776 \layout Standard
28777
28778
28779 \size footnotesize
28780 \SpecialChar ~
28781 \SpecialChar ~
28782 mov _p,a
28783 \layout Standard
28784
28785
28786 \size footnotesize
28787 \SpecialChar ~
28788 \SpecialChar ~
28789 clr a
28790 \layout Standard
28791
28792
28793 \size footnotesize
28794 \SpecialChar ~
28795 \SpecialChar ~
28796 addc a,(_p + 1)
28797 \layout Standard
28798
28799
28800 \size footnotesize
28801 \SpecialChar ~
28802 \SpecialChar ~
28803 mov (_p + 1),a
28804 \layout Standard
28805
28806
28807 \size footnotesize
28808 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
28809 \layout Standard
28810
28811
28812 \size footnotesize
28813 \SpecialChar ~
28814 \SpecialChar ~
28815 movx a,@dptr
28816 \layout Standard
28817
28818
28819 \size footnotesize
28820 \SpecialChar ~
28821 \SpecialChar ~
28822 mov r2,a
28823 \layout Standard
28824
28825
28826 \size footnotesize
28827 \SpecialChar ~
28828 \SpecialChar ~
28829 inc dptr
28830 \layout Standard
28831
28832
28833 \size footnotesize
28834 \SpecialChar ~
28835 \SpecialChar ~
28836 movx a,@dptr
28837 \layout Standard
28838
28839
28840 \size footnotesize
28841 \SpecialChar ~
28842 \SpecialChar ~
28843 mov r3,a
28844 \layout Standard
28845
28846
28847 \size footnotesize
28848 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
28849 \layout Standard
28850
28851
28852 \size footnotesize
28853 \SpecialChar ~
28854 \SpecialChar ~
28855 mov @r0,ar2
28856 \layout Standard
28857
28858
28859 \size footnotesize
28860 \SpecialChar ~
28861 \SpecialChar ~
28862 inc r0
28863 \layout Standard
28864
28865
28866 \size footnotesize
28867 \SpecialChar ~
28868 \SpecialChar ~
28869 mov @r0,ar3
28870 \layout Standard
28871
28872
28873 \size footnotesize
28874 ; iTemp6 [lr5:16]{_near * int}[r0] =
28875 \layout Standard
28876
28877
28878 \size footnotesize
28879 ; iTemp6 [lr5:16]{_near * int}[r0] +
28880 \layout Standard
28881
28882
28883 \size footnotesize
28884 ; 0x2 {short}
28885 \layout Standard
28886
28887
28888 \size footnotesize
28889 \SpecialChar ~
28890 \SpecialChar ~
28891 inc r0
28892 \layout Standard
28893
28894
28895 \size footnotesize
28896 ; goto _whilecontinue_0($1)
28897 \layout Standard
28898
28899
28900 \size footnotesize
28901 \SpecialChar ~
28902 \SpecialChar ~
28903 sjmp 00101$
28904 \layout Standard
28905
28906
28907 \size footnotesize
28908 ; _whilebreak_0($3) :
28909 \layout Standard
28910
28911
28912 \size footnotesize
28913 00103$:
28914 \layout Standard
28915
28916
28917 \size footnotesize
28918 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
28919 \layout Standard
28920
28921
28922 \size footnotesize
28923 \SpecialChar ~
28924 \SpecialChar ~
28925 mov r2,#0x00
28926 \layout Standard
28927
28928
28929 \size footnotesize
28930 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
28931 \layout Standard
28932
28933
28934 \size footnotesize
28935 \SpecialChar ~
28936 \SpecialChar ~
28937 mov r3,#0x00
28938 \layout Standard
28939
28940
28941 \size footnotesize
28942 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
28943 \layout Standard
28944
28945
28946 \size footnotesize
28947 \SpecialChar ~
28948 \SpecialChar ~
28949 mov r4,#0x00
28950 \layout Standard
28951
28952
28953 \size footnotesize
28954 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
28955 \layout Standard
28956
28957
28958 \size footnotesize
28959 \SpecialChar ~
28960 \SpecialChar ~
28961 mov r5,#0x0A
28962 \layout Standard
28963
28964
28965 \size footnotesize
28966 \SpecialChar ~
28967 \SpecialChar ~
28968 mov r6,#0x00
28969 \layout Standard
28970
28971
28972 \size footnotesize
28973 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
28974 \layout Standard
28975
28976
28977 \size footnotesize
28978 \SpecialChar ~
28979 \SpecialChar ~
28980 mov r7,#0x1E
28981 \layout Standard
28982
28983
28984 \size footnotesize
28985 \SpecialChar ~
28986 \SpecialChar ~
28987 mov r0,#0x00
28988 \layout Standard
28989
28990
28991 \size footnotesize
28992 ; _forcond_0($4) :
28993 \layout Standard
28994
28995
28996 \size footnotesize
28997 00104$:
28998 \layout Standard
28999
29000
29001 \size footnotesize
29002 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
29003 \layout Standard
29004
29005
29006 \size footnotesize
29007 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
29008 \layout Standard
29009
29010
29011 \size footnotesize
29012 \SpecialChar ~
29013 \SpecialChar ~
29014 clr c
29015 \layout Standard
29016
29017
29018 \size footnotesize
29019 \SpecialChar ~
29020 \SpecialChar ~
29021 mov a,r4
29022 \layout Standard
29023
29024
29025 \size footnotesize
29026 \SpecialChar ~
29027 \SpecialChar ~
29028 xrl a,#0x80
29029 \layout Standard
29030
29031
29032 \size footnotesize
29033 \SpecialChar ~
29034 \SpecialChar ~
29035 subb a,#0x8a
29036 \layout Standard
29037
29038
29039 \size footnotesize
29040 \SpecialChar ~
29041 \SpecialChar ~
29042 jnc 00107$
29043 \layout Standard
29044
29045
29046 \size footnotesize
29047 00115$:
29048 \layout Standard
29049
29050
29051 \size footnotesize
29052 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
29053 \layout Standard
29054
29055
29056 \size footnotesize
29057 ; iTemp21 [lr21:38]{short}[r4]
29058 \layout Standard
29059
29060
29061 \size footnotesize
29062 \SpecialChar ~
29063 \SpecialChar ~
29064 mov a,r4
29065 \layout Standard
29066
29067
29068 \size footnotesize
29069 \SpecialChar ~
29070 \SpecialChar ~
29071 add a,r2
29072 \layout Standard
29073
29074
29075 \size footnotesize
29076 \SpecialChar ~
29077 \SpecialChar ~
29078 mov r2,a
29079 \layout Standard
29080
29081
29082 \size footnotesize
29083 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
29084 \layout Standard
29085
29086
29087 \size footnotesize
29088 \SpecialChar ~
29089 \SpecialChar ~
29090 mov b,#0x03
29091 \layout Standard
29092
29093
29094 \size footnotesize
29095 \SpecialChar ~
29096 \SpecialChar ~
29097 mov a,r4
29098 \layout Standard
29099
29100
29101 \size footnotesize
29102 \SpecialChar ~
29103 \SpecialChar ~
29104 mul ab
29105 \layout Standard
29106
29107
29108 \size footnotesize
29109 \SpecialChar ~
29110 \SpecialChar ~
29111 mov r1,a
29112 \layout Standard
29113
29114
29115 \size footnotesize
29116 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
29117 \layout Standard
29118
29119
29120 \size footnotesize
29121 ; iTemp15 [lr29:30]{short}[r1]
29122 \layout Standard
29123
29124
29125 \size footnotesize
29126 \SpecialChar ~
29127 \SpecialChar ~
29128 add a,r3
29129 \layout Standard
29130
29131
29132 \size footnotesize
29133 \SpecialChar ~
29134 \SpecialChar ~
29135 mov r3,a
29136 \layout Standard
29137
29138
29139 \size footnotesize
29140 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
29141 \layout Standard
29142
29143
29144 \size footnotesize
29145 \SpecialChar ~
29146 \SpecialChar ~
29147 mov a,r7
29148 \layout Standard
29149
29150
29151 \size footnotesize
29152 \SpecialChar ~
29153 \SpecialChar ~
29154 add a,#0xfd
29155 \layout Standard
29156
29157
29158 \size footnotesize
29159 \SpecialChar ~
29160 \SpecialChar ~
29161 mov r7,a
29162 \layout Standard
29163
29164
29165 \size footnotesize
29166 \SpecialChar ~
29167 \SpecialChar ~
29168 mov a,r0
29169 \layout Standard
29170
29171
29172 \size footnotesize
29173 \SpecialChar ~
29174 \SpecialChar ~
29175 addc a,#0xff
29176 \layout Standard
29177
29178
29179 \size footnotesize
29180 \SpecialChar ~
29181 \SpecialChar ~
29182 mov r0,a
29183 \layout Standard
29184
29185
29186 \size footnotesize
29187 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
29188 \layout Standard
29189
29190
29191 \size footnotesize
29192 \SpecialChar ~
29193 \SpecialChar ~
29194 mov a,r7
29195 \layout Standard
29196
29197
29198 \size footnotesize
29199 \SpecialChar ~
29200 \SpecialChar ~
29201 add a,_gint
29202 \layout Standard
29203
29204
29205 \size footnotesize
29206 \SpecialChar ~
29207 \SpecialChar ~
29208 mov _gint,a
29209 \layout Standard
29210
29211
29212 \size footnotesize
29213 \SpecialChar ~
29214 \SpecialChar ~
29215 mov a,r0
29216 \layout Standard
29217
29218
29219 \size footnotesize
29220 \SpecialChar ~
29221 \SpecialChar ~
29222 addc a,(_gint + 1)
29223 \layout Standard
29224
29225
29226 \size footnotesize
29227 \SpecialChar ~
29228 \SpecialChar ~
29229 mov (_gint + 1),a
29230 \layout Standard
29231
29232
29233 \size footnotesize
29234 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
29235 \layout Standard
29236
29237
29238 \size footnotesize
29239 \SpecialChar ~
29240 \SpecialChar ~
29241 inc r4
29242 \layout Standard
29243
29244
29245 \size footnotesize
29246 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
29247 \layout Standard
29248
29249
29250 \size footnotesize
29251 \SpecialChar ~
29252 \SpecialChar ~
29253 dec r5
29254 \layout Standard
29255
29256
29257 \size footnotesize
29258 \SpecialChar ~
29259 \SpecialChar ~
29260 cjne r5,#0xff,00104$
29261 \layout Standard
29262
29263
29264 \size footnotesize
29265 \SpecialChar ~
29266 \SpecialChar ~
29267 dec r6
29268 \layout Standard
29269
29270
29271 \size footnotesize
29272 ; goto _forcond_0($4)
29273 \layout Standard
29274
29275
29276 \size footnotesize
29277 \SpecialChar ~
29278 \SpecialChar ~
29279 sjmp 00104$
29280 \layout Standard
29281
29282
29283 \size footnotesize
29284 ; _forbreak_0($7) :
29285 \layout Standard
29286
29287
29288 \size footnotesize
29289 00107$:
29290 \layout Standard
29291
29292
29293 \size footnotesize
29294 ; ret iTemp24 [lr40:41]{short}
29295 \layout Standard
29296
29297
29298 \size footnotesize
29299 \SpecialChar ~
29300 \SpecialChar ~
29301 mov a,r3
29302 \layout Standard
29303
29304
29305 \size footnotesize
29306 \SpecialChar ~
29307 \SpecialChar ~
29308 add a,r2
29309 \layout Standard
29310
29311
29312 \size footnotesize
29313 \SpecialChar ~
29314 \SpecialChar ~
29315 mov dpl,a
29316 \layout Standard
29317
29318
29319 \size footnotesize
29320 ; _return($8) :
29321 \layout Standard
29322
29323
29324 \size footnotesize
29325 00108$:
29326 \layout Standard
29327
29328
29329 \size footnotesize
29330 \SpecialChar ~
29331 \SpecialChar ~
29332 ret
29333 \newline
29334
29335 \layout Section
29336
29337 A few words about basic block successors, predecessors and dominators
29338 \layout Standard
29339
29340 Successors are basic blocks
29341 \begin_inset LatexCommand \index{Basic blocks}
29342
29343 \end_inset
29344
29345  that might execute after this basic block.
29346 \newline
29347 Predecessors are basic blocks that might execute before reaching this basic
29348  block.
29349 \newline
29350 Dominators are basic blocks that WILL execute before reaching this basic
29351  block.
29352 \newline
29353
29354 \layout Standard
29355
29356 [basic block 1]
29357 \layout Standard
29358
29359 if (something)
29360 \layout Standard
29361
29362 \SpecialChar ~
29363 \SpecialChar ~
29364 \SpecialChar ~
29365 \SpecialChar ~
29366 [basic block 2]
29367 \layout Standard
29368
29369 else
29370 \layout Standard
29371
29372 \SpecialChar ~
29373 \SpecialChar ~
29374 \SpecialChar ~
29375 \SpecialChar ~
29376 [basic block 3]
29377 \layout Standard
29378
29379 [basic block 4]
29380 \newline
29381
29382 \layout Standard
29383
29384 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
29385 \layout Standard
29386
29387 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
29388 \layout Standard
29389
29390 c) domVect of [BB4] = BB1 ...
29391  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
29392  was executed.
29393 \layout Chapter
29394
29395 Acknowledgments
29396 \layout Standard
29397
29398
29399 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
29400
29401 \end_inset
29402
29403
29404 \newline
29405
29406 \newline
29407
29408 \emph on
29409 Thanks to all the other volunteer developers who have helped with coding,
29410  testing, web-page creation, distribution sets, etc.
29411  You know who you are :-)
29412 \emph default
29413
29414 \newline
29415
29416 \layout Standard
29417
29418 This document was initially written by Sandeep Dutta
29419 \layout Standard
29420
29421 All product names mentioned herein may be trademarks
29422 \begin_inset LatexCommand \index{Trademarks}
29423
29424 \end_inset
29425
29426  of their respective companies.
29427
29428 \layout Section*
29429
29430 Alphabetical index
29431 \layout Standard
29432
29433 To avoid confusion, the installation and building options for SDCC itself
29434  (chapter 2) are not part of the index.
29435 \layout Standard
29436
29437
29438 \begin_inset LatexCommand \printindex{}
29439
29440 \end_inset
29441
29442
29443 \the_end