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.6.1
  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 retargeted for other microprocessors, support for Microchip PIC,
 146  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 retargetable 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
 583 \newline
 584
 585 \newline
 586 The latest version can be downloaded from
 587 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
 588
 589 \end_inset
 590
 591 .
 592
 593 \series bold
 594
 595 \series default
 596 \emph on
 597 Please note: the compiler will probably always be some steps ahead of this
 598  documentation
 599 \series bold
 600 \emph default
 601
 602 \begin_inset LatexCommand \index{Status of documentation}
 603
 604 \end_inset
 605
 606
 607 \begin_inset Foot
 608 collapsed false
 609
 610 \layout Standard
 611
 612 Obviously this has pros and cons
 613 \end_inset
 614
 615 .
 616 \layout Section
 617
 618 Open Source
 619 \layout Standard
 620
 621 All packages used in this compiler system are
 622 \emph on
 623 open source
 624 \emph default
 625  and
 626 \emph on
 627 freeware
 628 \emph default
 629 ; source code for all the sub-packages (pre-processor, assemblers, linkers
 630  etc) is distributed with the package.
 631  This documentation is maintained using a freeware word processor (LyX).
 632 \newline
 633 This program is free software; you can redistribute it and/or modify it
 634  under the terms of the GNU General Public License
 635 \begin_inset LatexCommand \index{GNU General Public License, GPL}
 636
 637 \end_inset
 638
 639  as published by the Free Software Foundation; either version 2, or (at
 640  your option) any later version.
 641  This program is distributed in the hope that it will be useful, but WITHOUT
 642  ANY WARRANTY; without even the implied warranty
 643 \begin_inset LatexCommand \index{warranty}
 644
 645 \end_inset
 646
 647  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 648  See the GNU General Public License for more details.
 649  You should have received a copy of the GNU General Public License along
 650  with this program; if not, write to the Free Software Foundation, 59 Temple
 651  Place - Suite 330, Boston, MA 02111-1307, USA.
 652  In other words, you are welcome to use, share and improve this program.
 653  You are forbidden to forbid anyone else to use, share and improve what
 654  you give them.
 655  Help stamp out software-hoarding!
 656 \layout Section
 657
 658 Typographic conventions
 659 \begin_inset LatexCommand \index{Typographic conventions}
 660
 661 \end_inset
 662
 663
 664 \layout Standard
 665
 666 Throughout this manual, we will use the following convention.
 667  Commands you have to type in are printed in
 668 \family sans
 669 \series bold
 670 "sans serif"
 671 \series default
 672 .
 673
 674 \family default
 675  Code samples are printed in
 676 \family typewriter
 677 typewriter font.
 678
 679 \family default
 680  Interesting items and new terms are printed in
 681 \emph on
 682 italic.
 683 \layout Section
 684
 685 Compatibility
 686 \begin_inset LatexCommand \label{sec:Compatibility-with-previous}
 687
 688 \end_inset
 689
 690  with previous versions
 691 \begin_inset LatexCommand \index{Compatibility with previous versions}
 692
 693 \end_inset
 694
 695
 696 \layout Standard
 697
 698 This version has numerous bug fixes compared with the previous version.
 699  But we also introduced some incompatibilities with older versions.
 700  Not just for the fun of it, but to make the compiler more stable, efficient
 701  and ANSI compliant
 702 \begin_inset LatexCommand \index{ANSI-compliance}
 703
 704 \end_inset
 705
 706  (see section
 707 \begin_inset LatexCommand \ref{sub:ANSI-Compliance}
 708
 709 \end_inset
 710
 711  for ANSI-Compliance).
 712
 713 \newline
 714
 715 \layout Itemize
 716
 717 short is now equivalent to int (16 bits), it used to be equivalent to char
 718  (8 bits) which is not ANSI compliant.
 719 \layout Itemize
 720
 721 the default directory for gcc-builds where include, library and documentation
 722  files are stored is now in /usr/local/share.
 723 \layout Itemize
 724
 725 char type parameters to vararg functions are casted to int unless explicitly
 726  casted, e.g.:
 727 \newline
 728
 729 \family typewriter
 730 \SpecialChar ~
 731 \SpecialChar ~
 732 char a=3;
 733 \newline
 734 \SpecialChar ~
 735 \SpecialChar ~
 736 printf ("%d %c
 737 \backslash
 738 n", a, (char)a);
 739 \family default
 740
 741 \newline
 742  will push a as an int and as a char resp.
 743 \layout Itemize
 744
 745 option -
 746 \begin_inset ERT
 747 status Collapsed
 748
 749 \layout Standard
 750
 751 \backslash
 752 /
 753 \end_inset
 754
 755 -regextend has been removed.
 756 \layout Itemize
 757
 758 option -
 759 \begin_inset ERT
 760 status Collapsed
 761
 762 \layout Standard
 763
 764 \backslash
 765 /
 766 \end_inset
 767
 768 -noregparms has been removed.
 769 \layout Itemize
 770
 771 option -
 772 \begin_inset ERT
 773 status Collapsed
 774
 775 \layout Standard
 776
 777 \backslash
 778 /
 779 \end_inset
 780
 781 -stack-after-data has been removed.
 782 \layout Itemize
 783
 784 bit
 785 \begin_inset LatexCommand \index{bit}
 786
 787 \end_inset
 788
 789  and sbit
 790 \begin_inset LatexCommand \index{sbit}
 791
 792 \end_inset
 793
 794
 795 \begin_inset LatexCommand \index{\_\_sbit}
 796
 797 \end_inset
 798
 799  types now consistently behave like the C99 _Bool type with respect to type
 800  conversion
 801 \begin_inset LatexCommand \index{type conversion}
 802
 803 \end_inset
 804
 805
 806 \begin_inset LatexCommand \index{type promotion}
 807
 808 \end_inset
 809
 810 .
 811  The most common incompatibility resulting from this change is related to
 812  bit toggling
 813 \begin_inset LatexCommand \index{Bit toggling}
 814
 815 \end_inset
 816
 817  idioms, e.g.:
 818 \newline
 819
 820 \family typewriter
 821 \SpecialChar ~
 822 \SpecialChar ~
 823 bit b;
 824 \newline
 825 \SpecialChar ~
 826 \SpecialChar ~
 827 b = ~b; /* equivalent to b=1 instead of toggling b */
 828 \begin_inset Marginal
 829 collapsed false
 830
 831 \layout Standard
 832
 833
 834 \series bold
 835 \SpecialChar ~
 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 detailed 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 using Cygwin and Mingw32
3413 \layout Standard
3414
3415 For building and installing a Cygwin executable follow the instructions
3416  for Linux.
3417 \newline
3418
3419 \newline
3420 On Cygwin a
3421 \begin_inset Quotes sld
3422 \end_inset
3423
3424 native
3425 \begin_inset Quotes srd
3426 \end_inset
3427
3428  Win32-binary can be built, which will not need the Cygwin-DLL.
3429  For the necessary 'configure' options see section 'configure options' or
3430  the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'.
3431 \newline
3432
3433 \newline
3434 In order to install Cygwin on Windows download setup.exe from
3435 \begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
3436
3437 \end_inset
3438
3439 .
3440  Run it, set the
3441 \begin_inset Quotes sld
3442 \end_inset
3443
3444 default text file type
3445 \begin_inset Quotes srd
3446 \end_inset
3447
3448  to
3449 \begin_inset Quotes sld
3450 \end_inset
3451
3452 unix
3453 \begin_inset Quotes srd
3454 \end_inset
3455
3456  and download/install at least the following packages.
3457  Some packages are selected by default, others will be automatically selected
3458  because of dependencies with the manually selected packages.
3459  Never deselect these packages!
3460 \layout Itemize
3461
3462 flex
3463 \layout Itemize
3464
3465 bison
3466 \layout Itemize
3467
3468 gcc ; version 3.x is fine, no need to use the old 2.9x
3469 \layout Itemize
3470
3471 binutils ; selected with gcc
3472 \layout Itemize
3473
3474 make
3475 \layout Itemize
3476
3477 rxvt ; a nice console, which makes life much easier under windoze (see below)
3478 \layout Itemize
3479
3480 man ; not really needed for building SDCC, but you'll miss it sooner or
3481  later
3482 \layout Itemize
3483
3484 less ; not really needed for building SDCC, but you'll miss it sooner or
3485  later
3486 \layout Itemize
3487
3488 svn ; only if you use Subversion access
3489 \layout Standard
3490
3491 If you want to develop something you'll need:
3492 \layout Itemize
3493
3494 python ; for the regression tests
3495 \layout Itemize
3496
3497 gdb ; the gnu debugger, together with the nice GUI
3498 \begin_inset Quotes sld
3499 \end_inset
3500
3501 insight
3502 \begin_inset Quotes srd
3503 \end_inset
3504
3505
3506 \layout Itemize
3507
3508 openssh ; to access the CF or commit changes
3509 \layout Itemize
3510
3511 autoconf and autoconf-devel ; if you want to fight with 'configure', don't
3512  use autoconf-stable!
3513 \layout Standard
3514
3515 rxvt is a nice console with history.
3516  Replace in your cygwin.bat the line
3517 \layout LyX-Code
3518
3519 bash -
3520 \begin_inset ERT
3521 status Collapsed
3522
3523 \layout Standard
3524
3525 \backslash
3526 /
3527 \end_inset
3528
3529 -login -i
3530 \layout Standard
3531
3532 with (one line):
3533 \layout LyX-Code
3534
3535 rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
3536 \layout LyX-Code
3537
3538      -bg black -fg white -geometry 100x65 -e bash -
3539 \begin_inset ERT
3540 status Collapsed
3541
3542 \layout Standard
3543
3544 \backslash
3545 /
3546 \end_inset
3547
3548 -login
3549 \layout Standard
3550
3551 Text selected with the mouse is automatically copied to the clipboard, pasting
3552  works with shift-insert.
3553 \newline
3554
3555 \newline
3556 The other good tip is to make sure you have no //c/-style paths anywhere,
3557  use /cygdrive/c/ instead.
3558  Using // invokes a network lookup which is very slow.
3559  If you think
3560 \begin_inset Quotes sld
3561 \end_inset
3562
3563 cygdrive
3564 \begin_inset Quotes srd
3565 \end_inset
3566
3567  is too long, you can change it with e.g.
3568 \layout LyX-Code
3569
3570 mount -s -u -c /mnt
3571 \layout Standard
3572
3573 SDCC sources use the unix line ending LF.
3574  Life is much easier, if you store the source tree on a drive which is mounted
3575  in binary mode.
3576  And use an editor which can handle LF-only line endings.
3577  Make sure not to commit files with windows line endings.
3578  The tabulator spacing
3579 \begin_inset LatexCommand \index{tabulator spacing (8 columns)}
3580
3581 \end_inset
3582
3583  used in the project is 8.
3584  Although a tabulator spacing of 8 is a sensible choice for programmers
3585  (it's a power of 2 and allows to display 8/16 bit signed variables without
3586  loosing columns) the plan is to move towards using only spaces in the source.
3587 \layout Subsection
3588
3589 Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
3590 \layout Standard
3591
3592
3593 \series medium
3594 Download the source package
3595 \series default
3596  either from the SDCC Subversion repository or from the
3597 \begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
3598
3599 \end_inset
3600
3601
3602 \series medium
3603 , it will be named something like sdcc
3604 \series default
3605 .src
3606 \series medium
3607 .tgz.
3608
3609 \series default
3610  SDCC is distributed with all the projects, workspaces, and files you need
3611  to build it using Visual C++ 6.0/NET (except for SDCDB and ucSim).
3612  The workspace name is 'sdcc.dsw'.
3613  Please note that as it is now, all the executables are created in a folder
3614  called sdcc
3615 \backslash
3616 bin_vc.
3617  Once built you need to copy the executables from sdcc
3618 \backslash
3619 bin_vc to sdcc
3620 \backslash
3621 bin before running SDCC.
3622
3623 \newline
3624
3625 \newline
3626 WARNING: Visual studio is very picky with line terminations; it expects
3627  the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings.
3628  When using the Subversion repository it's easiest to configure the svn
3629  client to convert automatically for you.
3630  If however you are getting a message such as "This makefile was not generated
3631  by Developer Studio etc.
3632  etc.
3633 \begin_inset Quotes srd
3634 \end_inset
3635
3636  when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
3637  need to convert the Unix style line endings to DOS style line endings.
3638  To do so you can use the
3639 \begin_inset Quotes sld
3640 \end_inset
3641
3642 unix2dos
3643 \begin_inset Quotes srd
3644 \end_inset
3645
3646  utility freely available on the internet.
3647  Doug Hawkins reported in the sdcc-user list that this works:
3648 \newline
3649
3650 \newline
3651 C:
3652 \backslash
3653 Programming
3654 \backslash
3655 SDCC> unix2dos sdcc.dsw
3656 \newline
3657 C:
3658 \backslash
3659 Programming
3660 \backslash
3661 SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
3662 \newline
3663
3664 \newline
3665 In order to build SDCC with MSVC you need win32 executables of bison.exe,
3666  flex.exe, and gawk.exe.
3667  One good place to get them is
3668 \begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
3669
3670 \end_inset
3671
3672
3673 \newline
3674
3675 \newline
3676 Download the file UnxUtils
3677 \begin_inset LatexCommand \index{UnxUtils}
3678
3679 \end_inset
3680
3681 .zip.
3682  Now you have to install the utilities and setup MSVC so it can locate the
3683  required programs.
3684  Here there are two alternatives (choose one!):
3685 \layout Enumerate
3686
3687 The easy way:
3688 \newline
3689
3690 \newline
3691 a) Extract UnxUtils.zip to your C:
3692 \backslash
3693  hard disk PRESERVING the original paths, otherwise bison won't work.
3694  (If you are using WinZip make certain that 'Use folder names' is selected)
3695 \newline
3696
3697 \newline
3698 b) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3699  in 'Show directories for:' select 'Executable files', and in the directories
3700  window add a new path: 'C:
3701 \backslash
3702 user
3703 \backslash
3704 local
3705 \backslash
3706 wbin', click ok.
3707 \newline
3708
3709 \newline
3710 (As a side effect, you get a bunch of Unix utilities that could be useful,
3711  such as diff and patch.)
3712 \layout Enumerate
3713
3714 A more compact way:
3715 \newline
3716
3717 \newline
3718 This one avoids extracting a bunch of files you may not use, but requires
3719  some extra work:
3720 \newline
3721
3722 \newline
3723 a) Create a directory were to put the tools needed, or use a directory already
3724  present.
3725  Say for example 'C:
3726 \backslash
3727 util'.
3728 \newline
3729
3730 \newline
3731 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
3732  to such directory WITHOUT preserving the original paths.
3733  (If you are using WinZip make certain that 'Use folder names' is not selected)
3734 \newline
3735
3736 \newline
3737 c) Rename bison.exe to '_bison.exe'.
3738 \newline
3739
3740 \newline
3741 d) Create a batch file 'bison.bat' in 'C:
3742 \backslash
3743 util
3744 \backslash
3745 ' and add these lines:
3746 \newline
3747 \SpecialChar ~
3748 \SpecialChar ~
3749 set BISON_SIMPLE=C:
3750 \backslash
3751 util
3752 \backslash
3753 bison.simple
3754 \newline
3755 \SpecialChar ~
3756 \SpecialChar ~
3757 set BISON_HAIRY=C:
3758 \backslash
3759 util
3760 \backslash
3761 bison.hairy
3762 \newline
3763 \SpecialChar ~
3764 \SpecialChar ~
3765 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
3766 \newline
3767
3768 \newline
3769 Steps 'c' and 'd' are needed because bison requires by default that the
3770  files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory,
3771  '/usr/local/share/' I think.
3772  So it is necessary to tell bison where those files are located if they
3773  are not in such directory.
3774  That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
3775 \newline
3776
3777 \newline
3778 e) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3779  in 'Show directories for:' select 'Executable files', and in the directories
3780  window add a new path: 'c:
3781 \backslash
3782 util', click ok.
3783  Note that you can use any other path instead of 'c:
3784 \backslash
3785 util', even the path where the Visual C++ tools are, probably: 'C:
3786 \backslash
3787 Program Files
3788 \backslash
3789 Microsoft Visual Studio
3790 \backslash
3791 Common
3792 \backslash
3793 Tools'.
3794  So you don't have to execute step 'e' :)
3795 \layout Standard
3796
3797 That is it.
3798  Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
3799  the executables from sdcc
3800 \backslash
3801 bin_vc to sdcc
3802 \backslash
3803 bin, and you can compile using SDCC.
3804 \layout Subsection
3805
3806 Building SDCC Using Borland
3807 \layout Enumerate
3808
3809 From the sdcc directory, run the command "make -f Makefile.bcc".
3810  This should regenerate all the .exe files in the bin directory except for
3811  SDCDB and ucSim.
3812 \layout Enumerate
3813
3814 If you modify any source files and need to rebuild, be aware that the dependenci
3815 es may not be correctly calculated.
3816  The safest option is to delete all .obj files and run the build again.
3817  From a Cygwin BASH prompt, this can easily be done with the command (be
3818  sure you are in the sdcc directory):
3819 \newline
3820
3821 \newline
3822
3823 \family sans
3824 \series bold
3825 find .
3826
3827 \backslash
3828 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
3829 \backslash
3830 ) -print -exec rm {}
3831 \backslash
3832 ;
3833 \family default
3834 \series default
3835
3836 \newline
3837
3838 \newline
3839 or on Windows NT/2000/XP from the command prompt with the command:
3840 \newline
3841
3842 \family sans
3843 \series bold
3844
3845 \newline
3846 del /s *.obj *.lib *.rul
3847 \family default
3848 \series default
3849  from the sdcc directory.
3850 \layout Subsection
3851
3852 Windows Install Using a ZIP Package
3853 \layout Enumerate
3854
3855 Download the binary zip package from
3856 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3857
3858 \end_inset
3859
3860  and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
3861  This should unpack to a group of sub-directories.
3862  An example directory structure after unpacking the mingw32 package is:
3863  c:
3864 \backslash
3865 sdcc
3866 \backslash
3867 bin for the executables, c:
3868 \backslash
3869 sdcc
3870 \backslash
3871 include and c:
3872 \backslash
3873 sdcc
3874 \backslash
3875 lib for the include and libraries.
3876 \layout Enumerate
3877
3878 Adjust your environment variable PATH to include the location of the bin
3879  directory or start sdcc using the full path.
3880 \layout Subsection
3881
3882 Windows Install Using the Setup Program
3883 \begin_inset LatexCommand \label{sub:Windows-Install}
3884
3885 \end_inset
3886
3887
3888 \layout Standard
3889
3890 Download the setup program
3891 \emph on
3892 sdcc-x.y.z-setup.exe
3893 \emph default
3894  for an official release from
3895 \newline
3896
3897 \begin_inset LatexCommand \url{http://sf.net/project/showfiles.php?group_id=599}
3898
3899 \end_inset
3900
3901  or a setup program for one of the snapshots
3902 \emph on
3903 sdcc-yyyymmdd-xxxx-setup.exe
3904 \emph default
3905  from
3906 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3907
3908 \end_inset
3909
3910  and execute it.
3911  A windows typical installer will guide you through the installation process.
3912 \layout Subsection
3913
3914 VPATH
3915 \begin_inset LatexCommand \index{VPATH}
3916
3917 \end_inset
3918
3919  feature
3920 \layout Standard
3921
3922 SDCC supports the VPATH feature provided by configure and make.
3923  It allows to separate the source and build trees.
3924  Here's an example:
3925 \layout Standard
3926
3927
3928 \family typewriter
3929 cd ~\SpecialChar ~
3930 \SpecialChar ~
3931 \SpecialChar ~
3932 \SpecialChar ~
3933 \SpecialChar ~
3934 \SpecialChar ~
3935 \SpecialChar ~
3936 \SpecialChar ~
3937 \SpecialChar ~
3938 \SpecialChar ~
3939 \SpecialChar ~
3940 \SpecialChar ~
3941 \SpecialChar ~
3942 \SpecialChar ~
3943 \SpecialChar ~
3944 \SpecialChar ~
3945 \SpecialChar ~
3946 \SpecialChar ~
3947 \SpecialChar ~
3948 \SpecialChar ~
3949 \SpecialChar ~
3950 # cd $HOME
3951 \layout Standard
3952
3953
3954 \family typewriter
3955 tar -xzf sdcc.src.tar.gz\SpecialChar ~
3956 # extract source to directory sdcc
3957 \layout Standard
3958
3959
3960 \family typewriter
3961 mkdir sdcc.build\SpecialChar ~
3962 \SpecialChar ~
3963 \SpecialChar ~
3964 \SpecialChar ~
3965 \SpecialChar ~
3966 \SpecialChar ~
3967 \SpecialChar ~
3968 \SpecialChar ~
3969 \SpecialChar ~
3970 # put output in sdcc.build
3971 \layout Standard
3972
3973
3974 \family typewriter
3975 cd sdcc.build
3976 \layout Standard
3977
3978
3979 \family typewriter
3980 ../sdcc/configure\SpecialChar ~
3981 \SpecialChar ~
3982 \SpecialChar ~
3983 \SpecialChar ~
3984 \SpecialChar ~
3985 \SpecialChar ~
3986 \SpecialChar ~
3987 \SpecialChar ~
3988 # configure is doing all the magic!
3989 \layout Standard
3990
3991
3992 \family typewriter
3993 make
3994 \layout Standard
3995 \noindent
3996 That's it!
3997 \series bold
3998 configure
3999 \series default
4000  will create the directory tree will all the necessary Makefiles in ~/sdcc.build.
4001  It automagically computes the variables srcdir, top_srcdir and top_buildir
4002  for each directory.
4003  After running
4004 \series bold
4005 make
4006 \series default
4007  the generated files will be in ~/sdcc.build, while the source files stay
4008  in ~/sdcc.
4009 \newline
4010 This is not only usefull for building different binaries, e.g.
4011  when cross compiling.
4012  It also gives you a much better overview in the source tree when all the
4013  generated files are not scattered between the source files.
4014  And the best thing is: if you want to change a file you can leave the original
4015  file untouched in the source directory.
4016  Simply copy it to the build directory, edit it, enter `make clean`, `rm
4017  Makefile.dep` and `make`.
4018
4019 \series bold
4020 make
4021 \series default
4022  will do the rest for you!
4023 \layout Section
4024
4025 Building the Documentation
4026 \layout Standard
4027
4028 Add -
4029 \begin_inset ERT
4030 status Collapsed
4031
4032 \layout Standard
4033
4034 \backslash
4035 /
4036 \end_inset
4037
4038 -enable-doc to the configure arguments to build the documentation together
4039  with all the other stuff.
4040  You will need several tools (LyX, LaTeX, LaTeX2HTML, pdflatex, dvipdf,
4041  dvips and makeindex) to get the job done.
4042  Another possibility is to change to the doc directory and to type
4043 \family sans
4044 \series bold
4045
4046 \begin_inset Quotes srd
4047 \end_inset
4048
4049 make
4050 \begin_inset Quotes srd
4051 \end_inset
4052
4053
4054 \family default
4055 \series default
4056  there.
4057  You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
4058 x).
4059  Using LyX
4060 \begin_inset LatexCommand \url{http://www.lyx.org}
4061
4062 \end_inset
4063
4064  as editor is straightforward.
4065  Prebuilt documentation in html and pdf format is available from
4066 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
4067
4068 \end_inset
4069
4070 .
4071 \layout Section
4072
4073 Reading the Documentation
4074 \layout Standard
4075
4076 Currently reading the document in pdf format is recommended, as for unknown
4077  reason the hyperlinks are working there whereas in the html version they
4078  are not
4079 \begin_inset Foot
4080 collapsed false
4081
4082 \layout Standard
4083
4084 If you should know why please drop us a note
4085 \end_inset
4086
4087 .
4088
4089 \newline
4090 You'll find the pdf version
4091 \begin_inset LatexCommand \index{PDF version of this document}
4092
4093 \end_inset
4094
4095  at
4096 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.pdf}
4097
4098 \end_inset
4099
4100 .
4101
4102 \newline
4103 A html version
4104 \begin_inset LatexCommand \index{HTML version of this document}
4105
4106 \end_inset
4107
4108  should be online at
4109 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.html/index.html}
4110
4111 \end_inset
4112
4113 .
4114 \newline
4115 This documentation is in some aspects different from a commercial documentation:
4116
4117 \layout Itemize
4118
4119 It tries to document SDCC for several processor architectures in one document
4120  (commercially these probably would be separate documents/products).
4121  This document
4122 \begin_inset LatexCommand \index{Status of documentation}
4123
4124 \end_inset
4125
4126  currently matches SDCC for mcs51 and DS390 best and does give too few informati
4127 on about f.e.
4128  Z80, PIC14, PIC16 and HC08.
4129 \layout Itemize
4130
4131 There are many references pointing away from this documentation.
4132  Don't let this distract you.
4133  If there f.e.
4134  was a reference like
4135 \begin_inset LatexCommand \url{http://www.opencores.org}
4136
4137 \end_inset
4138
4139  together with a statement
4140 \begin_inset Quotes sld
4141 \end_inset
4142
4143 some processors which are targetted by SDCC can be implemented in a
4144 \emph on
4145 f
4146 \emph default
4147 ield
4148 \emph on
4149 p
4150 \emph default
4151 rogrammable
4152 \emph on
4153 g
4154 \emph default
4155 ate
4156 \emph on
4157 a
4158 \emph default
4159 rray
4160 \begin_inset LatexCommand \index{FPGA (field programmable gate array)}
4161
4162 \end_inset
4163
4164
4165 \begin_inset Quotes srd
4166 \end_inset
4167
4168  or
4169 \begin_inset LatexCommand \url{http://sf.net/projects/fpgac}
4170
4171 \end_inset
4172
4173
4174 \begin_inset LatexCommand \index{FpgaC ((subset of) C to FPGA compiler)}
4175
4176 \end_inset
4177
4178
4179 \begin_inset Quotes sld
4180 \end_inset
4181
4182 have you ever heard of an open source compiler that compiles a subset of
4183  C for an FPGA?
4184 \begin_inset Quotes srd
4185 \end_inset
4186
4187  we expect you to have a quick look there and come back.
4188  If you read this you are on the right track.
4189 \layout Itemize
4190
4191 Some sections attribute more space to problems, restrictions and warnings
4192  than to the solution.
4193 \layout Itemize
4194
4195 The installation section and the section about the debugger is intimidating.
4196 \layout Itemize
4197
4198 There are still lots of typos and there are more different writing styles
4199  than pictures.
4200 \layout Section
4201
4202 Testing the SDCC Compiler
4203 \begin_inset LatexCommand \label{sec:Testing-the-SDCC}
4204
4205 \end_inset
4206
4207
4208 \layout Standard
4209
4210 The first thing you should do after installing your SDCC compiler is to
4211  see if it runs.
4212  Type
4213 \family sans
4214 \series bold
4215 "sdcc -
4216 \begin_inset ERT
4217 status Collapsed
4218
4219 \layout Standard
4220
4221 \backslash
4222 /
4223 \end_inset
4224
4225 -version"
4226 \begin_inset LatexCommand \index{version}
4227
4228 \end_inset
4229
4230
4231 \family default
4232 \series default
4233  at the prompt, and the program should run and output its version like:
4234
4235 \newline
4236
4237 \family typewriter
4238 SDCC : mcs51/z80/avr/ds390/pic16/pic14/ds400/hc08 2.5.6 #4169 (May 8 2006)
4239  (UNIX)
4240 \layout Standard
4241
4242 If it doesn't run, or gives a message about not finding sdcc program, then
4243  you need to check over your installation.
4244  Make sure that the sdcc bin directory is in your executable search path
4245  defined by the PATH environment setting (
4246 \series medium
4247 see
4248 \series default
4249 section
4250 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
4251
4252 \end_inset
4253
4254 \SpecialChar ~
4255
4256 \series medium
4257 Install trouble-shooting for suggestions
4258 \series default
4259 ).
4260  Make sure that the sdcc program is in the bin folder, if not perhaps something
4261  did not install correctly.
4262 \newline
4263
4264 \newline
4265
4266 \series medium
4267 SDCC
4268 \series default
4269 is commonly installed as described in section
4270 \begin_inset Quotes sld
4271 \end_inset
4272
4273 Install and search paths
4274 \begin_inset Quotes srd
4275 \end_inset
4276
4277 .
4278 \newline
4279
4280 \newline
4281
4282 \series medium
4283 Make sure the compiler works on a very simple example.
4284  Type in the following test.c program using your favorite
4285 \series default
4286 ASCII
4287 \series medium
4288 editor:
4289 \layout Verse
4290
4291
4292 \family typewriter
4293 char test;
4294 \newline
4295
4296 \newline
4297 void main(void) {
4298 \newline
4299 \SpecialChar ~
4300 \SpecialChar ~
4301 \SpecialChar ~
4302 \SpecialChar ~
4303 test=0;
4304 \newline
4305 }
4306 \layout Standard
4307
4308
4309 \series medium
4310 Compile this using the following command:
4311 \family sans
4312 \series bold
4313 "sdcc -c test.c".
4314
4315 \family default
4316 \series default
4317
4318 \series medium
4319 If all goes well, the compiler will generate a test.asm and test.rel file.
4320  Congratulations, you've just compiled your first program with SDCC.
4321  We used the -c option to tell SDCC not to link the generated code, just
4322  to keep things simple for this step.
4323 \series default
4324
4325 \newline
4326
4327 \newline
4328
4329 \series medium
4330 The next step is to try it with the linker.
4331  Type in
4332 \family sans
4333 \series bold
4334 "sdcc test.c
4335 \family default
4336 \series default
4337 "
4338 \series medium
4339 .
4340  If all goes well the compiler will link with the libraries and produce
4341  a test.ihx output file.
4342  If this step fails
4343 \series default
4344
4345 \series medium
4346 (no test.ihx, and the linker generates warnings), then the problem is most
4347  likely that
4348 \series default
4349 SDCC
4350 \series medium
4351  cannot find the
4352 \series default
4353 /
4354 \series medium
4355 usr/local/share/sdcc/lib directory
4356 \series default
4357
4358 \series medium
4359 (see
4360 \series default
4361 section
4362 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
4363
4364 \end_inset
4365
4366 \SpecialChar ~
4367
4368 \series medium
4369 Install trouble-shooting for suggestions).
4370 \series default
4371
4372 \newline
4373
4374 \newline
4375
4376 \series medium
4377 The final test is to ensure
4378 \series default
4379 SDCC
4380 \series medium
4381  can use the
4382 \series default
4383 standard
4384 \series medium
4385  header files and libraries.
4386  Edit test.c and change it to the following:
4387 \layout Verse
4388
4389
4390 \family typewriter
4391 #include <string.h>
4392 \newline
4393
4394 \newline
4395 char str1[10];
4396 \newline
4397
4398 \newline
4399 void main(void) {
4400 \newline
4401 \SpecialChar ~
4402 \SpecialChar ~
4403 strcpy(str1, "testing");
4404 \newline
4405 }
4406 \layout Standard
4407
4408
4409 \series medium
4410 Compile this by typing
4411 \family sans
4412 \series bold
4413 "sdcc test.c"
4414 \family default
4415 \series medium
4416 .
4417  This should generate a test.ihx output file, and it should give no warnings
4418  such as not finding the string.h file.
4419  If it cannot find the string.h file, then the problem is that
4420 \series default
4421 SDCC
4422 \series medium
4423  cannot find the /usr/local/share/sdcc/include directory
4424 \series default
4425
4426 \series medium
4427 (see the
4428 \series default
4429 section
4430 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
4431
4432 \end_inset
4433
4434 \SpecialChar ~
4435
4436 \series medium
4437 Install trouble-shooting section for suggestions).
4438
4439 \series default
4440  Use option
4441 \series bold
4442 -
4443 \begin_inset ERT
4444 status Collapsed
4445
4446 \layout Standard
4447
4448 \backslash
4449 /
4450 \end_inset
4451
4452 -print-search-dirs
4453 \series default
4454
4455 \begin_inset LatexCommand \index{-\/-print-search-dirs}
4456
4457 \end_inset
4458
4459  to find exactly where SDCC is looking for the include and lib files.
4460 \layout Section
4461
4462 Install Trouble-shooting
4463 \begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
4464
4465 \end_inset
4466
4467
4468 \begin_inset LatexCommand \index{Install trouble-shooting}
4469
4470 \end_inset
4471
4472
4473 \layout Subsection
4474
4475 If SDCC does not build correctly
4476 \layout Standard
4477
4478 A thing to try is starting from scratch by unpacking the .tgz source package
4479  again in an empty directory.
4480  Configure it like:
4481 \newline
4482
4483 \newline
4484
4485 \family sans
4486 \series bold
4487 ./configure 2>&1 | tee configure.log
4488 \family default
4489 \series default
4490
4491 \newline
4492
4493 \newline
4494 and build it like:
4495 \newline
4496
4497 \newline
4498
4499 \family sans
4500 \series bold
4501 make 2>&1 | tee make.log
4502 \family default
4503 \series default
4504
4505 \newline
4506
4507 \newline
4508 If anything goes wrong, you can review the log files to locate the problem.
4509  Or a relevant part of this can be attached to an email that could be helpful
4510  when requesting help from the mailing list.
4511 \layout Subsection
4512
4513 What the
4514 \begin_inset Quotes sld
4515 \end_inset
4516
4517 ./configure
4518 \begin_inset Quotes srd
4519 \end_inset
4520
4521  does
4522 \layout Standard
4523
4524 The
4525 \begin_inset Quotes sld
4526 \end_inset
4527
4528 ./configure
4529 \begin_inset Quotes srd
4530 \end_inset
4531
4532  command is a script that analyzes your system and performs some configuration
4533  to ensure the source package compiles on your system.
4534  It will take a few minutes to run, and will compile a few tests to determine
4535  what compiler features are installed.
4536 \layout Subsection
4537
4538 What the
4539 \begin_inset Quotes sld
4540 \end_inset
4541
4542 make
4543 \begin_inset Quotes srd
4544 \end_inset
4545
4546  does
4547 \layout Standard
4548
4549 This runs the GNU make tool, which automatically compiles all the source
4550  packages into the final installed binary executables.
4551 \layout Subsection
4552
4553 What the
4554 \begin_inset Quotes sld
4555 \end_inset
4556
4557 make install
4558 \begin_inset Quotes erd
4559 \end_inset
4560
4561  command does.
4562 \layout Standard
4563
4564 This will install the compiler, other executables libraries and include
4565  files into the appropriate directories.
4566  See sections
4567 \begin_inset LatexCommand \ref{sub:Install-paths}
4568
4569 \end_inset
4570
4571 ,\SpecialChar ~
4572
4573 \begin_inset LatexCommand \ref{sub:Search-Paths}
4574
4575 \end_inset
4576
4577 \SpecialChar ~
4578 about install and search paths.
4579 \newline
4580 On most systems you will need super-user privileges to do this.
4581 \layout Section
4582
4583 Components of SDCC
4584 \layout Standard
4585
4586 SDCC is not just a compiler, but a collection of tools by various developers.
4587  These include linkers, assemblers, simulators and other components.
4588  Here is a summary of some of the components.
4589  Note that the included simulator and assembler have separate documentation
4590  which you can find in the source package in their respective directories.
4591  As SDCC grows to include support for other processors, other packages from
4592  various developers are included and may have their own sets of documentation.
4593 \newline
4594
4595 \newline
4596 You might want to look at the files which are installed in <installdir>.
4597  At the time of this writing, we find the following programs for gcc-builds:
4598 \newline
4599
4600 \newline
4601 In <installdir>/bin:
4602 \layout Itemize
4603
4604 sdcc - The compiler.
4605 \layout Itemize
4606
4607 sdcpp - The C preprocessor.
4608 \layout Itemize
4609
4610 asx8051 - The assembler for 8051 type processors.
4611 \layout Itemize
4612
4613 as-z80
4614 \series bold
4615 ,
4616 \series default
4617 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
4618 \layout Itemize
4619
4620 aslink -The linker for 8051 type processors.
4621 \layout Itemize
4622
4623 link-z80
4624 \series bold
4625 ,
4626 \series default
4627 link-gbz80 - The Z80 and GameBoy Z80 linkers.
4628 \layout Itemize
4629
4630 s51 - The ucSim 8051 simulator.
4631 \layout Itemize
4632
4633 sdcdb - The source debugger.
4634 \layout Itemize
4635
4636 packihx - A tool to pack (compress) Intel hex files.
4637 \layout Standard
4638
4639 In <installdir>/share/sdcc/include
4640 \layout Itemize
4641
4642 the include files
4643 \layout Standard
4644
4645 In <installdir>/share/sdcc/lib
4646 \layout Itemize
4647
4648 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
4649  relocatables.
4650 \layout Standard
4651
4652 In <installdir>/share/sdcc/doc
4653 \layout Itemize
4654
4655 the documentation
4656 \layout Standard
4657
4658 As development for other processors proceeds, this list will expand to include
4659  executables to support processors like AVR, PIC, etc.
4660 \layout Subsection
4661
4662 sdcc - The Compiler
4663 \layout Standard
4664
4665 This is the actual compiler, it in turn uses the c-preprocessor and invokes
4666  the assembler and linkage editor.
4667 \layout Subsection
4668
4669 sdcpp - The C-Preprocessor
4670 \layout Standard
4671
4672 The preprocessor
4673 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
4674
4675 \end_inset
4676
4677  is a modified version of the GNU preprocessor.
4678  The C preprocessor is used to pull in #include sources, process #ifdef
4679  statements, #defines and so on.
4680 \layout Subsection
4681
4682 as
4683 \emph on
4684 xxxx
4685 \emph default
4686 , aslink, link-
4687 \emph on
4688 xxx
4689 \emph default
4690  - The Assemblers and Linkage Editors
4691 \layout Standard
4692
4693 This is retargettable assembler & linkage editor, it was developed by Alan
4694  Baldwin.
4695  John Hartman created the version for 8051, and I (Sandeep) have made some
4696  enhancements and bug fixes for it to work properly with SDCC.
4697 \layout Subsection
4698
4699 s51 - The Simulator
4700 \layout Standard
4701
4702 S51
4703 \begin_inset LatexCommand \index{s51}
4704
4705 \end_inset
4706
4707  is a freeware, opensource simulator developed by Daniel Drotos.
4708  The simulator is built as part of the build process.
4709  For more information visit Daniel's web site at:
4710 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
4711
4712 \end_inset
4713
4714 .
4715  It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
4716  XA51 family.
4717 \layout Subsection
4718
4719 sdcdb - Source Level Debugger
4720 \layout Standard
4721
4722 SDCDB
4723 \begin_inset LatexCommand \index{SDCDB (debugger)}
4724
4725 \end_inset
4726
4727  is the companion source level debugger.
4728  More about SDCDB in section
4729 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
4730
4731 \end_inset
4732
4733 .
4734  The current version of the debugger uses Daniel's Simulator S51
4735 \begin_inset LatexCommand \index{s51}
4736
4737 \end_inset
4738
4739 , but can be easily changed to use other simulators.
4740 \layout Chapter
4741
4742 Using SDCC
4743 \layout Section
4744
4745 Compiling
4746 \layout Subsection
4747
4748 Single Source File Projects
4749 \layout Standard
4750
4751 For single source file 8051 projects the process is very simple.
4752  Compile your programs with the following command
4753 \family sans
4754 \series bold
4755 "sdcc sourcefile.c".
4756
4757 \family default
4758 \series default
4759  This will compile, assemble and link your source file.
4760  Output files are as follows:
4761 \layout Itemize
4762
4763 sourcefile.asm
4764 \begin_inset LatexCommand \index{<file>.asm}
4765
4766 \end_inset
4767
4768  - Assembler source
4769 \begin_inset LatexCommand \index{Assembler source}
4770
4771 \end_inset
4772
4773  file created by the compiler
4774 \layout Itemize
4775
4776 sourcefile.lst
4777 \begin_inset LatexCommand \index{<file>.lst}
4778
4779 \end_inset
4780
4781  - Assembler listing
4782 \begin_inset LatexCommand \index{Assembler listing}
4783
4784 \end_inset
4785
4786  file created by the Assembler
4787 \layout Itemize
4788
4789 sourcefile.rst
4790 \begin_inset LatexCommand \index{<file>.rst}
4791
4792 \end_inset
4793
4794  - Assembler listing
4795 \begin_inset LatexCommand \index{Assembler listing}
4796
4797 \end_inset
4798
4799  file updated with linkedit information, created by linkage editor
4800 \layout Itemize
4801
4802 sourcefile.sym
4803 \begin_inset LatexCommand \index{<file>.sym}
4804
4805 \end_inset
4806
4807  - symbol listing
4808 \begin_inset LatexCommand \index{Symbol listing}
4809
4810 \end_inset
4811
4812  for the sourcefile, created by the assembler
4813 \layout Itemize
4814
4815 sourcefile.rel
4816 \begin_inset LatexCommand \index{<file>.rel}
4817
4818 \end_inset
4819
4820  or sourcefile.o
4821 \begin_inset LatexCommand \index{<file>.o}
4822
4823 \end_inset
4824
4825  - Object file
4826 \begin_inset LatexCommand \index{Object file}
4827
4828 \end_inset
4829
4830  created by the assembler, input to Linkage editor
4831 \layout Itemize
4832
4833 sourcefile.map
4834 \begin_inset LatexCommand \index{<file>.map}
4835
4836 \end_inset
4837
4838  - The memory map
4839 \begin_inset LatexCommand \index{Memory map}
4840
4841 \end_inset
4842
4843  for the load module, created by the Linker
4844 \layout Itemize
4845
4846 sourcefile.mem
4847 \begin_inset LatexCommand \index{<file>.mem}
4848
4849 \end_inset
4850
4851  - A file with a summary of the memory usage
4852 \layout Itemize
4853
4854 sourcefile.ihx
4855 \begin_inset LatexCommand \index{<file>.ihx}
4856
4857 \end_inset
4858
4859  - The load module in Intel hex format
4860 \begin_inset LatexCommand \index{Intel hex format}
4861
4862 \end_inset
4863
4864  (you can select the Motorola S19 format
4865 \begin_inset LatexCommand \index{Motorola S19 format}
4866
4867 \end_inset
4868
4869  with -
4870 \begin_inset ERT
4871 status Collapsed
4872
4873 \layout Standard
4874
4875 \backslash
4876 /
4877 \end_inset
4878
4879 -out-fmt-s19
4880 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
4881
4882 \end_inset
4883
4884 .
4885  If you need another format you might want to use
4886 \family sans
4887 \shape italic
4888 objdump
4889 \family default
4890 \shape default
4891
4892 \begin_inset LatexCommand \index{objdump (tool)}
4893
4894 \end_inset
4895
4896  or
4897 \family sans
4898 \shape italic
4899  srecord
4900 \family default
4901 \shape default
4902
4903 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4904
4905 \end_inset
4906
4907 ).
4908  Both formats are documented in the documentation of srecord
4909 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4910
4911 \end_inset
4912
4913
4914 \layout Itemize
4915
4916 sourcefile.adb
4917 \begin_inset LatexCommand \index{<file>.adb}
4918
4919 \end_inset
4920
4921  - An intermediate file containing debug information needed to create the
4922  .cdb file (with -
4923 \begin_inset ERT
4924 status Open
4925
4926 \layout Standard
4927
4928 \backslash
4929 /
4930 \end_inset
4931
4932 -debug
4933 \begin_inset LatexCommand \index{-\/-debug}
4934
4935 \end_inset
4936
4937 )
4938 \layout Itemize
4939
4940 sourcefile.cdb
4941 \begin_inset LatexCommand \index{<file>.cdb}
4942
4943 \end_inset
4944
4945  - An optional file (with -
4946 \begin_inset ERT
4947 status Collapsed
4948
4949 \layout Standard
4950
4951 \backslash
4952 /
4953 \end_inset
4954
4955 -debug) containing debug information.
4956  The format is documented in cdbfileformat.pdf
4957 \layout Itemize
4958
4959 sourcefile.
4960  - (no extension)
4961 \begin_inset LatexCommand \index{<file> (no extension)}
4962
4963 \end_inset
4964
4965  An optional AOMF or AOMF51
4966 \begin_inset LatexCommand \index{AOMF, AOMF51}
4967
4968 \end_inset
4969
4970
4971 \begin_inset LatexCommand \label{OMF file}
4972
4973 \end_inset
4974
4975 file containing debug information (generated with option -
4976 \begin_inset ERT
4977 status Collapsed
4978
4979 \layout Standard
4980
4981 \backslash
4982 /
4983 \end_inset
4984
4985 -debug).
4986  The (Intel)
4987 \emph on
4988  a
4989 \emph default
4990 bsolute
4991 \emph on
4992 o
4993 \emph default
4994 bject
4995 \emph on
4996 m
4997 \emph default
4998 odule
4999 \emph on
5000 f
5001 \emph default
5002 ormat is commonly used by third party tools (debuggers
5003 \begin_inset LatexCommand \index{Debugger}
5004
5005 \end_inset
5006
5007 , simulators, emulators)
5008 \layout Itemize
5009
5010 sourcefile.dump*
5011 \begin_inset LatexCommand \index{<file>.dump*}
5012
5013 \end_inset
5014
5015  - Dump file to debug the compiler it self (generated with option -
5016 \begin_inset ERT
5017 status Collapsed
5018
5019 \layout Standard
5020
5021 \backslash
5022 /
5023 \end_inset
5024
5025 -dumpall) (see section
5026 \begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
5027
5028 \end_inset
5029
5030 \SpecialChar ~
5031  and section
5032 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
5033
5034 \end_inset
5035
5036 \SpecialChar ~
5037
5038 \begin_inset Quotes sld
5039 \end_inset
5040
5041 Anatomy of the compiler
5042 \begin_inset Quotes srd
5043 \end_inset
5044
5045 ).
5046 \layout Subsection
5047
5048 Projects with Multiple Source Files
5049 \layout Standard
5050
5051 SDCC can compile only ONE file at a time.
5052  Let us for example assume that you have a project containing the following
5053  files:
5054 \newline
5055
5056 \newline
5057 foo1.c (contains some functions)
5058 \newline
5059 foo2.c (contains some more functions)
5060 \newline
5061 foomain.c (contains more functions and the function main)
5062 \newline
5063
5064 \size footnotesize
5065
5066 \newline
5067
5068 \size default
5069 The first two files will need to be compiled separately with the commands:
5070 \size footnotesize
5071
5072 \size default
5073
5074 \newline
5075
5076 \newline
5077
5078 \family sans
5079 \series bold
5080 sdcc\SpecialChar ~
5081 -c\SpecialChar ~
5082 foo1.c
5083 \family default
5084 \series default
5085 \size footnotesize
5086
5087 \newline
5088
5089 \family sans
5090 \series bold
5091 \size default
5092 sdcc\SpecialChar ~
5093 -c\SpecialChar ~
5094 foo2.c
5095 \family default
5096 \series default
5097
5098 \newline
5099
5100 \newline
5101 Then compile the source file containing the
5102 \emph on
5103 main()
5104 \emph default
5105  function and link
5106 \begin_inset LatexCommand \index{Linker}
5107
5108 \end_inset
5109
5110  the files together with the following command:
5111 \newline
5112
5113 \newline
5114
5115 \family sans
5116 \series bold
5117 sdcc\SpecialChar ~
5118 foomain.c\SpecialChar ~
5119 foo1.rel\SpecialChar ~
5120 foo2.rel
5121 \family default
5122 \series default
5123
5124 \begin_inset LatexCommand \index{<file>.rel}
5125
5126 \end_inset
5127
5128
5129 \newline
5130
5131 \newline
5132 Alternatively,
5133 \emph on
5134 foomain.c
5135 \emph default
5136 can be separately compiled as well:
5137 \family sans
5138 \series bold
5139
5140 \newline
5141
5142 \newline
5143 sdcc\SpecialChar ~
5144 -c\SpecialChar ~
5145 foomain.c
5146 \newline
5147 sdcc foomain.rel foo1.rel foo2.rel
5148 \newline
5149
5150 \newline
5151
5152 \family default
5153 \series default
5154 The file containing the
5155 \emph on
5156 main()
5157 \emph default
5158  function
5159 \emph on
5160
5161 \emph default
5162 \noun on
5163 must
5164 \noun default
5165  be the
5166 \noun on
5167 first
5168 \noun default
5169  file specified in the command line, since the linkage editor processes
5170  file in the order they are presented to it.
5171  The linker is invoked from SDCC using a script file with extension .lnk
5172 \begin_inset LatexCommand \index{<file>.lnk}
5173
5174 \end_inset
5175
5176 .
5177  You can view this file to troubleshoot linking problems such as those arising
5178  from missing libraries.
5179 \layout Subsection
5180
5181 Projects with Additional Libraries
5182 \begin_inset LatexCommand \index{Libraries}
5183
5184 \end_inset
5185
5186
5187 \layout Standard
5188
5189 Some reusable routines may be compiled into a library, see the documentation
5190  for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
5191  for how to create a
5192 \emph on
5193 .lib
5194 \begin_inset LatexCommand \index{<file>.lib}
5195
5196 \end_inset
5197
5198
5199 \emph default
5200  library file.
5201  Libraries created in this manner can be included in the command line.
5202  Make sure you include the -L <library-path> option to tell the linker where
5203  to look for these files if they are not in the current directory.
5204  Here is an example, assuming you have the source file
5205 \emph on
5206 foomain.c
5207 \emph default
5208  and a library
5209 \emph on
5210  foolib.lib
5211 \emph default
5212  in the directory
5213 \emph on
5214 mylib
5215 \emph default
5216  (if that is not the same as your current project):
5217 \newline
5218
5219 \newline
5220
5221 \family sans
5222 \series bold
5223 sdcc foomain.c foolib.lib -L mylib
5224 \newline
5225
5226 \newline
5227
5228 \family default
5229 \series default
5230 Note here that
5231 \emph on
5232  mylib
5233 \emph default
5234  must be an absolute path name.
5235 \newline
5236
5237 \newline
5238 The most efficient way to use libraries is to keep separate modules in separate
5239  source files.
5240  The lib file now should name all the modules.rel
5241 \begin_inset LatexCommand \index{<file>.rel}
5242
5243 \end_inset
5244
5245  files.
5246  For an example see the standard library file
5247 \emph on
5248 libsdcc.lib
5249 \emph default
5250  in the directory <installdir>/share/lib/small.
5251 \layout Subsection
5252
5253 Using sdcclib to Create and Manage Libraries
5254 \begin_inset LatexCommand \index{sdcclib}
5255
5256 \end_inset
5257
5258
5259 \layout Standard
5260
5261 Alternatively, instead of having a .rel file for each entry on the library
5262  file as described in the preceding section, sdcclib can be used to embed
5263  all the modules belonging to such library in the library file itself.
5264  This results in a larger library file, but it greatly reduces the number
5265  of disk files accessed by the linker.
5266   Additionally, the packed library file contains an index of all include
5267  modules and symbols that significantly speeds up the linking process.
5268  To display a list of options supported by sdcclib type:
5269 \newline
5270
5271 \layout Standard
5272
5273
5274 \family sans
5275 \series bold
5276 sdcclib -?
5277 \begin_inset LatexCommand \index{sdcclib}
5278
5279 \end_inset
5280
5281
5282 \newline
5283
5284 \newline
5285
5286 \family default
5287 \series default
5288 To create a new library file, start by compiling all the required modules.
5289  For example:
5290 \newline
5291
5292 \layout Standard
5293
5294
5295 \family sans
5296 \series bold
5297 sdcc -c _divsint.c
5298 \layout Standard
5299
5300
5301 \family sans
5302 \series bold
5303 sdcc -c _divuint.c
5304 \layout Standard
5305
5306
5307 \family sans
5308 \series bold
5309 sdcc -c _modsint.c
5310 \layout Standard
5311
5312
5313 \family sans
5314 \series bold
5315 sdcc -c _moduint.c
5316 \layout Standard
5317
5318
5319 \family sans
5320 \series bold
5321 sdcc -c _mulint.c
5322 \newline
5323
5324 \layout Standard
5325
5326 This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
5327  and _mulint.rel.
5328  The next step is to add the .rel files to the library file:
5329 \newline
5330
5331 \layout Standard
5332
5333
5334 \family sans
5335 \series bold
5336 sdcclib libint.lib _divsint.rel
5337 \family default
5338
5339 \begin_inset LatexCommand \index{sdcclib}
5340
5341 \end_inset
5342
5343
5344 \layout Standard
5345
5346
5347 \family sans
5348 \series bold
5349 sdcclib libint.lib _divuint.rel
5350 \layout Standard
5351
5352
5353 \family sans
5354 \series bold
5355 sdcclib libint.lib _modsint.rel
5356 \layout Standard
5357
5358
5359 \family sans
5360 \series bold
5361 sdcclib libint.lib _moduint.rel
5362 \layout Standard
5363
5364
5365 \family sans
5366 \series bold
5367 sdcclib libint.lib _mulint.rel
5368 \series default
5369
5370 \newline
5371
5372 \layout Standard
5373
5374 If the file already exists in the library, it will be replaced.
5375  To see what modules and symbols are included in the library, options -s
5376  and -m are available.
5377  For example:
5378 \newline
5379
5380 \newline
5381
5382 \family sans
5383 \series bold
5384 sdcclib -s libint.lib
5385 \family default
5386
5387 \begin_inset LatexCommand \index{sdcclib}
5388
5389 \end_inset
5390
5391
5392 \newline
5393
5394 \family typewriter
5395 \series default
5396 _divsint.rel:
5397 \layout Standard
5398
5399
5400 \family typewriter
5401 __divsint_a_1_1
5402 \layout Standard
5403
5404
5405 \family typewriter
5406 __divsint_PARM_2
5407 \layout Standard
5408
5409
5410 \family typewriter
5411 __divsint
5412 \newline
5413 _divuint.rel:
5414 \layout Standard
5415
5416
5417 \family typewriter
5418 __divuint_a_1_1
5419 \layout Standard
5420
5421
5422 \family typewriter
5423 __divuint_PARM_2
5424 \layout Standard
5425
5426
5427 \family typewriter
5428 __divuint_reste_1_1
5429 \layout Standard
5430
5431
5432 \family typewriter
5433 __divuint_count_1_1
5434 \layout Standard
5435
5436
5437 \family typewriter
5438 __divuint
5439 \newline
5440 _modsint.rel:
5441 \layout Standard
5442
5443
5444 \family typewriter
5445 __modsint_a_1_1
5446 \layout Standard
5447
5448
5449 \family typewriter
5450 __modsint_PARM_2
5451 \layout Standard
5452
5453
5454 \family typewriter
5455 __modsint
5456 \newline
5457 _moduint.rel:
5458 \layout Standard
5459
5460
5461 \family typewriter
5462 __moduint_a_1_1
5463 \layout Standard
5464
5465
5466 \family typewriter
5467 __moduint_PARM_2
5468 \layout Standard
5469
5470
5471 \family typewriter
5472 __moduint_count_1_1
5473 \layout Standard
5474
5475
5476 \family typewriter
5477 __moduint
5478 \newline
5479 _mulint.rel:
5480 \layout Standard
5481
5482
5483 \family typewriter
5484 __mulint_PARM_2
5485 \layout Standard
5486
5487
5488 \family typewriter
5489 __mulint
5490 \family default
5491 \series bold
5492
5493 \newline
5494
5495 \layout Standard
5496
5497 If the source files are compiled using -
5498 \begin_inset ERT
5499 status Open
5500
5501 \layout Standard
5502
5503 \backslash
5504 /
5505 \end_inset
5506
5507 -debug
5508 \begin_inset LatexCommand \index{-\/-debug}
5509
5510 \end_inset
5511
5512 , the corresponding debug information file .adb will be include in the library
5513  file as well.
5514  The library files created with sdcclib are plain text files, so they can
5515  be viewed with a text editor.
5516  It is not recomended to modify a library file created with sdcclib using
5517  a text editor, as there are file indexes numbers located accross the file
5518  used by the linker to quickly locate the required module to link.
5519  Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
5520  it can be safely deleted, since all the information required for linking
5521  is embedded in the library file itself.
5522  Library files created using sdcclib are used as described in the preceding
5523  sections.
5524 \layout Section
5525
5526 Command Line Options
5527 \begin_inset LatexCommand \index{Command Line Options}
5528
5529 \end_inset
5530
5531
5532 \layout Subsection
5533
5534 Processor Selection Options
5535 \begin_inset LatexCommand \index{Options processor selection}
5536
5537 \end_inset
5538
5539
5540 \begin_inset LatexCommand \index{Processor selection options}
5541
5542 \end_inset
5543
5544
5545 \layout List
5546 \labelwidthstring 00.00.0000
5547
5548
5549 \series bold
5550 -mmcs51
5551 \begin_inset LatexCommand \index{-mmcs51}
5552
5553 \end_inset
5554
5555
5556 \series default
5557  Generate code for the Intel MCS51
5558 \begin_inset LatexCommand \index{MCS51}
5559
5560 \end_inset
5561
5562  family of processors.
5563  This is the default processor target.
5564 \layout List
5565 \labelwidthstring 00.00.0000
5566
5567
5568 \series bold
5569 -mds390
5570 \begin_inset LatexCommand \index{-mds390}
5571
5572 \end_inset
5573
5574
5575 \series default
5576  Generate code for the Dallas DS80C390
5577 \begin_inset LatexCommand \index{DS80C390}
5578
5579 \end_inset
5580
5581  processor.
5582 \layout List
5583 \labelwidthstring 00.00.0000
5584
5585
5586 \series bold
5587 -mds400
5588 \begin_inset LatexCommand \index{-mds400}
5589
5590 \end_inset
5591
5592
5593 \series default
5594  Generate code for the Dallas DS80C400
5595 \begin_inset LatexCommand \index{DS80C400}
5596
5597 \end_inset
5598
5599  processor.
5600 \layout List
5601 \labelwidthstring 00.00.0000
5602
5603
5604 \series bold
5605 -mhc08
5606 \begin_inset LatexCommand \index{-mhc08}
5607
5608 \end_inset
5609
5610
5611 \series default
5612  Generate code for the Freescale/Motorola HC08
5613 \begin_inset LatexCommand \index{HC08}
5614
5615 \end_inset
5616
5617  family of processors.
5618 \layout List
5619 \labelwidthstring 00.00.0000
5620
5621
5622 \series bold
5623 -mz80
5624 \begin_inset LatexCommand \index{-mz80}
5625
5626 \end_inset
5627
5628
5629 \series default
5630  Generate code for the Zilog Z80
5631 \begin_inset LatexCommand \index{Z80}
5632
5633 \end_inset
5634
5635  family of processors.
5636 \layout List
5637 \labelwidthstring 00.00.0000
5638
5639
5640 \series bold
5641 -mgbz80
5642 \begin_inset LatexCommand \index{-mgbz80}
5643
5644 \end_inset
5645
5646
5647 \series default
5648  Generate code for the GameBoy Z80
5649 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
5650
5651 \end_inset
5652
5653  processor (Not actively maintained).
5654 \layout List
5655 \labelwidthstring 00.00.0000
5656
5657
5658 \series bold
5659 -mavr
5660 \begin_inset LatexCommand \index{-mavr}
5661
5662 \end_inset
5663
5664
5665 \series default
5666  Generate code for the Atmel AVR
5667 \begin_inset LatexCommand \index{AVR}
5668
5669 \end_inset
5670
5671  processor (In development, not complete).
5672  AVR users should probably have a look at winavr
5673 \begin_inset LatexCommand \url{http://sourceforge.net/projects/winavr}
5674
5675 \end_inset
5676
5677  or
5678 \begin_inset LatexCommand \url{http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index}
5679
5680 \end_inset
5681
5682 .
5683 \layout Comment
5684
5685 I think it is fair to direct users there for now.
5686  Open source is also about avoiding unnecessary work .
5687  But I didn't find the 'official' link.
5688 \layout List
5689 \labelwidthstring 00.00.0000
5690
5691
5692 \series bold
5693 -mpic14
5694 \begin_inset LatexCommand \index{-mpic14}
5695
5696 \end_inset
5697
5698
5699 \series default
5700  Generate code for the Microchip PIC 14
5701 \begin_inset LatexCommand \index{PIC14}
5702
5703 \end_inset
5704
5705 -bit processors (p16f84 and variants.
5706  In development, not complete).
5707 \layout Comment
5708
5709 p16f627 p16f628 p16f84 p16f873 p16f877?
5710 \layout List
5711 \labelwidthstring 00.00.0000
5712
5713
5714 \series bold
5715 -mpic16
5716 \begin_inset LatexCommand \index{-mpic16}
5717
5718 \end_inset
5719
5720
5721 \series default
5722  Generate code for the Microchip PIC 16
5723 \begin_inset LatexCommand \index{PIC16}
5724
5725 \end_inset
5726
5727 -bit processors (p18f452 and variants.
5728  In development, not complete).
5729 \layout List
5730 \labelwidthstring 00.00.0000
5731
5732
5733 \series bold
5734 -mtlcs900h
5735 \series default
5736  Generate code for the Toshiba TLCS-900H
5737 \begin_inset LatexCommand \index{TLCS-900H}
5738
5739 \end_inset
5740
5741  processor (Not maintained, not complete).
5742 \layout List
5743 \labelwidthstring 00.00.0000
5744
5745
5746 \series bold
5747 -mxa51
5748 \begin_inset LatexCommand \index{-mxa51}
5749
5750 \end_inset
5751
5752
5753 \series default
5754  Generate code for the Phillips XA51
5755 \begin_inset LatexCommand \index{XA51}
5756
5757 \end_inset
5758
5759  processor (Not maintained, not complete).
5760 \layout Subsection
5761
5762 Preprocessor Options
5763 \begin_inset LatexCommand \index{Options preprocessor}
5764
5765 \end_inset
5766
5767
5768 \begin_inset LatexCommand \index{Preprocessor options}
5769
5770 \end_inset
5771
5772
5773 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5774
5775 \end_inset
5776
5777
5778 \layout List
5779 \labelwidthstring 00.00.0000
5780
5781
5782 \series bold
5783 -I<path>
5784 \begin_inset LatexCommand \index{-I<path>}
5785
5786 \end_inset
5787
5788
5789 \series default
5790  The additional location where the pre processor will look for <..h> or
5791 \begin_inset Quotes eld
5792 \end_inset
5793
5794 ..h
5795 \begin_inset Quotes erd
5796 \end_inset
5797
5798  files.
5799 \layout List
5800 \labelwidthstring 00.00.0000
5801
5802
5803 \series bold
5804 -D<macro[=value]>
5805 \begin_inset LatexCommand \index{-D<macro[=value]>}
5806
5807 \end_inset
5808
5809
5810 \series default
5811  Command line definition of macros.
5812  Passed to the preprocessor.
5813 \layout List
5814 \labelwidthstring 00.00.0000
5815
5816
5817 \series bold
5818 -M
5819 \begin_inset LatexCommand \index{-M}
5820
5821 \end_inset
5822
5823
5824 \series default
5825  Tell the preprocessor to output a rule suitable for make describing the
5826  dependencies of each object file.
5827  For each source file, the preprocessor outputs one make-rule whose target
5828  is the object file name for that source file and whose dependencies are
5829  all the files `#include'd in it.
5830  This rule may be a single line or may be continued with `
5831 \backslash
5832 '-newline if it is long.
5833  The list of rules is printed on standard output instead of the preprocessed
5834  C program.
5835  `-M' implies `-E
5836 \begin_inset LatexCommand \index{-E}
5837
5838 \end_inset
5839
5840 '.
5841 \layout List
5842 \labelwidthstring 00.00.0000
5843
5844
5845 \series bold
5846 -C
5847 \begin_inset LatexCommand \index{-C}
5848
5849 \end_inset
5850
5851
5852 \series default
5853  Tell the preprocessor not to discard comments.
5854  Used with the `-E' option.
5855 \layout List
5856 \labelwidthstring 00.00.0000
5857
5858
5859 \series bold
5860 -MM
5861 \begin_inset LatexCommand \index{-MM}
5862
5863 \end_inset
5864
5865
5866 \size large
5867 \bar under
5868
5869 \series default
5870 \size default
5871 \bar default
5872 Like `-M' but the output mentions only the user header files included with
5873  `#include
5874 \begin_inset Quotes eld
5875 \end_inset
5876
5877 file"'.
5878  System header files included with `#include <file>' are omitted.
5879 \layout List
5880 \labelwidthstring 00.00.0000
5881
5882
5883 \series bold
5884 -Aquestion(answer)
5885 \begin_inset LatexCommand \index{-Aquestion(answer)}
5886
5887 \end_inset
5888
5889
5890 \series default
5891  Assert the answer answer for question, in case it is tested with a preprocessor
5892  conditional such as `#if #question(answer)'.
5893  `-A-' disables the standard assertions that normally describe the target
5894  machine.
5895 \layout List
5896 \labelwidthstring 00.00.0000
5897
5898
5899 \series bold
5900 -Umacro
5901 \begin_inset LatexCommand \index{-Umacro}
5902
5903 \end_inset
5904
5905
5906 \series default
5907  Undefine macro macro.
5908  `-U' options are evaluated after all `-D' options, but before any `-include'
5909  and `-imacros' options.
5910 \layout List
5911 \labelwidthstring 00.00.0000
5912
5913
5914 \series bold
5915 -dM
5916 \begin_inset LatexCommand \index{-dM}
5917
5918 \end_inset
5919
5920
5921 \series default
5922  Tell the preprocessor to output only a list of the macro definitions that
5923  are in effect at the end of preprocessing.
5924  Used with the `-E' option.
5925 \layout List
5926 \labelwidthstring 00.00.0000
5927
5928
5929 \series bold
5930 -dD
5931 \begin_inset LatexCommand \index{-dD}
5932
5933 \end_inset
5934
5935
5936 \series default
5937  Tell the preprocessor to pass all macro definitions into the output, in
5938  their proper sequence in the rest of the output.
5939 \layout List
5940 \labelwidthstring 00.00.0000
5941
5942
5943 \series bold
5944 -dN
5945 \begin_inset LatexCommand \index{-dN}
5946
5947 \end_inset
5948
5949
5950 \size large
5951 \bar under
5952
5953 \series default
5954 \size default
5955 \bar default
5956 Like `-dD' except that the macro arguments and contents are omitted.
5957  Only `#define name' is included in the output.
5958 \layout List
5959 \labelwidthstring 00.00.0000
5960
5961
5962 \series bold
5963 -Wp\SpecialChar ~
5964 preprocessorOption[,preprocessorOption]
5965 \series default
5966
5967 \begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
5968
5969 \end_inset
5970
5971 ...
5972  Pass the preprocessorOption to the preprocessor
5973 \family typewriter
5974 sdcpp
5975 \family default
5976
5977 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5978
5979 \end_inset
5980
5981 .
5982  SDCC uses an adapted version of the preprocessor cpp of the GNU Compiler
5983  Collection (gcc), if you need more dedicated options please refer to the
5984  documentation at
5985 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
5986
5987 \end_inset
5988
5989 .
5990 \layout Subsection
5991
5992 Linker Options
5993 \begin_inset LatexCommand \index{Options linker}
5994
5995 \end_inset
5996
5997
5998 \begin_inset LatexCommand \index{Linker options}
5999
6000 \end_inset
6001
6002
6003 \layout List
6004 \labelwidthstring 00.00.0000
6005
6006
6007 \series bold
6008 -L\SpecialChar ~
6009 -
6010 \series default
6011
6012 \begin_inset ERT
6013 status Collapsed
6014
6015 \layout Standard
6016
6017 \backslash
6018 /
6019 \end_inset
6020
6021
6022 \series bold
6023 -lib-path
6024 \begin_inset LatexCommand \index{-\/-lib-path <path>}
6025
6026 \end_inset
6027
6028
6029 \begin_inset LatexCommand \index{-L -\/-lib-path}
6030
6031 \end_inset
6032
6033
6034 \series default
6035 \SpecialChar ~
6036 <absolute path to additional libraries> This option is passed to the linkage
6037  editor's additional libraries
6038 \begin_inset LatexCommand \index{Libraries}
6039
6040 \end_inset
6041
6042  search path.
6043  The path name must be absolute.
6044  Additional library files may be specified in the command line.
6045  See section Compiling programs for more details.
6046 \layout List
6047 \labelwidthstring 00.00.0000
6048
6049
6050 \series bold
6051 -
6052 \begin_inset ERT
6053 status Collapsed
6054
6055 \layout Standard
6056
6057 \backslash
6058 /
6059 \end_inset
6060
6061 -xram-loc
6062 \series default
6063
6064 \begin_inset LatexCommand \index{-\/-xram-loc <Value>}
6065
6066 \end_inset
6067
6068 \SpecialChar ~
6069 <Value> The start location of the external ram
6070 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
6071
6072 \end_inset
6073
6074 , default value is 0.
6075  The value entered can be in Hexadecimal or Decimal format, e.g.: -
6076 \begin_inset ERT
6077 status Collapsed
6078
6079 \layout Standard
6080
6081 \backslash
6082 /
6083 \end_inset
6084
6085 -xram-loc 0x8000 or -
6086 \begin_inset ERT
6087 status Collapsed
6088
6089 \layout Standard
6090
6091 \backslash
6092 /
6093 \end_inset
6094
6095 -xram-loc 32768.
6096 \layout List
6097 \labelwidthstring 00.00.0000
6098
6099
6100 \series bold
6101 -
6102 \begin_inset ERT
6103 status Collapsed
6104
6105 \layout Standard
6106
6107 \backslash
6108 /
6109 \end_inset
6110
6111 -code-loc
6112 \series default
6113
6114 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
6115
6116 \end_inset
6117
6118 \SpecialChar ~
6119 <Value> The start location of the code
6120 \begin_inset LatexCommand \index{code}
6121
6122 \end_inset
6123
6124  segment, default value 0.
6125  Note when this option is used the interrupt vector table is also relocated
6126  to the given address.
6127  The value entered can be in Hexadecimal or Decimal format, e.g.: -
6128 \begin_inset ERT
6129 status Collapsed
6130
6131 \layout Standard
6132
6133 \backslash
6134 /
6135 \end_inset
6136
6137 -code-loc 0x8000 or -
6138 \begin_inset ERT
6139 status Collapsed
6140
6141 \layout Standard
6142
6143 \backslash
6144 /
6145 \end_inset
6146
6147 -code-loc 32768.
6148 \layout List
6149 \labelwidthstring 00.00.0000
6150
6151
6152 \series bold
6153 -
6154 \begin_inset ERT
6155 status Collapsed
6156
6157 \layout Standard
6158
6159 \backslash
6160 /
6161 \end_inset
6162
6163 -stack-loc
6164 \series default
6165
6166 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
6167
6168 \end_inset
6169
6170 \SpecialChar ~
6171 <Value> By default the stack
6172 \begin_inset LatexCommand \index{stack}
6173
6174 \end_inset
6175
6176  is placed after the data segment.
6177  Using this option the stack can be placed anywhere in the internal memory
6178  space of the 8051.
6179  The value entered can be in Hexadecimal or Decimal format, e.g.
6180  -
6181 \begin_inset ERT
6182 status Collapsed
6183
6184 \layout Standard
6185
6186 \backslash
6187 /
6188 \end_inset
6189
6190 -stack-loc 0x20 or -
6191 \begin_inset ERT
6192 status Collapsed
6193
6194 \layout Standard
6195
6196 \backslash
6197 /
6198 \end_inset
6199
6200 -stack-loc 32.
6201  Since the sp register is incremented before a push or call, the initial
6202  sp will be set to one byte prior the provided value.
6203  The provided value should not overlap any other memory areas such as used
6204  register banks or the data segment and with enough space for the current
6205  application.
6206  The
6207 \series bold
6208 -
6209 \begin_inset ERT
6210 status Collapsed
6211
6212 \layout Standard
6213
6214 \backslash
6215 /
6216 \end_inset
6217
6218 -pack-iram
6219 \series default
6220 \SpecialChar ~
6221
6222 \begin_inset LatexCommand \index{-\/-pack-iram}
6223
6224 \end_inset
6225
6226  option (which is now a default setting) will override this setting, so
6227  you should also specify the
6228 \series bold
6229 -
6230 \begin_inset ERT
6231 status Collapsed
6232
6233 \layout Standard
6234
6235 \backslash
6236 /
6237 \end_inset
6238
6239 -no-pack-iram
6240 \series default
6241 \SpecialChar ~
6242
6243 \begin_inset LatexCommand \index{-\/-no-pack-iram}
6244
6245 \end_inset
6246
6247  option if you need to manually place the stack.
6248 \layout List
6249 \labelwidthstring 00.00.0000
6250
6251
6252 \series bold
6253 -
6254 \begin_inset ERT
6255 status Collapsed
6256
6257 \layout Standard
6258
6259 \backslash
6260 /
6261 \end_inset
6262
6263 -xstack-loc
6264 \series default
6265
6266 \begin_inset LatexCommand \index{-\/-xstack-loc <Value>}
6267
6268 \end_inset
6269
6270 \SpecialChar ~
6271 <Value> By default the external stack
6272 \begin_inset LatexCommand \index{xstack}
6273
6274 \end_inset
6275
6276  is placed after the pdata segment.
6277  Using this option the xstack can be placed anywhere in the external memory
6278  space of the 8051.
6279  The value entered can be in Hexadecimal or Decimal format, e.g.
6280  -
6281 \begin_inset ERT
6282 status Collapsed
6283
6284 \layout Standard
6285
6286 \backslash
6287 /
6288 \end_inset
6289
6290 -xstack-loc 0x8000 or -
6291 \begin_inset ERT
6292 status Collapsed
6293
6294 \layout Standard
6295
6296 \backslash
6297 /
6298 \end_inset
6299
6300 -stack-loc 32768.
6301  The provided value should not overlap any other memory areas such as the
6302  pdata or xdata segment and with enough space for the current application.
6303 \layout List
6304 \labelwidthstring 00.00.0000
6305
6306
6307 \series bold
6308 -
6309 \begin_inset ERT
6310 status Collapsed
6311
6312 \layout Standard
6313
6314 \backslash
6315 /
6316 \end_inset
6317
6318 -data-loc
6319 \series default
6320
6321 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
6322
6323 \end_inset
6324
6325 \SpecialChar ~
6326 <Value> The start location of the internal ram data
6327 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
6328
6329 \end_inset
6330
6331  segment.
6332  The value entered can be in Hexadecimal or Decimal format, eg.
6333  -
6334 \begin_inset ERT
6335 status Collapsed
6336
6337 \layout Standard
6338
6339 \backslash
6340 /
6341 \end_inset
6342
6343 -data-loc 0x20 or -
6344 \begin_inset ERT
6345 status Collapsed
6346
6347 \layout Standard
6348
6349 \backslash
6350 /
6351 \end_inset
6352
6353 -data-loc 32.
6354  (By default, the start location of the internal ram data segment  is set
6355  as low as possible in memory, taking into account the used register banks
6356  and the bit segment at address 0x20.
6357  For example if register banks 0 and 1 are used without bit variables, the
6358  data segment will be set, if -
6359 \begin_inset ERT
6360 status Collapsed
6361
6362 \layout Standard
6363
6364 \backslash
6365 /
6366 \end_inset
6367
6368 -data-loc is not used, to location 0x10.)
6369 \layout List
6370 \labelwidthstring 00.00.0000
6371
6372
6373 \series bold
6374 -
6375 \begin_inset ERT
6376 status Collapsed
6377
6378 \layout Standard
6379
6380 \backslash
6381 /
6382 \end_inset
6383
6384 -idata-loc
6385 \series default
6386
6387 \begin_inset LatexCommand \index{-\/-idata-loc <Value>}
6388
6389 \end_inset
6390
6391 \SpecialChar ~
6392 <Value> The start location of the indirectly addressable internal ram
6393 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
6394
6395 \end_inset
6396
6397  of the 8051, default value is 0x80.
6398  The value entered can be in Hexadecimal or Decimal format, eg.
6399  -
6400 \begin_inset ERT
6401 status Collapsed
6402
6403 \layout Standard
6404
6405 \backslash
6406 /
6407 \end_inset
6408
6409 -idata-loc 0x88 or -
6410 \begin_inset ERT
6411 status Collapsed
6412
6413 \layout Standard
6414
6415 \backslash
6416 /
6417 \end_inset
6418
6419 -idata-loc 136.
6420 \layout List
6421 \labelwidthstring 00.00.0000
6422
6423
6424 \series bold
6425 -
6426 \begin_inset ERT
6427 status Collapsed
6428
6429 \layout Standard
6430
6431 \backslash
6432 /
6433 \end_inset
6434
6435 -bit-loc
6436 \series default
6437 \SpecialChar ~
6438 <Value> The start location of the bit
6439 \begin_inset LatexCommand \index{bit}
6440
6441 \end_inset
6442
6443  addressable internal ram of the 8051.
6444  This is
6445 \emph on
6446 not
6447 \emph default
6448  implemented yet.
6449  Instead an option can be passed directly to the linker: -Wl\SpecialChar ~
6450 -bBSEG=<Value>.
6451 \layout List
6452 \labelwidthstring 00.00.0000
6453
6454
6455 \series bold
6456 -
6457 \begin_inset ERT
6458 status Collapsed
6459
6460 \layout Standard
6461
6462 \backslash
6463 /
6464 \end_inset
6465
6466 -out-fmt-ihx
6467 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
6468
6469 \end_inset
6470
6471
6472 \bar under
6473
6474 \series default
6475 \bar default
6476 The linker output (final object code) is in Intel Hex format.
6477 \begin_inset LatexCommand \index{Intel hex format}
6478
6479 \end_inset
6480
6481  This is the default option.
6482  The format itself is documented in the documentation of srecord
6483 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
6484
6485 \end_inset
6486
6487 .
6488 \layout List
6489 \labelwidthstring 00.00.0000
6490
6491
6492 \series bold
6493 -
6494 \begin_inset ERT
6495 status Collapsed
6496
6497 \layout Standard
6498
6499 \backslash
6500 /
6501 \end_inset
6502
6503 -out-fmt-s19
6504 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
6505
6506 \end_inset
6507
6508
6509 \bar under
6510
6511 \series default
6512 \bar default
6513 The linker output (final object code) is in Motorola S19 format
6514 \begin_inset LatexCommand \index{Motorola S19 format}
6515
6516 \end_inset
6517
6518 .
6519  The format itself is documented in the documentation of srecord.
6520 \layout List
6521 \labelwidthstring 00.00.0000
6522
6523
6524 \series bold
6525 -
6526 \begin_inset ERT
6527 status Collapsed
6528
6529 \layout Standard
6530
6531 \backslash
6532 /
6533 \end_inset
6534
6535 -out-fmt-elf
6536 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
6537
6538 \end_inset
6539
6540
6541 \bar under
6542
6543 \series default
6544 \bar default
6545 The linker output (final object code) is in ELF format
6546 \begin_inset LatexCommand \index{ELF format}
6547
6548 \end_inset
6549
6550 .
6551  (Currently only supported for the HC08 processors)
6552 \layout List
6553 \labelwidthstring 00.00.0000
6554
6555
6556 \series bold
6557 -Wl\SpecialChar ~
6558 linkOption[,linkOption]
6559 \series default
6560
6561 \begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
6562
6563 \end_inset
6564
6565 ...
6566  Pass the linkOption to the linker.
6567  See file sdcc/as/doc/asxhtm.html for more on linker options.
6568 \layout Subsection
6569
6570 MCS51 Options
6571 \begin_inset LatexCommand \index{Options MCS51}
6572
6573 \end_inset
6574
6575
6576 \begin_inset LatexCommand \index{MCS51 options}
6577
6578 \end_inset
6579
6580
6581 \layout List
6582 \labelwidthstring 00.00.0000
6583
6584
6585 \series bold
6586 -
6587 \begin_inset ERT
6588 status Collapsed
6589
6590 \layout Standard
6591
6592 \backslash
6593 /
6594 \end_inset
6595
6596 -model-small
6597 \begin_inset LatexCommand \index{-\/-model-small}
6598
6599 \end_inset
6600
6601
6602 \series default
6603 \size large
6604 \emph on
6605
6606 \size default
6607 \emph default
6608 Generate code for Small Model programs, see section Memory Models for more
6609  details.
6610  This is the default model.
6611 \layout List
6612 \labelwidthstring 00.00.0000
6613
6614
6615 \series bold
6616 -
6617 \begin_inset ERT
6618 status Collapsed
6619
6620 \layout Standard
6621
6622 \backslash
6623 /
6624 \end_inset
6625
6626 -model-medium
6627 \begin_inset LatexCommand \index{-\/-model-medium}
6628
6629 \end_inset
6630
6631
6632 \series default
6633  Generate code for Medium model programs, see section Memory Models for
6634  more details.
6635  If this option is used all source files in the project have to be compiled
6636  with this option.
6637  It must also be used when invoking the linker.
6638 \layout List
6639 \labelwidthstring 00.00.0000
6640
6641
6642 \series bold
6643 -
6644 \begin_inset ERT
6645 status Collapsed
6646
6647 \layout Standard
6648
6649 \backslash
6650 /
6651 \end_inset
6652
6653 -model-large
6654 \begin_inset LatexCommand \index{-\/-model-large}
6655
6656 \end_inset
6657
6658
6659 \series default
6660  Generate code for Large model programs, see section Memory Models for more
6661  details.
6662  If this option is used all source files in the project have to be compiled
6663  with this option.
6664  It must also be used when invoking the linker.
6665 \layout List
6666 \labelwidthstring 00.00.0000
6667
6668
6669 \series bold
6670 -
6671 \begin_inset ERT
6672 status Collapsed
6673
6674 \layout Standard
6675
6676 \backslash
6677 /
6678 \end_inset
6679
6680 -xstack
6681 \begin_inset LatexCommand \index{-\/-xstack}
6682
6683 \end_inset
6684
6685
6686 \series default
6687  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
6688  variables and passing parameters.
6689  See section
6690 \begin_inset LatexCommand \ref{sub:External-Stack}
6691
6692 \end_inset
6693
6694 \SpecialChar ~
6695  External Stack for more details.
6696 \layout List
6697 \labelwidthstring 00.00.0000
6698
6699
6700 \series bold
6701 -
6702 \begin_inset ERT
6703 status Collapsed
6704
6705 \layout Standard
6706
6707 \backslash
6708 /
6709 \end_inset
6710
6711 -iram-size
6712 \series default
6713 \SpecialChar ~
6714 <Value>
6715 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
6716
6717 \end_inset
6718
6719  Causes the linker to check if the internal ram usage is within limits of
6720  the given value.
6721 \layout List
6722 \labelwidthstring 00.00.0000
6723
6724
6725 \series bold
6726 -
6727 \begin_inset ERT
6728 status Collapsed
6729
6730 \layout Standard
6731
6732 \backslash
6733 /
6734 \end_inset
6735
6736 -xram-size
6737 \series default
6738 \SpecialChar ~
6739 <Value>
6740 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
6741
6742 \end_inset
6743
6744  Causes the linker to check if the external ram usage is within limits of
6745  the given value.
6746 \layout List
6747 \labelwidthstring 00.00.0000
6748
6749
6750 \series bold
6751 -
6752 \begin_inset ERT
6753 status Collapsed
6754
6755 \layout Standard
6756
6757 \backslash
6758 /
6759 \end_inset
6760
6761 -code-size
6762 \series default
6763 \SpecialChar ~
6764 <Value>
6765 \begin_inset LatexCommand \index{-\/-code-size <Value>}
6766
6767 \end_inset
6768
6769  Causes the linker to check if the code memory usage is within limits of
6770  the given value.
6771 \layout List
6772 \labelwidthstring 00.00.0000
6773
6774
6775 \series bold
6776 -
6777 \begin_inset ERT
6778 status Collapsed
6779
6780 \layout Standard
6781
6782 \backslash
6783 /
6784 \end_inset
6785
6786 -stack-size
6787 \series default
6788 \SpecialChar ~
6789 <Value>
6790 \begin_inset LatexCommand \index{-\/-stack-size <Value>}
6791
6792 \end_inset
6793
6794  Causes the linker to check if there is at minimum <Value> bytes for stack.
6795 \layout List
6796 \labelwidthstring 00.00.0000
6797
6798
6799 \series bold
6800 -
6801 \begin_inset ERT
6802 status Collapsed
6803
6804 \layout Standard
6805
6806 \backslash
6807 /
6808 \end_inset
6809
6810 -pack-iram
6811 \series default
6812 \SpecialChar ~
6813
6814 \begin_inset LatexCommand \index{-\/-pack-iram}
6815
6816 \end_inset
6817
6818  Causes the linker to use unused register banks for data variables and pack
6819  data, idata and stack together.
6820  This is the default now.
6821 \layout List
6822 \labelwidthstring 00.00.0000
6823
6824
6825 \series bold
6826 -
6827 \begin_inset ERT
6828 status Collapsed
6829
6830 \layout Standard
6831
6832 \backslash
6833 /
6834 \end_inset
6835
6836 -no-pack-iram
6837 \series default
6838 \SpecialChar ~
6839
6840 \begin_inset LatexCommand \index{-\/-no-pack-iram}
6841
6842 \end_inset
6843
6844  Causes the linker to use old style for allocating memory areas.
6845 \layout Subsection
6846
6847 DS390 / DS400 Options
6848 \begin_inset LatexCommand \index{Options DS390}
6849
6850 \end_inset
6851
6852
6853 \begin_inset LatexCommand \index{DS390 options}
6854
6855 \end_inset
6856
6857
6858 \layout List
6859 \labelwidthstring 00.00.0000
6860
6861
6862 \series bold
6863 -
6864 \begin_inset ERT
6865 status Collapsed
6866
6867 \layout Standard
6868
6869 \backslash
6870 /
6871 \end_inset
6872
6873 -model-flat24
6874 \series default
6875
6876 \begin_inset LatexCommand \index{-\/-model-flat24}
6877
6878 \end_inset
6879
6880
6881 \size large
6882 \emph on
6883
6884 \size default
6885 \emph default
6886 Generate 24-bit flat mode code.
6887  This is the one and only that the ds390 code generator supports right now
6888  and is default when using
6889 \emph on
6890 -mds390
6891 \emph default
6892 .
6893  See section Memory Models for more details.
6894 \layout List
6895 \labelwidthstring 00.00.0000
6896
6897
6898 \series bold
6899 -
6900 \begin_inset ERT
6901 status Collapsed
6902
6903 \layout Standard
6904
6905 \backslash
6906 /
6907 \end_inset
6908
6909 -protect-sp-update
6910 \begin_inset LatexCommand \index{-\/-protect-sp-update}
6911
6912 \end_inset
6913
6914
6915 \series default
6916  disable interrupts during ESP:SP updates.
6917 \layout List
6918 \labelwidthstring 00.00.0000
6919
6920
6921 \series bold
6922 -
6923 \begin_inset ERT
6924 status Collapsed
6925
6926 \layout Standard
6927
6928 \backslash
6929 /
6930 \end_inset
6931
6932 -stack-10bit
6933 \series default
6934
6935 \begin_inset LatexCommand \index{-\/-stack-10bit}
6936
6937 \end_inset
6938
6939  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
6940  This is the one and only that the ds390 code generator supports right now
6941  and is default when using
6942 \emph on
6943 -mds390
6944 \emph default
6945 .
6946  In this mode, the stack is located in the lower 1K of the internal RAM,
6947  which is mapped to 0x400000.
6948  Note that the support is incomplete, since it still uses a single byte
6949  as the stack pointer.
6950  This means that only the lower 256 bytes of the potential 1K stack space
6951  will actually be used.
6952  However, this does allow you to reclaim the precious 256 bytes of low RAM
6953  for use for the DATA and IDATA segments.
6954  The compiler will not generate any code to put the processor into 10 bit
6955  stack mode.
6956  It is important to ensure that the processor is in this mode before calling
6957  any re-entrant functions compiled with this option.
6958  In principle, this should work with the
6959 \emph on
6960 -
6961 \begin_inset ERT
6962 status Collapsed
6963
6964 \layout Standard
6965
6966 \backslash
6967 /
6968 \end_inset
6969
6970 -stack-auto
6971 \begin_inset LatexCommand \index{-\/-stack-auto}
6972
6973 \end_inset
6974
6975
6976 \emph default
6977  option, but that has not been tested.
6978  It is incompatible with the
6979 \emph on
6980 -
6981 \begin_inset ERT
6982 status Collapsed
6983
6984 \layout Standard
6985
6986 \backslash
6987 /
6988 \end_inset
6989
6990 -xstack
6991 \begin_inset LatexCommand \index{-\/-xstack}
6992
6993 \end_inset
6994
6995
6996 \emph default
6997  option.
6998  It also only makes sense if the processor is in 24 bit contiguous addressing
6999  mode (see the
7000 \emph on
7001 -
7002 \begin_inset ERT
7003 status Collapsed
7004
7005 \layout Standard
7006
7007 \backslash
7008 /
7009 \end_inset
7010
7011 -model-flat24 option
7012 \emph default
7013 ).
7014 \layout List
7015 \labelwidthstring 00.00.0000
7016
7017
7018 \series bold
7019 -
7020 \begin_inset ERT
7021 status Collapsed
7022
7023 \layout Standard
7024
7025 \backslash
7026 /
7027 \end_inset
7028
7029 -stack-probe
7030 \begin_inset LatexCommand \index{-\/-stack-probe}
7031
7032 \end_inset
7033
7034
7035 \series default
7036  insert call to function __stack_probe at each function prologue.
7037 \layout List
7038 \labelwidthstring 00.00.0000
7039
7040
7041 \series bold
7042 -
7043 \begin_inset ERT
7044 status Collapsed
7045
7046 \layout Standard
7047
7048 \backslash
7049 /
7050 \end_inset
7051
7052 -tini-libid
7053 \begin_inset LatexCommand \index{-\/-tini-libid}
7054
7055 \end_inset
7056
7057
7058 \series default
7059  <nnnn> LibraryID used in -mTININative.
7060
7061 \layout List
7062 \labelwidthstring 00.00.0000
7063
7064
7065 \series bold
7066 -
7067 \begin_inset ERT
7068 status Collapsed
7069
7070 \layout Standard
7071
7072 \backslash
7073 /
7074 \end_inset
7075
7076 -use-accelerator
7077 \begin_inset LatexCommand \index{-\/-use-accelerator}
7078
7079 \end_inset
7080
7081
7082 \series default
7083  generate code for DS390 Arithmetic Accelerator.
7084
7085 \layout Subsection
7086
7087 Z80 Options
7088 \begin_inset LatexCommand \index{Options Z80}
7089
7090 \end_inset
7091
7092
7093 \begin_inset LatexCommand \index{Z80 options}
7094
7095 \end_inset
7096
7097
7098 \layout List
7099 \labelwidthstring 00.00.0000
7100
7101
7102 \series bold
7103 -
7104 \begin_inset ERT
7105 status Collapsed
7106
7107 \layout Standard
7108
7109 \backslash
7110 /
7111 \end_inset
7112
7113 -callee-saves-bc
7114 \series default
7115
7116 \begin_inset LatexCommand \index{-\/-callee-saves-bc}
7117
7118 \end_inset
7119
7120
7121 \size large
7122 \emph on
7123
7124 \size default
7125 \emph default
7126 Force a called function to always save BC.
7127 \layout List
7128 \labelwidthstring 00.00.0000
7129
7130
7131 \series bold
7132 -
7133 \begin_inset ERT
7134 status Collapsed
7135
7136 \layout Standard
7137
7138 \backslash
7139 /
7140 \end_inset
7141
7142 -no-std-crt0
7143 \series default
7144
7145 \begin_inset LatexCommand \index{-\/-no-std-crt0}
7146
7147 \end_inset
7148
7149  When linking, skip the standard crt0.o object file.
7150  You must provide your own crt0.o for your system when linking.
7151
7152 \layout Subsection
7153
7154 Optimization Options
7155 \begin_inset LatexCommand \index{Options optimization}
7156
7157 \end_inset
7158
7159
7160 \begin_inset LatexCommand \index{Optimization options}
7161
7162 \end_inset
7163
7164
7165 \layout List
7166 \labelwidthstring 00.00.0000
7167
7168
7169 \series bold
7170 -
7171 \begin_inset ERT
7172 status Collapsed
7173
7174 \layout Standard
7175
7176 \backslash
7177 /
7178 \end_inset
7179
7180 -nogcse
7181 \begin_inset LatexCommand \index{-\/-nogcse}
7182
7183 \end_inset
7184
7185
7186 \series default
7187  Will not do global subexpression elimination, this option may be used when
7188  the compiler creates undesirably large stack/data spaces to store compiler
7189  temporaries (
7190 \emph on
7191 s
7192 \emph default
7193 pill
7194 \emph on
7195 loc
7196 \emph default
7197 ations, sloc
7198 \begin_inset LatexCommand \index{sloc (spill location)}
7199
7200 \end_inset
7201
7202 ).
7203  A warning message will be generated when this happens and the compiler
7204  will indicate the number of extra bytes it allocated.
7205  It is recommended that this option NOT be used, #pragma\SpecialChar ~
7206 nogcse
7207 \begin_inset LatexCommand \index{\#pragma nogcse}
7208
7209 \end_inset
7210
7211  can be used to turn off global subexpression elimination
7212 \begin_inset LatexCommand \index{Subexpression elimination}
7213
7214 \end_inset
7215
7216  for a given function only.
7217 \layout List
7218 \labelwidthstring 00.00.0000
7219
7220
7221 \series bold
7222 -
7223 \begin_inset ERT
7224 status Collapsed
7225
7226 \layout Standard
7227
7228 \backslash
7229 /
7230 \end_inset
7231
7232 -noinvariant
7233 \begin_inset LatexCommand \index{-\/-noinvariant}
7234
7235 \end_inset
7236
7237
7238 \series default
7239  Will not do loop invariant optimizations, this may be turned off for reasons
7240  explained for the previous option.
7241  For more details of loop optimizations performed see Loop Invariants in
7242  section
7243 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
7244
7245 \end_inset
7246
7247 .
7248  It is recommended that this option NOT be used, #pragma\SpecialChar ~
7249 noinvariant
7250 \begin_inset LatexCommand \index{\#pragma noinvariant}
7251
7252 \end_inset
7253
7254  can be used to turn off invariant optimizations for a given function only.
7255 \layout List
7256 \labelwidthstring 00.00.0000
7257
7258
7259 \series bold
7260 -
7261 \begin_inset ERT
7262 status Collapsed
7263
7264 \layout Standard
7265
7266 \backslash
7267 /
7268 \end_inset
7269
7270 -noinduction
7271 \begin_inset LatexCommand \index{-\/-noinduction}
7272
7273 \end_inset
7274
7275
7276 \series default
7277  Will not do loop induction optimizations, see section strength reduction
7278  for more details.
7279  It is recommended that this option is NOT used, #pragma\SpecialChar ~
7280 noinduction
7281 \begin_inset LatexCommand \index{\#pragma noinduction}
7282
7283 \end_inset
7284
7285  can be used to turn off induction optimizations for a given function only.
7286 \layout List
7287 \labelwidthstring 00.00.0000
7288
7289
7290 \series bold
7291 -
7292 \begin_inset ERT
7293 status Collapsed
7294
7295 \layout Standard
7296
7297 \backslash
7298 /
7299 \end_inset
7300
7301 -nojtbound
7302 \begin_inset LatexCommand \index{-\/-nojtbound}
7303
7304 \end_inset
7305
7306
7307 \size large
7308 \bar under
7309
7310 \series default
7311 \size default
7312 \bar default
7313  Will not generate boundary condition check when switch statements
7314 \begin_inset LatexCommand \index{switch statement}
7315
7316 \end_inset
7317
7318  are implemented using jump-tables.
7319  See section
7320 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
7321
7322 \end_inset
7323
7324 \SpecialChar ~
7325 Switch Statements for more details.
7326  It is recommended that this option is NOT used, #pragma\SpecialChar ~
7327 nojtbound
7328 \begin_inset LatexCommand \index{\#pragma nojtbound}
7329
7330 \end_inset
7331
7332  can be used to turn off boundary checking for jump tables for a given function
7333  only.
7334 \layout List
7335 \labelwidthstring 00.00.0000
7336
7337
7338 \series bold
7339 -
7340 \begin_inset ERT
7341 status Collapsed
7342
7343 \layout Standard
7344
7345 \backslash
7346 /
7347 \end_inset
7348
7349 -noloopreverse
7350 \begin_inset LatexCommand \index{-\/-noloopreverse}
7351
7352 \end_inset
7353
7354
7355 \series default
7356 \size large
7357
7358 \size default
7359 Will not do loop reversal
7360 \begin_inset LatexCommand \index{Loop reversing}
7361
7362 \end_inset
7363
7364 optimization.
7365 \layout List
7366 \labelwidthstring 00.00.0000
7367
7368 -
7369 \begin_inset ERT
7370 status Collapsed
7371
7372 \layout Standard
7373
7374 \backslash
7375 /
7376 \end_inset
7377
7378 -
7379 \series bold
7380 nolabelopt
7381 \series default
7382
7383 \begin_inset LatexCommand \index{-\/-nolabelopt }
7384
7385 \end_inset
7386
7387 Will not optimize labels (makes the dumpfiles more readable).
7388 \layout List
7389 \labelwidthstring 00.00.0000
7390
7391
7392 \series bold
7393 -
7394 \begin_inset ERT
7395 status Collapsed
7396
7397 \layout Standard
7398
7399 \backslash
7400 /
7401 \end_inset
7402
7403 -no-xinit-opt
7404 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
7405
7406 \end_inset
7407
7408
7409 \series default
7410  Will not memcpy initialized data from code space into xdata space.
7411  This saves a few bytes in code space if you don't have initialized data
7412 \begin_inset LatexCommand \index{Variable initialization}
7413
7414 \end_inset
7415
7416 .
7417 \layout List
7418 \labelwidthstring 00.00.0000
7419
7420
7421 \series bold
7422 -
7423 \begin_inset ERT
7424 status Collapsed
7425
7426 \layout Standard
7427
7428 \backslash
7429 /
7430 \end_inset
7431
7432 -nooverlay
7433 \begin_inset LatexCommand \index{-\/-nooverlay}
7434
7435 \end_inset
7436
7437
7438 \series default
7439   The compiler will not overlay parameters and local variables of any function,
7440  see section Parameters and local variables for more details.
7441 \layout List
7442 \labelwidthstring 00.00.0000
7443
7444
7445 \series bold
7446 -
7447 \begin_inset ERT
7448 status Collapsed
7449
7450 \layout Standard
7451
7452 \backslash
7453 /
7454 \end_inset
7455
7456 -no-peep
7457 \begin_inset LatexCommand \index{-\/-no-peep}
7458
7459 \end_inset
7460
7461
7462 \series default
7463  Disable peep-hole optimization with built-in rules.
7464 \layout List
7465 \labelwidthstring 00.00.0000
7466
7467
7468 \series bold
7469 -
7470 \begin_inset ERT
7471 status Collapsed
7472
7473 \layout Standard
7474
7475 \backslash
7476 /
7477 \end_inset
7478
7479 -peep-file
7480 \series default
7481
7482 \begin_inset LatexCommand \index{-\/-peep-file}
7483
7484 \end_inset
7485
7486 \SpecialChar ~
7487 <filename> This option can be used to use additional rules to be used by
7488  the peep hole optimizer.
7489  See section
7490 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
7491
7492 \end_inset
7493
7494 \SpecialChar ~
7495 Peep Hole optimizations for details on how to write these rules.
7496 \layout List
7497 \labelwidthstring 00.00.0000
7498
7499
7500 \series bold
7501 -
7502 \begin_inset ERT
7503 status Collapsed
7504
7505 \layout Standard
7506
7507 \backslash
7508 /
7509 \end_inset
7510
7511 -peep-asm
7512 \begin_inset LatexCommand \index{-\/-peep-asm}
7513
7514 \end_inset
7515
7516
7517 \series default
7518  Pass the inline assembler code through the peep hole optimizer.
7519  This can cause unexpected changes to inline assembler code, please go through
7520  the peephole optimizer
7521 \begin_inset LatexCommand \index{Peephole optimizer}
7522
7523 \end_inset
7524
7525  rules defined in the source file tree '<target>/peeph.def' before using
7526  this option.
7527 \layout List
7528 \labelwidthstring 00.00.0000
7529
7530
7531 \series bold
7532 -
7533 \begin_inset ERT
7534 status Collapsed
7535
7536 \layout Standard
7537
7538 \backslash
7539 /
7540 \end_inset
7541
7542 -opt-code-speed
7543 \begin_inset LatexCommand \index{-\/-opt-code-speed}
7544
7545 \end_inset
7546
7547
7548 \series default
7549  The compiler will optimize code generation towards fast code, possibly
7550  at the expense of code size.
7551 \layout List
7552 \labelwidthstring 00.00.0000
7553
7554
7555 \series bold
7556 -
7557 \begin_inset ERT
7558 status Collapsed
7559
7560 \layout Standard
7561
7562 \backslash
7563 /
7564 \end_inset
7565
7566 -opt-code-size
7567 \begin_inset LatexCommand \index{-\/-opt-code-size}
7568
7569 \end_inset
7570
7571
7572 \series default
7573  The compiler will optimize code generation towards compact code, possibly
7574  at the expense of code speed.
7575 \layout Subsection
7576
7577 Other Options
7578 \begin_inset LatexCommand \index{Options other}
7579
7580 \end_inset
7581
7582
7583 \layout List
7584 \labelwidthstring 00.00.0000
7585
7586
7587 \series bold
7588 -c\SpecialChar ~
7589 -
7590 \begin_inset ERT
7591 status Collapsed
7592
7593 \layout Standard
7594
7595 \backslash
7596 /
7597 \end_inset
7598
7599 -compile-only
7600 \begin_inset LatexCommand \index{-\/-compile-only}
7601
7602 \end_inset
7603
7604
7605 \begin_inset LatexCommand \index{-c -\/-compile-only}
7606
7607 \end_inset
7608
7609
7610 \series default
7611  will compile and assemble the source, but will not call the linkage editor.
7612 \layout List
7613 \labelwidthstring 00.00.0000
7614
7615
7616 \series bold
7617 -
7618 \series default
7619
7620 \begin_inset ERT
7621 status Collapsed
7622
7623 \layout Standard
7624
7625 \backslash
7626 /
7627 \end_inset
7628
7629
7630 \series bold
7631 -c1mode
7632 \begin_inset LatexCommand \index{-\/-c1mode}
7633
7634 \end_inset
7635
7636
7637 \series default
7638  reads the preprocessed source from standard input and compiles it.
7639  The file name for the assembler output must be specified using the -o option.
7640 \layout List
7641 \labelwidthstring 00.00.0000
7642
7643
7644 \series bold
7645 -E
7646 \begin_inset LatexCommand \index{-E}
7647
7648 \end_inset
7649
7650
7651 \series default
7652  Run only the C preprocessor.
7653  Preprocess all the C source files specified and output the results to standard
7654  output.
7655 \layout List
7656 \labelwidthstring 00.00.0000
7657
7658
7659 \series bold
7660 -o\SpecialChar ~
7661 <path/file>
7662 \begin_inset LatexCommand \index{-o <path/file>}
7663
7664 \end_inset
7665
7666
7667 \series default
7668 The output path resp.
7669  file where everything will be placed.
7670  If the parameter is a path, it must have a trailing slash (or backslash
7671  for the Windows binaries) to be recognized as a path.
7672
7673 \layout List
7674 \labelwidthstring 00.00.0000
7675
7676
7677 \series bold
7678 -
7679 \begin_inset ERT
7680 status Collapsed
7681
7682 \layout Standard
7683
7684 \backslash
7685 /
7686 \end_inset
7687
7688 -stack-auto
7689 \begin_inset LatexCommand \index{-\/-stack-auto}
7690
7691 \end_inset
7692
7693
7694 \series default
7695 \size large
7696 \emph on
7697
7698 \size default
7699 \emph default
7700 All functions in the source file will be compiled as
7701 \emph on
7702 reentrant
7703 \emph default
7704
7705 \begin_inset LatexCommand \index{reentrant}
7706
7707 \end_inset
7708
7709 , i.e.
7710  the parameters and local variables will be allocated on the stack
7711 \begin_inset LatexCommand \index{stack}
7712
7713 \end_inset
7714
7715 .
7716  See section
7717 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
7718
7719 \end_inset
7720
7721  Parameters and Local Variables for more details.
7722  If this option is used all source files in the project should be compiled
7723  with this option.
7724  It automatically implies --int-long-reent and --float-reent.
7725
7726 \layout List
7727 \labelwidthstring 00.00.0000
7728
7729
7730 \series bold
7731 -
7732 \begin_inset ERT
7733 status Collapsed
7734
7735 \layout Standard
7736
7737 \backslash
7738 /
7739 \end_inset
7740
7741 -callee-saves
7742 \begin_inset LatexCommand \index{-\/-callee-saves}
7743
7744 \end_inset
7745
7746  function1[,function2][,function3]....
7747
7748 \series default
7749  The compiler by default uses a caller saves convention for register saving
7750  across function calls, however this can cause unnecessary register pushing
7751  & popping when calling small functions from larger functions.
7752  This option can be used to switch the register saving convention for the
7753  function names specified.
7754  The compiler will not save registers when calling these functions, no extra
7755  code will be generated at the entry & exit (function prologue
7756 \series bold
7757
7758 \begin_inset LatexCommand \index{function prologue}
7759
7760 \end_inset
7761
7762
7763 \series default
7764  & epilogue
7765 \series bold
7766
7767 \begin_inset LatexCommand \index{function epilogue}
7768
7769 \end_inset
7770
7771
7772 \series default
7773 ) for these functions to save & restore the registers used by these functions,
7774  this can SUBSTANTIALLY reduce code & improve run time performance of the
7775  generated code.
7776  In the future the compiler (with inter procedural analysis) will be able
7777  to determine the appropriate scheme to use for each function call.
7778  DO NOT use this option for built-in functions such as _mulint..., if this
7779  option is used for a library function the appropriate library function
7780  needs to be recompiled with the same option.
7781  If the project consists of multiple source files then all the source file
7782  should be compiled with the same -
7783 \begin_inset ERT
7784 status Collapsed
7785
7786 \layout Standard
7787
7788 \backslash
7789 /
7790 \end_inset
7791
7792 -callee-saves option string.
7793  Also see #pragma\SpecialChar ~
7794 callee_saves
7795 \begin_inset LatexCommand \index{\#pragma callee\_saves}
7796
7797 \end_inset
7798
7799 .
7800 \layout List
7801 \labelwidthstring 00.00.0000
7802
7803
7804 \series bold
7805 -
7806 \begin_inset ERT
7807 status Collapsed
7808
7809 \layout Standard
7810
7811 \backslash
7812 /
7813 \end_inset
7814
7815 -debug
7816 \begin_inset LatexCommand \index{-\/-debug}
7817
7818 \end_inset
7819
7820
7821 \bar under
7822
7823 \series default
7824 \bar default
7825 When this option is used the compiler will generate debug information.
7826  The debug information collected in a file with .cdb extension can be used
7827  with the SDCDB.
7828  For more information see documentation for SDCDB.
7829  Another file with no extension contains debug information in AOMF or AOMF51
7830 \begin_inset LatexCommand \index{AOMF, AOMF51}
7831
7832 \end_inset
7833
7834  format which is commonly used by third party tools.
7835 \layout List
7836 \labelwidthstring 00.00.0000
7837
7838
7839 \series bold
7840 -S
7841 \begin_inset LatexCommand \index{-S}
7842
7843 \end_inset
7844
7845
7846 \size large
7847 \bar under
7848
7849 \series default
7850 \size default
7851 \bar default
7852 Stop after the stage of compilation proper; do not assemble.
7853  The output is an assembler code file for the input file specified.
7854 \layout List
7855 \labelwidthstring 00.00.0000
7856
7857
7858 \series bold
7859 -
7860 \begin_inset ERT
7861 status Collapsed
7862
7863 \layout Standard
7864
7865 \backslash
7866 /
7867 \end_inset
7868
7869 -int-long-reent
7870 \begin_inset LatexCommand \index{-\/-int-long-reent}
7871
7872 \end_inset
7873
7874
7875 \series default
7876  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
7877  Note by default these libraries are compiled as non-reentrant.
7878  See section Installation for more details.
7879 \layout List
7880 \labelwidthstring 00.00.0000
7881
7882
7883 \series bold
7884 -
7885 \begin_inset ERT
7886 status Collapsed
7887
7888 \layout Standard
7889
7890 \backslash
7891 /
7892 \end_inset
7893
7894 -cyclomatic
7895 \begin_inset LatexCommand \index{-\/-cyclomatic}
7896
7897 \end_inset
7898
7899
7900 \bar under
7901
7902 \series default
7903 \bar default
7904 This option will cause the compiler to generate an information message for
7905  each function in the source file.
7906  The message contains some
7907 \emph on
7908 important
7909 \emph default
7910  information about the function.
7911  The number of edges and nodes the compiler detected in the control flow
7912  graph of the function, and most importantly the
7913 \emph on
7914 cyclomatic complexity
7915 \begin_inset LatexCommand \index{Cyclomatic complexity}
7916
7917 \end_inset
7918
7919
7920 \emph default
7921  see section on Cyclomatic Complexity for more details.
7922 \layout List
7923 \labelwidthstring 00.00.0000
7924
7925
7926 \series bold
7927 -
7928 \begin_inset ERT
7929 status Collapsed
7930
7931 \layout Standard
7932
7933 \backslash
7934 /
7935 \end_inset
7936
7937 -float-reent
7938 \begin_inset LatexCommand \index{-\/-float-reent}
7939
7940 \end_inset
7941
7942
7943 \series default
7944  Floating point library is compiled as reentrant
7945 \begin_inset LatexCommand \index{reentrant}
7946
7947 \end_inset
7948
7949 .
7950  See section Installation for more details.
7951 \layout List
7952 \labelwidthstring 00.00.0000
7953
7954
7955 \series bold
7956 -
7957 \begin_inset ERT
7958 status Collapsed
7959
7960 \layout Standard
7961
7962 \backslash
7963 /
7964 \end_inset
7965
7966 -main-return
7967 \begin_inset LatexCommand \index{-\/-main-return}
7968
7969 \end_inset
7970
7971
7972 \series default
7973  This option can be used if the code generated is called by a monitor program
7974  or if the main routine includes an endless loop.
7975  This option might result in slightly smaller code and save two bytes of
7976  stack space.
7977  The return from the 'main'
7978 \begin_inset LatexCommand \index{main return}
7979
7980 \end_inset
7981
7982  function will return to the function calling main.
7983  The default setting is to lock up i.e.
7984  generate a '
7985 \family typewriter
7986 sjmp .
7987 \family default
7988 '.
7989 \layout List
7990 \labelwidthstring 00.00.0000
7991
7992
7993 \series bold
7994 -
7995 \begin_inset ERT
7996 status Collapsed
7997
7998 \layout Standard
7999
8000 \backslash
8001 /
8002 \end_inset
8003
8004 -nostdinc
8005 \begin_inset LatexCommand \index{-\/-nostdinc}
8006
8007 \end_inset
8008
8009
8010 \series default
8011  This will prevent the compiler from passing on the default include path
8012  to the preprocessor.
8013 \layout List
8014 \labelwidthstring 00.00.0000
8015
8016
8017 \series bold
8018 -
8019 \begin_inset ERT
8020 status Collapsed
8021
8022 \layout Standard
8023
8024 \backslash
8025 /
8026 \end_inset
8027
8028 -nostdlib
8029 \begin_inset LatexCommand \index{-\/-nostdlib}
8030
8031 \end_inset
8032
8033
8034 \series default
8035  This will prevent the compiler from passing on the default library
8036 \begin_inset LatexCommand \index{Libraries}
8037
8038 \end_inset
8039
8040  path to the linker.
8041 \layout List
8042 \labelwidthstring 00.00.0000
8043
8044
8045 \series bold
8046 -
8047 \begin_inset ERT
8048 status Collapsed
8049
8050 \layout Standard
8051
8052 \backslash
8053 /
8054 \end_inset
8055
8056 -verbose
8057 \begin_inset LatexCommand \index{-\/-verbose}
8058
8059 \end_inset
8060
8061
8062 \series default
8063  Shows the various actions the compiler is performing.
8064 \layout List
8065 \labelwidthstring 00.00.0000
8066
8067
8068 \series bold
8069 -V
8070 \begin_inset LatexCommand \index{-V}
8071
8072 \end_inset
8073
8074
8075 \series default
8076  Shows the actual commands the compiler is executing.
8077 \layout List
8078 \labelwidthstring 00.00.0000
8079
8080
8081 \series bold
8082 -
8083 \begin_inset ERT
8084 status Collapsed
8085
8086 \layout Standard
8087
8088 \backslash
8089 /
8090 \end_inset
8091
8092 -no-c-code-in-asm
8093 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
8094
8095 \end_inset
8096
8097
8098 \series default
8099  Hides your ugly and inefficient c-code from the asm file, so you can always
8100  blame the compiler :)
8101 \layout List
8102 \labelwidthstring 00.00.0000
8103
8104
8105 \series bold
8106 -
8107 \begin_inset ERT
8108 status Collapsed
8109
8110 \layout Standard
8111
8112 \backslash
8113 /
8114 \end_inset
8115
8116 -no-peep-comments
8117 \begin_inset LatexCommand \index{-\/-no-peep-comments}
8118
8119 \end_inset
8120
8121
8122 \series default
8123  Will not include peep-hole comments in the generated files.
8124 \layout List
8125 \labelwidthstring 00.00.0000
8126
8127
8128 \series bold
8129 -
8130 \begin_inset ERT
8131 status Collapsed
8132
8133 \layout Standard
8134
8135 \backslash
8136 /
8137 \end_inset
8138
8139 -i-code-in-asm
8140 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
8141
8142 \end_inset
8143
8144
8145 \series default
8146  Include i-codes in the asm file.
8147  Sounds like noise but is most helpful for debugging the compiler itself.
8148 \layout List
8149 \labelwidthstring 00.00.0000
8150
8151
8152 \series bold
8153 -
8154 \begin_inset ERT
8155 status Collapsed
8156
8157 \layout Standard
8158
8159 \backslash
8160 /
8161 \end_inset
8162
8163 -less-pedantic
8164 \begin_inset LatexCommand \index{-\/-less-pedantic}
8165
8166 \end_inset
8167
8168
8169 \series default
8170  Disable some of the more pedantic warnings
8171 \begin_inset LatexCommand \index{Warnings}
8172
8173 \end_inset
8174
8175  (jwk burps: please be more specific here, please!).
8176 \layout List
8177 \labelwidthstring 00.00.0000
8178
8179
8180 \series bold
8181 -
8182 \begin_inset ERT
8183 status Collapsed
8184
8185 \layout Standard
8186
8187 \backslash
8188 /
8189 \end_inset
8190
8191 -disable-warning\SpecialChar ~
8192 <nnnn>
8193 \begin_inset LatexCommand \index{-\/-disable-warning}
8194
8195 \end_inset
8196
8197
8198 \series default
8199  Disable specific warning with number <nnnn>.
8200 \layout List
8201 \labelwidthstring 00.00.0000
8202
8203
8204 \series bold
8205 -
8206 \begin_inset ERT
8207 status Collapsed
8208
8209 \layout Standard
8210
8211 \backslash
8212 /
8213 \end_inset
8214
8215 -print-search-dirs
8216 \begin_inset LatexCommand \index{-\/-print-search-dirs}
8217
8218 \end_inset
8219
8220
8221 \series default
8222  Display the directories in the compiler's search path
8223 \layout List
8224 \labelwidthstring 00.00.0000
8225
8226
8227 \series bold
8228 -
8229 \begin_inset ERT
8230 status Collapsed
8231
8232 \layout Standard
8233
8234 \backslash
8235 /
8236 \end_inset
8237
8238 -vc
8239 \begin_inset LatexCommand \index{-\/-vc}
8240
8241 \end_inset
8242
8243
8244 \series default
8245  Display errors and warnings using MSVC style, so you can use SDCC with
8246  visual studio.
8247 \layout List
8248 \labelwidthstring 00.00.0000
8249
8250
8251 \series bold
8252 -
8253 \begin_inset ERT
8254 status Collapsed
8255
8256 \layout Standard
8257
8258 \backslash
8259 /
8260 \end_inset
8261
8262 -use-stdout
8263 \begin_inset LatexCommand \index{-\/-use-stdout}
8264
8265 \end_inset
8266
8267
8268 \series default
8269  Send errors and warnings to stdout instead of stderr.
8270 \layout List
8271 \labelwidthstring 00.00.0000
8272
8273
8274 \series bold
8275 -Wa\SpecialChar ~
8276 asmOption[,asmOption]
8277 \series default
8278
8279 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
8280
8281 \end_inset
8282
8283 ...
8284  Pass the asmOption to the assembler
8285 \begin_inset LatexCommand \index{Options assembler}
8286
8287 \end_inset
8288
8289
8290 \begin_inset LatexCommand \index{Assembler options}
8291
8292 \end_inset
8293
8294 .
8295  See file sdcc/as/doc/asxhtm.html for assembler options.cd
8296 \layout List
8297 \labelwidthstring 00.00.0000
8298
8299
8300 \series bold
8301 -
8302 \begin_inset ERT
8303 status Collapsed
8304
8305 \layout Standard
8306
8307 \backslash
8308 /
8309 \end_inset
8310
8311 -std-sdcc89
8312 \begin_inset LatexCommand \index{-\/-std-sdcc89}
8313
8314 \end_inset
8315
8316
8317 \series default
8318  Generally follow the C89 standard, but allow SDCC features that conflict
8319  with the standard (default).
8320 \layout List
8321 \labelwidthstring 00.00.0000
8322
8323
8324 \series bold
8325 -
8326 \begin_inset ERT
8327 status Collapsed
8328
8329 \layout Standard
8330
8331 \backslash
8332 /
8333 \end_inset
8334
8335 -std-c89
8336 \begin_inset LatexCommand \index{-\/-std-c89}
8337
8338 \end_inset
8339
8340
8341 \series default
8342  Follow the C89 standard and disable SDCC features that conflict with the
8343  standard.
8344 \layout List
8345 \labelwidthstring 00.00.0000
8346
8347
8348 \series bold
8349 -
8350 \begin_inset ERT
8351 status Collapsed
8352
8353 \layout Standard
8354
8355 \backslash
8356 /
8357 \end_inset
8358
8359 -std-sdcc99
8360 \begin_inset LatexCommand \index{-\/-std-sdcc99}
8361
8362 \end_inset
8363
8364
8365 \series default
8366  Generally follow the C99 standard, but allow SDCC features that conflict
8367  with the standard (incomplete support).
8368 \layout List
8369 \labelwidthstring 00.00.0000
8370
8371
8372 \series bold
8373 -
8374 \begin_inset ERT
8375 status Collapsed
8376
8377 \layout Standard
8378
8379 \backslash
8380 /
8381 \end_inset
8382
8383 -std-c99
8384 \begin_inset LatexCommand \index{-\/-std-sdcc99}
8385
8386 \end_inset
8387
8388
8389 \series default
8390  Follow the C99 standard and disable SDCC features that conflict with the
8391  standard (incomplete support).
8392 \layout List
8393 \labelwidthstring 00.00.0000
8394
8395
8396 \series bold
8397 -
8398 \begin_inset ERT
8399 status Collapsed
8400
8401 \layout Standard
8402
8403 \backslash
8404 /
8405 \end_inset
8406
8407 -codeseg
8408 \series default
8409
8410 \begin_inset LatexCommand \index{-\/-codeseg <Value>}
8411
8412 \end_inset
8413
8414 \SpecialChar ~
8415 <Name> The name to be used for the code
8416 \begin_inset LatexCommand \index{code}
8417
8418 \end_inset
8419
8420  segment, default CSEG.
8421  This is useful if you need to tell the compiler to put the code in a special
8422  segment so you can later on tell the linker to put this segment in a special
8423  place in memory.
8424  Can be used for instance when using bank switching to put the code in a
8425  bank.
8426 \layout List
8427 \labelwidthstring 00.00.0000
8428
8429
8430 \series bold
8431 -
8432 \begin_inset ERT
8433 status Collapsed
8434
8435 \layout Standard
8436
8437 \backslash
8438 /
8439 \end_inset
8440
8441 -constseg
8442 \series default
8443
8444 \begin_inset LatexCommand \index{-\/-constseg <Value>}
8445
8446 \end_inset
8447
8448 \SpecialChar ~
8449 <Name> The name to be used for the const
8450 \begin_inset LatexCommand \index{code}
8451
8452 \end_inset
8453
8454  segment, default CONST.
8455  This is useful if you need to tell the compiler to put the const data in
8456  a special segment so you can later on tell the linker to put this segment
8457  in a special place in memory.
8458  Can be used for instance when using bank switching to put the const data
8459  in a bank.
8460 \layout List
8461 \labelwidthstring 00.00.0000
8462
8463
8464 \series bold
8465 more-pedantic
8466 \series default
8467  Actually this is
8468 \series bold
8469 \emph on
8470 not
8471 \series default
8472 \emph default
8473  a SDCC compiler option but if you want
8474 \emph on
8475 more
8476 \emph default
8477  warnings you can use a separate tool dedicated to syntax checking like
8478  splint
8479 \begin_inset LatexCommand \label{lyx:more-pedantic-SPLINT}
8480
8481 \end_inset
8482
8483
8484 \begin_inset LatexCommand \index{lint (syntax checking tool)}
8485
8486 \end_inset
8487
8488
8489 \begin_inset LatexCommand \url{http://www.splint.org}
8490
8491 \end_inset
8492
8493 .
8494  To make your source files parseable by splint you will have to include
8495
8496 \family sans
8497 lint.h
8498 \family default
8499
8500 \begin_inset LatexCommand \index{splint (syntax checking tool)}
8501
8502 \end_inset
8503
8504  in your source file and add brackets around extended keywords (like
8505 \family sans
8506
8507 \begin_inset Quotes sld
8508 \end_inset
8509
8510 __at\SpecialChar ~
8511
8512 \series bold
8513 (
8514 \series default
8515 0xab
8516 \series bold
8517 )
8518 \series default
8519
8520 \begin_inset Quotes srd
8521 \end_inset
8522
8523
8524 \family default
8525  and
8526 \family sans
8527
8528 \begin_inset Quotes sld
8529 \end_inset
8530
8531 __interrupt\SpecialChar ~
8532 (2)
8533 \begin_inset Quotes srd
8534 \end_inset
8535
8536
8537 \family default
8538 ).
8539
8540 \newline
8541 Splint has an excellent on line manual at
8542 \begin_inset LatexCommand \url{http://www.splint.org/manual/}
8543
8544 \end_inset
8545
8546  and it's capabilities go beyond pure syntax checking.
8547  You'll need to tell splint the location of SDCC's include files so a typical
8548  command line could look like this:
8549 \newline
8550
8551 \family sans
8552 splint\SpecialChar ~
8553 -I\SpecialChar ~
8554 /usr/local/share/sdcc/include/mcs51/\SpecialChar ~
8555 \SpecialChar ~
8556 myprogram.c
8557 \layout Subsection
8558
8559 Intermediate Dump Options
8560 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
8561
8562 \end_inset
8563
8564
8565 \begin_inset LatexCommand \index{Options intermediate dump}
8566
8567 \end_inset
8568
8569
8570 \begin_inset LatexCommand \index{Intermediate dump options}
8571
8572 \end_inset
8573
8574
8575 \layout Standard
8576
8577 The following options are provided for the purpose of retargetting and debugging
8578  the compiler.
8579  They provide a means to dump the intermediate code (iCode
8580 \begin_inset LatexCommand \index{iCode}
8581
8582 \end_inset
8583
8584 ) generated by the compiler in human readable form at various stages of
8585  the compilation process.
8586  More on iCodes see chapter
8587 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
8588
8589 \end_inset
8590
8591
8592 \begin_inset Quotes srd
8593 \end_inset
8594
8595 The anatomy of the compiler
8596 \begin_inset Quotes srd
8597 \end_inset
8598
8599 .
8600 \layout List
8601 \labelwidthstring 00.00.0000
8602
8603
8604 \series bold
8605 -
8606 \begin_inset ERT
8607 status Collapsed
8608
8609 \layout Standard
8610
8611 \backslash
8612 /
8613 \end_inset
8614
8615 -dumpraw
8616 \begin_inset LatexCommand \index{-\/-dumpraw}
8617
8618 \end_inset
8619
8620
8621 \series default
8622  This option will cause the compiler to dump the intermediate code into
8623  a file of named
8624 \emph on
8625 <source filename>.dumpraw
8626 \emph default
8627  just after the intermediate code has been generated for a function, i.e.
8628  before any optimizations are done.
8629  The basic blocks
8630 \begin_inset LatexCommand \index{Basic blocks}
8631
8632 \end_inset
8633
8634  at this stage ordered in the depth first number, so they may not be in
8635  sequence of execution.
8636 \layout List
8637 \labelwidthstring 00.00.0000
8638
8639
8640 \series bold
8641 -
8642 \begin_inset ERT
8643 status Collapsed
8644
8645 \layout Standard
8646
8647 \backslash
8648 /
8649 \end_inset
8650
8651 -dumpgcse
8652 \begin_inset LatexCommand \index{-\/-dumpgcse}
8653
8654 \end_inset
8655
8656
8657 \series default
8658  Will create a dump of iCode's, after global subexpression elimination
8659 \begin_inset LatexCommand \index{Global subexpression elimination}
8660
8661 \end_inset
8662
8663 , into a file named
8664 \emph on
8665 <source filename>.dumpgcse.
8666 \layout List
8667 \labelwidthstring 00.00.0000
8668
8669
8670 \series bold
8671 -
8672 \begin_inset ERT
8673 status Collapsed
8674
8675 \layout Standard
8676
8677 \backslash
8678 /
8679 \end_inset
8680
8681 -dumpdeadcode
8682 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
8683
8684 \end_inset
8685
8686
8687 \series default
8688  Will create a dump of iCode's, after deadcode elimination
8689 \begin_inset LatexCommand \index{Dead-code elimination}
8690
8691 \end_inset
8692
8693 , into a file named
8694 \emph on
8695 <source filename>.dumpdeadcode.
8696 \layout List
8697 \labelwidthstring 00.00.0000
8698
8699
8700 \series bold
8701 -
8702 \begin_inset ERT
8703 status Collapsed
8704
8705 \layout Standard
8706
8707 \backslash
8708 /
8709 \end_inset
8710
8711 -dumploop
8712 \begin_inset LatexCommand \index{-\/-dumploop}
8713
8714 \end_inset
8715
8716
8717 \series default
8718 \size large
8719
8720 \size default
8721 Will create a dump of iCode's, after loop optimizations
8722 \begin_inset LatexCommand \index{Loop optimization}
8723
8724 \end_inset
8725
8726 , into a file named
8727 \emph on
8728 <source filename>.dumploop.
8729 \layout List
8730 \labelwidthstring 00.00.0000
8731
8732
8733 \series bold
8734 -
8735 \begin_inset ERT
8736 status Collapsed
8737
8738 \layout Standard
8739
8740 \backslash
8741 /
8742 \end_inset
8743
8744 -dumprange
8745 \begin_inset LatexCommand \index{-\/-dumprange}
8746
8747 \end_inset
8748
8749
8750 \series default
8751 \size large
8752
8753 \size default
8754 Will create a dump of iCode's, after live range analysis
8755 \begin_inset LatexCommand \index{Live range analysis}
8756
8757 \end_inset
8758
8759 , into a file named
8760 \emph on
8761 <source filename>.dumprange.
8762 \layout List
8763 \labelwidthstring 00.00.0000
8764
8765
8766 \series bold
8767 -
8768 \begin_inset ERT
8769 status Collapsed
8770
8771 \layout Standard
8772
8773 \backslash
8774 /
8775 \end_inset
8776
8777 -dumlrange
8778 \begin_inset LatexCommand \index{-\/-dumlrange}
8779
8780 \end_inset
8781
8782
8783 \series default
8784  Will dump the life ranges
8785 \begin_inset LatexCommand \index{Live range analysis}
8786
8787 \end_inset
8788
8789  for all symbols.
8790 \layout List
8791 \labelwidthstring 00.00.0000
8792
8793
8794 \series bold
8795 -
8796 \begin_inset ERT
8797 status Collapsed
8798
8799 \layout Standard
8800
8801 \backslash
8802 /
8803 \end_inset
8804
8805 -dumpregassign
8806 \begin_inset LatexCommand \index{-\/-dumpregassign}
8807
8808 \end_inset
8809
8810
8811 \bar under
8812
8813 \series default
8814 \bar default
8815 Will create a dump of iCode's, after register assignment
8816 \begin_inset LatexCommand \index{Register assignment}
8817
8818 \end_inset
8819
8820 , into a file named
8821 \emph on
8822 <source filename>.dumprassgn.
8823 \layout List
8824 \labelwidthstring 00.00.0000
8825
8826
8827 \series bold
8828 -
8829 \begin_inset ERT
8830 status Collapsed
8831
8832 \layout Standard
8833
8834 \backslash
8835 /
8836 \end_inset
8837
8838 -dumplrange
8839 \begin_inset LatexCommand \index{-\/-dumplrange}
8840
8841 \end_inset
8842
8843
8844 \series default
8845  Will create a dump of the live ranges of iTemp's
8846 \layout List
8847 \labelwidthstring 00.00.0000
8848
8849
8850 \series bold
8851 -
8852 \begin_inset ERT
8853 status Collapsed
8854
8855 \layout Standard
8856
8857 \backslash
8858 /
8859 \end_inset
8860
8861 -dumpall
8862 \begin_inset LatexCommand \index{-\/-dumpall}
8863
8864 \end_inset
8865
8866
8867 \size large
8868 \bar under
8869
8870 \series default
8871 \size default
8872 \bar default
8873 Will cause all the above mentioned dumps to be created.
8874 \layout Subsection
8875
8876 Redirecting output on Windows Shells
8877 \layout Standard
8878
8879 By default SDCC writes it's error messages to
8880 \begin_inset Quotes sld
8881 \end_inset
8882
8883 standard error
8884 \begin_inset Quotes srd
8885 \end_inset
8886
8887 .
8888  To force all messages to
8889 \begin_inset Quotes sld
8890 \end_inset
8891
8892 standard output
8893 \begin_inset Quotes srd
8894 \end_inset
8895
8896  use
8897 \series bold
8898 -
8899 \series default
8900 \emph on
8901
8902 \begin_inset ERT
8903 status Collapsed
8904
8905 \layout Standard
8906
8907 \backslash
8908 /
8909 \end_inset
8910
8911
8912 \series bold
8913 \emph default
8914 -
8915 \series default
8916 use-stdout
8917 \begin_inset LatexCommand \index{-\/-use-stdout}
8918
8919 \end_inset
8920
8921 .
8922  Additionally, if you happen to have visual studio installed in your windows
8923  machine, you can use it to compile your sources using a custom build and
8924  the SDCC -
8925 \emph on
8926
8927 \begin_inset ERT
8928 status Collapsed
8929
8930 \layout Standard
8931
8932 \backslash
8933 /
8934 \end_inset
8935
8936
8937 \emph default
8938 -vc
8939 \begin_inset LatexCommand \index{-\/-vc}
8940
8941 \end_inset
8942
8943  option.
8944  Something like this should work:
8945 \newline
8946
8947 \newline
8948
8949 \series bold
8950 c:
8951 \backslash
8952 sdcc
8953 \backslash
8954 bin
8955 \backslash
8956 sdcc.exe -
8957 \series default
8958 \emph on
8959
8960 \begin_inset ERT
8961 status Collapsed
8962
8963 \layout Standard
8964
8965 \backslash
8966 /
8967 \end_inset
8968
8969
8970 \series bold
8971 \emph default
8972 -vc -
8973 \series default
8974 \emph on
8975
8976 \begin_inset ERT
8977 status Collapsed
8978
8979 \layout Standard
8980
8981 \backslash
8982 /
8983 \end_inset
8984
8985
8986 \series bold
8987 \emph default
8988 -model-large -c $(InputPath)
8989 \layout Section
8990
8991 Environment variables
8992 \begin_inset LatexCommand \index{Environment variables}
8993
8994 \end_inset
8995
8996
8997 \layout Standard
8998
8999 SDCC recognizes the following environment variables:
9000 \layout List
9001 \labelwidthstring 00.00.0000
9002
9003
9004 \series bold
9005 SDCC_LEAVE_SIGNALS
9006 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
9007
9008 \end_inset
9009
9010
9011 \series default
9012  SDCC installs a signal handler
9013 \begin_inset LatexCommand \index{signal handler}
9014
9015 \end_inset
9016
9017  to be able to delete temporary files after an user break (^C) or an exception.
9018  If this environment variable is set, SDCC won't install the signal handler
9019  in order to be able to debug SDCC.
9020 \layout List
9021 \labelwidthstring 00.00.0000
9022
9023
9024 \series bold
9025 TMP,\SpecialChar ~
9026 TEMP,\SpecialChar ~
9027 TMPDIR
9028 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
9029
9030 \end_inset
9031
9032
9033 \series default
9034  Path, where temporary files will be created.
9035  The order of the variables is the search order.
9036  In a standard *nix environment these variables are not set, and there's
9037  no need to set them.
9038  On Windows it's recommended to set one of them.
9039 \layout List
9040 \labelwidthstring 00.00.0000
9041
9042
9043 \series bold
9044 SDCC_HOME
9045 \begin_inset LatexCommand \index{SDCC\_HOME}
9046
9047 \end_inset
9048
9049
9050 \series default
9051  Path, see section
9052 \begin_inset LatexCommand \ref{sub:Install-paths}
9053
9054 \end_inset
9055
9056 \SpecialChar ~
9057
9058 \begin_inset Quotes sld
9059 \end_inset
9060
9061  Install Paths
9062 \begin_inset Quotes srd
9063 \end_inset
9064
9065 .
9066 \layout List
9067 \labelwidthstring 00.00.0000
9068
9069
9070 \series bold
9071 SDCC_INCLUDE
9072 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
9073
9074 \end_inset
9075
9076
9077 \series default
9078  Path, see section
9079 \begin_inset LatexCommand \ref{sub:Search-Paths}
9080
9081 \end_inset
9082
9083 \SpecialChar ~
9084
9085 \begin_inset Quotes sld
9086 \end_inset
9087
9088 Search Paths
9089 \begin_inset Quotes srd
9090 \end_inset
9091
9092 .
9093 \layout List
9094 \labelwidthstring 00.00.0000
9095
9096
9097 \series bold
9098 SDCC_LIB
9099 \begin_inset LatexCommand \index{SDCC\_LIB}
9100
9101 \end_inset
9102
9103
9104 \series default
9105  Path, see section
9106 \begin_inset LatexCommand \ref{sub:Search-Paths}
9107
9108 \end_inset
9109
9110 \SpecialChar ~
9111
9112 \begin_inset Quotes sld
9113 \end_inset
9114
9115 Search Paths
9116 \begin_inset Quotes srd
9117 \end_inset
9118
9119 ..
9120 \layout Standard
9121
9122 There are some more environment variables recognized by SDCC, but these
9123  are solely used for debugging purposes.
9124  They can change or disappear very quickly, and will never be documented.
9125 \layout Section
9126
9127 Storage Class Language Extensions
9128 \layout Subsection
9129
9130 MCS51/DS390 Storage Class
9131 \begin_inset LatexCommand \index{Storage class}
9132
9133 \end_inset
9134
9135  Language Extensions
9136 \layout Standard
9137
9138 In addition to the ANSI storage classes SDCC allows the following MCS51
9139  specific storage classes:
9140 \layout Subsubsection
9141
9142 data
9143 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
9144
9145 \end_inset
9146
9147
9148 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
9149
9150 \end_inset
9151
9152  / near
9153 \begin_inset LatexCommand \index{near (storage class)}
9154
9155 \end_inset
9156
9157
9158 \begin_inset LatexCommand \index{\_\_near (storage class)}
9159
9160 \end_inset
9161
9162
9163 \layout Standard
9164
9165 This is the
9166 \series bold
9167 default
9168 \series default
9169  storage class for the Small Memory model (
9170 \emph on
9171 data
9172 \emph default
9173  and
9174 \emph on
9175 near
9176 \emph default
9177  or the more ANSI-C compliant forms
9178 \emph on
9179 __data
9180 \emph default
9181  and
9182 \emph on
9183 __near
9184 \emph default
9185  can be used synonymously).
9186  Variables declared with this storage class will be allocated in the directly
9187  addressable portion of the internal RAM of a 8051, e.g.:
9188 \layout Verse
9189
9190
9191 \family typewriter
9192 __data unsigned char test_data;
9193 \layout Standard
9194
9195 Writing 0x01 to this variable generates the assembly code:
9196 \layout Verse
9197
9198
9199 \family typewriter
9200 75*00 01\SpecialChar ~
9201 \SpecialChar ~
9202 \SpecialChar ~
9203 mov\SpecialChar ~
9204 \SpecialChar ~
9205 _test_data,#0x01
9206 \layout Subsubsection
9207
9208 xdata
9209 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9210
9211 \end_inset
9212
9213
9214 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9215
9216 \end_inset
9217
9218  / far
9219 \begin_inset LatexCommand \index{far (storage class)}
9220
9221 \end_inset
9222
9223
9224 \begin_inset LatexCommand \index{\_\_far (storage class)}
9225
9226 \end_inset
9227
9228
9229 \layout Standard
9230
9231 Variables declared with this storage class will be placed in the external
9232  RAM.
9233  This is the
9234 \series bold
9235 default
9236 \series default
9237  storage class for the Large Memory model, e.g.:
9238 \layout Verse
9239
9240
9241 \family typewriter
9242 __xdata unsigned char test_xdata;
9243 \layout Standard
9244
9245 Writing 0x01 to this variable generates the assembly code:
9246 \layout Verse
9247
9248
9249 \family typewriter
9250 90s00r00\SpecialChar ~
9251 \SpecialChar ~
9252 \SpecialChar ~
9253 mov\SpecialChar ~
9254 \SpecialChar ~
9255 dptr,#_test_xdata
9256 \newline
9257 74\SpecialChar ~
9258 01\SpecialChar ~
9259 \SpecialChar ~
9260 \SpecialChar ~
9261 \SpecialChar ~
9262 \SpecialChar ~
9263 \SpecialChar ~
9264 mov\SpecialChar ~
9265 \SpecialChar ~
9266 a,#0x01
9267 \newline
9268 F0\SpecialChar ~
9269 \SpecialChar ~
9270 \SpecialChar ~
9271 \SpecialChar ~
9272 \SpecialChar ~
9273 \SpecialChar ~
9274 \SpecialChar ~
9275 \SpecialChar ~
9276 \SpecialChar ~
9277 movx\SpecialChar ~
9278 @dptr,a
9279 \layout Subsubsection
9280
9281 idata
9282 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
9283
9284 \end_inset
9285
9286
9287 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
9288
9289 \end_inset
9290
9291
9292 \layout Standard
9293
9294 Variables declared with this storage class will be allocated into the indirectly
9295  addressable portion of the internal ram of a 8051, e.g.:
9296 \layout Verse
9297
9298
9299 \family typewriter
9300 __idata unsigned char test_idata;
9301 \layout Standard
9302
9303 Writing 0x01 to this variable generates the assembly code:
9304 \layout Verse
9305
9306
9307 \family typewriter
9308 78r00\SpecialChar ~
9309 \SpecialChar ~
9310 \SpecialChar ~
9311 \SpecialChar ~
9312 \SpecialChar ~
9313 \SpecialChar ~
9314 \SpecialChar ~
9315 mov\SpecialChar ~
9316 \SpecialChar ~
9317 r0,#_test_idata
9318 \newline
9319 76\SpecialChar ~
9320 01\SpecialChar ~
9321 \SpecialChar ~
9322 \SpecialChar ~
9323 \SpecialChar ~
9324 \SpecialChar ~
9325 \SpecialChar ~
9326 \SpecialChar ~
9327 mov\SpecialChar ~
9328 \SpecialChar ~
9329 @r0,#0x01
9330 \layout Standard
9331
9332 Please note, the first 128 byte of idata physically access the same RAM
9333  as the data memory.
9334  The original 8051 had 128 byte idata memory, nowadays most devices have
9335  256 byte idata memory.
9336  The stack
9337 \begin_inset LatexCommand \index{stack}
9338
9339 \end_inset
9340
9341  is located in idata memory.
9342 \layout Subsubsection
9343
9344 pdata
9345 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
9346
9347 \end_inset
9348
9349
9350 \begin_inset LatexCommand \index{\_\_pdata (mcs51, ds390 storage class)}
9351
9352 \end_inset
9353
9354
9355 \layout Standard
9356
9357 Paged xdata access is just as straightforward as using the other addressing
9358  modes of a 8051.
9359  It is typically located at the start of xdata and has a maximum size of
9360  256 bytes.
9361  The following example writes 0x01 to the pdata variable.
9362  Please note, pdata access physically accesses xdata memory.
9363  The high byte of the address is determined by port P2
9364 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
9365
9366 \end_inset
9367
9368 (or in case of some 8051 variants by a separate Special Function Register,
9369  see section
9370 \begin_inset LatexCommand \ref{sub:MCS51-variants}
9371
9372 \end_inset
9373
9374 ).
9375  This is the
9376 \series bold
9377 default
9378 \series default
9379  storage class for the Medium Memory model, e.g.:
9380 \layout Verse
9381
9382
9383 \family typewriter
9384 __pdata unsigned char test_pdata;
9385 \layout Standard
9386
9387 Writing 0x01 to this variable generates the assembly code:
9388 \layout Verse
9389
9390
9391 \family typewriter
9392 78r00\SpecialChar ~
9393 \SpecialChar ~
9394 \SpecialChar ~
9395 \SpecialChar ~
9396 \SpecialChar ~
9397 \SpecialChar ~
9398 mov r0,#_test_pdata
9399 \newline
9400 74 01\SpecialChar ~
9401 \SpecialChar ~
9402 \SpecialChar ~
9403 \SpecialChar ~
9404 \SpecialChar ~
9405 \SpecialChar ~
9406 mov a,#0x01
9407 \newline
9408 F2\SpecialChar ~
9409 \SpecialChar ~
9410 \SpecialChar ~
9411 \SpecialChar ~
9412 \SpecialChar ~
9413 \SpecialChar ~
9414 \SpecialChar ~
9415 \SpecialChar ~
9416 \SpecialChar ~
9417 movx @r0,a
9418 \layout Standard
9419
9420 If the -
9421 \begin_inset ERT
9422 status Collapsed
9423
9424 \layout Standard
9425
9426 \backslash
9427 /
9428 \end_inset
9429
9430 -xstack
9431 \begin_inset LatexCommand \index{-\/-xstack}
9432
9433 \end_inset
9434
9435  option is used the pdata memory area is followed by the xstack memory area
9436  and the sum of their sizes is limited to 256 bytes.
9437 \layout Subsubsection
9438
9439 code
9440 \begin_inset LatexCommand \index{code}
9441
9442 \end_inset
9443
9444
9445 \begin_inset LatexCommand \index{\_\_code}
9446
9447 \end_inset
9448
9449
9450 \layout Standard
9451
9452 'Variables' declared with this storage class will be placed in the code
9453  memory:
9454 \layout Verse
9455
9456
9457 \family typewriter
9458 __code unsigned char test_code;
9459 \layout Standard
9460
9461 Read access to this variable generates the assembly code:
9462 \layout Verse
9463
9464
9465 \family typewriter
9466 90s00r6F\SpecialChar ~
9467 \SpecialChar ~
9468 \SpecialChar ~
9469 mov dptr,#_test_code
9470 \newline
9471 E4\SpecialChar ~
9472 \SpecialChar ~
9473 \SpecialChar ~
9474 \SpecialChar ~
9475 \SpecialChar ~
9476 \SpecialChar ~
9477 \SpecialChar ~
9478 \SpecialChar ~
9479 \SpecialChar ~
9480 clr a
9481 \newline
9482 93\SpecialChar ~
9483 \SpecialChar ~
9484 \SpecialChar ~
9485 \SpecialChar ~
9486 \SpecialChar ~
9487 \SpecialChar ~
9488 \SpecialChar ~
9489 \SpecialChar ~
9490 \SpecialChar ~
9491 movc a,@a+dptr
9492 \layout Standard
9493
9494
9495 \family typewriter
9496 char
9497 \family default
9498  indexed arrays of characters in code memory can be accessed efficiently:
9499 \layout Verse
9500
9501
9502 \family typewriter
9503 __code char test_array[] = {'c','h','e','a','p'};
9504 \layout Standard
9505
9506 Read access to this array using an 8-bit unsigned index generates the assembly
9507  code:
9508 \layout Verse
9509
9510
9511 \family typewriter
9512 E5*00\SpecialChar ~
9513 \SpecialChar ~
9514 \SpecialChar ~
9515 \SpecialChar ~
9516 \SpecialChar ~
9517 \SpecialChar ~
9518 mov a,_index
9519 \layout Verse
9520
9521
9522 \family typewriter
9523 90s00r41\SpecialChar ~
9524 \SpecialChar ~
9525 \SpecialChar ~
9526 mov dptr,#_test_array
9527 \layout Verse
9528
9529
9530 \family typewriter
9531 93\SpecialChar ~
9532 \SpecialChar ~
9533 \SpecialChar ~
9534 \SpecialChar ~
9535 \SpecialChar ~
9536 \SpecialChar ~
9537 \SpecialChar ~
9538 \SpecialChar ~
9539 \SpecialChar ~
9540 movc a,@a+dptr
9541 \layout Subsubsection
9542
9543 bit
9544 \begin_inset LatexCommand \index{bit}
9545
9546 \end_inset
9547
9548
9549 \begin_inset LatexCommand \index{\_\_bit}
9550
9551 \end_inset
9552
9553
9554 \layout Standard
9555
9556 This is a data-type and a storage class specifier.
9557  When a variable is declared as a bit, it is allocated into the bit addressable
9558  memory of 8051, e.g.:
9559 \layout Verse
9560
9561
9562 \family typewriter
9563 __bit test_bit;
9564 \layout Standard
9565
9566 Writing 1 to this variable generates the assembly code:
9567 \layout Verse
9568
9569
9570 \family typewriter
9571 D2*00\SpecialChar ~
9572 \SpecialChar ~
9573 \SpecialChar ~
9574 \SpecialChar ~
9575 \SpecialChar ~
9576 \SpecialChar ~
9577 \SpecialChar ~
9578 setb\SpecialChar ~
9579 _test_bit
9580 \layout Standard
9581
9582 The bit addressable memory consists of 128 bits which are located from 0x20
9583  to 0x2f in data memory.
9584
9585 \newline
9586 Apart from this 8051 specific storage class most architectures support ANSI-C
9587  bitfields
9588 \begin_inset LatexCommand \index{bitfields}
9589
9590 \end_inset
9591
9592
9593 \begin_inset Foot
9594 collapsed false
9595
9596 \layout Standard
9597
9598 Not really meant as examples, but nevertheless showing what bitfields are
9599  about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
9600 \end_inset
9601
9602 .
9603  In accordance with ISO/IEC 9899 bits and bitfields without an explicit
9604  signed modifier are implemented as unsigned.
9605 \layout Subsubsection
9606
9607 sfr
9608 \begin_inset LatexCommand \index{sfr}
9609
9610 \end_inset
9611
9612
9613 \begin_inset LatexCommand \index{\_\_sfr}
9614
9615 \end_inset
9616
9617  / sfr16
9618 \begin_inset LatexCommand \index{sfr16}
9619
9620 \end_inset
9621
9622
9623 \begin_inset LatexCommand \index{\_\_sfr16}
9624
9625 \end_inset
9626
9627  / sfr32
9628 \begin_inset LatexCommand \index{sfr32}
9629
9630 \end_inset
9631
9632
9633 \begin_inset LatexCommand \index{\_\_sfr32}
9634
9635 \end_inset
9636
9637  / sbit
9638 \begin_inset LatexCommand \index{\_\_sbit}
9639
9640 \end_inset
9641
9642
9643 \layout Standard
9644
9645 Like the bit keyword,
9646 \emph on
9647 sfr / sfr16 / sfr32 / sbit
9648 \emph default
9649 signify both a data-type and storage class, they are used to describe the
9650
9651 \emph on
9652 s
9653 \emph default
9654 pecial
9655 \emph on
9656 f
9657 \emph default
9658 unction
9659 \emph on
9660 r
9661 \emph default
9662 egisters and
9663 \emph on
9664 s
9665 \emph default
9666 pecial
9667 \emph on
9668 bit
9669 \emph default
9670  variables of a 8051, eg:
9671 \layout Verse
9672
9673
9674 \family typewriter
9675 __sfr __at
9676 \begin_inset LatexCommand \index{at}
9677
9678 \end_inset
9679
9680
9681 \begin_inset LatexCommand \index{\_\_at}
9682
9683 \end_inset
9684
9685  (0x80) P0;\SpecialChar ~
9686  /* special function register P0 at location 0x80 */
9687 \newline
9688 /* 16 bit special function register combination for timer 0 */
9689 \newline
9690 /* with the high byte at location 0x8C and the low byte at location 0x8A
9691  */
9692 \newline
9693 __sfr16 __at
9694 \begin_inset LatexCommand \index{at}
9695
9696 \end_inset
9697
9698
9699 \begin_inset LatexCommand \index{\_\_at}
9700
9701 \end_inset
9702
9703  (0x8C8A) TMR0;
9704 \newline
9705 __sbit __at (0xd7) CY; /* CY (Carry Flag
9706 \begin_inset LatexCommand \index{Flags}
9707
9708 \end_inset
9709
9710
9711 \begin_inset LatexCommand \index{Carry flag}
9712
9713 \end_inset
9714
9715 ) */
9716 \layout Standard
9717
9718 Special function registers which are located on an address dividable by
9719  8 are bit-addressable, an
9720 \emph on
9721  sbit
9722 \emph default
9723  addresses a specific bit within these sfr.
9724 \newline
9725 16 Bit and 32 bit special function register combinations which require a
9726  certain access order are better not declared using
9727 \emph on
9728 sfr16
9729 \emph default
9730  or
9731 \emph on
9732 sfr32.
9733
9734 \emph default
9735  Allthough SDCC usually accesses them Least Significant Byte (LSB) first,
9736  this is not guaranteed.
9737 \layout Subsubsection
9738
9739 Pointers
9740 \begin_inset LatexCommand \index{Pointer}
9741
9742 \end_inset
9743
9744  to MCS51/DS390 specific memory spaces
9745 \layout Standard
9746
9747 SDCC allows (via language extensions) pointers to explicitly point to any
9748  of the memory spaces
9749 \begin_inset LatexCommand \index{Memory model}
9750
9751 \end_inset
9752
9753  of the 8051.
9754  In addition to the explicit pointers, the compiler uses (by default) generic
9755  pointers which can be used to point to any of the memory spaces.
9756 \newline
9757
9758 \newline
9759 Pointer declaration examples:
9760 \layout Verse
9761
9762
9763 \family typewriter
9764 /* pointer physically in internal ram pointing to object in external ram
9765  */
9766 \newline
9767 __xdata unsigned char * __data p;
9768 \newline
9769
9770 \newline
9771 /* pointer physically in external ram pointing to object in internal ram
9772  */
9773 \newline
9774 __data unsigned char * __xdata p;
9775 \newline
9776
9777 \newline
9778 /* pointer physically in code rom pointing to data in xdata space */
9779 \newline
9780 __xdata unsigned char * __code p;
9781 \newline
9782
9783 \newline
9784 /* pointer physically in code space pointing to data in code space */
9785 \newline
9786 __code unsigned char * __code p;
9787 \newline
9788
9789 \newline
9790 /* the following is a generic pointer physically located in xdata space
9791  */
9792 \newline
9793 char * __xdata p;
9794 \newline
9795
9796 \newline
9797 /* the following is a function pointer physically located in data space
9798  */
9799 \newline
9800 char (* __data fp)(void);
9801 \layout Standard
9802
9803 Well you get the idea.
9804
9805 \newline
9806
9807 \newline
9808 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
9809 \emph on
9810 generic
9811 \emph default
9812  pointers.
9813
9814 \size small
9815
9816 \newline
9817
9818 \newline
9819
9820 \size default
9821 The highest order byte of the
9822 \emph on
9823 generic
9824 \emph default
9825  pointers contains the data space information.
9826  Assembler support routines are called whenever data is stored or retrieved
9827  using
9828 \emph on
9829 generic
9830 \emph default
9831  pointers.
9832  These are useful for developing reusable library
9833 \begin_inset LatexCommand \index{Libraries}
9834
9835 \end_inset
9836
9837  routines.
9838  Explicitly specifying the pointer type will generate the most efficient
9839  code.
9840 \layout Subsubsection
9841
9842 Notes on MCS51 memory
9843 \begin_inset LatexCommand \index{MCS51 memory}
9844
9845 \end_inset
9846
9847  layout
9848 \layout Standard
9849
9850 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
9851  RAM memory which is structured as follows:
9852 \newline
9853
9854 \newline
9855 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
9856
9857 \newline
9858 - Bytes 20-2F - 16 bytes to hold 128 bit
9859 \begin_inset LatexCommand \index{bit}
9860
9861 \end_inset
9862
9863  variables and,
9864 \newline
9865 - Bytes 30-7F - 80 bytes for general purpose use.
9866 \newline
9867
9868 \layout Standard
9869
9870 Additionally some members of the MCS51 family may have up to 128 bytes of
9871  additional, indirectly addressable, internal RAM memory (
9872 \emph on
9873 idata
9874 \emph default
9875
9876 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
9877
9878 \end_inset
9879
9880
9881 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
9882
9883 \end_inset
9884
9885 ).
9886  Furthermore, some chips may have some built in external memory (
9887 \emph on
9888 xdata
9889 \emph default
9890
9891 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9892
9893 \end_inset
9894
9895
9896 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9897
9898 \end_inset
9899
9900 ) which should not be confused with the internal, directly addressable RAM
9901  memory (
9902 \emph on
9903 data
9904 \emph default
9905
9906 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
9907
9908 \end_inset
9909
9910
9911 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
9912
9913 \end_inset
9914
9915 ).
9916  Sometimes this built in
9917 \emph on
9918 xdata
9919 \emph default
9920  memory has to be activated before using it (you can probably find this
9921  information on the datasheet of the microcontroller your are using, see
9922  also section
9923 \begin_inset LatexCommand \ref{sub:Startup-Code}
9924
9925 \end_inset
9926
9927 \SpecialChar ~
9928 Startup-Code).
9929 \layout Standard
9930
9931 Normally SDCC will only use the first bank
9932 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
9933
9934 \end_inset
9935
9936  of registers (register bank 0), but it is possible to specify that other
9937  banks of registers (keyword
9938 \emph on
9939 using
9940 \emph default
9941
9942 \emph on
9943
9944 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
9945
9946 \end_inset
9947
9948
9949 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
9950
9951 \end_inset
9952
9953
9954 \emph default
9955 ) should be used in interrupt
9956 \begin_inset LatexCommand \index{interrupt}
9957
9958 \end_inset
9959
9960
9961 \begin_inset LatexCommand \index{\_\_interrupt}
9962
9963 \end_inset
9964
9965  routines.
9966  By default, the compiler will place the stack after the last byte of allocated
9967  memory for variables.
9968  For example, if the first 2 banks of registers are used, and only four
9969  bytes are used for
9970 \emph on
9971 data
9972 \emph default
9973  variables, it will position the base of the internal stack at address 20
9974  (0x14).
9975  This implies that as the stack
9976 \begin_inset LatexCommand \index{stack}
9977
9978 \end_inset
9979
9980  grows, it will use up the remaining register banks, and the 16 bytes used
9981  by the 128 bit variables, and 80 bytes for general purpose use.
9982  If any bit variables are used, the data variables will be placed in unused
9983  register banks and after the byte holding the last bit variable.
9984  For example, if register banks 0 and 1 are used, and there are 9 bit variables
9985  (two bytes used),
9986 \emph on
9987 data
9988 \emph default
9989  variables will be placed starting from address 0x10 to 0x20 and continue
9990  at address 0x22.
9991  You can also use -
9992 \begin_inset ERT
9993 status Collapsed
9994
9995 \layout Standard
9996
9997 \backslash
9998 /
9999 \end_inset
10000
10001 -data-loc
10002 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
10003
10004 \end_inset
10005
10006  to specify the start address of the
10007 \emph on
10008 data
10009 \emph default
10010  and -
10011 \begin_inset ERT
10012 status Collapsed
10013
10014 \layout Standard
10015
10016 \backslash
10017 /
10018 \end_inset
10019
10020 -iram-size
10021 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
10022
10023 \end_inset
10024
10025  to specify the size of the total internal RAM (
10026 \emph on
10027 data
10028 \emph default
10029 +
10030 \emph on
10031 idata
10032 \emph default
10033 ).
10034
10035 \newline
10036
10037 \layout Standard
10038
10039 By default the 8051 linker will place the stack after the last byte of (i)data
10040  variables.
10041  Option -
10042 \begin_inset ERT
10043 status Collapsed
10044
10045 \layout Standard
10046
10047 \backslash
10048 /
10049 \end_inset
10050
10051 -stack-loc
10052 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
10053
10054 \end_inset
10055
10056  allows you to specify the start of the stack, i.e.
10057  you could start it after any data in the general purpose area.
10058  If your microcontroller has additional indirectly addressable internal
10059  RAM (
10060 \emph on
10061 idata
10062 \emph default
10063 ) you can place the stack on it.
10064  You may also need to use -
10065 \begin_inset ERT
10066 status Collapsed
10067
10068 \layout Standard
10069
10070 \backslash
10071 /
10072 \end_inset
10073
10074 -xdata-loc
10075 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
10076
10077 \end_inset
10078
10079  to set the start address of the external RAM (
10080 \emph on
10081 xdata
10082 \emph default
10083 ) and -
10084 \begin_inset ERT
10085 status Collapsed
10086
10087 \layout Standard
10088
10089 \backslash
10090 /
10091 \end_inset
10092
10093 -xram-size
10094 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
10095
10096 \end_inset
10097
10098  to specify its size.
10099  Same goes for the code memory, using -
10100 \begin_inset ERT
10101 status Collapsed
10102
10103 \layout Standard
10104
10105 \backslash
10106 /
10107 \end_inset
10108
10109 -code-loc
10110 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
10111
10112 \end_inset
10113
10114  and -
10115 \begin_inset ERT
10116 status Collapsed
10117
10118 \layout Standard
10119
10120 \backslash
10121 /
10122 \end_inset
10123
10124 -code-size
10125 \begin_inset LatexCommand \index{-\/-code-size <Value>}
10126
10127 \end_inset
10128
10129 .
10130  If in doubt, don't specify any options and see if the resulting memory
10131  layout is appropriate, then you can adjust it.
10132 \layout Standard
10133
10134 The linker generates two files with memory allocation information.
10135  The first, with extension .map
10136 \begin_inset LatexCommand \index{<file>.map}
10137
10138 \end_inset
10139
10140  shows all the variables and segments.
10141  The second with extension .mem
10142 \begin_inset LatexCommand \index{<file>.mem}
10143
10144 \end_inset
10145
10146  shows the final memory layout.
10147  The linker will complain either if memory segments overlap, there is not
10148  enough memory, or there is not enough space for stack.
10149  If you get any linking warnings and/or errors related to stack or segments
10150  allocation, take a look at either the .map or .mem files to find out what
10151  the problem is.
10152  The .mem file may even suggest a solution to the problem.
10153 \layout Subsection
10154
10155 Z80/Z180 Storage Class
10156 \begin_inset LatexCommand \index{Storage class}
10157
10158 \end_inset
10159
10160  Language Extensions
10161 \layout Subsubsection
10162
10163 sfr
10164 \begin_inset LatexCommand \index{sfr}
10165
10166 \end_inset
10167
10168
10169 \begin_inset LatexCommand \index{\_\_sfr}
10170
10171 \end_inset
10172
10173  (in/out to 8-bit addresses)
10174 \layout Standard
10175
10176 The Z80
10177 \begin_inset LatexCommand \index{Z80}
10178
10179 \end_inset
10180
10181  family has separate address spaces for memory and
10182 \emph on
10183 i
10184 \emph default
10185 nput/
10186 \emph on
10187 o
10188 \emph default
10189 utput memory.
10190  I/O memory
10191 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
10192
10193 \end_inset
10194
10195  is accessed with special instructions, e.g.:
10196 \layout Verse
10197
10198
10199 \family typewriter
10200 sfr at 0x78 IoPort;\SpecialChar ~
10201 \SpecialChar ~
10202 /* define a var in I/O space at 78h called IoPort */
10203
10204 \layout Standard
10205
10206 Writing 0x01 to this variable generates the assembly code:
10207 \layout Verse
10208
10209
10210 \family typewriter
10211 3E 01\SpecialChar ~
10212 \SpecialChar ~
10213 \SpecialChar ~
10214 \SpecialChar ~
10215 \SpecialChar ~
10216 \SpecialChar ~
10217 ld a,#0x01
10218 \newline
10219 D3 78\SpecialChar ~
10220 \SpecialChar ~
10221 \SpecialChar ~
10222 \SpecialChar ~
10223 \SpecialChar ~
10224 \SpecialChar ~
10225 out (_IoPort),a
10226 \layout Subsubsection
10227
10228 banked sfr
10229 \begin_inset LatexCommand \index{sfr}
10230
10231 \end_inset
10232
10233
10234 \begin_inset LatexCommand \index{\_\_sfr}
10235
10236 \end_inset
10237
10238  (in/out to 16-bit addresses)
10239 \layout Standard
10240
10241 The keyword
10242 \emph on
10243 banked
10244 \emph default
10245  is used to support 16 bit addresses in I/O memory e.g.:
10246 \layout Verse
10247
10248
10249 \family typewriter
10250 sfr banked at
10251 \begin_inset LatexCommand \index{at}
10252
10253 \end_inset
10254
10255
10256 \begin_inset LatexCommand \index{\_\_at}
10257
10258 \end_inset
10259
10260  0x123 IoPort;
10261 \layout Standard
10262
10263 Writing 0x01 to this variable generates the assembly code:
10264 \layout Verse
10265
10266
10267 \family typewriter
10268 01 23 01\SpecialChar ~
10269 \SpecialChar ~
10270 \SpecialChar ~
10271 ld bc,#_IoPort
10272 \newline
10273 3E 01\SpecialChar ~
10274 \SpecialChar ~
10275 \SpecialChar ~
10276 \SpecialChar ~
10277 \SpecialChar ~
10278 \SpecialChar ~
10279 ld a,#0x01
10280 \newline
10281 ED 79\SpecialChar ~
10282 \SpecialChar ~
10283 \SpecialChar ~
10284 \SpecialChar ~
10285 \SpecialChar ~
10286 \SpecialChar ~
10287 out (c),a
10288 \layout Subsubsection
10289
10290 sfr
10291 \begin_inset LatexCommand \index{sfr}
10292
10293 \end_inset
10294
10295
10296 \begin_inset LatexCommand \index{\_\_sfr}
10297
10298 \end_inset
10299
10300  (in0/out0 to 8 bit addresses on Z180
10301 \begin_inset LatexCommand \index{Z180}
10302
10303 \end_inset
10304
10305 /HD64180
10306 \begin_inset LatexCommand \index{HD64180}
10307
10308 \end_inset
10309
10310 )
10311 \layout Standard
10312
10313 The compiler option -
10314 \begin_inset ERT
10315 status Collapsed
10316
10317 \layout Standard
10318
10319 \backslash
10320 /
10321 \end_inset
10322
10323 -portmode=180 (80) and a compiler #pragma\SpecialChar ~
10324 portmode
10325 \begin_inset LatexCommand \index{\#pragma portmode}
10326
10327 \end_inset
10328
10329 =z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
10330 ns
10331 \family typewriter
10332 in0/out0
10333 \family default
10334  instead of
10335 \family typewriter
10336 in/out
10337 \family default
10338 .
10339  If you include the file z180.h this will be set automatically.
10340 \layout Subsection
10341
10342 HC08 Storage Class
10343 \begin_inset LatexCommand \index{Storage class}
10344
10345 \end_inset
10346
10347  Language Extensions
10348 \layout Subsubsection
10349
10350 data
10351 \begin_inset LatexCommand \index{data (hc08 storage class)}
10352
10353 \end_inset
10354
10355
10356 \begin_inset LatexCommand \index{\_\_data (hc08 storage class)}
10357
10358 \end_inset
10359
10360
10361 \layout Standard
10362
10363 The data storage class declares a variable that resides in the first 256
10364  bytes of memory (the direct page).
10365  The HC08 is most efficient at accessing variables (especially pointers)
10366  stored here.
10367 \layout Subsubsection
10368
10369 xdata
10370 \begin_inset LatexCommand \index{xdata (hc08 storage class)}
10371
10372 \end_inset
10373
10374
10375 \begin_inset LatexCommand \index{\_\_xdata (hc08 storage class)}
10376
10377 \end_inset
10378
10379
10380 \layout Standard
10381
10382 The xdata storage class declares a variable that can reside anywhere in
10383  memory.
10384  This is the default if no storage class is specified.
10385
10386 \layout Section
10387
10388 Absolute Addressing
10389 \begin_inset LatexCommand \index{Absolute addressing}
10390
10391 \end_inset
10392
10393
10394 \layout Standard
10395
10396 Data items can be assigned an absolute address with the
10397 \emph on
10398 at
10399 \begin_inset LatexCommand \index{at}
10400
10401 \end_inset
10402
10403
10404 \begin_inset LatexCommand \index{\_\_at}
10405
10406 \end_inset
10407
10408  <address>
10409 \emph default
10410  keyword, in addition to a storage class, e.g.:
10411 \layout Verse
10412
10413
10414 \family typewriter
10415 xdata
10416 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
10417
10418 \end_inset
10419
10420
10421 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
10422
10423 \end_inset
10424
10425  at
10426 \begin_inset LatexCommand \index{at}
10427
10428 \end_inset
10429
10430
10431 \begin_inset LatexCommand \index{\_\_at}
10432
10433 \end_inset
10434
10435  (0x7ffe) unsigned int chksum;
10436 \layout Standard
10437
10438 or
10439 \layout Verse
10440
10441
10442 \family typewriter
10443 __xdata __at (0x7ffe) unsigned int chksum;
10444 \layout Standard
10445
10446 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
10447  of the external ram.
10448  The compiler does
10449 \emph on
10450 not
10451 \emph default
10452  reserve any space for variables declared in this way
10453 \begin_inset Marginal
10454 collapsed true
10455
10456 \layout Standard
10457
10458
10459 \series bold
10460 \SpecialChar ~
10461 !
10462 \end_inset
10463
10464  (they are implemented with an equate in the assembler).
10465  Thus it is left to the programmer to make sure there are no overlaps with
10466  other variables that are declared without the absolute address.
10467  The assembler listing file (.lst
10468 \begin_inset LatexCommand \index{<file>.lst}
10469
10470 \end_inset
10471
10472 ) and the linker output files (.rst
10473 \begin_inset LatexCommand \index{<file>.rst}
10474
10475 \end_inset
10476
10477 ) and (.map
10478 \begin_inset LatexCommand \index{<file>.map}
10479
10480 \end_inset
10481
10482 ) are good places to look for such overlaps.
10483  Variables with an absolute address are
10484 \emph on
10485 not
10486 \begin_inset Marginal
10487 collapsed true
10488
10489 \layout Standard
10490
10491
10492 \series bold
10493 \SpecialChar ~
10494 !
10495 \end_inset
10496
10497
10498 \emph default
10499  initialized
10500 \begin_inset LatexCommand \index{Variable initialization}
10501
10502 \end_inset
10503
10504 .
10505 \layout Standard
10506
10507 In case of memory mapped I/O devices the keyword
10508 \emph on
10509 volatile
10510 \emph default
10511  has to be used to tell the compiler that accesses might not be removed:
10512 \layout Verse
10513
10514
10515 \family typewriter
10516 volatile
10517 \begin_inset LatexCommand \index{volatile}
10518
10519 \end_inset
10520
10521  __xdata
10522 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
10523
10524 \end_inset
10525
10526  __at
10527 \begin_inset LatexCommand \index{at}
10528
10529 \end_inset
10530
10531  (0x8000) unsigned char PORTA_8255;
10532 \layout Standard
10533
10534 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
10535 r) array
10536 \family typewriter
10537 \size footnotesize
10538
10539 \begin_inset LatexCommand \index{Aligned array}
10540
10541 \end_inset
10542
10543
10544 \family default
10545 \size default
10546  starts at a block (256 byte) boundary
10547 \begin_inset LatexCommand \index{block boundary}
10548
10549 \end_inset
10550
10551  (section
10552 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
10553
10554 \end_inset
10555
10556  has an example).
10557 \newline
10558 Absolute addresses can be specified for variables in all storage classes,
10559  e.g.:
10560 \layout Verse
10561
10562
10563 \family typewriter
10564 __bit
10565 \begin_inset LatexCommand \index{bit}
10566
10567 \end_inset
10568
10569  __at
10570 \begin_inset LatexCommand \index{at}
10571
10572 \end_inset
10573
10574  (0x02) bvar;
10575 \layout Standard
10576
10577 The above example will allocate the variable at offset 0x02 in the bit-addressab
10578 le space.
10579  There is no real advantage to assigning absolute addresses to variables
10580  in this manner, unless you want strict control over all the variables allocated.
10581  One possible use would be to write hardware portable code.
10582  For example, if you have a routine that uses one or more of the microcontroller
10583  I/O pins, and such pins are different for two different hardwares, you
10584  can declare the I/O pins in your routine using:
10585 \layout Verse
10586
10587
10588 \family typewriter
10589 extern volatile
10590 \begin_inset LatexCommand \index{volatile}
10591
10592 \end_inset
10593
10594  __bit MOSI;\SpecialChar ~
10595 \SpecialChar ~
10596 \SpecialChar ~
10597 \SpecialChar ~
10598 /* master out, slave in */
10599 \newline
10600 extern volatile __bit MISO;\SpecialChar ~
10601 \SpecialChar ~
10602 \SpecialChar ~
10603 \SpecialChar ~
10604 /* master in, slave out */
10605 \newline
10606 extern volatile __bit MCLK;\SpecialChar ~
10607 \SpecialChar ~
10608 \SpecialChar ~
10609 \SpecialChar ~
10610 /* master clock */
10611 \newline
10612
10613 \newline
10614 /* Input and Output of a byte on a 3-wire serial bus.
10615 \newline
10616 \SpecialChar ~
10617 \SpecialChar ~
10618 \SpecialChar ~
10619 If needed adapt polarity of clock, polarity of data and bit order
10620 \newline
10621 \SpecialChar ~
10622 */
10623 \newline
10624 unsigned char spi_io(unsigned char out_byte)
10625 \newline
10626 {
10627 \newline
10628 \SpecialChar ~
10629 \SpecialChar ~
10630 \SpecialChar ~
10631 \SpecialChar ~
10632 unsigned char i=8;
10633 \newline
10634 \SpecialChar ~
10635 \SpecialChar ~
10636 \SpecialChar ~
10637 \SpecialChar ~
10638 do {
10639 \newline
10640 \SpecialChar ~
10641 \SpecialChar ~
10642 \SpecialChar ~
10643 \SpecialChar ~
10644 \SpecialChar ~
10645 \SpecialChar ~
10646 \SpecialChar ~
10647 \SpecialChar ~
10648 MOSI = out_byte & 0x80;
10649 \newline
10650 \SpecialChar ~
10651 \SpecialChar ~
10652 \SpecialChar ~
10653 \SpecialChar ~
10654 \SpecialChar ~
10655 \SpecialChar ~
10656 \SpecialChar ~
10657 \SpecialChar ~
10658 out_byte <<= 1;
10659 \newline
10660 \SpecialChar ~
10661 \SpecialChar ~
10662 \SpecialChar ~
10663 \SpecialChar ~
10664 \SpecialChar ~
10665 \SpecialChar ~
10666 \SpecialChar ~
10667 \SpecialChar ~
10668 MCLK = 1;
10669 \newline
10670 \SpecialChar ~
10671 \SpecialChar ~
10672 \SpecialChar ~
10673 \SpecialChar ~
10674 \SpecialChar ~
10675 \SpecialChar ~
10676 \SpecialChar ~
10677 \SpecialChar ~
10678 /* _asm nop _endasm; */\SpecialChar ~
10679 \SpecialChar ~
10680 \SpecialChar ~
10681 \SpecialChar ~
10682 \SpecialChar ~
10683 \SpecialChar ~
10684 \SpecialChar ~
10685 \SpecialChar ~
10686 /* for slow peripherals */
10687 \newline
10688 \SpecialChar ~
10689 \SpecialChar ~
10690 \SpecialChar ~
10691 \SpecialChar ~
10692 \SpecialChar ~
10693 \SpecialChar ~
10694 \SpecialChar ~
10695 \SpecialChar ~
10696 if(MISO)
10697 \newline
10698 \SpecialChar ~
10699 \SpecialChar ~
10700 \SpecialChar ~
10701 \SpecialChar ~
10702 \SpecialChar ~
10703 \SpecialChar ~
10704 \SpecialChar ~
10705 \SpecialChar ~
10706 \SpecialChar ~
10707 \SpecialChar ~
10708 \SpecialChar ~
10709 \SpecialChar ~
10710 out_byte += 1;
10711 \newline
10712 \SpecialChar ~
10713 \SpecialChar ~
10714 \SpecialChar ~
10715 \SpecialChar ~
10716 \SpecialChar ~
10717 \SpecialChar ~
10718 \SpecialChar ~
10719 \SpecialChar ~
10720 MCLK = 0;
10721 \newline
10722 \SpecialChar ~
10723 \SpecialChar ~
10724 \SpecialChar ~
10725 \SpecialChar ~
10726 } while(--i);
10727 \newline
10728 \SpecialChar ~
10729 \SpecialChar ~
10730 \SpecialChar ~
10731 \SpecialChar ~
10732 return out_byte;
10733 \newline
10734 }
10735 \layout Standard
10736
10737 Then, someplace in the code for the first hardware you would use
10738 \layout Verse
10739
10740
10741 \family typewriter
10742 __bit __at
10743 \begin_inset LatexCommand \index{at}
10744
10745 \end_inset
10746
10747
10748 \begin_inset LatexCommand \index{\_\_at}
10749
10750 \end_inset
10751
10752  (0x80) MOSI;\SpecialChar ~
10753 \SpecialChar ~
10754 \SpecialChar ~
10755 \SpecialChar ~
10756 /* I/O port 0, bit 0 */
10757 \newline
10758 __bit __at (0x81) MISO;\SpecialChar ~
10759 \SpecialChar ~
10760 \SpecialChar ~
10761 \SpecialChar ~
10762 /* I/O port 0, bit 1 */
10763 \newline
10764 __bit __at (0x82) MCLK;\SpecialChar ~
10765 \SpecialChar ~
10766 \SpecialChar ~
10767 \SpecialChar ~
10768 /* I/O port 0, bit 2 */
10769 \layout Standard
10770
10771 Similarly, for the second hardware you would use
10772 \layout Verse
10773
10774
10775 \family typewriter
10776 __bit __at (0x83) MOSI;\SpecialChar ~
10777 \SpecialChar ~
10778 \SpecialChar ~
10779 \SpecialChar ~
10780 /* I/O port 0, bit 3 */
10781 \newline
10782 __bit __at (0x91) MISO;\SpecialChar ~
10783 \SpecialChar ~
10784 \SpecialChar ~
10785 \SpecialChar ~
10786 /* I/O port 1, bit 1 */
10787 \newline
10788 __bit
10789 \begin_inset LatexCommand \index{bit}
10790
10791 \end_inset
10792
10793  __at (0x92) MCLK;\SpecialChar ~
10794 \SpecialChar ~
10795 \SpecialChar ~
10796 \SpecialChar ~
10797 /* I/O port 1, bit 2 */
10798 \layout Standard
10799
10800 and you can use the same hardware dependent routine without changes, as
10801  for example in a library.
10802  This is somehow similar to sbit, but only one absolute address has to be
10803  specified in the whole project.
10804 \layout Section
10805
10806 Parameters
10807 \begin_inset LatexCommand \index{Parameters}
10808
10809 \end_inset
10810
10811
10812 \begin_inset LatexCommand \index{function parameter}
10813
10814 \end_inset
10815
10816  & Local Variables
10817 \begin_inset LatexCommand \index{local variables}
10818
10819 \end_inset
10820
10821
10822 \begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
10823
10824 \end_inset
10825
10826
10827 \layout Standard
10828
10829 Automatic (local) variables and parameters to functions can either be placed
10830  on the stack or in data-space.
10831  The default action of the compiler is to place these variables in the internal
10832  RAM (for small model) or external RAM (for large model).
10833  This in fact makes them similar to
10834 \emph on
10835 static
10836 \begin_inset LatexCommand \index{static}
10837
10838 \end_inset
10839
10840
10841 \emph default
10842  so by default functions are non-reentrant
10843 \begin_inset LatexCommand \index{reentrant}
10844
10845 \end_inset
10846
10847 .
10848
10849 \newline
10850
10851 \newline
10852 They can be placed on the stack
10853 \begin_inset LatexCommand \index{stack}
10854
10855 \end_inset
10856
10857  by using the
10858 \emph on
10859  -
10860 \begin_inset ERT
10861 status Collapsed
10862
10863 \layout Standard
10864
10865 \backslash
10866 /
10867 \end_inset
10868
10869 -stack-auto
10870 \begin_inset LatexCommand \index{-\/-stack-auto}
10871
10872 \end_inset
10873
10874
10875 \emph default
10876  option, by using
10877 \emph on
10878 #pragma\SpecialChar ~
10879 stackauto
10880 \emph default
10881
10882 \begin_inset LatexCommand \index{\#pragma stackauto}
10883
10884 \end_inset
10885
10886  or by using the
10887 \emph on
10888 reentrant
10889 \begin_inset LatexCommand \index{reentrant}
10890
10891 \end_inset
10892
10893
10894 \emph default
10895  keyword in the function declaration, e.g.:
10896 \layout Verse
10897
10898
10899 \family typewriter
10900 unsigned char foo(char i) __reentrant
10901 \newline
10902 {
10903 \newline
10904 \SpecialChar ~
10905 \SpecialChar ~
10906 \SpecialChar ~
10907 \SpecialChar ~
10908 ...
10909
10910 \newline
10911 }
10912 \layout Standard
10913
10914 Since stack space on 8051 is limited, the
10915 \emph on
10916 reentrant
10917 \emph default
10918 keyword or the
10919 \emph on
10920  -
10921 \begin_inset ERT
10922 status Collapsed
10923
10924 \layout Standard
10925
10926 \backslash
10927 /
10928 \end_inset
10929
10930 -stack-auto
10931 \emph default
10932  option should be used sparingly.
10933  Note that the reentrant keyword just means that the parameters & local
10934  variables will be allocated to the stack, it
10935 \emph on
10936 does not
10937 \emph default
10938  mean that the function is register bank
10939 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
10940
10941 \end_inset
10942
10943  independent.
10944 \newline
10945
10946 \newline
10947 Local variables
10948 \begin_inset LatexCommand \index{local variables}
10949
10950 \end_inset
10951
10952  can be assigned storage classes and absolute
10953 \begin_inset LatexCommand \index{Absolute addressing}
10954
10955 \end_inset
10956
10957  addresses, e.g.:
10958 \layout Verse
10959
10960
10961 \family typewriter
10962 unsigned char foo()
10963 \newline
10964 {
10965 \newline
10966 \SpecialChar ~
10967 \SpecialChar ~
10968 \SpecialChar ~
10969 \SpecialChar ~
10970 __xdata unsigned char i;
10971 \newline
10972 \SpecialChar ~
10973 \SpecialChar ~
10974 \SpecialChar ~
10975 \SpecialChar ~
10976 __bit bvar;
10977 \newline
10978 \SpecialChar ~
10979 \SpecialChar ~
10980 \SpecialChar ~
10981 \SpecialChar ~
10982 __data __at
10983 \begin_inset LatexCommand \index{at}
10984
10985 \end_inset
10986
10987  (0x31) unsigned char j;
10988 \newline
10989 \SpecialChar ~
10990 \SpecialChar ~
10991 \SpecialChar ~
10992 \SpecialChar ~
10993 ...
10994
10995 \newline
10996 }
10997 \layout Standard
10998
10999 In the above example the variable
11000 \emph on
11001 i
11002 \emph default
11003  will be allocated in the external ram,
11004 \emph on
11005 bvar
11006 \emph default
11007  in bit addressable space and
11008 \emph on
11009  j
11010 \emph default
11011  in internal ram.
11012  When compiled with
11013 \emph on
11014 -
11015 \begin_inset ERT
11016 status Collapsed
11017
11018 \layout Standard
11019
11020 \backslash
11021 /
11022 \end_inset
11023
11024 -stack-auto
11025 \emph default
11026  or when a function is declared as
11027 \emph on
11028 reentrant
11029 \emph default
11030  this should only be done for static variables.
11031 \layout Standard
11032
11033 Parameters
11034 \begin_inset LatexCommand \index{function parameter}
11035
11036 \end_inset
11037
11038  however are not allowed any storage class
11039 \begin_inset LatexCommand \index{Storage class}
11040
11041 \end_inset
11042
11043 , (storage classes for parameters will be ignored), their allocation is
11044  governed by the memory model in use, and the reentrancy options.
11045 \layout Standard
11046
11047 It is however allowed to use bit parameters in reentrant functions and also
11048  non-static local bit variables are supported.
11049  Efficient use is limited to 8 semi-bitregisters in bit space.
11050  They are pushed and popped to stack as a single byte just like the normal
11051  registers.
11052 \layout Section
11053
11054 Overlaying
11055 \begin_inset LatexCommand \label{sub:Overlaying}
11056
11057 \end_inset
11058
11059
11060 \begin_inset LatexCommand \index{Overlaying}
11061
11062 \end_inset
11063
11064
11065 \layout Standard
11066
11067 For non-reentrant
11068 \begin_inset LatexCommand \index{reentrant}
11069
11070 \end_inset
11071
11072  functions SDCC will try to reduce internal ram space usage by overlaying
11073  parameters and local variables of a function (if possible).
11074  Parameters and local variables
11075 \begin_inset LatexCommand \index{local variables}
11076
11077 \end_inset
11078
11079  of a function will be allocated to an overlayable segment if the function
11080  has
11081 \emph on
11082 no other function calls and the function is non-reentrant and the memory
11083  model
11084 \begin_inset LatexCommand \index{Memory model}
11085
11086 \end_inset
11087
11088  is small.
11089
11090 \emph default
11091  If an explicit storage class
11092 \begin_inset LatexCommand \index{Storage class}
11093
11094 \end_inset
11095
11096  is specified for a local variable, it will NOT be overlayed.
11097 \layout Standard
11098
11099 Note that the compiler (not the linkage editor) makes the decision for overlayin
11100 g the data items.
11101  Functions that are called from an interrupt service routine
11102 \begin_inset Marginal
11103 collapsed true
11104
11105 \layout Standard
11106
11107
11108 \series bold
11109 !
11110 \end_inset
11111
11112  should be preceded by a #pragma\SpecialChar ~
11113 nooverlay
11114 \begin_inset LatexCommand \index{\#pragma nooverlay}
11115
11116 \end_inset
11117
11118  if they are not reentrant.
11119 \layout Standard
11120
11121 Also note that the compiler does not do any processing of inline assembler
11122  code, so the compiler might incorrectly assign local variables and parameters
11123  of a function into the overlay segment if the inline assembler code calls
11124  other c-functions that might use the overlay.
11125  In that case the #pragma\SpecialChar ~
11126 nooverlay should be used.
11127 \layout Standard
11128
11129 Parameters and local variables of functions that contain 16 or 32 bit multiplica
11130 tion
11131 \begin_inset LatexCommand \index{Multiplication}
11132
11133 \end_inset
11134
11135  or division
11136 \begin_inset LatexCommand \index{Division}
11137
11138 \end_inset
11139
11140  will NOT be overlayed since these are implemented using external functions,
11141  e.g.:
11142 \layout Verse
11143
11144
11145 \family typewriter
11146 #pragma save
11147 \newline
11148 #pragma nooverlay
11149 \begin_inset LatexCommand \index{\#pragma nooverlay}
11150
11151 \end_inset
11152
11153
11154 \newline
11155 void set_error(unsigned char errcd)
11156 \newline
11157 {
11158 \newline
11159 \SpecialChar ~
11160 \SpecialChar ~
11161 \SpecialChar ~
11162 \SpecialChar ~
11163 P3 = errcd;
11164 \newline
11165 }
11166 \newline
11167 #pragma restore
11168 \newline
11169
11170 \newline
11171 void some_isr () __interrupt
11172 \begin_inset LatexCommand \index{interrupt}
11173
11174 \end_inset
11175
11176  (2)
11177 \newline
11178 {
11179 \newline
11180 \SpecialChar ~
11181 \SpecialChar ~
11182 \SpecialChar ~
11183 \SpecialChar ~
11184 ...
11185 \newline
11186 \SpecialChar ~
11187 \SpecialChar ~
11188 \SpecialChar ~
11189 \SpecialChar ~
11190 set_error(10);
11191 \newline
11192 \SpecialChar ~
11193 \SpecialChar ~
11194 \SpecialChar ~
11195 \SpecialChar ~
11196 ...
11197
11198 \newline
11199 }
11200 \layout Standard
11201
11202 In the above example the parameter
11203 \emph on
11204 errcd
11205 \emph default
11206  for the function
11207 \emph on
11208 set_error
11209 \emph default
11210  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
11211 nooverlay was
11212  not present, this could cause unpredictable runtime behavior when called
11213  from an interrupt service routine.
11214  The #pragma\SpecialChar ~
11215 nooverlay ensures that the parameters and local variables for
11216  the function are NOT overlayed.
11217 \layout Section
11218
11219 Interrupt Service Routines
11220 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
11221
11222 \end_inset
11223
11224
11225 \layout Subsection
11226
11227 General Information
11228 \layout Standard
11229
11230 SDCC allows
11231 \emph on
11232 i
11233 \emph default
11234 nterrupt
11235 \emph on
11236 s
11237 \emph default
11238 ervice
11239 \emph on
11240 r
11241 \emph default
11242 outines to be coded in C, with some extended keywords.
11243 \layout Verse
11244
11245
11246 \family typewriter
11247 void timer_isr (void) __interrupt (1) __using (1)
11248 \newline
11249 {
11250 \newline
11251 \SpecialChar ~
11252 \SpecialChar ~
11253 \SpecialChar ~
11254 \SpecialChar ~
11255 ...
11256
11257 \newline
11258 }
11259 \layout Standard
11260
11261 The optional number following the
11262 \emph on
11263 interrupt
11264 \begin_inset LatexCommand \index{interrupt}
11265
11266 \end_inset
11267
11268
11269 \begin_inset LatexCommand \index{\_\_interrupt}
11270
11271 \end_inset
11272
11273
11274 \emph default
11275  keyword is the interrupt number this routine will service.
11276  When present, the compiler will insert a call to this routine in the interrupt
11277  vector table for the interrupt number specified.
11278  If you have multiple source files in your project, interrupt service routines
11279  can be present in any of them, but a prototype of the isr MUST be present
11280  or included in the file that contains the function
11281 \emph on
11282 main
11283 \emph default
11284 .
11285  The optional
11286 \emph on
11287 using
11288 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11289
11290 \end_inset
11291
11292
11293 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11294
11295 \end_inset
11296
11297
11298 \emph default
11299  keyword can be used to tell the compiler to use the specified register
11300  bank (8051 specific) when generating code for this function.
11301
11302 \newline
11303
11304 \layout Standard
11305
11306 Interrupt service routines open the door for some very interesting bugs:
11307 \newline
11308 If an interrupt service routine changes variables which are accessed by
11309  other functions these variables have to be declared
11310 \emph on
11311 volatile
11312 \emph default
11313
11314 \begin_inset LatexCommand \index{volatile}
11315
11316 \end_inset
11317
11318 .
11319
11320 \layout Standard
11321
11322 If the access to these variables is not
11323 \emph on
11324 atomic
11325 \begin_inset LatexCommand \index{atomic}
11326
11327 \end_inset
11328
11329
11330 \emph default
11331  (i.e.
11332  the processor needs more than one instruction for the access and could
11333  be interrupted while accessing the variable) the interrupt must be disabled
11334  during the access to avoid inconsistent data.
11335  Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
11336  and should be protected by disabling interrupts.
11337  You're not automatically on the safe side if you use 8 bit variables though.
11338  We need an example here: f.e.
11339  on the 8051 the harmless looking
11340 \begin_inset Quotes srd
11341 \end_inset
11342
11343
11344 \family typewriter
11345 flags\SpecialChar ~
11346 |=\SpecialChar ~
11347 0x80;
11348 \family default
11349
11350 \begin_inset Quotes sld
11351 \end_inset
11352
11353  is not atomic if
11354 \family typewriter
11355 flags
11356 \family default
11357  resides in xdata.
11358  Setting
11359 \begin_inset Quotes srd
11360 \end_inset
11361
11362
11363 \family typewriter
11364 flags\SpecialChar ~
11365 |=\SpecialChar ~
11366 0x40;
11367 \family default
11368
11369 \begin_inset Quotes sld
11370 \end_inset
11371
11372  from within an interrupt routine might get lost if the interrupt occurs
11373  at the wrong time.
11374
11375 \begin_inset Quotes sld
11376 \end_inset
11377
11378
11379 \family typewriter
11380 counter\SpecialChar ~
11381 +=\SpecialChar ~
11382 8;
11383 \family default
11384
11385 \begin_inset Quotes srd
11386 \end_inset
11387
11388  is not atomic on the 8051 even if
11389 \family typewriter
11390 counter
11391 \family default
11392  is located in data memory.
11393  Bugs like these are hard to reproduce and can cause a lot of trouble.
11394
11395 \layout Standard
11396
11397 The return address and the registers used in the interrupt service routine
11398  are saved on the stack
11399 \begin_inset LatexCommand \index{stack}
11400
11401 \end_inset
11402
11403  so there must be sufficient stack space.
11404  If there isn't variables or registers (or even the return address itself)
11405  will be corrupted.
11406  This
11407 \emph on
11408 stack overflow
11409 \emph default
11410
11411 \begin_inset LatexCommand \index{stack overflow}
11412
11413 \end_inset
11414
11415  is most likely to happen if the interrupt occurs during the
11416 \begin_inset Quotes sld
11417 \end_inset
11418
11419 deepest
11420 \begin_inset Quotes srd
11421 \end_inset
11422
11423  subroutine when the stack is already in use for f.e.
11424  many return addresses.
11425 \layout Standard
11426
11427 A special note here, int (16 bit) and long (32 bit) integer division
11428 \begin_inset LatexCommand \index{Division}
11429
11430 \end_inset
11431
11432 , multiplication
11433 \begin_inset LatexCommand \index{Multiplication}
11434
11435 \end_inset
11436
11437  & modulus
11438 \begin_inset LatexCommand \index{Modulus}
11439
11440 \end_inset
11441
11442  and floating-point
11443 \begin_inset LatexCommand \index{Floating point support}
11444
11445 \end_inset
11446
11447  operations are implemented using external support routines developed in
11448  ANSI-C.
11449  If an interrupt service routine needs to do any of these operations then
11450  the support routines (as mentioned in a following section) will have to
11451  be recompiled using the
11452 \emph on
11453  -
11454 \begin_inset ERT
11455 status Collapsed
11456
11457 \layout Standard
11458
11459 \backslash
11460 /
11461 \end_inset
11462
11463 -stack-auto
11464 \begin_inset LatexCommand \index{-\/-stack-auto}
11465
11466 \end_inset
11467
11468
11469 \emph default
11470  option and the source file will need to be compiled using the
11471 \emph on
11472 -
11473 \begin_inset ERT
11474 status Collapsed
11475
11476 \layout Standard
11477
11478 \backslash
11479 /
11480 \end_inset
11481
11482 -int-long-reent
11483 \emph default
11484
11485 \begin_inset LatexCommand \index{-\/-int-long-reent}
11486
11487 \end_inset
11488
11489  compiler option.
11490  Note, the type promotion
11491 \begin_inset LatexCommand \index{type promotion}
11492
11493 \end_inset
11494
11495  required by ANSI C can cause 16 bit routines to be used without the programmer
11496  being aware of it.
11497
11498 \layout Standard
11499
11500 Calling other functions from an interrupt service routine is not recommended,
11501  avoid it if possible.
11502  Note that when some function is called from an interrupt service routine
11503  it should be preceded by a #pragma\SpecialChar ~
11504 nooverlay
11505 \begin_inset LatexCommand \index{\#pragma nooverlay}
11506
11507 \end_inset
11508
11509  if it is not reentrant.
11510  Furthermore nonreentrant functions should not be called from the main program
11511  while the interrupt service routine might be active.
11512  They also must not be called from low priority interrupt service routines
11513  while a high priority interrupt service routine might be active.
11514  You could use semaphores or make the function
11515 \emph on
11516  critical
11517 \emph default
11518  if all parameters are passed in registers.
11519 \newline
11520
11521 \newline
11522 Also see section
11523 \begin_inset LatexCommand \ref{sub:Overlaying}
11524
11525 \end_inset
11526
11527 \SpecialChar ~
11528 about Overlaying and section
11529 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
11530
11531 \end_inset
11532
11533 \SpecialChar ~
11534 about Functions using private register banks.
11535 \layout Subsection
11536
11537 MCS51/DS390 Interrupt Service Routines
11538 \layout Standard
11539
11540 Interrupt numbers and the corresponding address & descriptions for the Standard
11541  8051/8052 are listed below.
11542  SDCC will automatically adjust the interrupt vector table to the maximum
11543  interrupt number specified.
11544 \newline
11545
11546 \layout Standard
11547 \align center
11548
11549 \begin_inset  Tabular
11550 <lyxtabular version="3" rows="9" columns="3">
11551 <features>
11552 <column alignment="center" valignment="top" leftline="true" width="0in">
11553 <column alignment="left" valignment="top" leftline="true" width="0in">
11554 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
11555 <row topline="true" bottomline="true">
11556 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11557 \begin_inset Text
11558
11559 \layout Standard
11560
11561 Interrupt #
11562 \end_inset
11563 </cell>
11564 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11565 \begin_inset Text
11566
11567 \layout Standard
11568
11569 Description
11570 \end_inset
11571 </cell>
11572 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11573 \begin_inset Text
11574
11575 \layout Standard
11576
11577 Vector Address
11578 \end_inset
11579 </cell>
11580 </row>
11581 <row topline="true">
11582 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11583 \begin_inset Text
11584
11585 \layout Standard
11586
11587 0
11588 \end_inset
11589 </cell>
11590 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11591 \begin_inset Text
11592
11593 \layout Standard
11594
11595 External 0
11596 \end_inset
11597 </cell>
11598 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11599 \begin_inset Text
11600
11601 \layout Standard
11602
11603 0x0003
11604 \end_inset
11605 </cell>
11606 </row>
11607 <row topline="true">
11608 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11609 \begin_inset Text
11610
11611 \layout Standard
11612
11613 1
11614 \end_inset
11615 </cell>
11616 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11617 \begin_inset Text
11618
11619 \layout Standard
11620
11621 Timer 0
11622 \end_inset
11623 </cell>
11624 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11625 \begin_inset Text
11626
11627 \layout Standard
11628
11629 0x000b
11630 \end_inset
11631 </cell>
11632 </row>
11633 <row topline="true">
11634 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11635 \begin_inset Text
11636
11637 \layout Standard
11638
11639 2
11640 \end_inset
11641 </cell>
11642 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11643 \begin_inset Text
11644
11645 \layout Standard
11646
11647 External 1
11648 \end_inset
11649 </cell>
11650 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11651 \begin_inset Text
11652
11653 \layout Standard
11654
11655 0x0013
11656 \end_inset
11657 </cell>
11658 </row>
11659 <row topline="true">
11660 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11661 \begin_inset Text
11662
11663 \layout Standard
11664
11665 3
11666 \end_inset
11667 </cell>
11668 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11669 \begin_inset Text
11670
11671 \layout Standard
11672
11673 Timer 1
11674 \end_inset
11675 </cell>
11676 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11677 \begin_inset Text
11678
11679 \layout Standard
11680
11681 0x001b
11682 \end_inset
11683 </cell>
11684 </row>
11685 <row topline="true">
11686 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11687 \begin_inset Text
11688
11689 \layout Standard
11690
11691 4
11692 \end_inset
11693 </cell>
11694 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11695 \begin_inset Text
11696
11697 \layout Standard
11698
11699 Serial
11700 \end_inset
11701 </cell>
11702 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11703 \begin_inset Text
11704
11705 \layout Standard
11706
11707 0x0023
11708 \end_inset
11709 </cell>
11710 </row>
11711 <row topline="true">
11712 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11713 \begin_inset Text
11714
11715 \layout Standard
11716
11717 5
11718 \end_inset
11719 </cell>
11720 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11721 \begin_inset Text
11722
11723 \layout Standard
11724
11725 Timer 2 (8052)
11726 \end_inset
11727 </cell>
11728 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11729 \begin_inset Text
11730
11731 \layout Standard
11732
11733 0x002b
11734 \end_inset
11735 </cell>
11736 </row>
11737 <row topline="true">
11738 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11739 \begin_inset Text
11740
11741 \layout Standard
11742
11743 ...
11744 \end_inset
11745 </cell>
11746 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11747 \begin_inset Text
11748
11749 \layout Standard
11750
11751 \end_inset
11752 </cell>
11753 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11754 \begin_inset Text
11755
11756 \layout Standard
11757
11758 ...
11759 \end_inset
11760 </cell>
11761 </row>
11762 <row topline="true" bottomline="true">
11763 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11764 \begin_inset Text
11765
11766 \layout Standard
11767
11768 n
11769 \end_inset
11770 </cell>
11771 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11772 \begin_inset Text
11773
11774 \layout Standard
11775
11776 \end_inset
11777 </cell>
11778 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11779 \begin_inset Text
11780
11781 \layout Standard
11782
11783 0x0003 + 8*n
11784 \end_inset
11785 </cell>
11786 </row>
11787 </lyxtabular>
11788
11789 \end_inset
11790
11791
11792 \newline
11793
11794 \layout Standard
11795
11796 If the interrupt service routine is defined without
11797 \emph on
11798 using
11799 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11800
11801 \end_inset
11802
11803
11804 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11805
11806 \end_inset
11807
11808
11809 \emph default
11810  a register bank or with register bank 0 (
11811 \emph on
11812 using
11813 \emph default
11814  0), the compiler will save the registers used by itself on the stack upon
11815  entry and restore them at exit, however if such an interrupt service routine
11816  calls another function then the entire register bank will be saved on the
11817  stack.
11818  This scheme may be advantageous for small interrupt service routines which
11819  have low register usage.
11820 \layout Standard
11821
11822 If the interrupt service routine is defined to be using a specific register
11823  bank then only
11824 \emph on
11825 a, b, dptr
11826 \emph default
11827  & psw are saved and restored, if such an interrupt service routine calls
11828  another function (using another register bank) then the entire register
11829  bank of the called function will be saved on the stack.
11830  This scheme is recommended for larger interrupt service routines.
11831 \layout Subsection
11832
11833 HC08 Interrupt Service Routines
11834 \layout Standard
11835
11836 Since the number of interrupts available is chip specific and the interrupt
11837  vector table always ends at the last byte of memory, the interrupt numbers
11838  corresponds to the interrupt vectors in reverse order of address.
11839  For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
11840  2 will use the interrupt vector at 0xfffa, and so on.
11841  However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
11842  this way; instead see section
11843 \begin_inset LatexCommand \ref{sub:Startup-Code}
11844
11845 \end_inset
11846
11847  for details on customizing startup.
11848 \layout Subsection
11849
11850 Z80 Interrupt Service Routines
11851 \layout Standard
11852
11853 The Z80 uses several different methods for determining the correct interrupt
11854  vector depending on the hardware implementation.
11855  Therefore, SDCC ignores the optional interrupt number and does not attempt
11856  to generate an interrupt vector table.
11857 \layout Standard
11858
11859 By default, SDCC generates code for a maskable interrupt, which uses a RETI
11860  instruction to return from the interrupt.
11861  To write an interrupt handler for the non-maskable interrupt, which needs
11862  a RETN instruction instead, add the
11863 \emph on
11864 critical
11865 \emph default
11866  keyword:
11867 \layout Verse
11868
11869
11870 \family typewriter
11871 void nmi_isr (void) critical interrupt
11872 \newline
11873 {
11874 \newline
11875 \SpecialChar ~
11876 \SpecialChar ~
11877 \SpecialChar ~
11878 \SpecialChar ~
11879 ...
11880
11881 \newline
11882 }
11883 \layout Standard
11884
11885 However if you need to create a non-interruptable interrupt service routine
11886  you would also require the
11887 \emph on
11888 critical
11889 \emph default
11890  keyword.
11891  To distinguish between this and an nmi_isr you must provide an interrupt
11892  number.
11893 \layout Section
11894
11895 Enabling and Disabling Interrupts
11896 \layout Subsection
11897
11898 Critical Functions and Critical Statements
11899 \layout Standard
11900
11901 A special keyword may be associated with a block or a function declaring
11902  it as
11903 \emph on
11904 critical
11905 \emph default
11906 .
11907  SDCC will generate code to disable all interrupts
11908 \begin_inset LatexCommand \index{interrupt}
11909
11910 \end_inset
11911
11912  upon entry to a critical function and restore the interrupt enable to the
11913  previous state before returning.
11914  Nesting critical functions will need one additional byte on the stack
11915 \begin_inset LatexCommand \index{stack}
11916
11917 \end_inset
11918
11919  for each call.
11920 \layout Verse
11921
11922
11923 \family typewriter
11924 int foo () __critical
11925 \begin_inset LatexCommand \index{critical}
11926
11927 \end_inset
11928
11929
11930 \begin_inset LatexCommand \index{\_\_critical}
11931
11932 \end_inset
11933
11934
11935 \newline
11936 {
11937 \newline
11938 \SpecialChar ~
11939 \SpecialChar ~
11940 \SpecialChar ~
11941 \SpecialChar ~
11942 ...
11943
11944 \newline
11945 \SpecialChar ~
11946 \SpecialChar ~
11947 \SpecialChar ~
11948 \SpecialChar ~
11949 ...
11950
11951 \newline
11952 }
11953 \layout Standard
11954
11955 The critical attribute maybe used with other attributes like
11956 \emph on
11957 reentrant.
11958 \emph default
11959
11960 \newline
11961 The keyword
11962 \emph on
11963 critical
11964 \emph default
11965  may also be used to disable interrupts more locally:
11966 \layout Verse
11967
11968
11969 \family typewriter
11970 __critical{ i++; }
11971 \layout Standard
11972
11973 More than one statement could have been included in the block.
11974 \layout Subsection
11975
11976 Enabling and Disabling Interrupts directly
11977 \layout Standard
11978
11979 Interrupts
11980 \begin_inset LatexCommand \index{interrupt}
11981
11982 \end_inset
11983
11984  can also be disabled and enabled directly (8051):
11985 \layout Verse
11986
11987
11988 \family typewriter
11989 EA = 0;\SpecialChar ~
11990 \SpecialChar ~
11991 \SpecialChar ~
11992 \SpecialChar ~
11993 \SpecialChar ~
11994 \SpecialChar ~
11995 \SpecialChar ~
11996 \SpecialChar ~
11997 \SpecialChar ~
11998 \SpecialChar ~
11999 \SpecialChar ~
12000 \SpecialChar ~
12001 or:\SpecialChar ~
12002 \SpecialChar ~
12003 \SpecialChar ~
12004 \SpecialChar ~
12005 \SpecialChar ~
12006 \SpecialChar ~
12007 \SpecialChar ~
12008 \SpecialChar ~
12009 \SpecialChar ~
12010 \SpecialChar ~
12011 \SpecialChar ~
12012 EA_SAVE = EA;
12013 \layout Verse
12014
12015
12016 \family typewriter
12017 ...\SpecialChar ~
12018 \SpecialChar ~
12019 \SpecialChar ~
12020 \SpecialChar ~
12021 \SpecialChar ~
12022 \SpecialChar ~
12023 \SpecialChar ~
12024 \SpecialChar ~
12025 \SpecialChar ~
12026 \SpecialChar ~
12027 \SpecialChar ~
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 EA = 0;
12048 \layout Verse
12049
12050
12051 \family typewriter
12052 EA = 1;\SpecialChar ~
12053 \SpecialChar ~
12054 \SpecialChar ~
12055 \SpecialChar ~
12056 \SpecialChar ~
12057 \SpecialChar ~
12058 \SpecialChar ~
12059 \SpecialChar ~
12060 \SpecialChar ~
12061 \SpecialChar ~
12062 \SpecialChar ~
12063 \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 ...
12079 \layout Verse
12080
12081
12082 \family typewriter
12083 \SpecialChar ~
12084 \SpecialChar ~
12085 \SpecialChar ~
12086 \SpecialChar ~
12087 \SpecialChar ~
12088 \SpecialChar ~
12089 \SpecialChar ~
12090 \SpecialChar ~
12091 \SpecialChar ~
12092 \SpecialChar ~
12093 \SpecialChar ~
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 EA = EA_SAVE;
12117 \layout Standard
12118
12119 On other architectures which have seperate opcodes for enabling and disabling
12120  interrupts you might want to make use of defines with inline assembly
12121 \begin_inset LatexCommand \index{Assembler routines}
12122
12123 \end_inset
12124
12125  (HC08):
12126 \layout Verse
12127
12128
12129 \family typewriter
12130 #define CLI _asm
12131 \begin_inset LatexCommand \index{\_asm}
12132
12133 \end_inset
12134
12135 \SpecialChar ~
12136 \SpecialChar ~
12137 cli\SpecialChar ~
12138 \SpecialChar ~
12139 _endasm
12140 \begin_inset LatexCommand \index{\_endasm}
12141
12142 \end_inset
12143
12144 ;
12145 \layout Verse
12146
12147
12148 \family typewriter
12149 #define SEI _asm\SpecialChar ~
12150 \SpecialChar ~
12151 sei\SpecialChar ~
12152 \SpecialChar ~
12153 _endasm;
12154 \layout Verse
12155
12156
12157 \family typewriter
12158 ...
12159 \layout Standard
12160
12161 Note: it is sometimes sufficient to disable only a specific interrupt source
12162  like f.e.
12163  a timer or serial interrupt by manipulating an
12164 \emph on
12165 interrupt mask
12166 \begin_inset LatexCommand \index{interrupt mask}
12167
12168 \end_inset
12169
12170
12171 \emph default
12172  register.
12173
12174 \layout Standard
12175
12176 Usually the time during which interrupts are disabled should be kept as
12177  short as possible.
12178  This minimizes both
12179 \emph on
12180 interrupt latency
12181 \emph default
12182
12183 \begin_inset LatexCommand \index{interrupt latency}
12184
12185 \end_inset
12186
12187  (the time between the occurrence of the interrupt and the execution of
12188  the first code in the interrupt routine) and
12189 \emph on
12190 interrupt jitter
12191 \emph default
12192
12193 \begin_inset LatexCommand \index{interrupt jitter}
12194
12195 \end_inset
12196
12197  (the difference between the shortest and the longest interrupt latency).
12198  These really are something different, f.e.
12199  a serial interrupt has to be served before its buffer overruns so it cares
12200  for the maximum interrupt latency, whereas it does not care about jitter.
12201  On a loudspeaker driven via a digital to analog converter which is fed
12202  by an interrupt a latency of a few milliseconds might be tolerable, whereas
12203  a much smaller jitter will be very audible.
12204 \layout Standard
12205
12206 You can reenable interrupts within an interrupt routine and on some architecture
12207 s you can make use of two (or more) levels of
12208 \emph on
12209 interrupt priorities
12210 \emph default
12211
12212 \begin_inset LatexCommand \index{interrupt priority}
12213
12214 \end_inset
12215
12216 .
12217  On some architectures which don't support interrupt priorities these can
12218  be implemented by manipulating the interrupt mask and reenabling interrupts
12219  within the interrupt routine.
12220  Check there is sufficient space on the stack
12221 \begin_inset LatexCommand \index{stack}
12222
12223 \end_inset
12224
12225  and don't add complexity unless you have to.
12226
12227 \layout Subsection
12228
12229 Semaphore
12230 \begin_inset LatexCommand \index{semaphore}
12231
12232 \end_inset
12233
12234  locking (mcs51/ds390)
12235 \layout Standard
12236
12237 Some architectures (mcs51/ds390) have an atomic
12238 \begin_inset LatexCommand \index{atomic}
12239
12240 \end_inset
12241
12242  bit test and
12243 \emph on
12244
12245 \emph default
12246 clear
12247 \emph on
12248
12249 \emph default
12250 instruction.
12251  These type of instructions are typically used in preemptive multitasking
12252  systems, where a routine f.e.
12253  claims the use of a data structure ('acquires a lock
12254 \begin_inset LatexCommand \index{lock}
12255
12256 \end_inset
12257
12258  on it'), makes some modifications and then releases the lock when the data
12259  structure is consistent again.
12260  The instruction may also be used if interrupt and non-interrupt code have
12261  to compete for a resource.
12262  With the atomic bit test and clear instruction interrupts
12263 \begin_inset LatexCommand \index{interrupt}
12264
12265 \end_inset
12266
12267  don't have to be disabled for the locking operation.
12268
12269 \layout Standard
12270
12271 SDCC generates this instruction if the source follows this pattern:
12272 \layout Verse
12273
12274
12275 \family typewriter
12276 volatile
12277 \begin_inset LatexCommand \index{volatile}
12278
12279 \end_inset
12280
12281  bit resource_is_free;
12282 \newline
12283
12284 \newline
12285 if (resource_is_free)
12286 \newline
12287 \SpecialChar ~
12288 \SpecialChar ~
12289 {
12290 \newline
12291 \SpecialChar ~
12292 \SpecialChar ~
12293 \SpecialChar ~
12294 \SpecialChar ~
12295 resource_is_free=0;
12296 \newline
12297 \SpecialChar ~
12298 \SpecialChar ~
12299 \SpecialChar ~
12300 \SpecialChar ~
12301 ...
12302
12303 \newline
12304 \SpecialChar ~
12305 \SpecialChar ~
12306 \SpecialChar ~
12307 \SpecialChar ~
12308 resource_is_free=1;
12309 \newline
12310 \SpecialChar ~
12311 \SpecialChar ~
12312 }
12313 \layout Standard
12314
12315 Note, mcs51 and ds390 support only an atomic
12316 \begin_inset LatexCommand \index{atomic}
12317
12318 \end_inset
12319
12320  bit test and
12321 \emph on
12322 clear
12323 \emph default
12324  instruction (as opposed to atomic bit test and
12325 \emph on
12326 set).
12327 \layout Section
12328
12329 Functions using private register banks
12330 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
12331
12332 \end_inset
12333
12334  (mcs51/ds390)
12335 \layout Standard
12336
12337 Some architectures have support for quickly changing register sets.
12338  SDCC supports this feature with the
12339 \emph on
12340 using
12341 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
12342
12343 \end_inset
12344
12345
12346 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
12347
12348 \end_inset
12349
12350
12351 \emph default
12352  attribute (which tells the compiler to use a register bank
12353 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
12354
12355 \end_inset
12356
12357  other than the default bank zero).
12358  It should only be applied to
12359 \emph on
12360 interrupt
12361 \begin_inset LatexCommand \index{interrupt}
12362
12363 \end_inset
12364
12365
12366 \emph default
12367  functions (see footnote below).
12368  This will in most circumstances make the generated ISR code more efficient
12369  since it will not have to save registers on the stack.
12370 \layout Standard
12371
12372 The
12373 \emph on
12374 using
12375 \emph default
12376  attribute will have no effect on the generated code for a
12377 \emph on
12378 non-interrupt
12379 \emph default
12380  function (but may occasionally be useful anyway
12381 \begin_inset Foot
12382 collapsed false
12383
12384 \layout Standard
12385
12386 possible exception: if a function is called ONLY from 'interrupt' functions
12387  using a particular bank, it can be declared with the same 'using' attribute
12388  as the calling 'interrupt' functions.
12389  For instance, if you have several ISRs using bank one, and all of them
12390  call memcpy(), it might make sense to create a specialized version of memcpy()
12391  'using 1', since this would prevent the ISR from having to save bank zero
12392  to the stack on entry and switch to bank zero before calling the function
12393 \end_inset
12394
12395 ).
12396 \newline
12397
12398 \emph on
12399 (pending: I don't think this has been done yet)
12400 \layout Standard
12401
12402 An
12403 \emph on
12404 interrupt
12405 \emph default
12406  function using a non-zero bank will assume that it can trash that register
12407  bank, and will not save it.
12408  Since high-priority interrupts
12409 \begin_inset LatexCommand \index{interrupts}
12410
12411 \end_inset
12412
12413
12414 \begin_inset LatexCommand \index{interrupt priority}
12415
12416 \end_inset
12417
12418  can interrupt low-priority ones on the 8051 and friends, this means that
12419  if a high-priority ISR
12420 \emph on
12421 using
12422 \emph default
12423  a particular bank occurs while processing a low-priority ISR
12424 \emph on
12425 using
12426 \emph default
12427  the same bank, terrible and bad things can happen.
12428  To prevent this, no single register bank should be
12429 \emph on
12430 used
12431 \emph default
12432  by both a high priority and a low priority ISR.
12433  This is probably most easily done by having all high priority ISRs use
12434  one bank and all low priority ISRs use another.
12435  If you have an ISR which can change priority at runtime, you're on your
12436  own: I suggest using the default bank zero and taking the small performance
12437  hit.
12438 \layout Standard
12439
12440 It is most efficient if your ISR calls no other functions.
12441  If your ISR must call other functions, it is most efficient if those functions
12442  use the same bank as the ISR (see note 1 below); the next best is if the
12443  called functions use bank zero.
12444  It is very inefficient to call a function using a different, non-zero bank
12445  from an ISR.
12446
12447 \layout Section
12448
12449 Startup Code
12450 \begin_inset LatexCommand \label{sub:Startup-Code}
12451
12452 \end_inset
12453
12454
12455 \begin_inset LatexCommand \index{Startup code}
12456
12457 \end_inset
12458
12459
12460 \layout Subsection
12461
12462 MCS51/DS390 Startup Code
12463 \layout Standard
12464
12465 The compiler inserts a call to the C routine
12466 \emph on
12467 _sdcc_external_startup()
12468 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
12469
12470 \end_inset
12471
12472
12473 \series bold
12474 \emph default
12475
12476 \series default
12477 at the start of the CODE area.
12478  This routine is in the runtime library
12479 \begin_inset LatexCommand \index{Runtime library}
12480
12481 \end_inset
12482
12483 .
12484  By default this routine returns 0, if this routine returns a non-zero value,
12485  the static & global variable initialization will be skipped and the function
12486  main will be invoked.
12487  Otherwise static & global variables will be initialized before the function
12488  main is invoked.
12489  You could add a
12490 \emph on
12491 _sdcc_external_startup()
12492 \emph default
12493  routine to your program to override the default if you need to setup hardware
12494  or perform some other critical operation prior to static & global variable
12495  initialization
12496 \begin_inset LatexCommand \index{Variable initialization}
12497
12498 \end_inset
12499
12500 .
12501  On some mcs51 variants xdata
12502 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
12503
12504 \end_inset
12505
12506  memory has to be explicitly enabled before it can be accessed or if the
12507  watchdog needs to be disabled, this is the place to do it.
12508  The startup code clears all internal data memory, 256 bytes by default,
12509  but from 0 to n-1 if
12510 \emph on
12511 -
12512 \begin_inset ERT
12513 status Collapsed
12514
12515 \layout Standard
12516
12517 \backslash
12518 /
12519 \end_inset
12520
12521 -iram-size
12522 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
12523
12524 \end_inset
12525
12526 n
12527 \emph default
12528  is used.
12529  (recommended for Chipcon CC1010).
12530 \layout Standard
12531
12532 See also the compiler option
12533 \emph on
12534 -
12535 \begin_inset ERT
12536 status Collapsed
12537
12538 \layout Standard
12539
12540 \backslash
12541 /
12542 \end_inset
12543
12544 -no-xinit
12545 \emph default
12546 -
12547 \emph on
12548 opt
12549 \emph default
12550
12551 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
12552
12553 \end_inset
12554
12555  and section
12556 \begin_inset LatexCommand \ref{sub:MCS51-variants}
12557
12558 \end_inset
12559
12560 \SpecialChar ~
12561 about MCS51-variants.
12562 \layout Subsection
12563
12564 HC08 Startup Code
12565 \layout Standard
12566
12567 The HC08 startup code follows the same scheme as the MCS51 startup code.
12568 \layout Subsection
12569
12570 Z80 Startup Code
12571 \layout Standard
12572
12573 On the Z80 the startup code is inserted by linking with crt0.o which is generated
12574  from sdcc/device/lib/z80/crt0.s.
12575  If you need a different startup code you can use the compiler option
12576 \emph on
12577 -
12578 \series bold
12579 \emph default
12580
12581 \begin_inset ERT
12582 status Collapsed
12583
12584 \layout Standard
12585
12586 \backslash
12587 /
12588 \end_inset
12589
12590
12591 \series default
12592 \emph on
12593 -no-std-crt0
12594 \emph default
12595
12596 \begin_inset LatexCommand \index{-\/-no-std-crt0}
12597
12598 \end_inset
12599
12600  and provide your own crt0.o.
12601
12602 \layout Section
12603
12604 Inline Assembler Code
12605 \begin_inset LatexCommand \index{Assembler routines}
12606
12607 \end_inset
12608
12609
12610 \layout Subsection
12611
12612 A Step by Step Introduction
12613 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
12614
12615 \end_inset
12616
12617
12618 \layout Standard
12619
12620 Starting from a small snippet of c-code this example shows for the MCS51
12621  how to use inline assembly, access variables, a function parameter and
12622  an array in xdata memory.
12623  The example uses an MCS51 here but is easily adapted for other architectures.
12624  This is a buffer routine which should be optimized:
12625 \layout Verse
12626
12627
12628 \family typewriter
12629 \size footnotesize
12630 unsigned char __far
12631 \begin_inset LatexCommand \index{far (storage class)}
12632
12633 \end_inset
12634
12635
12636 \begin_inset LatexCommand \index{\_\_far (storage class)}
12637
12638 \end_inset
12639
12640  __at
12641 \begin_inset LatexCommand \index{at}
12642
12643 \end_inset
12644
12645
12646 \begin_inset LatexCommand \index{\_\_at}
12647
12648 \end_inset
12649
12650 (0x7f00) buf[0x100];
12651 \begin_inset LatexCommand \index{Aligned array}
12652
12653 \end_inset
12654
12655
12656 \newline
12657 unsigned char head, tail;
12658 \newline
12659
12660 \newline
12661 void to_buffer( unsigned char c )
12662 \newline
12663 {
12664 \newline
12665 \SpecialChar ~
12666 \SpecialChar ~
12667 \SpecialChar ~
12668 \SpecialChar ~
12669 if( head != (unsigned char)(tail-1) )\SpecialChar ~
12670 /* cast
12671 \series bold
12672 needed
12673 \series default
12674  to avoid promotion
12675 \begin_inset LatexCommand \index{promotion to signed int}
12676
12677 \end_inset
12678
12679
12680 \begin_inset LatexCommand \index{type promotion}
12681
12682 \end_inset
12683
12684  to integer */
12685 \begin_inset Marginal
12686 collapsed false
12687
12688 \layout Standard
12689
12690
12691 \series bold
12692 \SpecialChar ~
12693 !
12694 \end_inset
12695
12696
12697 \newline
12698 \SpecialChar ~
12699 \SpecialChar ~
12700 \SpecialChar ~
12701 \SpecialChar ~
12702 \SpecialChar ~
12703 \SpecialChar ~
12704 \SpecialChar ~
12705 \SpecialChar ~
12706 buf[ head++ ] = c;\SpecialChar ~
12707 \SpecialChar ~
12708 \SpecialChar ~
12709 \SpecialChar ~
12710 \SpecialChar ~
12711 \SpecialChar ~
12712 \SpecialChar ~
12713 \SpecialChar ~
12714 \SpecialChar ~
12715 \SpecialChar ~
12716 \SpecialChar ~
12717 \SpecialChar ~
12718 \SpecialChar ~
12719 \SpecialChar ~
12720 \SpecialChar ~
12721 \SpecialChar ~
12722 /* access to a 256 byte aligned array */
12723 \newline
12724 }
12725 \layout Standard
12726
12727 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
12728  then a corresponding buffer.asm file is generated.
12729  We define a new function
12730 \family typewriter
12731 to_buffer_asm()
12732 \family default
12733  in file buffer.c in which we cut and paste the generated code, removing
12734  unwanted comments and some ':'.
12735  Then add
12736 \begin_inset Quotes sld
12737 \end_inset
12738
12739 _asm
12740 \begin_inset Quotes srd
12741 \end_inset
12742
12743  and
12744 \begin_inset Quotes sld
12745 \end_inset
12746
12747 _endasm;
12748 \begin_inset Quotes srd
12749 \end_inset
12750
12751  to the beginning and the end of the function body:
12752 \layout Verse
12753
12754
12755 \family typewriter
12756 \size footnotesize
12757 /* With a cut and paste from the .asm file, we have something to start with.
12758 \newline
12759 \SpecialChar ~
12760 \SpecialChar ~
12761 \SpecialChar ~
12762 The function is not yet OK! (registers aren't saved) */
12763 \newline
12764 void to_buffer_asm( unsigned char c )
12765 \newline
12766 {
12767 \newline
12768 \SpecialChar ~
12769 \SpecialChar ~
12770 \SpecialChar ~
12771 \SpecialChar ~
12772 _asm
12773 \begin_inset LatexCommand \index{\_asm}
12774
12775 \end_inset
12776
12777
12778 \begin_inset LatexCommand \index{\_\_asm}
12779
12780 \end_inset
12781
12782
12783 \newline
12784 \SpecialChar ~
12785 \SpecialChar ~
12786 \SpecialChar ~
12787 \SpecialChar ~
12788 mov\SpecialChar ~
12789 \SpecialChar ~
12790 r2,dpl
12791 \newline
12792 ;buffer.c if( head != (unsigned char)(tail-1) )
12793 \newline
12794 \SpecialChar ~
12795 \SpecialChar ~
12796 \SpecialChar ~
12797 \SpecialChar ~
12798 mov\SpecialChar ~
12799 \SpecialChar ~
12800 a,_tail
12801 \newline
12802 \SpecialChar ~
12803 \SpecialChar ~
12804 \SpecialChar ~
12805 \SpecialChar ~
12806 dec\SpecialChar ~
12807 \SpecialChar ~
12808 a
12809 \newline
12810 \SpecialChar ~
12811 \SpecialChar ~
12812 \SpecialChar ~
12813 \SpecialChar ~
12814 mov\SpecialChar ~
12815 \SpecialChar ~
12816 r3,a
12817 \newline
12818 \SpecialChar ~
12819 \SpecialChar ~
12820 \SpecialChar ~
12821 \SpecialChar ~
12822 mov\SpecialChar ~
12823 \SpecialChar ~
12824 a,_head
12825 \newline
12826 \SpecialChar ~
12827 \SpecialChar ~
12828 \SpecialChar ~
12829 \SpecialChar ~
12830 cjne a,ar3,00106$
12831 \newline
12832 \SpecialChar ~
12833 \SpecialChar ~
12834 \SpecialChar ~
12835 \SpecialChar ~
12836 ret
12837 \newline
12838 00106$:
12839 \newline
12840 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
12841 \begin_inset LatexCommand \index{Aligned array}
12842
12843 \end_inset
12844
12845
12846 \newline
12847 \SpecialChar ~
12848 \SpecialChar ~
12849 \SpecialChar ~
12850 \SpecialChar ~
12851 mov\SpecialChar ~
12852 \SpecialChar ~
12853 r3,_head
12854 \newline
12855 \SpecialChar ~
12856 \SpecialChar ~
12857 \SpecialChar ~
12858 \SpecialChar ~
12859 inc\SpecialChar ~
12860 \SpecialChar ~
12861 _head
12862 \newline
12863 \SpecialChar ~
12864 \SpecialChar ~
12865 \SpecialChar ~
12866 \SpecialChar ~
12867 mov\SpecialChar ~
12868 \SpecialChar ~
12869 dpl,r3
12870 \newline
12871 \SpecialChar ~
12872 \SpecialChar ~
12873 \SpecialChar ~
12874 \SpecialChar ~
12875 mov\SpecialChar ~
12876 \SpecialChar ~
12877 dph,#(_buf >> 8)
12878 \newline
12879 \SpecialChar ~
12880 \SpecialChar ~
12881 \SpecialChar ~
12882 \SpecialChar ~
12883 mov\SpecialChar ~
12884 \SpecialChar ~
12885 a,r2
12886 \newline
12887 \SpecialChar ~
12888 \SpecialChar ~
12889 \SpecialChar ~
12890 \SpecialChar ~
12891 movx @dptr,a
12892 \newline
12893 00103$:
12894 \newline
12895 \SpecialChar ~
12896 \SpecialChar ~
12897 \SpecialChar ~
12898 \SpecialChar ~
12899 ret
12900 \newline
12901 \SpecialChar ~
12902 \SpecialChar ~
12903 \SpecialChar ~
12904 \SpecialChar ~
12905 _endasm
12906 \begin_inset LatexCommand \index{\_endasm}
12907
12908 \end_inset
12909
12910
12911 \begin_inset LatexCommand \index{\_\_endasm}
12912
12913 \end_inset
12914
12915 ;
12916 \newline
12917 }
12918 \layout Standard
12919
12920 The new file buffer.c should compile with only one warning about the unreferenced
12921  function argument 'c'.
12922  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
12923  (1) and finally have:
12924 \layout Verse
12925
12926
12927 \family typewriter
12928 \size footnotesize
12929 unsigned char __far __at(0x7f00) buf[0x100];
12930 \newline
12931 unsigned char head, tail;
12932 \newline
12933 #define USE_ASSEMBLY (1)
12934 \newline
12935
12936 \newline
12937 #if !USE_ASSEMBLY
12938 \newline
12939
12940 \newline
12941 void to_buffer( unsigned char c )
12942 \newline
12943 {
12944 \newline
12945 \SpecialChar ~
12946 \SpecialChar ~
12947 \SpecialChar ~
12948 \SpecialChar ~
12949 if( head != (unsigned char)(tail-1) )
12950 \newline
12951 \SpecialChar ~
12952 \SpecialChar ~
12953 \SpecialChar ~
12954 \SpecialChar ~
12955 \SpecialChar ~
12956 \SpecialChar ~
12957 \SpecialChar ~
12958 \SpecialChar ~
12959 buf[ head++ ] = c;
12960 \newline
12961 }
12962 \newline
12963
12964 \newline
12965 #else
12966 \newline
12967
12968 \newline
12969 void to_buffer( unsigned char c )
12970 \newline
12971 {
12972 \newline
12973 \SpecialChar ~
12974 \SpecialChar ~
12975 \SpecialChar ~
12976 \SpecialChar ~
12977 c; // to avoid warning: unreferenced function argument
12978 \newline
12979 \SpecialChar ~
12980 \SpecialChar ~
12981 \SpecialChar ~
12982 \SpecialChar ~
12983 _asm
12984 \begin_inset LatexCommand \index{\_asm}
12985
12986 \end_inset
12987
12988
12989 \begin_inset LatexCommand \index{\_\_asm}
12990
12991 \end_inset
12992
12993
12994 \newline
12995 \SpecialChar ~
12996 \SpecialChar ~
12997 \SpecialChar ~
12998 \SpecialChar ~
12999 \SpecialChar ~
13000 \SpecialChar ~
13001 \SpecialChar ~
13002 \SpecialChar ~
13003 ; save used registers here.
13004
13005 \newline
13006 \SpecialChar ~
13007 \SpecialChar ~
13008 \SpecialChar ~
13009 \SpecialChar ~
13010 \SpecialChar ~
13011 \SpecialChar ~
13012 \SpecialChar ~
13013 \SpecialChar ~
13014 ; If we were still using r2,r3 we would have to push them here.
13015
13016 \newline
13017 ; if( head != (unsigned char)(tail-1) )
13018 \newline
13019 \SpecialChar ~
13020 \SpecialChar ~
13021 \SpecialChar ~
13022 \SpecialChar ~
13023 \SpecialChar ~
13024 \SpecialChar ~
13025 \SpecialChar ~
13026 \SpecialChar ~
13027 mov\SpecialChar ~
13028  a,_tail
13029 \newline
13030 \SpecialChar ~
13031 \SpecialChar ~
13032 \SpecialChar ~
13033 \SpecialChar ~
13034 \SpecialChar ~
13035 \SpecialChar ~
13036 \SpecialChar ~
13037 \SpecialChar ~
13038 dec\SpecialChar ~
13039  a
13040 \newline
13041 \SpecialChar ~
13042 \SpecialChar ~
13043 \SpecialChar ~
13044 \SpecialChar ~
13045 \SpecialChar ~
13046 \SpecialChar ~
13047 \SpecialChar ~
13048 \SpecialChar ~
13049 xrl\SpecialChar ~
13050  a,_head
13051 \newline
13052 \SpecialChar ~
13053 \SpecialChar ~
13054 \SpecialChar ~
13055 \SpecialChar ~
13056 \SpecialChar ~
13057 \SpecialChar ~
13058 \SpecialChar ~
13059 \SpecialChar ~
13060 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
13061 \newline
13062 \SpecialChar ~
13063 \SpecialChar ~
13064 \SpecialChar ~
13065 \SpecialChar ~
13066 \SpecialChar ~
13067 \SpecialChar ~
13068 \SpecialChar ~
13069 \SpecialChar ~
13070 jz\SpecialChar ~
13071 \SpecialChar ~
13072  t_b_end$
13073 \newline
13074 \SpecialChar ~
13075 \SpecialChar ~
13076 \SpecialChar ~
13077 \SpecialChar ~
13078 \SpecialChar ~
13079 \SpecialChar ~
13080 \SpecialChar ~
13081 \SpecialChar ~
13082 ;
13083 \newline
13084 ; buf[ head++ ] = c;
13085 \newline
13086 \SpecialChar ~
13087 \SpecialChar ~
13088 \SpecialChar ~
13089 \SpecialChar ~
13090 \SpecialChar ~
13091 \SpecialChar ~
13092 \SpecialChar ~
13093 \SpecialChar ~
13094 mov\SpecialChar ~
13095  a,dpl \SpecialChar ~
13096 \SpecialChar ~
13097 \SpecialChar ~
13098 \SpecialChar ~
13099 \SpecialChar ~
13100 \SpecialChar ~
13101 \SpecialChar ~
13102 ; dpl holds lower byte of function argument
13103 \newline
13104 \SpecialChar ~
13105 \SpecialChar ~
13106 \SpecialChar ~
13107 \SpecialChar ~
13108 \SpecialChar ~
13109 \SpecialChar ~
13110 \SpecialChar ~
13111 \SpecialChar ~
13112 mov\SpecialChar ~
13113  dpl,_head \SpecialChar ~
13114 \SpecialChar ~
13115 \SpecialChar ~
13116 ; buf is 0x100 byte aligned so head can be used directly
13117 \newline
13118 \SpecialChar ~
13119 \SpecialChar ~
13120 \SpecialChar ~
13121 \SpecialChar ~
13122 \SpecialChar ~
13123 \SpecialChar ~
13124 \SpecialChar ~
13125 \SpecialChar ~
13126 mov\SpecialChar ~
13127  dph,#(_buf>>8)
13128 \newline
13129 \SpecialChar ~
13130 \SpecialChar ~
13131 \SpecialChar ~
13132 \SpecialChar ~
13133 \SpecialChar ~
13134 \SpecialChar ~
13135 \SpecialChar ~
13136 \SpecialChar ~
13137 movx @dptr,a
13138 \newline
13139 \SpecialChar ~
13140 \SpecialChar ~
13141 \SpecialChar ~
13142 \SpecialChar ~
13143 \SpecialChar ~
13144 \SpecialChar ~
13145 \SpecialChar ~
13146 \SpecialChar ~
13147 inc \SpecialChar ~
13148 _head
13149 \newline
13150 \SpecialChar ~
13151 \SpecialChar ~
13152 \SpecialChar ~
13153 \SpecialChar ~
13154 \SpecialChar ~
13155 \SpecialChar ~
13156 \SpecialChar ~
13157 \SpecialChar ~
13158 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
13159 \newline
13160 t_b_end$:
13161 \newline
13162 \SpecialChar ~
13163 \SpecialChar ~
13164 \SpecialChar ~
13165 \SpecialChar ~
13166 \SpecialChar ~
13167 \SpecialChar ~
13168 \SpecialChar ~
13169 \SpecialChar ~
13170 ; restore used registers here
13171 \newline
13172 \SpecialChar ~
13173 \SpecialChar ~
13174 \SpecialChar ~
13175 \SpecialChar ~
13176 _endasm
13177 \begin_inset LatexCommand \index{\_endasm}
13178
13179 \end_inset
13180
13181
13182 \begin_inset LatexCommand \index{\_\_endasm}
13183
13184 \end_inset
13185
13186 ;
13187 \newline
13188 }
13189 \newline
13190 #endif
13191 \layout Standard
13192
13193 The inline assembler code can contain any valid code understood by the assembler
13194 , this includes any assembler directives and comment lines
13195 \begin_inset Foot
13196 collapsed false
13197
13198 \layout Standard
13199
13200 The assembler does not like some characters like ':' or ''' in comments.
13201  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
13202 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
13203
13204 \end_inset
13205
13206
13207 \begin_inset LatexCommand \index{Assembler documentation}
13208
13209 \end_inset
13210
13211
13212 \end_inset
13213
13214 .
13215  The compiler does not do any validation of the code within the
13216 \family typewriter
13217 _asm
13218 \begin_inset LatexCommand \index{\_asm}
13219
13220 \end_inset
13221
13222
13223 \begin_inset LatexCommand \index{\_\_asm}
13224
13225 \end_inset
13226
13227  ...
13228  _endasm
13229 \size footnotesize
13230
13231 \begin_inset LatexCommand \index{\_endasm}
13232
13233 \end_inset
13234
13235
13236 \begin_inset LatexCommand \index{\_\_endasm}
13237
13238 \end_inset
13239
13240
13241 \size default
13242 ;
13243 \family default
13244  keyword pair.
13245  Specifically it will not know which registers are used and thus register
13246  pushing/popping
13247 \begin_inset LatexCommand \index{push/pop}
13248
13249 \end_inset
13250
13251  has to be done manually.
13252
13253 \layout Standard
13254
13255 It is recommended that each assembly instruction (including labels) be placed
13256  in a separate line (as the example shows).
13257  When the -
13258 \begin_inset ERT
13259 status Collapsed
13260
13261 \layout Standard
13262
13263 \backslash
13264 /
13265 \end_inset
13266
13267 -
13268 \emph on
13269 peep-asm
13270 \begin_inset LatexCommand \index{-\/-peep-asm}
13271
13272 \end_inset
13273
13274
13275 \emph default
13276  command line option is used, the inline assembler code will be passed through
13277  the peephole optimizer
13278 \begin_inset LatexCommand \index{Peephole optimizer}
13279
13280 \end_inset
13281
13282 .
13283  There are only a few (if any) cases where this option makes sense, it might
13284  cause some unexpected changes in the inline assembler code.
13285  Please go through the peephole optimizer rules defined in file
13286 \emph on
13287 SDCCpeeph.def
13288 \emph default
13289  before using this option.
13290 \layout Subsection
13291
13292 Naked Functions
13293 \begin_inset LatexCommand \label{sub:Naked-Functions}
13294
13295 \end_inset
13296
13297
13298 \begin_inset LatexCommand \index{Naked functions}
13299
13300 \end_inset
13301
13302
13303 \layout Standard
13304
13305 A special keyword may be associated with a function declaring it as
13306 \emph on
13307 _naked
13308 \begin_inset LatexCommand \index{\_naked}
13309
13310 \end_inset
13311
13312
13313 \begin_inset LatexCommand \index{\_\_naked}
13314
13315 \end_inset
13316
13317 .
13318
13319 \emph default
13320 The
13321 \emph on
13322 _naked
13323 \emph default
13324  function modifier attribute prevents the compiler from generating prologue
13325 \begin_inset LatexCommand \index{function prologue}
13326
13327 \end_inset
13328
13329  and epilogue
13330 \begin_inset LatexCommand \index{function epilogue}
13331
13332 \end_inset
13333
13334  code for that function.
13335  This means that the user is entirely responsible for such things as saving
13336  any registers that may need to be preserved, selecting the proper register
13337  bank, generating the
13338 \emph on
13339 return
13340 \emph default
13341  instruction at the end, etc.
13342  Practically, this means that the contents of the function must be written
13343  in inline assembler.
13344  This is particularly useful for interrupt functions, which can have a large
13345  (and often unnecessary) prologue/epilogue.
13346  For example, compare the code generated by these two functions:
13347 \layout Verse
13348
13349
13350 \family typewriter
13351 volatile
13352 \begin_inset LatexCommand \index{volatile}
13353
13354 \end_inset
13355
13356  data unsigned char counter;
13357 \newline
13358
13359 \newline
13360 void simpleInterrupt(void) __interrupt
13361 \begin_inset LatexCommand \index{interrupt}
13362
13363 \end_inset
13364
13365
13366 \begin_inset LatexCommand \index{\_\_interrupt}
13367
13368 \end_inset
13369
13370  (1)
13371 \newline
13372 {
13373 \newline
13374 \SpecialChar ~
13375 \SpecialChar ~
13376 \SpecialChar ~
13377 \SpecialChar ~
13378 counter++;
13379 \newline
13380 }
13381 \newline
13382
13383 \newline
13384 void nakedInterrupt(void) __interrupt (2) __naked
13385 \newline
13386 {
13387 \newline
13388 \SpecialChar ~
13389 \SpecialChar ~
13390 \SpecialChar ~
13391 \SpecialChar ~
13392 _asm
13393 \begin_inset LatexCommand \index{\_asm}
13394
13395 \end_inset
13396
13397
13398 \begin_inset LatexCommand \index{\_\_asm}
13399
13400 \end_inset
13401
13402
13403 \newline
13404 \SpecialChar ~
13405 \SpecialChar ~
13406 \SpecialChar ~
13407 \SpecialChar ~
13408 \SpecialChar ~
13409 \SpecialChar ~
13410 inc\SpecialChar ~
13411 \SpecialChar ~
13412 \SpecialChar ~
13413 \SpecialChar ~
13414 \SpecialChar ~
13415 _counter ; does not change flags, no need to save psw
13416 \newline
13417 \SpecialChar ~
13418 \SpecialChar ~
13419 \SpecialChar ~
13420 \SpecialChar ~
13421 \SpecialChar ~
13422 \SpecialChar ~
13423 reti\SpecialChar ~
13424 \SpecialChar ~
13425 \SpecialChar ~
13426 \SpecialChar ~
13427 ; MUST explicitly include ret or reti in _naked function.
13428 \newline
13429 \SpecialChar ~
13430 \SpecialChar ~
13431 \SpecialChar ~
13432 \SpecialChar ~
13433 _endasm
13434 \begin_inset LatexCommand \index{\_endasm}
13435
13436 \end_inset
13437
13438
13439 \begin_inset LatexCommand \index{\_\_endasm}
13440
13441 \end_inset
13442
13443 ;
13444 \newline
13445 }
13446 \layout Standard
13447
13448 For an 8051 target, the generated simpleInterrupt looks like:
13449 \layout Verse
13450
13451
13452 \family typewriter
13453 Note, this is an
13454 \series bold
13455 outdated
13456 \series default
13457  example, recent versions of SDCC generate
13458 \newline
13459 the same code for simpleInterrupt() and nakedInterrupt()!
13460 \newline
13461
13462 \newline
13463 _simpleInterrupt:
13464 \newline
13465 \SpecialChar ~
13466 \SpecialChar ~
13467 \SpecialChar ~
13468 \SpecialChar ~
13469 push\SpecialChar ~
13470 \SpecialChar ~
13471 \SpecialChar ~
13472 \SpecialChar ~
13473 acc
13474 \newline
13475 \SpecialChar ~
13476 \SpecialChar ~
13477 \SpecialChar ~
13478 \SpecialChar ~
13479 push\SpecialChar ~
13480 \SpecialChar ~
13481 \SpecialChar ~
13482 \SpecialChar ~
13483 b
13484 \newline
13485 \SpecialChar ~
13486 \SpecialChar ~
13487 \SpecialChar ~
13488 \SpecialChar ~
13489 push\SpecialChar ~
13490 \SpecialChar ~
13491 \SpecialChar ~
13492 \SpecialChar ~
13493 dpl
13494 \newline
13495 \SpecialChar ~
13496 \SpecialChar ~
13497 \SpecialChar ~
13498 \SpecialChar ~
13499 push\SpecialChar ~
13500 \SpecialChar ~
13501 \SpecialChar ~
13502 \SpecialChar ~
13503 dph
13504 \newline
13505 \SpecialChar ~
13506 \SpecialChar ~
13507 \SpecialChar ~
13508 \SpecialChar ~
13509 push\SpecialChar ~
13510 \SpecialChar ~
13511 \SpecialChar ~
13512 \SpecialChar ~
13513 psw
13514 \newline
13515 \SpecialChar ~
13516 \SpecialChar ~
13517 \SpecialChar ~
13518 \SpecialChar ~
13519 mov\SpecialChar ~
13520 \SpecialChar ~
13521 \SpecialChar ~
13522 \SpecialChar ~
13523 \SpecialChar ~
13524 psw,#0x00
13525 \newline
13526 \SpecialChar ~
13527 \SpecialChar ~
13528 \SpecialChar ~
13529 \SpecialChar ~
13530 inc\SpecialChar ~
13531 \SpecialChar ~
13532 \SpecialChar ~
13533 \SpecialChar ~
13534 \SpecialChar ~
13535 _counter
13536 \newline
13537 \SpecialChar ~
13538 \SpecialChar ~
13539 \SpecialChar ~
13540 \SpecialChar ~
13541 pop\SpecialChar ~
13542 \SpecialChar ~
13543 \SpecialChar ~
13544 \SpecialChar ~
13545 \SpecialChar ~
13546 psw
13547 \newline
13548 \SpecialChar ~
13549 \SpecialChar ~
13550 \SpecialChar ~
13551 \SpecialChar ~
13552 pop\SpecialChar ~
13553 \SpecialChar ~
13554 \SpecialChar ~
13555 \SpecialChar ~
13556 \SpecialChar ~
13557 dph
13558 \newline
13559 \SpecialChar ~
13560 \SpecialChar ~
13561 \SpecialChar ~
13562 \SpecialChar ~
13563 pop\SpecialChar ~
13564 \SpecialChar ~
13565 \SpecialChar ~
13566 \SpecialChar ~
13567 \SpecialChar ~
13568 dpl
13569 \newline
13570 \SpecialChar ~
13571 \SpecialChar ~
13572 \SpecialChar ~
13573 \SpecialChar ~
13574 pop\SpecialChar ~
13575 \SpecialChar ~
13576 \SpecialChar ~
13577 \SpecialChar ~
13578 \SpecialChar ~
13579 b
13580 \newline
13581 \SpecialChar ~
13582 \SpecialChar ~
13583 \SpecialChar ~
13584 \SpecialChar ~
13585 pop\SpecialChar ~
13586 \SpecialChar ~
13587 \SpecialChar ~
13588 \SpecialChar ~
13589 \SpecialChar ~
13590 acc
13591 \newline
13592 \SpecialChar ~
13593 \SpecialChar ~
13594 \SpecialChar ~
13595 \SpecialChar ~
13596 reti
13597 \layout Standard
13598
13599 whereas nakedInterrupt looks like:
13600 \layout Verse
13601
13602
13603 \family typewriter
13604 _nakedInterrupt:
13605 \newline
13606 \SpecialChar ~
13607 \SpecialChar ~
13608 \SpecialChar ~
13609 \SpecialChar ~
13610 inc\SpecialChar ~
13611 \SpecialChar ~
13612 \SpecialChar ~
13613 \SpecialChar ~
13614 _counter ; does not change flags, no need to save psw
13615 \newline
13616 \SpecialChar ~
13617 \SpecialChar ~
13618 \SpecialChar ~
13619 \SpecialChar ~
13620 reti\SpecialChar ~
13621 \SpecialChar ~
13622 \SpecialChar ~
13623 \SpecialChar ~
13624 \SpecialChar ~
13625 \SpecialChar ~
13626 \SpecialChar ~
13627 \SpecialChar ~
13628 \SpecialChar ~
13629 \SpecialChar ~
13630 \SpecialChar ~
13631 \SpecialChar ~
13632 ; MUST explicitly include ret or reti in _naked function
13633 \layout Standard
13634
13635 The related directive #pragma exclude
13636 \begin_inset LatexCommand \index{\#pragma exclude}
13637
13638 \end_inset
13639
13640  allows a more fine grained control over pushing & popping
13641 \begin_inset LatexCommand \index{push/pop}
13642
13643 \end_inset
13644
13645  the registers.
13646 \layout Standard
13647
13648 While there is nothing preventing you from writing C code inside a
13649 \family typewriter
13650 _naked
13651 \family default
13652  function, there are many ways to shoot yourself in the foot doing this,
13653  and it is recommended that you stick to inline assembler.
13654 \layout Subsection
13655
13656 Use of Labels within Inline Assembler
13657 \layout Standard
13658
13659 SDCC allows the use of in-line assembler with a few restrictions regarding
13660  labels.
13661  In older versions of the compiler all labels defined within inline assembler
13662  code
13663 \emph on
13664 had to be
13665 \emph default
13666  of the form
13667 \emph on
13668 nnnnn$
13669 \emph default
13670  where nnnn is a number less than 100 (which implies a limit of utmost 100
13671  inline assembler labels
13672 \emph on
13673 per function
13674 \emph default
13675 \noun on
13676 )
13677 \noun default
13678 .
13679
13680 \layout Verse
13681
13682
13683 \family typewriter
13684 _asm
13685 \begin_inset LatexCommand \index{\_asm}
13686
13687 \end_inset
13688
13689
13690 \begin_inset LatexCommand \index{\_\_asm}
13691
13692 \end_inset
13693
13694
13695 \newline
13696 \SpecialChar ~
13697 \SpecialChar ~
13698 \SpecialChar ~
13699 \SpecialChar ~
13700 mov\SpecialChar ~
13701 \SpecialChar ~
13702 \SpecialChar ~
13703 \SpecialChar ~
13704 \SpecialChar ~
13705 b,#10
13706 \newline
13707 00001$:
13708 \newline
13709 \SpecialChar ~
13710 \SpecialChar ~
13711 \SpecialChar ~
13712 \SpecialChar ~
13713 djnz\SpecialChar ~
13714 \SpecialChar ~
13715 \SpecialChar ~
13716 \SpecialChar ~
13717 b,00001$
13718 \newline
13719 _endasm
13720 \begin_inset LatexCommand \index{\_endasm}
13721
13722 \end_inset
13723
13724
13725 \begin_inset LatexCommand \index{\_\_endasm}
13726
13727 \end_inset
13728
13729  ;
13730 \layout Standard
13731
13732 Inline assembler code cannot reference any C-Labels, however it can reference
13733  labels
13734 \begin_inset LatexCommand \index{Labels}
13735
13736 \end_inset
13737
13738  defined by the inline assembler, e.g.:
13739 \layout Verse
13740
13741
13742 \family typewriter
13743 foo() {
13744 \newline
13745 \SpecialChar ~
13746 \SpecialChar ~
13747 \SpecialChar ~
13748 \SpecialChar ~
13749 /* some c code */
13750 \newline
13751 \SpecialChar ~
13752 \SpecialChar ~
13753 \SpecialChar ~
13754 \SpecialChar ~
13755 _asm
13756 \newline
13757 \SpecialChar ~
13758 \SpecialChar ~
13759 \SpecialChar ~
13760 \SpecialChar ~
13761 \SpecialChar ~
13762 \SpecialChar ~
13763 ; some assembler code
13764 \newline
13765 \SpecialChar ~
13766 \SpecialChar ~
13767 \SpecialChar ~
13768 \SpecialChar ~
13769 \SpecialChar ~
13770 \SpecialChar ~
13771 ljmp $0003
13772 \newline
13773 \SpecialChar ~
13774 \SpecialChar ~
13775 \SpecialChar ~
13776 \SpecialChar ~
13777 _endasm;
13778 \newline
13779 \SpecialChar ~
13780 \SpecialChar ~
13781 \SpecialChar ~
13782 \SpecialChar ~
13783 /* some more c code */
13784 \newline
13785 clabel:\SpecialChar ~
13786 \SpecialChar ~
13787 /* inline assembler cannot reference this label */
13788 \newline
13789 \SpecialChar ~
13790 \SpecialChar ~
13791 \SpecialChar ~
13792 \SpecialChar ~
13793 _asm
13794 \newline
13795 \SpecialChar ~
13796 \SpecialChar ~
13797 \SpecialChar ~
13798 \SpecialChar ~
13799 $0003: ;label (can be referenced by inline assembler only)
13800 \newline
13801 \SpecialChar ~
13802 \SpecialChar ~
13803 \SpecialChar ~
13804 \SpecialChar ~
13805 _endasm
13806 \begin_inset LatexCommand \index{\_endasm}
13807
13808 \end_inset
13809
13810
13811 \begin_inset LatexCommand \index{\_\_endasm}
13812
13813 \end_inset
13814
13815  ;
13816 \newline
13817 \SpecialChar ~
13818 \SpecialChar ~
13819 \SpecialChar ~
13820 \SpecialChar ~
13821 /* some more c code */
13822 \newline
13823 }
13824 \layout Standard
13825
13826 In other words inline assembly code can access labels defined in inline
13827  assembly within the scope of the function.
13828  The same goes the other way, i.e.
13829  labels defines in inline assembly can not be accessed by C statements.
13830 \layout Section
13831
13832 Interfacing with Assembler Code
13833 \begin_inset LatexCommand \index{Assembler routines}
13834
13835 \end_inset
13836
13837
13838 \layout Subsection
13839
13840 Global Registers used for Parameter Passing
13841 \begin_inset LatexCommand \index{Parameter passing}
13842
13843 \end_inset
13844
13845
13846 \layout Standard
13847
13848 The compiler always uses the global registers
13849 \emph on
13850 DPL, DPH
13851 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
13852
13853 \end_inset
13854
13855
13856 \begin_inset LatexCommand \index{DPTR}
13857
13858 \end_inset
13859
13860 , B
13861 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
13862
13863 \end_inset
13864
13865
13866 \emph default
13867 and
13868 \emph on
13869  ACC
13870 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
13871
13872 \end_inset
13873
13874
13875 \emph default
13876  to pass the first parameter to a routine.
13877  The second parameter onwards is either allocated on the stack (for reentrant
13878  routines or if -
13879 \begin_inset ERT
13880 status Collapsed
13881
13882 \layout Standard
13883
13884 \backslash
13885 /
13886 \end_inset
13887
13888 -stack-auto is used) or in data / xdata memory (depending on the memory
13889  model).
13890
13891 \layout Subsection
13892
13893 Assembler Routine (non-reentrant)
13894 \layout Standard
13895
13896 In the following example
13897 \begin_inset LatexCommand \index{reentrant}
13898
13899 \end_inset
13900
13901
13902 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
13903
13904 \end_inset
13905
13906  the function c_func calls an assembler routine asm_func, which takes two
13907  parameters
13908 \begin_inset LatexCommand \index{function parameter}
13909
13910 \end_inset
13911
13912 .
13913 \layout Verse
13914
13915
13916 \family typewriter
13917 extern int asm_func(unsigned char, unsigned char);
13918 \newline
13919
13920 \newline
13921 int c_func (unsigned char i, unsigned char j)
13922 \newline
13923 {
13924 \newline
13925 \SpecialChar ~
13926 \SpecialChar ~
13927 \SpecialChar ~
13928 \SpecialChar ~
13929 return asm_func(i,j);
13930 \newline
13931 }
13932 \newline
13933
13934 \newline
13935 int main()
13936 \newline
13937 {
13938 \newline
13939 \SpecialChar ~
13940 \SpecialChar ~
13941 \SpecialChar ~
13942 \SpecialChar ~
13943 return c_func(10,9);
13944 \newline
13945 }
13946 \layout Standard
13947
13948 The corresponding assembler function is:
13949 \layout Verse
13950
13951
13952 \family typewriter
13953 .globl _asm_func_PARM_2
13954 \newline
13955 \SpecialChar ~
13956 \SpecialChar ~
13957 \SpecialChar ~
13958 \SpecialChar ~
13959 \SpecialChar ~
13960 \SpecialChar ~
13961 \SpecialChar ~
13962 \SpecialChar ~
13963 .globl _asm_func
13964 \newline
13965 \SpecialChar ~
13966 \SpecialChar ~
13967 \SpecialChar ~
13968 \SpecialChar ~
13969 \SpecialChar ~
13970 \SpecialChar ~
13971 \SpecialChar ~
13972 \SpecialChar ~
13973 .area OSEG
13974 \newline
13975 _asm_func_PARM_2:
13976 \newline
13977 \SpecialChar ~
13978 \SpecialChar ~
13979 \SpecialChar ~
13980 \SpecialChar ~
13981 \SpecialChar ~
13982 \SpecialChar ~
13983 \SpecialChar ~
13984 \SpecialChar ~
13985 .ds    1
13986 \newline
13987 \SpecialChar ~
13988 \SpecialChar ~
13989 \SpecialChar ~
13990 \SpecialChar ~
13991 \SpecialChar ~
13992 \SpecialChar ~
13993 \SpecialChar ~
13994 \SpecialChar ~
13995 .area CSEG
13996 \newline
13997 _asm_func:
13998 \newline
13999 \SpecialChar ~
14000 \SpecialChar ~
14001 \SpecialChar ~
14002 \SpecialChar ~
14003 \SpecialChar ~
14004 \SpecialChar ~
14005 \SpecialChar ~
14006 \SpecialChar ~
14007 mov\SpecialChar ~
14008 \SpecialChar ~
14009 \SpecialChar ~
14010 \SpecialChar ~
14011 a,dpl
14012 \newline
14013 \SpecialChar ~
14014 \SpecialChar ~
14015 \SpecialChar ~
14016 \SpecialChar ~
14017 \SpecialChar ~
14018 \SpecialChar ~
14019 \SpecialChar ~
14020 \SpecialChar ~
14021 add\SpecialChar ~
14022 \SpecialChar ~
14023 \SpecialChar ~
14024 \SpecialChar ~
14025 a,_asm_func_PARM_2
14026 \newline
14027 \SpecialChar ~
14028 \SpecialChar ~
14029 \SpecialChar ~
14030 \SpecialChar ~
14031 \SpecialChar ~
14032 \SpecialChar ~
14033 \SpecialChar ~
14034 \SpecialChar ~
14035 mov\SpecialChar ~
14036 \SpecialChar ~
14037 \SpecialChar ~
14038 \SpecialChar ~
14039 dpl,a
14040 \newline
14041 \SpecialChar ~
14042 \SpecialChar ~
14043 \SpecialChar ~
14044 \SpecialChar ~
14045 \SpecialChar ~
14046 \SpecialChar ~
14047 \SpecialChar ~
14048 \SpecialChar ~
14049 mov\SpecialChar ~
14050 \SpecialChar ~
14051 \SpecialChar ~
14052 \SpecialChar ~
14053 dph
14054 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
14055
14056 \end_inset
14057
14058 ,#0x00
14059 \newline
14060 \SpecialChar ~
14061 \SpecialChar ~
14062 \SpecialChar ~
14063 \SpecialChar ~
14064 \SpecialChar ~
14065 \SpecialChar ~
14066 \SpecialChar ~
14067 \SpecialChar ~
14068 ret
14069 \layout Standard
14070
14071 Note here that the return values
14072 \begin_inset LatexCommand \index{return value}
14073
14074 \end_inset
14075
14076  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
14077  two byte values.
14078  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
14079 b' & 'acc' for four byte values.
14080 \layout Standard
14081
14082 The parameter naming convention is _<function_name>_PARM_<n>, where n is
14083  the parameter number starting from 1, and counting from the left.
14084  The first parameter is passed in
14085 \begin_inset Quotes eld
14086 \end_inset
14087
14088 dpl
14089 \begin_inset Quotes erd
14090 \end_inset
14091
14092  for a one byte parameter,
14093 \begin_inset Quotes eld
14094 \end_inset
14095
14096 dptr
14097 \begin_inset Quotes erd
14098 \end_inset
14099
14100  for two bytes,
14101 \begin_inset Quotes eld
14102 \end_inset
14103
14104 b,dptr
14105 \begin_inset Quotes erd
14106 \end_inset
14107
14108  for three bytes and
14109 \begin_inset Quotes eld
14110 \end_inset
14111
14112 acc,b,dptr
14113 \begin_inset Quotes erd
14114 \end_inset
14115
14116  for a four bytes parameter.
14117  The variable name for the second parameter will be _<function_name>_PARM_2.
14118 \newline
14119
14120 \newline
14121 Assemble the assembler routine with the following command:
14122 \newline
14123
14124 \newline
14125
14126 \family sans
14127 \series bold
14128 asx8051 -losg asmfunc.asm
14129 \newline
14130
14131 \newline
14132
14133 \family default
14134 \series default
14135 Then compile and link the assembler routine to the C source file with the
14136  following command:
14137 \newline
14138
14139 \newline
14140
14141 \family sans
14142 \series bold
14143 sdcc cfunc.c asmfunc.rel
14144 \layout Subsection
14145
14146 Assembler Routine (reentrant)
14147 \layout Standard
14148
14149 In this case
14150 \begin_inset LatexCommand \index{reentrant}
14151
14152 \end_inset
14153
14154
14155 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
14156
14157 \end_inset
14158
14159  the second parameter
14160 \begin_inset LatexCommand \index{function parameter}
14161
14162 \end_inset
14163
14164  onwards will be passed on the stack, the parameters are pushed from right
14165  to left i.e.
14166  after the call the leftmost parameter will be on the top of the stack.
14167  Here is an example:
14168 \layout Verse
14169
14170
14171 \family typewriter
14172 extern int asm_func(unsigned char, unsigned char);
14173 \newline
14174
14175 \newline
14176 int c_func (unsigned char i, unsigned char j) reentrant
14177 \newline
14178 {
14179 \newline
14180 \SpecialChar ~
14181 \SpecialChar ~
14182 \SpecialChar ~
14183 \SpecialChar ~
14184 return asm_func(i,j);
14185 \newline
14186 }
14187 \newline
14188
14189 \newline
14190 int main()
14191 \newline
14192 {
14193 \newline
14194 \SpecialChar ~
14195 \SpecialChar ~
14196 \SpecialChar ~
14197 \SpecialChar ~
14198 return c_func(10,9);
14199 \newline
14200 }
14201 \layout Standard
14202
14203 The corresponding assembler routine is:
14204 \layout Verse
14205
14206
14207 \family typewriter
14208 .globl _asm_func
14209 \newline
14210 _asm_func:
14211 \newline
14212 \SpecialChar ~
14213 \SpecialChar ~
14214 \SpecialChar ~
14215 \SpecialChar ~
14216 push  _bp
14217 \newline
14218 \SpecialChar ~
14219 \SpecialChar ~
14220 \SpecialChar ~
14221 \SpecialChar ~
14222 mov _bp,sp
14223 \newline
14224 \SpecialChar ~
14225 \SpecialChar ~
14226 \SpecialChar ~
14227 \SpecialChar ~
14228 mov r2,dpl
14229 \newline
14230 \SpecialChar ~
14231 \SpecialChar ~
14232 \SpecialChar ~
14233 \SpecialChar ~
14234 mov a,_bp
14235 \newline
14236 \SpecialChar ~
14237 \SpecialChar ~
14238 \SpecialChar ~
14239 \SpecialChar ~
14240 add a,#0xfd
14241 \newline
14242 \SpecialChar ~
14243 \SpecialChar ~
14244 \SpecialChar ~
14245 \SpecialChar ~
14246 mov r0,a
14247 \newline
14248 \SpecialChar ~
14249 \SpecialChar ~
14250 \SpecialChar ~
14251 \SpecialChar ~
14252 add  a,#0xfc ;?
14253 \newline
14254 \SpecialChar ~
14255 \SpecialChar ~
14256 \SpecialChar ~
14257 \SpecialChar ~
14258 mov  r1,a
14259 \newline
14260 \SpecialChar ~
14261 \SpecialChar ~
14262 \SpecialChar ~
14263 \SpecialChar ~
14264 mov  a,@r0
14265 \newline
14266 \SpecialChar ~
14267 \SpecialChar ~
14268 \SpecialChar ~
14269 \SpecialChar ~
14270 add  a,r2 ;?
14271 \newline
14272 \SpecialChar ~
14273 \SpecialChar ~
14274 \SpecialChar ~
14275 \SpecialChar ~
14276 mov  dpl,a
14277 \newline
14278 \SpecialChar ~
14279 \SpecialChar ~
14280 \SpecialChar ~
14281 \SpecialChar ~
14282 mov  dph,#0x00
14283 \newline
14284 \SpecialChar ~
14285 \SpecialChar ~
14286 \SpecialChar ~
14287 \SpecialChar ~
14288 mov  sp,_bp
14289 \newline
14290 \SpecialChar ~
14291 \SpecialChar ~
14292 \SpecialChar ~
14293 \SpecialChar ~
14294 pop  _bp
14295 \newline
14296 \SpecialChar ~
14297 \SpecialChar ~
14298 \SpecialChar ~
14299 \SpecialChar ~
14300 ret
14301 \layout Standard
14302
14303 The compiling and linking procedure remains the same, however note the extra
14304  entry & exit linkage required for the assembler code, _bp is the stack
14305  frame pointer and is used to compute the offset into the stack for parameters
14306  and local variables.
14307 \layout Section
14308
14309 int (16 bit)
14310 \begin_inset LatexCommand \index{int (16 bit)}
14311
14312 \end_inset
14313
14314  and long (32 bit)
14315 \begin_inset LatexCommand \index{long (32 bit)}
14316
14317 \end_inset
14318
14319  Support
14320 \layout Standard
14321
14322 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
14323  multiplication and modulus operations are implemented by support routines.
14324  These support routines are all developed in ANSI-C to facilitate porting
14325  to other MCUs, although some model specific assembler optimizations are
14326  used.
14327  The following files contain the described routines, all of them can be
14328  found in <installdir>/share/sdcc/lib.
14329 \newline
14330
14331 \layout Standard
14332 \align center
14333
14334 \begin_inset  Tabular
14335 <lyxtabular version="3" rows="11" columns="2">
14336 <features>
14337 <column alignment="left" valignment="top" leftline="true" width="0">
14338 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
14339 <row topline="true" bottomline="true">
14340 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14341 \begin_inset Text
14342
14343 \layout Standard
14344
14345
14346 \series bold
14347 Function
14348 \end_inset
14349 </cell>
14350 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14351 \begin_inset Text
14352
14353 \layout Standard
14354
14355
14356 \series bold
14357 Description
14358 \end_inset
14359 </cell>
14360 </row>
14361 <row topline="true">
14362 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14363 \begin_inset Text
14364
14365 \layout Standard
14366
14367 _mulint.c
14368 \end_inset
14369 </cell>
14370 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14371 \begin_inset Text
14372
14373 \layout Standard
14374
14375 16 bit multiplication
14376 \end_inset
14377 </cell>
14378 </row>
14379 <row topline="true">
14380 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14381 \begin_inset Text
14382
14383 \layout Standard
14384
14385 _divsint.c
14386 \end_inset
14387 </cell>
14388 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14389 \begin_inset Text
14390
14391 \layout Standard
14392
14393  signed 16 bit division (calls _divuint)
14394 \end_inset
14395 </cell>
14396 </row>
14397 <row topline="true">
14398 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14399 \begin_inset Text
14400
14401 \layout Standard
14402
14403 _divuint.c
14404 \end_inset
14405 </cell>
14406 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14407 \begin_inset Text
14408
14409 \layout Standard
14410
14411  unsigned 16 bit division
14412 \end_inset
14413 </cell>
14414 </row>
14415 <row topline="true">
14416 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14417 \begin_inset Text
14418
14419 \layout Standard
14420
14421 _modsint.c
14422 \end_inset
14423 </cell>
14424 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14425 \begin_inset Text
14426
14427 \layout Standard
14428
14429 signed 16 bit modulus (calls _moduint)
14430 \end_inset
14431 </cell>
14432 </row>
14433 <row topline="true">
14434 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14435 \begin_inset Text
14436
14437 \layout Standard
14438
14439 _moduint.c
14440 \end_inset
14441 </cell>
14442 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14443 \begin_inset Text
14444
14445 \layout Standard
14446
14447 unsigned 16 bit modulus
14448 \end_inset
14449 </cell>
14450 </row>
14451 <row topline="true">
14452 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14453 \begin_inset Text
14454
14455 \layout Standard
14456
14457 _mullong.c
14458 \end_inset
14459 </cell>
14460 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14461 \begin_inset Text
14462
14463 \layout Standard
14464
14465 32 bit multiplication
14466 \end_inset
14467 </cell>
14468 </row>
14469 <row topline="true">
14470 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14471 \begin_inset Text
14472
14473 \layout Standard
14474
14475 _divslong.c
14476 \end_inset
14477 </cell>
14478 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14479 \begin_inset Text
14480
14481 \layout Standard
14482
14483  signed 32 division (calls _divulong)
14484 \end_inset
14485 </cell>
14486 </row>
14487 <row topline="true">
14488 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14489 \begin_inset Text
14490
14491 \layout Standard
14492
14493 _divulong.c
14494 \end_inset
14495 </cell>
14496 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14497 \begin_inset Text
14498
14499 \layout Standard
14500
14501 unsigned 32 division
14502 \end_inset
14503 </cell>
14504 </row>
14505 <row topline="true">
14506 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14507 \begin_inset Text
14508
14509 \layout Standard
14510
14511 _modslong.c
14512 \end_inset
14513 </cell>
14514 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14515 \begin_inset Text
14516
14517 \layout Standard
14518
14519  signed 32 bit modulus (calls _modulong)
14520 \end_inset
14521 </cell>
14522 </row>
14523 <row topline="true" bottomline="true">
14524 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14525 \begin_inset Text
14526
14527 \layout Standard
14528
14529 _modulong.c
14530 \end_inset
14531 </cell>
14532 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14533 \begin_inset Text
14534
14535 \layout Standard
14536
14537 unsigned 32 bit modulus
14538 \end_inset
14539 </cell>
14540 </row>
14541 </lyxtabular>
14542
14543 \end_inset
14544
14545
14546 \newline
14547
14548 \layout Standard
14549
14550 Since they are compiled as
14551 \emph on
14552 non-reentrant
14553 \emph default
14554
14555 \begin_inset LatexCommand \index{reentrant}
14556
14557 \end_inset
14558
14559 , interrupt
14560 \begin_inset LatexCommand \index{interrupt}
14561
14562 \end_inset
14563
14564  service routines should not do any of the above operations.
14565  If this is unavoidable then the above routines will need to be compiled
14566  with the
14567 \emph on
14568 -
14569 \begin_inset ERT
14570 status Collapsed
14571
14572 \layout Standard
14573
14574 \backslash
14575 /
14576 \end_inset
14577
14578 -stack-auto
14579 \begin_inset LatexCommand \index{-\/-stack-auto}
14580
14581 \end_inset
14582
14583
14584 \emph default
14585  option, after which the source program will have to be compiled with
14586 \emph on
14587 -
14588 \begin_inset ERT
14589 status Collapsed
14590
14591 \layout Standard
14592
14593 \backslash
14594 /
14595 \end_inset
14596
14597 -int-long-reent
14598 \begin_inset LatexCommand \index{-\/-int-long-reent}
14599
14600 \end_inset
14601
14602
14603 \emph default
14604  option.
14605  Notice that you don't have to call these routines directly.
14606  The compiler will use them automatically every time an integer operation
14607  is required.
14608 \layout Section
14609
14610 Floating Point Support
14611 \begin_inset LatexCommand \index{Floating point support}
14612
14613 \end_inset
14614
14615
14616 \layout Standard
14617
14618 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
14619  floating point support routines are derived from gcc's floatlib.c and consist
14620  of the following routines:
14621 \newline
14622
14623 \layout Standard
14624 \align center
14625
14626 \size footnotesize
14627
14628 \begin_inset  Tabular
14629 <lyxtabular version="3" rows="17" columns="2">
14630 <features>
14631 <column alignment="left" valignment="top" leftline="true" width="0">
14632 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
14633 <row topline="true" bottomline="true">
14634 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14635 \begin_inset Text
14636
14637 \layout Standard
14638
14639
14640 \family roman
14641 \series medium
14642 \shape up
14643 \size normal
14644 \emph off
14645 \bar no
14646 \noun off
14647 \color none
14648 Function
14649 \end_inset
14650 </cell>
14651 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14652 \begin_inset Text
14653
14654 \layout Standard
14655
14656 Description
14657 \end_inset
14658 </cell>
14659 </row>
14660 <row topline="true">
14661 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14662 \begin_inset Text
14663
14664 \layout Standard
14665
14666
14667 \family roman
14668 \series medium
14669 \shape up
14670 \size normal
14671 \emph off
14672 \bar no
14673 \noun off
14674 \color none
14675 _fsadd.c
14676 \end_inset
14677 </cell>
14678 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14679 \begin_inset Text
14680
14681 \layout Standard
14682
14683
14684 \family roman
14685 \series medium
14686 \shape up
14687 \size normal
14688 \emph off
14689 \bar no
14690 \noun off
14691 \color none
14692 add floating point numbers
14693 \end_inset
14694 </cell>
14695 </row>
14696 <row topline="true">
14697 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14698 \begin_inset Text
14699
14700 \layout Standard
14701
14702
14703 \family roman
14704 \series medium
14705 \shape up
14706 \size normal
14707 \emph off
14708 \bar no
14709 \noun off
14710 \color none
14711 _fssub.c
14712 \end_inset
14713 </cell>
14714 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14715 \begin_inset Text
14716
14717 \layout Standard
14718
14719
14720 \family roman
14721 \series medium
14722 \shape up
14723 \size normal
14724 \emph off
14725 \bar no
14726 \noun off
14727 \color none
14728 subtract floating point numbers
14729 \end_inset
14730 </cell>
14731 </row>
14732 <row topline="true">
14733 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14734 \begin_inset Text
14735
14736 \layout Standard
14737
14738
14739 \family roman
14740 \series medium
14741 \shape up
14742 \size normal
14743 \emph off
14744 \bar no
14745 \noun off
14746 \color none
14747 _fsdiv.c
14748 \end_inset
14749 </cell>
14750 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14751 \begin_inset Text
14752
14753 \layout Standard
14754
14755
14756 \family roman
14757 \series medium
14758 \shape up
14759 \size normal
14760 \emph off
14761 \bar no
14762 \noun off
14763 \color none
14764 divide floating point numbers
14765 \end_inset
14766 </cell>
14767 </row>
14768 <row topline="true">
14769 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14770 \begin_inset Text
14771
14772 \layout Standard
14773
14774
14775 \family roman
14776 \series medium
14777 \shape up
14778 \size normal
14779 \emph off
14780 \bar no
14781 \noun off
14782 \color none
14783 _fsmul.c
14784 \end_inset
14785 </cell>
14786 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14787 \begin_inset Text
14788
14789 \layout Standard
14790
14791
14792 \family roman
14793 \series medium
14794 \shape up
14795 \size normal
14796 \emph off
14797 \bar no
14798 \noun off
14799 \color none
14800 multiply floating point numbers
14801 \end_inset
14802 </cell>
14803 </row>
14804 <row topline="true">
14805 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14806 \begin_inset Text
14807
14808 \layout Standard
14809
14810
14811 \family roman
14812 \series medium
14813 \shape up
14814 \size normal
14815 \emph off
14816 \bar no
14817 \noun off
14818 \color none
14819 _fs2uchar.c
14820 \end_inset
14821 </cell>
14822 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14823 \begin_inset Text
14824
14825 \layout Standard
14826
14827
14828 \family roman
14829 \series medium
14830 \shape up
14831 \size normal
14832 \emph off
14833 \bar no
14834 \noun off
14835 \color none
14836 convert floating point to unsigned char
14837 \end_inset
14838 </cell>
14839 </row>
14840 <row topline="true">
14841 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14842 \begin_inset Text
14843
14844 \layout Standard
14845
14846
14847 \family roman
14848 \series medium
14849 \shape up
14850 \size normal
14851 \emph off
14852 \bar no
14853 \noun off
14854 \color none
14855 _fs2char.c
14856 \end_inset
14857 </cell>
14858 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14859 \begin_inset Text
14860
14861 \layout Standard
14862
14863
14864 \family roman
14865 \series medium
14866 \shape up
14867 \size normal
14868 \emph off
14869 \bar no
14870 \noun off
14871 \color none
14872 convert floating point to signed char
14873 \end_inset
14874 </cell>
14875 </row>
14876 <row topline="true">
14877 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14878 \begin_inset Text
14879
14880 \layout Standard
14881
14882
14883 \family roman
14884 \series medium
14885 \shape up
14886 \size normal
14887 \emph off
14888 \bar no
14889 \noun off
14890 \color none
14891 _fs2uint.c
14892 \end_inset
14893 </cell>
14894 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14895 \begin_inset Text
14896
14897 \layout Standard
14898
14899
14900 \family roman
14901 \series medium
14902 \shape up
14903 \size normal
14904 \emph off
14905 \bar no
14906 \noun off
14907 \color none
14908 convert floating point to unsigned int
14909 \end_inset
14910 </cell>
14911 </row>
14912 <row topline="true">
14913 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14914 \begin_inset Text
14915
14916 \layout Standard
14917
14918
14919 \family roman
14920 \series medium
14921 \shape up
14922 \size normal
14923 \emph off
14924 \bar no
14925 \noun off
14926 \color none
14927 _fs2int.c
14928 \end_inset
14929 </cell>
14930 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14931 \begin_inset Text
14932
14933 \layout Standard
14934
14935
14936 \family roman
14937 \series medium
14938 \shape up
14939 \size normal
14940 \emph off
14941 \bar no
14942 \noun off
14943 \color none
14944 convert floating point to signed int
14945 \end_inset
14946 </cell>
14947 </row>
14948 <row topline="true">
14949 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14950 \begin_inset Text
14951
14952 \layout Standard
14953
14954
14955 \family roman
14956 \series medium
14957 \shape up
14958 \size normal
14959 \emph off
14960 \bar no
14961 \noun off
14962 \color none
14963 _fs2ulong.
14964 \family default
14965 \series default
14966 \shape default
14967 \size default
14968 \emph default
14969 \bar default
14970 \noun default
14971 \color default
14972 c
14973 \end_inset
14974 </cell>
14975 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14976 \begin_inset Text
14977
14978 \layout Standard
14979
14980
14981 \family roman
14982 \series medium
14983 \shape up
14984 \size normal
14985 \emph off
14986 \bar no
14987 \noun off
14988 \color none
14989 convert floating point to unsigned long
14990 \end_inset
14991 </cell>
14992 </row>
14993 <row topline="true">
14994 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14995 \begin_inset Text
14996
14997 \layout Standard
14998
14999
15000 \family roman
15001 \series medium
15002 \shape up
15003 \size normal
15004 \emph off
15005 \bar no
15006 \noun off
15007 \color none
15008 _fs2long.c
15009 \end_inset
15010 </cell>
15011 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15012 \begin_inset Text
15013
15014 \layout Standard
15015
15016
15017 \family roman
15018 \series medium
15019 \shape up
15020 \size normal
15021 \emph off
15022 \bar no
15023 \noun off
15024 \color none
15025 convert floating point to signed long
15026 \end_inset
15027 </cell>
15028 </row>
15029 <row topline="true">
15030 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15031 \begin_inset Text
15032
15033 \layout Standard
15034
15035
15036 \family roman
15037 \series medium
15038 \shape up
15039 \size normal
15040 \emph off
15041 \bar no
15042 \noun off
15043 \color none
15044 _uchar2fs.c
15045 \end_inset
15046 </cell>
15047 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15048 \begin_inset Text
15049
15050 \layout Standard
15051
15052
15053 \family roman
15054 \series medium
15055 \shape up
15056 \size normal
15057 \emph off
15058 \bar no
15059 \noun off
15060 \color none
15061 convert unsigned char to floating point
15062 \end_inset
15063 </cell>
15064 </row>
15065 <row topline="true">
15066 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15067 \begin_inset Text
15068
15069 \layout Standard
15070
15071
15072 \family roman
15073 \series medium
15074 \shape up
15075 \size normal
15076 \emph off
15077 \bar no
15078 \noun off
15079 \color none
15080 _char2fs.c
15081 \end_inset
15082 </cell>
15083 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15084 \begin_inset Text
15085
15086 \layout Standard
15087
15088
15089 \family roman
15090 \series medium
15091 \shape up
15092 \size normal
15093 \emph off
15094 \bar no
15095 \noun off
15096 \color none
15097 convert char to floating point number
15098 \end_inset
15099 </cell>
15100 </row>
15101 <row topline="true">
15102 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15103 \begin_inset Text
15104
15105 \layout Standard
15106
15107
15108 \family roman
15109 \series medium
15110 \shape up
15111 \size normal
15112 \emph off
15113 \bar no
15114 \noun off
15115 \color none
15116 _uint2fs.c
15117 \end_inset
15118 </cell>
15119 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15120 \begin_inset Text
15121
15122 \layout Standard
15123
15124
15125 \family roman
15126 \series medium
15127 \shape up
15128 \size normal
15129 \emph off
15130 \bar no
15131 \noun off
15132 \color none
15133 convert unsigned int to floating point
15134 \end_inset
15135 </cell>
15136 </row>
15137 <row topline="true">
15138 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15139 \begin_inset Text
15140
15141 \layout Standard
15142
15143
15144 \family roman
15145 \series medium
15146 \shape up
15147 \size normal
15148 \emph off
15149 \bar no
15150 \noun off
15151 \color none
15152 _int2fs.c
15153 \end_inset
15154 </cell>
15155 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15156 \begin_inset Text
15157
15158 \layout Standard
15159
15160
15161 \family roman
15162 \series medium
15163 \shape up
15164 \size normal
15165 \emph off
15166 \bar no
15167 \noun off
15168 \color none
15169 convert int to floating point numbers
15170 \end_inset
15171 </cell>
15172 </row>
15173 <row topline="true">
15174 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15175 \begin_inset Text
15176
15177 \layout Standard
15178
15179
15180 \family roman
15181 \series medium
15182 \shape up
15183 \size normal
15184 \emph off
15185 \bar no
15186 \noun off
15187 \color none
15188 _ulong2fs.c
15189 \end_inset
15190 </cell>
15191 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15192 \begin_inset Text
15193
15194 \layout Standard
15195
15196
15197 \family roman
15198 \series medium
15199 \shape up
15200 \size normal
15201 \emph off
15202 \bar no
15203 \noun off
15204 \color none
15205 convert unsigned long to floating point number
15206 \end_inset
15207 </cell>
15208 </row>
15209 <row topline="true" bottomline="true">
15210 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15211 \begin_inset Text
15212
15213 \layout Standard
15214
15215
15216 \family roman
15217 \series medium
15218 \shape up
15219 \size normal
15220 \emph off
15221 \bar no
15222 \noun off
15223 \color none
15224 _long2fs.c
15225 \end_inset
15226 </cell>
15227 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15228 \begin_inset Text
15229
15230 \layout Standard
15231
15232
15233 \family roman
15234 \series medium
15235 \shape up
15236 \size normal
15237 \emph off
15238 \bar no
15239 \noun off
15240 \color none
15241 convert long to floating point number
15242 \end_inset
15243 </cell>
15244 </row>
15245 </lyxtabular>
15246
15247 \end_inset
15248
15249
15250 \newline
15251
15252 \layout Standard
15253
15254 These support routines are developed in ANSI-C so there is room for space
15255  and speed improvement
15256 \begin_inset Foot
15257 collapsed false
15258
15259 \layout Standard
15260
15261 These floating point routines (
15262 \emph on
15263 not
15264 \emph default
15265  sinf(), cosf(), ...) for the mcs51 are implemented in assembler.
15266
15267 \end_inset
15268
15269 .
15270  Note if all these routines are used simultaneously the data space might
15271  overflow.
15272  For serious floating point usage the large model might be needed.
15273  Also notice that you don't have to call this routines directly.
15274  The compiler will use them automatically every time a floating point operation
15275  is required.
15276 \layout Section
15277
15278 Library Routines
15279 \begin_inset LatexCommand \index{Libraries}
15280
15281 \end_inset
15282
15283
15284 \layout Standard
15285
15286
15287 \emph on
15288 <pending: this is messy and incomplete - a little more information is in
15289  sdcc/doc/libdoc.txt
15290 \emph default
15291  >
15292 \layout Subsection
15293
15294 Compiler support routines (_gptrget, _mulint etc.)
15295 \layout Subsection
15296
15297 Stdclib functions (puts, printf, strcat etc.)
15298 \layout Subsubsection
15299
15300 <stdio.h>
15301 \layout Standard
15302
15303
15304 \begin_inset LatexCommand \index{<stdio.h>}
15305
15306 \end_inset
15307
15308 As usual on embedded systems you have to provide your own
15309 \family typewriter
15310 getchar()
15311 \begin_inset LatexCommand \index{getchar()}
15312
15313 \end_inset
15314
15315
15316 \family default
15317 and
15318 \family typewriter
15319 putchar()
15320 \begin_inset LatexCommand \index{putchar()}
15321
15322 \end_inset
15323
15324
15325 \family default
15326  routines.
15327  SDCC does not know whether the system connects to a serial line with or
15328  without handshake, LCD, keyboard or other device.
15329  And whether a
15330 \family typewriter
15331 lf
15332 \family default
15333  to
15334 \family typewriter
15335 crlf
15336 \family default
15337  conversion within
15338 \family typewriter
15339 putchar()
15340 \family default
15341  is intended.
15342  You'll find examples for serial routines f.e.
15343  in sdcc/device/lib.
15344 \layout Standard
15345
15346 The default
15347 \family typewriter
15348  printf()
15349 \begin_inset LatexCommand \index{printf()}
15350
15351 \end_inset
15352
15353
15354 \family default
15355 implementation in
15356 \family typewriter
15357  printf_large.c
15358 \family default
15359  does not support float (except on ds390).
15360  To enable this recompile it with the option
15361 \emph on
15362 -
15363 \begin_inset ERT
15364 status Collapsed
15365
15366 \layout Standard
15367
15368 \backslash
15369 /
15370 \end_inset
15371
15372 DUSE_FLOATS=1
15373 \begin_inset LatexCommand \index{USE\_FLOATS}
15374
15375 \end_inset
15376
15377
15378 \emph default
15379  on the command line.
15380  Use
15381 \emph on
15382  -
15383 \begin_inset ERT
15384 status Collapsed
15385
15386 \layout Standard
15387
15388 \backslash
15389 /
15390 \end_inset
15391
15392 -model-large
15393 \begin_inset LatexCommand \index{-\/-model-large}
15394
15395 \end_inset
15396
15397
15398 \emph default
15399  for the mcs51 port, since this uses a lot of memory.
15400 \layout Standard
15401
15402 If you're short on memory you might want to use
15403 \family typewriter
15404 printf_small()
15405 \begin_inset LatexCommand \index{printf\_small()}
15406
15407 \end_inset
15408
15409
15410 \family default
15411
15412 \emph on
15413 instead
15414 \emph default
15415  of
15416 \family typewriter
15417  printf().
15418
15419 \family default
15420  For the mcs51 there additionally are assembly versions
15421 \family typewriter
15422 printf_tiny()
15423 \begin_inset LatexCommand \index{printf\_tiny() (mcs51)}
15424
15425 \end_inset
15426
15427
15428 \family default
15429  (subset of printf using less than 270 bytes) and
15430 \family typewriter
15431 printf_fast()
15432 \begin_inset LatexCommand \index{printf\_fast() (mcs51)}
15433
15434 \end_inset
15435
15436
15437 \family default
15438 and
15439 \family typewriter
15440  printf_fast_f()
15441 \begin_inset LatexCommand \index{printf\_fast\_f() (mcs51)}
15442
15443 \end_inset
15444
15445
15446 \family default
15447  (floating-point aware version of printf_fast) which should fit the requirements
15448  of many embedded systems (printf_fast() can be customized by unsetting
15449  #defines to
15450 \emph on
15451 not
15452 \emph default
15453  support long variables and field widths).
15454 \layout Subsubsection
15455
15456 <malloc.h>
15457 \begin_inset LatexCommand \index{malloc.h}
15458
15459 \end_inset
15460
15461
15462 \layout Standard
15463
15464 Before using dynamic
15465 \begin_inset LatexCommand \index{dynamic}
15466
15467 \end_inset
15468
15469  memory allocation with SDCC, you have to provide heap
15470 \begin_inset LatexCommand \index{heap}
15471
15472 \end_inset
15473
15474  space for malloc to allocate memory from
15475 \family typewriter
15476 .
15477
15478 \family default
15479 You can acomplish this by including the following code into your source:
15480 \layout Verse
15481
15482
15483 \family typewriter
15484 #include <malloc.h>
15485 \begin_inset LatexCommand \index{malloc.h}
15486
15487 \end_inset
15488
15489  /* calloc
15490 \begin_inset LatexCommand \index{calloc}
15491
15492 \end_inset
15493
15494 , malloc
15495 \begin_inset LatexCommand \index{malloc}
15496
15497 \end_inset
15498
15499 , realloc
15500 \begin_inset LatexCommand \index{realloc}
15501
15502 \end_inset
15503
15504 , and free
15505 \begin_inset LatexCommand \index{free}
15506
15507 \end_inset
15508
15509  */
15510 \newline
15511
15512 \newline
15513 #define HEAPSIZE 0x1000 /* Adjust depending on available memory */
15514 \newline
15515 unsigned char xdata myheap[HEAPSIZE]; /* The actual heap for dynamic memory
15516  */
15517 \newline
15518
15519 \newline
15520 void main (void)
15521 \newline
15522 {
15523 \newline
15524 \SpecialChar ~
15525 \SpecialChar ~
15526 \SpecialChar ~
15527 /* Your variable declarations come here*/
15528 \newline
15529 \SpecialChar ~
15530 \SpecialChar ~
15531 \SpecialChar ~
15532 ...
15533 \newline
15534 \SpecialChar ~
15535 \SpecialChar ~
15536 \SpecialChar ~
15537 init_dynamic_memory((MEMHEADER xdata *)myheap, HEAPSIZE);
15538 \newline
15539 \SpecialChar ~
15540 \SpecialChar ~
15541 \SpecialChar ~
15542 ...
15543  /* Rest of your code*/
15544 \newline
15545 }
15546 \newline
15547
15548 \layout Subsection
15549
15550 Math functions (sinf, powf, sqrtf etc.)
15551 \layout Subsubsection
15552
15553 <math.h>
15554 \layout Standard
15555
15556 See definitions in file <math.h>.
15557 \layout Subsection
15558
15559 Other libraries
15560 \layout Standard
15561
15562 Libraries
15563 \begin_inset LatexCommand \index{Libraries}
15564
15565 \end_inset
15566
15567  included in SDCC should have a license at least as liberal as the GNU Lesser
15568  General Public License
15569 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
15570
15571 \end_inset
15572
15573
15574 \emph on
15575 LGPL
15576 \emph default
15577 .
15578 \layout Comment
15579
15580 license statements for the libraries are missing.
15581  sdcc/device/lib/ser_ir.c
15582 \layout Comment
15583
15584 or _decdptr f.e.
15585  come with a GPL (as opposed to LGPL) License - this will not be liberal
15586  enough for many embedded programmers.
15587 \layout Standard
15588
15589 If you have ported some library or want to share experience about some code
15590  which f.e.
15591  falls into any of these categories Busses (I
15592 \begin_inset Formula $^{\textrm{2}}$
15593 \end_inset
15594
15595 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
15596  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
15597  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
15598 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
15599
15600 \end_inset
15601
15602 \SpecialChar ~
15603 would certainly like to hear about it.
15604  Programmers coding for embedded systems are not especially famous for being
15605  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
15606 e these references are very valuable.
15607  Let's help to create a climate where information is shared.
15608 \layout Section
15609
15610 Memory Models
15611 \layout Subsection
15612
15613 MCS51 Memory Models
15614 \begin_inset LatexCommand \index{Memory model}
15615
15616 \end_inset
15617
15618
15619 \begin_inset LatexCommand \index{MCS51 memory model}
15620
15621 \end_inset
15622
15623
15624 \layout Subsubsection
15625
15626 Small, Medium and Large
15627 \layout Standard
15628
15629 SDCC allows three memory models for MCS51 code,
15630 \shape slanted
15631 small, medium
15632 \shape default
15633  and
15634 \shape slanted
15635 large
15636 \shape default
15637 .
15638  Modules compiled with different memory models should
15639 \emph on
15640 never
15641 \emph default
15642  be combined together or the results would be unpredictable.
15643  The library routines supplied with the compiler are compiled as small,
15644  medium and large.
15645  The compiled library modules are contained in separate directories as small,
15646  medium and large so that you can link to the appropriate set.
15647 \layout Standard
15648
15649 When the medium or large model is used all variables declared without a
15650  storage class will be allocated into the external ram, this includes all
15651  parameters and local variables (for non-reentrant
15652 \begin_inset LatexCommand \index{reentrant}
15653
15654 \end_inset
15655
15656  functions).
15657  When the small model is used variables without storage class are allocated
15658  in the internal ram.
15659 \layout Standard
15660
15661 Judicious usage of the processor specific storage classes
15662 \begin_inset LatexCommand \index{Storage class}
15663
15664 \end_inset
15665
15666  and the 'reentrant' function type will yield much more efficient code,
15667  than using the large model.
15668  Several optimizations are disabled when the program is compiled using the
15669  large model, it is therefore recommended that the small model be used unless
15670  absolutely required.
15671 \layout Subsubsection
15672
15673 External Stack
15674 \begin_inset LatexCommand \label{sub:External-Stack}
15675
15676 \end_inset
15677
15678
15679 \begin_inset LatexCommand \index{stack}
15680
15681 \end_inset
15682
15683
15684 \begin_inset LatexCommand \index{External stack (mcs51)}
15685
15686 \end_inset
15687
15688
15689 \layout Standard
15690
15691 The external stack (-
15692 \begin_inset ERT
15693 status Collapsed
15694
15695 \layout Standard
15696
15697 \backslash
15698 /
15699 \end_inset
15700
15701 -xstack option
15702 \begin_inset LatexCommand \index{-\/-xstack}
15703
15704 \end_inset
15705
15706 ) is located in pdata
15707 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
15708
15709 \end_inset
15710
15711  memory (usually at the start of the external ram segment) and uses all
15712  unused space in pdata (max.
15713  256 bytes).
15714  When -
15715 \begin_inset ERT
15716 status Collapsed
15717
15718 \layout Standard
15719
15720 \backslash
15721 /
15722 \end_inset
15723
15724 -xstack option is used to compile the program, the parameters and local
15725  variables
15726 \begin_inset LatexCommand \index{local variables}
15727
15728 \end_inset
15729
15730  of all reentrant functions are allocated in this area.
15731  This option is provided for programs with large stack space requirements.
15732  When used with the -
15733 \begin_inset ERT
15734 status Collapsed
15735
15736 \layout Standard
15737
15738 \backslash
15739 /
15740 \end_inset
15741
15742 -stack-auto
15743 \begin_inset LatexCommand \index{-\/-stack-auto}
15744
15745 \end_inset
15746
15747  option, all parameters and local variables are allocated on the external
15748  stack (note: support libraries will need to be recompiled with the same
15749  options.
15750  There is a predefined target in the library makefile).
15751 \layout Standard
15752
15753 The compiler outputs the higher order address byte of the external ram segment
15754  into port P2
15755 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
15756
15757 \end_inset
15758
15759  (see also section
15760 \begin_inset LatexCommand \ref{sub:MCS51-variants}
15761
15762 \end_inset
15763
15764 ), therefore when using the External Stack option, this port
15765 \emph on
15766 may not
15767 \emph default
15768  be used by the application program.
15769 \layout Subsection
15770
15771 DS390 Memory Model
15772 \begin_inset LatexCommand \index{Memory model}
15773
15774 \end_inset
15775
15776
15777 \begin_inset LatexCommand \index{DS390 memory model}
15778
15779 \end_inset
15780
15781
15782 \layout Standard
15783
15784 The only model supported is Flat 24
15785 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
15786
15787 \end_inset
15788
15789 .
15790  This generates code for the 24 bit contiguous addressing mode of the Dallas
15791  DS80C390 part.
15792  In this mode, up to four meg of external RAM or code space can be directly
15793  addressed.
15794  See the data sheets at www.dalsemi.com for further information on this part.
15795 \newline
15796
15797 \newline
15798 Note that the compiler does not generate any code to place the processor
15799  into 24 bitmode (although
15800 \emph on
15801 tinibios
15802 \emph default
15803  in the ds390 libraries will do that for you).
15804  If you don't use
15805 \emph on
15806 tinibios
15807 \emph default
15808
15809 \begin_inset LatexCommand \index{Tinibios (DS390)}
15810
15811 \end_inset
15812
15813 , the boot loader or similar code must ensure that the processor is in 24
15814  bit contiguous addressing mode before calling the SDCC startup code.
15815 \newline
15816
15817 \newline
15818 Like the
15819 \emph on
15820 -
15821 \begin_inset ERT
15822 status Collapsed
15823
15824 \layout Standard
15825
15826 \backslash
15827 /
15828 \end_inset
15829
15830 -model-large
15831 \emph default
15832  option, variables will by default be placed into the XDATA segment.
15833
15834 \newline
15835
15836 \newline
15837 Segments may be placed anywhere in the 4 meg address space using the usual
15838  -
15839 \begin_inset ERT
15840 status Collapsed
15841
15842 \layout Standard
15843
15844 \backslash
15845 /
15846 \end_inset
15847
15848 -*-loc options.
15849  Note that if any segments are located above 64K, the -r flag must be passed
15850  to the linker to generate the proper segment relocations, and the Intel
15851  HEX output format must be used.
15852  The -r flag can be passed to the linker by using the option
15853 \emph on
15854 -Wl-r
15855 \emph default
15856  on the SDCC command line.
15857  However, currently the linker can not handle code segments > 64k.
15858 \layout Section
15859
15860 Pragmas
15861 \begin_inset LatexCommand \index{Pragmas}
15862
15863 \end_inset
15864
15865
15866 \layout Standard
15867
15868 SDCC supports the following #pragma directives:
15869 \layout Itemize
15870
15871 save
15872 \begin_inset LatexCommand \index{\#pragma save}
15873
15874 \end_inset
15875
15876  - this will save all current options to the save/restore stack.
15877  See #pragma\SpecialChar ~
15878 restore.
15879 \layout Itemize
15880
15881 restore
15882 \begin_inset LatexCommand \index{\#pragma restore}
15883
15884 \end_inset
15885
15886  - will restore saved options from the last save.
15887  saves & restores can be nested.
15888  SDCC uses a save/restore stack: save pushes current options to the stack,
15889  restore pulls current options from the stack.
15890  See #pragma\SpecialChar ~
15891 save.
15892 \newline
15893
15894 \layout Itemize
15895
15896 callee_saves
15897 \begin_inset LatexCommand \index{\#pragma callee\_saves}
15898
15899 \end_inset
15900
15901
15902 \begin_inset LatexCommand \index{function prologue}
15903
15904 \end_inset
15905
15906  function1[,function2[,function3...]] - The compiler by default uses a caller
15907  saves convention for register saving across function calls, however this
15908  can cause unnecessary register pushing & popping
15909 \begin_inset LatexCommand \index{push/pop}
15910
15911 \end_inset
15912
15913  when calling small functions from larger functions.
15914  This option can be used to switch off the register saving convention for
15915  the function names specified.
15916  The compiler will not save registers when calling these functions, extra
15917  code need to be manually inserted at the entry & exit for these functions
15918  to save & restore the registers used by these functions, this can SUBSTANTIALLY
15919  reduce code & improve run time performance of the generated code.
15920  In the future the compiler (with inter procedural analysis) may be able
15921  to determine the appropriate scheme to use for each function call.
15922  If -
15923 \begin_inset ERT
15924 status Collapsed
15925
15926 \layout Standard
15927
15928 \backslash
15929 /
15930 \end_inset
15931
15932 -callee-saves command line option is used, the function names specified
15933  in #pragma\SpecialChar ~
15934 callee_saves
15935 \begin_inset LatexCommand \index{\#pragma callee\_saves}
15936
15937 \end_inset
15938
15939  is appended to the list of functions specified in the command line.
15940 \layout Itemize
15941
15942 exclude
15943 \begin_inset LatexCommand \index{\#pragma exclude}
15944
15945 \end_inset
15946
15947  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
15948  of pairs of push/pop
15949 \begin_inset LatexCommand \index{push/pop}
15950
15951 \end_inset
15952
15953  instructions in
15954 \emph on
15955 I
15956 \emph default
15957 nterrupt
15958 \begin_inset LatexCommand \index{interrupt}
15959
15960 \end_inset
15961
15962
15963 \emph on
15964 S
15965 \emph default
15966 ervice
15967 \emph on
15968 R
15969 \emph default
15970 outines.
15971  The directive should be placed immediately before the ISR function definition
15972  and it affects ALL ISR functions following it.
15973  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
15974 exclude\SpecialChar ~
15975 none
15976 \begin_inset LatexCommand \index{\#pragma exclude}
15977
15978 \end_inset
15979
15980 .
15981  See also the related keyword _naked
15982 \begin_inset LatexCommand \index{\_naked}
15983
15984 \end_inset
15985
15986
15987 \begin_inset LatexCommand \index{\_\_naked}
15988
15989 \end_inset
15990
15991 .
15992 \layout Itemize
15993
15994 less_pedantic
15995 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
15996
15997 \end_inset
15998
15999  - the compiler will not warn you anymore for obvious mistakes, you'r on
16000  your own now ;-(
16001 \layout Itemize
16002
16003 disable_warning <nnnn>
16004 \begin_inset LatexCommand \index{\#pragma disable\_warning}
16005
16006 \end_inset
16007
16008  - the compiler will not warn you anymore about warning number <nnnn>.
16009 \layout Itemize
16010
16011 nogcse
16012 \begin_inset LatexCommand \index{\#pragma nogcse}
16013
16014 \end_inset
16015
16016  - will stop global common subexpression elimination.
16017 \layout Itemize
16018
16019 noinduction
16020 \begin_inset LatexCommand \index{\#pragma noinduction}
16021
16022 \end_inset
16023
16024  - will stop loop induction optimizations.
16025 \layout Itemize
16026
16027 noinvariant
16028 \begin_inset LatexCommand \index{\#pragma noinvariant}
16029
16030 \end_inset
16031
16032  - will not do loop invariant optimizations.
16033  For more details see Loop Invariants in section
16034 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
16035
16036 \end_inset
16037
16038 .
16039 \layout Itemize
16040
16041 noiv
16042 \begin_inset LatexCommand \index{\#pragma noiv}
16043
16044 \end_inset
16045
16046  - Do not generate interrupt
16047 \begin_inset LatexCommand \index{interrupt}
16048
16049 \end_inset
16050
16051  vector table entries for all ISR functions defined after the pragma.
16052  This is useful in cases where the interrupt vector table must be defined
16053  manually, or when there is a secondary, manually defined interrupt vector
16054  table (e.g.
16055  for the autovector feature of the Cypress EZ-USB FX2).
16056  More elegantly this can be achieved by obmitting the optional interrupt
16057  number after the interrupt keyword, see section
16058 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
16059
16060 \end_inset
16061
16062 \SpecialChar ~
16063 about interrupts.
16064 \layout Itemize
16065
16066 nojtbound
16067 \begin_inset LatexCommand \index{\#pragma nojtbound}
16068
16069 \end_inset
16070
16071  - will not generate code for boundary value checking, when switch statements
16072  are turned into jump-tables (dangerous).
16073  For more details see section
16074 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
16075
16076 \end_inset
16077
16078 .
16079 \layout Itemize
16080
16081 noloopreverse
16082 \begin_inset LatexCommand \index{\#pragma noloopreverse}
16083
16084 \end_inset
16085
16086  - Will not do loop reversal optimization
16087 \layout Itemize
16088
16089 nooverlay
16090 \begin_inset LatexCommand \index{\#pragma nooverlay}
16091
16092 \end_inset
16093
16094  - the compiler will not overlay the parameters and local variables of a
16095  function.
16096 \layout Itemize
16097
16098 stackauto
16099 \begin_inset LatexCommand \index{\#pragma stackauto}
16100
16101 \end_inset
16102
16103 - See option -
16104 \begin_inset ERT
16105 status Collapsed
16106
16107 \layout Standard
16108
16109 \backslash
16110 /
16111 \end_inset
16112
16113 -stack-auto
16114 \begin_inset LatexCommand \index{-\/-stack-auto}
16115
16116 \end_inset
16117
16118  and section
16119 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
16120
16121 \end_inset
16122
16123  Parameters and Local Variables.
16124 \layout Itemize
16125
16126 opt_code_speed
16127 \begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
16128
16129 \end_inset
16130
16131 - The compiler will optimize code generation towards fast code, possibly
16132  at the expense of code size.
16133 \layout Itemize
16134
16135 opt_code_size
16136 \begin_inset LatexCommand \index{\#pragma opt\_code\_size}
16137
16138 \end_inset
16139
16140 - The compiler will optimize code generation towards compact code, possibly
16141  at the expense of code speed.
16142 \layout Itemize
16143
16144 opt_code_balanced
16145 \begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
16146
16147 \end_inset
16148
16149 - The compiler will attempt to generate code that is both compact and fast,
16150  as long as meeting one goal is not a detriment to the other (this is the
16151  default).
16152
16153 \layout Itemize
16154
16155 std_sdcc89
16156 \begin_inset LatexCommand \index{\#pragma std\_sdcc89}
16157
16158 \end_inset
16159
16160 - Generally follow the C89 standard, but allow SDCC features that conflict
16161  with the standard (default).
16162 \layout Itemize
16163
16164 std_c89
16165 \begin_inset LatexCommand \index{\#pragma std\_c89}
16166
16167 \end_inset
16168
16169 - Follow the C89 standard and disable SDCC features that conflict with the
16170  standard.
16171 \layout Itemize
16172
16173 std_sdcc99
16174 \begin_inset LatexCommand \index{\#pragma std\_sdcc99}
16175
16176 \end_inset
16177
16178 - Generally follow the C99 standard, but allow SDCC features that conflict
16179  with the standard (incomplete support).
16180 \layout Itemize
16181
16182 std_c99
16183 \begin_inset LatexCommand \index{\#pragma std\_c99}
16184
16185 \end_inset
16186
16187 - Follow the C99 standard and disable SDCC features that conflict with the
16188  standard (incomplete support).
16189 \layout Itemize
16190
16191 codeseg <name>
16192 \begin_inset LatexCommand \index{\#pragma codeseg}
16193
16194 \end_inset
16195
16196 - Use this name (max.
16197  8 characters) for the code segment.
16198  See option -
16199 \begin_inset ERT
16200 status Collapsed
16201
16202 \layout Standard
16203
16204 \backslash
16205 /
16206 \end_inset
16207
16208 -codeseg.
16209 \layout Itemize
16210
16211 constseg <name>
16212 \begin_inset LatexCommand \index{\#pragma constseg}
16213
16214 \end_inset
16215
16216 - Use this name (max.
16217  8 characters) for the const segment.
16218  See option -
16219 \begin_inset ERT
16220 status Collapsed
16221
16222 \layout Standard
16223
16224 \backslash
16225 /
16226 \end_inset
16227
16228 -constseg.
16229 \layout Standard
16230
16231 SDCPP supports the following #pragma directives:
16232 \layout Itemize
16233
16234 preproc_asm
16235 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
16236
16237 \end_inset
16238
16239  (+ | -) - switch _asm _endasm block preprocessing on / off.
16240  Default is on.
16241  You use this prama to define multilines of assembly code.
16242  This will prevent the preprocessor from changing the formating required
16243  by assembly code.
16244  Below is an example on how to use this pragma.
16245 \layout Verse
16246
16247
16248 \family typewriter
16249 #pragma preproc_asm -
16250 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
16251
16252 \end_inset
16253
16254
16255 \newline
16256 #define MYDELAY _asm
16257 \newline
16258 \SpecialChar ~
16259 \SpecialChar ~
16260 \SpecialChar ~
16261 nop ;my assembly comment...
16262 \newline
16263 \SpecialChar ~
16264 \SpecialChar ~
16265 \SpecialChar ~
16266 nop
16267 \newline
16268 \SpecialChar ~
16269 \SpecialChar ~
16270 \SpecialChar ~
16271 nop
16272 \newline
16273 _endasm
16274 \newline
16275 #pragma preproc_asm +
16276 \newline
16277
16278 \newline
16279 void foo (void)
16280 \newline
16281 {
16282 \newline
16283 \SpecialChar ~
16284 \SpecialChar ~
16285 \SpecialChar ~
16286  ...
16287
16288 \newline
16289 \SpecialChar ~
16290 \SpecialChar ~
16291 \SpecialChar ~
16292  MYDELAY;
16293 \newline
16294 \SpecialChar ~
16295 \SpecialChar ~
16296 \SpecialChar ~
16297  ...
16298
16299 \newline
16300 }
16301 \newline
16302
16303 \layout Standard
16304
16305 The pragma's are intended to be used to turn-on or off certain optimizations
16306  which might cause the compiler to generate extra stack / data space to
16307  store compiler generated temporary variables.
16308  This usually happens in large functions.
16309  Pragma directives should be used as shown in the following example, they
16310  are used to control options & optimizations for a given function; pragmas
16311  should be placed before and/or after a function, placing pragma's inside
16312  a function body could have unpredictable results.
16313 \layout Verse
16314
16315
16316 \family typewriter
16317 #pragma save
16318 \begin_inset LatexCommand \index{\#pragma save}
16319
16320 \end_inset
16321
16322  \SpecialChar ~
16323 \SpecialChar ~
16324 \SpecialChar ~
16325 \SpecialChar ~
16326 \SpecialChar ~
16327 \SpecialChar ~
16328 \SpecialChar ~
16329 /* save the current settings */
16330 \newline
16331 #pragma nogcse
16332 \begin_inset LatexCommand \index{\#pragma nogcse}
16333
16334 \end_inset
16335
16336  \SpecialChar ~
16337 \SpecialChar ~
16338 \SpecialChar ~
16339 \SpecialChar ~
16340 \SpecialChar ~
16341 /* turnoff global subexpression elimination */
16342 \newline
16343 #pragma noinduction
16344 \begin_inset LatexCommand \index{\#pragma noinduction}
16345
16346 \end_inset
16347
16348  /* turn off induction optimizations */
16349 \newline
16350 int foo ()
16351 \newline
16352 {
16353 \newline
16354 \SpecialChar ~
16355  \SpecialChar ~
16356  ...
16357
16358 \newline
16359 \SpecialChar ~
16360  \SpecialChar ~
16361  /* large code */
16362 \newline
16363 \SpecialChar ~
16364  \SpecialChar ~
16365  ...
16366
16367 \newline
16368 }
16369 \newline
16370 #pragma restore
16371 \begin_inset LatexCommand \index{\#pragma restore}
16372
16373 \end_inset
16374
16375  /* turn the optimizations back on */
16376 \layout Standard
16377
16378 The compiler will generate a warning message when extra space is allocated.
16379  It is strongly recommended that the save and restore pragma's be used when
16380  changing options for a function.
16381 \newline
16382
16383 \newline
16384
16385 \newline
16386
16387 \layout Section
16388
16389 Defines Created by the Compiler
16390 \layout Standard
16391
16392 The compiler creates the following #defines
16393 \begin_inset LatexCommand \index{\#defines}
16394
16395 \end_inset
16396
16397
16398 \begin_inset LatexCommand \index{Defines created by the compiler}
16399
16400 \end_inset
16401
16402 :
16403 \newline
16404
16405 \layout Standard
16406
16407
16408 \begin_inset  Tabular
16409 <lyxtabular version="3" rows="11" columns="2">
16410 <features>
16411 <column alignment="left" valignment="top" leftline="true" width="3in">
16412 <column alignment="left" valignment="top" leftline="true" rightline="true" width="3in">
16413 <row topline="true" bottomline="true">
16414 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16415 \begin_inset Text
16416
16417 \layout Standard
16418
16419
16420 \series bold
16421 #define
16422 \end_inset
16423 </cell>
16424 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16425 \begin_inset Text
16426
16427 \layout Standard
16428
16429
16430 \series bold
16431 Description
16432 \end_inset
16433 </cell>
16434 </row>
16435 <row topline="true">
16436 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16437 \begin_inset Text
16438
16439 \layout Standard
16440
16441 SDCC
16442 \begin_inset LatexCommand \index{SDCC}
16443
16444 \end_inset
16445
16446
16447 \end_inset
16448 </cell>
16449 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16450 \begin_inset Text
16451
16452 \layout Standard
16453
16454 Always defined.
16455  Since version 2.5.6 the version number as an int (ex.
16456  256)
16457 \end_inset
16458 </cell>
16459 </row>
16460 <row topline="true">
16461 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16462 \begin_inset Text
16463
16464 \layout Standard
16465
16466 SDCC_mcs51
16467 \begin_inset LatexCommand \index{SDCC\_mcs51}
16468
16469 \end_inset
16470
16471  or SDCC_ds390
16472 \begin_inset LatexCommand \index{SDCC\_ds390}
16473
16474 \end_inset
16475
16476  or SDCC_z80
16477 \begin_inset LatexCommand \index{SDCC\_z80}
16478
16479 \end_inset
16480
16481 , etc.
16482 \end_inset
16483 </cell>
16484 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16485 \begin_inset Text
16486
16487 \layout Standard
16488
16489 depending on the model used (e.g.: -mds390)
16490 \end_inset
16491 </cell>
16492 </row>
16493 <row topline="true">
16494 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16495 \begin_inset Text
16496
16497 \layout Standard
16498
16499 __mcs51
16500 \begin_inset LatexCommand \index{\_\_mcs51}
16501
16502 \end_inset
16503
16504 , __ds390
16505 \begin_inset LatexCommand \index{\_\_ds390}
16506
16507 \end_inset
16508
16509 , __hc08
16510 \begin_inset LatexCommand \index{\_\_hc08}
16511
16512 \end_inset
16513
16514 , __z80
16515 \begin_inset LatexCommand \index{\_\_z80}
16516
16517 \end_inset
16518
16519 , etc
16520 \end_inset
16521 </cell>
16522 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16523 \begin_inset Text
16524
16525 \layout Standard
16526
16527 depending on the model used (e.g.
16528  -mz80)
16529 \end_inset
16530 </cell>
16531 </row>
16532 <row topline="true">
16533 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16534 \begin_inset Text
16535
16536 \layout Standard
16537
16538 SDCC_STACK_AUTO
16539 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
16540
16541 \end_inset
16542
16543
16544 \end_inset
16545 </cell>
16546 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16547 \begin_inset Text
16548
16549 \layout Standard
16550
16551 when
16552 \emph on
16553 -
16554 \begin_inset ERT
16555 status Collapsed
16556
16557 \layout Standard
16558
16559 \backslash
16560 /
16561 \end_inset
16562
16563 -stack-auto
16564 \emph default
16565  option is used
16566 \end_inset
16567 </cell>
16568 </row>
16569 <row topline="true">
16570 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16571 \begin_inset Text
16572
16573 \layout Standard
16574
16575 SDCC_MODEL_SMALL
16576 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
16577
16578 \end_inset
16579
16580
16581 \end_inset
16582 </cell>
16583 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16584 \begin_inset Text
16585
16586 \layout Standard
16587
16588 when
16589 \emph on
16590 -
16591 \begin_inset ERT
16592 status Collapsed
16593
16594 \layout Standard
16595
16596 \backslash
16597 /
16598 \end_inset
16599
16600 -model-small
16601 \emph default
16602  is used
16603 \end_inset
16604 </cell>
16605 </row>
16606 <row topline="true">
16607 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16608 \begin_inset Text
16609
16610 \layout Standard
16611
16612 SDCC_MODEL_MEDIUM
16613 \begin_inset LatexCommand \index{SDCC\_MODEL\_MEDIUM}
16614
16615 \end_inset
16616
16617
16618 \end_inset
16619 </cell>
16620 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16621 \begin_inset Text
16622
16623 \layout Standard
16624
16625 when
16626 \emph on
16627 -
16628 \begin_inset ERT
16629 status Collapsed
16630
16631 \layout Standard
16632
16633 \backslash
16634 /
16635 \end_inset
16636
16637 -model-medium
16638 \emph default
16639  is used
16640 \end_inset
16641 </cell>
16642 </row>
16643 <row topline="true">
16644 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16645 \begin_inset Text
16646
16647 \layout Standard
16648
16649 SDCC_MODEL_LARGE
16650 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
16651
16652 \end_inset
16653
16654
16655 \end_inset
16656 </cell>
16657 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16658 \begin_inset Text
16659
16660 \layout Standard
16661
16662 when
16663 \emph on
16664 -
16665 \begin_inset ERT
16666 status Collapsed
16667
16668 \layout Standard
16669
16670 \backslash
16671 /
16672 \end_inset
16673
16674 -model-large
16675 \emph default
16676  is used
16677 \end_inset
16678 </cell>
16679 </row>
16680 <row topline="true">
16681 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16682 \begin_inset Text
16683
16684 \layout Standard
16685
16686 SDCC_USE_XSTACK
16687 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
16688
16689 \end_inset
16690
16691
16692 \end_inset
16693 </cell>
16694 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16695 \begin_inset Text
16696
16697 \layout Standard
16698
16699 when
16700 \emph on
16701 -
16702 \begin_inset ERT
16703 status Collapsed
16704
16705 \layout Standard
16706
16707 \backslash
16708 /
16709 \end_inset
16710
16711 -xstack
16712 \emph default
16713  option is used
16714 \end_inset
16715 </cell>
16716 </row>
16717 <row topline="true">
16718 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16719 \begin_inset Text
16720
16721 \layout Standard
16722
16723 SDCC_STACK_TENBIT
16724 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
16725
16726 \end_inset
16727
16728
16729 \end_inset
16730 </cell>
16731 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16732 \begin_inset Text
16733
16734 \layout Standard
16735
16736 when
16737 \emph on
16738 -mds390
16739 \emph default
16740  is used
16741 \end_inset
16742 </cell>
16743 </row>
16744 <row topline="true" bottomline="true">
16745 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16746 \begin_inset Text
16747
16748 \layout Standard
16749
16750 SDCC_MODEL_FLAT24
16751 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
16752
16753 \end_inset
16754
16755
16756 \end_inset
16757 </cell>
16758 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16759 \begin_inset Text
16760
16761 \layout Standard
16762
16763 when
16764 \emph on
16765 -mds390
16766 \emph default
16767  is used
16768 \end_inset
16769 </cell>
16770 </row>
16771 </lyxtabular>
16772
16773 \end_inset
16774
16775
16776 \layout Chapter
16777
16778 Notes on supported Processors
16779 \layout Section
16780
16781 MCS51 variants
16782 \begin_inset LatexCommand \label{sub:MCS51-variants}
16783
16784 \end_inset
16785
16786
16787 \begin_inset LatexCommand \index{MCS51 variants}
16788
16789 \end_inset
16790
16791
16792 \layout Standard
16793
16794 MCS51 processors are available from many vendors and come in many different
16795  flavours.
16796  While they might differ considerably in respect to Special Function Registers
16797  the core MCS51 is usually not modified or is kept compatible.
16798
16799 \layout Subsection
16800
16801 pdata access by SFR
16802 \layout Standard
16803
16804 With the upcome of devices with internal xdata and flash memory devices
16805  using port P2
16806 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
16807
16808 \end_inset
16809
16810  as dedicated I/O port is becoming more popular.
16811  Switching the high byte for pdata
16812 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
16813
16814 \end_inset
16815
16816  access which was formerly done by port P2 is then achieved by a Special
16817  Function Register
16818 \begin_inset LatexCommand \index{sfr}
16819
16820 \end_inset
16821
16822 .
16823  In well-established MCS51 tradition the address of this
16824 \emph on
16825 sfr
16826 \emph default
16827  is where the chip designers decided to put it.
16828  Needless to say that they didn't agree on a common name either.
16829  So that the startup code can correctly initialize xdata variables, you
16830  should define an sfr with the name _XPAGE
16831 \family typewriter
16832
16833 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
16834
16835 \end_inset
16836
16837
16838 \family default
16839  at the appropriate location if the default, port P2, is not used for this.
16840  Some examples are:
16841 \layout Verse
16842
16843
16844 \family typewriter
16845 sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
16846 \layout Verse
16847
16848
16849 \family typewriter
16850 sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
16851 \layout Verse
16852
16853
16854 \family typewriter
16855 sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
16856 \layout Standard
16857
16858 For more exotic implementations further customizations may be needed.
16859  See section
16860 \begin_inset LatexCommand \ref{sub:Startup-Code}
16861
16862 \end_inset
16863
16864  for other possibilities.
16865 \layout Subsection
16866
16867 Other Features available by SFR
16868 \layout Standard
16869
16870 Some MCS51 variants offer features like Double DPTR
16871 \begin_inset LatexCommand \index{DPTR}
16872
16873 \end_inset
16874
16875 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
16876  These are currently not used for the MCS51 port.
16877  If you absolutely need them you can fall back to inline assembly or submit
16878  a patch to SDCC.
16879 \layout Section
16880
16881 DS400 port
16882 \layout Standard
16883
16884 The DS80C400 microcontroller has a rich set of peripherals.
16885  In its built-in ROM library it includes functions to access some of the
16886  features, among them is a TCP stack with IP4 and IP6 support.
16887  Library headers (currently in beta status) and other files are provided
16888  at
16889 \size footnotesize
16890
16891 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
16892
16893 \end_inset
16894
16895 .
16896
16897 \layout Section
16898
16899 The Z80 and gbz80 port
16900 \layout Standard
16901
16902 SDCC can target both the Zilog
16903 \begin_inset LatexCommand \index{Z80}
16904
16905 \end_inset
16906
16907  and the Nintendo Gameboy's Z80-like gbz80
16908 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
16909
16910 \end_inset
16911
16912 .
16913  The Z80 port is passed through the same
16914 \emph on
16915 regressions tests
16916 \begin_inset LatexCommand \index{Regression test}
16917
16918 \end_inset
16919
16920
16921 \emph default
16922  as the MCS51 and DS390 ports, so floating point support, support for long
16923  variables and bitfield support is fine.
16924  See mailing lists and forums about interrupt routines.
16925 \layout Standard
16926
16927 As always, the code is the authoritative reference - see z80/ralloc.c and
16928  z80/gen.c.
16929  The stack
16930 \begin_inset LatexCommand \index{stack}
16931
16932 \end_inset
16933
16934  frame is similar to that generated by the IAR Z80 compiler.
16935  IX is used as the base pointer, HL and IY are used as a temporary registers,
16936  and BC and DE are available for holding variables.
16937  Return values
16938 \begin_inset LatexCommand \index{return value}
16939
16940 \end_inset
16941
16942  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
16943  bytes).
16944  The gbz80 port use the same set of registers for the return values, but
16945  in a different order of significance: E (one byte), DE (two bytes), or
16946  HLDE (four bytes).
16947 \layout Section
16948
16949 The HC08 port
16950 \layout Standard
16951
16952 The port to the Motorola HC08
16953 \begin_inset LatexCommand \index{HC08}
16954
16955 \end_inset
16956
16957  family has been added in October 2003, and is still undergoing some basic
16958  development.
16959  The code generator is complete, but the register allocation is still quite
16960  unoptimized.
16961  Some of the SDCC's standard C library functions have embedded non-HC08
16962  inline assembly and so are not yet usable.
16963 \newline
16964
16965 \newline
16966
16967 \layout Section
16968
16969 The PIC14 port
16970 \layout Standard
16971
16972 The 14bit PIC
16973 \begin_inset LatexCommand \index{PIC14}
16974
16975 \end_inset
16976
16977  port still requires a major effort from the development community.
16978  However it can work for very simple code.
16979 \layout Subsection
16980
16981 C code and 14bit PIC code page
16982 \begin_inset LatexCommand \index{code page (pic14)}
16983
16984 \end_inset
16985
16986  and RAM banks
16987 \begin_inset LatexCommand \index{RAM bank (pic14)}
16988
16989 \end_inset
16990
16991
16992 \layout Standard
16993
16994 The linker organizes allocation for the code page and RAM banks.
16995  It does not have intimate knowledge of the code flow.
16996  It will put all the code section of a single asm file into a single code
16997  page.
16998  In order to make use of multiple code pages, separate asm files must be
16999  used.
17000  The compiler treats all functions of a single C file as being in the same
17001  code page unless it is non static.
17002  The compiler treats all local variables of a single C file as being in
17003  the same RAM bank unless it is an extern.
17004 \newline
17005
17006 \newline
17007 To get the best follow these guide lines:
17008 \layout Enumerate
17009
17010 make local functions static, as non static functions require code page selection
17011  overhead.
17012 \layout Enumerate
17013
17014 Make local variables static as extern variables require RAM bank selection
17015  overhead.
17016 \layout Enumerate
17017
17018 For devices that have multiple code pages it is more efficient to use the
17019  same number of files as pages, i.e.
17020  for the 16F877 use 4 separate files and i.e.
17021  for the 16F874 use 2 separate files.
17022  This way the linker can put the code for each file into different code
17023  pages and the compiler can allocate reusable variables more efficiently
17024  and there's less page selection overhead.
17025  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
17026  instruction set) use 'unsigned char' whereever possible instead of 'int'.
17027 \layout Subsection
17028
17029 Creating a device include file
17030 \layout Standard
17031
17032 For generating a device include file use the support perl script inc2h.pl
17033  kept in directory support/script.
17034 \layout Subsection
17035
17036 Interrupt code
17037 \layout Standard
17038
17039 For the interrupt function, use the keyword 'interrupt'
17040 \begin_inset LatexCommand \index{interrupt}
17041
17042 \end_inset
17043
17044  with level number of 0 (PIC14 only has 1 interrupt so this number is only
17045  there to avoid a syntax error - it ought to be fixed).
17046  E.g.:
17047 \layout Verse
17048
17049
17050 \family typewriter
17051 void Intr(void) interrupt 0
17052 \newline
17053 {
17054 \newline
17055 \SpecialChar ~
17056 \SpecialChar ~
17057 T0IF = 0; /* Clear timer interrupt */
17058 \newline
17059 }
17060 \layout Subsection
17061
17062 Linking and assembling
17063 \layout Standard
17064
17065 For assembling you can use either GPUTILS'
17066 \begin_inset LatexCommand \index{gputils (pic tools)}
17067
17068 \end_inset
17069
17070  gpasm.exe or MPLAB's mpasmwin.exe.
17071  GPUTILS is available from
17072 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
17073
17074 \end_inset
17075
17076 .
17077  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
17078  If you use MPLAB and an interrupt function then the linker script file
17079  vectors section will need to be enlarged to link with mplink.
17080 \newline
17081
17082 \newline
17083 Here is a
17084 \family typewriter
17085 Makefile
17086 \family default
17087  using GPUTILS:
17088 \layout Verse
17089
17090
17091 \family typewriter
17092 .c.o:
17093 \newline
17094 \SpecialChar ~
17095 \SpecialChar ~
17096 \SpecialChar ~
17097 \SpecialChar ~
17098 \SpecialChar ~
17099 \SpecialChar ~
17100 \SpecialChar ~
17101 \SpecialChar ~
17102 sdcc -S -V -mpic14 -p16F877 $<
17103 \newline
17104 \SpecialChar ~
17105 \SpecialChar ~
17106 \SpecialChar ~
17107 \SpecialChar ~
17108 \SpecialChar ~
17109 \SpecialChar ~
17110 \SpecialChar ~
17111 \SpecialChar ~
17112 gpasm -c $*.asm
17113 \newline
17114
17115 \newline
17116 $(PRJ).hex: $(OBJS)
17117 \newline
17118 \SpecialChar ~
17119 \SpecialChar ~
17120 \SpecialChar ~
17121 \SpecialChar ~
17122 \SpecialChar ~
17123 \SpecialChar ~
17124 \SpecialChar ~
17125 \SpecialChar ~
17126 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS) libsdcc.lib
17127 \layout Standard
17128
17129 Here is a
17130 \family typewriter
17131 Makefile
17132 \family default
17133  using MPLAB:
17134 \layout Verse
17135
17136
17137 \family typewriter
17138 .c.o:
17139 \newline
17140 \SpecialChar ~
17141 \SpecialChar ~
17142 \SpecialChar ~
17143 \SpecialChar ~
17144 \SpecialChar ~
17145 \SpecialChar ~
17146 \SpecialChar ~
17147 \SpecialChar ~
17148 sdcc -S -V -mpic14 -p16F877 $<
17149 \newline
17150 \SpecialChar ~
17151 \SpecialChar ~
17152 \SpecialChar ~
17153 \SpecialChar ~
17154 \SpecialChar ~
17155 \SpecialChar ~
17156 \SpecialChar ~
17157 \SpecialChar ~
17158 mpasmwin /q /o $*.asm
17159 \newline
17160
17161 \newline
17162 $(PRJ).hex: $(OBJS)
17163 \newline
17164 \SpecialChar ~
17165 \SpecialChar ~
17166 \SpecialChar ~
17167 \SpecialChar ~
17168 \SpecialChar ~
17169 \SpecialChar ~
17170 \SpecialChar ~
17171 \SpecialChar ~
17172 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS) libsdcc.lib
17173 \layout Standard
17174
17175 Please note that indentations within a
17176 \family typewriter
17177  Makefile
17178 \family default
17179  have to be done with a tabulator character.
17180 \layout Subsection
17181
17182 Command-line options
17183 \layout Standard
17184
17185 Besides the switches common to all SDCC backends, the PIC14 port accepts
17186  the following options (for an updated list see sdcc -
17187 \begin_inset ERT
17188 status Collapsed
17189
17190 \layout Standard
17191
17192 \backslash
17193 /
17194 \end_inset
17195
17196 -help):
17197 \layout List
17198 \labelwidthstring 00.00.0000
17199
17200 -
17201 \begin_inset ERT
17202 status Collapsed
17203
17204 \layout Standard
17205
17206 \backslash
17207 /
17208 \end_inset
17209
17210 -debug-extra emit debug info in assembly output
17211 \layout List
17212 \labelwidthstring 00.00.0000
17213
17214 -
17215 \begin_inset ERT
17216 status Collapsed
17217
17218 \layout Standard
17219
17220 \backslash
17221 /
17222 \end_inset
17223
17224 -no-pcode-opt disable (slightly faulty) optimization on pCode
17225 \layout Subsection
17226
17227 The library
17228 \layout Subsubsection
17229
17230 error: missing definition for symbol
17231 \begin_inset Quotes sld
17232 \end_inset
17233
17234 __gptrget1
17235 \begin_inset Quotes srd
17236 \end_inset
17237
17238
17239 \layout Standard
17240
17241 The PIC14 port uses library routines to provide more complex operations
17242  like multiplication, division/modulus and (generic) pointer dereferencing.
17243  In order to add these routines to your project, you must link with PIC14's
17244
17245 \family typewriter
17246 libsdcc.lib
17247 \family default
17248 .
17249  For single source file projects this is done automatically, more complex
17250  projects must add
17251 \family typewriter
17252 libsdcc.lib
17253 \family default
17254  to the linker's arguments.
17255  Make sure you also add an include path for the library (using the -I switch
17256  to the linker)!
17257 \layout Subsubsection
17258
17259 Processor mismatch in file
17260 \begin_inset Quotes sld
17261 \end_inset
17262
17263 XXX
17264 \begin_inset Quotes srd
17265 \end_inset
17266
17267 .
17268 \layout Standard
17269
17270 This warning can usually be ignored due to the very good compatibility amongst
17271  14 bit PIC devices.
17272 \layout Standard
17273
17274 You might also consider recompiling the library for your specific device
17275  by changing the ARCH=p16f877 (default target) entry in
17276 \family typewriter
17277 device/lib/pic/Makefile.in
17278 \family default
17279  and
17280 \family typewriter
17281 device/lib/pic/Makefile
17282 \family default
17283  to reflect your device.
17284  This might even improve performance for smaller devices as unneccesary
17285  BANKSELs migth be removed.
17286 \layout Subsection
17287
17288 Known bugs
17289 \layout Subsubsection
17290
17291 initialized data
17292 \layout Standard
17293
17294 Currently, data can only be initialized if it resides in the source file
17295  together with
17296 \emph on
17297 main()
17298 \emph default
17299 .
17300  Data in other source files will silently
17301 \series bold
17302 not
17303 \series default
17304  be initialized.
17305 \layout Section
17306
17307 The PIC16
17308 \begin_inset LatexCommand \index{PIC16}
17309
17310 \end_inset
17311
17312  port
17313 \layout Standard
17314
17315 The PIC16
17316 \begin_inset LatexCommand \index{PIC16}
17317
17318 \end_inset
17319
17320  port is the portion of SDCC that is responsible to produce code for the
17321  Microchip
17322 \begin_inset LatexCommand \index{Microchip}
17323
17324 \end_inset
17325
17326 (TM) microcontrollers with 16 bit core.
17327  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
17328  Currently supported devices are:
17329 \layout Standard
17330 \align center
17331
17332 \begin_inset  Tabular
17333 <lyxtabular version="3" rows="4" columns="6">
17334 <features>
17335 <column alignment="center" valignment="top" leftline="true" width="0">
17336 <column alignment="center" valignment="top" leftline="true" width="0">
17337 <column alignment="center" valignment="top" leftline="true" width="0">
17338 <column alignment="center" valignment="top" leftline="true" width="0">
17339 <column alignment="center" valignment="top" leftline="true" width="0">
17340 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17341 <row topline="true">
17342 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17343 \begin_inset Text
17344
17345 \layout Standard
17346
17347 18F242
17348 \end_inset
17349 </cell>
17350 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17351 \begin_inset Text
17352
17353 \layout Standard
17354
17355 18F248
17356 \end_inset
17357 </cell>
17358 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17359 \begin_inset Text
17360
17361 \layout Standard
17362
17363 18F252
17364 \end_inset
17365 </cell>
17366 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17367 \begin_inset Text
17368
17369 \layout Standard
17370
17371 18F258
17372 \end_inset
17373 </cell>
17374 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17375 \begin_inset Text
17376
17377 \layout Standard
17378
17379 18F442
17380 \end_inset
17381 </cell>
17382 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17383 \begin_inset Text
17384
17385 \layout Standard
17386
17387 18F448
17388 \end_inset
17389 </cell>
17390 </row>
17391 <row topline="true">
17392 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17393 \begin_inset Text
17394
17395 \layout Standard
17396
17397 18F452
17398 \end_inset
17399 </cell>
17400 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17401 \begin_inset Text
17402
17403 \layout Standard
17404
17405 18F458
17406 \end_inset
17407 </cell>
17408 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17409 \begin_inset Text
17410
17411 \layout Standard
17412
17413 18F1220
17414 \end_inset
17415 </cell>
17416 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17417 \begin_inset Text
17418
17419 \layout Standard
17420
17421 18F2220
17422 \end_inset
17423 </cell>
17424 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17425 \begin_inset Text
17426
17427 \layout Standard
17428
17429 18F2550
17430 \end_inset
17431 </cell>
17432 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17433 \begin_inset Text
17434
17435 \layout Standard
17436
17437 18F4331
17438 \end_inset
17439 </cell>
17440 </row>
17441 <row topline="true">
17442 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17443 \begin_inset Text
17444
17445 \layout Standard
17446
17447 18F4455
17448 \end_inset
17449 </cell>
17450 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17451 \begin_inset Text
17452
17453 \layout Standard
17454
17455 18F6520
17456 \end_inset
17457 </cell>
17458 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17459 \begin_inset Text
17460
17461 \layout Standard
17462
17463 18F6620
17464 \end_inset
17465 </cell>
17466 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17467 \begin_inset Text
17468
17469 \layout Standard
17470
17471 18F6680
17472 \end_inset
17473 </cell>
17474 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17475 \begin_inset Text
17476
17477 \layout Standard
17478
17479 18F6720
17480 \end_inset
17481 </cell>
17482 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17483 \begin_inset Text
17484
17485 \layout Standard
17486
17487 18F8520
17488 \end_inset
17489 </cell>
17490 </row>
17491 <row topline="true" bottomline="true">
17492 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17493 \begin_inset Text
17494
17495 \layout Standard
17496
17497 18F8620
17498 \end_inset
17499 </cell>
17500 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17501 \begin_inset Text
17502
17503 \layout Standard
17504
17505 18F8680
17506 \end_inset
17507 </cell>
17508 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17509 \begin_inset Text
17510
17511 \layout Standard
17512
17513 18F8720
17514 \end_inset
17515 </cell>
17516 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17517 \begin_inset Text
17518
17519 \layout Standard
17520
17521 \end_inset
17522 </cell>
17523 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17524 \begin_inset Text
17525
17526 \layout Standard
17527
17528 \end_inset
17529 </cell>
17530 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17531 \begin_inset Text
17532
17533 \layout Standard
17534
17535 \end_inset
17536 </cell>
17537 </row>
17538 </lyxtabular>
17539
17540 \end_inset
17541
17542
17543 \layout Subsection
17544
17545 Global Options
17546 \layout Standard
17547
17548 PIC16 port supports the standard command line arguments as supposed, with
17549  the exception of certain cases that will be mentioned in the following
17550  list:
17551 \layout List
17552 \labelwidthstring 00.00.0000
17553
17554 -
17555 \begin_inset ERT
17556 status Collapsed
17557
17558 \layout Standard
17559
17560 \backslash
17561 /
17562 \end_inset
17563
17564 -callee-saves See -
17565 \begin_inset ERT
17566 status Collapsed
17567
17568 \layout Standard
17569
17570 \backslash
17571 /
17572 \end_inset
17573
17574 -all-callee-saves
17575 \layout List
17576 \labelwidthstring 00.00.0000
17577
17578 -
17579 \begin_inset ERT
17580 status Collapsed
17581
17582 \layout Standard
17583
17584 \backslash
17585 /
17586 \end_inset
17587
17588 -all-callee-saves All function arguments are passed on stack by default.
17589
17590 \emph on
17591 There is no need to specify this in the command line.
17592 \layout List
17593 \labelwidthstring 00.00.0000
17594
17595 -
17596 \begin_inset ERT
17597 status Collapsed
17598
17599 \layout Standard
17600
17601 \backslash
17602 /
17603 \end_inset
17604
17605 -fommit-frame-pointer Frame pointer will be omitted when the function uses
17606  no local variables.
17607 \layout Subsection
17608
17609 Port Specific Options
17610 \begin_inset LatexCommand \index{Options PIC16}
17611
17612 \end_inset
17613
17614
17615 \layout Standard
17616
17617 The port specific options appear after the global options in the sdcc --help
17618  output.
17619 \layout Subsubsection
17620
17621 General Options
17622 \layout Standard
17623
17624 General options enable certain port features and optimizations.
17625 \layout List
17626 \labelwidthstring 00.00.0000
17627
17628 -
17629 \begin_inset ERT
17630 status Collapsed
17631
17632 \layout Standard
17633
17634 \backslash
17635 /
17636 \end_inset
17637
17638 -stack-model=[model] Used in conjuction with the command above.
17639  Defines the stack model to be used, valid stack models are :
17640 \begin_deeper
17641 \layout List
17642 \labelwidthstring 00.00.0000
17643
17644
17645 \emph on
17646 small
17647 \emph default
17648  Selects small stack model.
17649  8 bit stack and frame pointers.
17650  Supports 256 bytes stack size.
17651 \layout List
17652 \labelwidthstring 00.00.0000
17653
17654
17655 \emph on
17656 large
17657 \emph default
17658  Selects large stack model.
17659  16 bit stack and frame pointers.
17660  Supports 65536 bytes stack size.
17661 \end_deeper
17662 \layout List
17663 \labelwidthstring 00.00.0000
17664
17665 -
17666 \begin_inset ERT
17667 status Collapsed
17668
17669 \layout Standard
17670
17671 \backslash
17672 /
17673 \end_inset
17674
17675 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
17676  unitialized data variables with [kword].
17677  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
17678 \layout List
17679 \labelwidthstring 00.00.0000
17680
17681 -
17682 \begin_inset ERT
17683 status Collapsed
17684
17685 \layout Standard
17686
17687 \backslash
17688 /
17689 \end_inset
17690
17691 -ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
17692  Useful for bootloaders.
17693 \layout List
17694 \labelwidthstring 00.00.0000
17695
17696 -
17697 \begin_inset ERT
17698 status Collapsed
17699
17700 \layout Standard
17701
17702 \backslash
17703 /
17704 \end_inset
17705
17706 -asm= sets the full path and name of an external assembler to call.
17707 \layout List
17708 \labelwidthstring 00.00.0000
17709
17710 -
17711 \begin_inset ERT
17712 status Collapsed
17713
17714 \layout Standard
17715
17716 \backslash
17717 /
17718 \end_inset
17719
17720 -link= sets the full path and name of an external linker to call.
17721 \layout List
17722 \labelwidthstring 00.00.0000
17723
17724 -
17725 \begin_inset ERT
17726 status Collapsed
17727
17728 \layout Standard
17729
17730 \backslash
17731 /
17732 \end_inset
17733
17734 -mplab-comp MPLAB compatibility option.
17735  Currently only suppresses special gpasm directives.
17736 \layout Subsubsection
17737
17738 Optimization Options
17739 \layout List
17740 \labelwidthstring 00.00.0000
17741
17742 -
17743 \begin_inset ERT
17744 status Collapsed
17745
17746 \layout Standard
17747
17748 \backslash
17749 /
17750 \end_inset
17751
17752 -optimize-goto Try to use (conditional) BRA instead of GOTO
17753 \layout List
17754 \labelwidthstring 00.00.0000
17755
17756 -
17757 \begin_inset ERT
17758 status Collapsed
17759
17760 \layout Standard
17761
17762 \backslash
17763 /
17764 \end_inset
17765
17766 -optimize-cmp Try to optimize some compares.
17767 \layout List
17768 \labelwidthstring 00.00.0000
17769
17770 -
17771 \begin_inset ERT
17772 status Collapsed
17773
17774 \layout Standard
17775
17776 \backslash
17777 /
17778 \end_inset
17779
17780 -optimize-df Analyze the dataflow of the generated code and improve it.
17781 \layout List
17782 \labelwidthstring 00.00.0000
17783
17784 -
17785 \begin_inset ERT
17786 status Collapsed
17787
17788 \layout Standard
17789
17790 \backslash
17791 /
17792 \end_inset
17793
17794 -obanksel=nn Set optimization level for inserting BANKSELs.
17795 \newline
17796
17797 \begin_deeper
17798 \layout List
17799 \labelwidthstring 00.00.0000
17800
17801 0 no optimization
17802 \layout List
17803 \labelwidthstring 00.00.0000
17804
17805 1 checks previous used register and if it is the same then does not emit
17806  BANKSEL, accounts only for labels.
17807 \layout List
17808 \labelwidthstring 00.00.0000
17809
17810 2 tries to check the location of (even different) symbols and removes BANKSELs
17811  if they are in the same bank.
17812
17813 \newline
17814
17815 \emph on
17816 Important: There might be problems if the linker script has data sections
17817  across bank borders!
17818 \end_deeper
17819 \layout Subsubsection
17820
17821 Linking Options
17822 \layout List
17823 \labelwidthstring 00.00.0000
17824
17825 -
17826 \begin_inset ERT
17827 status Collapsed
17828
17829 \layout Standard
17830
17831 \backslash
17832 /
17833 \end_inset
17834
17835 -nodefaultlibs do not link default libraries when linking
17836 \layout List
17837 \labelwidthstring 00.00.0000
17838
17839 -
17840 \begin_inset ERT
17841 status Collapsed
17842
17843 \layout Standard
17844
17845 \backslash
17846 /
17847 \end_inset
17848
17849 -no-crt Don't link the default run-time modules
17850 \layout List
17851 \labelwidthstring 00.00.0000
17852
17853 -
17854 \begin_inset ERT
17855 status Collapsed
17856
17857 \layout Standard
17858
17859 \backslash
17860 /
17861 \end_inset
17862
17863 -use-crt= Use a custom run-time module instead of the defaults.
17864 \layout Subsubsection
17865
17866 Debugging Options
17867 \layout Standard
17868
17869 Debugging options enable extra debugging information in the output files.
17870 \layout List
17871 \labelwidthstring 00.00.0000
17872
17873 -
17874 \begin_inset ERT
17875 status Collapsed
17876
17877 \layout Standard
17878
17879 \backslash
17880 /
17881 \end_inset
17882
17883 -debug-xtra Similar to -
17884 \begin_inset ERT
17885 status Collapsed
17886
17887 \layout Standard
17888
17889 \backslash
17890 /
17891 \end_inset
17892
17893 -debug
17894 \begin_inset LatexCommand \index{-\/-debug}
17895
17896 \end_inset
17897
17898 , but dumps more information.
17899 \layout List
17900 \labelwidthstring 00.00.0000
17901
17902 -
17903 \begin_inset ERT
17904 status Collapsed
17905
17906 \layout Standard
17907
17908 \backslash
17909 /
17910 \end_inset
17911
17912 -debug-ralloc Force register allocator to dump <source>.d file with debugging
17913  information.
17914  <source> is the name of the file compiled.
17915 \layout List
17916 \labelwidthstring 00.00.0000
17917
17918 -
17919 \begin_inset ERT
17920 status Collapsed
17921
17922 \layout Standard
17923
17924 \backslash
17925 /
17926 \end_inset
17927
17928 -pcode-verbose Enable pcode debugging information in translation.
17929 \layout List
17930 \labelwidthstring 00.00.0000
17931
17932 -
17933 \begin_inset ERT
17934 status Collapsed
17935
17936 \layout Standard
17937
17938 \backslash
17939 /
17940 \end_inset
17941
17942 -denable-peeps Force the usage of peepholes.
17943  Use with care.
17944 \layout List
17945 \labelwidthstring 00.00.0000
17946
17947 -
17948 \begin_inset ERT
17949 status Collapsed
17950
17951 \layout Standard
17952
17953 \backslash
17954 /
17955 \end_inset
17956
17957 -gstack Trace push/pops for stack pointer overflow
17958 \layout List
17959 \labelwidthstring 00.00.0000
17960
17961 -
17962 \begin_inset ERT
17963 status Collapsed
17964
17965 \layout Standard
17966
17967 \backslash
17968 /
17969 \end_inset
17970
17971 -call-tree dump call tree in .calltree file
17972 \layout Subsection
17973
17974 Enviromental Variables
17975 \layout Standard
17976
17977 There is a number of enviromental variables that can be used when running
17978  SDCC to enable certain optimizations or force a specific program behaviour.
17979  these variables are primarily for debugging purposes so they can be enabled/dis
17980 abled at will.
17981 \layout Standard
17982
17983 Currently there is only two such variables available:
17984 \layout List
17985 \labelwidthstring 00.00.0000
17986
17987 OPTIMIZE_BITFIELD_POINTER_GET when this variable exists reading of structure
17988  bitfields is optimized by directly loading FSR0 with the address of the
17989  bitfield structure.
17990  Normally SDCC will cast the bitfield structure to a bitfield pointer and
17991  then load FSR0.
17992  This step saves data ram and code space for functions that perform heavy
17993  use of bitfields.
17994  (ie.
17995  80 bytes of code space are saved when compiling malloc.c with this option).
17996
17997 \layout List
17998 \labelwidthstring 00.00.0000
17999
18000 NO_REG_OPT do not perform pCode registers optimization.
18001  This should be used for debugging purposes.
18002  In some where bugs in the pcode optimizer are found, users can benefit
18003  from temporarily disabling the optimizer until the bug is fixed.
18004 \layout Subsection
18005
18006 Preprocessor Macros
18007 \layout Standard
18008
18009 PIC16 port defines the following preprocessor macros while translating a
18010  source.
18011 \layout Standard
18012 \align center
18013
18014 \begin_inset  Tabular
18015 <lyxtabular version="3" rows="6" columns="2">
18016 <features>
18017 <column alignment="center" valignment="top" leftline="true" width="0">
18018 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18019 <row topline="true" bottomline="true">
18020 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18021 \begin_inset Text
18022
18023 \layout Standard
18024
18025 Macro
18026 \end_inset
18027 </cell>
18028 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18029 \begin_inset Text
18030
18031 \layout Standard
18032
18033 Description
18034 \end_inset
18035 </cell>
18036 </row>
18037 <row topline="true">
18038 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18039 \begin_inset Text
18040
18041 \layout Standard
18042
18043 SDCC_pic16
18044 \end_inset
18045 </cell>
18046 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18047 \begin_inset Text
18048
18049 \layout Standard
18050
18051 Port identification
18052 \end_inset
18053 </cell>
18054 </row>
18055 <row topline="true">
18056 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18057 \begin_inset Text
18058
18059 \layout Standard
18060
18061 _
18062 \begin_inset ERT
18063 status Collapsed
18064
18065 \layout Standard
18066
18067 \backslash
18068 /
18069 \end_inset
18070
18071 _pic16
18072 \end_inset
18073 </cell>
18074 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18075 \begin_inset Text
18076
18077 \layout Standard
18078
18079 Port identification (same as above)
18080 \end_inset
18081 </cell>
18082 </row>
18083 <row topline="true">
18084 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18085 \begin_inset Text
18086
18087 \layout Standard
18088
18089 pic18fxxxx
18090 \end_inset
18091 </cell>
18092 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18093 \begin_inset Text
18094
18095 \layout Standard
18096
18097 MCU Identification.
18098
18099 \emph on
18100 xxxx
18101 \emph default
18102  is the microcontrol identification number, i.e.
18103  452, 6620, etc
18104 \end_inset
18105 </cell>
18106 </row>
18107 <row topline="true">
18108 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18109 \begin_inset Text
18110
18111 \layout Standard
18112
18113 _
18114 \begin_inset ERT
18115 status Collapsed
18116
18117 \layout Standard
18118
18119 \backslash
18120 /
18121 \end_inset
18122
18123 _18Fxxxx
18124 \end_inset
18125 </cell>
18126 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18127 \begin_inset Text
18128
18129 \layout Standard
18130
18131 MCU Identification (same as above)
18132 \end_inset
18133 </cell>
18134 </row>
18135 <row topline="true" bottomline="true">
18136 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18137 \begin_inset Text
18138
18139 \layout Standard
18140
18141 STACK_MODEL_nnn
18142 \end_inset
18143 </cell>
18144 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18145 \begin_inset Text
18146
18147 \layout Standard
18148
18149 nnn = SMALL or LARGE respectively according to the stack model used
18150 \end_inset
18151 </cell>
18152 </row>
18153 </lyxtabular>
18154
18155 \end_inset
18156
18157
18158 \layout Standard
18159
18160 In addition the following macros are defined when calling assembler:
18161 \layout Standard
18162 \align center
18163
18164 \begin_inset  Tabular
18165 <lyxtabular version="3" rows="4" columns="2">
18166 <features>
18167 <column alignment="center" valignment="top" leftline="true" width="0">
18168 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18169 <row topline="true" bottomline="true">
18170 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18171 \begin_inset Text
18172
18173 \layout Standard
18174
18175 Macro
18176 \end_inset
18177 </cell>
18178 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18179 \begin_inset Text
18180
18181 \layout Standard
18182
18183 Description
18184 \end_inset
18185 </cell>
18186 </row>
18187 <row topline="true">
18188 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18189 \begin_inset Text
18190
18191 \layout Standard
18192
18193 __18Fxxxx
18194 \end_inset
18195 </cell>
18196 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18197 \begin_inset Text
18198
18199 \layout Standard
18200
18201 MCU Identification.
18202
18203 \emph on
18204 xxxx
18205 \emph default
18206  is the microcontrol identification number, i.e.
18207  452, 6620, etc
18208 \end_inset
18209 </cell>
18210 </row>
18211 <row topline="true">
18212 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18213 \begin_inset Text
18214
18215 \layout Standard
18216
18217 SDCC_MODEL_nnn
18218 \end_inset
18219 </cell>
18220 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18221 \begin_inset Text
18222
18223 \layout Standard
18224
18225 nnn = SMALL or LARGE respectively according to the memory model used for
18226  SDCC
18227 \end_inset
18228 </cell>
18229 </row>
18230 <row topline="true" bottomline="true">
18231 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18232 \begin_inset Text
18233
18234 \layout Standard
18235
18236 STACK_MODEL_nnn
18237 \end_inset
18238 </cell>
18239 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18240 \begin_inset Text
18241
18242 \layout Standard
18243
18244 nnn = SMALL or LARGE respectively according to the stack model used
18245 \end_inset
18246 </cell>
18247 </row>
18248 </lyxtabular>
18249
18250 \end_inset
18251
18252
18253 \layout Subsection
18254
18255 Directories
18256 \layout Standard
18257
18258 PIC16
18259 \begin_inset LatexCommand \index{PIC16}
18260
18261 \end_inset
18262
18263  port uses the following directories for searching header files and libraries.
18264 \layout Standard
18265 \align center
18266
18267 \begin_inset  Tabular
18268 <lyxtabular version="3" rows="3" columns="4">
18269 <features>
18270 <column alignment="center" valignment="top" leftline="true" width="0">
18271 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18272 <column alignment="center" valignment="top" width="0">
18273 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18274 <row topline="true" bottomline="true">
18275 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18276 \begin_inset Text
18277
18278 \layout Standard
18279
18280 Directory
18281 \end_inset
18282 </cell>
18283 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18284 \begin_inset Text
18285
18286 \layout Standard
18287
18288 Description
18289 \end_inset
18290 </cell>
18291 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18292 \begin_inset Text
18293
18294 \layout Standard
18295
18296 Target
18297 \end_inset
18298 </cell>
18299 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18300 \begin_inset Text
18301
18302 \layout Standard
18303
18304 Command prefix
18305 \end_inset
18306 </cell>
18307 </row>
18308 <row topline="true">
18309 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18310 \begin_inset Text
18311
18312 \layout Standard
18313
18314 PREFIX/sdcc/include/pic16
18315 \end_inset
18316 </cell>
18317 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18318 \begin_inset Text
18319
18320 \layout Standard
18321
18322 PIC16 specific headers
18323 \end_inset
18324 </cell>
18325 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18326 \begin_inset Text
18327
18328 \layout Standard
18329
18330 Compiler
18331 \end_inset
18332 </cell>
18333 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18334 \begin_inset Text
18335
18336 \layout Standard
18337
18338 -I
18339 \end_inset
18340 </cell>
18341 </row>
18342 <row topline="true" bottomline="true">
18343 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18344 \begin_inset Text
18345
18346 \layout Standard
18347
18348 PREFIX/sdcc/lib/pic16
18349 \end_inset
18350 </cell>
18351 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18352 \begin_inset Text
18353
18354 \layout Standard
18355
18356 PIC16 specific libraries
18357 \end_inset
18358 </cell>
18359 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18360 \begin_inset Text
18361
18362 \layout Standard
18363
18364 Linker
18365 \end_inset
18366 </cell>
18367 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18368 \begin_inset Text
18369
18370 \layout Standard
18371
18372 -L
18373 \end_inset
18374 </cell>
18375 </row>
18376 </lyxtabular>
18377
18378 \end_inset
18379
18380
18381 \layout Subsection
18382
18383 Pragmas
18384 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
18385
18386 \end_inset
18387
18388
18389 \layout Standard
18390
18391 PIC16 port currently supports the following pragmas:
18392 \layout List
18393 \labelwidthstring 00.00.0000
18394
18395 stack pragma stack forces the code generator to initialize the stack & frame
18396  pointers at a specific address.
18397  This is an adhoc solution for cases where no STACK directive is available
18398  in the linker script or gplink is not instructed to create a stack section.
18399 \newline
18400 The stack pragma should be used only once in a project.
18401  Multiple pragmas may result in indeterminate behaviour of the program.
18402 \begin_inset Foot
18403 collapsed false
18404
18405 \layout Standard
18406
18407 The old format (ie.
18408  #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
18409  cross page boundaries (or even exceed the available data RAM) and crash
18410  the program.
18411  Make sure that stack does not cross page boundaries when using the SMALL
18412  stack model.
18413 \end_inset
18414
18415
18416 \newline
18417 The format is as follows:
18418 \layout LyX-Code
18419
18420 #pragma stack bottom_address [stack_size]
18421 \layout Standard
18422
18423
18424 \emph on
18425 bottom_address
18426 \emph default
18427  is the lower bound of the stack section.
18428  The stack pointer initially will point at address (bottom_address+stack_size-1).
18429 \layout LyX-Code
18430
18431 Example:
18432 \layout LyX-Code
18433
18434 \layout LyX-Code
18435
18436 /* initializes stack of 100 bytes at RAM address 0x200 */
18437 \layout LyX-Code
18438
18439 #pragma stack 0x200 100
18440 \layout Standard
18441
18442 If the stack_size field is omitted then a stack is created with the default
18443  size of 64.
18444  This size might be enough for most programs, but its not enough for operations
18445  with deep function nesting or excessive stack usage.
18446 \layout List
18447 \labelwidthstring 00.00.0000
18448
18449 wparam
18450 \emph on
18451 This pragma is deprecated.
18452  Its use will cause a warning message to be issued.
18453 \emph default
18454
18455 \newline
18456
18457 \layout List
18458 \labelwidthstring 00.00.0000
18459
18460 code place a function symbol at static FLASH address
18461 \layout LyX-Code
18462
18463 Example:
18464 \layout LyX-Code
18465
18466 \layout LyX-Code
18467
18468 /* place function test_func at 0x4000 */
18469 \layout LyX-Code
18470
18471 #pragma code test_func 0x4000
18472 \layout LyX-Code
18473
18474 \layout List
18475 \labelwidthstring 00.00.0000
18476
18477 library instructs the linker to use a library module.
18478 \newline
18479 Usage:
18480 \layout LyX-Code
18481
18482 #pragma library module_name
18483 \layout Standard
18484
18485
18486 \emph on
18487 module_name
18488 \emph default
18489  can be any library or object file (including its path).
18490  Note that there are four reserved keywords which have special meaning.
18491  These are:
18492 \layout Standard
18493 \align center
18494
18495 \begin_inset  Tabular
18496 <lyxtabular version="3" rows="6" columns="3">
18497 <features>
18498 <column alignment="center" valignment="top" leftline="true" width="0">
18499 <column alignment="block" valignment="top" leftline="true" width="20page%">
18500 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
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 Keyword
18508 \end_inset
18509 </cell>
18510 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18511 \begin_inset Text
18512
18513 \layout Standard
18514
18515 Description
18516 \end_inset
18517 </cell>
18518 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18519 \begin_inset Text
18520
18521 \layout Standard
18522
18523 Module to link
18524 \end_inset
18525 </cell>
18526 </row>
18527 <row topline="true">
18528 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18529 \begin_inset Text
18530
18531 \layout Standard
18532
18533
18534 \series bold
18535 ignore
18536 \end_inset
18537 </cell>
18538 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18539 \begin_inset Text
18540
18541 \layout Standard
18542
18543 ignore all library pragmas
18544 \end_inset
18545 </cell>
18546 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18547 \begin_inset Text
18548
18549 \layout Standard
18550
18551
18552 \emph on
18553 (none)
18554 \end_inset
18555 </cell>
18556 </row>
18557 <row topline="true">
18558 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18559 \begin_inset Text
18560
18561 \layout Standard
18562
18563
18564 \series bold
18565 c
18566 \end_inset
18567 </cell>
18568 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18569 \begin_inset Text
18570
18571 \layout Standard
18572
18573 link the C library
18574 \end_inset
18575 </cell>
18576 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18577 \begin_inset Text
18578
18579 \layout Standard
18580
18581
18582 \emph on
18583 libc18f
18584 \emph default
18585 .lib
18586 \end_inset
18587 </cell>
18588 </row>
18589 <row topline="true">
18590 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18591 \begin_inset Text
18592
18593 \layout Standard
18594
18595
18596 \series bold
18597 math
18598 \end_inset
18599 </cell>
18600 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18601 \begin_inset Text
18602
18603 \layout Standard
18604
18605 link the Math libarary
18606 \end_inset
18607 </cell>
18608 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18609 \begin_inset Text
18610
18611 \layout Standard
18612
18613
18614 \emph on
18615 libm18f
18616 \emph default
18617 .lib
18618 \end_inset
18619 </cell>
18620 </row>
18621 <row topline="true">
18622 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18623 \begin_inset Text
18624
18625 \layout Standard
18626
18627
18628 \series bold
18629 io
18630 \end_inset
18631 </cell>
18632 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18633 \begin_inset Text
18634
18635 \layout Standard
18636
18637 link the I/O library
18638 \end_inset
18639 </cell>
18640 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18641 \begin_inset Text
18642
18643 \layout Standard
18644
18645
18646 \emph on
18647 libio18f*
18648 \emph default
18649 .lib
18650 \end_inset
18651 </cell>
18652 </row>
18653 <row topline="true" bottomline="true">
18654 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18655 \begin_inset Text
18656
18657 \layout Standard
18658
18659
18660 \series bold
18661 debug
18662 \end_inset
18663 </cell>
18664 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18665 \begin_inset Text
18666
18667 \layout Standard
18668
18669 link the debug library
18670 \end_inset
18671 </cell>
18672 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18673 \begin_inset Text
18674
18675 \layout Standard
18676
18677
18678 \emph on
18679 libdebug
18680 \emph default
18681 .lib
18682 \end_inset
18683 </cell>
18684 </row>
18685 </lyxtabular>
18686
18687 \end_inset
18688
18689
18690 \newline
18691 * is the device number, i.e.
18692  452 for PIC18F452 MCU.
18693 \layout Standard
18694
18695 This feature allows for linking with specific libraries withoug having to
18696  explicit name them in the command line.
18697  Note that the
18698 \noun on
18699 ignore
18700 \noun default
18701  keyword will reject all modules specified by the library pragma.
18702 \layout List
18703 \labelwidthstring 00.00.0000
18704
18705 udata pragma udata instructs the compiler to emit code so that linker will
18706  place a variable at a specific memory bank
18707 \layout LyX-Code
18708
18709 Example:
18710 \layout LyX-Code
18711
18712 \layout LyX-Code
18713
18714 /* places variable foo at bank2 */
18715 \layout LyX-Code
18716
18717 #pragma udata bank2 foo
18718 \layout LyX-Code
18719
18720 char foo;
18721 \layout Standard
18722
18723 In order for this pragma to work extra SECTION directives should be added
18724  in the .lkr script.
18725  In the following example a sample .lkr file is shown:
18726 \layout LyX-Code
18727
18728 \layout LyX-Code
18729
18730 // Sample linker script for the PIC18F452 processor
18731 \layout LyX-Code
18732
18733 LIBPATH .
18734 \layout LyX-Code
18735
18736 CODEPAGE   NAME=vectors    START=0x0            END=0x29           PROTECTED
18737 \layout LyX-Code
18738
18739 CODEPAGE   NAME=page       START=0x2A           END=0x7FFF
18740 \layout LyX-Code
18741
18742 CODEPAGE   NAME=idlocs     START=0x200000       END=0x200007       PROTECTED
18743 \layout LyX-Code
18744
18745 CODEPAGE   NAME=config     START=0x300000       END=0x30000D       PROTECTED
18746 \layout LyX-Code
18747
18748 CODEPAGE   NAME=devid      START=0x3FFFFE       END=0x3FFFFF       PROTECTED
18749 \layout LyX-Code
18750
18751 CODEPAGE   NAME=eedata     START=0xF00000       END=0xF000FF       PROTECTED
18752 \layout LyX-Code
18753
18754 ACCESSBANK NAME=accessram  START=0x0            END=0x7F
18755 \layout LyX-Code
18756
18757 \layout LyX-Code
18758
18759 DATABANK   NAME=gpr0       START=0x80           END=0xFF
18760 \layout LyX-Code
18761
18762 DATABANK   NAME=gpr1       START=0x100          END=0x1FF
18763 \layout LyX-Code
18764
18765 DATABANK   NAME=gpr2       START=0x200          END=0x2FF
18766 \layout LyX-Code
18767
18768 DATABANK   NAME=gpr3       START=0x300          END=0x3FF
18769 \layout LyX-Code
18770
18771 DATABANK   NAME=gpr4       START=0x400          END=0x4FF
18772 \layout LyX-Code
18773
18774 DATABANK   NAME=gpr5       START=0x500          END=0x5FF
18775 \layout LyX-Code
18776
18777 ACCESSBANK NAME=accesssfr  START=0xF80          END=0xFFF          PROTECTED
18778 \layout LyX-Code
18779
18780 \layout LyX-Code
18781
18782 SECTION    NAME=CONFIG     ROM=config
18783 \layout LyX-Code
18784
18785 \layout LyX-Code
18786
18787 SECTION    NAME=bank0      RAM=gpr0       # these SECTION directives
18788 \layout LyX-Code
18789
18790 SECTION    NAME=bank1      RAM=gpr1       # should be added to link
18791 \layout LyX-Code
18792
18793 SECTION    NAME=bank2      RAM=gpr2       # section name 'bank?' with
18794 \layout LyX-Code
18795
18796 SECTION    NAME=bank3      RAM=gpr3       # a specific DATABANK name
18797 \layout LyX-Code
18798
18799 SECTION    NAME=bank4      RAM=gpr4
18800 \layout LyX-Code
18801
18802 SECTION    NAME=bank5      RAM=gpr5
18803 \layout Standard
18804
18805 The linker will recognise the section name set in the pragma statement and
18806  will position the variable at the memory bank set with the RAM field at
18807  the SECTION line in the linker script file.
18808 \layout Subsection
18809
18810 Header Files
18811 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
18812
18813 \end_inset
18814
18815
18816 \layout Standard
18817
18818 There is one main header file that can be included to the source files using
18819  the pic16 port.
18820  That file is the
18821 \series bold
18822 pic18fregs.h
18823 \series default
18824 .
18825  This header file contains the definitions for the processor special registers,
18826  so it is necessary if the source accesses them.
18827  It can be included by adding the following line in the beginning of the
18828  file:
18829 \layout LyX-Code
18830
18831 #include <pic18fregs.h>
18832 \layout Standard
18833
18834 The specific microcontroller is selected within the pic18fregs.h automatically,
18835  so the same source can be used with a variety of devices.
18836 \layout Subsection
18837
18838 Libraries
18839 \layout Standard
18840
18841 The libraries that PIC16
18842 \begin_inset LatexCommand \index{PIC16}
18843
18844 \end_inset
18845
18846  port depends on are the microcontroller device libraries which contain
18847  the symbol definitions for the microcontroller special function registers.
18848  These libraries have the format pic18fxxxx.lib, where
18849 \emph on
18850 xxxx
18851 \emph default
18852  is the microcontroller identification number.
18853  The specific library is selected automatically by the compiler at link
18854  stage according to the selected device.
18855 \layout Standard
18856
18857 Libraries are created with gplib which is part of the gputils package
18858 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
18859
18860 \end_inset
18861
18862 .
18863 \layout Subsubsection*
18864
18865 Building the libraries
18866 \layout Standard
18867
18868 Before using SDCC/pic16 there are some libraries that need to be compiled.
18869  This process is not done automatically by SDCC since not all users use
18870  SDCC for pic16 projects.
18871  So each user should compile the libraries separately.
18872 \layout Standard
18873
18874 The steps to compile the pic16 libraries under Linux are:
18875 \layout LyX-Code
18876
18877 cd device/lib/pic16
18878 \layout LyX-Code
18879
18880 ./configure
18881 \layout LyX-Code
18882
18883 make
18884 \layout LyX-Code
18885
18886 cd ..
18887 \layout LyX-Code
18888
18889 make model-pic16
18890 \layout LyX-Code
18891
18892 su -c 'make install'     # install the libraries, you need the root password
18893 \layout Standard
18894
18895 If you need to install the headers too, do:
18896 \layout LyX-Code
18897
18898 cd device/include
18899 \layout LyX-Code
18900
18901 su -c 'make install'     # install the headers, you need the root password
18902 \layout Standard
18903
18904 There exist a special target to build the I/O libraries.
18905  This target is not automatically build because it will build the I/O library
18906  for
18907 \emph on
18908 every
18909 \emph default
18910  supported device.
18911  This way building will take quite a lot of time.
18912  Users are advised to edit the
18913 \series bold
18914 device/lib/pic16/pics.build
18915 \series default
18916  file and then execute:
18917 \layout LyX-Code
18918
18919 make lib-io
18920 \layout Subsection
18921
18922 Memory Models
18923 \layout Standard
18924
18925 The following memory models are supported by the PIC16 port:
18926 \layout Itemize
18927
18928 small model
18929 \layout Itemize
18930
18931 large model
18932 \layout Standard
18933
18934 Memory model affects the default size of pointers within the source.
18935  The sizes are shown in the next table:
18936 \layout Standard
18937 \align center
18938
18939 \begin_inset  Tabular
18940 <lyxtabular version="3" rows="3" columns="3">
18941 <features>
18942 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18943 <column alignment="center" valignment="top" leftline="true" width="0">
18944 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18945 <row topline="true" bottomline="true">
18946 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18947 \begin_inset Text
18948
18949 \layout Standard
18950
18951 Pointer sizes according to memory model
18952 \end_inset
18953 </cell>
18954 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18955 \begin_inset Text
18956
18957 \layout Standard
18958
18959 small model
18960 \end_inset
18961 </cell>
18962 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18963 \begin_inset Text
18964
18965 \layout Standard
18966
18967 large model
18968 \end_inset
18969 </cell>
18970 </row>
18971 <row topline="true" bottomline="true">
18972 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18973 \begin_inset Text
18974
18975 \layout Standard
18976
18977 code pointers
18978 \end_inset
18979 </cell>
18980 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18981 \begin_inset Text
18982
18983 \layout Standard
18984
18985 16-bits
18986 \end_inset
18987 </cell>
18988 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18989 \begin_inset Text
18990
18991 \layout Standard
18992
18993 24-bits
18994 \end_inset
18995 </cell>
18996 </row>
18997 <row topline="true" bottomline="true">
18998 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18999 \begin_inset Text
19000
19001 \layout Standard
19002
19003 data pointers
19004 \end_inset
19005 </cell>
19006 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
19007 \begin_inset Text
19008
19009 \layout Standard
19010
19011 16-bits
19012 \end_inset
19013 </cell>
19014 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19015 \begin_inset Text
19016
19017 \layout Standard
19018
19019 16-bits
19020 \end_inset
19021 </cell>
19022 </row>
19023 </lyxtabular>
19024
19025 \end_inset
19026
19027
19028 \layout Standard
19029
19030 It is advisable that all sources within a project are compiled with the
19031  same memory model.
19032  If one wants to override the default memory model, this can be done by
19033  declaring a pointer as
19034 \series bold
19035 far
19036 \series default
19037  or
19038 \series bold
19039 near
19040 \series default
19041 .
19042  Far selects large memory model's pointers, while near selects small memory
19043  model's pointers.
19044 \layout Standard
19045
19046 The standard device libraries (see
19047 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
19048
19049 \end_inset
19050
19051 ) contain no reference to pointers, so they can be used with both memory
19052  models.
19053 \layout Subsection
19054
19055 Stack
19056 \layout Standard
19057
19058 The stack implementation for the PIC16 port uses two indirect registers,
19059  FSR1 and FSR2.
19060 \layout List
19061 \labelwidthstring 00.00.0000
19062
19063 FSR1 is assigned as stack pointer
19064 \layout List
19065 \labelwidthstring 00.00.0000
19066
19067 FSR2 is assigned as frame pointer
19068 \layout Standard
19069
19070 The following stack models are supported by the PIC16 port
19071 \layout Itemize
19072
19073
19074 \noun on
19075 small
19076 \noun default
19077  model
19078 \layout Itemize
19079
19080
19081 \noun on
19082 large
19083 \noun default
19084  model
19085 \layout Standard
19086
19087
19088 \noun on
19089 Small
19090 \noun default
19091  model means that only the FSRxL byte is used to access stack and frame,
19092  while
19093 \emph on
19094 \noun on
19095 large
19096 \emph default
19097 \noun default
19098  uses both FSRxL and FSRxH registers.
19099  The following table shows the stack/frame pointers sizes according to stack
19100  model and the maximum space they can address:
19101 \layout Standard
19102 \align center
19103
19104 \begin_inset  Tabular
19105 <lyxtabular version="3" rows="3" columns="3">
19106 <features>
19107 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19108 <column alignment="center" valignment="top" leftline="true" width="0">
19109 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19110 <row topline="true" bottomline="true">
19111 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19112 \begin_inset Text
19113
19114 \layout Standard
19115
19116 Stack & Frame pointer sizes according to stack model
19117 \end_inset
19118 </cell>
19119 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19120 \begin_inset Text
19121
19122 \layout Standard
19123
19124 small
19125 \end_inset
19126 </cell>
19127 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19128 \begin_inset Text
19129
19130 \layout Standard
19131
19132 large
19133 \end_inset
19134 </cell>
19135 </row>
19136 <row topline="true">
19137 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19138 \begin_inset Text
19139
19140 \layout Standard
19141
19142 Stack pointer FSR1
19143 \end_inset
19144 </cell>
19145 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19146 \begin_inset Text
19147
19148 \layout Standard
19149
19150 8-bits
19151 \end_inset
19152 </cell>
19153 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19154 \begin_inset Text
19155
19156 \layout Standard
19157
19158 16-bits
19159 \end_inset
19160 </cell>
19161 </row>
19162 <row topline="true" bottomline="true">
19163 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19164 \begin_inset Text
19165
19166 \layout Standard
19167
19168 Frame pointer FSR2
19169 \end_inset
19170 </cell>
19171 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19172 \begin_inset Text
19173
19174 \layout Standard
19175
19176 8-bits
19177 \end_inset
19178 </cell>
19179 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19180 \begin_inset Text
19181
19182 \layout Standard
19183
19184 16-bits
19185 \end_inset
19186 </cell>
19187 </row>
19188 </lyxtabular>
19189
19190 \end_inset
19191
19192
19193 \layout Standard
19194
19195
19196 \noun on
19197 Large
19198 \noun default
19199 stack model is currently not working properly throughout the code generator.
19200  So its use is not advised.
19201  Also there are some other points that need special care:
19202 \newline
19203
19204 \layout Enumerate
19205
19206 Do not create stack sections with size more than one physical bank (that
19207  is 256 bytes)
19208 \layout Enumerate
19209
19210 Stack sections should no cross physical bank limits (i.e.
19211  #pragma stack 0x50 0x100)
19212 \layout Standard
19213
19214 These limitations are caused by the fact that only FSRxL is modified when
19215  using SMALL stack model, so no more than 256 bytes of stack can be used.
19216  This problem will disappear after LARGE model is fully implemented.
19217 \layout Subsection
19218
19219 Functions
19220 \layout Standard
19221
19222 In addition to the standard SDCC function keywords, PIC16 port makes available
19223  two more:
19224 \layout List
19225 \labelwidthstring 00.00.0000
19226
19227 wparam Use the WREG to pass one byte of the first function argument.
19228  This improves speed but you may not use this for functions with arguments
19229  that are called via function pointers, otherwise the first byte of the
19230  first parameter will get lost.
19231  Usage:
19232 \layout LyX-Code
19233
19234 void func_wparam(int a) wparam
19235 \layout LyX-Code
19236
19237 {
19238 \layout LyX-Code
19239
19240     /* WREG hold the lower part of a */
19241 \layout LyX-Code
19242
19243     /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
19244  */
19245 \layout LyX-Code
19246
19247 ...
19248 \layout LyX-Code
19249
19250 }
19251 \layout Standard
19252
19253 This keyword replaces the deprecated wparam pragma.
19254 \layout List
19255 \labelwidthstring 00.00.0000
19256
19257 shadowregs When entering/exiting an ISR, it is possible to take advantage
19258  of the PIC18F hardware shadow registers which hold the values of WREG,
19259  STATUS and BSR registers.
19260  This can be done by adding the keyword
19261 \emph on
19262 shadowregs
19263 \emph default
19264  before the
19265 \emph on
19266 interrupt
19267 \emph default
19268  keyword in the function's header.
19269 \layout LyX-Code
19270
19271 void isr_shadow(void) shadowregs interrupt 1
19272 \layout LyX-Code
19273
19274 {
19275 \layout LyX-Code
19276
19277 ...
19278 \layout LyX-Code
19279
19280 }
19281 \layout Standard
19282
19283
19284 \emph on
19285 shadowregs
19286 \emph default
19287  instructs the code generator not to store/restore WREG, STATUS, BSR when
19288  entering/exiting the ISR.
19289 \layout Subsection
19290
19291 Function return values
19292 \layout Standard
19293
19294 Return values from functions are placed to the appropriate registers following
19295  a modified Microchip policy optimized for SDCC.
19296  The following table shows these registers:
19297 \layout Standard
19298 \align center
19299
19300 \begin_inset  Tabular
19301 <lyxtabular version="3" rows="6" columns="2">
19302 <features>
19303 <column alignment="center" valignment="top" leftline="true" width="0">
19304 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19305 <row topline="true" bottomline="true">
19306 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19307 \begin_inset Text
19308
19309 \layout Standard
19310
19311 size
19312 \end_inset
19313 </cell>
19314 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19315 \begin_inset Text
19316
19317 \layout Standard
19318
19319 destination register
19320 \end_inset
19321 </cell>
19322 </row>
19323 <row topline="true">
19324 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19325 \begin_inset Text
19326
19327 \layout Standard
19328
19329 8 bits
19330 \end_inset
19331 </cell>
19332 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19333 \begin_inset Text
19334
19335 \layout Standard
19336
19337 WREG
19338 \end_inset
19339 </cell>
19340 </row>
19341 <row topline="true">
19342 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19343 \begin_inset Text
19344
19345 \layout Standard
19346
19347 16 bits
19348 \end_inset
19349 </cell>
19350 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19351 \begin_inset Text
19352
19353 \layout Standard
19354
19355 PRODL:WREG
19356 \end_inset
19357 </cell>
19358 </row>
19359 <row topline="true">
19360 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19361 \begin_inset Text
19362
19363 \layout Standard
19364
19365 24 bits
19366 \end_inset
19367 </cell>
19368 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19369 \begin_inset Text
19370
19371 \layout Standard
19372
19373 PRODH:PRODL:WREG
19374 \end_inset
19375 </cell>
19376 </row>
19377 <row topline="true">
19378 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19379 \begin_inset Text
19380
19381 \layout Standard
19382
19383 32 bits
19384 \end_inset
19385 </cell>
19386 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19387 \begin_inset Text
19388
19389 \layout Standard
19390
19391 FSR0L:PRODH:PRODL:WREG
19392 \end_inset
19393 </cell>
19394 </row>
19395 <row topline="true" bottomline="true">
19396 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19397 \begin_inset Text
19398
19399 \layout Standard
19400
19401 >32 bits
19402 \end_inset
19403 </cell>
19404 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19405 \begin_inset Text
19406
19407 \layout Standard
19408
19409 on stack, FSR0 points to the beginning
19410 \end_inset
19411 </cell>
19412 </row>
19413 </lyxtabular>
19414
19415 \end_inset
19416
19417
19418 \layout Subsection
19419
19420 Interrupts
19421 \layout Standard
19422
19423 An interrupt servive routine (ISR) is declared using the
19424 \emph on
19425 interrupt
19426 \emph default
19427  keyword.
19428 \layout LyX-Code
19429
19430 void isr(void) interrupt
19431 \emph on
19432 n
19433 \layout LyX-Code
19434
19435 {
19436 \layout LyX-Code
19437
19438 ...
19439 \layout LyX-Code
19440
19441 }
19442 \layout Standard
19443
19444
19445 \emph on
19446 n
19447 \emph default
19448  is the interrupt number, which for PIC18F devices can be:
19449 \layout Standard
19450 \align center
19451
19452 \begin_inset  Tabular
19453 <lyxtabular version="3" rows="4" columns="3">
19454 <features>
19455 <column alignment="center" valignment="top" leftline="true" width="0">
19456 <column alignment="center" valignment="top" leftline="true" width="0">
19457 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19458 <row topline="true" bottomline="true">
19459 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19460 \begin_inset Text
19461
19462 \layout Standard
19463
19464
19465 \emph on
19466 n
19467 \end_inset
19468 </cell>
19469 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19470 \begin_inset Text
19471
19472 \layout Standard
19473
19474 Interrupt Vector
19475 \end_inset
19476 </cell>
19477 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19478 \begin_inset Text
19479
19480 \layout Standard
19481
19482 Interrupt Vector Address
19483 \end_inset
19484 </cell>
19485 </row>
19486 <row topline="true">
19487 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19488 \begin_inset Text
19489
19490 \layout Standard
19491
19492 0
19493 \end_inset
19494 </cell>
19495 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19496 \begin_inset Text
19497
19498 \layout Standard
19499
19500 RESET vector
19501 \end_inset
19502 </cell>
19503 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19504 \begin_inset Text
19505
19506 \layout Standard
19507
19508 0x000000
19509 \end_inset
19510 </cell>
19511 </row>
19512 <row topline="true">
19513 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19514 \begin_inset Text
19515
19516 \layout Standard
19517
19518
19519 \family roman
19520 \series medium
19521 \shape up
19522 \size normal
19523 \emph off
19524 \bar no
19525 \noun off
19526 \color none
19527 1
19528 \end_inset
19529 </cell>
19530 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19531 \begin_inset Text
19532
19533 \layout Standard
19534
19535
19536 \family roman
19537 \series medium
19538 \shape up
19539 \size normal
19540 \emph off
19541 \bar no
19542 \noun off
19543 \color none
19544 HIGH priority interrupts
19545 \end_inset
19546 </cell>
19547 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19548 \begin_inset Text
19549
19550 \layout Standard
19551
19552 0x000008
19553 \end_inset
19554 </cell>
19555 </row>
19556 <row topline="true" bottomline="true">
19557 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19558 \begin_inset Text
19559
19560 \layout Standard
19561
19562 2
19563 \end_inset
19564 </cell>
19565 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19566 \begin_inset Text
19567
19568 \layout Standard
19569
19570 LOW priority interrupts
19571 \end_inset
19572 </cell>
19573 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19574 \begin_inset Text
19575
19576 \layout Standard
19577
19578 0x000018
19579 \end_inset
19580 </cell>
19581 </row>
19582 </lyxtabular>
19583
19584 \end_inset
19585
19586
19587 \layout Standard
19588
19589 When generating assembly code for ISR the code generator places a
19590 \noun on
19591 goto
19592 \noun default
19593 instruction at the
19594 \emph on
19595 Interrupt Vector Address
19596 \emph default
19597  which points at the genetated ISR.
19598  This single GOTO instruction is part of an automatically generated
19599 \emph on
19600 interrupt entry point
19601 \emph default
19602  function.
19603  The actuall ISR code is placed as normally would in the code space.
19604  Upon interrupt request, the GOTO instruction is executed which jumps to
19605  the ISR code.
19606  When declaring interrupt functions as _naked this GOTO instruction is
19607 \series bold
19608 not
19609 \series default
19610  generated.
19611  The whole interrupt functions is therefore placed at the Interrupt Vector
19612  Address of the specific interrupt.
19613  This is not a problem for the LOW priority interrupts, but it is a problem
19614  for the RESET and the HIGH priority interrupts because code may be written
19615  at the next interrupt´s vector address and cause undeterminate program
19616  behaviour if that interrupt is raised.
19617 \begin_inset Foot
19618 collapsed false
19619
19620 \layout Standard
19621
19622 This is not a problem when
19623 \layout Enumerate
19624
19625 this is a HIGH interrupt ISR and LOW interrupts are
19626 \emph on
19627 disabled
19628 \emph default
19629  or not used.
19630 \layout Enumerate
19631
19632 when the ISR is small enough not to reach the next interrupt´s vector address.
19633 \end_inset
19634
19635
19636 \layout Standard
19637
19638
19639 \emph on
19640 n
19641 \emph default
19642  is possible to be omitted.
19643  This way a function is generated similar to an ISR, but it is not assigned
19644  to any interrupt.
19645 \layout Standard
19646
19647 When entering an interrupt, currently the PIC16
19648 \begin_inset LatexCommand \index{PIC16}
19649
19650 \end_inset
19651
19652  port automatically saves the following registers:
19653 \layout Itemize
19654
19655 WREG
19656 \layout Itemize
19657
19658 STATUS
19659 \layout Itemize
19660
19661 BSR
19662 \layout Itemize
19663
19664 PROD (PRODL and PRODH)
19665 \layout Itemize
19666
19667 FSR0 (FSR0L and FSR0H)
19668 \layout Standard
19669
19670 These registers are restored upon return from the interrupt routine.
19671 \begin_inset Foot
19672 collapsed false
19673
19674 \layout Standard
19675
19676 NOTE that when the _naked attribute is specified for an interrupt routine,
19677  then NO registers are stored or restored.
19678 \end_inset
19679
19680
19681 \layout Subsection
19682
19683 Generic Pointers
19684 \layout Standard
19685
19686 Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
19687  There are 3 types of generic pointers currently implemented data, code
19688  and eeprom pointers.
19689  They are differentiated by the value of the 7th and 6th bits of the upper
19690  byte:
19691 \layout Standard
19692 \align center
19693
19694 \begin_inset  Tabular
19695 <lyxtabular version="3" rows="5" columns="5">
19696 <features>
19697 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19698 <column alignment="center" valignment="top" width="0">
19699 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19700 <column alignment="center" valignment="top" width="0">
19701 <column alignment="left" valignment="top" rightline="true" width="0">
19702 <row topline="true" bottomline="true">
19703 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19704 \begin_inset Text
19705
19706 \layout Standard
19707
19708 pointer type
19709 \end_inset
19710 </cell>
19711 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19712 \begin_inset Text
19713
19714 \layout Standard
19715
19716 7th bit
19717 \end_inset
19718 </cell>
19719 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19720 \begin_inset Text
19721
19722 \layout Standard
19723
19724 6th bit
19725 \end_inset
19726 </cell>
19727 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19728 \begin_inset Text
19729
19730 \layout Standard
19731
19732 rest of the pointer
19733 \end_inset
19734 </cell>
19735 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19736 \begin_inset Text
19737
19738 \layout Standard
19739
19740 description
19741 \end_inset
19742 </cell>
19743 </row>
19744 <row topline="true" bottomline="true">
19745 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19746 \begin_inset Text
19747
19748 \layout Standard
19749
19750 data
19751 \end_inset
19752 </cell>
19753 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19754 \begin_inset Text
19755
19756 \layout Standard
19757
19758 1
19759 \end_inset
19760 </cell>
19761 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19762 \begin_inset Text
19763
19764 \layout Standard
19765
19766 0
19767 \end_inset
19768 </cell>
19769 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19770 \begin_inset Text
19771
19772 \layout Standard
19773
19774
19775 \family typewriter
19776 \shape slanted
19777 \emph on
19778 uuuuuu uuuuxxxx xxxxxxxx
19779 \end_inset
19780 </cell>
19781 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19782 \begin_inset Text
19783
19784 \layout Standard
19785
19786 a 12-bit data pointer in data RAM memory
19787 \end_inset
19788 </cell>
19789 </row>
19790 <row bottomline="true">
19791 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19792 \begin_inset Text
19793
19794 \layout Standard
19795
19796 code
19797 \end_inset
19798 </cell>
19799 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19800 \begin_inset Text
19801
19802 \layout Standard
19803
19804 0
19805 \end_inset
19806 </cell>
19807 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19808 \begin_inset Text
19809
19810 \layout Standard
19811
19812 0
19813 \end_inset
19814 </cell>
19815 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19816 \begin_inset Text
19817
19818 \layout Standard
19819
19820
19821 \family typewriter
19822 \shape slanted
19823 \emph on
19824 uxxxxx xxxxxxxx xxxxxxxx
19825 \end_inset
19826 </cell>
19827 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19828 \begin_inset Text
19829
19830 \layout Standard
19831
19832 a 21-bit code pointer in FLASH memory
19833 \end_inset
19834 </cell>
19835 </row>
19836 <row bottomline="true">
19837 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19838 \begin_inset Text
19839
19840 \layout Standard
19841
19842 eeprom
19843 \end_inset
19844 </cell>
19845 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19846 \begin_inset Text
19847
19848 \layout Standard
19849
19850 0
19851 \end_inset
19852 </cell>
19853 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19854 \begin_inset Text
19855
19856 \layout Standard
19857
19858 1
19859 \end_inset
19860 </cell>
19861 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19862 \begin_inset Text
19863
19864 \layout Standard
19865
19866
19867 \family typewriter
19868 \shape slanted
19869 \emph on
19870 uuuuuu uuuuuuxx xxxxxxxx
19871 \end_inset
19872 </cell>
19873 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19874 \begin_inset Text
19875
19876 \layout Standard
19877
19878 a 10-bit eeprom pointer in EEPROM memory
19879 \end_inset
19880 </cell>
19881 </row>
19882 <row bottomline="true">
19883 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19884 \begin_inset Text
19885
19886 \layout Standard
19887
19888 (unimplemented)
19889 \end_inset
19890 </cell>
19891 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19892 \begin_inset Text
19893
19894 \layout Standard
19895
19896 1
19897 \end_inset
19898 </cell>
19899 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19900 \begin_inset Text
19901
19902 \layout Standard
19903
19904 1
19905 \end_inset
19906 </cell>
19907 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19908 \begin_inset Text
19909
19910 \layout Standard
19911
19912
19913 \family typewriter
19914 \shape slanted
19915 \emph on
19916 xxxxxx xxxxxxxx xxxxxxxx
19917 \end_inset
19918 </cell>
19919 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19920 \begin_inset Text
19921
19922 \layout Standard
19923
19924 unimplemented pointer type
19925 \end_inset
19926 </cell>
19927 </row>
19928 </lyxtabular>
19929
19930 \end_inset
19931
19932
19933 \layout Standard
19934
19935 Generic pointer are read and written with a set of library functions which
19936  read/write 1, 2, 3, 4 bytes.
19937 \layout Subsection
19938
19939 PIC16 C Libraries
19940 \layout Subsubsection
19941
19942 Standard I/O Streams
19943 \layout Standard
19944
19945 In the
19946 \emph on
19947 stdio.h
19948 \emph default
19949  the type FILE is defined as:
19950 \layout LyX-Code
19951
19952 typedef char * FILE;
19953 \layout Standard
19954
19955 This type is the stream type implemented I/O in the PIC18F devices.
19956  Also the standard input and output streams are declared in stdio.h:
19957 \layout LyX-Code
19958
19959 extern FILE * stdin;
19960 \layout LyX-Code
19961
19962 extern FILE * stdout;
19963 \layout Standard
19964
19965 The FILE type is actually a generic pointer which defines one more type
19966  of generic pointers, the
19967 \emph on
19968 stream
19969 \emph default
19970 pointer.
19971  This new type has the format:
19972 \layout Standard
19973 \align center
19974
19975 \begin_inset  Tabular
19976 <lyxtabular version="3" rows="2" columns="7">
19977 <features>
19978 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19979 <column alignment="center" valignment="top" width="0">
19980 <column alignment="center" valignment="top" leftline="true" width="0">
19981 <column alignment="center" valignment="top" leftline="true" width="0">
19982 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19983 <column alignment="center" valignment="top" width="0">
19984 <column alignment="left" valignment="top" rightline="true" width="0">
19985 <row topline="true" bottomline="true">
19986 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19987 \begin_inset Text
19988
19989 \layout Standard
19990
19991 pointer type
19992 \end_inset
19993 </cell>
19994 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19995 \begin_inset Text
19996
19997 \layout Standard
19998
19999 <7:6>
20000 \end_inset
20001 </cell>
20002 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20003 \begin_inset Text
20004
20005 \layout Standard
20006
20007 <5>
20008 \end_inset
20009 </cell>
20010 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20011 \begin_inset Text
20012
20013 \layout Standard
20014
20015 <4>
20016 \end_inset
20017 </cell>
20018 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20019 \begin_inset Text
20020
20021 \layout Standard
20022
20023 <3:0>
20024 \end_inset
20025 </cell>
20026 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20027 \begin_inset Text
20028
20029 \layout Standard
20030
20031 rest of the pointer
20032 \end_inset
20033 </cell>
20034 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20035 \begin_inset Text
20036
20037 \layout Standard
20038
20039 descrption
20040 \end_inset
20041 </cell>
20042 </row>
20043 <row topline="true" bottomline="true">
20044 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20045 \begin_inset Text
20046
20047 \layout Standard
20048
20049 stream
20050 \end_inset
20051 </cell>
20052 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20053 \begin_inset Text
20054
20055 \layout Standard
20056
20057 00
20058 \end_inset
20059 </cell>
20060 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20061 \begin_inset Text
20062
20063 \layout Standard
20064
20065 1
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 0
20074 \end_inset
20075 </cell>
20076 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20077 \begin_inset Text
20078
20079 \layout Standard
20080
20081 nnnn
20082 \end_inset
20083 </cell>
20084 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20085 \begin_inset Text
20086
20087 \layout Standard
20088
20089
20090 \family typewriter
20091 \shape slanted
20092 \emph on
20093 uuuuuuuu uuuuuuuu
20094 \end_inset
20095 </cell>
20096 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20097 \begin_inset Text
20098
20099 \layout Standard
20100
20101 upper byte high nubble is 0x2n, the rest are zeroes
20102 \end_inset
20103 </cell>
20104 </row>
20105 </lyxtabular>
20106
20107 \end_inset
20108
20109
20110 \layout Standard
20111
20112 Currently implemented there are 3 types of streams defined:
20113 \layout Standard
20114 \align center
20115
20116 \begin_inset  Tabular
20117 <lyxtabular version="3" rows="4" columns="4">
20118 <features>
20119 <column alignment="center" valignment="top" leftline="true" width="0">
20120 <column alignment="center" valignment="top" leftline="true" width="0">
20121 <column alignment="center" valignment="top" leftline="true" width="0">
20122 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20123 <row topline="true" bottomline="true">
20124 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20125 \begin_inset Text
20126
20127 \layout Standard
20128
20129 stream type
20130 \end_inset
20131 </cell>
20132 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20133 \begin_inset Text
20134
20135 \layout Standard
20136
20137 value
20138 \end_inset
20139 </cell>
20140 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20141 \begin_inset Text
20142
20143 \layout Standard
20144
20145 module
20146 \end_inset
20147 </cell>
20148 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20149 \begin_inset Text
20150
20151 \layout Standard
20152
20153 description
20154 \end_inset
20155 </cell>
20156 </row>
20157 <row topline="true">
20158 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20159 \begin_inset Text
20160
20161 \layout Standard
20162
20163 STREAM_USART
20164 \end_inset
20165 </cell>
20166 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20167 \begin_inset Text
20168
20169 \layout Standard
20170
20171
20172 \family typewriter
20173 0x200000UL
20174 \end_inset
20175 </cell>
20176 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20177 \begin_inset Text
20178
20179 \layout Standard
20180
20181 USART
20182 \end_inset
20183 </cell>
20184 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20185 \begin_inset Text
20186
20187 \layout Standard
20188
20189 Writes/Reads characters via the USART peripheral
20190 \end_inset
20191 </cell>
20192 </row>
20193 <row topline="true">
20194 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20195 \begin_inset Text
20196
20197 \layout Standard
20198
20199 STREAM_MSSP
20200 \end_inset
20201 </cell>
20202 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20203 \begin_inset Text
20204
20205 \layout Standard
20206
20207
20208 \family typewriter
20209 0x210000UL
20210 \end_inset
20211 </cell>
20212 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20213 \begin_inset Text
20214
20215 \layout Standard
20216
20217 MSSP
20218 \end_inset
20219 </cell>
20220 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20221 \begin_inset Text
20222
20223 \layout Standard
20224
20225 Writes/Reads characters via the MSSP peripheral
20226 \end_inset
20227 </cell>
20228 </row>
20229 <row topline="true" bottomline="true">
20230 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20231 \begin_inset Text
20232
20233 \layout Standard
20234
20235 STREAM_USER
20236 \end_inset
20237 </cell>
20238 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20239 \begin_inset Text
20240
20241 \layout Standard
20242
20243
20244 \family typewriter
20245 0x2f0000UL
20246 \end_inset
20247 </cell>
20248 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20249 \begin_inset Text
20250
20251 \layout Standard
20252
20253 (none)
20254 \end_inset
20255 </cell>
20256 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20257 \begin_inset Text
20258
20259 \layout Standard
20260
20261 Writes/Reads characters via used defined functions
20262 \end_inset
20263 </cell>
20264 </row>
20265 </lyxtabular>
20266
20267 \end_inset
20268
20269
20270 \layout Standard
20271
20272 The stream identifiers are declared as macros in the stdio.h header.
20273 \layout Standard
20274
20275 In the libc library there exist the functions that are used to write to
20276  each of the above streams.
20277  These are
20278 \layout List
20279 \labelwidthstring 00.00.0000
20280
20281 _
20282 \begin_inset ERT
20283 status Collapsed
20284
20285 \layout Standard
20286
20287 \backslash
20288 /
20289 \end_inset
20290
20291 _stream_usart_putchar writes a character at the USART stream
20292 \layout List
20293 \labelwidthstring 00.00.0000
20294
20295 _
20296 \begin_inset ERT
20297 status Collapsed
20298
20299 \layout Standard
20300
20301 \backslash
20302 /
20303 \end_inset
20304
20305 _stream_mssp_putchar writes a character at the MSSP stream
20306 \layout List
20307 \labelwidthstring 00.00.0000
20308
20309 putchar dummy function.
20310  This writes a character to a user specified manner.
20311 \layout Standard
20312
20313 In order to increase performance
20314 \emph on
20315 putchar
20316 \emph default
20317 is declared in stdio.h as having its parameter in WREG (it has the wparam
20318  keyword).
20319  In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
20320  in a user-friendly way.
20321
20322 \emph on
20323 arg
20324 \emph default
20325  is the name of the variable that holds the character to print.
20326  An example follows:
20327 \layout LyX-Code
20328
20329 #include <pic18fregs.h>
20330 \newline
20331 #include <stdio.h>
20332 \newline
20333
20334 \newline
20335 PUTCHAR( c )
20336 \layout LyX-Code
20337
20338 {
20339 \layout LyX-Code
20340
20341     PORTA = c;    /* dump character c to PORTA */
20342 \layout LyX-Code
20343
20344 }
20345 \newline
20346
20347 \newline
20348 void main(void)
20349 \layout LyX-Code
20350
20351 {
20352 \layout LyX-Code
20353
20354     stdout = STREAM_USER;    /* this is not necessary, since stdout points
20355 \layout LyX-Code
20356
20357                               * by default to STREAM_USER */
20358 \layout LyX-Code
20359
20360     printf (¨This is a printf test
20361 \backslash
20362 n¨);
20363 \layout LyX-Code
20364
20365 }
20366 \layout LyX-Code
20367
20368 \layout Subsubsection
20369
20370 Printing functions
20371 \layout Standard
20372
20373 PIC16 contains an implementation of the printf-family of functions.
20374  There exist the following functions:
20375 \layout LyX-Code
20376
20377 extern unsigned int sprintf(char *buf, char *fmt, ...);
20378 \layout LyX-Code
20379
20380 extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
20381 \layout LyX-Code
20382
20383 \layout LyX-Code
20384
20385 extern unsigned int printf(char *fmt, ...);
20386 \layout LyX-Code
20387
20388 extern unsigned int vprintf(char *fmt, va_lista ap);
20389 \layout LyX-Code
20390
20391 \layout LyX-Code
20392
20393 extern unsigned int fprintf(FILE *fp, char *fmt, ...);
20394 \layout LyX-Code
20395
20396 extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
20397 \layout Standard
20398
20399 For sprintf and vsprintf
20400 \emph on
20401 buf
20402 \emph default
20403 should normally be a data pointer where the resulting string will be placed.
20404  No range checking is done so the user should allocate the necessery buffer.
20405  For fprintf and vfprintf
20406 \emph on
20407 fp
20408 \emph default
20409  should be a stream pointer (i.e.
20410  stdout, STREAM_MSSP, etc...).
20411 \layout Subsubsection
20412
20413 Signals
20414 \layout Standard
20415
20416 The PIC18F family of microcontrollers supports a number of interrupt sources.
20417  A list of these interrupts is shown in the following table:
20418 \layout Standard
20419 \align center
20420
20421 \begin_inset  Tabular
20422 <lyxtabular version="3" rows="11" columns="4">
20423 <features>
20424 <column alignment="left" valignment="top" leftline="true" width="0">
20425 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20426 <column alignment="left" valignment="top" leftline="true" width="0">
20427 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20428 <row topline="true" bottomline="true">
20429 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20430 \begin_inset Text
20431
20432 \layout Standard
20433
20434 signal name
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 description
20443 \end_inset
20444 </cell>
20445 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20446 \begin_inset Text
20447
20448 \layout Standard
20449
20450 signal name
20451 \end_inset
20452 </cell>
20453 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20454 \begin_inset Text
20455
20456 \layout Standard
20457
20458 descritpion
20459 \end_inset
20460 </cell>
20461 </row>
20462 <row topline="true">
20463 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20464 \begin_inset Text
20465
20466 \layout Standard
20467
20468 SIG_RB
20469 \end_inset
20470 </cell>
20471 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20472 \begin_inset Text
20473
20474 \layout Standard
20475
20476 PORTB change interrupt
20477 \end_inset
20478 </cell>
20479 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20480 \begin_inset Text
20481
20482 \layout Standard
20483
20484 SIG_EE
20485 \end_inset
20486 </cell>
20487 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20488 \begin_inset Text
20489
20490 \layout Standard
20491
20492 EEPROM/FLASH write complete interrupt
20493 \end_inset
20494 </cell>
20495 </row>
20496 <row topline="true">
20497 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20498 \begin_inset Text
20499
20500 \layout Standard
20501
20502 SIG_INT0
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 INT0 external interrupt
20511 \end_inset
20512 </cell>
20513 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20514 \begin_inset Text
20515
20516 \layout Standard
20517
20518 SIG_BCOL
20519 \end_inset
20520 </cell>
20521 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20522 \begin_inset Text
20523
20524 \layout Standard
20525
20526 Bus collision interrupt
20527 \end_inset
20528 </cell>
20529 </row>
20530 <row topline="true">
20531 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20532 \begin_inset Text
20533
20534 \layout Standard
20535
20536 SIG_INT1
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 INT1 external interrupt
20545 \end_inset
20546 </cell>
20547 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20548 \begin_inset Text
20549
20550 \layout Standard
20551
20552 SIG_LVD
20553 \end_inset
20554 </cell>
20555 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20556 \begin_inset Text
20557
20558 \layout Standard
20559
20560 Low voltage detect interrupt
20561 \end_inset
20562 </cell>
20563 </row>
20564 <row topline="true">
20565 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20566 \begin_inset Text
20567
20568 \layout Standard
20569
20570 SIG_INT2
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 INT2 external interrupt
20579 \end_inset
20580 </cell>
20581 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20582 \begin_inset Text
20583
20584 \layout Standard
20585
20586 SIG_PSP
20587 \end_inset
20588 </cell>
20589 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20590 \begin_inset Text
20591
20592 \layout Standard
20593
20594 Parallel slave port interrupt
20595 \end_inset
20596 </cell>
20597 </row>
20598 <row topline="true">
20599 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20600 \begin_inset Text
20601
20602 \layout Standard
20603
20604 SIG_CCP1
20605 \end_inset
20606 </cell>
20607 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20608 \begin_inset Text
20609
20610 \layout Standard
20611
20612 CCP1 module interrupt
20613 \end_inset
20614 </cell>
20615 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20616 \begin_inset Text
20617
20618 \layout Standard
20619
20620 SIG_AD
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 AD convertion complete interrupt
20629 \end_inset
20630 </cell>
20631 </row>
20632 <row topline="true">
20633 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20634 \begin_inset Text
20635
20636 \layout Standard
20637
20638 SIG_CCP2
20639 \end_inset
20640 </cell>
20641 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20642 \begin_inset Text
20643
20644 \layout Standard
20645
20646 CCP2 module interrupt
20647 \end_inset
20648 </cell>
20649 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20650 \begin_inset Text
20651
20652 \layout Standard
20653
20654 SIG_RC
20655 \end_inset
20656 </cell>
20657 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20658 \begin_inset Text
20659
20660 \layout Standard
20661
20662 USART receive interrupt
20663 \end_inset
20664 </cell>
20665 </row>
20666 <row topline="true">
20667 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20668 \begin_inset Text
20669
20670 \layout Standard
20671
20672 SIG_TMR0
20673 \end_inset
20674 </cell>
20675 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20676 \begin_inset Text
20677
20678 \layout Standard
20679
20680 TMR0 overflow interrupt
20681 \end_inset
20682 </cell>
20683 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20684 \begin_inset Text
20685
20686 \layout Standard
20687
20688 SIG_TX
20689 \end_inset
20690 </cell>
20691 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20692 \begin_inset Text
20693
20694 \layout Standard
20695
20696 USART transmit interrupt
20697 \end_inset
20698 </cell>
20699 </row>
20700 <row topline="true">
20701 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20702 \begin_inset Text
20703
20704 \layout Standard
20705
20706 SIG_TMR1
20707 \end_inset
20708 </cell>
20709 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20710 \begin_inset Text
20711
20712 \layout Standard
20713
20714 TMR1 overflow interrupt
20715 \end_inset
20716 </cell>
20717 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20718 \begin_inset Text
20719
20720 \layout Standard
20721
20722 SIG_MSSP
20723 \end_inset
20724 </cell>
20725 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20726 \begin_inset Text
20727
20728 \layout Standard
20729
20730 SSP receive/transmit interrupt
20731 \end_inset
20732 </cell>
20733 </row>
20734 <row topline="true">
20735 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20736 \begin_inset Text
20737
20738 \layout Standard
20739
20740 SIG_TMR2
20741 \end_inset
20742 </cell>
20743 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20744 \begin_inset Text
20745
20746 \layout Standard
20747
20748 TMR2 matches PR2 interrupt
20749 \end_inset
20750 </cell>
20751 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20752 \begin_inset Text
20753
20754 \layout Standard
20755
20756 \end_inset
20757 </cell>
20758 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20759 \begin_inset Text
20760
20761 \layout Standard
20762
20763 \end_inset
20764 </cell>
20765 </row>
20766 <row topline="true" bottomline="true">
20767 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20768 \begin_inset Text
20769
20770 \layout Standard
20771
20772 SIG_TMR3
20773 \end_inset
20774 </cell>
20775 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20776 \begin_inset Text
20777
20778 \layout Standard
20779
20780 TMR3 overflow interrupt
20781 \end_inset
20782 </cell>
20783 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20784 \begin_inset Text
20785
20786 \layout Standard
20787
20788 \end_inset
20789 </cell>
20790 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20791 \begin_inset Text
20792
20793 \layout Standard
20794
20795 \end_inset
20796 </cell>
20797 </row>
20798 </lyxtabular>
20799
20800 \end_inset
20801
20802
20803 \layout Standard
20804
20805 The prototypes for these names are defined in the header file
20806 \emph on
20807 signal.h
20808 \emph default
20809  .
20810 \layout Standard
20811
20812 In order to simplify signal handling, a number of macros is provided:
20813 \layout List
20814 \labelwidthstring 00.00.0000
20815
20816 DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
20817  high priority interrupts.
20818
20819 \emph on
20820 name
20821 \emph default
20822  is the function name to use.
20823 \layout List
20824 \labelwidthstring 00.00.0000
20825
20826 DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
20827  low priority interrupt.
20828
20829 \emph on
20830 name
20831 \emph default
20832  is the function name to use.
20833 \layout List
20834 \labelwidthstring 00.00.0000
20835
20836 DEF_HANDLER(sig,handler) define a handler for signal
20837 \emph on
20838 sig.
20839 \layout List
20840 \labelwidthstring 00.00.0000
20841
20842 END_DEF end the declaration of the dispatch table.
20843 \layout Standard
20844
20845 Additionally there are two more macros to simplify the declaration of the
20846  signal handler:
20847 \layout List
20848 \labelwidthstring 00.00.0000
20849
20850
20851 \series medium
20852 SIGHANDLER(handler)
20853 \series default
20854 this declares the function prototype for the
20855 \emph on
20856 handler
20857 \emph default
20858  function.
20859 \layout List
20860 \labelwidthstring 00.00.0000
20861
20862 SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
20863 \layout Standard
20864
20865 An example of using the macros above is shown below:
20866 \layout LyX-Code
20867
20868 #include <pic18fregs.h>
20869 \layout LyX-Code
20870
20871 #include <signal.h>
20872 \newline
20873
20874 \newline
20875 DEF_INTHIGH(high_int)
20876 \layout LyX-Code
20877
20878 DEF_HANDLER(SIG_TMR0, _tmr0_handler)
20879 \layout LyX-Code
20880
20881 DEF_HANDLER(SIG_BCOL, _bcol_handler)
20882 \layout LyX-Code
20883
20884 END_DEF
20885 \newline
20886
20887 \newline
20888 SIGHANDLER(_tmr0_handler)
20889 \layout LyX-Code
20890
20891 {
20892 \layout LyX-Code
20893
20894   /* action to be taken when timer 0 overflows */
20895 \layout LyX-Code
20896
20897 }
20898 \newline
20899
20900 \newline
20901 SIGHANDLERNAKED(_bcol_handler)
20902 \layout LyX-Code
20903
20904 {
20905 \layout LyX-Code
20906
20907   _asm
20908 \layout LyX-Code
20909
20910     /* action to be taken when bus collision occurs */
20911 \layout LyX-Code
20912
20913     retfie
20914 \layout LyX-Code
20915
20916  _endasm;
20917 \layout LyX-Code
20918
20919 }
20920 \layout Standard
20921
20922
20923 \series bold
20924 NOTES:
20925 \series default
20926  Special care should be taken when using the above scheme:
20927 \layout Itemize
20928
20929 do not place a colon (;) at the end of the DEF_* and END_DEF macros.
20930 \layout Itemize
20931
20932 when declaring SIGHANDLERNAKED handler never forget to use
20933 \emph on
20934 retfie
20935 \emph default
20936  for proper returning.
20937 \layout Subsection
20938
20939 PIC16 Port -- Tips
20940 \layout Standard
20941
20942 Here you can find some general tips for compiling programs with SDCC/pic16.
20943 \layout Subsubsection
20944
20945 Stack size
20946 \layout Standard
20947
20948 The default stack size (that is 64 bytes) probably is enough for many programs.
20949  One must take care that when there are many levels of function nesting,
20950  or there is excessive usage of stack, its size should be extended.
20951  An example of such a case is the printf/sprintf family of functions.
20952  If you encounter problems like not being able to print integers, then you
20953  need to set the stack size around the maximum (256 for small stack model).
20954  The following diagram shows what happens when calling printf to print an
20955  integer:
20956 \layout LyX-Code
20957
20958 printf () --> ltoa () --> ultoa () --> divschar ()
20959 \layout Standard
20960
20961 It is should be understood that stack is easily consumed when calling complicate
20962 d functions.
20963  Using command line arguments like -
20964 \begin_inset ERT
20965 status Collapsed
20966
20967 \layout Standard
20968
20969 \backslash
20970 /
20971 \end_inset
20972
20973 -fommit-frame-pointer might reduce stack usage by not creating unnecessery
20974  stack frames.
20975  Other ways to reduce stack usage may exist.
20976 \layout Chapter
20977
20978 Debugging
20979 \layout Standard
20980
20981 There are several approaches to debugging your code.
20982  This chapter is meant to show your options and to give detail on some of
20983  them:
20984 \newline
20985
20986 \newline
20987 When writing your code:
20988 \layout Itemize
20989
20990 write your code with debugging in mind (avoid duplicating code, put conceptually
20991  similar variables into structs, use structured code, have strategic points
20992  within your code where all variables are consistent, ...)
20993 \layout Itemize
20994
20995 run a syntax-checking tool like splint
20996 \begin_inset LatexCommand \index{splint (syntax checking tool)}
20997
20998 \end_inset
20999
21000
21001 \begin_inset LatexCommand \index{lint (syntax checking tool)}
21002
21003 \end_inset
21004
21005  (see -
21006 \begin_inset ERT
21007 status Collapsed
21008
21009 \layout Standard
21010
21011 \backslash
21012 /
21013 \end_inset
21014
21015 -more-pedantic
21016 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
21017
21018 \end_inset
21019
21020 ) over the code.
21021 \layout Itemize
21022
21023 for the high level code use a C-compiler (like f.e.
21024  GCC) to compile run and debug the code on your host.
21025  See (see -
21026 \begin_inset ERT
21027 status Collapsed
21028
21029 \layout Standard
21030
21031 \backslash
21032 /
21033 \end_inset
21034
21035 -more-pedantic
21036 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
21037
21038 \end_inset
21039
21040  ) on howto handle syntax extensions like __xdata, __at(), ...
21041
21042 \layout Itemize
21043
21044 use another C-compiler to compile code for your target.
21045  Always an option but not recommended:) And not very likely to help you.
21046  If you seriously consider walking this path you should at least occasionally
21047  check portability of your code.
21048  Most commercial compiler vendors will offer an evaluation version so you
21049  can test compile your code or snippets of your code.
21050 \layout Standard
21051
21052 Debugging on a simulator:
21053 \layout Itemize
21054
21055 there is a separate section about SDCDB (section
21056 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
21057
21058 \end_inset
21059
21060 ) below.
21061 \layout Itemize
21062
21063 or (8051 specific) use a freeware/commercial simulator which interfaces
21064  to the AOMF
21065 \begin_inset LatexCommand \index{AOMF, AOMF51}
21066
21067 \end_inset
21068
21069  file (see
21070 \begin_inset LatexCommand \ref{OMF file}
21071
21072 \end_inset
21073
21074 ) optionally generated by SDCC.
21075 \layout Standard
21076
21077 Debugging On-target:
21078 \layout Itemize
21079
21080 use a MCU port pin to serially output debug data to the RS232 port of your
21081  host.
21082  You'll probably want some level shifting device typically involving a MAX232
21083  or similar IC.
21084  If the hardware serial port of the MCU is not available search for 'Software
21085  UART' in your favourite search machine.
21086 \layout Itemize
21087
21088 use an on-target monitor.
21089  In this context a monitor is a small program which usually accepts commands
21090  via a serial line and allows to set program counter, to single step through
21091  a program and read/write memory locations.
21092  For the 8051 good examples of monitors are paulmon and cmon51 (see section
21093
21094 \begin_inset LatexCommand \ref{sec:Related-open-source-tools}
21095
21096 \end_inset
21097
21098 ).
21099 \layout Itemize
21100
21101 toggle MCU port pins at strategic points within your code and use an oscilloscop
21102 e.
21103  A
21104 \emph on
21105 digital oscilloscope
21106 \emph default
21107
21108 \begin_inset LatexCommand \index{oscilloscope}
21109
21110 \end_inset
21111
21112  with deep trace memory is really helpful especially if you have to debug
21113  a realtime application.
21114  If you need to monitor more pins than your oscilloscope provides you can
21115  sometimes get away with a small R-2R network.
21116  On a single channel oscilloscope you could f.e.
21117  monitor 2 push-pull driven pins by connecting one via a 10\SpecialChar ~
21118 k
21119 \begin_inset Formula $\Omega$
21120 \end_inset
21121
21122  resistor and the other one by a 5\SpecialChar ~
21123 k
21124 \begin_inset Formula $\Omega$
21125 \end_inset
21126
21127  resistor to the oscilloscope probe (check output drive capability of the
21128  pins you want to monitor).
21129  If you need to monitor many more pins a
21130 \emph on
21131 logic analyzer
21132 \emph default
21133  will be handy.
21134 \layout Itemize
21135
21136 use an ICE (
21137 \emph on
21138 i
21139 \emph default
21140 n
21141 \emph on
21142 c
21143 \emph default
21144 ircuit
21145 \emph on
21146 e
21147 \emph default
21148 mulator
21149 \begin_inset LatexCommand \index{ICE (in circuit emulator)}
21150
21151 \end_inset
21152
21153 ).
21154  Usually very expensive.
21155  And very nice to have too.
21156  And usually locks you (for years...) to the devices the ICE can emulate.
21157
21158 \layout Itemize
21159
21160 use a remote debugger.
21161  In most 8-bit systems the symbol information is not available on the target,
21162  and a complete debugger is too bulky for the target system.
21163  Therefore usually a debugger on the host system connects to an on-target
21164  debugging stub which accepts only primitive commands.
21165
21166 \newline
21167 Terms to enter into your favourite search engine could be 'remote debugging',
21168  'gdb stub' or 'inferior debugger'.
21169  (is there one?)
21170 \layout Itemize
21171
21172 use an on target hardware debugger.
21173  Some of the more modern MCUs include hardware support for setting break
21174  points and monitoring/changing variables by using dedicated hardware pins.
21175  This facility doesn't require additional code to run on the target and
21176
21177 \emph on
21178 usually
21179 \emph default
21180  doesn't affect runtime behaviour until a breakpoint is hit.
21181  For the mcs51 most hardware debuggers use the AOMF
21182 \begin_inset LatexCommand \index{AOMF, AOMF51}
21183
21184 \end_inset
21185
21186  file (see
21187 \begin_inset LatexCommand \ref{OMF file}
21188
21189 \end_inset
21190
21191 ) as input file.
21192
21193 \layout Standard
21194
21195 Last not least:
21196 \layout Itemize
21197
21198 if you are not familiar with any of the following terms you're likely to
21199  run into problems rather sooner than later:
21200 \emph on
21201 volatile
21202 \emph default
21203 ,
21204 \emph on
21205 atomic
21206 \emph default
21207 ,
21208 \emph on
21209 memory map
21210 \emph default
21211 ,
21212 \emph on
21213 overlay
21214 \emph default
21215 .
21216  As an embedded programmer you
21217 \emph on
21218 have
21219 \emph default
21220  to know them so why not look them up
21221 \emph on
21222 before
21223 \emph default
21224  you have problems?)
21225 \layout Itemize
21226
21227 tell someone else about your problem (actually this is a surprisingly effective
21228  means to hunt down the bug even if the listener is not familiar with your
21229  environment).
21230  As 'failure to communicate' is probably one of the job-induced deformations
21231  of an embedded programmer this is highly encouraged.
21232 \layout Section
21233
21234 Debugging with SDCDB
21235 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
21236
21237 \end_inset
21238
21239
21240 \begin_inset LatexCommand \index{SDCDB (debugger)}
21241
21242 \end_inset
21243
21244
21245 \layout Standard
21246
21247 SDCC is distributed with a source level debugger
21248 \begin_inset LatexCommand \index{Debugger}
21249
21250 \end_inset
21251
21252 .
21253  The debugger uses a command line interface, the command repertoire of the
21254  debugger has been kept as close to gdb
21255 \begin_inset LatexCommand \index{gdb}
21256
21257 \end_inset
21258
21259  (the GNU debugger) as possible.
21260  The configuration and build process is part of the standard compiler installati
21261 on, which also builds and installs the debugger in the target directory
21262  specified during configuration.
21263  The debugger allows you debug BOTH at the C source and at the ASM source
21264  level.
21265 \layout Subsection
21266
21267 Compiling for Debugging
21268 \layout Standard
21269
21270 The -
21271 \begin_inset ERT
21272 status Collapsed
21273
21274 \layout Standard
21275
21276 \backslash
21277 /
21278 \end_inset
21279
21280 -debug
21281 \begin_inset LatexCommand \index{-\/-debug}
21282
21283 \end_inset
21284
21285  option must be specified for all files for which debug information is to
21286  be generated.
21287  The compiler generates a .adb file for each of these files.
21288  The linker creates the .cdb
21289 \begin_inset LatexCommand \index{<file>.cdb}
21290
21291 \end_inset
21292
21293  file from the .adb
21294 \begin_inset LatexCommand \index{<file>.adb}
21295
21296 \end_inset
21297
21298  files and the address information.
21299  This .cdb is used by the debugger.
21300 \layout Subsection
21301
21302 How the Debugger Works
21303 \layout Standard
21304
21305 When the -
21306 \begin_inset ERT
21307 status Collapsed
21308
21309 \layout Standard
21310
21311 \backslash
21312 /
21313 \end_inset
21314
21315 -debug option is specified the compiler generates extra symbol information
21316  some of which are put into the assembler source and some are put into the
21317  .adb file.
21318  Then the linker creates the .cdb file from the individual .adb files with
21319  the address information for the symbols.
21320  The debugger reads the symbolic information generated by the compiler &
21321  the address information generated by the linker.
21322  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
21323  execution is controlled by the debugger.
21324  When a command is issued for the debugger, it translates it into appropriate
21325  commands for the simulator.
21326  (Currently SDCDM only connects to the simulator but
21327 \emph on
21328 newcdb
21329 \emph default
21330  at
21331 \begin_inset LatexCommand \url{http://ec2drv.sf.net/}
21332
21333 \end_inset
21334
21335  is an effort to connect directly to the hardware.)
21336 \layout Subsection
21337
21338 Starting the Debugger SDCDB
21339 \layout Standard
21340
21341 The debugger can be started using the following command line.
21342  (Assume the file you are debugging has the file name foo).
21343 \newline
21344
21345 \newline
21346
21347 \family sans
21348 \series bold
21349 sdcdb foo
21350 \newline
21351
21352 \family default
21353 \series default
21354
21355 \newline
21356 The debugger will look for the following files.
21357 \layout Itemize
21358
21359 foo.c - the source file.
21360 \layout Itemize
21361
21362 foo.cdb - the debugger symbol information file.
21363 \layout Itemize
21364
21365 foo.ihx - the Intel hex format
21366 \begin_inset LatexCommand \index{Intel hex format}
21367
21368 \end_inset
21369
21370  object file.
21371 \layout Subsection
21372
21373 SDCDB Command Line Options
21374 \layout Itemize
21375
21376 -
21377 \begin_inset ERT
21378 status Collapsed
21379
21380 \layout Standard
21381
21382 \backslash
21383 /
21384 \end_inset
21385
21386 -directory=<source file directory> this option can used to specify the directory
21387  search list.
21388  The debugger will look into the directory list specified for source, cdb
21389  & ihx files.
21390  The items in the directory list must be separated by ':', e.g.
21391  if the source files can be in the directories /home/src1 and /home/src2,
21392  the -
21393 \begin_inset ERT
21394 status Collapsed
21395
21396 \layout Standard
21397
21398 \backslash
21399 /
21400 \end_inset
21401
21402 -directory option should be -
21403 \begin_inset ERT
21404 status Collapsed
21405
21406 \layout Standard
21407
21408 \backslash
21409 /
21410 \end_inset
21411
21412 -directory=/home/src1:/home/src2.
21413  Note there can be no spaces in the option.
21414
21415 \layout Itemize
21416
21417 -cd <directory> - change to the <directory>.
21418 \layout Itemize
21419
21420 -fullname - used by GUI front ends.
21421 \layout Itemize
21422
21423 -cpu <cpu-type> - this argument is passed to the simulator please see the
21424  simulator docs for details.
21425 \layout Itemize
21426
21427 -X <Clock frequency > this options is passed to the simulator please see
21428  the simulator docs for details.
21429 \layout Itemize
21430
21431 -s <serial port file> passed to simulator see the simulator docs for details.
21432 \layout Itemize
21433
21434 -S <serial in,out> passed to simulator see the simulator docs for details.
21435 \layout Itemize
21436
21437 -k <port number> passed to simulator see the simulator docs for details.
21438 \layout Subsection
21439
21440 SDCDB Debugger Commands
21441 \layout Standard
21442
21443 As mentioned earlier the command interface for the debugger has been deliberatel
21444 y kept as close the GNU debugger gdb, as possible.
21445  This will help the integration with existing graphical user interfaces
21446  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
21447  If you use a graphical user interface for the debugger you can skip this
21448  section.
21449 \layout Subsubsection*
21450
21451 break [line | file:line | function | file:function]
21452 \layout Standard
21453
21454 Set breakpoint at specified line or function:
21455 \newline
21456
21457 \newline
21458
21459 \family sans
21460 \series bold
21461 sdcdb>break 100
21462 \newline
21463 sdcdb>break foo.c:100
21464 \newline
21465 sdcdb>break funcfoo
21466 \newline
21467 sdcdb>break foo.c:funcfoo
21468 \layout Subsubsection*
21469
21470 clear [line | file:line | function | file:function ]
21471 \layout Standard
21472
21473 Clear breakpoint at specified line or function:
21474 \newline
21475
21476 \newline
21477
21478 \family sans
21479 \series bold
21480 sdcdb>clear 100
21481 \newline
21482 sdcdb>clear foo.c:100
21483 \newline
21484 sdcdb>clear funcfoo
21485 \newline
21486 sdcdb>clear foo.c:funcfoo
21487 \layout Subsubsection*
21488
21489 continue
21490 \layout Standard
21491
21492 Continue program being debugged, after breakpoint.
21493 \layout Subsubsection*
21494
21495 finish
21496 \layout Standard
21497
21498 Execute till the end of the current function.
21499 \layout Subsubsection*
21500
21501 delete [n]
21502 \layout Standard
21503
21504 Delete breakpoint number 'n'.
21505  If used without any option clear ALL user defined break points.
21506 \layout Subsubsection*
21507
21508 info [break | stack | frame | registers ]
21509 \layout Itemize
21510
21511 info break - list all breakpoints
21512 \layout Itemize
21513
21514 info stack - show the function call stack.
21515 \layout Itemize
21516
21517 info frame - show information about the current execution frame.
21518 \layout Itemize
21519
21520 info registers - show content of all registers.
21521 \layout Subsubsection*
21522
21523 step
21524 \layout Standard
21525
21526 Step program until it reaches a different source line.
21527  Note: pressing <return> repeats the last command.
21528 \layout Subsubsection*
21529
21530 next
21531 \layout Standard
21532
21533 Step program, proceeding through subroutine calls.
21534 \layout Subsubsection*
21535
21536 run
21537 \layout Standard
21538
21539 Start debugged program.
21540 \layout Subsubsection*
21541
21542 ptype variable
21543 \layout Standard
21544
21545 Print type information of the variable.
21546 \layout Subsubsection*
21547
21548 print variable
21549 \layout Standard
21550
21551 print value of variable.
21552 \layout Subsubsection*
21553
21554 file filename
21555 \layout Standard
21556
21557 load the given file name.
21558  Note this is an alternate method of loading file for debugging.
21559 \layout Subsubsection*
21560
21561 frame
21562 \layout Standard
21563
21564 print information about current frame.
21565 \layout Subsubsection*
21566
21567 set srcmode
21568 \layout Standard
21569
21570 Toggle between C source & assembly source.
21571 \layout Subsubsection*
21572
21573 ! simulator command
21574 \layout Standard
21575
21576 Send the string following '!' to the simulator, the simulator response is
21577  displayed.
21578  Note the debugger does not interpret the command being sent to the simulator,
21579  so if a command like 'go' is sent the debugger can loose its execution
21580  context and may display incorrect values.
21581 \layout Subsubsection*
21582
21583 quit
21584 \layout Standard
21585
21586 "Watch me now.
21587  Iam going Down.
21588  My name is Bobby Brown"
21589 \layout Subsection
21590
21591 Interfacing SDCDB with DDD
21592 \layout Comment
21593
21594 The screenshot was converted from png to eps with:
21595 \begin_inset Quotes sld
21596 \end_inset
21597
21598 bmeps -c -e8f -p3 ddd_example.png >ddd_example.eps
21599 \begin_inset Quotes srd
21600 \end_inset
21601
21602  which produces a pretty compact eps file which is free from compression
21603  artifacts.
21604 \layout Comment
21605
21606 The screenshot was included in sdccman.lyx cvs version 1.120 but later removed
21607  as this broke the build system on Sourceforge (pdf-file was broken).
21608 \layout Standard
21609
21610 The .eps File
21611 \size footnotesize
21612
21613 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/doc/figures/ddd_example.eps}
21614
21615 \end_inset
21616
21617
21618 \size default
21619  shows a screenshot of a debugging session with DDD
21620 \begin_inset LatexCommand \index{DDD (debugger)}
21621
21622 \end_inset
21623
21624  (Unix only) on a simulated 8032.
21625  The debugging session might not run as smoothly as the screenshot suggests.
21626  The debugger allows setting of breakpoints, displaying and changing variables,
21627  single stepping through C and assembler code.
21628
21629 \newline
21630 The source was compiled with
21631 \family sans
21632 \series bold
21633
21634 \newline
21635
21636 \newline
21637 sdcc -
21638 \family default
21639 \series default
21640
21641 \begin_inset ERT
21642 status Collapsed
21643
21644 \layout Standard
21645
21646 \backslash
21647 /
21648 \end_inset
21649
21650
21651 \family sans
21652 \series bold
21653 -debug ddd_example.c
21654 \family default
21655 \series default
21656
21657 \family sans
21658 \series bold
21659
21660 \newline
21661
21662 \family default
21663 \series default
21664
21665 \newline
21666 and DDD was invoked with
21667 \family sans
21668 \series bold
21669
21670 \newline
21671
21672 \newline
21673 ddd -debugger 'sdcdb -cpu 8032 ddd_example'
21674 \layout Subsection
21675
21676 Interfacing SDCDB with XEmacs
21677 \begin_inset LatexCommand \index{XEmacs}
21678
21679 \end_inset
21680
21681
21682 \begin_inset LatexCommand \index{Emacs}
21683
21684 \end_inset
21685
21686
21687 \layout Standard
21688
21689 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
21690  sdcdb.el and sdcdbsrc.el.
21691  These two files can be found in the $(prefix)/bin directory after the installat
21692 ion is complete.
21693  These files need to be loaded into XEmacs for the interface to work.
21694  This can be done at XEmacs startup time by inserting the following into
21695  your '.xemacs' file (which can be found in your HOME directory):
21696 \newline
21697
21698 \newline
21699
21700 \family typewriter
21701 (load-file sdcdbsrc.el)
21702 \family default
21703
21704 \newline
21705
21706 \newline
21707 .xemacs is a lisp file so the () around the command is REQUIRED.
21708  The files can also be loaded dynamically while XEmacs is running, set the
21709  environment variable 'EMACSLOADPATH' to the installation bin directory
21710  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
21711  To start the interface enter the following command:
21712 \newline
21713
21714 \newline
21715
21716 \family sans
21717 \series bold
21718 ESC-x sdcdbsrc
21719 \family default
21720 \series default
21721
21722 \newline
21723
21724 \newline
21725 You will prompted to enter the file name to be debugged.
21726
21727 \newline
21728
21729 \newline
21730 The command line options that are passed to the simulator directly are bound
21731  to default values in the file sdcdbsrc.el.
21732  The variables are listed below, these values maybe changed as required.
21733 \layout Itemize
21734
21735 sdcdbsrc-cpu-type '51
21736 \layout Itemize
21737
21738 sdcdbsrc-frequency '11059200
21739 \layout Itemize
21740
21741 sdcdbsrc-serial nil
21742 \layout Standard
21743
21744 The following is a list of key mapping for the debugger interface.
21745 \layout Standard
21746
21747 \SpecialChar ~
21748
21749 \family typewriter
21750
21751 \newline
21752 ;;\SpecialChar ~
21753 Current Listing ::
21754 \newline
21755 ;;key\SpecialChar ~
21756 \SpecialChar ~
21757 \SpecialChar ~
21758 \SpecialChar ~
21759 \SpecialChar ~
21760 \SpecialChar ~
21761 \SpecialChar ~
21762 \SpecialChar ~
21763 \SpecialChar ~
21764 \SpecialChar ~
21765 \SpecialChar ~
21766 \SpecialChar ~
21767 \SpecialChar ~
21768 \SpecialChar ~
21769 binding\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 \SpecialChar ~
21783 \SpecialChar ~
21784 \SpecialChar ~
21785 \SpecialChar ~
21786 \SpecialChar ~
21787 \SpecialChar ~
21788 \SpecialChar ~
21789 \SpecialChar ~
21790 \SpecialChar ~
21791 Comment
21792 \newline
21793 ;;---\SpecialChar ~
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 \SpecialChar ~
21811 \SpecialChar ~
21812 \SpecialChar ~
21813 \SpecialChar ~
21814 \SpecialChar ~
21815 \SpecialChar ~
21816 \SpecialChar ~
21817 \SpecialChar ~
21818 \SpecialChar ~
21819 \SpecialChar ~
21820 \SpecialChar ~
21821 \SpecialChar ~
21822 \SpecialChar ~
21823 \SpecialChar ~
21824 \SpecialChar ~
21825 \SpecialChar ~
21826 \SpecialChar ~
21827 \SpecialChar ~
21828 \SpecialChar ~
21829 -------
21830 \newline
21831 ;;
21832 \newline
21833 ;;\SpecialChar ~
21834 n\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 sdcdb-next-from-src\SpecialChar ~
21850 \SpecialChar ~
21851 \SpecialChar ~
21852 \SpecialChar ~
21853 \SpecialChar ~
21854 \SpecialChar ~
21855 \SpecialChar ~
21856 \SpecialChar ~
21857 \SpecialChar ~
21858 \SpecialChar ~
21859 SDCDB next command
21860 \newline
21861 ;;\SpecialChar ~
21862 b\SpecialChar ~
21863 \SpecialChar ~
21864 \SpecialChar ~
21865 \SpecialChar ~
21866 \SpecialChar ~
21867 \SpecialChar ~
21868 \SpecialChar ~
21869 \SpecialChar ~
21870 \SpecialChar ~
21871 \SpecialChar ~
21872 \SpecialChar ~
21873 \SpecialChar ~
21874 \SpecialChar ~
21875 \SpecialChar ~
21876 \SpecialChar ~
21877 sdcdb-back-from-src\SpecialChar ~
21878 \SpecialChar ~
21879 \SpecialChar ~
21880 \SpecialChar ~
21881 \SpecialChar ~
21882 \SpecialChar ~
21883 \SpecialChar ~
21884 \SpecialChar ~
21885 \SpecialChar ~
21886 \SpecialChar ~
21887 SDCDB back command
21888 \newline
21889 ;;\SpecialChar ~
21890 c\SpecialChar ~
21891 \SpecialChar ~
21892 \SpecialChar ~
21893 \SpecialChar ~
21894 \SpecialChar ~
21895 \SpecialChar ~
21896 \SpecialChar ~
21897 \SpecialChar ~
21898 \SpecialChar ~
21899 \SpecialChar ~
21900 \SpecialChar ~
21901 \SpecialChar ~
21902 \SpecialChar ~
21903 \SpecialChar ~
21904 \SpecialChar ~
21905 sdcdb-cont-from-src\SpecialChar ~
21906 \SpecialChar ~
21907 \SpecialChar ~
21908 \SpecialChar ~
21909 \SpecialChar ~
21910 \SpecialChar ~
21911 \SpecialChar ~
21912 \SpecialChar ~
21913 \SpecialChar ~
21914 \SpecialChar ~
21915 SDCDB continue command
21916 \newline
21917 ;;\SpecialChar ~
21918 s\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 sdcdb-step-from-src\SpecialChar ~
21934 \SpecialChar ~
21935 \SpecialChar ~
21936 \SpecialChar ~
21937 \SpecialChar ~
21938 \SpecialChar ~
21939 \SpecialChar ~
21940 \SpecialChar ~
21941 \SpecialChar ~
21942 \SpecialChar ~
21943 SDCDB step command
21944 \newline
21945 ;;\SpecialChar ~
21946 ?\SpecialChar ~
21947 \SpecialChar ~
21948 \SpecialChar ~
21949 \SpecialChar ~
21950 \SpecialChar ~
21951 \SpecialChar ~
21952 \SpecialChar ~
21953 \SpecialChar ~
21954 \SpecialChar ~
21955 \SpecialChar ~
21956 \SpecialChar ~
21957 \SpecialChar ~
21958 \SpecialChar ~
21959 \SpecialChar ~
21960 \SpecialChar ~
21961 sdcdb-whatis-c-sexp\SpecialChar ~
21962 \SpecialChar ~
21963 \SpecialChar ~
21964 \SpecialChar ~
21965 \SpecialChar ~
21966 \SpecialChar ~
21967 \SpecialChar ~
21968 \SpecialChar ~
21969 \SpecialChar ~
21970 \SpecialChar ~
21971 SDCDB ptypecommand for data at
21972 \newline
21973 ;;\SpecialChar ~
21974 \SpecialChar ~
21975 \SpecialChar ~
21976 \SpecialChar ~
21977 \SpecialChar ~
21978 \SpecialChar ~
21979 \SpecialChar ~
21980 \SpecialChar ~
21981 \SpecialChar ~
21982 \SpecialChar ~
21983 \SpecialChar ~
21984 \SpecialChar ~
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 buffer point
22021 \newline
22022 ;;\SpecialChar ~
22023 x\SpecialChar ~
22024 \SpecialChar ~
22025 \SpecialChar ~
22026 \SpecialChar ~
22027 \SpecialChar ~
22028 \SpecialChar ~
22029 \SpecialChar ~
22030 \SpecialChar ~
22031 \SpecialChar ~
22032 \SpecialChar ~
22033 \SpecialChar ~
22034 \SpecialChar ~
22035 \SpecialChar ~
22036 \SpecialChar ~
22037 \SpecialChar ~
22038 sdcdbsrc-delete\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 SDCDB Delete all breakpoints if no arg
22053 \newline
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 \SpecialChar ~
22082 \SpecialChar ~
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 \SpecialChar ~
22100 \SpecialChar ~
22101 given or delete arg (C-u arg x)
22102 \newline
22103 ;;\SpecialChar ~
22104 m\SpecialChar ~
22105 \SpecialChar ~
22106 \SpecialChar ~
22107 \SpecialChar ~
22108 \SpecialChar ~
22109 \SpecialChar ~
22110 \SpecialChar ~
22111 \SpecialChar ~
22112 \SpecialChar ~
22113 \SpecialChar ~
22114 \SpecialChar ~
22115 \SpecialChar ~
22116 \SpecialChar ~
22117 \SpecialChar ~
22118 \SpecialChar ~
22119 sdcdbsrc-frame\SpecialChar ~
22120 \SpecialChar ~
22121 \SpecialChar ~
22122 \SpecialChar ~
22123 \SpecialChar ~
22124 \SpecialChar ~
22125 \SpecialChar ~
22126 \SpecialChar ~
22127 \SpecialChar ~
22128 \SpecialChar ~
22129 \SpecialChar ~
22130 \SpecialChar ~
22131 \SpecialChar ~
22132 \SpecialChar ~
22133 \SpecialChar ~
22134 SDCDB Display current frame if no arg,
22135 \newline
22136 ;;\SpecialChar ~
22137 \SpecialChar ~
22138 \SpecialChar ~
22139 \SpecialChar ~
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 given or display frame arg
22184 \newline
22185 ;;\SpecialChar ~
22186 \SpecialChar ~
22187 \SpecialChar ~
22188 \SpecialChar ~
22189 \SpecialChar ~
22190 \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 \SpecialChar ~
22206 \SpecialChar ~
22207 \SpecialChar ~
22208 \SpecialChar ~
22209 \SpecialChar ~
22210 \SpecialChar ~
22211 \SpecialChar ~
22212 \SpecialChar ~
22213 \SpecialChar ~
22214 \SpecialChar ~
22215 \SpecialChar ~
22216 \SpecialChar ~
22217 \SpecialChar ~
22218 \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 buffer point
22233 \newline
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 \SpecialChar ~
22250 sdcdbsrc-goto-sdcdb\SpecialChar ~
22251 \SpecialChar ~
22252 \SpecialChar ~
22253 \SpecialChar ~
22254 \SpecialChar ~
22255 \SpecialChar ~
22256 \SpecialChar ~
22257 \SpecialChar ~
22258 \SpecialChar ~
22259 \SpecialChar ~
22260 Goto the SDCDB output buffer
22261 \newline
22262 ;;\SpecialChar ~
22263 p\SpecialChar ~
22264 \SpecialChar ~
22265 \SpecialChar ~
22266 \SpecialChar ~
22267 \SpecialChar ~
22268 \SpecialChar ~
22269 \SpecialChar ~
22270 \SpecialChar ~
22271 \SpecialChar ~
22272 \SpecialChar ~
22273 \SpecialChar ~
22274 \SpecialChar ~
22275 \SpecialChar ~
22276 \SpecialChar ~
22277 \SpecialChar ~
22278 sdcdb-print-c-sexp\SpecialChar ~
22279 \SpecialChar ~
22280 \SpecialChar ~
22281 \SpecialChar ~
22282 \SpecialChar ~
22283 \SpecialChar ~
22284 \SpecialChar ~
22285 \SpecialChar ~
22286 \SpecialChar ~
22287 \SpecialChar ~
22288 \SpecialChar ~
22289 SDCDB print command for data at
22290 \newline
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 \SpecialChar ~
22306 \SpecialChar ~
22307 \SpecialChar ~
22308 \SpecialChar ~
22309 \SpecialChar ~
22310 \SpecialChar ~
22311 \SpecialChar ~
22312 \SpecialChar ~
22313 \SpecialChar ~
22314 \SpecialChar ~
22315 \SpecialChar ~
22316 \SpecialChar ~
22317 \SpecialChar ~
22318 \SpecialChar ~
22319 \SpecialChar ~
22320 \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 \SpecialChar ~
22337 \SpecialChar ~
22338 buffer point
22339 \newline
22340 ;;\SpecialChar ~
22341 g\SpecialChar ~
22342 \SpecialChar ~
22343 \SpecialChar ~
22344 \SpecialChar ~
22345 \SpecialChar ~
22346 \SpecialChar ~
22347 \SpecialChar ~
22348 \SpecialChar ~
22349 \SpecialChar ~
22350 \SpecialChar ~
22351 \SpecialChar ~
22352 \SpecialChar ~
22353 \SpecialChar ~
22354 \SpecialChar ~
22355 \SpecialChar ~
22356 sdcdbsrc-goto-sdcdb\SpecialChar ~
22357 \SpecialChar ~
22358 \SpecialChar ~
22359 \SpecialChar ~
22360 \SpecialChar ~
22361 \SpecialChar ~
22362 \SpecialChar ~
22363 \SpecialChar ~
22364 \SpecialChar ~
22365 \SpecialChar ~
22366 Goto the SDCDB output buffer
22367 \newline
22368 ;;\SpecialChar ~
22369 t\SpecialChar ~
22370 \SpecialChar ~
22371 \SpecialChar ~
22372 \SpecialChar ~
22373 \SpecialChar ~
22374 \SpecialChar ~
22375 \SpecialChar ~
22376 \SpecialChar ~
22377 \SpecialChar ~
22378 \SpecialChar ~
22379 \SpecialChar ~
22380 \SpecialChar ~
22381 \SpecialChar ~
22382 \SpecialChar ~
22383 \SpecialChar ~
22384 sdcdbsrc-mode\SpecialChar ~
22385 \SpecialChar ~
22386 \SpecialChar ~
22387 \SpecialChar ~
22388 \SpecialChar ~
22389 \SpecialChar ~
22390 \SpecialChar ~
22391 \SpecialChar ~
22392 \SpecialChar ~
22393 \SpecialChar ~
22394 \SpecialChar ~
22395 \SpecialChar ~
22396 \SpecialChar ~
22397 \SpecialChar ~
22398 \SpecialChar ~
22399 \SpecialChar ~
22400 Toggles Sdcdbsrc mode (turns it off)
22401 \newline
22402 ;;
22403 \newline
22404 ;;\SpecialChar ~
22405 C-c\SpecialChar ~
22406 C-f\SpecialChar ~
22407 \SpecialChar ~
22408 \SpecialChar ~
22409 \SpecialChar ~
22410 \SpecialChar ~
22411 \SpecialChar ~
22412 \SpecialChar ~
22413 \SpecialChar ~
22414 \SpecialChar ~
22415 sdcdb-finish-from-src\SpecialChar ~
22416 \SpecialChar ~
22417 \SpecialChar ~
22418 \SpecialChar ~
22419 \SpecialChar ~
22420 \SpecialChar ~
22421 \SpecialChar ~
22422 \SpecialChar ~
22423 SDCDB finish command
22424 \newline
22425 ;;
22426 \newline
22427 ;;\SpecialChar ~
22428 C-x\SpecialChar ~
22429 SPC\SpecialChar ~
22430 \SpecialChar ~
22431 \SpecialChar ~
22432 \SpecialChar ~
22433 \SpecialChar ~
22434 \SpecialChar ~
22435 \SpecialChar ~
22436 \SpecialChar ~
22437 \SpecialChar ~
22438 sdcdb-break\SpecialChar ~
22439 \SpecialChar ~
22440 \SpecialChar ~
22441 \SpecialChar ~
22442 \SpecialChar ~
22443 \SpecialChar ~
22444 \SpecialChar ~
22445 \SpecialChar ~
22446 \SpecialChar ~
22447 \SpecialChar ~
22448 \SpecialChar ~
22449 \SpecialChar ~
22450 \SpecialChar ~
22451 \SpecialChar ~
22452 \SpecialChar ~
22453 \SpecialChar ~
22454 \SpecialChar ~
22455 \SpecialChar ~
22456 Set break for line with point
22457 \newline
22458 ;;\SpecialChar ~
22459 ESC\SpecialChar ~
22460 t\SpecialChar ~
22461 \SpecialChar ~
22462 \SpecialChar ~
22463 \SpecialChar ~
22464 \SpecialChar ~
22465 \SpecialChar ~
22466 \SpecialChar ~
22467 \SpecialChar ~
22468 \SpecialChar ~
22469 \SpecialChar ~
22470 \SpecialChar ~
22471 sdcdbsrc-mode\SpecialChar ~
22472 \SpecialChar ~
22473 \SpecialChar ~
22474 \SpecialChar ~
22475 \SpecialChar ~
22476 \SpecialChar ~
22477 \SpecialChar ~
22478 \SpecialChar ~
22479 \SpecialChar ~
22480 \SpecialChar ~
22481 \SpecialChar ~
22482 \SpecialChar ~
22483 \SpecialChar ~
22484 \SpecialChar ~
22485 \SpecialChar ~
22486 \SpecialChar ~
22487 Toggle Sdcdbsrc mode
22488 \newline
22489 ;;\SpecialChar ~
22490 ESC\SpecialChar ~
22491 m\SpecialChar ~
22492 \SpecialChar ~
22493 \SpecialChar ~
22494 \SpecialChar ~
22495 \SpecialChar ~
22496 \SpecialChar ~
22497 \SpecialChar ~
22498 \SpecialChar ~
22499 \SpecialChar ~
22500 \SpecialChar ~
22501 \SpecialChar ~
22502 sdcdbsrc-srcmode\SpecialChar ~
22503 \SpecialChar ~
22504 \SpecialChar ~
22505 \SpecialChar ~
22506 \SpecialChar ~
22507 \SpecialChar ~
22508 \SpecialChar ~
22509 \SpecialChar ~
22510 \SpecialChar ~
22511 \SpecialChar ~
22512 \SpecialChar ~
22513 \SpecialChar ~
22514 \SpecialChar ~
22515 Toggle list mode
22516 \newline
22517 ;;
22518 \newline
22519
22520 \layout Chapter
22521 \pagebreak_top
22522 TIPS
22523 \layout Standard
22524
22525 Here are a few guidelines that will help the compiler generate more efficient
22526  code, some of the tips are specific to this compiler others are generally
22527  good programming practice.
22528 \layout Itemize
22529
22530 Use the smallest data type to represent your data-value.
22531  If it is known in advance that the value is going to be less than 256 then
22532  use an 'unsigned char' instead of a 'short' or 'int'.
22533  Please note, that ANSI C requires both signed and unsigned chars to be
22534  promoted to 'signed int'
22535 \begin_inset LatexCommand \index{promotion to signed int}
22536
22537 \end_inset
22538
22539  before doing any operation.
22540  This promotion
22541 \begin_inset LatexCommand \index{type promotion}
22542
22543 \end_inset
22544
22545
22546 \begin_inset LatexCommand \label{type promotion}
22547
22548 \end_inset
22549
22550  can be omitted, if the result is the same.
22551  The effect of the promotion rules together with the sign-extension is often
22552  surprising:
22553 \begin_deeper
22554 \layout Verse
22555
22556
22557 \family typewriter
22558 unsigned char uc = 0xfe;
22559 \newline
22560 if (uc * uc < 0) /* this is true! */
22561 \newline
22562 {
22563 \newline
22564 \SpecialChar ~
22565 \SpecialChar ~
22566 \SpecialChar ~
22567 \SpecialChar ~
22568 ....
22569 \newline
22570 }
22571 \layout Standard
22572
22573
22574 \family typewriter
22575 uc * uc
22576 \family default
22577  is evaluated as
22578 \family typewriter
22579 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
22580 \family default
22581 .
22582
22583 \newline
22584 Another one:
22585 \layout Verse
22586
22587
22588 \family typewriter
22589 (unsigned char) -12 / (signed char) -3 = ...
22590 \layout Standard
22591
22592 No, the result is not 4:
22593 \layout Verse
22594
22595
22596 \family typewriter
22597 (int) (unsigned char) -12 / (int) (signed char) -3 =
22598 \newline
22599 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
22600 \newline
22601 (int) 0x00f4 / (int) 0xfffd =
22602 \newline
22603 (int) 0x00f4 / (int) 0xfffd =
22604 \newline
22605 (int) 244 / (int) -3 =
22606 \newline
22607 (int) -81 = (int) 0xffaf;
22608 \layout Standard
22609
22610 Don't complain, that gcc gives you a different result.
22611  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
22612  Therefore the results are different.
22613 \newline
22614 From
22615 \begin_inset Quotes sld
22616 \end_inset
22617
22618 comp.lang.c FAQ
22619 \begin_inset Quotes srd
22620 \end_inset
22621
22622 :
22623 \layout Quote
22624
22625 If well-defined overflow characteristics are important and negative values
22626  are not, or if you want to steer clear of sign-extension problems when
22627  manipulating bits or bytes, use one of the corresponding unsigned types.
22628  (Beware when mixing signed and unsigned values in expressions, though.)
22629 \newline
22630 Although character types (especially unsigned char) can be used as "tiny"
22631  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
22632 ble sign extension and increased code size.
22633 \end_deeper
22634 \layout Itemize
22635
22636 Use unsigned when it is known in advance that the value is not going to
22637  be negative.
22638  This helps especially if you are doing division or multiplication, bit-shifting
22639  or are using an array index.
22640 \layout Itemize
22641
22642 NEVER jump into a LOOP.
22643 \layout Itemize
22644
22645 Declare the variables to be local
22646 \begin_inset LatexCommand \index{local variables}
22647
22648 \end_inset
22649
22650  whenever possible, especially loop control variables (induction).
22651 \layout Itemize
22652
22653 Since the compiler does not always do implicit integral promotion, the programme
22654 r should do an explicit cast when integral promotion is required.
22655 \layout Itemize
22656
22657 Reducing the size of division, multiplication & modulus operations can reduce
22658  code size substantially.
22659  Take the following code for example.
22660 \begin_deeper
22661 \layout Verse
22662
22663
22664 \family typewriter
22665 foobar(unsigned int p1, unsigned char ch)
22666 \newline
22667 {
22668 \newline
22669 \SpecialChar ~
22670 \SpecialChar ~
22671 \SpecialChar ~
22672 \SpecialChar ~
22673 unsigned char ch1 = p1 % ch ;
22674 \newline
22675 \SpecialChar ~
22676 \SpecialChar ~
22677 \SpecialChar ~
22678 \SpecialChar ~
22679 ....
22680 \newline
22681 }
22682 \layout Standard
22683
22684 For the modulus operation the variable ch will be promoted to unsigned int
22685  first then the modulus operation will be performed (this will lead to a
22686  call to support routine _moduint()), and the result will be casted to a
22687  char.
22688  If the code is changed to
22689 \layout Verse
22690
22691
22692 \family typewriter
22693 foobar(unsigned int p1, unsigned char ch)
22694 \newline
22695 {
22696 \newline
22697 \SpecialChar ~
22698 \SpecialChar ~
22699 \SpecialChar ~
22700 \SpecialChar ~
22701 unsigned char ch1 = (unsigned char)p1 % ch ;
22702 \newline
22703 \SpecialChar ~
22704 \SpecialChar ~
22705 \SpecialChar ~
22706 \SpecialChar ~
22707 ....
22708 \newline
22709 }
22710 \layout Standard
22711
22712 It would substantially reduce the code generated (future versions of the
22713  compiler will be smart enough to detect such optimization opportunities).
22714 \end_deeper
22715 \layout Itemize
22716
22717 Have a look at the assembly listing to get a
22718 \begin_inset Quotes sld
22719 \end_inset
22720
22721 feeling
22722 \begin_inset Quotes srd
22723 \end_inset
22724
22725  for the code generation.
22726 \layout Section
22727
22728 Porting code from or to other compilers
22729 \layout Itemize
22730
22731 check whether endianness of the compilers differs and adapt where needed.
22732 \layout Itemize
22733
22734 check the device specific header files for compiler specific syntax.
22735  Eventually include the file <compiler.h
22736 \begin_inset LatexCommand \index{compiler.h (include file)}
22737
22738 \end_inset
22739
22740 > to allow using common header files.
22741 \layout Itemize
22742
22743 check whether the startup code contains the correct initialization (watchdog,
22744  peripherals).
22745 \layout Itemize
22746
22747 check whether the sizes of short, int, long match.
22748 \layout Itemize
22749
22750 check if some 16 or 32 bit hardware registers require a specific addressing
22751  order (least significant or most significant byte first) and adapt if needed
22752  (
22753 \emph on
22754 first
22755 \emph default
22756  and
22757 \emph on
22758 last
22759 \emph default
22760  relate to time and not to lower/upper memory location here, so this is
22761
22762 \emph on
22763 not
22764 \emph default
22765  the same as endianness).
22766 \layout Itemize
22767
22768 check whether the keyword
22769 \emph on
22770 volatile
22771 \emph default
22772  is used where needed.
22773  The compilers might differ in their optimization characteristics (as different
22774  versions of the same compiler might also use more clever optimizations
22775  this is good idea anyway).
22776 \layout Itemize
22777
22778 check that the compilers are not told to supress warnings.
22779 \layout Itemize
22780
22781 check and convert compiler specific extensions (interrupts, memory areas,
22782  pragmas etc.).
22783 \layout Itemize
22784
22785 check for differences in type promotion (especially check for math operations
22786  on char variables and for the use of the ~\SpecialChar ~
22787 operator on bit variables.
22788  See
22789 \begin_inset LatexCommand \ref{type promotion}
22790
22791 \end_inset
22792
22793  and
22794 \begin_inset LatexCommand \ref{sec:Compatibility-with-previous}
22795
22796 \end_inset
22797
22798 ).
22799 \layout Itemize
22800
22801 check the assembly code generated for interrupt routines (f.e.
22802  for calls to possibly non-reentrant library functions).
22803 \layout Itemize
22804
22805 check whether timing loops result in proper timing (or preferably consider
22806  a rewrite of the code with timer based delays instead).
22807 \layout Itemize
22808
22809 check for differences in printf parameters (some compilers push (va_arg
22810 \begin_inset LatexCommand \index{va\_arg}
22811
22812 \end_inset
22813
22814 ) char variables as integers others as char).
22815 \layout Itemize
22816
22817 check the resulting memory layout.
22818 \layout Section
22819
22820 Tools
22821 \begin_inset LatexCommand \index{Tools}
22822
22823 \end_inset
22824
22825  included in the distribution
22826 \layout Standard
22827 \align center
22828
22829 \begin_inset  Tabular
22830 <lyxtabular version="3" rows="12" columns="3">
22831 <features>
22832 <column alignment="left" valignment="top" leftline="true" width="0pt">
22833 <column alignment="left" valignment="top" leftline="true" width="0pt">
22834 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
22835 <row topline="true" bottomline="true">
22836 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22837 \begin_inset Text
22838
22839 \layout Standard
22840
22841 Name
22842 \end_inset
22843 </cell>
22844 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22845 \begin_inset Text
22846
22847 \layout Standard
22848
22849 Purpose
22850 \end_inset
22851 </cell>
22852 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22853 \begin_inset Text
22854
22855 \layout Standard
22856
22857 Directory
22858 \end_inset
22859 </cell>
22860 </row>
22861 <row topline="true">
22862 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22863 \begin_inset Text
22864
22865 \layout Standard
22866
22867 ucSsim
22868 \end_inset
22869 </cell>
22870 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22871 \begin_inset Text
22872
22873 \layout Standard
22874
22875 Simulator for various architectures
22876 \end_inset
22877 </cell>
22878 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22879 \begin_inset Text
22880
22881 \layout Standard
22882
22883 sdcc/sim/ucsim
22884 \end_inset
22885 </cell>
22886 </row>
22887 <row topline="true">
22888 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22889 \begin_inset Text
22890
22891 \layout Standard
22892
22893 keil2sdcc.pl
22894 \end_inset
22895 </cell>
22896 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22897 \begin_inset Text
22898
22899 \layout Standard
22900
22901 header file conversion
22902 \end_inset
22903 </cell>
22904 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22905 \begin_inset Text
22906
22907 \layout Standard
22908
22909 sdcc/support/scripts
22910 \end_inset
22911 </cell>
22912 </row>
22913 <row topline="true">
22914 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22915 \begin_inset Text
22916
22917 \layout Standard
22918
22919 mh2h.c
22920 \end_inset
22921 </cell>
22922 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22923 \begin_inset Text
22924
22925 \layout Standard
22926
22927 header file conversion
22928 \end_inset
22929 </cell>
22930 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22931 \begin_inset Text
22932
22933 \layout Standard
22934
22935 sdcc/support/scripts
22936 \end_inset
22937 </cell>
22938 </row>
22939 <row topline="true">
22940 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22941 \begin_inset Text
22942
22943 \layout Standard
22944
22945 as-gbz80
22946 \end_inset
22947 </cell>
22948 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22949 \begin_inset Text
22950
22951 \layout Standard
22952
22953 Assembler
22954 \end_inset
22955 </cell>
22956 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22957 \begin_inset Text
22958
22959 \layout Standard
22960
22961
22962 \family roman
22963 \series medium
22964 \shape up
22965 \size normal
22966 \emph off
22967 \bar no
22968 \noun off
22969 \color none
22970 sdcc/bin
22971 \end_inset
22972 </cell>
22973 </row>
22974 <row topline="true">
22975 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22976 \begin_inset Text
22977
22978 \layout Standard
22979
22980 as-z80
22981 \end_inset
22982 </cell>
22983 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22984 \begin_inset Text
22985
22986 \layout Standard
22987
22988 Assembler
22989 \end_inset
22990 </cell>
22991 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22992 \begin_inset Text
22993
22994 \layout Standard
22995
22996
22997 \family roman
22998 \series medium
22999 \shape up
23000 \size normal
23001 \emph off
23002 \bar no
23003 \noun off
23004 \color none
23005 sdcc/bin
23006 \end_inset
23007 </cell>
23008 </row>
23009 <row topline="true">
23010 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23011 \begin_inset Text
23012
23013 \layout Standard
23014
23015 asx8051
23016 \end_inset
23017 </cell>
23018 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23019 \begin_inset Text
23020
23021 \layout Standard
23022
23023 Assembler
23024 \end_inset
23025 </cell>
23026 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23027 \begin_inset Text
23028
23029 \layout Standard
23030
23031
23032 \family roman
23033 \series medium
23034 \shape up
23035 \size normal
23036 \emph off
23037 \bar no
23038 \noun off
23039 \color none
23040 sdcc/bin
23041 \end_inset
23042 </cell>
23043 </row>
23044 <row topline="true">
23045 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23046 \begin_inset Text
23047
23048 \layout Standard
23049
23050 SDCDB
23051 \end_inset
23052 </cell>
23053 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23054 \begin_inset Text
23055
23056 \layout Standard
23057
23058 Simulator
23059 \end_inset
23060 </cell>
23061 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23062 \begin_inset Text
23063
23064 \layout Standard
23065
23066
23067 \family roman
23068 \series medium
23069 \shape up
23070 \size normal
23071 \emph off
23072 \bar no
23073 \noun off
23074 \color none
23075 sdcc/bin
23076 \end_inset
23077 </cell>
23078 </row>
23079 <row topline="true">
23080 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23081 \begin_inset Text
23082
23083 \layout Standard
23084
23085 aslink
23086 \end_inset
23087 </cell>
23088 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23089 \begin_inset Text
23090
23091 \layout Standard
23092
23093 Linker
23094 \end_inset
23095 </cell>
23096 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23097 \begin_inset Text
23098
23099 \layout Standard
23100
23101
23102 \family roman
23103 \series medium
23104 \shape up
23105 \size normal
23106 \emph off
23107 \bar no
23108 \noun off
23109 \color none
23110 sdcc/bin
23111 \end_inset
23112 </cell>
23113 </row>
23114 <row topline="true">
23115 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23116 \begin_inset Text
23117
23118 \layout Standard
23119
23120 link-z80
23121 \end_inset
23122 </cell>
23123 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23124 \begin_inset Text
23125
23126 \layout Standard
23127
23128 Linker
23129 \end_inset
23130 </cell>
23131 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23132 \begin_inset Text
23133
23134 \layout Standard
23135
23136
23137 \family roman
23138 \series medium
23139 \shape up
23140 \size normal
23141 \emph off
23142 \bar no
23143 \noun off
23144 \color none
23145 sdcc/bin
23146 \end_inset
23147 </cell>
23148 </row>
23149 <row topline="true">
23150 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23151 \begin_inset Text
23152
23153 \layout Standard
23154
23155 link-gbz80
23156 \end_inset
23157 </cell>
23158 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23159 \begin_inset Text
23160
23161 \layout Standard
23162
23163 Linker
23164 \end_inset
23165 </cell>
23166 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23167 \begin_inset Text
23168
23169 \layout Standard
23170
23171
23172 \family roman
23173 \series medium
23174 \shape up
23175 \size normal
23176 \emph off
23177 \bar no
23178 \noun off
23179 \color none
23180 sdcc/bin
23181 \end_inset
23182 </cell>
23183 </row>
23184 <row topline="true" bottomline="true">
23185 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23186 \begin_inset Text
23187
23188 \layout Standard
23189
23190 packihx
23191 \end_inset
23192 </cell>
23193 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23194 \begin_inset Text
23195
23196 \layout Standard
23197
23198 ihx packer
23199 \end_inset
23200 </cell>
23201 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23202 \begin_inset Text
23203
23204 \layout Standard
23205
23206
23207 \family roman
23208 \series medium
23209 \shape up
23210 \size normal
23211 \emph off
23212 \bar no
23213 \noun off
23214 \color none
23215 sdcc/bin
23216 \end_inset
23217 </cell>
23218 </row>
23219 </lyxtabular>
23220
23221 \end_inset
23222
23223
23224 \newline
23225
23226 \layout Section
23227
23228 Documentation
23229 \begin_inset LatexCommand \index{Documentation}
23230
23231 \end_inset
23232
23233  included in the distribution
23234 \layout Standard
23235 \align center
23236
23237 \begin_inset  Tabular
23238 <lyxtabular version="3" rows="10" columns="2">
23239 <features>
23240 <column alignment="left" valignment="top" leftline="true" width="0">
23241 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
23242 <row topline="true" bottomline="true">
23243 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23244 \begin_inset Text
23245
23246 \layout Standard
23247
23248 Subject / Title
23249 \end_inset
23250 </cell>
23251 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23252 \begin_inset Text
23253
23254 \layout Standard
23255
23256 Where to get / filename
23257 \end_inset
23258 </cell>
23259 </row>
23260 <row topline="true">
23261 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23262 \begin_inset Text
23263
23264 \layout Standard
23265
23266 SDCC Compiler User Guide
23267 \end_inset
23268 </cell>
23269 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23270 \begin_inset Text
23271
23272 \layout Standard
23273
23274 You're reading it right now
23275 \end_inset
23276 </cell>
23277 </row>
23278 <row topline="true">
23279 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23280 \begin_inset Text
23281
23282 \layout Standard
23283
23284 Changelog of SDCC
23285 \end_inset
23286 </cell>
23287 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23288 \begin_inset Text
23289
23290 \layout Standard
23291
23292 sdcc/Changelog
23293 \end_inset
23294 </cell>
23295 </row>
23296 <row topline="true">
23297 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23298 \begin_inset Text
23299
23300 \layout Standard
23301
23302 ASXXXX
23303 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
23304
23305 \end_inset
23306
23307
23308 \begin_inset LatexCommand \index{Assembler documentation}
23309
23310 \end_inset
23311
23312  Assemblers and ASLINK
23313 \begin_inset LatexCommand \index{aslink}
23314
23315 \end_inset
23316
23317
23318 \begin_inset LatexCommand \index{Linker documentation}
23319
23320 \end_inset
23321
23322  Relocating Linker
23323 \end_inset
23324 </cell>
23325 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23326 \begin_inset Text
23327
23328 \layout Standard
23329
23330 sdcc/as/doc/asxhtm.html
23331 \end_inset
23332 </cell>
23333 </row>
23334 <row topline="true">
23335 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23336 \begin_inset Text
23337
23338 \layout Standard
23339
23340 SDCC regression test
23341 \begin_inset LatexCommand \index{Regression test}
23342
23343 \end_inset
23344
23345
23346 \end_inset
23347 </cell>
23348 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23349 \begin_inset Text
23350
23351 \layout Standard
23352
23353 sdcc/doc/test_suite_spec.pdf
23354 \end_inset
23355 </cell>
23356 </row>
23357 <row topline="true">
23358 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23359 \begin_inset Text
23360
23361 \layout Standard
23362
23363 Various notes
23364 \end_inset
23365 </cell>
23366 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23367 \begin_inset Text
23368
23369 \layout Standard
23370
23371 sdcc/doc/*
23372 \end_inset
23373 </cell>
23374 </row>
23375 <row topline="true">
23376 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23377 \begin_inset Text
23378
23379 \layout Standard
23380
23381 Notes on debugging with SDCDB
23382 \begin_inset LatexCommand \index{SDCDB (debugger)}
23383
23384 \end_inset
23385
23386
23387 \end_inset
23388 </cell>
23389 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23390 \begin_inset Text
23391
23392 \layout Standard
23393
23394 sdcc/debugger/README
23395 \end_inset
23396 </cell>
23397 </row>
23398 <row topline="true">
23399 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23400 \begin_inset Text
23401
23402 \layout Standard
23403
23404 Software simulator for microcontrollers
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 \family roman
23414 \series medium
23415 \shape up
23416 \size normal
23417 \emph off
23418 \bar no
23419 \noun off
23420 \color none
23421 sdcc/sim/ucsim/doc
23422 \family default
23423 \series default
23424 \shape default
23425 \size default
23426 \emph default
23427 \bar default
23428 \noun default
23429 \color default
23430 /index.html
23431 \end_inset
23432 </cell>
23433 </row>
23434 <row topline="true">
23435 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23436 \begin_inset Text
23437
23438 \layout Standard
23439
23440 Temporary notes on the pic16
23441 \begin_inset LatexCommand \index{PIC16}
23442
23443 \end_inset
23444
23445  port
23446 \end_inset
23447 </cell>
23448 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23449 \begin_inset Text
23450
23451 \layout Standard
23452
23453 sdcc/src/pic16/NOTES
23454 \end_inset
23455 </cell>
23456 </row>
23457 <row topline="true" bottomline="true">
23458 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23459 \begin_inset Text
23460
23461 \layout Standard
23462
23463 SDCC internal documentation (debugging file format)
23464 \end_inset
23465 </cell>
23466 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23467 \begin_inset Text
23468
23469 \layout Standard
23470
23471 sdcc/doc/
23472 \family roman
23473 \series medium
23474 \shape up
23475 \size normal
23476 \emph off
23477 \bar no
23478 \noun off
23479 \color none
23480 cdbfileformat.pd
23481 \family default
23482 \series default
23483 \shape default
23484 \size default
23485 \emph default
23486 \bar default
23487 \noun default
23488 \color default
23489 f
23490 \end_inset
23491 </cell>
23492 </row>
23493 </lyxtabular>
23494
23495 \end_inset
23496
23497
23498 \newline
23499
23500 \layout Section
23501
23502 Related open source tools
23503 \begin_inset LatexCommand \label{sec:Related-open-source-tools}
23504
23505 \end_inset
23506
23507
23508 \begin_inset LatexCommand \index{Related tools}
23509
23510 \end_inset
23511
23512
23513 \layout Standard
23514 \align center
23515
23516 \begin_inset  Tabular
23517 <lyxtabular version="3" rows="14" columns="3">
23518 <features>
23519 <column alignment="left" valignment="top" leftline="true" width="0pt">
23520 <column alignment="block" valignment="top" leftline="true" width="30line%">
23521 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
23522 <row topline="true" bottomline="true">
23523 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23524 \begin_inset Text
23525
23526 \layout Standard
23527
23528 Name
23529 \end_inset
23530 </cell>
23531 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23532 \begin_inset Text
23533
23534 \layout Standard
23535
23536 Purpose
23537 \end_inset
23538 </cell>
23539 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23540 \begin_inset Text
23541
23542 \layout Standard
23543
23544 Where to get
23545 \end_inset
23546 </cell>
23547 </row>
23548 <row topline="true">
23549 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23550 \begin_inset Text
23551
23552 \layout Standard
23553
23554 gpsim
23555 \begin_inset LatexCommand \index{gpsim (pic simulator)}
23556
23557 \end_inset
23558
23559
23560 \end_inset
23561 </cell>
23562 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23563 \begin_inset Text
23564
23565 \layout Standard
23566
23567 PIC simulator
23568 \end_inset
23569 </cell>
23570 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23571 \begin_inset Text
23572
23573 \layout Standard
23574
23575
23576 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
23577
23578 \end_inset
23579
23580
23581 \end_inset
23582 </cell>
23583 </row>
23584 <row topline="true">
23585 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23586 \begin_inset Text
23587
23588 \layout Standard
23589
23590 gputils
23591 \begin_inset LatexCommand \index{gputils (pic tools)}
23592
23593 \end_inset
23594
23595
23596 \end_inset
23597 </cell>
23598 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23599 \begin_inset Text
23600
23601 \layout Standard
23602
23603 GNU PIC utilities
23604 \end_inset
23605 </cell>
23606 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23607 \begin_inset Text
23608
23609 \layout Standard
23610
23611
23612 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
23613
23614 \end_inset
23615
23616
23617 \end_inset
23618 </cell>
23619 </row>
23620 <row topline="true">
23621 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23622 \begin_inset Text
23623
23624 \layout Standard
23625
23626 flP5
23627 \end_inset
23628 </cell>
23629 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23630 \begin_inset Text
23631
23632 \layout Standard
23633
23634 PIC programmer
23635 \end_inset
23636 </cell>
23637 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23638 \begin_inset Text
23639
23640 \layout Standard
23641
23642
23643 \begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/}
23644
23645 \end_inset
23646
23647
23648 \end_inset
23649 </cell>
23650 </row>
23651 <row topline="true">
23652 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23653 \begin_inset Text
23654
23655 \layout Standard
23656
23657 ec2drv/newcdb
23658 \end_inset
23659 </cell>
23660 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23661 \begin_inset Text
23662
23663 \layout Standard
23664
23665 Tools for Silicon Laboratories JTAG debug adapter, partly based on SDCDB
23666  (Unix only)
23667 \end_inset
23668 </cell>
23669 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23670 \begin_inset Text
23671
23672 \layout Standard
23673
23674
23675 \begin_inset LatexCommand \url{http://sourceforge.net/projects/ec2drv}
23676
23677 \end_inset
23678
23679
23680 \end_inset
23681 </cell>
23682 </row>
23683 <row topline="true">
23684 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23685 \begin_inset Text
23686
23687 \layout Standard
23688
23689 indent
23690 \begin_inset LatexCommand \index{indent (source formatting tool)}
23691
23692 \end_inset
23693
23694
23695 \end_inset
23696 </cell>
23697 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23698 \begin_inset Text
23699
23700 \layout Standard
23701
23702 Formats C source - Master of the white spaces
23703 \end_inset
23704 </cell>
23705 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23706 \begin_inset Text
23707
23708 \layout Standard
23709
23710
23711 \begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html}
23712
23713 \end_inset
23714
23715
23716 \end_inset
23717 </cell>
23718 </row>
23719 <row topline="true">
23720 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23721 \begin_inset Text
23722
23723 \layout Standard
23724
23725 srecord
23726 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
23727
23728 \end_inset
23729
23730
23731 \end_inset
23732 </cell>
23733 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23734 \begin_inset Text
23735
23736 \layout Standard
23737
23738 Object file conversion, checksumming, ...
23739 \end_inset
23740 </cell>
23741 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23742 \begin_inset Text
23743
23744 \layout Standard
23745
23746
23747 \begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord}
23748
23749 \end_inset
23750
23751
23752 \end_inset
23753 </cell>
23754 </row>
23755 <row topline="true">
23756 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23757 \begin_inset Text
23758
23759 \layout Standard
23760
23761 objdump
23762 \begin_inset LatexCommand \index{objdump (tool)}
23763
23764 \end_inset
23765
23766
23767 \end_inset
23768 </cell>
23769 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23770 \begin_inset Text
23771
23772 \layout Standard
23773
23774 Object file conversion, ...
23775 \end_inset
23776 </cell>
23777 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23778 \begin_inset Text
23779
23780 \layout Standard
23781
23782 Part of binutils (should be there anyway)
23783 \end_inset
23784 </cell>
23785 </row>
23786 <row topline="true">
23787 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23788 \begin_inset Text
23789
23790 \layout Standard
23791
23792 cmon51
23793 \end_inset
23794 </cell>
23795 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23796 \begin_inset Text
23797
23798 \layout Standard
23799
23800 8051 monitor (hex up-/download, single step, disassemble)
23801 \end_inset
23802 </cell>
23803 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23804 \begin_inset Text
23805
23806 \layout Standard
23807
23808
23809 \begin_inset LatexCommand \url{http://sourceforge.net/projects/cmon51}
23810
23811 \end_inset
23812
23813
23814 \end_inset
23815 </cell>
23816 </row>
23817 <row topline="true">
23818 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23819 \begin_inset Text
23820
23821 \layout Standard
23822
23823 doxygen
23824 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
23825
23826 \end_inset
23827
23828
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 Source code documentation system
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
23845 \begin_inset LatexCommand \url{http://www.doxygen.org}
23846
23847 \end_inset
23848
23849
23850 \end_inset
23851 </cell>
23852 </row>
23853 <row topline="true">
23854 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23855 \begin_inset Text
23856
23857 \layout Standard
23858
23859 kdevelop
23860 \end_inset
23861 </cell>
23862 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23863 \begin_inset Text
23864
23865 \layout Standard
23866
23867 IDE (has anyone tried integrating SDCC & SDCDB? Unix only)
23868 \end_inset
23869 </cell>
23870 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23871 \begin_inset Text
23872
23873 \layout Standard
23874
23875
23876 \begin_inset LatexCommand \url{http://www.kdevelop.org}
23877
23878 \end_inset
23879
23880
23881 \end_inset
23882 </cell>
23883 </row>
23884 <row topline="true">
23885 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23886 \begin_inset Text
23887
23888 \layout Standard
23889
23890 paulmon
23891 \end_inset
23892 </cell>
23893 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23894 \begin_inset Text
23895
23896 \layout Standard
23897
23898 8051 monitor (hex up-/download, single step, disassemble)
23899 \end_inset
23900 </cell>
23901 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23902 \begin_inset Text
23903
23904 \layout Standard
23905
23906
23907 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/paulmon2.html}
23908
23909 \end_inset
23910
23911
23912 \end_inset
23913 </cell>
23914 </row>
23915 <row topline="true">
23916 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23917 \begin_inset Text
23918
23919 \layout Standard
23920
23921 splint
23922 \begin_inset LatexCommand \index{splint (syntax checking tool)}
23923
23924 \end_inset
23925
23926
23927 \end_inset
23928 </cell>
23929 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23930 \begin_inset Text
23931
23932 \layout Standard
23933
23934 Statically checks c sources (see
23935 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
23936
23937 \end_inset
23938
23939 )
23940 \end_inset
23941 </cell>
23942 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23943 \begin_inset Text
23944
23945 \layout Standard
23946
23947
23948 \begin_inset LatexCommand \url{http://www.splint.org}
23949
23950 \end_inset
23951
23952
23953 \end_inset
23954 </cell>
23955 </row>
23956 <row topline="true" bottomline="true">
23957 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23958 \begin_inset Text
23959
23960 \layout Standard
23961
23962 ddd
23963 \begin_inset LatexCommand \index{ddd (debugger)}
23964
23965 \end_inset
23966
23967
23968 \end_inset
23969 </cell>
23970 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23971 \begin_inset Text
23972
23973 \layout Standard
23974
23975 Debugger, serves nicely as GUI to SDCDB
23976 \begin_inset LatexCommand \index{SDCDB (debugger)}
23977
23978 \end_inset
23979
23980  (Unix only)
23981 \end_inset
23982 </cell>
23983 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23984 \begin_inset Text
23985
23986 \layout Standard
23987
23988
23989 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
23990
23991 \end_inset
23992
23993
23994 \end_inset
23995 </cell>
23996 </row>
23997 </lyxtabular>
23998
23999 \end_inset
24000
24001
24002 \newline
24003
24004 \layout Section
24005
24006 Related documentation / recommended reading
24007 \layout Standard
24008 \align center
24009
24010 \begin_inset  Tabular
24011 <lyxtabular version="3" rows="8" columns="3">
24012 <features>
24013 <column alignment="left" valignment="top" leftline="true" width="0pt">
24014 <column alignment="block" valignment="top" leftline="true" width="30line%">
24015 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
24016 <row topline="true" bottomline="true">
24017 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24018 \begin_inset Text
24019
24020 \layout Standard
24021
24022 Name
24023 \end_inset
24024 </cell>
24025 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24026 \begin_inset Text
24027
24028 \layout Standard
24029
24030 Subject / Title
24031 \end_inset
24032 </cell>
24033 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24034 \begin_inset Text
24035
24036 \layout Standard
24037
24038 Where to get
24039 \end_inset
24040 </cell>
24041 </row>
24042 <row topline="true">
24043 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24044 \begin_inset Text
24045
24046 \layout Standard
24047
24048
24049 \family roman
24050 \series medium
24051 \shape up
24052 \size normal
24053 \emph off
24054 \bar no
24055 \noun off
24056 \color none
24057 c-refcard.pdf
24058 \end_inset
24059 </cell>
24060 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24061 \begin_inset Text
24062
24063 \layout Standard
24064
24065 C Reference Card
24066 \begin_inset LatexCommand \index{C Reference card}
24067
24068 \end_inset
24069
24070 , 2 pages
24071 \end_inset
24072 </cell>
24073 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24074 \begin_inset Text
24075
24076 \layout Standard
24077
24078
24079 \begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html}
24080
24081 \end_inset
24082
24083
24084 \end_inset
24085 </cell>
24086 </row>
24087 <row topline="true">
24088 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24089 \begin_inset Text
24090
24091 \layout Standard
24092
24093 c-faq
24094 \end_inset
24095 </cell>
24096 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24097 \begin_inset Text
24098
24099 \layout Standard
24100
24101 C-FAQ-list
24102 \end_inset
24103 </cell>
24104 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24105 \begin_inset Text
24106
24107 \layout Standard
24108
24109
24110 \begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
24111
24112 \end_inset
24113
24114
24115 \end_inset
24116 </cell>
24117 </row>
24118 <row topline="true">
24119 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24120 \begin_inset Text
24121
24122 \layout Standard
24123
24124 ISO/IEC 9899:TC2
24125 \end_inset
24126 </cell>
24127 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24128 \begin_inset Text
24129
24130 \layout Standard
24131
24132
24133 \begin_inset Quotes sld
24134 \end_inset
24135
24136 C-Standard
24137 \begin_inset Quotes srd
24138 \end_inset
24139
24140
24141 \end_inset
24142 </cell>
24143 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24144 \begin_inset Text
24145
24146 \layout Standard
24147
24148
24149 \size footnotesize
24150
24151 \begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899}
24152
24153 \end_inset
24154
24155
24156 \end_inset
24157 </cell>
24158 </row>
24159 <row topline="true">
24160 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24161 \begin_inset Text
24162
24163 \layout Standard
24164
24165 ISO/IEC DTR 18037
24166 \end_inset
24167 </cell>
24168 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24169 \begin_inset Text
24170
24171 \layout Standard
24172
24173
24174 \begin_inset Quotes sld
24175 \end_inset
24176
24177 Extensions for Embedded C
24178 \begin_inset Quotes srd
24179 \end_inset
24180
24181
24182 \end_inset
24183 </cell>
24184 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24185 \begin_inset Text
24186
24187 \layout Standard
24188
24189
24190 \size footnotesize
24191
24192 \begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1021.pdf}
24193
24194 \end_inset
24195
24196
24197 \end_inset
24198 </cell>
24199 </row>
24200 <row topline="true">
24201 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24202 \begin_inset Text
24203
24204 \layout Standard
24205
24206 \end_inset
24207 </cell>
24208 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24209 \begin_inset Text
24210
24211 \layout Standard
24212
24213 Latest datasheet of the target CPU
24214 \end_inset
24215 </cell>
24216 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24217 \begin_inset Text
24218
24219 \layout Standard
24220
24221 vendor
24222 \end_inset
24223 </cell>
24224 </row>
24225 <row topline="true">
24226 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24227 \begin_inset Text
24228
24229 \layout Standard
24230
24231 \end_inset
24232 </cell>
24233 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24234 \begin_inset Text
24235
24236 \layout Standard
24237
24238 Revision history of datasheet
24239 \end_inset
24240 </cell>
24241 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24242 \begin_inset Text
24243
24244 \layout Standard
24245
24246 vendor
24247 \end_inset
24248 </cell>
24249 </row>
24250 <row topline="true" bottomline="true">
24251 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24252 \begin_inset Text
24253
24254 \layout Standard
24255
24256 S.
24257  S.
24258  Muchnick
24259 \end_inset
24260 </cell>
24261 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24262 \begin_inset Text
24263
24264 \layout Standard
24265
24266 Advanced Compiler Design and Implementation
24267 \end_inset
24268 </cell>
24269 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24270 \begin_inset Text
24271
24272 \layout Standard
24273
24274 bookstore (very dedicated, probably read other books first)
24275 \end_inset
24276 </cell>
24277 </row>
24278 </lyxtabular>
24279
24280 \end_inset
24281
24282
24283 \newline
24284
24285 \layout Section
24286
24287 Some Questions
24288 \layout Standard
24289
24290 Some questions answered, some pointers given - it might be time to in turn
24291  ask
24292 \emph on
24293 you
24294 \emph default
24295  some questions:
24296 \layout Itemize
24297
24298 can you solve your project with the selected microcontroller? Would you
24299  find out early or rather late that your target is too small/slow/whatever?
24300  Can you switch to a slightly better device if it doesn't fit?
24301 \layout Itemize
24302
24303 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
24304  and/or another programming language be more adequate? Would an operating
24305  system on the target device help?
24306 \layout Itemize
24307
24308 if you solved the problem, will the marketing department be happy?
24309 \layout Itemize
24310
24311 if the marketing department is happy, will customers be happy?
24312 \layout Itemize
24313
24314 if you're the project manager, marketing department and maybe even the customer
24315  in one person, have you tried to see the project from the outside?
24316 \layout Itemize
24317
24318 is the project done if you think it is done? Or is just that other interface/pro
24319 tocol/feature/configuration/option missing? How about website, manual(s),
24320  internationali(z|s)ation, packaging, labels, 2nd source for components,
24321  electromagnetic compatability/interference, documentation for production,
24322  production test software, update mechanism, patent issues?
24323 \layout Itemize
24324
24325 is your project adequately positioned in that magic triangle: fame, fortune,
24326  fun?
24327 \layout Standard
24328
24329 Maybe not all answers to these questions are known and some answers may
24330  even be
24331 \emph on
24332 no
24333 \emph default
24334 , nevertheless knowing these questions may help you to avoid burnout
24335 \begin_inset Foot
24336 collapsed false
24337
24338 \layout Standard
24339
24340 burnout is bad for electronic devices, programmers and motorcycle tyres
24341 \end_inset
24342
24343 .
24344  Chances are you didn't want to hear some of them...
24345 \layout Chapter
24346
24347 Support
24348 \begin_inset LatexCommand \index{Support}
24349
24350 \end_inset
24351
24352
24353 \layout Standard
24354
24355 SDCC has grown to be a large project.
24356  The compiler alone (without the preprocessor, assembler and linker) is
24357  well over 100,000 lines of code (blank stripped).
24358  The open source nature of this project is a key to its continued growth
24359  and support.
24360  You gain the benefit and support of many active software developers and
24361  end users.
24362  Is SDCC perfect? No, that's why we need your help.
24363  The developers take pride in fixing reported bugs.
24364  You can help by reporting the bugs and helping other SDCC users.
24365  There are lots of ways to contribute, and we encourage you to take part
24366  in making SDCC a great software package.
24367
24368 \layout Standard
24369
24370 The SDCC project is hosted on the SDCC sourceforge site at
24371 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
24372
24373 \end_inset
24374
24375 .
24376  You'll find the complete set of mailing lists
24377 \begin_inset LatexCommand \index{Mailing list(s)}
24378
24379 \end_inset
24380
24381 , forums, bug reporting system, patch submission
24382 \begin_inset LatexCommand \index{Patch submission}
24383
24384 \end_inset
24385
24386  system, download
24387 \begin_inset LatexCommand \index{download}
24388
24389 \end_inset
24390
24391  area and Subversion code repository
24392 \begin_inset LatexCommand \index{Subversion code repository}
24393
24394 \end_inset
24395
24396  there.
24397 \layout Section
24398
24399 Reporting Bugs
24400 \begin_inset LatexCommand \index{Bug reporting}
24401
24402 \end_inset
24403
24404
24405 \begin_inset LatexCommand \index{Reporting bugs}
24406
24407 \end_inset
24408
24409
24410 \layout Standard
24411
24412 The recommended way of reporting bugs is using the infrastructure of the
24413  sourceforge site.
24414  You can follow the status of bug reports there and have an overview about
24415  the known bugs.
24416 \layout Standard
24417
24418 Bug reports are automatically forwarded to the developer mailing list and
24419  will be fixed ASAP.
24420  When reporting a bug, it is very useful to include a small test program
24421  (the smaller the better) which reproduces the problem.
24422  If you can isolate the problem by looking at the generated assembly code,
24423  this can be very helpful.
24424  Compiling your program with the -
24425 \begin_inset ERT
24426 status Collapsed
24427
24428 \layout Standard
24429
24430 \backslash
24431 /
24432 \end_inset
24433
24434 -dumpall
24435 \begin_inset LatexCommand \index{-\/-dumpall}
24436
24437 \end_inset
24438
24439  option can sometimes be useful in locating optimization problems.
24440  When reporting a bug please maker sure you:
24441 \layout Enumerate
24442
24443 Attach the code you are compiling with SDCC.
24444
24445 \layout Enumerate
24446
24447 Specify the exact command you use to run SDCC, or attach your Makefile.
24448
24449 \layout Enumerate
24450
24451 Specify the SDCC version (type "
24452 \family sans
24453 \series bold
24454 sdcc -v
24455 \family default
24456 \series default
24457 "), your platform, and operating system.
24458
24459 \layout Enumerate
24460
24461 Provide an exact copy of any error message or incorrect output.
24462
24463 \layout Enumerate
24464
24465 Put something meaningful in the subject of your message.
24466 \layout Standard
24467
24468 Please attempt to include these 5 important parts, as applicable, in all
24469  requests for support or when reporting any problems or bugs with SDCC.
24470  Though this will make your message lengthy, it will greatly improve your
24471  chance that SDCC users and developers will be able to help you.
24472  Some SDCC developers are frustrated by bug reports without code provided
24473  that they can use to reproduce and ultimately fix the problem, so please
24474  be sure to provide sample code if you are reporting a bug!
24475 \layout Standard
24476
24477 Please have a short check that you are using a recent version of SDCC and
24478  the bug is not yet known.
24479  This is the link for reporting bugs:
24480 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
24481
24482 \end_inset
24483
24484 .
24485 \layout Section
24486
24487 Requesting Features
24488 \begin_inset LatexCommand \label{sub:Requesting-Features}
24489
24490 \end_inset
24491
24492
24493 \begin_inset LatexCommand \index{Feature request}
24494
24495 \end_inset
24496
24497
24498 \begin_inset LatexCommand \index{Requesting features}
24499
24500 \end_inset
24501
24502
24503 \layout Standard
24504
24505 Like bug reports feature requests are forwarded to the developer mailing
24506  list.
24507  This is the link for requesting features:
24508 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
24509
24510 \end_inset
24511
24512 .
24513 \layout Section
24514
24515 Submitting patches
24516 \layout Standard
24517
24518 Like bug reports contributed patches are forwarded to the developer mailing
24519  list.
24520  This is the link for submitting patches
24521 \begin_inset LatexCommand \index{Patch submission}
24522
24523 \end_inset
24524
24525 :
24526 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
24527
24528 \end_inset
24529
24530 .
24531 \layout Standard
24532
24533 You need to specify some parameters to the
24534 \family typewriter
24535 diff
24536 \family default
24537  command for the patches to be useful.
24538  If you modified more than one file a patch created f.e.
24539  with
24540 \family sans
24541 \series bold
24542
24543 \begin_inset Quotes sld
24544 \end_inset
24545
24546 diff -Naur unmodified_directory modified_directory >my_changes.patch
24547 \begin_inset Quotes srd
24548 \end_inset
24549
24550
24551 \family default
24552 \series default
24553  will be fine, otherwise
24554 \family sans
24555 \series bold
24556
24557 \begin_inset Quotes sld
24558 \end_inset
24559
24560 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
24561 \begin_inset Quotes srd
24562 \end_inset
24563
24564
24565 \series default
24566
24567 \family default
24568 will do.
24569 \layout Section
24570
24571 Getting Help
24572 \layout Standard
24573
24574 These links should take you directly to the
24575 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
24576
24577 \end_inset
24578
24579
24580 \begin_inset Foot
24581 collapsed false
24582
24583 \layout Standard
24584
24585 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
24586  automated messages (mid 2003)
24587 \end_inset
24588
24589  and the
24590 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
24591
24592 \end_inset
24593
24594 , lists
24595 \begin_inset LatexCommand \index{Mailing list(s)}
24596
24597 \end_inset
24598
24599  and forums are archived and searchable so if you are lucky someone already
24600  had a similar problem.
24601  While mails to the lists themselves are delivered promptly their web front
24602  end on sourceforge sometimes shows a severe time lag (up to several weeks),
24603  if you're seriously using SDCC please consider subscribing to the lists.
24604 \layout Section
24605
24606 ChangeLog
24607 \layout Standard
24608
24609 You can follow the status of the Subversion version
24610 \begin_inset LatexCommand \index{version}
24611
24612 \end_inset
24613
24614  of SDCC by watching the Changelog
24615 \begin_inset LatexCommand \index{Changelog}
24616
24617 \end_inset
24618
24619  in the Subversion repository
24620 \size footnotesize
24621
24622 \begin_inset LatexCommand \htmlurl{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/ChangeLog}
24623
24624 \end_inset
24625
24626 .
24627 \layout Section
24628
24629 Subversion Source Code Repository
24630 \layout Standard
24631
24632 The output of
24633 \family sans
24634 \series bold
24635 sdcc --version
24636 \family default
24637 \series default
24638  or the filenames of the snapshot versions of SDCC include date and its
24639  Subversion
24640 \begin_inset LatexCommand \index{Subversion}
24641
24642 \end_inset
24643
24644  number.
24645  Subversion allows to download the source of recent or previous versions
24646
24647 \begin_inset LatexCommand \url{http://sourceforge.net/svn/?group_id=599}
24648
24649 \end_inset
24650
24651  (by number or by date).
24652  An on-line source code browser and detailled instructions are also available
24653  there.
24654  SDCC versions starting from 1999 up to now are available (currently the
24655  versions prior to the conversion from cvs to Subversion (April 2006) are
24656  either by accessible by Subversion or by cvs).
24657 \layout Section
24658
24659 Release policy
24660 \begin_inset LatexCommand \index{Release policy}
24661
24662 \end_inset
24663
24664
24665 \layout Standard
24666
24667 Historically there often were long delays between official releases and
24668  the sourceforge download area tends to get not updated at all.
24669  Excuses in the past might have referred to problems with live range analysis,
24670  but as this was fixed a while ago, the current problem is that another
24671  excuse has to be found.
24672  Kidding aside, we have to get better there! On the other hand there are
24673  daily snapshots available at
24674 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
24675
24676 \end_inset
24677
24678 , and you can always build the very last version (hopefully with many bugs
24679  fixed, and features added) from the source code available at
24680 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
24681
24682 \end_inset
24683
24684 .
24685 \layout Section
24686
24687 Examples
24688 \begin_inset LatexCommand \index{Examples}
24689
24690 \end_inset
24691
24692
24693 \layout Standard
24694
24695 You'll find some small examples in the directory
24696 \emph on
24697 sdcc/device/examples/.
24698
24699 \emph default
24700 More examples and libraries are available at
24701 \emph on
24702  The SDCC Open Knowledge Resource
24703 \begin_inset LatexCommand \url{http://sdccokr.dl9sec.de/}
24704
24705 \end_inset
24706
24707
24708 \emph default
24709 web site or at
24710 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
24711
24712 \end_inset
24713
24714 .
24715 \layout Comment
24716
24717 I did insert a reference to Paul's web site here although it seems rather
24718  dedicated to a specific 8032 board (I think it's okay because it f.e.
24719  shows LCD/Harddisc interface and has a free 8051 monitor.
24720  Independent 8032 board vendors face hard competition of heavily subsidized
24721  development boards anyway).
24722 \layout Comment
24723
24724 Maybe we should include some links to real world applications.
24725  Preferably pointer to pointers (one for each architecture) so this stays
24726  manageable here?
24727 \layout Section
24728
24729 Quality control
24730 \begin_inset LatexCommand \index{Quality control}
24731
24732 \end_inset
24733
24734
24735 \layout Standard
24736
24737 The compiler is passed through nightly compile and build checks.
24738  The so called
24739 \shape italic
24740 regression tests
24741 \shape default
24742
24743 \begin_inset LatexCommand \index{Regression test}
24744
24745 \end_inset
24746
24747  check that SDCC itself compiles flawlessly on several platforms and checks
24748  the quality of the code generated by SDCC by running the code through simulator
24749 s.
24750  There is a separate document
24751 \shape italic
24752 test_suite.pdf
24753 \begin_inset LatexCommand \index{Test suite}
24754
24755 \end_inset
24756
24757
24758 \shape default
24759  about this.
24760 \layout Standard
24761
24762 You'll find the test code in the directory
24763 \shape italic
24764 sdcc/support/regression
24765 \shape default
24766 .
24767  You can run these tests manually by running
24768 \family sans
24769 make
24770 \family default
24771  in this directory (or f.e.
24772
24773 \family sans
24774 \series bold
24775
24776 \begin_inset Quotes sld
24777 \end_inset
24778
24779 make test-mcs51
24780 \begin_inset Quotes srd
24781 \end_inset
24782
24783
24784 \family default
24785 \series default
24786  if you don't want to run the complete tests).
24787  The test code might also be interesting if you want to look for examples
24788 \begin_inset LatexCommand \index{Examples}
24789
24790 \end_inset
24791
24792  checking corner cases of SDCC or if you plan to submit patches
24793 \begin_inset LatexCommand \index{Patch submission}
24794
24795 \end_inset
24796
24797 .
24798 \layout Standard
24799
24800 The pic port uses a different set of regression tests, you'll find them
24801  in the directory
24802 \shape italic
24803 sdcc/src/regression
24804 \shape default
24805 .
24806 \layout Section
24807
24808 Use of SDCC in Education
24809 \layout Standard
24810
24811 In short:
24812 \emph on
24813 highly
24814 \emph default
24815  encouraged
24816 \begin_inset Foot
24817 collapsed false
24818
24819 \layout Standard
24820
24821 the phrase "use in education" might evoke the association "
24822 \emph on
24823 only
24824 \emph default
24825  fit for use in education".
24826  This connotation is not intended but nevertheless risked as the licensing
24827  of SDCC makes it difficult to offer educational discounts
24828 \end_inset
24829
24830 .
24831  If your rationales are to:
24832 \layout Enumerate
24833
24834 give students a chance to understand the
24835 \emph on
24836 complete
24837 \emph default
24838  steps of code generation
24839 \layout Enumerate
24840
24841 have a curriculum that can be extended for years.
24842  Then you could use an fpga board as target and your curriculum will seamlessly
24843  extend from logic synthesis (
24844 \begin_inset LatexCommand \url[http://www.opencores.org]{opencores.org}
24845
24846 \end_inset
24847
24848 ,
24849 \begin_inset LatexCommand \url[Oregano]{http://www.oregano.at/ip/ip01.htm}
24850
24851 \end_inset
24852
24853 ), over assembly programming, to C to FPGA compilers (
24854 \begin_inset LatexCommand \url[FPGAC]{http://sf.net/projects/fpgac}
24855
24856 \end_inset
24857
24858 ) and to C.
24859 \layout Enumerate
24860
24861 be able to insert excursions about skills like using a revision control
24862  system, submitting/applying patches, using a type-setting (as opposed to
24863  word-processing) engine LyX/LaTeX, using
24864 \begin_inset LatexCommand \url[SourceForge]{http://www.sf.net}
24865
24866 \end_inset
24867
24868 , following some
24869 \begin_inset LatexCommand \url[netiquette]{http://en.wikipedia.org/wiki/Netiquette}
24870
24871 \end_inset
24872
24873 , understanding BSD/LGPL/GPL/Proprietary licensing, growth models of Open
24874  Source Software, CPU simulation, compiler regression tests
24875 \begin_inset LatexCommand \index{Regression test}
24876
24877 \end_inset
24878
24879 .
24880
24881 \newline
24882 And if there should be a shortage of ideas then you can always point students
24883  to the ever-growing feature request list
24884 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
24885
24886 \end_inset
24887
24888 .
24889 \layout Enumerate
24890
24891 not tie students to a specific host platform and instead allow them to use
24892  a host platform of
24893 \emph on
24894 their
24895 \emph default
24896  choice (among them Alpha, i386, i386_64, MacOs, Mips, Sparc, Windows and
24897  eventually
24898 \begin_inset LatexCommand \url[OLPC]{http://wiki.laptop.org/wiki/One_Laptop_per_Child}
24899
24900 \end_inset
24901
24902 )
24903 \layout Enumerate
24904
24905 not encourage students to use illegal copies of educational software
24906 \layout Enumerate
24907
24908 be immune to licensing/availability/price changes of the chosen tool chain
24909 \layout Enumerate
24910
24911 be able to change to a new target platform without having to adopt a new
24912  tool chain
24913 \layout Enumerate
24914
24915 have complete control over and insight into the tool chain
24916 \layout Enumerate
24917
24918 make your students aware about the pros and cons of open source software
24919  development
24920 \layout Enumerate
24921
24922 give back to the public as you are probably at least partially publically
24923  funded
24924 \layout Enumerate
24925
24926 give students a chance to publically prove their skills and to possibly
24927  see a world wide impact
24928 \layout Standard
24929
24930 then SDCC is probably among the first choices.
24931  Well, probably SDCC might be the only choice.
24932 \layout Chapter
24933 \pagebreak_top
24934 SDCC Technical Data
24935 \layout Section
24936
24937 Optimizations
24938 \begin_inset LatexCommand \index{Optimizations}
24939
24940 \end_inset
24941
24942
24943 \layout Standard
24944
24945 SDCC performs a host of standard optimizations in addition to some MCU specific
24946  optimizations.
24947
24948 \layout Subsection
24949
24950 Sub-expression Elimination
24951 \begin_inset LatexCommand \index{Subexpression elimination}
24952
24953 \end_inset
24954
24955
24956 \layout Standard
24957
24958 The compiler does local and
24959 \emph on
24960 g
24961 \emph default
24962 lobal
24963 \emph on
24964 c
24965 \emph default
24966 ommon
24967 \emph on
24968 s
24969 \emph default
24970 ubexpression
24971 \emph on
24972 e
24973 \emph default
24974 limination, e.g.:
24975 \layout Verse
24976
24977
24978 \family typewriter
24979 i = x + y + 1;
24980 \newline
24981 j = x + y;
24982 \layout Standard
24983
24984 will be translated to
24985 \layout Verse
24986
24987
24988 \family typewriter
24989 iTemp = x + y;
24990 \newline
24991 i = iTemp + 1;
24992 \newline
24993 j = iTemp;
24994 \layout Standard
24995
24996 Some subexpressions are not as obvious as the above example, e.g.:
24997 \layout Verse
24998
24999
25000 \family typewriter
25001 a->b[i].c = 10;
25002 \newline
25003 a->b[i].d = 11;
25004 \layout Standard
25005
25006 In this case the address arithmetic a->b[i] will be computed only once;
25007  the equivalent code in C would be.
25008 \layout Verse
25009
25010
25011 \family typewriter
25012 iTemp = a->b[i];
25013 \newline
25014 iTemp.c = 10;
25015 \newline
25016 iTemp.d = 11;
25017 \layout Standard
25018
25019 The compiler will try to keep these temporary variables in registers.
25020 \layout Subsection
25021
25022 Dead-Code Elimination
25023 \begin_inset LatexCommand \index{Dead-code elimination}
25024
25025 \end_inset
25026
25027
25028 \layout Verse
25029
25030
25031 \family typewriter
25032 int global;
25033 \newline
25034
25035 \newline
25036 void f () {
25037 \newline
25038 \SpecialChar ~
25039 \SpecialChar ~
25040 int i;
25041 \newline
25042 \SpecialChar ~
25043 \SpecialChar ~
25044 i = 1; \SpecialChar ~
25045 \SpecialChar ~
25046 \SpecialChar ~
25047 \SpecialChar ~
25048 \SpecialChar ~
25049 /* dead store */
25050 \newline
25051 \SpecialChar ~
25052 \SpecialChar ~
25053 global = 1;\SpecialChar ~
25054 /* dead store */
25055 \newline
25056 \SpecialChar ~
25057 \SpecialChar ~
25058 global = 2;
25059 \newline
25060 \SpecialChar ~
25061 \SpecialChar ~
25062 return;
25063 \newline
25064 \SpecialChar ~
25065 \SpecialChar ~
25066 global = 3;\SpecialChar ~
25067 /* unreachable */
25068 \newline
25069 }
25070 \layout Standard
25071
25072 will be changed to
25073 \layout Verse
25074
25075
25076 \family typewriter
25077 int global;
25078 \newline
25079
25080 \newline
25081 void f () {
25082 \newline
25083 \SpecialChar ~
25084 \SpecialChar ~
25085 global = 2;
25086 \newline
25087 }
25088 \layout Subsection
25089
25090 Copy-Propagation
25091 \begin_inset LatexCommand \index{Copy propagation}
25092
25093 \end_inset
25094
25095
25096 \layout Verse
25097
25098
25099 \family typewriter
25100 int f() {
25101 \newline
25102 \SpecialChar ~
25103 \SpecialChar ~
25104 int i, j;
25105 \newline
25106 \SpecialChar ~
25107 \SpecialChar ~
25108 i = 10;
25109 \newline
25110 \SpecialChar ~
25111 \SpecialChar ~
25112 j = i;
25113 \newline
25114 \SpecialChar ~
25115 \SpecialChar ~
25116 return j;
25117 \newline
25118 }
25119 \layout Standard
25120
25121 will be changed to
25122 \layout Verse
25123
25124
25125 \family typewriter
25126 int f() {
25127 \newline
25128 \SpecialChar ~
25129 \SpecialChar ~
25130 int i, j;
25131 \newline
25132 \SpecialChar ~
25133 \SpecialChar ~
25134 i = 10;
25135 \newline
25136 \SpecialChar ~
25137 \SpecialChar ~
25138 j = 10;
25139 \newline
25140 \SpecialChar ~
25141 \SpecialChar ~
25142 return 10;
25143 \newline
25144 }
25145 \layout Standard
25146
25147 Note: the dead stores created by this copy propagation will be eliminated
25148  by dead-code elimination.
25149 \layout Subsection
25150
25151 Loop Optimizations
25152 \begin_inset LatexCommand \index{Loop optimization}
25153
25154 \end_inset
25155
25156
25157 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
25158
25159 \end_inset
25160
25161
25162 \layout Standard
25163
25164 Two types of loop optimizations are done by SDCC
25165 \emph on
25166 loop invariant
25167 \emph default
25168  lifting and
25169 \emph on
25170  strength reduction
25171 \emph default
25172  of loop induction variables.
25173  In addition to the strength reduction the optimizer marks the induction
25174  variables and the register allocator tries to keep the induction variables
25175  in registers for the duration of the loop.
25176  Because of this preference of the register allocator
25177 \begin_inset LatexCommand \index{Register allocation}
25178
25179 \end_inset
25180
25181 , loop induction optimization causes an increase in register pressure, which
25182  may cause unwanted spilling of other temporary variables into the stack
25183 \begin_inset LatexCommand \index{stack}
25184
25185 \end_inset
25186
25187  / data space.
25188  The compiler will generate a warning message when it is forced to allocate
25189  extra space either on the stack or data space.
25190  If this extra space allocation is undesirable then induction optimization
25191  can be eliminated either for the entire source file (with -
25192 \begin_inset ERT
25193 status Collapsed
25194
25195 \layout Standard
25196
25197 \backslash
25198 /
25199 \end_inset
25200
25201 -noinduction option) or for a given function only using #pragma\SpecialChar ~
25202 noinduction
25203 \begin_inset LatexCommand \index{\#pragma noinduction}
25204
25205 \end_inset
25206
25207 .
25208 \newline
25209
25210 \newline
25211 Loop Invariant:
25212 \layout Verse
25213
25214
25215 \family typewriter
25216 for (i = 0 ; i < 100 ; i ++)
25217 \newline
25218 \SpecialChar ~
25219 \SpecialChar ~
25220 \SpecialChar ~
25221 \SpecialChar ~
25222 f += k + l;
25223 \layout Standard
25224
25225 changed to
25226 \layout Verse
25227
25228
25229 \family typewriter
25230 itemp = k + l;
25231 \newline
25232 for (i = 0; i < 100; i++)
25233 \newline
25234 \SpecialChar ~
25235 \SpecialChar ~
25236 \SpecialChar ~
25237 \SpecialChar ~
25238 f += itemp;
25239 \layout Standard
25240
25241 As mentioned previously some loop invariants are not as apparent, all static
25242  address computations are also moved out of the loop.
25243 \newline
25244
25245 \newline
25246 Strength Reduction
25247 \begin_inset LatexCommand \index{Strength reduction}
25248
25249 \end_inset
25250
25251 , this optimization substitutes an expression by a cheaper expression:
25252 \layout Verse
25253
25254
25255 \family typewriter
25256 for (i=0;i < 100; i++)
25257 \newline
25258 \SpecialChar ~
25259 \SpecialChar ~
25260 \SpecialChar ~
25261 \SpecialChar ~
25262 ar[i*5] = i*3;
25263 \layout Standard
25264
25265 changed to
25266 \layout Verse
25267
25268
25269 \family typewriter
25270 itemp1 = 0;
25271 \newline
25272 itemp2 = 0;
25273 \newline
25274 for (i=0;i< 100;i++) {
25275 \newline
25276 \SpecialChar ~
25277 \SpecialChar ~
25278 \SpecialChar ~
25279 \SpecialChar ~
25280 ar[itemp1] = itemp2;
25281 \newline
25282 \SpecialChar ~
25283 \SpecialChar ~
25284 \SpecialChar ~
25285 \SpecialChar ~
25286 itemp1 += 5;
25287 \newline
25288 \SpecialChar ~
25289 \SpecialChar ~
25290 \SpecialChar ~
25291 \SpecialChar ~
25292 itemp2 += 3;
25293 \newline
25294 }
25295 \layout Standard
25296
25297 The more expensive multiplication
25298 \begin_inset LatexCommand \index{Multiplication}
25299
25300 \end_inset
25301
25302  is changed to a less expensive addition.
25303 \layout Subsection
25304
25305 Loop Reversing
25306 \begin_inset LatexCommand \index{Loop reversing}
25307
25308 \end_inset
25309
25310
25311 \layout Standard
25312
25313 This optimization is done to reduce the overhead of checking loop boundaries
25314  for every iteration.
25315  Some simple loops can be reversed and implemented using a
25316 \begin_inset Quotes eld
25317 \end_inset
25318
25319 decrement and jump if not zero
25320 \begin_inset Quotes erd
25321 \end_inset
25322
25323  instruction.
25324  SDCC checks for the following criterion to determine if a loop is reversible
25325  (note: more sophisticated compilers use data-dependency analysis to make
25326  this determination, SDCC uses a more simple minded analysis).
25327 \layout Itemize
25328
25329 The 'for' loop is of the form
25330 \newline
25331
25332 \newline
25333
25334 \family typewriter
25335 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
25336  += 1])
25337 \newline
25338 \SpecialChar ~
25339 \SpecialChar ~
25340 \SpecialChar ~
25341 \SpecialChar ~
25342 <for body>
25343 \layout Itemize
25344
25345 The <for body> does not contain
25346 \begin_inset Quotes eld
25347 \end_inset
25348
25349 continue
25350 \begin_inset Quotes erd
25351 \end_inset
25352
25353  or 'break
25354 \begin_inset Quotes erd
25355 \end_inset
25356
25357 .
25358 \layout Itemize
25359
25360 All goto's are contained within the loop.
25361 \layout Itemize
25362
25363 No function calls within the loop.
25364 \layout Itemize
25365
25366 The loop control variable <sym> is not assigned any value within the loop
25367 \layout Itemize
25368
25369 The loop control variable does NOT participate in any arithmetic operation
25370  within the loop.
25371 \layout Itemize
25372
25373 There are NO switch statements in the loop.
25374 \layout Subsection
25375
25376 Algebraic Simplifications
25377 \layout Standard
25378
25379 SDCC does numerous algebraic simplifications, the following is a small sub-set
25380  of these optimizations.
25381 \layout Verse
25382
25383
25384 \family typewriter
25385 i = j + 0;\SpecialChar ~
25386 \SpecialChar ~
25387 \SpecialChar ~
25388 \SpecialChar ~
25389  /* changed to: */\SpecialChar ~
25390 \SpecialChar ~
25391 \SpecialChar ~
25392 \SpecialChar ~
25393  i = j;
25394 \newline
25395 i /= 2;\SpecialChar ~
25396 \SpecialChar ~
25397 \SpecialChar ~
25398 \SpecialChar ~
25399 \SpecialChar ~
25400 \SpecialChar ~
25401 \SpecialChar ~
25402  /* changed to: */\SpecialChar ~
25403 \SpecialChar ~
25404 \SpecialChar ~
25405 \SpecialChar ~
25406  i >>= 1;
25407 \newline
25408 i = j - j;\SpecialChar ~
25409 \SpecialChar ~
25410 \SpecialChar ~
25411 \SpecialChar ~
25412  /* changed to: */\SpecialChar ~
25413 \SpecialChar ~
25414 \SpecialChar ~
25415 \SpecialChar ~
25416  i = 0;
25417 \newline
25418 i = j / 1;\SpecialChar ~
25419 \SpecialChar ~
25420 \SpecialChar ~
25421 \SpecialChar ~
25422  /* changed to: */\SpecialChar ~
25423 \SpecialChar ~
25424 \SpecialChar ~
25425 \SpecialChar ~
25426  i = j;
25427 \layout Standard
25428
25429 Note the subexpressions
25430 \begin_inset LatexCommand \index{Subexpression}
25431
25432 \end_inset
25433
25434  given above are generally introduced by macro expansions or as a result
25435  of copy/constant propagation.
25436 \layout Subsection
25437
25438 'switch' Statements
25439 \begin_inset LatexCommand \label{sub:'switch'-Statements}
25440
25441 \end_inset
25442
25443
25444 \begin_inset LatexCommand \index{switch statement}
25445
25446 \end_inset
25447
25448
25449 \layout Standard
25450
25451 SDCC can optimize switch statements to jump tables
25452 \begin_inset LatexCommand \index{jump tables}
25453
25454 \end_inset
25455
25456 .
25457  It makes the decision based on an estimate of the generated code size.
25458  SDCC is quite liberal in the requirements for jump table generation:
25459 \layout Itemize
25460
25461 The labels need not be in order, and the starting number need not be one
25462  or zero, the case labels are in numerical sequence or not too many case
25463  labels are missing.
25464 \begin_deeper
25465 \layout Verse
25466
25467
25468 \family typewriter
25469 switch(i) {\SpecialChar ~
25470 \SpecialChar ~
25471 \SpecialChar ~
25472 \SpecialChar ~
25473 \SpecialChar ~
25474 \SpecialChar ~
25475 \SpecialChar ~
25476 \SpecialChar ~
25477 \SpecialChar ~
25478 \SpecialChar ~
25479 \SpecialChar ~
25480 \SpecialChar ~
25481 \SpecialChar ~
25482 \SpecialChar ~
25483 \SpecialChar ~
25484 \SpecialChar ~
25485 \SpecialChar ~
25486 \SpecialChar ~
25487 \SpecialChar ~
25488 \SpecialChar ~
25489 \SpecialChar ~
25490 \SpecialChar ~
25491 \SpecialChar ~
25492 \SpecialChar ~
25493 \SpecialChar ~
25494 \SpecialChar ~
25495 switch (i) {
25496 \newline
25497 \SpecialChar ~
25498 \SpecialChar ~
25499 \SpecialChar ~
25500 case 4: ...\SpecialChar ~
25501 \SpecialChar ~
25502 \SpecialChar ~
25503 \SpecialChar ~
25504 \SpecialChar ~
25505 \SpecialChar ~
25506 \SpecialChar ~
25507 \SpecialChar ~
25508 \SpecialChar ~
25509 \SpecialChar ~
25510 \SpecialChar ~
25511 \SpecialChar ~
25512 \SpecialChar ~
25513 \SpecialChar ~
25514 \SpecialChar ~
25515 \SpecialChar ~
25516 \SpecialChar ~
25517 \SpecialChar ~
25518 \SpecialChar ~
25519 \SpecialChar ~
25520 \SpecialChar ~
25521 \SpecialChar ~
25522 \SpecialChar ~
25523 \SpecialChar ~
25524 \SpecialChar ~
25525 \SpecialChar ~
25526 case 0: ...
25527
25528 \newline
25529 \SpecialChar ~
25530 \SpecialChar ~
25531 \SpecialChar ~
25532 case 5: ...\SpecialChar ~
25533 \SpecialChar ~
25534 \SpecialChar ~
25535 \SpecialChar ~
25536 \SpecialChar ~
25537 \SpecialChar ~
25538 \SpecialChar ~
25539 \SpecialChar ~
25540 \SpecialChar ~
25541 \SpecialChar ~
25542 \SpecialChar ~
25543 \SpecialChar ~
25544 \SpecialChar ~
25545 \SpecialChar ~
25546 \SpecialChar ~
25547 \SpecialChar ~
25548 \SpecialChar ~
25549 \SpecialChar ~
25550 \SpecialChar ~
25551 \SpecialChar ~
25552 \SpecialChar ~
25553 \SpecialChar ~
25554 \SpecialChar ~
25555 \SpecialChar ~
25556 \SpecialChar ~
25557 \SpecialChar ~
25558 case 1: ...
25559
25560 \newline
25561 \SpecialChar ~
25562 \SpecialChar ~
25563 \SpecialChar ~
25564 case 3: ...\SpecialChar ~
25565 \SpecialChar ~
25566 \SpecialChar ~
25567 \SpecialChar ~
25568 \SpecialChar ~
25569 \SpecialChar ~
25570 \SpecialChar ~
25571 \SpecialChar ~
25572 \SpecialChar ~
25573 \SpecialChar ~
25574 \SpecialChar ~
25575 \SpecialChar ~
25576 \SpecialChar ~
25577 \SpecialChar ~
25578 \SpecialChar ~
25579 \SpecialChar ~
25580 \SpecialChar ~
25581 \SpecialChar ~
25582 \SpecialChar ~
25583 \SpecialChar ~
25584 \SpecialChar ~
25585 \SpecialChar ~
25586 \SpecialChar ~
25587 \SpecialChar ~
25588 \SpecialChar ~
25589 \SpecialChar ~
25590
25591 \newline
25592 \SpecialChar ~
25593 \SpecialChar ~
25594 \SpecialChar ~
25595 case 6: ...\SpecialChar ~
25596 \SpecialChar ~
25597 \SpecialChar ~
25598 \SpecialChar ~
25599 \SpecialChar ~
25600 \SpecialChar ~
25601 \SpecialChar ~
25602 \SpecialChar ~
25603 \SpecialChar ~
25604 \SpecialChar ~
25605 \SpecialChar ~
25606 \SpecialChar ~
25607 \SpecialChar ~
25608 \SpecialChar ~
25609 \SpecialChar ~
25610 \SpecialChar ~
25611 \SpecialChar ~
25612 \SpecialChar ~
25613 \SpecialChar ~
25614 \SpecialChar ~
25615 \SpecialChar ~
25616 \SpecialChar ~
25617 \SpecialChar ~
25618 \SpecialChar ~
25619 \SpecialChar ~
25620 \SpecialChar ~
25621 case 3: ...
25622
25623 \newline
25624 \SpecialChar ~
25625 \SpecialChar ~
25626 \SpecialChar ~
25627 case 7: ...\SpecialChar ~
25628 \SpecialChar ~
25629 \SpecialChar ~
25630 \SpecialChar ~
25631 \SpecialChar ~
25632 \SpecialChar ~
25633 \SpecialChar ~
25634 \SpecialChar ~
25635 \SpecialChar ~
25636 \SpecialChar ~
25637 \SpecialChar ~
25638 \SpecialChar ~
25639 \SpecialChar ~
25640 \SpecialChar ~
25641 \SpecialChar ~
25642 \SpecialChar ~
25643 \SpecialChar ~
25644 \SpecialChar ~
25645 \SpecialChar ~
25646 \SpecialChar ~
25647 \SpecialChar ~
25648 \SpecialChar ~
25649 \SpecialChar ~
25650 \SpecialChar ~
25651 \SpecialChar ~
25652 \SpecialChar ~
25653 case 4: ...
25654
25655 \newline
25656 \SpecialChar ~
25657 \SpecialChar ~
25658 \SpecialChar ~
25659 case 8: ...\SpecialChar ~
25660 \SpecialChar ~
25661 \SpecialChar ~
25662 \SpecialChar ~
25663 \SpecialChar ~
25664 \SpecialChar ~
25665 \SpecialChar ~
25666 \SpecialChar ~
25667 \SpecialChar ~
25668 \SpecialChar ~
25669 \SpecialChar ~
25670 \SpecialChar ~
25671 \SpecialChar ~
25672 \SpecialChar ~
25673 \SpecialChar ~
25674 \SpecialChar ~
25675 \SpecialChar ~
25676 \SpecialChar ~
25677 \SpecialChar ~
25678 \SpecialChar ~
25679 \SpecialChar ~
25680 \SpecialChar ~
25681 \SpecialChar ~
25682 \SpecialChar ~
25683 \SpecialChar ~
25684 \SpecialChar ~
25685 case 5: ...
25686
25687 \newline
25688 \SpecialChar ~
25689 \SpecialChar ~
25690 \SpecialChar ~
25691 case 9: ...\SpecialChar ~
25692 \SpecialChar ~
25693 \SpecialChar ~
25694 \SpecialChar ~
25695 \SpecialChar ~
25696 \SpecialChar ~
25697 \SpecialChar ~
25698 \SpecialChar ~
25699 \SpecialChar ~
25700 \SpecialChar ~
25701 \SpecialChar ~
25702 \SpecialChar ~
25703 \SpecialChar ~
25704 \SpecialChar ~
25705 \SpecialChar ~
25706 \SpecialChar ~
25707 \SpecialChar ~
25708 \SpecialChar ~
25709 \SpecialChar ~
25710 \SpecialChar ~
25711 \SpecialChar ~
25712 \SpecialChar ~
25713 \SpecialChar ~
25714 \SpecialChar ~
25715 \SpecialChar ~
25716 \SpecialChar ~
25717 case 6: ...
25718
25719 \newline
25720 \SpecialChar ~
25721 \SpecialChar ~
25722 \SpecialChar ~
25723 case 10: ...\SpecialChar ~
25724 \SpecialChar ~
25725 \SpecialChar ~
25726 \SpecialChar ~
25727 \SpecialChar ~
25728 \SpecialChar ~
25729 \SpecialChar ~
25730 \SpecialChar ~
25731 \SpecialChar ~
25732 \SpecialChar ~
25733 \SpecialChar ~
25734 \SpecialChar ~
25735 \SpecialChar ~
25736 \SpecialChar ~
25737 \SpecialChar ~
25738 \SpecialChar ~
25739 \SpecialChar ~
25740 \SpecialChar ~
25741 \SpecialChar ~
25742 \SpecialChar ~
25743 \SpecialChar ~
25744 \SpecialChar ~
25745 \SpecialChar ~
25746 \SpecialChar ~
25747 \SpecialChar ~
25748 case 7: ...
25749
25750 \newline
25751 \SpecialChar ~
25752 \SpecialChar ~
25753 \SpecialChar ~
25754 case 11: ...\SpecialChar ~
25755 \SpecialChar ~
25756 \SpecialChar ~
25757 \SpecialChar ~
25758 \SpecialChar ~
25759 \SpecialChar ~
25760 \SpecialChar ~
25761 \SpecialChar ~
25762 \SpecialChar ~
25763 \SpecialChar ~
25764 \SpecialChar ~
25765 \SpecialChar ~
25766 \SpecialChar ~
25767 \SpecialChar ~
25768 \SpecialChar ~
25769 \SpecialChar ~
25770 \SpecialChar ~
25771 \SpecialChar ~
25772 \SpecialChar ~
25773 \SpecialChar ~
25774 \SpecialChar ~
25775 \SpecialChar ~
25776 \SpecialChar ~
25777 \SpecialChar ~
25778 \SpecialChar ~
25779 case 8: ...
25780
25781 \newline
25782 }\SpecialChar ~
25783 \SpecialChar ~
25784 \SpecialChar ~
25785 \SpecialChar ~
25786 \SpecialChar ~
25787 \SpecialChar ~
25788 \SpecialChar ~
25789 \SpecialChar ~
25790 \SpecialChar ~
25791 \SpecialChar ~
25792 \SpecialChar ~
25793 \SpecialChar ~
25794 \SpecialChar ~
25795 \SpecialChar ~
25796 \SpecialChar ~
25797 \SpecialChar ~
25798 \SpecialChar ~
25799 \SpecialChar ~
25800 \SpecialChar ~
25801 \SpecialChar ~
25802 \SpecialChar ~
25803 \SpecialChar ~
25804 \SpecialChar ~
25805 \SpecialChar ~
25806 \SpecialChar ~
25807 \SpecialChar ~
25808 \SpecialChar ~
25809 \SpecialChar ~
25810 \SpecialChar ~
25811 \SpecialChar ~
25812 \SpecialChar ~
25813 \SpecialChar ~
25814 \SpecialChar ~
25815 \SpecialChar ~
25816 \SpecialChar ~
25817 \SpecialChar ~
25818 }
25819 \layout Standard
25820
25821 Both the above switch statements will be implemented using a jump-table.
25822  The example to the right side is slightly more efficient as the check for
25823  the lower boundary of the jump-table is not needed.
25824 \end_deeper
25825 \layout Itemize
25826
25827 The number of case labels is not larger than supported by the target architectur
25828 e.
25829 \layout Itemize
25830
25831 If the case labels are not in numerical sequence ('gaps' between cases)
25832  SDCC checks whether a jump table with additionally inserted dummy cases
25833  is still attractive.
25834
25835 \layout Itemize
25836
25837 If the starting number is not zero and a check for the lower boundary of
25838  the jump-table can thus be eliminated SDCC might insert dummy cases 0,
25839  ...
25840  .
25841 \layout Standard
25842
25843 Switch statements which have large gaps in the numeric sequence or those
25844  that have too many case labels can be split into more than one switch statement
25845  for efficient code generation, e.g.:
25846 \layout Verse
25847
25848
25849 \family typewriter
25850 switch (i) {
25851 \newline
25852 \SpecialChar ~
25853 \SpecialChar ~
25854 case 1: ...
25855
25856 \newline
25857 \SpecialChar ~
25858 \SpecialChar ~
25859 case 2: ...
25860
25861 \newline
25862 \SpecialChar ~
25863 \SpecialChar ~
25864 case 3: ...
25865
25866 \newline
25867 \SpecialChar ~
25868 \SpecialChar ~
25869 case 4: ...
25870
25871 \newline
25872 \SpecialChar ~
25873 \SpecialChar ~
25874 case 5: ...
25875
25876 \newline
25877 \SpecialChar ~
25878 \SpecialChar ~
25879 case 6: ...
25880
25881 \newline
25882 \SpecialChar ~
25883 \SpecialChar ~
25884 case 7: ...
25885
25886 \newline
25887 \SpecialChar ~
25888 \SpecialChar ~
25889 case 101: ...
25890
25891 \newline
25892 \SpecialChar ~
25893 \SpecialChar ~
25894 case 102: ...
25895
25896 \newline
25897 \SpecialChar ~
25898 \SpecialChar ~
25899 case 103: ...
25900
25901 \newline
25902 \SpecialChar ~
25903 \SpecialChar ~
25904 case 104: ...
25905
25906 \newline
25907 \SpecialChar ~
25908 \SpecialChar ~
25909 case 105: ...
25910
25911 \newline
25912 \SpecialChar ~
25913 \SpecialChar ~
25914 case 106: ...
25915
25916 \newline
25917 \SpecialChar ~
25918 \SpecialChar ~
25919 case 107: ...
25920
25921 \newline
25922 }
25923 \layout Standard
25924
25925 If the above switch statement is broken down into two switch statements
25926 \layout Verse
25927
25928
25929 \family typewriter
25930 switch (i) {
25931 \newline
25932 \SpecialChar ~
25933 \SpecialChar ~
25934 case 1: ...
25935
25936 \newline
25937 \SpecialChar ~
25938 \SpecialChar ~
25939 case 2: ...
25940
25941 \newline
25942 \SpecialChar ~
25943 \SpecialChar ~
25944 case 3: ...
25945
25946 \newline
25947 \SpecialChar ~
25948 \SpecialChar ~
25949 case 4: ...
25950
25951 \newline
25952 \SpecialChar ~
25953 \SpecialChar ~
25954 case 5: ...
25955
25956 \newline
25957 \SpecialChar ~
25958 \SpecialChar ~
25959 case 6: ...
25960
25961 \newline
25962 \SpecialChar ~
25963 \SpecialChar ~
25964 case 7: ...
25965
25966 \newline
25967 }
25968 \layout Standard
25969
25970 and
25971 \layout Verse
25972
25973
25974 \family typewriter
25975 switch (i) {
25976 \newline
25977 \SpecialChar ~
25978 \SpecialChar ~
25979 case 101: ...
25980
25981 \newline
25982 \SpecialChar ~
25983 \SpecialChar ~
25984 case 102: ...
25985
25986 \newline
25987 \SpecialChar ~
25988 \SpecialChar ~
25989 case 103: ...
25990
25991 \newline
25992 \SpecialChar ~
25993 \SpecialChar ~
25994 case 104: ...
25995
25996 \newline
25997 \SpecialChar ~
25998 \SpecialChar ~
25999 case 105: ...
26000
26001 \newline
26002 \SpecialChar ~
26003 \SpecialChar ~
26004 case 106: ...
26005
26006 \newline
26007 \SpecialChar ~
26008 \SpecialChar ~
26009 case 107: ...
26010
26011 \newline
26012 }
26013 \layout Standard
26014
26015 then both the switch statements will be implemented using jump-tables whereas
26016  the unmodified switch statement will not be.
26017 \layout Comment
26018
26019 There might be reasons which SDCC cannot know about to either favour or
26020  not favour jump tables.
26021  If the target system has to be as quick for the last switch case as for
26022  the first (pro jump table), or if the switch argument is known to be zero
26023  in the majority of the cases (contra jump table).
26024 \layout Standard
26025
26026 The pragma nojtbound
26027 \begin_inset LatexCommand \index{\#pragma nojtbound}
26028
26029 \end_inset
26030
26031  can be used to turn off checking the
26032 \emph on
26033 j
26034 \emph default
26035 ump
26036 \emph on
26037 t
26038 \emph default
26039 able
26040 \emph on
26041 bound
26042 \emph default
26043 aries.
26044  It has no effect if a default label is supplied.
26045  Use of this pragma is dangerous: if the switch
26046 \begin_inset LatexCommand \index{switch statement}
26047
26048 \end_inset
26049
26050  argument is not matched by a case statement the processor will happily
26051  jump into Nirvana.
26052 \layout Subsection
26053
26054 Bit-shifting Operations
26055 \begin_inset LatexCommand \index{Bit shifting}
26056
26057 \end_inset
26058
26059 .
26060 \layout Standard
26061
26062 Bit shifting is one of the most frequently used operation in embedded programmin
26063 g.
26064  SDCC tries to implement bit-shift operations in the most efficient way
26065  possible, e.g.:
26066 \layout Verse
26067
26068
26069 \family typewriter
26070 unsigned char i;
26071 \newline
26072 ...
26073
26074 \newline
26075 i >>= 4;
26076 \newline
26077 ...
26078 \layout Standard
26079
26080 generates the following code:
26081 \layout Verse
26082
26083
26084 \family typewriter
26085 mov\SpecialChar ~
26086  a,_i
26087 \newline
26088 swap a
26089 \newline
26090 anl\SpecialChar ~
26091  a,#0x0f
26092 \newline
26093 mov\SpecialChar ~
26094  _i,a
26095 \layout Standard
26096
26097 In general SDCC will never setup a loop if the shift count is known.
26098  Another example:
26099 \layout Verse
26100
26101
26102 \family typewriter
26103 unsigned int i;
26104 \newline
26105 ...
26106
26107 \newline
26108 i >>= 9;
26109 \newline
26110 ...
26111 \layout Standard
26112
26113 will generate:
26114 \layout Verse
26115
26116
26117 \family typewriter
26118 mov\SpecialChar ~
26119 \SpecialChar ~
26120 a,(_i + 1)
26121 \newline
26122 mov\SpecialChar ~
26123 \SpecialChar ~
26124 (_i + 1),#0x00
26125 \newline
26126 clr\SpecialChar ~
26127 \SpecialChar ~
26128 c
26129 \newline
26130 rrc\SpecialChar ~
26131 \SpecialChar ~
26132 a
26133 \newline
26134 mov\SpecialChar ~
26135 \SpecialChar ~
26136 _i,a
26137 \layout Subsection
26138
26139 Bit-rotation
26140 \begin_inset LatexCommand \index{Bit rotation}
26141
26142 \end_inset
26143
26144
26145 \layout Standard
26146
26147 A special case of the bit-shift operation is bit rotation
26148 \begin_inset LatexCommand \index{rotating bits}
26149
26150 \end_inset
26151
26152 , SDCC recognizes the following expression to be a left bit-rotation:
26153 \layout Verse
26154
26155
26156 \family typewriter
26157 \series bold
26158 unsigned
26159 \series default
26160 \SpecialChar ~
26161 \SpecialChar ~
26162 char i;\SpecialChar ~
26163 \SpecialChar ~
26164 \SpecialChar ~
26165 \SpecialChar ~
26166 \SpecialChar ~
26167 \SpecialChar ~
26168 \SpecialChar ~
26169 \SpecialChar ~
26170 \SpecialChar ~
26171 \SpecialChar ~
26172 \SpecialChar ~
26173 /* unsigned is needed for rotation */
26174 \newline
26175 ...
26176
26177 \newline
26178 i = ((i << 1) | (i >> 7));
26179 \family default
26180
26181 \newline
26182
26183 \family typewriter
26184 ...
26185 \layout Standard
26186
26187 will generate the following code:
26188 \layout Verse
26189
26190
26191 \family typewriter
26192 mov\SpecialChar ~
26193 \SpecialChar ~
26194 a,_i
26195 \newline
26196 rl\SpecialChar ~
26197 \SpecialChar ~
26198 \SpecialChar ~
26199 a
26200 \newline
26201 mov\SpecialChar ~
26202 \SpecialChar ~
26203 _i,a
26204 \layout Standard
26205
26206 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
26207 ns of this case will also be recognized as bit-rotation, i.e.:
26208 \layout Verse
26209
26210
26211 \family typewriter
26212 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
26213 \layout Subsection
26214
26215 Nibble and Byte Swapping
26216 \layout Standard
26217
26218 Other special cases of the bit-shift operations are nibble or byte swapping
26219 \begin_inset LatexCommand \index{swapping nibbles/bytes}
26220
26221 \end_inset
26222
26223 , SDCC recognizes the following expressions:
26224 \layout Verse
26225
26226
26227 \family typewriter
26228 \series bold
26229 unsigned
26230 \series default
26231 \SpecialChar ~
26232 \SpecialChar ~
26233 char i;
26234 \newline
26235
26236 \series bold
26237 unsigned
26238 \series default
26239 \SpecialChar ~
26240 \SpecialChar ~
26241 int j;
26242 \newline
26243 ...
26244
26245 \newline
26246 i = ((i << 4) | (i >> 4));
26247 \family default
26248
26249 \newline
26250
26251 \family typewriter
26252 j = ((j << 8) | (j >> 8));
26253 \layout Standard
26254
26255 and generates a swap instruction for the nibble swapping
26256 \begin_inset LatexCommand \index{Nibble swapping}
26257
26258 \end_inset
26259
26260  or move instructions for the byte swapping
26261 \begin_inset LatexCommand \index{Byte swapping}
26262
26263 \end_inset
26264
26265 .
26266  The
26267 \begin_inset Quotes sld
26268 \end_inset
26269
26270 j
26271 \begin_inset Quotes srd
26272 \end_inset
26273
26274  example can be used to convert from little to big-endian or vice versa.
26275  If you want to change the endianness of a
26276 \emph on
26277 signed
26278 \emph default
26279  integer you have to cast to
26280 \family typewriter
26281 (unsigned int)
26282 \family default
26283  first.
26284 \layout Standard
26285
26286 Note that SDCC stores numbers in little-endian
26287 \begin_inset Foot
26288 collapsed false
26289
26290 \layout Standard
26291
26292 Usually 8-bit processors don't care much about endianness.
26293  This is not the case for the standard 8051 which only has an instruction
26294  to increment its
26295 \emph on
26296 dptr
26297 \emph default
26298
26299 \begin_inset LatexCommand \index{DPTR}
26300
26301 \end_inset
26302
26303 -datapointer
26304 \emph on
26305
26306 \emph default
26307 so little-endian is the more efficient byte order.
26308 \end_inset
26309
26310
26311 \begin_inset LatexCommand \index{little-endian}
26312
26313 \end_inset
26314
26315
26316 \begin_inset LatexCommand \index{Endianness}
26317
26318 \end_inset
26319
26320  format (i.e.
26321  lowest order first).
26322 \layout Subsection
26323
26324 Highest Order Bit
26325 \begin_inset LatexCommand \index{Highest Order Bit}
26326
26327 \end_inset
26328
26329  / Any Order Bit
26330 \begin_inset LatexCommand \index{Any Order Bit}
26331
26332 \end_inset
26333
26334
26335 \layout Standard
26336
26337 It is frequently required to obtain the highest order bit of an integral
26338  type (long, int, short or char types).
26339  Also obtaining any other order bit is not uncommon.
26340  SDCC recognizes the following expressions to yield the highest order bit
26341  and generates optimized code for it, e.g.:
26342 \layout Verse
26343
26344
26345 \family typewriter
26346 unsigned int gint;
26347 \newline
26348
26349 \newline
26350 foo () {
26351 \newline
26352 \SpecialChar ~
26353 \SpecialChar ~
26354 unsigned char hob1, aob1;
26355 \newline
26356 \SpecialChar ~
26357 \SpecialChar ~
26358 bit hob2, hob3, aob2, aob3;
26359 \newline
26360 \SpecialChar ~
26361 \SpecialChar ~
26362 ...
26363
26364 \newline
26365 \SpecialChar ~
26366 \SpecialChar ~
26367 hob1 = (gint >> 15) & 1;
26368 \newline
26369 \SpecialChar ~
26370 \SpecialChar ~
26371 hob2 = (gint >> 15) & 1;
26372 \newline
26373 \SpecialChar ~
26374 \SpecialChar ~
26375 hob3 = gint & 0x8000;
26376 \newline
26377 \SpecialChar ~
26378 \SpecialChar ~
26379 aob1 = (gint >> 9) & 1;
26380 \newline
26381 \SpecialChar ~
26382 \SpecialChar ~
26383 aob2 = (gint >> 8) & 1;
26384 \newline
26385 \SpecialChar ~
26386 \SpecialChar ~
26387 aob3 = gint & 0x0800;
26388 \newline
26389 \SpecialChar ~
26390 \SpecialChar ~
26391 ..
26392
26393 \newline
26394 }
26395 \layout Standard
26396
26397 will generate the following code:
26398 \layout Verse
26399
26400
26401 \family typewriter
26402 \SpecialChar ~
26403 \SpecialChar ~
26404 \SpecialChar ~
26405 \SpecialChar ~
26406 \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 \SpecialChar ~
26422 \SpecialChar ~
26423 \SpecialChar ~
26424 \SpecialChar ~
26425 \SpecialChar ~
26426 \SpecialChar ~
26427  61 ;\SpecialChar ~
26428  hob.c 7
26429 \newline
26430 000A E5*01\SpecialChar ~
26431 \SpecialChar ~
26432 \SpecialChar ~
26433 \SpecialChar ~
26434 \SpecialChar ~
26435 \SpecialChar ~
26436 \SpecialChar ~
26437 \SpecialChar ~
26438 \SpecialChar ~
26439 \SpecialChar ~
26440 \SpecialChar ~
26441 \SpecialChar ~
26442 \SpecialChar ~
26443 \SpecialChar ~
26444 \SpecialChar ~
26445  62\SpecialChar ~
26446 \SpecialChar ~
26447 \SpecialChar ~
26448 \SpecialChar ~
26449 \SpecialChar ~
26450 \SpecialChar ~
26451 \SpecialChar ~
26452 \SpecialChar ~
26453  mov\SpecialChar ~
26454 \SpecialChar ~
26455  a,(_gint + 1)
26456 \newline
26457 000C 23\SpecialChar ~
26458 \SpecialChar ~
26459 \SpecialChar ~
26460 \SpecialChar ~
26461 \SpecialChar ~
26462 \SpecialChar ~
26463 \SpecialChar ~
26464 \SpecialChar ~
26465 \SpecialChar ~
26466 \SpecialChar ~
26467 \SpecialChar ~
26468 \SpecialChar ~
26469 \SpecialChar ~
26470 \SpecialChar ~
26471 \SpecialChar ~
26472 \SpecialChar ~
26473 \SpecialChar ~
26474 \SpecialChar ~
26475  63\SpecialChar ~
26476 \SpecialChar ~
26477 \SpecialChar ~
26478 \SpecialChar ~
26479 \SpecialChar ~
26480 \SpecialChar ~
26481 \SpecialChar ~
26482 \SpecialChar ~
26483  rl\SpecialChar ~
26484 \SpecialChar ~
26485 \SpecialChar ~
26486  a
26487 \newline
26488 000D 54 01\SpecialChar ~
26489 \SpecialChar ~
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  64\SpecialChar ~
26504 \SpecialChar ~
26505 \SpecialChar ~
26506 \SpecialChar ~
26507 \SpecialChar ~
26508 \SpecialChar ~
26509 \SpecialChar ~
26510 \SpecialChar ~
26511  anl\SpecialChar ~
26512 \SpecialChar ~
26513  a,#0x01
26514 \newline
26515 000F F5*02\SpecialChar ~
26516 \SpecialChar ~
26517 \SpecialChar ~
26518 \SpecialChar ~
26519 \SpecialChar ~
26520 \SpecialChar ~
26521 \SpecialChar ~
26522 \SpecialChar ~
26523 \SpecialChar ~
26524 \SpecialChar ~
26525 \SpecialChar ~
26526 \SpecialChar ~
26527 \SpecialChar ~
26528 \SpecialChar ~
26529 \SpecialChar ~
26530  65\SpecialChar ~
26531 \SpecialChar ~
26532 \SpecialChar ~
26533 \SpecialChar ~
26534 \SpecialChar ~
26535 \SpecialChar ~
26536 \SpecialChar ~
26537 \SpecialChar ~
26538  mov\SpecialChar ~
26539 \SpecialChar ~
26540  _foo_hob1_1_1,a
26541 \newline
26542 \SpecialChar ~
26543 \SpecialChar ~
26544 \SpecialChar ~
26545 \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 \SpecialChar ~
26564 \SpecialChar ~
26565 \SpecialChar ~
26566 \SpecialChar ~
26567  66 ;\SpecialChar ~
26568  hob.c 8
26569 \newline
26570 0011 E5*01\SpecialChar ~
26571 \SpecialChar ~
26572 \SpecialChar ~
26573 \SpecialChar ~
26574 \SpecialChar ~
26575 \SpecialChar ~
26576 \SpecialChar ~
26577 \SpecialChar ~
26578 \SpecialChar ~
26579 \SpecialChar ~
26580 \SpecialChar ~
26581 \SpecialChar ~
26582 \SpecialChar ~
26583 \SpecialChar ~
26584 \SpecialChar ~
26585  67\SpecialChar ~
26586 \SpecialChar ~
26587 \SpecialChar ~
26588 \SpecialChar ~
26589 \SpecialChar ~
26590 \SpecialChar ~
26591 \SpecialChar ~
26592 \SpecialChar ~
26593  mov\SpecialChar ~
26594 \SpecialChar ~
26595  a,(_gint + 1)
26596 \newline
26597 0013 33\SpecialChar ~
26598 \SpecialChar ~
26599 \SpecialChar ~
26600 \SpecialChar ~
26601 \SpecialChar ~
26602 \SpecialChar ~
26603 \SpecialChar ~
26604 \SpecialChar ~
26605 \SpecialChar ~
26606 \SpecialChar ~
26607 \SpecialChar ~
26608 \SpecialChar ~
26609 \SpecialChar ~
26610 \SpecialChar ~
26611 \SpecialChar ~
26612 \SpecialChar ~
26613 \SpecialChar ~
26614 \SpecialChar ~
26615  68\SpecialChar ~
26616 \SpecialChar ~
26617 \SpecialChar ~
26618 \SpecialChar ~
26619 \SpecialChar ~
26620 \SpecialChar ~
26621 \SpecialChar ~
26622 \SpecialChar ~
26623  rlc\SpecialChar ~
26624 \SpecialChar ~
26625  a
26626 \newline
26627 0014 92*00\SpecialChar ~
26628 \SpecialChar ~
26629 \SpecialChar ~
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  69\SpecialChar ~
26643 \SpecialChar ~
26644 \SpecialChar ~
26645 \SpecialChar ~
26646 \SpecialChar ~
26647 \SpecialChar ~
26648 \SpecialChar ~
26649 \SpecialChar ~
26650  mov\SpecialChar ~
26651 \SpecialChar ~
26652  _foo_hob2_1_1,c
26653 \newline
26654 \SpecialChar ~
26655 \SpecialChar ~
26656 \SpecialChar ~
26657 \SpecialChar ~
26658 \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 \SpecialChar ~
26674 \SpecialChar ~
26675 \SpecialChar ~
26676 \SpecialChar ~
26677 \SpecialChar ~
26678 \SpecialChar ~
26679  66 ;\SpecialChar ~
26680  hob.c 9
26681 \newline
26682 0016 E5*01\SpecialChar ~
26683 \SpecialChar ~
26684 \SpecialChar ~
26685 \SpecialChar ~
26686 \SpecialChar ~
26687 \SpecialChar ~
26688 \SpecialChar ~
26689 \SpecialChar ~
26690 \SpecialChar ~
26691 \SpecialChar ~
26692 \SpecialChar ~
26693 \SpecialChar ~
26694 \SpecialChar ~
26695 \SpecialChar ~
26696 \SpecialChar ~
26697  67\SpecialChar ~
26698 \SpecialChar ~
26699 \SpecialChar ~
26700 \SpecialChar ~
26701 \SpecialChar ~
26702 \SpecialChar ~
26703 \SpecialChar ~
26704 \SpecialChar ~
26705  mov\SpecialChar ~
26706 \SpecialChar ~
26707  a,(_gint + 1)
26708 \newline
26709 0018 33\SpecialChar ~
26710 \SpecialChar ~
26711 \SpecialChar ~
26712 \SpecialChar ~
26713 \SpecialChar ~
26714 \SpecialChar ~
26715 \SpecialChar ~
26716 \SpecialChar ~
26717 \SpecialChar ~
26718 \SpecialChar ~
26719 \SpecialChar ~
26720 \SpecialChar ~
26721 \SpecialChar ~
26722 \SpecialChar ~
26723 \SpecialChar ~
26724 \SpecialChar ~
26725 \SpecialChar ~
26726 \SpecialChar ~
26727  68\SpecialChar ~
26728 \SpecialChar ~
26729 \SpecialChar ~
26730 \SpecialChar ~
26731 \SpecialChar ~
26732 \SpecialChar ~
26733 \SpecialChar ~
26734 \SpecialChar ~
26735  rlc\SpecialChar ~
26736 \SpecialChar ~
26737  a
26738 \newline
26739 0019 92*01\SpecialChar ~
26740 \SpecialChar ~
26741 \SpecialChar ~
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  69\SpecialChar ~
26755 \SpecialChar ~
26756 \SpecialChar ~
26757 \SpecialChar ~
26758 \SpecialChar ~
26759 \SpecialChar ~
26760 \SpecialChar ~
26761 \SpecialChar ~
26762  mov\SpecialChar ~
26763 \SpecialChar ~
26764  _foo_hob3_1_1,c
26765 \newline
26766 \SpecialChar ~
26767 \SpecialChar ~
26768 \SpecialChar ~
26769 \SpecialChar ~
26770 \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 \SpecialChar ~
26786 \SpecialChar ~
26787 \SpecialChar ~
26788 \SpecialChar ~
26789 \SpecialChar ~
26790 \SpecialChar ~
26791  70 ;\SpecialChar ~
26792  hob.c 10
26793 \newline
26794 001B E5*01\SpecialChar ~
26795 \SpecialChar ~
26796 \SpecialChar ~
26797 \SpecialChar ~
26798 \SpecialChar ~
26799 \SpecialChar ~
26800 \SpecialChar ~
26801 \SpecialChar ~
26802 \SpecialChar ~
26803 \SpecialChar ~
26804 \SpecialChar ~
26805 \SpecialChar ~
26806 \SpecialChar ~
26807 \SpecialChar ~
26808 \SpecialChar ~
26809  71\SpecialChar ~
26810 \SpecialChar ~
26811 \SpecialChar ~
26812 \SpecialChar ~
26813 \SpecialChar ~
26814 \SpecialChar ~
26815 \SpecialChar ~
26816 \SpecialChar ~
26817  mov\SpecialChar ~
26818 \SpecialChar ~
26819  a,(_gint + 1)
26820 \newline
26821 001D 03\SpecialChar ~
26822 \SpecialChar ~
26823 \SpecialChar ~
26824 \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  72\SpecialChar ~
26840 \SpecialChar ~
26841 \SpecialChar ~
26842 \SpecialChar ~
26843 \SpecialChar ~
26844 \SpecialChar ~
26845 \SpecialChar ~
26846 \SpecialChar ~
26847  rr\SpecialChar ~
26848 \SpecialChar ~
26849 \SpecialChar ~
26850  a
26851 \newline
26852 001E 54 01\SpecialChar ~
26853 \SpecialChar ~
26854 \SpecialChar ~
26855 \SpecialChar ~
26856 \SpecialChar ~
26857 \SpecialChar ~
26858 \SpecialChar ~
26859 \SpecialChar ~
26860 \SpecialChar ~
26861 \SpecialChar ~
26862 \SpecialChar ~
26863 \SpecialChar ~
26864 \SpecialChar ~
26865 \SpecialChar ~
26866 \SpecialChar ~
26867  73\SpecialChar ~
26868 \SpecialChar ~
26869 \SpecialChar ~
26870 \SpecialChar ~
26871 \SpecialChar ~
26872 \SpecialChar ~
26873 \SpecialChar ~
26874 \SpecialChar ~
26875  anl\SpecialChar ~
26876 \SpecialChar ~
26877  a,#0x01
26878 \newline
26879 0020 F5*03\SpecialChar ~
26880 \SpecialChar ~
26881 \SpecialChar ~
26882 \SpecialChar ~
26883 \SpecialChar ~
26884 \SpecialChar ~
26885 \SpecialChar ~
26886 \SpecialChar ~
26887 \SpecialChar ~
26888 \SpecialChar ~
26889 \SpecialChar ~
26890 \SpecialChar ~
26891 \SpecialChar ~
26892 \SpecialChar ~
26893 \SpecialChar ~
26894  74\SpecialChar ~
26895 \SpecialChar ~
26896 \SpecialChar ~
26897 \SpecialChar ~
26898 \SpecialChar ~
26899 \SpecialChar ~
26900 \SpecialChar ~
26901 \SpecialChar ~
26902  mov\SpecialChar ~
26903 \SpecialChar ~
26904  _foo_aob1_1_1,a
26905 \newline
26906 \SpecialChar ~
26907 \SpecialChar ~
26908 \SpecialChar ~
26909 \SpecialChar ~
26910 \SpecialChar ~
26911 \SpecialChar ~
26912 \SpecialChar ~
26913 \SpecialChar ~
26914 \SpecialChar ~
26915 \SpecialChar ~
26916 \SpecialChar ~
26917 \SpecialChar ~
26918 \SpecialChar ~
26919 \SpecialChar ~
26920 \SpecialChar ~
26921 \SpecialChar ~
26922 \SpecialChar ~
26923 \SpecialChar ~
26924 \SpecialChar ~
26925 \SpecialChar ~
26926 \SpecialChar ~
26927 \SpecialChar ~
26928 \SpecialChar ~
26929 \SpecialChar ~
26930 \SpecialChar ~
26931  75 ;\SpecialChar ~
26932  hob.c 11
26933 \newline
26934 0022 E5*01\SpecialChar ~
26935 \SpecialChar ~
26936 \SpecialChar ~
26937 \SpecialChar ~
26938 \SpecialChar ~
26939 \SpecialChar ~
26940 \SpecialChar ~
26941 \SpecialChar ~
26942 \SpecialChar ~
26943 \SpecialChar ~
26944 \SpecialChar ~
26945 \SpecialChar ~
26946 \SpecialChar ~
26947 \SpecialChar ~
26948 \SpecialChar ~
26949  76\SpecialChar ~
26950 \SpecialChar ~
26951 \SpecialChar ~
26952 \SpecialChar ~
26953 \SpecialChar ~
26954 \SpecialChar ~
26955 \SpecialChar ~
26956 \SpecialChar ~
26957  mov\SpecialChar ~
26958 \SpecialChar ~
26959  a,(_gint + 1)
26960 \newline
26961 0024 13\SpecialChar ~
26962 \SpecialChar ~
26963 \SpecialChar ~
26964 \SpecialChar ~
26965 \SpecialChar ~
26966 \SpecialChar ~
26967 \SpecialChar ~
26968 \SpecialChar ~
26969 \SpecialChar ~
26970 \SpecialChar ~
26971 \SpecialChar ~
26972 \SpecialChar ~
26973 \SpecialChar ~
26974 \SpecialChar ~
26975 \SpecialChar ~
26976 \SpecialChar ~
26977 \SpecialChar ~
26978 \SpecialChar ~
26979  77\SpecialChar ~
26980 \SpecialChar ~
26981 \SpecialChar ~
26982 \SpecialChar ~
26983 \SpecialChar ~
26984 \SpecialChar ~
26985 \SpecialChar ~
26986 \SpecialChar ~
26987  rrc\SpecialChar ~
26988 \SpecialChar ~
26989  a
26990 \newline
26991 0025 92*02\SpecialChar ~
26992 \SpecialChar ~
26993 \SpecialChar ~
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  78\SpecialChar ~
27007 \SpecialChar ~
27008 \SpecialChar ~
27009 \SpecialChar ~
27010 \SpecialChar ~
27011 \SpecialChar ~
27012 \SpecialChar ~
27013 \SpecialChar ~
27014  mov\SpecialChar ~
27015 \SpecialChar ~
27016  _foo_aob2_1_1,c
27017 \newline
27018 \SpecialChar ~
27019 \SpecialChar ~
27020 \SpecialChar ~
27021 \SpecialChar ~
27022 \SpecialChar ~
27023 \SpecialChar ~
27024 \SpecialChar ~
27025 \SpecialChar ~
27026 \SpecialChar ~
27027 \SpecialChar ~
27028 \SpecialChar ~
27029 \SpecialChar ~
27030 \SpecialChar ~
27031 \SpecialChar ~
27032 \SpecialChar ~
27033 \SpecialChar ~
27034 \SpecialChar ~
27035 \SpecialChar ~
27036 \SpecialChar ~
27037 \SpecialChar ~
27038 \SpecialChar ~
27039 \SpecialChar ~
27040 \SpecialChar ~
27041 \SpecialChar ~
27042 \SpecialChar ~
27043  79 ;\SpecialChar ~
27044  hob.c 12
27045 \newline
27046 0027 E5*01\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  80\SpecialChar ~
27062 \SpecialChar ~
27063 \SpecialChar ~
27064 \SpecialChar ~
27065 \SpecialChar ~
27066 \SpecialChar ~
27067 \SpecialChar ~
27068 \SpecialChar ~
27069  mov\SpecialChar ~
27070 \SpecialChar ~
27071  a,(_gint + 1)
27072 \newline
27073 0029 A2 E3\SpecialChar ~
27074 \SpecialChar ~
27075 \SpecialChar ~
27076 \SpecialChar ~
27077 \SpecialChar ~
27078 \SpecialChar ~
27079 \SpecialChar ~
27080 \SpecialChar ~
27081 \SpecialChar ~
27082 \SpecialChar ~
27083 \SpecialChar ~
27084 \SpecialChar ~
27085 \SpecialChar ~
27086 \SpecialChar ~
27087 \SpecialChar ~
27088  81\SpecialChar ~
27089 \SpecialChar ~
27090 \SpecialChar ~
27091 \SpecialChar ~
27092 \SpecialChar ~
27093 \SpecialChar ~
27094 \SpecialChar ~
27095 \SpecialChar ~
27096  mov\SpecialChar ~
27097 \SpecialChar ~
27098  c,acc[3]
27099 \newline
27100 002B 92*03\SpecialChar ~
27101 \SpecialChar ~
27102 \SpecialChar ~
27103 \SpecialChar ~
27104 \SpecialChar ~
27105 \SpecialChar ~
27106 \SpecialChar ~
27107 \SpecialChar ~
27108 \SpecialChar ~
27109 \SpecialChar ~
27110 \SpecialChar ~
27111 \SpecialChar ~
27112 \SpecialChar ~
27113 \SpecialChar ~
27114 \SpecialChar ~
27115  82\SpecialChar ~
27116 \SpecialChar ~
27117 \SpecialChar ~
27118 \SpecialChar ~
27119 \SpecialChar ~
27120 \SpecialChar ~
27121 \SpecialChar ~
27122 \SpecialChar ~
27123  mov\SpecialChar ~
27124 \SpecialChar ~
27125  _foo_aob3_1_1,c
27126 \layout Standard
27127
27128 Other variations of these cases however will
27129 \emph on
27130 not
27131 \emph default
27132  be recognized.
27133  They are standard C expressions, so I heartily recommend these be the only
27134  way to get the highest order bit, (it is portable).
27135  Of course it will be recognized even if it is embedded in other expressions,
27136  e.g.:
27137 \layout Verse
27138
27139
27140 \family typewriter
27141 xyz = gint + ((gint >> 15) & 1);
27142 \layout Standard
27143
27144 will still be recognized.
27145 \layout Subsection
27146
27147 Higher Order Byte
27148 \begin_inset LatexCommand \index{Higher Order Byte}
27149
27150 \end_inset
27151
27152  / Higher Order Word
27153 \begin_inset LatexCommand \index{Higher Order Word}
27154
27155 \end_inset
27156
27157
27158 \layout Standard
27159
27160 It is also frequently required to obtain a higher order byte or word of
27161  a larger integral type (long, int or short types).
27162  SDCC recognizes the following expressions to yield the higher order byte
27163  or word and generates optimized code for it, e.g.:
27164 \layout Verse
27165
27166
27167 \family typewriter
27168 unsigned int gint;
27169 \newline
27170 unsigned long int glong;
27171 \newline
27172
27173 \newline
27174 foo () {
27175 \newline
27176 \SpecialChar ~
27177 \SpecialChar ~
27178 unsigned char hob1, hob2;
27179 \newline
27180 \SpecialChar ~
27181 \SpecialChar ~
27182 unsigned int how1, how2;
27183 \newline
27184 \SpecialChar ~
27185 \SpecialChar ~
27186 ...
27187
27188 \newline
27189 \SpecialChar ~
27190 \SpecialChar ~
27191 hob1 = (gint >> 8) & 0xFF;
27192 \newline
27193 \SpecialChar ~
27194 \SpecialChar ~
27195 hob2 = glong >> 24;
27196 \newline
27197 \SpecialChar ~
27198 \SpecialChar ~
27199 how1 = (glong >> 16) & 0xFFFF;
27200 \newline
27201 \SpecialChar ~
27202 \SpecialChar ~
27203 how2 = glong >> 8;
27204 \newline
27205 \SpecialChar ~
27206 \SpecialChar ~
27207 ..
27208
27209 \newline
27210 }
27211 \layout Standard
27212
27213 will generate the following code:
27214 \layout Verse
27215
27216
27217 \family typewriter
27218 \SpecialChar ~
27219 \SpecialChar ~
27220 \SpecialChar ~
27221 \SpecialChar ~
27222 \SpecialChar ~
27223 \SpecialChar ~
27224 \SpecialChar ~
27225 \SpecialChar ~
27226 \SpecialChar ~
27227 \SpecialChar ~
27228 \SpecialChar ~
27229 \SpecialChar ~
27230 \SpecialChar ~
27231 \SpecialChar ~
27232 \SpecialChar ~
27233 \SpecialChar ~
27234 \SpecialChar ~
27235 \SpecialChar ~
27236 \SpecialChar ~
27237 \SpecialChar ~
27238 \SpecialChar ~
27239 \SpecialChar ~
27240 \SpecialChar ~
27241 \SpecialChar ~
27242 \SpecialChar ~
27243  91 ;\SpecialChar ~
27244  hob.c 15
27245 \newline
27246 0037 85*01*06\SpecialChar ~
27247 \SpecialChar ~
27248 \SpecialChar ~
27249 \SpecialChar ~
27250 \SpecialChar ~
27251 \SpecialChar ~
27252 \SpecialChar ~
27253 \SpecialChar ~
27254 \SpecialChar ~
27255 \SpecialChar ~
27256 \SpecialChar ~
27257 \SpecialChar ~
27258  92\SpecialChar ~
27259 \SpecialChar ~
27260 \SpecialChar ~
27261 \SpecialChar ~
27262 \SpecialChar ~
27263 \SpecialChar ~
27264 \SpecialChar ~
27265 \SpecialChar ~
27266  mov\SpecialChar ~
27267 \SpecialChar ~
27268  _foo_hob1_1_1,(_gint + 1)
27269 \newline
27270 \SpecialChar ~
27271 \SpecialChar ~
27272 \SpecialChar ~
27273 \SpecialChar ~
27274 \SpecialChar ~
27275 \SpecialChar ~
27276 \SpecialChar ~
27277 \SpecialChar ~
27278 \SpecialChar ~
27279 \SpecialChar ~
27280 \SpecialChar ~
27281 \SpecialChar ~
27282 \SpecialChar ~
27283 \SpecialChar ~
27284 \SpecialChar ~
27285 \SpecialChar ~
27286 \SpecialChar ~
27287 \SpecialChar ~
27288 \SpecialChar ~
27289 \SpecialChar ~
27290 \SpecialChar ~
27291 \SpecialChar ~
27292 \SpecialChar ~
27293 \SpecialChar ~
27294 \SpecialChar ~
27295  93 ;\SpecialChar ~
27296  hob.c 16
27297 \newline
27298 003A 85*05*07\SpecialChar ~
27299 \SpecialChar ~
27300 \SpecialChar ~
27301 \SpecialChar ~
27302 \SpecialChar ~
27303 \SpecialChar ~
27304 \SpecialChar ~
27305 \SpecialChar ~
27306 \SpecialChar ~
27307 \SpecialChar ~
27308 \SpecialChar ~
27309 \SpecialChar ~
27310  94\SpecialChar ~
27311 \SpecialChar ~
27312 \SpecialChar ~
27313 \SpecialChar ~
27314 \SpecialChar ~
27315 \SpecialChar ~
27316 \SpecialChar ~
27317 \SpecialChar ~
27318  mov\SpecialChar ~
27319 \SpecialChar ~
27320  _foo_hob2_1_1,(_glong + 3)
27321 \newline
27322 \SpecialChar ~
27323 \SpecialChar ~
27324 \SpecialChar ~
27325 \SpecialChar ~
27326 \SpecialChar ~
27327 \SpecialChar ~
27328 \SpecialChar ~
27329 \SpecialChar ~
27330 \SpecialChar ~
27331 \SpecialChar ~
27332 \SpecialChar ~
27333 \SpecialChar ~
27334 \SpecialChar ~
27335 \SpecialChar ~
27336 \SpecialChar ~
27337 \SpecialChar ~
27338 \SpecialChar ~
27339 \SpecialChar ~
27340 \SpecialChar ~
27341 \SpecialChar ~
27342 \SpecialChar ~
27343 \SpecialChar ~
27344 \SpecialChar ~
27345 \SpecialChar ~
27346 \SpecialChar ~
27347  95 ;\SpecialChar ~
27348  hob.c 17
27349 \newline
27350 003D 85*04*08\SpecialChar ~
27351 \SpecialChar ~
27352 \SpecialChar ~
27353 \SpecialChar ~
27354 \SpecialChar ~
27355 \SpecialChar ~
27356 \SpecialChar ~
27357 \SpecialChar ~
27358 \SpecialChar ~
27359 \SpecialChar ~
27360 \SpecialChar ~
27361 \SpecialChar ~
27362  96\SpecialChar ~
27363 \SpecialChar ~
27364 \SpecialChar ~
27365 \SpecialChar ~
27366 \SpecialChar ~
27367 \SpecialChar ~
27368 \SpecialChar ~
27369 \SpecialChar ~
27370  mov\SpecialChar ~
27371 \SpecialChar ~
27372  _foo_how1_1_1,(_glong + 2)
27373 \newline
27374 0040 85*05*09\SpecialChar ~
27375 \SpecialChar ~
27376 \SpecialChar ~
27377 \SpecialChar ~
27378 \SpecialChar ~
27379 \SpecialChar ~
27380 \SpecialChar ~
27381 \SpecialChar ~
27382 \SpecialChar ~
27383 \SpecialChar ~
27384 \SpecialChar ~
27385 \SpecialChar ~
27386  97\SpecialChar ~
27387 \SpecialChar ~
27388 \SpecialChar ~
27389 \SpecialChar ~
27390 \SpecialChar ~
27391 \SpecialChar ~
27392 \SpecialChar ~
27393 \SpecialChar ~
27394  mov\SpecialChar ~
27395 \SpecialChar ~
27396  (_foo_how1_1_1 + 1),(_glong + 3)
27397 \newline
27398 0043 85*03*0A\SpecialChar ~
27399 \SpecialChar ~
27400 \SpecialChar ~
27401 \SpecialChar ~
27402 \SpecialChar ~
27403 \SpecialChar ~
27404 \SpecialChar ~
27405 \SpecialChar ~
27406 \SpecialChar ~
27407 \SpecialChar ~
27408 \SpecialChar ~
27409 \SpecialChar ~
27410  98\SpecialChar ~
27411 \SpecialChar ~
27412 \SpecialChar ~
27413 \SpecialChar ~
27414 \SpecialChar ~
27415 \SpecialChar ~
27416 \SpecialChar ~
27417 \SpecialChar ~
27418  mov\SpecialChar ~
27419 \SpecialChar ~
27420  _foo_how2_1_1,(_glong + 1)
27421 \newline
27422 0046 85*04*0B\SpecialChar ~
27423 \SpecialChar ~
27424 \SpecialChar ~
27425 \SpecialChar ~
27426 \SpecialChar ~
27427 \SpecialChar ~
27428 \SpecialChar ~
27429 \SpecialChar ~
27430 \SpecialChar ~
27431 \SpecialChar ~
27432 \SpecialChar ~
27433 \SpecialChar ~
27434  99\SpecialChar ~
27435 \SpecialChar ~
27436 \SpecialChar ~
27437 \SpecialChar ~
27438 \SpecialChar ~
27439 \SpecialChar ~
27440 \SpecialChar ~
27441 \SpecialChar ~
27442  mov\SpecialChar ~
27443 \SpecialChar ~
27444  (_foo_how2_1_1 + 1),(_glong + 2)
27445 \layout Standard
27446
27447 Again, variations of these cases may
27448 \emph on
27449 not
27450 \emph default
27451  be recognized.
27452  They are standard C expressions, so I heartily recommend these be the only
27453  way to get the higher order byte/word, (it is portable).
27454  Of course it will be recognized even if it is embedded in other expressions,
27455  e.g.:
27456 \layout Verse
27457
27458
27459 \family typewriter
27460 xyz = gint + ((gint >> 8) & 0xFF);
27461 \layout Standard
27462
27463 will still be recognized.
27464 \layout Subsection
27465
27466 Peephole Optimizer
27467 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
27468
27469 \end_inset
27470
27471
27472 \begin_inset LatexCommand \index{Peephole optimizer}
27473
27474 \end_inset
27475
27476
27477 \layout Standard
27478
27479 The compiler uses a rule based, pattern matching and re-writing mechanism
27480  for peep-hole optimization.
27481  It is inspired by
27482 \emph on
27483 copt
27484 \emph default
27485  a peep-hole optimizer by Christopher W.
27486  Fraser (cwfraser\SpecialChar ~
27487 @\SpecialChar ~
27488 microsoft.com).
27489  A default set of rules are compiled into the compiler, additional rules
27490  may be added with the
27491 \emph on
27492 -
27493 \begin_inset ERT
27494 status Collapsed
27495
27496 \layout Standard
27497
27498 \backslash
27499 /
27500 \end_inset
27501
27502 -peep-file
27503 \begin_inset LatexCommand \index{-\/-peep-file}
27504
27505 \end_inset
27506
27507  <filename>
27508 \emph default
27509  option.
27510  The rule language is best illustrated with examples.
27511 \layout Verse
27512
27513
27514 \family typewriter
27515 replace {
27516 \newline
27517 \SpecialChar ~
27518 \SpecialChar ~
27519 mov %1,a
27520 \newline
27521 \SpecialChar ~
27522 \SpecialChar ~
27523 mov a,%1
27524 \newline
27525 } by {
27526 \newline
27527 \SpecialChar ~
27528 \SpecialChar ~
27529 mov %1,a
27530 \newline
27531 }
27532 \layout Standard
27533
27534 The above rule will change the following assembly
27535 \begin_inset LatexCommand \index{Assembler routines}
27536
27537 \end_inset
27538
27539  sequence:
27540 \layout Verse
27541
27542
27543 \family typewriter
27544 mov r1,a
27545 \newline
27546 mov a,r1
27547 \layout Standard
27548
27549 to
27550 \layout Verse
27551
27552
27553 \family typewriter
27554 mov r1,a
27555 \layout Standard
27556
27557 Note: All occurrences of a
27558 \emph on
27559 %n
27560 \emph default
27561  (pattern variable) must denote the same string.
27562  With the above rule, the assembly sequence:
27563 \layout Verse
27564
27565
27566 \family typewriter
27567 mov r1,a
27568 \newline
27569 mov a,r2
27570 \layout Standard
27571
27572 will remain unmodified.
27573 \newline
27574
27575 \newline
27576 Other special case optimizations may be added by the user (via
27577 \emph on
27578 -
27579 \begin_inset ERT
27580 status Collapsed
27581
27582 \layout Standard
27583
27584 \backslash
27585 /
27586 \end_inset
27587
27588 -peep-file option
27589 \emph default
27590 ).
27591  E.g.
27592  some variants of the 8051 MCU
27593 \begin_inset LatexCommand \index{MCS51 variants}
27594
27595 \end_inset
27596
27597  allow only
27598 \family typewriter
27599 ajmp
27600 \family default
27601  and
27602 \family typewriter
27603 acall
27604 \family default
27605 .
27606  The following two rules will change all
27607 \family typewriter
27608 ljmp
27609 \family default
27610  and
27611 \family typewriter
27612 lcall
27613 \family default
27614  to
27615 \family typewriter
27616 ajmp
27617 \family default
27618  and
27619 \family typewriter
27620 acall
27621 \layout Verse
27622
27623
27624 \family typewriter
27625 replace { lcall %1 } by { acall %1 }
27626 \newline
27627 replace { ljmp %1 } by { ajmp %1 }
27628 \layout Standard
27629
27630 The
27631 \emph on
27632 inline-assembler code
27633 \emph default
27634  is also passed through the peep hole optimizer, thus the peephole optimizer
27635  can also be used as an assembly level macro expander.
27636  The rules themselves are MCU dependent whereas the rule language infra-structur
27637 e is MCU independent.
27638  Peephole optimization rules for other MCU can be easily programmed using
27639  the rule language.
27640 \newline
27641
27642 \newline
27643 The syntax for a rule is as follows:
27644 \layout Verse
27645
27646
27647 \family typewriter
27648 rule := replace [ restart ] '{' <assembly sequence> '
27649 \backslash
27650 n'
27651 \newline
27652 \SpecialChar ~
27653  \SpecialChar ~
27654  \SpecialChar ~
27655  \SpecialChar ~
27656  \SpecialChar ~
27657  \SpecialChar ~
27658  \SpecialChar ~
27659  \SpecialChar ~
27660  \SpecialChar ~
27661  \SpecialChar ~
27662  \SpecialChar ~
27663  \SpecialChar ~
27664  \SpecialChar ~
27665  \SpecialChar ~
27666  '}' by '{' '
27667 \backslash
27668 n'
27669 \newline
27670 \SpecialChar ~
27671  \SpecialChar ~
27672  \SpecialChar ~
27673  \SpecialChar ~
27674  \SpecialChar ~
27675  \SpecialChar ~
27676  \SpecialChar ~
27677  \SpecialChar ~
27678  \SpecialChar ~
27679  \SpecialChar ~
27680  \SpecialChar ~
27681  \SpecialChar ~
27682  \SpecialChar ~
27683  \SpecialChar ~
27684  \SpecialChar ~
27685  \SpecialChar ~
27686  <assembly sequence> '
27687 \backslash
27688 n'
27689 \newline
27690 \SpecialChar ~
27691  \SpecialChar ~
27692  \SpecialChar ~
27693  \SpecialChar ~
27694  \SpecialChar ~
27695  \SpecialChar ~
27696  \SpecialChar ~
27697  \SpecialChar ~
27698  \SpecialChar ~
27699  \SpecialChar ~
27700  \SpecialChar ~
27701  \SpecialChar ~
27702  \SpecialChar ~
27703  \SpecialChar ~
27704  '}' [if <functionName> ] '
27705 \backslash
27706 n'
27707 \layout Standard
27708
27709 <assembly sequence> := assembly instruction (each instruction including
27710  labels must be on a separate line).
27711 \newline
27712
27713 \newline
27714 The optimizer will apply to the rules one by one from the top in the sequence
27715  of their appearance, it will terminate when all rules are exhausted.
27716  If the 'restart' option is specified, then the optimizer will start matching
27717  the rules again from the top, this option for a rule is expensive (performance)
27718 , it is intended to be used in situations where a transformation will trigger
27719  the same rule again.
27720  An example of this (not a good one, it has side effects) is the following
27721  rule:
27722 \layout Verse
27723
27724
27725 \family typewriter
27726 replace restart {
27727 \newline
27728 \SpecialChar ~
27729 \SpecialChar ~
27730 pop %1
27731 \newline
27732 \SpecialChar ~
27733 \SpecialChar ~
27734 push %1 } by {
27735 \newline
27736 \SpecialChar ~
27737 \SpecialChar ~
27738 ; nop
27739 \newline
27740 }
27741 \layout Standard
27742
27743 Note that the replace pattern cannot be a blank, but can be a comment line.
27744  Without the 'restart' option only the innermost 'pop' 'push' pair would
27745  be eliminated, i.e.:
27746 \layout Verse
27747
27748
27749 \family typewriter
27750 pop ar1
27751 \newline
27752 pop ar2
27753 \newline
27754 push ar2
27755 \newline
27756 push ar1
27757 \layout Standard
27758
27759 would result in:
27760 \layout Verse
27761
27762
27763 \family typewriter
27764 pop ar1
27765 \newline
27766 ; nop
27767 \newline
27768 push ar1
27769 \layout Standard
27770
27771
27772 \emph on
27773 with
27774 \emph default
27775  the restart option the rule will be applied again to the resulting code
27776  and then all the pop-push pairs will be eliminated to yield:
27777 \layout Verse
27778
27779
27780 \family typewriter
27781 ; nop
27782 \newline
27783 ; nop
27784 \layout Standard
27785
27786 A conditional function can be attached to a rule.
27787  Attaching rules are somewhat more involved, let me illustrate this with
27788  an example.
27789 \layout Verse
27790
27791
27792 \family typewriter
27793 replace {
27794 \newline
27795 \SpecialChar ~
27796  \SpecialChar ~
27797  \SpecialChar ~
27798 ljmp %5
27799 \newline
27800 %2:
27801 \newline
27802 } by {
27803 \newline
27804 \SpecialChar ~
27805  \SpecialChar ~
27806  \SpecialChar ~
27807 sjmp %5
27808 \newline
27809 %2:
27810 \newline
27811 } if labelInRange
27812 \layout Standard
27813
27814 The optimizer does a look-up of a function name table defined in function
27815
27816 \emph on
27817 callFuncByName
27818 \emph default
27819  in the source file SDCCpeeph.c, with the name
27820 \emph on
27821 labelInRange
27822 \emph default
27823 .
27824  If it finds a corresponding entry the function is called.
27825  Note there can be no parameters specified for these functions, in this
27826  case the use of
27827 \emph on
27828 %5
27829 \emph default
27830  is crucial, since the function
27831 \emph on
27832 labelInRange
27833 \emph default
27834  expects to find the label in that particular variable (the hash table containin
27835 g the variable bindings is passed as a parameter).
27836  If you want to code more such functions, take a close look at the function
27837  labelInRange and the calling mechanism in source file SDCCpeeph.c.
27838  Currently implemented are
27839 \emph on
27840 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
27841  24bitMode, portIsDS390, 24bitModeAndPortDS390
27842 \emph default
27843 and
27844 \emph on
27845  notVolatile
27846 \emph default
27847 .
27848 \layout Standard
27849
27850 I know this whole thing is a little kludgey, but maybe some day we will
27851  have some better means.
27852  If you are looking at this file, you will see the default rules that are
27853  compiled into the compiler, you can add your own rules in the default set
27854  there if you get tired of specifying the -
27855 \begin_inset ERT
27856 status Collapsed
27857
27858 \layout Standard
27859
27860 \backslash
27861 /
27862 \end_inset
27863
27864 -peep-file option.
27865 \layout Section
27866
27867 ANSI-Compliance
27868 \begin_inset LatexCommand \index{ANSI-compliance}
27869
27870 \end_inset
27871
27872
27873 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
27874
27875 \end_inset
27876
27877
27878 \layout Standard
27879
27880 The latest publically available version of the standard
27881 \emph on
27882 ISO/IEC 9899 - Programming languages - C
27883 \emph default
27884  should be available at:
27885 \begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899}
27886
27887 \end_inset
27888
27889 .
27890 \newline
27891
27892 \layout Standard
27893
27894 Deviations from the compliance:
27895 \layout Itemize
27896
27897 functions are not reentrant
27898 \begin_inset LatexCommand \index{reentrant}
27899
27900 \end_inset
27901
27902  unless explicitly declared as such or the
27903 \series bold
27904 -
27905 \begin_inset ERT
27906 status Collapsed
27907
27908 \layout Standard
27909
27910 \backslash
27911 /
27912 \end_inset
27913
27914 -stack-auto
27915 \begin_inset LatexCommand \index{-\/-stack-auto}
27916
27917 \end_inset
27918
27919
27920 \series default
27921  command line option is specified.
27922 \layout Itemize
27923
27924 structures and unions cannot be assigned values directly, cannot be passed
27925  as function parameters or assigned to each other and cannot be a return
27926  value from a function, e.g.:
27927 \begin_deeper
27928 \layout Verse
27929
27930
27931 \family typewriter
27932 struct s { ...
27933  };
27934 \newline
27935 struct s s1, s2;
27936 \newline
27937 foo()
27938 \newline
27939 {
27940 \newline
27941 \SpecialChar ~
27942 \SpecialChar ~
27943 \SpecialChar ~
27944 \SpecialChar ~
27945 ...
27946
27947 \newline
27948 \SpecialChar ~
27949 \SpecialChar ~
27950 \SpecialChar ~
27951 \SpecialChar ~
27952 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
27953 \newline
27954 \SpecialChar ~
27955 \SpecialChar ~
27956 \SpecialChar ~
27957 \SpecialChar ~
27958 ...
27959
27960 \newline
27961 }
27962 \newline
27963 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
27964  */
27965 \newline
27966 {
27967 \newline
27968 \SpecialChar ~
27969 \SpecialChar ~
27970 \SpecialChar ~
27971 \SpecialChar ~
27972 struct s rets;
27973 \newline
27974 \SpecialChar ~
27975 \SpecialChar ~
27976 \SpecialChar ~
27977 \SpecialChar ~
27978 ...
27979
27980 \newline
27981 \SpecialChar ~
27982 \SpecialChar ~
27983 \SpecialChar ~
27984 \SpecialChar ~
27985 return rets;/* is invalid in SDCC although allowed in ANSI */
27986 \newline
27987 }
27988 \end_deeper
27989 \layout Itemize
27990
27991 initialization of structure arrays must be fully braced.
27992 \begin_deeper
27993 \layout Verse
27994
27995
27996 \family typewriter
27997 struct s { char x } a[] = {1, 2}; /* invalid in SDCC */
27998 \newline
27999 struct s { char x } a[] = {{1}, {2}}; /* OK */
28000 \end_deeper
28001 \layout Itemize
28002
28003 'long long
28004 \begin_inset LatexCommand \index{long long (not supported)}
28005
28006 \end_inset
28007
28008 ' (64 bit integers
28009 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
28010
28011 \end_inset
28012
28013 ) not supported.
28014 \layout Itemize
28015
28016 'double
28017 \begin_inset LatexCommand \index{double (not supported)}
28018
28019 \end_inset
28020
28021 ' precision floating point
28022 \begin_inset LatexCommand \index{Floating point support}
28023
28024 \end_inset
28025
28026 not supported.
28027 \layout Itemize
28028
28029 Old K&R style
28030 \begin_inset LatexCommand \index{K\&R style}
28031
28032 \end_inset
28033
28034  function declarations are NOT allowed.
28035 \begin_deeper
28036 \layout Verse
28037
28038
28039 \family typewriter
28040 foo(i,j) /* this old style of function declarations */
28041 \newline
28042 int i,j; /* are valid in ANSI but not valid in SDCC */
28043 \newline
28044 {
28045 \newline
28046 \SpecialChar ~
28047 \SpecialChar ~
28048 \SpecialChar ~
28049 \SpecialChar ~
28050 ...
28051
28052 \newline
28053 }
28054 \end_deeper
28055 \layout Itemize
28056
28057 Most enhancements in C99 are not supported, f.e.:
28058 \begin_deeper
28059 \layout Verse
28060
28061
28062 \family typewriter
28063 \series bold
28064 inline
28065 \series default
28066  int increment (int a) { return a+1; } /* is invalid in SDCC although allowed
28067  in C99 */
28068 \newline
28069 for (
28070 \series bold
28071 int
28072 \series default
28073  i=0; i<10; i++) /* is invalid in SDCC although allowed in C99 */
28074 \end_deeper
28075 \layout Itemize
28076
28077 Certain words that are valid identifiers in the standard may be reserved
28078  words in SDCC unless the
28079 \series bold
28080 -
28081 \begin_inset ERT
28082 status Collapsed
28083
28084 \layout Standard
28085
28086 \backslash
28087 /
28088 \end_inset
28089
28090 -std-c89
28091 \begin_inset LatexCommand \index{-\/-std-c89}
28092
28093 \end_inset
28094
28095  or -
28096 \begin_inset ERT
28097 status Collapsed
28098
28099 \layout Standard
28100
28101 \backslash
28102 /
28103 \end_inset
28104
28105 -std-c99
28106 \begin_inset LatexCommand \index{-\/-std-c99}
28107
28108 \end_inset
28109
28110
28111 \series default
28112  command line options are used.
28113  These may include (depending on the selected processor): 'at', 'banked',
28114  'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup
28115 t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs',
28116  'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and
28117  '_naked'.
28118  Compliant equivalents of these keywords are always available in a form
28119  that begin with two underscores
28120 \begin_inset LatexCommand \index{\_\_ (prefix for extended keywords)}
28121
28122 \end_inset
28123
28124 , f.e.
28125  '__data' instead of 'data'.
28126 \layout Section
28127
28128 Cyclomatic Complexity
28129 \begin_inset LatexCommand \index{Cyclomatic complexity}
28130
28131 \end_inset
28132
28133
28134 \layout Standard
28135
28136 Cyclomatic complexity of a function is defined as the number of independent
28137  paths the program can take during execution of the function.
28138  This is an important number since it defines the number test cases you
28139  have to generate to validate the function.
28140  The accepted industry standard for complexity number is 10, if the cyclomatic
28141  complexity reported by SDCC exceeds 10 you should think about simplification
28142  of the function logic.
28143  Note that the complexity level is not related to the number of lines of
28144  code in a function.
28145  Large functions can have low complexity, and small functions can have large
28146  complexity levels.
28147
28148 \newline
28149
28150 \newline
28151 SDCC uses the following formula to compute the complexity:
28152 \newline
28153
28154 \layout Standard
28155
28156 complexity = (number of edges in control flow graph) - (number of nodes
28157  in control flow graph) + 2;
28158 \newline
28159
28160 \newline
28161 Having said that the industry standard is 10, you should be aware that in
28162  some cases it be may unavoidable to have a complexity level of less than
28163  10.
28164  For example if you have switch statement with more than 10 case labels,
28165  each case label adds one to the complexity level.
28166  The complexity level is by no means an absolute measure of the algorithmic
28167  complexity of the function, it does however provide a good starting point
28168  for which functions you might look at for further optimization.
28169 \layout Section
28170
28171 Retargetting for other Processors
28172 \layout Standard
28173
28174 The issues for retargetting the compiler are far too numerous to be covered
28175  by this document.
28176  What follows is a brief description of each of the seven phases of the
28177  compiler and its MCU dependency.
28178 \layout Itemize
28179
28180 Parsing the source and building the annotated parse tree.
28181  This phase is largely MCU independent (except for the language extensions).
28182  Syntax & semantic checks are also done in this phase, along with some initial
28183  optimizations like back patching labels and the pattern matching optimizations
28184  like bit-rotation etc.
28185 \layout Itemize
28186
28187 The second phase involves generating an intermediate code which can be easy
28188  manipulated during the later phases.
28189  This phase is entirely MCU independent.
28190  The intermediate code generation assumes the target machine has unlimited
28191  number of registers, and designates them with the name iTemp.
28192  The compiler can be made to dump a human readable form of the code generated
28193  by using the -
28194 \begin_inset ERT
28195 status Collapsed
28196
28197 \layout Standard
28198
28199 \backslash
28200 /
28201 \end_inset
28202
28203 -dumpraw option.
28204 \layout Itemize
28205
28206 This phase does the bulk of the standard optimizations and is also MCU independe
28207 nt.
28208  This phase can be broken down into several sub-phases:
28209 \newline
28210
28211 \newline
28212 Break down intermediate code (iCode) into basic blocks.
28213 \newline
28214 Do control flow & data flow analysis on the basic blocks.
28215 \newline
28216 Do local common subexpression elimination, then global subexpression elimination
28217 \newline
28218 Dead code elimination
28219 \newline
28220 Loop optimizations
28221 \newline
28222 If loop optimizations caused any changes then do 'global subexpression eliminati
28223 on' and 'dead code elimination' again.
28224 \layout Itemize
28225
28226 This phase determines the live-ranges; by live range I mean those iTemp
28227  variables defined by the compiler that still survive after all the optimization
28228 s.
28229  Live range analysis
28230 \begin_inset LatexCommand \index{Live range analysis}
28231
28232 \end_inset
28233
28234  is essential for register allocation, since these computation determines
28235  which of these iTemps will be assigned to registers, and for how long.
28236 \layout Itemize
28237
28238 Phase five is register allocation.
28239  There are two parts to this process.
28240 \newline
28241
28242 \newline
28243 The first part I call 'register packing' (for lack of a better term).
28244  In this case several MCU specific expression folding is done to reduce
28245  register pressure.
28246 \newline
28247
28248 \newline
28249 The second part is more MCU independent and deals with allocating registers
28250  to the remaining live ranges.
28251  A lot of MCU specific code does creep into this phase because of the limited
28252  number of index registers available in the 8051.
28253 \layout Itemize
28254
28255 The Code generation phase is (unhappily), entirely MCU dependent and very
28256  little (if any at all) of this code can be reused for other MCU.
28257  However the scheme for allocating a homogenized assembler operand for each
28258  iCode operand may be reused.
28259 \layout Itemize
28260
28261 As mentioned in the optimization section the peep-hole optimizer is rule
28262  based system, which can reprogrammed for other MCUs.
28263 \layout Chapter
28264
28265 Compiler internals
28266 \begin_inset LatexCommand \index{Compiler internals}
28267
28268 \end_inset
28269
28270
28271 \layout Section
28272
28273 The anatomy of the compiler
28274 \begin_inset LatexCommand \label{sub:The-anatomy-of}
28275
28276 \end_inset
28277
28278
28279 \layout Standard
28280
28281
28282 \shape italic
28283 This is an excerpt from an article published in Circuit Cellar Magazine
28284  in
28285 \series bold
28286 August 2000
28287 \series default
28288 .
28289  It's a little outdated (the compiler is much more efficient now and user/develo
28290 per friendly), but pretty well exposes the guts of it all.
28291 \shape default
28292
28293 \newline
28294
28295 \newline
28296 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
28297  It is fairly easy to retarget for other 8-bit MCU.
28298  Here we take a look at some of the internals of the compiler.
28299
28300 \layout Paragraph*
28301
28302 Parsing
28303 \begin_inset LatexCommand \index{Parsing}
28304
28305 \end_inset
28306
28307
28308 \layout Standard
28309
28310 Parsing the input source file and creating an AST (Annotated Syntax Tree
28311 \begin_inset LatexCommand \index{Annotated syntax tree}
28312
28313 \end_inset
28314
28315 ).
28316  This phase also involves propagating types (annotating each node of the
28317  parse tree with type information) and semantic analysis.
28318  There are some MCU specific parsing rules.
28319  For example the storage classes, the extended storage classes are MCU specific
28320  while there may be a xdata storage class for 8051 there is no such storage
28321  class for z80 or Atmel AVR.
28322  SDCC allows MCU specific storage class extensions, i.e.
28323  xdata will be treated as a storage class specifier when parsing 8051 C
28324  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
28325  C code.
28326 \layout Paragraph*
28327
28328 Generating iCode
28329 \begin_inset LatexCommand \index{iCode}
28330
28331 \end_inset
28332
28333
28334 \layout Standard
28335
28336 Intermediate code generation.
28337  In this phase the AST is broken down into three-operand form (iCode).
28338  These three operand forms are represented as doubly linked lists.
28339  ICode is the term given to the intermediate form generated by the compiler.
28340  ICode example section shows some examples of iCode generated for some simple
28341  C source functions.
28342 \layout Paragraph*
28343
28344 Optimizations
28345 \begin_inset LatexCommand \index{Optimizations}
28346
28347 \end_inset
28348
28349 .
28350 \layout Standard
28351
28352 Bulk of the target independent optimizations is performed in this phase.
28353  The optimizations include constant propagation, common sub-expression eliminati
28354 on, loop invariant code movement, strength reduction of loop induction variables
28355  and dead-code elimination.
28356 \layout Paragraph*
28357
28358 Live range analysis
28359 \begin_inset LatexCommand \index{Live range analysis}
28360
28361 \end_inset
28362
28363
28364 \layout Standard
28365
28366 During intermediate code generation phase, the compiler assumes the target
28367  machine has infinite number of registers and generates a lot of temporary
28368  variables.
28369  The live range computation determines the lifetime of each of these compiler-ge
28370 nerated temporaries.
28371  A picture speaks a thousand words.
28372  ICode example sections show the live range annotations for each of the
28373  operand.
28374  It is important to note here, each iCode is assigned a number in the order
28375  of its execution in the function.
28376  The live ranges are computed in terms of these numbers.
28377  The from number is the number of the iCode which first defines the operand
28378  and the to number signifies the iCode which uses this operand last.
28379 \layout Paragraph*
28380
28381 Register Allocation
28382 \begin_inset LatexCommand \index{Register allocation}
28383
28384 \end_inset
28385
28386
28387 \layout Standard
28388
28389 The register allocation determines the type and number of registers needed
28390  by each operand.
28391  In most MCUs only a few registers can be used for indirect addressing.
28392  In case of 8051 for example the registers R0 & R1 can be used to indirectly
28393  address the internal ram and DPTR to indirectly address the external ram.
28394  The compiler will try to allocate the appropriate register to pointer variables
28395  if it can.
28396  ICode example section shows the operands annotated with the registers assigned
28397  to them.
28398  The compiler will try to keep operands in registers as much as possible;
28399  there are several schemes the compiler uses to do achieve this.
28400  When the compiler runs out of registers the compiler will check to see
28401  if there are any live operands which is not used or defined in the current
28402  basic block being processed, if there are any found then it will push that
28403  operand and use the registers in this block, the operand will then be popped
28404  at the end of the basic block.
28405
28406 \layout Standard
28407
28408 There are other MCU specific considerations in this phase.
28409  Some MCUs have an accumulator; very short-lived operands could be assigned
28410  to the accumulator instead of a general-purpose register.
28411 \layout Paragraph*
28412
28413 Code generation
28414 \layout Standard
28415
28416 Figure II gives a table of iCode operations supported by the compiler.
28417  The code generation involves translating these operations into corresponding
28418  assembly code for the processor.
28419  This sounds overly simple but that is the essence of code generation.
28420  Some of the iCode operations are generated on a MCU specific manner for
28421  example, the z80 port does not use registers to pass parameters so the
28422  SEND and RECV iCode operations will not be generated, and it also does
28423  not support JUMPTABLES.
28424
28425 \newline
28426
28427 \series bold
28428 \shape italic
28429 \color red
28430 <Where is Figure II?>
28431 \layout Comment
28432
28433 In the original article Figure II was announced to be downloadable on
28434 \shape italic
28435 Circuit Cellar
28436 \shape default
28437 's web site.
28438  Unfortunately it never seemed to have shown up there, so: where is Figure
28439  II?
28440 \layout Paragraph*
28441
28442 ICode Example
28443 \begin_inset LatexCommand \index{iCode}
28444
28445 \end_inset
28446
28447
28448 \layout Standard
28449
28450 This section shows some details of iCode.
28451  The example C code does not do anything useful; it is used as an example
28452  to illustrate the intermediate code generated by the compiler.
28453 \layout Verse
28454
28455
28456 \family typewriter
28457 1.\SpecialChar ~
28458 xdata int * p;
28459 \newline
28460 2.\SpecialChar ~
28461 int gint;
28462 \newline
28463 3.\SpecialChar ~
28464 /* This function does nothing useful.
28465  It is used
28466 \newline
28467 4.\SpecialChar ~
28468 \SpecialChar ~
28469 \SpecialChar ~
28470 \SpecialChar ~
28471 for the purpose of explaining iCode */
28472 \newline
28473 5.\SpecialChar ~
28474 short function (data int *x)
28475 \newline
28476 6.\SpecialChar ~
28477 {
28478 \newline
28479 7.\SpecialChar ~
28480 \SpecialChar ~
28481 \SpecialChar ~
28482 short i=10; \SpecialChar ~
28483 \SpecialChar ~
28484 /* dead initialization eliminated */
28485 \newline
28486 8.\SpecialChar ~
28487 \SpecialChar ~
28488 \SpecialChar ~
28489 short sum=10; /* dead initialization eliminated */
28490 \newline
28491 9.\SpecialChar ~
28492 \SpecialChar ~
28493 \SpecialChar ~
28494 short mul;
28495 \newline
28496 10.\SpecialChar ~
28497 \SpecialChar ~
28498 int j ;
28499 \newline
28500 11.\SpecialChar ~
28501 \SpecialChar ~
28502 while (*x) *x++ = *p++;
28503 \newline
28504 12.\SpecialChar ~
28505 \SpecialChar ~
28506 \SpecialChar ~
28507 \SpecialChar ~
28508 sum = 0 ;
28509 \newline
28510 13.\SpecialChar ~
28511 \SpecialChar ~
28512 mul = 0;
28513 \newline
28514 14.\SpecialChar ~
28515 \SpecialChar ~
28516 /* compiler detects i,j to be induction variables */
28517 \newline
28518 15.\SpecialChar ~
28519 \SpecialChar ~
28520 for (i = 0, j = 10 ; i < 10 ; i++, j
28521 \family default
28522 -
28523 \begin_inset ERT
28524 status Collapsed
28525
28526 \layout Standard
28527
28528 \backslash
28529 /
28530 \end_inset
28531
28532 -
28533 \family typewriter
28534 ) {
28535 \newline
28536 16.\SpecialChar ~
28537 \SpecialChar ~
28538 \SpecialChar ~
28539 \SpecialChar ~
28540 sum += i;
28541 \newline
28542 17.\SpecialChar ~
28543 \SpecialChar ~
28544 \SpecialChar ~
28545 \SpecialChar ~
28546 mul += i * 3; \SpecialChar ~
28547 \SpecialChar ~
28548 /* this multiplication remains */
28549 \newline
28550 18.\SpecialChar ~
28551 \SpecialChar ~
28552 \SpecialChar ~
28553 \SpecialChar ~
28554 gint += j * 3;\SpecialChar ~
28555 \SpecialChar ~
28556 /* this multiplication changed to addition */
28557 \newline
28558 19.\SpecialChar ~
28559 \SpecialChar ~
28560 }
28561 \newline
28562 20.\SpecialChar ~
28563 \SpecialChar ~
28564 return sum+mul;
28565 \newline
28566 21.\SpecialChar ~
28567 }
28568 \layout Standard
28569
28570 In addition to the operands each iCode contains information about the filename
28571  and line it corresponds to in the source file.
28572  The first field in the listing should be interpreted as follows:
28573 \newline
28574
28575 \shape italic
28576 \size footnotesize
28577 Filename(linenumber: iCode Execution sequence number : ICode hash table
28578  key : loop depth of the iCode).
28579 \shape default
28580 \size default
28581
28582 \newline
28583 Then follows the human readable form of the ICode operation.
28584  Each operand of this triplet form can be of three basic types a) compiler
28585  generated temporary b) user defined variable c) a constant value.
28586  Note that local variables and parameters are replaced by compiler generated
28587  temporaries.
28588  Live ranges
28589 \begin_inset LatexCommand \index{Live range analysis}
28590
28591 \end_inset
28592
28593  are computed only for temporaries (i.e.
28594  live ranges are not computed for global variables).
28595  Registers
28596 \begin_inset LatexCommand \index{Register allocation}
28597
28598 \end_inset
28599
28600  are allocated for temporaries only.
28601  Operands are formatted in the following manner:
28602 \newline
28603
28604 \shape italic
28605 \size footnotesize
28606 Operand Name [lr live-from : live-to ] { type information } [ registers
28607  allocated ].
28608 \shape default
28609 \size default
28610
28611 \newline
28612 As mentioned earlier the live ranges are computed in terms of the execution
28613  sequence number of the iCodes, for example
28614 \newline
28615 the iTemp0 is live from (i.e.
28616  first defined in iCode with execution sequence number 3, and is last used
28617  in the iCode with sequence number 5).
28618  For induction variables such as iTemp21 the live range computation extends
28619  the lifetime from the start to the end of the loop.
28620 \newline
28621 The register allocator used the live range information to allocate registers,
28622  the same registers may be used for different temporaries if their live
28623  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
28624  iTemp17 since their live ranges do not overlap.
28625  In addition the allocator also takes into consideration the type and usage
28626  of a temporary, for example itemp6 is a pointer to near space and is used
28627  as to fetch data from (i.e.
28628  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
28629  Some short lived temporaries are allocated to special registers which have
28630  meaning to the code generator e.g.
28631  iTemp13 is allocated to a pseudo register CC which tells the back end that
28632  the temporary is used only for a conditional jump the code generation makes
28633  use of this information to optimize a compare and jump ICode.
28634 \newline
28635 There are several loop optimizations
28636 \begin_inset LatexCommand \index{Loop optimization}
28637
28638 \end_inset
28639
28640  performed by the compiler.
28641  It can detect induction variables iTemp21(i) and iTemp23(j).
28642  Also note the compiler does selective strength reduction
28643 \begin_inset LatexCommand \index{Strength reduction}
28644
28645 \end_inset
28646
28647 , i.e.
28648  the multiplication of an induction variable in line 18 (gint = j * 3) is
28649  changed to addition, a new temporary iTemp17 is allocated and assigned
28650  a initial value, a constant 3 is then added for each iteration of the loop.
28651  The compiler does not change the multiplication
28652 \begin_inset LatexCommand \index{Multiplication}
28653
28654 \end_inset
28655
28656  in line 17 however since the processor does support an 8 * 8 bit multiplication.
28657 \newline
28658 Note the dead code elimination
28659 \begin_inset LatexCommand \index{Dead-code elimination}
28660
28661 \end_inset
28662
28663  optimization eliminated the dead assignments in line 7 & 8 to I and sum
28664  respectively.
28665 \newline
28666
28667 \layout Standard
28668
28669
28670 \size footnotesize
28671 Sample.c (5:1:0:0) _entry($9) :
28672 \layout Standard
28673
28674
28675 \size footnotesize
28676 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
28677 \layout Standard
28678
28679
28680 \size footnotesize
28681 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
28682 \layout Standard
28683
28684
28685 \size footnotesize
28686 Sample.c(11:4:53:0) preHeaderLbl0($11) :
28687 \layout Standard
28688
28689
28690 \size footnotesize
28691 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
28692  * int}[r2]
28693 \layout Standard
28694
28695
28696 \size footnotesize
28697 Sample.c(11:6:5:1) _whilecontinue_0($1) :
28698 \layout Standard
28699
28700
28701 \size footnotesize
28702 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
28703  int}[r0]]
28704 \layout Standard
28705
28706
28707 \size footnotesize
28708 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
28709 \layout Standard
28710
28711
28712 \size footnotesize
28713 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
28714  * int}
28715 \layout Standard
28716
28717
28718 \size footnotesize
28719 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
28720  {short}
28721 \layout Standard
28722
28723
28724 \size footnotesize
28725 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
28726  * int}[DPTR]]
28727 \layout Standard
28728
28729
28730 \size footnotesize
28731 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
28732 }[r2 r3]
28733 \layout Standard
28734
28735
28736 \size footnotesize
28737 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
28738  * int}[r0] + 0x2 {short}
28739 \layout Standard
28740
28741
28742 \size footnotesize
28743 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
28744 \layout Standard
28745
28746
28747 \size footnotesize
28748 Sample.c(11:17:21:0)_whilebreak_0($3) :
28749 \layout Standard
28750
28751
28752 \size footnotesize
28753 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
28754 \layout Standard
28755
28756
28757 \size footnotesize
28758 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
28759 \layout Standard
28760
28761
28762 \size footnotesize
28763 Sample.c(15:20:54:0)preHeaderLbl1($13) :
28764 \layout Standard
28765
28766
28767 \size footnotesize
28768 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
28769 \layout Standard
28770
28771
28772 \size footnotesize
28773 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
28774 \layout Standard
28775
28776
28777 \size footnotesize
28778 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
28779 \layout Standard
28780
28781
28782 \size footnotesize
28783 Sample.c(15:24:26:1)_forcond_0($4) :
28784 \layout Standard
28785
28786
28787 \size footnotesize
28788 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
28789  < 0xa {short}
28790 \layout Standard
28791
28792
28793 \size footnotesize
28794 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
28795 \layout Standard
28796
28797
28798 \size footnotesize
28799 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
28800  + ITemp21 [lr21:38]{short}[r4]
28801 \layout Standard
28802
28803
28804 \size footnotesize
28805 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
28806  * 0x3 {short}
28807 \layout Standard
28808
28809
28810 \size footnotesize
28811 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
28812  + iTemp15 [lr29:30]{short}[r1]
28813 \layout Standard
28814
28815
28816 \size footnotesize
28817 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
28818  r0]- 0x3 {short}
28819 \layout Standard
28820
28821
28822 \size footnotesize
28823 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
28824 int}[r7 r0]
28825 \layout Standard
28826
28827
28828 \size footnotesize
28829 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
28830  + 0x1 {short}
28831 \layout Standard
28832
28833
28834 \size footnotesize
28835 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
28836  r6]- 0x1 {short}
28837 \layout Standard
28838
28839
28840 \size footnotesize
28841 Sample.c(19:38:47:1) goto _forcond_0($4)
28842 \layout Standard
28843
28844
28845 \size footnotesize
28846 Sample.c(19:39:48:0)_forbreak_0($7) :
28847 \layout Standard
28848
28849
28850 \size footnotesize
28851 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
28852  + ITemp11 [lr19:40]{short}[r3]
28853 \layout Standard
28854
28855
28856 \size footnotesize
28857 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
28858 \layout Standard
28859
28860
28861 \size footnotesize
28862 Sample.c(20:42:51:0)_return($8) :
28863 \layout Standard
28864
28865
28866 \size footnotesize
28867 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
28868 \size default
28869
28870 \newline
28871
28872 \newline
28873 Finally the code generated for this function:
28874 \newline
28875
28876 \layout Standard
28877
28878
28879 \size footnotesize
28880 .area DSEG (DATA)
28881 \layout Standard
28882
28883
28884 \size footnotesize
28885 _p::
28886 \layout Standard
28887
28888
28889 \size footnotesize
28890 \SpecialChar ~
28891 \SpecialChar ~
28892 .ds 2
28893 \layout Standard
28894
28895
28896 \size footnotesize
28897 _gint::
28898 \layout Standard
28899
28900
28901 \size footnotesize
28902 \SpecialChar ~
28903 \SpecialChar ~
28904 .ds 2
28905 \layout Standard
28906
28907
28908 \size footnotesize
28909 ; sample.c 5
28910 \layout Standard
28911
28912
28913 \size footnotesize
28914 ; ----------------------------------------------
28915 \layout Standard
28916
28917
28918 \size footnotesize
28919 ; function function
28920 \layout Standard
28921
28922
28923 \size footnotesize
28924 ; ----------------------------------------------
28925 \layout Standard
28926
28927
28928 \size footnotesize
28929 _function:
28930 \layout Standard
28931
28932
28933 \size footnotesize
28934 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
28935 \layout Standard
28936
28937
28938 \size footnotesize
28939 \SpecialChar ~
28940 \SpecialChar ~
28941 mov r2,dpl
28942 \layout Standard
28943
28944
28945 \size footnotesize
28946 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
28947 \layout Standard
28948
28949
28950 \size footnotesize
28951 \SpecialChar ~
28952 \SpecialChar ~
28953 mov ar0,r2
28954 \layout Standard
28955
28956
28957 \size footnotesize
28958 ;_whilecontinue_0($1) :
28959 \layout Standard
28960
28961
28962 \size footnotesize
28963 00101$:
28964 \layout Standard
28965
28966
28967 \size footnotesize
28968 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
28969 \layout Standard
28970
28971
28972 \size footnotesize
28973 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
28974 \layout Standard
28975
28976
28977 \size footnotesize
28978 \SpecialChar ~
28979 \SpecialChar ~
28980 mov ar2,@r0
28981 \layout Standard
28982
28983
28984 \size footnotesize
28985 \SpecialChar ~
28986 \SpecialChar ~
28987 inc r0
28988 \layout Standard
28989
28990
28991 \size footnotesize
28992 \SpecialChar ~
28993 \SpecialChar ~
28994 mov ar3,@r0
28995 \layout Standard
28996
28997
28998 \size footnotesize
28999 \SpecialChar ~
29000 \SpecialChar ~
29001 dec r0
29002 \layout Standard
29003
29004
29005 \size footnotesize
29006 \SpecialChar ~
29007 \SpecialChar ~
29008 mov a,r2
29009 \layout Standard
29010
29011
29012 \size footnotesize
29013 \SpecialChar ~
29014 \SpecialChar ~
29015 orl a,r3
29016 \layout Standard
29017
29018
29019 \size footnotesize
29020 \SpecialChar ~
29021 \SpecialChar ~
29022 jz 00103$
29023 \layout Standard
29024
29025
29026 \size footnotesize
29027 00114$:
29028 \layout Standard
29029
29030
29031 \size footnotesize
29032 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
29033 \layout Standard
29034
29035
29036 \size footnotesize
29037 \SpecialChar ~
29038 \SpecialChar ~
29039 mov dpl,_p
29040 \layout Standard
29041
29042
29043 \size footnotesize
29044 \SpecialChar ~
29045 \SpecialChar ~
29046 mov dph,(_p + 1)
29047 \layout Standard
29048
29049
29050 \size footnotesize
29051 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
29052 \layout Standard
29053
29054
29055 \size footnotesize
29056 \SpecialChar ~
29057 \SpecialChar ~
29058 mov a,#0x02
29059 \layout Standard
29060
29061
29062 \size footnotesize
29063 \SpecialChar ~
29064 \SpecialChar ~
29065 add a,_p
29066 \layout Standard
29067
29068
29069 \size footnotesize
29070 \SpecialChar ~
29071 \SpecialChar ~
29072 mov _p,a
29073 \layout Standard
29074
29075
29076 \size footnotesize
29077 \SpecialChar ~
29078 \SpecialChar ~
29079 clr a
29080 \layout Standard
29081
29082
29083 \size footnotesize
29084 \SpecialChar ~
29085 \SpecialChar ~
29086 addc a,(_p + 1)
29087 \layout Standard
29088
29089
29090 \size footnotesize
29091 \SpecialChar ~
29092 \SpecialChar ~
29093 mov (_p + 1),a
29094 \layout Standard
29095
29096
29097 \size footnotesize
29098 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
29099 \layout Standard
29100
29101
29102 \size footnotesize
29103 \SpecialChar ~
29104 \SpecialChar ~
29105 movx a,@dptr
29106 \layout Standard
29107
29108
29109 \size footnotesize
29110 \SpecialChar ~
29111 \SpecialChar ~
29112 mov r2,a
29113 \layout Standard
29114
29115
29116 \size footnotesize
29117 \SpecialChar ~
29118 \SpecialChar ~
29119 inc dptr
29120 \layout Standard
29121
29122
29123 \size footnotesize
29124 \SpecialChar ~
29125 \SpecialChar ~
29126 movx a,@dptr
29127 \layout Standard
29128
29129
29130 \size footnotesize
29131 \SpecialChar ~
29132 \SpecialChar ~
29133 mov r3,a
29134 \layout Standard
29135
29136
29137 \size footnotesize
29138 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
29139 \layout Standard
29140
29141
29142 \size footnotesize
29143 \SpecialChar ~
29144 \SpecialChar ~
29145 mov @r0,ar2
29146 \layout Standard
29147
29148
29149 \size footnotesize
29150 \SpecialChar ~
29151 \SpecialChar ~
29152 inc r0
29153 \layout Standard
29154
29155
29156 \size footnotesize
29157 \SpecialChar ~
29158 \SpecialChar ~
29159 mov @r0,ar3
29160 \layout Standard
29161
29162
29163 \size footnotesize
29164 ; iTemp6 [lr5:16]{_near * int}[r0] =
29165 \layout Standard
29166
29167
29168 \size footnotesize
29169 ; iTemp6 [lr5:16]{_near * int}[r0] +
29170 \layout Standard
29171
29172
29173 \size footnotesize
29174 ; 0x2 {short}
29175 \layout Standard
29176
29177
29178 \size footnotesize
29179 \SpecialChar ~
29180 \SpecialChar ~
29181 inc r0
29182 \layout Standard
29183
29184
29185 \size footnotesize
29186 ; goto _whilecontinue_0($1)
29187 \layout Standard
29188
29189
29190 \size footnotesize
29191 \SpecialChar ~
29192 \SpecialChar ~
29193 sjmp 00101$
29194 \layout Standard
29195
29196
29197 \size footnotesize
29198 ; _whilebreak_0($3) :
29199 \layout Standard
29200
29201
29202 \size footnotesize
29203 00103$:
29204 \layout Standard
29205
29206
29207 \size footnotesize
29208 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
29209 \layout Standard
29210
29211
29212 \size footnotesize
29213 \SpecialChar ~
29214 \SpecialChar ~
29215 mov r2,#0x00
29216 \layout Standard
29217
29218
29219 \size footnotesize
29220 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
29221 \layout Standard
29222
29223
29224 \size footnotesize
29225 \SpecialChar ~
29226 \SpecialChar ~
29227 mov r3,#0x00
29228 \layout Standard
29229
29230
29231 \size footnotesize
29232 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
29233 \layout Standard
29234
29235
29236 \size footnotesize
29237 \SpecialChar ~
29238 \SpecialChar ~
29239 mov r4,#0x00
29240 \layout Standard
29241
29242
29243 \size footnotesize
29244 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
29245 \layout Standard
29246
29247
29248 \size footnotesize
29249 \SpecialChar ~
29250 \SpecialChar ~
29251 mov r5,#0x0A
29252 \layout Standard
29253
29254
29255 \size footnotesize
29256 \SpecialChar ~
29257 \SpecialChar ~
29258 mov r6,#0x00
29259 \layout Standard
29260
29261
29262 \size footnotesize
29263 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
29264 \layout Standard
29265
29266
29267 \size footnotesize
29268 \SpecialChar ~
29269 \SpecialChar ~
29270 mov r7,#0x1E
29271 \layout Standard
29272
29273
29274 \size footnotesize
29275 \SpecialChar ~
29276 \SpecialChar ~
29277 mov r0,#0x00
29278 \layout Standard
29279
29280
29281 \size footnotesize
29282 ; _forcond_0($4) :
29283 \layout Standard
29284
29285
29286 \size footnotesize
29287 00104$:
29288 \layout Standard
29289
29290
29291 \size footnotesize
29292 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
29293 \layout Standard
29294
29295
29296 \size footnotesize
29297 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
29298 \layout Standard
29299
29300
29301 \size footnotesize
29302 \SpecialChar ~
29303 \SpecialChar ~
29304 clr c
29305 \layout Standard
29306
29307
29308 \size footnotesize
29309 \SpecialChar ~
29310 \SpecialChar ~
29311 mov a,r4
29312 \layout Standard
29313
29314
29315 \size footnotesize
29316 \SpecialChar ~
29317 \SpecialChar ~
29318 xrl a,#0x80
29319 \layout Standard
29320
29321
29322 \size footnotesize
29323 \SpecialChar ~
29324 \SpecialChar ~
29325 subb a,#0x8a
29326 \layout Standard
29327
29328
29329 \size footnotesize
29330 \SpecialChar ~
29331 \SpecialChar ~
29332 jnc 00107$
29333 \layout Standard
29334
29335
29336 \size footnotesize
29337 00115$:
29338 \layout Standard
29339
29340
29341 \size footnotesize
29342 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
29343 \layout Standard
29344
29345
29346 \size footnotesize
29347 ; iTemp21 [lr21:38]{short}[r4]
29348 \layout Standard
29349
29350
29351 \size footnotesize
29352 \SpecialChar ~
29353 \SpecialChar ~
29354 mov a,r4
29355 \layout Standard
29356
29357
29358 \size footnotesize
29359 \SpecialChar ~
29360 \SpecialChar ~
29361 add a,r2
29362 \layout Standard
29363
29364
29365 \size footnotesize
29366 \SpecialChar ~
29367 \SpecialChar ~
29368 mov r2,a
29369 \layout Standard
29370
29371
29372 \size footnotesize
29373 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
29374 \layout Standard
29375
29376
29377 \size footnotesize
29378 \SpecialChar ~
29379 \SpecialChar ~
29380 mov b,#0x03
29381 \layout Standard
29382
29383
29384 \size footnotesize
29385 \SpecialChar ~
29386 \SpecialChar ~
29387 mov a,r4
29388 \layout Standard
29389
29390
29391 \size footnotesize
29392 \SpecialChar ~
29393 \SpecialChar ~
29394 mul ab
29395 \layout Standard
29396
29397
29398 \size footnotesize
29399 \SpecialChar ~
29400 \SpecialChar ~
29401 mov r1,a
29402 \layout Standard
29403
29404
29405 \size footnotesize
29406 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
29407 \layout Standard
29408
29409
29410 \size footnotesize
29411 ; iTemp15 [lr29:30]{short}[r1]
29412 \layout Standard
29413
29414
29415 \size footnotesize
29416 \SpecialChar ~
29417 \SpecialChar ~
29418 add a,r3
29419 \layout Standard
29420
29421
29422 \size footnotesize
29423 \SpecialChar ~
29424 \SpecialChar ~
29425 mov r3,a
29426 \layout Standard
29427
29428
29429 \size footnotesize
29430 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
29431 \layout Standard
29432
29433
29434 \size footnotesize
29435 \SpecialChar ~
29436 \SpecialChar ~
29437 mov a,r7
29438 \layout Standard
29439
29440
29441 \size footnotesize
29442 \SpecialChar ~
29443 \SpecialChar ~
29444 add a,#0xfd
29445 \layout Standard
29446
29447
29448 \size footnotesize
29449 \SpecialChar ~
29450 \SpecialChar ~
29451 mov r7,a
29452 \layout Standard
29453
29454
29455 \size footnotesize
29456 \SpecialChar ~
29457 \SpecialChar ~
29458 mov a,r0
29459 \layout Standard
29460
29461
29462 \size footnotesize
29463 \SpecialChar ~
29464 \SpecialChar ~
29465 addc a,#0xff
29466 \layout Standard
29467
29468
29469 \size footnotesize
29470 \SpecialChar ~
29471 \SpecialChar ~
29472 mov r0,a
29473 \layout Standard
29474
29475
29476 \size footnotesize
29477 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
29478 \layout Standard
29479
29480
29481 \size footnotesize
29482 \SpecialChar ~
29483 \SpecialChar ~
29484 mov a,r7
29485 \layout Standard
29486
29487
29488 \size footnotesize
29489 \SpecialChar ~
29490 \SpecialChar ~
29491 add a,_gint
29492 \layout Standard
29493
29494
29495 \size footnotesize
29496 \SpecialChar ~
29497 \SpecialChar ~
29498 mov _gint,a
29499 \layout Standard
29500
29501
29502 \size footnotesize
29503 \SpecialChar ~
29504 \SpecialChar ~
29505 mov a,r0
29506 \layout Standard
29507
29508
29509 \size footnotesize
29510 \SpecialChar ~
29511 \SpecialChar ~
29512 addc a,(_gint + 1)
29513 \layout Standard
29514
29515
29516 \size footnotesize
29517 \SpecialChar ~
29518 \SpecialChar ~
29519 mov (_gint + 1),a
29520 \layout Standard
29521
29522
29523 \size footnotesize
29524 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
29525 \layout Standard
29526
29527
29528 \size footnotesize
29529 \SpecialChar ~
29530 \SpecialChar ~
29531 inc r4
29532 \layout Standard
29533
29534
29535 \size footnotesize
29536 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
29537 \layout Standard
29538
29539
29540 \size footnotesize
29541 \SpecialChar ~
29542 \SpecialChar ~
29543 dec r5
29544 \layout Standard
29545
29546
29547 \size footnotesize
29548 \SpecialChar ~
29549 \SpecialChar ~
29550 cjne r5,#0xff,00104$
29551 \layout Standard
29552
29553
29554 \size footnotesize
29555 \SpecialChar ~
29556 \SpecialChar ~
29557 dec r6
29558 \layout Standard
29559
29560
29561 \size footnotesize
29562 ; goto _forcond_0($4)
29563 \layout Standard
29564
29565
29566 \size footnotesize
29567 \SpecialChar ~
29568 \SpecialChar ~
29569 sjmp 00104$
29570 \layout Standard
29571
29572
29573 \size footnotesize
29574 ; _forbreak_0($7) :
29575 \layout Standard
29576
29577
29578 \size footnotesize
29579 00107$:
29580 \layout Standard
29581
29582
29583 \size footnotesize
29584 ; ret iTemp24 [lr40:41]{short}
29585 \layout Standard
29586
29587
29588 \size footnotesize
29589 \SpecialChar ~
29590 \SpecialChar ~
29591 mov a,r3
29592 \layout Standard
29593
29594
29595 \size footnotesize
29596 \SpecialChar ~
29597 \SpecialChar ~
29598 add a,r2
29599 \layout Standard
29600
29601
29602 \size footnotesize
29603 \SpecialChar ~
29604 \SpecialChar ~
29605 mov dpl,a
29606 \layout Standard
29607
29608
29609 \size footnotesize
29610 ; _return($8) :
29611 \layout Standard
29612
29613
29614 \size footnotesize
29615 00108$:
29616 \layout Standard
29617
29618
29619 \size footnotesize
29620 \SpecialChar ~
29621 \SpecialChar ~
29622 ret
29623 \newline
29624
29625 \layout Section
29626
29627 A few words about basic block successors, predecessors and dominators
29628 \layout Standard
29629
29630 Successors are basic blocks
29631 \begin_inset LatexCommand \index{Basic blocks}
29632
29633 \end_inset
29634
29635  that might execute after this basic block.
29636 \newline
29637 Predecessors are basic blocks that might execute before reaching this basic
29638  block.
29639 \newline
29640 Dominators are basic blocks that WILL execute before reaching this basic
29641  block.
29642 \newline
29643
29644 \layout Standard
29645
29646 [basic block 1]
29647 \layout Standard
29648
29649 if (something)
29650 \layout Standard
29651
29652 \SpecialChar ~
29653 \SpecialChar ~
29654 \SpecialChar ~
29655 \SpecialChar ~
29656 [basic block 2]
29657 \layout Standard
29658
29659 else
29660 \layout Standard
29661
29662 \SpecialChar ~
29663 \SpecialChar ~
29664 \SpecialChar ~
29665 \SpecialChar ~
29666 [basic block 3]
29667 \layout Standard
29668
29669 [basic block 4]
29670 \newline
29671
29672 \layout Standard
29673
29674 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
29675 \layout Standard
29676
29677 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
29678 \layout Standard
29679
29680 c) domVect of [BB4] = BB1 ...
29681  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
29682  was executed.
29683 \layout Chapter
29684
29685 Acknowledgments
29686 \layout Standard
29687
29688
29689 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
29690
29691 \end_inset
29692
29693
29694 \newline
29695
29696 \newline
29697
29698 \emph on
29699 Thanks to all the other volunteer developers who have helped with coding,
29700  testing, web-page creation, distribution sets, etc.
29701  You know who you are :-)
29702 \emph default
29703
29704 \newline
29705
29706 \layout Standard
29707
29708 This document was initially written by Sandeep Dutta
29709 \layout Standard
29710
29711 All product names mentioned herein may be trademarks
29712 \begin_inset LatexCommand \index{Trademarks}
29713
29714 \end_inset
29715
29716  of their respective companies.
29717
29718 \layout Section*
29719
29720 Alphabetical index
29721 \layout Standard
29722
29723 To avoid confusion, the installation and building options for SDCC itself
29724  (chapter 2) are not part of the index.
29725 \layout Standard
29726
29727
29728 \begin_inset LatexCommand \printindex{}
29729
29730 \end_inset
29731
29732
29733 \the_end