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 -host=i586-mingw32msvc
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 -build=unknown-unknown-linux-gnu
1967 \layout Standard
1968
1969 To
1970 \begin_inset Quotes sld
1971 \end_inset
1972
1973 cross
1974 \begin_inset Quotes srd
1975 \end_inset
1976
1977 compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32
1978 ):
1979 \layout LyX-Code
1980
1981 ./configure -C
1982 \backslash
1983
1984 \newline
1985 -
1986 \begin_inset ERT
1987 status Collapsed
1988
1989 \layout Standard
1990
1991 \backslash
1992 /
1993 \end_inset
1994
1995 -prefix=
1996 \begin_inset Quotes srd
1997 \end_inset
1998
1999 /sdcc
2000 \begin_inset Quotes srd
2001 \end_inset
2002
2003
2004 \backslash
2005
2006 \newline
2007 -
2008 \begin_inset ERT
2009 status Collapsed
2010
2011 \layout Standard
2012
2013 \backslash
2014 /
2015 \end_inset
2016
2017 -datadir=
2018 \begin_inset Quotes srd
2019 \end_inset
2020
2021 /sdcc
2022 \begin_inset Quotes srd
2023 \end_inset
2024
2025
2026 \backslash
2027
2028 \newline
2029 docdir=
2030 \begin_inset Quotes srd
2031 \end_inset
2032
2033 /sdcc/doc
2034 \begin_inset Quotes srd
2035 \end_inset
2036
2037
2038 \backslash
2039
2040 \newline
2041 include_dir_suffix=
2042 \begin_inset Quotes srd
2043 \end_inset
2044
2045 include
2046 \begin_inset Quotes srd
2047 \end_inset
2048
2049
2050 \backslash
2051
2052 \newline
2053 lib_dir_suffix=
2054 \begin_inset Quotes srd
2055 \end_inset
2056
2057 lib
2058 \begin_inset Quotes srd
2059 \end_inset
2060
2061
2062 \backslash
2063
2064 \newline
2065 sdccconf_h_dir_separator=
2066 \begin_inset Quotes srd
2067 \end_inset
2068
2069
2070 \backslash
2071
2072 \backslash
2073
2074 \backslash
2075
2076 \backslash
2077
2078 \begin_inset Quotes srd
2079 \end_inset
2080
2081
2082 \backslash
2083
2084 \newline
2085 CC=
2086 \begin_inset Quotes srd
2087 \end_inset
2088
2089 gcc -mno-cygwin
2090 \begin_inset Quotes srd
2091 \end_inset
2092
2093
2094 \backslash
2095
2096 \newline
2097 CXX=
2098 \begin_inset Quotes srd
2099 \end_inset
2100
2101 g++ -mno-cygwin
2102 \begin_inset Quotes srd
2103 \end_inset
2104
2105
2106 \layout Standard
2107
2108 'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
2109  The option '-
2110 \begin_inset ERT
2111 status Collapsed
2112
2113 \layout Standard
2114
2115 \backslash
2116 /
2117 \end_inset
2118
2119 -C' turns on caching, which gives a little bit extra speed.
2120  However if options are changed, it can be necessary to delete the config.cache
2121  file.
2122 \layout Section
2123
2124 Install paths
2125 \begin_inset LatexCommand \label{sub:Install-paths}
2126
2127 \end_inset
2128
2129
2130 \begin_inset LatexCommand \index{Install paths}
2131
2132 \end_inset
2133
2134
2135 \layout Standard
2136 \added_space_top medskip \align center
2137
2138 \begin_inset  Tabular
2139 <lyxtabular version="3" rows="5" columns="4">
2140 <features>
2141 <column alignment="left" valignment="top" leftline="true" width="0">
2142 <column alignment="left" valignment="top" leftline="true" width="0">
2143 <column alignment="left" valignment="top" leftline="true" width="0">
2144 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
2145 <row topline="true" bottomline="true">
2146 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2147 \begin_inset Text
2148
2149 \layout Standard
2150
2151
2152 \series bold
2153 Description
2154 \end_inset
2155 </cell>
2156 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2157 \begin_inset Text
2158
2159 \layout Standard
2160
2161
2162 \series bold
2163 Path
2164 \end_inset
2165 </cell>
2166 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2167 \begin_inset Text
2168
2169 \layout Standard
2170
2171
2172 \series bold
2173 Default
2174 \end_inset
2175 </cell>
2176 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2177 \begin_inset Text
2178
2179 \layout Standard
2180
2181
2182 \series bold
2183 Win32 builds
2184 \end_inset
2185 </cell>
2186 </row>
2187 <row topline="true">
2188 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2189 \begin_inset Text
2190
2191 \layout Standard
2192
2193 Binary files*
2194 \end_inset
2195 </cell>
2196 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2197 \begin_inset Text
2198
2199 \layout Standard
2200
2201
2202 \emph on
2203 $EXEC_PREFIX
2204 \end_inset
2205 </cell>
2206 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2207 \begin_inset Text
2208
2209 \layout Standard
2210
2211 /usr/local/bin
2212 \end_inset
2213 </cell>
2214 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2215 \begin_inset Text
2216
2217 \layout Standard
2218
2219
2220 \backslash
2221 sdcc
2222 \backslash
2223 bin
2224 \end_inset
2225 </cell>
2226 </row>
2227 <row topline="true">
2228 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2229 \begin_inset Text
2230
2231 \layout Standard
2232
2233 Include files
2234 \end_inset
2235 </cell>
2236 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2237 \begin_inset Text
2238
2239 \layout Standard
2240
2241
2242 \emph on
2243 $DATADIR/ $INCLUDE_DIR_SUFFIX
2244 \end_inset
2245 </cell>
2246 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2247 \begin_inset Text
2248
2249 \layout Standard
2250
2251 /usr/local/share/sdcc/include
2252 \end_inset
2253 </cell>
2254 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2255 \begin_inset Text
2256
2257 \layout Standard
2258
2259
2260 \backslash
2261 sdcc
2262 \backslash
2263 include
2264 \end_inset
2265 </cell>
2266 </row>
2267 <row topline="true">
2268 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2269 \begin_inset Text
2270
2271 \layout Standard
2272
2273 Library file**
2274 \end_inset
2275 </cell>
2276 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2277 \begin_inset Text
2278
2279 \layout Standard
2280
2281
2282 \emph on
2283 $DATADIR/$LIB_DIR_SUFFIX
2284 \end_inset
2285 </cell>
2286 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2287 \begin_inset Text
2288
2289 \layout Standard
2290
2291 /usr/local/share/sdcc/lib
2292 \end_inset
2293 </cell>
2294 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2295 \begin_inset Text
2296
2297 \layout Standard
2298
2299
2300 \backslash
2301 sdcc
2302 \backslash
2303 lib
2304 \end_inset
2305 </cell>
2306 </row>
2307 <row topline="true" bottomline="true">
2308 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2309 \begin_inset Text
2310
2311 \layout Standard
2312
2313 Documentation
2314 \end_inset
2315 </cell>
2316 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2317 \begin_inset Text
2318
2319 \layout Standard
2320
2321
2322 \emph on
2323 $DOCDIR
2324 \end_inset
2325 </cell>
2326 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2327 \begin_inset Text
2328
2329 \layout Standard
2330
2331 /usr/local/share/sdcc/doc
2332 \end_inset
2333 </cell>
2334 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2335 \begin_inset Text
2336
2337 \layout Standard
2338
2339
2340 \backslash
2341 sdcc
2342 \backslash
2343 doc
2344 \end_inset
2345 </cell>
2346 </row>
2347 </lyxtabular>
2348
2349 \end_inset
2350
2351
2352 \layout Verse
2353
2354
2355 \size footnotesize
2356 *compiler, preprocessor, assembler, and linker
2357 \newline
2358 **the
2359 \shape italic
2360 model
2361 \shape default
2362  is auto-appended by the compiler, e.g.
2363  small, large, z80, ds390 etc
2364 \layout Standard
2365 \noindent
2366 The install paths can still be changed during `make install` with e.g.:
2367 \layout LyX-Code
2368
2369 make install prefix=$(HOME)/local/sdcc
2370 \layout Standard
2371
2372 Of course this doesn't change the search paths compiled into the binaries.
2373 \newline
2374
2375 \newline
2376 Moreover the install path can be changed by defining DESTDIR
2377 \begin_inset LatexCommand \index{DESTDIR}
2378
2379 \end_inset
2380
2381 :
2382 \layout LyX-Code
2383
2384 make install DESTDIR=$(HOME)/sdcc.rpm/
2385 \layout Standard
2386
2387 Please note that DESTDIR must have a trailing slash!
2388 \layout Section
2389
2390 Search Paths
2391 \begin_inset LatexCommand \label{sub:Search-Paths}
2392
2393 \end_inset
2394
2395
2396 \begin_inset LatexCommand \index{Search path}
2397
2398 \end_inset
2399
2400
2401 \layout Standard
2402
2403 Some search paths or parts of them are determined by configure variables
2404  (in
2405 \emph on
2406 italics
2407 \emph default
2408 , see section above).
2409  Further search paths are determined by environment variables during runtime.
2410
2411 \newline
2412 The paths searched when running the compiler are as follows (the first catch
2413  wins):
2414 \newline
2415
2416 \newline
2417 1.
2418  Binary files (preprocessor, assembler and linker)
2419 \newline
2420
2421 \layout Standard
2422 \align center
2423
2424 \begin_inset  Tabular
2425 <lyxtabular version="3" rows="4" columns="3">
2426 <features>
2427 <column alignment="block" valignment="top" leftline="true" width="0in">
2428 <column alignment="block" valignment="top" leftline="true" width="0in">
2429 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2430 <row topline="true" bottomline="true">
2431 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2432 \begin_inset Text
2433
2434 \layout Standard
2435
2436 Search path
2437 \end_inset
2438 </cell>
2439 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2440 \begin_inset Text
2441
2442 \layout Standard
2443
2444 default
2445 \end_inset
2446 </cell>
2447 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2448 \begin_inset Text
2449
2450 \layout Standard
2451
2452 Win32 builds
2453 \end_inset
2454 </cell>
2455 </row>
2456 <row topline="true">
2457 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2458 \begin_inset Text
2459
2460 \layout Standard
2461
2462 $SDCC_HOME/
2463 \emph on
2464 $PPREFIX2BIN_DIR
2465 \end_inset
2466 </cell>
2467 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2468 \begin_inset Text
2469
2470 \layout Standard
2471
2472 $SDCC_HOME/bin
2473 \end_inset
2474 </cell>
2475 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2476 \begin_inset Text
2477
2478 \layout Standard
2479
2480 $SDCC_HOME
2481 \backslash
2482 bin
2483 \end_inset
2484 </cell>
2485 </row>
2486 <row topline="true">
2487 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2488 \begin_inset Text
2489
2490 \layout Standard
2491
2492 Path of argv[0] (if available)
2493 \end_inset
2494 </cell>
2495 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2496 \begin_inset Text
2497
2498 \layout Standard
2499
2500 Path of argv[0]
2501 \end_inset
2502 </cell>
2503 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2504 \begin_inset Text
2505
2506 \layout Standard
2507
2508 Path of argv[0]
2509 \end_inset
2510 </cell>
2511 </row>
2512 <row topline="true" bottomline="true">
2513 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2514 \begin_inset Text
2515
2516 \layout Standard
2517
2518 $PATH
2519 \end_inset
2520 </cell>
2521 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2522 \begin_inset Text
2523
2524 \layout Standard
2525
2526 $PATH
2527 \end_inset
2528 </cell>
2529 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2530 \begin_inset Text
2531
2532 \layout Standard
2533
2534 $PATH
2535 \end_inset
2536 </cell>
2537 </row>
2538 </lyxtabular>
2539
2540 \end_inset
2541
2542
2543 \newline
2544
2545 \layout Standard
2546 \noindent
2547 2.
2548  Include files
2549 \newline
2550
2551 \layout Standard
2552 \align center
2553
2554 \begin_inset  Tabular
2555 <lyxtabular version="3" rows="6" columns="3">
2556 <features>
2557 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2558 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2559 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2560 <row topline="true" bottomline="true">
2561 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2562 \begin_inset Text
2563
2564 \layout Standard
2565
2566 Search path
2567 \end_inset
2568 </cell>
2569 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2570 \begin_inset Text
2571
2572 \layout Standard
2573
2574 default
2575 \end_inset
2576 </cell>
2577 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2578 \begin_inset Text
2579
2580 \layout Standard
2581
2582 Win32 builds
2583 \end_inset
2584 </cell>
2585 </row>
2586 <row topline="true">
2587 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2588 \begin_inset Text
2589
2590 \layout Standard
2591
2592 -
2593 \begin_inset ERT
2594 status Collapsed
2595
2596 \layout Standard
2597
2598 \backslash
2599 /
2600 \end_inset
2601
2602 -I dir
2603 \end_inset
2604 </cell>
2605 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2606 \begin_inset Text
2607
2608 \layout Standard
2609
2610 -
2611 \begin_inset ERT
2612 status Collapsed
2613
2614 \layout Standard
2615
2616 \backslash
2617 /
2618 \end_inset
2619
2620 -I dir
2621 \end_inset
2622 </cell>
2623 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2624 \begin_inset Text
2625
2626 \layout Standard
2627
2628 -
2629 \begin_inset ERT
2630 status Collapsed
2631
2632 \layout Standard
2633
2634 \backslash
2635 /
2636 \end_inset
2637
2638 -I dir
2639 \end_inset
2640 </cell>
2641 </row>
2642 <row topline="true">
2643 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2644 \begin_inset Text
2645
2646 \layout Standard
2647
2648 $SDCC_INCLUDE
2649 \end_inset
2650 </cell>
2651 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2652 \begin_inset Text
2653
2654 \layout Standard
2655
2656 $SDCC_INCLUDE
2657 \end_inset
2658 </cell>
2659 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2660 \begin_inset Text
2661
2662 \layout Standard
2663
2664 $SDCC_INCLUDE
2665 \end_inset
2666 </cell>
2667 </row>
2668 <row topline="true">
2669 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2670 \begin_inset Text
2671
2672 \layout Standard
2673
2674 $SDCC_HOME/
2675 \newline
2676
2677 \emph on
2678 $PREFIX2DATA_DIR/
2679 \newline
2680 $INCLUDE_DIR_SUFFIX
2681 \end_inset
2682 </cell>
2683 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2684 \begin_inset Text
2685
2686 \layout Standard
2687
2688 $SDCC_ HOME/
2689 \newline
2690 share/sdcc/
2691 \newline
2692 include
2693 \end_inset
2694 </cell>
2695 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2696 \begin_inset Text
2697
2698 \layout Standard
2699
2700 $SDCC_HOME
2701 \backslash
2702 include
2703 \end_inset
2704 </cell>
2705 </row>
2706 <row topline="true">
2707 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2708 \begin_inset Text
2709
2710 \layout Standard
2711
2712 path(argv[0])/
2713 \newline
2714
2715 \emph on
2716 $BIN2DATADIR/
2717 \emph default
2718
2719 \newline
2720
2721 \emph on
2722 $INCLUDE_DIR_SUFFIX
2723 \end_inset
2724 </cell>
2725 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2726 \begin_inset Text
2727
2728 \layout Standard
2729
2730 path(argv[0])/
2731 \newline
2732 ../sdcc/include
2733 \newline
2734 \SpecialChar ~
2735 \SpecialChar ~
2736 \SpecialChar ~
2737 \SpecialChar ~
2738 \SpecialChar ~
2739 \SpecialChar ~
2740 \SpecialChar ~
2741 \SpecialChar ~
2742 \SpecialChar ~
2743 \SpecialChar ~
2744 \SpecialChar ~
2745 \SpecialChar ~
2746 \SpecialChar ~
2747 \SpecialChar ~
2748 \SpecialChar ~
2749 \SpecialChar ~
2750 \SpecialChar ~
2751 \SpecialChar ~
2752 \SpecialChar ~
2753 \SpecialChar ~
2754 \SpecialChar ~
2755 \SpecialChar ~
2756 \SpecialChar ~
2757 \SpecialChar ~
2758 \SpecialChar ~
2759 \SpecialChar ~
2760 \SpecialChar ~
2761 \SpecialChar ~
2762 \SpecialChar ~
2763 \SpecialChar ~
2764 \SpecialChar ~
2765 \SpecialChar ~
2766 \SpecialChar ~
2767 \SpecialChar ~
2768 \SpecialChar ~
2769 \SpecialChar ~
2770 \SpecialChar ~
2771 \SpecialChar ~
2772
2773 \end_inset
2774 </cell>
2775 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2776 \begin_inset Text
2777
2778 \layout Standard
2779
2780 path(argv[0])
2781 \backslash
2782 ..
2783 \backslash
2784 include
2785 \end_inset
2786 </cell>
2787 </row>
2788 <row topline="true" bottomline="true">
2789 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2790 \begin_inset Text
2791
2792 \layout Standard
2793
2794
2795 \emph on
2796 $DATADIR/
2797 \emph default
2798
2799 \newline
2800
2801 \emph on
2802 $INCLUDE_DIR_SUFFIX
2803 \end_inset
2804 </cell>
2805 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2806 \begin_inset Text
2807
2808 \layout Standard
2809
2810 /usr/local/share/sdcc/
2811 \newline
2812 include
2813 \end_inset
2814 </cell>
2815 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2816 \begin_inset Text
2817
2818 \layout Standard
2819
2820 (not on Win32)
2821 \end_inset
2822 </cell>
2823 </row>
2824 </lyxtabular>
2825
2826 \end_inset
2827
2828
2829 \newline
2830
2831 \layout Standard
2832 \noindent
2833 The option -
2834 \begin_inset ERT
2835 status Collapsed
2836
2837 \layout Standard
2838
2839 \backslash
2840 /
2841 \end_inset
2842
2843 -nostdinc disables the last two search paths.
2844 \newline
2845
2846 \newline
2847 3.
2848  Library files
2849 \newline
2850
2851 \layout Standard
2852
2853 With the exception of
2854 \begin_inset Quotes sld
2855 \end_inset
2856
2857 -
2858 \begin_inset ERT
2859 status Collapsed
2860
2861 \layout Standard
2862
2863 \backslash
2864 /
2865 \end_inset
2866
2867 -L dir
2868 \begin_inset Quotes srd
2869 \end_inset
2870
2871  the
2872 \shape italic
2873 model
2874 \shape default
2875  is auto-appended by the compiler (e.g.
2876  small, large, z80, ds390 etc.).
2877
2878 \newline
2879
2880 \layout Standard
2881 \align center
2882
2883 \begin_inset  Tabular
2884 <lyxtabular version="3" rows="6" columns="3">
2885 <features>
2886 <column alignment="block" valignment="top" leftline="true" width="1.7in">
2887 <column alignment="block" valignment="top" leftline="true" width="1.2in">
2888 <column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
2889 <row topline="true" bottomline="true">
2890 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2891 \begin_inset Text
2892
2893 \layout Standard
2894
2895 Search path
2896 \end_inset
2897 </cell>
2898 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2899 \begin_inset Text
2900
2901 \layout Standard
2902
2903 default
2904 \end_inset
2905 </cell>
2906 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2907 \begin_inset Text
2908
2909 \layout Standard
2910
2911 Win32 builds
2912 \end_inset
2913 </cell>
2914 </row>
2915 <row topline="true">
2916 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2917 \begin_inset Text
2918
2919 \layout Standard
2920
2921 -
2922 \begin_inset ERT
2923 status Collapsed
2924
2925 \layout Standard
2926
2927 \backslash
2928 /
2929 \end_inset
2930
2931 -L dir
2932 \end_inset
2933 </cell>
2934 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2935 \begin_inset Text
2936
2937 \layout Standard
2938
2939 -
2940 \begin_inset ERT
2941 status Collapsed
2942
2943 \layout Standard
2944
2945 \backslash
2946 /
2947 \end_inset
2948
2949 -L dir
2950 \end_inset
2951 </cell>
2952 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2953 \begin_inset Text
2954
2955 \layout Standard
2956
2957 -
2958 \begin_inset ERT
2959 status Collapsed
2960
2961 \layout Standard
2962
2963 \backslash
2964 /
2965 \end_inset
2966
2967 -L dir
2968 \end_inset
2969 </cell>
2970 </row>
2971 <row topline="true">
2972 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2973 \begin_inset Text
2974
2975 \layout Standard
2976
2977 $SDCC_LIB/
2978 \newline
2979
2980 \emph on
2981 <model>
2982 \end_inset
2983 </cell>
2984 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2985 \begin_inset Text
2986
2987 \layout Standard
2988
2989 $SDCC_LIB/
2990 \newline
2991
2992 \emph on
2993 <model>
2994 \end_inset
2995 </cell>
2996 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2997 \begin_inset Text
2998
2999 \layout Standard
3000
3001 $SDCC_LIB
3002 \backslash
3003
3004 \newline
3005
3006 \emph on
3007 <model>
3008 \end_inset
3009 </cell>
3010 </row>
3011 <row topline="true">
3012 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3013 \begin_inset Text
3014
3015 \layout Standard
3016
3017 $SDCC_HOME/
3018 \newline
3019
3020 \emph on
3021 $PREFIX2DATA_DIR/
3022 \newline
3023 $LIB_DIR_SUFFIX/<model>
3024 \end_inset
3025 </cell>
3026 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3027 \begin_inset Text
3028
3029 \layout Standard
3030
3031 $SDCC_HOME/
3032 \newline
3033 share/sdcc/
3034 \newline
3035 lib/
3036 \emph on
3037 <model>
3038 \end_inset
3039 </cell>
3040 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3041 \begin_inset Text
3042
3043 \layout Standard
3044
3045 $SDCC_HOME
3046 \backslash
3047 lib
3048 \backslash
3049
3050 \emph on
3051
3052 \newline
3053 <model>
3054 \end_inset
3055 </cell>
3056 </row>
3057 <row topline="true">
3058 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3059 \begin_inset Text
3060
3061 \layout Standard
3062
3063 path(argv[0])/
3064 \newline
3065
3066 \emph on
3067 $BIN2DATADIR/
3068 \emph default
3069
3070 \newline
3071
3072 \emph on
3073 $LIB_DIR_SUFFIX/<model>
3074 \end_inset
3075 </cell>
3076 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3077 \begin_inset Text
3078
3079 \layout Standard
3080
3081 path(argv[0])/
3082 \newline
3083 ../sdcc/lib/
3084 \emph on
3085 <model>
3086 \newline
3087 \SpecialChar ~
3088 \SpecialChar ~
3089 \SpecialChar ~
3090 \SpecialChar ~
3091 \SpecialChar ~
3092 \SpecialChar ~
3093 \SpecialChar ~
3094 \SpecialChar ~
3095 \SpecialChar ~
3096 \SpecialChar ~
3097 \SpecialChar ~
3098 \SpecialChar ~
3099 \SpecialChar ~
3100 \SpecialChar ~
3101 \SpecialChar ~
3102 \SpecialChar ~
3103 \SpecialChar ~
3104 \SpecialChar ~
3105 \SpecialChar ~
3106 \SpecialChar ~
3107 \SpecialChar ~
3108 \SpecialChar ~
3109 \SpecialChar ~
3110 \SpecialChar ~
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
3127 \end_inset
3128 </cell>
3129 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3130 \begin_inset Text
3131
3132 \layout Standard
3133
3134 path(argv[0])
3135 \backslash
3136
3137 \newline
3138 ..
3139 \backslash
3140 lib
3141 \backslash
3142
3143 \emph on
3144 <model>
3145 \newline
3146 \SpecialChar ~
3147 \SpecialChar ~
3148 \SpecialChar ~
3149 \SpecialChar ~
3150 \SpecialChar ~
3151 \SpecialChar ~
3152 \SpecialChar ~
3153 \SpecialChar ~
3154 \SpecialChar ~
3155 \SpecialChar ~
3156 \SpecialChar ~
3157 \SpecialChar ~
3158 \SpecialChar ~
3159 \SpecialChar ~
3160 \SpecialChar ~
3161 \SpecialChar ~
3162 \SpecialChar ~
3163 \SpecialChar ~
3164 \SpecialChar ~
3165 \SpecialChar ~
3166 \SpecialChar ~
3167 \SpecialChar ~
3168 \SpecialChar ~
3169 \SpecialChar ~
3170 \SpecialChar ~
3171 \SpecialChar ~
3172 \SpecialChar ~
3173 \SpecialChar ~
3174 \SpecialChar ~
3175 \SpecialChar ~
3176 \SpecialChar ~
3177 \SpecialChar ~
3178 \SpecialChar ~
3179 \SpecialChar ~
3180 \SpecialChar ~
3181
3182 \end_inset
3183 </cell>
3184 </row>
3185 <row topline="true" bottomline="true">
3186 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3187 \begin_inset Text
3188
3189 \layout Standard
3190
3191
3192 \emph on
3193 $DATADIR/
3194 \newline
3195 $LIB_DIR_SUFFIX/<model>
3196 \end_inset
3197 </cell>
3198 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3199 \begin_inset Text
3200
3201 \layout Standard
3202
3203 /usr/local/share/sdcc/
3204 \newline
3205 lib/
3206 \emph on
3207 <model>
3208 \end_inset
3209 </cell>
3210 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3211 \begin_inset Text
3212
3213 \layout Standard
3214
3215 (not on Win32)
3216 \end_inset
3217 </cell>
3218 </row>
3219 </lyxtabular>
3220
3221 \end_inset
3222
3223
3224 \newline
3225
3226 \layout Comment
3227
3228 Don't delete any of the stray spaces in the table above without checking
3229  the HTML output (last line)!
3230 \layout Standard
3231
3232 \SpecialChar ~
3233
3234 \newline
3235 The option -
3236 \begin_inset ERT
3237 status Collapsed
3238
3239 \layout Standard
3240
3241 \backslash
3242 /
3243 \end_inset
3244
3245 -nostdlib disables the last two search paths.
3246 \layout Section
3247
3248 Building SDCC
3249 \begin_inset LatexCommand \index{Building SDCC}
3250
3251 \end_inset
3252
3253
3254 \layout Subsection
3255
3256 Building SDCC on Linux
3257 \begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux}
3258
3259 \end_inset
3260
3261
3262 \layout Enumerate
3263
3264
3265 \series medium
3266 Download the source package
3267 \series default
3268  either from the SDCC Subversion repository or from the nightly snapshots
3269 \series medium
3270 , it will be named something like sdcc
3271 \series default
3272 .src
3273 \series medium
3274 .t
3275 \series default
3276 ar.
3277 \series medium
3278 gz
3279 \series default
3280
3281 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
3282
3283 \end_inset
3284
3285 .
3286 \layout Enumerate
3287
3288
3289 \series medium
3290 Bring up a command line terminal, such as xterm.
3291 \layout Enumerate
3292
3293
3294 \series medium
3295 Unpack the file using a command like:
3296 \family sans
3297 \series bold
3298 "tar -xvzf sdcc.src.tar.gz
3299 \family default
3300 \series default
3301 "
3302 \series medium
3303 , this will create a sub-directory called sdcc with all of the sources.
3304 \layout Enumerate
3305
3306 Change directory into the main SDCC directory, for example type:
3307 \family sans
3308 \series bold
3309 "cd sdcc
3310 \series default
3311 ".
3312 \layout Enumerate
3313
3314
3315 \series medium
3316 Type
3317 \family sans
3318 \series bold
3319 "./configure
3320 \family default
3321 \series default
3322 ".
3323  This configures the package for compilation on your system.
3324 \layout Enumerate
3325
3326
3327 \series medium
3328 Type
3329 \family sans
3330 \series bold
3331 "make
3332 \family default
3333 \series default
3334 "
3335 \series medium
3336 .
3337
3338 \series default
3339  All of the source packages will compile, this can take a while.
3340 \layout Enumerate
3341
3342
3343 \series medium
3344 Type
3345 \family sans
3346 \series bold
3347 "make install"
3348 \family default
3349 \series default
3350  as root
3351 \series medium
3352 .
3353
3354 \series default
3355  This copies the binary executables, the include files, the libraries and
3356  the documentation to the install directories.
3357  Proceed with section
3358 \begin_inset LatexCommand \ref{sec:Testing-the-SDCC}
3359
3360 \end_inset
3361
3362 .
3363 \layout Subsection
3364
3365 Building SDCC on OSX 2.x
3366 \layout Standard
3367
3368 Follow the instruction for Linux.
3369 \newline
3370
3371 \newline
3372 On OSX 2.x it was reported, that the default gcc (version 3.1 20020420 (prerelease
3373 )) fails to compile SDCC.
3374  Fortunately there's also gcc 2.9.x installed, which works fine.
3375  This compiler can be selected by running 'configure' with:
3376 \layout LyX-Code
3377
3378 ./configure CC=gcc2 CXX=g++2
3379 \layout Subsection
3380
3381 Cross compiling SDCC on Linux for Windows
3382 \layout Standard
3383
3384 With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
3385  See section 'Configure Options'.
3386 \layout Subsection
3387
3388 Building SDCC using Cygwin and Mingw32
3389 \layout Standard
3390
3391 For building and installing a Cygwin executable follow the instructions
3392  for Linux.
3393 \newline
3394
3395 \newline
3396 On Cygwin a
3397 \begin_inset Quotes sld
3398 \end_inset
3399
3400 native
3401 \begin_inset Quotes srd
3402 \end_inset
3403
3404  Win32-binary can be built, which will not need the Cygwin-DLL.
3405  For the necessary 'configure' options see section 'configure options' or
3406  the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'.
3407 \newline
3408
3409 \newline
3410 In order to install Cygwin on Windows download setup.exe from
3411 \begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
3412
3413 \end_inset
3414
3415 .
3416  Run it, set the
3417 \begin_inset Quotes sld
3418 \end_inset
3419
3420 default text file type
3421 \begin_inset Quotes srd
3422 \end_inset
3423
3424  to
3425 \begin_inset Quotes sld
3426 \end_inset
3427
3428 unix
3429 \begin_inset Quotes srd
3430 \end_inset
3431
3432  and download/install at least the following packages.
3433  Some packages are selected by default, others will be automatically selected
3434  because of dependencies with the manually selected packages.
3435  Never deselect these packages!
3436 \layout Itemize
3437
3438 flex
3439 \layout Itemize
3440
3441 bison
3442 \layout Itemize
3443
3444 gcc ; version 3.x is fine, no need to use the old 2.9x
3445 \layout Itemize
3446
3447 binutils ; selected with gcc
3448 \layout Itemize
3449
3450 make
3451 \layout Itemize
3452
3453 rxvt ; a nice console, which makes life much easier under windoze (see below)
3454 \layout Itemize
3455
3456 man ; not really needed for building SDCC, but you'll miss it sooner or
3457  later
3458 \layout Itemize
3459
3460 less ; not really needed for building SDCC, but you'll miss it sooner or
3461  later
3462 \layout Itemize
3463
3464 svn ; only if you use Subversion access
3465 \layout Standard
3466
3467 If you want to develop something you'll need:
3468 \layout Itemize
3469
3470 python ; for the regression tests
3471 \layout Itemize
3472
3473 gdb ; the gnu debugger, together with the nice GUI
3474 \begin_inset Quotes sld
3475 \end_inset
3476
3477 insight
3478 \begin_inset Quotes srd
3479 \end_inset
3480
3481
3482 \layout Itemize
3483
3484 openssh ; to access the CF or commit changes
3485 \layout Itemize
3486
3487 autoconf and autoconf-devel ; if you want to fight with 'configure', don't
3488  use autoconf-stable!
3489 \layout Standard
3490
3491 rxvt is a nice console with history.
3492  Replace in your cygwin.bat the line
3493 \layout LyX-Code
3494
3495 bash -
3496 \begin_inset ERT
3497 status Collapsed
3498
3499 \layout Standard
3500
3501 \backslash
3502 /
3503 \end_inset
3504
3505 -login -i
3506 \layout Standard
3507
3508 with (one line):
3509 \layout LyX-Code
3510
3511 rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
3512 \layout LyX-Code
3513
3514      -bg black -fg white -geometry 100x65 -e bash -
3515 \begin_inset ERT
3516 status Collapsed
3517
3518 \layout Standard
3519
3520 \backslash
3521 /
3522 \end_inset
3523
3524 -login
3525 \layout Standard
3526
3527 Text selected with the mouse is automatically copied to the clipboard, pasting
3528  works with shift-insert.
3529 \newline
3530
3531 \newline
3532 The other good tip is to make sure you have no //c/-style paths anywhere,
3533  use /cygdrive/c/ instead.
3534  Using // invokes a network lookup which is very slow.
3535  If you think
3536 \begin_inset Quotes sld
3537 \end_inset
3538
3539 cygdrive
3540 \begin_inset Quotes srd
3541 \end_inset
3542
3543  is too long, you can change it with e.g.
3544 \layout LyX-Code
3545
3546 mount -s -u -c /mnt
3547 \layout Standard
3548
3549 SDCC sources use the unix line ending LF.
3550  Life is much easier, if you store the source tree on a drive which is mounted
3551  in binary mode.
3552  And use an editor which can handle LF-only line endings.
3553  Make sure not to commit files with windows line endings.
3554  The tabulator spacing
3555 \begin_inset LatexCommand \index{tabulator spacing (8 columns)}
3556
3557 \end_inset
3558
3559  used in the project is 8.
3560  Although a tabulator spacing of 8 is a sensible choice for programmers
3561  (it's a power of 2 and allows to display 8/16 bit signed variables without
3562  loosing columns) the plan is to move towards using only spaces in the source.
3563 \layout Subsection
3564
3565 Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
3566 \layout Standard
3567
3568
3569 \series medium
3570 Download the source package
3571 \series default
3572  either from the SDCC Subversion repository or from the
3573 \begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
3574
3575 \end_inset
3576
3577
3578 \series medium
3579 , it will be named something like sdcc
3580 \series default
3581 .src
3582 \series medium
3583 .tgz.
3584
3585 \series default
3586  SDCC is distributed with all the projects, workspaces, and files you need
3587  to build it using Visual C++ 6.0/NET (except for SDCDB and ucSim).
3588  The workspace name is 'sdcc.dsw'.
3589  Please note that as it is now, all the executables are created in a folder
3590  called sdcc
3591 \backslash
3592 bin_vc.
3593  Once built you need to copy the executables from sdcc
3594 \backslash
3595 bin_vc to sdcc
3596 \backslash
3597 bin before running SDCC.
3598
3599 \newline
3600
3601 \newline
3602 WARNING: Visual studio is very picky with line terminations; it expects
3603  the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings.
3604  When using the Subversion repository it's easiest to configure the svn
3605  client to convert automatically for you.
3606  If however you are getting a message such as "This makefile was not generated
3607  by Developer Studio etc.
3608  etc.
3609 \begin_inset Quotes srd
3610 \end_inset
3611
3612  when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
3613  need to convert the Unix style line endings to DOS style line endings.
3614  To do so you can use the
3615 \begin_inset Quotes sld
3616 \end_inset
3617
3618 unix2dos
3619 \begin_inset Quotes srd
3620 \end_inset
3621
3622  utility freely available on the internet.
3623  Doug Hawkins reported in the sdcc-user list that this works:
3624 \newline
3625
3626 \newline
3627 C:
3628 \backslash
3629 Programming
3630 \backslash
3631 SDCC> unix2dos sdcc.dsw
3632 \newline
3633 C:
3634 \backslash
3635 Programming
3636 \backslash
3637 SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
3638 \newline
3639
3640 \newline
3641 In order to build SDCC with MSVC you need win32 executables of bison.exe,
3642  flex.exe, and gawk.exe.
3643  One good place to get them is
3644 \begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
3645
3646 \end_inset
3647
3648
3649 \newline
3650
3651 \newline
3652 Download the file UnxUtils
3653 \begin_inset LatexCommand \index{UnxUtils}
3654
3655 \end_inset
3656
3657 .zip.
3658  Now you have to install the utilities and setup MSVC so it can locate the
3659  required programs.
3660  Here there are two alternatives (choose one!):
3661 \layout Enumerate
3662
3663 The easy way:
3664 \newline
3665
3666 \newline
3667 a) Extract UnxUtils.zip to your C:
3668 \backslash
3669  hard disk PRESERVING the original paths, otherwise bison won't work.
3670  (If you are using WinZip make certain that 'Use folder names' is selected)
3671 \newline
3672
3673 \newline
3674 b) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3675  in 'Show directories for:' select 'Executable files', and in the directories
3676  window add a new path: 'C:
3677 \backslash
3678 user
3679 \backslash
3680 local
3681 \backslash
3682 wbin', click ok.
3683 \newline
3684
3685 \newline
3686 (As a side effect, you get a bunch of Unix utilities that could be useful,
3687  such as diff and patch.)
3688 \layout Enumerate
3689
3690 A more compact way:
3691 \newline
3692
3693 \newline
3694 This one avoids extracting a bunch of files you may not use, but requires
3695  some extra work:
3696 \newline
3697
3698 \newline
3699 a) Create a directory were to put the tools needed, or use a directory already
3700  present.
3701  Say for example 'C:
3702 \backslash
3703 util'.
3704 \newline
3705
3706 \newline
3707 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
3708  to such directory WITHOUT preserving the original paths.
3709  (If you are using WinZip make certain that 'Use folder names' is not selected)
3710 \newline
3711
3712 \newline
3713 c) Rename bison.exe to '_bison.exe'.
3714 \newline
3715
3716 \newline
3717 d) Create a batch file 'bison.bat' in 'C:
3718 \backslash
3719 util
3720 \backslash
3721 ' and add these lines:
3722 \newline
3723 \SpecialChar ~
3724 \SpecialChar ~
3725 set BISON_SIMPLE=C:
3726 \backslash
3727 util
3728 \backslash
3729 bison.simple
3730 \newline
3731 \SpecialChar ~
3732 \SpecialChar ~
3733 set BISON_HAIRY=C:
3734 \backslash
3735 util
3736 \backslash
3737 bison.hairy
3738 \newline
3739 \SpecialChar ~
3740 \SpecialChar ~
3741 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
3742 \newline
3743
3744 \newline
3745 Steps 'c' and 'd' are needed because bison requires by default that the
3746  files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory,
3747  '/usr/local/share/' I think.
3748  So it is necessary to tell bison where those files are located if they
3749  are not in such directory.
3750  That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
3751 \newline
3752
3753 \newline
3754 e) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3755  in 'Show directories for:' select 'Executable files', and in the directories
3756  window add a new path: 'c:
3757 \backslash
3758 util', click ok.
3759  Note that you can use any other path instead of 'c:
3760 \backslash
3761 util', even the path where the Visual C++ tools are, probably: 'C:
3762 \backslash
3763 Program Files
3764 \backslash
3765 Microsoft Visual Studio
3766 \backslash
3767 Common
3768 \backslash
3769 Tools'.
3770  So you don't have to execute step 'e' :)
3771 \layout Standard
3772
3773 That is it.
3774  Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
3775  the executables from sdcc
3776 \backslash
3777 bin_vc to sdcc
3778 \backslash
3779 bin, and you can compile using SDCC.
3780 \layout Subsection
3781
3782 Building SDCC Using Borland
3783 \layout Enumerate
3784
3785 From the sdcc directory, run the command "make -f Makefile.bcc".
3786  This should regenerate all the .exe files in the bin directory except for
3787  SDCDB and ucSim.
3788 \layout Enumerate
3789
3790 If you modify any source files and need to rebuild, be aware that the dependenci
3791 es may not be correctly calculated.
3792  The safest option is to delete all .obj files and run the build again.
3793  From a Cygwin BASH prompt, this can easily be done with the command (be
3794  sure you are in the sdcc directory):
3795 \newline
3796
3797 \newline
3798
3799 \family sans
3800 \series bold
3801 find .
3802
3803 \backslash
3804 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
3805 \backslash
3806 ) -print -exec rm {}
3807 \backslash
3808 ;
3809 \family default
3810 \series default
3811
3812 \newline
3813
3814 \newline
3815 or on Windows NT/2000/XP from the command prompt with the command:
3816 \newline
3817
3818 \family sans
3819 \series bold
3820
3821 \newline
3822 del /s *.obj *.lib *.rul
3823 \family default
3824 \series default
3825  from the sdcc directory.
3826 \layout Subsection
3827
3828 Windows Install Using a ZIP Package
3829 \layout Enumerate
3830
3831 Download the binary zip package from
3832 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3833
3834 \end_inset
3835
3836  and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
3837  This should unpack to a group of sub-directories.
3838  An example directory structure after unpacking the mingw32 package is:
3839  c:
3840 \backslash
3841 sdcc
3842 \backslash
3843 bin for the executables, c:
3844 \backslash
3845 sdcc
3846 \backslash
3847 include and c:
3848 \backslash
3849 sdcc
3850 \backslash
3851 lib for the include and libraries.
3852 \layout Enumerate
3853
3854 Adjust your environment variable PATH to include the location of the bin
3855  directory or start sdcc using the full path.
3856 \layout Subsection
3857
3858 Windows Install Using the Setup Program
3859 \begin_inset LatexCommand \label{sub:Windows-Install}
3860
3861 \end_inset
3862
3863
3864 \layout Standard
3865
3866 Download the setup program
3867 \emph on
3868 sdcc-x.y.z-setup.exe
3869 \emph default
3870  for an official release from
3871 \newline
3872
3873 \begin_inset LatexCommand \url{http://sf.net/project/showfiles.php?group_id=599}
3874
3875 \end_inset
3876
3877  or a setup program for one of the snapshots
3878 \emph on
3879 sdcc-yyyymmdd-xxxx-setup.exe
3880 \emph default
3881  from
3882 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3883
3884 \end_inset
3885
3886  and execute it.
3887  A windows typical installer will guide you through the installation process.
3888 \layout Subsection
3889
3890 VPATH
3891 \begin_inset LatexCommand \index{VPATH}
3892
3893 \end_inset
3894
3895  feature
3896 \layout Standard
3897
3898 SDCC supports the VPATH feature provided by configure and make.
3899  It allows to separate the source and build trees.
3900  Here's an example:
3901 \layout Standard
3902
3903
3904 \family typewriter
3905 cd ~\SpecialChar ~
3906 \SpecialChar ~
3907 \SpecialChar ~
3908 \SpecialChar ~
3909 \SpecialChar ~
3910 \SpecialChar ~
3911 \SpecialChar ~
3912 \SpecialChar ~
3913 \SpecialChar ~
3914 \SpecialChar ~
3915 \SpecialChar ~
3916 \SpecialChar ~
3917 \SpecialChar ~
3918 \SpecialChar ~
3919 \SpecialChar ~
3920 \SpecialChar ~
3921 \SpecialChar ~
3922 \SpecialChar ~
3923 \SpecialChar ~
3924 \SpecialChar ~
3925 \SpecialChar ~
3926 # cd $HOME
3927 \layout Standard
3928
3929
3930 \family typewriter
3931 tar -xzf sdcc.src.tar.gz\SpecialChar ~
3932 # extract source to directory sdcc
3933 \layout Standard
3934
3935
3936 \family typewriter
3937 mkdir sdcc.build\SpecialChar ~
3938 \SpecialChar ~
3939 \SpecialChar ~
3940 \SpecialChar ~
3941 \SpecialChar ~
3942 \SpecialChar ~
3943 \SpecialChar ~
3944 \SpecialChar ~
3945 \SpecialChar ~
3946 # put output in sdcc.build
3947 \layout Standard
3948
3949
3950 \family typewriter
3951 cd sdcc.build
3952 \layout Standard
3953
3954
3955 \family typewriter
3956 ../sdcc/configure\SpecialChar ~
3957 \SpecialChar ~
3958 \SpecialChar ~
3959 \SpecialChar ~
3960 \SpecialChar ~
3961 \SpecialChar ~
3962 \SpecialChar ~
3963 \SpecialChar ~
3964 # configure is doing all the magic!
3965 \layout Standard
3966
3967
3968 \family typewriter
3969 make
3970 \layout Standard
3971 \noindent
3972 That's it!
3973 \series bold
3974 configure
3975 \series default
3976  will create the directory tree will all the necessary Makefiles in ~/sdcc.build.
3977  It automagically computes the variables srcdir, top_srcdir and top_buildir
3978  for each directory.
3979  After running
3980 \series bold
3981 make
3982 \series default
3983  the generated files will be in ~/sdcc.build, while the source files stay
3984  in ~/sdcc.
3985 \newline
3986 This is not only usefull for building different binaries, e.g.
3987  when cross compiling.
3988  It also gives you a much better overview in the source tree when all the
3989  generated files are not scattered between the source files.
3990  And the best thing is: if you want to change a file you can leave the original
3991  file untouched in the source directory.
3992  Simply copy it to the build directory, edit it, enter `make clean`, `rm
3993  Makefile.dep` and `make`.
3994
3995 \series bold
3996 make
3997 \series default
3998  will do the rest for you!
3999 \layout Section
4000
4001 Building the Documentation
4002 \layout Standard
4003
4004 Add -
4005 \begin_inset ERT
4006 status Collapsed
4007
4008 \layout Standard
4009
4010 \backslash
4011 /
4012 \end_inset
4013
4014 -enable-doc to the configure arguments to build the documentation together
4015  with all the other stuff.
4016  You will need several tools (LyX, LaTeX, LaTeX2HTML, pdflatex, dvipdf,
4017  dvips and makeindex) to get the job done.
4018  Another possibility is to change to the doc directory and to type
4019 \family sans
4020 \series bold
4021
4022 \begin_inset Quotes srd
4023 \end_inset
4024
4025 make
4026 \begin_inset Quotes srd
4027 \end_inset
4028
4029
4030 \family default
4031 \series default
4032  there.
4033  You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
4034 x).
4035  Using LyX
4036 \begin_inset LatexCommand \url{http://www.lyx.org}
4037
4038 \end_inset
4039
4040  as editor is straightforward.
4041  Prebuilt documentation in html and pdf format is available from
4042 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
4043
4044 \end_inset
4045
4046 .
4047 \layout Section
4048
4049 Reading the Documentation
4050 \layout Standard
4051
4052 Currently reading the document in pdf format is recommended, as for unknown
4053  reason the hyperlinks are working there whereas in the html version they
4054  are not
4055 \begin_inset Foot
4056 collapsed false
4057
4058 \layout Standard
4059
4060 If you should know why please drop us a note
4061 \end_inset
4062
4063 .
4064
4065 \newline
4066 You'll find the pdf version
4067 \begin_inset LatexCommand \index{PDF version of this document}
4068
4069 \end_inset
4070
4071  at
4072 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.pdf}
4073
4074 \end_inset
4075
4076 .
4077
4078 \newline
4079 A html version
4080 \begin_inset LatexCommand \index{HTML version of this document}
4081
4082 \end_inset
4083
4084  should be online at
4085 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.html/index.html}
4086
4087 \end_inset
4088
4089 .
4090 \newline
4091 This documentation is in some aspects different from a commercial documentation:
4092
4093 \layout Itemize
4094
4095 It tries to document SDCC for several processor architectures in one document
4096  (commercially these probably would be separate documents/products).
4097  This document
4098 \begin_inset LatexCommand \index{Status of documentation}
4099
4100 \end_inset
4101
4102  currently matches SDCC for mcs51 and DS390 best and does give too few informati
4103 on about f.e.
4104  Z80, PIC14, PIC16 and HC08.
4105 \layout Itemize
4106
4107 There are many references pointing away from this documentation.
4108  Don't let this distract you.
4109  If there f.e.
4110  was a reference like
4111 \begin_inset LatexCommand \url{http://www.opencores.org}
4112
4113 \end_inset
4114
4115  together with a statement
4116 \begin_inset Quotes sld
4117 \end_inset
4118
4119 some processors which are targetted by SDCC can be implemented in a
4120 \emph on
4121 f
4122 \emph default
4123 ield
4124 \emph on
4125 p
4126 \emph default
4127 rogrammable
4128 \emph on
4129 g
4130 \emph default
4131 ate
4132 \emph on
4133 a
4134 \emph default
4135 rray
4136 \begin_inset LatexCommand \index{FPGA (field programmable gate array)}
4137
4138 \end_inset
4139
4140
4141 \begin_inset Quotes srd
4142 \end_inset
4143
4144  or
4145 \begin_inset LatexCommand \url{http://sf.net/projects/fpgac}
4146
4147 \end_inset
4148
4149
4150 \begin_inset LatexCommand \index{FpgaC ((subset of) C to FPGA compiler)}
4151
4152 \end_inset
4153
4154
4155 \begin_inset Quotes sld
4156 \end_inset
4157
4158 have you ever heard of an open source compiler that compiles a subset of
4159  C for an FPGA?
4160 \begin_inset Quotes srd
4161 \end_inset
4162
4163  we expect you to have a quick look there and come back.
4164  If you read this you are on the right track.
4165 \layout Itemize
4166
4167 Some sections attribute more space to problems, restrictions and warnings
4168  than to the solution.
4169 \layout Itemize
4170
4171 The installation section and the section about the debugger is intimidating.
4172 \layout Itemize
4173
4174 There are still lots of typos and there are more different writing styles
4175  than pictures.
4176 \layout Section
4177
4178 Testing the SDCC Compiler
4179 \begin_inset LatexCommand \label{sec:Testing-the-SDCC}
4180
4181 \end_inset
4182
4183
4184 \layout Standard
4185
4186 The first thing you should do after installing your SDCC compiler is to
4187  see if it runs.
4188  Type
4189 \family sans
4190 \series bold
4191 "sdcc -
4192 \begin_inset ERT
4193 status Collapsed
4194
4195 \layout Standard
4196
4197 \backslash
4198 /
4199 \end_inset
4200
4201 -version"
4202 \begin_inset LatexCommand \index{version}
4203
4204 \end_inset
4205
4206
4207 \family default
4208 \series default
4209  at the prompt, and the program should run and output its version like:
4210
4211 \newline
4212
4213 \family typewriter
4214 SDCC : mcs51/z80/avr/ds390/pic16/pic14/ds400/hc08 2.5.6 #4169 (May 8 2006)
4215  (UNIX)
4216 \layout Standard
4217
4218 If it doesn't run, or gives a message about not finding sdcc program, then
4219  you need to check over your installation.
4220  Make sure that the sdcc bin directory is in your executable search path
4221  defined by the PATH environment setting (
4222 \series medium
4223 see
4224 \series default
4225 section
4226 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
4227
4228 \end_inset
4229
4230 \SpecialChar ~
4231
4232 \series medium
4233 Install trouble-shooting for suggestions
4234 \series default
4235 ).
4236  Make sure that the sdcc program is in the bin folder, if not perhaps something
4237  did not install correctly.
4238 \newline
4239
4240 \newline
4241
4242 \series medium
4243 SDCC
4244 \series default
4245 is commonly installed as described in section
4246 \begin_inset Quotes sld
4247 \end_inset
4248
4249 Install and search paths
4250 \begin_inset Quotes srd
4251 \end_inset
4252
4253 .
4254 \newline
4255
4256 \newline
4257
4258 \series medium
4259 Make sure the compiler works on a very simple example.
4260  Type in the following test.c program using your favorite
4261 \series default
4262 ASCII
4263 \series medium
4264 editor:
4265 \layout Verse
4266
4267
4268 \family typewriter
4269 char test;
4270 \newline
4271
4272 \newline
4273 void main(void) {
4274 \newline
4275 \SpecialChar ~
4276 \SpecialChar ~
4277 \SpecialChar ~
4278 \SpecialChar ~
4279 test=0;
4280 \newline
4281 }
4282 \layout Standard
4283
4284
4285 \series medium
4286 Compile this using the following command:
4287 \family sans
4288 \series bold
4289 "sdcc -c test.c".
4290
4291 \family default
4292 \series default
4293
4294 \series medium
4295 If all goes well, the compiler will generate a test.asm and test.rel file.
4296  Congratulations, you've just compiled your first program with SDCC.
4297  We used the -c option to tell SDCC not to link the generated code, just
4298  to keep things simple for this step.
4299 \series default
4300
4301 \newline
4302
4303 \newline
4304
4305 \series medium
4306 The next step is to try it with the linker.
4307  Type in
4308 \family sans
4309 \series bold
4310 "sdcc test.c
4311 \family default
4312 \series default
4313 "
4314 \series medium
4315 .
4316  If all goes well the compiler will link with the libraries and produce
4317  a test.ihx output file.
4318  If this step fails
4319 \series default
4320
4321 \series medium
4322 (no test.ihx, and the linker generates warnings), then the problem is most
4323  likely that
4324 \series default
4325 SDCC
4326 \series medium
4327  cannot find the
4328 \series default
4329 /
4330 \series medium
4331 usr/local/share/sdcc/lib directory
4332 \series default
4333
4334 \series medium
4335 (see
4336 \series default
4337 section
4338 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
4339
4340 \end_inset
4341
4342 \SpecialChar ~
4343
4344 \series medium
4345 Install trouble-shooting for suggestions).
4346 \series default
4347
4348 \newline
4349
4350 \newline
4351
4352 \series medium
4353 The final test is to ensure
4354 \series default
4355 SDCC
4356 \series medium
4357  can use the
4358 \series default
4359 standard
4360 \series medium
4361  header files and libraries.
4362  Edit test.c and change it to the following:
4363 \layout Verse
4364
4365
4366 \family typewriter
4367 #include <string.h>
4368 \newline
4369
4370 \newline
4371 char str1[10];
4372 \newline
4373
4374 \newline
4375 void main(void) {
4376 \newline
4377 \SpecialChar ~
4378 \SpecialChar ~
4379 strcpy(str1, "testing");
4380 \newline
4381 }
4382 \layout Standard
4383
4384
4385 \series medium
4386 Compile this by typing
4387 \family sans
4388 \series bold
4389 "sdcc test.c"
4390 \family default
4391 \series medium
4392 .
4393  This should generate a test.ihx output file, and it should give no warnings
4394  such as not finding the string.h file.
4395  If it cannot find the string.h file, then the problem is that
4396 \series default
4397 SDCC
4398 \series medium
4399  cannot find the /usr/local/share/sdcc/include directory
4400 \series default
4401
4402 \series medium
4403 (see the
4404 \series default
4405 section
4406 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
4407
4408 \end_inset
4409
4410 \SpecialChar ~
4411
4412 \series medium
4413 Install trouble-shooting section for suggestions).
4414
4415 \series default
4416  Use option
4417 \series bold
4418 -
4419 \begin_inset ERT
4420 status Collapsed
4421
4422 \layout Standard
4423
4424 \backslash
4425 /
4426 \end_inset
4427
4428 -print-search-dirs
4429 \series default
4430
4431 \begin_inset LatexCommand \index{-\/-print-search-dirs}
4432
4433 \end_inset
4434
4435  to find exactly where SDCC is looking for the include and lib files.
4436 \layout Section
4437
4438 Install Trouble-shooting
4439 \begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
4440
4441 \end_inset
4442
4443
4444 \begin_inset LatexCommand \index{Install trouble-shooting}
4445
4446 \end_inset
4447
4448
4449 \layout Subsection
4450
4451 If SDCC does not build correctly
4452 \layout Standard
4453
4454 A thing to try is starting from scratch by unpacking the .tgz source package
4455  again in an empty directory.
4456  Configure it like:
4457 \newline
4458
4459 \newline
4460
4461 \family sans
4462 \series bold
4463 ./configure 2>&1 | tee configure.log
4464 \family default
4465 \series default
4466
4467 \newline
4468
4469 \newline
4470 and build it like:
4471 \newline
4472
4473 \newline
4474
4475 \family sans
4476 \series bold
4477 make 2>&1 | tee make.log
4478 \family default
4479 \series default
4480
4481 \newline
4482
4483 \newline
4484 If anything goes wrong, you can review the log files to locate the problem.
4485  Or a relevant part of this can be attached to an email that could be helpful
4486  when requesting help from the mailing list.
4487 \layout Subsection
4488
4489 What the
4490 \begin_inset Quotes sld
4491 \end_inset
4492
4493 ./configure
4494 \begin_inset Quotes srd
4495 \end_inset
4496
4497  does
4498 \layout Standard
4499
4500 The
4501 \begin_inset Quotes sld
4502 \end_inset
4503
4504 ./configure
4505 \begin_inset Quotes srd
4506 \end_inset
4507
4508  command is a script that analyzes your system and performs some configuration
4509  to ensure the source package compiles on your system.
4510  It will take a few minutes to run, and will compile a few tests to determine
4511  what compiler features are installed.
4512 \layout Subsection
4513
4514 What the
4515 \begin_inset Quotes sld
4516 \end_inset
4517
4518 make
4519 \begin_inset Quotes srd
4520 \end_inset
4521
4522  does
4523 \layout Standard
4524
4525 This runs the GNU make tool, which automatically compiles all the source
4526  packages into the final installed binary executables.
4527 \layout Subsection
4528
4529 What the
4530 \begin_inset Quotes sld
4531 \end_inset
4532
4533 make install
4534 \begin_inset Quotes erd
4535 \end_inset
4536
4537  command does.
4538 \layout Standard
4539
4540 This will install the compiler, other executables libraries and include
4541  files into the appropriate directories.
4542  See sections
4543 \begin_inset LatexCommand \ref{sub:Install-paths}
4544
4545 \end_inset
4546
4547 ,\SpecialChar ~
4548
4549 \begin_inset LatexCommand \ref{sub:Search-Paths}
4550
4551 \end_inset
4552
4553 \SpecialChar ~
4554 about install and search paths.
4555 \newline
4556 On most systems you will need super-user privileges to do this.
4557 \layout Section
4558
4559 Components of SDCC
4560 \layout Standard
4561
4562 SDCC is not just a compiler, but a collection of tools by various developers.
4563  These include linkers, assemblers, simulators and other components.
4564  Here is a summary of some of the components.
4565  Note that the included simulator and assembler have separate documentation
4566  which you can find in the source package in their respective directories.
4567  As SDCC grows to include support for other processors, other packages from
4568  various developers are included and may have their own sets of documentation.
4569 \newline
4570
4571 \newline
4572 You might want to look at the files which are installed in <installdir>.
4573  At the time of this writing, we find the following programs for gcc-builds:
4574 \newline
4575
4576 \newline
4577 In <installdir>/bin:
4578 \layout Itemize
4579
4580 sdcc - The compiler.
4581 \layout Itemize
4582
4583 sdcpp - The C preprocessor.
4584 \layout Itemize
4585
4586 asx8051 - The assembler for 8051 type processors.
4587 \layout Itemize
4588
4589 as-z80
4590 \series bold
4591 ,
4592 \series default
4593 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
4594 \layout Itemize
4595
4596 aslink -The linker for 8051 type processors.
4597 \layout Itemize
4598
4599 link-z80
4600 \series bold
4601 ,
4602 \series default
4603 link-gbz80 - The Z80 and GameBoy Z80 linkers.
4604 \layout Itemize
4605
4606 s51 - The ucSim 8051 simulator.
4607 \layout Itemize
4608
4609 sdcdb - The source debugger.
4610 \layout Itemize
4611
4612 packihx - A tool to pack (compress) Intel hex files.
4613 \layout Standard
4614
4615 In <installdir>/share/sdcc/include
4616 \layout Itemize
4617
4618 the include files
4619 \layout Standard
4620
4621 In <installdir>/share/sdcc/lib
4622 \layout Itemize
4623
4624 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
4625  relocatables.
4626 \layout Standard
4627
4628 In <installdir>/share/sdcc/doc
4629 \layout Itemize
4630
4631 the documentation
4632 \layout Standard
4633
4634 As development for other processors proceeds, this list will expand to include
4635  executables to support processors like AVR, PIC, etc.
4636 \layout Subsection
4637
4638 sdcc - The Compiler
4639 \layout Standard
4640
4641 This is the actual compiler, it in turn uses the c-preprocessor and invokes
4642  the assembler and linkage editor.
4643 \layout Subsection
4644
4645 sdcpp - The C-Preprocessor
4646 \layout Standard
4647
4648 The preprocessor
4649 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
4650
4651 \end_inset
4652
4653  is a modified version of the GNU preprocessor.
4654  The C preprocessor is used to pull in #include sources, process #ifdef
4655  statements, #defines and so on.
4656 \layout Subsection
4657
4658 as
4659 \emph on
4660 xxxx
4661 \emph default
4662 , aslink, link-
4663 \emph on
4664 xxx
4665 \emph default
4666  - The Assemblers and Linkage Editors
4667 \layout Standard
4668
4669 This is retargettable assembler & linkage editor, it was developed by Alan
4670  Baldwin.
4671  John Hartman created the version for 8051, and I (Sandeep) have made some
4672  enhancements and bug fixes for it to work properly with SDCC.
4673 \layout Subsection
4674
4675 s51 - The Simulator
4676 \layout Standard
4677
4678 S51
4679 \begin_inset LatexCommand \index{s51}
4680
4681 \end_inset
4682
4683  is a freeware, opensource simulator developed by Daniel Drotos.
4684  The simulator is built as part of the build process.
4685  For more information visit Daniel's web site at:
4686 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
4687
4688 \end_inset
4689
4690 .
4691  It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
4692  XA51 family.
4693 \layout Subsection
4694
4695 sdcdb - Source Level Debugger
4696 \layout Standard
4697
4698 SDCDB
4699 \begin_inset LatexCommand \index{SDCDB (debugger)}
4700
4701 \end_inset
4702
4703  is the companion source level debugger.
4704  More about SDCDB in section
4705 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
4706
4707 \end_inset
4708
4709 .
4710  The current version of the debugger uses Daniel's Simulator S51
4711 \begin_inset LatexCommand \index{s51}
4712
4713 \end_inset
4714
4715 , but can be easily changed to use other simulators.
4716 \layout Chapter
4717
4718 Using SDCC
4719 \layout Section
4720
4721 Compiling
4722 \layout Subsection
4723
4724 Single Source File Projects
4725 \layout Standard
4726
4727 For single source file 8051 projects the process is very simple.
4728  Compile your programs with the following command
4729 \family sans
4730 \series bold
4731 "sdcc sourcefile.c".
4732
4733 \family default
4734 \series default
4735  This will compile, assemble and link your source file.
4736  Output files are as follows:
4737 \layout Itemize
4738
4739 sourcefile.asm
4740 \begin_inset LatexCommand \index{<file>.asm}
4741
4742 \end_inset
4743
4744  - Assembler source
4745 \begin_inset LatexCommand \index{Assembler source}
4746
4747 \end_inset
4748
4749  file created by the compiler
4750 \layout Itemize
4751
4752 sourcefile.lst
4753 \begin_inset LatexCommand \index{<file>.lst}
4754
4755 \end_inset
4756
4757  - Assembler listing
4758 \begin_inset LatexCommand \index{Assembler listing}
4759
4760 \end_inset
4761
4762  file created by the Assembler
4763 \layout Itemize
4764
4765 sourcefile.rst
4766 \begin_inset LatexCommand \index{<file>.rst}
4767
4768 \end_inset
4769
4770  - Assembler listing
4771 \begin_inset LatexCommand \index{Assembler listing}
4772
4773 \end_inset
4774
4775  file updated with linkedit information, created by linkage editor
4776 \layout Itemize
4777
4778 sourcefile.sym
4779 \begin_inset LatexCommand \index{<file>.sym}
4780
4781 \end_inset
4782
4783  - symbol listing
4784 \begin_inset LatexCommand \index{Symbol listing}
4785
4786 \end_inset
4787
4788  for the sourcefile, created by the assembler
4789 \layout Itemize
4790
4791 sourcefile.rel
4792 \begin_inset LatexCommand \index{<file>.rel}
4793
4794 \end_inset
4795
4796  or sourcefile.o
4797 \begin_inset LatexCommand \index{<file>.o}
4798
4799 \end_inset
4800
4801  - Object file
4802 \begin_inset LatexCommand \index{Object file}
4803
4804 \end_inset
4805
4806  created by the assembler, input to Linkage editor
4807 \layout Itemize
4808
4809 sourcefile.map
4810 \begin_inset LatexCommand \index{<file>.map}
4811
4812 \end_inset
4813
4814  - The memory map
4815 \begin_inset LatexCommand \index{Memory map}
4816
4817 \end_inset
4818
4819  for the load module, created by the Linker
4820 \layout Itemize
4821
4822 sourcefile.mem
4823 \begin_inset LatexCommand \index{<file>.mem}
4824
4825 \end_inset
4826
4827  - A file with a summary of the memory usage
4828 \layout Itemize
4829
4830 sourcefile.ihx
4831 \begin_inset LatexCommand \index{<file>.ihx}
4832
4833 \end_inset
4834
4835  - The load module in Intel hex format
4836 \begin_inset LatexCommand \index{Intel hex format}
4837
4838 \end_inset
4839
4840  (you can select the Motorola S19 format
4841 \begin_inset LatexCommand \index{Motorola S19 format}
4842
4843 \end_inset
4844
4845  with -
4846 \begin_inset ERT
4847 status Collapsed
4848
4849 \layout Standard
4850
4851 \backslash
4852 /
4853 \end_inset
4854
4855 -out-fmt-s19
4856 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
4857
4858 \end_inset
4859
4860 .
4861  If you need another format you might want to use
4862 \family sans
4863 \shape italic
4864 objdump
4865 \family default
4866 \shape default
4867
4868 \begin_inset LatexCommand \index{objdump (tool)}
4869
4870 \end_inset
4871
4872  or
4873 \family sans
4874 \shape italic
4875  srecord
4876 \family default
4877 \shape default
4878
4879 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4880
4881 \end_inset
4882
4883 ).
4884  Both formats are documented in the documentation of srecord
4885 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4886
4887 \end_inset
4888
4889
4890 \layout Itemize
4891
4892 sourcefile.adb
4893 \begin_inset LatexCommand \index{<file>.adb}
4894
4895 \end_inset
4896
4897  - An intermediate file containing debug information needed to create the
4898  .cdb file (with -
4899 \begin_inset ERT
4900 status Open
4901
4902 \layout Standard
4903
4904 \backslash
4905 /
4906 \end_inset
4907
4908 -debug
4909 \begin_inset LatexCommand \index{-\/-debug}
4910
4911 \end_inset
4912
4913 )
4914 \layout Itemize
4915
4916 sourcefile.cdb
4917 \begin_inset LatexCommand \index{<file>.cdb}
4918
4919 \end_inset
4920
4921  - An optional file (with -
4922 \begin_inset ERT
4923 status Collapsed
4924
4925 \layout Standard
4926
4927 \backslash
4928 /
4929 \end_inset
4930
4931 -debug) containing debug information.
4932  The format is documented in cdbfileformat.pdf
4933 \layout Itemize
4934
4935 sourcefile.
4936  - (no extension)
4937 \begin_inset LatexCommand \index{<file> (no extension)}
4938
4939 \end_inset
4940
4941  An optional AOMF or AOMF51
4942 \begin_inset LatexCommand \index{AOMF, AOMF51}
4943
4944 \end_inset
4945
4946
4947 \begin_inset LatexCommand \label{OMF file}
4948
4949 \end_inset
4950
4951 file containing debug information (generated with option -
4952 \begin_inset ERT
4953 status Collapsed
4954
4955 \layout Standard
4956
4957 \backslash
4958 /
4959 \end_inset
4960
4961 -debug).
4962  The (Intel)
4963 \emph on
4964  a
4965 \emph default
4966 bsolute
4967 \emph on
4968 o
4969 \emph default
4970 bject
4971 \emph on
4972 m
4973 \emph default
4974 odule
4975 \emph on
4976 f
4977 \emph default
4978 ormat is commonly used by third party tools (debuggers
4979 \begin_inset LatexCommand \index{Debugger}
4980
4981 \end_inset
4982
4983 , simulators, emulators)
4984 \layout Itemize
4985
4986 sourcefile.dump*
4987 \begin_inset LatexCommand \index{<file>.dump*}
4988
4989 \end_inset
4990
4991  - Dump file to debug the compiler it self (generated with option -
4992 \begin_inset ERT
4993 status Collapsed
4994
4995 \layout Standard
4996
4997 \backslash
4998 /
4999 \end_inset
5000
5001 -dumpall) (see section
5002 \begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
5003
5004 \end_inset
5005
5006 \SpecialChar ~
5007  and section
5008 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
5009
5010 \end_inset
5011
5012 \SpecialChar ~
5013
5014 \begin_inset Quotes sld
5015 \end_inset
5016
5017 Anatomy of the compiler
5018 \begin_inset Quotes srd
5019 \end_inset
5020
5021 ).
5022 \layout Subsection
5023
5024 Projects with Multiple Source Files
5025 \layout Standard
5026
5027 SDCC can compile only ONE file at a time.
5028  Let us for example assume that you have a project containing the following
5029  files:
5030 \newline
5031
5032 \newline
5033 foo1.c (contains some functions)
5034 \newline
5035 foo2.c (contains some more functions)
5036 \newline
5037 foomain.c (contains more functions and the function main)
5038 \newline
5039
5040 \size footnotesize
5041
5042 \newline
5043
5044 \size default
5045 The first two files will need to be compiled separately with the commands:
5046 \size footnotesize
5047
5048 \size default
5049
5050 \newline
5051
5052 \newline
5053
5054 \family sans
5055 \series bold
5056 sdcc\SpecialChar ~
5057 -c\SpecialChar ~
5058 foo1.c
5059 \family default
5060 \series default
5061 \size footnotesize
5062
5063 \newline
5064
5065 \family sans
5066 \series bold
5067 \size default
5068 sdcc\SpecialChar ~
5069 -c\SpecialChar ~
5070 foo2.c
5071 \family default
5072 \series default
5073
5074 \newline
5075
5076 \newline
5077 Then compile the source file containing the
5078 \emph on
5079 main()
5080 \emph default
5081  function and link
5082 \begin_inset LatexCommand \index{Linker}
5083
5084 \end_inset
5085
5086  the files together with the following command:
5087 \newline
5088
5089 \newline
5090
5091 \family sans
5092 \series bold
5093 sdcc\SpecialChar ~
5094 foomain.c\SpecialChar ~
5095 foo1.rel\SpecialChar ~
5096 foo2.rel
5097 \family default
5098 \series default
5099
5100 \begin_inset LatexCommand \index{<file>.rel}
5101
5102 \end_inset
5103
5104
5105 \newline
5106
5107 \newline
5108 Alternatively,
5109 \emph on
5110 foomain.c
5111 \emph default
5112 can be separately compiled as well:
5113 \family sans
5114 \series bold
5115
5116 \newline
5117
5118 \newline
5119 sdcc\SpecialChar ~
5120 -c\SpecialChar ~
5121 foomain.c
5122 \newline
5123 sdcc foomain.rel foo1.rel foo2.rel
5124 \newline
5125
5126 \newline
5127
5128 \family default
5129 \series default
5130 The file containing the
5131 \emph on
5132 main()
5133 \emph default
5134  function
5135 \emph on
5136
5137 \emph default
5138 \noun on
5139 must
5140 \noun default
5141  be the
5142 \noun on
5143 first
5144 \noun default
5145  file specified in the command line, since the linkage editor processes
5146  file in the order they are presented to it.
5147  The linker is invoked from SDCC using a script file with extension .lnk
5148 \begin_inset LatexCommand \index{<file>.lnk}
5149
5150 \end_inset
5151
5152 .
5153  You can view this file to troubleshoot linking problems such as those arising
5154  from missing libraries.
5155 \layout Subsection
5156
5157 Projects with Additional Libraries
5158 \begin_inset LatexCommand \index{Libraries}
5159
5160 \end_inset
5161
5162
5163 \layout Standard
5164
5165 Some reusable routines may be compiled into a library, see the documentation
5166  for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
5167  for how to create a
5168 \emph on
5169 .lib
5170 \begin_inset LatexCommand \index{<file>.lib}
5171
5172 \end_inset
5173
5174
5175 \emph default
5176  library file.
5177  Libraries created in this manner can be included in the command line.
5178  Make sure you include the -L <library-path> option to tell the linker where
5179  to look for these files if they are not in the current directory.
5180  Here is an example, assuming you have the source file
5181 \emph on
5182 foomain.c
5183 \emph default
5184  and a library
5185 \emph on
5186  foolib.lib
5187 \emph default
5188  in the directory
5189 \emph on
5190 mylib
5191 \emph default
5192  (if that is not the same as your current project):
5193 \newline
5194
5195 \newline
5196
5197 \family sans
5198 \series bold
5199 sdcc foomain.c foolib.lib -L mylib
5200 \newline
5201
5202 \newline
5203
5204 \family default
5205 \series default
5206 Note here that
5207 \emph on
5208  mylib
5209 \emph default
5210  must be an absolute path name.
5211 \newline
5212
5213 \newline
5214 The most efficient way to use libraries is to keep separate modules in separate
5215  source files.
5216  The lib file now should name all the modules.rel
5217 \begin_inset LatexCommand \index{<file>.rel}
5218
5219 \end_inset
5220
5221  files.
5222  For an example see the standard library file
5223 \emph on
5224 libsdcc.lib
5225 \emph default
5226  in the directory <installdir>/share/lib/small.
5227 \layout Subsection
5228
5229 Using sdcclib to Create and Manage Libraries
5230 \begin_inset LatexCommand \index{sdcclib}
5231
5232 \end_inset
5233
5234
5235 \layout Standard
5236
5237 Alternatively, instead of having a .rel file for each entry on the library
5238  file as described in the preceding section, sdcclib can be used to embed
5239  all the modules belonging to such library in the library file itself.
5240  This results in a larger library file, but it greatly reduces the number
5241  of disk files accessed by the linker.
5242   Additionally, the packed library file contains an index of all include
5243  modules and symbols that significantly speeds up the linking process.
5244  To display a list of options supported by sdcclib type:
5245 \newline
5246
5247 \layout Standard
5248
5249
5250 \family sans
5251 \series bold
5252 sdcclib -?
5253 \begin_inset LatexCommand \index{sdcclib}
5254
5255 \end_inset
5256
5257
5258 \newline
5259
5260 \newline
5261
5262 \family default
5263 \series default
5264 To create a new library file, start by compiling all the required modules.
5265  For example:
5266 \newline
5267
5268 \layout Standard
5269
5270
5271 \family sans
5272 \series bold
5273 sdcc -c _divsint.c
5274 \layout Standard
5275
5276
5277 \family sans
5278 \series bold
5279 sdcc -c _divuint.c
5280 \layout Standard
5281
5282
5283 \family sans
5284 \series bold
5285 sdcc -c _modsint.c
5286 \layout Standard
5287
5288
5289 \family sans
5290 \series bold
5291 sdcc -c _moduint.c
5292 \layout Standard
5293
5294
5295 \family sans
5296 \series bold
5297 sdcc -c _mulint.c
5298 \newline
5299
5300 \layout Standard
5301
5302 This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
5303  and _mulint.rel.
5304  The next step is to add the .rel files to the library file:
5305 \newline
5306
5307 \layout Standard
5308
5309
5310 \family sans
5311 \series bold
5312 sdcclib libint.lib _divsint.rel
5313 \family default
5314
5315 \begin_inset LatexCommand \index{sdcclib}
5316
5317 \end_inset
5318
5319
5320 \layout Standard
5321
5322
5323 \family sans
5324 \series bold
5325 sdcclib libint.lib _divuint.rel
5326 \layout Standard
5327
5328
5329 \family sans
5330 \series bold
5331 sdcclib libint.lib _modsint.rel
5332 \layout Standard
5333
5334
5335 \family sans
5336 \series bold
5337 sdcclib libint.lib _moduint.rel
5338 \layout Standard
5339
5340
5341 \family sans
5342 \series bold
5343 sdcclib libint.lib _mulint.rel
5344 \series default
5345
5346 \newline
5347
5348 \layout Standard
5349
5350 If the file already exists in the library, it will be replaced.
5351  To see what modules and symbols are included in the library, options -s
5352  and -m are available.
5353  For example:
5354 \newline
5355
5356 \newline
5357
5358 \family sans
5359 \series bold
5360 sdcclib -s libint.lib
5361 \family default
5362
5363 \begin_inset LatexCommand \index{sdcclib}
5364
5365 \end_inset
5366
5367
5368 \newline
5369
5370 \family typewriter
5371 \series default
5372 _divsint.rel:
5373 \layout Standard
5374
5375
5376 \family typewriter
5377 __divsint_a_1_1
5378 \layout Standard
5379
5380
5381 \family typewriter
5382 __divsint_PARM_2
5383 \layout Standard
5384
5385
5386 \family typewriter
5387 __divsint
5388 \newline
5389 _divuint.rel:
5390 \layout Standard
5391
5392
5393 \family typewriter
5394 __divuint_a_1_1
5395 \layout Standard
5396
5397
5398 \family typewriter
5399 __divuint_PARM_2
5400 \layout Standard
5401
5402
5403 \family typewriter
5404 __divuint_reste_1_1
5405 \layout Standard
5406
5407
5408 \family typewriter
5409 __divuint_count_1_1
5410 \layout Standard
5411
5412
5413 \family typewriter
5414 __divuint
5415 \newline
5416 _modsint.rel:
5417 \layout Standard
5418
5419
5420 \family typewriter
5421 __modsint_a_1_1
5422 \layout Standard
5423
5424
5425 \family typewriter
5426 __modsint_PARM_2
5427 \layout Standard
5428
5429
5430 \family typewriter
5431 __modsint
5432 \newline
5433 _moduint.rel:
5434 \layout Standard
5435
5436
5437 \family typewriter
5438 __moduint_a_1_1
5439 \layout Standard
5440
5441
5442 \family typewriter
5443 __moduint_PARM_2
5444 \layout Standard
5445
5446
5447 \family typewriter
5448 __moduint_count_1_1
5449 \layout Standard
5450
5451
5452 \family typewriter
5453 __moduint
5454 \newline
5455 _mulint.rel:
5456 \layout Standard
5457
5458
5459 \family typewriter
5460 __mulint_PARM_2
5461 \layout Standard
5462
5463
5464 \family typewriter
5465 __mulint
5466 \family default
5467 \series bold
5468
5469 \newline
5470
5471 \layout Standard
5472
5473 If the source files are compiled using -
5474 \begin_inset ERT
5475 status Open
5476
5477 \layout Standard
5478
5479 \backslash
5480 /
5481 \end_inset
5482
5483 -debug
5484 \begin_inset LatexCommand \index{-\/-debug}
5485
5486 \end_inset
5487
5488 , the corresponding debug information file .adb will be include in the library
5489  file as well.
5490  The library files created with sdcclib are plain text files, so they can
5491  be viewed with a text editor.
5492  It is not recomended to modify a library file created with sdcclib using
5493  a text editor, as there are file indexes numbers located accross the file
5494  used by the linker to quickly locate the required module to link.
5495  Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
5496  it can be safely deleted, since all the information required for linking
5497  is embedded in the library file itself.
5498  Library files created using sdcclib are used as described in the preceding
5499  sections.
5500 \layout Section
5501
5502 Command Line Options
5503 \begin_inset LatexCommand \index{Command Line Options}
5504
5505 \end_inset
5506
5507
5508 \layout Subsection
5509
5510 Processor Selection Options
5511 \begin_inset LatexCommand \index{Options processor selection}
5512
5513 \end_inset
5514
5515
5516 \begin_inset LatexCommand \index{Processor selection options}
5517
5518 \end_inset
5519
5520
5521 \layout List
5522 \labelwidthstring 00.00.0000
5523
5524
5525 \series bold
5526 -mmcs51
5527 \begin_inset LatexCommand \index{-mmcs51}
5528
5529 \end_inset
5530
5531
5532 \series default
5533  Generate code for the Intel MCS51
5534 \begin_inset LatexCommand \index{MCS51}
5535
5536 \end_inset
5537
5538  family of processors.
5539  This is the default processor target.
5540 \layout List
5541 \labelwidthstring 00.00.0000
5542
5543
5544 \series bold
5545 -mds390
5546 \begin_inset LatexCommand \index{-mds390}
5547
5548 \end_inset
5549
5550
5551 \series default
5552  Generate code for the Dallas DS80C390
5553 \begin_inset LatexCommand \index{DS80C390}
5554
5555 \end_inset
5556
5557  processor.
5558 \layout List
5559 \labelwidthstring 00.00.0000
5560
5561
5562 \series bold
5563 -mds400
5564 \begin_inset LatexCommand \index{-mds400}
5565
5566 \end_inset
5567
5568
5569 \series default
5570  Generate code for the Dallas DS80C400
5571 \begin_inset LatexCommand \index{DS80C400}
5572
5573 \end_inset
5574
5575  processor.
5576 \layout List
5577 \labelwidthstring 00.00.0000
5578
5579
5580 \series bold
5581 -mhc08
5582 \begin_inset LatexCommand \index{-mhc08}
5583
5584 \end_inset
5585
5586
5587 \series default
5588  Generate code for the Freescale/Motorola HC08
5589 \begin_inset LatexCommand \index{HC08}
5590
5591 \end_inset
5592
5593  family of processors.
5594 \layout List
5595 \labelwidthstring 00.00.0000
5596
5597
5598 \series bold
5599 -mz80
5600 \begin_inset LatexCommand \index{-mz80}
5601
5602 \end_inset
5603
5604
5605 \series default
5606  Generate code for the Zilog Z80
5607 \begin_inset LatexCommand \index{Z80}
5608
5609 \end_inset
5610
5611  family of processors.
5612 \layout List
5613 \labelwidthstring 00.00.0000
5614
5615
5616 \series bold
5617 -mgbz80
5618 \begin_inset LatexCommand \index{-mgbz80}
5619
5620 \end_inset
5621
5622
5623 \series default
5624  Generate code for the GameBoy Z80
5625 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
5626
5627 \end_inset
5628
5629  processor (Not actively maintained).
5630 \layout List
5631 \labelwidthstring 00.00.0000
5632
5633
5634 \series bold
5635 -mavr
5636 \begin_inset LatexCommand \index{-mavr}
5637
5638 \end_inset
5639
5640
5641 \series default
5642  Generate code for the Atmel AVR
5643 \begin_inset LatexCommand \index{AVR}
5644
5645 \end_inset
5646
5647  processor (In development, not complete).
5648  AVR users should probably have a look at winavr
5649 \begin_inset LatexCommand \url{http://sourceforge.net/projects/winavr}
5650
5651 \end_inset
5652
5653  or
5654 \begin_inset LatexCommand \url{http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index}
5655
5656 \end_inset
5657
5658 .
5659 \layout Comment
5660
5661 I think it is fair to direct users there for now.
5662  Open source is also about avoiding unnecessary work .
5663  But I didn't find the 'official' link.
5664 \layout List
5665 \labelwidthstring 00.00.0000
5666
5667
5668 \series bold
5669 -mpic14
5670 \begin_inset LatexCommand \index{-mpic14}
5671
5672 \end_inset
5673
5674
5675 \series default
5676  Generate code for the Microchip PIC 14
5677 \begin_inset LatexCommand \index{PIC14}
5678
5679 \end_inset
5680
5681 -bit processors (p16f84 and variants.
5682  In development, not complete).
5683 \layout Comment
5684
5685 p16f627 p16f628 p16f84 p16f873 p16f877?
5686 \layout List
5687 \labelwidthstring 00.00.0000
5688
5689
5690 \series bold
5691 -mpic16
5692 \begin_inset LatexCommand \index{-mpic16}
5693
5694 \end_inset
5695
5696
5697 \series default
5698  Generate code for the Microchip PIC 16
5699 \begin_inset LatexCommand \index{PIC16}
5700
5701 \end_inset
5702
5703 -bit processors (p18f452 and variants.
5704  In development, not complete).
5705 \layout List
5706 \labelwidthstring 00.00.0000
5707
5708
5709 \series bold
5710 -mtlcs900h
5711 \series default
5712  Generate code for the Toshiba TLCS-900H
5713 \begin_inset LatexCommand \index{TLCS-900H}
5714
5715 \end_inset
5716
5717  processor (Not maintained, not complete).
5718 \layout List
5719 \labelwidthstring 00.00.0000
5720
5721
5722 \series bold
5723 -mxa51
5724 \begin_inset LatexCommand \index{-mxa51}
5725
5726 \end_inset
5727
5728
5729 \series default
5730  Generate code for the Phillips XA51
5731 \begin_inset LatexCommand \index{XA51}
5732
5733 \end_inset
5734
5735  processor (Not maintained, not complete).
5736 \layout Subsection
5737
5738 Preprocessor Options
5739 \begin_inset LatexCommand \index{Options preprocessor}
5740
5741 \end_inset
5742
5743
5744 \begin_inset LatexCommand \index{Preprocessor options}
5745
5746 \end_inset
5747
5748
5749 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5750
5751 \end_inset
5752
5753
5754 \layout List
5755 \labelwidthstring 00.00.0000
5756
5757
5758 \series bold
5759 -I<path>
5760 \begin_inset LatexCommand \index{-I<path>}
5761
5762 \end_inset
5763
5764
5765 \series default
5766  The additional location where the pre processor will look for <..h> or
5767 \begin_inset Quotes eld
5768 \end_inset
5769
5770 ..h
5771 \begin_inset Quotes erd
5772 \end_inset
5773
5774  files.
5775 \layout List
5776 \labelwidthstring 00.00.0000
5777
5778
5779 \series bold
5780 -D<macro[=value]>
5781 \begin_inset LatexCommand \index{-D<macro[=value]>}
5782
5783 \end_inset
5784
5785
5786 \series default
5787  Command line definition of macros.
5788  Passed to the preprocessor.
5789 \layout List
5790 \labelwidthstring 00.00.0000
5791
5792
5793 \series bold
5794 -M
5795 \begin_inset LatexCommand \index{-M}
5796
5797 \end_inset
5798
5799
5800 \series default
5801  Tell the preprocessor to output a rule suitable for make describing the
5802  dependencies of each object file.
5803  For each source file, the preprocessor outputs one make-rule whose target
5804  is the object file name for that source file and whose dependencies are
5805  all the files `#include'd in it.
5806  This rule may be a single line or may be continued with `
5807 \backslash
5808 '-newline if it is long.
5809  The list of rules is printed on standard output instead of the preprocessed
5810  C program.
5811  `-M' implies `-E
5812 \begin_inset LatexCommand \index{-E}
5813
5814 \end_inset
5815
5816 '.
5817 \layout List
5818 \labelwidthstring 00.00.0000
5819
5820
5821 \series bold
5822 -C
5823 \begin_inset LatexCommand \index{-C}
5824
5825 \end_inset
5826
5827
5828 \series default
5829  Tell the preprocessor not to discard comments.
5830  Used with the `-E' option.
5831 \layout List
5832 \labelwidthstring 00.00.0000
5833
5834
5835 \series bold
5836 -MM
5837 \begin_inset LatexCommand \index{-MM}
5838
5839 \end_inset
5840
5841
5842 \size large
5843 \bar under
5844
5845 \series default
5846 \size default
5847 \bar default
5848 Like `-M' but the output mentions only the user header files included with
5849  `#include
5850 \begin_inset Quotes eld
5851 \end_inset
5852
5853 file"'.
5854  System header files included with `#include <file>' are omitted.
5855 \layout List
5856 \labelwidthstring 00.00.0000
5857
5858
5859 \series bold
5860 -Aquestion(answer)
5861 \begin_inset LatexCommand \index{-Aquestion(answer)}
5862
5863 \end_inset
5864
5865
5866 \series default
5867  Assert the answer answer for question, in case it is tested with a preprocessor
5868  conditional such as `#if #question(answer)'.
5869  `-A-' disables the standard assertions that normally describe the target
5870  machine.
5871 \layout List
5872 \labelwidthstring 00.00.0000
5873
5874
5875 \series bold
5876 -Umacro
5877 \begin_inset LatexCommand \index{-Umacro}
5878
5879 \end_inset
5880
5881
5882 \series default
5883  Undefine macro macro.
5884  `-U' options are evaluated after all `-D' options, but before any `-include'
5885  and `-imacros' options.
5886 \layout List
5887 \labelwidthstring 00.00.0000
5888
5889
5890 \series bold
5891 -dM
5892 \begin_inset LatexCommand \index{-dM}
5893
5894 \end_inset
5895
5896
5897 \series default
5898  Tell the preprocessor to output only a list of the macro definitions that
5899  are in effect at the end of preprocessing.
5900  Used with the `-E' option.
5901 \layout List
5902 \labelwidthstring 00.00.0000
5903
5904
5905 \series bold
5906 -dD
5907 \begin_inset LatexCommand \index{-dD}
5908
5909 \end_inset
5910
5911
5912 \series default
5913  Tell the preprocessor to pass all macro definitions into the output, in
5914  their proper sequence in the rest of the output.
5915 \layout List
5916 \labelwidthstring 00.00.0000
5917
5918
5919 \series bold
5920 -dN
5921 \begin_inset LatexCommand \index{-dN}
5922
5923 \end_inset
5924
5925
5926 \size large
5927 \bar under
5928
5929 \series default
5930 \size default
5931 \bar default
5932 Like `-dD' except that the macro arguments and contents are omitted.
5933  Only `#define name' is included in the output.
5934 \layout List
5935 \labelwidthstring 00.00.0000
5936
5937
5938 \series bold
5939 -Wp\SpecialChar ~
5940 preprocessorOption[,preprocessorOption]
5941 \series default
5942
5943 \begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
5944
5945 \end_inset
5946
5947 ...
5948  Pass the preprocessorOption to the preprocessor
5949 \family typewriter
5950 sdcpp
5951 \family default
5952
5953 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5954
5955 \end_inset
5956
5957 .
5958  SDCC uses an adapted version of the preprocessor cpp of the GNU Compiler
5959  Collection (gcc), if you need more dedicated options please refer to the
5960  documentation at
5961 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
5962
5963 \end_inset
5964
5965 .
5966 \layout Subsection
5967
5968 Linker Options
5969 \begin_inset LatexCommand \index{Options linker}
5970
5971 \end_inset
5972
5973
5974 \begin_inset LatexCommand \index{Linker options}
5975
5976 \end_inset
5977
5978
5979 \layout List
5980 \labelwidthstring 00.00.0000
5981
5982
5983 \series bold
5984 -L\SpecialChar ~
5985 -
5986 \series default
5987
5988 \begin_inset ERT
5989 status Collapsed
5990
5991 \layout Standard
5992
5993 \backslash
5994 /
5995 \end_inset
5996
5997
5998 \series bold
5999 -lib-path
6000 \begin_inset LatexCommand \index{-\/-lib-path <path>}
6001
6002 \end_inset
6003
6004
6005 \begin_inset LatexCommand \index{-L -\/-lib-path}
6006
6007 \end_inset
6008
6009
6010 \series default
6011 \SpecialChar ~
6012 <absolute path to additional libraries> This option is passed to the linkage
6013  editor's additional libraries
6014 \begin_inset LatexCommand \index{Libraries}
6015
6016 \end_inset
6017
6018  search path.
6019  The path name must be absolute.
6020  Additional library files may be specified in the command line.
6021  See section Compiling programs for more details.
6022 \layout List
6023 \labelwidthstring 00.00.0000
6024
6025
6026 \series bold
6027 -
6028 \begin_inset ERT
6029 status Collapsed
6030
6031 \layout Standard
6032
6033 \backslash
6034 /
6035 \end_inset
6036
6037 -xram-loc
6038 \series default
6039
6040 \begin_inset LatexCommand \index{-\/-xram-loc <Value>}
6041
6042 \end_inset
6043
6044 \SpecialChar ~
6045 <Value> The start location of the external ram
6046 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
6047
6048 \end_inset
6049
6050 , default value is 0.
6051  The value entered can be in Hexadecimal or Decimal format, e.g.: -
6052 \begin_inset ERT
6053 status Collapsed
6054
6055 \layout Standard
6056
6057 \backslash
6058 /
6059 \end_inset
6060
6061 -xram-loc 0x8000 or -
6062 \begin_inset ERT
6063 status Collapsed
6064
6065 \layout Standard
6066
6067 \backslash
6068 /
6069 \end_inset
6070
6071 -xram-loc 32768.
6072 \layout List
6073 \labelwidthstring 00.00.0000
6074
6075
6076 \series bold
6077 -
6078 \begin_inset ERT
6079 status Collapsed
6080
6081 \layout Standard
6082
6083 \backslash
6084 /
6085 \end_inset
6086
6087 -code-loc
6088 \series default
6089
6090 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
6091
6092 \end_inset
6093
6094 \SpecialChar ~
6095 <Value> The start location of the code
6096 \begin_inset LatexCommand \index{code}
6097
6098 \end_inset
6099
6100  segment, default value 0.
6101  Note when this option is used the interrupt vector table is also relocated
6102  to the given address.
6103  The value entered can be in Hexadecimal or Decimal format, e.g.: -
6104 \begin_inset ERT
6105 status Collapsed
6106
6107 \layout Standard
6108
6109 \backslash
6110 /
6111 \end_inset
6112
6113 -code-loc 0x8000 or -
6114 \begin_inset ERT
6115 status Collapsed
6116
6117 \layout Standard
6118
6119 \backslash
6120 /
6121 \end_inset
6122
6123 -code-loc 32768.
6124 \layout List
6125 \labelwidthstring 00.00.0000
6126
6127
6128 \series bold
6129 -
6130 \begin_inset ERT
6131 status Collapsed
6132
6133 \layout Standard
6134
6135 \backslash
6136 /
6137 \end_inset
6138
6139 -stack-loc
6140 \series default
6141
6142 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
6143
6144 \end_inset
6145
6146 \SpecialChar ~
6147 <Value> By default the stack
6148 \begin_inset LatexCommand \index{stack}
6149
6150 \end_inset
6151
6152  is placed after the data segment.
6153  Using this option the stack can be placed anywhere in the internal memory
6154  space of the 8051.
6155  The value entered can be in Hexadecimal or Decimal format, e.g.
6156  -
6157 \begin_inset ERT
6158 status Collapsed
6159
6160 \layout Standard
6161
6162 \backslash
6163 /
6164 \end_inset
6165
6166 -stack-loc 0x20 or -
6167 \begin_inset ERT
6168 status Collapsed
6169
6170 \layout Standard
6171
6172 \backslash
6173 /
6174 \end_inset
6175
6176 -stack-loc 32.
6177  Since the sp register is incremented before a push or call, the initial
6178  sp will be set to one byte prior the provided value.
6179  The provided value should not overlap any other memory areas such as used
6180  register banks or the data segment and with enough space for the current
6181  application.
6182  The
6183 \series bold
6184 -
6185 \begin_inset ERT
6186 status Collapsed
6187
6188 \layout Standard
6189
6190 \backslash
6191 /
6192 \end_inset
6193
6194 -pack-iram
6195 \series default
6196 \SpecialChar ~
6197
6198 \begin_inset LatexCommand \index{-\/-pack-iram}
6199
6200 \end_inset
6201
6202  option (which is now a default setting) will override this setting, so
6203  you should also specify the
6204 \series bold
6205 -
6206 \begin_inset ERT
6207 status Collapsed
6208
6209 \layout Standard
6210
6211 \backslash
6212 /
6213 \end_inset
6214
6215 -no-pack-iram
6216 \series default
6217 \SpecialChar ~
6218
6219 \begin_inset LatexCommand \index{-\/-no-pack-iram}
6220
6221 \end_inset
6222
6223  option if you need to manually place the stack.
6224 \layout List
6225 \labelwidthstring 00.00.0000
6226
6227
6228 \series bold
6229 -
6230 \begin_inset ERT
6231 status Collapsed
6232
6233 \layout Standard
6234
6235 \backslash
6236 /
6237 \end_inset
6238
6239 -xstack-loc
6240 \series default
6241
6242 \begin_inset LatexCommand \index{-\/-xstack-loc <Value>}
6243
6244 \end_inset
6245
6246 \SpecialChar ~
6247 <Value> By default the external stack
6248 \begin_inset LatexCommand \index{xstack}
6249
6250 \end_inset
6251
6252  is placed after the pdata segment.
6253  Using this option the xstack can be placed anywhere in the external memory
6254  space of the 8051.
6255  The value entered can be in Hexadecimal or Decimal format, e.g.
6256  -
6257 \begin_inset ERT
6258 status Collapsed
6259
6260 \layout Standard
6261
6262 \backslash
6263 /
6264 \end_inset
6265
6266 -xstack-loc 0x8000 or -
6267 \begin_inset ERT
6268 status Collapsed
6269
6270 \layout Standard
6271
6272 \backslash
6273 /
6274 \end_inset
6275
6276 -stack-loc 32768.
6277  The provided value should not overlap any other memory areas such as the
6278  pdata or xdata segment and with enough space for the current application.
6279 \layout List
6280 \labelwidthstring 00.00.0000
6281
6282
6283 \series bold
6284 -
6285 \begin_inset ERT
6286 status Collapsed
6287
6288 \layout Standard
6289
6290 \backslash
6291 /
6292 \end_inset
6293
6294 -data-loc
6295 \series default
6296
6297 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
6298
6299 \end_inset
6300
6301 \SpecialChar ~
6302 <Value> The start location of the internal ram data
6303 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
6304
6305 \end_inset
6306
6307  segment.
6308  The value entered can be in Hexadecimal or Decimal format, eg.
6309  -
6310 \begin_inset ERT
6311 status Collapsed
6312
6313 \layout Standard
6314
6315 \backslash
6316 /
6317 \end_inset
6318
6319 -data-loc 0x20 or -
6320 \begin_inset ERT
6321 status Collapsed
6322
6323 \layout Standard
6324
6325 \backslash
6326 /
6327 \end_inset
6328
6329 -data-loc 32.
6330  (By default, the start location of the internal ram data segment  is set
6331  as low as possible in memory, taking into account the used register banks
6332  and the bit segment at address 0x20.
6333  For example if register banks 0 and 1 are used without bit variables, the
6334  data segment will be set, if -
6335 \begin_inset ERT
6336 status Collapsed
6337
6338 \layout Standard
6339
6340 \backslash
6341 /
6342 \end_inset
6343
6344 -data-loc is not used, to location 0x10.)
6345 \layout List
6346 \labelwidthstring 00.00.0000
6347
6348
6349 \series bold
6350 -
6351 \begin_inset ERT
6352 status Collapsed
6353
6354 \layout Standard
6355
6356 \backslash
6357 /
6358 \end_inset
6359
6360 -idata-loc
6361 \series default
6362
6363 \begin_inset LatexCommand \index{-\/-idata-loc <Value>}
6364
6365 \end_inset
6366
6367 \SpecialChar ~
6368 <Value> The start location of the indirectly addressable internal ram
6369 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
6370
6371 \end_inset
6372
6373  of the 8051, default value is 0x80.
6374  The value entered can be in Hexadecimal or Decimal format, eg.
6375  -
6376 \begin_inset ERT
6377 status Collapsed
6378
6379 \layout Standard
6380
6381 \backslash
6382 /
6383 \end_inset
6384
6385 -idata-loc 0x88 or -
6386 \begin_inset ERT
6387 status Collapsed
6388
6389 \layout Standard
6390
6391 \backslash
6392 /
6393 \end_inset
6394
6395 -idata-loc 136.
6396 \layout List
6397 \labelwidthstring 00.00.0000
6398
6399
6400 \series bold
6401 -
6402 \begin_inset ERT
6403 status Collapsed
6404
6405 \layout Standard
6406
6407 \backslash
6408 /
6409 \end_inset
6410
6411 -bit-loc
6412 \series default
6413 \SpecialChar ~
6414 <Value> The start location of the bit
6415 \begin_inset LatexCommand \index{bit}
6416
6417 \end_inset
6418
6419  addressable internal ram of the 8051.
6420  This is
6421 \emph on
6422 not
6423 \emph default
6424  implemented yet.
6425  Instead an option can be passed directly to the linker: -Wl\SpecialChar ~
6426 -bBSEG=<Value>.
6427 \layout List
6428 \labelwidthstring 00.00.0000
6429
6430
6431 \series bold
6432 -
6433 \begin_inset ERT
6434 status Collapsed
6435
6436 \layout Standard
6437
6438 \backslash
6439 /
6440 \end_inset
6441
6442 -out-fmt-ihx
6443 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
6444
6445 \end_inset
6446
6447
6448 \bar under
6449
6450 \series default
6451 \bar default
6452 The linker output (final object code) is in Intel Hex format.
6453 \begin_inset LatexCommand \index{Intel hex format}
6454
6455 \end_inset
6456
6457  This is the default option.
6458  The format itself is documented in the documentation of srecord
6459 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
6460
6461 \end_inset
6462
6463 .
6464 \layout List
6465 \labelwidthstring 00.00.0000
6466
6467
6468 \series bold
6469 -
6470 \begin_inset ERT
6471 status Collapsed
6472
6473 \layout Standard
6474
6475 \backslash
6476 /
6477 \end_inset
6478
6479 -out-fmt-s19
6480 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
6481
6482 \end_inset
6483
6484
6485 \bar under
6486
6487 \series default
6488 \bar default
6489 The linker output (final object code) is in Motorola S19 format
6490 \begin_inset LatexCommand \index{Motorola S19 format}
6491
6492 \end_inset
6493
6494 .
6495  The format itself is documented in the documentation of srecord.
6496 \layout List
6497 \labelwidthstring 00.00.0000
6498
6499
6500 \series bold
6501 -
6502 \begin_inset ERT
6503 status Collapsed
6504
6505 \layout Standard
6506
6507 \backslash
6508 /
6509 \end_inset
6510
6511 -out-fmt-elf
6512 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
6513
6514 \end_inset
6515
6516
6517 \bar under
6518
6519 \series default
6520 \bar default
6521 The linker output (final object code) is in ELF format
6522 \begin_inset LatexCommand \index{ELF format}
6523
6524 \end_inset
6525
6526 .
6527  (Currently only supported for the HC08 processors)
6528 \layout List
6529 \labelwidthstring 00.00.0000
6530
6531
6532 \series bold
6533 -Wl\SpecialChar ~
6534 linkOption[,linkOption]
6535 \series default
6536
6537 \begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
6538
6539 \end_inset
6540
6541 ...
6542  Pass the linkOption to the linker.
6543  See file sdcc/as/doc/asxhtm.html for more on linker options.
6544 \layout Subsection
6545
6546 MCS51 Options
6547 \begin_inset LatexCommand \index{Options MCS51}
6548
6549 \end_inset
6550
6551
6552 \begin_inset LatexCommand \index{MCS51 options}
6553
6554 \end_inset
6555
6556
6557 \layout List
6558 \labelwidthstring 00.00.0000
6559
6560
6561 \series bold
6562 -
6563 \begin_inset ERT
6564 status Collapsed
6565
6566 \layout Standard
6567
6568 \backslash
6569 /
6570 \end_inset
6571
6572 -model-small
6573 \begin_inset LatexCommand \index{-\/-model-small}
6574
6575 \end_inset
6576
6577
6578 \series default
6579 \size large
6580 \emph on
6581
6582 \size default
6583 \emph default
6584 Generate code for Small Model programs, see section Memory Models for more
6585  details.
6586  This is the default model.
6587 \layout List
6588 \labelwidthstring 00.00.0000
6589
6590
6591 \series bold
6592 -
6593 \begin_inset ERT
6594 status Collapsed
6595
6596 \layout Standard
6597
6598 \backslash
6599 /
6600 \end_inset
6601
6602 -model-medium
6603 \begin_inset LatexCommand \index{-\/-model-medium}
6604
6605 \end_inset
6606
6607
6608 \series default
6609  Generate code for Medium model programs, see section Memory Models for
6610  more details.
6611  If this option is used all source files in the project have to be compiled
6612  with this option.
6613  It must also be used when invoking the linker.
6614 \layout List
6615 \labelwidthstring 00.00.0000
6616
6617
6618 \series bold
6619 -
6620 \begin_inset ERT
6621 status Collapsed
6622
6623 \layout Standard
6624
6625 \backslash
6626 /
6627 \end_inset
6628
6629 -model-large
6630 \begin_inset LatexCommand \index{-\/-model-large}
6631
6632 \end_inset
6633
6634
6635 \series default
6636  Generate code for Large model programs, see section Memory Models for more
6637  details.
6638  If this option is used all source files in the project have to be compiled
6639  with this option.
6640  It must also be used when invoking the linker.
6641 \layout List
6642 \labelwidthstring 00.00.0000
6643
6644
6645 \series bold
6646 -
6647 \begin_inset ERT
6648 status Collapsed
6649
6650 \layout Standard
6651
6652 \backslash
6653 /
6654 \end_inset
6655
6656 -xstack
6657 \begin_inset LatexCommand \index{-\/-xstack}
6658
6659 \end_inset
6660
6661
6662 \series default
6663  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
6664  variables and passing parameters.
6665  See section
6666 \begin_inset LatexCommand \ref{sub:External-Stack}
6667
6668 \end_inset
6669
6670 \SpecialChar ~
6671  External Stack for more details.
6672 \layout List
6673 \labelwidthstring 00.00.0000
6674
6675
6676 \series bold
6677 -
6678 \begin_inset ERT
6679 status Collapsed
6680
6681 \layout Standard
6682
6683 \backslash
6684 /
6685 \end_inset
6686
6687 -iram-size
6688 \series default
6689 \SpecialChar ~
6690 <Value>
6691 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
6692
6693 \end_inset
6694
6695  Causes the linker to check if the internal ram usage is within limits of
6696  the given value.
6697 \layout List
6698 \labelwidthstring 00.00.0000
6699
6700
6701 \series bold
6702 -
6703 \begin_inset ERT
6704 status Collapsed
6705
6706 \layout Standard
6707
6708 \backslash
6709 /
6710 \end_inset
6711
6712 -xram-size
6713 \series default
6714 \SpecialChar ~
6715 <Value>
6716 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
6717
6718 \end_inset
6719
6720  Causes the linker to check if the external ram usage is within limits of
6721  the given value.
6722 \layout List
6723 \labelwidthstring 00.00.0000
6724
6725
6726 \series bold
6727 -
6728 \begin_inset ERT
6729 status Collapsed
6730
6731 \layout Standard
6732
6733 \backslash
6734 /
6735 \end_inset
6736
6737 -code-size
6738 \series default
6739 \SpecialChar ~
6740 <Value>
6741 \begin_inset LatexCommand \index{-\/-code-size <Value>}
6742
6743 \end_inset
6744
6745  Causes the linker to check if the code memory usage is within limits of
6746  the given value.
6747 \layout List
6748 \labelwidthstring 00.00.0000
6749
6750
6751 \series bold
6752 -
6753 \begin_inset ERT
6754 status Collapsed
6755
6756 \layout Standard
6757
6758 \backslash
6759 /
6760 \end_inset
6761
6762 -stack-size
6763 \series default
6764 \SpecialChar ~
6765 <Value>
6766 \begin_inset LatexCommand \index{-\/-stack-size <Value>}
6767
6768 \end_inset
6769
6770  Causes the linker to check if there is at minimum <Value> bytes for stack.
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 -pack-iram
6787 \series default
6788 \SpecialChar ~
6789
6790 \begin_inset LatexCommand \index{-\/-pack-iram}
6791
6792 \end_inset
6793
6794  Causes the linker to use unused register banks for data variables and pack
6795  data, idata and stack together.
6796  This is the default now.
6797 \layout List
6798 \labelwidthstring 00.00.0000
6799
6800
6801 \series bold
6802 -
6803 \begin_inset ERT
6804 status Collapsed
6805
6806 \layout Standard
6807
6808 \backslash
6809 /
6810 \end_inset
6811
6812 -no-pack-iram
6813 \series default
6814 \SpecialChar ~
6815
6816 \begin_inset LatexCommand \index{-\/-no-pack-iram}
6817
6818 \end_inset
6819
6820  Causes the linker to use old style for allocating memory areas.
6821 \layout Subsection
6822
6823 DS390 / DS400 Options
6824 \begin_inset LatexCommand \index{Options DS390}
6825
6826 \end_inset
6827
6828
6829 \begin_inset LatexCommand \index{DS390 options}
6830
6831 \end_inset
6832
6833
6834 \layout List
6835 \labelwidthstring 00.00.0000
6836
6837
6838 \series bold
6839 -
6840 \begin_inset ERT
6841 status Collapsed
6842
6843 \layout Standard
6844
6845 \backslash
6846 /
6847 \end_inset
6848
6849 -model-flat24
6850 \series default
6851
6852 \begin_inset LatexCommand \index{-\/-model-flat24}
6853
6854 \end_inset
6855
6856
6857 \size large
6858 \emph on
6859
6860 \size default
6861 \emph default
6862 Generate 24-bit flat mode code.
6863  This is the one and only that the ds390 code generator supports right now
6864  and is default when using
6865 \emph on
6866 -mds390
6867 \emph default
6868 .
6869  See section Memory Models for more details.
6870 \layout List
6871 \labelwidthstring 00.00.0000
6872
6873
6874 \series bold
6875 -
6876 \begin_inset ERT
6877 status Collapsed
6878
6879 \layout Standard
6880
6881 \backslash
6882 /
6883 \end_inset
6884
6885 -protect-sp-update
6886 \begin_inset LatexCommand \index{-\/-protect-sp-update}
6887
6888 \end_inset
6889
6890
6891 \series default
6892  disable interrupts during ESP:SP updates.
6893 \layout List
6894 \labelwidthstring 00.00.0000
6895
6896
6897 \series bold
6898 -
6899 \begin_inset ERT
6900 status Collapsed
6901
6902 \layout Standard
6903
6904 \backslash
6905 /
6906 \end_inset
6907
6908 -stack-10bit
6909 \series default
6910
6911 \begin_inset LatexCommand \index{-\/-stack-10bit}
6912
6913 \end_inset
6914
6915  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
6916  This is the one and only that the ds390 code generator supports right now
6917  and is default when using
6918 \emph on
6919 -mds390
6920 \emph default
6921 .
6922  In this mode, the stack is located in the lower 1K of the internal RAM,
6923  which is mapped to 0x400000.
6924  Note that the support is incomplete, since it still uses a single byte
6925  as the stack pointer.
6926  This means that only the lower 256 bytes of the potential 1K stack space
6927  will actually be used.
6928  However, this does allow you to reclaim the precious 256 bytes of low RAM
6929  for use for the DATA and IDATA segments.
6930  The compiler will not generate any code to put the processor into 10 bit
6931  stack mode.
6932  It is important to ensure that the processor is in this mode before calling
6933  any re-entrant functions compiled with this option.
6934  In principle, this should work with the
6935 \emph on
6936 -
6937 \begin_inset ERT
6938 status Collapsed
6939
6940 \layout Standard
6941
6942 \backslash
6943 /
6944 \end_inset
6945
6946 -stack-auto
6947 \begin_inset LatexCommand \index{-\/-stack-auto}
6948
6949 \end_inset
6950
6951
6952 \emph default
6953  option, but that has not been tested.
6954  It is incompatible with the
6955 \emph on
6956 -
6957 \begin_inset ERT
6958 status Collapsed
6959
6960 \layout Standard
6961
6962 \backslash
6963 /
6964 \end_inset
6965
6966 -xstack
6967 \begin_inset LatexCommand \index{-\/-xstack}
6968
6969 \end_inset
6970
6971
6972 \emph default
6973  option.
6974  It also only makes sense if the processor is in 24 bit contiguous addressing
6975  mode (see the
6976 \emph on
6977 -
6978 \begin_inset ERT
6979 status Collapsed
6980
6981 \layout Standard
6982
6983 \backslash
6984 /
6985 \end_inset
6986
6987 -model-flat24 option
6988 \emph default
6989 ).
6990 \layout List
6991 \labelwidthstring 00.00.0000
6992
6993
6994 \series bold
6995 -
6996 \begin_inset ERT
6997 status Collapsed
6998
6999 \layout Standard
7000
7001 \backslash
7002 /
7003 \end_inset
7004
7005 -stack-probe
7006 \begin_inset LatexCommand \index{-\/-stack-probe}
7007
7008 \end_inset
7009
7010
7011 \series default
7012  insert call to function __stack_probe at each function prologue.
7013 \layout List
7014 \labelwidthstring 00.00.0000
7015
7016
7017 \series bold
7018 -
7019 \begin_inset ERT
7020 status Collapsed
7021
7022 \layout Standard
7023
7024 \backslash
7025 /
7026 \end_inset
7027
7028 -tini-libid
7029 \begin_inset LatexCommand \index{-\/-tini-libid}
7030
7031 \end_inset
7032
7033
7034 \series default
7035  <nnnn> LibraryID used in -mTININative.
7036
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 -use-accelerator
7053 \begin_inset LatexCommand \index{-\/-use-accelerator}
7054
7055 \end_inset
7056
7057
7058 \series default
7059  generate code for DS390 Arithmetic Accelerator.
7060
7061 \layout Subsection
7062
7063 Z80 Options
7064 \begin_inset LatexCommand \index{Options Z80}
7065
7066 \end_inset
7067
7068
7069 \begin_inset LatexCommand \index{Z80 options}
7070
7071 \end_inset
7072
7073
7074 \layout List
7075 \labelwidthstring 00.00.0000
7076
7077
7078 \series bold
7079 -
7080 \begin_inset ERT
7081 status Collapsed
7082
7083 \layout Standard
7084
7085 \backslash
7086 /
7087 \end_inset
7088
7089 -callee-saves-bc
7090 \series default
7091
7092 \begin_inset LatexCommand \index{-\/-callee-saves-bc}
7093
7094 \end_inset
7095
7096
7097 \size large
7098 \emph on
7099
7100 \size default
7101 \emph default
7102 Force a called function to always save BC.
7103 \layout List
7104 \labelwidthstring 00.00.0000
7105
7106
7107 \series bold
7108 -
7109 \begin_inset ERT
7110 status Collapsed
7111
7112 \layout Standard
7113
7114 \backslash
7115 /
7116 \end_inset
7117
7118 -no-std-crt0
7119 \series default
7120
7121 \begin_inset LatexCommand \index{-\/-no-std-crt0}
7122
7123 \end_inset
7124
7125  When linking, skip the standard crt0.o object file.
7126  You must provide your own crt0.o for your system when linking.
7127
7128 \layout Subsection
7129
7130 Optimization Options
7131 \begin_inset LatexCommand \index{Options optimization}
7132
7133 \end_inset
7134
7135
7136 \begin_inset LatexCommand \index{Optimization options}
7137
7138 \end_inset
7139
7140
7141 \layout List
7142 \labelwidthstring 00.00.0000
7143
7144
7145 \series bold
7146 -
7147 \begin_inset ERT
7148 status Collapsed
7149
7150 \layout Standard
7151
7152 \backslash
7153 /
7154 \end_inset
7155
7156 -nogcse
7157 \begin_inset LatexCommand \index{-\/-nogcse}
7158
7159 \end_inset
7160
7161
7162 \series default
7163  Will not do global subexpression elimination, this option may be used when
7164  the compiler creates undesirably large stack/data spaces to store compiler
7165  temporaries (
7166 \emph on
7167 s
7168 \emph default
7169 pill
7170 \emph on
7171 loc
7172 \emph default
7173 ations, sloc
7174 \begin_inset LatexCommand \index{sloc (spill location)}
7175
7176 \end_inset
7177
7178 ).
7179  A warning message will be generated when this happens and the compiler
7180  will indicate the number of extra bytes it allocated.
7181  It is recommended that this option NOT be used, #pragma\SpecialChar ~
7182 nogcse
7183 \begin_inset LatexCommand \index{\#pragma nogcse}
7184
7185 \end_inset
7186
7187  can be used to turn off global subexpression elimination
7188 \begin_inset LatexCommand \index{Subexpression elimination}
7189
7190 \end_inset
7191
7192  for a given function only.
7193 \layout List
7194 \labelwidthstring 00.00.0000
7195
7196
7197 \series bold
7198 -
7199 \begin_inset ERT
7200 status Collapsed
7201
7202 \layout Standard
7203
7204 \backslash
7205 /
7206 \end_inset
7207
7208 -noinvariant
7209 \begin_inset LatexCommand \index{-\/-noinvariant}
7210
7211 \end_inset
7212
7213
7214 \series default
7215  Will not do loop invariant optimizations, this may be turned off for reasons
7216  explained for the previous option.
7217  For more details of loop optimizations performed see Loop Invariants in
7218  section
7219 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
7220
7221 \end_inset
7222
7223 .
7224  It is recommended that this option NOT be used, #pragma\SpecialChar ~
7225 noinvariant
7226 \begin_inset LatexCommand \index{\#pragma noinvariant}
7227
7228 \end_inset
7229
7230  can be used to turn off invariant optimizations for a given function only.
7231 \layout List
7232 \labelwidthstring 00.00.0000
7233
7234
7235 \series bold
7236 -
7237 \begin_inset ERT
7238 status Collapsed
7239
7240 \layout Standard
7241
7242 \backslash
7243 /
7244 \end_inset
7245
7246 -noinduction
7247 \begin_inset LatexCommand \index{-\/-noinduction}
7248
7249 \end_inset
7250
7251
7252 \series default
7253  Will not do loop induction optimizations, see section strength reduction
7254  for more details.
7255  It is recommended that this option is NOT used, #pragma\SpecialChar ~
7256 noinduction
7257 \begin_inset LatexCommand \index{\#pragma noinduction}
7258
7259 \end_inset
7260
7261  can be used to turn off induction optimizations for a given function only.
7262 \layout List
7263 \labelwidthstring 00.00.0000
7264
7265
7266 \series bold
7267 -
7268 \begin_inset ERT
7269 status Collapsed
7270
7271 \layout Standard
7272
7273 \backslash
7274 /
7275 \end_inset
7276
7277 -nojtbound
7278 \begin_inset LatexCommand \index{-\/-nojtbound}
7279
7280 \end_inset
7281
7282
7283 \size large
7284 \bar under
7285
7286 \series default
7287 \size default
7288 \bar default
7289  Will not generate boundary condition check when switch statements
7290 \begin_inset LatexCommand \index{switch statement}
7291
7292 \end_inset
7293
7294  are implemented using jump-tables.
7295  See section
7296 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
7297
7298 \end_inset
7299
7300 \SpecialChar ~
7301 Switch Statements for more details.
7302  It is recommended that this option is NOT used, #pragma\SpecialChar ~
7303 nojtbound
7304 \begin_inset LatexCommand \index{\#pragma nojtbound}
7305
7306 \end_inset
7307
7308  can be used to turn off boundary checking for jump tables for a given function
7309  only.
7310 \layout List
7311 \labelwidthstring 00.00.0000
7312
7313
7314 \series bold
7315 -
7316 \begin_inset ERT
7317 status Collapsed
7318
7319 \layout Standard
7320
7321 \backslash
7322 /
7323 \end_inset
7324
7325 -noloopreverse
7326 \begin_inset LatexCommand \index{-\/-noloopreverse}
7327
7328 \end_inset
7329
7330
7331 \series default
7332 \size large
7333
7334 \size default
7335 Will not do loop reversal
7336 \begin_inset LatexCommand \index{Loop reversing}
7337
7338 \end_inset
7339
7340 optimization.
7341 \layout List
7342 \labelwidthstring 00.00.0000
7343
7344 -
7345 \begin_inset ERT
7346 status Collapsed
7347
7348 \layout Standard
7349
7350 \backslash
7351 /
7352 \end_inset
7353
7354 -
7355 \series bold
7356 nolabelopt
7357 \series default
7358
7359 \begin_inset LatexCommand \index{-\/-nolabelopt }
7360
7361 \end_inset
7362
7363 Will not optimize labels (makes the dumpfiles more readable).
7364 \layout List
7365 \labelwidthstring 00.00.0000
7366
7367
7368 \series bold
7369 -
7370 \begin_inset ERT
7371 status Collapsed
7372
7373 \layout Standard
7374
7375 \backslash
7376 /
7377 \end_inset
7378
7379 -no-xinit-opt
7380 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
7381
7382 \end_inset
7383
7384
7385 \series default
7386  Will not memcpy initialized data from code space into xdata space.
7387  This saves a few bytes in code space if you don't have initialized data
7388 \begin_inset LatexCommand \index{Variable initialization}
7389
7390 \end_inset
7391
7392 .
7393 \layout List
7394 \labelwidthstring 00.00.0000
7395
7396
7397 \series bold
7398 -
7399 \begin_inset ERT
7400 status Collapsed
7401
7402 \layout Standard
7403
7404 \backslash
7405 /
7406 \end_inset
7407
7408 -nooverlay
7409 \begin_inset LatexCommand \index{-\/-nooverlay}
7410
7411 \end_inset
7412
7413
7414 \series default
7415   The compiler will not overlay parameters and local variables of any function,
7416  see section Parameters and local variables for more details.
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 -no-peep
7433 \begin_inset LatexCommand \index{-\/-no-peep}
7434
7435 \end_inset
7436
7437
7438 \series default
7439  Disable peep-hole optimization with built-in rules.
7440 \layout List
7441 \labelwidthstring 00.00.0000
7442
7443
7444 \series bold
7445 -
7446 \begin_inset ERT
7447 status Collapsed
7448
7449 \layout Standard
7450
7451 \backslash
7452 /
7453 \end_inset
7454
7455 -peep-file
7456 \series default
7457
7458 \begin_inset LatexCommand \index{-\/-peep-file}
7459
7460 \end_inset
7461
7462 \SpecialChar ~
7463 <filename> This option can be used to use additional rules to be used by
7464  the peep hole optimizer.
7465  See section
7466 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
7467
7468 \end_inset
7469
7470 \SpecialChar ~
7471 Peep Hole optimizations for details on how to write these rules.
7472 \layout List
7473 \labelwidthstring 00.00.0000
7474
7475
7476 \series bold
7477 -
7478 \begin_inset ERT
7479 status Collapsed
7480
7481 \layout Standard
7482
7483 \backslash
7484 /
7485 \end_inset
7486
7487 -peep-asm
7488 \begin_inset LatexCommand \index{-\/-peep-asm}
7489
7490 \end_inset
7491
7492
7493 \series default
7494  Pass the inline assembler code through the peep hole optimizer.
7495  This can cause unexpected changes to inline assembler code, please go through
7496  the peephole optimizer
7497 \begin_inset LatexCommand \index{Peephole optimizer}
7498
7499 \end_inset
7500
7501  rules defined in the source file tree '<target>/peeph.def' before using
7502  this option.
7503 \layout List
7504 \labelwidthstring 00.00.0000
7505
7506
7507 \series bold
7508 -
7509 \begin_inset ERT
7510 status Collapsed
7511
7512 \layout Standard
7513
7514 \backslash
7515 /
7516 \end_inset
7517
7518 -opt-code-speed
7519 \begin_inset LatexCommand \index{-\/-opt-code-speed}
7520
7521 \end_inset
7522
7523
7524 \series default
7525  The compiler will optimize code generation towards fast code, possibly
7526  at the expense of code size.
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-size
7543 \begin_inset LatexCommand \index{-\/-opt-code-size}
7544
7545 \end_inset
7546
7547
7548 \series default
7549  The compiler will optimize code generation towards compact code, possibly
7550  at the expense of code speed.
7551 \layout Subsection
7552
7553 Other Options
7554 \begin_inset LatexCommand \index{Options other}
7555
7556 \end_inset
7557
7558
7559 \layout List
7560 \labelwidthstring 00.00.0000
7561
7562
7563 \series bold
7564 -c\SpecialChar ~
7565 -
7566 \begin_inset ERT
7567 status Collapsed
7568
7569 \layout Standard
7570
7571 \backslash
7572 /
7573 \end_inset
7574
7575 -compile-only
7576 \begin_inset LatexCommand \index{-\/-compile-only}
7577
7578 \end_inset
7579
7580
7581 \begin_inset LatexCommand \index{-c -\/-compile-only}
7582
7583 \end_inset
7584
7585
7586 \series default
7587  will compile and assemble the source, but will not call the linkage editor.
7588 \layout List
7589 \labelwidthstring 00.00.0000
7590
7591
7592 \series bold
7593 -
7594 \series default
7595
7596 \begin_inset ERT
7597 status Collapsed
7598
7599 \layout Standard
7600
7601 \backslash
7602 /
7603 \end_inset
7604
7605
7606 \series bold
7607 -c1mode
7608 \begin_inset LatexCommand \index{-\/-c1mode}
7609
7610 \end_inset
7611
7612
7613 \series default
7614  reads the preprocessed source from standard input and compiles it.
7615  The file name for the assembler output must be specified using the -o option.
7616 \layout List
7617 \labelwidthstring 00.00.0000
7618
7619
7620 \series bold
7621 -E
7622 \begin_inset LatexCommand \index{-E}
7623
7624 \end_inset
7625
7626
7627 \series default
7628  Run only the C preprocessor.
7629  Preprocess all the C source files specified and output the results to standard
7630  output.
7631 \layout List
7632 \labelwidthstring 00.00.0000
7633
7634
7635 \series bold
7636 -o\SpecialChar ~
7637 <path/file>
7638 \begin_inset LatexCommand \index{-o <path/file>}
7639
7640 \end_inset
7641
7642
7643 \series default
7644 The output path resp.
7645  file where everything will be placed.
7646  If the parameter is a path, it must have a trailing slash (or backslash
7647  for the Windows binaries) to be recognized as a path.
7648
7649 \layout List
7650 \labelwidthstring 00.00.0000
7651
7652
7653 \series bold
7654 -
7655 \begin_inset ERT
7656 status Collapsed
7657
7658 \layout Standard
7659
7660 \backslash
7661 /
7662 \end_inset
7663
7664 -stack-auto
7665 \begin_inset LatexCommand \index{-\/-stack-auto}
7666
7667 \end_inset
7668
7669
7670 \series default
7671 \size large
7672 \emph on
7673
7674 \size default
7675 \emph default
7676 All functions in the source file will be compiled as
7677 \emph on
7678 reentrant
7679 \emph default
7680
7681 \begin_inset LatexCommand \index{reentrant}
7682
7683 \end_inset
7684
7685 , i.e.
7686  the parameters and local variables will be allocated on the stack
7687 \begin_inset LatexCommand \index{stack}
7688
7689 \end_inset
7690
7691 .
7692  See section
7693 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
7694
7695 \end_inset
7696
7697  Parameters and Local Variables for more details.
7698  If this option is used all source files in the project should be compiled
7699  with this option.
7700  It automatically implies --int-long-reent and --float-reent.
7701
7702 \layout List
7703 \labelwidthstring 00.00.0000
7704
7705
7706 \series bold
7707 -
7708 \begin_inset ERT
7709 status Collapsed
7710
7711 \layout Standard
7712
7713 \backslash
7714 /
7715 \end_inset
7716
7717 -callee-saves
7718 \begin_inset LatexCommand \index{-\/-callee-saves}
7719
7720 \end_inset
7721
7722  function1[,function2][,function3]....
7723
7724 \series default
7725  The compiler by default uses a caller saves convention for register saving
7726  across function calls, however this can cause unnecessary register pushing
7727  & popping when calling small functions from larger functions.
7728  This option can be used to switch the register saving convention for the
7729  function names specified.
7730  The compiler will not save registers when calling these functions, no extra
7731  code will be generated at the entry & exit (function prologue
7732 \series bold
7733
7734 \begin_inset LatexCommand \index{function prologue}
7735
7736 \end_inset
7737
7738
7739 \series default
7740  & epilogue
7741 \series bold
7742
7743 \begin_inset LatexCommand \index{function epilogue}
7744
7745 \end_inset
7746
7747
7748 \series default
7749 ) for these functions to save & restore the registers used by these functions,
7750  this can SUBSTANTIALLY reduce code & improve run time performance of the
7751  generated code.
7752  In the future the compiler (with inter procedural analysis) will be able
7753  to determine the appropriate scheme to use for each function call.
7754  DO NOT use this option for built-in functions such as _mulint..., if this
7755  option is used for a library function the appropriate library function
7756  needs to be recompiled with the same option.
7757  If the project consists of multiple source files then all the source file
7758  should be compiled with the same -
7759 \begin_inset ERT
7760 status Collapsed
7761
7762 \layout Standard
7763
7764 \backslash
7765 /
7766 \end_inset
7767
7768 -callee-saves option string.
7769  Also see #pragma\SpecialChar ~
7770 callee_saves
7771 \begin_inset LatexCommand \index{\#pragma callee\_saves}
7772
7773 \end_inset
7774
7775 .
7776 \layout List
7777 \labelwidthstring 00.00.0000
7778
7779
7780 \series bold
7781 -
7782 \begin_inset ERT
7783 status Collapsed
7784
7785 \layout Standard
7786
7787 \backslash
7788 /
7789 \end_inset
7790
7791 -debug
7792 \begin_inset LatexCommand \index{-\/-debug}
7793
7794 \end_inset
7795
7796
7797 \bar under
7798
7799 \series default
7800 \bar default
7801 When this option is used the compiler will generate debug information.
7802  The debug information collected in a file with .cdb extension can be used
7803  with the SDCDB.
7804  For more information see documentation for SDCDB.
7805  Another file with no extension contains debug information in AOMF or AOMF51
7806 \begin_inset LatexCommand \index{AOMF, AOMF51}
7807
7808 \end_inset
7809
7810  format which is commonly used by third party tools.
7811 \layout List
7812 \labelwidthstring 00.00.0000
7813
7814
7815 \series bold
7816 -S
7817 \begin_inset LatexCommand \index{-S}
7818
7819 \end_inset
7820
7821
7822 \size large
7823 \bar under
7824
7825 \series default
7826 \size default
7827 \bar default
7828 Stop after the stage of compilation proper; do not assemble.
7829  The output is an assembler code file for the input file specified.
7830 \layout List
7831 \labelwidthstring 00.00.0000
7832
7833
7834 \series bold
7835 -
7836 \begin_inset ERT
7837 status Collapsed
7838
7839 \layout Standard
7840
7841 \backslash
7842 /
7843 \end_inset
7844
7845 -int-long-reent
7846 \begin_inset LatexCommand \index{-\/-int-long-reent}
7847
7848 \end_inset
7849
7850
7851 \series default
7852  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
7853  Note by default these libraries are compiled as non-reentrant.
7854  See section Installation for more details.
7855 \layout List
7856 \labelwidthstring 00.00.0000
7857
7858
7859 \series bold
7860 -
7861 \begin_inset ERT
7862 status Collapsed
7863
7864 \layout Standard
7865
7866 \backslash
7867 /
7868 \end_inset
7869
7870 -cyclomatic
7871 \begin_inset LatexCommand \index{-\/-cyclomatic}
7872
7873 \end_inset
7874
7875
7876 \bar under
7877
7878 \series default
7879 \bar default
7880 This option will cause the compiler to generate an information message for
7881  each function in the source file.
7882  The message contains some
7883 \emph on
7884 important
7885 \emph default
7886  information about the function.
7887  The number of edges and nodes the compiler detected in the control flow
7888  graph of the function, and most importantly the
7889 \emph on
7890 cyclomatic complexity
7891 \begin_inset LatexCommand \index{Cyclomatic complexity}
7892
7893 \end_inset
7894
7895
7896 \emph default
7897  see section on Cyclomatic Complexity for more details.
7898 \layout List
7899 \labelwidthstring 00.00.0000
7900
7901
7902 \series bold
7903 -
7904 \begin_inset ERT
7905 status Collapsed
7906
7907 \layout Standard
7908
7909 \backslash
7910 /
7911 \end_inset
7912
7913 -float-reent
7914 \begin_inset LatexCommand \index{-\/-float-reent}
7915
7916 \end_inset
7917
7918
7919 \series default
7920  Floating point library is compiled as reentrant
7921 \begin_inset LatexCommand \index{reentrant}
7922
7923 \end_inset
7924
7925 .
7926  See section Installation for more details.
7927 \layout List
7928 \labelwidthstring 00.00.0000
7929
7930
7931 \series bold
7932 -
7933 \begin_inset ERT
7934 status Collapsed
7935
7936 \layout Standard
7937
7938 \backslash
7939 /
7940 \end_inset
7941
7942 -main-return
7943 \begin_inset LatexCommand \index{-\/-main-return}
7944
7945 \end_inset
7946
7947
7948 \series default
7949  This option can be used if the code generated is called by a monitor program
7950  or if the main routine includes an endless loop.
7951  This option might result in slightly smaller code and save two bytes of
7952  stack space.
7953  The return from the 'main'
7954 \begin_inset LatexCommand \index{main return}
7955
7956 \end_inset
7957
7958  function will return to the function calling main.
7959  The default setting is to lock up i.e.
7960  generate a '
7961 \family typewriter
7962 sjmp .
7963 \family default
7964 '.
7965 \layout List
7966 \labelwidthstring 00.00.0000
7967
7968
7969 \series bold
7970 -
7971 \begin_inset ERT
7972 status Collapsed
7973
7974 \layout Standard
7975
7976 \backslash
7977 /
7978 \end_inset
7979
7980 -nostdinc
7981 \begin_inset LatexCommand \index{-\/-nostdinc}
7982
7983 \end_inset
7984
7985
7986 \series default
7987  This will prevent the compiler from passing on the default include path
7988  to the preprocessor.
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 -nostdlib
8005 \begin_inset LatexCommand \index{-\/-nostdlib}
8006
8007 \end_inset
8008
8009
8010 \series default
8011  This will prevent the compiler from passing on the default library
8012 \begin_inset LatexCommand \index{Libraries}
8013
8014 \end_inset
8015
8016  path to the linker.
8017 \layout List
8018 \labelwidthstring 00.00.0000
8019
8020
8021 \series bold
8022 -
8023 \begin_inset ERT
8024 status Collapsed
8025
8026 \layout Standard
8027
8028 \backslash
8029 /
8030 \end_inset
8031
8032 -verbose
8033 \begin_inset LatexCommand \index{-\/-verbose}
8034
8035 \end_inset
8036
8037
8038 \series default
8039  Shows the various actions the compiler is performing.
8040 \layout List
8041 \labelwidthstring 00.00.0000
8042
8043
8044 \series bold
8045 -V
8046 \begin_inset LatexCommand \index{-V}
8047
8048 \end_inset
8049
8050
8051 \series default
8052  Shows the actual commands the compiler is executing.
8053 \layout List
8054 \labelwidthstring 00.00.0000
8055
8056
8057 \series bold
8058 -
8059 \begin_inset ERT
8060 status Collapsed
8061
8062 \layout Standard
8063
8064 \backslash
8065 /
8066 \end_inset
8067
8068 -no-c-code-in-asm
8069 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
8070
8071 \end_inset
8072
8073
8074 \series default
8075  Hides your ugly and inefficient c-code from the asm file, so you can always
8076  blame the compiler :)
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-peep-comments
8093 \begin_inset LatexCommand \index{-\/-no-peep-comments}
8094
8095 \end_inset
8096
8097
8098 \series default
8099  Will not include peep-hole comments in the generated files.
8100 \layout List
8101 \labelwidthstring 00.00.0000
8102
8103
8104 \series bold
8105 -
8106 \begin_inset ERT
8107 status Collapsed
8108
8109 \layout Standard
8110
8111 \backslash
8112 /
8113 \end_inset
8114
8115 -i-code-in-asm
8116 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
8117
8118 \end_inset
8119
8120
8121 \series default
8122  Include i-codes in the asm file.
8123  Sounds like noise but is most helpful for debugging the compiler itself.
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 -less-pedantic
8140 \begin_inset LatexCommand \index{-\/-less-pedantic}
8141
8142 \end_inset
8143
8144
8145 \series default
8146  Disable some of the more pedantic warnings
8147 \begin_inset LatexCommand \index{Warnings}
8148
8149 \end_inset
8150
8151  (jwk burps: please be more specific here, please!).
8152 \layout List
8153 \labelwidthstring 00.00.0000
8154
8155
8156 \series bold
8157 -
8158 \begin_inset ERT
8159 status Collapsed
8160
8161 \layout Standard
8162
8163 \backslash
8164 /
8165 \end_inset
8166
8167 -disable-warning\SpecialChar ~
8168 <nnnn>
8169 \begin_inset LatexCommand \index{-\/-disable-warning}
8170
8171 \end_inset
8172
8173
8174 \series default
8175  Disable specific warning with number <nnnn>.
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 -print-search-dirs
8192 \begin_inset LatexCommand \index{-\/-print-search-dirs}
8193
8194 \end_inset
8195
8196
8197 \series default
8198  Display the directories in the compiler's search path
8199 \layout List
8200 \labelwidthstring 00.00.0000
8201
8202
8203 \series bold
8204 -
8205 \begin_inset ERT
8206 status Collapsed
8207
8208 \layout Standard
8209
8210 \backslash
8211 /
8212 \end_inset
8213
8214 -vc
8215 \begin_inset LatexCommand \index{-\/-vc}
8216
8217 \end_inset
8218
8219
8220 \series default
8221  Display errors and warnings using MSVC style, so you can use SDCC with
8222  visual studio.
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 -use-stdout
8239 \begin_inset LatexCommand \index{-\/-use-stdout}
8240
8241 \end_inset
8242
8243
8244 \series default
8245  Send errors and warnings to stdout instead of stderr.
8246 \layout List
8247 \labelwidthstring 00.00.0000
8248
8249
8250 \series bold
8251 -Wa\SpecialChar ~
8252 asmOption[,asmOption]
8253 \series default
8254
8255 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
8256
8257 \end_inset
8258
8259 ...
8260  Pass the asmOption to the assembler
8261 \begin_inset LatexCommand \index{Options assembler}
8262
8263 \end_inset
8264
8265
8266 \begin_inset LatexCommand \index{Assembler options}
8267
8268 \end_inset
8269
8270 .
8271  See file sdcc/as/doc/asxhtm.html for assembler options.cd
8272 \layout List
8273 \labelwidthstring 00.00.0000
8274
8275
8276 \series bold
8277 -
8278 \begin_inset ERT
8279 status Collapsed
8280
8281 \layout Standard
8282
8283 \backslash
8284 /
8285 \end_inset
8286
8287 -std-sdcc89
8288 \begin_inset LatexCommand \index{-\/-std-sdcc89}
8289
8290 \end_inset
8291
8292
8293 \series default
8294  Generally follow the C89 standard, but allow SDCC features that conflict
8295  with the standard (default).
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-c89
8312 \begin_inset LatexCommand \index{-\/-std-c89}
8313
8314 \end_inset
8315
8316
8317 \series default
8318  Follow the C89 standard and disable SDCC features that conflict with the
8319  standard.
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-sdcc99
8336 \begin_inset LatexCommand \index{-\/-std-sdcc99}
8337
8338 \end_inset
8339
8340
8341 \series default
8342  Generally follow the C99 standard, but allow SDCC features that conflict
8343  with the standard (incomplete support).
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-c99
8360 \begin_inset LatexCommand \index{-\/-std-sdcc99}
8361
8362 \end_inset
8363
8364
8365 \series default
8366  Follow the C99 standard and disable SDCC features that conflict with the
8367  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 -codeseg
8384 \series default
8385
8386 \begin_inset LatexCommand \index{-\/-codeseg <Value>}
8387
8388 \end_inset
8389
8390 \SpecialChar ~
8391 <Name> The name to be used for the code
8392 \begin_inset LatexCommand \index{code}
8393
8394 \end_inset
8395
8396  segment, default CSEG.
8397  This is useful if you need to tell the compiler to put the code in a special
8398  segment so you can later on tell the linker to put this segment in a special
8399  place in memory.
8400  Can be used for instance when using bank switching to put the code in a
8401  bank.
8402 \layout List
8403 \labelwidthstring 00.00.0000
8404
8405
8406 \series bold
8407 -
8408 \begin_inset ERT
8409 status Collapsed
8410
8411 \layout Standard
8412
8413 \backslash
8414 /
8415 \end_inset
8416
8417 -constseg
8418 \series default
8419
8420 \begin_inset LatexCommand \index{-\/-constseg <Value>}
8421
8422 \end_inset
8423
8424 \SpecialChar ~
8425 <Name> The name to be used for the const
8426 \begin_inset LatexCommand \index{code}
8427
8428 \end_inset
8429
8430  segment, default CONST.
8431  This is useful if you need to tell the compiler to put the const data in
8432  a special segment so you can later on tell the linker to put this segment
8433  in a special place in memory.
8434  Can be used for instance when using bank switching to put the const data
8435  in a bank.
8436 \layout List
8437 \labelwidthstring 00.00.0000
8438
8439
8440 \series bold
8441 more-pedantic
8442 \series default
8443  Actually this is
8444 \series bold
8445 \emph on
8446 not
8447 \series default
8448 \emph default
8449  a SDCC compiler option but if you want
8450 \emph on
8451 more
8452 \emph default
8453  warnings you can use a separate tool dedicated to syntax checking like
8454  splint
8455 \begin_inset LatexCommand \label{lyx:more-pedantic-SPLINT}
8456
8457 \end_inset
8458
8459
8460 \begin_inset LatexCommand \index{lint (syntax checking tool)}
8461
8462 \end_inset
8463
8464
8465 \begin_inset LatexCommand \url{http://www.splint.org}
8466
8467 \end_inset
8468
8469 .
8470  To make your source files parseable by splint you will have to include
8471
8472 \family sans
8473 lint.h
8474 \family default
8475
8476 \begin_inset LatexCommand \index{splint (syntax checking tool)}
8477
8478 \end_inset
8479
8480  in your source file and add brackets around extended keywords (like
8481 \family sans
8482
8483 \begin_inset Quotes sld
8484 \end_inset
8485
8486 __at\SpecialChar ~
8487
8488 \series bold
8489 (
8490 \series default
8491 0xab
8492 \series bold
8493 )
8494 \series default
8495
8496 \begin_inset Quotes srd
8497 \end_inset
8498
8499
8500 \family default
8501  and
8502 \family sans
8503
8504 \begin_inset Quotes sld
8505 \end_inset
8506
8507 __interrupt\SpecialChar ~
8508 (2)
8509 \begin_inset Quotes srd
8510 \end_inset
8511
8512
8513 \family default
8514 ).
8515
8516 \newline
8517 Splint has an excellent on line manual at
8518 \begin_inset LatexCommand \url{http://www.splint.org/manual/}
8519
8520 \end_inset
8521
8522  and it's capabilities go beyond pure syntax checking.
8523  You'll need to tell splint the location of SDCC's include files so a typical
8524  command line could look like this:
8525 \newline
8526
8527 \family sans
8528 splint\SpecialChar ~
8529 -I\SpecialChar ~
8530 /usr/local/share/sdcc/include/mcs51/\SpecialChar ~
8531 \SpecialChar ~
8532 myprogram.c
8533 \layout Subsection
8534
8535 Intermediate Dump Options
8536 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
8537
8538 \end_inset
8539
8540
8541 \begin_inset LatexCommand \index{Options intermediate dump}
8542
8543 \end_inset
8544
8545
8546 \begin_inset LatexCommand \index{Intermediate dump options}
8547
8548 \end_inset
8549
8550
8551 \layout Standard
8552
8553 The following options are provided for the purpose of retargetting and debugging
8554  the compiler.
8555  They provide a means to dump the intermediate code (iCode
8556 \begin_inset LatexCommand \index{iCode}
8557
8558 \end_inset
8559
8560 ) generated by the compiler in human readable form at various stages of
8561  the compilation process.
8562  More on iCodes see chapter
8563 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
8564
8565 \end_inset
8566
8567
8568 \begin_inset Quotes srd
8569 \end_inset
8570
8571 The anatomy of the compiler
8572 \begin_inset Quotes srd
8573 \end_inset
8574
8575 .
8576 \layout List
8577 \labelwidthstring 00.00.0000
8578
8579
8580 \series bold
8581 -
8582 \begin_inset ERT
8583 status Collapsed
8584
8585 \layout Standard
8586
8587 \backslash
8588 /
8589 \end_inset
8590
8591 -dumpraw
8592 \begin_inset LatexCommand \index{-\/-dumpraw}
8593
8594 \end_inset
8595
8596
8597 \series default
8598  This option will cause the compiler to dump the intermediate code into
8599  a file of named
8600 \emph on
8601 <source filename>.dumpraw
8602 \emph default
8603  just after the intermediate code has been generated for a function, i.e.
8604  before any optimizations are done.
8605  The basic blocks
8606 \begin_inset LatexCommand \index{Basic blocks}
8607
8608 \end_inset
8609
8610  at this stage ordered in the depth first number, so they may not be in
8611  sequence of execution.
8612 \layout List
8613 \labelwidthstring 00.00.0000
8614
8615
8616 \series bold
8617 -
8618 \begin_inset ERT
8619 status Collapsed
8620
8621 \layout Standard
8622
8623 \backslash
8624 /
8625 \end_inset
8626
8627 -dumpgcse
8628 \begin_inset LatexCommand \index{-\/-dumpgcse}
8629
8630 \end_inset
8631
8632
8633 \series default
8634  Will create a dump of iCode's, after global subexpression elimination
8635 \begin_inset LatexCommand \index{Global subexpression elimination}
8636
8637 \end_inset
8638
8639 , into a file named
8640 \emph on
8641 <source filename>.dumpgcse.
8642 \layout List
8643 \labelwidthstring 00.00.0000
8644
8645
8646 \series bold
8647 -
8648 \begin_inset ERT
8649 status Collapsed
8650
8651 \layout Standard
8652
8653 \backslash
8654 /
8655 \end_inset
8656
8657 -dumpdeadcode
8658 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
8659
8660 \end_inset
8661
8662
8663 \series default
8664  Will create a dump of iCode's, after deadcode elimination
8665 \begin_inset LatexCommand \index{Dead-code elimination}
8666
8667 \end_inset
8668
8669 , into a file named
8670 \emph on
8671 <source filename>.dumpdeadcode.
8672 \layout List
8673 \labelwidthstring 00.00.0000
8674
8675
8676 \series bold
8677 -
8678 \begin_inset ERT
8679 status Collapsed
8680
8681 \layout Standard
8682
8683 \backslash
8684 /
8685 \end_inset
8686
8687 -dumploop
8688 \begin_inset LatexCommand \index{-\/-dumploop}
8689
8690 \end_inset
8691
8692
8693 \series default
8694 \size large
8695
8696 \size default
8697 Will create a dump of iCode's, after loop optimizations
8698 \begin_inset LatexCommand \index{Loop optimization}
8699
8700 \end_inset
8701
8702 , into a file named
8703 \emph on
8704 <source filename>.dumploop.
8705 \layout List
8706 \labelwidthstring 00.00.0000
8707
8708
8709 \series bold
8710 -
8711 \begin_inset ERT
8712 status Collapsed
8713
8714 \layout Standard
8715
8716 \backslash
8717 /
8718 \end_inset
8719
8720 -dumprange
8721 \begin_inset LatexCommand \index{-\/-dumprange}
8722
8723 \end_inset
8724
8725
8726 \series default
8727 \size large
8728
8729 \size default
8730 Will create a dump of iCode's, after live range analysis
8731 \begin_inset LatexCommand \index{Live range analysis}
8732
8733 \end_inset
8734
8735 , into a file named
8736 \emph on
8737 <source filename>.dumprange.
8738 \layout List
8739 \labelwidthstring 00.00.0000
8740
8741
8742 \series bold
8743 -
8744 \begin_inset ERT
8745 status Collapsed
8746
8747 \layout Standard
8748
8749 \backslash
8750 /
8751 \end_inset
8752
8753 -dumlrange
8754 \begin_inset LatexCommand \index{-\/-dumlrange}
8755
8756 \end_inset
8757
8758
8759 \series default
8760  Will dump the life ranges
8761 \begin_inset LatexCommand \index{Live range analysis}
8762
8763 \end_inset
8764
8765  for all symbols.
8766 \layout List
8767 \labelwidthstring 00.00.0000
8768
8769
8770 \series bold
8771 -
8772 \begin_inset ERT
8773 status Collapsed
8774
8775 \layout Standard
8776
8777 \backslash
8778 /
8779 \end_inset
8780
8781 -dumpregassign
8782 \begin_inset LatexCommand \index{-\/-dumpregassign}
8783
8784 \end_inset
8785
8786
8787 \bar under
8788
8789 \series default
8790 \bar default
8791 Will create a dump of iCode's, after register assignment
8792 \begin_inset LatexCommand \index{Register assignment}
8793
8794 \end_inset
8795
8796 , into a file named
8797 \emph on
8798 <source filename>.dumprassgn.
8799 \layout List
8800 \labelwidthstring 00.00.0000
8801
8802
8803 \series bold
8804 -
8805 \begin_inset ERT
8806 status Collapsed
8807
8808 \layout Standard
8809
8810 \backslash
8811 /
8812 \end_inset
8813
8814 -dumplrange
8815 \begin_inset LatexCommand \index{-\/-dumplrange}
8816
8817 \end_inset
8818
8819
8820 \series default
8821  Will create a dump of the live ranges of iTemp's
8822 \layout List
8823 \labelwidthstring 00.00.0000
8824
8825
8826 \series bold
8827 -
8828 \begin_inset ERT
8829 status Collapsed
8830
8831 \layout Standard
8832
8833 \backslash
8834 /
8835 \end_inset
8836
8837 -dumpall
8838 \begin_inset LatexCommand \index{-\/-dumpall}
8839
8840 \end_inset
8841
8842
8843 \size large
8844 \bar under
8845
8846 \series default
8847 \size default
8848 \bar default
8849 Will cause all the above mentioned dumps to be created.
8850 \layout Subsection
8851
8852 Redirecting output on Windows Shells
8853 \layout Standard
8854
8855 By default SDCC writes it's error messages to
8856 \begin_inset Quotes sld
8857 \end_inset
8858
8859 standard error
8860 \begin_inset Quotes srd
8861 \end_inset
8862
8863 .
8864  To force all messages to
8865 \begin_inset Quotes sld
8866 \end_inset
8867
8868 standard output
8869 \begin_inset Quotes srd
8870 \end_inset
8871
8872  use
8873 \series bold
8874 -
8875 \series default
8876 \emph on
8877
8878 \begin_inset ERT
8879 status Collapsed
8880
8881 \layout Standard
8882
8883 \backslash
8884 /
8885 \end_inset
8886
8887
8888 \series bold
8889 \emph default
8890 -
8891 \series default
8892 use-stdout
8893 \begin_inset LatexCommand \index{-\/-use-stdout}
8894
8895 \end_inset
8896
8897 .
8898  Additionally, if you happen to have visual studio installed in your windows
8899  machine, you can use it to compile your sources using a custom build and
8900  the SDCC -
8901 \emph on
8902
8903 \begin_inset ERT
8904 status Collapsed
8905
8906 \layout Standard
8907
8908 \backslash
8909 /
8910 \end_inset
8911
8912
8913 \emph default
8914 -vc
8915 \begin_inset LatexCommand \index{-\/-vc}
8916
8917 \end_inset
8918
8919  option.
8920  Something like this should work:
8921 \newline
8922
8923 \newline
8924
8925 \series bold
8926 c:
8927 \backslash
8928 sdcc
8929 \backslash
8930 bin
8931 \backslash
8932 sdcc.exe -
8933 \series default
8934 \emph on
8935
8936 \begin_inset ERT
8937 status Collapsed
8938
8939 \layout Standard
8940
8941 \backslash
8942 /
8943 \end_inset
8944
8945
8946 \series bold
8947 \emph default
8948 -vc -
8949 \series default
8950 \emph on
8951
8952 \begin_inset ERT
8953 status Collapsed
8954
8955 \layout Standard
8956
8957 \backslash
8958 /
8959 \end_inset
8960
8961
8962 \series bold
8963 \emph default
8964 -model-large -c $(InputPath)
8965 \layout Section
8966
8967 Environment variables
8968 \begin_inset LatexCommand \index{Environment variables}
8969
8970 \end_inset
8971
8972
8973 \layout Standard
8974
8975 SDCC recognizes the following environment variables:
8976 \layout List
8977 \labelwidthstring 00.00.0000
8978
8979
8980 \series bold
8981 SDCC_LEAVE_SIGNALS
8982 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
8983
8984 \end_inset
8985
8986
8987 \series default
8988  SDCC installs a signal handler
8989 \begin_inset LatexCommand \index{signal handler}
8990
8991 \end_inset
8992
8993  to be able to delete temporary files after an user break (^C) or an exception.
8994  If this environment variable is set, SDCC won't install the signal handler
8995  in order to be able to debug SDCC.
8996 \layout List
8997 \labelwidthstring 00.00.0000
8998
8999
9000 \series bold
9001 TMP,\SpecialChar ~
9002 TEMP,\SpecialChar ~
9003 TMPDIR
9004 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
9005
9006 \end_inset
9007
9008
9009 \series default
9010  Path, where temporary files will be created.
9011  The order of the variables is the search order.
9012  In a standard *nix environment these variables are not set, and there's
9013  no need to set them.
9014  On Windows it's recommended to set one of them.
9015 \layout List
9016 \labelwidthstring 00.00.0000
9017
9018
9019 \series bold
9020 SDCC_HOME
9021 \begin_inset LatexCommand \index{SDCC\_HOME}
9022
9023 \end_inset
9024
9025
9026 \series default
9027  Path, see section
9028 \begin_inset LatexCommand \ref{sub:Install-paths}
9029
9030 \end_inset
9031
9032 \SpecialChar ~
9033
9034 \begin_inset Quotes sld
9035 \end_inset
9036
9037  Install Paths
9038 \begin_inset Quotes srd
9039 \end_inset
9040
9041 .
9042 \layout List
9043 \labelwidthstring 00.00.0000
9044
9045
9046 \series bold
9047 SDCC_INCLUDE
9048 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
9049
9050 \end_inset
9051
9052
9053 \series default
9054  Path, see section
9055 \begin_inset LatexCommand \ref{sub:Search-Paths}
9056
9057 \end_inset
9058
9059 \SpecialChar ~
9060
9061 \begin_inset Quotes sld
9062 \end_inset
9063
9064 Search Paths
9065 \begin_inset Quotes srd
9066 \end_inset
9067
9068 .
9069 \layout List
9070 \labelwidthstring 00.00.0000
9071
9072
9073 \series bold
9074 SDCC_LIB
9075 \begin_inset LatexCommand \index{SDCC\_LIB}
9076
9077 \end_inset
9078
9079
9080 \series default
9081  Path, see section
9082 \begin_inset LatexCommand \ref{sub:Search-Paths}
9083
9084 \end_inset
9085
9086 \SpecialChar ~
9087
9088 \begin_inset Quotes sld
9089 \end_inset
9090
9091 Search Paths
9092 \begin_inset Quotes srd
9093 \end_inset
9094
9095 ..
9096 \layout Standard
9097
9098 There are some more environment variables recognized by SDCC, but these
9099  are solely used for debugging purposes.
9100  They can change or disappear very quickly, and will never be documented.
9101 \layout Section
9102
9103 Storage Class Language Extensions
9104 \layout Subsection
9105
9106 MCS51/DS390 Storage Class
9107 \begin_inset LatexCommand \index{Storage class}
9108
9109 \end_inset
9110
9111  Language Extensions
9112 \layout Standard
9113
9114 In addition to the ANSI storage classes SDCC allows the following MCS51
9115  specific storage classes:
9116 \layout Subsubsection
9117
9118 data
9119 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
9120
9121 \end_inset
9122
9123
9124 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
9125
9126 \end_inset
9127
9128  / near
9129 \begin_inset LatexCommand \index{near (storage class)}
9130
9131 \end_inset
9132
9133
9134 \begin_inset LatexCommand \index{\_\_near (storage class)}
9135
9136 \end_inset
9137
9138
9139 \layout Standard
9140
9141 This is the
9142 \series bold
9143 default
9144 \series default
9145  storage class for the Small Memory model (
9146 \emph on
9147 data
9148 \emph default
9149  and
9150 \emph on
9151 near
9152 \emph default
9153  or the more ANSI-C compliant forms
9154 \emph on
9155 __data
9156 \emph default
9157  and
9158 \emph on
9159 __near
9160 \emph default
9161  can be used synonymously).
9162  Variables declared with this storage class will be allocated in the directly
9163  addressable portion of the internal RAM of a 8051, e.g.:
9164 \layout Verse
9165
9166
9167 \family typewriter
9168 __data unsigned char test_data;
9169 \layout Standard
9170
9171 Writing 0x01 to this variable generates the assembly code:
9172 \layout Verse
9173
9174
9175 \family typewriter
9176 75*00 01\SpecialChar ~
9177 \SpecialChar ~
9178 \SpecialChar ~
9179 mov\SpecialChar ~
9180 \SpecialChar ~
9181 _test_data,#0x01
9182 \layout Subsubsection
9183
9184 xdata
9185 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9186
9187 \end_inset
9188
9189
9190 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9191
9192 \end_inset
9193
9194  / far
9195 \begin_inset LatexCommand \index{far (storage class)}
9196
9197 \end_inset
9198
9199
9200 \begin_inset LatexCommand \index{\_\_far (storage class)}
9201
9202 \end_inset
9203
9204
9205 \layout Standard
9206
9207 Variables declared with this storage class will be placed in the external
9208  RAM.
9209  This is the
9210 \series bold
9211 default
9212 \series default
9213  storage class for the Large Memory model, e.g.:
9214 \layout Verse
9215
9216
9217 \family typewriter
9218 __xdata unsigned char test_xdata;
9219 \layout Standard
9220
9221 Writing 0x01 to this variable generates the assembly code:
9222 \layout Verse
9223
9224
9225 \family typewriter
9226 90s00r00\SpecialChar ~
9227 \SpecialChar ~
9228 \SpecialChar ~
9229 mov\SpecialChar ~
9230 \SpecialChar ~
9231 dptr,#_test_xdata
9232 \newline
9233 74\SpecialChar ~
9234 01\SpecialChar ~
9235 \SpecialChar ~
9236 \SpecialChar ~
9237 \SpecialChar ~
9238 \SpecialChar ~
9239 \SpecialChar ~
9240 mov\SpecialChar ~
9241 \SpecialChar ~
9242 a,#0x01
9243 \newline
9244 F0\SpecialChar ~
9245 \SpecialChar ~
9246 \SpecialChar ~
9247 \SpecialChar ~
9248 \SpecialChar ~
9249 \SpecialChar ~
9250 \SpecialChar ~
9251 \SpecialChar ~
9252 \SpecialChar ~
9253 movx\SpecialChar ~
9254 @dptr,a
9255 \layout Subsubsection
9256
9257 idata
9258 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
9259
9260 \end_inset
9261
9262
9263 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
9264
9265 \end_inset
9266
9267
9268 \layout Standard
9269
9270 Variables declared with this storage class will be allocated into the indirectly
9271  addressable portion of the internal ram of a 8051, e.g.:
9272 \layout Verse
9273
9274
9275 \family typewriter
9276 __idata unsigned char test_idata;
9277 \layout Standard
9278
9279 Writing 0x01 to this variable generates the assembly code:
9280 \layout Verse
9281
9282
9283 \family typewriter
9284 78r00\SpecialChar ~
9285 \SpecialChar ~
9286 \SpecialChar ~
9287 \SpecialChar ~
9288 \SpecialChar ~
9289 \SpecialChar ~
9290 \SpecialChar ~
9291 mov\SpecialChar ~
9292 \SpecialChar ~
9293 r0,#_test_idata
9294 \newline
9295 76\SpecialChar ~
9296 01\SpecialChar ~
9297 \SpecialChar ~
9298 \SpecialChar ~
9299 \SpecialChar ~
9300 \SpecialChar ~
9301 \SpecialChar ~
9302 \SpecialChar ~
9303 mov\SpecialChar ~
9304 \SpecialChar ~
9305 @r0,#0x01
9306 \layout Standard
9307
9308 Please note, the first 128 byte of idata physically access the same RAM
9309  as the data memory.
9310  The original 8051 had 128 byte idata memory, nowadays most devices have
9311  256 byte idata memory.
9312  The stack
9313 \begin_inset LatexCommand \index{stack}
9314
9315 \end_inset
9316
9317  is located in idata memory.
9318 \layout Subsubsection
9319
9320 pdata
9321 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
9322
9323 \end_inset
9324
9325
9326 \begin_inset LatexCommand \index{\_\_pdata (mcs51, ds390 storage class)}
9327
9328 \end_inset
9329
9330
9331 \layout Standard
9332
9333 Paged xdata access is just as straightforward as using the other addressing
9334  modes of a 8051.
9335  It is typically located at the start of xdata and has a maximum size of
9336  256 bytes.
9337  The following example writes 0x01 to the pdata variable.
9338  Please note, pdata access physically accesses xdata memory.
9339  The high byte of the address is determined by port P2
9340 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
9341
9342 \end_inset
9343
9344 (or in case of some 8051 variants by a separate Special Function Register,
9345  see section
9346 \begin_inset LatexCommand \ref{sub:MCS51-variants}
9347
9348 \end_inset
9349
9350 ).
9351  This is the
9352 \series bold
9353 default
9354 \series default
9355  storage class for the Medium Memory model, e.g.:
9356 \layout Verse
9357
9358
9359 \family typewriter
9360 __pdata unsigned char test_pdata;
9361 \layout Standard
9362
9363 Writing 0x01 to this variable generates the assembly code:
9364 \layout Verse
9365
9366
9367 \family typewriter
9368 78r00\SpecialChar ~
9369 \SpecialChar ~
9370 \SpecialChar ~
9371 \SpecialChar ~
9372 \SpecialChar ~
9373 \SpecialChar ~
9374 mov r0,#_test_pdata
9375 \newline
9376 74 01\SpecialChar ~
9377 \SpecialChar ~
9378 \SpecialChar ~
9379 \SpecialChar ~
9380 \SpecialChar ~
9381 \SpecialChar ~
9382 mov a,#0x01
9383 \newline
9384 F2\SpecialChar ~
9385 \SpecialChar ~
9386 \SpecialChar ~
9387 \SpecialChar ~
9388 \SpecialChar ~
9389 \SpecialChar ~
9390 \SpecialChar ~
9391 \SpecialChar ~
9392 \SpecialChar ~
9393 movx @r0,a
9394 \layout Standard
9395
9396 If the -
9397 \begin_inset ERT
9398 status Collapsed
9399
9400 \layout Standard
9401
9402 \backslash
9403 /
9404 \end_inset
9405
9406 -xstack
9407 \begin_inset LatexCommand \index{-\/-xstack}
9408
9409 \end_inset
9410
9411  option is used the pdata memory area is followed by the xstack memory area
9412  and the sum of their sizes is limited to 256 bytes.
9413 \layout Subsubsection
9414
9415 code
9416 \begin_inset LatexCommand \index{code}
9417
9418 \end_inset
9419
9420
9421 \begin_inset LatexCommand \index{\_\_code}
9422
9423 \end_inset
9424
9425
9426 \layout Standard
9427
9428 'Variables' declared with this storage class will be placed in the code
9429  memory:
9430 \layout Verse
9431
9432
9433 \family typewriter
9434 __code unsigned char test_code;
9435 \layout Standard
9436
9437 Read access to this variable generates the assembly code:
9438 \layout Verse
9439
9440
9441 \family typewriter
9442 90s00r6F\SpecialChar ~
9443 \SpecialChar ~
9444 \SpecialChar ~
9445 mov dptr,#_test_code
9446 \newline
9447 E4\SpecialChar ~
9448 \SpecialChar ~
9449 \SpecialChar ~
9450 \SpecialChar ~
9451 \SpecialChar ~
9452 \SpecialChar ~
9453 \SpecialChar ~
9454 \SpecialChar ~
9455 \SpecialChar ~
9456 clr a
9457 \newline
9458 93\SpecialChar ~
9459 \SpecialChar ~
9460 \SpecialChar ~
9461 \SpecialChar ~
9462 \SpecialChar ~
9463 \SpecialChar ~
9464 \SpecialChar ~
9465 \SpecialChar ~
9466 \SpecialChar ~
9467 movc a,@a+dptr
9468 \layout Standard
9469
9470
9471 \family typewriter
9472 char
9473 \family default
9474  indexed arrays of characters in code memory can be accessed efficiently:
9475 \layout Verse
9476
9477
9478 \family typewriter
9479 __code char test_array[] = {'c','h','e','a','p'};
9480 \layout Standard
9481
9482 Read access to this array using an 8-bit unsigned index generates the assembly
9483  code:
9484 \layout Verse
9485
9486
9487 \family typewriter
9488 E5*00\SpecialChar ~
9489 \SpecialChar ~
9490 \SpecialChar ~
9491 \SpecialChar ~
9492 \SpecialChar ~
9493 \SpecialChar ~
9494 mov a,_index
9495 \layout Verse
9496
9497
9498 \family typewriter
9499 90s00r41\SpecialChar ~
9500 \SpecialChar ~
9501 \SpecialChar ~
9502 mov dptr,#_test_array
9503 \layout Verse
9504
9505
9506 \family typewriter
9507 93\SpecialChar ~
9508 \SpecialChar ~
9509 \SpecialChar ~
9510 \SpecialChar ~
9511 \SpecialChar ~
9512 \SpecialChar ~
9513 \SpecialChar ~
9514 \SpecialChar ~
9515 \SpecialChar ~
9516 movc a,@a+dptr
9517 \layout Subsubsection
9518
9519 bit
9520 \begin_inset LatexCommand \index{bit}
9521
9522 \end_inset
9523
9524
9525 \begin_inset LatexCommand \index{\_\_bit}
9526
9527 \end_inset
9528
9529
9530 \layout Standard
9531
9532 This is a data-type and a storage class specifier.
9533  When a variable is declared as a bit, it is allocated into the bit addressable
9534  memory of 8051, e.g.:
9535 \layout Verse
9536
9537
9538 \family typewriter
9539 __bit test_bit;
9540 \layout Standard
9541
9542 Writing 1 to this variable generates the assembly code:
9543 \layout Verse
9544
9545
9546 \family typewriter
9547 D2*00\SpecialChar ~
9548 \SpecialChar ~
9549 \SpecialChar ~
9550 \SpecialChar ~
9551 \SpecialChar ~
9552 \SpecialChar ~
9553 \SpecialChar ~
9554 setb\SpecialChar ~
9555 _test_bit
9556 \layout Standard
9557
9558 The bit addressable memory consists of 128 bits which are located from 0x20
9559  to 0x2f in data memory.
9560
9561 \newline
9562 Apart from this 8051 specific storage class most architectures support ANSI-C
9563  bitfields
9564 \begin_inset LatexCommand \index{bitfields}
9565
9566 \end_inset
9567
9568
9569 \begin_inset Foot
9570 collapsed false
9571
9572 \layout Standard
9573
9574 Not really meant as examples, but nevertheless showing what bitfields are
9575  about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
9576 \end_inset
9577
9578 .
9579  In accordance with ISO/IEC 9899 bits and bitfields without an explicit
9580  signed modifier are implemented as unsigned.
9581 \layout Subsubsection
9582
9583 sfr
9584 \begin_inset LatexCommand \index{sfr}
9585
9586 \end_inset
9587
9588
9589 \begin_inset LatexCommand \index{\_\_sfr}
9590
9591 \end_inset
9592
9593  / sfr16
9594 \begin_inset LatexCommand \index{sfr16}
9595
9596 \end_inset
9597
9598
9599 \begin_inset LatexCommand \index{\_\_sfr16}
9600
9601 \end_inset
9602
9603  / sfr32
9604 \begin_inset LatexCommand \index{sfr32}
9605
9606 \end_inset
9607
9608
9609 \begin_inset LatexCommand \index{\_\_sfr32}
9610
9611 \end_inset
9612
9613  / sbit
9614 \begin_inset LatexCommand \index{\_\_sbit}
9615
9616 \end_inset
9617
9618
9619 \layout Standard
9620
9621 Like the bit keyword,
9622 \emph on
9623 sfr / sfr16 / sfr32 / sbit
9624 \emph default
9625 signify both a data-type and storage class, they are used to describe the
9626
9627 \emph on
9628 s
9629 \emph default
9630 pecial
9631 \emph on
9632 f
9633 \emph default
9634 unction
9635 \emph on
9636 r
9637 \emph default
9638 egisters and
9639 \emph on
9640 s
9641 \emph default
9642 pecial
9643 \emph on
9644 bit
9645 \emph default
9646  variables of a 8051, eg:
9647 \layout Verse
9648
9649
9650 \family typewriter
9651 __sfr __at
9652 \begin_inset LatexCommand \index{at}
9653
9654 \end_inset
9655
9656
9657 \begin_inset LatexCommand \index{\_\_at}
9658
9659 \end_inset
9660
9661  (0x80) P0;\SpecialChar ~
9662  /* special function register P0 at location 0x80 */
9663 \newline
9664 /* 16 bit special function register combination for timer 0 */
9665 \newline
9666 /* with the high byte at location 0x8C and the low byte at location 0x8A
9667  */
9668 \newline
9669 __sfr16 __at
9670 \begin_inset LatexCommand \index{at}
9671
9672 \end_inset
9673
9674
9675 \begin_inset LatexCommand \index{\_\_at}
9676
9677 \end_inset
9678
9679  (0x8C8A) TMR0;
9680 \newline
9681 __sbit __at (0xd7) CY; /* CY (Carry Flag
9682 \begin_inset LatexCommand \index{Flags}
9683
9684 \end_inset
9685
9686
9687 \begin_inset LatexCommand \index{Carry flag}
9688
9689 \end_inset
9690
9691 ) */
9692 \layout Standard
9693
9694 Special function registers which are located on an address dividable by
9695  8 are bit-addressable, an
9696 \emph on
9697  sbit
9698 \emph default
9699  addresses a specific bit within these sfr.
9700 \newline
9701 16 Bit and 32 bit special function register combinations which require a
9702  certain access order are better not declared using
9703 \emph on
9704 sfr16
9705 \emph default
9706  or
9707 \emph on
9708 sfr32.
9709
9710 \emph default
9711  Allthough SDCC usually accesses them Least Significant Byte (LSB) first,
9712  this is not guaranteed.
9713 \layout Subsubsection
9714
9715 Pointers
9716 \begin_inset LatexCommand \index{Pointer}
9717
9718 \end_inset
9719
9720  to MCS51/DS390 specific memory spaces
9721 \layout Standard
9722
9723 SDCC allows (via language extensions) pointers to explicitly point to any
9724  of the memory spaces
9725 \begin_inset LatexCommand \index{Memory model}
9726
9727 \end_inset
9728
9729  of the 8051.
9730  In addition to the explicit pointers, the compiler uses (by default) generic
9731  pointers which can be used to point to any of the memory spaces.
9732 \newline
9733
9734 \newline
9735 Pointer declaration examples:
9736 \layout Verse
9737
9738
9739 \family typewriter
9740 /* pointer physically in internal ram pointing to object in external ram
9741  */
9742 \newline
9743 __xdata unsigned char * __data p;
9744 \newline
9745
9746 \newline
9747 /* pointer physically in external ram pointing to object in internal ram
9748  */
9749 \newline
9750 __data unsigned char * __xdata p;
9751 \newline
9752
9753 \newline
9754 /* pointer physically in code rom pointing to data in xdata space */
9755 \newline
9756 __xdata unsigned char * __code p;
9757 \newline
9758
9759 \newline
9760 /* pointer physically in code space pointing to data in code space */
9761 \newline
9762 __code unsigned char * __code p;
9763 \newline
9764
9765 \newline
9766 /* the following is a generic pointer physically located in xdata space
9767  */
9768 \newline
9769 char * __xdata p;
9770 \newline
9771
9772 \newline
9773 /* the following is a function pointer physically located in data space
9774  */
9775 \newline
9776 char (* __data fp)(void);
9777 \layout Standard
9778
9779 Well you get the idea.
9780
9781 \newline
9782
9783 \newline
9784 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
9785 \emph on
9786 generic
9787 \emph default
9788  pointers.
9789
9790 \size small
9791
9792 \newline
9793
9794 \newline
9795
9796 \size default
9797 The highest order byte of the
9798 \emph on
9799 generic
9800 \emph default
9801  pointers contains the data space information.
9802  Assembler support routines are called whenever data is stored or retrieved
9803  using
9804 \emph on
9805 generic
9806 \emph default
9807  pointers.
9808  These are useful for developing reusable library
9809 \begin_inset LatexCommand \index{Libraries}
9810
9811 \end_inset
9812
9813  routines.
9814  Explicitly specifying the pointer type will generate the most efficient
9815  code.
9816 \layout Subsubsection
9817
9818 Notes on MCS51 memory
9819 \begin_inset LatexCommand \index{MCS51 memory}
9820
9821 \end_inset
9822
9823  layout
9824 \layout Standard
9825
9826 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
9827  RAM memory which is structured as follows:
9828 \newline
9829
9830 \newline
9831 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
9832
9833 \newline
9834 - Bytes 20-2F - 16 bytes to hold 128 bit
9835 \begin_inset LatexCommand \index{bit}
9836
9837 \end_inset
9838
9839  variables and,
9840 \newline
9841 - Bytes 30-7F - 80 bytes for general purpose use.
9842 \newline
9843
9844 \layout Standard
9845
9846 Additionally some members of the MCS51 family may have up to 128 bytes of
9847  additional, indirectly addressable, internal RAM memory (
9848 \emph on
9849 idata
9850 \emph default
9851
9852 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
9853
9854 \end_inset
9855
9856
9857 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
9858
9859 \end_inset
9860
9861 ).
9862  Furthermore, some chips may have some built in external memory (
9863 \emph on
9864 xdata
9865 \emph default
9866
9867 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9868
9869 \end_inset
9870
9871
9872 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9873
9874 \end_inset
9875
9876 ) which should not be confused with the internal, directly addressable RAM
9877  memory (
9878 \emph on
9879 data
9880 \emph default
9881
9882 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
9883
9884 \end_inset
9885
9886
9887 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
9888
9889 \end_inset
9890
9891 ).
9892  Sometimes this built in
9893 \emph on
9894 xdata
9895 \emph default
9896  memory has to be activated before using it (you can probably find this
9897  information on the datasheet of the microcontroller your are using, see
9898  also section
9899 \begin_inset LatexCommand \ref{sub:Startup-Code}
9900
9901 \end_inset
9902
9903 \SpecialChar ~
9904 Startup-Code).
9905 \layout Standard
9906
9907 Normally SDCC will only use the first bank
9908 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
9909
9910 \end_inset
9911
9912  of registers (register bank 0), but it is possible to specify that other
9913  banks of registers (keyword
9914 \emph on
9915 using
9916 \emph default
9917
9918 \emph on
9919
9920 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
9921
9922 \end_inset
9923
9924
9925 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
9926
9927 \end_inset
9928
9929
9930 \emph default
9931 ) should be used in interrupt
9932 \begin_inset LatexCommand \index{interrupt}
9933
9934 \end_inset
9935
9936
9937 \begin_inset LatexCommand \index{\_\_interrupt}
9938
9939 \end_inset
9940
9941  routines.
9942  By default, the compiler will place the stack after the last byte of allocated
9943  memory for variables.
9944  For example, if the first 2 banks of registers are used, and only four
9945  bytes are used for
9946 \emph on
9947 data
9948 \emph default
9949  variables, it will position the base of the internal stack at address 20
9950  (0x14).
9951  This implies that as the stack
9952 \begin_inset LatexCommand \index{stack}
9953
9954 \end_inset
9955
9956  grows, it will use up the remaining register banks, and the 16 bytes used
9957  by the 128 bit variables, and 80 bytes for general purpose use.
9958  If any bit variables are used, the data variables will be placed in unused
9959  register banks and after the byte holding the last bit variable.
9960  For example, if register banks 0 and 1 are used, and there are 9 bit variables
9961  (two bytes used),
9962 \emph on
9963 data
9964 \emph default
9965  variables will be placed starting from address 0x10 to 0x20 and continue
9966  at address 0x22.
9967  You can also use -
9968 \begin_inset ERT
9969 status Collapsed
9970
9971 \layout Standard
9972
9973 \backslash
9974 /
9975 \end_inset
9976
9977 -data-loc
9978 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
9979
9980 \end_inset
9981
9982  to specify the start address of the
9983 \emph on
9984 data
9985 \emph default
9986  and -
9987 \begin_inset ERT
9988 status Collapsed
9989
9990 \layout Standard
9991
9992 \backslash
9993 /
9994 \end_inset
9995
9996 -iram-size
9997 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
9998
9999 \end_inset
10000
10001  to specify the size of the total internal RAM (
10002 \emph on
10003 data
10004 \emph default
10005 +
10006 \emph on
10007 idata
10008 \emph default
10009 ).
10010
10011 \newline
10012
10013 \layout Standard
10014
10015 By default the 8051 linker will place the stack after the last byte of (i)data
10016  variables.
10017  Option -
10018 \begin_inset ERT
10019 status Collapsed
10020
10021 \layout Standard
10022
10023 \backslash
10024 /
10025 \end_inset
10026
10027 -stack-loc
10028 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
10029
10030 \end_inset
10031
10032  allows you to specify the start of the stack, i.e.
10033  you could start it after any data in the general purpose area.
10034  If your microcontroller has additional indirectly addressable internal
10035  RAM (
10036 \emph on
10037 idata
10038 \emph default
10039 ) you can place the stack on it.
10040  You may also need to use -
10041 \begin_inset ERT
10042 status Collapsed
10043
10044 \layout Standard
10045
10046 \backslash
10047 /
10048 \end_inset
10049
10050 -xdata-loc
10051 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
10052
10053 \end_inset
10054
10055  to set the start address of the external RAM (
10056 \emph on
10057 xdata
10058 \emph default
10059 ) and -
10060 \begin_inset ERT
10061 status Collapsed
10062
10063 \layout Standard
10064
10065 \backslash
10066 /
10067 \end_inset
10068
10069 -xram-size
10070 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
10071
10072 \end_inset
10073
10074  to specify its size.
10075  Same goes for the code memory, using -
10076 \begin_inset ERT
10077 status Collapsed
10078
10079 \layout Standard
10080
10081 \backslash
10082 /
10083 \end_inset
10084
10085 -code-loc
10086 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
10087
10088 \end_inset
10089
10090  and -
10091 \begin_inset ERT
10092 status Collapsed
10093
10094 \layout Standard
10095
10096 \backslash
10097 /
10098 \end_inset
10099
10100 -code-size
10101 \begin_inset LatexCommand \index{-\/-code-size <Value>}
10102
10103 \end_inset
10104
10105 .
10106  If in doubt, don't specify any options and see if the resulting memory
10107  layout is appropriate, then you can adjust it.
10108 \layout Standard
10109
10110 The linker generates two files with memory allocation information.
10111  The first, with extension .map
10112 \begin_inset LatexCommand \index{<file>.map}
10113
10114 \end_inset
10115
10116  shows all the variables and segments.
10117  The second with extension .mem
10118 \begin_inset LatexCommand \index{<file>.mem}
10119
10120 \end_inset
10121
10122  shows the final memory layout.
10123  The linker will complain either if memory segments overlap, there is not
10124  enough memory, or there is not enough space for stack.
10125  If you get any linking warnings and/or errors related to stack or segments
10126  allocation, take a look at either the .map or .mem files to find out what
10127  the problem is.
10128  The .mem file may even suggest a solution to the problem.
10129 \layout Subsection
10130
10131 Z80/Z180 Storage Class
10132 \begin_inset LatexCommand \index{Storage class}
10133
10134 \end_inset
10135
10136  Language Extensions
10137 \layout Subsubsection
10138
10139 sfr
10140 \begin_inset LatexCommand \index{sfr}
10141
10142 \end_inset
10143
10144
10145 \begin_inset LatexCommand \index{\_\_sfr}
10146
10147 \end_inset
10148
10149  (in/out to 8-bit addresses)
10150 \layout Standard
10151
10152 The Z80
10153 \begin_inset LatexCommand \index{Z80}
10154
10155 \end_inset
10156
10157  family has separate address spaces for memory and
10158 \emph on
10159 i
10160 \emph default
10161 nput/
10162 \emph on
10163 o
10164 \emph default
10165 utput memory.
10166  I/O memory
10167 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
10168
10169 \end_inset
10170
10171  is accessed with special instructions, e.g.:
10172 \layout Verse
10173
10174
10175 \family typewriter
10176 sfr at 0x78 IoPort;\SpecialChar ~
10177 \SpecialChar ~
10178 /* define a var in I/O space at 78h called IoPort */
10179
10180 \layout Standard
10181
10182 Writing 0x01 to this variable generates the assembly code:
10183 \layout Verse
10184
10185
10186 \family typewriter
10187 3E 01\SpecialChar ~
10188 \SpecialChar ~
10189 \SpecialChar ~
10190 \SpecialChar ~
10191 \SpecialChar ~
10192 \SpecialChar ~
10193 ld a,#0x01
10194 \newline
10195 D3 78\SpecialChar ~
10196 \SpecialChar ~
10197 \SpecialChar ~
10198 \SpecialChar ~
10199 \SpecialChar ~
10200 \SpecialChar ~
10201 out (_IoPort),a
10202 \layout Subsubsection
10203
10204 banked sfr
10205 \begin_inset LatexCommand \index{sfr}
10206
10207 \end_inset
10208
10209
10210 \begin_inset LatexCommand \index{\_\_sfr}
10211
10212 \end_inset
10213
10214  (in/out to 16-bit addresses)
10215 \layout Standard
10216
10217 The keyword
10218 \emph on
10219 banked
10220 \emph default
10221  is used to support 16 bit addresses in I/O memory e.g.:
10222 \layout Verse
10223
10224
10225 \family typewriter
10226 sfr banked at
10227 \begin_inset LatexCommand \index{at}
10228
10229 \end_inset
10230
10231
10232 \begin_inset LatexCommand \index{\_\_at}
10233
10234 \end_inset
10235
10236  0x123 IoPort;
10237 \layout Standard
10238
10239 Writing 0x01 to this variable generates the assembly code:
10240 \layout Verse
10241
10242
10243 \family typewriter
10244 01 23 01\SpecialChar ~
10245 \SpecialChar ~
10246 \SpecialChar ~
10247 ld bc,#_IoPort
10248 \newline
10249 3E 01\SpecialChar ~
10250 \SpecialChar ~
10251 \SpecialChar ~
10252 \SpecialChar ~
10253 \SpecialChar ~
10254 \SpecialChar ~
10255 ld a,#0x01
10256 \newline
10257 ED 79\SpecialChar ~
10258 \SpecialChar ~
10259 \SpecialChar ~
10260 \SpecialChar ~
10261 \SpecialChar ~
10262 \SpecialChar ~
10263 out (c),a
10264 \layout Subsubsection
10265
10266 sfr
10267 \begin_inset LatexCommand \index{sfr}
10268
10269 \end_inset
10270
10271
10272 \begin_inset LatexCommand \index{\_\_sfr}
10273
10274 \end_inset
10275
10276  (in0/out0 to 8 bit addresses on Z180
10277 \begin_inset LatexCommand \index{Z180}
10278
10279 \end_inset
10280
10281 /HD64180
10282 \begin_inset LatexCommand \index{HD64180}
10283
10284 \end_inset
10285
10286 )
10287 \layout Standard
10288
10289 The compiler option -
10290 \begin_inset ERT
10291 status Collapsed
10292
10293 \layout Standard
10294
10295 \backslash
10296 /
10297 \end_inset
10298
10299 -portmode=180 (80) and a compiler #pragma\SpecialChar ~
10300 portmode
10301 \begin_inset LatexCommand \index{\#pragma portmode}
10302
10303 \end_inset
10304
10305 =z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
10306 ns
10307 \family typewriter
10308 in0/out0
10309 \family default
10310  instead of
10311 \family typewriter
10312 in/out
10313 \family default
10314 .
10315  If you include the file z180.h this will be set automatically.
10316 \layout Subsection
10317
10318 HC08 Storage Class
10319 \begin_inset LatexCommand \index{Storage class}
10320
10321 \end_inset
10322
10323  Language Extensions
10324 \layout Subsubsection
10325
10326 data
10327 \begin_inset LatexCommand \index{data (hc08 storage class)}
10328
10329 \end_inset
10330
10331
10332 \begin_inset LatexCommand \index{\_\_data (hc08 storage class)}
10333
10334 \end_inset
10335
10336
10337 \layout Standard
10338
10339 The data storage class declares a variable that resides in the first 256
10340  bytes of memory (the direct page).
10341  The HC08 is most efficient at accessing variables (especially pointers)
10342  stored here.
10343 \layout Subsubsection
10344
10345 xdata
10346 \begin_inset LatexCommand \index{xdata (hc08 storage class)}
10347
10348 \end_inset
10349
10350
10351 \begin_inset LatexCommand \index{\_\_xdata (hc08 storage class)}
10352
10353 \end_inset
10354
10355
10356 \layout Standard
10357
10358 The xdata storage class declares a variable that can reside anywhere in
10359  memory.
10360  This is the default if no storage class is specified.
10361
10362 \layout Section
10363
10364 Absolute Addressing
10365 \begin_inset LatexCommand \index{Absolute addressing}
10366
10367 \end_inset
10368
10369
10370 \layout Standard
10371
10372 Data items can be assigned an absolute address with the
10373 \emph on
10374 at
10375 \begin_inset LatexCommand \index{at}
10376
10377 \end_inset
10378
10379
10380 \begin_inset LatexCommand \index{\_\_at}
10381
10382 \end_inset
10383
10384  <address>
10385 \emph default
10386  keyword, in addition to a storage class, e.g.:
10387 \layout Verse
10388
10389
10390 \family typewriter
10391 xdata
10392 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
10393
10394 \end_inset
10395
10396
10397 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
10398
10399 \end_inset
10400
10401  at
10402 \begin_inset LatexCommand \index{at}
10403
10404 \end_inset
10405
10406
10407 \begin_inset LatexCommand \index{\_\_at}
10408
10409 \end_inset
10410
10411  (0x7ffe) unsigned int chksum;
10412 \layout Standard
10413
10414 or
10415 \layout Verse
10416
10417
10418 \family typewriter
10419 __xdata __at (0x7ffe) unsigned int chksum;
10420 \layout Standard
10421
10422 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
10423  of the external ram.
10424  The compiler does
10425 \emph on
10426 not
10427 \emph default
10428  reserve any space for variables declared in this way
10429 \begin_inset Marginal
10430 collapsed true
10431
10432 \layout Standard
10433
10434
10435 \series bold
10436 \SpecialChar ~
10437 !
10438 \end_inset
10439
10440  (they are implemented with an equate in the assembler).
10441  Thus it is left to the programmer to make sure there are no overlaps with
10442  other variables that are declared without the absolute address.
10443  The assembler listing file (.lst
10444 \begin_inset LatexCommand \index{<file>.lst}
10445
10446 \end_inset
10447
10448 ) and the linker output files (.rst
10449 \begin_inset LatexCommand \index{<file>.rst}
10450
10451 \end_inset
10452
10453 ) and (.map
10454 \begin_inset LatexCommand \index{<file>.map}
10455
10456 \end_inset
10457
10458 ) are good places to look for such overlaps.
10459  Variables with an absolute address are
10460 \emph on
10461 not
10462 \begin_inset Marginal
10463 collapsed true
10464
10465 \layout Standard
10466
10467
10468 \series bold
10469 \SpecialChar ~
10470 !
10471 \end_inset
10472
10473
10474 \emph default
10475  initialized
10476 \begin_inset LatexCommand \index{Variable initialization}
10477
10478 \end_inset
10479
10480 .
10481 \layout Standard
10482
10483 In case of memory mapped I/O devices the keyword
10484 \emph on
10485 volatile
10486 \emph default
10487  has to be used to tell the compiler that accesses might not be removed:
10488 \layout Verse
10489
10490
10491 \family typewriter
10492 volatile
10493 \begin_inset LatexCommand \index{volatile}
10494
10495 \end_inset
10496
10497  __xdata
10498 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
10499
10500 \end_inset
10501
10502  __at
10503 \begin_inset LatexCommand \index{at}
10504
10505 \end_inset
10506
10507  (0x8000) unsigned char PORTA_8255;
10508 \layout Standard
10509
10510 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
10511 r) array
10512 \family typewriter
10513 \size footnotesize
10514
10515 \begin_inset LatexCommand \index{Aligned array}
10516
10517 \end_inset
10518
10519
10520 \family default
10521 \size default
10522  starts at a block (256 byte) boundary
10523 \begin_inset LatexCommand \index{block boundary}
10524
10525 \end_inset
10526
10527  (section
10528 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
10529
10530 \end_inset
10531
10532  has an example).
10533 \newline
10534 Absolute addresses can be specified for variables in all storage classes,
10535  e.g.:
10536 \layout Verse
10537
10538
10539 \family typewriter
10540 __bit
10541 \begin_inset LatexCommand \index{bit}
10542
10543 \end_inset
10544
10545  __at
10546 \begin_inset LatexCommand \index{at}
10547
10548 \end_inset
10549
10550  (0x02) bvar;
10551 \layout Standard
10552
10553 The above example will allocate the variable at offset 0x02 in the bit-addressab
10554 le space.
10555  There is no real advantage to assigning absolute addresses to variables
10556  in this manner, unless you want strict control over all the variables allocated.
10557  One possible use would be to write hardware portable code.
10558  For example, if you have a routine that uses one or more of the microcontroller
10559  I/O pins, and such pins are different for two different hardwares, you
10560  can declare the I/O pins in your routine using:
10561 \layout Verse
10562
10563
10564 \family typewriter
10565 extern volatile
10566 \begin_inset LatexCommand \index{volatile}
10567
10568 \end_inset
10569
10570  __bit MOSI;\SpecialChar ~
10571 \SpecialChar ~
10572 \SpecialChar ~
10573 \SpecialChar ~
10574 /* master out, slave in */
10575 \newline
10576 extern volatile __bit MISO;\SpecialChar ~
10577 \SpecialChar ~
10578 \SpecialChar ~
10579 \SpecialChar ~
10580 /* master in, slave out */
10581 \newline
10582 extern volatile __bit MCLK;\SpecialChar ~
10583 \SpecialChar ~
10584 \SpecialChar ~
10585 \SpecialChar ~
10586 /* master clock */
10587 \newline
10588
10589 \newline
10590 /* Input and Output of a byte on a 3-wire serial bus.
10591 \newline
10592 \SpecialChar ~
10593 \SpecialChar ~
10594 \SpecialChar ~
10595 If needed adapt polarity of clock, polarity of data and bit order
10596 \newline
10597 \SpecialChar ~
10598 */
10599 \newline
10600 unsigned char spi_io(unsigned char out_byte)
10601 \newline
10602 {
10603 \newline
10604 \SpecialChar ~
10605 \SpecialChar ~
10606 \SpecialChar ~
10607 \SpecialChar ~
10608 unsigned char i=8;
10609 \newline
10610 \SpecialChar ~
10611 \SpecialChar ~
10612 \SpecialChar ~
10613 \SpecialChar ~
10614 do {
10615 \newline
10616 \SpecialChar ~
10617 \SpecialChar ~
10618 \SpecialChar ~
10619 \SpecialChar ~
10620 \SpecialChar ~
10621 \SpecialChar ~
10622 \SpecialChar ~
10623 \SpecialChar ~
10624 MOSI = out_byte & 0x80;
10625 \newline
10626 \SpecialChar ~
10627 \SpecialChar ~
10628 \SpecialChar ~
10629 \SpecialChar ~
10630 \SpecialChar ~
10631 \SpecialChar ~
10632 \SpecialChar ~
10633 \SpecialChar ~
10634 out_byte <<= 1;
10635 \newline
10636 \SpecialChar ~
10637 \SpecialChar ~
10638 \SpecialChar ~
10639 \SpecialChar ~
10640 \SpecialChar ~
10641 \SpecialChar ~
10642 \SpecialChar ~
10643 \SpecialChar ~
10644 MCLK = 1;
10645 \newline
10646 \SpecialChar ~
10647 \SpecialChar ~
10648 \SpecialChar ~
10649 \SpecialChar ~
10650 \SpecialChar ~
10651 \SpecialChar ~
10652 \SpecialChar ~
10653 \SpecialChar ~
10654 /* _asm nop _endasm; */\SpecialChar ~
10655 \SpecialChar ~
10656 \SpecialChar ~
10657 \SpecialChar ~
10658 \SpecialChar ~
10659 \SpecialChar ~
10660 \SpecialChar ~
10661 \SpecialChar ~
10662 /* for slow peripherals */
10663 \newline
10664 \SpecialChar ~
10665 \SpecialChar ~
10666 \SpecialChar ~
10667 \SpecialChar ~
10668 \SpecialChar ~
10669 \SpecialChar ~
10670 \SpecialChar ~
10671 \SpecialChar ~
10672 if(MISO)
10673 \newline
10674 \SpecialChar ~
10675 \SpecialChar ~
10676 \SpecialChar ~
10677 \SpecialChar ~
10678 \SpecialChar ~
10679 \SpecialChar ~
10680 \SpecialChar ~
10681 \SpecialChar ~
10682 \SpecialChar ~
10683 \SpecialChar ~
10684 \SpecialChar ~
10685 \SpecialChar ~
10686 out_byte += 1;
10687 \newline
10688 \SpecialChar ~
10689 \SpecialChar ~
10690 \SpecialChar ~
10691 \SpecialChar ~
10692 \SpecialChar ~
10693 \SpecialChar ~
10694 \SpecialChar ~
10695 \SpecialChar ~
10696 MCLK = 0;
10697 \newline
10698 \SpecialChar ~
10699 \SpecialChar ~
10700 \SpecialChar ~
10701 \SpecialChar ~
10702 } while(--i);
10703 \newline
10704 \SpecialChar ~
10705 \SpecialChar ~
10706 \SpecialChar ~
10707 \SpecialChar ~
10708 return out_byte;
10709 \newline
10710 }
10711 \layout Standard
10712
10713 Then, someplace in the code for the first hardware you would use
10714 \layout Verse
10715
10716
10717 \family typewriter
10718 __bit __at
10719 \begin_inset LatexCommand \index{at}
10720
10721 \end_inset
10722
10723
10724 \begin_inset LatexCommand \index{\_\_at}
10725
10726 \end_inset
10727
10728  (0x80) MOSI;\SpecialChar ~
10729 \SpecialChar ~
10730 \SpecialChar ~
10731 \SpecialChar ~
10732 /* I/O port 0, bit 0 */
10733 \newline
10734 __bit __at (0x81) MISO;\SpecialChar ~
10735 \SpecialChar ~
10736 \SpecialChar ~
10737 \SpecialChar ~
10738 /* I/O port 0, bit 1 */
10739 \newline
10740 __bit __at (0x82) MCLK;\SpecialChar ~
10741 \SpecialChar ~
10742 \SpecialChar ~
10743 \SpecialChar ~
10744 /* I/O port 0, bit 2 */
10745 \layout Standard
10746
10747 Similarly, for the second hardware you would use
10748 \layout Verse
10749
10750
10751 \family typewriter
10752 __bit __at (0x83) MOSI;\SpecialChar ~
10753 \SpecialChar ~
10754 \SpecialChar ~
10755 \SpecialChar ~
10756 /* I/O port 0, bit 3 */
10757 \newline
10758 __bit __at (0x91) MISO;\SpecialChar ~
10759 \SpecialChar ~
10760 \SpecialChar ~
10761 \SpecialChar ~
10762 /* I/O port 1, bit 1 */
10763 \newline
10764 __bit
10765 \begin_inset LatexCommand \index{bit}
10766
10767 \end_inset
10768
10769  __at (0x92) MCLK;\SpecialChar ~
10770 \SpecialChar ~
10771 \SpecialChar ~
10772 \SpecialChar ~
10773 /* I/O port 1, bit 2 */
10774 \layout Standard
10775
10776 and you can use the same hardware dependent routine without changes, as
10777  for example in a library.
10778  This is somehow similar to sbit, but only one absolute address has to be
10779  specified in the whole project.
10780 \layout Section
10781
10782 Parameters
10783 \begin_inset LatexCommand \index{Parameters}
10784
10785 \end_inset
10786
10787
10788 \begin_inset LatexCommand \index{function parameter}
10789
10790 \end_inset
10791
10792  & Local Variables
10793 \begin_inset LatexCommand \index{local variables}
10794
10795 \end_inset
10796
10797
10798 \begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
10799
10800 \end_inset
10801
10802
10803 \layout Standard
10804
10805 Automatic (local) variables and parameters to functions can either be placed
10806  on the stack or in data-space.
10807  The default action of the compiler is to place these variables in the internal
10808  RAM (for small model) or external RAM (for large model).
10809  This in fact makes them similar to
10810 \emph on
10811 static
10812 \begin_inset LatexCommand \index{static}
10813
10814 \end_inset
10815
10816
10817 \emph default
10818  so by default functions are non-reentrant
10819 \begin_inset LatexCommand \index{reentrant}
10820
10821 \end_inset
10822
10823 .
10824
10825 \newline
10826
10827 \newline
10828 They can be placed on the stack
10829 \begin_inset LatexCommand \index{stack}
10830
10831 \end_inset
10832
10833  by using the
10834 \emph on
10835  -
10836 \begin_inset ERT
10837 status Collapsed
10838
10839 \layout Standard
10840
10841 \backslash
10842 /
10843 \end_inset
10844
10845 -stack-auto
10846 \begin_inset LatexCommand \index{-\/-stack-auto}
10847
10848 \end_inset
10849
10850
10851 \emph default
10852  option, by using
10853 \emph on
10854 #pragma\SpecialChar ~
10855 stackauto
10856 \emph default
10857
10858 \begin_inset LatexCommand \index{\#pragma stackauto}
10859
10860 \end_inset
10861
10862  or by using the
10863 \emph on
10864 reentrant
10865 \begin_inset LatexCommand \index{reentrant}
10866
10867 \end_inset
10868
10869
10870 \emph default
10871  keyword in the function declaration, e.g.:
10872 \layout Verse
10873
10874
10875 \family typewriter
10876 unsigned char foo(char i) __reentrant
10877 \newline
10878 {
10879 \newline
10880 \SpecialChar ~
10881 \SpecialChar ~
10882 \SpecialChar ~
10883 \SpecialChar ~
10884 ...
10885
10886 \newline
10887 }
10888 \layout Standard
10889
10890 Since stack space on 8051 is limited, the
10891 \emph on
10892 reentrant
10893 \emph default
10894 keyword or the
10895 \emph on
10896  -
10897 \begin_inset ERT
10898 status Collapsed
10899
10900 \layout Standard
10901
10902 \backslash
10903 /
10904 \end_inset
10905
10906 -stack-auto
10907 \emph default
10908  option should be used sparingly.
10909  Note that the reentrant keyword just means that the parameters & local
10910  variables will be allocated to the stack, it
10911 \emph on
10912 does not
10913 \emph default
10914  mean that the function is register bank
10915 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
10916
10917 \end_inset
10918
10919  independent.
10920 \newline
10921
10922 \newline
10923 Local variables
10924 \begin_inset LatexCommand \index{local variables}
10925
10926 \end_inset
10927
10928  can be assigned storage classes and absolute
10929 \begin_inset LatexCommand \index{Absolute addressing}
10930
10931 \end_inset
10932
10933  addresses, e.g.:
10934 \layout Verse
10935
10936
10937 \family typewriter
10938 unsigned char foo()
10939 \newline
10940 {
10941 \newline
10942 \SpecialChar ~
10943 \SpecialChar ~
10944 \SpecialChar ~
10945 \SpecialChar ~
10946 __xdata unsigned char i;
10947 \newline
10948 \SpecialChar ~
10949 \SpecialChar ~
10950 \SpecialChar ~
10951 \SpecialChar ~
10952 __bit bvar;
10953 \newline
10954 \SpecialChar ~
10955 \SpecialChar ~
10956 \SpecialChar ~
10957 \SpecialChar ~
10958 __data __at
10959 \begin_inset LatexCommand \index{at}
10960
10961 \end_inset
10962
10963  (0x31) unsigned char j;
10964 \newline
10965 \SpecialChar ~
10966 \SpecialChar ~
10967 \SpecialChar ~
10968 \SpecialChar ~
10969 ...
10970
10971 \newline
10972 }
10973 \layout Standard
10974
10975 In the above example the variable
10976 \emph on
10977 i
10978 \emph default
10979  will be allocated in the external ram,
10980 \emph on
10981 bvar
10982 \emph default
10983  in bit addressable space and
10984 \emph on
10985  j
10986 \emph default
10987  in internal ram.
10988  When compiled with
10989 \emph on
10990 -
10991 \begin_inset ERT
10992 status Collapsed
10993
10994 \layout Standard
10995
10996 \backslash
10997 /
10998 \end_inset
10999
11000 -stack-auto
11001 \emph default
11002  or when a function is declared as
11003 \emph on
11004 reentrant
11005 \emph default
11006  this should only be done for static variables.
11007 \layout Standard
11008
11009 Parameters
11010 \begin_inset LatexCommand \index{function parameter}
11011
11012 \end_inset
11013
11014  however are not allowed any storage class
11015 \begin_inset LatexCommand \index{Storage class}
11016
11017 \end_inset
11018
11019 , (storage classes for parameters will be ignored), their allocation is
11020  governed by the memory model in use, and the reentrancy options.
11021 \layout Standard
11022
11023 It is however allowed to use bit parameters in reentrant functions and also
11024  non-static local bit variables are supported.
11025  Efficient use is limited to 8 semi-bitregisters in bit space.
11026  They are pushed and popped to stack as a single byte just like the normal
11027  registers.
11028 \layout Section
11029
11030 Overlaying
11031 \begin_inset LatexCommand \label{sub:Overlaying}
11032
11033 \end_inset
11034
11035
11036 \begin_inset LatexCommand \index{Overlaying}
11037
11038 \end_inset
11039
11040
11041 \layout Standard
11042
11043 For non-reentrant
11044 \begin_inset LatexCommand \index{reentrant}
11045
11046 \end_inset
11047
11048  functions SDCC will try to reduce internal ram space usage by overlaying
11049  parameters and local variables of a function (if possible).
11050  Parameters and local variables
11051 \begin_inset LatexCommand \index{local variables}
11052
11053 \end_inset
11054
11055  of a function will be allocated to an overlayable segment if the function
11056  has
11057 \emph on
11058 no other function calls and the function is non-reentrant and the memory
11059  model
11060 \begin_inset LatexCommand \index{Memory model}
11061
11062 \end_inset
11063
11064  is small.
11065
11066 \emph default
11067  If an explicit storage class
11068 \begin_inset LatexCommand \index{Storage class}
11069
11070 \end_inset
11071
11072  is specified for a local variable, it will NOT be overlayed.
11073 \layout Standard
11074
11075 Note that the compiler (not the linkage editor) makes the decision for overlayin
11076 g the data items.
11077  Functions that are called from an interrupt service routine
11078 \begin_inset Marginal
11079 collapsed true
11080
11081 \layout Standard
11082
11083
11084 \series bold
11085 !
11086 \end_inset
11087
11088  should be preceded by a #pragma\SpecialChar ~
11089 nooverlay
11090 \begin_inset LatexCommand \index{\#pragma nooverlay}
11091
11092 \end_inset
11093
11094  if they are not reentrant.
11095 \layout Standard
11096
11097 Also note that the compiler does not do any processing of inline assembler
11098  code, so the compiler might incorrectly assign local variables and parameters
11099  of a function into the overlay segment if the inline assembler code calls
11100  other c-functions that might use the overlay.
11101  In that case the #pragma\SpecialChar ~
11102 nooverlay should be used.
11103 \layout Standard
11104
11105 Parameters and local variables of functions that contain 16 or 32 bit multiplica
11106 tion
11107 \begin_inset LatexCommand \index{Multiplication}
11108
11109 \end_inset
11110
11111  or division
11112 \begin_inset LatexCommand \index{Division}
11113
11114 \end_inset
11115
11116  will NOT be overlayed since these are implemented using external functions,
11117  e.g.:
11118 \layout Verse
11119
11120
11121 \family typewriter
11122 #pragma save
11123 \newline
11124 #pragma nooverlay
11125 \begin_inset LatexCommand \index{\#pragma nooverlay}
11126
11127 \end_inset
11128
11129
11130 \newline
11131 void set_error(unsigned char errcd)
11132 \newline
11133 {
11134 \newline
11135 \SpecialChar ~
11136 \SpecialChar ~
11137 \SpecialChar ~
11138 \SpecialChar ~
11139 P3 = errcd;
11140 \newline
11141 }
11142 \newline
11143 #pragma restore
11144 \newline
11145
11146 \newline
11147 void some_isr () __interrupt
11148 \begin_inset LatexCommand \index{interrupt}
11149
11150 \end_inset
11151
11152  (2)
11153 \newline
11154 {
11155 \newline
11156 \SpecialChar ~
11157 \SpecialChar ~
11158 \SpecialChar ~
11159 \SpecialChar ~
11160 ...
11161 \newline
11162 \SpecialChar ~
11163 \SpecialChar ~
11164 \SpecialChar ~
11165 \SpecialChar ~
11166 set_error(10);
11167 \newline
11168 \SpecialChar ~
11169 \SpecialChar ~
11170 \SpecialChar ~
11171 \SpecialChar ~
11172 ...
11173
11174 \newline
11175 }
11176 \layout Standard
11177
11178 In the above example the parameter
11179 \emph on
11180 errcd
11181 \emph default
11182  for the function
11183 \emph on
11184 set_error
11185 \emph default
11186  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
11187 nooverlay was
11188  not present, this could cause unpredictable runtime behavior when called
11189  from an interrupt service routine.
11190  The #pragma\SpecialChar ~
11191 nooverlay ensures that the parameters and local variables for
11192  the function are NOT overlayed.
11193 \layout Section
11194
11195 Interrupt Service Routines
11196 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
11197
11198 \end_inset
11199
11200
11201 \layout Subsection
11202
11203 General Information
11204 \layout Standard
11205
11206 SDCC allows
11207 \emph on
11208 i
11209 \emph default
11210 nterrupt
11211 \emph on
11212 s
11213 \emph default
11214 ervice
11215 \emph on
11216 r
11217 \emph default
11218 outines to be coded in C, with some extended keywords.
11219 \layout Verse
11220
11221
11222 \family typewriter
11223 void timer_isr (void) __interrupt (1) __using (1)
11224 \newline
11225 {
11226 \newline
11227 \SpecialChar ~
11228 \SpecialChar ~
11229 \SpecialChar ~
11230 \SpecialChar ~
11231 ...
11232
11233 \newline
11234 }
11235 \layout Standard
11236
11237 The optional number following the
11238 \emph on
11239 interrupt
11240 \begin_inset LatexCommand \index{interrupt}
11241
11242 \end_inset
11243
11244
11245 \begin_inset LatexCommand \index{\_\_interrupt}
11246
11247 \end_inset
11248
11249
11250 \emph default
11251  keyword is the interrupt number this routine will service.
11252  When present, the compiler will insert a call to this routine in the interrupt
11253  vector table for the interrupt number specified.
11254  If you have multiple source files in your project, interrupt service routines
11255  can be present in any of them, but a prototype of the isr MUST be present
11256  or included in the file that contains the function
11257 \emph on
11258 main
11259 \emph default
11260 .
11261  The optional
11262 \emph on
11263 using
11264 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11265
11266 \end_inset
11267
11268
11269 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11270
11271 \end_inset
11272
11273
11274 \emph default
11275  keyword can be used to tell the compiler to use the specified register
11276  bank (8051 specific) when generating code for this function.
11277
11278 \newline
11279
11280 \layout Standard
11281
11282 Interrupt service routines open the door for some very interesting bugs:
11283 \newline
11284 If an interrupt service routine changes variables which are accessed by
11285  other functions these variables have to be declared
11286 \emph on
11287 volatile
11288 \emph default
11289
11290 \begin_inset LatexCommand \index{volatile}
11291
11292 \end_inset
11293
11294 .
11295
11296 \layout Standard
11297
11298 If the access to these variables is not
11299 \emph on
11300 atomic
11301 \begin_inset LatexCommand \index{atomic}
11302
11303 \end_inset
11304
11305
11306 \emph default
11307  (i.e.
11308  the processor needs more than one instruction for the access and could
11309  be interrupted while accessing the variable) the interrupt must be disabled
11310  during the access to avoid inconsistent data.
11311  Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
11312  and should be protected by disabling interrupts.
11313  You're not automatically on the safe side if you use 8 bit variables though.
11314  We need an example here: f.e.
11315  on the 8051 the harmless looking
11316 \begin_inset Quotes srd
11317 \end_inset
11318
11319
11320 \family typewriter
11321 flags\SpecialChar ~
11322 |=\SpecialChar ~
11323 0x80;
11324 \family default
11325
11326 \begin_inset Quotes sld
11327 \end_inset
11328
11329  is not atomic if
11330 \family typewriter
11331 flags
11332 \family default
11333  resides in xdata.
11334  Setting
11335 \begin_inset Quotes srd
11336 \end_inset
11337
11338
11339 \family typewriter
11340 flags\SpecialChar ~
11341 |=\SpecialChar ~
11342 0x40;
11343 \family default
11344
11345 \begin_inset Quotes sld
11346 \end_inset
11347
11348  from within an interrupt routine might get lost if the interrupt occurs
11349  at the wrong time.
11350
11351 \begin_inset Quotes sld
11352 \end_inset
11353
11354
11355 \family typewriter
11356 counter\SpecialChar ~
11357 +=\SpecialChar ~
11358 8;
11359 \family default
11360
11361 \begin_inset Quotes srd
11362 \end_inset
11363
11364  is not atomic on the 8051 even if
11365 \family typewriter
11366 counter
11367 \family default
11368  is located in data memory.
11369  Bugs like these are hard to reproduce and can cause a lot of trouble.
11370
11371 \layout Standard
11372
11373 The return address and the registers used in the interrupt service routine
11374  are saved on the stack
11375 \begin_inset LatexCommand \index{stack}
11376
11377 \end_inset
11378
11379  so there must be sufficient stack space.
11380  If there isn't variables or registers (or even the return address itself)
11381  will be corrupted.
11382  This
11383 \emph on
11384 stack overflow
11385 \emph default
11386
11387 \begin_inset LatexCommand \index{stack overflow}
11388
11389 \end_inset
11390
11391  is most likely to happen if the interrupt occurs during the
11392 \begin_inset Quotes sld
11393 \end_inset
11394
11395 deepest
11396 \begin_inset Quotes srd
11397 \end_inset
11398
11399  subroutine when the stack is already in use for f.e.
11400  many return addresses.
11401 \layout Standard
11402
11403 A special note here, int (16 bit) and long (32 bit) integer division
11404 \begin_inset LatexCommand \index{Division}
11405
11406 \end_inset
11407
11408 , multiplication
11409 \begin_inset LatexCommand \index{Multiplication}
11410
11411 \end_inset
11412
11413  & modulus
11414 \begin_inset LatexCommand \index{Modulus}
11415
11416 \end_inset
11417
11418  and floating-point
11419 \begin_inset LatexCommand \index{Floating point support}
11420
11421 \end_inset
11422
11423  operations are implemented using external support routines developed in
11424  ANSI-C.
11425  If an interrupt service routine needs to do any of these operations then
11426  the support routines (as mentioned in a following section) will have to
11427  be recompiled using the
11428 \emph on
11429  -
11430 \begin_inset ERT
11431 status Collapsed
11432
11433 \layout Standard
11434
11435 \backslash
11436 /
11437 \end_inset
11438
11439 -stack-auto
11440 \begin_inset LatexCommand \index{-\/-stack-auto}
11441
11442 \end_inset
11443
11444
11445 \emph default
11446  option and the source file will need to be compiled using the
11447 \emph on
11448 -
11449 \begin_inset ERT
11450 status Collapsed
11451
11452 \layout Standard
11453
11454 \backslash
11455 /
11456 \end_inset
11457
11458 -int-long-reent
11459 \emph default
11460
11461 \begin_inset LatexCommand \index{-\/-int-long-reent}
11462
11463 \end_inset
11464
11465  compiler option.
11466  Note, the type promotion
11467 \begin_inset LatexCommand \index{type promotion}
11468
11469 \end_inset
11470
11471  required by ANSI C can cause 16 bit routines to be used without the programmer
11472  being aware of it.
11473
11474 \layout Standard
11475
11476 Calling other functions from an interrupt service routine is not recommended,
11477  avoid it if possible.
11478  Note that when some function is called from an interrupt service routine
11479  it should be preceded by a #pragma\SpecialChar ~
11480 nooverlay
11481 \begin_inset LatexCommand \index{\#pragma nooverlay}
11482
11483 \end_inset
11484
11485  if it is not reentrant.
11486  Furthermore nonreentrant functions should not be called from the main program
11487  while the interrupt service routine might be active.
11488  They also must not be called from low priority interrupt service routines
11489  while a high priority interrupt service routine might be active.
11490  You could use semaphores or make the function
11491 \emph on
11492  critical
11493 \emph default
11494  if all parameters are passed in registers.
11495 \newline
11496
11497 \newline
11498 Also see section
11499 \begin_inset LatexCommand \ref{sub:Overlaying}
11500
11501 \end_inset
11502
11503 \SpecialChar ~
11504 about Overlaying and section
11505 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
11506
11507 \end_inset
11508
11509 \SpecialChar ~
11510 about Functions using private register banks.
11511 \layout Subsection
11512
11513 MCS51/DS390 Interrupt Service Routines
11514 \layout Standard
11515
11516 Interrupt numbers and the corresponding address & descriptions for the Standard
11517  8051/8052 are listed below.
11518  SDCC will automatically adjust the interrupt vector table to the maximum
11519  interrupt number specified.
11520 \newline
11521
11522 \layout Standard
11523 \align center
11524
11525 \begin_inset  Tabular
11526 <lyxtabular version="3" rows="9" columns="3">
11527 <features>
11528 <column alignment="center" valignment="top" leftline="true" width="0in">
11529 <column alignment="left" valignment="top" leftline="true" width="0in">
11530 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
11531 <row topline="true" bottomline="true">
11532 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11533 \begin_inset Text
11534
11535 \layout Standard
11536
11537 Interrupt #
11538 \end_inset
11539 </cell>
11540 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11541 \begin_inset Text
11542
11543 \layout Standard
11544
11545 Description
11546 \end_inset
11547 </cell>
11548 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11549 \begin_inset Text
11550
11551 \layout Standard
11552
11553 Vector Address
11554 \end_inset
11555 </cell>
11556 </row>
11557 <row topline="true">
11558 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11559 \begin_inset Text
11560
11561 \layout Standard
11562
11563 0
11564 \end_inset
11565 </cell>
11566 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11567 \begin_inset Text
11568
11569 \layout Standard
11570
11571 External 0
11572 \end_inset
11573 </cell>
11574 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11575 \begin_inset Text
11576
11577 \layout Standard
11578
11579 0x0003
11580 \end_inset
11581 </cell>
11582 </row>
11583 <row topline="true">
11584 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11585 \begin_inset Text
11586
11587 \layout Standard
11588
11589 1
11590 \end_inset
11591 </cell>
11592 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11593 \begin_inset Text
11594
11595 \layout Standard
11596
11597 Timer 0
11598 \end_inset
11599 </cell>
11600 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11601 \begin_inset Text
11602
11603 \layout Standard
11604
11605 0x000b
11606 \end_inset
11607 </cell>
11608 </row>
11609 <row topline="true">
11610 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11611 \begin_inset Text
11612
11613 \layout Standard
11614
11615 2
11616 \end_inset
11617 </cell>
11618 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11619 \begin_inset Text
11620
11621 \layout Standard
11622
11623 External 1
11624 \end_inset
11625 </cell>
11626 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11627 \begin_inset Text
11628
11629 \layout Standard
11630
11631 0x0013
11632 \end_inset
11633 </cell>
11634 </row>
11635 <row topline="true">
11636 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11637 \begin_inset Text
11638
11639 \layout Standard
11640
11641 3
11642 \end_inset
11643 </cell>
11644 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11645 \begin_inset Text
11646
11647 \layout Standard
11648
11649 Timer 1
11650 \end_inset
11651 </cell>
11652 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11653 \begin_inset Text
11654
11655 \layout Standard
11656
11657 0x001b
11658 \end_inset
11659 </cell>
11660 </row>
11661 <row topline="true">
11662 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11663 \begin_inset Text
11664
11665 \layout Standard
11666
11667 4
11668 \end_inset
11669 </cell>
11670 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11671 \begin_inset Text
11672
11673 \layout Standard
11674
11675 Serial
11676 \end_inset
11677 </cell>
11678 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11679 \begin_inset Text
11680
11681 \layout Standard
11682
11683 0x0023
11684 \end_inset
11685 </cell>
11686 </row>
11687 <row topline="true">
11688 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11689 \begin_inset Text
11690
11691 \layout Standard
11692
11693 5
11694 \end_inset
11695 </cell>
11696 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11697 \begin_inset Text
11698
11699 \layout Standard
11700
11701 Timer 2 (8052)
11702 \end_inset
11703 </cell>
11704 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11705 \begin_inset Text
11706
11707 \layout Standard
11708
11709 0x002b
11710 \end_inset
11711 </cell>
11712 </row>
11713 <row topline="true">
11714 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11715 \begin_inset Text
11716
11717 \layout Standard
11718
11719 ...
11720 \end_inset
11721 </cell>
11722 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11723 \begin_inset Text
11724
11725 \layout Standard
11726
11727 \end_inset
11728 </cell>
11729 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11730 \begin_inset Text
11731
11732 \layout Standard
11733
11734 ...
11735 \end_inset
11736 </cell>
11737 </row>
11738 <row topline="true" bottomline="true">
11739 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11740 \begin_inset Text
11741
11742 \layout Standard
11743
11744 n
11745 \end_inset
11746 </cell>
11747 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11748 \begin_inset Text
11749
11750 \layout Standard
11751
11752 \end_inset
11753 </cell>
11754 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11755 \begin_inset Text
11756
11757 \layout Standard
11758
11759 0x0003 + 8*n
11760 \end_inset
11761 </cell>
11762 </row>
11763 </lyxtabular>
11764
11765 \end_inset
11766
11767
11768 \newline
11769
11770 \layout Standard
11771
11772 If the interrupt service routine is defined without
11773 \emph on
11774 using
11775 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11776
11777 \end_inset
11778
11779
11780 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11781
11782 \end_inset
11783
11784
11785 \emph default
11786  a register bank or with register bank 0 (
11787 \emph on
11788 using
11789 \emph default
11790  0), the compiler will save the registers used by itself on the stack upon
11791  entry and restore them at exit, however if such an interrupt service routine
11792  calls another function then the entire register bank will be saved on the
11793  stack.
11794  This scheme may be advantageous for small interrupt service routines which
11795  have low register usage.
11796 \layout Standard
11797
11798 If the interrupt service routine is defined to be using a specific register
11799  bank then only
11800 \emph on
11801 a, b, dptr
11802 \emph default
11803  & psw are saved and restored, if such an interrupt service routine calls
11804  another function (using another register bank) then the entire register
11805  bank of the called function will be saved on the stack.
11806  This scheme is recommended for larger interrupt service routines.
11807 \layout Subsection
11808
11809 HC08 Interrupt Service Routines
11810 \layout Standard
11811
11812 Since the number of interrupts available is chip specific and the interrupt
11813  vector table always ends at the last byte of memory, the interrupt numbers
11814  corresponds to the interrupt vectors in reverse order of address.
11815  For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
11816  2 will use the interrupt vector at 0xfffa, and so on.
11817  However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
11818  this way; instead see section
11819 \begin_inset LatexCommand \ref{sub:Startup-Code}
11820
11821 \end_inset
11822
11823  for details on customizing startup.
11824 \layout Subsection
11825
11826 Z80 Interrupt Service Routines
11827 \layout Standard
11828
11829 The Z80 uses several different methods for determining the correct interrupt
11830  vector depending on the hardware implementation.
11831  Therefore, SDCC ignores the optional interrupt number and does not attempt
11832  to generate an interrupt vector table.
11833 \layout Standard
11834
11835 By default, SDCC generates code for a maskable interrupt, which uses a RETI
11836  instruction to return from the interrupt.
11837  To write an interrupt handler for the non-maskable interrupt, which needs
11838  a RETN instruction instead, add the
11839 \emph on
11840 critical
11841 \emph default
11842  keyword:
11843 \layout Verse
11844
11845
11846 \family typewriter
11847 void nmi_isr (void) critical interrupt
11848 \newline
11849 {
11850 \newline
11851 \SpecialChar ~
11852 \SpecialChar ~
11853 \SpecialChar ~
11854 \SpecialChar ~
11855 ...
11856
11857 \newline
11858 }
11859 \layout Standard
11860
11861 However if you need to create a non-interruptable interrupt service routine
11862  you would also require the
11863 \emph on
11864 critical
11865 \emph default
11866  keyword.
11867  To distinguish between this and an nmi_isr you must provide an interrupt
11868  number.
11869 \layout Section
11870
11871 Enabling and Disabling Interrupts
11872 \layout Subsection
11873
11874 Critical Functions and Critical Statements
11875 \layout Standard
11876
11877 A special keyword may be associated with a block or a function declaring
11878  it as
11879 \emph on
11880 critical
11881 \emph default
11882 .
11883  SDCC will generate code to disable all interrupts
11884 \begin_inset LatexCommand \index{interrupt}
11885
11886 \end_inset
11887
11888  upon entry to a critical function and restore the interrupt enable to the
11889  previous state before returning.
11890  Nesting critical functions will need one additional byte on the stack
11891 \begin_inset LatexCommand \index{stack}
11892
11893 \end_inset
11894
11895  for each call.
11896 \layout Verse
11897
11898
11899 \family typewriter
11900 int foo () __critical
11901 \begin_inset LatexCommand \index{critical}
11902
11903 \end_inset
11904
11905
11906 \begin_inset LatexCommand \index{\_\_critical}
11907
11908 \end_inset
11909
11910
11911 \newline
11912 {
11913 \newline
11914 \SpecialChar ~
11915 \SpecialChar ~
11916 \SpecialChar ~
11917 \SpecialChar ~
11918 ...
11919
11920 \newline
11921 \SpecialChar ~
11922 \SpecialChar ~
11923 \SpecialChar ~
11924 \SpecialChar ~
11925 ...
11926
11927 \newline
11928 }
11929 \layout Standard
11930
11931 The critical attribute maybe used with other attributes like
11932 \emph on
11933 reentrant.
11934 \emph default
11935
11936 \newline
11937 The keyword
11938 \emph on
11939 critical
11940 \emph default
11941  may also be used to disable interrupts more locally:
11942 \layout Verse
11943
11944
11945 \family typewriter
11946 __critical{ i++; }
11947 \layout Standard
11948
11949 More than one statement could have been included in the block.
11950 \layout Subsection
11951
11952 Enabling and Disabling Interrupts directly
11953 \layout Standard
11954
11955 Interrupts
11956 \begin_inset LatexCommand \index{interrupt}
11957
11958 \end_inset
11959
11960  can also be disabled and enabled directly (8051):
11961 \layout Verse
11962
11963
11964 \family typewriter
11965 EA = 0;\SpecialChar ~
11966 \SpecialChar ~
11967 \SpecialChar ~
11968 \SpecialChar ~
11969 \SpecialChar ~
11970 \SpecialChar ~
11971 \SpecialChar ~
11972 \SpecialChar ~
11973 \SpecialChar ~
11974 \SpecialChar ~
11975 \SpecialChar ~
11976 \SpecialChar ~
11977 or:\SpecialChar ~
11978 \SpecialChar ~
11979 \SpecialChar ~
11980 \SpecialChar ~
11981 \SpecialChar ~
11982 \SpecialChar ~
11983 \SpecialChar ~
11984 \SpecialChar ~
11985 \SpecialChar ~
11986 \SpecialChar ~
11987 \SpecialChar ~
11988 EA_SAVE = EA;
11989 \layout Verse
11990
11991
11992 \family typewriter
11993 ...\SpecialChar ~
11994 \SpecialChar ~
11995 \SpecialChar ~
11996 \SpecialChar ~
11997 \SpecialChar ~
11998 \SpecialChar ~
11999 \SpecialChar ~
12000 \SpecialChar ~
12001 \SpecialChar ~
12002 \SpecialChar ~
12003 \SpecialChar ~
12004 \SpecialChar ~
12005 \SpecialChar ~
12006 \SpecialChar ~
12007 \SpecialChar ~
12008 \SpecialChar ~
12009 \SpecialChar ~
12010 \SpecialChar ~
12011 \SpecialChar ~
12012 \SpecialChar ~
12013 \SpecialChar ~
12014 \SpecialChar ~
12015 \SpecialChar ~
12016 \SpecialChar ~
12017 \SpecialChar ~
12018 \SpecialChar ~
12019 \SpecialChar ~
12020 \SpecialChar ~
12021 \SpecialChar ~
12022 \SpecialChar ~
12023 EA = 0;
12024 \layout Verse
12025
12026
12027 \family typewriter
12028 EA = 1;\SpecialChar ~
12029 \SpecialChar ~
12030 \SpecialChar ~
12031 \SpecialChar ~
12032 \SpecialChar ~
12033 \SpecialChar ~
12034 \SpecialChar ~
12035 \SpecialChar ~
12036 \SpecialChar ~
12037 \SpecialChar ~
12038 \SpecialChar ~
12039 \SpecialChar ~
12040 \SpecialChar ~
12041 \SpecialChar ~
12042 \SpecialChar ~
12043 \SpecialChar ~
12044 \SpecialChar ~
12045 \SpecialChar ~
12046 \SpecialChar ~
12047 \SpecialChar ~
12048 \SpecialChar ~
12049 \SpecialChar ~
12050 \SpecialChar ~
12051 \SpecialChar ~
12052 \SpecialChar ~
12053 \SpecialChar ~
12054 ...
12055 \layout Verse
12056
12057
12058 \family typewriter
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 \SpecialChar ~
12079 \SpecialChar ~
12080 \SpecialChar ~
12081 \SpecialChar ~
12082 \SpecialChar ~
12083 \SpecialChar ~
12084 \SpecialChar ~
12085 \SpecialChar ~
12086 \SpecialChar ~
12087 \SpecialChar ~
12088 \SpecialChar ~
12089 \SpecialChar ~
12090 \SpecialChar ~
12091 \SpecialChar ~
12092 EA = EA_SAVE;
12093 \layout Standard
12094
12095 On other architectures which have seperate opcodes for enabling and disabling
12096  interrupts you might want to make use of defines with inline assembly
12097 \begin_inset LatexCommand \index{Assembler routines}
12098
12099 \end_inset
12100
12101  (HC08):
12102 \layout Verse
12103
12104
12105 \family typewriter
12106 #define CLI _asm
12107 \begin_inset LatexCommand \index{\_asm}
12108
12109 \end_inset
12110
12111 \SpecialChar ~
12112 \SpecialChar ~
12113 cli\SpecialChar ~
12114 \SpecialChar ~
12115 _endasm
12116 \begin_inset LatexCommand \index{\_endasm}
12117
12118 \end_inset
12119
12120 ;
12121 \layout Verse
12122
12123
12124 \family typewriter
12125 #define SEI _asm\SpecialChar ~
12126 \SpecialChar ~
12127 sei\SpecialChar ~
12128 \SpecialChar ~
12129 _endasm;
12130 \layout Verse
12131
12132
12133 \family typewriter
12134 ...
12135 \layout Standard
12136
12137 Note: it is sometimes sufficient to disable only a specific interrupt source
12138  like f.e.
12139  a timer or serial interrupt by manipulating an
12140 \emph on
12141 interrupt mask
12142 \begin_inset LatexCommand \index{interrupt mask}
12143
12144 \end_inset
12145
12146
12147 \emph default
12148  register.
12149
12150 \layout Standard
12151
12152 Usually the time during which interrupts are disabled should be kept as
12153  short as possible.
12154  This minimizes both
12155 \emph on
12156 interrupt latency
12157 \emph default
12158
12159 \begin_inset LatexCommand \index{interrupt latency}
12160
12161 \end_inset
12162
12163  (the time between the occurrence of the interrupt and the execution of
12164  the first code in the interrupt routine) and
12165 \emph on
12166 interrupt jitter
12167 \emph default
12168
12169 \begin_inset LatexCommand \index{interrupt jitter}
12170
12171 \end_inset
12172
12173  (the difference between the shortest and the longest interrupt latency).
12174  These really are something different, f.e.
12175  a serial interrupt has to be served before its buffer overruns so it cares
12176  for the maximum interrupt latency, whereas it does not care about jitter.
12177  On a loudspeaker driven via a digital to analog converter which is fed
12178  by an interrupt a latency of a few milliseconds might be tolerable, whereas
12179  a much smaller jitter will be very audible.
12180 \layout Standard
12181
12182 You can reenable interrupts within an interrupt routine and on some architecture
12183 s you can make use of two (or more) levels of
12184 \emph on
12185 interrupt priorities
12186 \emph default
12187
12188 \begin_inset LatexCommand \index{interrupt priority}
12189
12190 \end_inset
12191
12192 .
12193  On some architectures which don't support interrupt priorities these can
12194  be implemented by manipulating the interrupt mask and reenabling interrupts
12195  within the interrupt routine.
12196  Check there is sufficient space on the stack
12197 \begin_inset LatexCommand \index{stack}
12198
12199 \end_inset
12200
12201  and don't add complexity unless you have to.
12202
12203 \layout Subsection
12204
12205 Semaphore
12206 \begin_inset LatexCommand \index{semaphore}
12207
12208 \end_inset
12209
12210  locking (mcs51/ds390)
12211 \layout Standard
12212
12213 Some architectures (mcs51/ds390) have an atomic
12214 \begin_inset LatexCommand \index{atomic}
12215
12216 \end_inset
12217
12218  bit test and
12219 \emph on
12220
12221 \emph default
12222 clear
12223 \emph on
12224
12225 \emph default
12226 instruction.
12227  These type of instructions are typically used in preemptive multitasking
12228  systems, where a routine f.e.
12229  claims the use of a data structure ('acquires a lock
12230 \begin_inset LatexCommand \index{lock}
12231
12232 \end_inset
12233
12234  on it'), makes some modifications and then releases the lock when the data
12235  structure is consistent again.
12236  The instruction may also be used if interrupt and non-interrupt code have
12237  to compete for a resource.
12238  With the atomic bit test and clear instruction interrupts
12239 \begin_inset LatexCommand \index{interrupt}
12240
12241 \end_inset
12242
12243  don't have to be disabled for the locking operation.
12244
12245 \layout Standard
12246
12247 SDCC generates this instruction if the source follows this pattern:
12248 \layout Verse
12249
12250
12251 \family typewriter
12252 volatile
12253 \begin_inset LatexCommand \index{volatile}
12254
12255 \end_inset
12256
12257  bit resource_is_free;
12258 \newline
12259
12260 \newline
12261 if (resource_is_free)
12262 \newline
12263 \SpecialChar ~
12264 \SpecialChar ~
12265 {
12266 \newline
12267 \SpecialChar ~
12268 \SpecialChar ~
12269 \SpecialChar ~
12270 \SpecialChar ~
12271 resource_is_free=0;
12272 \newline
12273 \SpecialChar ~
12274 \SpecialChar ~
12275 \SpecialChar ~
12276 \SpecialChar ~
12277 ...
12278
12279 \newline
12280 \SpecialChar ~
12281 \SpecialChar ~
12282 \SpecialChar ~
12283 \SpecialChar ~
12284 resource_is_free=1;
12285 \newline
12286 \SpecialChar ~
12287 \SpecialChar ~
12288 }
12289 \layout Standard
12290
12291 Note, mcs51 and ds390 support only an atomic
12292 \begin_inset LatexCommand \index{atomic}
12293
12294 \end_inset
12295
12296  bit test and
12297 \emph on
12298 clear
12299 \emph default
12300  instruction (as opposed to atomic bit test and
12301 \emph on
12302 set).
12303 \layout Section
12304
12305 Functions using private register banks
12306 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
12307
12308 \end_inset
12309
12310  (mcs51/ds390)
12311 \layout Standard
12312
12313 Some architectures have support for quickly changing register sets.
12314  SDCC supports this feature with the
12315 \emph on
12316 using
12317 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
12318
12319 \end_inset
12320
12321
12322 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
12323
12324 \end_inset
12325
12326
12327 \emph default
12328  attribute (which tells the compiler to use a register bank
12329 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
12330
12331 \end_inset
12332
12333  other than the default bank zero).
12334  It should only be applied to
12335 \emph on
12336 interrupt
12337 \begin_inset LatexCommand \index{interrupt}
12338
12339 \end_inset
12340
12341
12342 \emph default
12343  functions (see footnote below).
12344  This will in most circumstances make the generated ISR code more efficient
12345  since it will not have to save registers on the stack.
12346 \layout Standard
12347
12348 The
12349 \emph on
12350 using
12351 \emph default
12352  attribute will have no effect on the generated code for a
12353 \emph on
12354 non-interrupt
12355 \emph default
12356  function (but may occasionally be useful anyway
12357 \begin_inset Foot
12358 collapsed false
12359
12360 \layout Standard
12361
12362 possible exception: if a function is called ONLY from 'interrupt' functions
12363  using a particular bank, it can be declared with the same 'using' attribute
12364  as the calling 'interrupt' functions.
12365  For instance, if you have several ISRs using bank one, and all of them
12366  call memcpy(), it might make sense to create a specialized version of memcpy()
12367  'using 1', since this would prevent the ISR from having to save bank zero
12368  to the stack on entry and switch to bank zero before calling the function
12369 \end_inset
12370
12371 ).
12372 \newline
12373
12374 \emph on
12375 (pending: I don't think this has been done yet)
12376 \layout Standard
12377
12378 An
12379 \emph on
12380 interrupt
12381 \emph default
12382  function using a non-zero bank will assume that it can trash that register
12383  bank, and will not save it.
12384  Since high-priority interrupts
12385 \begin_inset LatexCommand \index{interrupts}
12386
12387 \end_inset
12388
12389
12390 \begin_inset LatexCommand \index{interrupt priority}
12391
12392 \end_inset
12393
12394  can interrupt low-priority ones on the 8051 and friends, this means that
12395  if a high-priority ISR
12396 \emph on
12397 using
12398 \emph default
12399  a particular bank occurs while processing a low-priority ISR
12400 \emph on
12401 using
12402 \emph default
12403  the same bank, terrible and bad things can happen.
12404  To prevent this, no single register bank should be
12405 \emph on
12406 used
12407 \emph default
12408  by both a high priority and a low priority ISR.
12409  This is probably most easily done by having all high priority ISRs use
12410  one bank and all low priority ISRs use another.
12411  If you have an ISR which can change priority at runtime, you're on your
12412  own: I suggest using the default bank zero and taking the small performance
12413  hit.
12414 \layout Standard
12415
12416 It is most efficient if your ISR calls no other functions.
12417  If your ISR must call other functions, it is most efficient if those functions
12418  use the same bank as the ISR (see note 1 below); the next best is if the
12419  called functions use bank zero.
12420  It is very inefficient to call a function using a different, non-zero bank
12421  from an ISR.
12422
12423 \layout Section
12424
12425 Startup Code
12426 \begin_inset LatexCommand \label{sub:Startup-Code}
12427
12428 \end_inset
12429
12430
12431 \begin_inset LatexCommand \index{Startup code}
12432
12433 \end_inset
12434
12435
12436 \layout Subsection
12437
12438 MCS51/DS390 Startup Code
12439 \layout Standard
12440
12441 The compiler inserts a call to the C routine
12442 \emph on
12443 _sdcc_external_startup()
12444 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
12445
12446 \end_inset
12447
12448
12449 \series bold
12450 \emph default
12451
12452 \series default
12453 at the start of the CODE area.
12454  This routine is in the runtime library
12455 \begin_inset LatexCommand \index{Runtime library}
12456
12457 \end_inset
12458
12459 .
12460  By default this routine returns 0, if this routine returns a non-zero value,
12461  the static & global variable initialization will be skipped and the function
12462  main will be invoked.
12463  Otherwise static & global variables will be initialized before the function
12464  main is invoked.
12465  You could add a
12466 \emph on
12467 _sdcc_external_startup()
12468 \emph default
12469  routine to your program to override the default if you need to setup hardware
12470  or perform some other critical operation prior to static & global variable
12471  initialization
12472 \begin_inset LatexCommand \index{Variable initialization}
12473
12474 \end_inset
12475
12476 .
12477  On some mcs51 variants xdata
12478 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
12479
12480 \end_inset
12481
12482  memory has to be explicitly enabled before it can be accessed or if the
12483  watchdog needs to be disabled, this is the place to do it.
12484  The startup code clears all internal data memory, 256 bytes by default,
12485  but from 0 to n-1 if
12486 \emph on
12487 -
12488 \begin_inset ERT
12489 status Collapsed
12490
12491 \layout Standard
12492
12493 \backslash
12494 /
12495 \end_inset
12496
12497 -iram-size
12498 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
12499
12500 \end_inset
12501
12502 n
12503 \emph default
12504  is used.
12505  (recommended for Chipcon CC1010).
12506 \layout Standard
12507
12508 See also the compiler option
12509 \emph on
12510 -
12511 \begin_inset ERT
12512 status Collapsed
12513
12514 \layout Standard
12515
12516 \backslash
12517 /
12518 \end_inset
12519
12520 -no-xinit
12521 \emph default
12522 -
12523 \emph on
12524 opt
12525 \emph default
12526
12527 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
12528
12529 \end_inset
12530
12531  and section
12532 \begin_inset LatexCommand \ref{sub:MCS51-variants}
12533
12534 \end_inset
12535
12536 \SpecialChar ~
12537 about MCS51-variants.
12538 \layout Subsection
12539
12540 HC08 Startup Code
12541 \layout Standard
12542
12543 The HC08 startup code follows the same scheme as the MCS51 startup code.
12544 \layout Subsection
12545
12546 Z80 Startup Code
12547 \layout Standard
12548
12549 On the Z80 the startup code is inserted by linking with crt0.o which is generated
12550  from sdcc/device/lib/z80/crt0.s.
12551  If you need a different startup code you can use the compiler option
12552 \emph on
12553 -
12554 \series bold
12555 \emph default
12556
12557 \begin_inset ERT
12558 status Collapsed
12559
12560 \layout Standard
12561
12562 \backslash
12563 /
12564 \end_inset
12565
12566
12567 \series default
12568 \emph on
12569 -no-std-crt0
12570 \emph default
12571
12572 \begin_inset LatexCommand \index{-\/-no-std-crt0}
12573
12574 \end_inset
12575
12576  and provide your own crt0.o.
12577
12578 \layout Section
12579
12580 Inline Assembler Code
12581 \begin_inset LatexCommand \index{Assembler routines}
12582
12583 \end_inset
12584
12585
12586 \layout Subsection
12587
12588 A Step by Step Introduction
12589 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
12590
12591 \end_inset
12592
12593
12594 \layout Standard
12595
12596 Starting from a small snippet of c-code this example shows for the MCS51
12597  how to use inline assembly, access variables, a function parameter and
12598  an array in xdata memory.
12599  The example uses an MCS51 here but is easily adapted for other architectures.
12600  This is a buffer routine which should be optimized:
12601 \layout Verse
12602
12603
12604 \family typewriter
12605 \size footnotesize
12606 unsigned char __far
12607 \begin_inset LatexCommand \index{far (storage class)}
12608
12609 \end_inset
12610
12611
12612 \begin_inset LatexCommand \index{\_\_far (storage class)}
12613
12614 \end_inset
12615
12616  __at
12617 \begin_inset LatexCommand \index{at}
12618
12619 \end_inset
12620
12621
12622 \begin_inset LatexCommand \index{\_\_at}
12623
12624 \end_inset
12625
12626 (0x7f00) buf[0x100];
12627 \begin_inset LatexCommand \index{Aligned array}
12628
12629 \end_inset
12630
12631
12632 \newline
12633 unsigned char head, tail;
12634 \newline
12635
12636 \newline
12637 void to_buffer( unsigned char c )
12638 \newline
12639 {
12640 \newline
12641 \SpecialChar ~
12642 \SpecialChar ~
12643 \SpecialChar ~
12644 \SpecialChar ~
12645 if( head != (unsigned char)(tail-1) )\SpecialChar ~
12646 /* cast
12647 \series bold
12648 needed
12649 \series default
12650  to avoid promotion
12651 \begin_inset LatexCommand \index{promotion to signed int}
12652
12653 \end_inset
12654
12655
12656 \begin_inset LatexCommand \index{type promotion}
12657
12658 \end_inset
12659
12660  to integer */
12661 \begin_inset Marginal
12662 collapsed false
12663
12664 \layout Standard
12665
12666
12667 \series bold
12668 \SpecialChar ~
12669 !
12670 \end_inset
12671
12672
12673 \newline
12674 \SpecialChar ~
12675 \SpecialChar ~
12676 \SpecialChar ~
12677 \SpecialChar ~
12678 \SpecialChar ~
12679 \SpecialChar ~
12680 \SpecialChar ~
12681 \SpecialChar ~
12682 buf[ head++ ] = c;\SpecialChar ~
12683 \SpecialChar ~
12684 \SpecialChar ~
12685 \SpecialChar ~
12686 \SpecialChar ~
12687 \SpecialChar ~
12688 \SpecialChar ~
12689 \SpecialChar ~
12690 \SpecialChar ~
12691 \SpecialChar ~
12692 \SpecialChar ~
12693 \SpecialChar ~
12694 \SpecialChar ~
12695 \SpecialChar ~
12696 \SpecialChar ~
12697 \SpecialChar ~
12698 /* access to a 256 byte aligned array */
12699 \newline
12700 }
12701 \layout Standard
12702
12703 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
12704  then a corresponding buffer.asm file is generated.
12705  We define a new function
12706 \family typewriter
12707 to_buffer_asm()
12708 \family default
12709  in file buffer.c in which we cut and paste the generated code, removing
12710  unwanted comments and some ':'.
12711  Then add
12712 \begin_inset Quotes sld
12713 \end_inset
12714
12715 _asm
12716 \begin_inset Quotes srd
12717 \end_inset
12718
12719  and
12720 \begin_inset Quotes sld
12721 \end_inset
12722
12723 _endasm;
12724 \begin_inset Quotes srd
12725 \end_inset
12726
12727  to the beginning and the end of the function body:
12728 \layout Verse
12729
12730
12731 \family typewriter
12732 \size footnotesize
12733 /* With a cut and paste from the .asm file, we have something to start with.
12734 \newline
12735 \SpecialChar ~
12736 \SpecialChar ~
12737 \SpecialChar ~
12738 The function is not yet OK! (registers aren't saved) */
12739 \newline
12740 void to_buffer_asm( unsigned char c )
12741 \newline
12742 {
12743 \newline
12744 \SpecialChar ~
12745 \SpecialChar ~
12746 \SpecialChar ~
12747 \SpecialChar ~
12748 _asm
12749 \begin_inset LatexCommand \index{\_asm}
12750
12751 \end_inset
12752
12753
12754 \begin_inset LatexCommand \index{\_\_asm}
12755
12756 \end_inset
12757
12758
12759 \newline
12760 \SpecialChar ~
12761 \SpecialChar ~
12762 \SpecialChar ~
12763 \SpecialChar ~
12764 mov\SpecialChar ~
12765 \SpecialChar ~
12766 r2,dpl
12767 \newline
12768 ;buffer.c if( head != (unsigned char)(tail-1) )
12769 \newline
12770 \SpecialChar ~
12771 \SpecialChar ~
12772 \SpecialChar ~
12773 \SpecialChar ~
12774 mov\SpecialChar ~
12775 \SpecialChar ~
12776 a,_tail
12777 \newline
12778 \SpecialChar ~
12779 \SpecialChar ~
12780 \SpecialChar ~
12781 \SpecialChar ~
12782 dec\SpecialChar ~
12783 \SpecialChar ~
12784 a
12785 \newline
12786 \SpecialChar ~
12787 \SpecialChar ~
12788 \SpecialChar ~
12789 \SpecialChar ~
12790 mov\SpecialChar ~
12791 \SpecialChar ~
12792 r3,a
12793 \newline
12794 \SpecialChar ~
12795 \SpecialChar ~
12796 \SpecialChar ~
12797 \SpecialChar ~
12798 mov\SpecialChar ~
12799 \SpecialChar ~
12800 a,_head
12801 \newline
12802 \SpecialChar ~
12803 \SpecialChar ~
12804 \SpecialChar ~
12805 \SpecialChar ~
12806 cjne a,ar3,00106$
12807 \newline
12808 \SpecialChar ~
12809 \SpecialChar ~
12810 \SpecialChar ~
12811 \SpecialChar ~
12812 ret
12813 \newline
12814 00106$:
12815 \newline
12816 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
12817 \begin_inset LatexCommand \index{Aligned array}
12818
12819 \end_inset
12820
12821
12822 \newline
12823 \SpecialChar ~
12824 \SpecialChar ~
12825 \SpecialChar ~
12826 \SpecialChar ~
12827 mov\SpecialChar ~
12828 \SpecialChar ~
12829 r3,_head
12830 \newline
12831 \SpecialChar ~
12832 \SpecialChar ~
12833 \SpecialChar ~
12834 \SpecialChar ~
12835 inc\SpecialChar ~
12836 \SpecialChar ~
12837 _head
12838 \newline
12839 \SpecialChar ~
12840 \SpecialChar ~
12841 \SpecialChar ~
12842 \SpecialChar ~
12843 mov\SpecialChar ~
12844 \SpecialChar ~
12845 dpl,r3
12846 \newline
12847 \SpecialChar ~
12848 \SpecialChar ~
12849 \SpecialChar ~
12850 \SpecialChar ~
12851 mov\SpecialChar ~
12852 \SpecialChar ~
12853 dph,#(_buf >> 8)
12854 \newline
12855 \SpecialChar ~
12856 \SpecialChar ~
12857 \SpecialChar ~
12858 \SpecialChar ~
12859 mov\SpecialChar ~
12860 \SpecialChar ~
12861 a,r2
12862 \newline
12863 \SpecialChar ~
12864 \SpecialChar ~
12865 \SpecialChar ~
12866 \SpecialChar ~
12867 movx @dptr,a
12868 \newline
12869 00103$:
12870 \newline
12871 \SpecialChar ~
12872 \SpecialChar ~
12873 \SpecialChar ~
12874 \SpecialChar ~
12875 ret
12876 \newline
12877 \SpecialChar ~
12878 \SpecialChar ~
12879 \SpecialChar ~
12880 \SpecialChar ~
12881 _endasm
12882 \begin_inset LatexCommand \index{\_endasm}
12883
12884 \end_inset
12885
12886
12887 \begin_inset LatexCommand \index{\_\_endasm}
12888
12889 \end_inset
12890
12891 ;
12892 \newline
12893 }
12894 \layout Standard
12895
12896 The new file buffer.c should compile with only one warning about the unreferenced
12897  function argument 'c'.
12898  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
12899  (1) and finally have:
12900 \layout Verse
12901
12902
12903 \family typewriter
12904 \size footnotesize
12905 unsigned char __far __at(0x7f00) buf[0x100];
12906 \newline
12907 unsigned char head, tail;
12908 \newline
12909 #define USE_ASSEMBLY (1)
12910 \newline
12911
12912 \newline
12913 #if !USE_ASSEMBLY
12914 \newline
12915
12916 \newline
12917 void to_buffer( unsigned char c )
12918 \newline
12919 {
12920 \newline
12921 \SpecialChar ~
12922 \SpecialChar ~
12923 \SpecialChar ~
12924 \SpecialChar ~
12925 if( head != (unsigned char)(tail-1) )
12926 \newline
12927 \SpecialChar ~
12928 \SpecialChar ~
12929 \SpecialChar ~
12930 \SpecialChar ~
12931 \SpecialChar ~
12932 \SpecialChar ~
12933 \SpecialChar ~
12934 \SpecialChar ~
12935 buf[ head++ ] = c;
12936 \newline
12937 }
12938 \newline
12939
12940 \newline
12941 #else
12942 \newline
12943
12944 \newline
12945 void to_buffer( unsigned char c )
12946 \newline
12947 {
12948 \newline
12949 \SpecialChar ~
12950 \SpecialChar ~
12951 \SpecialChar ~
12952 \SpecialChar ~
12953 c; // to avoid warning: unreferenced function argument
12954 \newline
12955 \SpecialChar ~
12956 \SpecialChar ~
12957 \SpecialChar ~
12958 \SpecialChar ~
12959 _asm
12960 \begin_inset LatexCommand \index{\_asm}
12961
12962 \end_inset
12963
12964
12965 \begin_inset LatexCommand \index{\_\_asm}
12966
12967 \end_inset
12968
12969
12970 \newline
12971 \SpecialChar ~
12972 \SpecialChar ~
12973 \SpecialChar ~
12974 \SpecialChar ~
12975 \SpecialChar ~
12976 \SpecialChar ~
12977 \SpecialChar ~
12978 \SpecialChar ~
12979 ; save used registers here.
12980
12981 \newline
12982 \SpecialChar ~
12983 \SpecialChar ~
12984 \SpecialChar ~
12985 \SpecialChar ~
12986 \SpecialChar ~
12987 \SpecialChar ~
12988 \SpecialChar ~
12989 \SpecialChar ~
12990 ; If we were still using r2,r3 we would have to push them here.
12991
12992 \newline
12993 ; if( head != (unsigned char)(tail-1) )
12994 \newline
12995 \SpecialChar ~
12996 \SpecialChar ~
12997 \SpecialChar ~
12998 \SpecialChar ~
12999 \SpecialChar ~
13000 \SpecialChar ~
13001 \SpecialChar ~
13002 \SpecialChar ~
13003 mov\SpecialChar ~
13004  a,_tail
13005 \newline
13006 \SpecialChar ~
13007 \SpecialChar ~
13008 \SpecialChar ~
13009 \SpecialChar ~
13010 \SpecialChar ~
13011 \SpecialChar ~
13012 \SpecialChar ~
13013 \SpecialChar ~
13014 dec\SpecialChar ~
13015  a
13016 \newline
13017 \SpecialChar ~
13018 \SpecialChar ~
13019 \SpecialChar ~
13020 \SpecialChar ~
13021 \SpecialChar ~
13022 \SpecialChar ~
13023 \SpecialChar ~
13024 \SpecialChar ~
13025 xrl\SpecialChar ~
13026  a,_head
13027 \newline
13028 \SpecialChar ~
13029 \SpecialChar ~
13030 \SpecialChar ~
13031 \SpecialChar ~
13032 \SpecialChar ~
13033 \SpecialChar ~
13034 \SpecialChar ~
13035 \SpecialChar ~
13036 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
13037 \newline
13038 \SpecialChar ~
13039 \SpecialChar ~
13040 \SpecialChar ~
13041 \SpecialChar ~
13042 \SpecialChar ~
13043 \SpecialChar ~
13044 \SpecialChar ~
13045 \SpecialChar ~
13046 jz\SpecialChar ~
13047 \SpecialChar ~
13048  t_b_end$
13049 \newline
13050 \SpecialChar ~
13051 \SpecialChar ~
13052 \SpecialChar ~
13053 \SpecialChar ~
13054 \SpecialChar ~
13055 \SpecialChar ~
13056 \SpecialChar ~
13057 \SpecialChar ~
13058 ;
13059 \newline
13060 ; buf[ head++ ] = c;
13061 \newline
13062 \SpecialChar ~
13063 \SpecialChar ~
13064 \SpecialChar ~
13065 \SpecialChar ~
13066 \SpecialChar ~
13067 \SpecialChar ~
13068 \SpecialChar ~
13069 \SpecialChar ~
13070 mov\SpecialChar ~
13071  a,dpl \SpecialChar ~
13072 \SpecialChar ~
13073 \SpecialChar ~
13074 \SpecialChar ~
13075 \SpecialChar ~
13076 \SpecialChar ~
13077 \SpecialChar ~
13078 ; dpl holds lower byte of function argument
13079 \newline
13080 \SpecialChar ~
13081 \SpecialChar ~
13082 \SpecialChar ~
13083 \SpecialChar ~
13084 \SpecialChar ~
13085 \SpecialChar ~
13086 \SpecialChar ~
13087 \SpecialChar ~
13088 mov\SpecialChar ~
13089  dpl,_head \SpecialChar ~
13090 \SpecialChar ~
13091 \SpecialChar ~
13092 ; buf is 0x100 byte aligned so head can be used directly
13093 \newline
13094 \SpecialChar ~
13095 \SpecialChar ~
13096 \SpecialChar ~
13097 \SpecialChar ~
13098 \SpecialChar ~
13099 \SpecialChar ~
13100 \SpecialChar ~
13101 \SpecialChar ~
13102 mov\SpecialChar ~
13103  dph,#(_buf>>8)
13104 \newline
13105 \SpecialChar ~
13106 \SpecialChar ~
13107 \SpecialChar ~
13108 \SpecialChar ~
13109 \SpecialChar ~
13110 \SpecialChar ~
13111 \SpecialChar ~
13112 \SpecialChar ~
13113 movx @dptr,a
13114 \newline
13115 \SpecialChar ~
13116 \SpecialChar ~
13117 \SpecialChar ~
13118 \SpecialChar ~
13119 \SpecialChar ~
13120 \SpecialChar ~
13121 \SpecialChar ~
13122 \SpecialChar ~
13123 inc \SpecialChar ~
13124 _head
13125 \newline
13126 \SpecialChar ~
13127 \SpecialChar ~
13128 \SpecialChar ~
13129 \SpecialChar ~
13130 \SpecialChar ~
13131 \SpecialChar ~
13132 \SpecialChar ~
13133 \SpecialChar ~
13134 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
13135 \newline
13136 t_b_end$:
13137 \newline
13138 \SpecialChar ~
13139 \SpecialChar ~
13140 \SpecialChar ~
13141 \SpecialChar ~
13142 \SpecialChar ~
13143 \SpecialChar ~
13144 \SpecialChar ~
13145 \SpecialChar ~
13146 ; restore used registers here
13147 \newline
13148 \SpecialChar ~
13149 \SpecialChar ~
13150 \SpecialChar ~
13151 \SpecialChar ~
13152 _endasm
13153 \begin_inset LatexCommand \index{\_endasm}
13154
13155 \end_inset
13156
13157
13158 \begin_inset LatexCommand \index{\_\_endasm}
13159
13160 \end_inset
13161
13162 ;
13163 \newline
13164 }
13165 \newline
13166 #endif
13167 \layout Standard
13168
13169 The inline assembler code can contain any valid code understood by the assembler
13170 , this includes any assembler directives and comment lines
13171 \begin_inset Foot
13172 collapsed false
13173
13174 \layout Standard
13175
13176 The assembler does not like some characters like ':' or ''' in comments.
13177  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
13178 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
13179
13180 \end_inset
13181
13182
13183 \begin_inset LatexCommand \index{Assembler documentation}
13184
13185 \end_inset
13186
13187
13188 \end_inset
13189
13190 .
13191  The compiler does not do any validation of the code within the
13192 \family typewriter
13193 _asm
13194 \begin_inset LatexCommand \index{\_asm}
13195
13196 \end_inset
13197
13198
13199 \begin_inset LatexCommand \index{\_\_asm}
13200
13201 \end_inset
13202
13203  ...
13204  _endasm
13205 \size footnotesize
13206
13207 \begin_inset LatexCommand \index{\_endasm}
13208
13209 \end_inset
13210
13211
13212 \begin_inset LatexCommand \index{\_\_endasm}
13213
13214 \end_inset
13215
13216
13217 \size default
13218 ;
13219 \family default
13220  keyword pair.
13221  Specifically it will not know which registers are used and thus register
13222  pushing/popping
13223 \begin_inset LatexCommand \index{push/pop}
13224
13225 \end_inset
13226
13227  has to be done manually.
13228
13229 \layout Standard
13230
13231 It is recommended that each assembly instruction (including labels) be placed
13232  in a separate line (as the example shows).
13233  When the -
13234 \begin_inset ERT
13235 status Collapsed
13236
13237 \layout Standard
13238
13239 \backslash
13240 /
13241 \end_inset
13242
13243 -
13244 \emph on
13245 peep-asm
13246 \begin_inset LatexCommand \index{-\/-peep-asm}
13247
13248 \end_inset
13249
13250
13251 \emph default
13252  command line option is used, the inline assembler code will be passed through
13253  the peephole optimizer
13254 \begin_inset LatexCommand \index{Peephole optimizer}
13255
13256 \end_inset
13257
13258 .
13259  There are only a few (if any) cases where this option makes sense, it might
13260  cause some unexpected changes in the inline assembler code.
13261  Please go through the peephole optimizer rules defined in file
13262 \emph on
13263 SDCCpeeph.def
13264 \emph default
13265  before using this option.
13266 \layout Subsection
13267
13268 Naked Functions
13269 \begin_inset LatexCommand \label{sub:Naked-Functions}
13270
13271 \end_inset
13272
13273
13274 \begin_inset LatexCommand \index{Naked functions}
13275
13276 \end_inset
13277
13278
13279 \layout Standard
13280
13281 A special keyword may be associated with a function declaring it as
13282 \emph on
13283 _naked
13284 \begin_inset LatexCommand \index{\_naked}
13285
13286 \end_inset
13287
13288
13289 \begin_inset LatexCommand \index{\_\_naked}
13290
13291 \end_inset
13292
13293 .
13294
13295 \emph default
13296 The
13297 \emph on
13298 _naked
13299 \emph default
13300  function modifier attribute prevents the compiler from generating prologue
13301 \begin_inset LatexCommand \index{function prologue}
13302
13303 \end_inset
13304
13305  and epilogue
13306 \begin_inset LatexCommand \index{function epilogue}
13307
13308 \end_inset
13309
13310  code for that function.
13311  This means that the user is entirely responsible for such things as saving
13312  any registers that may need to be preserved, selecting the proper register
13313  bank, generating the
13314 \emph on
13315 return
13316 \emph default
13317  instruction at the end, etc.
13318  Practically, this means that the contents of the function must be written
13319  in inline assembler.
13320  This is particularly useful for interrupt functions, which can have a large
13321  (and often unnecessary) prologue/epilogue.
13322  For example, compare the code generated by these two functions:
13323 \layout Verse
13324
13325
13326 \family typewriter
13327 volatile
13328 \begin_inset LatexCommand \index{volatile}
13329
13330 \end_inset
13331
13332  data unsigned char counter;
13333 \newline
13334
13335 \newline
13336 void simpleInterrupt(void) __interrupt
13337 \begin_inset LatexCommand \index{interrupt}
13338
13339 \end_inset
13340
13341
13342 \begin_inset LatexCommand \index{\_\_interrupt}
13343
13344 \end_inset
13345
13346  (1)
13347 \newline
13348 {
13349 \newline
13350 \SpecialChar ~
13351 \SpecialChar ~
13352 \SpecialChar ~
13353 \SpecialChar ~
13354 counter++;
13355 \newline
13356 }
13357 \newline
13358
13359 \newline
13360 void nakedInterrupt(void) __interrupt (2) __naked
13361 \newline
13362 {
13363 \newline
13364 \SpecialChar ~
13365 \SpecialChar ~
13366 \SpecialChar ~
13367 \SpecialChar ~
13368 _asm
13369 \begin_inset LatexCommand \index{\_asm}
13370
13371 \end_inset
13372
13373
13374 \begin_inset LatexCommand \index{\_\_asm}
13375
13376 \end_inset
13377
13378
13379 \newline
13380 \SpecialChar ~
13381 \SpecialChar ~
13382 \SpecialChar ~
13383 \SpecialChar ~
13384 \SpecialChar ~
13385 \SpecialChar ~
13386 inc\SpecialChar ~
13387 \SpecialChar ~
13388 \SpecialChar ~
13389 \SpecialChar ~
13390 \SpecialChar ~
13391 _counter ; does not change flags, no need to save psw
13392 \newline
13393 \SpecialChar ~
13394 \SpecialChar ~
13395 \SpecialChar ~
13396 \SpecialChar ~
13397 \SpecialChar ~
13398 \SpecialChar ~
13399 reti\SpecialChar ~
13400 \SpecialChar ~
13401 \SpecialChar ~
13402 \SpecialChar ~
13403 ; MUST explicitly include ret or reti in _naked function.
13404 \newline
13405 \SpecialChar ~
13406 \SpecialChar ~
13407 \SpecialChar ~
13408 \SpecialChar ~
13409 _endasm
13410 \begin_inset LatexCommand \index{\_endasm}
13411
13412 \end_inset
13413
13414
13415 \begin_inset LatexCommand \index{\_\_endasm}
13416
13417 \end_inset
13418
13419 ;
13420 \newline
13421 }
13422 \layout Standard
13423
13424 For an 8051 target, the generated simpleInterrupt looks like:
13425 \layout Verse
13426
13427
13428 \family typewriter
13429 Note, this is an
13430 \series bold
13431 outdated
13432 \series default
13433  example, recent versions of SDCC generate
13434 \newline
13435 the same code for simpleInterrupt() and nakedInterrupt()!
13436 \newline
13437
13438 \newline
13439 _simpleInterrupt:
13440 \newline
13441 \SpecialChar ~
13442 \SpecialChar ~
13443 \SpecialChar ~
13444 \SpecialChar ~
13445 push\SpecialChar ~
13446 \SpecialChar ~
13447 \SpecialChar ~
13448 \SpecialChar ~
13449 acc
13450 \newline
13451 \SpecialChar ~
13452 \SpecialChar ~
13453 \SpecialChar ~
13454 \SpecialChar ~
13455 push\SpecialChar ~
13456 \SpecialChar ~
13457 \SpecialChar ~
13458 \SpecialChar ~
13459 b
13460 \newline
13461 \SpecialChar ~
13462 \SpecialChar ~
13463 \SpecialChar ~
13464 \SpecialChar ~
13465 push\SpecialChar ~
13466 \SpecialChar ~
13467 \SpecialChar ~
13468 \SpecialChar ~
13469 dpl
13470 \newline
13471 \SpecialChar ~
13472 \SpecialChar ~
13473 \SpecialChar ~
13474 \SpecialChar ~
13475 push\SpecialChar ~
13476 \SpecialChar ~
13477 \SpecialChar ~
13478 \SpecialChar ~
13479 dph
13480 \newline
13481 \SpecialChar ~
13482 \SpecialChar ~
13483 \SpecialChar ~
13484 \SpecialChar ~
13485 push\SpecialChar ~
13486 \SpecialChar ~
13487 \SpecialChar ~
13488 \SpecialChar ~
13489 psw
13490 \newline
13491 \SpecialChar ~
13492 \SpecialChar ~
13493 \SpecialChar ~
13494 \SpecialChar ~
13495 mov\SpecialChar ~
13496 \SpecialChar ~
13497 \SpecialChar ~
13498 \SpecialChar ~
13499 \SpecialChar ~
13500 psw,#0x00
13501 \newline
13502 \SpecialChar ~
13503 \SpecialChar ~
13504 \SpecialChar ~
13505 \SpecialChar ~
13506 inc\SpecialChar ~
13507 \SpecialChar ~
13508 \SpecialChar ~
13509 \SpecialChar ~
13510 \SpecialChar ~
13511 _counter
13512 \newline
13513 \SpecialChar ~
13514 \SpecialChar ~
13515 \SpecialChar ~
13516 \SpecialChar ~
13517 pop\SpecialChar ~
13518 \SpecialChar ~
13519 \SpecialChar ~
13520 \SpecialChar ~
13521 \SpecialChar ~
13522 psw
13523 \newline
13524 \SpecialChar ~
13525 \SpecialChar ~
13526 \SpecialChar ~
13527 \SpecialChar ~
13528 pop\SpecialChar ~
13529 \SpecialChar ~
13530 \SpecialChar ~
13531 \SpecialChar ~
13532 \SpecialChar ~
13533 dph
13534 \newline
13535 \SpecialChar ~
13536 \SpecialChar ~
13537 \SpecialChar ~
13538 \SpecialChar ~
13539 pop\SpecialChar ~
13540 \SpecialChar ~
13541 \SpecialChar ~
13542 \SpecialChar ~
13543 \SpecialChar ~
13544 dpl
13545 \newline
13546 \SpecialChar ~
13547 \SpecialChar ~
13548 \SpecialChar ~
13549 \SpecialChar ~
13550 pop\SpecialChar ~
13551 \SpecialChar ~
13552 \SpecialChar ~
13553 \SpecialChar ~
13554 \SpecialChar ~
13555 b
13556 \newline
13557 \SpecialChar ~
13558 \SpecialChar ~
13559 \SpecialChar ~
13560 \SpecialChar ~
13561 pop\SpecialChar ~
13562 \SpecialChar ~
13563 \SpecialChar ~
13564 \SpecialChar ~
13565 \SpecialChar ~
13566 acc
13567 \newline
13568 \SpecialChar ~
13569 \SpecialChar ~
13570 \SpecialChar ~
13571 \SpecialChar ~
13572 reti
13573 \layout Standard
13574
13575 whereas nakedInterrupt looks like:
13576 \layout Verse
13577
13578
13579 \family typewriter
13580 _nakedInterrupt:
13581 \newline
13582 \SpecialChar ~
13583 \SpecialChar ~
13584 \SpecialChar ~
13585 \SpecialChar ~
13586 inc\SpecialChar ~
13587 \SpecialChar ~
13588 \SpecialChar ~
13589 \SpecialChar ~
13590 _counter ; does not change flags, no need to save psw
13591 \newline
13592 \SpecialChar ~
13593 \SpecialChar ~
13594 \SpecialChar ~
13595 \SpecialChar ~
13596 reti\SpecialChar ~
13597 \SpecialChar ~
13598 \SpecialChar ~
13599 \SpecialChar ~
13600 \SpecialChar ~
13601 \SpecialChar ~
13602 \SpecialChar ~
13603 \SpecialChar ~
13604 \SpecialChar ~
13605 \SpecialChar ~
13606 \SpecialChar ~
13607 \SpecialChar ~
13608 ; MUST explicitly include ret or reti in _naked function
13609 \layout Standard
13610
13611 The related directive #pragma exclude
13612 \begin_inset LatexCommand \index{\#pragma exclude}
13613
13614 \end_inset
13615
13616  allows a more fine grained control over pushing & popping
13617 \begin_inset LatexCommand \index{push/pop}
13618
13619 \end_inset
13620
13621  the registers.
13622 \layout Standard
13623
13624 While there is nothing preventing you from writing C code inside a
13625 \family typewriter
13626 _naked
13627 \family default
13628  function, there are many ways to shoot yourself in the foot doing this,
13629  and it is recommended that you stick to inline assembler.
13630 \layout Subsection
13631
13632 Use of Labels within Inline Assembler
13633 \layout Standard
13634
13635 SDCC allows the use of in-line assembler with a few restrictions regarding
13636  labels.
13637  In older versions of the compiler all labels defined within inline assembler
13638  code
13639 \emph on
13640 had to be
13641 \emph default
13642  of the form
13643 \emph on
13644 nnnnn$
13645 \emph default
13646  where nnnn is a number less than 100 (which implies a limit of utmost 100
13647  inline assembler labels
13648 \emph on
13649 per function
13650 \emph default
13651 \noun on
13652 )
13653 \noun default
13654 .
13655
13656 \layout Verse
13657
13658
13659 \family typewriter
13660 _asm
13661 \begin_inset LatexCommand \index{\_asm}
13662
13663 \end_inset
13664
13665
13666 \begin_inset LatexCommand \index{\_\_asm}
13667
13668 \end_inset
13669
13670
13671 \newline
13672 \SpecialChar ~
13673 \SpecialChar ~
13674 \SpecialChar ~
13675 \SpecialChar ~
13676 mov\SpecialChar ~
13677 \SpecialChar ~
13678 \SpecialChar ~
13679 \SpecialChar ~
13680 \SpecialChar ~
13681 b,#10
13682 \newline
13683 00001$:
13684 \newline
13685 \SpecialChar ~
13686 \SpecialChar ~
13687 \SpecialChar ~
13688 \SpecialChar ~
13689 djnz\SpecialChar ~
13690 \SpecialChar ~
13691 \SpecialChar ~
13692 \SpecialChar ~
13693 b,00001$
13694 \newline
13695 _endasm
13696 \begin_inset LatexCommand \index{\_endasm}
13697
13698 \end_inset
13699
13700
13701 \begin_inset LatexCommand \index{\_\_endasm}
13702
13703 \end_inset
13704
13705  ;
13706 \layout Standard
13707
13708 Inline assembler code cannot reference any C-Labels, however it can reference
13709  labels
13710 \begin_inset LatexCommand \index{Labels}
13711
13712 \end_inset
13713
13714  defined by the inline assembler, e.g.:
13715 \layout Verse
13716
13717
13718 \family typewriter
13719 foo() {
13720 \newline
13721 \SpecialChar ~
13722 \SpecialChar ~
13723 \SpecialChar ~
13724 \SpecialChar ~
13725 /* some c code */
13726 \newline
13727 \SpecialChar ~
13728 \SpecialChar ~
13729 \SpecialChar ~
13730 \SpecialChar ~
13731 _asm
13732 \newline
13733 \SpecialChar ~
13734 \SpecialChar ~
13735 \SpecialChar ~
13736 \SpecialChar ~
13737 \SpecialChar ~
13738 \SpecialChar ~
13739 ; some assembler code
13740 \newline
13741 \SpecialChar ~
13742 \SpecialChar ~
13743 \SpecialChar ~
13744 \SpecialChar ~
13745 \SpecialChar ~
13746 \SpecialChar ~
13747 ljmp $0003
13748 \newline
13749 \SpecialChar ~
13750 \SpecialChar ~
13751 \SpecialChar ~
13752 \SpecialChar ~
13753 _endasm;
13754 \newline
13755 \SpecialChar ~
13756 \SpecialChar ~
13757 \SpecialChar ~
13758 \SpecialChar ~
13759 /* some more c code */
13760 \newline
13761 clabel:\SpecialChar ~
13762 \SpecialChar ~
13763 /* inline assembler cannot reference this label */
13764 \newline
13765 \SpecialChar ~
13766 \SpecialChar ~
13767 \SpecialChar ~
13768 \SpecialChar ~
13769 _asm
13770 \newline
13771 \SpecialChar ~
13772 \SpecialChar ~
13773 \SpecialChar ~
13774 \SpecialChar ~
13775 $0003: ;label (can be referenced by inline assembler only)
13776 \newline
13777 \SpecialChar ~
13778 \SpecialChar ~
13779 \SpecialChar ~
13780 \SpecialChar ~
13781 _endasm
13782 \begin_inset LatexCommand \index{\_endasm}
13783
13784 \end_inset
13785
13786
13787 \begin_inset LatexCommand \index{\_\_endasm}
13788
13789 \end_inset
13790
13791  ;
13792 \newline
13793 \SpecialChar ~
13794 \SpecialChar ~
13795 \SpecialChar ~
13796 \SpecialChar ~
13797 /* some more c code */
13798 \newline
13799 }
13800 \layout Standard
13801
13802 In other words inline assembly code can access labels defined in inline
13803  assembly within the scope of the function.
13804  The same goes the other way, i.e.
13805  labels defines in inline assembly can not be accessed by C statements.
13806 \layout Section
13807
13808 Interfacing with Assembler Code
13809 \begin_inset LatexCommand \index{Assembler routines}
13810
13811 \end_inset
13812
13813
13814 \layout Subsection
13815
13816 Global Registers used for Parameter Passing
13817 \begin_inset LatexCommand \index{Parameter passing}
13818
13819 \end_inset
13820
13821
13822 \layout Standard
13823
13824 The compiler always uses the global registers
13825 \emph on
13826 DPL, DPH
13827 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
13828
13829 \end_inset
13830
13831
13832 \begin_inset LatexCommand \index{DPTR}
13833
13834 \end_inset
13835
13836 , B
13837 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
13838
13839 \end_inset
13840
13841
13842 \emph default
13843 and
13844 \emph on
13845  ACC
13846 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
13847
13848 \end_inset
13849
13850
13851 \emph default
13852  to pass the first parameter to a routine.
13853  The second parameter onwards is either allocated on the stack (for reentrant
13854  routines or if -
13855 \begin_inset ERT
13856 status Collapsed
13857
13858 \layout Standard
13859
13860 \backslash
13861 /
13862 \end_inset
13863
13864 -stack-auto is used) or in data / xdata memory (depending on the memory
13865  model).
13866
13867 \layout Subsection
13868
13869 Assembler Routine (non-reentrant)
13870 \layout Standard
13871
13872 In the following example
13873 \begin_inset LatexCommand \index{reentrant}
13874
13875 \end_inset
13876
13877
13878 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
13879
13880 \end_inset
13881
13882  the function c_func calls an assembler routine asm_func, which takes two
13883  parameters
13884 \begin_inset LatexCommand \index{function parameter}
13885
13886 \end_inset
13887
13888 .
13889 \layout Verse
13890
13891
13892 \family typewriter
13893 extern int asm_func(unsigned char, unsigned char);
13894 \newline
13895
13896 \newline
13897 int c_func (unsigned char i, unsigned char j)
13898 \newline
13899 {
13900 \newline
13901 \SpecialChar ~
13902 \SpecialChar ~
13903 \SpecialChar ~
13904 \SpecialChar ~
13905 return asm_func(i,j);
13906 \newline
13907 }
13908 \newline
13909
13910 \newline
13911 int main()
13912 \newline
13913 {
13914 \newline
13915 \SpecialChar ~
13916 \SpecialChar ~
13917 \SpecialChar ~
13918 \SpecialChar ~
13919 return c_func(10,9);
13920 \newline
13921 }
13922 \layout Standard
13923
13924 The corresponding assembler function is:
13925 \layout Verse
13926
13927
13928 \family typewriter
13929 .globl _asm_func_PARM_2
13930 \newline
13931 \SpecialChar ~
13932 \SpecialChar ~
13933 \SpecialChar ~
13934 \SpecialChar ~
13935 \SpecialChar ~
13936 \SpecialChar ~
13937 \SpecialChar ~
13938 \SpecialChar ~
13939 .globl _asm_func
13940 \newline
13941 \SpecialChar ~
13942 \SpecialChar ~
13943 \SpecialChar ~
13944 \SpecialChar ~
13945 \SpecialChar ~
13946 \SpecialChar ~
13947 \SpecialChar ~
13948 \SpecialChar ~
13949 .area OSEG
13950 \newline
13951 _asm_func_PARM_2:
13952 \newline
13953 \SpecialChar ~
13954 \SpecialChar ~
13955 \SpecialChar ~
13956 \SpecialChar ~
13957 \SpecialChar ~
13958 \SpecialChar ~
13959 \SpecialChar ~
13960 \SpecialChar ~
13961 .ds    1
13962 \newline
13963 \SpecialChar ~
13964 \SpecialChar ~
13965 \SpecialChar ~
13966 \SpecialChar ~
13967 \SpecialChar ~
13968 \SpecialChar ~
13969 \SpecialChar ~
13970 \SpecialChar ~
13971 .area CSEG
13972 \newline
13973 _asm_func:
13974 \newline
13975 \SpecialChar ~
13976 \SpecialChar ~
13977 \SpecialChar ~
13978 \SpecialChar ~
13979 \SpecialChar ~
13980 \SpecialChar ~
13981 \SpecialChar ~
13982 \SpecialChar ~
13983 mov\SpecialChar ~
13984 \SpecialChar ~
13985 \SpecialChar ~
13986 \SpecialChar ~
13987 a,dpl
13988 \newline
13989 \SpecialChar ~
13990 \SpecialChar ~
13991 \SpecialChar ~
13992 \SpecialChar ~
13993 \SpecialChar ~
13994 \SpecialChar ~
13995 \SpecialChar ~
13996 \SpecialChar ~
13997 add\SpecialChar ~
13998 \SpecialChar ~
13999 \SpecialChar ~
14000 \SpecialChar ~
14001 a,_asm_func_PARM_2
14002 \newline
14003 \SpecialChar ~
14004 \SpecialChar ~
14005 \SpecialChar ~
14006 \SpecialChar ~
14007 \SpecialChar ~
14008 \SpecialChar ~
14009 \SpecialChar ~
14010 \SpecialChar ~
14011 mov\SpecialChar ~
14012 \SpecialChar ~
14013 \SpecialChar ~
14014 \SpecialChar ~
14015 dpl,a
14016 \newline
14017 \SpecialChar ~
14018 \SpecialChar ~
14019 \SpecialChar ~
14020 \SpecialChar ~
14021 \SpecialChar ~
14022 \SpecialChar ~
14023 \SpecialChar ~
14024 \SpecialChar ~
14025 mov\SpecialChar ~
14026 \SpecialChar ~
14027 \SpecialChar ~
14028 \SpecialChar ~
14029 dph
14030 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
14031
14032 \end_inset
14033
14034 ,#0x00
14035 \newline
14036 \SpecialChar ~
14037 \SpecialChar ~
14038 \SpecialChar ~
14039 \SpecialChar ~
14040 \SpecialChar ~
14041 \SpecialChar ~
14042 \SpecialChar ~
14043 \SpecialChar ~
14044 ret
14045 \layout Standard
14046
14047 Note here that the return values
14048 \begin_inset LatexCommand \index{return value}
14049
14050 \end_inset
14051
14052  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
14053  two byte values.
14054  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
14055 b' & 'acc' for four byte values.
14056 \layout Standard
14057
14058 The parameter naming convention is _<function_name>_PARM_<n>, where n is
14059  the parameter number starting from 1, and counting from the left.
14060  The first parameter is passed in
14061 \begin_inset Quotes eld
14062 \end_inset
14063
14064 dpl
14065 \begin_inset Quotes erd
14066 \end_inset
14067
14068  for a one byte parameter,
14069 \begin_inset Quotes eld
14070 \end_inset
14071
14072 dptr
14073 \begin_inset Quotes erd
14074 \end_inset
14075
14076  for two bytes,
14077 \begin_inset Quotes eld
14078 \end_inset
14079
14080 b,dptr
14081 \begin_inset Quotes erd
14082 \end_inset
14083
14084  for three bytes and
14085 \begin_inset Quotes eld
14086 \end_inset
14087
14088 acc,b,dptr
14089 \begin_inset Quotes erd
14090 \end_inset
14091
14092  for a four bytes parameter.
14093  The variable name for the second parameter will be _<function_name>_PARM_2.
14094 \newline
14095
14096 \newline
14097 Assemble the assembler routine with the following command:
14098 \newline
14099
14100 \newline
14101
14102 \family sans
14103 \series bold
14104 asx8051 -losg asmfunc.asm
14105 \newline
14106
14107 \newline
14108
14109 \family default
14110 \series default
14111 Then compile and link the assembler routine to the C source file with the
14112  following command:
14113 \newline
14114
14115 \newline
14116
14117 \family sans
14118 \series bold
14119 sdcc cfunc.c asmfunc.rel
14120 \layout Subsection
14121
14122 Assembler Routine (reentrant)
14123 \layout Standard
14124
14125 In this case
14126 \begin_inset LatexCommand \index{reentrant}
14127
14128 \end_inset
14129
14130
14131 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
14132
14133 \end_inset
14134
14135  the second parameter
14136 \begin_inset LatexCommand \index{function parameter}
14137
14138 \end_inset
14139
14140  onwards will be passed on the stack, the parameters are pushed from right
14141  to left i.e.
14142  after the call the leftmost parameter will be on the top of the stack.
14143  Here is an example:
14144 \layout Verse
14145
14146
14147 \family typewriter
14148 extern int asm_func(unsigned char, unsigned char);
14149 \newline
14150
14151 \newline
14152 int c_func (unsigned char i, unsigned char j) reentrant
14153 \newline
14154 {
14155 \newline
14156 \SpecialChar ~
14157 \SpecialChar ~
14158 \SpecialChar ~
14159 \SpecialChar ~
14160 return asm_func(i,j);
14161 \newline
14162 }
14163 \newline
14164
14165 \newline
14166 int main()
14167 \newline
14168 {
14169 \newline
14170 \SpecialChar ~
14171 \SpecialChar ~
14172 \SpecialChar ~
14173 \SpecialChar ~
14174 return c_func(10,9);
14175 \newline
14176 }
14177 \layout Standard
14178
14179 The corresponding assembler routine is:
14180 \layout Verse
14181
14182
14183 \family typewriter
14184 .globl _asm_func
14185 \newline
14186 _asm_func:
14187 \newline
14188 \SpecialChar ~
14189 \SpecialChar ~
14190 \SpecialChar ~
14191 \SpecialChar ~
14192 push  _bp
14193 \newline
14194 \SpecialChar ~
14195 \SpecialChar ~
14196 \SpecialChar ~
14197 \SpecialChar ~
14198 mov _bp,sp
14199 \newline
14200 \SpecialChar ~
14201 \SpecialChar ~
14202 \SpecialChar ~
14203 \SpecialChar ~
14204 mov r2,dpl
14205 \newline
14206 \SpecialChar ~
14207 \SpecialChar ~
14208 \SpecialChar ~
14209 \SpecialChar ~
14210 mov a,_bp
14211 \newline
14212 \SpecialChar ~
14213 \SpecialChar ~
14214 \SpecialChar ~
14215 \SpecialChar ~
14216 add a,#0xfd
14217 \newline
14218 \SpecialChar ~
14219 \SpecialChar ~
14220 \SpecialChar ~
14221 \SpecialChar ~
14222 mov r0,a
14223 \newline
14224 \SpecialChar ~
14225 \SpecialChar ~
14226 \SpecialChar ~
14227 \SpecialChar ~
14228 add  a,#0xfc ;?
14229 \newline
14230 \SpecialChar ~
14231 \SpecialChar ~
14232 \SpecialChar ~
14233 \SpecialChar ~
14234 mov  r1,a
14235 \newline
14236 \SpecialChar ~
14237 \SpecialChar ~
14238 \SpecialChar ~
14239 \SpecialChar ~
14240 mov  a,@r0
14241 \newline
14242 \SpecialChar ~
14243 \SpecialChar ~
14244 \SpecialChar ~
14245 \SpecialChar ~
14246 add  a,r2 ;?
14247 \newline
14248 \SpecialChar ~
14249 \SpecialChar ~
14250 \SpecialChar ~
14251 \SpecialChar ~
14252 mov  dpl,a
14253 \newline
14254 \SpecialChar ~
14255 \SpecialChar ~
14256 \SpecialChar ~
14257 \SpecialChar ~
14258 mov  dph,#0x00
14259 \newline
14260 \SpecialChar ~
14261 \SpecialChar ~
14262 \SpecialChar ~
14263 \SpecialChar ~
14264 mov  sp,_bp
14265 \newline
14266 \SpecialChar ~
14267 \SpecialChar ~
14268 \SpecialChar ~
14269 \SpecialChar ~
14270 pop  _bp
14271 \newline
14272 \SpecialChar ~
14273 \SpecialChar ~
14274 \SpecialChar ~
14275 \SpecialChar ~
14276 ret
14277 \layout Standard
14278
14279 The compiling and linking procedure remains the same, however note the extra
14280  entry & exit linkage required for the assembler code, _bp is the stack
14281  frame pointer and is used to compute the offset into the stack for parameters
14282  and local variables.
14283 \layout Section
14284
14285 int (16 bit)
14286 \begin_inset LatexCommand \index{int (16 bit)}
14287
14288 \end_inset
14289
14290  and long (32 bit)
14291 \begin_inset LatexCommand \index{long (32 bit)}
14292
14293 \end_inset
14294
14295  Support
14296 \layout Standard
14297
14298 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
14299  multiplication and modulus operations are implemented by support routines.
14300  These support routines are all developed in ANSI-C to facilitate porting
14301  to other MCUs, although some model specific assembler optimizations are
14302  used.
14303  The following files contain the described routines, all of them can be
14304  found in <installdir>/share/sdcc/lib.
14305 \newline
14306
14307 \layout Standard
14308 \align center
14309
14310 \begin_inset  Tabular
14311 <lyxtabular version="3" rows="11" columns="2">
14312 <features>
14313 <column alignment="left" valignment="top" leftline="true" width="0">
14314 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
14315 <row topline="true" bottomline="true">
14316 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14317 \begin_inset Text
14318
14319 \layout Standard
14320
14321
14322 \series bold
14323 Function
14324 \end_inset
14325 </cell>
14326 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14327 \begin_inset Text
14328
14329 \layout Standard
14330
14331
14332 \series bold
14333 Description
14334 \end_inset
14335 </cell>
14336 </row>
14337 <row topline="true">
14338 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14339 \begin_inset Text
14340
14341 \layout Standard
14342
14343 _mulint.c
14344 \end_inset
14345 </cell>
14346 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14347 \begin_inset Text
14348
14349 \layout Standard
14350
14351 16 bit multiplication
14352 \end_inset
14353 </cell>
14354 </row>
14355 <row topline="true">
14356 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14357 \begin_inset Text
14358
14359 \layout Standard
14360
14361 _divsint.c
14362 \end_inset
14363 </cell>
14364 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14365 \begin_inset Text
14366
14367 \layout Standard
14368
14369  signed 16 bit division (calls _divuint)
14370 \end_inset
14371 </cell>
14372 </row>
14373 <row topline="true">
14374 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14375 \begin_inset Text
14376
14377 \layout Standard
14378
14379 _divuint.c
14380 \end_inset
14381 </cell>
14382 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14383 \begin_inset Text
14384
14385 \layout Standard
14386
14387  unsigned 16 bit division
14388 \end_inset
14389 </cell>
14390 </row>
14391 <row topline="true">
14392 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14393 \begin_inset Text
14394
14395 \layout Standard
14396
14397 _modsint.c
14398 \end_inset
14399 </cell>
14400 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14401 \begin_inset Text
14402
14403 \layout Standard
14404
14405 signed 16 bit modulus (calls _moduint)
14406 \end_inset
14407 </cell>
14408 </row>
14409 <row topline="true">
14410 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14411 \begin_inset Text
14412
14413 \layout Standard
14414
14415 _moduint.c
14416 \end_inset
14417 </cell>
14418 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14419 \begin_inset Text
14420
14421 \layout Standard
14422
14423 unsigned 16 bit modulus
14424 \end_inset
14425 </cell>
14426 </row>
14427 <row topline="true">
14428 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14429 \begin_inset Text
14430
14431 \layout Standard
14432
14433 _mullong.c
14434 \end_inset
14435 </cell>
14436 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14437 \begin_inset Text
14438
14439 \layout Standard
14440
14441 32 bit multiplication
14442 \end_inset
14443 </cell>
14444 </row>
14445 <row topline="true">
14446 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14447 \begin_inset Text
14448
14449 \layout Standard
14450
14451 _divslong.c
14452 \end_inset
14453 </cell>
14454 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14455 \begin_inset Text
14456
14457 \layout Standard
14458
14459  signed 32 division (calls _divulong)
14460 \end_inset
14461 </cell>
14462 </row>
14463 <row topline="true">
14464 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14465 \begin_inset Text
14466
14467 \layout Standard
14468
14469 _divulong.c
14470 \end_inset
14471 </cell>
14472 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14473 \begin_inset Text
14474
14475 \layout Standard
14476
14477 unsigned 32 division
14478 \end_inset
14479 </cell>
14480 </row>
14481 <row topline="true">
14482 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14483 \begin_inset Text
14484
14485 \layout Standard
14486
14487 _modslong.c
14488 \end_inset
14489 </cell>
14490 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14491 \begin_inset Text
14492
14493 \layout Standard
14494
14495  signed 32 bit modulus (calls _modulong)
14496 \end_inset
14497 </cell>
14498 </row>
14499 <row topline="true" bottomline="true">
14500 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14501 \begin_inset Text
14502
14503 \layout Standard
14504
14505 _modulong.c
14506 \end_inset
14507 </cell>
14508 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14509 \begin_inset Text
14510
14511 \layout Standard
14512
14513 unsigned 32 bit modulus
14514 \end_inset
14515 </cell>
14516 </row>
14517 </lyxtabular>
14518
14519 \end_inset
14520
14521
14522 \newline
14523
14524 \layout Standard
14525
14526 Since they are compiled as
14527 \emph on
14528 non-reentrant
14529 \emph default
14530
14531 \begin_inset LatexCommand \index{reentrant}
14532
14533 \end_inset
14534
14535 , interrupt
14536 \begin_inset LatexCommand \index{interrupt}
14537
14538 \end_inset
14539
14540  service routines should not do any of the above operations.
14541  If this is unavoidable then the above routines will need to be compiled
14542  with the
14543 \emph on
14544 -
14545 \begin_inset ERT
14546 status Collapsed
14547
14548 \layout Standard
14549
14550 \backslash
14551 /
14552 \end_inset
14553
14554 -stack-auto
14555 \begin_inset LatexCommand \index{-\/-stack-auto}
14556
14557 \end_inset
14558
14559
14560 \emph default
14561  option, after which the source program will have to be compiled with
14562 \emph on
14563 -
14564 \begin_inset ERT
14565 status Collapsed
14566
14567 \layout Standard
14568
14569 \backslash
14570 /
14571 \end_inset
14572
14573 -int-long-reent
14574 \begin_inset LatexCommand \index{-\/-int-long-reent}
14575
14576 \end_inset
14577
14578
14579 \emph default
14580  option.
14581  Notice that you don't have to call these routines directly.
14582  The compiler will use them automatically every time an integer operation
14583  is required.
14584 \layout Section
14585
14586 Floating Point Support
14587 \begin_inset LatexCommand \index{Floating point support}
14588
14589 \end_inset
14590
14591
14592 \layout Standard
14593
14594 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
14595  floating point support routines are derived from gcc's floatlib.c and consist
14596  of the following routines:
14597 \newline
14598
14599 \layout Standard
14600 \align center
14601
14602 \size footnotesize
14603
14604 \begin_inset  Tabular
14605 <lyxtabular version="3" rows="17" columns="2">
14606 <features>
14607 <column alignment="left" valignment="top" leftline="true" width="0">
14608 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
14609 <row topline="true" bottomline="true">
14610 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14611 \begin_inset Text
14612
14613 \layout Standard
14614
14615
14616 \family roman
14617 \series medium
14618 \shape up
14619 \size normal
14620 \emph off
14621 \bar no
14622 \noun off
14623 \color none
14624 Function
14625 \end_inset
14626 </cell>
14627 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14628 \begin_inset Text
14629
14630 \layout Standard
14631
14632 Description
14633 \end_inset
14634 </cell>
14635 </row>
14636 <row topline="true">
14637 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14638 \begin_inset Text
14639
14640 \layout Standard
14641
14642
14643 \family roman
14644 \series medium
14645 \shape up
14646 \size normal
14647 \emph off
14648 \bar no
14649 \noun off
14650 \color none
14651 _fsadd.c
14652 \end_inset
14653 </cell>
14654 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14655 \begin_inset Text
14656
14657 \layout Standard
14658
14659
14660 \family roman
14661 \series medium
14662 \shape up
14663 \size normal
14664 \emph off
14665 \bar no
14666 \noun off
14667 \color none
14668 add floating point numbers
14669 \end_inset
14670 </cell>
14671 </row>
14672 <row topline="true">
14673 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14674 \begin_inset Text
14675
14676 \layout Standard
14677
14678
14679 \family roman
14680 \series medium
14681 \shape up
14682 \size normal
14683 \emph off
14684 \bar no
14685 \noun off
14686 \color none
14687 _fssub.c
14688 \end_inset
14689 </cell>
14690 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14691 \begin_inset Text
14692
14693 \layout Standard
14694
14695
14696 \family roman
14697 \series medium
14698 \shape up
14699 \size normal
14700 \emph off
14701 \bar no
14702 \noun off
14703 \color none
14704 subtract floating point numbers
14705 \end_inset
14706 </cell>
14707 </row>
14708 <row topline="true">
14709 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14710 \begin_inset Text
14711
14712 \layout Standard
14713
14714
14715 \family roman
14716 \series medium
14717 \shape up
14718 \size normal
14719 \emph off
14720 \bar no
14721 \noun off
14722 \color none
14723 _fsdiv.c
14724 \end_inset
14725 </cell>
14726 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14727 \begin_inset Text
14728
14729 \layout Standard
14730
14731
14732 \family roman
14733 \series medium
14734 \shape up
14735 \size normal
14736 \emph off
14737 \bar no
14738 \noun off
14739 \color none
14740 divide floating point numbers
14741 \end_inset
14742 </cell>
14743 </row>
14744 <row topline="true">
14745 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14746 \begin_inset Text
14747
14748 \layout Standard
14749
14750
14751 \family roman
14752 \series medium
14753 \shape up
14754 \size normal
14755 \emph off
14756 \bar no
14757 \noun off
14758 \color none
14759 _fsmul.c
14760 \end_inset
14761 </cell>
14762 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14763 \begin_inset Text
14764
14765 \layout Standard
14766
14767
14768 \family roman
14769 \series medium
14770 \shape up
14771 \size normal
14772 \emph off
14773 \bar no
14774 \noun off
14775 \color none
14776 multiply floating point numbers
14777 \end_inset
14778 </cell>
14779 </row>
14780 <row topline="true">
14781 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14782 \begin_inset Text
14783
14784 \layout Standard
14785
14786
14787 \family roman
14788 \series medium
14789 \shape up
14790 \size normal
14791 \emph off
14792 \bar no
14793 \noun off
14794 \color none
14795 _fs2uchar.c
14796 \end_inset
14797 </cell>
14798 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14799 \begin_inset Text
14800
14801 \layout Standard
14802
14803
14804 \family roman
14805 \series medium
14806 \shape up
14807 \size normal
14808 \emph off
14809 \bar no
14810 \noun off
14811 \color none
14812 convert floating point to unsigned char
14813 \end_inset
14814 </cell>
14815 </row>
14816 <row topline="true">
14817 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14818 \begin_inset Text
14819
14820 \layout Standard
14821
14822
14823 \family roman
14824 \series medium
14825 \shape up
14826 \size normal
14827 \emph off
14828 \bar no
14829 \noun off
14830 \color none
14831 _fs2char.c
14832 \end_inset
14833 </cell>
14834 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14835 \begin_inset Text
14836
14837 \layout Standard
14838
14839
14840 \family roman
14841 \series medium
14842 \shape up
14843 \size normal
14844 \emph off
14845 \bar no
14846 \noun off
14847 \color none
14848 convert floating point to signed char
14849 \end_inset
14850 </cell>
14851 </row>
14852 <row topline="true">
14853 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14854 \begin_inset Text
14855
14856 \layout Standard
14857
14858
14859 \family roman
14860 \series medium
14861 \shape up
14862 \size normal
14863 \emph off
14864 \bar no
14865 \noun off
14866 \color none
14867 _fs2uint.c
14868 \end_inset
14869 </cell>
14870 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14871 \begin_inset Text
14872
14873 \layout Standard
14874
14875
14876 \family roman
14877 \series medium
14878 \shape up
14879 \size normal
14880 \emph off
14881 \bar no
14882 \noun off
14883 \color none
14884 convert floating point to unsigned int
14885 \end_inset
14886 </cell>
14887 </row>
14888 <row topline="true">
14889 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14890 \begin_inset Text
14891
14892 \layout Standard
14893
14894
14895 \family roman
14896 \series medium
14897 \shape up
14898 \size normal
14899 \emph off
14900 \bar no
14901 \noun off
14902 \color none
14903 _fs2int.c
14904 \end_inset
14905 </cell>
14906 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14907 \begin_inset Text
14908
14909 \layout Standard
14910
14911
14912 \family roman
14913 \series medium
14914 \shape up
14915 \size normal
14916 \emph off
14917 \bar no
14918 \noun off
14919 \color none
14920 convert floating point to signed int
14921 \end_inset
14922 </cell>
14923 </row>
14924 <row topline="true">
14925 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14926 \begin_inset Text
14927
14928 \layout Standard
14929
14930
14931 \family roman
14932 \series medium
14933 \shape up
14934 \size normal
14935 \emph off
14936 \bar no
14937 \noun off
14938 \color none
14939 _fs2ulong.
14940 \family default
14941 \series default
14942 \shape default
14943 \size default
14944 \emph default
14945 \bar default
14946 \noun default
14947 \color default
14948 c
14949 \end_inset
14950 </cell>
14951 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14952 \begin_inset Text
14953
14954 \layout Standard
14955
14956
14957 \family roman
14958 \series medium
14959 \shape up
14960 \size normal
14961 \emph off
14962 \bar no
14963 \noun off
14964 \color none
14965 convert floating point to unsigned long
14966 \end_inset
14967 </cell>
14968 </row>
14969 <row topline="true">
14970 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14971 \begin_inset Text
14972
14973 \layout Standard
14974
14975
14976 \family roman
14977 \series medium
14978 \shape up
14979 \size normal
14980 \emph off
14981 \bar no
14982 \noun off
14983 \color none
14984 _fs2long.c
14985 \end_inset
14986 </cell>
14987 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14988 \begin_inset Text
14989
14990 \layout Standard
14991
14992
14993 \family roman
14994 \series medium
14995 \shape up
14996 \size normal
14997 \emph off
14998 \bar no
14999 \noun off
15000 \color none
15001 convert floating point to signed long
15002 \end_inset
15003 </cell>
15004 </row>
15005 <row topline="true">
15006 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15007 \begin_inset Text
15008
15009 \layout Standard
15010
15011
15012 \family roman
15013 \series medium
15014 \shape up
15015 \size normal
15016 \emph off
15017 \bar no
15018 \noun off
15019 \color none
15020 _uchar2fs.c
15021 \end_inset
15022 </cell>
15023 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15024 \begin_inset Text
15025
15026 \layout Standard
15027
15028
15029 \family roman
15030 \series medium
15031 \shape up
15032 \size normal
15033 \emph off
15034 \bar no
15035 \noun off
15036 \color none
15037 convert unsigned char to floating point
15038 \end_inset
15039 </cell>
15040 </row>
15041 <row topline="true">
15042 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15043 \begin_inset Text
15044
15045 \layout Standard
15046
15047
15048 \family roman
15049 \series medium
15050 \shape up
15051 \size normal
15052 \emph off
15053 \bar no
15054 \noun off
15055 \color none
15056 _char2fs.c
15057 \end_inset
15058 </cell>
15059 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15060 \begin_inset Text
15061
15062 \layout Standard
15063
15064
15065 \family roman
15066 \series medium
15067 \shape up
15068 \size normal
15069 \emph off
15070 \bar no
15071 \noun off
15072 \color none
15073 convert char to floating point number
15074 \end_inset
15075 </cell>
15076 </row>
15077 <row topline="true">
15078 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15079 \begin_inset Text
15080
15081 \layout Standard
15082
15083
15084 \family roman
15085 \series medium
15086 \shape up
15087 \size normal
15088 \emph off
15089 \bar no
15090 \noun off
15091 \color none
15092 _uint2fs.c
15093 \end_inset
15094 </cell>
15095 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15096 \begin_inset Text
15097
15098 \layout Standard
15099
15100
15101 \family roman
15102 \series medium
15103 \shape up
15104 \size normal
15105 \emph off
15106 \bar no
15107 \noun off
15108 \color none
15109 convert unsigned int to floating point
15110 \end_inset
15111 </cell>
15112 </row>
15113 <row topline="true">
15114 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15115 \begin_inset Text
15116
15117 \layout Standard
15118
15119
15120 \family roman
15121 \series medium
15122 \shape up
15123 \size normal
15124 \emph off
15125 \bar no
15126 \noun off
15127 \color none
15128 _int2fs.c
15129 \end_inset
15130 </cell>
15131 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15132 \begin_inset Text
15133
15134 \layout Standard
15135
15136
15137 \family roman
15138 \series medium
15139 \shape up
15140 \size normal
15141 \emph off
15142 \bar no
15143 \noun off
15144 \color none
15145 convert int to floating point numbers
15146 \end_inset
15147 </cell>
15148 </row>
15149 <row topline="true">
15150 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15151 \begin_inset Text
15152
15153 \layout Standard
15154
15155
15156 \family roman
15157 \series medium
15158 \shape up
15159 \size normal
15160 \emph off
15161 \bar no
15162 \noun off
15163 \color none
15164 _ulong2fs.c
15165 \end_inset
15166 </cell>
15167 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15168 \begin_inset Text
15169
15170 \layout Standard
15171
15172
15173 \family roman
15174 \series medium
15175 \shape up
15176 \size normal
15177 \emph off
15178 \bar no
15179 \noun off
15180 \color none
15181 convert unsigned long to floating point number
15182 \end_inset
15183 </cell>
15184 </row>
15185 <row topline="true" bottomline="true">
15186 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15187 \begin_inset Text
15188
15189 \layout Standard
15190
15191
15192 \family roman
15193 \series medium
15194 \shape up
15195 \size normal
15196 \emph off
15197 \bar no
15198 \noun off
15199 \color none
15200 _long2fs.c
15201 \end_inset
15202 </cell>
15203 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15204 \begin_inset Text
15205
15206 \layout Standard
15207
15208
15209 \family roman
15210 \series medium
15211 \shape up
15212 \size normal
15213 \emph off
15214 \bar no
15215 \noun off
15216 \color none
15217 convert long to floating point number
15218 \end_inset
15219 </cell>
15220 </row>
15221 </lyxtabular>
15222
15223 \end_inset
15224
15225
15226 \newline
15227
15228 \layout Standard
15229
15230 These support routines are developed in ANSI-C so there is room for space
15231  and speed improvement
15232 \begin_inset Foot
15233 collapsed false
15234
15235 \layout Standard
15236
15237 These floating point routines (
15238 \emph on
15239 not
15240 \emph default
15241  sinf(), cosf(), ...) for the mcs51 are implemented in assembler.
15242
15243 \end_inset
15244
15245 .
15246  Note if all these routines are used simultaneously the data space might
15247  overflow.
15248  For serious floating point usage the large model might be needed.
15249  Also notice that you don't have to call this routines directly.
15250  The compiler will use them automatically every time a floating point operation
15251  is required.
15252 \layout Section
15253
15254 Library Routines
15255 \begin_inset LatexCommand \index{Libraries}
15256
15257 \end_inset
15258
15259
15260 \layout Standard
15261
15262
15263 \emph on
15264 <pending: this is messy and incomplete - a little more information is in
15265  sdcc/doc/libdoc.txt
15266 \emph default
15267  >
15268 \layout Subsection
15269
15270 Compiler support routines (_gptrget, _mulint etc.)
15271 \layout Subsection
15272
15273 Stdclib functions (puts, printf, strcat etc.)
15274 \layout Subsubsection
15275
15276 <stdio.h>
15277 \layout Standard
15278
15279
15280 \begin_inset LatexCommand \index{<stdio.h>}
15281
15282 \end_inset
15283
15284 As usual on embedded systems you have to provide your own
15285 \family typewriter
15286 getchar()
15287 \begin_inset LatexCommand \index{getchar()}
15288
15289 \end_inset
15290
15291
15292 \family default
15293 and
15294 \family typewriter
15295 putchar()
15296 \begin_inset LatexCommand \index{putchar()}
15297
15298 \end_inset
15299
15300
15301 \family default
15302  routines.
15303  SDCC does not know whether the system connects to a serial line with or
15304  without handshake, LCD, keyboard or other device.
15305  And whether a
15306 \family typewriter
15307 lf
15308 \family default
15309  to
15310 \family typewriter
15311 crlf
15312 \family default
15313  conversion within
15314 \family typewriter
15315 putchar()
15316 \family default
15317  is intended.
15318  You'll find examples for serial routines f.e.
15319  in sdcc/device/lib.
15320 \layout Standard
15321
15322 The default
15323 \family typewriter
15324  printf()
15325 \begin_inset LatexCommand \index{printf()}
15326
15327 \end_inset
15328
15329
15330 \family default
15331 implementation in
15332 \family typewriter
15333  printf_large.c
15334 \family default
15335  does not support float (except on ds390).
15336  To enable this recompile it with the option
15337 \emph on
15338 -
15339 \begin_inset ERT
15340 status Collapsed
15341
15342 \layout Standard
15343
15344 \backslash
15345 /
15346 \end_inset
15347
15348 DUSE_FLOATS=1
15349 \begin_inset LatexCommand \index{USE\_FLOATS}
15350
15351 \end_inset
15352
15353
15354 \emph default
15355  on the command line.
15356  Use
15357 \emph on
15358  -
15359 \begin_inset ERT
15360 status Collapsed
15361
15362 \layout Standard
15363
15364 \backslash
15365 /
15366 \end_inset
15367
15368 -model-large
15369 \begin_inset LatexCommand \index{-\/-model-large}
15370
15371 \end_inset
15372
15373
15374 \emph default
15375  for the mcs51 port, since this uses a lot of memory.
15376 \layout Standard
15377
15378 If you're short on memory you might want to use
15379 \family typewriter
15380 printf_small()
15381 \begin_inset LatexCommand \index{printf\_small()}
15382
15383 \end_inset
15384
15385
15386 \family default
15387
15388 \emph on
15389 instead
15390 \emph default
15391  of
15392 \family typewriter
15393  printf().
15394
15395 \family default
15396  For the mcs51 there additionally are assembly versions
15397 \family typewriter
15398 printf_tiny()
15399 \begin_inset LatexCommand \index{printf\_tiny() (mcs51)}
15400
15401 \end_inset
15402
15403
15404 \family default
15405  (subset of printf using less than 270 bytes) and
15406 \family typewriter
15407 printf_fast()
15408 \begin_inset LatexCommand \index{printf\_fast() (mcs51)}
15409
15410 \end_inset
15411
15412
15413 \family default
15414 and
15415 \family typewriter
15416  printf_fast_f()
15417 \begin_inset LatexCommand \index{printf\_fast\_f() (mcs51)}
15418
15419 \end_inset
15420
15421
15422 \family default
15423  (floating-point aware version of printf_fast) which should fit the requirements
15424  of many embedded systems (printf_fast() can be customized by unsetting
15425  #defines to
15426 \emph on
15427 not
15428 \emph default
15429  support long variables and field widths).
15430 \layout Subsubsection
15431
15432 <malloc.h>
15433 \begin_inset LatexCommand \index{malloc.h}
15434
15435 \end_inset
15436
15437
15438 \layout Standard
15439
15440 Before using dynamic
15441 \begin_inset LatexCommand \index{dynamic}
15442
15443 \end_inset
15444
15445  memory allocation with SDCC, you have to provide heap
15446 \begin_inset LatexCommand \index{heap}
15447
15448 \end_inset
15449
15450  space for malloc to allocate memory from
15451 \family typewriter
15452 .
15453
15454 \family default
15455 You can acomplish this by including the following code into your source:
15456 \layout Verse
15457
15458
15459 \family typewriter
15460 #include <malloc.h>
15461 \begin_inset LatexCommand \index{malloc.h}
15462
15463 \end_inset
15464
15465  /* calloc
15466 \begin_inset LatexCommand \index{calloc}
15467
15468 \end_inset
15469
15470 , malloc
15471 \begin_inset LatexCommand \index{malloc}
15472
15473 \end_inset
15474
15475 , realloc
15476 \begin_inset LatexCommand \index{realloc}
15477
15478 \end_inset
15479
15480 , and free
15481 \begin_inset LatexCommand \index{free}
15482
15483 \end_inset
15484
15485  */
15486 \newline
15487
15488 \newline
15489 #define HEAPSIZE 0x1000 /* Adjust depending on available memory */
15490 \newline
15491 unsigned char xdata myheap[HEAPSIZE]; /* The actual heap for dynamic memory
15492  */
15493 \newline
15494
15495 \newline
15496 void main (void)
15497 \newline
15498 {
15499 \newline
15500 \SpecialChar ~
15501 \SpecialChar ~
15502 \SpecialChar ~
15503 /* Your variable declarations come here*/
15504 \newline
15505 \SpecialChar ~
15506 \SpecialChar ~
15507 \SpecialChar ~
15508 ...
15509 \newline
15510 \SpecialChar ~
15511 \SpecialChar ~
15512 \SpecialChar ~
15513 init_dynamic_memory((MEMHEADER xdata *)myheap, HEAPSIZE);
15514 \newline
15515 \SpecialChar ~
15516 \SpecialChar ~
15517 \SpecialChar ~
15518 ...
15519  /* Rest of your code*/
15520 \newline
15521 }
15522 \newline
15523
15524 \layout Subsection
15525
15526 Math functions (sinf, powf, sqrtf etc.)
15527 \layout Subsubsection
15528
15529 <math.h>
15530 \layout Standard
15531
15532 See definitions in file <math.h>.
15533 \layout Subsection
15534
15535 Other libraries
15536 \layout Standard
15537
15538 Libraries
15539 \begin_inset LatexCommand \index{Libraries}
15540
15541 \end_inset
15542
15543  included in SDCC should have a license at least as liberal as the GNU Lesser
15544  General Public License
15545 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
15546
15547 \end_inset
15548
15549
15550 \emph on
15551 LGPL
15552 \emph default
15553 .
15554 \layout Comment
15555
15556 license statements for the libraries are missing.
15557  sdcc/device/lib/ser_ir.c
15558 \layout Comment
15559
15560 or _decdptr f.e.
15561  come with a GPL (as opposed to LGPL) License - this will not be liberal
15562  enough for many embedded programmers.
15563 \layout Standard
15564
15565 If you have ported some library or want to share experience about some code
15566  which f.e.
15567  falls into any of these categories Busses (I
15568 \begin_inset Formula $^{\textrm{2}}$
15569 \end_inset
15570
15571 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
15572  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
15573  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
15574 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
15575
15576 \end_inset
15577
15578 \SpecialChar ~
15579 would certainly like to hear about it.
15580  Programmers coding for embedded systems are not especially famous for being
15581  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
15582 e these references are very valuable.
15583  Let's help to create a climate where information is shared.
15584 \layout Section
15585
15586 Memory Models
15587 \layout Subsection
15588
15589 MCS51 Memory Models
15590 \begin_inset LatexCommand \index{Memory model}
15591
15592 \end_inset
15593
15594
15595 \begin_inset LatexCommand \index{MCS51 memory model}
15596
15597 \end_inset
15598
15599
15600 \layout Subsubsection
15601
15602 Small, Medium and Large
15603 \layout Standard
15604
15605 SDCC allows three memory models for MCS51 code,
15606 \shape slanted
15607 small, medium
15608 \shape default
15609  and
15610 \shape slanted
15611 large
15612 \shape default
15613 .
15614  Modules compiled with different memory models should
15615 \emph on
15616 never
15617 \emph default
15618  be combined together or the results would be unpredictable.
15619  The library routines supplied with the compiler are compiled as small,
15620  medium and large.
15621  The compiled library modules are contained in separate directories as small,
15622  medium and large so that you can link to the appropriate set.
15623 \layout Standard
15624
15625 When the medium or large model is used all variables declared without a
15626  storage class will be allocated into the external ram, this includes all
15627  parameters and local variables (for non-reentrant
15628 \begin_inset LatexCommand \index{reentrant}
15629
15630 \end_inset
15631
15632  functions).
15633  When the small model is used variables without storage class are allocated
15634  in the internal ram.
15635 \layout Standard
15636
15637 Judicious usage of the processor specific storage classes
15638 \begin_inset LatexCommand \index{Storage class}
15639
15640 \end_inset
15641
15642  and the 'reentrant' function type will yield much more efficient code,
15643  than using the large model.
15644  Several optimizations are disabled when the program is compiled using the
15645  large model, it is therefore recommended that the small model be used unless
15646  absolutely required.
15647 \layout Subsubsection
15648
15649 External Stack
15650 \begin_inset LatexCommand \label{sub:External-Stack}
15651
15652 \end_inset
15653
15654
15655 \begin_inset LatexCommand \index{stack}
15656
15657 \end_inset
15658
15659
15660 \begin_inset LatexCommand \index{External stack (mcs51)}
15661
15662 \end_inset
15663
15664
15665 \layout Standard
15666
15667 The external stack (-
15668 \begin_inset ERT
15669 status Collapsed
15670
15671 \layout Standard
15672
15673 \backslash
15674 /
15675 \end_inset
15676
15677 -xstack option
15678 \begin_inset LatexCommand \index{-\/-xstack}
15679
15680 \end_inset
15681
15682 ) is located in pdata
15683 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
15684
15685 \end_inset
15686
15687  memory (usually at the start of the external ram segment) and uses all
15688  unused space in pdata (max.
15689  256 bytes).
15690  When -
15691 \begin_inset ERT
15692 status Collapsed
15693
15694 \layout Standard
15695
15696 \backslash
15697 /
15698 \end_inset
15699
15700 -xstack option is used to compile the program, the parameters and local
15701  variables
15702 \begin_inset LatexCommand \index{local variables}
15703
15704 \end_inset
15705
15706  of all reentrant functions are allocated in this area.
15707  This option is provided for programs with large stack space requirements.
15708  When used with the -
15709 \begin_inset ERT
15710 status Collapsed
15711
15712 \layout Standard
15713
15714 \backslash
15715 /
15716 \end_inset
15717
15718 -stack-auto
15719 \begin_inset LatexCommand \index{-\/-stack-auto}
15720
15721 \end_inset
15722
15723  option, all parameters and local variables are allocated on the external
15724  stack (note: support libraries will need to be recompiled with the same
15725  options.
15726  There is a predefined target in the library makefile).
15727 \layout Standard
15728
15729 The compiler outputs the higher order address byte of the external ram segment
15730  into port P2
15731 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
15732
15733 \end_inset
15734
15735  (see also section
15736 \begin_inset LatexCommand \ref{sub:MCS51-variants}
15737
15738 \end_inset
15739
15740 ), therefore when using the External Stack option, this port
15741 \emph on
15742 may not
15743 \emph default
15744  be used by the application program.
15745 \layout Subsection
15746
15747 DS390 Memory Model
15748 \begin_inset LatexCommand \index{Memory model}
15749
15750 \end_inset
15751
15752
15753 \begin_inset LatexCommand \index{DS390 memory model}
15754
15755 \end_inset
15756
15757
15758 \layout Standard
15759
15760 The only model supported is Flat 24
15761 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
15762
15763 \end_inset
15764
15765 .
15766  This generates code for the 24 bit contiguous addressing mode of the Dallas
15767  DS80C390 part.
15768  In this mode, up to four meg of external RAM or code space can be directly
15769  addressed.
15770  See the data sheets at www.dalsemi.com for further information on this part.
15771 \newline
15772
15773 \newline
15774 Note that the compiler does not generate any code to place the processor
15775  into 24 bitmode (although
15776 \emph on
15777 tinibios
15778 \emph default
15779  in the ds390 libraries will do that for you).
15780  If you don't use
15781 \emph on
15782 tinibios
15783 \emph default
15784
15785 \begin_inset LatexCommand \index{Tinibios (DS390)}
15786
15787 \end_inset
15788
15789 , the boot loader or similar code must ensure that the processor is in 24
15790  bit contiguous addressing mode before calling the SDCC startup code.
15791 \newline
15792
15793 \newline
15794 Like the
15795 \emph on
15796 -
15797 \begin_inset ERT
15798 status Collapsed
15799
15800 \layout Standard
15801
15802 \backslash
15803 /
15804 \end_inset
15805
15806 -model-large
15807 \emph default
15808  option, variables will by default be placed into the XDATA segment.
15809
15810 \newline
15811
15812 \newline
15813 Segments may be placed anywhere in the 4 meg address space using the usual
15814  -
15815 \begin_inset ERT
15816 status Collapsed
15817
15818 \layout Standard
15819
15820 \backslash
15821 /
15822 \end_inset
15823
15824 -*-loc options.
15825  Note that if any segments are located above 64K, the -r flag must be passed
15826  to the linker to generate the proper segment relocations, and the Intel
15827  HEX output format must be used.
15828  The -r flag can be passed to the linker by using the option
15829 \emph on
15830 -Wl-r
15831 \emph default
15832  on the SDCC command line.
15833  However, currently the linker can not handle code segments > 64k.
15834 \layout Section
15835
15836 Pragmas
15837 \begin_inset LatexCommand \index{Pragmas}
15838
15839 \end_inset
15840
15841
15842 \layout Standard
15843
15844 SDCC supports the following #pragma directives:
15845 \layout Itemize
15846
15847 save
15848 \begin_inset LatexCommand \index{\#pragma save}
15849
15850 \end_inset
15851
15852  - this will save all current options to the save/restore stack.
15853  See #pragma\SpecialChar ~
15854 restore.
15855 \layout Itemize
15856
15857 restore
15858 \begin_inset LatexCommand \index{\#pragma restore}
15859
15860 \end_inset
15861
15862  - will restore saved options from the last save.
15863  saves & restores can be nested.
15864  SDCC uses a save/restore stack: save pushes current options to the stack,
15865  restore pulls current options from the stack.
15866  See #pragma\SpecialChar ~
15867 save.
15868 \newline
15869
15870 \layout Itemize
15871
15872 callee_saves
15873 \begin_inset LatexCommand \index{\#pragma callee\_saves}
15874
15875 \end_inset
15876
15877
15878 \begin_inset LatexCommand \index{function prologue}
15879
15880 \end_inset
15881
15882  function1[,function2[,function3...]] - The compiler by default uses a caller
15883  saves convention for register saving across function calls, however this
15884  can cause unnecessary register pushing & popping
15885 \begin_inset LatexCommand \index{push/pop}
15886
15887 \end_inset
15888
15889  when calling small functions from larger functions.
15890  This option can be used to switch off the register saving convention for
15891  the function names specified.
15892  The compiler will not save registers when calling these functions, extra
15893  code need to be manually inserted at the entry & exit for these functions
15894  to save & restore the registers used by these functions, this can SUBSTANTIALLY
15895  reduce code & improve run time performance of the generated code.
15896  In the future the compiler (with inter procedural analysis) may be able
15897  to determine the appropriate scheme to use for each function call.
15898  If -
15899 \begin_inset ERT
15900 status Collapsed
15901
15902 \layout Standard
15903
15904 \backslash
15905 /
15906 \end_inset
15907
15908 -callee-saves command line option is used, the function names specified
15909  in #pragma\SpecialChar ~
15910 callee_saves
15911 \begin_inset LatexCommand \index{\#pragma callee\_saves}
15912
15913 \end_inset
15914
15915  is appended to the list of functions specified in the command line.
15916 \layout Itemize
15917
15918 exclude
15919 \begin_inset LatexCommand \index{\#pragma exclude}
15920
15921 \end_inset
15922
15923  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
15924  of pairs of push/pop
15925 \begin_inset LatexCommand \index{push/pop}
15926
15927 \end_inset
15928
15929  instructions in
15930 \emph on
15931 I
15932 \emph default
15933 nterrupt
15934 \begin_inset LatexCommand \index{interrupt}
15935
15936 \end_inset
15937
15938
15939 \emph on
15940 S
15941 \emph default
15942 ervice
15943 \emph on
15944 R
15945 \emph default
15946 outines.
15947  The directive should be placed immediately before the ISR function definition
15948  and it affects ALL ISR functions following it.
15949  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
15950 exclude\SpecialChar ~
15951 none
15952 \begin_inset LatexCommand \index{\#pragma exclude}
15953
15954 \end_inset
15955
15956 .
15957  See also the related keyword _naked
15958 \begin_inset LatexCommand \index{\_naked}
15959
15960 \end_inset
15961
15962
15963 \begin_inset LatexCommand \index{\_\_naked}
15964
15965 \end_inset
15966
15967 .
15968 \layout Itemize
15969
15970 less_pedantic
15971 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
15972
15973 \end_inset
15974
15975  - the compiler will not warn you anymore for obvious mistakes, you'r on
15976  your own now ;-(
15977 \layout Itemize
15978
15979 disable_warning <nnnn>
15980 \begin_inset LatexCommand \index{\#pragma disable\_warning}
15981
15982 \end_inset
15983
15984  - the compiler will not warn you anymore about warning number <nnnn>.
15985 \layout Itemize
15986
15987 nogcse
15988 \begin_inset LatexCommand \index{\#pragma nogcse}
15989
15990 \end_inset
15991
15992  - will stop global common subexpression elimination.
15993 \layout Itemize
15994
15995 noinduction
15996 \begin_inset LatexCommand \index{\#pragma noinduction}
15997
15998 \end_inset
15999
16000  - will stop loop induction optimizations.
16001 \layout Itemize
16002
16003 noinvariant
16004 \begin_inset LatexCommand \index{\#pragma noinvariant}
16005
16006 \end_inset
16007
16008  - will not do loop invariant optimizations.
16009  For more details see Loop Invariants in section
16010 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
16011
16012 \end_inset
16013
16014 .
16015 \layout Itemize
16016
16017 noiv
16018 \begin_inset LatexCommand \index{\#pragma noiv}
16019
16020 \end_inset
16021
16022  - Do not generate interrupt
16023 \begin_inset LatexCommand \index{interrupt}
16024
16025 \end_inset
16026
16027  vector table entries for all ISR functions defined after the pragma.
16028  This is useful in cases where the interrupt vector table must be defined
16029  manually, or when there is a secondary, manually defined interrupt vector
16030  table (e.g.
16031  for the autovector feature of the Cypress EZ-USB FX2).
16032  More elegantly this can be achieved by obmitting the optional interrupt
16033  number after the interrupt keyword, see section
16034 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
16035
16036 \end_inset
16037
16038 \SpecialChar ~
16039 about interrupts.
16040 \layout Itemize
16041
16042 nojtbound
16043 \begin_inset LatexCommand \index{\#pragma nojtbound}
16044
16045 \end_inset
16046
16047  - will not generate code for boundary value checking, when switch statements
16048  are turned into jump-tables (dangerous).
16049  For more details see section
16050 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
16051
16052 \end_inset
16053
16054 .
16055 \layout Itemize
16056
16057 noloopreverse
16058 \begin_inset LatexCommand \index{\#pragma noloopreverse}
16059
16060 \end_inset
16061
16062  - Will not do loop reversal optimization
16063 \layout Itemize
16064
16065 nooverlay
16066 \begin_inset LatexCommand \index{\#pragma nooverlay}
16067
16068 \end_inset
16069
16070  - the compiler will not overlay the parameters and local variables of a
16071  function.
16072 \layout Itemize
16073
16074 stackauto
16075 \begin_inset LatexCommand \index{\#pragma stackauto}
16076
16077 \end_inset
16078
16079 - See option -
16080 \begin_inset ERT
16081 status Collapsed
16082
16083 \layout Standard
16084
16085 \backslash
16086 /
16087 \end_inset
16088
16089 -stack-auto
16090 \begin_inset LatexCommand \index{-\/-stack-auto}
16091
16092 \end_inset
16093
16094  and section
16095 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
16096
16097 \end_inset
16098
16099  Parameters and Local Variables.
16100 \layout Itemize
16101
16102 opt_code_speed
16103 \begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
16104
16105 \end_inset
16106
16107 - The compiler will optimize code generation towards fast code, possibly
16108  at the expense of code size.
16109 \layout Itemize
16110
16111 opt_code_size
16112 \begin_inset LatexCommand \index{\#pragma opt\_code\_size}
16113
16114 \end_inset
16115
16116 - The compiler will optimize code generation towards compact code, possibly
16117  at the expense of code speed.
16118 \layout Itemize
16119
16120 opt_code_balanced
16121 \begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
16122
16123 \end_inset
16124
16125 - The compiler will attempt to generate code that is both compact and fast,
16126  as long as meeting one goal is not a detriment to the other (this is the
16127  default).
16128
16129 \layout Itemize
16130
16131 std_sdcc89
16132 \begin_inset LatexCommand \index{\#pragma std\_sdcc89}
16133
16134 \end_inset
16135
16136 - Generally follow the C89 standard, but allow SDCC features that conflict
16137  with the standard (default).
16138 \layout Itemize
16139
16140 std_c89
16141 \begin_inset LatexCommand \index{\#pragma std\_c89}
16142
16143 \end_inset
16144
16145 - Follow the C89 standard and disable SDCC features that conflict with the
16146  standard.
16147 \layout Itemize
16148
16149 std_sdcc99
16150 \begin_inset LatexCommand \index{\#pragma std\_sdcc99}
16151
16152 \end_inset
16153
16154 - Generally follow the C99 standard, but allow SDCC features that conflict
16155  with the standard (incomplete support).
16156 \layout Itemize
16157
16158 std_c99
16159 \begin_inset LatexCommand \index{\#pragma std\_c99}
16160
16161 \end_inset
16162
16163 - Follow the C99 standard and disable SDCC features that conflict with the
16164  standard (incomplete support).
16165 \layout Itemize
16166
16167 codeseg <name>
16168 \begin_inset LatexCommand \index{\#pragma codeseg}
16169
16170 \end_inset
16171
16172 - Use this name (max.
16173  8 characters) for the code segment.
16174  See option -
16175 \begin_inset ERT
16176 status Collapsed
16177
16178 \layout Standard
16179
16180 \backslash
16181 /
16182 \end_inset
16183
16184 -codeseg.
16185 \layout Itemize
16186
16187 constseg <name>
16188 \begin_inset LatexCommand \index{\#pragma constseg}
16189
16190 \end_inset
16191
16192 - Use this name (max.
16193  8 characters) for the const segment.
16194  See option -
16195 \begin_inset ERT
16196 status Collapsed
16197
16198 \layout Standard
16199
16200 \backslash
16201 /
16202 \end_inset
16203
16204 -constseg.
16205 \layout Standard
16206
16207 SDCPP supports the following #pragma directives:
16208 \layout Itemize
16209
16210 preproc_asm
16211 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
16212
16213 \end_inset
16214
16215  (+ | -) - switch _asm _endasm block preprocessing on / off.
16216  Default is on.
16217  You use this prama to define multilines of assembly code.
16218  This will prevent the preprocessor from changing the formating required
16219  by assembly code.
16220  Below is an example on how to use this pragma.
16221 \layout Verse
16222
16223
16224 \family typewriter
16225 #pragma preproc_asm -
16226 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
16227
16228 \end_inset
16229
16230
16231 \newline
16232 #define MYDELAY _asm
16233 \newline
16234 \SpecialChar ~
16235 \SpecialChar ~
16236 \SpecialChar ~
16237 nop ;my assembly comment...
16238 \newline
16239 \SpecialChar ~
16240 \SpecialChar ~
16241 \SpecialChar ~
16242 nop
16243 \newline
16244 \SpecialChar ~
16245 \SpecialChar ~
16246 \SpecialChar ~
16247 nop
16248 \newline
16249 _endasm
16250 \newline
16251 #pragma preproc_asm +
16252 \newline
16253
16254 \newline
16255 void foo (void)
16256 \newline
16257 {
16258 \newline
16259 \SpecialChar ~
16260 \SpecialChar ~
16261 \SpecialChar ~
16262  ...
16263
16264 \newline
16265 \SpecialChar ~
16266 \SpecialChar ~
16267 \SpecialChar ~
16268  MYDELAY;
16269 \newline
16270 \SpecialChar ~
16271 \SpecialChar ~
16272 \SpecialChar ~
16273  ...
16274
16275 \newline
16276 }
16277 \newline
16278
16279 \layout Standard
16280
16281 The pragma's are intended to be used to turn-on or off certain optimizations
16282  which might cause the compiler to generate extra stack / data space to
16283  store compiler generated temporary variables.
16284  This usually happens in large functions.
16285  Pragma directives should be used as shown in the following example, they
16286  are used to control options & optimizations for a given function; pragmas
16287  should be placed before and/or after a function, placing pragma's inside
16288  a function body could have unpredictable results.
16289 \layout Verse
16290
16291
16292 \family typewriter
16293 #pragma save
16294 \begin_inset LatexCommand \index{\#pragma save}
16295
16296 \end_inset
16297
16298  \SpecialChar ~
16299 \SpecialChar ~
16300 \SpecialChar ~
16301 \SpecialChar ~
16302 \SpecialChar ~
16303 \SpecialChar ~
16304 \SpecialChar ~
16305 /* save the current settings */
16306 \newline
16307 #pragma nogcse
16308 \begin_inset LatexCommand \index{\#pragma nogcse}
16309
16310 \end_inset
16311
16312  \SpecialChar ~
16313 \SpecialChar ~
16314 \SpecialChar ~
16315 \SpecialChar ~
16316 \SpecialChar ~
16317 /* turnoff global subexpression elimination */
16318 \newline
16319 #pragma noinduction
16320 \begin_inset LatexCommand \index{\#pragma noinduction}
16321
16322 \end_inset
16323
16324  /* turn off induction optimizations */
16325 \newline
16326 int foo ()
16327 \newline
16328 {
16329 \newline
16330 \SpecialChar ~
16331  \SpecialChar ~
16332  ...
16333
16334 \newline
16335 \SpecialChar ~
16336  \SpecialChar ~
16337  /* large code */
16338 \newline
16339 \SpecialChar ~
16340  \SpecialChar ~
16341  ...
16342
16343 \newline
16344 }
16345 \newline
16346 #pragma restore
16347 \begin_inset LatexCommand \index{\#pragma restore}
16348
16349 \end_inset
16350
16351  /* turn the optimizations back on */
16352 \layout Standard
16353
16354 The compiler will generate a warning message when extra space is allocated.
16355  It is strongly recommended that the save and restore pragma's be used when
16356  changing options for a function.
16357 \newline
16358
16359 \newline
16360
16361 \newline
16362
16363 \layout Section
16364
16365 Defines Created by the Compiler
16366 \layout Standard
16367
16368 The compiler creates the following #defines
16369 \begin_inset LatexCommand \index{\#defines}
16370
16371 \end_inset
16372
16373
16374 \begin_inset LatexCommand \index{Defines created by the compiler}
16375
16376 \end_inset
16377
16378 :
16379 \newline
16380
16381 \layout Standard
16382
16383
16384 \begin_inset  Tabular
16385 <lyxtabular version="3" rows="11" columns="2">
16386 <features>
16387 <column alignment="left" valignment="top" leftline="true" width="3in">
16388 <column alignment="left" valignment="top" leftline="true" rightline="true" width="3in">
16389 <row topline="true" bottomline="true">
16390 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16391 \begin_inset Text
16392
16393 \layout Standard
16394
16395
16396 \series bold
16397 #define
16398 \end_inset
16399 </cell>
16400 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16401 \begin_inset Text
16402
16403 \layout Standard
16404
16405
16406 \series bold
16407 Description
16408 \end_inset
16409 </cell>
16410 </row>
16411 <row topline="true">
16412 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16413 \begin_inset Text
16414
16415 \layout Standard
16416
16417 SDCC
16418 \begin_inset LatexCommand \index{SDCC}
16419
16420 \end_inset
16421
16422
16423 \end_inset
16424 </cell>
16425 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16426 \begin_inset Text
16427
16428 \layout Standard
16429
16430 Always defined.
16431  Since version 2.5.6 the version number as an int (ex.
16432  256)
16433 \end_inset
16434 </cell>
16435 </row>
16436 <row topline="true">
16437 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16438 \begin_inset Text
16439
16440 \layout Standard
16441
16442 SDCC_mcs51
16443 \begin_inset LatexCommand \index{SDCC\_mcs51}
16444
16445 \end_inset
16446
16447  or SDCC_ds390
16448 \begin_inset LatexCommand \index{SDCC\_ds390}
16449
16450 \end_inset
16451
16452  or SDCC_z80
16453 \begin_inset LatexCommand \index{SDCC\_z80}
16454
16455 \end_inset
16456
16457 , etc.
16458 \end_inset
16459 </cell>
16460 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16461 \begin_inset Text
16462
16463 \layout Standard
16464
16465 depending on the model used (e.g.: -mds390)
16466 \end_inset
16467 </cell>
16468 </row>
16469 <row topline="true">
16470 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16471 \begin_inset Text
16472
16473 \layout Standard
16474
16475 __mcs51
16476 \begin_inset LatexCommand \index{\_\_mcs51}
16477
16478 \end_inset
16479
16480 , __ds390
16481 \begin_inset LatexCommand \index{\_\_ds390}
16482
16483 \end_inset
16484
16485 , __hc08
16486 \begin_inset LatexCommand \index{\_\_hc08}
16487
16488 \end_inset
16489
16490 , __z80
16491 \begin_inset LatexCommand \index{\_\_z80}
16492
16493 \end_inset
16494
16495 , etc
16496 \end_inset
16497 </cell>
16498 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16499 \begin_inset Text
16500
16501 \layout Standard
16502
16503 depending on the model used (e.g.
16504  -mz80)
16505 \end_inset
16506 </cell>
16507 </row>
16508 <row topline="true">
16509 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16510 \begin_inset Text
16511
16512 \layout Standard
16513
16514 SDCC_STACK_AUTO
16515 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
16516
16517 \end_inset
16518
16519
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 when
16528 \emph on
16529 -
16530 \begin_inset ERT
16531 status Collapsed
16532
16533 \layout Standard
16534
16535 \backslash
16536 /
16537 \end_inset
16538
16539 -stack-auto
16540 \emph default
16541  option is used
16542 \end_inset
16543 </cell>
16544 </row>
16545 <row topline="true">
16546 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16547 \begin_inset Text
16548
16549 \layout Standard
16550
16551 SDCC_MODEL_SMALL
16552 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
16553
16554 \end_inset
16555
16556
16557 \end_inset
16558 </cell>
16559 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16560 \begin_inset Text
16561
16562 \layout Standard
16563
16564 when
16565 \emph on
16566 -
16567 \begin_inset ERT
16568 status Collapsed
16569
16570 \layout Standard
16571
16572 \backslash
16573 /
16574 \end_inset
16575
16576 -model-small
16577 \emph default
16578  is used
16579 \end_inset
16580 </cell>
16581 </row>
16582 <row topline="true">
16583 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16584 \begin_inset Text
16585
16586 \layout Standard
16587
16588 SDCC_MODEL_MEDIUM
16589 \begin_inset LatexCommand \index{SDCC\_MODEL\_MEDIUM}
16590
16591 \end_inset
16592
16593
16594 \end_inset
16595 </cell>
16596 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16597 \begin_inset Text
16598
16599 \layout Standard
16600
16601 when
16602 \emph on
16603 -
16604 \begin_inset ERT
16605 status Collapsed
16606
16607 \layout Standard
16608
16609 \backslash
16610 /
16611 \end_inset
16612
16613 -model-medium
16614 \emph default
16615  is used
16616 \end_inset
16617 </cell>
16618 </row>
16619 <row topline="true">
16620 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16621 \begin_inset Text
16622
16623 \layout Standard
16624
16625 SDCC_MODEL_LARGE
16626 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
16627
16628 \end_inset
16629
16630
16631 \end_inset
16632 </cell>
16633 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16634 \begin_inset Text
16635
16636 \layout Standard
16637
16638 when
16639 \emph on
16640 -
16641 \begin_inset ERT
16642 status Collapsed
16643
16644 \layout Standard
16645
16646 \backslash
16647 /
16648 \end_inset
16649
16650 -model-large
16651 \emph default
16652  is used
16653 \end_inset
16654 </cell>
16655 </row>
16656 <row topline="true">
16657 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16658 \begin_inset Text
16659
16660 \layout Standard
16661
16662 SDCC_USE_XSTACK
16663 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
16664
16665 \end_inset
16666
16667
16668 \end_inset
16669 </cell>
16670 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16671 \begin_inset Text
16672
16673 \layout Standard
16674
16675 when
16676 \emph on
16677 -
16678 \begin_inset ERT
16679 status Collapsed
16680
16681 \layout Standard
16682
16683 \backslash
16684 /
16685 \end_inset
16686
16687 -xstack
16688 \emph default
16689  option is used
16690 \end_inset
16691 </cell>
16692 </row>
16693 <row topline="true">
16694 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16695 \begin_inset Text
16696
16697 \layout Standard
16698
16699 SDCC_STACK_TENBIT
16700 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
16701
16702 \end_inset
16703
16704
16705 \end_inset
16706 </cell>
16707 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16708 \begin_inset Text
16709
16710 \layout Standard
16711
16712 when
16713 \emph on
16714 -mds390
16715 \emph default
16716  is used
16717 \end_inset
16718 </cell>
16719 </row>
16720 <row topline="true" bottomline="true">
16721 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16722 \begin_inset Text
16723
16724 \layout Standard
16725
16726 SDCC_MODEL_FLAT24
16727 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
16728
16729 \end_inset
16730
16731
16732 \end_inset
16733 </cell>
16734 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16735 \begin_inset Text
16736
16737 \layout Standard
16738
16739 when
16740 \emph on
16741 -mds390
16742 \emph default
16743  is used
16744 \end_inset
16745 </cell>
16746 </row>
16747 </lyxtabular>
16748
16749 \end_inset
16750
16751
16752 \layout Chapter
16753
16754 Notes on supported Processors
16755 \layout Section
16756
16757 MCS51 variants
16758 \begin_inset LatexCommand \label{sub:MCS51-variants}
16759
16760 \end_inset
16761
16762
16763 \begin_inset LatexCommand \index{MCS51 variants}
16764
16765 \end_inset
16766
16767
16768 \layout Standard
16769
16770 MCS51 processors are available from many vendors and come in many different
16771  flavours.
16772  While they might differ considerably in respect to Special Function Registers
16773  the core MCS51 is usually not modified or is kept compatible.
16774
16775 \layout Subsection
16776
16777 pdata access by SFR
16778 \layout Standard
16779
16780 With the upcome of devices with internal xdata and flash memory devices
16781  using port P2
16782 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
16783
16784 \end_inset
16785
16786  as dedicated I/O port is becoming more popular.
16787  Switching the high byte for pdata
16788 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
16789
16790 \end_inset
16791
16792  access which was formerly done by port P2 is then achieved by a Special
16793  Function Register
16794 \begin_inset LatexCommand \index{sfr}
16795
16796 \end_inset
16797
16798 .
16799  In well-established MCS51 tradition the address of this
16800 \emph on
16801 sfr
16802 \emph default
16803  is where the chip designers decided to put it.
16804  Needless to say that they didn't agree on a common name either.
16805  So that the startup code can correctly initialize xdata variables, you
16806  should define an sfr with the name _XPAGE
16807 \family typewriter
16808
16809 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
16810
16811 \end_inset
16812
16813
16814 \family default
16815  at the appropriate location if the default, port P2, is not used for this.
16816  Some examples are:
16817 \layout Verse
16818
16819
16820 \family typewriter
16821 sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
16822 \layout Verse
16823
16824
16825 \family typewriter
16826 sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
16827 \layout Verse
16828
16829
16830 \family typewriter
16831 sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
16832 \layout Standard
16833
16834 For more exotic implementations further customizations may be needed.
16835  See section
16836 \begin_inset LatexCommand \ref{sub:Startup-Code}
16837
16838 \end_inset
16839
16840  for other possibilities.
16841 \layout Subsection
16842
16843 Other Features available by SFR
16844 \layout Standard
16845
16846 Some MCS51 variants offer features like Double DPTR
16847 \begin_inset LatexCommand \index{DPTR}
16848
16849 \end_inset
16850
16851 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
16852  These are currently not used for the MCS51 port.
16853  If you absolutely need them you can fall back to inline assembly or submit
16854  a patch to SDCC.
16855 \layout Section
16856
16857 DS400 port
16858 \layout Standard
16859
16860 The DS80C400 microcontroller has a rich set of peripherals.
16861  In its built-in ROM library it includes functions to access some of the
16862  features, among them is a TCP stack with IP4 and IP6 support.
16863  Library headers (currently in beta status) and other files are provided
16864  at
16865 \size footnotesize
16866
16867 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
16868
16869 \end_inset
16870
16871 .
16872
16873 \layout Section
16874
16875 The Z80 and gbz80 port
16876 \layout Standard
16877
16878 SDCC can target both the Zilog
16879 \begin_inset LatexCommand \index{Z80}
16880
16881 \end_inset
16882
16883  and the Nintendo Gameboy's Z80-like gbz80
16884 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
16885
16886 \end_inset
16887
16888 .
16889  The Z80 port is passed through the same
16890 \emph on
16891 regressions tests
16892 \begin_inset LatexCommand \index{Regression test}
16893
16894 \end_inset
16895
16896
16897 \emph default
16898  as the MCS51 and DS390 ports, so floating point support, support for long
16899  variables and bitfield support is fine.
16900  See mailing lists and forums about interrupt routines.
16901 \layout Standard
16902
16903 As always, the code is the authoritative reference - see z80/ralloc.c and
16904  z80/gen.c.
16905  The stack
16906 \begin_inset LatexCommand \index{stack}
16907
16908 \end_inset
16909
16910  frame is similar to that generated by the IAR Z80 compiler.
16911  IX is used as the base pointer, HL and IY are used as a temporary registers,
16912  and BC and DE are available for holding variables.
16913  Return values
16914 \begin_inset LatexCommand \index{return value}
16915
16916 \end_inset
16917
16918  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
16919  bytes).
16920  The gbz80 port use the same set of registers for the return values, but
16921  in a different order of significance: E (one byte), DE (two bytes), or
16922  HLDE (four bytes).
16923 \layout Section
16924
16925 The HC08 port
16926 \layout Standard
16927
16928 The port to the Motorola HC08
16929 \begin_inset LatexCommand \index{HC08}
16930
16931 \end_inset
16932
16933  family has been added in October 2003, and is still undergoing some basic
16934  development.
16935  The code generator is complete, but the register allocation is still quite
16936  unoptimized.
16937  Some of the SDCC's standard C library functions have embedded non-HC08
16938  inline assembly and so are not yet usable.
16939 \newline
16940
16941 \newline
16942
16943 \layout Section
16944
16945 The PIC14 port
16946 \layout Standard
16947
16948 The 14bit PIC
16949 \begin_inset LatexCommand \index{PIC14}
16950
16951 \end_inset
16952
16953  port still requires a major effort from the development community.
16954  However it can work for very simple code.
16955 \layout Subsection
16956
16957 C code and 14bit PIC code page
16958 \begin_inset LatexCommand \index{code page (pic14)}
16959
16960 \end_inset
16961
16962  and RAM banks
16963 \begin_inset LatexCommand \index{RAM bank (pic14)}
16964
16965 \end_inset
16966
16967
16968 \layout Standard
16969
16970 The linker organizes allocation for the code page and RAM banks.
16971  It does not have intimate knowledge of the code flow.
16972  It will put all the code section of a single asm file into a single code
16973  page.
16974  In order to make use of multiple code pages, separate asm files must be
16975  used.
16976  The compiler treats all functions of a single C file as being in the same
16977  code page unless it is non static.
16978  The compiler treats all local variables of a single C file as being in
16979  the same RAM bank unless it is an extern.
16980 \newline
16981
16982 \newline
16983 To get the best follow these guide lines:
16984 \layout Enumerate
16985
16986 make local functions static, as non static functions require code page selection
16987  overhead.
16988 \layout Enumerate
16989
16990 Make local variables static as extern variables require RAM bank selection
16991  overhead.
16992 \layout Enumerate
16993
16994 For devices that have multiple code pages it is more efficient to use the
16995  same number of files as pages, i.e.
16996  for the 16F877 use 4 separate files and i.e.
16997  for the 16F874 use 2 separate files.
16998  This way the linker can put the code for each file into different code
16999  pages and the compiler can allocate reusable variables more efficiently
17000  and there's less page selection overhead.
17001  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
17002  instruction set) use 'unsigned char' whereever possible instead of 'int'.
17003 \layout Subsection
17004
17005 Creating a device include file
17006 \layout Standard
17007
17008 For generating a device include file use the support perl script inc2h.pl
17009  kept in directory support/script.
17010 \layout Subsection
17011
17012 Interrupt code
17013 \layout Standard
17014
17015 For the interrupt function, use the keyword 'interrupt'
17016 \begin_inset LatexCommand \index{interrupt}
17017
17018 \end_inset
17019
17020  with level number of 0 (PIC14 only has 1 interrupt so this number is only
17021  there to avoid a syntax error - it ought to be fixed).
17022  E.g.:
17023 \layout Verse
17024
17025
17026 \family typewriter
17027 void Intr(void) interrupt 0
17028 \newline
17029 {
17030 \newline
17031 \SpecialChar ~
17032 \SpecialChar ~
17033 T0IF = 0; /* Clear timer interrupt */
17034 \newline
17035 }
17036 \layout Subsection
17037
17038 Linking and assembling
17039 \layout Standard
17040
17041 For assembling you can use either GPUTILS'
17042 \begin_inset LatexCommand \index{gputils (pic tools)}
17043
17044 \end_inset
17045
17046  gpasm.exe or MPLAB's mpasmwin.exe.
17047  GPUTILS is available from
17048 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
17049
17050 \end_inset
17051
17052 .
17053  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
17054  If you use MPLAB and an interrupt function then the linker script file
17055  vectors section will need to be enlarged to link with mplink.
17056 \newline
17057
17058 \newline
17059 Here is a
17060 \family typewriter
17061 Makefile
17062 \family default
17063  using GPUTILS:
17064 \layout Verse
17065
17066
17067 \family typewriter
17068 .c.o:
17069 \newline
17070 \SpecialChar ~
17071 \SpecialChar ~
17072 \SpecialChar ~
17073 \SpecialChar ~
17074 \SpecialChar ~
17075 \SpecialChar ~
17076 \SpecialChar ~
17077 \SpecialChar ~
17078 sdcc -S -V -mpic14 -p16F877 $<
17079 \newline
17080 \SpecialChar ~
17081 \SpecialChar ~
17082 \SpecialChar ~
17083 \SpecialChar ~
17084 \SpecialChar ~
17085 \SpecialChar ~
17086 \SpecialChar ~
17087 \SpecialChar ~
17088 gpasm -c $*.asm
17089 \newline
17090
17091 \newline
17092 $(PRJ).hex: $(OBJS)
17093 \newline
17094 \SpecialChar ~
17095 \SpecialChar ~
17096 \SpecialChar ~
17097 \SpecialChar ~
17098 \SpecialChar ~
17099 \SpecialChar ~
17100 \SpecialChar ~
17101 \SpecialChar ~
17102 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS) libsdcc.lib
17103 \layout Standard
17104
17105 Here is a
17106 \family typewriter
17107 Makefile
17108 \family default
17109  using MPLAB:
17110 \layout Verse
17111
17112
17113 \family typewriter
17114 .c.o:
17115 \newline
17116 \SpecialChar ~
17117 \SpecialChar ~
17118 \SpecialChar ~
17119 \SpecialChar ~
17120 \SpecialChar ~
17121 \SpecialChar ~
17122 \SpecialChar ~
17123 \SpecialChar ~
17124 sdcc -S -V -mpic14 -p16F877 $<
17125 \newline
17126 \SpecialChar ~
17127 \SpecialChar ~
17128 \SpecialChar ~
17129 \SpecialChar ~
17130 \SpecialChar ~
17131 \SpecialChar ~
17132 \SpecialChar ~
17133 \SpecialChar ~
17134 mpasmwin /q /o $*.asm
17135 \newline
17136
17137 \newline
17138 $(PRJ).hex: $(OBJS)
17139 \newline
17140 \SpecialChar ~
17141 \SpecialChar ~
17142 \SpecialChar ~
17143 \SpecialChar ~
17144 \SpecialChar ~
17145 \SpecialChar ~
17146 \SpecialChar ~
17147 \SpecialChar ~
17148 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS) libsdcc.lib
17149 \layout Standard
17150
17151 Please note that indentations within a
17152 \family typewriter
17153  Makefile
17154 \family default
17155  have to be done with a tabulator character.
17156 \layout Subsection
17157
17158 Command-line options
17159 \layout Standard
17160
17161 Besides the switches common to all SDCC backends, the PIC14 port accepts
17162  the following options (for an updated list see sdcc -
17163 \begin_inset ERT
17164 status Collapsed
17165
17166 \layout Standard
17167
17168 \backslash
17169 /
17170 \end_inset
17171
17172 -help):
17173 \layout List
17174 \labelwidthstring 00.00.0000
17175
17176 -
17177 \begin_inset ERT
17178 status Collapsed
17179
17180 \layout Standard
17181
17182 \backslash
17183 /
17184 \end_inset
17185
17186 -debug-extra emit debug info in assembly output
17187 \layout List
17188 \labelwidthstring 00.00.0000
17189
17190 -
17191 \begin_inset ERT
17192 status Collapsed
17193
17194 \layout Standard
17195
17196 \backslash
17197 /
17198 \end_inset
17199
17200 -no-pcode-opt disable (slightly faulty) optimization on pCode
17201 \layout Subsection
17202
17203 The library
17204 \layout Subsubsection
17205
17206 error: missing definition for symbol
17207 \begin_inset Quotes sld
17208 \end_inset
17209
17210 __gptrget1
17211 \begin_inset Quotes srd
17212 \end_inset
17213
17214
17215 \layout Standard
17216
17217 The PIC14 port uses library routines to provide more complex operations
17218  like multiplication, division/modulus and (generic) pointer dereferencing.
17219  In order to add these routines to your project, you must link with PIC14's
17220
17221 \family typewriter
17222 libsdcc.lib
17223 \family default
17224 .
17225  For single source file projects this is done automatically, more complex
17226  projects must add
17227 \family typewriter
17228 libsdcc.lib
17229 \family default
17230  to the linker's arguments.
17231  Make sure you also add an include path for the library (using the -I switch
17232  to the linker)!
17233 \layout Subsubsection
17234
17235 Processor mismatch in file
17236 \begin_inset Quotes sld
17237 \end_inset
17238
17239 XXX
17240 \begin_inset Quotes srd
17241 \end_inset
17242
17243 .
17244 \layout Standard
17245
17246 This warning can usually be ignored due to the very good compatibility amongst
17247  14 bit PIC devices.
17248 \layout Standard
17249
17250 You might also consider recompiling the library for your specific device
17251  by changing the ARCH=p16f877 (default target) entry in
17252 \family typewriter
17253 device/lib/pic/Makefile.in
17254 \family default
17255  and
17256 \family typewriter
17257 device/lib/pic/Makefile
17258 \family default
17259  to reflect your device.
17260  This might even improve performance for smaller devices as unneccesary
17261  BANKSELs migth be removed.
17262 \layout Subsection
17263
17264 Known bugs
17265 \layout Subsubsection
17266
17267 initialized data
17268 \layout Standard
17269
17270 Currently, data can only be initialized if it resides in the source file
17271  together with
17272 \emph on
17273 main()
17274 \emph default
17275 .
17276  Data in other source files will silently
17277 \series bold
17278 not
17279 \series default
17280  be initialized.
17281 \layout Section
17282
17283 The PIC16
17284 \begin_inset LatexCommand \index{PIC16}
17285
17286 \end_inset
17287
17288  port
17289 \layout Standard
17290
17291 The PIC16
17292 \begin_inset LatexCommand \index{PIC16}
17293
17294 \end_inset
17295
17296  port is the portion of SDCC that is responsible to produce code for the
17297  Microchip
17298 \begin_inset LatexCommand \index{Microchip}
17299
17300 \end_inset
17301
17302 (TM) microcontrollers with 16 bit core.
17303  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
17304  Currently supported devices are:
17305 \layout Standard
17306 \align center
17307
17308 \begin_inset  Tabular
17309 <lyxtabular version="3" rows="4" columns="6">
17310 <features>
17311 <column alignment="center" valignment="top" leftline="true" width="0">
17312 <column alignment="center" valignment="top" leftline="true" width="0">
17313 <column alignment="center" valignment="top" leftline="true" width="0">
17314 <column alignment="center" valignment="top" leftline="true" width="0">
17315 <column alignment="center" valignment="top" leftline="true" width="0">
17316 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17317 <row topline="true">
17318 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17319 \begin_inset Text
17320
17321 \layout Standard
17322
17323 18F242
17324 \end_inset
17325 </cell>
17326 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17327 \begin_inset Text
17328
17329 \layout Standard
17330
17331 18F248
17332 \end_inset
17333 </cell>
17334 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17335 \begin_inset Text
17336
17337 \layout Standard
17338
17339 18F252
17340 \end_inset
17341 </cell>
17342 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17343 \begin_inset Text
17344
17345 \layout Standard
17346
17347 18F258
17348 \end_inset
17349 </cell>
17350 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17351 \begin_inset Text
17352
17353 \layout Standard
17354
17355 18F442
17356 \end_inset
17357 </cell>
17358 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17359 \begin_inset Text
17360
17361 \layout Standard
17362
17363 18F448
17364 \end_inset
17365 </cell>
17366 </row>
17367 <row topline="true">
17368 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17369 \begin_inset Text
17370
17371 \layout Standard
17372
17373 18F452
17374 \end_inset
17375 </cell>
17376 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17377 \begin_inset Text
17378
17379 \layout Standard
17380
17381 18F458
17382 \end_inset
17383 </cell>
17384 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17385 \begin_inset Text
17386
17387 \layout Standard
17388
17389 18F1220
17390 \end_inset
17391 </cell>
17392 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17393 \begin_inset Text
17394
17395 \layout Standard
17396
17397 18F2220
17398 \end_inset
17399 </cell>
17400 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17401 \begin_inset Text
17402
17403 \layout Standard
17404
17405 18F2550
17406 \end_inset
17407 </cell>
17408 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17409 \begin_inset Text
17410
17411 \layout Standard
17412
17413 18F4331
17414 \end_inset
17415 </cell>
17416 </row>
17417 <row topline="true">
17418 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17419 \begin_inset Text
17420
17421 \layout Standard
17422
17423 18F4455
17424 \end_inset
17425 </cell>
17426 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17427 \begin_inset Text
17428
17429 \layout Standard
17430
17431 18F6520
17432 \end_inset
17433 </cell>
17434 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17435 \begin_inset Text
17436
17437 \layout Standard
17438
17439 18F6620
17440 \end_inset
17441 </cell>
17442 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17443 \begin_inset Text
17444
17445 \layout Standard
17446
17447 18F6680
17448 \end_inset
17449 </cell>
17450 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17451 \begin_inset Text
17452
17453 \layout Standard
17454
17455 18F6720
17456 \end_inset
17457 </cell>
17458 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17459 \begin_inset Text
17460
17461 \layout Standard
17462
17463 18F8520
17464 \end_inset
17465 </cell>
17466 </row>
17467 <row topline="true" bottomline="true">
17468 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17469 \begin_inset Text
17470
17471 \layout Standard
17472
17473 18F8620
17474 \end_inset
17475 </cell>
17476 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17477 \begin_inset Text
17478
17479 \layout Standard
17480
17481 18F8680
17482 \end_inset
17483 </cell>
17484 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17485 \begin_inset Text
17486
17487 \layout Standard
17488
17489 18F8720
17490 \end_inset
17491 </cell>
17492 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17493 \begin_inset Text
17494
17495 \layout Standard
17496
17497 \end_inset
17498 </cell>
17499 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17500 \begin_inset Text
17501
17502 \layout Standard
17503
17504 \end_inset
17505 </cell>
17506 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17507 \begin_inset Text
17508
17509 \layout Standard
17510
17511 \end_inset
17512 </cell>
17513 </row>
17514 </lyxtabular>
17515
17516 \end_inset
17517
17518
17519 \layout Subsection
17520
17521 Global Options
17522 \layout Standard
17523
17524 PIC16 port supports the standard command line arguments as supposed, with
17525  the exception of certain cases that will be mentioned in the following
17526  list:
17527 \layout List
17528 \labelwidthstring 00.00.0000
17529
17530 -
17531 \begin_inset ERT
17532 status Collapsed
17533
17534 \layout Standard
17535
17536 \backslash
17537 /
17538 \end_inset
17539
17540 -callee-saves See -
17541 \begin_inset ERT
17542 status Collapsed
17543
17544 \layout Standard
17545
17546 \backslash
17547 /
17548 \end_inset
17549
17550 -all-callee-saves
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 -all-callee-saves All function arguments are passed on stack by default.
17565
17566 \emph on
17567 There is no need to specify this in the command line.
17568 \layout List
17569 \labelwidthstring 00.00.0000
17570
17571 -
17572 \begin_inset ERT
17573 status Collapsed
17574
17575 \layout Standard
17576
17577 \backslash
17578 /
17579 \end_inset
17580
17581 -fommit-frame-pointer Frame pointer will be omitted when the function uses
17582  no local variables.
17583 \layout Subsection
17584
17585 Port Specific Options
17586 \begin_inset LatexCommand \index{Options PIC16}
17587
17588 \end_inset
17589
17590
17591 \layout Standard
17592
17593 The port specific options appear after the global options in the sdcc --help
17594  output.
17595 \layout Subsubsection
17596
17597 General Options
17598 \layout Standard
17599
17600 General options enable certain port features and optimizations.
17601 \layout List
17602 \labelwidthstring 00.00.0000
17603
17604 -
17605 \begin_inset ERT
17606 status Collapsed
17607
17608 \layout Standard
17609
17610 \backslash
17611 /
17612 \end_inset
17613
17614 -stack-model=[model] Used in conjuction with the command above.
17615  Defines the stack model to be used, valid stack models are :
17616 \begin_deeper
17617 \layout List
17618 \labelwidthstring 00.00.0000
17619
17620
17621 \emph on
17622 small
17623 \emph default
17624  Selects small stack model.
17625  8 bit stack and frame pointers.
17626  Supports 256 bytes stack size.
17627 \layout List
17628 \labelwidthstring 00.00.0000
17629
17630
17631 \emph on
17632 large
17633 \emph default
17634  Selects large stack model.
17635  16 bit stack and frame pointers.
17636  Supports 65536 bytes stack size.
17637 \end_deeper
17638 \layout List
17639 \labelwidthstring 00.00.0000
17640
17641 -
17642 \begin_inset ERT
17643 status Collapsed
17644
17645 \layout Standard
17646
17647 \backslash
17648 /
17649 \end_inset
17650
17651 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
17652  unitialized data variables with [kword].
17653  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
17654 \layout List
17655 \labelwidthstring 00.00.0000
17656
17657 -
17658 \begin_inset ERT
17659 status Collapsed
17660
17661 \layout Standard
17662
17663 \backslash
17664 /
17665 \end_inset
17666
17667 -ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
17668  Useful for bootloaders.
17669 \layout List
17670 \labelwidthstring 00.00.0000
17671
17672 -
17673 \begin_inset ERT
17674 status Collapsed
17675
17676 \layout Standard
17677
17678 \backslash
17679 /
17680 \end_inset
17681
17682 -asm= sets the full path and name of an external assembler to call.
17683 \layout List
17684 \labelwidthstring 00.00.0000
17685
17686 -
17687 \begin_inset ERT
17688 status Collapsed
17689
17690 \layout Standard
17691
17692 \backslash
17693 /
17694 \end_inset
17695
17696 -link= sets the full path and name of an external linker to call.
17697 \layout List
17698 \labelwidthstring 00.00.0000
17699
17700 -
17701 \begin_inset ERT
17702 status Collapsed
17703
17704 \layout Standard
17705
17706 \backslash
17707 /
17708 \end_inset
17709
17710 -mplab-comp MPLAB compatibility option.
17711  Currently only suppresses special gpasm directives.
17712 \layout Subsubsection
17713
17714 Optimization Options
17715 \layout List
17716 \labelwidthstring 00.00.0000
17717
17718 -
17719 \begin_inset ERT
17720 status Collapsed
17721
17722 \layout Standard
17723
17724 \backslash
17725 /
17726 \end_inset
17727
17728 -optimize-goto Try to use (conditional) BRA instead of GOTO
17729 \layout List
17730 \labelwidthstring 00.00.0000
17731
17732 -
17733 \begin_inset ERT
17734 status Collapsed
17735
17736 \layout Standard
17737
17738 \backslash
17739 /
17740 \end_inset
17741
17742 -optimize-cmp Try to optimize some compares.
17743 \layout List
17744 \labelwidthstring 00.00.0000
17745
17746 -
17747 \begin_inset ERT
17748 status Collapsed
17749
17750 \layout Standard
17751
17752 \backslash
17753 /
17754 \end_inset
17755
17756 -optimize-df Analyze the dataflow of the generated code and improve it.
17757 \layout List
17758 \labelwidthstring 00.00.0000
17759
17760 -
17761 \begin_inset ERT
17762 status Collapsed
17763
17764 \layout Standard
17765
17766 \backslash
17767 /
17768 \end_inset
17769
17770 -obanksel=nn Set optimization level for inserting BANKSELs.
17771 \newline
17772
17773 \begin_deeper
17774 \layout List
17775 \labelwidthstring 00.00.0000
17776
17777 0 no optimization
17778 \layout List
17779 \labelwidthstring 00.00.0000
17780
17781 1 checks previous used register and if it is the same then does not emit
17782  BANKSEL, accounts only for labels.
17783 \layout List
17784 \labelwidthstring 00.00.0000
17785
17786 2 tries to check the location of (even different) symbols and removes BANKSELs
17787  if they are in the same bank.
17788
17789 \newline
17790
17791 \emph on
17792 Important: There might be problems if the linker script has data sections
17793  across bank borders!
17794 \end_deeper
17795 \layout Subsubsection
17796
17797 Linking Options
17798 \layout List
17799 \labelwidthstring 00.00.0000
17800
17801 -
17802 \begin_inset ERT
17803 status Collapsed
17804
17805 \layout Standard
17806
17807 \backslash
17808 /
17809 \end_inset
17810
17811 -nodefaultlibs do not link default libraries when linking
17812 \layout List
17813 \labelwidthstring 00.00.0000
17814
17815 -
17816 \begin_inset ERT
17817 status Collapsed
17818
17819 \layout Standard
17820
17821 \backslash
17822 /
17823 \end_inset
17824
17825 -no-crt Don't link the default run-time modules
17826 \layout List
17827 \labelwidthstring 00.00.0000
17828
17829 -
17830 \begin_inset ERT
17831 status Collapsed
17832
17833 \layout Standard
17834
17835 \backslash
17836 /
17837 \end_inset
17838
17839 -use-crt= Use a custom run-time module instead of the defaults.
17840 \layout Subsubsection
17841
17842 Debugging Options
17843 \layout Standard
17844
17845 Debugging options enable extra debugging information in the output files.
17846 \layout List
17847 \labelwidthstring 00.00.0000
17848
17849 -
17850 \begin_inset ERT
17851 status Collapsed
17852
17853 \layout Standard
17854
17855 \backslash
17856 /
17857 \end_inset
17858
17859 -debug-xtra Similar to -
17860 \begin_inset ERT
17861 status Collapsed
17862
17863 \layout Standard
17864
17865 \backslash
17866 /
17867 \end_inset
17868
17869 -debug
17870 \begin_inset LatexCommand \index{-\/-debug}
17871
17872 \end_inset
17873
17874 , but dumps more information.
17875 \layout List
17876 \labelwidthstring 00.00.0000
17877
17878 -
17879 \begin_inset ERT
17880 status Collapsed
17881
17882 \layout Standard
17883
17884 \backslash
17885 /
17886 \end_inset
17887
17888 -debug-ralloc Force register allocator to dump <source>.d file with debugging
17889  information.
17890  <source> is the name of the file compiled.
17891 \layout List
17892 \labelwidthstring 00.00.0000
17893
17894 -
17895 \begin_inset ERT
17896 status Collapsed
17897
17898 \layout Standard
17899
17900 \backslash
17901 /
17902 \end_inset
17903
17904 -pcode-verbose Enable pcode debugging information in translation.
17905 \layout List
17906 \labelwidthstring 00.00.0000
17907
17908 -
17909 \begin_inset ERT
17910 status Collapsed
17911
17912 \layout Standard
17913
17914 \backslash
17915 /
17916 \end_inset
17917
17918 -denable-peeps Force the usage of peepholes.
17919  Use with care.
17920 \layout List
17921 \labelwidthstring 00.00.0000
17922
17923 -
17924 \begin_inset ERT
17925 status Collapsed
17926
17927 \layout Standard
17928
17929 \backslash
17930 /
17931 \end_inset
17932
17933 -gstack Trace push/pops for stack pointer overflow
17934 \layout List
17935 \labelwidthstring 00.00.0000
17936
17937 -
17938 \begin_inset ERT
17939 status Collapsed
17940
17941 \layout Standard
17942
17943 \backslash
17944 /
17945 \end_inset
17946
17947 -call-tree dump call tree in .calltree file
17948 \layout Subsection
17949
17950 Enviromental Variables
17951 \layout Standard
17952
17953 There is a number of enviromental variables that can be used when running
17954  SDCC to enable certain optimizations or force a specific program behaviour.
17955  these variables are primarily for debugging purposes so they can be enabled/dis
17956 abled at will.
17957 \layout Standard
17958
17959 Currently there is only two such variables available:
17960 \layout List
17961 \labelwidthstring 00.00.0000
17962
17963 OPTIMIZE_BITFIELD_POINTER_GET when this variable exists reading of structure
17964  bitfields is optimized by directly loading FSR0 with the address of the
17965  bitfield structure.
17966  Normally SDCC will cast the bitfield structure to a bitfield pointer and
17967  then load FSR0.
17968  This step saves data ram and code space for functions that perform heavy
17969  use of bitfields.
17970  (ie.
17971  80 bytes of code space are saved when compiling malloc.c with this option).
17972
17973 \layout List
17974 \labelwidthstring 00.00.0000
17975
17976 NO_REG_OPT do not perform pCode registers optimization.
17977  This should be used for debugging purposes.
17978  In some where bugs in the pcode optimizer are found, users can benefit
17979  from temporarily disabling the optimizer until the bug is fixed.
17980 \layout Subsection
17981
17982 Preprocessor Macros
17983 \layout Standard
17984
17985 PIC16 port defines the following preprocessor macros while translating a
17986  source.
17987 \layout Standard
17988 \align center
17989
17990 \begin_inset  Tabular
17991 <lyxtabular version="3" rows="6" columns="2">
17992 <features>
17993 <column alignment="center" valignment="top" leftline="true" width="0">
17994 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17995 <row topline="true" bottomline="true">
17996 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17997 \begin_inset Text
17998
17999 \layout Standard
18000
18001 Macro
18002 \end_inset
18003 </cell>
18004 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18005 \begin_inset Text
18006
18007 \layout Standard
18008
18009 Description
18010 \end_inset
18011 </cell>
18012 </row>
18013 <row topline="true">
18014 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18015 \begin_inset Text
18016
18017 \layout Standard
18018
18019 SDCC_pic16
18020 \end_inset
18021 </cell>
18022 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18023 \begin_inset Text
18024
18025 \layout Standard
18026
18027 Port identification
18028 \end_inset
18029 </cell>
18030 </row>
18031 <row topline="true">
18032 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18033 \begin_inset Text
18034
18035 \layout Standard
18036
18037 _
18038 \begin_inset ERT
18039 status Collapsed
18040
18041 \layout Standard
18042
18043 \backslash
18044 /
18045 \end_inset
18046
18047 _pic16
18048 \end_inset
18049 </cell>
18050 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18051 \begin_inset Text
18052
18053 \layout Standard
18054
18055 Port identification (same as above)
18056 \end_inset
18057 </cell>
18058 </row>
18059 <row topline="true">
18060 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18061 \begin_inset Text
18062
18063 \layout Standard
18064
18065 pic18fxxxx
18066 \end_inset
18067 </cell>
18068 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18069 \begin_inset Text
18070
18071 \layout Standard
18072
18073 MCU Identification.
18074
18075 \emph on
18076 xxxx
18077 \emph default
18078  is the microcontrol identification number, i.e.
18079  452, 6620, etc
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 _
18090 \begin_inset ERT
18091 status Collapsed
18092
18093 \layout Standard
18094
18095 \backslash
18096 /
18097 \end_inset
18098
18099 _18Fxxxx
18100 \end_inset
18101 </cell>
18102 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18103 \begin_inset Text
18104
18105 \layout Standard
18106
18107 MCU Identification (same as above)
18108 \end_inset
18109 </cell>
18110 </row>
18111 <row topline="true" bottomline="true">
18112 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18113 \begin_inset Text
18114
18115 \layout Standard
18116
18117 STACK_MODEL_nnn
18118 \end_inset
18119 </cell>
18120 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18121 \begin_inset Text
18122
18123 \layout Standard
18124
18125 nnn = SMALL or LARGE respectively according to the stack model used
18126 \end_inset
18127 </cell>
18128 </row>
18129 </lyxtabular>
18130
18131 \end_inset
18132
18133
18134 \layout Standard
18135
18136 In addition the following macros are defined when calling assembler:
18137 \layout Standard
18138 \align center
18139
18140 \begin_inset  Tabular
18141 <lyxtabular version="3" rows="4" columns="2">
18142 <features>
18143 <column alignment="center" valignment="top" leftline="true" width="0">
18144 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18145 <row topline="true" bottomline="true">
18146 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18147 \begin_inset Text
18148
18149 \layout Standard
18150
18151 Macro
18152 \end_inset
18153 </cell>
18154 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18155 \begin_inset Text
18156
18157 \layout Standard
18158
18159 Description
18160 \end_inset
18161 </cell>
18162 </row>
18163 <row topline="true">
18164 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18165 \begin_inset Text
18166
18167 \layout Standard
18168
18169 __18Fxxxx
18170 \end_inset
18171 </cell>
18172 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18173 \begin_inset Text
18174
18175 \layout Standard
18176
18177 MCU Identification.
18178
18179 \emph on
18180 xxxx
18181 \emph default
18182  is the microcontrol identification number, i.e.
18183  452, 6620, etc
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 SDCC_MODEL_nnn
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 nnn = SMALL or LARGE respectively according to the memory model used for
18202  SDCC
18203 \end_inset
18204 </cell>
18205 </row>
18206 <row topline="true" bottomline="true">
18207 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18208 \begin_inset Text
18209
18210 \layout Standard
18211
18212 STACK_MODEL_nnn
18213 \end_inset
18214 </cell>
18215 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18216 \begin_inset Text
18217
18218 \layout Standard
18219
18220 nnn = SMALL or LARGE respectively according to the stack model used
18221 \end_inset
18222 </cell>
18223 </row>
18224 </lyxtabular>
18225
18226 \end_inset
18227
18228
18229 \layout Subsection
18230
18231 Directories
18232 \layout Standard
18233
18234 PIC16
18235 \begin_inset LatexCommand \index{PIC16}
18236
18237 \end_inset
18238
18239  port uses the following directories for searching header files and libraries.
18240 \layout Standard
18241 \align center
18242
18243 \begin_inset  Tabular
18244 <lyxtabular version="3" rows="3" columns="4">
18245 <features>
18246 <column alignment="center" valignment="top" leftline="true" width="0">
18247 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18248 <column alignment="center" valignment="top" width="0">
18249 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18250 <row topline="true" bottomline="true">
18251 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18252 \begin_inset Text
18253
18254 \layout Standard
18255
18256 Directory
18257 \end_inset
18258 </cell>
18259 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18260 \begin_inset Text
18261
18262 \layout Standard
18263
18264 Description
18265 \end_inset
18266 </cell>
18267 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18268 \begin_inset Text
18269
18270 \layout Standard
18271
18272 Target
18273 \end_inset
18274 </cell>
18275 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18276 \begin_inset Text
18277
18278 \layout Standard
18279
18280 Command prefix
18281 \end_inset
18282 </cell>
18283 </row>
18284 <row topline="true">
18285 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18286 \begin_inset Text
18287
18288 \layout Standard
18289
18290 PREFIX/sdcc/include/pic16
18291 \end_inset
18292 </cell>
18293 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18294 \begin_inset Text
18295
18296 \layout Standard
18297
18298 PIC16 specific headers
18299 \end_inset
18300 </cell>
18301 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18302 \begin_inset Text
18303
18304 \layout Standard
18305
18306 Compiler
18307 \end_inset
18308 </cell>
18309 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18310 \begin_inset Text
18311
18312 \layout Standard
18313
18314 -I
18315 \end_inset
18316 </cell>
18317 </row>
18318 <row topline="true" bottomline="true">
18319 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18320 \begin_inset Text
18321
18322 \layout Standard
18323
18324 PREFIX/sdcc/lib/pic16
18325 \end_inset
18326 </cell>
18327 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18328 \begin_inset Text
18329
18330 \layout Standard
18331
18332 PIC16 specific libraries
18333 \end_inset
18334 </cell>
18335 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18336 \begin_inset Text
18337
18338 \layout Standard
18339
18340 Linker
18341 \end_inset
18342 </cell>
18343 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18344 \begin_inset Text
18345
18346 \layout Standard
18347
18348 -L
18349 \end_inset
18350 </cell>
18351 </row>
18352 </lyxtabular>
18353
18354 \end_inset
18355
18356
18357 \layout Subsection
18358
18359 Pragmas
18360 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
18361
18362 \end_inset
18363
18364
18365 \layout Standard
18366
18367 PIC16 port currently supports the following pragmas:
18368 \layout List
18369 \labelwidthstring 00.00.0000
18370
18371 stack pragma stack forces the code generator to initialize the stack & frame
18372  pointers at a specific address.
18373  This is an adhoc solution for cases where no STACK directive is available
18374  in the linker script or gplink is not instructed to create a stack section.
18375 \newline
18376 The stack pragma should be used only once in a project.
18377  Multiple pragmas may result in indeterminate behaviour of the program.
18378 \begin_inset Foot
18379 collapsed false
18380
18381 \layout Standard
18382
18383 The old format (ie.
18384  #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
18385  cross page boundaries (or even exceed the available data RAM) and crash
18386  the program.
18387  Make sure that stack does not cross page boundaries when using the SMALL
18388  stack model.
18389 \end_inset
18390
18391
18392 \newline
18393 The format is as follows:
18394 \layout LyX-Code
18395
18396 #pragma stack bottom_address [stack_size]
18397 \layout Standard
18398
18399
18400 \emph on
18401 bottom_address
18402 \emph default
18403  is the lower bound of the stack section.
18404  The stack pointer initially will point at address (bottom_address+stack_size-1).
18405 \layout LyX-Code
18406
18407 Example:
18408 \layout LyX-Code
18409
18410 \layout LyX-Code
18411
18412 /* initializes stack of 100 bytes at RAM address 0x200 */
18413 \layout LyX-Code
18414
18415 #pragma stack 0x200 100
18416 \layout Standard
18417
18418 If the stack_size field is omitted then a stack is created with the default
18419  size of 64.
18420  This size might be enough for most programs, but its not enough for operations
18421  with deep function nesting or excessive stack usage.
18422 \layout List
18423 \labelwidthstring 00.00.0000
18424
18425 wparam
18426 \emph on
18427 This pragma is deprecated.
18428  Its use will cause a warning message to be issued.
18429 \emph default
18430
18431 \newline
18432
18433 \layout List
18434 \labelwidthstring 00.00.0000
18435
18436 code place a function symbol at static FLASH address
18437 \layout LyX-Code
18438
18439 Example:
18440 \layout LyX-Code
18441
18442 \layout LyX-Code
18443
18444 /* place function test_func at 0x4000 */
18445 \layout LyX-Code
18446
18447 #pragma code test_func 0x4000
18448 \layout LyX-Code
18449
18450 \layout List
18451 \labelwidthstring 00.00.0000
18452
18453 library instructs the linker to use a library module.
18454 \newline
18455 Usage:
18456 \layout LyX-Code
18457
18458 #pragma library module_name
18459 \layout Standard
18460
18461
18462 \emph on
18463 module_name
18464 \emph default
18465  can be any library or object file (including its path).
18466  Note that there are four reserved keywords which have special meaning.
18467  These are:
18468 \layout Standard
18469 \align center
18470
18471 \begin_inset  Tabular
18472 <lyxtabular version="3" rows="6" columns="3">
18473 <features>
18474 <column alignment="center" valignment="top" leftline="true" width="0">
18475 <column alignment="block" valignment="top" leftline="true" width="20page%">
18476 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
18477 <row topline="true" bottomline="true">
18478 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18479 \begin_inset Text
18480
18481 \layout Standard
18482
18483 Keyword
18484 \end_inset
18485 </cell>
18486 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18487 \begin_inset Text
18488
18489 \layout Standard
18490
18491 Description
18492 \end_inset
18493 </cell>
18494 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18495 \begin_inset Text
18496
18497 \layout Standard
18498
18499 Module to link
18500 \end_inset
18501 </cell>
18502 </row>
18503 <row topline="true">
18504 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18505 \begin_inset Text
18506
18507 \layout Standard
18508
18509
18510 \series bold
18511 ignore
18512 \end_inset
18513 </cell>
18514 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18515 \begin_inset Text
18516
18517 \layout Standard
18518
18519 ignore all library pragmas
18520 \end_inset
18521 </cell>
18522 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18523 \begin_inset Text
18524
18525 \layout Standard
18526
18527
18528 \emph on
18529 (none)
18530 \end_inset
18531 </cell>
18532 </row>
18533 <row topline="true">
18534 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18535 \begin_inset Text
18536
18537 \layout Standard
18538
18539
18540 \series bold
18541 c
18542 \end_inset
18543 </cell>
18544 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18545 \begin_inset Text
18546
18547 \layout Standard
18548
18549 link the C library
18550 \end_inset
18551 </cell>
18552 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18553 \begin_inset Text
18554
18555 \layout Standard
18556
18557
18558 \emph on
18559 libc18f
18560 \emph default
18561 .lib
18562 \end_inset
18563 </cell>
18564 </row>
18565 <row topline="true">
18566 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18567 \begin_inset Text
18568
18569 \layout Standard
18570
18571
18572 \series bold
18573 math
18574 \end_inset
18575 </cell>
18576 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18577 \begin_inset Text
18578
18579 \layout Standard
18580
18581 link the Math libarary
18582 \end_inset
18583 </cell>
18584 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18585 \begin_inset Text
18586
18587 \layout Standard
18588
18589
18590 \emph on
18591 libm18f
18592 \emph default
18593 .lib
18594 \end_inset
18595 </cell>
18596 </row>
18597 <row topline="true">
18598 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18599 \begin_inset Text
18600
18601 \layout Standard
18602
18603
18604 \series bold
18605 io
18606 \end_inset
18607 </cell>
18608 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18609 \begin_inset Text
18610
18611 \layout Standard
18612
18613 link the I/O library
18614 \end_inset
18615 </cell>
18616 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18617 \begin_inset Text
18618
18619 \layout Standard
18620
18621
18622 \emph on
18623 libio18f*
18624 \emph default
18625 .lib
18626 \end_inset
18627 </cell>
18628 </row>
18629 <row topline="true" bottomline="true">
18630 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18631 \begin_inset Text
18632
18633 \layout Standard
18634
18635
18636 \series bold
18637 debug
18638 \end_inset
18639 </cell>
18640 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18641 \begin_inset Text
18642
18643 \layout Standard
18644
18645 link the debug library
18646 \end_inset
18647 </cell>
18648 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18649 \begin_inset Text
18650
18651 \layout Standard
18652
18653
18654 \emph on
18655 libdebug
18656 \emph default
18657 .lib
18658 \end_inset
18659 </cell>
18660 </row>
18661 </lyxtabular>
18662
18663 \end_inset
18664
18665
18666 \newline
18667 * is the device number, i.e.
18668  452 for PIC18F452 MCU.
18669 \layout Standard
18670
18671 This feature allows for linking with specific libraries withoug having to
18672  explicit name them in the command line.
18673  Note that the
18674 \noun on
18675 ignore
18676 \noun default
18677  keyword will reject all modules specified by the library pragma.
18678 \layout List
18679 \labelwidthstring 00.00.0000
18680
18681 udata pragma udata instructs the compiler to emit code so that linker will
18682  place a variable at a specific memory bank
18683 \layout LyX-Code
18684
18685 Example:
18686 \layout LyX-Code
18687
18688 \layout LyX-Code
18689
18690 /* places variable foo at bank2 */
18691 \layout LyX-Code
18692
18693 #pragma udata bank2 foo
18694 \layout LyX-Code
18695
18696 char foo;
18697 \layout Standard
18698
18699 In order for this pragma to work extra SECTION directives should be added
18700  in the .lkr script.
18701  In the following example a sample .lkr file is shown:
18702 \layout LyX-Code
18703
18704 \layout LyX-Code
18705
18706 // Sample linker script for the PIC18F452 processor
18707 \layout LyX-Code
18708
18709 LIBPATH .
18710 \layout LyX-Code
18711
18712 CODEPAGE   NAME=vectors    START=0x0            END=0x29           PROTECTED
18713 \layout LyX-Code
18714
18715 CODEPAGE   NAME=page       START=0x2A           END=0x7FFF
18716 \layout LyX-Code
18717
18718 CODEPAGE   NAME=idlocs     START=0x200000       END=0x200007       PROTECTED
18719 \layout LyX-Code
18720
18721 CODEPAGE   NAME=config     START=0x300000       END=0x30000D       PROTECTED
18722 \layout LyX-Code
18723
18724 CODEPAGE   NAME=devid      START=0x3FFFFE       END=0x3FFFFF       PROTECTED
18725 \layout LyX-Code
18726
18727 CODEPAGE   NAME=eedata     START=0xF00000       END=0xF000FF       PROTECTED
18728 \layout LyX-Code
18729
18730 ACCESSBANK NAME=accessram  START=0x0            END=0x7F
18731 \layout LyX-Code
18732
18733 \layout LyX-Code
18734
18735 DATABANK   NAME=gpr0       START=0x80           END=0xFF
18736 \layout LyX-Code
18737
18738 DATABANK   NAME=gpr1       START=0x100          END=0x1FF
18739 \layout LyX-Code
18740
18741 DATABANK   NAME=gpr2       START=0x200          END=0x2FF
18742 \layout LyX-Code
18743
18744 DATABANK   NAME=gpr3       START=0x300          END=0x3FF
18745 \layout LyX-Code
18746
18747 DATABANK   NAME=gpr4       START=0x400          END=0x4FF
18748 \layout LyX-Code
18749
18750 DATABANK   NAME=gpr5       START=0x500          END=0x5FF
18751 \layout LyX-Code
18752
18753 ACCESSBANK NAME=accesssfr  START=0xF80          END=0xFFF          PROTECTED
18754 \layout LyX-Code
18755
18756 \layout LyX-Code
18757
18758 SECTION    NAME=CONFIG     ROM=config
18759 \layout LyX-Code
18760
18761 \layout LyX-Code
18762
18763 SECTION    NAME=bank0      RAM=gpr0       # these SECTION directives
18764 \layout LyX-Code
18765
18766 SECTION    NAME=bank1      RAM=gpr1       # should be added to link
18767 \layout LyX-Code
18768
18769 SECTION    NAME=bank2      RAM=gpr2       # section name 'bank?' with
18770 \layout LyX-Code
18771
18772 SECTION    NAME=bank3      RAM=gpr3       # a specific DATABANK name
18773 \layout LyX-Code
18774
18775 SECTION    NAME=bank4      RAM=gpr4
18776 \layout LyX-Code
18777
18778 SECTION    NAME=bank5      RAM=gpr5
18779 \layout Standard
18780
18781 The linker will recognise the section name set in the pragma statement and
18782  will position the variable at the memory bank set with the RAM field at
18783  the SECTION line in the linker script file.
18784 \layout Subsection
18785
18786 Header Files
18787 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
18788
18789 \end_inset
18790
18791
18792 \layout Standard
18793
18794 There is one main header file that can be included to the source files using
18795  the pic16 port.
18796  That file is the
18797 \series bold
18798 pic18fregs.h
18799 \series default
18800 .
18801  This header file contains the definitions for the processor special registers,
18802  so it is necessary if the source accesses them.
18803  It can be included by adding the following line in the beginning of the
18804  file:
18805 \layout LyX-Code
18806
18807 #include <pic18fregs.h>
18808 \layout Standard
18809
18810 The specific microcontroller is selected within the pic18fregs.h automatically,
18811  so the same source can be used with a variety of devices.
18812 \layout Subsection
18813
18814 Libraries
18815 \layout Standard
18816
18817 The libraries that PIC16
18818 \begin_inset LatexCommand \index{PIC16}
18819
18820 \end_inset
18821
18822  port depends on are the microcontroller device libraries which contain
18823  the symbol definitions for the microcontroller special function registers.
18824  These libraries have the format pic18fxxxx.lib, where
18825 \emph on
18826 xxxx
18827 \emph default
18828  is the microcontroller identification number.
18829  The specific library is selected automatically by the compiler at link
18830  stage according to the selected device.
18831 \layout Standard
18832
18833 Libraries are created with gplib which is part of the gputils package
18834 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
18835
18836 \end_inset
18837
18838 .
18839 \layout Subsubsection*
18840
18841 Building the libraries
18842 \layout Standard
18843
18844 Before using SDCC/pic16 there are some libraries that need to be compiled.
18845  This process is not done automatically by SDCC since not all users use
18846  SDCC for pic16 projects.
18847  So each user should compile the libraries separately.
18848 \layout Standard
18849
18850 The steps to compile the pic16 libraries under Linux are:
18851 \layout LyX-Code
18852
18853 cd device/lib/pic16
18854 \layout LyX-Code
18855
18856 ./configure
18857 \layout LyX-Code
18858
18859 make
18860 \layout LyX-Code
18861
18862 cd ..
18863 \layout LyX-Code
18864
18865 make model-pic16
18866 \layout LyX-Code
18867
18868 su -c 'make install'     # install the libraries, you need the root password
18869 \layout Standard
18870
18871 If you need to install the headers too, do:
18872 \layout LyX-Code
18873
18874 cd device/include
18875 \layout LyX-Code
18876
18877 su -c 'make install'     # install the headers, you need the root password
18878 \layout Standard
18879
18880 There exist a special target to build the I/O libraries.
18881  This target is not automatically build because it will build the I/O library
18882  for
18883 \emph on
18884 every
18885 \emph default
18886  supported device.
18887  This way building will take quite a lot of time.
18888  Users are advised to edit the
18889 \series bold
18890 device/lib/pic16/pics.build
18891 \series default
18892  file and then execute:
18893 \layout LyX-Code
18894
18895 make lib-io
18896 \layout Subsection
18897
18898 Memory Models
18899 \layout Standard
18900
18901 The following memory models are supported by the PIC16 port:
18902 \layout Itemize
18903
18904 small model
18905 \layout Itemize
18906
18907 large model
18908 \layout Standard
18909
18910 Memory model affects the default size of pointers within the source.
18911  The sizes are shown in the next table:
18912 \layout Standard
18913 \align center
18914
18915 \begin_inset  Tabular
18916 <lyxtabular version="3" rows="3" columns="3">
18917 <features>
18918 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18919 <column alignment="center" valignment="top" leftline="true" width="0">
18920 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18921 <row topline="true" bottomline="true">
18922 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18923 \begin_inset Text
18924
18925 \layout Standard
18926
18927 Pointer sizes according to memory model
18928 \end_inset
18929 </cell>
18930 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18931 \begin_inset Text
18932
18933 \layout Standard
18934
18935 small model
18936 \end_inset
18937 </cell>
18938 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18939 \begin_inset Text
18940
18941 \layout Standard
18942
18943 large model
18944 \end_inset
18945 </cell>
18946 </row>
18947 <row topline="true" bottomline="true">
18948 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18949 \begin_inset Text
18950
18951 \layout Standard
18952
18953 code pointers
18954 \end_inset
18955 </cell>
18956 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18957 \begin_inset Text
18958
18959 \layout Standard
18960
18961 16-bits
18962 \end_inset
18963 </cell>
18964 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18965 \begin_inset Text
18966
18967 \layout Standard
18968
18969 24-bits
18970 \end_inset
18971 </cell>
18972 </row>
18973 <row topline="true" bottomline="true">
18974 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18975 \begin_inset Text
18976
18977 \layout Standard
18978
18979 data pointers
18980 \end_inset
18981 </cell>
18982 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
18983 \begin_inset Text
18984
18985 \layout Standard
18986
18987 16-bits
18988 \end_inset
18989 </cell>
18990 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18991 \begin_inset Text
18992
18993 \layout Standard
18994
18995 16-bits
18996 \end_inset
18997 </cell>
18998 </row>
18999 </lyxtabular>
19000
19001 \end_inset
19002
19003
19004 \layout Standard
19005
19006 It is advisable that all sources within a project are compiled with the
19007  same memory model.
19008  If one wants to override the default memory model, this can be done by
19009  declaring a pointer as
19010 \series bold
19011 far
19012 \series default
19013  or
19014 \series bold
19015 near
19016 \series default
19017 .
19018  Far selects large memory model's pointers, while near selects small memory
19019  model's pointers.
19020 \layout Standard
19021
19022 The standard device libraries (see
19023 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
19024
19025 \end_inset
19026
19027 ) contain no reference to pointers, so they can be used with both memory
19028  models.
19029 \layout Subsection
19030
19031 Stack
19032 \layout Standard
19033
19034 The stack implementation for the PIC16 port uses two indirect registers,
19035  FSR1 and FSR2.
19036 \layout List
19037 \labelwidthstring 00.00.0000
19038
19039 FSR1 is assigned as stack pointer
19040 \layout List
19041 \labelwidthstring 00.00.0000
19042
19043 FSR2 is assigned as frame pointer
19044 \layout Standard
19045
19046 The following stack models are supported by the PIC16 port
19047 \layout Itemize
19048
19049
19050 \noun on
19051 small
19052 \noun default
19053  model
19054 \layout Itemize
19055
19056
19057 \noun on
19058 large
19059 \noun default
19060  model
19061 \layout Standard
19062
19063
19064 \noun on
19065 Small
19066 \noun default
19067  model means that only the FSRxL byte is used to access stack and frame,
19068  while
19069 \emph on
19070 \noun on
19071 large
19072 \emph default
19073 \noun default
19074  uses both FSRxL and FSRxH registers.
19075  The following table shows the stack/frame pointers sizes according to stack
19076  model and the maximum space they can address:
19077 \layout Standard
19078 \align center
19079
19080 \begin_inset  Tabular
19081 <lyxtabular version="3" rows="3" columns="3">
19082 <features>
19083 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19084 <column alignment="center" valignment="top" leftline="true" width="0">
19085 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19086 <row topline="true" bottomline="true">
19087 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19088 \begin_inset Text
19089
19090 \layout Standard
19091
19092 Stack & Frame pointer sizes according to stack model
19093 \end_inset
19094 </cell>
19095 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19096 \begin_inset Text
19097
19098 \layout Standard
19099
19100 small
19101 \end_inset
19102 </cell>
19103 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19104 \begin_inset Text
19105
19106 \layout Standard
19107
19108 large
19109 \end_inset
19110 </cell>
19111 </row>
19112 <row topline="true">
19113 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19114 \begin_inset Text
19115
19116 \layout Standard
19117
19118 Stack pointer FSR1
19119 \end_inset
19120 </cell>
19121 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19122 \begin_inset Text
19123
19124 \layout Standard
19125
19126 8-bits
19127 \end_inset
19128 </cell>
19129 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19130 \begin_inset Text
19131
19132 \layout Standard
19133
19134 16-bits
19135 \end_inset
19136 </cell>
19137 </row>
19138 <row topline="true" bottomline="true">
19139 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19140 \begin_inset Text
19141
19142 \layout Standard
19143
19144 Frame pointer FSR2
19145 \end_inset
19146 </cell>
19147 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19148 \begin_inset Text
19149
19150 \layout Standard
19151
19152 8-bits
19153 \end_inset
19154 </cell>
19155 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19156 \begin_inset Text
19157
19158 \layout Standard
19159
19160 16-bits
19161 \end_inset
19162 </cell>
19163 </row>
19164 </lyxtabular>
19165
19166 \end_inset
19167
19168
19169 \layout Standard
19170
19171
19172 \noun on
19173 Large
19174 \noun default
19175 stack model is currently not working properly throughout the code generator.
19176  So its use is not advised.
19177  Also there are some other points that need special care:
19178 \newline
19179
19180 \layout Enumerate
19181
19182 Do not create stack sections with size more than one physical bank (that
19183  is 256 bytes)
19184 \layout Enumerate
19185
19186 Stack sections should no cross physical bank limits (i.e.
19187  #pragma stack 0x50 0x100)
19188 \layout Standard
19189
19190 These limitations are caused by the fact that only FSRxL is modified when
19191  using SMALL stack model, so no more than 256 bytes of stack can be used.
19192  This problem will disappear after LARGE model is fully implemented.
19193 \layout Subsection
19194
19195 Functions
19196 \layout Standard
19197
19198 In addition to the standard SDCC function keywords, PIC16 port makes available
19199  two more:
19200 \layout List
19201 \labelwidthstring 00.00.0000
19202
19203 wparam Use the WREG to pass one byte of the first function argument.
19204  This improves speed but you may not use this for functions with arguments
19205  that are called via function pointers, otherwise the first byte of the
19206  first parameter will get lost.
19207  Usage:
19208 \layout LyX-Code
19209
19210 void func_wparam(int a) wparam
19211 \layout LyX-Code
19212
19213 {
19214 \layout LyX-Code
19215
19216     /* WREG hold the lower part of a */
19217 \layout LyX-Code
19218
19219     /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
19220  */
19221 \layout LyX-Code
19222
19223 ...
19224 \layout LyX-Code
19225
19226 }
19227 \layout Standard
19228
19229 This keyword replaces the deprecated wparam pragma.
19230 \layout List
19231 \labelwidthstring 00.00.0000
19232
19233 shadowregs When entering/exiting an ISR, it is possible to take advantage
19234  of the PIC18F hardware shadow registers which hold the values of WREG,
19235  STATUS and BSR registers.
19236  This can be done by adding the keyword
19237 \emph on
19238 shadowregs
19239 \emph default
19240  before the
19241 \emph on
19242 interrupt
19243 \emph default
19244  keyword in the function's header.
19245 \layout LyX-Code
19246
19247 void isr_shadow(void) shadowregs interrupt 1
19248 \layout LyX-Code
19249
19250 {
19251 \layout LyX-Code
19252
19253 ...
19254 \layout LyX-Code
19255
19256 }
19257 \layout Standard
19258
19259
19260 \emph on
19261 shadowregs
19262 \emph default
19263  instructs the code generator not to store/restore WREG, STATUS, BSR when
19264  entering/exiting the ISR.
19265 \layout Subsection
19266
19267 Function return values
19268 \layout Standard
19269
19270 Return values from functions are placed to the appropriate registers following
19271  a modified Microchip policy optimized for SDCC.
19272  The following table shows these registers:
19273 \layout Standard
19274 \align center
19275
19276 \begin_inset  Tabular
19277 <lyxtabular version="3" rows="6" columns="2">
19278 <features>
19279 <column alignment="center" valignment="top" leftline="true" width="0">
19280 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19281 <row topline="true" bottomline="true">
19282 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19283 \begin_inset Text
19284
19285 \layout Standard
19286
19287 size
19288 \end_inset
19289 </cell>
19290 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19291 \begin_inset Text
19292
19293 \layout Standard
19294
19295 destination register
19296 \end_inset
19297 </cell>
19298 </row>
19299 <row topline="true">
19300 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19301 \begin_inset Text
19302
19303 \layout Standard
19304
19305 8 bits
19306 \end_inset
19307 </cell>
19308 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19309 \begin_inset Text
19310
19311 \layout Standard
19312
19313 WREG
19314 \end_inset
19315 </cell>
19316 </row>
19317 <row topline="true">
19318 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19319 \begin_inset Text
19320
19321 \layout Standard
19322
19323 16 bits
19324 \end_inset
19325 </cell>
19326 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19327 \begin_inset Text
19328
19329 \layout Standard
19330
19331 PRODL:WREG
19332 \end_inset
19333 </cell>
19334 </row>
19335 <row topline="true">
19336 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19337 \begin_inset Text
19338
19339 \layout Standard
19340
19341 24 bits
19342 \end_inset
19343 </cell>
19344 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19345 \begin_inset Text
19346
19347 \layout Standard
19348
19349 PRODH:PRODL:WREG
19350 \end_inset
19351 </cell>
19352 </row>
19353 <row topline="true">
19354 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19355 \begin_inset Text
19356
19357 \layout Standard
19358
19359 32 bits
19360 \end_inset
19361 </cell>
19362 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19363 \begin_inset Text
19364
19365 \layout Standard
19366
19367 FSR0L:PRODH:PRODL:WREG
19368 \end_inset
19369 </cell>
19370 </row>
19371 <row topline="true" bottomline="true">
19372 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19373 \begin_inset Text
19374
19375 \layout Standard
19376
19377 >32 bits
19378 \end_inset
19379 </cell>
19380 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19381 \begin_inset Text
19382
19383 \layout Standard
19384
19385 on stack, FSR0 points to the beginning
19386 \end_inset
19387 </cell>
19388 </row>
19389 </lyxtabular>
19390
19391 \end_inset
19392
19393
19394 \layout Subsection
19395
19396 Interrupts
19397 \layout Standard
19398
19399 An interrupt servive routine (ISR) is declared using the
19400 \emph on
19401 interrupt
19402 \emph default
19403  keyword.
19404 \layout LyX-Code
19405
19406 void isr(void) interrupt
19407 \emph on
19408 n
19409 \layout LyX-Code
19410
19411 {
19412 \layout LyX-Code
19413
19414 ...
19415 \layout LyX-Code
19416
19417 }
19418 \layout Standard
19419
19420
19421 \emph on
19422 n
19423 \emph default
19424  is the interrupt number, which for PIC18F devices can be:
19425 \layout Standard
19426 \align center
19427
19428 \begin_inset  Tabular
19429 <lyxtabular version="3" rows="4" columns="3">
19430 <features>
19431 <column alignment="center" valignment="top" leftline="true" width="0">
19432 <column alignment="center" valignment="top" leftline="true" width="0">
19433 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19434 <row topline="true" bottomline="true">
19435 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19436 \begin_inset Text
19437
19438 \layout Standard
19439
19440
19441 \emph on
19442 n
19443 \end_inset
19444 </cell>
19445 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19446 \begin_inset Text
19447
19448 \layout Standard
19449
19450 Interrupt Vector
19451 \end_inset
19452 </cell>
19453 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19454 \begin_inset Text
19455
19456 \layout Standard
19457
19458 Interrupt Vector Address
19459 \end_inset
19460 </cell>
19461 </row>
19462 <row topline="true">
19463 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19464 \begin_inset Text
19465
19466 \layout Standard
19467
19468 0
19469 \end_inset
19470 </cell>
19471 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19472 \begin_inset Text
19473
19474 \layout Standard
19475
19476 RESET vector
19477 \end_inset
19478 </cell>
19479 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19480 \begin_inset Text
19481
19482 \layout Standard
19483
19484 0x000000
19485 \end_inset
19486 </cell>
19487 </row>
19488 <row topline="true">
19489 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19490 \begin_inset Text
19491
19492 \layout Standard
19493
19494
19495 \family roman
19496 \series medium
19497 \shape up
19498 \size normal
19499 \emph off
19500 \bar no
19501 \noun off
19502 \color none
19503 1
19504 \end_inset
19505 </cell>
19506 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19507 \begin_inset Text
19508
19509 \layout Standard
19510
19511
19512 \family roman
19513 \series medium
19514 \shape up
19515 \size normal
19516 \emph off
19517 \bar no
19518 \noun off
19519 \color none
19520 HIGH priority interrupts
19521 \end_inset
19522 </cell>
19523 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19524 \begin_inset Text
19525
19526 \layout Standard
19527
19528 0x000008
19529 \end_inset
19530 </cell>
19531 </row>
19532 <row topline="true" bottomline="true">
19533 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19534 \begin_inset Text
19535
19536 \layout Standard
19537
19538 2
19539 \end_inset
19540 </cell>
19541 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19542 \begin_inset Text
19543
19544 \layout Standard
19545
19546 LOW priority interrupts
19547 \end_inset
19548 </cell>
19549 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19550 \begin_inset Text
19551
19552 \layout Standard
19553
19554 0x000018
19555 \end_inset
19556 </cell>
19557 </row>
19558 </lyxtabular>
19559
19560 \end_inset
19561
19562
19563 \layout Standard
19564
19565 When generating assembly code for ISR the code generator places a
19566 \noun on
19567 goto
19568 \noun default
19569 instruction at the
19570 \emph on
19571 Interrupt Vector Address
19572 \emph default
19573  which points at the genetated ISR.
19574  This single GOTO instruction is part of an automatically generated
19575 \emph on
19576 interrupt entry point
19577 \emph default
19578  function.
19579  The actuall ISR code is placed as normally would in the code space.
19580  Upon interrupt request, the GOTO instruction is executed which jumps to
19581  the ISR code.
19582  When declaring interrupt functions as _naked this GOTO instruction is
19583 \series bold
19584 not
19585 \series default
19586  generated.
19587  The whole interrupt functions is therefore placed at the Interrupt Vector
19588  Address of the specific interrupt.
19589  This is not a problem for the LOW priority interrupts, but it is a problem
19590  for the RESET and the HIGH priority interrupts because code may be written
19591  at the next interrupt´s vector address and cause undeterminate program
19592  behaviour if that interrupt is raised.
19593 \begin_inset Foot
19594 collapsed false
19595
19596 \layout Standard
19597
19598 This is not a problem when
19599 \layout Enumerate
19600
19601 this is a HIGH interrupt ISR and LOW interrupts are
19602 \emph on
19603 disabled
19604 \emph default
19605  or not used.
19606 \layout Enumerate
19607
19608 when the ISR is small enough not to reach the next interrupt´s vector address.
19609 \end_inset
19610
19611
19612 \layout Standard
19613
19614
19615 \emph on
19616 n
19617 \emph default
19618  is possible to be omitted.
19619  This way a function is generated similar to an ISR, but it is not assigned
19620  to any interrupt.
19621 \layout Standard
19622
19623 When entering an interrupt, currently the PIC16
19624 \begin_inset LatexCommand \index{PIC16}
19625
19626 \end_inset
19627
19628  port automatically saves the following registers:
19629 \layout Itemize
19630
19631 WREG
19632 \layout Itemize
19633
19634 STATUS
19635 \layout Itemize
19636
19637 BSR
19638 \layout Itemize
19639
19640 PROD (PRODL and PRODH)
19641 \layout Itemize
19642
19643 FSR0 (FSR0L and FSR0H)
19644 \layout Standard
19645
19646 These registers are restored upon return from the interrupt routine.
19647 \begin_inset Foot
19648 collapsed false
19649
19650 \layout Standard
19651
19652 NOTE that when the _naked attribute is specified for an interrupt routine,
19653  then NO registers are stored or restored.
19654 \end_inset
19655
19656
19657 \layout Subsection
19658
19659 Generic Pointers
19660 \layout Standard
19661
19662 Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
19663  There are 3 types of generic pointers currently implemented data, code
19664  and eeprom pointers.
19665  They are differentiated by the value of the 7th and 6th bits of the upper
19666  byte:
19667 \layout Standard
19668 \align center
19669
19670 \begin_inset  Tabular
19671 <lyxtabular version="3" rows="5" columns="5">
19672 <features>
19673 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19674 <column alignment="center" valignment="top" width="0">
19675 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19676 <column alignment="center" valignment="top" width="0">
19677 <column alignment="left" valignment="top" rightline="true" width="0">
19678 <row topline="true" bottomline="true">
19679 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19680 \begin_inset Text
19681
19682 \layout Standard
19683
19684 pointer type
19685 \end_inset
19686 </cell>
19687 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19688 \begin_inset Text
19689
19690 \layout Standard
19691
19692 7th bit
19693 \end_inset
19694 </cell>
19695 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19696 \begin_inset Text
19697
19698 \layout Standard
19699
19700 6th bit
19701 \end_inset
19702 </cell>
19703 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19704 \begin_inset Text
19705
19706 \layout Standard
19707
19708 rest of the pointer
19709 \end_inset
19710 </cell>
19711 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19712 \begin_inset Text
19713
19714 \layout Standard
19715
19716 description
19717 \end_inset
19718 </cell>
19719 </row>
19720 <row topline="true" bottomline="true">
19721 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19722 \begin_inset Text
19723
19724 \layout Standard
19725
19726 data
19727 \end_inset
19728 </cell>
19729 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19730 \begin_inset Text
19731
19732 \layout Standard
19733
19734 1
19735 \end_inset
19736 </cell>
19737 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19738 \begin_inset Text
19739
19740 \layout Standard
19741
19742 0
19743 \end_inset
19744 </cell>
19745 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19746 \begin_inset Text
19747
19748 \layout Standard
19749
19750
19751 \family typewriter
19752 \shape slanted
19753 \emph on
19754 uuuuuu uuuuxxxx xxxxxxxx
19755 \end_inset
19756 </cell>
19757 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19758 \begin_inset Text
19759
19760 \layout Standard
19761
19762 a 12-bit data pointer in data RAM memory
19763 \end_inset
19764 </cell>
19765 </row>
19766 <row bottomline="true">
19767 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19768 \begin_inset Text
19769
19770 \layout Standard
19771
19772 code
19773 \end_inset
19774 </cell>
19775 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19776 \begin_inset Text
19777
19778 \layout Standard
19779
19780 0
19781 \end_inset
19782 </cell>
19783 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19784 \begin_inset Text
19785
19786 \layout Standard
19787
19788 0
19789 \end_inset
19790 </cell>
19791 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19792 \begin_inset Text
19793
19794 \layout Standard
19795
19796
19797 \family typewriter
19798 \shape slanted
19799 \emph on
19800 uxxxxx xxxxxxxx xxxxxxxx
19801 \end_inset
19802 </cell>
19803 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19804 \begin_inset Text
19805
19806 \layout Standard
19807
19808 a 21-bit code pointer in FLASH memory
19809 \end_inset
19810 </cell>
19811 </row>
19812 <row bottomline="true">
19813 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19814 \begin_inset Text
19815
19816 \layout Standard
19817
19818 eeprom
19819 \end_inset
19820 </cell>
19821 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19822 \begin_inset Text
19823
19824 \layout Standard
19825
19826 0
19827 \end_inset
19828 </cell>
19829 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19830 \begin_inset Text
19831
19832 \layout Standard
19833
19834 1
19835 \end_inset
19836 </cell>
19837 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19838 \begin_inset Text
19839
19840 \layout Standard
19841
19842
19843 \family typewriter
19844 \shape slanted
19845 \emph on
19846 uuuuuu uuuuuuxx xxxxxxxx
19847 \end_inset
19848 </cell>
19849 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19850 \begin_inset Text
19851
19852 \layout Standard
19853
19854 a 10-bit eeprom pointer in EEPROM memory
19855 \end_inset
19856 </cell>
19857 </row>
19858 <row bottomline="true">
19859 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19860 \begin_inset Text
19861
19862 \layout Standard
19863
19864 (unimplemented)
19865 \end_inset
19866 </cell>
19867 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19868 \begin_inset Text
19869
19870 \layout Standard
19871
19872 1
19873 \end_inset
19874 </cell>
19875 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19876 \begin_inset Text
19877
19878 \layout Standard
19879
19880 1
19881 \end_inset
19882 </cell>
19883 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19884 \begin_inset Text
19885
19886 \layout Standard
19887
19888
19889 \family typewriter
19890 \shape slanted
19891 \emph on
19892 xxxxxx xxxxxxxx xxxxxxxx
19893 \end_inset
19894 </cell>
19895 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19896 \begin_inset Text
19897
19898 \layout Standard
19899
19900 unimplemented pointer type
19901 \end_inset
19902 </cell>
19903 </row>
19904 </lyxtabular>
19905
19906 \end_inset
19907
19908
19909 \layout Standard
19910
19911 Generic pointer are read and written with a set of library functions which
19912  read/write 1, 2, 3, 4 bytes.
19913 \layout Subsection
19914
19915 PIC16 C Libraries
19916 \layout Subsubsection
19917
19918 Standard I/O Streams
19919 \layout Standard
19920
19921 In the
19922 \emph on
19923 stdio.h
19924 \emph default
19925  the type FILE is defined as:
19926 \layout LyX-Code
19927
19928 typedef char * FILE;
19929 \layout Standard
19930
19931 This type is the stream type implemented I/O in the PIC18F devices.
19932  Also the standard input and output streams are declared in stdio.h:
19933 \layout LyX-Code
19934
19935 extern FILE * stdin;
19936 \layout LyX-Code
19937
19938 extern FILE * stdout;
19939 \layout Standard
19940
19941 The FILE type is actually a generic pointer which defines one more type
19942  of generic pointers, the
19943 \emph on
19944 stream
19945 \emph default
19946 pointer.
19947  This new type has the format:
19948 \layout Standard
19949 \align center
19950
19951 \begin_inset  Tabular
19952 <lyxtabular version="3" rows="2" columns="7">
19953 <features>
19954 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19955 <column alignment="center" valignment="top" width="0">
19956 <column alignment="center" valignment="top" leftline="true" width="0">
19957 <column alignment="center" valignment="top" leftline="true" width="0">
19958 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19959 <column alignment="center" valignment="top" width="0">
19960 <column alignment="left" valignment="top" rightline="true" width="0">
19961 <row topline="true" bottomline="true">
19962 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19963 \begin_inset Text
19964
19965 \layout Standard
19966
19967 pointer type
19968 \end_inset
19969 </cell>
19970 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19971 \begin_inset Text
19972
19973 \layout Standard
19974
19975 <7:6>
19976 \end_inset
19977 </cell>
19978 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19979 \begin_inset Text
19980
19981 \layout Standard
19982
19983 <5>
19984 \end_inset
19985 </cell>
19986 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19987 \begin_inset Text
19988
19989 \layout Standard
19990
19991 <4>
19992 \end_inset
19993 </cell>
19994 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19995 \begin_inset Text
19996
19997 \layout Standard
19998
19999 <3:0>
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 rest of the pointer
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 descrption
20016 \end_inset
20017 </cell>
20018 </row>
20019 <row topline="true" bottomline="true">
20020 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20021 \begin_inset Text
20022
20023 \layout Standard
20024
20025 stream
20026 \end_inset
20027 </cell>
20028 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20029 \begin_inset Text
20030
20031 \layout Standard
20032
20033 00
20034 \end_inset
20035 </cell>
20036 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20037 \begin_inset Text
20038
20039 \layout Standard
20040
20041 1
20042 \end_inset
20043 </cell>
20044 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20045 \begin_inset Text
20046
20047 \layout Standard
20048
20049 0
20050 \end_inset
20051 </cell>
20052 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20053 \begin_inset Text
20054
20055 \layout Standard
20056
20057 nnnn
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
20066 \family typewriter
20067 \shape slanted
20068 \emph on
20069 uuuuuuuu uuuuuuuu
20070 \end_inset
20071 </cell>
20072 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20073 \begin_inset Text
20074
20075 \layout Standard
20076
20077 upper byte high nubble is 0x2n, the rest are zeroes
20078 \end_inset
20079 </cell>
20080 </row>
20081 </lyxtabular>
20082
20083 \end_inset
20084
20085
20086 \layout Standard
20087
20088 Currently implemented there are 3 types of streams defined:
20089 \layout Standard
20090 \align center
20091
20092 \begin_inset  Tabular
20093 <lyxtabular version="3" rows="4" columns="4">
20094 <features>
20095 <column alignment="center" valignment="top" leftline="true" width="0">
20096 <column alignment="center" valignment="top" leftline="true" width="0">
20097 <column alignment="center" valignment="top" leftline="true" width="0">
20098 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20099 <row topline="true" bottomline="true">
20100 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20101 \begin_inset Text
20102
20103 \layout Standard
20104
20105 stream type
20106 \end_inset
20107 </cell>
20108 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20109 \begin_inset Text
20110
20111 \layout Standard
20112
20113 value
20114 \end_inset
20115 </cell>
20116 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20117 \begin_inset Text
20118
20119 \layout Standard
20120
20121 module
20122 \end_inset
20123 </cell>
20124 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20125 \begin_inset Text
20126
20127 \layout Standard
20128
20129 description
20130 \end_inset
20131 </cell>
20132 </row>
20133 <row topline="true">
20134 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20135 \begin_inset Text
20136
20137 \layout Standard
20138
20139 STREAM_USART
20140 \end_inset
20141 </cell>
20142 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20143 \begin_inset Text
20144
20145 \layout Standard
20146
20147
20148 \family typewriter
20149 0x200000UL
20150 \end_inset
20151 </cell>
20152 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20153 \begin_inset Text
20154
20155 \layout Standard
20156
20157 USART
20158 \end_inset
20159 </cell>
20160 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20161 \begin_inset Text
20162
20163 \layout Standard
20164
20165 Writes/Reads characters via the USART peripheral
20166 \end_inset
20167 </cell>
20168 </row>
20169 <row topline="true">
20170 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20171 \begin_inset Text
20172
20173 \layout Standard
20174
20175 STREAM_MSSP
20176 \end_inset
20177 </cell>
20178 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20179 \begin_inset Text
20180
20181 \layout Standard
20182
20183
20184 \family typewriter
20185 0x210000UL
20186 \end_inset
20187 </cell>
20188 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20189 \begin_inset Text
20190
20191 \layout Standard
20192
20193 MSSP
20194 \end_inset
20195 </cell>
20196 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20197 \begin_inset Text
20198
20199 \layout Standard
20200
20201 Writes/Reads characters via the MSSP peripheral
20202 \end_inset
20203 </cell>
20204 </row>
20205 <row topline="true" bottomline="true">
20206 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20207 \begin_inset Text
20208
20209 \layout Standard
20210
20211 STREAM_USER
20212 \end_inset
20213 </cell>
20214 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20215 \begin_inset Text
20216
20217 \layout Standard
20218
20219
20220 \family typewriter
20221 0x2f0000UL
20222 \end_inset
20223 </cell>
20224 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20225 \begin_inset Text
20226
20227 \layout Standard
20228
20229 (none)
20230 \end_inset
20231 </cell>
20232 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20233 \begin_inset Text
20234
20235 \layout Standard
20236
20237 Writes/Reads characters via used defined functions
20238 \end_inset
20239 </cell>
20240 </row>
20241 </lyxtabular>
20242
20243 \end_inset
20244
20245
20246 \layout Standard
20247
20248 The stream identifiers are declared as macros in the stdio.h header.
20249 \layout Standard
20250
20251 In the libc library there exist the functions that are used to write to
20252  each of the above streams.
20253  These are
20254 \layout List
20255 \labelwidthstring 00.00.0000
20256
20257 _
20258 \begin_inset ERT
20259 status Collapsed
20260
20261 \layout Standard
20262
20263 \backslash
20264 /
20265 \end_inset
20266
20267 _stream_usart_putchar writes a character at the USART stream
20268 \layout List
20269 \labelwidthstring 00.00.0000
20270
20271 _
20272 \begin_inset ERT
20273 status Collapsed
20274
20275 \layout Standard
20276
20277 \backslash
20278 /
20279 \end_inset
20280
20281 _stream_mssp_putchar writes a character at the MSSP stream
20282 \layout List
20283 \labelwidthstring 00.00.0000
20284
20285 putchar dummy function.
20286  This writes a character to a user specified manner.
20287 \layout Standard
20288
20289 In order to increase performance
20290 \emph on
20291 putchar
20292 \emph default
20293 is declared in stdio.h as having its parameter in WREG (it has the wparam
20294  keyword).
20295  In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
20296  in a user-friendly way.
20297
20298 \emph on
20299 arg
20300 \emph default
20301  is the name of the variable that holds the character to print.
20302  An example follows:
20303 \layout LyX-Code
20304
20305 #include <pic18fregs.h>
20306 \newline
20307 #include <stdio.h>
20308 \newline
20309
20310 \newline
20311 PUTCHAR( c )
20312 \layout LyX-Code
20313
20314 {
20315 \layout LyX-Code
20316
20317     PORTA = c;    /* dump character c to PORTA */
20318 \layout LyX-Code
20319
20320 }
20321 \newline
20322
20323 \newline
20324 void main(void)
20325 \layout LyX-Code
20326
20327 {
20328 \layout LyX-Code
20329
20330     stdout = STREAM_USER;    /* this is not necessary, since stdout points
20331 \layout LyX-Code
20332
20333                               * by default to STREAM_USER */
20334 \layout LyX-Code
20335
20336     printf (¨This is a printf test
20337 \backslash
20338 n¨);
20339 \layout LyX-Code
20340
20341 }
20342 \layout LyX-Code
20343
20344 \layout Subsubsection
20345
20346 Printing functions
20347 \layout Standard
20348
20349 PIC16 contains an implementation of the printf-family of functions.
20350  There exist the following functions:
20351 \layout LyX-Code
20352
20353 extern unsigned int sprintf(char *buf, char *fmt, ...);
20354 \layout LyX-Code
20355
20356 extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
20357 \layout LyX-Code
20358
20359 \layout LyX-Code
20360
20361 extern unsigned int printf(char *fmt, ...);
20362 \layout LyX-Code
20363
20364 extern unsigned int vprintf(char *fmt, va_lista ap);
20365 \layout LyX-Code
20366
20367 \layout LyX-Code
20368
20369 extern unsigned int fprintf(FILE *fp, char *fmt, ...);
20370 \layout LyX-Code
20371
20372 extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
20373 \layout Standard
20374
20375 For sprintf and vsprintf
20376 \emph on
20377 buf
20378 \emph default
20379 should normally be a data pointer where the resulting string will be placed.
20380  No range checking is done so the user should allocate the necessery buffer.
20381  For fprintf and vfprintf
20382 \emph on
20383 fp
20384 \emph default
20385  should be a stream pointer (i.e.
20386  stdout, STREAM_MSSP, etc...).
20387 \layout Subsubsection
20388
20389 Signals
20390 \layout Standard
20391
20392 The PIC18F family of microcontrollers supports a number of interrupt sources.
20393  A list of these interrupts is shown in the following table:
20394 \layout Standard
20395 \align center
20396
20397 \begin_inset  Tabular
20398 <lyxtabular version="3" rows="11" columns="4">
20399 <features>
20400 <column alignment="left" valignment="top" leftline="true" width="0">
20401 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20402 <column alignment="left" valignment="top" leftline="true" width="0">
20403 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20404 <row topline="true" bottomline="true">
20405 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20406 \begin_inset Text
20407
20408 \layout Standard
20409
20410 signal name
20411 \end_inset
20412 </cell>
20413 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20414 \begin_inset Text
20415
20416 \layout Standard
20417
20418 description
20419 \end_inset
20420 </cell>
20421 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20422 \begin_inset Text
20423
20424 \layout Standard
20425
20426 signal name
20427 \end_inset
20428 </cell>
20429 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20430 \begin_inset Text
20431
20432 \layout Standard
20433
20434 descritpion
20435 \end_inset
20436 </cell>
20437 </row>
20438 <row topline="true">
20439 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20440 \begin_inset Text
20441
20442 \layout Standard
20443
20444 SIG_RB
20445 \end_inset
20446 </cell>
20447 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20448 \begin_inset Text
20449
20450 \layout Standard
20451
20452 PORTB change interrupt
20453 \end_inset
20454 </cell>
20455 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20456 \begin_inset Text
20457
20458 \layout Standard
20459
20460 SIG_EE
20461 \end_inset
20462 </cell>
20463 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20464 \begin_inset Text
20465
20466 \layout Standard
20467
20468 EEPROM/FLASH write complete interrupt
20469 \end_inset
20470 </cell>
20471 </row>
20472 <row topline="true">
20473 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20474 \begin_inset Text
20475
20476 \layout Standard
20477
20478 SIG_INT0
20479 \end_inset
20480 </cell>
20481 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20482 \begin_inset Text
20483
20484 \layout Standard
20485
20486 INT0 external interrupt
20487 \end_inset
20488 </cell>
20489 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20490 \begin_inset Text
20491
20492 \layout Standard
20493
20494 SIG_BCOL
20495 \end_inset
20496 </cell>
20497 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20498 \begin_inset Text
20499
20500 \layout Standard
20501
20502 Bus collision interrupt
20503 \end_inset
20504 </cell>
20505 </row>
20506 <row topline="true">
20507 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20508 \begin_inset Text
20509
20510 \layout Standard
20511
20512 SIG_INT1
20513 \end_inset
20514 </cell>
20515 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20516 \begin_inset Text
20517
20518 \layout Standard
20519
20520 INT1 external interrupt
20521 \end_inset
20522 </cell>
20523 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20524 \begin_inset Text
20525
20526 \layout Standard
20527
20528 SIG_LVD
20529 \end_inset
20530 </cell>
20531 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20532 \begin_inset Text
20533
20534 \layout Standard
20535
20536 Low voltage detect interrupt
20537 \end_inset
20538 </cell>
20539 </row>
20540 <row topline="true">
20541 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20542 \begin_inset Text
20543
20544 \layout Standard
20545
20546 SIG_INT2
20547 \end_inset
20548 </cell>
20549 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20550 \begin_inset Text
20551
20552 \layout Standard
20553
20554 INT2 external interrupt
20555 \end_inset
20556 </cell>
20557 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20558 \begin_inset Text
20559
20560 \layout Standard
20561
20562 SIG_PSP
20563 \end_inset
20564 </cell>
20565 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20566 \begin_inset Text
20567
20568 \layout Standard
20569
20570 Parallel slave port interrupt
20571 \end_inset
20572 </cell>
20573 </row>
20574 <row topline="true">
20575 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20576 \begin_inset Text
20577
20578 \layout Standard
20579
20580 SIG_CCP1
20581 \end_inset
20582 </cell>
20583 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20584 \begin_inset Text
20585
20586 \layout Standard
20587
20588 CCP1 module interrupt
20589 \end_inset
20590 </cell>
20591 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20592 \begin_inset Text
20593
20594 \layout Standard
20595
20596 SIG_AD
20597 \end_inset
20598 </cell>
20599 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20600 \begin_inset Text
20601
20602 \layout Standard
20603
20604 AD convertion complete interrupt
20605 \end_inset
20606 </cell>
20607 </row>
20608 <row topline="true">
20609 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20610 \begin_inset Text
20611
20612 \layout Standard
20613
20614 SIG_CCP2
20615 \end_inset
20616 </cell>
20617 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20618 \begin_inset Text
20619
20620 \layout Standard
20621
20622 CCP2 module interrupt
20623 \end_inset
20624 </cell>
20625 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20626 \begin_inset Text
20627
20628 \layout Standard
20629
20630 SIG_RC
20631 \end_inset
20632 </cell>
20633 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20634 \begin_inset Text
20635
20636 \layout Standard
20637
20638 USART receive interrupt
20639 \end_inset
20640 </cell>
20641 </row>
20642 <row topline="true">
20643 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20644 \begin_inset Text
20645
20646 \layout Standard
20647
20648 SIG_TMR0
20649 \end_inset
20650 </cell>
20651 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20652 \begin_inset Text
20653
20654 \layout Standard
20655
20656 TMR0 overflow interrupt
20657 \end_inset
20658 </cell>
20659 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20660 \begin_inset Text
20661
20662 \layout Standard
20663
20664 SIG_TX
20665 \end_inset
20666 </cell>
20667 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20668 \begin_inset Text
20669
20670 \layout Standard
20671
20672 USART transmit interrupt
20673 \end_inset
20674 </cell>
20675 </row>
20676 <row topline="true">
20677 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20678 \begin_inset Text
20679
20680 \layout Standard
20681
20682 SIG_TMR1
20683 \end_inset
20684 </cell>
20685 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20686 \begin_inset Text
20687
20688 \layout Standard
20689
20690 TMR1 overflow interrupt
20691 \end_inset
20692 </cell>
20693 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20694 \begin_inset Text
20695
20696 \layout Standard
20697
20698 SIG_MSSP
20699 \end_inset
20700 </cell>
20701 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20702 \begin_inset Text
20703
20704 \layout Standard
20705
20706 SSP receive/transmit interrupt
20707 \end_inset
20708 </cell>
20709 </row>
20710 <row topline="true">
20711 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20712 \begin_inset Text
20713
20714 \layout Standard
20715
20716 SIG_TMR2
20717 \end_inset
20718 </cell>
20719 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20720 \begin_inset Text
20721
20722 \layout Standard
20723
20724 TMR2 matches PR2 interrupt
20725 \end_inset
20726 </cell>
20727 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20728 \begin_inset Text
20729
20730 \layout Standard
20731
20732 \end_inset
20733 </cell>
20734 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20735 \begin_inset Text
20736
20737 \layout Standard
20738
20739 \end_inset
20740 </cell>
20741 </row>
20742 <row topline="true" bottomline="true">
20743 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20744 \begin_inset Text
20745
20746 \layout Standard
20747
20748 SIG_TMR3
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 TMR3 overflow interrupt
20757 \end_inset
20758 </cell>
20759 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20760 \begin_inset Text
20761
20762 \layout Standard
20763
20764 \end_inset
20765 </cell>
20766 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20767 \begin_inset Text
20768
20769 \layout Standard
20770
20771 \end_inset
20772 </cell>
20773 </row>
20774 </lyxtabular>
20775
20776 \end_inset
20777
20778
20779 \layout Standard
20780
20781 The prototypes for these names are defined in the header file
20782 \emph on
20783 signal.h
20784 \emph default
20785  .
20786 \layout Standard
20787
20788 In order to simplify signal handling, a number of macros is provided:
20789 \layout List
20790 \labelwidthstring 00.00.0000
20791
20792 DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
20793  high priority interrupts.
20794
20795 \emph on
20796 name
20797 \emph default
20798  is the function name to use.
20799 \layout List
20800 \labelwidthstring 00.00.0000
20801
20802 DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
20803  low priority interrupt.
20804
20805 \emph on
20806 name
20807 \emph default
20808  is the function name to use.
20809 \layout List
20810 \labelwidthstring 00.00.0000
20811
20812 DEF_HANDLER(sig,handler) define a handler for signal
20813 \emph on
20814 sig.
20815 \layout List
20816 \labelwidthstring 00.00.0000
20817
20818 END_DEF end the declaration of the dispatch table.
20819 \layout Standard
20820
20821 Additionally there are two more macros to simplify the declaration of the
20822  signal handler:
20823 \layout List
20824 \labelwidthstring 00.00.0000
20825
20826
20827 \series medium
20828 SIGHANDLER(handler)
20829 \series default
20830 this declares the function prototype for the
20831 \emph on
20832 handler
20833 \emph default
20834  function.
20835 \layout List
20836 \labelwidthstring 00.00.0000
20837
20838 SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
20839 \layout Standard
20840
20841 An example of using the macros above is shown below:
20842 \layout LyX-Code
20843
20844 #include <pic18fregs.h>
20845 \layout LyX-Code
20846
20847 #include <signal.h>
20848 \newline
20849
20850 \newline
20851 DEF_INTHIGH(high_int)
20852 \layout LyX-Code
20853
20854 DEF_HANDLER(SIG_TMR0, _tmr0_handler)
20855 \layout LyX-Code
20856
20857 DEF_HANDLER(SIG_BCOL, _bcol_handler)
20858 \layout LyX-Code
20859
20860 END_DEF
20861 \newline
20862
20863 \newline
20864 SIGHANDLER(_tmr0_handler)
20865 \layout LyX-Code
20866
20867 {
20868 \layout LyX-Code
20869
20870   /* action to be taken when timer 0 overflows */
20871 \layout LyX-Code
20872
20873 }
20874 \newline
20875
20876 \newline
20877 SIGHANDLERNAKED(_bcol_handler)
20878 \layout LyX-Code
20879
20880 {
20881 \layout LyX-Code
20882
20883   _asm
20884 \layout LyX-Code
20885
20886     /* action to be taken when bus collision occurs */
20887 \layout LyX-Code
20888
20889     retfie
20890 \layout LyX-Code
20891
20892  _endasm;
20893 \layout LyX-Code
20894
20895 }
20896 \layout Standard
20897
20898
20899 \series bold
20900 NOTES:
20901 \series default
20902  Special care should be taken when using the above scheme:
20903 \layout Itemize
20904
20905 do not place a colon (;) at the end of the DEF_* and END_DEF macros.
20906 \layout Itemize
20907
20908 when declaring SIGHANDLERNAKED handler never forget to use
20909 \emph on
20910 retfie
20911 \emph default
20912  for proper returning.
20913 \layout Subsection
20914
20915 PIC16 Port -- Tips
20916 \layout Standard
20917
20918 Here you can find some general tips for compiling programs with SDCC/pic16.
20919 \layout Subsubsection
20920
20921 Stack size
20922 \layout Standard
20923
20924 The default stack size (that is 64 bytes) probably is enough for many programs.
20925  One must take care that when there are many levels of function nesting,
20926  or there is excessive usage of stack, its size should be extended.
20927  An example of such a case is the printf/sprintf family of functions.
20928  If you encounter problems like not being able to print integers, then you
20929  need to set the stack size around the maximum (256 for small stack model).
20930  The following diagram shows what happens when calling printf to print an
20931  integer:
20932 \layout LyX-Code
20933
20934 printf () --> ltoa () --> ultoa () --> divschar ()
20935 \layout Standard
20936
20937 It is should be understood that stack is easily consumed when calling complicate
20938 d functions.
20939  Using command line arguments like -
20940 \begin_inset ERT
20941 status Collapsed
20942
20943 \layout Standard
20944
20945 \backslash
20946 /
20947 \end_inset
20948
20949 -fommit-frame-pointer might reduce stack usage by not creating unnecessery
20950  stack frames.
20951  Other ways to reduce stack usage may exist.
20952 \layout Chapter
20953
20954 Debugging
20955 \layout Standard
20956
20957 There are several approaches to debugging your code.
20958  This chapter is meant to show your options and to give detail on some of
20959  them:
20960 \newline
20961
20962 \newline
20963 When writing your code:
20964 \layout Itemize
20965
20966 write your code with debugging in mind (avoid duplicating code, put conceptually
20967  similar variables into structs, use structured code, have strategic points
20968  within your code where all variables are consistent, ...)
20969 \layout Itemize
20970
20971 run a syntax-checking tool like splint
20972 \begin_inset LatexCommand \index{splint (syntax checking tool)}
20973
20974 \end_inset
20975
20976
20977 \begin_inset LatexCommand \index{lint (syntax checking tool)}
20978
20979 \end_inset
20980
20981  (see -
20982 \begin_inset ERT
20983 status Collapsed
20984
20985 \layout Standard
20986
20987 \backslash
20988 /
20989 \end_inset
20990
20991 -more-pedantic
20992 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
20993
20994 \end_inset
20995
20996 ) over the code.
20997 \layout Itemize
20998
20999 for the high level code use a C-compiler (like f.e.
21000  GCC) to compile run and debug the code on your host.
21001  See (see -
21002 \begin_inset ERT
21003 status Collapsed
21004
21005 \layout Standard
21006
21007 \backslash
21008 /
21009 \end_inset
21010
21011 -more-pedantic
21012 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
21013
21014 \end_inset
21015
21016  ) on howto handle syntax extensions like __xdata, __at(), ...
21017
21018 \layout Itemize
21019
21020 use another C-compiler to compile code for your target.
21021  Always an option but not recommended:) And not very likely to help you.
21022  If you seriously consider walking this path you should at least occasionally
21023  check portability of your code.
21024  Most commercial compiler vendors will offer an evaluation version so you
21025  can test compile your code or snippets of your code.
21026 \layout Standard
21027
21028 Debugging on a simulator:
21029 \layout Itemize
21030
21031 there is a separate section about SDCDB (section
21032 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
21033
21034 \end_inset
21035
21036 ) below.
21037 \layout Itemize
21038
21039 or (8051 specific) use a freeware/commercial simulator which interfaces
21040  to the AOMF
21041 \begin_inset LatexCommand \index{AOMF, AOMF51}
21042
21043 \end_inset
21044
21045  file (see
21046 \begin_inset LatexCommand \ref{OMF file}
21047
21048 \end_inset
21049
21050 ) optionally generated by SDCC.
21051 \layout Standard
21052
21053 Debugging On-target:
21054 \layout Itemize
21055
21056 use a MCU port pin to serially output debug data to the RS232 port of your
21057  host.
21058  You'll probably want some level shifting device typically involving a MAX232
21059  or similar IC.
21060  If the hardware serial port of the MCU is not available search for 'Software
21061  UART' in your favourite search machine.
21062 \layout Itemize
21063
21064 use an on-target monitor.
21065  In this context a monitor is a small program which usually accepts commands
21066  via a serial line and allows to set program counter, to single step through
21067  a program and read/write memory locations.
21068  For the 8051 good examples of monitors are paulmon and cmon51 (see section
21069
21070 \begin_inset LatexCommand \ref{sec:Related-open-source-tools}
21071
21072 \end_inset
21073
21074 ).
21075 \layout Itemize
21076
21077 toggle MCU port pins at strategic points within your code and use an oscilloscop
21078 e.
21079  A
21080 \emph on
21081 digital oscilloscope
21082 \emph default
21083
21084 \begin_inset LatexCommand \index{oscilloscope}
21085
21086 \end_inset
21087
21088  with deep trace memory is really helpful especially if you have to debug
21089  a realtime application.
21090  If you need to monitor more pins than your oscilloscope provides you can
21091  sometimes get away with a small R-2R network.
21092  On a single channel oscilloscope you could f.e.
21093  monitor 2 push-pull driven pins by connecting one via a 10\SpecialChar ~
21094 k
21095 \begin_inset Formula $\Omega$
21096 \end_inset
21097
21098  resistor and the other one by a 5\SpecialChar ~
21099 k
21100 \begin_inset Formula $\Omega$
21101 \end_inset
21102
21103  resistor to the oscilloscope probe (check output drive capability of the
21104  pins you want to monitor).
21105  If you need to monitor many more pins a
21106 \emph on
21107 logic analyzer
21108 \emph default
21109  will be handy.
21110 \layout Itemize
21111
21112 use an ICE (
21113 \emph on
21114 i
21115 \emph default
21116 n
21117 \emph on
21118 c
21119 \emph default
21120 ircuit
21121 \emph on
21122 e
21123 \emph default
21124 mulator
21125 \begin_inset LatexCommand \index{ICE (in circuit emulator)}
21126
21127 \end_inset
21128
21129 ).
21130  Usually very expensive.
21131  And very nice to have too.
21132  And usually locks you (for years...) to the devices the ICE can emulate.
21133
21134 \layout Itemize
21135
21136 use a remote debugger.
21137  In most 8-bit systems the symbol information is not available on the target,
21138  and a complete debugger is too bulky for the target system.
21139  Therefore usually a debugger on the host system connects to an on-target
21140  debugging stub which accepts only primitive commands.
21141
21142 \newline
21143 Terms to enter into your favourite search engine could be 'remote debugging',
21144  'gdb stub' or 'inferior debugger'.
21145  (is there one?)
21146 \layout Itemize
21147
21148 use an on target hardware debugger.
21149  Some of the more modern MCUs include hardware support for setting break
21150  points and monitoring/changing variables by using dedicated hardware pins.
21151  This facility doesn't require additional code to run on the target and
21152
21153 \emph on
21154 usually
21155 \emph default
21156  doesn't affect runtime behaviour until a breakpoint is hit.
21157  For the mcs51 most hardware debuggers use the AOMF
21158 \begin_inset LatexCommand \index{AOMF, AOMF51}
21159
21160 \end_inset
21161
21162  file (see
21163 \begin_inset LatexCommand \ref{OMF file}
21164
21165 \end_inset
21166
21167 ) as input file.
21168
21169 \layout Standard
21170
21171 Last not least:
21172 \layout Itemize
21173
21174 if you are not familiar with any of the following terms you're likely to
21175  run into problems rather sooner than later:
21176 \emph on
21177 volatile
21178 \emph default
21179 ,
21180 \emph on
21181 atomic
21182 \emph default
21183 ,
21184 \emph on
21185 memory map
21186 \emph default
21187 ,
21188 \emph on
21189 overlay
21190 \emph default
21191 .
21192  As an embedded programmer you
21193 \emph on
21194 have
21195 \emph default
21196  to know them so why not look them up
21197 \emph on
21198 before
21199 \emph default
21200  you have problems?)
21201 \layout Itemize
21202
21203 tell someone else about your problem (actually this is a surprisingly effective
21204  means to hunt down the bug even if the listener is not familiar with your
21205  environment).
21206  As 'failure to communicate' is probably one of the job-induced deformations
21207  of an embedded programmer this is highly encouraged.
21208 \layout Section
21209
21210 Debugging with SDCDB
21211 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
21212
21213 \end_inset
21214
21215
21216 \begin_inset LatexCommand \index{SDCDB (debugger)}
21217
21218 \end_inset
21219
21220
21221 \layout Standard
21222
21223 SDCC is distributed with a source level debugger
21224 \begin_inset LatexCommand \index{Debugger}
21225
21226 \end_inset
21227
21228 .
21229  The debugger uses a command line interface, the command repertoire of the
21230  debugger has been kept as close to gdb
21231 \begin_inset LatexCommand \index{gdb}
21232
21233 \end_inset
21234
21235  (the GNU debugger) as possible.
21236  The configuration and build process is part of the standard compiler installati
21237 on, which also builds and installs the debugger in the target directory
21238  specified during configuration.
21239  The debugger allows you debug BOTH at the C source and at the ASM source
21240  level.
21241 \layout Subsection
21242
21243 Compiling for Debugging
21244 \layout Standard
21245
21246 The -
21247 \begin_inset ERT
21248 status Collapsed
21249
21250 \layout Standard
21251
21252 \backslash
21253 /
21254 \end_inset
21255
21256 -debug
21257 \begin_inset LatexCommand \index{-\/-debug}
21258
21259 \end_inset
21260
21261  option must be specified for all files for which debug information is to
21262  be generated.
21263  The compiler generates a .adb file for each of these files.
21264  The linker creates the .cdb
21265 \begin_inset LatexCommand \index{<file>.cdb}
21266
21267 \end_inset
21268
21269  file from the .adb
21270 \begin_inset LatexCommand \index{<file>.adb}
21271
21272 \end_inset
21273
21274  files and the address information.
21275  This .cdb is used by the debugger.
21276 \layout Subsection
21277
21278 How the Debugger Works
21279 \layout Standard
21280
21281 When the -
21282 \begin_inset ERT
21283 status Collapsed
21284
21285 \layout Standard
21286
21287 \backslash
21288 /
21289 \end_inset
21290
21291 -debug option is specified the compiler generates extra symbol information
21292  some of which are put into the assembler source and some are put into the
21293  .adb file.
21294  Then the linker creates the .cdb file from the individual .adb files with
21295  the address information for the symbols.
21296  The debugger reads the symbolic information generated by the compiler &
21297  the address information generated by the linker.
21298  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
21299  execution is controlled by the debugger.
21300  When a command is issued for the debugger, it translates it into appropriate
21301  commands for the simulator.
21302  (Currently SDCDM only connects to the simulator but
21303 \emph on
21304 newcdb
21305 \emph default
21306  at
21307 \begin_inset LatexCommand \url{http://ec2drv.sf.net/}
21308
21309 \end_inset
21310
21311  is an effort to connect directly to the hardware.)
21312 \layout Subsection
21313
21314 Starting the Debugger SDCDB
21315 \layout Standard
21316
21317 The debugger can be started using the following command line.
21318  (Assume the file you are debugging has the file name foo).
21319 \newline
21320
21321 \newline
21322
21323 \family sans
21324 \series bold
21325 sdcdb foo
21326 \newline
21327
21328 \family default
21329 \series default
21330
21331 \newline
21332 The debugger will look for the following files.
21333 \layout Itemize
21334
21335 foo.c - the source file.
21336 \layout Itemize
21337
21338 foo.cdb - the debugger symbol information file.
21339 \layout Itemize
21340
21341 foo.ihx - the Intel hex format
21342 \begin_inset LatexCommand \index{Intel hex format}
21343
21344 \end_inset
21345
21346  object file.
21347 \layout Subsection
21348
21349 SDCDB Command Line Options
21350 \layout Itemize
21351
21352 -
21353 \begin_inset ERT
21354 status Collapsed
21355
21356 \layout Standard
21357
21358 \backslash
21359 /
21360 \end_inset
21361
21362 -directory=<source file directory> this option can used to specify the directory
21363  search list.
21364  The debugger will look into the directory list specified for source, cdb
21365  & ihx files.
21366  The items in the directory list must be separated by ':', e.g.
21367  if the source files can be in the directories /home/src1 and /home/src2,
21368  the -
21369 \begin_inset ERT
21370 status Collapsed
21371
21372 \layout Standard
21373
21374 \backslash
21375 /
21376 \end_inset
21377
21378 -directory option should be -
21379 \begin_inset ERT
21380 status Collapsed
21381
21382 \layout Standard
21383
21384 \backslash
21385 /
21386 \end_inset
21387
21388 -directory=/home/src1:/home/src2.
21389  Note there can be no spaces in the option.
21390
21391 \layout Itemize
21392
21393 -cd <directory> - change to the <directory>.
21394 \layout Itemize
21395
21396 -fullname - used by GUI front ends.
21397 \layout Itemize
21398
21399 -cpu <cpu-type> - this argument is passed to the simulator please see the
21400  simulator docs for details.
21401 \layout Itemize
21402
21403 -X <Clock frequency > this options is passed to the simulator please see
21404  the simulator docs for details.
21405 \layout Itemize
21406
21407 -s <serial port file> passed to simulator see the simulator docs for details.
21408 \layout Itemize
21409
21410 -S <serial in,out> passed to simulator see the simulator docs for details.
21411 \layout Itemize
21412
21413 -k <port number> passed to simulator see the simulator docs for details.
21414 \layout Subsection
21415
21416 SDCDB Debugger Commands
21417 \layout Standard
21418
21419 As mentioned earlier the command interface for the debugger has been deliberatel
21420 y kept as close the GNU debugger gdb, as possible.
21421  This will help the integration with existing graphical user interfaces
21422  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
21423  If you use a graphical user interface for the debugger you can skip this
21424  section.
21425 \layout Subsubsection*
21426
21427 break [line | file:line | function | file:function]
21428 \layout Standard
21429
21430 Set breakpoint at specified line or function:
21431 \newline
21432
21433 \newline
21434
21435 \family sans
21436 \series bold
21437 sdcdb>break 100
21438 \newline
21439 sdcdb>break foo.c:100
21440 \newline
21441 sdcdb>break funcfoo
21442 \newline
21443 sdcdb>break foo.c:funcfoo
21444 \layout Subsubsection*
21445
21446 clear [line | file:line | function | file:function ]
21447 \layout Standard
21448
21449 Clear breakpoint at specified line or function:
21450 \newline
21451
21452 \newline
21453
21454 \family sans
21455 \series bold
21456 sdcdb>clear 100
21457 \newline
21458 sdcdb>clear foo.c:100
21459 \newline
21460 sdcdb>clear funcfoo
21461 \newline
21462 sdcdb>clear foo.c:funcfoo
21463 \layout Subsubsection*
21464
21465 continue
21466 \layout Standard
21467
21468 Continue program being debugged, after breakpoint.
21469 \layout Subsubsection*
21470
21471 finish
21472 \layout Standard
21473
21474 Execute till the end of the current function.
21475 \layout Subsubsection*
21476
21477 delete [n]
21478 \layout Standard
21479
21480 Delete breakpoint number 'n'.
21481  If used without any option clear ALL user defined break points.
21482 \layout Subsubsection*
21483
21484 info [break | stack | frame | registers ]
21485 \layout Itemize
21486
21487 info break - list all breakpoints
21488 \layout Itemize
21489
21490 info stack - show the function call stack.
21491 \layout Itemize
21492
21493 info frame - show information about the current execution frame.
21494 \layout Itemize
21495
21496 info registers - show content of all registers.
21497 \layout Subsubsection*
21498
21499 step
21500 \layout Standard
21501
21502 Step program until it reaches a different source line.
21503  Note: pressing <return> repeats the last command.
21504 \layout Subsubsection*
21505
21506 next
21507 \layout Standard
21508
21509 Step program, proceeding through subroutine calls.
21510 \layout Subsubsection*
21511
21512 run
21513 \layout Standard
21514
21515 Start debugged program.
21516 \layout Subsubsection*
21517
21518 ptype variable
21519 \layout Standard
21520
21521 Print type information of the variable.
21522 \layout Subsubsection*
21523
21524 print variable
21525 \layout Standard
21526
21527 print value of variable.
21528 \layout Subsubsection*
21529
21530 file filename
21531 \layout Standard
21532
21533 load the given file name.
21534  Note this is an alternate method of loading file for debugging.
21535 \layout Subsubsection*
21536
21537 frame
21538 \layout Standard
21539
21540 print information about current frame.
21541 \layout Subsubsection*
21542
21543 set srcmode
21544 \layout Standard
21545
21546 Toggle between C source & assembly source.
21547 \layout Subsubsection*
21548
21549 ! simulator command
21550 \layout Standard
21551
21552 Send the string following '!' to the simulator, the simulator response is
21553  displayed.
21554  Note the debugger does not interpret the command being sent to the simulator,
21555  so if a command like 'go' is sent the debugger can loose its execution
21556  context and may display incorrect values.
21557 \layout Subsubsection*
21558
21559 quit
21560 \layout Standard
21561
21562 "Watch me now.
21563  Iam going Down.
21564  My name is Bobby Brown"
21565 \layout Subsection
21566
21567 Interfacing SDCDB with DDD
21568 \layout Comment
21569
21570 The screenshot was converted from png to eps with:
21571 \begin_inset Quotes sld
21572 \end_inset
21573
21574 bmeps -c -e8f -p3 ddd_example.png >ddd_example.eps
21575 \begin_inset Quotes srd
21576 \end_inset
21577
21578  which produces a pretty compact eps file which is free from compression
21579  artifacts.
21580 \layout Comment
21581
21582 The screenshot was included in sdccman.lyx cvs version 1.120 but later removed
21583  as this broke the build system on Sourceforge (pdf-file was broken).
21584 \layout Standard
21585
21586 The .eps File
21587 \size footnotesize
21588
21589 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/doc/figures/ddd_example.eps}
21590
21591 \end_inset
21592
21593
21594 \size default
21595  shows a screenshot of a debugging session with DDD
21596 \begin_inset LatexCommand \index{DDD (debugger)}
21597
21598 \end_inset
21599
21600  (Unix only) on a simulated 8032.
21601  The debugging session might not run as smoothly as the screenshot suggests.
21602  The debugger allows setting of breakpoints, displaying and changing variables,
21603  single stepping through C and assembler code.
21604
21605 \newline
21606 The source was compiled with
21607 \family sans
21608 \series bold
21609
21610 \newline
21611
21612 \newline
21613 sdcc -
21614 \family default
21615 \series default
21616
21617 \begin_inset ERT
21618 status Collapsed
21619
21620 \layout Standard
21621
21622 \backslash
21623 /
21624 \end_inset
21625
21626
21627 \family sans
21628 \series bold
21629 -debug ddd_example.c
21630 \family default
21631 \series default
21632
21633 \family sans
21634 \series bold
21635
21636 \newline
21637
21638 \family default
21639 \series default
21640
21641 \newline
21642 and DDD was invoked with
21643 \family sans
21644 \series bold
21645
21646 \newline
21647
21648 \newline
21649 ddd -debugger 'sdcdb -cpu 8032 ddd_example'
21650 \layout Subsection
21651
21652 Interfacing SDCDB with XEmacs
21653 \begin_inset LatexCommand \index{XEmacs}
21654
21655 \end_inset
21656
21657
21658 \begin_inset LatexCommand \index{Emacs}
21659
21660 \end_inset
21661
21662
21663 \layout Standard
21664
21665 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
21666  sdcdb.el and sdcdbsrc.el.
21667  These two files can be found in the $(prefix)/bin directory after the installat
21668 ion is complete.
21669  These files need to be loaded into XEmacs for the interface to work.
21670  This can be done at XEmacs startup time by inserting the following into
21671  your '.xemacs' file (which can be found in your HOME directory):
21672 \newline
21673
21674 \newline
21675
21676 \family typewriter
21677 (load-file sdcdbsrc.el)
21678 \family default
21679
21680 \newline
21681
21682 \newline
21683 .xemacs is a lisp file so the () around the command is REQUIRED.
21684  The files can also be loaded dynamically while XEmacs is running, set the
21685  environment variable 'EMACSLOADPATH' to the installation bin directory
21686  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
21687  To start the interface enter the following command:
21688 \newline
21689
21690 \newline
21691
21692 \family sans
21693 \series bold
21694 ESC-x sdcdbsrc
21695 \family default
21696 \series default
21697
21698 \newline
21699
21700 \newline
21701 You will prompted to enter the file name to be debugged.
21702
21703 \newline
21704
21705 \newline
21706 The command line options that are passed to the simulator directly are bound
21707  to default values in the file sdcdbsrc.el.
21708  The variables are listed below, these values maybe changed as required.
21709 \layout Itemize
21710
21711 sdcdbsrc-cpu-type '51
21712 \layout Itemize
21713
21714 sdcdbsrc-frequency '11059200
21715 \layout Itemize
21716
21717 sdcdbsrc-serial nil
21718 \layout Standard
21719
21720 The following is a list of key mapping for the debugger interface.
21721 \layout Standard
21722
21723 \SpecialChar ~
21724
21725 \family typewriter
21726
21727 \newline
21728 ;;\SpecialChar ~
21729 Current Listing ::
21730 \newline
21731 ;;key\SpecialChar ~
21732 \SpecialChar ~
21733 \SpecialChar ~
21734 \SpecialChar ~
21735 \SpecialChar ~
21736 \SpecialChar ~
21737 \SpecialChar ~
21738 \SpecialChar ~
21739 \SpecialChar ~
21740 \SpecialChar ~
21741 \SpecialChar ~
21742 \SpecialChar ~
21743 \SpecialChar ~
21744 \SpecialChar ~
21745 binding\SpecialChar ~
21746 \SpecialChar ~
21747 \SpecialChar ~
21748 \SpecialChar ~
21749 \SpecialChar ~
21750 \SpecialChar ~
21751 \SpecialChar ~
21752 \SpecialChar ~
21753 \SpecialChar ~
21754 \SpecialChar ~
21755 \SpecialChar ~
21756 \SpecialChar ~
21757 \SpecialChar ~
21758 \SpecialChar ~
21759 \SpecialChar ~
21760 \SpecialChar ~
21761 \SpecialChar ~
21762 \SpecialChar ~
21763 \SpecialChar ~
21764 \SpecialChar ~
21765 \SpecialChar ~
21766 \SpecialChar ~
21767 Comment
21768 \newline
21769 ;;---\SpecialChar ~
21770 \SpecialChar ~
21771 \SpecialChar ~
21772 \SpecialChar ~
21773 \SpecialChar ~
21774 \SpecialChar ~
21775 \SpecialChar ~
21776 \SpecialChar ~
21777 \SpecialChar ~
21778 \SpecialChar ~
21779 \SpecialChar ~
21780 \SpecialChar ~
21781 \SpecialChar ~
21782 \SpecialChar ~
21783 -------\SpecialChar ~
21784 \SpecialChar ~
21785 \SpecialChar ~
21786 \SpecialChar ~
21787 \SpecialChar ~
21788 \SpecialChar ~
21789 \SpecialChar ~
21790 \SpecialChar ~
21791 \SpecialChar ~
21792 \SpecialChar ~
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 -------
21806 \newline
21807 ;;
21808 \newline
21809 ;;\SpecialChar ~
21810 n\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 sdcdb-next-from-src\SpecialChar ~
21826 \SpecialChar ~
21827 \SpecialChar ~
21828 \SpecialChar ~
21829 \SpecialChar ~
21830 \SpecialChar ~
21831 \SpecialChar ~
21832 \SpecialChar ~
21833 \SpecialChar ~
21834 \SpecialChar ~
21835 SDCDB next command
21836 \newline
21837 ;;\SpecialChar ~
21838 b\SpecialChar ~
21839 \SpecialChar ~
21840 \SpecialChar ~
21841 \SpecialChar ~
21842 \SpecialChar ~
21843 \SpecialChar ~
21844 \SpecialChar ~
21845 \SpecialChar ~
21846 \SpecialChar ~
21847 \SpecialChar ~
21848 \SpecialChar ~
21849 \SpecialChar ~
21850 \SpecialChar ~
21851 \SpecialChar ~
21852 \SpecialChar ~
21853 sdcdb-back-from-src\SpecialChar ~
21854 \SpecialChar ~
21855 \SpecialChar ~
21856 \SpecialChar ~
21857 \SpecialChar ~
21858 \SpecialChar ~
21859 \SpecialChar ~
21860 \SpecialChar ~
21861 \SpecialChar ~
21862 \SpecialChar ~
21863 SDCDB back command
21864 \newline
21865 ;;\SpecialChar ~
21866 c\SpecialChar ~
21867 \SpecialChar ~
21868 \SpecialChar ~
21869 \SpecialChar ~
21870 \SpecialChar ~
21871 \SpecialChar ~
21872 \SpecialChar ~
21873 \SpecialChar ~
21874 \SpecialChar ~
21875 \SpecialChar ~
21876 \SpecialChar ~
21877 \SpecialChar ~
21878 \SpecialChar ~
21879 \SpecialChar ~
21880 \SpecialChar ~
21881 sdcdb-cont-from-src\SpecialChar ~
21882 \SpecialChar ~
21883 \SpecialChar ~
21884 \SpecialChar ~
21885 \SpecialChar ~
21886 \SpecialChar ~
21887 \SpecialChar ~
21888 \SpecialChar ~
21889 \SpecialChar ~
21890 \SpecialChar ~
21891 SDCDB continue command
21892 \newline
21893 ;;\SpecialChar ~
21894 s\SpecialChar ~
21895 \SpecialChar ~
21896 \SpecialChar ~
21897 \SpecialChar ~
21898 \SpecialChar ~
21899 \SpecialChar ~
21900 \SpecialChar ~
21901 \SpecialChar ~
21902 \SpecialChar ~
21903 \SpecialChar ~
21904 \SpecialChar ~
21905 \SpecialChar ~
21906 \SpecialChar ~
21907 \SpecialChar ~
21908 \SpecialChar ~
21909 sdcdb-step-from-src\SpecialChar ~
21910 \SpecialChar ~
21911 \SpecialChar ~
21912 \SpecialChar ~
21913 \SpecialChar ~
21914 \SpecialChar ~
21915 \SpecialChar ~
21916 \SpecialChar ~
21917 \SpecialChar ~
21918 \SpecialChar ~
21919 SDCDB step command
21920 \newline
21921 ;;\SpecialChar ~
21922 ?\SpecialChar ~
21923 \SpecialChar ~
21924 \SpecialChar ~
21925 \SpecialChar ~
21926 \SpecialChar ~
21927 \SpecialChar ~
21928 \SpecialChar ~
21929 \SpecialChar ~
21930 \SpecialChar ~
21931 \SpecialChar ~
21932 \SpecialChar ~
21933 \SpecialChar ~
21934 \SpecialChar ~
21935 \SpecialChar ~
21936 \SpecialChar ~
21937 sdcdb-whatis-c-sexp\SpecialChar ~
21938 \SpecialChar ~
21939 \SpecialChar ~
21940 \SpecialChar ~
21941 \SpecialChar ~
21942 \SpecialChar ~
21943 \SpecialChar ~
21944 \SpecialChar ~
21945 \SpecialChar ~
21946 \SpecialChar ~
21947 SDCDB ptypecommand for data at
21948 \newline
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 \SpecialChar ~
21962 \SpecialChar ~
21963 \SpecialChar ~
21964 \SpecialChar ~
21965 \SpecialChar ~
21966 \SpecialChar ~
21967 \SpecialChar ~
21968 \SpecialChar ~
21969 \SpecialChar ~
21970 \SpecialChar ~
21971 \SpecialChar ~
21972 \SpecialChar ~
21973 \SpecialChar ~
21974 \SpecialChar ~
21975 \SpecialChar ~
21976 \SpecialChar ~
21977 \SpecialChar ~
21978 \SpecialChar ~
21979 \SpecialChar ~
21980 \SpecialChar ~
21981 \SpecialChar ~
21982 \SpecialChar ~
21983 \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 buffer point
21997 \newline
21998 ;;\SpecialChar ~
21999 x\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 sdcdbsrc-delete\SpecialChar ~
22015 \SpecialChar ~
22016 \SpecialChar ~
22017 \SpecialChar ~
22018 \SpecialChar ~
22019 \SpecialChar ~
22020 \SpecialChar ~
22021 \SpecialChar ~
22022 \SpecialChar ~
22023 \SpecialChar ~
22024 \SpecialChar ~
22025 \SpecialChar ~
22026 \SpecialChar ~
22027 \SpecialChar ~
22028 SDCDB Delete all breakpoints if no arg
22029 \newline
22030 ;;\SpecialChar ~
22031 \SpecialChar ~
22032 \SpecialChar ~
22033 \SpecialChar ~
22034 \SpecialChar ~
22035 \SpecialChar ~
22036 \SpecialChar ~
22037 \SpecialChar ~
22038 \SpecialChar ~
22039 \SpecialChar ~
22040 \SpecialChar ~
22041 \SpecialChar ~
22042 \SpecialChar ~
22043 \SpecialChar ~
22044 \SpecialChar ~
22045 \SpecialChar ~
22046 \SpecialChar ~
22047 \SpecialChar ~
22048 \SpecialChar ~
22049 \SpecialChar ~
22050 \SpecialChar ~
22051 \SpecialChar ~
22052 \SpecialChar ~
22053 \SpecialChar ~
22054 \SpecialChar ~
22055 \SpecialChar ~
22056 \SpecialChar ~
22057 \SpecialChar ~
22058 \SpecialChar ~
22059 \SpecialChar ~
22060 \SpecialChar ~
22061 \SpecialChar ~
22062 \SpecialChar ~
22063 \SpecialChar ~
22064 \SpecialChar ~
22065 \SpecialChar ~
22066 \SpecialChar ~
22067 \SpecialChar ~
22068 \SpecialChar ~
22069 \SpecialChar ~
22070 \SpecialChar ~
22071 \SpecialChar ~
22072 \SpecialChar ~
22073 \SpecialChar ~
22074 \SpecialChar ~
22075 \SpecialChar ~
22076 \SpecialChar ~
22077 given or delete arg (C-u arg x)
22078 \newline
22079 ;;\SpecialChar ~
22080 m\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 sdcdbsrc-frame\SpecialChar ~
22096 \SpecialChar ~
22097 \SpecialChar ~
22098 \SpecialChar ~
22099 \SpecialChar ~
22100 \SpecialChar ~
22101 \SpecialChar ~
22102 \SpecialChar ~
22103 \SpecialChar ~
22104 \SpecialChar ~
22105 \SpecialChar ~
22106 \SpecialChar ~
22107 \SpecialChar ~
22108 \SpecialChar ~
22109 \SpecialChar ~
22110 SDCDB Display current frame if no arg,
22111 \newline
22112 ;;\SpecialChar ~
22113 \SpecialChar ~
22114 \SpecialChar ~
22115 \SpecialChar ~
22116 \SpecialChar ~
22117 \SpecialChar ~
22118 \SpecialChar ~
22119 \SpecialChar ~
22120 \SpecialChar ~
22121 \SpecialChar ~
22122 \SpecialChar ~
22123 \SpecialChar ~
22124 \SpecialChar ~
22125 \SpecialChar ~
22126 \SpecialChar ~
22127 \SpecialChar ~
22128 \SpecialChar ~
22129 \SpecialChar ~
22130 \SpecialChar ~
22131 \SpecialChar ~
22132 \SpecialChar ~
22133 \SpecialChar ~
22134 \SpecialChar ~
22135 \SpecialChar ~
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 given or display frame arg
22160 \newline
22161 ;;\SpecialChar ~
22162 \SpecialChar ~
22163 \SpecialChar ~
22164 \SpecialChar ~
22165 \SpecialChar ~
22166 \SpecialChar ~
22167 \SpecialChar ~
22168 \SpecialChar ~
22169 \SpecialChar ~
22170 \SpecialChar ~
22171 \SpecialChar ~
22172 \SpecialChar ~
22173 \SpecialChar ~
22174 \SpecialChar ~
22175 \SpecialChar ~
22176 \SpecialChar ~
22177 \SpecialChar ~
22178 \SpecialChar ~
22179 \SpecialChar ~
22180 \SpecialChar ~
22181 \SpecialChar ~
22182 \SpecialChar ~
22183 \SpecialChar ~
22184 \SpecialChar ~
22185 \SpecialChar ~
22186 \SpecialChar ~
22187 \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 buffer point
22209 \newline
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 sdcdbsrc-goto-sdcdb\SpecialChar ~
22227 \SpecialChar ~
22228 \SpecialChar ~
22229 \SpecialChar ~
22230 \SpecialChar ~
22231 \SpecialChar ~
22232 \SpecialChar ~
22233 \SpecialChar ~
22234 \SpecialChar ~
22235 \SpecialChar ~
22236 Goto the SDCDB output buffer
22237 \newline
22238 ;;\SpecialChar ~
22239 p\SpecialChar ~
22240 \SpecialChar ~
22241 \SpecialChar ~
22242 \SpecialChar ~
22243 \SpecialChar ~
22244 \SpecialChar ~
22245 \SpecialChar ~
22246 \SpecialChar ~
22247 \SpecialChar ~
22248 \SpecialChar ~
22249 \SpecialChar ~
22250 \SpecialChar ~
22251 \SpecialChar ~
22252 \SpecialChar ~
22253 \SpecialChar ~
22254 sdcdb-print-c-sexp\SpecialChar ~
22255 \SpecialChar ~
22256 \SpecialChar ~
22257 \SpecialChar ~
22258 \SpecialChar ~
22259 \SpecialChar ~
22260 \SpecialChar ~
22261 \SpecialChar ~
22262 \SpecialChar ~
22263 \SpecialChar ~
22264 \SpecialChar ~
22265 SDCDB print command for data at
22266 \newline
22267 ;;\SpecialChar ~
22268 \SpecialChar ~
22269 \SpecialChar ~
22270 \SpecialChar ~
22271 \SpecialChar ~
22272 \SpecialChar ~
22273 \SpecialChar ~
22274 \SpecialChar ~
22275 \SpecialChar ~
22276 \SpecialChar ~
22277 \SpecialChar ~
22278 \SpecialChar ~
22279 \SpecialChar ~
22280 \SpecialChar ~
22281 \SpecialChar ~
22282 \SpecialChar ~
22283 \SpecialChar ~
22284 \SpecialChar ~
22285 \SpecialChar ~
22286 \SpecialChar ~
22287 \SpecialChar ~
22288 \SpecialChar ~
22289 \SpecialChar ~
22290 \SpecialChar ~
22291 \SpecialChar ~
22292 \SpecialChar ~
22293 \SpecialChar ~
22294 \SpecialChar ~
22295 \SpecialChar ~
22296 \SpecialChar ~
22297 \SpecialChar ~
22298 \SpecialChar ~
22299 \SpecialChar ~
22300 \SpecialChar ~
22301 \SpecialChar ~
22302 \SpecialChar ~
22303 \SpecialChar ~
22304 \SpecialChar ~
22305 \SpecialChar ~
22306 \SpecialChar ~
22307 \SpecialChar ~
22308 \SpecialChar ~
22309 \SpecialChar ~
22310 \SpecialChar ~
22311 \SpecialChar ~
22312 \SpecialChar ~
22313 \SpecialChar ~
22314 buffer point
22315 \newline
22316 ;;\SpecialChar ~
22317 g\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 sdcdbsrc-goto-sdcdb\SpecialChar ~
22333 \SpecialChar ~
22334 \SpecialChar ~
22335 \SpecialChar ~
22336 \SpecialChar ~
22337 \SpecialChar ~
22338 \SpecialChar ~
22339 \SpecialChar ~
22340 \SpecialChar ~
22341 \SpecialChar ~
22342 Goto the SDCDB output buffer
22343 \newline
22344 ;;\SpecialChar ~
22345 t\SpecialChar ~
22346 \SpecialChar ~
22347 \SpecialChar ~
22348 \SpecialChar ~
22349 \SpecialChar ~
22350 \SpecialChar ~
22351 \SpecialChar ~
22352 \SpecialChar ~
22353 \SpecialChar ~
22354 \SpecialChar ~
22355 \SpecialChar ~
22356 \SpecialChar ~
22357 \SpecialChar ~
22358 \SpecialChar ~
22359 \SpecialChar ~
22360 sdcdbsrc-mode\SpecialChar ~
22361 \SpecialChar ~
22362 \SpecialChar ~
22363 \SpecialChar ~
22364 \SpecialChar ~
22365 \SpecialChar ~
22366 \SpecialChar ~
22367 \SpecialChar ~
22368 \SpecialChar ~
22369 \SpecialChar ~
22370 \SpecialChar ~
22371 \SpecialChar ~
22372 \SpecialChar ~
22373 \SpecialChar ~
22374 \SpecialChar ~
22375 \SpecialChar ~
22376 Toggles Sdcdbsrc mode (turns it off)
22377 \newline
22378 ;;
22379 \newline
22380 ;;\SpecialChar ~
22381 C-c\SpecialChar ~
22382 C-f\SpecialChar ~
22383 \SpecialChar ~
22384 \SpecialChar ~
22385 \SpecialChar ~
22386 \SpecialChar ~
22387 \SpecialChar ~
22388 \SpecialChar ~
22389 \SpecialChar ~
22390 \SpecialChar ~
22391 sdcdb-finish-from-src\SpecialChar ~
22392 \SpecialChar ~
22393 \SpecialChar ~
22394 \SpecialChar ~
22395 \SpecialChar ~
22396 \SpecialChar ~
22397 \SpecialChar ~
22398 \SpecialChar ~
22399 SDCDB finish command
22400 \newline
22401 ;;
22402 \newline
22403 ;;\SpecialChar ~
22404 C-x\SpecialChar ~
22405 SPC\SpecialChar ~
22406 \SpecialChar ~
22407 \SpecialChar ~
22408 \SpecialChar ~
22409 \SpecialChar ~
22410 \SpecialChar ~
22411 \SpecialChar ~
22412 \SpecialChar ~
22413 \SpecialChar ~
22414 sdcdb-break\SpecialChar ~
22415 \SpecialChar ~
22416 \SpecialChar ~
22417 \SpecialChar ~
22418 \SpecialChar ~
22419 \SpecialChar ~
22420 \SpecialChar ~
22421 \SpecialChar ~
22422 \SpecialChar ~
22423 \SpecialChar ~
22424 \SpecialChar ~
22425 \SpecialChar ~
22426 \SpecialChar ~
22427 \SpecialChar ~
22428 \SpecialChar ~
22429 \SpecialChar ~
22430 \SpecialChar ~
22431 \SpecialChar ~
22432 Set break for line with point
22433 \newline
22434 ;;\SpecialChar ~
22435 ESC\SpecialChar ~
22436 t\SpecialChar ~
22437 \SpecialChar ~
22438 \SpecialChar ~
22439 \SpecialChar ~
22440 \SpecialChar ~
22441 \SpecialChar ~
22442 \SpecialChar ~
22443 \SpecialChar ~
22444 \SpecialChar ~
22445 \SpecialChar ~
22446 \SpecialChar ~
22447 sdcdbsrc-mode\SpecialChar ~
22448 \SpecialChar ~
22449 \SpecialChar ~
22450 \SpecialChar ~
22451 \SpecialChar ~
22452 \SpecialChar ~
22453 \SpecialChar ~
22454 \SpecialChar ~
22455 \SpecialChar ~
22456 \SpecialChar ~
22457 \SpecialChar ~
22458 \SpecialChar ~
22459 \SpecialChar ~
22460 \SpecialChar ~
22461 \SpecialChar ~
22462 \SpecialChar ~
22463 Toggle Sdcdbsrc mode
22464 \newline
22465 ;;\SpecialChar ~
22466 ESC\SpecialChar ~
22467 m\SpecialChar ~
22468 \SpecialChar ~
22469 \SpecialChar ~
22470 \SpecialChar ~
22471 \SpecialChar ~
22472 \SpecialChar ~
22473 \SpecialChar ~
22474 \SpecialChar ~
22475 \SpecialChar ~
22476 \SpecialChar ~
22477 \SpecialChar ~
22478 sdcdbsrc-srcmode\SpecialChar ~
22479 \SpecialChar ~
22480 \SpecialChar ~
22481 \SpecialChar ~
22482 \SpecialChar ~
22483 \SpecialChar ~
22484 \SpecialChar ~
22485 \SpecialChar ~
22486 \SpecialChar ~
22487 \SpecialChar ~
22488 \SpecialChar ~
22489 \SpecialChar ~
22490 \SpecialChar ~
22491 Toggle list mode
22492 \newline
22493 ;;
22494 \newline
22495
22496 \layout Chapter
22497 \pagebreak_top
22498 TIPS
22499 \layout Standard
22500
22501 Here are a few guidelines that will help the compiler generate more efficient
22502  code, some of the tips are specific to this compiler others are generally
22503  good programming practice.
22504 \layout Itemize
22505
22506 Use the smallest data type to represent your data-value.
22507  If it is known in advance that the value is going to be less than 256 then
22508  use an 'unsigned char' instead of a 'short' or 'int'.
22509  Please note, that ANSI C requires both signed and unsigned chars to be
22510  promoted to 'signed int'
22511 \begin_inset LatexCommand \index{promotion to signed int}
22512
22513 \end_inset
22514
22515  before doing any operation.
22516  This promotion
22517 \begin_inset LatexCommand \index{type promotion}
22518
22519 \end_inset
22520
22521
22522 \begin_inset LatexCommand \label{type promotion}
22523
22524 \end_inset
22525
22526  can be omitted, if the result is the same.
22527  The effect of the promotion rules together with the sign-extension is often
22528  surprising:
22529 \begin_deeper
22530 \layout Verse
22531
22532
22533 \family typewriter
22534 unsigned char uc = 0xfe;
22535 \newline
22536 if (uc * uc < 0) /* this is true! */
22537 \newline
22538 {
22539 \newline
22540 \SpecialChar ~
22541 \SpecialChar ~
22542 \SpecialChar ~
22543 \SpecialChar ~
22544 ....
22545 \newline
22546 }
22547 \layout Standard
22548
22549
22550 \family typewriter
22551 uc * uc
22552 \family default
22553  is evaluated as
22554 \family typewriter
22555 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
22556 \family default
22557 .
22558
22559 \newline
22560 Another one:
22561 \layout Verse
22562
22563
22564 \family typewriter
22565 (unsigned char) -12 / (signed char) -3 = ...
22566 \layout Standard
22567
22568 No, the result is not 4:
22569 \layout Verse
22570
22571
22572 \family typewriter
22573 (int) (unsigned char) -12 / (int) (signed char) -3 =
22574 \newline
22575 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
22576 \newline
22577 (int) 0x00f4 / (int) 0xfffd =
22578 \newline
22579 (int) 0x00f4 / (int) 0xfffd =
22580 \newline
22581 (int) 244 / (int) -3 =
22582 \newline
22583 (int) -81 = (int) 0xffaf;
22584 \layout Standard
22585
22586 Don't complain, that gcc gives you a different result.
22587  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
22588  Therefore the results are different.
22589 \newline
22590 From
22591 \begin_inset Quotes sld
22592 \end_inset
22593
22594 comp.lang.c FAQ
22595 \begin_inset Quotes srd
22596 \end_inset
22597
22598 :
22599 \layout Quote
22600
22601 If well-defined overflow characteristics are important and negative values
22602  are not, or if you want to steer clear of sign-extension problems when
22603  manipulating bits or bytes, use one of the corresponding unsigned types.
22604  (Beware when mixing signed and unsigned values in expressions, though.)
22605 \newline
22606 Although character types (especially unsigned char) can be used as "tiny"
22607  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
22608 ble sign extension and increased code size.
22609 \end_deeper
22610 \layout Itemize
22611
22612 Use unsigned when it is known in advance that the value is not going to
22613  be negative.
22614  This helps especially if you are doing division or multiplication, bit-shifting
22615  or are using an array index.
22616 \layout Itemize
22617
22618 NEVER jump into a LOOP.
22619 \layout Itemize
22620
22621 Declare the variables to be local
22622 \begin_inset LatexCommand \index{local variables}
22623
22624 \end_inset
22625
22626  whenever possible, especially loop control variables (induction).
22627 \layout Itemize
22628
22629 Since the compiler does not always do implicit integral promotion, the programme
22630 r should do an explicit cast when integral promotion is required.
22631 \layout Itemize
22632
22633 Reducing the size of division, multiplication & modulus operations can reduce
22634  code size substantially.
22635  Take the following code for example.
22636 \begin_deeper
22637 \layout Verse
22638
22639
22640 \family typewriter
22641 foobar(unsigned int p1, unsigned char ch)
22642 \newline
22643 {
22644 \newline
22645 \SpecialChar ~
22646 \SpecialChar ~
22647 \SpecialChar ~
22648 \SpecialChar ~
22649 unsigned char ch1 = p1 % ch ;
22650 \newline
22651 \SpecialChar ~
22652 \SpecialChar ~
22653 \SpecialChar ~
22654 \SpecialChar ~
22655 ....
22656 \newline
22657 }
22658 \layout Standard
22659
22660 For the modulus operation the variable ch will be promoted to unsigned int
22661  first then the modulus operation will be performed (this will lead to a
22662  call to support routine _moduint()), and the result will be casted to a
22663  char.
22664  If the code is changed to
22665 \layout Verse
22666
22667
22668 \family typewriter
22669 foobar(unsigned int p1, unsigned char ch)
22670 \newline
22671 {
22672 \newline
22673 \SpecialChar ~
22674 \SpecialChar ~
22675 \SpecialChar ~
22676 \SpecialChar ~
22677 unsigned char ch1 = (unsigned char)p1 % ch ;
22678 \newline
22679 \SpecialChar ~
22680 \SpecialChar ~
22681 \SpecialChar ~
22682 \SpecialChar ~
22683 ....
22684 \newline
22685 }
22686 \layout Standard
22687
22688 It would substantially reduce the code generated (future versions of the
22689  compiler will be smart enough to detect such optimization opportunities).
22690 \end_deeper
22691 \layout Itemize
22692
22693 Have a look at the assembly listing to get a
22694 \begin_inset Quotes sld
22695 \end_inset
22696
22697 feeling
22698 \begin_inset Quotes srd
22699 \end_inset
22700
22701  for the code generation.
22702 \layout Section
22703
22704 Porting code from or to other compilers
22705 \layout Itemize
22706
22707 check whether endianness of the compilers differs and adapt where needed.
22708 \layout Itemize
22709
22710 check the device specific header files for compiler specific syntax.
22711  Eventually include the file <compiler.h
22712 \begin_inset LatexCommand \index{compiler.h (include file)}
22713
22714 \end_inset
22715
22716 > to allow using common header files.
22717 \layout Itemize
22718
22719 check whether the startup code contains the correct initialization (watchdog,
22720  peripherals).
22721 \layout Itemize
22722
22723 check whether the sizes of short, int, long match.
22724 \layout Itemize
22725
22726 check if some 16 or 32 bit hardware registers require a specific addressing
22727  order (least significant or most significant byte first) and adapt if needed
22728  (
22729 \emph on
22730 first
22731 \emph default
22732  and
22733 \emph on
22734 last
22735 \emph default
22736  relate to time and not to lower/upper memory location here, so this is
22737
22738 \emph on
22739 not
22740 \emph default
22741  the same as endianness).
22742 \layout Itemize
22743
22744 check whether the keyword
22745 \emph on
22746 volatile
22747 \emph default
22748  is used where needed.
22749  The compilers might differ in their optimization characteristics (as different
22750  versions of the same compiler might also use more clever optimizations
22751  this is good idea anyway).
22752 \layout Itemize
22753
22754 check that the compilers are not told to supress warnings.
22755 \layout Itemize
22756
22757 check and convert compiler specific extensions (interrupts, memory areas,
22758  pragmas etc.).
22759 \layout Itemize
22760
22761 check for differences in type promotion (especially check for math operations
22762  on char variables and for the use of the ~\SpecialChar ~
22763 operator on bit variables.
22764  See
22765 \begin_inset LatexCommand \ref{type promotion}
22766
22767 \end_inset
22768
22769  and
22770 \begin_inset LatexCommand \ref{sec:Compatibility-with-previous}
22771
22772 \end_inset
22773
22774 ).
22775 \layout Itemize
22776
22777 check the assembly code generated for interrupt routines (f.e.
22778  for calls to possibly non-reentrant library functions).
22779 \layout Itemize
22780
22781 check whether timing loops result in proper timing (or preferably consider
22782  a rewrite of the code with timer based delays instead).
22783 \layout Itemize
22784
22785 check for differences in printf parameters (some compilers push (va_arg
22786 \begin_inset LatexCommand \index{va\_arg}
22787
22788 \end_inset
22789
22790 ) char variables as integers others as char).
22791 \layout Itemize
22792
22793 check the resulting memory layout.
22794 \layout Section
22795
22796 Tools
22797 \begin_inset LatexCommand \index{Tools}
22798
22799 \end_inset
22800
22801  included in the distribution
22802 \layout Standard
22803 \align center
22804
22805 \begin_inset  Tabular
22806 <lyxtabular version="3" rows="12" columns="3">
22807 <features>
22808 <column alignment="left" valignment="top" leftline="true" width="0pt">
22809 <column alignment="left" valignment="top" leftline="true" width="0pt">
22810 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
22811 <row topline="true" bottomline="true">
22812 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22813 \begin_inset Text
22814
22815 \layout Standard
22816
22817 Name
22818 \end_inset
22819 </cell>
22820 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22821 \begin_inset Text
22822
22823 \layout Standard
22824
22825 Purpose
22826 \end_inset
22827 </cell>
22828 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22829 \begin_inset Text
22830
22831 \layout Standard
22832
22833 Directory
22834 \end_inset
22835 </cell>
22836 </row>
22837 <row topline="true">
22838 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22839 \begin_inset Text
22840
22841 \layout Standard
22842
22843 ucSsim
22844 \end_inset
22845 </cell>
22846 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22847 \begin_inset Text
22848
22849 \layout Standard
22850
22851 Simulator for various architectures
22852 \end_inset
22853 </cell>
22854 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22855 \begin_inset Text
22856
22857 \layout Standard
22858
22859 sdcc/sim/ucsim
22860 \end_inset
22861 </cell>
22862 </row>
22863 <row topline="true">
22864 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22865 \begin_inset Text
22866
22867 \layout Standard
22868
22869 keil2sdcc.pl
22870 \end_inset
22871 </cell>
22872 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22873 \begin_inset Text
22874
22875 \layout Standard
22876
22877 header file conversion
22878 \end_inset
22879 </cell>
22880 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22881 \begin_inset Text
22882
22883 \layout Standard
22884
22885 sdcc/support/scripts
22886 \end_inset
22887 </cell>
22888 </row>
22889 <row topline="true">
22890 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22891 \begin_inset Text
22892
22893 \layout Standard
22894
22895 mh2h.c
22896 \end_inset
22897 </cell>
22898 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22899 \begin_inset Text
22900
22901 \layout Standard
22902
22903 header file conversion
22904 \end_inset
22905 </cell>
22906 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22907 \begin_inset Text
22908
22909 \layout Standard
22910
22911 sdcc/support/scripts
22912 \end_inset
22913 </cell>
22914 </row>
22915 <row topline="true">
22916 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22917 \begin_inset Text
22918
22919 \layout Standard
22920
22921 as-gbz80
22922 \end_inset
22923 </cell>
22924 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22925 \begin_inset Text
22926
22927 \layout Standard
22928
22929 Assembler
22930 \end_inset
22931 </cell>
22932 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22933 \begin_inset Text
22934
22935 \layout Standard
22936
22937
22938 \family roman
22939 \series medium
22940 \shape up
22941 \size normal
22942 \emph off
22943 \bar no
22944 \noun off
22945 \color none
22946 sdcc/bin
22947 \end_inset
22948 </cell>
22949 </row>
22950 <row topline="true">
22951 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22952 \begin_inset Text
22953
22954 \layout Standard
22955
22956 as-z80
22957 \end_inset
22958 </cell>
22959 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22960 \begin_inset Text
22961
22962 \layout Standard
22963
22964 Assembler
22965 \end_inset
22966 </cell>
22967 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
22968 \begin_inset Text
22969
22970 \layout Standard
22971
22972
22973 \family roman
22974 \series medium
22975 \shape up
22976 \size normal
22977 \emph off
22978 \bar no
22979 \noun off
22980 \color none
22981 sdcc/bin
22982 \end_inset
22983 </cell>
22984 </row>
22985 <row topline="true">
22986 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22987 \begin_inset Text
22988
22989 \layout Standard
22990
22991 asx8051
22992 \end_inset
22993 </cell>
22994 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
22995 \begin_inset Text
22996
22997 \layout Standard
22998
22999 Assembler
23000 \end_inset
23001 </cell>
23002 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23003 \begin_inset Text
23004
23005 \layout Standard
23006
23007
23008 \family roman
23009 \series medium
23010 \shape up
23011 \size normal
23012 \emph off
23013 \bar no
23014 \noun off
23015 \color none
23016 sdcc/bin
23017 \end_inset
23018 </cell>
23019 </row>
23020 <row topline="true">
23021 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23022 \begin_inset Text
23023
23024 \layout Standard
23025
23026 SDCDB
23027 \end_inset
23028 </cell>
23029 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23030 \begin_inset Text
23031
23032 \layout Standard
23033
23034 Simulator
23035 \end_inset
23036 </cell>
23037 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23038 \begin_inset Text
23039
23040 \layout Standard
23041
23042
23043 \family roman
23044 \series medium
23045 \shape up
23046 \size normal
23047 \emph off
23048 \bar no
23049 \noun off
23050 \color none
23051 sdcc/bin
23052 \end_inset
23053 </cell>
23054 </row>
23055 <row topline="true">
23056 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23057 \begin_inset Text
23058
23059 \layout Standard
23060
23061 aslink
23062 \end_inset
23063 </cell>
23064 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23065 \begin_inset Text
23066
23067 \layout Standard
23068
23069 Linker
23070 \end_inset
23071 </cell>
23072 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23073 \begin_inset Text
23074
23075 \layout Standard
23076
23077
23078 \family roman
23079 \series medium
23080 \shape up
23081 \size normal
23082 \emph off
23083 \bar no
23084 \noun off
23085 \color none
23086 sdcc/bin
23087 \end_inset
23088 </cell>
23089 </row>
23090 <row topline="true">
23091 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23092 \begin_inset Text
23093
23094 \layout Standard
23095
23096 link-z80
23097 \end_inset
23098 </cell>
23099 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23100 \begin_inset Text
23101
23102 \layout Standard
23103
23104 Linker
23105 \end_inset
23106 </cell>
23107 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23108 \begin_inset Text
23109
23110 \layout Standard
23111
23112
23113 \family roman
23114 \series medium
23115 \shape up
23116 \size normal
23117 \emph off
23118 \bar no
23119 \noun off
23120 \color none
23121 sdcc/bin
23122 \end_inset
23123 </cell>
23124 </row>
23125 <row topline="true">
23126 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23127 \begin_inset Text
23128
23129 \layout Standard
23130
23131 link-gbz80
23132 \end_inset
23133 </cell>
23134 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23135 \begin_inset Text
23136
23137 \layout Standard
23138
23139 Linker
23140 \end_inset
23141 </cell>
23142 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23143 \begin_inset Text
23144
23145 \layout Standard
23146
23147
23148 \family roman
23149 \series medium
23150 \shape up
23151 \size normal
23152 \emph off
23153 \bar no
23154 \noun off
23155 \color none
23156 sdcc/bin
23157 \end_inset
23158 </cell>
23159 </row>
23160 <row topline="true" bottomline="true">
23161 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23162 \begin_inset Text
23163
23164 \layout Standard
23165
23166 packihx
23167 \end_inset
23168 </cell>
23169 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23170 \begin_inset Text
23171
23172 \layout Standard
23173
23174 ihx packer
23175 \end_inset
23176 </cell>
23177 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23178 \begin_inset Text
23179
23180 \layout Standard
23181
23182
23183 \family roman
23184 \series medium
23185 \shape up
23186 \size normal
23187 \emph off
23188 \bar no
23189 \noun off
23190 \color none
23191 sdcc/bin
23192 \end_inset
23193 </cell>
23194 </row>
23195 </lyxtabular>
23196
23197 \end_inset
23198
23199
23200 \newline
23201
23202 \layout Section
23203
23204 Documentation
23205 \begin_inset LatexCommand \index{Documentation}
23206
23207 \end_inset
23208
23209  included in the distribution
23210 \layout Standard
23211 \align center
23212
23213 \begin_inset  Tabular
23214 <lyxtabular version="3" rows="10" columns="2">
23215 <features>
23216 <column alignment="left" valignment="top" leftline="true" width="0">
23217 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
23218 <row topline="true" bottomline="true">
23219 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23220 \begin_inset Text
23221
23222 \layout Standard
23223
23224 Subject / Title
23225 \end_inset
23226 </cell>
23227 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23228 \begin_inset Text
23229
23230 \layout Standard
23231
23232 Where to get / filename
23233 \end_inset
23234 </cell>
23235 </row>
23236 <row topline="true">
23237 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23238 \begin_inset Text
23239
23240 \layout Standard
23241
23242 SDCC Compiler User Guide
23243 \end_inset
23244 </cell>
23245 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23246 \begin_inset Text
23247
23248 \layout Standard
23249
23250 You're reading it right now
23251 \end_inset
23252 </cell>
23253 </row>
23254 <row topline="true">
23255 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23256 \begin_inset Text
23257
23258 \layout Standard
23259
23260 Changelog of SDCC
23261 \end_inset
23262 </cell>
23263 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23264 \begin_inset Text
23265
23266 \layout Standard
23267
23268 sdcc/Changelog
23269 \end_inset
23270 </cell>
23271 </row>
23272 <row topline="true">
23273 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23274 \begin_inset Text
23275
23276 \layout Standard
23277
23278 ASXXXX
23279 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
23280
23281 \end_inset
23282
23283
23284 \begin_inset LatexCommand \index{Assembler documentation}
23285
23286 \end_inset
23287
23288  Assemblers and ASLINK
23289 \begin_inset LatexCommand \index{aslink}
23290
23291 \end_inset
23292
23293
23294 \begin_inset LatexCommand \index{Linker documentation}
23295
23296 \end_inset
23297
23298  Relocating Linker
23299 \end_inset
23300 </cell>
23301 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23302 \begin_inset Text
23303
23304 \layout Standard
23305
23306 sdcc/as/doc/asxhtm.html
23307 \end_inset
23308 </cell>
23309 </row>
23310 <row topline="true">
23311 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23312 \begin_inset Text
23313
23314 \layout Standard
23315
23316 SDCC regression test
23317 \begin_inset LatexCommand \index{Regression test}
23318
23319 \end_inset
23320
23321
23322 \end_inset
23323 </cell>
23324 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23325 \begin_inset Text
23326
23327 \layout Standard
23328
23329 sdcc/doc/test_suite_spec.pdf
23330 \end_inset
23331 </cell>
23332 </row>
23333 <row topline="true">
23334 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23335 \begin_inset Text
23336
23337 \layout Standard
23338
23339 Various notes
23340 \end_inset
23341 </cell>
23342 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23343 \begin_inset Text
23344
23345 \layout Standard
23346
23347 sdcc/doc/*
23348 \end_inset
23349 </cell>
23350 </row>
23351 <row topline="true">
23352 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23353 \begin_inset Text
23354
23355 \layout Standard
23356
23357 Notes on debugging with SDCDB
23358 \begin_inset LatexCommand \index{SDCDB (debugger)}
23359
23360 \end_inset
23361
23362
23363 \end_inset
23364 </cell>
23365 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23366 \begin_inset Text
23367
23368 \layout Standard
23369
23370 sdcc/debugger/README
23371 \end_inset
23372 </cell>
23373 </row>
23374 <row topline="true">
23375 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23376 \begin_inset Text
23377
23378 \layout Standard
23379
23380 Software simulator for microcontrollers
23381 \end_inset
23382 </cell>
23383 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23384 \begin_inset Text
23385
23386 \layout Standard
23387
23388
23389 \family roman
23390 \series medium
23391 \shape up
23392 \size normal
23393 \emph off
23394 \bar no
23395 \noun off
23396 \color none
23397 sdcc/sim/ucsim/doc
23398 \family default
23399 \series default
23400 \shape default
23401 \size default
23402 \emph default
23403 \bar default
23404 \noun default
23405 \color default
23406 /index.html
23407 \end_inset
23408 </cell>
23409 </row>
23410 <row topline="true">
23411 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23412 \begin_inset Text
23413
23414 \layout Standard
23415
23416 Temporary notes on the pic16
23417 \begin_inset LatexCommand \index{PIC16}
23418
23419 \end_inset
23420
23421  port
23422 \end_inset
23423 </cell>
23424 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23425 \begin_inset Text
23426
23427 \layout Standard
23428
23429 sdcc/src/pic16/NOTES
23430 \end_inset
23431 </cell>
23432 </row>
23433 <row topline="true" bottomline="true">
23434 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23435 \begin_inset Text
23436
23437 \layout Standard
23438
23439 SDCC internal documentation (debugging file format)
23440 \end_inset
23441 </cell>
23442 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23443 \begin_inset Text
23444
23445 \layout Standard
23446
23447 sdcc/doc/
23448 \family roman
23449 \series medium
23450 \shape up
23451 \size normal
23452 \emph off
23453 \bar no
23454 \noun off
23455 \color none
23456 cdbfileformat.pd
23457 \family default
23458 \series default
23459 \shape default
23460 \size default
23461 \emph default
23462 \bar default
23463 \noun default
23464 \color default
23465 f
23466 \end_inset
23467 </cell>
23468 </row>
23469 </lyxtabular>
23470
23471 \end_inset
23472
23473
23474 \newline
23475
23476 \layout Section
23477
23478 Related open source tools
23479 \begin_inset LatexCommand \label{sec:Related-open-source-tools}
23480
23481 \end_inset
23482
23483
23484 \begin_inset LatexCommand \index{Related tools}
23485
23486 \end_inset
23487
23488
23489 \layout Standard
23490 \align center
23491
23492 \begin_inset  Tabular
23493 <lyxtabular version="3" rows="14" columns="3">
23494 <features>
23495 <column alignment="left" valignment="top" leftline="true" width="0pt">
23496 <column alignment="block" valignment="top" leftline="true" width="30line%">
23497 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
23498 <row topline="true" bottomline="true">
23499 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23500 \begin_inset Text
23501
23502 \layout Standard
23503
23504 Name
23505 \end_inset
23506 </cell>
23507 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23508 \begin_inset Text
23509
23510 \layout Standard
23511
23512 Purpose
23513 \end_inset
23514 </cell>
23515 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23516 \begin_inset Text
23517
23518 \layout Standard
23519
23520 Where to get
23521 \end_inset
23522 </cell>
23523 </row>
23524 <row topline="true">
23525 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23526 \begin_inset Text
23527
23528 \layout Standard
23529
23530 gpsim
23531 \begin_inset LatexCommand \index{gpsim (pic simulator)}
23532
23533 \end_inset
23534
23535
23536 \end_inset
23537 </cell>
23538 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23539 \begin_inset Text
23540
23541 \layout Standard
23542
23543 PIC simulator
23544 \end_inset
23545 </cell>
23546 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23547 \begin_inset Text
23548
23549 \layout Standard
23550
23551
23552 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
23553
23554 \end_inset
23555
23556
23557 \end_inset
23558 </cell>
23559 </row>
23560 <row topline="true">
23561 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23562 \begin_inset Text
23563
23564 \layout Standard
23565
23566 gputils
23567 \begin_inset LatexCommand \index{gputils (pic tools)}
23568
23569 \end_inset
23570
23571
23572 \end_inset
23573 </cell>
23574 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23575 \begin_inset Text
23576
23577 \layout Standard
23578
23579 GNU PIC utilities
23580 \end_inset
23581 </cell>
23582 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23583 \begin_inset Text
23584
23585 \layout Standard
23586
23587
23588 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
23589
23590 \end_inset
23591
23592
23593 \end_inset
23594 </cell>
23595 </row>
23596 <row topline="true">
23597 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23598 \begin_inset Text
23599
23600 \layout Standard
23601
23602 flP5
23603 \end_inset
23604 </cell>
23605 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23606 \begin_inset Text
23607
23608 \layout Standard
23609
23610 PIC programmer
23611 \end_inset
23612 </cell>
23613 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23614 \begin_inset Text
23615
23616 \layout Standard
23617
23618
23619 \begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/}
23620
23621 \end_inset
23622
23623
23624 \end_inset
23625 </cell>
23626 </row>
23627 <row topline="true">
23628 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23629 \begin_inset Text
23630
23631 \layout Standard
23632
23633 ec2drv/newcdb
23634 \end_inset
23635 </cell>
23636 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23637 \begin_inset Text
23638
23639 \layout Standard
23640
23641 Tools for Silicon Laboratories JTAG debug adapter, partly based on SDCDB
23642  (Unix only)
23643 \end_inset
23644 </cell>
23645 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23646 \begin_inset Text
23647
23648 \layout Standard
23649
23650
23651 \begin_inset LatexCommand \url{http://sourceforge.net/projects/ec2drv}
23652
23653 \end_inset
23654
23655
23656 \end_inset
23657 </cell>
23658 </row>
23659 <row topline="true">
23660 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23661 \begin_inset Text
23662
23663 \layout Standard
23664
23665 indent
23666 \begin_inset LatexCommand \index{indent (source formatting tool)}
23667
23668 \end_inset
23669
23670
23671 \end_inset
23672 </cell>
23673 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23674 \begin_inset Text
23675
23676 \layout Standard
23677
23678 Formats C source - Master of the white spaces
23679 \end_inset
23680 </cell>
23681 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23682 \begin_inset Text
23683
23684 \layout Standard
23685
23686
23687 \begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html}
23688
23689 \end_inset
23690
23691
23692 \end_inset
23693 </cell>
23694 </row>
23695 <row topline="true">
23696 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23697 \begin_inset Text
23698
23699 \layout Standard
23700
23701 srecord
23702 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
23703
23704 \end_inset
23705
23706
23707 \end_inset
23708 </cell>
23709 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23710 \begin_inset Text
23711
23712 \layout Standard
23713
23714 Object file conversion, checksumming, ...
23715 \end_inset
23716 </cell>
23717 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23718 \begin_inset Text
23719
23720 \layout Standard
23721
23722
23723 \begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord}
23724
23725 \end_inset
23726
23727
23728 \end_inset
23729 </cell>
23730 </row>
23731 <row topline="true">
23732 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23733 \begin_inset Text
23734
23735 \layout Standard
23736
23737 objdump
23738 \begin_inset LatexCommand \index{objdump (tool)}
23739
23740 \end_inset
23741
23742
23743 \end_inset
23744 </cell>
23745 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23746 \begin_inset Text
23747
23748 \layout Standard
23749
23750 Object file conversion, ...
23751 \end_inset
23752 </cell>
23753 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23754 \begin_inset Text
23755
23756 \layout Standard
23757
23758 Part of binutils (should be there anyway)
23759 \end_inset
23760 </cell>
23761 </row>
23762 <row topline="true">
23763 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23764 \begin_inset Text
23765
23766 \layout Standard
23767
23768 cmon51
23769 \end_inset
23770 </cell>
23771 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23772 \begin_inset Text
23773
23774 \layout Standard
23775
23776 8051 monitor (hex up-/download, single step, disassemble)
23777 \end_inset
23778 </cell>
23779 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23780 \begin_inset Text
23781
23782 \layout Standard
23783
23784
23785 \begin_inset LatexCommand \url{http://sourceforge.net/projects/cmon51}
23786
23787 \end_inset
23788
23789
23790 \end_inset
23791 </cell>
23792 </row>
23793 <row topline="true">
23794 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23795 \begin_inset Text
23796
23797 \layout Standard
23798
23799 doxygen
23800 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
23801
23802 \end_inset
23803
23804
23805 \end_inset
23806 </cell>
23807 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23808 \begin_inset Text
23809
23810 \layout Standard
23811
23812 Source code documentation system
23813 \end_inset
23814 </cell>
23815 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23816 \begin_inset Text
23817
23818 \layout Standard
23819
23820
23821 \begin_inset LatexCommand \url{http://www.doxygen.org}
23822
23823 \end_inset
23824
23825
23826 \end_inset
23827 </cell>
23828 </row>
23829 <row topline="true">
23830 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23831 \begin_inset Text
23832
23833 \layout Standard
23834
23835 kdevelop
23836 \end_inset
23837 </cell>
23838 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23839 \begin_inset Text
23840
23841 \layout Standard
23842
23843 IDE (has anyone tried integrating SDCC & SDCDB? Unix only)
23844 \end_inset
23845 </cell>
23846 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23847 \begin_inset Text
23848
23849 \layout Standard
23850
23851
23852 \begin_inset LatexCommand \url{http://www.kdevelop.org}
23853
23854 \end_inset
23855
23856
23857 \end_inset
23858 </cell>
23859 </row>
23860 <row topline="true">
23861 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23862 \begin_inset Text
23863
23864 \layout Standard
23865
23866 paulmon
23867 \end_inset
23868 </cell>
23869 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23870 \begin_inset Text
23871
23872 \layout Standard
23873
23874 8051 monitor (hex up-/download, single step, disassemble)
23875 \end_inset
23876 </cell>
23877 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23878 \begin_inset Text
23879
23880 \layout Standard
23881
23882
23883 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/paulmon2.html}
23884
23885 \end_inset
23886
23887
23888 \end_inset
23889 </cell>
23890 </row>
23891 <row topline="true">
23892 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23893 \begin_inset Text
23894
23895 \layout Standard
23896
23897 splint
23898 \begin_inset LatexCommand \index{splint (syntax checking tool)}
23899
23900 \end_inset
23901
23902
23903 \end_inset
23904 </cell>
23905 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23906 \begin_inset Text
23907
23908 \layout Standard
23909
23910 Statically checks c sources (see
23911 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
23912
23913 \end_inset
23914
23915 )
23916 \end_inset
23917 </cell>
23918 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23919 \begin_inset Text
23920
23921 \layout Standard
23922
23923
23924 \begin_inset LatexCommand \url{http://www.splint.org}
23925
23926 \end_inset
23927
23928
23929 \end_inset
23930 </cell>
23931 </row>
23932 <row topline="true" bottomline="true">
23933 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23934 \begin_inset Text
23935
23936 \layout Standard
23937
23938 ddd
23939 \begin_inset LatexCommand \index{ddd (debugger)}
23940
23941 \end_inset
23942
23943
23944 \end_inset
23945 </cell>
23946 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23947 \begin_inset Text
23948
23949 \layout Standard
23950
23951 Debugger, serves nicely as GUI to SDCDB
23952 \begin_inset LatexCommand \index{SDCDB (debugger)}
23953
23954 \end_inset
23955
23956  (Unix only)
23957 \end_inset
23958 </cell>
23959 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23960 \begin_inset Text
23961
23962 \layout Standard
23963
23964
23965 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
23966
23967 \end_inset
23968
23969
23970 \end_inset
23971 </cell>
23972 </row>
23973 </lyxtabular>
23974
23975 \end_inset
23976
23977
23978 \newline
23979
23980 \layout Section
23981
23982 Related documentation / recommended reading
23983 \layout Standard
23984 \align center
23985
23986 \begin_inset  Tabular
23987 <lyxtabular version="3" rows="8" columns="3">
23988 <features>
23989 <column alignment="left" valignment="top" leftline="true" width="0pt">
23990 <column alignment="block" valignment="top" leftline="true" width="30line%">
23991 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
23992 <row topline="true" bottomline="true">
23993 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23994 \begin_inset Text
23995
23996 \layout Standard
23997
23998 Name
23999 \end_inset
24000 </cell>
24001 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24002 \begin_inset Text
24003
24004 \layout Standard
24005
24006 Subject / Title
24007 \end_inset
24008 </cell>
24009 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24010 \begin_inset Text
24011
24012 \layout Standard
24013
24014 Where to get
24015 \end_inset
24016 </cell>
24017 </row>
24018 <row topline="true">
24019 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24020 \begin_inset Text
24021
24022 \layout Standard
24023
24024
24025 \family roman
24026 \series medium
24027 \shape up
24028 \size normal
24029 \emph off
24030 \bar no
24031 \noun off
24032 \color none
24033 c-refcard.pdf
24034 \end_inset
24035 </cell>
24036 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24037 \begin_inset Text
24038
24039 \layout Standard
24040
24041 C Reference Card
24042 \begin_inset LatexCommand \index{C Reference card}
24043
24044 \end_inset
24045
24046 , 2 pages
24047 \end_inset
24048 </cell>
24049 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24050 \begin_inset Text
24051
24052 \layout Standard
24053
24054
24055 \begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html}
24056
24057 \end_inset
24058
24059
24060 \end_inset
24061 </cell>
24062 </row>
24063 <row topline="true">
24064 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24065 \begin_inset Text
24066
24067 \layout Standard
24068
24069 c-faq
24070 \end_inset
24071 </cell>
24072 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24073 \begin_inset Text
24074
24075 \layout Standard
24076
24077 C-FAQ-list
24078 \end_inset
24079 </cell>
24080 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24081 \begin_inset Text
24082
24083 \layout Standard
24084
24085
24086 \begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
24087
24088 \end_inset
24089
24090
24091 \end_inset
24092 </cell>
24093 </row>
24094 <row topline="true">
24095 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24096 \begin_inset Text
24097
24098 \layout Standard
24099
24100 ISO/IEC 9899:TC2
24101 \end_inset
24102 </cell>
24103 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24104 \begin_inset Text
24105
24106 \layout Standard
24107
24108
24109 \begin_inset Quotes sld
24110 \end_inset
24111
24112 C-Standard
24113 \begin_inset Quotes srd
24114 \end_inset
24115
24116
24117 \end_inset
24118 </cell>
24119 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24120 \begin_inset Text
24121
24122 \layout Standard
24123
24124
24125 \size footnotesize
24126
24127 \begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899}
24128
24129 \end_inset
24130
24131
24132 \end_inset
24133 </cell>
24134 </row>
24135 <row topline="true">
24136 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24137 \begin_inset Text
24138
24139 \layout Standard
24140
24141 ISO/IEC DTR 18037
24142 \end_inset
24143 </cell>
24144 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24145 \begin_inset Text
24146
24147 \layout Standard
24148
24149
24150 \begin_inset Quotes sld
24151 \end_inset
24152
24153 Extensions for Embedded C
24154 \begin_inset Quotes srd
24155 \end_inset
24156
24157
24158 \end_inset
24159 </cell>
24160 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24161 \begin_inset Text
24162
24163 \layout Standard
24164
24165
24166 \size footnotesize
24167
24168 \begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1021.pdf}
24169
24170 \end_inset
24171
24172
24173 \end_inset
24174 </cell>
24175 </row>
24176 <row topline="true">
24177 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24178 \begin_inset Text
24179
24180 \layout Standard
24181
24182 \end_inset
24183 </cell>
24184 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24185 \begin_inset Text
24186
24187 \layout Standard
24188
24189 Latest datasheet of the target CPU
24190 \end_inset
24191 </cell>
24192 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24193 \begin_inset Text
24194
24195 \layout Standard
24196
24197 vendor
24198 \end_inset
24199 </cell>
24200 </row>
24201 <row topline="true">
24202 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24203 \begin_inset Text
24204
24205 \layout Standard
24206
24207 \end_inset
24208 </cell>
24209 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24210 \begin_inset Text
24211
24212 \layout Standard
24213
24214 Revision history of datasheet
24215 \end_inset
24216 </cell>
24217 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24218 \begin_inset Text
24219
24220 \layout Standard
24221
24222 vendor
24223 \end_inset
24224 </cell>
24225 </row>
24226 <row topline="true" bottomline="true">
24227 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24228 \begin_inset Text
24229
24230 \layout Standard
24231
24232 S.
24233  S.
24234  Muchnick
24235 \end_inset
24236 </cell>
24237 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24238 \begin_inset Text
24239
24240 \layout Standard
24241
24242 Advanced Compiler Design and Implementation
24243 \end_inset
24244 </cell>
24245 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24246 \begin_inset Text
24247
24248 \layout Standard
24249
24250 bookstore (very dedicated, probably read other books first)
24251 \end_inset
24252 </cell>
24253 </row>
24254 </lyxtabular>
24255
24256 \end_inset
24257
24258
24259 \newline
24260
24261 \layout Section
24262
24263 Some Questions
24264 \layout Standard
24265
24266 Some questions answered, some pointers given - it might be time to in turn
24267  ask
24268 \emph on
24269 you
24270 \emph default
24271  some questions:
24272 \layout Itemize
24273
24274 can you solve your project with the selected microcontroller? Would you
24275  find out early or rather late that your target is too small/slow/whatever?
24276  Can you switch to a slightly better device if it doesn't fit?
24277 \layout Itemize
24278
24279 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
24280  and/or another programming language be more adequate? Would an operating
24281  system on the target device help?
24282 \layout Itemize
24283
24284 if you solved the problem, will the marketing department be happy?
24285 \layout Itemize
24286
24287 if the marketing department is happy, will customers be happy?
24288 \layout Itemize
24289
24290 if you're the project manager, marketing department and maybe even the customer
24291  in one person, have you tried to see the project from the outside?
24292 \layout Itemize
24293
24294 is the project done if you think it is done? Or is just that other interface/pro
24295 tocol/feature/configuration/option missing? How about website, manual(s),
24296  internationali(z|s)ation, packaging, labels, 2nd source for components,
24297  electromagnetic compatability/interference, documentation for production,
24298  production test software, update mechanism, patent issues?
24299 \layout Itemize
24300
24301 is your project adequately positioned in that magic triangle: fame, fortune,
24302  fun?
24303 \layout Standard
24304
24305 Maybe not all answers to these questions are known and some answers may
24306  even be
24307 \emph on
24308 no
24309 \emph default
24310 , nevertheless knowing these questions may help you to avoid burnout
24311 \begin_inset Foot
24312 collapsed false
24313
24314 \layout Standard
24315
24316 burnout is bad for electronic devices, programmers and motorcycle tyres
24317 \end_inset
24318
24319 .
24320  Chances are you didn't want to hear some of them...
24321 \layout Chapter
24322
24323 Support
24324 \begin_inset LatexCommand \index{Support}
24325
24326 \end_inset
24327
24328
24329 \layout Standard
24330
24331 SDCC has grown to be a large project.
24332  The compiler alone (without the preprocessor, assembler and linker) is
24333  well over 100,000 lines of code (blank stripped).
24334  The open source nature of this project is a key to its continued growth
24335  and support.
24336  You gain the benefit and support of many active software developers and
24337  end users.
24338  Is SDCC perfect? No, that's why we need your help.
24339  The developers take pride in fixing reported bugs.
24340  You can help by reporting the bugs and helping other SDCC users.
24341  There are lots of ways to contribute, and we encourage you to take part
24342  in making SDCC a great software package.
24343
24344 \layout Standard
24345
24346 The SDCC project is hosted on the SDCC sourceforge site at
24347 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
24348
24349 \end_inset
24350
24351 .
24352  You'll find the complete set of mailing lists
24353 \begin_inset LatexCommand \index{Mailing list(s)}
24354
24355 \end_inset
24356
24357 , forums, bug reporting system, patch submission
24358 \begin_inset LatexCommand \index{Patch submission}
24359
24360 \end_inset
24361
24362  system, download
24363 \begin_inset LatexCommand \index{download}
24364
24365 \end_inset
24366
24367  area and Subversion code repository
24368 \begin_inset LatexCommand \index{Subversion code repository}
24369
24370 \end_inset
24371
24372  there.
24373 \layout Section
24374
24375 Reporting Bugs
24376 \begin_inset LatexCommand \index{Bug reporting}
24377
24378 \end_inset
24379
24380
24381 \begin_inset LatexCommand \index{Reporting bugs}
24382
24383 \end_inset
24384
24385
24386 \layout Standard
24387
24388 The recommended way of reporting bugs is using the infrastructure of the
24389  sourceforge site.
24390  You can follow the status of bug reports there and have an overview about
24391  the known bugs.
24392 \layout Standard
24393
24394 Bug reports are automatically forwarded to the developer mailing list and
24395  will be fixed ASAP.
24396  When reporting a bug, it is very useful to include a small test program
24397  (the smaller the better) which reproduces the problem.
24398  If you can isolate the problem by looking at the generated assembly code,
24399  this can be very helpful.
24400  Compiling your program with the -
24401 \begin_inset ERT
24402 status Collapsed
24403
24404 \layout Standard
24405
24406 \backslash
24407 /
24408 \end_inset
24409
24410 -dumpall
24411 \begin_inset LatexCommand \index{-\/-dumpall}
24412
24413 \end_inset
24414
24415  option can sometimes be useful in locating optimization problems.
24416  When reporting a bug please maker sure you:
24417 \layout Enumerate
24418
24419 Attach the code you are compiling with SDCC.
24420
24421 \layout Enumerate
24422
24423 Specify the exact command you use to run SDCC, or attach your Makefile.
24424
24425 \layout Enumerate
24426
24427 Specify the SDCC version (type "
24428 \family sans
24429 \series bold
24430 sdcc -v
24431 \family default
24432 \series default
24433 "), your platform, and operating system.
24434
24435 \layout Enumerate
24436
24437 Provide an exact copy of any error message or incorrect output.
24438
24439 \layout Enumerate
24440
24441 Put something meaningful in the subject of your message.
24442 \layout Standard
24443
24444 Please attempt to include these 5 important parts, as applicable, in all
24445  requests for support or when reporting any problems or bugs with SDCC.
24446  Though this will make your message lengthy, it will greatly improve your
24447  chance that SDCC users and developers will be able to help you.
24448  Some SDCC developers are frustrated by bug reports without code provided
24449  that they can use to reproduce and ultimately fix the problem, so please
24450  be sure to provide sample code if you are reporting a bug!
24451 \layout Standard
24452
24453 Please have a short check that you are using a recent version of SDCC and
24454  the bug is not yet known.
24455  This is the link for reporting bugs:
24456 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
24457
24458 \end_inset
24459
24460 .
24461 \layout Section
24462
24463 Requesting Features
24464 \begin_inset LatexCommand \label{sub:Requesting-Features}
24465
24466 \end_inset
24467
24468
24469 \begin_inset LatexCommand \index{Feature request}
24470
24471 \end_inset
24472
24473
24474 \begin_inset LatexCommand \index{Requesting features}
24475
24476 \end_inset
24477
24478
24479 \layout Standard
24480
24481 Like bug reports feature requests are forwarded to the developer mailing
24482  list.
24483  This is the link for requesting features:
24484 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
24485
24486 \end_inset
24487
24488 .
24489 \layout Section
24490
24491 Submitting patches
24492 \layout Standard
24493
24494 Like bug reports contributed patches are forwarded to the developer mailing
24495  list.
24496  This is the link for submitting patches
24497 \begin_inset LatexCommand \index{Patch submission}
24498
24499 \end_inset
24500
24501 :
24502 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
24503
24504 \end_inset
24505
24506 .
24507 \layout Standard
24508
24509 You need to specify some parameters to the
24510 \family typewriter
24511 diff
24512 \family default
24513  command for the patches to be useful.
24514  If you modified more than one file a patch created f.e.
24515  with
24516 \family sans
24517 \series bold
24518
24519 \begin_inset Quotes sld
24520 \end_inset
24521
24522 diff -Naur unmodified_directory modified_directory >my_changes.patch
24523 \begin_inset Quotes srd
24524 \end_inset
24525
24526
24527 \family default
24528 \series default
24529  will be fine, otherwise
24530 \family sans
24531 \series bold
24532
24533 \begin_inset Quotes sld
24534 \end_inset
24535
24536 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
24537 \begin_inset Quotes srd
24538 \end_inset
24539
24540
24541 \series default
24542
24543 \family default
24544 will do.
24545 \layout Section
24546
24547 Getting Help
24548 \layout Standard
24549
24550 These links should take you directly to the
24551 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
24552
24553 \end_inset
24554
24555
24556 \begin_inset Foot
24557 collapsed false
24558
24559 \layout Standard
24560
24561 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
24562  automated messages (mid 2003)
24563 \end_inset
24564
24565  and the
24566 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
24567
24568 \end_inset
24569
24570 , lists
24571 \begin_inset LatexCommand \index{Mailing list(s)}
24572
24573 \end_inset
24574
24575  and forums are archived and searchable so if you are lucky someone already
24576  had a similar problem.
24577  While mails to the lists themselves are delivered promptly their web front
24578  end on sourceforge sometimes shows a severe time lag (up to several weeks),
24579  if you're seriously using SDCC please consider subscribing to the lists.
24580 \layout Section
24581
24582 ChangeLog
24583 \layout Standard
24584
24585 You can follow the status of the Subversion version
24586 \begin_inset LatexCommand \index{version}
24587
24588 \end_inset
24589
24590  of SDCC by watching the Changelog
24591 \begin_inset LatexCommand \index{Changelog}
24592
24593 \end_inset
24594
24595  in the Subversion repository
24596 \size footnotesize
24597
24598 \begin_inset LatexCommand \htmlurl{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/ChangeLog}
24599
24600 \end_inset
24601
24602 .
24603 \layout Section
24604
24605 Subversion Source Code Repository
24606 \layout Standard
24607
24608 The output of
24609 \family sans
24610 \series bold
24611 sdcc --version
24612 \family default
24613 \series default
24614  or the filenames of the snapshot versions of SDCC include date and its
24615  Subversion
24616 \begin_inset LatexCommand \index{Subversion}
24617
24618 \end_inset
24619
24620  number.
24621  Subversion allows to download the source of recent or previous versions
24622
24623 \begin_inset LatexCommand \url{http://sourceforge.net/svn/?group_id=599}
24624
24625 \end_inset
24626
24627  (by number or by date).
24628  An on-line source code browser and detailled instructions are also available
24629  there.
24630  SDCC versions starting from 1999 up to now are available (currently the
24631  versions prior to the conversion from cvs to Subversion (April 2006) are
24632  either by accessible by Subversion or by cvs).
24633 \layout Section
24634
24635 Release policy
24636 \begin_inset LatexCommand \index{Release policy}
24637
24638 \end_inset
24639
24640
24641 \layout Standard
24642
24643 Historically there often were long delays between official releases and
24644  the sourceforge download area tends to get not updated at all.
24645  Excuses in the past might have referred to problems with live range analysis,
24646  but as this was fixed a while ago, the current problem is that another
24647  excuse has to be found.
24648  Kidding aside, we have to get better there! On the other hand there are
24649  daily snapshots available at
24650 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
24651
24652 \end_inset
24653
24654 , and you can always build the very last version (hopefully with many bugs
24655  fixed, and features added) from the source code available at
24656 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
24657
24658 \end_inset
24659
24660 .
24661 \layout Section
24662
24663 Examples
24664 \begin_inset LatexCommand \index{Examples}
24665
24666 \end_inset
24667
24668
24669 \layout Standard
24670
24671 You'll find some small examples in the directory
24672 \emph on
24673 sdcc/device/examples/.
24674
24675 \emph default
24676 More examples and libraries are available at
24677 \emph on
24678  The SDCC Open Knowledge Resource
24679 \begin_inset LatexCommand \url{http://sdccokr.dl9sec.de/}
24680
24681 \end_inset
24682
24683
24684 \emph default
24685 web site or at
24686 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
24687
24688 \end_inset
24689
24690 .
24691 \layout Comment
24692
24693 I did insert a reference to Paul's web site here although it seems rather
24694  dedicated to a specific 8032 board (I think it's okay because it f.e.
24695  shows LCD/Harddisc interface and has a free 8051 monitor.
24696  Independent 8032 board vendors face hard competition of heavily subsidized
24697  development boards anyway).
24698 \layout Comment
24699
24700 Maybe we should include some links to real world applications.
24701  Preferably pointer to pointers (one for each architecture) so this stays
24702  manageable here?
24703 \layout Section
24704
24705 Quality control
24706 \begin_inset LatexCommand \index{Quality control}
24707
24708 \end_inset
24709
24710
24711 \layout Standard
24712
24713 The compiler is passed through nightly compile and build checks.
24714  The so called
24715 \shape italic
24716 regression tests
24717 \shape default
24718
24719 \begin_inset LatexCommand \index{Regression test}
24720
24721 \end_inset
24722
24723  check that SDCC itself compiles flawlessly on several platforms and checks
24724  the quality of the code generated by SDCC by running the code through simulator
24725 s.
24726  There is a separate document
24727 \shape italic
24728 test_suite.pdf
24729 \begin_inset LatexCommand \index{Test suite}
24730
24731 \end_inset
24732
24733
24734 \shape default
24735  about this.
24736 \layout Standard
24737
24738 You'll find the test code in the directory
24739 \shape italic
24740 sdcc/support/regression
24741 \shape default
24742 .
24743  You can run these tests manually by running
24744 \family sans
24745 make
24746 \family default
24747  in this directory (or f.e.
24748
24749 \family sans
24750 \series bold
24751
24752 \begin_inset Quotes sld
24753 \end_inset
24754
24755 make test-mcs51
24756 \begin_inset Quotes srd
24757 \end_inset
24758
24759
24760 \family default
24761 \series default
24762  if you don't want to run the complete tests).
24763  The test code might also be interesting if you want to look for examples
24764 \begin_inset LatexCommand \index{Examples}
24765
24766 \end_inset
24767
24768  checking corner cases of SDCC or if you plan to submit patches
24769 \begin_inset LatexCommand \index{Patch submission}
24770
24771 \end_inset
24772
24773 .
24774 \layout Standard
24775
24776 The pic port uses a different set of regression tests, you'll find them
24777  in the directory
24778 \shape italic
24779 sdcc/src/regression
24780 \shape default
24781 .
24782 \layout Section
24783
24784 Use of SDCC in Education
24785 \layout Standard
24786
24787 In short:
24788 \emph on
24789 highly
24790 \emph default
24791  encouraged
24792 \begin_inset Foot
24793 collapsed false
24794
24795 \layout Standard
24796
24797 the phrase "use in education" might evoke the association "
24798 \emph on
24799 only
24800 \emph default
24801  fit for use in education".
24802  This connotation is not intended but nevertheless risked as the licensing
24803  of SDCC makes it difficult to offer educational discounts
24804 \end_inset
24805
24806 .
24807  If your rationales are to:
24808 \layout Enumerate
24809
24810 give students a chance to understand the
24811 \emph on
24812 complete
24813 \emph default
24814  steps of code generation
24815 \layout Enumerate
24816
24817 have a curriculum that can be extended for years.
24818  Then you could use an fpga board as target and your curriculum will seamlessly
24819  extend from logic synthesis (
24820 \begin_inset LatexCommand \url[http://www.opencores.org]{opencores.org}
24821
24822 \end_inset
24823
24824 ,
24825 \begin_inset LatexCommand \url[Oregano]{http://www.oregano.at/ip/ip01.htm}
24826
24827 \end_inset
24828
24829 ), over assembly programming, to C to FPGA compilers (
24830 \begin_inset LatexCommand \url[FPGAC]{http://sf.net/projects/fpgac}
24831
24832 \end_inset
24833
24834 ) and to C.
24835 \layout Enumerate
24836
24837 be able to insert excursions about skills like using a revision control
24838  system, submitting/applying patches, using a type-setting (as opposed to
24839  word-processing) engine LyX/LaTeX, using
24840 \begin_inset LatexCommand \url[SourceForge]{http://www.sf.net}
24841
24842 \end_inset
24843
24844 , following some
24845 \begin_inset LatexCommand \url[netiquette]{http://en.wikipedia.org/wiki/Netiquette}
24846
24847 \end_inset
24848
24849 , understanding BSD/LGPL/GPL/Proprietary licensing, growth models of Open
24850  Source Software, CPU simulation, compiler regression tests
24851 \begin_inset LatexCommand \index{Regression test}
24852
24853 \end_inset
24854
24855 .
24856
24857 \newline
24858 And if there should be a shortage of ideas then you can always point students
24859  to the ever-growing feature request list
24860 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
24861
24862 \end_inset
24863
24864 .
24865 \layout Enumerate
24866
24867 not tie students to a specific host platform and instead allow them to use
24868  a host platform of
24869 \emph on
24870 their
24871 \emph default
24872  choice (among them Alpha, i386, i386_64, MacOs, Mips, Sparc, Windows and
24873  eventually
24874 \begin_inset LatexCommand \url[OLPC]{http://wiki.laptop.org/wiki/One_Laptop_per_Child}
24875
24876 \end_inset
24877
24878 )
24879 \layout Enumerate
24880
24881 not encourage students to use illegal copies of educational software
24882 \layout Enumerate
24883
24884 be immune to licensing/availability/price changes of the chosen tool chain
24885 \layout Enumerate
24886
24887 be able to change to a new target platform without having to adopt a new
24888  tool chain
24889 \layout Enumerate
24890
24891 have complete control over and insight into the tool chain
24892 \layout Enumerate
24893
24894 make your students aware about the pros and cons of open source software
24895  development
24896 \layout Enumerate
24897
24898 give back to the public as you are probably at least partially publically
24899  funded
24900 \layout Enumerate
24901
24902 give students a chance to publically prove their skills and to possibly
24903  see a world wide impact
24904 \layout Standard
24905
24906 then SDCC is probably among the first choices.
24907  Well, probably SDCC might be the only choice.
24908 \layout Chapter
24909 \pagebreak_top
24910 SDCC Technical Data
24911 \layout Section
24912
24913 Optimizations
24914 \begin_inset LatexCommand \index{Optimizations}
24915
24916 \end_inset
24917
24918
24919 \layout Standard
24920
24921 SDCC performs a host of standard optimizations in addition to some MCU specific
24922  optimizations.
24923
24924 \layout Subsection
24925
24926 Sub-expression Elimination
24927 \begin_inset LatexCommand \index{Subexpression elimination}
24928
24929 \end_inset
24930
24931
24932 \layout Standard
24933
24934 The compiler does local and
24935 \emph on
24936 g
24937 \emph default
24938 lobal
24939 \emph on
24940 c
24941 \emph default
24942 ommon
24943 \emph on
24944 s
24945 \emph default
24946 ubexpression
24947 \emph on
24948 e
24949 \emph default
24950 limination, e.g.:
24951 \layout Verse
24952
24953
24954 \family typewriter
24955 i = x + y + 1;
24956 \newline
24957 j = x + y;
24958 \layout Standard
24959
24960 will be translated to
24961 \layout Verse
24962
24963
24964 \family typewriter
24965 iTemp = x + y;
24966 \newline
24967 i = iTemp + 1;
24968 \newline
24969 j = iTemp;
24970 \layout Standard
24971
24972 Some subexpressions are not as obvious as the above example, e.g.:
24973 \layout Verse
24974
24975
24976 \family typewriter
24977 a->b[i].c = 10;
24978 \newline
24979 a->b[i].d = 11;
24980 \layout Standard
24981
24982 In this case the address arithmetic a->b[i] will be computed only once;
24983  the equivalent code in C would be.
24984 \layout Verse
24985
24986
24987 \family typewriter
24988 iTemp = a->b[i];
24989 \newline
24990 iTemp.c = 10;
24991 \newline
24992 iTemp.d = 11;
24993 \layout Standard
24994
24995 The compiler will try to keep these temporary variables in registers.
24996 \layout Subsection
24997
24998 Dead-Code Elimination
24999 \begin_inset LatexCommand \index{Dead-code elimination}
25000
25001 \end_inset
25002
25003
25004 \layout Verse
25005
25006
25007 \family typewriter
25008 int global;
25009 \newline
25010
25011 \newline
25012 void f () {
25013 \newline
25014 \SpecialChar ~
25015 \SpecialChar ~
25016 int i;
25017 \newline
25018 \SpecialChar ~
25019 \SpecialChar ~
25020 i = 1; \SpecialChar ~
25021 \SpecialChar ~
25022 \SpecialChar ~
25023 \SpecialChar ~
25024 \SpecialChar ~
25025 /* dead store */
25026 \newline
25027 \SpecialChar ~
25028 \SpecialChar ~
25029 global = 1;\SpecialChar ~
25030 /* dead store */
25031 \newline
25032 \SpecialChar ~
25033 \SpecialChar ~
25034 global = 2;
25035 \newline
25036 \SpecialChar ~
25037 \SpecialChar ~
25038 return;
25039 \newline
25040 \SpecialChar ~
25041 \SpecialChar ~
25042 global = 3;\SpecialChar ~
25043 /* unreachable */
25044 \newline
25045 }
25046 \layout Standard
25047
25048 will be changed to
25049 \layout Verse
25050
25051
25052 \family typewriter
25053 int global;
25054 \newline
25055
25056 \newline
25057 void f () {
25058 \newline
25059 \SpecialChar ~
25060 \SpecialChar ~
25061 global = 2;
25062 \newline
25063 }
25064 \layout Subsection
25065
25066 Copy-Propagation
25067 \begin_inset LatexCommand \index{Copy propagation}
25068
25069 \end_inset
25070
25071
25072 \layout Verse
25073
25074
25075 \family typewriter
25076 int f() {
25077 \newline
25078 \SpecialChar ~
25079 \SpecialChar ~
25080 int i, j;
25081 \newline
25082 \SpecialChar ~
25083 \SpecialChar ~
25084 i = 10;
25085 \newline
25086 \SpecialChar ~
25087 \SpecialChar ~
25088 j = i;
25089 \newline
25090 \SpecialChar ~
25091 \SpecialChar ~
25092 return j;
25093 \newline
25094 }
25095 \layout Standard
25096
25097 will be changed to
25098 \layout Verse
25099
25100
25101 \family typewriter
25102 int f() {
25103 \newline
25104 \SpecialChar ~
25105 \SpecialChar ~
25106 int i, j;
25107 \newline
25108 \SpecialChar ~
25109 \SpecialChar ~
25110 i = 10;
25111 \newline
25112 \SpecialChar ~
25113 \SpecialChar ~
25114 j = 10;
25115 \newline
25116 \SpecialChar ~
25117 \SpecialChar ~
25118 return 10;
25119 \newline
25120 }
25121 \layout Standard
25122
25123 Note: the dead stores created by this copy propagation will be eliminated
25124  by dead-code elimination.
25125 \layout Subsection
25126
25127 Loop Optimizations
25128 \begin_inset LatexCommand \index{Loop optimization}
25129
25130 \end_inset
25131
25132
25133 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
25134
25135 \end_inset
25136
25137
25138 \layout Standard
25139
25140 Two types of loop optimizations are done by SDCC
25141 \emph on
25142 loop invariant
25143 \emph default
25144  lifting and
25145 \emph on
25146  strength reduction
25147 \emph default
25148  of loop induction variables.
25149  In addition to the strength reduction the optimizer marks the induction
25150  variables and the register allocator tries to keep the induction variables
25151  in registers for the duration of the loop.
25152  Because of this preference of the register allocator
25153 \begin_inset LatexCommand \index{Register allocation}
25154
25155 \end_inset
25156
25157 , loop induction optimization causes an increase in register pressure, which
25158  may cause unwanted spilling of other temporary variables into the stack
25159 \begin_inset LatexCommand \index{stack}
25160
25161 \end_inset
25162
25163  / data space.
25164  The compiler will generate a warning message when it is forced to allocate
25165  extra space either on the stack or data space.
25166  If this extra space allocation is undesirable then induction optimization
25167  can be eliminated either for the entire source file (with -
25168 \begin_inset ERT
25169 status Collapsed
25170
25171 \layout Standard
25172
25173 \backslash
25174 /
25175 \end_inset
25176
25177 -noinduction option) or for a given function only using #pragma\SpecialChar ~
25178 noinduction
25179 \begin_inset LatexCommand \index{\#pragma noinduction}
25180
25181 \end_inset
25182
25183 .
25184 \newline
25185
25186 \newline
25187 Loop Invariant:
25188 \layout Verse
25189
25190
25191 \family typewriter
25192 for (i = 0 ; i < 100 ; i ++)
25193 \newline
25194 \SpecialChar ~
25195 \SpecialChar ~
25196 \SpecialChar ~
25197 \SpecialChar ~
25198 f += k + l;
25199 \layout Standard
25200
25201 changed to
25202 \layout Verse
25203
25204
25205 \family typewriter
25206 itemp = k + l;
25207 \newline
25208 for (i = 0; i < 100; i++)
25209 \newline
25210 \SpecialChar ~
25211 \SpecialChar ~
25212 \SpecialChar ~
25213 \SpecialChar ~
25214 f += itemp;
25215 \layout Standard
25216
25217 As mentioned previously some loop invariants are not as apparent, all static
25218  address computations are also moved out of the loop.
25219 \newline
25220
25221 \newline
25222 Strength Reduction
25223 \begin_inset LatexCommand \index{Strength reduction}
25224
25225 \end_inset
25226
25227 , this optimization substitutes an expression by a cheaper expression:
25228 \layout Verse
25229
25230
25231 \family typewriter
25232 for (i=0;i < 100; i++)
25233 \newline
25234 \SpecialChar ~
25235 \SpecialChar ~
25236 \SpecialChar ~
25237 \SpecialChar ~
25238 ar[i*5] = i*3;
25239 \layout Standard
25240
25241 changed to
25242 \layout Verse
25243
25244
25245 \family typewriter
25246 itemp1 = 0;
25247 \newline
25248 itemp2 = 0;
25249 \newline
25250 for (i=0;i< 100;i++) {
25251 \newline
25252 \SpecialChar ~
25253 \SpecialChar ~
25254 \SpecialChar ~
25255 \SpecialChar ~
25256 ar[itemp1] = itemp2;
25257 \newline
25258 \SpecialChar ~
25259 \SpecialChar ~
25260 \SpecialChar ~
25261 \SpecialChar ~
25262 itemp1 += 5;
25263 \newline
25264 \SpecialChar ~
25265 \SpecialChar ~
25266 \SpecialChar ~
25267 \SpecialChar ~
25268 itemp2 += 3;
25269 \newline
25270 }
25271 \layout Standard
25272
25273 The more expensive multiplication
25274 \begin_inset LatexCommand \index{Multiplication}
25275
25276 \end_inset
25277
25278  is changed to a less expensive addition.
25279 \layout Subsection
25280
25281 Loop Reversing
25282 \begin_inset LatexCommand \index{Loop reversing}
25283
25284 \end_inset
25285
25286
25287 \layout Standard
25288
25289 This optimization is done to reduce the overhead of checking loop boundaries
25290  for every iteration.
25291  Some simple loops can be reversed and implemented using a
25292 \begin_inset Quotes eld
25293 \end_inset
25294
25295 decrement and jump if not zero
25296 \begin_inset Quotes erd
25297 \end_inset
25298
25299  instruction.
25300  SDCC checks for the following criterion to determine if a loop is reversible
25301  (note: more sophisticated compilers use data-dependency analysis to make
25302  this determination, SDCC uses a more simple minded analysis).
25303 \layout Itemize
25304
25305 The 'for' loop is of the form
25306 \newline
25307
25308 \newline
25309
25310 \family typewriter
25311 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
25312  += 1])
25313 \newline
25314 \SpecialChar ~
25315 \SpecialChar ~
25316 \SpecialChar ~
25317 \SpecialChar ~
25318 <for body>
25319 \layout Itemize
25320
25321 The <for body> does not contain
25322 \begin_inset Quotes eld
25323 \end_inset
25324
25325 continue
25326 \begin_inset Quotes erd
25327 \end_inset
25328
25329  or 'break
25330 \begin_inset Quotes erd
25331 \end_inset
25332
25333 .
25334 \layout Itemize
25335
25336 All goto's are contained within the loop.
25337 \layout Itemize
25338
25339 No function calls within the loop.
25340 \layout Itemize
25341
25342 The loop control variable <sym> is not assigned any value within the loop
25343 \layout Itemize
25344
25345 The loop control variable does NOT participate in any arithmetic operation
25346  within the loop.
25347 \layout Itemize
25348
25349 There are NO switch statements in the loop.
25350 \layout Subsection
25351
25352 Algebraic Simplifications
25353 \layout Standard
25354
25355 SDCC does numerous algebraic simplifications, the following is a small sub-set
25356  of these optimizations.
25357 \layout Verse
25358
25359
25360 \family typewriter
25361 i = j + 0;\SpecialChar ~
25362 \SpecialChar ~
25363 \SpecialChar ~
25364 \SpecialChar ~
25365  /* changed to: */\SpecialChar ~
25366 \SpecialChar ~
25367 \SpecialChar ~
25368 \SpecialChar ~
25369  i = j;
25370 \newline
25371 i /= 2;\SpecialChar ~
25372 \SpecialChar ~
25373 \SpecialChar ~
25374 \SpecialChar ~
25375 \SpecialChar ~
25376 \SpecialChar ~
25377 \SpecialChar ~
25378  /* changed to: */\SpecialChar ~
25379 \SpecialChar ~
25380 \SpecialChar ~
25381 \SpecialChar ~
25382  i >>= 1;
25383 \newline
25384 i = j - j;\SpecialChar ~
25385 \SpecialChar ~
25386 \SpecialChar ~
25387 \SpecialChar ~
25388  /* changed to: */\SpecialChar ~
25389 \SpecialChar ~
25390 \SpecialChar ~
25391 \SpecialChar ~
25392  i = 0;
25393 \newline
25394 i = j / 1;\SpecialChar ~
25395 \SpecialChar ~
25396 \SpecialChar ~
25397 \SpecialChar ~
25398  /* changed to: */\SpecialChar ~
25399 \SpecialChar ~
25400 \SpecialChar ~
25401 \SpecialChar ~
25402  i = j;
25403 \layout Standard
25404
25405 Note the subexpressions
25406 \begin_inset LatexCommand \index{Subexpression}
25407
25408 \end_inset
25409
25410  given above are generally introduced by macro expansions or as a result
25411  of copy/constant propagation.
25412 \layout Subsection
25413
25414 'switch' Statements
25415 \begin_inset LatexCommand \label{sub:'switch'-Statements}
25416
25417 \end_inset
25418
25419
25420 \begin_inset LatexCommand \index{switch statement}
25421
25422 \end_inset
25423
25424
25425 \layout Standard
25426
25427 SDCC can optimize switch statements to jump tables
25428 \begin_inset LatexCommand \index{jump tables}
25429
25430 \end_inset
25431
25432 .
25433  It makes the decision based on an estimate of the generated code size.
25434  SDCC is quite liberal in the requirements for jump table generation:
25435 \layout Itemize
25436
25437 The labels need not be in order, and the starting number need not be one
25438  or zero, the case labels are in numerical sequence or not too many case
25439  labels are missing.
25440 \begin_deeper
25441 \layout Verse
25442
25443
25444 \family typewriter
25445 switch(i) {\SpecialChar ~
25446 \SpecialChar ~
25447 \SpecialChar ~
25448 \SpecialChar ~
25449 \SpecialChar ~
25450 \SpecialChar ~
25451 \SpecialChar ~
25452 \SpecialChar ~
25453 \SpecialChar ~
25454 \SpecialChar ~
25455 \SpecialChar ~
25456 \SpecialChar ~
25457 \SpecialChar ~
25458 \SpecialChar ~
25459 \SpecialChar ~
25460 \SpecialChar ~
25461 \SpecialChar ~
25462 \SpecialChar ~
25463 \SpecialChar ~
25464 \SpecialChar ~
25465 \SpecialChar ~
25466 \SpecialChar ~
25467 \SpecialChar ~
25468 \SpecialChar ~
25469 \SpecialChar ~
25470 \SpecialChar ~
25471 switch (i) {
25472 \newline
25473 \SpecialChar ~
25474 \SpecialChar ~
25475 \SpecialChar ~
25476 case 4: ...\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 \SpecialChar ~
25496 \SpecialChar ~
25497 \SpecialChar ~
25498 \SpecialChar ~
25499 \SpecialChar ~
25500 \SpecialChar ~
25501 \SpecialChar ~
25502 case 0: ...
25503
25504 \newline
25505 \SpecialChar ~
25506 \SpecialChar ~
25507 \SpecialChar ~
25508 case 5: ...\SpecialChar ~
25509 \SpecialChar ~
25510 \SpecialChar ~
25511 \SpecialChar ~
25512 \SpecialChar ~
25513 \SpecialChar ~
25514 \SpecialChar ~
25515 \SpecialChar ~
25516 \SpecialChar ~
25517 \SpecialChar ~
25518 \SpecialChar ~
25519 \SpecialChar ~
25520 \SpecialChar ~
25521 \SpecialChar ~
25522 \SpecialChar ~
25523 \SpecialChar ~
25524 \SpecialChar ~
25525 \SpecialChar ~
25526 \SpecialChar ~
25527 \SpecialChar ~
25528 \SpecialChar ~
25529 \SpecialChar ~
25530 \SpecialChar ~
25531 \SpecialChar ~
25532 \SpecialChar ~
25533 \SpecialChar ~
25534 case 1: ...
25535
25536 \newline
25537 \SpecialChar ~
25538 \SpecialChar ~
25539 \SpecialChar ~
25540 case 3: ...\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 \SpecialChar ~
25559 \SpecialChar ~
25560 \SpecialChar ~
25561 \SpecialChar ~
25562 \SpecialChar ~
25563 \SpecialChar ~
25564 \SpecialChar ~
25565 \SpecialChar ~
25566
25567 \newline
25568 \SpecialChar ~
25569 \SpecialChar ~
25570 \SpecialChar ~
25571 case 6: ...\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 \SpecialChar ~
25591 \SpecialChar ~
25592 \SpecialChar ~
25593 \SpecialChar ~
25594 \SpecialChar ~
25595 \SpecialChar ~
25596 \SpecialChar ~
25597 case 3: ...
25598
25599 \newline
25600 \SpecialChar ~
25601 \SpecialChar ~
25602 \SpecialChar ~
25603 case 7: ...\SpecialChar ~
25604 \SpecialChar ~
25605 \SpecialChar ~
25606 \SpecialChar ~
25607 \SpecialChar ~
25608 \SpecialChar ~
25609 \SpecialChar ~
25610 \SpecialChar ~
25611 \SpecialChar ~
25612 \SpecialChar ~
25613 \SpecialChar ~
25614 \SpecialChar ~
25615 \SpecialChar ~
25616 \SpecialChar ~
25617 \SpecialChar ~
25618 \SpecialChar ~
25619 \SpecialChar ~
25620 \SpecialChar ~
25621 \SpecialChar ~
25622 \SpecialChar ~
25623 \SpecialChar ~
25624 \SpecialChar ~
25625 \SpecialChar ~
25626 \SpecialChar ~
25627 \SpecialChar ~
25628 \SpecialChar ~
25629 case 4: ...
25630
25631 \newline
25632 \SpecialChar ~
25633 \SpecialChar ~
25634 \SpecialChar ~
25635 case 8: ...\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 \SpecialChar ~
25654 \SpecialChar ~
25655 \SpecialChar ~
25656 \SpecialChar ~
25657 \SpecialChar ~
25658 \SpecialChar ~
25659 \SpecialChar ~
25660 \SpecialChar ~
25661 case 5: ...
25662
25663 \newline
25664 \SpecialChar ~
25665 \SpecialChar ~
25666 \SpecialChar ~
25667 case 9: ...\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 \SpecialChar ~
25686 \SpecialChar ~
25687 \SpecialChar ~
25688 \SpecialChar ~
25689 \SpecialChar ~
25690 \SpecialChar ~
25691 \SpecialChar ~
25692 \SpecialChar ~
25693 case 6: ...
25694
25695 \newline
25696 \SpecialChar ~
25697 \SpecialChar ~
25698 \SpecialChar ~
25699 case 10: ...\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 \SpecialChar ~
25718 \SpecialChar ~
25719 \SpecialChar ~
25720 \SpecialChar ~
25721 \SpecialChar ~
25722 \SpecialChar ~
25723 \SpecialChar ~
25724 case 7: ...
25725
25726 \newline
25727 \SpecialChar ~
25728 \SpecialChar ~
25729 \SpecialChar ~
25730 case 11: ...\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 \SpecialChar ~
25749 \SpecialChar ~
25750 \SpecialChar ~
25751 \SpecialChar ~
25752 \SpecialChar ~
25753 \SpecialChar ~
25754 \SpecialChar ~
25755 case 8: ...
25756
25757 \newline
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 \SpecialChar ~
25780 \SpecialChar ~
25781 \SpecialChar ~
25782 \SpecialChar ~
25783 \SpecialChar ~
25784 \SpecialChar ~
25785 \SpecialChar ~
25786 \SpecialChar ~
25787 \SpecialChar ~
25788 \SpecialChar ~
25789 \SpecialChar ~
25790 \SpecialChar ~
25791 \SpecialChar ~
25792 \SpecialChar ~
25793 \SpecialChar ~
25794 }
25795 \layout Standard
25796
25797 Both the above switch statements will be implemented using a jump-table.
25798  The example to the right side is slightly more efficient as the check for
25799  the lower boundary of the jump-table is not needed.
25800 \end_deeper
25801 \layout Itemize
25802
25803 The number of case labels is not larger than supported by the target architectur
25804 e.
25805 \layout Itemize
25806
25807 If the case labels are not in numerical sequence ('gaps' between cases)
25808  SDCC checks whether a jump table with additionally inserted dummy cases
25809  is still attractive.
25810
25811 \layout Itemize
25812
25813 If the starting number is not zero and a check for the lower boundary of
25814  the jump-table can thus be eliminated SDCC might insert dummy cases 0,
25815  ...
25816  .
25817 \layout Standard
25818
25819 Switch statements which have large gaps in the numeric sequence or those
25820  that have too many case labels can be split into more than one switch statement
25821  for efficient code generation, e.g.:
25822 \layout Verse
25823
25824
25825 \family typewriter
25826 switch (i) {
25827 \newline
25828 \SpecialChar ~
25829 \SpecialChar ~
25830 case 1: ...
25831
25832 \newline
25833 \SpecialChar ~
25834 \SpecialChar ~
25835 case 2: ...
25836
25837 \newline
25838 \SpecialChar ~
25839 \SpecialChar ~
25840 case 3: ...
25841
25842 \newline
25843 \SpecialChar ~
25844 \SpecialChar ~
25845 case 4: ...
25846
25847 \newline
25848 \SpecialChar ~
25849 \SpecialChar ~
25850 case 5: ...
25851
25852 \newline
25853 \SpecialChar ~
25854 \SpecialChar ~
25855 case 6: ...
25856
25857 \newline
25858 \SpecialChar ~
25859 \SpecialChar ~
25860 case 7: ...
25861
25862 \newline
25863 \SpecialChar ~
25864 \SpecialChar ~
25865 case 101: ...
25866
25867 \newline
25868 \SpecialChar ~
25869 \SpecialChar ~
25870 case 102: ...
25871
25872 \newline
25873 \SpecialChar ~
25874 \SpecialChar ~
25875 case 103: ...
25876
25877 \newline
25878 \SpecialChar ~
25879 \SpecialChar ~
25880 case 104: ...
25881
25882 \newline
25883 \SpecialChar ~
25884 \SpecialChar ~
25885 case 105: ...
25886
25887 \newline
25888 \SpecialChar ~
25889 \SpecialChar ~
25890 case 106: ...
25891
25892 \newline
25893 \SpecialChar ~
25894 \SpecialChar ~
25895 case 107: ...
25896
25897 \newline
25898 }
25899 \layout Standard
25900
25901 If the above switch statement is broken down into two switch statements
25902 \layout Verse
25903
25904
25905 \family typewriter
25906 switch (i) {
25907 \newline
25908 \SpecialChar ~
25909 \SpecialChar ~
25910 case 1: ...
25911
25912 \newline
25913 \SpecialChar ~
25914 \SpecialChar ~
25915 case 2: ...
25916
25917 \newline
25918 \SpecialChar ~
25919 \SpecialChar ~
25920 case 3: ...
25921
25922 \newline
25923 \SpecialChar ~
25924 \SpecialChar ~
25925 case 4: ...
25926
25927 \newline
25928 \SpecialChar ~
25929 \SpecialChar ~
25930 case 5: ...
25931
25932 \newline
25933 \SpecialChar ~
25934 \SpecialChar ~
25935 case 6: ...
25936
25937 \newline
25938 \SpecialChar ~
25939 \SpecialChar ~
25940 case 7: ...
25941
25942 \newline
25943 }
25944 \layout Standard
25945
25946 and
25947 \layout Verse
25948
25949
25950 \family typewriter
25951 switch (i) {
25952 \newline
25953 \SpecialChar ~
25954 \SpecialChar ~
25955 case 101: ...
25956
25957 \newline
25958 \SpecialChar ~
25959 \SpecialChar ~
25960 case 102: ...
25961
25962 \newline
25963 \SpecialChar ~
25964 \SpecialChar ~
25965 case 103: ...
25966
25967 \newline
25968 \SpecialChar ~
25969 \SpecialChar ~
25970 case 104: ...
25971
25972 \newline
25973 \SpecialChar ~
25974 \SpecialChar ~
25975 case 105: ...
25976
25977 \newline
25978 \SpecialChar ~
25979 \SpecialChar ~
25980 case 106: ...
25981
25982 \newline
25983 \SpecialChar ~
25984 \SpecialChar ~
25985 case 107: ...
25986
25987 \newline
25988 }
25989 \layout Standard
25990
25991 then both the switch statements will be implemented using jump-tables whereas
25992  the unmodified switch statement will not be.
25993 \layout Comment
25994
25995 There might be reasons which SDCC cannot know about to either favour or
25996  not favour jump tables.
25997  If the target system has to be as quick for the last switch case as for
25998  the first (pro jump table), or if the switch argument is known to be zero
25999  in the majority of the cases (contra jump table).
26000 \layout Standard
26001
26002 The pragma nojtbound
26003 \begin_inset LatexCommand \index{\#pragma nojtbound}
26004
26005 \end_inset
26006
26007  can be used to turn off checking the
26008 \emph on
26009 j
26010 \emph default
26011 ump
26012 \emph on
26013 t
26014 \emph default
26015 able
26016 \emph on
26017 bound
26018 \emph default
26019 aries.
26020  It has no effect if a default label is supplied.
26021  Use of this pragma is dangerous: if the switch
26022 \begin_inset LatexCommand \index{switch statement}
26023
26024 \end_inset
26025
26026  argument is not matched by a case statement the processor will happily
26027  jump into Nirvana.
26028 \layout Subsection
26029
26030 Bit-shifting Operations
26031 \begin_inset LatexCommand \index{Bit shifting}
26032
26033 \end_inset
26034
26035 .
26036 \layout Standard
26037
26038 Bit shifting is one of the most frequently used operation in embedded programmin
26039 g.
26040  SDCC tries to implement bit-shift operations in the most efficient way
26041  possible, e.g.:
26042 \layout Verse
26043
26044
26045 \family typewriter
26046 unsigned char i;
26047 \newline
26048 ...
26049
26050 \newline
26051 i >>= 4;
26052 \newline
26053 ...
26054 \layout Standard
26055
26056 generates the following code:
26057 \layout Verse
26058
26059
26060 \family typewriter
26061 mov\SpecialChar ~
26062  a,_i
26063 \newline
26064 swap a
26065 \newline
26066 anl\SpecialChar ~
26067  a,#0x0f
26068 \newline
26069 mov\SpecialChar ~
26070  _i,a
26071 \layout Standard
26072
26073 In general SDCC will never setup a loop if the shift count is known.
26074  Another example:
26075 \layout Verse
26076
26077
26078 \family typewriter
26079 unsigned int i;
26080 \newline
26081 ...
26082
26083 \newline
26084 i >>= 9;
26085 \newline
26086 ...
26087 \layout Standard
26088
26089 will generate:
26090 \layout Verse
26091
26092
26093 \family typewriter
26094 mov\SpecialChar ~
26095 \SpecialChar ~
26096 a,(_i + 1)
26097 \newline
26098 mov\SpecialChar ~
26099 \SpecialChar ~
26100 (_i + 1),#0x00
26101 \newline
26102 clr\SpecialChar ~
26103 \SpecialChar ~
26104 c
26105 \newline
26106 rrc\SpecialChar ~
26107 \SpecialChar ~
26108 a
26109 \newline
26110 mov\SpecialChar ~
26111 \SpecialChar ~
26112 _i,a
26113 \layout Subsection
26114
26115 Bit-rotation
26116 \begin_inset LatexCommand \index{Bit rotation}
26117
26118 \end_inset
26119
26120
26121 \layout Standard
26122
26123 A special case of the bit-shift operation is bit rotation
26124 \begin_inset LatexCommand \index{rotating bits}
26125
26126 \end_inset
26127
26128 , SDCC recognizes the following expression to be a left bit-rotation:
26129 \layout Verse
26130
26131
26132 \family typewriter
26133 \series bold
26134 unsigned
26135 \series default
26136 \SpecialChar ~
26137 \SpecialChar ~
26138 char i;\SpecialChar ~
26139 \SpecialChar ~
26140 \SpecialChar ~
26141 \SpecialChar ~
26142 \SpecialChar ~
26143 \SpecialChar ~
26144 \SpecialChar ~
26145 \SpecialChar ~
26146 \SpecialChar ~
26147 \SpecialChar ~
26148 \SpecialChar ~
26149 /* unsigned is needed for rotation */
26150 \newline
26151 ...
26152
26153 \newline
26154 i = ((i << 1) | (i >> 7));
26155 \family default
26156
26157 \newline
26158
26159 \family typewriter
26160 ...
26161 \layout Standard
26162
26163 will generate the following code:
26164 \layout Verse
26165
26166
26167 \family typewriter
26168 mov\SpecialChar ~
26169 \SpecialChar ~
26170 a,_i
26171 \newline
26172 rl\SpecialChar ~
26173 \SpecialChar ~
26174 \SpecialChar ~
26175 a
26176 \newline
26177 mov\SpecialChar ~
26178 \SpecialChar ~
26179 _i,a
26180 \layout Standard
26181
26182 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
26183 ns of this case will also be recognized as bit-rotation, i.e.:
26184 \layout Verse
26185
26186
26187 \family typewriter
26188 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
26189 \layout Subsection
26190
26191 Nibble and Byte Swapping
26192 \layout Standard
26193
26194 Other special cases of the bit-shift operations are nibble or byte swapping
26195 \begin_inset LatexCommand \index{swapping nibbles/bytes}
26196
26197 \end_inset
26198
26199 , SDCC recognizes the following expressions:
26200 \layout Verse
26201
26202
26203 \family typewriter
26204 \series bold
26205 unsigned
26206 \series default
26207 \SpecialChar ~
26208 \SpecialChar ~
26209 char i;
26210 \newline
26211
26212 \series bold
26213 unsigned
26214 \series default
26215 \SpecialChar ~
26216 \SpecialChar ~
26217 int j;
26218 \newline
26219 ...
26220
26221 \newline
26222 i = ((i << 4) | (i >> 4));
26223 \family default
26224
26225 \newline
26226
26227 \family typewriter
26228 j = ((j << 8) | (j >> 8));
26229 \layout Standard
26230
26231 and generates a swap instruction for the nibble swapping
26232 \begin_inset LatexCommand \index{Nibble swapping}
26233
26234 \end_inset
26235
26236  or move instructions for the byte swapping
26237 \begin_inset LatexCommand \index{Byte swapping}
26238
26239 \end_inset
26240
26241 .
26242  The
26243 \begin_inset Quotes sld
26244 \end_inset
26245
26246 j
26247 \begin_inset Quotes srd
26248 \end_inset
26249
26250  example can be used to convert from little to big-endian or vice versa.
26251  If you want to change the endianness of a
26252 \emph on
26253 signed
26254 \emph default
26255  integer you have to cast to
26256 \family typewriter
26257 (unsigned int)
26258 \family default
26259  first.
26260 \layout Standard
26261
26262 Note that SDCC stores numbers in little-endian
26263 \begin_inset Foot
26264 collapsed false
26265
26266 \layout Standard
26267
26268 Usually 8-bit processors don't care much about endianness.
26269  This is not the case for the standard 8051 which only has an instruction
26270  to increment its
26271 \emph on
26272 dptr
26273 \emph default
26274
26275 \begin_inset LatexCommand \index{DPTR}
26276
26277 \end_inset
26278
26279 -datapointer
26280 \emph on
26281
26282 \emph default
26283 so little-endian is the more efficient byte order.
26284 \end_inset
26285
26286
26287 \begin_inset LatexCommand \index{little-endian}
26288
26289 \end_inset
26290
26291
26292 \begin_inset LatexCommand \index{Endianness}
26293
26294 \end_inset
26295
26296  format (i.e.
26297  lowest order first).
26298 \layout Subsection
26299
26300 Highest Order Bit
26301 \begin_inset LatexCommand \index{Highest Order Bit}
26302
26303 \end_inset
26304
26305  / Any Order Bit
26306 \begin_inset LatexCommand \index{Any Order Bit}
26307
26308 \end_inset
26309
26310
26311 \layout Standard
26312
26313 It is frequently required to obtain the highest order bit of an integral
26314  type (long, int, short or char types).
26315  Also obtaining any other order bit is not uncommon.
26316  SDCC recognizes the following expressions to yield the highest order bit
26317  and generates optimized code for it, e.g.:
26318 \layout Verse
26319
26320
26321 \family typewriter
26322 unsigned int gint;
26323 \newline
26324
26325 \newline
26326 foo () {
26327 \newline
26328 \SpecialChar ~
26329 \SpecialChar ~
26330 unsigned char hob1, aob1;
26331 \newline
26332 \SpecialChar ~
26333 \SpecialChar ~
26334 bit hob2, hob3, aob2, aob3;
26335 \newline
26336 \SpecialChar ~
26337 \SpecialChar ~
26338 ...
26339
26340 \newline
26341 \SpecialChar ~
26342 \SpecialChar ~
26343 hob1 = (gint >> 15) & 1;
26344 \newline
26345 \SpecialChar ~
26346 \SpecialChar ~
26347 hob2 = (gint >> 15) & 1;
26348 \newline
26349 \SpecialChar ~
26350 \SpecialChar ~
26351 hob3 = gint & 0x8000;
26352 \newline
26353 \SpecialChar ~
26354 \SpecialChar ~
26355 aob1 = (gint >> 9) & 1;
26356 \newline
26357 \SpecialChar ~
26358 \SpecialChar ~
26359 aob2 = (gint >> 8) & 1;
26360 \newline
26361 \SpecialChar ~
26362 \SpecialChar ~
26363 aob3 = gint & 0x0800;
26364 \newline
26365 \SpecialChar ~
26366 \SpecialChar ~
26367 ..
26368
26369 \newline
26370 }
26371 \layout Standard
26372
26373 will generate the following code:
26374 \layout Verse
26375
26376
26377 \family typewriter
26378 \SpecialChar ~
26379 \SpecialChar ~
26380 \SpecialChar ~
26381 \SpecialChar ~
26382 \SpecialChar ~
26383 \SpecialChar ~
26384 \SpecialChar ~
26385 \SpecialChar ~
26386 \SpecialChar ~
26387 \SpecialChar ~
26388 \SpecialChar ~
26389 \SpecialChar ~
26390 \SpecialChar ~
26391 \SpecialChar ~
26392 \SpecialChar ~
26393 \SpecialChar ~
26394 \SpecialChar ~
26395 \SpecialChar ~
26396 \SpecialChar ~
26397 \SpecialChar ~
26398 \SpecialChar ~
26399 \SpecialChar ~
26400 \SpecialChar ~
26401 \SpecialChar ~
26402 \SpecialChar ~
26403  61 ;\SpecialChar ~
26404  hob.c 7
26405 \newline
26406 000A E5*01\SpecialChar ~
26407 \SpecialChar ~
26408 \SpecialChar ~
26409 \SpecialChar ~
26410 \SpecialChar ~
26411 \SpecialChar ~
26412 \SpecialChar ~
26413 \SpecialChar ~
26414 \SpecialChar ~
26415 \SpecialChar ~
26416 \SpecialChar ~
26417 \SpecialChar ~
26418 \SpecialChar ~
26419 \SpecialChar ~
26420 \SpecialChar ~
26421  62\SpecialChar ~
26422 \SpecialChar ~
26423 \SpecialChar ~
26424 \SpecialChar ~
26425 \SpecialChar ~
26426 \SpecialChar ~
26427 \SpecialChar ~
26428 \SpecialChar ~
26429  mov\SpecialChar ~
26430 \SpecialChar ~
26431  a,(_gint + 1)
26432 \newline
26433 000C 23\SpecialChar ~
26434 \SpecialChar ~
26435 \SpecialChar ~
26436 \SpecialChar ~
26437 \SpecialChar ~
26438 \SpecialChar ~
26439 \SpecialChar ~
26440 \SpecialChar ~
26441 \SpecialChar ~
26442 \SpecialChar ~
26443 \SpecialChar ~
26444 \SpecialChar ~
26445 \SpecialChar ~
26446 \SpecialChar ~
26447 \SpecialChar ~
26448 \SpecialChar ~
26449 \SpecialChar ~
26450 \SpecialChar ~
26451  63\SpecialChar ~
26452 \SpecialChar ~
26453 \SpecialChar ~
26454 \SpecialChar ~
26455 \SpecialChar ~
26456 \SpecialChar ~
26457 \SpecialChar ~
26458 \SpecialChar ~
26459  rl\SpecialChar ~
26460 \SpecialChar ~
26461 \SpecialChar ~
26462  a
26463 \newline
26464 000D 54 01\SpecialChar ~
26465 \SpecialChar ~
26466 \SpecialChar ~
26467 \SpecialChar ~
26468 \SpecialChar ~
26469 \SpecialChar ~
26470 \SpecialChar ~
26471 \SpecialChar ~
26472 \SpecialChar ~
26473 \SpecialChar ~
26474 \SpecialChar ~
26475 \SpecialChar ~
26476 \SpecialChar ~
26477 \SpecialChar ~
26478 \SpecialChar ~
26479  64\SpecialChar ~
26480 \SpecialChar ~
26481 \SpecialChar ~
26482 \SpecialChar ~
26483 \SpecialChar ~
26484 \SpecialChar ~
26485 \SpecialChar ~
26486 \SpecialChar ~
26487  anl\SpecialChar ~
26488 \SpecialChar ~
26489  a,#0x01
26490 \newline
26491 000F F5*02\SpecialChar ~
26492 \SpecialChar ~
26493 \SpecialChar ~
26494 \SpecialChar ~
26495 \SpecialChar ~
26496 \SpecialChar ~
26497 \SpecialChar ~
26498 \SpecialChar ~
26499 \SpecialChar ~
26500 \SpecialChar ~
26501 \SpecialChar ~
26502 \SpecialChar ~
26503 \SpecialChar ~
26504 \SpecialChar ~
26505 \SpecialChar ~
26506  65\SpecialChar ~
26507 \SpecialChar ~
26508 \SpecialChar ~
26509 \SpecialChar ~
26510 \SpecialChar ~
26511 \SpecialChar ~
26512 \SpecialChar ~
26513 \SpecialChar ~
26514  mov\SpecialChar ~
26515 \SpecialChar ~
26516  _foo_hob1_1_1,a
26517 \newline
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 \SpecialChar ~
26531 \SpecialChar ~
26532 \SpecialChar ~
26533 \SpecialChar ~
26534 \SpecialChar ~
26535 \SpecialChar ~
26536 \SpecialChar ~
26537 \SpecialChar ~
26538 \SpecialChar ~
26539 \SpecialChar ~
26540 \SpecialChar ~
26541 \SpecialChar ~
26542 \SpecialChar ~
26543  66 ;\SpecialChar ~
26544  hob.c 8
26545 \newline
26546 0011 E5*01\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  67\SpecialChar ~
26562 \SpecialChar ~
26563 \SpecialChar ~
26564 \SpecialChar ~
26565 \SpecialChar ~
26566 \SpecialChar ~
26567 \SpecialChar ~
26568 \SpecialChar ~
26569  mov\SpecialChar ~
26570 \SpecialChar ~
26571  a,(_gint + 1)
26572 \newline
26573 0013 33\SpecialChar ~
26574 \SpecialChar ~
26575 \SpecialChar ~
26576 \SpecialChar ~
26577 \SpecialChar ~
26578 \SpecialChar ~
26579 \SpecialChar ~
26580 \SpecialChar ~
26581 \SpecialChar ~
26582 \SpecialChar ~
26583 \SpecialChar ~
26584 \SpecialChar ~
26585 \SpecialChar ~
26586 \SpecialChar ~
26587 \SpecialChar ~
26588 \SpecialChar ~
26589 \SpecialChar ~
26590 \SpecialChar ~
26591  68\SpecialChar ~
26592 \SpecialChar ~
26593 \SpecialChar ~
26594 \SpecialChar ~
26595 \SpecialChar ~
26596 \SpecialChar ~
26597 \SpecialChar ~
26598 \SpecialChar ~
26599  rlc\SpecialChar ~
26600 \SpecialChar ~
26601  a
26602 \newline
26603 0014 92*00\SpecialChar ~
26604 \SpecialChar ~
26605 \SpecialChar ~
26606 \SpecialChar ~
26607 \SpecialChar ~
26608 \SpecialChar ~
26609 \SpecialChar ~
26610 \SpecialChar ~
26611 \SpecialChar ~
26612 \SpecialChar ~
26613 \SpecialChar ~
26614 \SpecialChar ~
26615 \SpecialChar ~
26616 \SpecialChar ~
26617 \SpecialChar ~
26618  69\SpecialChar ~
26619 \SpecialChar ~
26620 \SpecialChar ~
26621 \SpecialChar ~
26622 \SpecialChar ~
26623 \SpecialChar ~
26624 \SpecialChar ~
26625 \SpecialChar ~
26626  mov\SpecialChar ~
26627 \SpecialChar ~
26628  _foo_hob2_1_1,c
26629 \newline
26630 \SpecialChar ~
26631 \SpecialChar ~
26632 \SpecialChar ~
26633 \SpecialChar ~
26634 \SpecialChar ~
26635 \SpecialChar ~
26636 \SpecialChar ~
26637 \SpecialChar ~
26638 \SpecialChar ~
26639 \SpecialChar ~
26640 \SpecialChar ~
26641 \SpecialChar ~
26642 \SpecialChar ~
26643 \SpecialChar ~
26644 \SpecialChar ~
26645 \SpecialChar ~
26646 \SpecialChar ~
26647 \SpecialChar ~
26648 \SpecialChar ~
26649 \SpecialChar ~
26650 \SpecialChar ~
26651 \SpecialChar ~
26652 \SpecialChar ~
26653 \SpecialChar ~
26654 \SpecialChar ~
26655  66 ;\SpecialChar ~
26656  hob.c 9
26657 \newline
26658 0016 E5*01\SpecialChar ~
26659 \SpecialChar ~
26660 \SpecialChar ~
26661 \SpecialChar ~
26662 \SpecialChar ~
26663 \SpecialChar ~
26664 \SpecialChar ~
26665 \SpecialChar ~
26666 \SpecialChar ~
26667 \SpecialChar ~
26668 \SpecialChar ~
26669 \SpecialChar ~
26670 \SpecialChar ~
26671 \SpecialChar ~
26672 \SpecialChar ~
26673  67\SpecialChar ~
26674 \SpecialChar ~
26675 \SpecialChar ~
26676 \SpecialChar ~
26677 \SpecialChar ~
26678 \SpecialChar ~
26679 \SpecialChar ~
26680 \SpecialChar ~
26681  mov\SpecialChar ~
26682 \SpecialChar ~
26683  a,(_gint + 1)
26684 \newline
26685 0018 33\SpecialChar ~
26686 \SpecialChar ~
26687 \SpecialChar ~
26688 \SpecialChar ~
26689 \SpecialChar ~
26690 \SpecialChar ~
26691 \SpecialChar ~
26692 \SpecialChar ~
26693 \SpecialChar ~
26694 \SpecialChar ~
26695 \SpecialChar ~
26696 \SpecialChar ~
26697 \SpecialChar ~
26698 \SpecialChar ~
26699 \SpecialChar ~
26700 \SpecialChar ~
26701 \SpecialChar ~
26702 \SpecialChar ~
26703  68\SpecialChar ~
26704 \SpecialChar ~
26705 \SpecialChar ~
26706 \SpecialChar ~
26707 \SpecialChar ~
26708 \SpecialChar ~
26709 \SpecialChar ~
26710 \SpecialChar ~
26711  rlc\SpecialChar ~
26712 \SpecialChar ~
26713  a
26714 \newline
26715 0019 92*01\SpecialChar ~
26716 \SpecialChar ~
26717 \SpecialChar ~
26718 \SpecialChar ~
26719 \SpecialChar ~
26720 \SpecialChar ~
26721 \SpecialChar ~
26722 \SpecialChar ~
26723 \SpecialChar ~
26724 \SpecialChar ~
26725 \SpecialChar ~
26726 \SpecialChar ~
26727 \SpecialChar ~
26728 \SpecialChar ~
26729 \SpecialChar ~
26730  69\SpecialChar ~
26731 \SpecialChar ~
26732 \SpecialChar ~
26733 \SpecialChar ~
26734 \SpecialChar ~
26735 \SpecialChar ~
26736 \SpecialChar ~
26737 \SpecialChar ~
26738  mov\SpecialChar ~
26739 \SpecialChar ~
26740  _foo_hob3_1_1,c
26741 \newline
26742 \SpecialChar ~
26743 \SpecialChar ~
26744 \SpecialChar ~
26745 \SpecialChar ~
26746 \SpecialChar ~
26747 \SpecialChar ~
26748 \SpecialChar ~
26749 \SpecialChar ~
26750 \SpecialChar ~
26751 \SpecialChar ~
26752 \SpecialChar ~
26753 \SpecialChar ~
26754 \SpecialChar ~
26755 \SpecialChar ~
26756 \SpecialChar ~
26757 \SpecialChar ~
26758 \SpecialChar ~
26759 \SpecialChar ~
26760 \SpecialChar ~
26761 \SpecialChar ~
26762 \SpecialChar ~
26763 \SpecialChar ~
26764 \SpecialChar ~
26765 \SpecialChar ~
26766 \SpecialChar ~
26767  70 ;\SpecialChar ~
26768  hob.c 10
26769 \newline
26770 001B E5*01\SpecialChar ~
26771 \SpecialChar ~
26772 \SpecialChar ~
26773 \SpecialChar ~
26774 \SpecialChar ~
26775 \SpecialChar ~
26776 \SpecialChar ~
26777 \SpecialChar ~
26778 \SpecialChar ~
26779 \SpecialChar ~
26780 \SpecialChar ~
26781 \SpecialChar ~
26782 \SpecialChar ~
26783 \SpecialChar ~
26784 \SpecialChar ~
26785  71\SpecialChar ~
26786 \SpecialChar ~
26787 \SpecialChar ~
26788 \SpecialChar ~
26789 \SpecialChar ~
26790 \SpecialChar ~
26791 \SpecialChar ~
26792 \SpecialChar ~
26793  mov\SpecialChar ~
26794 \SpecialChar ~
26795  a,(_gint + 1)
26796 \newline
26797 001D 03\SpecialChar ~
26798 \SpecialChar ~
26799 \SpecialChar ~
26800 \SpecialChar ~
26801 \SpecialChar ~
26802 \SpecialChar ~
26803 \SpecialChar ~
26804 \SpecialChar ~
26805 \SpecialChar ~
26806 \SpecialChar ~
26807 \SpecialChar ~
26808 \SpecialChar ~
26809 \SpecialChar ~
26810 \SpecialChar ~
26811 \SpecialChar ~
26812 \SpecialChar ~
26813 \SpecialChar ~
26814 \SpecialChar ~
26815  72\SpecialChar ~
26816 \SpecialChar ~
26817 \SpecialChar ~
26818 \SpecialChar ~
26819 \SpecialChar ~
26820 \SpecialChar ~
26821 \SpecialChar ~
26822 \SpecialChar ~
26823  rr\SpecialChar ~
26824 \SpecialChar ~
26825 \SpecialChar ~
26826  a
26827 \newline
26828 001E 54 01\SpecialChar ~
26829 \SpecialChar ~
26830 \SpecialChar ~
26831 \SpecialChar ~
26832 \SpecialChar ~
26833 \SpecialChar ~
26834 \SpecialChar ~
26835 \SpecialChar ~
26836 \SpecialChar ~
26837 \SpecialChar ~
26838 \SpecialChar ~
26839 \SpecialChar ~
26840 \SpecialChar ~
26841 \SpecialChar ~
26842 \SpecialChar ~
26843  73\SpecialChar ~
26844 \SpecialChar ~
26845 \SpecialChar ~
26846 \SpecialChar ~
26847 \SpecialChar ~
26848 \SpecialChar ~
26849 \SpecialChar ~
26850 \SpecialChar ~
26851  anl\SpecialChar ~
26852 \SpecialChar ~
26853  a,#0x01
26854 \newline
26855 0020 F5*03\SpecialChar ~
26856 \SpecialChar ~
26857 \SpecialChar ~
26858 \SpecialChar ~
26859 \SpecialChar ~
26860 \SpecialChar ~
26861 \SpecialChar ~
26862 \SpecialChar ~
26863 \SpecialChar ~
26864 \SpecialChar ~
26865 \SpecialChar ~
26866 \SpecialChar ~
26867 \SpecialChar ~
26868 \SpecialChar ~
26869 \SpecialChar ~
26870  74\SpecialChar ~
26871 \SpecialChar ~
26872 \SpecialChar ~
26873 \SpecialChar ~
26874 \SpecialChar ~
26875 \SpecialChar ~
26876 \SpecialChar ~
26877 \SpecialChar ~
26878  mov\SpecialChar ~
26879 \SpecialChar ~
26880  _foo_aob1_1_1,a
26881 \newline
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 \SpecialChar ~
26895 \SpecialChar ~
26896 \SpecialChar ~
26897 \SpecialChar ~
26898 \SpecialChar ~
26899 \SpecialChar ~
26900 \SpecialChar ~
26901 \SpecialChar ~
26902 \SpecialChar ~
26903 \SpecialChar ~
26904 \SpecialChar ~
26905 \SpecialChar ~
26906 \SpecialChar ~
26907  75 ;\SpecialChar ~
26908  hob.c 11
26909 \newline
26910 0022 E5*01\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  76\SpecialChar ~
26926 \SpecialChar ~
26927 \SpecialChar ~
26928 \SpecialChar ~
26929 \SpecialChar ~
26930 \SpecialChar ~
26931 \SpecialChar ~
26932 \SpecialChar ~
26933  mov\SpecialChar ~
26934 \SpecialChar ~
26935  a,(_gint + 1)
26936 \newline
26937 0024 13\SpecialChar ~
26938 \SpecialChar ~
26939 \SpecialChar ~
26940 \SpecialChar ~
26941 \SpecialChar ~
26942 \SpecialChar ~
26943 \SpecialChar ~
26944 \SpecialChar ~
26945 \SpecialChar ~
26946 \SpecialChar ~
26947 \SpecialChar ~
26948 \SpecialChar ~
26949 \SpecialChar ~
26950 \SpecialChar ~
26951 \SpecialChar ~
26952 \SpecialChar ~
26953 \SpecialChar ~
26954 \SpecialChar ~
26955  77\SpecialChar ~
26956 \SpecialChar ~
26957 \SpecialChar ~
26958 \SpecialChar ~
26959 \SpecialChar ~
26960 \SpecialChar ~
26961 \SpecialChar ~
26962 \SpecialChar ~
26963  rrc\SpecialChar ~
26964 \SpecialChar ~
26965  a
26966 \newline
26967 0025 92*02\SpecialChar ~
26968 \SpecialChar ~
26969 \SpecialChar ~
26970 \SpecialChar ~
26971 \SpecialChar ~
26972 \SpecialChar ~
26973 \SpecialChar ~
26974 \SpecialChar ~
26975 \SpecialChar ~
26976 \SpecialChar ~
26977 \SpecialChar ~
26978 \SpecialChar ~
26979 \SpecialChar ~
26980 \SpecialChar ~
26981 \SpecialChar ~
26982  78\SpecialChar ~
26983 \SpecialChar ~
26984 \SpecialChar ~
26985 \SpecialChar ~
26986 \SpecialChar ~
26987 \SpecialChar ~
26988 \SpecialChar ~
26989 \SpecialChar ~
26990  mov\SpecialChar ~
26991 \SpecialChar ~
26992  _foo_aob2_1_1,c
26993 \newline
26994 \SpecialChar ~
26995 \SpecialChar ~
26996 \SpecialChar ~
26997 \SpecialChar ~
26998 \SpecialChar ~
26999 \SpecialChar ~
27000 \SpecialChar ~
27001 \SpecialChar ~
27002 \SpecialChar ~
27003 \SpecialChar ~
27004 \SpecialChar ~
27005 \SpecialChar ~
27006 \SpecialChar ~
27007 \SpecialChar ~
27008 \SpecialChar ~
27009 \SpecialChar ~
27010 \SpecialChar ~
27011 \SpecialChar ~
27012 \SpecialChar ~
27013 \SpecialChar ~
27014 \SpecialChar ~
27015 \SpecialChar ~
27016 \SpecialChar ~
27017 \SpecialChar ~
27018 \SpecialChar ~
27019  79 ;\SpecialChar ~
27020  hob.c 12
27021 \newline
27022 0027 E5*01\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  80\SpecialChar ~
27038 \SpecialChar ~
27039 \SpecialChar ~
27040 \SpecialChar ~
27041 \SpecialChar ~
27042 \SpecialChar ~
27043 \SpecialChar ~
27044 \SpecialChar ~
27045  mov\SpecialChar ~
27046 \SpecialChar ~
27047  a,(_gint + 1)
27048 \newline
27049 0029 A2 E3\SpecialChar ~
27050 \SpecialChar ~
27051 \SpecialChar ~
27052 \SpecialChar ~
27053 \SpecialChar ~
27054 \SpecialChar ~
27055 \SpecialChar ~
27056 \SpecialChar ~
27057 \SpecialChar ~
27058 \SpecialChar ~
27059 \SpecialChar ~
27060 \SpecialChar ~
27061 \SpecialChar ~
27062 \SpecialChar ~
27063 \SpecialChar ~
27064  81\SpecialChar ~
27065 \SpecialChar ~
27066 \SpecialChar ~
27067 \SpecialChar ~
27068 \SpecialChar ~
27069 \SpecialChar ~
27070 \SpecialChar ~
27071 \SpecialChar ~
27072  mov\SpecialChar ~
27073 \SpecialChar ~
27074  c,acc[3]
27075 \newline
27076 002B 92*03\SpecialChar ~
27077 \SpecialChar ~
27078 \SpecialChar ~
27079 \SpecialChar ~
27080 \SpecialChar ~
27081 \SpecialChar ~
27082 \SpecialChar ~
27083 \SpecialChar ~
27084 \SpecialChar ~
27085 \SpecialChar ~
27086 \SpecialChar ~
27087 \SpecialChar ~
27088 \SpecialChar ~
27089 \SpecialChar ~
27090 \SpecialChar ~
27091  82\SpecialChar ~
27092 \SpecialChar ~
27093 \SpecialChar ~
27094 \SpecialChar ~
27095 \SpecialChar ~
27096 \SpecialChar ~
27097 \SpecialChar ~
27098 \SpecialChar ~
27099  mov\SpecialChar ~
27100 \SpecialChar ~
27101  _foo_aob3_1_1,c
27102 \layout Standard
27103
27104 Other variations of these cases however will
27105 \emph on
27106 not
27107 \emph default
27108  be recognized.
27109  They are standard C expressions, so I heartily recommend these be the only
27110  way to get the highest order bit, (it is portable).
27111  Of course it will be recognized even if it is embedded in other expressions,
27112  e.g.:
27113 \layout Verse
27114
27115
27116 \family typewriter
27117 xyz = gint + ((gint >> 15) & 1);
27118 \layout Standard
27119
27120 will still be recognized.
27121 \layout Subsection
27122
27123 Higher Order Byte
27124 \begin_inset LatexCommand \index{Higher Order Byte}
27125
27126 \end_inset
27127
27128  / Higher Order Word
27129 \begin_inset LatexCommand \index{Higher Order Word}
27130
27131 \end_inset
27132
27133
27134 \layout Standard
27135
27136 It is also frequently required to obtain a higher order byte or word of
27137  a larger integral type (long, int or short types).
27138  SDCC recognizes the following expressions to yield the higher order byte
27139  or word and generates optimized code for it, e.g.:
27140 \layout Verse
27141
27142
27143 \family typewriter
27144 unsigned int gint;
27145 \newline
27146 unsigned long int glong;
27147 \newline
27148
27149 \newline
27150 foo () {
27151 \newline
27152 \SpecialChar ~
27153 \SpecialChar ~
27154 unsigned char hob1, hob2;
27155 \newline
27156 \SpecialChar ~
27157 \SpecialChar ~
27158 unsigned int how1, how2;
27159 \newline
27160 \SpecialChar ~
27161 \SpecialChar ~
27162 ...
27163
27164 \newline
27165 \SpecialChar ~
27166 \SpecialChar ~
27167 hob1 = (gint >> 8) & 0xFF;
27168 \newline
27169 \SpecialChar ~
27170 \SpecialChar ~
27171 hob2 = glong >> 24;
27172 \newline
27173 \SpecialChar ~
27174 \SpecialChar ~
27175 how1 = (glong >> 16) & 0xFFFF;
27176 \newline
27177 \SpecialChar ~
27178 \SpecialChar ~
27179 how2 = glong >> 8;
27180 \newline
27181 \SpecialChar ~
27182 \SpecialChar ~
27183 ..
27184
27185 \newline
27186 }
27187 \layout Standard
27188
27189 will generate the following code:
27190 \layout Verse
27191
27192
27193 \family typewriter
27194 \SpecialChar ~
27195 \SpecialChar ~
27196 \SpecialChar ~
27197 \SpecialChar ~
27198 \SpecialChar ~
27199 \SpecialChar ~
27200 \SpecialChar ~
27201 \SpecialChar ~
27202 \SpecialChar ~
27203 \SpecialChar ~
27204 \SpecialChar ~
27205 \SpecialChar ~
27206 \SpecialChar ~
27207 \SpecialChar ~
27208 \SpecialChar ~
27209 \SpecialChar ~
27210 \SpecialChar ~
27211 \SpecialChar ~
27212 \SpecialChar ~
27213 \SpecialChar ~
27214 \SpecialChar ~
27215 \SpecialChar ~
27216 \SpecialChar ~
27217 \SpecialChar ~
27218 \SpecialChar ~
27219  91 ;\SpecialChar ~
27220  hob.c 15
27221 \newline
27222 0037 85*01*06\SpecialChar ~
27223 \SpecialChar ~
27224 \SpecialChar ~
27225 \SpecialChar ~
27226 \SpecialChar ~
27227 \SpecialChar ~
27228 \SpecialChar ~
27229 \SpecialChar ~
27230 \SpecialChar ~
27231 \SpecialChar ~
27232 \SpecialChar ~
27233 \SpecialChar ~
27234  92\SpecialChar ~
27235 \SpecialChar ~
27236 \SpecialChar ~
27237 \SpecialChar ~
27238 \SpecialChar ~
27239 \SpecialChar ~
27240 \SpecialChar ~
27241 \SpecialChar ~
27242  mov\SpecialChar ~
27243 \SpecialChar ~
27244  _foo_hob1_1_1,(_gint + 1)
27245 \newline
27246 \SpecialChar ~
27247 \SpecialChar ~
27248 \SpecialChar ~
27249 \SpecialChar ~
27250 \SpecialChar ~
27251 \SpecialChar ~
27252 \SpecialChar ~
27253 \SpecialChar ~
27254 \SpecialChar ~
27255 \SpecialChar ~
27256 \SpecialChar ~
27257 \SpecialChar ~
27258 \SpecialChar ~
27259 \SpecialChar ~
27260 \SpecialChar ~
27261 \SpecialChar ~
27262 \SpecialChar ~
27263 \SpecialChar ~
27264 \SpecialChar ~
27265 \SpecialChar ~
27266 \SpecialChar ~
27267 \SpecialChar ~
27268 \SpecialChar ~
27269 \SpecialChar ~
27270 \SpecialChar ~
27271  93 ;\SpecialChar ~
27272  hob.c 16
27273 \newline
27274 003A 85*05*07\SpecialChar ~
27275 \SpecialChar ~
27276 \SpecialChar ~
27277 \SpecialChar ~
27278 \SpecialChar ~
27279 \SpecialChar ~
27280 \SpecialChar ~
27281 \SpecialChar ~
27282 \SpecialChar ~
27283 \SpecialChar ~
27284 \SpecialChar ~
27285 \SpecialChar ~
27286  94\SpecialChar ~
27287 \SpecialChar ~
27288 \SpecialChar ~
27289 \SpecialChar ~
27290 \SpecialChar ~
27291 \SpecialChar ~
27292 \SpecialChar ~
27293 \SpecialChar ~
27294  mov\SpecialChar ~
27295 \SpecialChar ~
27296  _foo_hob2_1_1,(_glong + 3)
27297 \newline
27298 \SpecialChar ~
27299 \SpecialChar ~
27300 \SpecialChar ~
27301 \SpecialChar ~
27302 \SpecialChar ~
27303 \SpecialChar ~
27304 \SpecialChar ~
27305 \SpecialChar ~
27306 \SpecialChar ~
27307 \SpecialChar ~
27308 \SpecialChar ~
27309 \SpecialChar ~
27310 \SpecialChar ~
27311 \SpecialChar ~
27312 \SpecialChar ~
27313 \SpecialChar ~
27314 \SpecialChar ~
27315 \SpecialChar ~
27316 \SpecialChar ~
27317 \SpecialChar ~
27318 \SpecialChar ~
27319 \SpecialChar ~
27320 \SpecialChar ~
27321 \SpecialChar ~
27322 \SpecialChar ~
27323  95 ;\SpecialChar ~
27324  hob.c 17
27325 \newline
27326 003D 85*04*08\SpecialChar ~
27327 \SpecialChar ~
27328 \SpecialChar ~
27329 \SpecialChar ~
27330 \SpecialChar ~
27331 \SpecialChar ~
27332 \SpecialChar ~
27333 \SpecialChar ~
27334 \SpecialChar ~
27335 \SpecialChar ~
27336 \SpecialChar ~
27337 \SpecialChar ~
27338  96\SpecialChar ~
27339 \SpecialChar ~
27340 \SpecialChar ~
27341 \SpecialChar ~
27342 \SpecialChar ~
27343 \SpecialChar ~
27344 \SpecialChar ~
27345 \SpecialChar ~
27346  mov\SpecialChar ~
27347 \SpecialChar ~
27348  _foo_how1_1_1,(_glong + 2)
27349 \newline
27350 0040 85*05*09\SpecialChar ~
27351 \SpecialChar ~
27352 \SpecialChar ~
27353 \SpecialChar ~
27354 \SpecialChar ~
27355 \SpecialChar ~
27356 \SpecialChar ~
27357 \SpecialChar ~
27358 \SpecialChar ~
27359 \SpecialChar ~
27360 \SpecialChar ~
27361 \SpecialChar ~
27362  97\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 + 1),(_glong + 3)
27373 \newline
27374 0043 85*03*0A\SpecialChar ~
27375 \SpecialChar ~
27376 \SpecialChar ~
27377 \SpecialChar ~
27378 \SpecialChar ~
27379 \SpecialChar ~
27380 \SpecialChar ~
27381 \SpecialChar ~
27382 \SpecialChar ~
27383 \SpecialChar ~
27384 \SpecialChar ~
27385 \SpecialChar ~
27386  98\SpecialChar ~
27387 \SpecialChar ~
27388 \SpecialChar ~
27389 \SpecialChar ~
27390 \SpecialChar ~
27391 \SpecialChar ~
27392 \SpecialChar ~
27393 \SpecialChar ~
27394  mov\SpecialChar ~
27395 \SpecialChar ~
27396  _foo_how2_1_1,(_glong + 1)
27397 \newline
27398 0046 85*04*0B\SpecialChar ~
27399 \SpecialChar ~
27400 \SpecialChar ~
27401 \SpecialChar ~
27402 \SpecialChar ~
27403 \SpecialChar ~
27404 \SpecialChar ~
27405 \SpecialChar ~
27406 \SpecialChar ~
27407 \SpecialChar ~
27408 \SpecialChar ~
27409 \SpecialChar ~
27410  99\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 + 1),(_glong + 2)
27421 \layout Standard
27422
27423 Again, variations of these cases may
27424 \emph on
27425 not
27426 \emph default
27427  be recognized.
27428  They are standard C expressions, so I heartily recommend these be the only
27429  way to get the higher order byte/word, (it is portable).
27430  Of course it will be recognized even if it is embedded in other expressions,
27431  e.g.:
27432 \layout Verse
27433
27434
27435 \family typewriter
27436 xyz = gint + ((gint >> 8) & 0xFF);
27437 \layout Standard
27438
27439 will still be recognized.
27440 \layout Subsection
27441
27442 Peephole Optimizer
27443 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
27444
27445 \end_inset
27446
27447
27448 \begin_inset LatexCommand \index{Peephole optimizer}
27449
27450 \end_inset
27451
27452
27453 \layout Standard
27454
27455 The compiler uses a rule based, pattern matching and re-writing mechanism
27456  for peep-hole optimization.
27457  It is inspired by
27458 \emph on
27459 copt
27460 \emph default
27461  a peep-hole optimizer by Christopher W.
27462  Fraser (cwfraser\SpecialChar ~
27463 @\SpecialChar ~
27464 microsoft.com).
27465  A default set of rules are compiled into the compiler, additional rules
27466  may be added with the
27467 \emph on
27468 -
27469 \begin_inset ERT
27470 status Collapsed
27471
27472 \layout Standard
27473
27474 \backslash
27475 /
27476 \end_inset
27477
27478 -peep-file
27479 \begin_inset LatexCommand \index{-\/-peep-file}
27480
27481 \end_inset
27482
27483  <filename>
27484 \emph default
27485  option.
27486  The rule language is best illustrated with examples.
27487 \layout Verse
27488
27489
27490 \family typewriter
27491 replace {
27492 \newline
27493 \SpecialChar ~
27494 \SpecialChar ~
27495 mov %1,a
27496 \newline
27497 \SpecialChar ~
27498 \SpecialChar ~
27499 mov a,%1
27500 \newline
27501 } by {
27502 \newline
27503 \SpecialChar ~
27504 \SpecialChar ~
27505 mov %1,a
27506 \newline
27507 }
27508 \layout Standard
27509
27510 The above rule will change the following assembly
27511 \begin_inset LatexCommand \index{Assembler routines}
27512
27513 \end_inset
27514
27515  sequence:
27516 \layout Verse
27517
27518
27519 \family typewriter
27520 mov r1,a
27521 \newline
27522 mov a,r1
27523 \layout Standard
27524
27525 to
27526 \layout Verse
27527
27528
27529 \family typewriter
27530 mov r1,a
27531 \layout Standard
27532
27533 Note: All occurrences of a
27534 \emph on
27535 %n
27536 \emph default
27537  (pattern variable) must denote the same string.
27538  With the above rule, the assembly sequence:
27539 \layout Verse
27540
27541
27542 \family typewriter
27543 mov r1,a
27544 \newline
27545 mov a,r2
27546 \layout Standard
27547
27548 will remain unmodified.
27549 \newline
27550
27551 \newline
27552 Other special case optimizations may be added by the user (via
27553 \emph on
27554 -
27555 \begin_inset ERT
27556 status Collapsed
27557
27558 \layout Standard
27559
27560 \backslash
27561 /
27562 \end_inset
27563
27564 -peep-file option
27565 \emph default
27566 ).
27567  E.g.
27568  some variants of the 8051 MCU
27569 \begin_inset LatexCommand \index{MCS51 variants}
27570
27571 \end_inset
27572
27573  allow only
27574 \family typewriter
27575 ajmp
27576 \family default
27577  and
27578 \family typewriter
27579 acall
27580 \family default
27581 .
27582  The following two rules will change all
27583 \family typewriter
27584 ljmp
27585 \family default
27586  and
27587 \family typewriter
27588 lcall
27589 \family default
27590  to
27591 \family typewriter
27592 ajmp
27593 \family default
27594  and
27595 \family typewriter
27596 acall
27597 \layout Verse
27598
27599
27600 \family typewriter
27601 replace { lcall %1 } by { acall %1 }
27602 \newline
27603 replace { ljmp %1 } by { ajmp %1 }
27604 \layout Standard
27605
27606 The
27607 \emph on
27608 inline-assembler code
27609 \emph default
27610  is also passed through the peep hole optimizer, thus the peephole optimizer
27611  can also be used as an assembly level macro expander.
27612  The rules themselves are MCU dependent whereas the rule language infra-structur
27613 e is MCU independent.
27614  Peephole optimization rules for other MCU can be easily programmed using
27615  the rule language.
27616 \newline
27617
27618 \newline
27619 The syntax for a rule is as follows:
27620 \layout Verse
27621
27622
27623 \family typewriter
27624 rule := replace [ restart ] '{' <assembly sequence> '
27625 \backslash
27626 n'
27627 \newline
27628 \SpecialChar ~
27629  \SpecialChar ~
27630  \SpecialChar ~
27631  \SpecialChar ~
27632  \SpecialChar ~
27633  \SpecialChar ~
27634  \SpecialChar ~
27635  \SpecialChar ~
27636  \SpecialChar ~
27637  \SpecialChar ~
27638  \SpecialChar ~
27639  \SpecialChar ~
27640  \SpecialChar ~
27641  \SpecialChar ~
27642  '}' by '{' '
27643 \backslash
27644 n'
27645 \newline
27646 \SpecialChar ~
27647  \SpecialChar ~
27648  \SpecialChar ~
27649  \SpecialChar ~
27650  \SpecialChar ~
27651  \SpecialChar ~
27652  \SpecialChar ~
27653  \SpecialChar ~
27654  \SpecialChar ~
27655  \SpecialChar ~
27656  \SpecialChar ~
27657  \SpecialChar ~
27658  \SpecialChar ~
27659  \SpecialChar ~
27660  \SpecialChar ~
27661  \SpecialChar ~
27662  <assembly sequence> '
27663 \backslash
27664 n'
27665 \newline
27666 \SpecialChar ~
27667  \SpecialChar ~
27668  \SpecialChar ~
27669  \SpecialChar ~
27670  \SpecialChar ~
27671  \SpecialChar ~
27672  \SpecialChar ~
27673  \SpecialChar ~
27674  \SpecialChar ~
27675  \SpecialChar ~
27676  \SpecialChar ~
27677  \SpecialChar ~
27678  \SpecialChar ~
27679  \SpecialChar ~
27680  '}' [if <functionName> ] '
27681 \backslash
27682 n'
27683 \layout Standard
27684
27685 <assembly sequence> := assembly instruction (each instruction including
27686  labels must be on a separate line).
27687 \newline
27688
27689 \newline
27690 The optimizer will apply to the rules one by one from the top in the sequence
27691  of their appearance, it will terminate when all rules are exhausted.
27692  If the 'restart' option is specified, then the optimizer will start matching
27693  the rules again from the top, this option for a rule is expensive (performance)
27694 , it is intended to be used in situations where a transformation will trigger
27695  the same rule again.
27696  An example of this (not a good one, it has side effects) is the following
27697  rule:
27698 \layout Verse
27699
27700
27701 \family typewriter
27702 replace restart {
27703 \newline
27704 \SpecialChar ~
27705 \SpecialChar ~
27706 pop %1
27707 \newline
27708 \SpecialChar ~
27709 \SpecialChar ~
27710 push %1 } by {
27711 \newline
27712 \SpecialChar ~
27713 \SpecialChar ~
27714 ; nop
27715 \newline
27716 }
27717 \layout Standard
27718
27719 Note that the replace pattern cannot be a blank, but can be a comment line.
27720  Without the 'restart' option only the innermost 'pop' 'push' pair would
27721  be eliminated, i.e.:
27722 \layout Verse
27723
27724
27725 \family typewriter
27726 pop ar1
27727 \newline
27728 pop ar2
27729 \newline
27730 push ar2
27731 \newline
27732 push ar1
27733 \layout Standard
27734
27735 would result in:
27736 \layout Verse
27737
27738
27739 \family typewriter
27740 pop ar1
27741 \newline
27742 ; nop
27743 \newline
27744 push ar1
27745 \layout Standard
27746
27747
27748 \emph on
27749 with
27750 \emph default
27751  the restart option the rule will be applied again to the resulting code
27752  and then all the pop-push pairs will be eliminated to yield:
27753 \layout Verse
27754
27755
27756 \family typewriter
27757 ; nop
27758 \newline
27759 ; nop
27760 \layout Standard
27761
27762 A conditional function can be attached to a rule.
27763  Attaching rules are somewhat more involved, let me illustrate this with
27764  an example.
27765 \layout Verse
27766
27767
27768 \family typewriter
27769 replace {
27770 \newline
27771 \SpecialChar ~
27772  \SpecialChar ~
27773  \SpecialChar ~
27774 ljmp %5
27775 \newline
27776 %2:
27777 \newline
27778 } by {
27779 \newline
27780 \SpecialChar ~
27781  \SpecialChar ~
27782  \SpecialChar ~
27783 sjmp %5
27784 \newline
27785 %2:
27786 \newline
27787 } if labelInRange
27788 \layout Standard
27789
27790 The optimizer does a look-up of a function name table defined in function
27791
27792 \emph on
27793 callFuncByName
27794 \emph default
27795  in the source file SDCCpeeph.c, with the name
27796 \emph on
27797 labelInRange
27798 \emph default
27799 .
27800  If it finds a corresponding entry the function is called.
27801  Note there can be no parameters specified for these functions, in this
27802  case the use of
27803 \emph on
27804 %5
27805 \emph default
27806  is crucial, since the function
27807 \emph on
27808 labelInRange
27809 \emph default
27810  expects to find the label in that particular variable (the hash table containin
27811 g the variable bindings is passed as a parameter).
27812  If you want to code more such functions, take a close look at the function
27813  labelInRange and the calling mechanism in source file SDCCpeeph.c.
27814  Currently implemented are
27815 \emph on
27816 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
27817  24bitMode, portIsDS390, 24bitModeAndPortDS390
27818 \emph default
27819 and
27820 \emph on
27821  notVolatile
27822 \emph default
27823 .
27824 \layout Standard
27825
27826 I know this whole thing is a little kludgey, but maybe some day we will
27827  have some better means.
27828  If you are looking at this file, you will see the default rules that are
27829  compiled into the compiler, you can add your own rules in the default set
27830  there if you get tired of specifying the -
27831 \begin_inset ERT
27832 status Collapsed
27833
27834 \layout Standard
27835
27836 \backslash
27837 /
27838 \end_inset
27839
27840 -peep-file option.
27841 \layout Section
27842
27843 ANSI-Compliance
27844 \begin_inset LatexCommand \index{ANSI-compliance}
27845
27846 \end_inset
27847
27848
27849 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
27850
27851 \end_inset
27852
27853
27854 \layout Standard
27855
27856 The latest publically available version of the standard
27857 \emph on
27858 ISO/IEC 9899 - Programming languages - C
27859 \emph default
27860  should be available at:
27861 \begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899}
27862
27863 \end_inset
27864
27865 .
27866 \newline
27867
27868 \layout Standard
27869
27870 Deviations from the compliance:
27871 \layout Itemize
27872
27873 functions are not reentrant
27874 \begin_inset LatexCommand \index{reentrant}
27875
27876 \end_inset
27877
27878  unless explicitly declared as such or the
27879 \series bold
27880 -
27881 \begin_inset ERT
27882 status Collapsed
27883
27884 \layout Standard
27885
27886 \backslash
27887 /
27888 \end_inset
27889
27890 -stack-auto
27891 \begin_inset LatexCommand \index{-\/-stack-auto}
27892
27893 \end_inset
27894
27895
27896 \series default
27897  command line option is specified.
27898 \layout Itemize
27899
27900 structures and unions cannot be assigned values directly, cannot be passed
27901  as function parameters or assigned to each other and cannot be a return
27902  value from a function, e.g.:
27903 \begin_deeper
27904 \layout Verse
27905
27906
27907 \family typewriter
27908 struct s { ...
27909  };
27910 \newline
27911 struct s s1, s2;
27912 \newline
27913 foo()
27914 \newline
27915 {
27916 \newline
27917 \SpecialChar ~
27918 \SpecialChar ~
27919 \SpecialChar ~
27920 \SpecialChar ~
27921 ...
27922
27923 \newline
27924 \SpecialChar ~
27925 \SpecialChar ~
27926 \SpecialChar ~
27927 \SpecialChar ~
27928 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
27929 \newline
27930 \SpecialChar ~
27931 \SpecialChar ~
27932 \SpecialChar ~
27933 \SpecialChar ~
27934 ...
27935
27936 \newline
27937 }
27938 \newline
27939 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
27940  */
27941 \newline
27942 {
27943 \newline
27944 \SpecialChar ~
27945 \SpecialChar ~
27946 \SpecialChar ~
27947 \SpecialChar ~
27948 struct s rets;
27949 \newline
27950 \SpecialChar ~
27951 \SpecialChar ~
27952 \SpecialChar ~
27953 \SpecialChar ~
27954 ...
27955
27956 \newline
27957 \SpecialChar ~
27958 \SpecialChar ~
27959 \SpecialChar ~
27960 \SpecialChar ~
27961 return rets;/* is invalid in SDCC although allowed in ANSI */
27962 \newline
27963 }
27964 \end_deeper
27965 \layout Itemize
27966
27967 initialization of structure arrays must be fully braced.
27968 \begin_deeper
27969 \layout Verse
27970
27971
27972 \family typewriter
27973 struct s { char x } a[] = {1, 2}; /* invalid in SDCC */
27974 \newline
27975 struct s { char x } a[] = {{1}, {2}}; /* OK */
27976 \end_deeper
27977 \layout Itemize
27978
27979 'long long
27980 \begin_inset LatexCommand \index{long long (not supported)}
27981
27982 \end_inset
27983
27984 ' (64 bit integers
27985 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
27986
27987 \end_inset
27988
27989 ) not supported.
27990 \layout Itemize
27991
27992 'double
27993 \begin_inset LatexCommand \index{double (not supported)}
27994
27995 \end_inset
27996
27997 ' precision floating point
27998 \begin_inset LatexCommand \index{Floating point support}
27999
28000 \end_inset
28001
28002 not supported.
28003 \layout Itemize
28004
28005 Old K&R style
28006 \begin_inset LatexCommand \index{K\&R style}
28007
28008 \end_inset
28009
28010  function declarations are NOT allowed.
28011 \begin_deeper
28012 \layout Verse
28013
28014
28015 \family typewriter
28016 foo(i,j) /* this old style of function declarations */
28017 \newline
28018 int i,j; /* are valid in ANSI but not valid in SDCC */
28019 \newline
28020 {
28021 \newline
28022 \SpecialChar ~
28023 \SpecialChar ~
28024 \SpecialChar ~
28025 \SpecialChar ~
28026 ...
28027
28028 \newline
28029 }
28030 \end_deeper
28031 \layout Itemize
28032
28033 Most enhancements in C99 are not supported, f.e.:
28034 \begin_deeper
28035 \layout Verse
28036
28037
28038 \family typewriter
28039 \series bold
28040 inline
28041 \series default
28042  int increment (int a) { return a+1; } /* is invalid in SDCC although allowed
28043  in C99 */
28044 \newline
28045 for (
28046 \series bold
28047 int
28048 \series default
28049  i=0; i<10; i++) /* is invalid in SDCC although allowed in C99 */
28050 \end_deeper
28051 \layout Itemize
28052
28053 Certain words that are valid identifiers in the standard may be reserved
28054  words in SDCC unless the
28055 \series bold
28056 -
28057 \begin_inset ERT
28058 status Collapsed
28059
28060 \layout Standard
28061
28062 \backslash
28063 /
28064 \end_inset
28065
28066 -std-c89
28067 \begin_inset LatexCommand \index{-\/-std-c89}
28068
28069 \end_inset
28070
28071  or -
28072 \begin_inset ERT
28073 status Collapsed
28074
28075 \layout Standard
28076
28077 \backslash
28078 /
28079 \end_inset
28080
28081 -std-c99
28082 \begin_inset LatexCommand \index{-\/-std-c99}
28083
28084 \end_inset
28085
28086
28087 \series default
28088  command line options are used.
28089  These may include (depending on the selected processor): 'at', 'banked',
28090  'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup
28091 t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs',
28092  'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and
28093  '_naked'.
28094  Compliant equivalents of these keywords are always available in a form
28095  that begin with two underscores
28096 \begin_inset LatexCommand \index{\_\_ (prefix for extended keywords)}
28097
28098 \end_inset
28099
28100 , f.e.
28101  '__data' instead of 'data'.
28102 \layout Section
28103
28104 Cyclomatic Complexity
28105 \begin_inset LatexCommand \index{Cyclomatic complexity}
28106
28107 \end_inset
28108
28109
28110 \layout Standard
28111
28112 Cyclomatic complexity of a function is defined as the number of independent
28113  paths the program can take during execution of the function.
28114  This is an important number since it defines the number test cases you
28115  have to generate to validate the function.
28116  The accepted industry standard for complexity number is 10, if the cyclomatic
28117  complexity reported by SDCC exceeds 10 you should think about simplification
28118  of the function logic.
28119  Note that the complexity level is not related to the number of lines of
28120  code in a function.
28121  Large functions can have low complexity, and small functions can have large
28122  complexity levels.
28123
28124 \newline
28125
28126 \newline
28127 SDCC uses the following formula to compute the complexity:
28128 \newline
28129
28130 \layout Standard
28131
28132 complexity = (number of edges in control flow graph) - (number of nodes
28133  in control flow graph) + 2;
28134 \newline
28135
28136 \newline
28137 Having said that the industry standard is 10, you should be aware that in
28138  some cases it be may unavoidable to have a complexity level of less than
28139  10.
28140  For example if you have switch statement with more than 10 case labels,
28141  each case label adds one to the complexity level.
28142  The complexity level is by no means an absolute measure of the algorithmic
28143  complexity of the function, it does however provide a good starting point
28144  for which functions you might look at for further optimization.
28145 \layout Section
28146
28147 Retargetting for other Processors
28148 \layout Standard
28149
28150 The issues for retargetting the compiler are far too numerous to be covered
28151  by this document.
28152  What follows is a brief description of each of the seven phases of the
28153  compiler and its MCU dependency.
28154 \layout Itemize
28155
28156 Parsing the source and building the annotated parse tree.
28157  This phase is largely MCU independent (except for the language extensions).
28158  Syntax & semantic checks are also done in this phase, along with some initial
28159  optimizations like back patching labels and the pattern matching optimizations
28160  like bit-rotation etc.
28161 \layout Itemize
28162
28163 The second phase involves generating an intermediate code which can be easy
28164  manipulated during the later phases.
28165  This phase is entirely MCU independent.
28166  The intermediate code generation assumes the target machine has unlimited
28167  number of registers, and designates them with the name iTemp.
28168  The compiler can be made to dump a human readable form of the code generated
28169  by using the -
28170 \begin_inset ERT
28171 status Collapsed
28172
28173 \layout Standard
28174
28175 \backslash
28176 /
28177 \end_inset
28178
28179 -dumpraw option.
28180 \layout Itemize
28181
28182 This phase does the bulk of the standard optimizations and is also MCU independe
28183 nt.
28184  This phase can be broken down into several sub-phases:
28185 \newline
28186
28187 \newline
28188 Break down intermediate code (iCode) into basic blocks.
28189 \newline
28190 Do control flow & data flow analysis on the basic blocks.
28191 \newline
28192 Do local common subexpression elimination, then global subexpression elimination
28193 \newline
28194 Dead code elimination
28195 \newline
28196 Loop optimizations
28197 \newline
28198 If loop optimizations caused any changes then do 'global subexpression eliminati
28199 on' and 'dead code elimination' again.
28200 \layout Itemize
28201
28202 This phase determines the live-ranges; by live range I mean those iTemp
28203  variables defined by the compiler that still survive after all the optimization
28204 s.
28205  Live range analysis
28206 \begin_inset LatexCommand \index{Live range analysis}
28207
28208 \end_inset
28209
28210  is essential for register allocation, since these computation determines
28211  which of these iTemps will be assigned to registers, and for how long.
28212 \layout Itemize
28213
28214 Phase five is register allocation.
28215  There are two parts to this process.
28216 \newline
28217
28218 \newline
28219 The first part I call 'register packing' (for lack of a better term).
28220  In this case several MCU specific expression folding is done to reduce
28221  register pressure.
28222 \newline
28223
28224 \newline
28225 The second part is more MCU independent and deals with allocating registers
28226  to the remaining live ranges.
28227  A lot of MCU specific code does creep into this phase because of the limited
28228  number of index registers available in the 8051.
28229 \layout Itemize
28230
28231 The Code generation phase is (unhappily), entirely MCU dependent and very
28232  little (if any at all) of this code can be reused for other MCU.
28233  However the scheme for allocating a homogenized assembler operand for each
28234  iCode operand may be reused.
28235 \layout Itemize
28236
28237 As mentioned in the optimization section the peep-hole optimizer is rule
28238  based system, which can reprogrammed for other MCUs.
28239 \layout Chapter
28240
28241 Compiler internals
28242 \begin_inset LatexCommand \index{Compiler internals}
28243
28244 \end_inset
28245
28246
28247 \layout Section
28248
28249 The anatomy of the compiler
28250 \begin_inset LatexCommand \label{sub:The-anatomy-of}
28251
28252 \end_inset
28253
28254
28255 \layout Standard
28256
28257
28258 \shape italic
28259 This is an excerpt from an article published in Circuit Cellar Magazine
28260  in
28261 \series bold
28262 August 2000
28263 \series default
28264 .
28265  It's a little outdated (the compiler is much more efficient now and user/develo
28266 per friendly), but pretty well exposes the guts of it all.
28267 \shape default
28268
28269 \newline
28270
28271 \newline
28272 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
28273  It is fairly easy to retarget for other 8-bit MCU.
28274  Here we take a look at some of the internals of the compiler.
28275
28276 \layout Paragraph*
28277
28278 Parsing
28279 \begin_inset LatexCommand \index{Parsing}
28280
28281 \end_inset
28282
28283
28284 \layout Standard
28285
28286 Parsing the input source file and creating an AST (Annotated Syntax Tree
28287 \begin_inset LatexCommand \index{Annotated syntax tree}
28288
28289 \end_inset
28290
28291 ).
28292  This phase also involves propagating types (annotating each node of the
28293  parse tree with type information) and semantic analysis.
28294  There are some MCU specific parsing rules.
28295  For example the storage classes, the extended storage classes are MCU specific
28296  while there may be a xdata storage class for 8051 there is no such storage
28297  class for z80 or Atmel AVR.
28298  SDCC allows MCU specific storage class extensions, i.e.
28299  xdata will be treated as a storage class specifier when parsing 8051 C
28300  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
28301  C code.
28302 \layout Paragraph*
28303
28304 Generating iCode
28305 \begin_inset LatexCommand \index{iCode}
28306
28307 \end_inset
28308
28309
28310 \layout Standard
28311
28312 Intermediate code generation.
28313  In this phase the AST is broken down into three-operand form (iCode).
28314  These three operand forms are represented as doubly linked lists.
28315  ICode is the term given to the intermediate form generated by the compiler.
28316  ICode example section shows some examples of iCode generated for some simple
28317  C source functions.
28318 \layout Paragraph*
28319
28320 Optimizations
28321 \begin_inset LatexCommand \index{Optimizations}
28322
28323 \end_inset
28324
28325 .
28326 \layout Standard
28327
28328 Bulk of the target independent optimizations is performed in this phase.
28329  The optimizations include constant propagation, common sub-expression eliminati
28330 on, loop invariant code movement, strength reduction of loop induction variables
28331  and dead-code elimination.
28332 \layout Paragraph*
28333
28334 Live range analysis
28335 \begin_inset LatexCommand \index{Live range analysis}
28336
28337 \end_inset
28338
28339
28340 \layout Standard
28341
28342 During intermediate code generation phase, the compiler assumes the target
28343  machine has infinite number of registers and generates a lot of temporary
28344  variables.
28345  The live range computation determines the lifetime of each of these compiler-ge
28346 nerated temporaries.
28347  A picture speaks a thousand words.
28348  ICode example sections show the live range annotations for each of the
28349  operand.
28350  It is important to note here, each iCode is assigned a number in the order
28351  of its execution in the function.
28352  The live ranges are computed in terms of these numbers.
28353  The from number is the number of the iCode which first defines the operand
28354  and the to number signifies the iCode which uses this operand last.
28355 \layout Paragraph*
28356
28357 Register Allocation
28358 \begin_inset LatexCommand \index{Register allocation}
28359
28360 \end_inset
28361
28362
28363 \layout Standard
28364
28365 The register allocation determines the type and number of registers needed
28366  by each operand.
28367  In most MCUs only a few registers can be used for indirect addressing.
28368  In case of 8051 for example the registers R0 & R1 can be used to indirectly
28369  address the internal ram and DPTR to indirectly address the external ram.
28370  The compiler will try to allocate the appropriate register to pointer variables
28371  if it can.
28372  ICode example section shows the operands annotated with the registers assigned
28373  to them.
28374  The compiler will try to keep operands in registers as much as possible;
28375  there are several schemes the compiler uses to do achieve this.
28376  When the compiler runs out of registers the compiler will check to see
28377  if there are any live operands which is not used or defined in the current
28378  basic block being processed, if there are any found then it will push that
28379  operand and use the registers in this block, the operand will then be popped
28380  at the end of the basic block.
28381
28382 \layout Standard
28383
28384 There are other MCU specific considerations in this phase.
28385  Some MCUs have an accumulator; very short-lived operands could be assigned
28386  to the accumulator instead of a general-purpose register.
28387 \layout Paragraph*
28388
28389 Code generation
28390 \layout Standard
28391
28392 Figure II gives a table of iCode operations supported by the compiler.
28393  The code generation involves translating these operations into corresponding
28394  assembly code for the processor.
28395  This sounds overly simple but that is the essence of code generation.
28396  Some of the iCode operations are generated on a MCU specific manner for
28397  example, the z80 port does not use registers to pass parameters so the
28398  SEND and RECV iCode operations will not be generated, and it also does
28399  not support JUMPTABLES.
28400
28401 \newline
28402
28403 \series bold
28404 \shape italic
28405 \color red
28406 <Where is Figure II?>
28407 \layout Comment
28408
28409 In the original article Figure II was announced to be downloadable on
28410 \shape italic
28411 Circuit Cellar
28412 \shape default
28413 's web site.
28414  Unfortunately it never seemed to have shown up there, so: where is Figure
28415  II?
28416 \layout Paragraph*
28417
28418 ICode Example
28419 \begin_inset LatexCommand \index{iCode}
28420
28421 \end_inset
28422
28423
28424 \layout Standard
28425
28426 This section shows some details of iCode.
28427  The example C code does not do anything useful; it is used as an example
28428  to illustrate the intermediate code generated by the compiler.
28429 \layout Verse
28430
28431
28432 \family typewriter
28433 1.\SpecialChar ~
28434 xdata int * p;
28435 \newline
28436 2.\SpecialChar ~
28437 int gint;
28438 \newline
28439 3.\SpecialChar ~
28440 /* This function does nothing useful.
28441  It is used
28442 \newline
28443 4.\SpecialChar ~
28444 \SpecialChar ~
28445 \SpecialChar ~
28446 \SpecialChar ~
28447 for the purpose of explaining iCode */
28448 \newline
28449 5.\SpecialChar ~
28450 short function (data int *x)
28451 \newline
28452 6.\SpecialChar ~
28453 {
28454 \newline
28455 7.\SpecialChar ~
28456 \SpecialChar ~
28457 \SpecialChar ~
28458 short i=10; \SpecialChar ~
28459 \SpecialChar ~
28460 /* dead initialization eliminated */
28461 \newline
28462 8.\SpecialChar ~
28463 \SpecialChar ~
28464 \SpecialChar ~
28465 short sum=10; /* dead initialization eliminated */
28466 \newline
28467 9.\SpecialChar ~
28468 \SpecialChar ~
28469 \SpecialChar ~
28470 short mul;
28471 \newline
28472 10.\SpecialChar ~
28473 \SpecialChar ~
28474 int j ;
28475 \newline
28476 11.\SpecialChar ~
28477 \SpecialChar ~
28478 while (*x) *x++ = *p++;
28479 \newline
28480 12.\SpecialChar ~
28481 \SpecialChar ~
28482 \SpecialChar ~
28483 \SpecialChar ~
28484 sum = 0 ;
28485 \newline
28486 13.\SpecialChar ~
28487 \SpecialChar ~
28488 mul = 0;
28489 \newline
28490 14.\SpecialChar ~
28491 \SpecialChar ~
28492 /* compiler detects i,j to be induction variables */
28493 \newline
28494 15.\SpecialChar ~
28495 \SpecialChar ~
28496 for (i = 0, j = 10 ; i < 10 ; i++, j
28497 \family default
28498 -
28499 \begin_inset ERT
28500 status Collapsed
28501
28502 \layout Standard
28503
28504 \backslash
28505 /
28506 \end_inset
28507
28508 -
28509 \family typewriter
28510 ) {
28511 \newline
28512 16.\SpecialChar ~
28513 \SpecialChar ~
28514 \SpecialChar ~
28515 \SpecialChar ~
28516 sum += i;
28517 \newline
28518 17.\SpecialChar ~
28519 \SpecialChar ~
28520 \SpecialChar ~
28521 \SpecialChar ~
28522 mul += i * 3; \SpecialChar ~
28523 \SpecialChar ~
28524 /* this multiplication remains */
28525 \newline
28526 18.\SpecialChar ~
28527 \SpecialChar ~
28528 \SpecialChar ~
28529 \SpecialChar ~
28530 gint += j * 3;\SpecialChar ~
28531 \SpecialChar ~
28532 /* this multiplication changed to addition */
28533 \newline
28534 19.\SpecialChar ~
28535 \SpecialChar ~
28536 }
28537 \newline
28538 20.\SpecialChar ~
28539 \SpecialChar ~
28540 return sum+mul;
28541 \newline
28542 21.\SpecialChar ~
28543 }
28544 \layout Standard
28545
28546 In addition to the operands each iCode contains information about the filename
28547  and line it corresponds to in the source file.
28548  The first field in the listing should be interpreted as follows:
28549 \newline
28550
28551 \shape italic
28552 \size footnotesize
28553 Filename(linenumber: iCode Execution sequence number : ICode hash table
28554  key : loop depth of the iCode).
28555 \shape default
28556 \size default
28557
28558 \newline
28559 Then follows the human readable form of the ICode operation.
28560  Each operand of this triplet form can be of three basic types a) compiler
28561  generated temporary b) user defined variable c) a constant value.
28562  Note that local variables and parameters are replaced by compiler generated
28563  temporaries.
28564  Live ranges
28565 \begin_inset LatexCommand \index{Live range analysis}
28566
28567 \end_inset
28568
28569  are computed only for temporaries (i.e.
28570  live ranges are not computed for global variables).
28571  Registers
28572 \begin_inset LatexCommand \index{Register allocation}
28573
28574 \end_inset
28575
28576  are allocated for temporaries only.
28577  Operands are formatted in the following manner:
28578 \newline
28579
28580 \shape italic
28581 \size footnotesize
28582 Operand Name [lr live-from : live-to ] { type information } [ registers
28583  allocated ].
28584 \shape default
28585 \size default
28586
28587 \newline
28588 As mentioned earlier the live ranges are computed in terms of the execution
28589  sequence number of the iCodes, for example
28590 \newline
28591 the iTemp0 is live from (i.e.
28592  first defined in iCode with execution sequence number 3, and is last used
28593  in the iCode with sequence number 5).
28594  For induction variables such as iTemp21 the live range computation extends
28595  the lifetime from the start to the end of the loop.
28596 \newline
28597 The register allocator used the live range information to allocate registers,
28598  the same registers may be used for different temporaries if their live
28599  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
28600  iTemp17 since their live ranges do not overlap.
28601  In addition the allocator also takes into consideration the type and usage
28602  of a temporary, for example itemp6 is a pointer to near space and is used
28603  as to fetch data from (i.e.
28604  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
28605  Some short lived temporaries are allocated to special registers which have
28606  meaning to the code generator e.g.
28607  iTemp13 is allocated to a pseudo register CC which tells the back end that
28608  the temporary is used only for a conditional jump the code generation makes
28609  use of this information to optimize a compare and jump ICode.
28610 \newline
28611 There are several loop optimizations
28612 \begin_inset LatexCommand \index{Loop optimization}
28613
28614 \end_inset
28615
28616  performed by the compiler.
28617  It can detect induction variables iTemp21(i) and iTemp23(j).
28618  Also note the compiler does selective strength reduction
28619 \begin_inset LatexCommand \index{Strength reduction}
28620
28621 \end_inset
28622
28623 , i.e.
28624  the multiplication of an induction variable in line 18 (gint = j * 3) is
28625  changed to addition, a new temporary iTemp17 is allocated and assigned
28626  a initial value, a constant 3 is then added for each iteration of the loop.
28627  The compiler does not change the multiplication
28628 \begin_inset LatexCommand \index{Multiplication}
28629
28630 \end_inset
28631
28632  in line 17 however since the processor does support an 8 * 8 bit multiplication.
28633 \newline
28634 Note the dead code elimination
28635 \begin_inset LatexCommand \index{Dead-code elimination}
28636
28637 \end_inset
28638
28639  optimization eliminated the dead assignments in line 7 & 8 to I and sum
28640  respectively.
28641 \newline
28642
28643 \layout Standard
28644
28645
28646 \size footnotesize
28647 Sample.c (5:1:0:0) _entry($9) :
28648 \layout Standard
28649
28650
28651 \size footnotesize
28652 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
28653 \layout Standard
28654
28655
28656 \size footnotesize
28657 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
28658 \layout Standard
28659
28660
28661 \size footnotesize
28662 Sample.c(11:4:53:0) preHeaderLbl0($11) :
28663 \layout Standard
28664
28665
28666 \size footnotesize
28667 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
28668  * int}[r2]
28669 \layout Standard
28670
28671
28672 \size footnotesize
28673 Sample.c(11:6:5:1) _whilecontinue_0($1) :
28674 \layout Standard
28675
28676
28677 \size footnotesize
28678 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
28679  int}[r0]]
28680 \layout Standard
28681
28682
28683 \size footnotesize
28684 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
28685 \layout Standard
28686
28687
28688 \size footnotesize
28689 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
28690  * int}
28691 \layout Standard
28692
28693
28694 \size footnotesize
28695 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
28696  {short}
28697 \layout Standard
28698
28699
28700 \size footnotesize
28701 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
28702  * int}[DPTR]]
28703 \layout Standard
28704
28705
28706 \size footnotesize
28707 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
28708 }[r2 r3]
28709 \layout Standard
28710
28711
28712 \size footnotesize
28713 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
28714  * int}[r0] + 0x2 {short}
28715 \layout Standard
28716
28717
28718 \size footnotesize
28719 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
28720 \layout Standard
28721
28722
28723 \size footnotesize
28724 Sample.c(11:17:21:0)_whilebreak_0($3) :
28725 \layout Standard
28726
28727
28728 \size footnotesize
28729 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
28730 \layout Standard
28731
28732
28733 \size footnotesize
28734 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
28735 \layout Standard
28736
28737
28738 \size footnotesize
28739 Sample.c(15:20:54:0)preHeaderLbl1($13) :
28740 \layout Standard
28741
28742
28743 \size footnotesize
28744 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
28745 \layout Standard
28746
28747
28748 \size footnotesize
28749 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
28750 \layout Standard
28751
28752
28753 \size footnotesize
28754 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
28755 \layout Standard
28756
28757
28758 \size footnotesize
28759 Sample.c(15:24:26:1)_forcond_0($4) :
28760 \layout Standard
28761
28762
28763 \size footnotesize
28764 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
28765  < 0xa {short}
28766 \layout Standard
28767
28768
28769 \size footnotesize
28770 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
28771 \layout Standard
28772
28773
28774 \size footnotesize
28775 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
28776  + ITemp21 [lr21:38]{short}[r4]
28777 \layout Standard
28778
28779
28780 \size footnotesize
28781 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
28782  * 0x3 {short}
28783 \layout Standard
28784
28785
28786 \size footnotesize
28787 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
28788  + iTemp15 [lr29:30]{short}[r1]
28789 \layout Standard
28790
28791
28792 \size footnotesize
28793 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
28794  r0]- 0x3 {short}
28795 \layout Standard
28796
28797
28798 \size footnotesize
28799 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
28800 int}[r7 r0]
28801 \layout Standard
28802
28803
28804 \size footnotesize
28805 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
28806  + 0x1 {short}
28807 \layout Standard
28808
28809
28810 \size footnotesize
28811 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
28812  r6]- 0x1 {short}
28813 \layout Standard
28814
28815
28816 \size footnotesize
28817 Sample.c(19:38:47:1) goto _forcond_0($4)
28818 \layout Standard
28819
28820
28821 \size footnotesize
28822 Sample.c(19:39:48:0)_forbreak_0($7) :
28823 \layout Standard
28824
28825
28826 \size footnotesize
28827 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
28828  + ITemp11 [lr19:40]{short}[r3]
28829 \layout Standard
28830
28831
28832 \size footnotesize
28833 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
28834 \layout Standard
28835
28836
28837 \size footnotesize
28838 Sample.c(20:42:51:0)_return($8) :
28839 \layout Standard
28840
28841
28842 \size footnotesize
28843 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
28844 \size default
28845
28846 \newline
28847
28848 \newline
28849 Finally the code generated for this function:
28850 \newline
28851
28852 \layout Standard
28853
28854
28855 \size footnotesize
28856 .area DSEG (DATA)
28857 \layout Standard
28858
28859
28860 \size footnotesize
28861 _p::
28862 \layout Standard
28863
28864
28865 \size footnotesize
28866 \SpecialChar ~
28867 \SpecialChar ~
28868 .ds 2
28869 \layout Standard
28870
28871
28872 \size footnotesize
28873 _gint::
28874 \layout Standard
28875
28876
28877 \size footnotesize
28878 \SpecialChar ~
28879 \SpecialChar ~
28880 .ds 2
28881 \layout Standard
28882
28883
28884 \size footnotesize
28885 ; sample.c 5
28886 \layout Standard
28887
28888
28889 \size footnotesize
28890 ; ----------------------------------------------
28891 \layout Standard
28892
28893
28894 \size footnotesize
28895 ; function function
28896 \layout Standard
28897
28898
28899 \size footnotesize
28900 ; ----------------------------------------------
28901 \layout Standard
28902
28903
28904 \size footnotesize
28905 _function:
28906 \layout Standard
28907
28908
28909 \size footnotesize
28910 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
28911 \layout Standard
28912
28913
28914 \size footnotesize
28915 \SpecialChar ~
28916 \SpecialChar ~
28917 mov r2,dpl
28918 \layout Standard
28919
28920
28921 \size footnotesize
28922 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
28923 \layout Standard
28924
28925
28926 \size footnotesize
28927 \SpecialChar ~
28928 \SpecialChar ~
28929 mov ar0,r2
28930 \layout Standard
28931
28932
28933 \size footnotesize
28934 ;_whilecontinue_0($1) :
28935 \layout Standard
28936
28937
28938 \size footnotesize
28939 00101$:
28940 \layout Standard
28941
28942
28943 \size footnotesize
28944 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
28945 \layout Standard
28946
28947
28948 \size footnotesize
28949 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
28950 \layout Standard
28951
28952
28953 \size footnotesize
28954 \SpecialChar ~
28955 \SpecialChar ~
28956 mov ar2,@r0
28957 \layout Standard
28958
28959
28960 \size footnotesize
28961 \SpecialChar ~
28962 \SpecialChar ~
28963 inc r0
28964 \layout Standard
28965
28966
28967 \size footnotesize
28968 \SpecialChar ~
28969 \SpecialChar ~
28970 mov ar3,@r0
28971 \layout Standard
28972
28973
28974 \size footnotesize
28975 \SpecialChar ~
28976 \SpecialChar ~
28977 dec r0
28978 \layout Standard
28979
28980
28981 \size footnotesize
28982 \SpecialChar ~
28983 \SpecialChar ~
28984 mov a,r2
28985 \layout Standard
28986
28987
28988 \size footnotesize
28989 \SpecialChar ~
28990 \SpecialChar ~
28991 orl a,r3
28992 \layout Standard
28993
28994
28995 \size footnotesize
28996 \SpecialChar ~
28997 \SpecialChar ~
28998 jz 00103$
28999 \layout Standard
29000
29001
29002 \size footnotesize
29003 00114$:
29004 \layout Standard
29005
29006
29007 \size footnotesize
29008 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
29009 \layout Standard
29010
29011
29012 \size footnotesize
29013 \SpecialChar ~
29014 \SpecialChar ~
29015 mov dpl,_p
29016 \layout Standard
29017
29018
29019 \size footnotesize
29020 \SpecialChar ~
29021 \SpecialChar ~
29022 mov dph,(_p + 1)
29023 \layout Standard
29024
29025
29026 \size footnotesize
29027 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
29028 \layout Standard
29029
29030
29031 \size footnotesize
29032 \SpecialChar ~
29033 \SpecialChar ~
29034 mov a,#0x02
29035 \layout Standard
29036
29037
29038 \size footnotesize
29039 \SpecialChar ~
29040 \SpecialChar ~
29041 add a,_p
29042 \layout Standard
29043
29044
29045 \size footnotesize
29046 \SpecialChar ~
29047 \SpecialChar ~
29048 mov _p,a
29049 \layout Standard
29050
29051
29052 \size footnotesize
29053 \SpecialChar ~
29054 \SpecialChar ~
29055 clr a
29056 \layout Standard
29057
29058
29059 \size footnotesize
29060 \SpecialChar ~
29061 \SpecialChar ~
29062 addc a,(_p + 1)
29063 \layout Standard
29064
29065
29066 \size footnotesize
29067 \SpecialChar ~
29068 \SpecialChar ~
29069 mov (_p + 1),a
29070 \layout Standard
29071
29072
29073 \size footnotesize
29074 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
29075 \layout Standard
29076
29077
29078 \size footnotesize
29079 \SpecialChar ~
29080 \SpecialChar ~
29081 movx a,@dptr
29082 \layout Standard
29083
29084
29085 \size footnotesize
29086 \SpecialChar ~
29087 \SpecialChar ~
29088 mov r2,a
29089 \layout Standard
29090
29091
29092 \size footnotesize
29093 \SpecialChar ~
29094 \SpecialChar ~
29095 inc dptr
29096 \layout Standard
29097
29098
29099 \size footnotesize
29100 \SpecialChar ~
29101 \SpecialChar ~
29102 movx a,@dptr
29103 \layout Standard
29104
29105
29106 \size footnotesize
29107 \SpecialChar ~
29108 \SpecialChar ~
29109 mov r3,a
29110 \layout Standard
29111
29112
29113 \size footnotesize
29114 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
29115 \layout Standard
29116
29117
29118 \size footnotesize
29119 \SpecialChar ~
29120 \SpecialChar ~
29121 mov @r0,ar2
29122 \layout Standard
29123
29124
29125 \size footnotesize
29126 \SpecialChar ~
29127 \SpecialChar ~
29128 inc r0
29129 \layout Standard
29130
29131
29132 \size footnotesize
29133 \SpecialChar ~
29134 \SpecialChar ~
29135 mov @r0,ar3
29136 \layout Standard
29137
29138
29139 \size footnotesize
29140 ; iTemp6 [lr5:16]{_near * int}[r0] =
29141 \layout Standard
29142
29143
29144 \size footnotesize
29145 ; iTemp6 [lr5:16]{_near * int}[r0] +
29146 \layout Standard
29147
29148
29149 \size footnotesize
29150 ; 0x2 {short}
29151 \layout Standard
29152
29153
29154 \size footnotesize
29155 \SpecialChar ~
29156 \SpecialChar ~
29157 inc r0
29158 \layout Standard
29159
29160
29161 \size footnotesize
29162 ; goto _whilecontinue_0($1)
29163 \layout Standard
29164
29165
29166 \size footnotesize
29167 \SpecialChar ~
29168 \SpecialChar ~
29169 sjmp 00101$
29170 \layout Standard
29171
29172
29173 \size footnotesize
29174 ; _whilebreak_0($3) :
29175 \layout Standard
29176
29177
29178 \size footnotesize
29179 00103$:
29180 \layout Standard
29181
29182
29183 \size footnotesize
29184 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
29185 \layout Standard
29186
29187
29188 \size footnotesize
29189 \SpecialChar ~
29190 \SpecialChar ~
29191 mov r2,#0x00
29192 \layout Standard
29193
29194
29195 \size footnotesize
29196 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
29197 \layout Standard
29198
29199
29200 \size footnotesize
29201 \SpecialChar ~
29202 \SpecialChar ~
29203 mov r3,#0x00
29204 \layout Standard
29205
29206
29207 \size footnotesize
29208 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
29209 \layout Standard
29210
29211
29212 \size footnotesize
29213 \SpecialChar ~
29214 \SpecialChar ~
29215 mov r4,#0x00
29216 \layout Standard
29217
29218
29219 \size footnotesize
29220 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
29221 \layout Standard
29222
29223
29224 \size footnotesize
29225 \SpecialChar ~
29226 \SpecialChar ~
29227 mov r5,#0x0A
29228 \layout Standard
29229
29230
29231 \size footnotesize
29232 \SpecialChar ~
29233 \SpecialChar ~
29234 mov r6,#0x00
29235 \layout Standard
29236
29237
29238 \size footnotesize
29239 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
29240 \layout Standard
29241
29242
29243 \size footnotesize
29244 \SpecialChar ~
29245 \SpecialChar ~
29246 mov r7,#0x1E
29247 \layout Standard
29248
29249
29250 \size footnotesize
29251 \SpecialChar ~
29252 \SpecialChar ~
29253 mov r0,#0x00
29254 \layout Standard
29255
29256
29257 \size footnotesize
29258 ; _forcond_0($4) :
29259 \layout Standard
29260
29261
29262 \size footnotesize
29263 00104$:
29264 \layout Standard
29265
29266
29267 \size footnotesize
29268 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
29269 \layout Standard
29270
29271
29272 \size footnotesize
29273 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
29274 \layout Standard
29275
29276
29277 \size footnotesize
29278 \SpecialChar ~
29279 \SpecialChar ~
29280 clr c
29281 \layout Standard
29282
29283
29284 \size footnotesize
29285 \SpecialChar ~
29286 \SpecialChar ~
29287 mov a,r4
29288 \layout Standard
29289
29290
29291 \size footnotesize
29292 \SpecialChar ~
29293 \SpecialChar ~
29294 xrl a,#0x80
29295 \layout Standard
29296
29297
29298 \size footnotesize
29299 \SpecialChar ~
29300 \SpecialChar ~
29301 subb a,#0x8a
29302 \layout Standard
29303
29304
29305 \size footnotesize
29306 \SpecialChar ~
29307 \SpecialChar ~
29308 jnc 00107$
29309 \layout Standard
29310
29311
29312 \size footnotesize
29313 00115$:
29314 \layout Standard
29315
29316
29317 \size footnotesize
29318 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
29319 \layout Standard
29320
29321
29322 \size footnotesize
29323 ; iTemp21 [lr21:38]{short}[r4]
29324 \layout Standard
29325
29326
29327 \size footnotesize
29328 \SpecialChar ~
29329 \SpecialChar ~
29330 mov a,r4
29331 \layout Standard
29332
29333
29334 \size footnotesize
29335 \SpecialChar ~
29336 \SpecialChar ~
29337 add a,r2
29338 \layout Standard
29339
29340
29341 \size footnotesize
29342 \SpecialChar ~
29343 \SpecialChar ~
29344 mov r2,a
29345 \layout Standard
29346
29347
29348 \size footnotesize
29349 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
29350 \layout Standard
29351
29352
29353 \size footnotesize
29354 \SpecialChar ~
29355 \SpecialChar ~
29356 mov b,#0x03
29357 \layout Standard
29358
29359
29360 \size footnotesize
29361 \SpecialChar ~
29362 \SpecialChar ~
29363 mov a,r4
29364 \layout Standard
29365
29366
29367 \size footnotesize
29368 \SpecialChar ~
29369 \SpecialChar ~
29370 mul ab
29371 \layout Standard
29372
29373
29374 \size footnotesize
29375 \SpecialChar ~
29376 \SpecialChar ~
29377 mov r1,a
29378 \layout Standard
29379
29380
29381 \size footnotesize
29382 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
29383 \layout Standard
29384
29385
29386 \size footnotesize
29387 ; iTemp15 [lr29:30]{short}[r1]
29388 \layout Standard
29389
29390
29391 \size footnotesize
29392 \SpecialChar ~
29393 \SpecialChar ~
29394 add a,r3
29395 \layout Standard
29396
29397
29398 \size footnotesize
29399 \SpecialChar ~
29400 \SpecialChar ~
29401 mov r3,a
29402 \layout Standard
29403
29404
29405 \size footnotesize
29406 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
29407 \layout Standard
29408
29409
29410 \size footnotesize
29411 \SpecialChar ~
29412 \SpecialChar ~
29413 mov a,r7
29414 \layout Standard
29415
29416
29417 \size footnotesize
29418 \SpecialChar ~
29419 \SpecialChar ~
29420 add a,#0xfd
29421 \layout Standard
29422
29423
29424 \size footnotesize
29425 \SpecialChar ~
29426 \SpecialChar ~
29427 mov r7,a
29428 \layout Standard
29429
29430
29431 \size footnotesize
29432 \SpecialChar ~
29433 \SpecialChar ~
29434 mov a,r0
29435 \layout Standard
29436
29437
29438 \size footnotesize
29439 \SpecialChar ~
29440 \SpecialChar ~
29441 addc a,#0xff
29442 \layout Standard
29443
29444
29445 \size footnotesize
29446 \SpecialChar ~
29447 \SpecialChar ~
29448 mov r0,a
29449 \layout Standard
29450
29451
29452 \size footnotesize
29453 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
29454 \layout Standard
29455
29456
29457 \size footnotesize
29458 \SpecialChar ~
29459 \SpecialChar ~
29460 mov a,r7
29461 \layout Standard
29462
29463
29464 \size footnotesize
29465 \SpecialChar ~
29466 \SpecialChar ~
29467 add a,_gint
29468 \layout Standard
29469
29470
29471 \size footnotesize
29472 \SpecialChar ~
29473 \SpecialChar ~
29474 mov _gint,a
29475 \layout Standard
29476
29477
29478 \size footnotesize
29479 \SpecialChar ~
29480 \SpecialChar ~
29481 mov a,r0
29482 \layout Standard
29483
29484
29485 \size footnotesize
29486 \SpecialChar ~
29487 \SpecialChar ~
29488 addc a,(_gint + 1)
29489 \layout Standard
29490
29491
29492 \size footnotesize
29493 \SpecialChar ~
29494 \SpecialChar ~
29495 mov (_gint + 1),a
29496 \layout Standard
29497
29498
29499 \size footnotesize
29500 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
29501 \layout Standard
29502
29503
29504 \size footnotesize
29505 \SpecialChar ~
29506 \SpecialChar ~
29507 inc r4
29508 \layout Standard
29509
29510
29511 \size footnotesize
29512 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
29513 \layout Standard
29514
29515
29516 \size footnotesize
29517 \SpecialChar ~
29518 \SpecialChar ~
29519 dec r5
29520 \layout Standard
29521
29522
29523 \size footnotesize
29524 \SpecialChar ~
29525 \SpecialChar ~
29526 cjne r5,#0xff,00104$
29527 \layout Standard
29528
29529
29530 \size footnotesize
29531 \SpecialChar ~
29532 \SpecialChar ~
29533 dec r6
29534 \layout Standard
29535
29536
29537 \size footnotesize
29538 ; goto _forcond_0($4)
29539 \layout Standard
29540
29541
29542 \size footnotesize
29543 \SpecialChar ~
29544 \SpecialChar ~
29545 sjmp 00104$
29546 \layout Standard
29547
29548
29549 \size footnotesize
29550 ; _forbreak_0($7) :
29551 \layout Standard
29552
29553
29554 \size footnotesize
29555 00107$:
29556 \layout Standard
29557
29558
29559 \size footnotesize
29560 ; ret iTemp24 [lr40:41]{short}
29561 \layout Standard
29562
29563
29564 \size footnotesize
29565 \SpecialChar ~
29566 \SpecialChar ~
29567 mov a,r3
29568 \layout Standard
29569
29570
29571 \size footnotesize
29572 \SpecialChar ~
29573 \SpecialChar ~
29574 add a,r2
29575 \layout Standard
29576
29577
29578 \size footnotesize
29579 \SpecialChar ~
29580 \SpecialChar ~
29581 mov dpl,a
29582 \layout Standard
29583
29584
29585 \size footnotesize
29586 ; _return($8) :
29587 \layout Standard
29588
29589
29590 \size footnotesize
29591 00108$:
29592 \layout Standard
29593
29594
29595 \size footnotesize
29596 \SpecialChar ~
29597 \SpecialChar ~
29598 ret
29599 \newline
29600
29601 \layout Section
29602
29603 A few words about basic block successors, predecessors and dominators
29604 \layout Standard
29605
29606 Successors are basic blocks
29607 \begin_inset LatexCommand \index{Basic blocks}
29608
29609 \end_inset
29610
29611  that might execute after this basic block.
29612 \newline
29613 Predecessors are basic blocks that might execute before reaching this basic
29614  block.
29615 \newline
29616 Dominators are basic blocks that WILL execute before reaching this basic
29617  block.
29618 \newline
29619
29620 \layout Standard
29621
29622 [basic block 1]
29623 \layout Standard
29624
29625 if (something)
29626 \layout Standard
29627
29628 \SpecialChar ~
29629 \SpecialChar ~
29630 \SpecialChar ~
29631 \SpecialChar ~
29632 [basic block 2]
29633 \layout Standard
29634
29635 else
29636 \layout Standard
29637
29638 \SpecialChar ~
29639 \SpecialChar ~
29640 \SpecialChar ~
29641 \SpecialChar ~
29642 [basic block 3]
29643 \layout Standard
29644
29645 [basic block 4]
29646 \newline
29647
29648 \layout Standard
29649
29650 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
29651 \layout Standard
29652
29653 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
29654 \layout Standard
29655
29656 c) domVect of [BB4] = BB1 ...
29657  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
29658  was executed.
29659 \layout Chapter
29660
29661 Acknowledgments
29662 \layout Standard
29663
29664
29665 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
29666
29667 \end_inset
29668
29669
29670 \newline
29671
29672 \newline
29673
29674 \emph on
29675 Thanks to all the other volunteer developers who have helped with coding,
29676  testing, web-page creation, distribution sets, etc.
29677  You know who you are :-)
29678 \emph default
29679
29680 \newline
29681
29682 \layout Standard
29683
29684 This document was initially written by Sandeep Dutta
29685 \layout Standard
29686
29687 All product names mentioned herein may be trademarks
29688 \begin_inset LatexCommand \index{Trademarks}
29689
29690 \end_inset
29691
29692  of their respective companies.
29693
29694 \layout Section*
29695
29696 Alphabetical index
29697 \layout Standard
29698
29699 To avoid confusion, the installation and building options for SDCC itself
29700  (chapter 2) are not part of the index.
29701 \layout Standard
29702
29703
29704 \begin_inset LatexCommand \printindex{}
29705
29706 \end_inset
29707
29708
29709 \the_end