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 assembler CPU DS390                 embedded development free Floating Point Arithmetic Freescale GPL HC08 inline Intel ISO/IEC 9899:1990 Linux MAC OS X manual Maxim mcs51 Microchip microcontroller open source PIC Unix Windows 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.2
  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="block" valignment="top" leftline="true" rightline="true" width="20text%">
 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.295
 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 1.175494351E-38,
 506 \family roman
 507 \series medium
 508 \shape up
 509 \size normal
 510 \emph off
 511 \bar no
 512 \noun off
 513 \color none
 514 3.402823466E+38
 515 \end_inset
 516 </cell>
 517 </row>
 518 <row topline="true" bottomline="true">
 519 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 520 \begin_inset Text
 521
 522 \layout Standard
 523
 524 pointer
 525 \end_inset
 526 </cell>
 527 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 528 \begin_inset Text
 529
 530 \layout Standard
 531
 532 1, 2, 3 or 4 bytes
 533 \end_inset
 534 </cell>
 535 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 536 \begin_inset Text
 537
 538 \layout Standard
 539
 540 generic
 541 \end_inset
 542 </cell>
 543 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 544 \begin_inset Text
 545
 546 \layout Standard
 547
 548 \end_inset
 549 </cell>
 550 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 551 \begin_inset Text
 552
 553 \layout Standard
 554
 555 \end_inset
 556 </cell>
 557 </row>
 558 </lyxtabular>
 559
 560 \end_inset
 561
 562
 563 \newline
 564 The compiler also allows
 565 \emph on
 566 inline assembler code
 567 \emph default
 568  to be embedded anywhere in a function.
 569  In addition, routines developed in assembly can also be called.
 570 \newline
 571
 572 \newline
 573 SDCC also provides an option (-
 574 \begin_inset ERT
 575 status Collapsed
 576
 577 \layout Standard
 578
 579 \backslash
 580 /
 581 \end_inset
 582
 583 -cyclomatic) to report the relative complexity of a function.
 584  These functions can then be further optimized, or hand coded in assembly
 585  if needed.
 586
 587 \newline
 588
 589 \newline
 590 SDCC also comes with a companion source level debugger SDCDB, the debugger
 591  currently uses ucSim a freeware simulator for 8051 and other micro-controllers.<
 592 \newline
 593
 594 \newline
 595 The latest version can be downloaded from
 596 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
 597
 598 \end_inset
 599
 600 .
 601
 602 \series bold
 603
 604 \series default
 605 \emph on
 606 Please note: the compiler will probably always be some steps ahead of this
 607  documentation
 608 \series bold
 609 \emph default
 610
 611 \begin_inset LatexCommand \index{Status of documentation}
 612
 613 \end_inset
 614
 615
 616 \begin_inset Foot
 617 collapsed false
 618
 619 \layout Standard
 620
 621 Obviously this has pros and cons
 622 \end_inset
 623
 624 .
 625 \layout Section
 626
 627 Open Source
 628 \layout Standard
 629
 630 All packages used in this compiler system are
 631 \emph on
 632 open source
 633 \emph default
 634  and
 635 \emph on
 636 freeware
 637 \emph default
 638 ; source code for all the sub-packages (pre-processor, assemblers, linkers
 639  etc) is distributed with the package.
 640  This documentation is maintained using a freeware word processor (LyX).
 641 \newline
 642 This program is free software; you can redistribute it and/or modify it
 643  under the terms of the GNU General Public License
 644 \begin_inset LatexCommand \index{GNU General Public License, GPL}
 645
 646 \end_inset
 647
 648  as published by the Free Software Foundation; either version 2, or (at
 649  your option) any later version.
 650  This program is distributed in the hope that it will be useful, but WITHOUT
 651  ANY WARRANTY; without even the implied warranty
 652 \begin_inset LatexCommand \index{warranty}
 653
 654 \end_inset
 655
 656  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 657  See the GNU General Public License for more details.
 658  You should have received a copy of the GNU General Public License along
 659  with this program; if not, write to the Free Software Foundation, 59 Temple
 660  Place - Suite 330, Boston, MA 02111-1307, USA.
 661  In other words, you are welcome to use, share and improve this program.
 662  You are forbidden to forbid anyone else to use, share and improve what
 663  you give them.
 664  Help stamp out software-hoarding!
 665 \layout Section
 666
 667 Typographic conventions
 668 \begin_inset LatexCommand \index{Typographic conventions}
 669
 670 \end_inset
 671
 672
 673 \layout Standard
 674
 675 Throughout this manual, we will use the following convention.
 676  Commands you have to type in are printed in
 677 \family sans
 678 \series bold
 679 "sans serif"
 680 \series default
 681 .
 682
 683 \family default
 684  Code samples are printed in
 685 \family typewriter
 686 typewriter font.
 687
 688 \family default
 689  Interesting items and new terms are printed in
 690 \emph on
 691 italic.
 692 \layout Section
 693
 694 Compatibility
 695 \begin_inset LatexCommand \label{sec:Compatibility-with-previous}
 696
 697 \end_inset
 698
 699  with previous versions
 700 \begin_inset LatexCommand \index{Compatibility with previous versions}
 701
 702 \end_inset
 703
 704
 705 \layout Standard
 706
 707 This version has numerous bug fixes compared with the previous version.
 708  But we also introduced some incompatibilities with older versions.
 709  Not just for the fun of it, but to make the compiler more stable, efficient
 710  and ANSI compliant
 711 \begin_inset LatexCommand \index{ANSI-compliance}
 712
 713 \end_inset
 714
 715  (see section
 716 \begin_inset LatexCommand \ref{sub:ANSI-Compliance}
 717
 718 \end_inset
 719
 720  for ANSI-Compliance).
 721
 722 \newline
 723
 724 \layout Itemize
 725
 726 short is now equivalent to int (16 bits), it used to be equivalent to char
 727  (8 bits) which is not ANSI compliant.
 728 \layout Itemize
 729
 730 the default directory for gcc-builds where include, library and documentation
 731  files are stored is now in /usr/local/share.
 732 \layout Itemize
 733
 734 char type parameters to vararg
 735 \begin_inset LatexCommand \index{vararg, va\_arg}
 736
 737 \end_inset
 738
 739  functions are casted to int unless explicitly casted
 740 \begin_inset Marginal
 741 collapsed true
 742
 743 \layout Standard
 744
 745
 746 \series bold
 747 \SpecialChar ~
 748 !
 749 \end_inset
 750
 751 , e.g.:
 752 \newline
 753
 754 \family typewriter
 755 \SpecialChar ~
 756 \SpecialChar ~
 757 char a=3;
 758 \newline
 759 \SpecialChar ~
 760 \SpecialChar ~
 761 printf ("%d %c
 762 \backslash
 763 n", a, (char)a);
 764 \family default
 765
 766 \newline
 767  will push a as an int and as a char resp.
 768 \layout Itemize
 769
 770 option -
 771 \begin_inset ERT
 772 status Collapsed
 773
 774 \layout Standard
 775
 776 \backslash
 777 /
 778 \end_inset
 779
 780 -regextend has been removed.
 781 \layout Itemize
 782
 783 option -
 784 \begin_inset ERT
 785 status Collapsed
 786
 787 \layout Standard
 788
 789 \backslash
 790 /
 791 \end_inset
 792
 793 -noregparms has been removed.
 794 \layout Itemize
 795
 796 option -
 797 \begin_inset ERT
 798 status Collapsed
 799
 800 \layout Standard
 801
 802 \backslash
 803 /
 804 \end_inset
 805
 806 -stack-after-data has been removed.
 807 \layout Itemize
 808
 809 bit
 810 \begin_inset LatexCommand \index{bit}
 811
 812 \end_inset
 813
 814  and sbit
 815 \begin_inset LatexCommand \index{sbit}
 816
 817 \end_inset
 818
 819
 820 \begin_inset LatexCommand \index{\_\_sbit}
 821
 822 \end_inset
 823
 824  types now consistently behave like the C99 _Bool type with respect to type
 825  conversion
 826 \begin_inset LatexCommand \index{type conversion}
 827
 828 \end_inset
 829
 830
 831 \begin_inset LatexCommand \index{type promotion}
 832
 833 \end_inset
 834
 835 .
 836  The most common incompatibility resulting from this change is related to
 837  bit toggling
 838 \begin_inset LatexCommand \index{Bit toggling}
 839
 840 \end_inset
 841
 842  idioms, e.g.:
 843 \newline
 844
 845 \family typewriter
 846 \SpecialChar ~
 847 \SpecialChar ~
 848 bit b;
 849 \newline
 850 \SpecialChar ~
 851 \SpecialChar ~
 852 b = ~
 853 \begin_inset LatexCommand \index{\~\/ Operator}
 854
 855 \end_inset
 856
 857 b; /* equivalent to b=1 instead of toggling b */
 858 \begin_inset Marginal
 859 collapsed true
 860
 861 \layout Standard
 862
 863
 864 \series bold
 865 \SpecialChar ~
 866 !
 867 \end_inset
 868
 869
 870 \newline
 871 \SpecialChar ~
 872 \SpecialChar ~
 873 b = !b; /* toggles b */
 874 \newline
 875
 876 \family default
 877 In previous versions, both forms would have toggled the bit.
 878 \layout Standard
 879
 880
 881 \emph on
 882 <pending: more incompatibilities?>
 883 \layout Section
 884
 885 System Requirements
 886 \layout Standard
 887
 888 What do you need before you start installation of SDCC? A computer, and
 889  a desire to compute.
 890  The preferred method of installation is to compile SDCC from source using
 891  GNU gcc and make.
 892  For Windows some pre-compiled binary distributions are available for your
 893  convenience.
 894  You should have some experience with command line tools and compiler use.
 895 \layout Section
 896
 897 Other Resources
 898 \layout Standard
 899
 900 The SDCC home page at
 901 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
 902
 903 \end_inset
 904
 905  is a great place to find distribution sets.
 906  You can also find links to the user mailing lists that offer help or discuss
 907  SDCC with other SDCC users.
 908  Web links to other SDCC related sites can also be found here.
 909  This document can be found in the DOC directory of the source package as
 910  a text or HTML file.
 911  A pdf version of this document is available at
 912 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
 913
 914 \end_inset
 915
 916 .
 917  Some of the other tools (simulator and assembler) included with SDCC contain
 918  their own documentation and can be found in the source distribution.
 919  If you want the latest unreleased software, the complete source package
 920  is available directly from Subversion on https://svn.sourceforge.net/svnroot/sdcc
 921 /trunk/sdcc.
 922 \layout Section
 923
 924 Wishes for the future
 925 \layout Standard
 926
 927 There are (and always will be) some things that could be done.
 928  Here are some I can think of:
 929 \newline
 930
 931 \layout Standard
 932
 933
 934 \family typewriter
 935 char KernelFunction3(char p) at 0x340;
 936 \newline
 937
 938 \layout Standard
 939
 940
 941 \family typewriter
 942 better code banking
 943 \begin_inset LatexCommand \index{code banking (limited support)}
 944
 945 \end_inset
 946
 947  support for mcs51
 948 \newline
 949
 950 \newline
 951
 952 \family default
 953 If you can think of some more, please see the section
 954 \begin_inset LatexCommand \ref{sub:Requesting-Features}
 955
 956 \end_inset
 957
 958  about filing feature requests
 959 \begin_inset LatexCommand \index{Requesting features}
 960
 961 \end_inset
 962
 963
 964 \begin_inset LatexCommand \index{Feature request}
 965
 966 \end_inset
 967
 968 .
 969 \newline
 970
 971 \layout Chapter
 972
 973 Installing SDCC
 974 \begin_inset LatexCommand \index{Installation}
 975
 976 \end_inset
 977
 978
 979 \layout Standard
 980
 981 For most users it is sufficient to skip to either section
 982 \begin_inset LatexCommand \ref{sub:Building-SDCC-on-Linux}
 983
 984 \end_inset
 985
 986  (Unix) or section
 987 \begin_inset LatexCommand \ref{sub:Windows-Install}
 988
 989 \end_inset
 990
 991  (Windows).
 992  More detailed instructions follow below.
 993 \layout Section
 994
 995 Configure Options
 996 \begin_inset LatexCommand \index{Options SDCC configuration}
 997
 998 \end_inset
 999
1000
1001 \layout Standard
1002
1003 The install paths, search paths and other options are defined when running
1004  'configure'.
1005  The defaults can be overridden by:
1006 \layout List
1007 \labelwidthstring 00.00.0000
1008
1009 -
1010 \begin_inset ERT
1011 status Collapsed
1012
1013 \layout Standard
1014
1015 \backslash
1016 /
1017 \end_inset
1018
1019 -prefix see table below
1020 \layout List
1021 \labelwidthstring 00.00.0000
1022
1023 -
1024 \begin_inset ERT
1025 status Collapsed
1026
1027 \layout Standard
1028
1029 \backslash
1030 /
1031 \end_inset
1032
1033 -exec_prefix see table below
1034 \layout List
1035 \labelwidthstring 00.00.0000
1036
1037 -
1038 \begin_inset ERT
1039 status Collapsed
1040
1041 \layout Standard
1042
1043 \backslash
1044 /
1045 \end_inset
1046
1047 -bindir see table below
1048 \layout List
1049 \labelwidthstring 00.00.0000
1050
1051 -
1052 \begin_inset ERT
1053 status Collapsed
1054
1055 \layout Standard
1056
1057 \backslash
1058 /
1059 \end_inset
1060
1061 -datadir see table below
1062 \newline
1063
1064 \layout List
1065 \labelwidthstring 00.00.0000
1066
1067 \SpecialChar ~
1068 \SpecialChar ~
1069 docdir environment variable, see table below
1070 \layout List
1071 \labelwidthstring 00.00.0000
1072
1073 \SpecialChar ~
1074 \SpecialChar ~
1075 include_dir_suffix environment variable, see table below
1076 \layout List
1077 \labelwidthstring 00.00.0000
1078
1079 \SpecialChar ~
1080 \SpecialChar ~
1081 lib_dir_suffix environment variable, see table below
1082 \layout List
1083 \labelwidthstring 00.00.0000
1084
1085 \SpecialChar ~
1086 \SpecialChar ~
1087 sdccconf_h_dir_separator environment variable, either / or
1088 \backslash
1089
1090 \backslash
1091  makes sense here.
1092  This character will only be used in sdccconf.h; don't forget it's a C-header,
1093  therefore a double-backslash is needed there.
1094 \newline
1095
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-mcs51-port Excludes the Intel mcs51 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-gbz80-port Excludes the Gameboy gbz80 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-z80-port Excludes the z80 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-avr-port Excludes the AVR 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-ds390-port Excludes the DS390 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-hc08-port Excludes the HC08 port
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-pic-port Excludes the PIC port
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-xa51-port Excludes the XA51 port
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 -disable-ucsim Disables configuring and building of ucsim
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 -disable-device-lib Disables automatically building device libraries
1236 \layout List
1237 \labelwidthstring 00.00.0000
1238
1239 -
1240 \begin_inset ERT
1241 status Collapsed
1242
1243 \layout Standard
1244
1245 \backslash
1246 /
1247 \end_inset
1248
1249 -disable-packihx Disables building packihx
1250 \newline
1251
1252 \layout List
1253 \labelwidthstring 00.00.0000
1254
1255 -
1256 \begin_inset ERT
1257 status Collapsed
1258
1259 \layout Standard
1260
1261 \backslash
1262 /
1263 \end_inset
1264
1265 -enable-doc Build pdf, html and txt files from the lyx sources
1266 \layout List
1267 \labelwidthstring 00.00.0000
1268
1269 -
1270 \begin_inset ERT
1271 status Collapsed
1272
1273 \layout Standard
1274
1275 \backslash
1276 /
1277 \end_inset
1278
1279 -enable-libgc Use the Bohem memory allocator.
1280  Lower runtime footprint.
1281 \layout Standard
1282
1283 Furthermore the environment variables CC, CFLAGS, ...
1284  the tools and their arguments can be influenced.
1285  Please see `configure -
1286 \begin_inset ERT
1287 status Collapsed
1288
1289 \layout Standard
1290
1291 \backslash
1292 /
1293 \end_inset
1294
1295 -help` and the man/info pages of `configure` for details.
1296 \newline
1297
1298 \newline
1299 The names of the standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB,
1300  STD_FP_LIB, STD_DS390_LIB, STD_XA51_LIB and the environment variables SDCC_DIR_
1301 NAME, SDCC_INCLUDE_NAME, SDCC_LIB_NAME are defined by `configure` too.
1302  At the moment it's not possible to change the default settings (it was
1303  simply never required).
1304 \newline
1305
1306 \newline
1307 These configure options are compiled into the binaries, and can only be
1308  changed by rerunning 'configure' and recompiling SDCC.
1309  The configure options are written in
1310 \emph on
1311 italics
1312 \emph default
1313  to distinguish them from run time environment variables (see section search
1314  paths).
1315 \newline
1316
1317 \newline
1318 The settings for
1319 \begin_inset Quotes sld
1320 \end_inset
1321
1322 Win32 builds
1323 \begin_inset Quotes srd
1324 \end_inset
1325
1326  are used by the SDCC team to build the official Win32 binaries.
1327  The SDCC team uses Mingw32 to build the official Windows binaries, because
1328  it's
1329 \layout Enumerate
1330
1331 open source,
1332 \layout Enumerate
1333
1334 a gcc compiler and last but not least
1335 \layout Enumerate
1336
1337 the binaries can be built by cross compiling on Sourceforge's compile farm.
1338 \layout Standard
1339
1340 See the examples, how to pass the Win32 settings to 'configure'.
1341  The other Win32 builds using Borland, VC or whatever don't use 'configure',
1342  but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
1343  for Win32.
1344 \newline
1345
1346 \newline
1347 These defaults are:
1348 \newline
1349
1350 \layout Standard
1351 \align center
1352
1353 \begin_inset  Tabular
1354 <lyxtabular version="3" rows="8" columns="3">
1355 <features>
1356 <column alignment="block" valignment="top" leftline="true" width="0in">
1357 <column alignment="block" valignment="top" leftline="true" width="0in">
1358 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1359 <row topline="true" bottomline="true">
1360 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1361 \begin_inset Text
1362
1363 \layout Standard
1364
1365 Variable
1366 \end_inset
1367 </cell>
1368 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1369 \begin_inset Text
1370
1371 \layout Standard
1372
1373 default
1374 \end_inset
1375 </cell>
1376 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1377 \begin_inset Text
1378
1379 \layout Standard
1380
1381 Win32 builds
1382 \end_inset
1383 </cell>
1384 </row>
1385 <row topline="true">
1386 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1387 \begin_inset Text
1388
1389 \layout Standard
1390
1391
1392 \emph on
1393 PREFIX
1394 \end_inset
1395 </cell>
1396 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1397 \begin_inset Text
1398
1399 \layout Standard
1400
1401 /usr/local
1402 \end_inset
1403 </cell>
1404 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1405 \begin_inset Text
1406
1407 \layout Standard
1408
1409
1410 \backslash
1411 sdcc
1412 \end_inset
1413 </cell>
1414 </row>
1415 <row topline="true">
1416 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1417 \begin_inset Text
1418
1419 \layout Standard
1420
1421
1422 \emph on
1423 EXEC_PREFIX
1424 \end_inset
1425 </cell>
1426 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1427 \begin_inset Text
1428
1429 \layout Standard
1430
1431
1432 \emph on
1433 $PREFIX
1434 \end_inset
1435 </cell>
1436 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1437 \begin_inset Text
1438
1439 \layout Standard
1440
1441
1442 \emph on
1443 $PREFIX
1444 \end_inset
1445 </cell>
1446 </row>
1447 <row topline="true">
1448 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1449 \begin_inset Text
1450
1451 \layout Standard
1452
1453
1454 \emph on
1455 BINDIR
1456 \end_inset
1457 </cell>
1458 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1459 \begin_inset Text
1460
1461 \layout Standard
1462
1463
1464 \emph on
1465 $EXECPREFIX
1466 \emph default
1467 /bin
1468 \end_inset
1469 </cell>
1470 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1471 \begin_inset Text
1472
1473 \layout Standard
1474
1475
1476 \emph on
1477 $EXECPREFIX
1478 \emph default
1479
1480 \backslash
1481 bin
1482 \end_inset
1483 </cell>
1484 </row>
1485 <row topline="true">
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 \end_inset
1495 </cell>
1496 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1497 \begin_inset Text
1498
1499 \layout Standard
1500
1501
1502 \emph on
1503 $PREFIX
1504 \emph default
1505 /share
1506 \end_inset
1507 </cell>
1508 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1509 \begin_inset Text
1510
1511 \layout Standard
1512
1513
1514 \emph on
1515 $PREFIX
1516 \end_inset
1517 </cell>
1518 </row>
1519 <row topline="true">
1520 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1521 \begin_inset Text
1522
1523 \layout Standard
1524
1525
1526 \emph on
1527 DOCDIR
1528 \end_inset
1529 </cell>
1530 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1531 \begin_inset Text
1532
1533 \layout Standard
1534
1535
1536 \emph on
1537 $DATADIR
1538 \emph default
1539 /sdcc/doc
1540 \end_inset
1541 </cell>
1542 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1543 \begin_inset Text
1544
1545 \layout Standard
1546
1547
1548 \emph on
1549 $DATADIR
1550 \emph default
1551
1552 \backslash
1553 doc
1554 \end_inset
1555 </cell>
1556 </row>
1557 <row topline="true">
1558 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1559 \begin_inset Text
1560
1561 \layout Standard
1562
1563
1564 \emph on
1565 INCLUDE_DIR_SUFFIX
1566 \end_inset
1567 </cell>
1568 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1569 \begin_inset Text
1570
1571 \layout Standard
1572
1573 sdcc/include
1574 \end_inset
1575 </cell>
1576 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1577 \begin_inset Text
1578
1579 \layout Standard
1580
1581 include
1582 \end_inset
1583 </cell>
1584 </row>
1585 <row topline="true" bottomline="true">
1586 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1587 \begin_inset Text
1588
1589 \layout Standard
1590
1591
1592 \emph on
1593 LIB_DIR_SUFFIX
1594 \end_inset
1595 </cell>
1596 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1597 \begin_inset Text
1598
1599 \layout Standard
1600
1601 sdcc/lib
1602 \end_inset
1603 </cell>
1604 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1605 \begin_inset Text
1606
1607 \layout Standard
1608
1609 lib
1610 \end_inset
1611 </cell>
1612 </row>
1613 </lyxtabular>
1614
1615 \end_inset
1616
1617
1618 \newline
1619
1620 \layout Standard
1621 \noindent
1622 'configure' also computes relative paths.
1623  This is needed for full relocatability of a binary package and to complete
1624  search paths (see section search paths below):
1625 \newline
1626
1627 \layout Standard
1628 \align center
1629
1630 \begin_inset  Tabular
1631 <lyxtabular version="3" rows="4" columns="3">
1632 <features>
1633 <column alignment="block" valignment="top" leftline="true" width="0in">
1634 <column alignment="block" valignment="top" leftline="true" width="0in">
1635 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1636 <row topline="true" bottomline="true">
1637 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1638 \begin_inset Text
1639
1640 \layout Standard
1641
1642 Variable (computed)
1643 \end_inset
1644 </cell>
1645 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1646 \begin_inset Text
1647
1648 \layout Standard
1649
1650 default
1651 \end_inset
1652 </cell>
1653 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1654 \begin_inset Text
1655
1656 \layout Standard
1657
1658 Win32 builds
1659 \end_inset
1660 </cell>
1661 </row>
1662 <row topline="true" bottomline="true">
1663 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1664 \begin_inset Text
1665
1666 \layout Standard
1667
1668
1669 \emph on
1670 BIN2DATA_DIR
1671 \end_inset
1672 </cell>
1673 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1674 \begin_inset Text
1675
1676 \layout Standard
1677
1678 ../share
1679 \end_inset
1680 </cell>
1681 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1682 \begin_inset Text
1683
1684 \layout Standard
1685
1686 ..
1687 \end_inset
1688 </cell>
1689 </row>
1690 <row bottomline="true">
1691 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1692 \begin_inset Text
1693
1694 \layout Standard
1695
1696
1697 \emph on
1698 PREFIX2BIN_DIR
1699 \end_inset
1700 </cell>
1701 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1702 \begin_inset Text
1703
1704 \layout Standard
1705
1706 bin
1707 \end_inset
1708 </cell>
1709 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1710 \begin_inset Text
1711
1712 \layout Standard
1713
1714 bin
1715 \end_inset
1716 </cell>
1717 </row>
1718 <row bottomline="true">
1719 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1720 \begin_inset Text
1721
1722 \layout Standard
1723
1724
1725 \emph on
1726 PREFIX2DATA_DIR
1727 \end_inset
1728 </cell>
1729 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1730 \begin_inset Text
1731
1732 \layout Standard
1733
1734 share/sdcc
1735 \end_inset
1736 </cell>
1737 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1738 \begin_inset Text
1739
1740 \layout Standard
1741
1742 \end_inset
1743 </cell>
1744 </row>
1745 </lyxtabular>
1746
1747 \end_inset
1748
1749
1750 \newline
1751
1752 \layout Standard
1753 \noindent
1754 Examples:
1755 \layout LyX-Code
1756
1757 ./configure
1758 \newline
1759 ./configure -
1760 \begin_inset ERT
1761 status Collapsed
1762
1763 \layout Standard
1764
1765 \backslash
1766 /
1767 \end_inset
1768
1769 -prefix=
1770 \begin_inset Quotes srd
1771 \end_inset
1772
1773 /usr/bin
1774 \begin_inset Quotes srd
1775 \end_inset
1776
1777  -
1778 \begin_inset ERT
1779 status Collapsed
1780
1781 \layout Standard
1782
1783 \backslash
1784 /
1785 \end_inset
1786
1787 -datadir=
1788 \begin_inset Quotes srd
1789 \end_inset
1790
1791 /usr/share
1792 \begin_inset Quotes srd
1793 \end_inset
1794
1795
1796 \newline
1797 ./configure -
1798 \begin_inset ERT
1799 status Collapsed
1800
1801 \layout Standard
1802
1803 \backslash
1804 /
1805 \end_inset
1806
1807 -disable-avr-port -
1808 \begin_inset ERT
1809 status Collapsed
1810
1811 \layout Standard
1812
1813 \backslash
1814 /
1815 \end_inset
1816
1817 -disable-xa51-port
1818 \layout Standard
1819
1820 To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw
1821 32'):
1822 \layout LyX-Code
1823
1824 ./configure
1825 \backslash
1826
1827 \newline
1828 CC=
1829 \begin_inset Quotes srd
1830 \end_inset
1831
1832 i586-mingw32msvc-gcc
1833 \begin_inset Quotes srd
1834 \end_inset
1835
1836  CXX=
1837 \begin_inset Quotes srd
1838 \end_inset
1839
1840 i586-mingw32msvc-g++
1841 \begin_inset Quotes srd
1842 \end_inset
1843
1844
1845 \backslash
1846
1847 \newline
1848 RANLIB=
1849 \begin_inset Quotes srd
1850 \end_inset
1851
1852 i586-mingw32msvc-ranlib
1853 \begin_inset Quotes srd
1854 \end_inset
1855
1856
1857 \backslash
1858
1859 \newline
1860 STRIP=
1861 \begin_inset Quotes srd
1862 \end_inset
1863
1864 i586-mingw32msvc-strip
1865 \begin_inset Quotes srd
1866 \end_inset
1867
1868
1869 \backslash
1870
1871 \newline
1872 -
1873 \begin_inset ERT
1874 status Collapsed
1875
1876 \layout Standard
1877
1878 \backslash
1879 /
1880 \end_inset
1881
1882 -prefix=
1883 \begin_inset Quotes srd
1884 \end_inset
1885
1886 /sdcc
1887 \begin_inset Quotes srd
1888 \end_inset
1889
1890
1891 \backslash
1892
1893 \newline
1894 -
1895 \begin_inset ERT
1896 status Collapsed
1897
1898 \layout Standard
1899
1900 \backslash
1901 /
1902 \end_inset
1903
1904 -datadir=
1905 \begin_inset Quotes srd
1906 \end_inset
1907
1908 /sdcc
1909 \begin_inset Quotes srd
1910 \end_inset
1911
1912
1913 \backslash
1914
1915 \newline
1916 docdir=
1917 \begin_inset Quotes srd
1918 \end_inset
1919
1920 /sdcc/doc
1921 \begin_inset Quotes srd
1922 \end_inset
1923
1924
1925 \backslash
1926
1927 \newline
1928 include_dir_suffix=
1929 \begin_inset Quotes srd
1930 \end_inset
1931
1932 include
1933 \begin_inset Quotes srd
1934 \end_inset
1935
1936
1937 \backslash
1938
1939 \newline
1940 lib_dir_suffix=
1941 \begin_inset Quotes srd
1942 \end_inset
1943
1944 lib
1945 \begin_inset Quotes srd
1946 \end_inset
1947
1948
1949 \backslash
1950
1951 \newline
1952 sdccconf_h_dir_separator=
1953 \begin_inset Quotes srd
1954 \end_inset
1955
1956
1957 \backslash
1958
1959 \backslash
1960
1961 \backslash
1962
1963 \backslash
1964
1965 \begin_inset Quotes srd
1966 \end_inset
1967
1968
1969 \backslash
1970
1971 \newline
1972 -
1973 \begin_inset ERT
1974 status Collapsed
1975
1976 \layout Standard
1977
1978 \backslash
1979 /
1980 \end_inset
1981
1982 -disable-device-lib
1983 \backslash
1984
1985 \newline
1986 -
1987 \begin_inset ERT
1988 status Collapsed
1989
1990 \layout Standard
1991
1992 \backslash
1993 /
1994 \end_inset
1995
1996 -host=i586-mingw32msvc
1997 \backslash
1998
1999 \newline
2000 -
2001 \begin_inset ERT
2002 status Collapsed
2003
2004 \layout Standard
2005
2006 \backslash
2007 /
2008 \end_inset
2009
2010 -build=unknown-unknown-linux-gnu
2011 \layout Standard
2012
2013 To
2014 \begin_inset Quotes sld
2015 \end_inset
2016
2017 cross
2018 \begin_inset Quotes srd
2019 \end_inset
2020
2021 compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32
2022 ):
2023 \layout LyX-Code
2024
2025 ./configure -C
2026 \backslash
2027
2028 \newline
2029 -
2030 \begin_inset ERT
2031 status Collapsed
2032
2033 \layout Standard
2034
2035 \backslash
2036 /
2037 \end_inset
2038
2039 -prefix=
2040 \begin_inset Quotes srd
2041 \end_inset
2042
2043 /sdcc
2044 \begin_inset Quotes srd
2045 \end_inset
2046
2047
2048 \backslash
2049
2050 \newline
2051 -
2052 \begin_inset ERT
2053 status Collapsed
2054
2055 \layout Standard
2056
2057 \backslash
2058 /
2059 \end_inset
2060
2061 -datadir=
2062 \begin_inset Quotes srd
2063 \end_inset
2064
2065 /sdcc
2066 \begin_inset Quotes srd
2067 \end_inset
2068
2069
2070 \backslash
2071
2072 \newline
2073 docdir=
2074 \begin_inset Quotes srd
2075 \end_inset
2076
2077 /sdcc/doc
2078 \begin_inset Quotes srd
2079 \end_inset
2080
2081
2082 \backslash
2083
2084 \newline
2085 include_dir_suffix=
2086 \begin_inset Quotes srd
2087 \end_inset
2088
2089 include
2090 \begin_inset Quotes srd
2091 \end_inset
2092
2093
2094 \backslash
2095
2096 \newline
2097 lib_dir_suffix=
2098 \begin_inset Quotes srd
2099 \end_inset
2100
2101 lib
2102 \begin_inset Quotes srd
2103 \end_inset
2104
2105
2106 \backslash
2107
2108 \newline
2109 sdccconf_h_dir_separator=
2110 \begin_inset Quotes srd
2111 \end_inset
2112
2113
2114 \backslash
2115
2116 \backslash
2117
2118 \backslash
2119
2120 \backslash
2121
2122 \begin_inset Quotes srd
2123 \end_inset
2124
2125
2126 \backslash
2127
2128 \newline
2129 CC=
2130 \begin_inset Quotes srd
2131 \end_inset
2132
2133 gcc -mno-cygwin
2134 \begin_inset Quotes srd
2135 \end_inset
2136
2137
2138 \backslash
2139
2140 \newline
2141 CXX=
2142 \begin_inset Quotes srd
2143 \end_inset
2144
2145 g++ -mno-cygwin
2146 \begin_inset Quotes srd
2147 \end_inset
2148
2149
2150 \layout Standard
2151
2152 'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
2153  The option '-
2154 \begin_inset ERT
2155 status Collapsed
2156
2157 \layout Standard
2158
2159 \backslash
2160 /
2161 \end_inset
2162
2163 -C' turns on caching, which gives a little bit extra speed.
2164  However if options are changed, it can be necessary to delete the config.cache
2165  file.
2166 \layout Section
2167
2168 Install paths
2169 \begin_inset LatexCommand \label{sub:Install-paths}
2170
2171 \end_inset
2172
2173
2174 \begin_inset LatexCommand \index{Install paths}
2175
2176 \end_inset
2177
2178
2179 \layout Standard
2180 \added_space_top medskip \align center
2181
2182 \begin_inset  Tabular
2183 <lyxtabular version="3" rows="5" columns="4">
2184 <features>
2185 <column alignment="left" valignment="top" leftline="true" width="0">
2186 <column alignment="left" valignment="top" leftline="true" width="0">
2187 <column alignment="left" valignment="top" leftline="true" width="0">
2188 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
2189 <row topline="true" bottomline="true">
2190 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2191 \begin_inset Text
2192
2193 \layout Standard
2194
2195
2196 \series bold
2197 Description
2198 \end_inset
2199 </cell>
2200 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2201 \begin_inset Text
2202
2203 \layout Standard
2204
2205
2206 \series bold
2207 Path
2208 \end_inset
2209 </cell>
2210 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2211 \begin_inset Text
2212
2213 \layout Standard
2214
2215
2216 \series bold
2217 Default
2218 \end_inset
2219 </cell>
2220 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2221 \begin_inset Text
2222
2223 \layout Standard
2224
2225
2226 \series bold
2227 Win32 builds
2228 \end_inset
2229 </cell>
2230 </row>
2231 <row topline="true">
2232 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2233 \begin_inset Text
2234
2235 \layout Standard
2236
2237 Binary files*
2238 \end_inset
2239 </cell>
2240 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2241 \begin_inset Text
2242
2243 \layout Standard
2244
2245
2246 \emph on
2247 $EXEC_PREFIX
2248 \end_inset
2249 </cell>
2250 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2251 \begin_inset Text
2252
2253 \layout Standard
2254
2255 /usr/local/bin
2256 \end_inset
2257 </cell>
2258 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2259 \begin_inset Text
2260
2261 \layout Standard
2262
2263
2264 \backslash
2265 sdcc
2266 \backslash
2267 bin
2268 \end_inset
2269 </cell>
2270 </row>
2271 <row topline="true">
2272 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2273 \begin_inset Text
2274
2275 \layout Standard
2276
2277 Include files
2278 \end_inset
2279 </cell>
2280 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2281 \begin_inset Text
2282
2283 \layout Standard
2284
2285
2286 \emph on
2287 $DATADIR/ $INCLUDE_DIR_SUFFIX
2288 \end_inset
2289 </cell>
2290 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2291 \begin_inset Text
2292
2293 \layout Standard
2294
2295 /usr/local/share/sdcc/include
2296 \end_inset
2297 </cell>
2298 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2299 \begin_inset Text
2300
2301 \layout Standard
2302
2303
2304 \backslash
2305 sdcc
2306 \backslash
2307 include
2308 \end_inset
2309 </cell>
2310 </row>
2311 <row topline="true">
2312 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2313 \begin_inset Text
2314
2315 \layout Standard
2316
2317 Library file**
2318 \end_inset
2319 </cell>
2320 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2321 \begin_inset Text
2322
2323 \layout Standard
2324
2325
2326 \emph on
2327 $DATADIR/$LIB_DIR_SUFFIX
2328 \end_inset
2329 </cell>
2330 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2331 \begin_inset Text
2332
2333 \layout Standard
2334
2335 /usr/local/share/sdcc/lib
2336 \end_inset
2337 </cell>
2338 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2339 \begin_inset Text
2340
2341 \layout Standard
2342
2343
2344 \backslash
2345 sdcc
2346 \backslash
2347 lib
2348 \end_inset
2349 </cell>
2350 </row>
2351 <row topline="true" bottomline="true">
2352 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2353 \begin_inset Text
2354
2355 \layout Standard
2356
2357 Documentation
2358 \end_inset
2359 </cell>
2360 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2361 \begin_inset Text
2362
2363 \layout Standard
2364
2365
2366 \emph on
2367 $DOCDIR
2368 \end_inset
2369 </cell>
2370 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2371 \begin_inset Text
2372
2373 \layout Standard
2374
2375 /usr/local/share/sdcc/doc
2376 \end_inset
2377 </cell>
2378 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2379 \begin_inset Text
2380
2381 \layout Standard
2382
2383
2384 \backslash
2385 sdcc
2386 \backslash
2387 doc
2388 \end_inset
2389 </cell>
2390 </row>
2391 </lyxtabular>
2392
2393 \end_inset
2394
2395
2396 \layout Verse
2397
2398
2399 \size footnotesize
2400 *compiler, preprocessor, assembler, and linker
2401 \newline
2402 **the
2403 \shape italic
2404 model
2405 \shape default
2406  is auto-appended by the compiler, e.g.
2407  small, large, z80, ds390 etc
2408 \layout Standard
2409 \noindent
2410 The install paths can still be changed during `make install` with e.g.:
2411 \layout LyX-Code
2412
2413 make install prefix=$(HOME)/local/sdcc
2414 \layout Standard
2415
2416 Of course this doesn't change the search paths compiled into the binaries.
2417 \newline
2418
2419 \newline
2420 Moreover the install path can be changed by defining DESTDIR
2421 \begin_inset LatexCommand \index{DESTDIR}
2422
2423 \end_inset
2424
2425 :
2426 \layout LyX-Code
2427
2428 make install DESTDIR=$(HOME)/sdcc.rpm/
2429 \layout Standard
2430
2431 Please note that DESTDIR must have a trailing slash!
2432 \layout Section
2433
2434 Search Paths
2435 \begin_inset LatexCommand \label{sub:Search-Paths}
2436
2437 \end_inset
2438
2439
2440 \begin_inset LatexCommand \index{Search path}
2441
2442 \end_inset
2443
2444
2445 \layout Standard
2446
2447 Some search paths or parts of them are determined by configure variables
2448  (in
2449 \emph on
2450 italics
2451 \emph default
2452 , see section above).
2453  Further search paths are determined by environment variables during runtime.
2454
2455 \newline
2456 The paths searched when running the compiler are as follows (the first catch
2457  wins):
2458 \newline
2459
2460 \newline
2461 1.
2462  Binary files (preprocessor, assembler and linker)
2463 \newline
2464
2465 \layout Standard
2466 \align center
2467
2468 \begin_inset  Tabular
2469 <lyxtabular version="3" rows="4" columns="3">
2470 <features>
2471 <column alignment="block" valignment="top" leftline="true" width="0in">
2472 <column alignment="block" valignment="top" leftline="true" width="0in">
2473 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2474 <row topline="true" bottomline="true">
2475 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2476 \begin_inset Text
2477
2478 \layout Standard
2479
2480 Search path
2481 \end_inset
2482 </cell>
2483 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2484 \begin_inset Text
2485
2486 \layout Standard
2487
2488 default
2489 \end_inset
2490 </cell>
2491 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2492 \begin_inset Text
2493
2494 \layout Standard
2495
2496 Win32 builds
2497 \end_inset
2498 </cell>
2499 </row>
2500 <row topline="true">
2501 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2502 \begin_inset Text
2503
2504 \layout Standard
2505
2506 $SDCC_HOME/
2507 \emph on
2508 $PPREFIX2BIN_DIR
2509 \end_inset
2510 </cell>
2511 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2512 \begin_inset Text
2513
2514 \layout Standard
2515
2516 $SDCC_HOME/bin
2517 \end_inset
2518 </cell>
2519 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2520 \begin_inset Text
2521
2522 \layout Standard
2523
2524 $SDCC_HOME
2525 \backslash
2526 bin
2527 \end_inset
2528 </cell>
2529 </row>
2530 <row topline="true">
2531 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2532 \begin_inset Text
2533
2534 \layout Standard
2535
2536 Path of argv[0] (if available)
2537 \end_inset
2538 </cell>
2539 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2540 \begin_inset Text
2541
2542 \layout Standard
2543
2544 Path of argv[0]
2545 \end_inset
2546 </cell>
2547 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2548 \begin_inset Text
2549
2550 \layout Standard
2551
2552 Path of argv[0]
2553 \end_inset
2554 </cell>
2555 </row>
2556 <row topline="true" bottomline="true">
2557 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2558 \begin_inset Text
2559
2560 \layout Standard
2561
2562 $PATH
2563 \end_inset
2564 </cell>
2565 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2566 \begin_inset Text
2567
2568 \layout Standard
2569
2570 $PATH
2571 \end_inset
2572 </cell>
2573 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2574 \begin_inset Text
2575
2576 \layout Standard
2577
2578 $PATH
2579 \end_inset
2580 </cell>
2581 </row>
2582 </lyxtabular>
2583
2584 \end_inset
2585
2586
2587 \newline
2588
2589 \layout Standard
2590 \noindent
2591 2.
2592  Include files
2593 \newline
2594
2595 \layout Standard
2596 \align center
2597
2598 \begin_inset  Tabular
2599 <lyxtabular version="3" rows="6" columns="3">
2600 <features>
2601 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2602 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2603 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2604 <row topline="true" bottomline="true">
2605 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2606 \begin_inset Text
2607
2608 \layout Standard
2609
2610 Search path
2611 \end_inset
2612 </cell>
2613 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2614 \begin_inset Text
2615
2616 \layout Standard
2617
2618 default
2619 \end_inset
2620 </cell>
2621 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2622 \begin_inset Text
2623
2624 \layout Standard
2625
2626 Win32 builds
2627 \end_inset
2628 </cell>
2629 </row>
2630 <row topline="true">
2631 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2632 \begin_inset Text
2633
2634 \layout Standard
2635
2636 -
2637 \begin_inset ERT
2638 status Collapsed
2639
2640 \layout Standard
2641
2642 \backslash
2643 /
2644 \end_inset
2645
2646 -I dir
2647 \end_inset
2648 </cell>
2649 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2650 \begin_inset Text
2651
2652 \layout Standard
2653
2654 -
2655 \begin_inset ERT
2656 status Collapsed
2657
2658 \layout Standard
2659
2660 \backslash
2661 /
2662 \end_inset
2663
2664 -I dir
2665 \end_inset
2666 </cell>
2667 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2668 \begin_inset Text
2669
2670 \layout Standard
2671
2672 -
2673 \begin_inset ERT
2674 status Collapsed
2675
2676 \layout Standard
2677
2678 \backslash
2679 /
2680 \end_inset
2681
2682 -I dir
2683 \end_inset
2684 </cell>
2685 </row>
2686 <row topline="true">
2687 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2688 \begin_inset Text
2689
2690 \layout Standard
2691
2692 $SDCC_INCLUDE
2693 \end_inset
2694 </cell>
2695 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2696 \begin_inset Text
2697
2698 \layout Standard
2699
2700 $SDCC_INCLUDE
2701 \end_inset
2702 </cell>
2703 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2704 \begin_inset Text
2705
2706 \layout Standard
2707
2708 $SDCC_INCLUDE
2709 \end_inset
2710 </cell>
2711 </row>
2712 <row topline="true">
2713 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2714 \begin_inset Text
2715
2716 \layout Standard
2717
2718 $SDCC_HOME/
2719 \newline
2720
2721 \emph on
2722 $PREFIX2DATA_DIR/
2723 \newline
2724 $INCLUDE_DIR_SUFFIX
2725 \end_inset
2726 </cell>
2727 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2728 \begin_inset Text
2729
2730 \layout Standard
2731
2732 $SDCC_ HOME/
2733 \newline
2734 share/sdcc/
2735 \newline
2736 include
2737 \end_inset
2738 </cell>
2739 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2740 \begin_inset Text
2741
2742 \layout Standard
2743
2744 $SDCC_HOME
2745 \backslash
2746 include
2747 \end_inset
2748 </cell>
2749 </row>
2750 <row topline="true">
2751 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2752 \begin_inset Text
2753
2754 \layout Standard
2755
2756 path(argv[0])/
2757 \newline
2758
2759 \emph on
2760 $BIN2DATADIR/
2761 \emph default
2762
2763 \newline
2764
2765 \emph on
2766 $INCLUDE_DIR_SUFFIX
2767 \end_inset
2768 </cell>
2769 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2770 \begin_inset Text
2771
2772 \layout Standard
2773
2774 path(argv[0])/
2775 \newline
2776 ../sdcc/include
2777 \newline
2778 \SpecialChar ~
2779 \SpecialChar ~
2780 \SpecialChar ~
2781 \SpecialChar ~
2782 \SpecialChar ~
2783 \SpecialChar ~
2784 \SpecialChar ~
2785 \SpecialChar ~
2786 \SpecialChar ~
2787 \SpecialChar ~
2788 \SpecialChar ~
2789 \SpecialChar ~
2790 \SpecialChar ~
2791 \SpecialChar ~
2792 \SpecialChar ~
2793 \SpecialChar ~
2794 \SpecialChar ~
2795 \SpecialChar ~
2796 \SpecialChar ~
2797 \SpecialChar ~
2798 \SpecialChar ~
2799 \SpecialChar ~
2800 \SpecialChar ~
2801 \SpecialChar ~
2802 \SpecialChar ~
2803 \SpecialChar ~
2804 \SpecialChar ~
2805 \SpecialChar ~
2806 \SpecialChar ~
2807 \SpecialChar ~
2808 \SpecialChar ~
2809 \SpecialChar ~
2810 \SpecialChar ~
2811 \SpecialChar ~
2812 \SpecialChar ~
2813 \SpecialChar ~
2814 \SpecialChar ~
2815 \SpecialChar ~
2816
2817 \end_inset
2818 </cell>
2819 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2820 \begin_inset Text
2821
2822 \layout Standard
2823
2824 path(argv[0])
2825 \backslash
2826 ..
2827 \backslash
2828 include
2829 \end_inset
2830 </cell>
2831 </row>
2832 <row topline="true" bottomline="true">
2833 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2834 \begin_inset Text
2835
2836 \layout Standard
2837
2838
2839 \emph on
2840 $DATADIR/
2841 \emph default
2842
2843 \newline
2844
2845 \emph on
2846 $INCLUDE_DIR_SUFFIX
2847 \end_inset
2848 </cell>
2849 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2850 \begin_inset Text
2851
2852 \layout Standard
2853
2854 /usr/local/share/sdcc/
2855 \newline
2856 include
2857 \end_inset
2858 </cell>
2859 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2860 \begin_inset Text
2861
2862 \layout Standard
2863
2864 (not on Win32)
2865 \end_inset
2866 </cell>
2867 </row>
2868 </lyxtabular>
2869
2870 \end_inset
2871
2872
2873 \newline
2874
2875 \layout Standard
2876 \noindent
2877 The option -
2878 \begin_inset ERT
2879 status Collapsed
2880
2881 \layout Standard
2882
2883 \backslash
2884 /
2885 \end_inset
2886
2887 -nostdinc disables the last two search paths.
2888 \newline
2889
2890 \newline
2891 3.
2892  Library files
2893 \newline
2894
2895 \layout Standard
2896
2897 With the exception of
2898 \begin_inset Quotes sld
2899 \end_inset
2900
2901 -
2902 \begin_inset ERT
2903 status Collapsed
2904
2905 \layout Standard
2906
2907 \backslash
2908 /
2909 \end_inset
2910
2911 -L dir
2912 \begin_inset Quotes srd
2913 \end_inset
2914
2915  the
2916 \shape italic
2917 model
2918 \shape default
2919  is auto-appended by the compiler (e.g.
2920  small, large, z80, ds390 etc.).
2921
2922 \newline
2923
2924 \layout Standard
2925 \align center
2926
2927 \begin_inset  Tabular
2928 <lyxtabular version="3" rows="6" columns="3">
2929 <features>
2930 <column alignment="block" valignment="top" leftline="true" width="1.7in">
2931 <column alignment="block" valignment="top" leftline="true" width="1.2in">
2932 <column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
2933 <row topline="true" bottomline="true">
2934 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2935 \begin_inset Text
2936
2937 \layout Standard
2938
2939 Search path
2940 \end_inset
2941 </cell>
2942 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2943 \begin_inset Text
2944
2945 \layout Standard
2946
2947 default
2948 \end_inset
2949 </cell>
2950 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2951 \begin_inset Text
2952
2953 \layout Standard
2954
2955 Win32 builds
2956 \end_inset
2957 </cell>
2958 </row>
2959 <row topline="true">
2960 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2961 \begin_inset Text
2962
2963 \layout Standard
2964
2965 -
2966 \begin_inset ERT
2967 status Collapsed
2968
2969 \layout Standard
2970
2971 \backslash
2972 /
2973 \end_inset
2974
2975 -L dir
2976 \end_inset
2977 </cell>
2978 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2979 \begin_inset Text
2980
2981 \layout Standard
2982
2983 -
2984 \begin_inset ERT
2985 status Collapsed
2986
2987 \layout Standard
2988
2989 \backslash
2990 /
2991 \end_inset
2992
2993 -L dir
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 -
3002 \begin_inset ERT
3003 status Collapsed
3004
3005 \layout Standard
3006
3007 \backslash
3008 /
3009 \end_inset
3010
3011 -L dir
3012 \end_inset
3013 </cell>
3014 </row>
3015 <row topline="true">
3016 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3017 \begin_inset Text
3018
3019 \layout Standard
3020
3021 $SDCC_LIB/
3022 \newline
3023
3024 \emph on
3025 <model>
3026 \end_inset
3027 </cell>
3028 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3029 \begin_inset Text
3030
3031 \layout Standard
3032
3033 $SDCC_LIB/
3034 \newline
3035
3036 \emph on
3037 <model>
3038 \end_inset
3039 </cell>
3040 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3041 \begin_inset Text
3042
3043 \layout Standard
3044
3045 $SDCC_LIB
3046 \backslash
3047
3048 \newline
3049
3050 \emph on
3051 <model>
3052 \end_inset
3053 </cell>
3054 </row>
3055 <row topline="true">
3056 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3057 \begin_inset Text
3058
3059 \layout Standard
3060
3061 $SDCC_HOME/
3062 \newline
3063
3064 \emph on
3065 $PREFIX2DATA_DIR/
3066 \newline
3067 $LIB_DIR_SUFFIX/<model>
3068 \end_inset
3069 </cell>
3070 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3071 \begin_inset Text
3072
3073 \layout Standard
3074
3075 $SDCC_HOME/
3076 \newline
3077 share/sdcc/
3078 \newline
3079 lib/
3080 \emph on
3081 <model>
3082 \end_inset
3083 </cell>
3084 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3085 \begin_inset Text
3086
3087 \layout Standard
3088
3089 $SDCC_HOME
3090 \backslash
3091 lib
3092 \backslash
3093
3094 \emph on
3095
3096 \newline
3097 <model>
3098 \end_inset
3099 </cell>
3100 </row>
3101 <row topline="true">
3102 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3103 \begin_inset Text
3104
3105 \layout Standard
3106
3107 path(argv[0])/
3108 \newline
3109
3110 \emph on
3111 $BIN2DATADIR/
3112 \emph default
3113
3114 \newline
3115
3116 \emph on
3117 $LIB_DIR_SUFFIX/<model>
3118 \end_inset
3119 </cell>
3120 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
3121 \begin_inset Text
3122
3123 \layout Standard
3124
3125 path(argv[0])/
3126 \newline
3127 ../sdcc/lib/
3128 \emph on
3129 <model>
3130 \newline
3131 \SpecialChar ~
3132 \SpecialChar ~
3133 \SpecialChar ~
3134 \SpecialChar ~
3135 \SpecialChar ~
3136 \SpecialChar ~
3137 \SpecialChar ~
3138 \SpecialChar ~
3139 \SpecialChar ~
3140 \SpecialChar ~
3141 \SpecialChar ~
3142 \SpecialChar ~
3143 \SpecialChar ~
3144 \SpecialChar ~
3145 \SpecialChar ~
3146 \SpecialChar ~
3147 \SpecialChar ~
3148 \SpecialChar ~
3149 \SpecialChar ~
3150 \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
3171 \end_inset
3172 </cell>
3173 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3174 \begin_inset Text
3175
3176 \layout Standard
3177
3178 path(argv[0])
3179 \backslash
3180
3181 \newline
3182 ..
3183 \backslash
3184 lib
3185 \backslash
3186
3187 \emph on
3188 <model>
3189 \newline
3190 \SpecialChar ~
3191 \SpecialChar ~
3192 \SpecialChar ~
3193 \SpecialChar ~
3194 \SpecialChar ~
3195 \SpecialChar ~
3196 \SpecialChar ~
3197 \SpecialChar ~
3198 \SpecialChar ~
3199 \SpecialChar ~
3200 \SpecialChar ~
3201 \SpecialChar ~
3202 \SpecialChar ~
3203 \SpecialChar ~
3204 \SpecialChar ~
3205 \SpecialChar ~
3206 \SpecialChar ~
3207 \SpecialChar ~
3208 \SpecialChar ~
3209 \SpecialChar ~
3210 \SpecialChar ~
3211 \SpecialChar ~
3212 \SpecialChar ~
3213 \SpecialChar ~
3214 \SpecialChar ~
3215 \SpecialChar ~
3216 \SpecialChar ~
3217 \SpecialChar ~
3218 \SpecialChar ~
3219 \SpecialChar ~
3220 \SpecialChar ~
3221 \SpecialChar ~
3222 \SpecialChar ~
3223 \SpecialChar ~
3224 \SpecialChar ~
3225
3226 \end_inset
3227 </cell>
3228 </row>
3229 <row topline="true" bottomline="true">
3230 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3231 \begin_inset Text
3232
3233 \layout Standard
3234
3235
3236 \emph on
3237 $DATADIR/
3238 \newline
3239 $LIB_DIR_SUFFIX/<model>
3240 \end_inset
3241 </cell>
3242 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3243 \begin_inset Text
3244
3245 \layout Standard
3246
3247 /usr/local/share/sdcc/
3248 \newline
3249 lib/
3250 \emph on
3251 <model>
3252 \end_inset
3253 </cell>
3254 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3255 \begin_inset Text
3256
3257 \layout Standard
3258
3259 (not on Win32)
3260 \end_inset
3261 </cell>
3262 </row>
3263 </lyxtabular>
3264
3265 \end_inset
3266
3267
3268 \newline
3269
3270 \layout Comment
3271
3272 Don't delete any of the stray spaces in the table above without checking
3273  the HTML output (last line)!
3274 \layout Standard
3275
3276 \SpecialChar ~
3277
3278 \newline
3279 The option -
3280 \begin_inset ERT
3281 status Collapsed
3282
3283 \layout Standard
3284
3285 \backslash
3286 /
3287 \end_inset
3288
3289 -nostdlib disables the last two search paths.
3290 \layout Section
3291
3292 Building SDCC
3293 \begin_inset LatexCommand \index{Building SDCC}
3294
3295 \end_inset
3296
3297
3298 \layout Subsection
3299
3300 Building SDCC on Linux
3301 \begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux}
3302
3303 \end_inset
3304
3305
3306 \layout Enumerate
3307
3308
3309 \series medium
3310 Download the source package
3311 \series default
3312  either from the SDCC Subversion repository or from the nightly snapshots
3313 \series medium
3314 , it will be named something like sdcc
3315 \series default
3316 .src
3317 \series medium
3318 .t
3319 \series default
3320 ar.
3321 \series medium
3322 gz
3323 \series default
3324
3325 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
3326
3327 \end_inset
3328
3329 .
3330 \layout Enumerate
3331
3332
3333 \series medium
3334 Bring up a command line terminal, such as xterm.
3335 \layout Enumerate
3336
3337
3338 \series medium
3339 Unpack the file using a command like:
3340 \family sans
3341 \series bold
3342 "tar -xvzf sdcc.src.tar.gz
3343 \family default
3344 \series default
3345 "
3346 \series medium
3347 , this will create a sub-directory called sdcc with all of the sources.
3348 \layout Enumerate
3349
3350 Change directory into the main SDCC directory, for example type:
3351 \family sans
3352 \series bold
3353 "cd sdcc
3354 \series default
3355 ".
3356 \layout Enumerate
3357
3358
3359 \series medium
3360 Type
3361 \family sans
3362 \series bold
3363 "./configure
3364 \family default
3365 \series default
3366 ".
3367  This configures the package for compilation on your system.
3368 \layout Enumerate
3369
3370
3371 \series medium
3372 Type
3373 \family sans
3374 \series bold
3375 "make
3376 \family default
3377 \series default
3378 "
3379 \series medium
3380 .
3381
3382 \series default
3383  All of the source packages will compile, this can take a while.
3384 \layout Enumerate
3385
3386
3387 \series medium
3388 Type
3389 \family sans
3390 \series bold
3391 "make install"
3392 \family default
3393 \series default
3394  as root
3395 \series medium
3396 .
3397
3398 \series default
3399  This copies the binary executables, the include files, the libraries and
3400  the documentation to the install directories.
3401  Proceed with section
3402 \begin_inset LatexCommand \ref{sec:Testing-the-SDCC}
3403
3404 \end_inset
3405
3406 .
3407 \layout Subsection
3408
3409 Building SDCC on OSX 2.x
3410 \layout Standard
3411
3412 Follow the instruction for Linux.
3413 \newline
3414
3415 \newline
3416 On OSX 2.x it was reported, that the default gcc (version 3.1 20020420 (prerelease
3417 )) fails to compile SDCC.
3418  Fortunately there's also gcc 2.9.x installed, which works fine.
3419  This compiler can be selected by running 'configure' with:
3420 \layout LyX-Code
3421
3422 ./configure CC=gcc2 CXX=g++2
3423 \layout Subsection
3424
3425 Cross compiling SDCC on Linux for Windows
3426 \layout Standard
3427
3428 With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
3429  See section 'Configure Options'.
3430 \layout Subsection
3431
3432 Building SDCC using Cygwin and Mingw32
3433 \layout Standard
3434
3435 For building and installing a Cygwin executable follow the instructions
3436  for Linux.
3437 \newline
3438
3439 \newline
3440 On Cygwin a
3441 \begin_inset Quotes sld
3442 \end_inset
3443
3444 native
3445 \begin_inset Quotes srd
3446 \end_inset
3447
3448  Win32-binary can be built, which will not need the Cygwin-DLL.
3449  For the necessary 'configure' options see section 'configure options' or
3450  the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'.
3451 \newline
3452
3453 \newline
3454 In order to install Cygwin on Windows download setup.exe from
3455 \begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
3456
3457 \end_inset
3458
3459 .
3460  Run it, set the
3461 \begin_inset Quotes sld
3462 \end_inset
3463
3464 default text file type
3465 \begin_inset Quotes srd
3466 \end_inset
3467
3468  to
3469 \begin_inset Quotes sld
3470 \end_inset
3471
3472 unix
3473 \begin_inset Quotes srd
3474 \end_inset
3475
3476  and download/install at least the following packages.
3477  Some packages are selected by default, others will be automatically selected
3478  because of dependencies with the manually selected packages.
3479  Never deselect these packages!
3480 \layout Itemize
3481
3482 flex
3483 \layout Itemize
3484
3485 bison
3486 \layout Itemize
3487
3488 gcc ; version 3.x is fine, no need to use the old 2.9x
3489 \layout Itemize
3490
3491 binutils ; selected with gcc
3492 \layout Itemize
3493
3494 make
3495 \layout Itemize
3496
3497 rxvt ; a nice console, which makes life much easier under windoze (see below)
3498 \layout Itemize
3499
3500 man ; not really needed for building SDCC, but you'll miss it sooner or
3501  later
3502 \layout Itemize
3503
3504 less ; not really needed for building SDCC, but you'll miss it sooner or
3505  later
3506 \layout Itemize
3507
3508 svn ; only if you use Subversion access
3509 \layout Standard
3510
3511 If you want to develop something you'll need:
3512 \layout Itemize
3513
3514 python ; for the regression tests
3515 \layout Itemize
3516
3517 gdb ; the gnu debugger, together with the nice GUI
3518 \begin_inset Quotes sld
3519 \end_inset
3520
3521 insight
3522 \begin_inset Quotes srd
3523 \end_inset
3524
3525
3526 \layout Itemize
3527
3528 openssh ; to access the CF or commit changes
3529 \layout Itemize
3530
3531 autoconf and autoconf-devel ; if you want to fight with 'configure', don't
3532  use autoconf-stable!
3533 \layout Standard
3534
3535 rxvt is a nice console with history.
3536  Replace in your cygwin.bat the line
3537 \layout LyX-Code
3538
3539 bash -
3540 \begin_inset ERT
3541 status Collapsed
3542
3543 \layout Standard
3544
3545 \backslash
3546 /
3547 \end_inset
3548
3549 -login -i
3550 \layout Standard
3551
3552 with (one line):
3553 \layout LyX-Code
3554
3555 rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
3556 \layout LyX-Code
3557
3558      -bg black -fg white -geometry 100x65 -e bash -
3559 \begin_inset ERT
3560 status Collapsed
3561
3562 \layout Standard
3563
3564 \backslash
3565 /
3566 \end_inset
3567
3568 -login
3569 \layout Standard
3570
3571 Text selected with the mouse is automatically copied to the clipboard, pasting
3572  works with shift-insert.
3573 \newline
3574
3575 \newline
3576 The other good tip is to make sure you have no //c/-style paths anywhere,
3577  use /cygdrive/c/ instead.
3578  Using // invokes a network lookup which is very slow.
3579  If you think
3580 \begin_inset Quotes sld
3581 \end_inset
3582
3583 cygdrive
3584 \begin_inset Quotes srd
3585 \end_inset
3586
3587  is too long, you can change it with e.g.
3588 \layout LyX-Code
3589
3590 mount -s -u -c /mnt
3591 \layout Standard
3592
3593 SDCC sources use the unix line ending LF.
3594  Life is much easier, if you store the source tree on a drive which is mounted
3595  in binary mode.
3596  And use an editor which can handle LF-only line endings.
3597  Make sure not to commit files with windows line endings.
3598  The tabulator spacing
3599 \begin_inset LatexCommand \index{tabulator spacing (8 columns)}
3600
3601 \end_inset
3602
3603  used in the project is 8.
3604  Although a tabulator spacing of 8 is a sensible choice for programmers
3605  (it's a power of 2 and allows to display 8/16 bit signed variables without
3606  loosing columns) the plan is to move towards using only spaces in the source.
3607 \layout Subsection
3608
3609 Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
3610 \layout Standard
3611
3612
3613 \series medium
3614 Download the source package
3615 \series default
3616  either from the SDCC Subversion repository or from the
3617 \begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
3618
3619 \end_inset
3620
3621
3622 \series medium
3623 , it will be named something like sdcc
3624 \series default
3625 .src
3626 \series medium
3627 .tgz.
3628
3629 \series default
3630  SDCC is distributed with all the projects, workspaces, and files you need
3631  to build it using Visual C++ 6.0/NET (except for SDCDB and ucSim).
3632  The workspace name is 'sdcc.dsw'.
3633  Please note that as it is now, all the executables are created in a folder
3634  called sdcc
3635 \backslash
3636 bin_vc.
3637  Once built you need to copy the executables from sdcc
3638 \backslash
3639 bin_vc to sdcc
3640 \backslash
3641 bin before running SDCC.
3642
3643 \newline
3644
3645 \newline
3646 WARNING: Visual studio is very picky with line terminations; it expects
3647  the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings.
3648  When using the Subversion repository it's easiest to configure the svn
3649  client to convert automatically for you.
3650  If however you are getting a message such as "This makefile was not generated
3651  by Developer Studio etc.
3652  etc.
3653 \begin_inset Quotes srd
3654 \end_inset
3655
3656  when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
3657  need to convert the Unix style line endings to DOS style line endings.
3658  To do so you can use the
3659 \begin_inset Quotes sld
3660 \end_inset
3661
3662 unix2dos
3663 \begin_inset Quotes srd
3664 \end_inset
3665
3666  utility freely available on the internet.
3667  Doug Hawkins reported in the sdcc-user list that this works:
3668 \newline
3669
3670 \newline
3671 C:
3672 \backslash
3673 Programming
3674 \backslash
3675 SDCC> unix2dos sdcc.dsw
3676 \newline
3677 C:
3678 \backslash
3679 Programming
3680 \backslash
3681 SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
3682 \newline
3683
3684 \newline
3685 In order to build SDCC with MSVC you need win32 executables of bison.exe,
3686  flex.exe, and gawk.exe.
3687  One good place to get them is
3688 \begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
3689
3690 \end_inset
3691
3692
3693 \newline
3694
3695 \newline
3696 Download the file UnxUtils
3697 \begin_inset LatexCommand \index{UnxUtils}
3698
3699 \end_inset
3700
3701 .zip.
3702  Now you have to install the utilities and setup MSVC so it can locate the
3703  required programs.
3704  Here there are two alternatives (choose one!):
3705 \layout Enumerate
3706
3707 The easy way:
3708 \newline
3709
3710 \newline
3711 a) Extract UnxUtils.zip to your C:
3712 \backslash
3713  hard disk PRESERVING the original paths, otherwise bison won't work.
3714  (If you are using WinZip make certain that 'Use folder names' is selected)
3715 \newline
3716
3717 \newline
3718 b) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3719  in 'Show directories for:' select 'Executable files', and in the directories
3720  window add a new path: 'C:
3721 \backslash
3722 user
3723 \backslash
3724 local
3725 \backslash
3726 wbin', click ok.
3727 \newline
3728
3729 \newline
3730 (As a side effect, you get a bunch of Unix utilities that could be useful,
3731  such as diff and patch.)
3732 \layout Enumerate
3733
3734 A more compact way:
3735 \newline
3736
3737 \newline
3738 This one avoids extracting a bunch of files you may not use, but requires
3739  some extra work:
3740 \newline
3741
3742 \newline
3743 a) Create a directory were to put the tools needed, or use a directory already
3744  present.
3745  Say for example 'C:
3746 \backslash
3747 util'.
3748 \newline
3749
3750 \newline
3751 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
3752  to such directory WITHOUT preserving the original paths.
3753  (If you are using WinZip make certain that 'Use folder names' is not selected)
3754 \newline
3755
3756 \newline
3757 c) Rename bison.exe to '_bison.exe'.
3758 \newline
3759
3760 \newline
3761 d) Create a batch file 'bison.bat' in 'C:
3762 \backslash
3763 util
3764 \backslash
3765 ' and add these lines:
3766 \newline
3767 \SpecialChar ~
3768 \SpecialChar ~
3769 set BISON_SIMPLE=C:
3770 \backslash
3771 util
3772 \backslash
3773 bison.simple
3774 \newline
3775 \SpecialChar ~
3776 \SpecialChar ~
3777 set BISON_HAIRY=C:
3778 \backslash
3779 util
3780 \backslash
3781 bison.hairy
3782 \newline
3783 \SpecialChar ~
3784 \SpecialChar ~
3785 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
3786 \newline
3787
3788 \newline
3789 Steps 'c' and 'd' are needed because bison requires by default that the
3790  files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory,
3791  '/usr/local/share/' I think.
3792  So it is necessary to tell bison where those files are located if they
3793  are not in such directory.
3794  That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
3795 \newline
3796
3797 \newline
3798 e) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3799  in 'Show directories for:' select 'Executable files', and in the directories
3800  window add a new path: 'c:
3801 \backslash
3802 util', click ok.
3803  Note that you can use any other path instead of 'c:
3804 \backslash
3805 util', even the path where the Visual C++ tools are, probably: 'C:
3806 \backslash
3807 Program Files
3808 \backslash
3809 Microsoft Visual Studio
3810 \backslash
3811 Common
3812 \backslash
3813 Tools'.
3814  So you don't have to execute step 'e' :)
3815 \layout Standard
3816
3817 That is it.
3818  Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
3819  the executables from sdcc
3820 \backslash
3821 bin_vc to sdcc
3822 \backslash
3823 bin, and you can compile using SDCC.
3824 \layout Subsection
3825
3826 Building SDCC Using Borland
3827 \layout Enumerate
3828
3829 From the sdcc directory, run the command "make -f Makefile.bcc".
3830  This should regenerate all the .exe files in the bin directory except for
3831  SDCDB and ucSim.
3832 \layout Enumerate
3833
3834 If you modify any source files and need to rebuild, be aware that the dependenci
3835 es may not be correctly calculated.
3836  The safest option is to delete all .obj files and run the build again.
3837  From a Cygwin BASH prompt, this can easily be done with the command (be
3838  sure you are in the sdcc directory):
3839 \newline
3840
3841 \newline
3842
3843 \family sans
3844 \series bold
3845 find .
3846
3847 \backslash
3848 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
3849 \backslash
3850 ) -print -exec rm {}
3851 \backslash
3852 ;
3853 \family default
3854 \series default
3855
3856 \newline
3857
3858 \newline
3859 or on Windows NT/2000/XP from the command prompt with the command:
3860 \newline
3861
3862 \family sans
3863 \series bold
3864
3865 \newline
3866 del /s *.obj *.lib *.rul
3867 \family default
3868 \series default
3869  from the sdcc directory.
3870 \layout Subsection
3871
3872 Windows Install Using a ZIP Package
3873 \layout Enumerate
3874
3875 Download the binary zip package from
3876 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3877
3878 \end_inset
3879
3880  and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
3881  This should unpack to a group of sub-directories.
3882  An example directory structure after unpacking the mingw32 package is:
3883  c:
3884 \backslash
3885 sdcc
3886 \backslash
3887 bin for the executables, c:
3888 \backslash
3889 sdcc
3890 \backslash
3891 include and c:
3892 \backslash
3893 sdcc
3894 \backslash
3895 lib for the include and libraries.
3896 \layout Enumerate
3897
3898 Adjust your environment variable PATH to include the location of the bin
3899  directory or start sdcc using the full path.
3900 \layout Subsection
3901
3902 Windows Install Using the Setup Program
3903 \begin_inset LatexCommand \label{sub:Windows-Install}
3904
3905 \end_inset
3906
3907
3908 \layout Standard
3909
3910 Download the setup program
3911 \emph on
3912 sdcc-x.y.z-setup.exe
3913 \emph default
3914  for an official release from
3915 \newline
3916
3917 \begin_inset LatexCommand \url{http://sf.net/project/showfiles.php?group_id=599}
3918
3919 \end_inset
3920
3921  or a setup program for one of the snapshots
3922 \emph on
3923 sdcc-yyyymmdd-xxxx-setup.exe
3924 \emph default
3925  from
3926 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
3927
3928 \end_inset
3929
3930  and execute it.
3931  A windows typical installer will guide you through the installation process.
3932 \layout Subsection
3933
3934 VPATH
3935 \begin_inset LatexCommand \index{VPATH}
3936
3937 \end_inset
3938
3939  feature
3940 \layout Standard
3941
3942 SDCC supports the VPATH feature provided by configure and make.
3943  It allows to separate the source and build trees.
3944  Here's an example:
3945 \layout Standard
3946
3947
3948 \family typewriter
3949 cd ~\SpecialChar ~
3950 \SpecialChar ~
3951 \SpecialChar ~
3952 \SpecialChar ~
3953 \SpecialChar ~
3954 \SpecialChar ~
3955 \SpecialChar ~
3956 \SpecialChar ~
3957 \SpecialChar ~
3958 \SpecialChar ~
3959 \SpecialChar ~
3960 \SpecialChar ~
3961 \SpecialChar ~
3962 \SpecialChar ~
3963 \SpecialChar ~
3964 \SpecialChar ~
3965 \SpecialChar ~
3966 \SpecialChar ~
3967 \SpecialChar ~
3968 \SpecialChar ~
3969 \SpecialChar ~
3970 # cd $HOME
3971 \layout Standard
3972
3973
3974 \family typewriter
3975 tar -xzf sdcc.src.tar.gz\SpecialChar ~
3976 # extract source to directory sdcc
3977 \layout Standard
3978
3979
3980 \family typewriter
3981 mkdir sdcc.build\SpecialChar ~
3982 \SpecialChar ~
3983 \SpecialChar ~
3984 \SpecialChar ~
3985 \SpecialChar ~
3986 \SpecialChar ~
3987 \SpecialChar ~
3988 \SpecialChar ~
3989 \SpecialChar ~
3990 # put output in sdcc.build
3991 \layout Standard
3992
3993
3994 \family typewriter
3995 cd sdcc.build
3996 \layout Standard
3997
3998
3999 \family typewriter
4000 ../sdcc/configure\SpecialChar ~
4001 \SpecialChar ~
4002 \SpecialChar ~
4003 \SpecialChar ~
4004 \SpecialChar ~
4005 \SpecialChar ~
4006 \SpecialChar ~
4007 \SpecialChar ~
4008 # configure is doing all the magic!
4009 \layout Standard
4010
4011
4012 \family typewriter
4013 make
4014 \layout Standard
4015 \noindent
4016 That's it!
4017 \series bold
4018 configure
4019 \series default
4020  will create the directory tree will all the necessary Makefiles in ~/sdcc.build.
4021  It automagically computes the variables srcdir, top_srcdir and top_buildir
4022  for each directory.
4023  After running
4024 \series bold
4025 make
4026 \series default
4027  the generated files will be in ~/sdcc.build, while the source files stay
4028  in ~/sdcc.
4029 \newline
4030 This is not only usefull for building different binaries, e.g.
4031  when cross compiling.
4032  It also gives you a much better overview in the source tree when all the
4033  generated files are not scattered between the source files.
4034  And the best thing is: if you want to change a file you can leave the original
4035  file untouched in the source directory.
4036  Simply copy it to the build directory, edit it, enter `make clean`, `rm
4037  Makefile.dep` and `make`.
4038
4039 \series bold
4040 make
4041 \series default
4042  will do the rest for you!
4043 \layout Section
4044
4045 Building the Documentation
4046 \layout Standard
4047
4048 Add -
4049 \begin_inset ERT
4050 status Collapsed
4051
4052 \layout Standard
4053
4054 \backslash
4055 /
4056 \end_inset
4057
4058 -enable-doc to the configure arguments to build the documentation together
4059  with all the other stuff.
4060  You will need several tools (LyX, LaTeX, LaTeX2HTML, pdflatex, dvipdf,
4061  dvips and makeindex) to get the job done.
4062  Another possibility is to change to the doc directory and to type
4063 \family sans
4064 \series bold
4065
4066 \begin_inset Quotes srd
4067 \end_inset
4068
4069 make
4070 \begin_inset Quotes srd
4071 \end_inset
4072
4073
4074 \family default
4075 \series default
4076  there.
4077  You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
4078 x).
4079  Using LyX
4080 \begin_inset LatexCommand \url{http://www.lyx.org}
4081
4082 \end_inset
4083
4084  as editor is straightforward.
4085  Prebuilt documentation in html and pdf format is available from
4086 \begin_inset LatexCommand \url{http://sdcc.sf.net/snap.php}
4087
4088 \end_inset
4089
4090 .
4091 \layout Section
4092
4093 Reading the Documentation
4094 \begin_inset LatexCommand \index{Documentation}
4095
4096 \end_inset
4097
4098
4099 \layout Standard
4100
4101 Currently reading the document in pdf format is recommended, as for unknown
4102  reason the hyperlinks are working there whereas in the html version they
4103  are not
4104 \begin_inset Foot
4105 collapsed false
4106
4107 \layout Standard
4108
4109 If you should know why please drop us a note
4110 \end_inset
4111
4112 .
4113
4114 \newline
4115 You'll find the pdf version
4116 \begin_inset LatexCommand \index{PDF version of this document}
4117
4118 \end_inset
4119
4120  at
4121 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.pdf}
4122
4123 \end_inset
4124
4125 .
4126
4127 \newline
4128 A html version
4129 \begin_inset LatexCommand \index{HTML version of this document}
4130
4131 \end_inset
4132
4133  should be online at
4134 \begin_inset LatexCommand \url{http://sdcc.sf.net/doc/sdccman.html/index.html}
4135
4136 \end_inset
4137
4138 .
4139 \newline
4140 This documentation is in some aspects different from a commercial documentation:
4141
4142 \layout Itemize
4143
4144 It tries to document SDCC for several processor architectures in one document
4145  (commercially these probably would be separate documents/products).
4146  This document
4147 \begin_inset LatexCommand \index{Status of documentation}
4148
4149 \end_inset
4150
4151  currently matches SDCC for mcs51 and DS390 best and does give too few informati
4152 on about f.e.
4153  Z80, PIC14, PIC16 and HC08.
4154 \layout Itemize
4155
4156 There are many references pointing away from this documentation.
4157  Don't let this distract you.
4158  If there f.e.
4159  was a reference like
4160 \begin_inset LatexCommand \url{http://www.opencores.org}
4161
4162 \end_inset
4163
4164  together with a statement
4165 \begin_inset Quotes sld
4166 \end_inset
4167
4168 some processors which are targetted by SDCC can be implemented in a
4169 \emph on
4170 f
4171 \emph default
4172 ield
4173 \emph on
4174 p
4175 \emph default
4176 rogrammable
4177 \emph on
4178 g
4179 \emph default
4180 ate
4181 \emph on
4182 a
4183 \emph default
4184 rray
4185 \begin_inset LatexCommand \index{FPGA (field programmable gate array)}
4186
4187 \end_inset
4188
4189
4190 \begin_inset Quotes srd
4191 \end_inset
4192
4193  or
4194 \begin_inset LatexCommand \url{http://sf.net/projects/fpgac}
4195
4196 \end_inset
4197
4198
4199 \begin_inset LatexCommand \index{FpgaC ((subset of) C to FPGA compiler)}
4200
4201 \end_inset
4202
4203
4204 \begin_inset Quotes sld
4205 \end_inset
4206
4207 have you ever heard of an open source compiler that compiles a subset of
4208  C for an FPGA?
4209 \begin_inset Quotes srd
4210 \end_inset
4211
4212  we expect you to have a quick look there and come back.
4213  If you read this you are on the right track.
4214 \layout Itemize
4215
4216 Some sections attribute more space to problems, restrictions and warnings
4217  than to the solution.
4218 \layout Itemize
4219
4220 The installation section and the section about the debugger is intimidating.
4221 \layout Itemize
4222
4223 There are still lots of typos and there are more different writing styles
4224  than pictures.
4225 \layout Section
4226
4227 Testing the SDCC Compiler
4228 \begin_inset LatexCommand \label{sec:Testing-the-SDCC}
4229
4230 \end_inset
4231
4232
4233 \layout Standard
4234
4235 The first thing you should do after installing your SDCC compiler is to
4236  see if it runs.
4237  Type
4238 \family sans
4239 \series bold
4240 "sdcc -
4241 \begin_inset ERT
4242 status Collapsed
4243
4244 \layout Standard
4245
4246 \backslash
4247 /
4248 \end_inset
4249
4250 -version"
4251 \begin_inset LatexCommand \index{version}
4252
4253 \end_inset
4254
4255
4256 \family default
4257 \series default
4258  at the prompt, and the program should run and output its version like:
4259
4260 \newline
4261
4262 \family typewriter
4263 SDCC : mcs51/z80/avr/ds390/pic16/pic14/ds400/hc08 2.5.6 #4169 (May 8 2006)
4264  (UNIX)
4265 \layout Standard
4266
4267 If it doesn't run, or gives a message about not finding sdcc program, then
4268  you need to check over your installation.
4269  Make sure that the sdcc bin directory is in your executable search path
4270  defined by the PATH environment setting (
4271 \series medium
4272 see
4273 \series default
4274 section
4275 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
4276
4277 \end_inset
4278
4279 \SpecialChar ~
4280
4281 \series medium
4282 Install trouble-shooting for suggestions
4283 \series default
4284 ).
4285  Make sure that the sdcc program is in the bin folder, if not perhaps something
4286  did not install correctly.
4287 \newline
4288
4289 \newline
4290
4291 \series medium
4292 SDCC
4293 \series default
4294 is commonly installed as described in section
4295 \begin_inset Quotes sld
4296 \end_inset
4297
4298 Install and search paths
4299 \begin_inset Quotes srd
4300 \end_inset
4301
4302 .
4303 \newline
4304
4305 \newline
4306
4307 \series medium
4308 Make sure the compiler works on a very simple example.
4309  Type in the following test.c program using your favorite
4310 \series default
4311 ASCII
4312 \series medium
4313 editor:
4314 \layout Verse
4315
4316
4317 \family typewriter
4318 char test;
4319 \newline
4320
4321 \newline
4322 void main(void) {
4323 \newline
4324 \SpecialChar ~
4325 \SpecialChar ~
4326 \SpecialChar ~
4327 \SpecialChar ~
4328 test=0;
4329 \newline
4330 }
4331 \layout Standard
4332
4333
4334 \series medium
4335 Compile this using the following command:
4336 \family sans
4337 \series bold
4338 "sdcc -c test.c".
4339
4340 \family default
4341 \series default
4342
4343 \series medium
4344 If all goes well, the compiler will generate a test.asm and test.rel file.
4345  Congratulations, you've just compiled your first program with SDCC.
4346  We used the -c option to tell SDCC not to link the generated code, just
4347  to keep things simple for this step.
4348 \series default
4349
4350 \newline
4351
4352 \newline
4353
4354 \series medium
4355 The next step is to try it with the linker.
4356  Type in
4357 \family sans
4358 \series bold
4359 "sdcc test.c
4360 \family default
4361 \series default
4362 "
4363 \series medium
4364 .
4365  If all goes well the compiler will link with the libraries and produce
4366  a test.ihx output file.
4367  If this step fails
4368 \series default
4369
4370 \series medium
4371 (no test.ihx, and the linker generates warnings), then the problem is most
4372  likely that
4373 \series default
4374 SDCC
4375 \series medium
4376  cannot find the
4377 \series default
4378 /
4379 \series medium
4380 usr/local/share/sdcc/lib directory
4381 \series default
4382
4383 \series medium
4384 (see
4385 \series default
4386 section
4387 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
4388
4389 \end_inset
4390
4391 \SpecialChar ~
4392
4393 \series medium
4394 Install trouble-shooting for suggestions).
4395 \series default
4396
4397 \newline
4398
4399 \newline
4400
4401 \series medium
4402 The final test is to ensure
4403 \series default
4404 SDCC
4405 \series medium
4406  can use the
4407 \series default
4408 standard
4409 \series medium
4410  header files and libraries.
4411  Edit test.c and change it to the following:
4412 \layout Verse
4413
4414
4415 \family typewriter
4416 #include <string.h>
4417 \newline
4418
4419 \newline
4420 char str1[10];
4421 \newline
4422
4423 \newline
4424 void main(void) {
4425 \newline
4426 \SpecialChar ~
4427 \SpecialChar ~
4428 strcpy(str1, "testing");
4429 \newline
4430 }
4431 \layout Standard
4432
4433
4434 \series medium
4435 Compile this by typing
4436 \family sans
4437 \series bold
4438 "sdcc test.c"
4439 \family default
4440 \series medium
4441 .
4442  This should generate a test.ihx output file, and it should give no warnings
4443  such as not finding the string.h file.
4444  If it cannot find the string.h file, then the problem is that
4445 \series default
4446 SDCC
4447 \series medium
4448  cannot find the /usr/local/share/sdcc/include directory
4449 \series default
4450
4451 \series medium
4452 (see the
4453 \series default
4454 section
4455 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
4456
4457 \end_inset
4458
4459 \SpecialChar ~
4460
4461 \series medium
4462 Install trouble-shooting section for suggestions).
4463
4464 \series default
4465  Use option
4466 \series bold
4467 -
4468 \begin_inset ERT
4469 status Collapsed
4470
4471 \layout Standard
4472
4473 \backslash
4474 /
4475 \end_inset
4476
4477 -print-search-dirs
4478 \series default
4479
4480 \begin_inset LatexCommand \index{-\/-print-search-dirs}
4481
4482 \end_inset
4483
4484  to find exactly where SDCC is looking for the include and lib files.
4485 \layout Section
4486
4487 Install Trouble-shooting
4488 \begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
4489
4490 \end_inset
4491
4492
4493 \begin_inset LatexCommand \index{Install trouble-shooting}
4494
4495 \end_inset
4496
4497
4498 \layout Subsection
4499
4500 If SDCC does not build correctly
4501 \layout Standard
4502
4503 A thing to try is starting from scratch by unpacking the .tgz source package
4504  again in an empty directory.
4505  Configure it like:
4506 \newline
4507
4508 \newline
4509
4510 \family sans
4511 \series bold
4512 ./configure 2>&1 | tee configure.log
4513 \family default
4514 \series default
4515
4516 \newline
4517
4518 \newline
4519 and build it like:
4520 \newline
4521
4522 \newline
4523
4524 \family sans
4525 \series bold
4526 make 2>&1 | tee make.log
4527 \family default
4528 \series default
4529
4530 \newline
4531
4532 \newline
4533 If anything goes wrong, you can review the log files to locate the problem.
4534  Or a relevant part of this can be attached to an email that could be helpful
4535  when requesting help from the mailing list.
4536 \layout Subsection
4537
4538 What the
4539 \begin_inset Quotes sld
4540 \end_inset
4541
4542 ./configure
4543 \begin_inset Quotes srd
4544 \end_inset
4545
4546  does
4547 \layout Standard
4548
4549 The
4550 \begin_inset Quotes sld
4551 \end_inset
4552
4553 ./configure
4554 \begin_inset Quotes srd
4555 \end_inset
4556
4557  command is a script that analyzes your system and performs some configuration
4558  to ensure the source package compiles on your system.
4559  It will take a few minutes to run, and will compile a few tests to determine
4560  what compiler features are installed.
4561 \layout Subsection
4562
4563 What the
4564 \begin_inset Quotes sld
4565 \end_inset
4566
4567 make
4568 \begin_inset Quotes srd
4569 \end_inset
4570
4571  does
4572 \layout Standard
4573
4574 This runs the GNU make tool, which automatically compiles all the source
4575  packages into the final installed binary executables.
4576 \layout Subsection
4577
4578 What the
4579 \begin_inset Quotes sld
4580 \end_inset
4581
4582 make install
4583 \begin_inset Quotes erd
4584 \end_inset
4585
4586  command does.
4587 \layout Standard
4588
4589 This will install the compiler, other executables libraries and include
4590  files into the appropriate directories.
4591  See sections
4592 \begin_inset LatexCommand \ref{sub:Install-paths}
4593
4594 \end_inset
4595
4596 ,\SpecialChar ~
4597
4598 \begin_inset LatexCommand \ref{sub:Search-Paths}
4599
4600 \end_inset
4601
4602 \SpecialChar ~
4603 about install and search paths.
4604 \newline
4605 On most systems you will need super-user privileges to do this.
4606 \layout Section
4607
4608 Components of SDCC
4609 \layout Standard
4610
4611 SDCC is not just a compiler, but a collection of tools by various developers.
4612  These include linkers, assemblers, simulators and other components.
4613  Here is a summary of some of the components.
4614  Note that the included simulator and assembler have separate documentation
4615  which you can find in the source package in their respective directories.
4616  As SDCC grows to include support for other processors, other packages from
4617  various developers are included and may have their own sets of documentation.
4618 \newline
4619
4620 \newline
4621 You might want to look at the files which are installed in <installdir>.
4622  At the time of this writing, we find the following programs for gcc-builds:
4623 \newline
4624
4625 \newline
4626 In <installdir>/bin:
4627 \layout Itemize
4628
4629 sdcc - The compiler.
4630 \layout Itemize
4631
4632 sdcpp - The C preprocessor.
4633 \layout Itemize
4634
4635 asx8051 - The assembler for 8051 type processors.
4636 \layout Itemize
4637
4638 as-z80
4639 \series bold
4640 ,
4641 \series default
4642 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
4643 \layout Itemize
4644
4645 aslink -The linker for 8051 type processors.
4646 \layout Itemize
4647
4648 link-z80
4649 \series bold
4650 ,
4651 \series default
4652 link-gbz80 - The Z80 and GameBoy Z80 linkers.
4653 \layout Itemize
4654
4655 s51 - The ucSim 8051 simulator.
4656 \layout Itemize
4657
4658 sdcdb - The source debugger.
4659 \layout Itemize
4660
4661 packihx - A tool to pack (compress) Intel hex files.
4662 \layout Standard
4663
4664 In <installdir>/share/sdcc/include
4665 \layout Itemize
4666
4667 the include files
4668 \layout Standard
4669
4670 In <installdir>/share/sdcc/lib
4671 \layout Itemize
4672
4673 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
4674  relocatables.
4675 \layout Standard
4676
4677 In <installdir>/share/sdcc/doc
4678 \layout Itemize
4679
4680 the documentation
4681 \layout Standard
4682
4683 As development for other processors proceeds, this list will expand to include
4684  executables to support processors like AVR, PIC, etc.
4685 \layout Subsection
4686
4687 sdcc - The Compiler
4688 \layout Standard
4689
4690 This is the actual compiler, it in turn uses the c-preprocessor and invokes
4691  the assembler and linkage editor.
4692 \layout Subsection
4693
4694 sdcpp - The C-Preprocessor
4695 \layout Standard
4696
4697 The preprocessor
4698 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
4699
4700 \end_inset
4701
4702  is a modified version of the GNU cpp
4703 \begin_inset LatexCommand \index{cpp|see{sdcpp}}
4704
4705 \end_inset
4706
4707  preprocessor
4708 \begin_inset LatexCommand \url{http://gcc.gnu.org/}
4709
4710 \end_inset
4711
4712 .
4713  The C preprocessor is used to pull in #include sources, process #ifdef
4714  statements, #defines and so on.
4715 \layout Subsection
4716
4717 as
4718 \emph on
4719 xxxx
4720 \emph default
4721 , aslink, link-
4722 \emph on
4723 xxx
4724 \emph default
4725  - The Assemblers and Linkage Editors
4726 \layout Standard
4727
4728 This is retargettable assembler & linkage editor, it was developed by Alan
4729  Baldwin.
4730  John Hartman created the version for 8051, and I (Sandeep) have made some
4731  enhancements and bug fixes for it to work properly with SDCC.
4732 \layout Subsection
4733
4734 s51 - The Simulator
4735 \layout Standard
4736
4737 S51
4738 \begin_inset LatexCommand \index{s51}
4739
4740 \end_inset
4741
4742  is a freeware, opensource simulator developed by Daniel Drotos.
4743  The simulator is built as part of the build process.
4744  For more information visit Daniel's web site at:
4745 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
4746
4747 \end_inset
4748
4749 .
4750  It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
4751  XA51 family.
4752 \layout Subsection
4753
4754 sdcdb - Source Level Debugger
4755 \layout Standard
4756
4757 SDCDB
4758 \begin_inset LatexCommand \index{SDCDB (debugger)}
4759
4760 \end_inset
4761
4762  is the companion source level debugger.
4763  More about SDCDB in section
4764 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
4765
4766 \end_inset
4767
4768 .
4769  The current version of the debugger uses Daniel's Simulator S51
4770 \begin_inset LatexCommand \index{s51}
4771
4772 \end_inset
4773
4774 , but can be easily changed to use other simulators.
4775 \layout Chapter
4776
4777 Using SDCC
4778 \layout Section
4779
4780 Compiling
4781 \layout Subsection
4782
4783 Single Source File Projects
4784 \layout Standard
4785
4786 For single source file 8051 projects the process is very simple.
4787  Compile your programs with the following command
4788 \family sans
4789 \series bold
4790 "sdcc sourcefile.c".
4791
4792 \family default
4793 \series default
4794  This will compile, assemble and link your source file.
4795  Output files are as follows:
4796 \layout Itemize
4797
4798 sourcefile.asm
4799 \begin_inset LatexCommand \index{<file>.asm}
4800
4801 \end_inset
4802
4803  - Assembler source
4804 \begin_inset LatexCommand \index{Assembler source}
4805
4806 \end_inset
4807
4808  file created by the compiler
4809 \layout Itemize
4810
4811 sourcefile.lst
4812 \begin_inset LatexCommand \index{<file>.lst}
4813
4814 \end_inset
4815
4816  - Assembler listing
4817 \begin_inset LatexCommand \index{Assembler listing}
4818
4819 \end_inset
4820
4821  file created by the Assembler
4822 \layout Itemize
4823
4824 sourcefile.rst
4825 \begin_inset LatexCommand \index{<file>.rst}
4826
4827 \end_inset
4828
4829  - Assembler listing
4830 \begin_inset LatexCommand \index{Assembler listing}
4831
4832 \end_inset
4833
4834  file updated with linkedit information, created by linkage editor
4835 \layout Itemize
4836
4837 sourcefile.sym
4838 \begin_inset LatexCommand \index{<file>.sym}
4839
4840 \end_inset
4841
4842  - symbol listing
4843 \begin_inset LatexCommand \index{Symbol listing}
4844
4845 \end_inset
4846
4847  for the sourcefile, created by the assembler
4848 \layout Itemize
4849
4850 sourcefile.rel
4851 \begin_inset LatexCommand \index{<file>.rel}
4852
4853 \end_inset
4854
4855  or sourcefile.o
4856 \begin_inset LatexCommand \index{<file>.o}
4857
4858 \end_inset
4859
4860  - Object file
4861 \begin_inset LatexCommand \index{Object file}
4862
4863 \end_inset
4864
4865  created by the assembler, input to Linkage editor
4866 \layout Itemize
4867
4868 sourcefile.map
4869 \begin_inset LatexCommand \index{<file>.map}
4870
4871 \end_inset
4872
4873  - The memory map
4874 \begin_inset LatexCommand \index{Memory map}
4875
4876 \end_inset
4877
4878  for the load module, created by the Linker
4879 \layout Itemize
4880
4881 sourcefile.mem
4882 \begin_inset LatexCommand \index{<file>.mem}
4883
4884 \end_inset
4885
4886  - A file with a summary of the memory usage
4887 \layout Itemize
4888
4889 sourcefile.ihx
4890 \begin_inset LatexCommand \index{<file>.ihx}
4891
4892 \end_inset
4893
4894  - The load module in Intel hex format
4895 \begin_inset LatexCommand \index{Intel hex format}
4896
4897 \end_inset
4898
4899  (you can select the Motorola S19 format
4900 \begin_inset LatexCommand \index{Motorola S19 format}
4901
4902 \end_inset
4903
4904  with -
4905 \begin_inset ERT
4906 status Collapsed
4907
4908 \layout Standard
4909
4910 \backslash
4911 /
4912 \end_inset
4913
4914 -out-fmt-s19
4915 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
4916
4917 \end_inset
4918
4919 .
4920  If you need another format you might want to use
4921 \family sans
4922 \shape italic
4923 objdump
4924 \family default
4925 \shape default
4926
4927 \begin_inset LatexCommand \index{objdump (tool)}
4928
4929 \end_inset
4930
4931  or
4932 \family sans
4933 \shape italic
4934  srecord
4935 \family default
4936 \shape default
4937
4938 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4939
4940 \end_inset
4941
4942 ).
4943  Both formats are documented in the documentation of srecord
4944 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
4945
4946 \end_inset
4947
4948
4949 \layout Itemize
4950
4951 sourcefile.adb
4952 \begin_inset LatexCommand \index{<file>.adb}
4953
4954 \end_inset
4955
4956  - An intermediate file containing debug information needed to create the
4957  .cdb file (with -
4958 \begin_inset ERT
4959 status Collapsed
4960
4961 \layout Standard
4962
4963 \backslash
4964 /
4965 \end_inset
4966
4967 -debug
4968 \begin_inset LatexCommand \index{-\/-debug}
4969
4970 \end_inset
4971
4972 )
4973 \layout Itemize
4974
4975 sourcefile.cdb
4976 \begin_inset LatexCommand \index{<file>.cdb}
4977
4978 \end_inset
4979
4980  - An optional file (with -
4981 \begin_inset ERT
4982 status Collapsed
4983
4984 \layout Standard
4985
4986 \backslash
4987 /
4988 \end_inset
4989
4990 -debug) containing debug information.
4991  The format is documented in cdbfileformat.pdf
4992 \layout Itemize
4993
4994 sourcefile.
4995  - (no extension)
4996 \begin_inset LatexCommand \index{<file> (no extension)}
4997
4998 \end_inset
4999
5000  An optional AOMF or AOMF51
5001 \begin_inset LatexCommand \index{AOMF, AOMF51}
5002
5003 \end_inset
5004
5005
5006 \begin_inset LatexCommand \label{OMF file}
5007
5008 \end_inset
5009
5010 file containing debug information (generated with option -
5011 \begin_inset ERT
5012 status Collapsed
5013
5014 \layout Standard
5015
5016 \backslash
5017 /
5018 \end_inset
5019
5020 -debug).
5021  The (Intel)
5022 \emph on
5023  a
5024 \emph default
5025 bsolute
5026 \emph on
5027 o
5028 \emph default
5029 bject
5030 \emph on
5031 m
5032 \emph default
5033 odule
5034 \emph on
5035 f
5036 \emph default
5037 ormat is commonly used by third party tools (debuggers
5038 \begin_inset LatexCommand \index{Debugger}
5039
5040 \end_inset
5041
5042 , simulators, emulators)
5043 \layout Itemize
5044
5045 sourcefile.dump*
5046 \begin_inset LatexCommand \index{<file>.dump*}
5047
5048 \end_inset
5049
5050  - Dump file to debug the compiler it self (generated with option -
5051 \begin_inset ERT
5052 status Collapsed
5053
5054 \layout Standard
5055
5056 \backslash
5057 /
5058 \end_inset
5059
5060 -dumpall) (see section
5061 \begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
5062
5063 \end_inset
5064
5065 \SpecialChar ~
5066  and section
5067 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
5068
5069 \end_inset
5070
5071 \SpecialChar ~
5072
5073 \begin_inset Quotes sld
5074 \end_inset
5075
5076 Anatomy of the compiler
5077 \begin_inset Quotes srd
5078 \end_inset
5079
5080 ).
5081 \layout Subsection
5082
5083 Postprocessing the Intel Hex
5084 \begin_inset LatexCommand \index{Intel hex format}
5085
5086 \end_inset
5087
5088  file
5089 \layout Standard
5090
5091 In most cases this won't be needed but the Intel Hex file
5092 \begin_inset LatexCommand \index{<file>.ihx}
5093
5094 \end_inset
5095
5096  which is generated by SDCC might include lines of varying length and the
5097  addresses within the file are not guaranteed to be strictly ascending.
5098  If your toolchain or a bootloader does not like this you can use the tool
5099
5100 \family typewriter
5101 packihx
5102 \family default
5103
5104 \begin_inset LatexCommand \index{packihx (tool)}
5105
5106 \end_inset
5107
5108  which is part of the SDCC distribution:
5109 \newline
5110
5111 \newline
5112
5113 \family sans
5114 \series bold
5115  packihx sourcefile.ihx >sourcefile.hex
5116 \family default
5117 \series default
5118
5119 \newline
5120
5121 \newline
5122 The separately available
5123 \emph on
5124  srecord
5125 \emph default
5126
5127 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
5128
5129 \end_inset
5130
5131  package additionally allows to set undefined locations to a predefined
5132  value, to insert checksums
5133 \begin_inset LatexCommand \index{checksum}
5134
5135 \end_inset
5136
5137  of various flavours (crc, add, xor) and to perform other manipulations
5138  (convert, split, crop, offset, ...).
5139
5140 \newline
5141
5142 \newline
5143
5144 \family sans
5145 \series bold
5146 srec_cat\SpecialChar ~
5147 \SpecialChar ~
5148 sourcefile.ihx -intel\SpecialChar ~
5149 \SpecialChar ~
5150 -o sourcefile.hex -intel
5151 \newline
5152
5153 \newline
5154
5155 \family default
5156 \series default
5157 An example for a more complex command line
5158 \begin_inset Foot
5159 collapsed false
5160
5161 \layout Standard
5162
5163 the command backfills
5164 \begin_inset LatexCommand \index{backfill unused memory}
5165
5166 \end_inset
5167
5168  unused memory with 0x12 and the overall 16 bit sum of the complete 64 kByte
5169  block is zero.
5170  If the program counter on an mcs51 runs wild the backfill pattern 0x12
5171  will be interpreted as an
5172 \family typewriter
5173 lcall
5174 \family default
5175  to address
5176 \family typewriter
5177 0x1212
5178 \family default
5179  (where an emergency routine could sit).
5180 \end_inset
5181
5182  could look like:
5183 \newline
5184
5185 \newline
5186
5187 \family sans
5188 \series bold
5189 \size footnotesize
5190 srec_cat\SpecialChar ~
5191 sourcefile.ihx -intel\SpecialChar ~
5192 \SpecialChar ~
5193 -fill 0x12 0x0000 0xfffe\SpecialChar ~
5194 -little-endian-checksum-nega
5195 tive 0xfffe 0x02 0x02\SpecialChar ~
5196 \SpecialChar ~
5197 -o sourcefile.hex -intel
5198 \size default
5199
5200 \newline
5201
5202 \newline
5203
5204 \family default
5205 \series default
5206 The srecord package is available at
5207 \begin_inset LatexCommand \url{http://sf.net/projects/srecord}
5208
5209 \end_inset
5210
5211  .
5212 \layout Subsection
5213
5214 Projects with Multiple Source Files
5215 \layout Standard
5216
5217 SDCC can compile only ONE file at a time.
5218  Let us for example assume that you have a project containing the following
5219  files:
5220 \newline
5221
5222 \newline
5223 foo1.c (contains some functions)
5224 \newline
5225 foo2.c (contains some more functions)
5226 \newline
5227 foomain.c (contains more functions and the function main)
5228 \newline
5229
5230 \size footnotesize
5231
5232 \newline
5233
5234 \size default
5235 The first two files will need to be compiled separately with the commands:
5236 \size footnotesize
5237
5238 \size default
5239
5240 \newline
5241
5242 \newline
5243
5244 \family sans
5245 \series bold
5246 sdcc\SpecialChar ~
5247 -c\SpecialChar ~
5248 foo1.c
5249 \family default
5250 \series default
5251 \size footnotesize
5252
5253 \newline
5254
5255 \family sans
5256 \series bold
5257 \size default
5258 sdcc\SpecialChar ~
5259 -c\SpecialChar ~
5260 foo2.c
5261 \family default
5262 \series default
5263
5264 \newline
5265
5266 \newline
5267 Then compile the source file containing the
5268 \emph on
5269 main()
5270 \emph default
5271  function and link
5272 \begin_inset LatexCommand \index{Linker}
5273
5274 \end_inset
5275
5276  the files together with the following command:
5277 \newline
5278
5279 \newline
5280
5281 \family sans
5282 \series bold
5283 sdcc\SpecialChar ~
5284 foomain.c\SpecialChar ~
5285 foo1.rel\SpecialChar ~
5286 foo2.rel
5287 \family default
5288 \series default
5289
5290 \begin_inset LatexCommand \index{<file>.rel}
5291
5292 \end_inset
5293
5294
5295 \newline
5296
5297 \newline
5298 Alternatively,
5299 \emph on
5300 foomain.c
5301 \emph default
5302 can be separately compiled as well:
5303 \family sans
5304 \series bold
5305
5306 \newline
5307
5308 \newline
5309 sdcc\SpecialChar ~
5310 -c\SpecialChar ~
5311 foomain.c
5312 \newline
5313 sdcc foomain.rel foo1.rel foo2.rel
5314 \newline
5315
5316 \newline
5317
5318 \family default
5319 \series default
5320 The file containing the
5321 \emph on
5322 main()
5323 \emph default
5324  function
5325 \emph on
5326
5327 \emph default
5328 \noun on
5329 must
5330 \noun default
5331  be the
5332 \noun on
5333 first
5334 \noun default
5335  file specified in the command line, since the linkage editor processes
5336  file in the order they are presented to it.
5337  The linker is invoked from SDCC using a script file with extension .lnk
5338 \begin_inset LatexCommand \index{<file>.lnk}
5339
5340 \end_inset
5341
5342 .
5343  You can view this file to troubleshoot linking problems such as those arising
5344  from missing libraries.
5345 \layout Subsection
5346
5347 Projects with Additional Libraries
5348 \begin_inset LatexCommand \index{Libraries}
5349
5350 \end_inset
5351
5352
5353 \layout Standard
5354
5355 Some reusable routines may be compiled into a library, see the documentation
5356  for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
5357  for how to create a
5358 \emph on
5359 .lib
5360 \begin_inset LatexCommand \index{<file>.lib}
5361
5362 \end_inset
5363
5364
5365 \emph default
5366  library file.
5367  Libraries created in this manner can be included in the command line.
5368  Make sure you include the -L <library-path> option to tell the linker where
5369  to look for these files if they are not in the current directory.
5370  Here is an example, assuming you have the source file
5371 \emph on
5372 foomain.c
5373 \emph default
5374  and a library
5375 \emph on
5376  foolib.lib
5377 \emph default
5378  in the directory
5379 \emph on
5380 mylib
5381 \emph default
5382  (if that is not the same as your current project):
5383 \newline
5384
5385 \newline
5386
5387 \family sans
5388 \series bold
5389 sdcc foomain.c foolib.lib -L mylib
5390 \newline
5391
5392 \newline
5393
5394 \family default
5395 \series default
5396 Note here that
5397 \emph on
5398  mylib
5399 \emph default
5400  must be an absolute path name.
5401 \newline
5402
5403 \newline
5404 The most efficient way to use libraries is to keep separate modules in separate
5405  source files.
5406  The lib file now should name all the modules.rel
5407 \begin_inset LatexCommand \index{<file>.rel}
5408
5409 \end_inset
5410
5411  files.
5412  For an example see the standard library file
5413 \emph on
5414 libsdcc.lib
5415 \emph default
5416  in the directory <installdir>/share/lib/small.
5417 \layout Subsection
5418
5419 Using sdcclib to Create and Manage Libraries
5420 \begin_inset LatexCommand \index{sdcclib}
5421
5422 \end_inset
5423
5424
5425 \layout Standard
5426
5427 Alternatively, instead of having a .rel file for each entry on the library
5428  file as described in the preceding section, sdcclib can be used to embed
5429  all the modules belonging to such library in the library file itself.
5430  This results in a larger library file, but it greatly reduces the number
5431  of disk files accessed by the linker.
5432   Additionally, the packed library file contains an index of all include
5433  modules and symbols that significantly speeds up the linking process.
5434  To display a list of options supported by sdcclib type:
5435 \newline
5436
5437 \layout Standard
5438
5439
5440 \family sans
5441 \series bold
5442 sdcclib -?
5443 \begin_inset LatexCommand \index{sdcclib}
5444
5445 \end_inset
5446
5447
5448 \newline
5449
5450 \newline
5451
5452 \family default
5453 \series default
5454 To create a new library file, start by compiling all the required modules.
5455  For example:
5456 \newline
5457
5458 \layout Standard
5459
5460
5461 \family sans
5462 \series bold
5463 sdcc -c _divsint.c
5464 \layout Standard
5465
5466
5467 \family sans
5468 \series bold
5469 sdcc -c _divuint.c
5470 \layout Standard
5471
5472
5473 \family sans
5474 \series bold
5475 sdcc -c _modsint.c
5476 \layout Standard
5477
5478
5479 \family sans
5480 \series bold
5481 sdcc -c _moduint.c
5482 \layout Standard
5483
5484
5485 \family sans
5486 \series bold
5487 sdcc -c _mulint.c
5488 \newline
5489
5490 \layout Standard
5491
5492 This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
5493  and _mulint.rel.
5494  The next step is to add the .rel files to the library file:
5495 \newline
5496
5497 \layout Standard
5498
5499
5500 \family sans
5501 \series bold
5502 sdcclib libint.lib _divsint.rel
5503 \family default
5504
5505 \begin_inset LatexCommand \index{sdcclib}
5506
5507 \end_inset
5508
5509
5510 \layout Standard
5511
5512
5513 \family sans
5514 \series bold
5515 sdcclib libint.lib _divuint.rel
5516 \layout Standard
5517
5518
5519 \family sans
5520 \series bold
5521 sdcclib libint.lib _modsint.rel
5522 \layout Standard
5523
5524
5525 \family sans
5526 \series bold
5527 sdcclib libint.lib _moduint.rel
5528 \layout Standard
5529
5530
5531 \family sans
5532 \series bold
5533 sdcclib libint.lib _mulint.rel
5534 \series default
5535
5536 \newline
5537
5538 \layout Standard
5539
5540 If the file already exists in the library, it will be replaced.
5541  To see what modules and symbols are included in the library, options -s
5542  and -m are available.
5543  For example:
5544 \newline
5545
5546 \newline
5547
5548 \family sans
5549 \series bold
5550 sdcclib -s libint.lib
5551 \family default
5552
5553 \begin_inset LatexCommand \index{sdcclib}
5554
5555 \end_inset
5556
5557
5558 \newline
5559
5560 \family typewriter
5561 \series default
5562 _divsint.rel:
5563 \layout Standard
5564
5565
5566 \family typewriter
5567 __divsint_a_1_1
5568 \layout Standard
5569
5570
5571 \family typewriter
5572 __divsint_PARM_2
5573 \layout Standard
5574
5575
5576 \family typewriter
5577 __divsint
5578 \newline
5579 _divuint.rel:
5580 \layout Standard
5581
5582
5583 \family typewriter
5584 __divuint_a_1_1
5585 \layout Standard
5586
5587
5588 \family typewriter
5589 __divuint_PARM_2
5590 \layout Standard
5591
5592
5593 \family typewriter
5594 __divuint_reste_1_1
5595 \layout Standard
5596
5597
5598 \family typewriter
5599 __divuint_count_1_1
5600 \layout Standard
5601
5602
5603 \family typewriter
5604 __divuint
5605 \newline
5606 _modsint.rel:
5607 \layout Standard
5608
5609
5610 \family typewriter
5611 __modsint_a_1_1
5612 \layout Standard
5613
5614
5615 \family typewriter
5616 __modsint_PARM_2
5617 \layout Standard
5618
5619
5620 \family typewriter
5621 __modsint
5622 \newline
5623 _moduint.rel:
5624 \layout Standard
5625
5626
5627 \family typewriter
5628 __moduint_a_1_1
5629 \layout Standard
5630
5631
5632 \family typewriter
5633 __moduint_PARM_2
5634 \layout Standard
5635
5636
5637 \family typewriter
5638 __moduint_count_1_1
5639 \layout Standard
5640
5641
5642 \family typewriter
5643 __moduint
5644 \newline
5645 _mulint.rel:
5646 \layout Standard
5647
5648
5649 \family typewriter
5650 __mulint_PARM_2
5651 \layout Standard
5652
5653
5654 \family typewriter
5655 __mulint
5656 \family default
5657 \series bold
5658
5659 \newline
5660
5661 \layout Standard
5662 \added_space_bottom bigskip
5663 If the source files are compiled using -
5664 \begin_inset ERT
5665 status Collapsed
5666
5667 \layout Standard
5668
5669 \backslash
5670 /
5671 \end_inset
5672
5673 -debug
5674 \begin_inset LatexCommand \index{-\/-debug}
5675
5676 \end_inset
5677
5678 , the corresponding debug information file .adb will be include in the library
5679  file as well.
5680  The library files created with sdcclib are plain text files, so they can
5681  be viewed with a text editor.
5682  It is not recomended to modify a library file created with sdcclib using
5683  a text editor, as there are file indexes numbers located accross the file
5684  used by the linker to quickly locate the required module to link.
5685  Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
5686  it can be safely deleted, since all the information required for linking
5687  is embedded in the library file itself.
5688  Library files created using sdcclib are used as described in the preceding
5689  sections.
5690 \layout Section
5691
5692 Command Line Options
5693 \begin_inset LatexCommand \index{Command Line Options}
5694
5695 \end_inset
5696
5697
5698 \layout Subsection
5699
5700 Processor Selection Options
5701 \begin_inset LatexCommand \index{Options processor selection}
5702
5703 \end_inset
5704
5705
5706 \begin_inset LatexCommand \index{Processor selection options}
5707
5708 \end_inset
5709
5710
5711 \layout List
5712 \labelwidthstring 00.00.0000
5713
5714
5715 \series bold
5716 -mmcs51
5717 \begin_inset LatexCommand \index{-mmcs51}
5718
5719 \end_inset
5720
5721
5722 \series default
5723  Generate code for the Intel MCS51
5724 \begin_inset LatexCommand \index{MCS51}
5725
5726 \end_inset
5727
5728  family of processors.
5729  This is the default processor target.
5730 \layout List
5731 \labelwidthstring 00.00.0000
5732
5733
5734 \series bold
5735 -mds390
5736 \begin_inset LatexCommand \index{-mds390}
5737
5738 \end_inset
5739
5740
5741 \series default
5742  Generate code for the Dallas DS80C390
5743 \begin_inset LatexCommand \index{DS80C390}
5744
5745 \end_inset
5746
5747  processor.
5748 \layout List
5749 \labelwidthstring 00.00.0000
5750
5751
5752 \series bold
5753 -mds400
5754 \begin_inset LatexCommand \index{-mds400}
5755
5756 \end_inset
5757
5758
5759 \series default
5760  Generate code for the Dallas DS80C400
5761 \begin_inset LatexCommand \index{DS80C400}
5762
5763 \end_inset
5764
5765  processor.
5766 \layout List
5767 \labelwidthstring 00.00.0000
5768
5769
5770 \series bold
5771 -mhc08
5772 \begin_inset LatexCommand \index{-mhc08}
5773
5774 \end_inset
5775
5776
5777 \series default
5778  Generate code for the Freescale/Motorola HC08
5779 \begin_inset LatexCommand \index{HC08}
5780
5781 \end_inset
5782
5783  family of processors.
5784 \layout List
5785 \labelwidthstring 00.00.0000
5786
5787
5788 \series bold
5789 -mz80
5790 \begin_inset LatexCommand \index{-mz80}
5791
5792 \end_inset
5793
5794
5795 \series default
5796  Generate code for the Zilog Z80
5797 \begin_inset LatexCommand \index{Z80}
5798
5799 \end_inset
5800
5801  family of processors.
5802 \layout List
5803 \labelwidthstring 00.00.0000
5804
5805
5806 \series bold
5807 -mgbz80
5808 \begin_inset LatexCommand \index{-mgbz80}
5809
5810 \end_inset
5811
5812
5813 \series default
5814  Generate code for the GameBoy Z80
5815 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
5816
5817 \end_inset
5818
5819  processor (Not actively maintained).
5820 \layout List
5821 \labelwidthstring 00.00.0000
5822
5823
5824 \series bold
5825 -mavr
5826 \begin_inset LatexCommand \index{-mavr}
5827
5828 \end_inset
5829
5830
5831 \series default
5832  Generate code for the Atmel AVR
5833 \begin_inset LatexCommand \index{AVR}
5834
5835 \end_inset
5836
5837  processor (Not maintained, not complete).
5838  AVR users should probably have a look at winavr
5839 \begin_inset LatexCommand \url{http://sourceforge.net/projects/winavr}
5840
5841 \end_inset
5842
5843  or
5844 \begin_inset LatexCommand \url{http://www.avrfreaks.net/index.php?name=PNphpBB2&file=index}
5845
5846 \end_inset
5847
5848 .
5849 \layout Comment
5850
5851 I think it is fair to direct users there for now.
5852  Open source is also about avoiding unnecessary work .
5853  But I didn't find the 'official' link.
5854 \layout List
5855 \labelwidthstring 00.00.0000
5856
5857
5858 \series bold
5859 -mpic14
5860 \begin_inset LatexCommand \index{-mpic14}
5861
5862 \end_inset
5863
5864
5865 \series default
5866  Generate code for the Microchip PIC 14
5867 \begin_inset LatexCommand \index{PIC14}
5868
5869 \end_inset
5870
5871 -bit processors (p16f84 and variants.
5872  In development, not complete).
5873 \layout Comment
5874
5875 p16f627 p16f628 p16f84 p16f873 p16f877?
5876 \layout List
5877 \labelwidthstring 00.00.0000
5878
5879
5880 \series bold
5881 -mpic16
5882 \begin_inset LatexCommand \index{-mpic16}
5883
5884 \end_inset
5885
5886
5887 \series default
5888  Generate code for the Microchip PIC 16
5889 \begin_inset LatexCommand \index{PIC16}
5890
5891 \end_inset
5892
5893 -bit processors (p18f452 and variants.
5894  In development, not complete).
5895 \layout List
5896 \labelwidthstring 00.00.0000
5897
5898
5899 \series bold
5900 -mtlcs900h
5901 \series default
5902  Generate code for the Toshiba TLCS-900H
5903 \begin_inset LatexCommand \index{TLCS-900H}
5904
5905 \end_inset
5906
5907  processor (Not maintained, not complete).
5908 \layout List
5909 \added_space_bottom bigskip \labelwidthstring 00.00.0000
5910
5911
5912 \series bold
5913 -mxa51
5914 \begin_inset LatexCommand \index{-mxa51}
5915
5916 \end_inset
5917
5918
5919 \series default
5920  Generate code for the Phillips XA51
5921 \begin_inset LatexCommand \index{XA51}
5922
5923 \end_inset
5924
5925  processor (Not maintained, not complete).
5926 \layout Subsection
5927
5928 Preprocessor Options
5929 \begin_inset LatexCommand \index{Options preprocessor}
5930
5931 \end_inset
5932
5933
5934 \begin_inset LatexCommand \index{Preprocessor options}
5935
5936 \end_inset
5937
5938
5939 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5940
5941 \end_inset
5942
5943
5944 \layout List
5945 \labelwidthstring 00.00.0000
5946
5947
5948 \series bold
5949 -I<path>
5950 \begin_inset LatexCommand \index{-I<path>}
5951
5952 \end_inset
5953
5954
5955 \series default
5956  The additional location where the pre processor will look for <..h> or
5957 \begin_inset Quotes eld
5958 \end_inset
5959
5960 ..h
5961 \begin_inset Quotes erd
5962 \end_inset
5963
5964  files.
5965 \layout List
5966 \labelwidthstring 00.00.0000
5967
5968
5969 \series bold
5970 -D<macro[=value]>
5971 \begin_inset LatexCommand \index{-D<macro[=value]>}
5972
5973 \end_inset
5974
5975
5976 \series default
5977  Command line definition of macros.
5978  Passed to the preprocessor.
5979 \layout List
5980 \labelwidthstring 00.00.0000
5981
5982
5983 \series bold
5984 -M
5985 \begin_inset LatexCommand \index{-M}
5986
5987 \end_inset
5988
5989
5990 \series default
5991  Tell the preprocessor to output a rule suitable for make describing the
5992  dependencies of each object file.
5993  For each source file, the preprocessor outputs one make-rule whose target
5994  is the object file name for that source file and whose dependencies are
5995  all the files `#include'd in it.
5996  This rule may be a single line or may be continued with `
5997 \backslash
5998 '-newline if it is long.
5999  The list of rules is printed on standard output instead of the preprocessed
6000  C program.
6001  `-M' implies `-E
6002 \begin_inset LatexCommand \index{-E}
6003
6004 \end_inset
6005
6006 '.
6007 \layout List
6008 \labelwidthstring 00.00.0000
6009
6010
6011 \series bold
6012 -C
6013 \begin_inset LatexCommand \index{-C}
6014
6015 \end_inset
6016
6017
6018 \series default
6019  Tell the preprocessor not to discard comments.
6020  Used with the `-E' option.
6021 \layout List
6022 \labelwidthstring 00.00.0000
6023
6024
6025 \series bold
6026 -MM
6027 \begin_inset LatexCommand \index{-MM}
6028
6029 \end_inset
6030
6031
6032 \size large
6033 \bar under
6034
6035 \series default
6036 \size default
6037 \bar default
6038 Like `-M' but the output mentions only the user header files included with
6039  `#include
6040 \begin_inset Quotes eld
6041 \end_inset
6042
6043 file"'.
6044  System header files included with `#include <file>' are omitted.
6045 \layout List
6046 \labelwidthstring 00.00.0000
6047
6048
6049 \series bold
6050 -Aquestion(answer)
6051 \begin_inset LatexCommand \index{-Aquestion(answer)}
6052
6053 \end_inset
6054
6055
6056 \series default
6057  Assert the answer answer for question, in case it is tested with a preprocessor
6058  conditional such as `#if #question(answer)'.
6059  `-A-' disables the standard assertions that normally describe the target
6060  machine.
6061 \layout List
6062 \labelwidthstring 00.00.0000
6063
6064
6065 \series bold
6066 -Umacro
6067 \begin_inset LatexCommand \index{-Umacro}
6068
6069 \end_inset
6070
6071
6072 \series default
6073  Undefine macro macro.
6074  `-U' options are evaluated after all `-D' options, but before any `-include'
6075  and `-imacros' options.
6076 \layout List
6077 \labelwidthstring 00.00.0000
6078
6079
6080 \series bold
6081 -dM
6082 \begin_inset LatexCommand \index{-dM}
6083
6084 \end_inset
6085
6086
6087 \series default
6088  Tell the preprocessor to output only a list of the macro definitions that
6089  are in effect at the end of preprocessing.
6090  Used with the `-E' option.
6091 \layout List
6092 \labelwidthstring 00.00.0000
6093
6094
6095 \series bold
6096 -dD
6097 \begin_inset LatexCommand \index{-dD}
6098
6099 \end_inset
6100
6101
6102 \series default
6103  Tell the preprocessor to pass all macro definitions into the output, in
6104  their proper sequence in the rest of the output.
6105 \layout List
6106 \labelwidthstring 00.00.0000
6107
6108
6109 \series bold
6110 -dN
6111 \begin_inset LatexCommand \index{-dN}
6112
6113 \end_inset
6114
6115
6116 \size large
6117 \bar under
6118
6119 \series default
6120 \size default
6121 \bar default
6122 Like `-dD' except that the macro arguments and contents are omitted.
6123  Only `#define name' is included in the output.
6124 \layout List
6125 \labelwidthstring 00.00.0000
6126
6127
6128 \series bold
6129 -pedantic-parse-number
6130 \begin_inset LatexCommand \index{-pedantic-parse-number}
6131
6132 \end_inset
6133
6134
6135 \size large
6136 \bar under
6137
6138 \series default
6139 \size default
6140 \bar default
6141 Pedentic parse numbers so that situations like 0xfe-LO_B(3) are parsed properly
6142  and the macro LO_B(3) gets expanded.
6143  See also #pragma pedantic_parse_number in section
6144 \begin_inset LatexCommand \ref{sec:Pragmas}
6145
6146 \end_inset
6147
6148
6149 \emph on
6150 Note: this functionality is not in conformance with standard!
6151
6152 \layout List
6153 \added_space_bottom bigskip \labelwidthstring 00.00.0000
6154
6155
6156 \series bold
6157 -Wp\SpecialChar ~
6158 preprocessorOption[,preprocessorOption]
6159 \series default
6160
6161 \begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
6162
6163 \end_inset
6164
6165 ...
6166  Pass the preprocessorOption to the preprocessor
6167 \family typewriter
6168 sdcpp
6169 \family default
6170
6171 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
6172
6173 \end_inset
6174
6175 .
6176  SDCC uses an adapted version of the preprocessor
6177 \emph on
6178 cpp
6179 \emph default
6180  of the GNU Compiler Collection
6181 \begin_inset LatexCommand \index{gcc (GNU Compiler Collection)}
6182
6183 \end_inset
6184
6185  (
6186 \emph on
6187 gcc
6188 \emph default
6189
6190 \begin_inset LatexCommand \url{http://gcc.gnu.org/}
6191
6192 \end_inset
6193
6194 ), if you need more dedicated options please refer to the GCC\SpecialChar ~
6195 4.1.1\SpecialChar ~
6196 CPP\SpecialChar ~
6197 Manual
6198  at
6199 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
6200
6201 \end_inset
6202
6203 .
6204 \layout Subsection
6205
6206 Linker Options
6207 \begin_inset LatexCommand \index{Options linker}
6208
6209 \end_inset
6210
6211
6212 \begin_inset LatexCommand \index{Linker options}
6213
6214 \end_inset
6215
6216
6217 \layout List
6218 \labelwidthstring 00.00.0000
6219
6220
6221 \series bold
6222 -L\SpecialChar ~
6223 -
6224 \series default
6225
6226 \begin_inset ERT
6227 status Collapsed
6228
6229 \layout Standard
6230
6231 \backslash
6232 /
6233 \end_inset
6234
6235
6236 \series bold
6237 -lib-path
6238 \begin_inset LatexCommand \index{-\/-lib-path <path>}
6239
6240 \end_inset
6241
6242
6243 \begin_inset LatexCommand \index{-L -\/-lib-path}
6244
6245 \end_inset
6246
6247
6248 \series default
6249 \SpecialChar ~
6250 <absolute path to additional libraries> This option is passed to the linkage
6251  editor's additional libraries
6252 \begin_inset LatexCommand \index{Libraries}
6253
6254 \end_inset
6255
6256  search path.
6257  The path name must be absolute.
6258  Additional library files may be specified in the command line.
6259  See section Compiling programs for more details.
6260 \layout List
6261 \labelwidthstring 00.00.0000
6262
6263
6264 \series bold
6265 -
6266 \begin_inset ERT
6267 status Collapsed
6268
6269 \layout Standard
6270
6271 \backslash
6272 /
6273 \end_inset
6274
6275 -xram-loc
6276 \series default
6277
6278 \begin_inset LatexCommand \index{-\/-xram-loc <Value>}
6279
6280 \end_inset
6281
6282 \SpecialChar ~
6283 <Value> The start location of the external ram
6284 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
6285
6286 \end_inset
6287
6288 , default value is 0.
6289  The value entered can be in Hexadecimal or Decimal format, e.g.: -
6290 \begin_inset ERT
6291 status Collapsed
6292
6293 \layout Standard
6294
6295 \backslash
6296 /
6297 \end_inset
6298
6299 -xram-loc 0x8000 or -
6300 \begin_inset ERT
6301 status Collapsed
6302
6303 \layout Standard
6304
6305 \backslash
6306 /
6307 \end_inset
6308
6309 -xram-loc 32768.
6310 \layout List
6311 \labelwidthstring 00.00.0000
6312
6313
6314 \series bold
6315 -
6316 \begin_inset ERT
6317 status Collapsed
6318
6319 \layout Standard
6320
6321 \backslash
6322 /
6323 \end_inset
6324
6325 -code-loc
6326 \series default
6327
6328 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
6329
6330 \end_inset
6331
6332 \SpecialChar ~
6333 <Value> The start location of the code
6334 \begin_inset LatexCommand \index{code}
6335
6336 \end_inset
6337
6338  segment, default value 0.
6339  Note when this option is used the interrupt vector table
6340 \begin_inset LatexCommand \index{interrupt vector table}
6341
6342 \end_inset
6343
6344  is also relocated to the given address.
6345  The value entered can be in Hexadecimal or Decimal format, e.g.: -
6346 \begin_inset ERT
6347 status Collapsed
6348
6349 \layout Standard
6350
6351 \backslash
6352 /
6353 \end_inset
6354
6355 -code-loc 0x8000 or -
6356 \begin_inset ERT
6357 status Collapsed
6358
6359 \layout Standard
6360
6361 \backslash
6362 /
6363 \end_inset
6364
6365 -code-loc 32768.
6366 \layout List
6367 \labelwidthstring 00.00.0000
6368
6369
6370 \series bold
6371 -
6372 \begin_inset ERT
6373 status Collapsed
6374
6375 \layout Standard
6376
6377 \backslash
6378 /
6379 \end_inset
6380
6381 -stack-loc
6382 \series default
6383
6384 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
6385
6386 \end_inset
6387
6388 \SpecialChar ~
6389 <Value> By default the stack
6390 \begin_inset LatexCommand \index{stack}
6391
6392 \end_inset
6393
6394  is placed after the data segment.
6395  Using this option the stack can be placed anywhere in the internal memory
6396  space of the 8051.
6397  The value entered can be in Hexadecimal or Decimal format, e.g.
6398  -
6399 \begin_inset ERT
6400 status Collapsed
6401
6402 \layout Standard
6403
6404 \backslash
6405 /
6406 \end_inset
6407
6408 -stack-loc 0x20 or -
6409 \begin_inset ERT
6410 status Collapsed
6411
6412 \layout Standard
6413
6414 \backslash
6415 /
6416 \end_inset
6417
6418 -stack-loc 32.
6419  Since the sp register is incremented before a push or call, the initial
6420  sp will be set to one byte prior the provided value.
6421  The provided value should not overlap any other memory areas such as used
6422  register banks or the data segment and with enough space for the current
6423  application.
6424  The
6425 \series bold
6426 -
6427 \begin_inset ERT
6428 status Collapsed
6429
6430 \layout Standard
6431
6432 \backslash
6433 /
6434 \end_inset
6435
6436 -pack-iram
6437 \series default
6438 \SpecialChar ~
6439
6440 \begin_inset LatexCommand \index{-\/-pack-iram}
6441
6442 \end_inset
6443
6444  option (which is now a default setting) will override this setting, so
6445  you should also specify the
6446 \series bold
6447 -
6448 \begin_inset ERT
6449 status Collapsed
6450
6451 \layout Standard
6452
6453 \backslash
6454 /
6455 \end_inset
6456
6457 -no-pack-iram
6458 \series default
6459 \SpecialChar ~
6460
6461 \begin_inset LatexCommand \index{-\/-no-pack-iram}
6462
6463 \end_inset
6464
6465  option if you need to manually place the stack.
6466 \layout List
6467 \labelwidthstring 00.00.0000
6468
6469
6470 \series bold
6471 -
6472 \begin_inset ERT
6473 status Collapsed
6474
6475 \layout Standard
6476
6477 \backslash
6478 /
6479 \end_inset
6480
6481 -xstack-loc
6482 \series default
6483
6484 \begin_inset LatexCommand \index{-\/-xstack-loc <Value>}
6485
6486 \end_inset
6487
6488 \SpecialChar ~
6489 <Value> By default the external stack
6490 \begin_inset LatexCommand \index{xstack}
6491
6492 \end_inset
6493
6494  is placed after the pdata
6495 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
6496
6497 \end_inset
6498
6499  segment.
6500  Using this option the xstack can be placed anywhere in the external memory
6501  space of the 8051.
6502  The value entered can be in Hexadecimal or Decimal format, e.g.
6503  -
6504 \begin_inset ERT
6505 status Collapsed
6506
6507 \layout Standard
6508
6509 \backslash
6510 /
6511 \end_inset
6512
6513 -xstack-loc 0x8000 or -
6514 \begin_inset ERT
6515 status Collapsed
6516
6517 \layout Standard
6518
6519 \backslash
6520 /
6521 \end_inset
6522
6523 -stack-loc 32768.
6524  The provided value should not overlap any other memory areas such as the
6525  pdata or xdata segment and with enough space for the current application.
6526 \layout List
6527 \labelwidthstring 00.00.0000
6528
6529
6530 \series bold
6531 -
6532 \begin_inset ERT
6533 status Collapsed
6534
6535 \layout Standard
6536
6537 \backslash
6538 /
6539 \end_inset
6540
6541 -data-loc
6542 \series default
6543
6544 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
6545
6546 \end_inset
6547
6548 \SpecialChar ~
6549 <Value> The start location of the internal ram data
6550 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
6551
6552 \end_inset
6553
6554  segment.
6555  The value entered can be in Hexadecimal or Decimal format, eg.
6556  -
6557 \begin_inset ERT
6558 status Collapsed
6559
6560 \layout Standard
6561
6562 \backslash
6563 /
6564 \end_inset
6565
6566 -data-loc 0x20 or -
6567 \begin_inset ERT
6568 status Collapsed
6569
6570 \layout Standard
6571
6572 \backslash
6573 /
6574 \end_inset
6575
6576 -data-loc 32.
6577  (By default, the start location of the internal ram data segment  is set
6578  as low as possible in memory, taking into account the used register banks
6579  and the bit segment at address 0x20.
6580  For example if register banks 0 and 1 are used without bit variables, the
6581  data segment will be set, if -
6582 \begin_inset ERT
6583 status Collapsed
6584
6585 \layout Standard
6586
6587 \backslash
6588 /
6589 \end_inset
6590
6591 -data-loc is not used, to location 0x10.)
6592 \layout List
6593 \labelwidthstring 00.00.0000
6594
6595
6596 \series bold
6597 -
6598 \begin_inset ERT
6599 status Collapsed
6600
6601 \layout Standard
6602
6603 \backslash
6604 /
6605 \end_inset
6606
6607 -idata-loc
6608 \series default
6609
6610 \begin_inset LatexCommand \index{-\/-idata-loc <Value>}
6611
6612 \end_inset
6613
6614 \SpecialChar ~
6615 <Value> The start location of the indirectly addressable internal ram
6616 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
6617
6618 \end_inset
6619
6620  of the 8051, default value is 0x80.
6621  The value entered can be in Hexadecimal or Decimal format, eg.
6622  -
6623 \begin_inset ERT
6624 status Collapsed
6625
6626 \layout Standard
6627
6628 \backslash
6629 /
6630 \end_inset
6631
6632 -idata-loc 0x88 or -
6633 \begin_inset ERT
6634 status Collapsed
6635
6636 \layout Standard
6637
6638 \backslash
6639 /
6640 \end_inset
6641
6642 -idata-loc 136.
6643 \layout List
6644 \labelwidthstring 00.00.0000
6645
6646
6647 \series bold
6648 -
6649 \begin_inset ERT
6650 status Collapsed
6651
6652 \layout Standard
6653
6654 \backslash
6655 /
6656 \end_inset
6657
6658 -bit-loc
6659 \series default
6660 \SpecialChar ~
6661 <Value> The start location of the bit
6662 \begin_inset LatexCommand \index{bit}
6663
6664 \end_inset
6665
6666  addressable internal ram of the 8051.
6667  This is
6668 \emph on
6669 not
6670 \emph default
6671  implemented yet.
6672  Instead an option can be passed directly to the linker: -Wl\SpecialChar ~
6673 -bBSEG=<Value>.
6674 \layout List
6675 \labelwidthstring 00.00.0000
6676
6677
6678 \series bold
6679 -
6680 \begin_inset ERT
6681 status Collapsed
6682
6683 \layout Standard
6684
6685 \backslash
6686 /
6687 \end_inset
6688
6689 -out-fmt-ihx
6690 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
6691
6692 \end_inset
6693
6694
6695 \bar under
6696
6697 \series default
6698 \bar default
6699 The linker output (final object code) is in Intel Hex format.
6700 \begin_inset LatexCommand \index{Intel hex format}
6701
6702 \end_inset
6703
6704  This is the default option.
6705  The format itself is documented in the documentation of srecord
6706 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
6707
6708 \end_inset
6709
6710 .
6711 \layout List
6712 \labelwidthstring 00.00.0000
6713
6714
6715 \series bold
6716 -
6717 \begin_inset ERT
6718 status Collapsed
6719
6720 \layout Standard
6721
6722 \backslash
6723 /
6724 \end_inset
6725
6726 -out-fmt-s19
6727 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
6728
6729 \end_inset
6730
6731
6732 \bar under
6733
6734 \series default
6735 \bar default
6736 The linker output (final object code) is in Motorola S19 format
6737 \begin_inset LatexCommand \index{Motorola S19 format}
6738
6739 \end_inset
6740
6741 .
6742  The format itself is documented in the documentation of srecord.
6743 \layout List
6744 \labelwidthstring 00.00.0000
6745
6746
6747 \series bold
6748 -
6749 \begin_inset ERT
6750 status Collapsed
6751
6752 \layout Standard
6753
6754 \backslash
6755 /
6756 \end_inset
6757
6758 -out-fmt-elf
6759 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
6760
6761 \end_inset
6762
6763
6764 \begin_inset LatexCommand \index{HC08!Options!-\/-out-fmt-elf}
6765
6766 \end_inset
6767
6768
6769 \bar under
6770
6771 \series default
6772 \bar default
6773 The linker output (final object code) is in ELF format
6774 \begin_inset LatexCommand \index{ELF format}
6775
6776 \end_inset
6777
6778 .
6779  (Currently only supported for the HC08
6780 \begin_inset LatexCommand \index{HC08}
6781
6782 \end_inset
6783
6784  processors)
6785 \layout List
6786 \added_space_bottom bigskip \labelwidthstring 00.00.0000
6787
6788
6789 \series bold
6790 -Wl\SpecialChar ~
6791 linkOption[,linkOption]
6792 \series default
6793
6794 \begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
6795
6796 \end_inset
6797
6798 ...
6799  Pass the linkOption to the linker.
6800  If a bootloader is used an option like
6801 \begin_inset Quotes sld
6802 \end_inset
6803
6804 -Wl\SpecialChar ~
6805 -bCSEG=0x1000
6806 \begin_inset Quotes srd
6807 \end_inset
6808
6809  would be typical to set the start of the code segment.
6810  See also #pragma constseg and #pragma codeseg in section
6811 \begin_inset LatexCommand \ref{sec:Pragmas}
6812
6813 \end_inset
6814
6815  .
6816  File sdcc/as/doc/asxhtm.html has more on linker options.
6817 \layout Subsection
6818
6819 MCS51 Options
6820 \begin_inset LatexCommand \index{Options MCS51}
6821
6822 \end_inset
6823
6824
6825 \begin_inset LatexCommand \index{MCS51 options}
6826
6827 \end_inset
6828
6829
6830 \layout List
6831 \labelwidthstring 00.00.0000
6832
6833
6834 \series bold
6835 -
6836 \begin_inset ERT
6837 status Collapsed
6838
6839 \layout Standard
6840
6841 \backslash
6842 /
6843 \end_inset
6844
6845 -model-small
6846 \begin_inset LatexCommand \index{-\/-model-small}
6847
6848 \end_inset
6849
6850
6851 \series default
6852 \size large
6853 \emph on
6854
6855 \size default
6856 \emph default
6857 Generate code for Small Model programs, see section Memory Models for more
6858  details.
6859  This is the default model.
6860 \layout List
6861 \labelwidthstring 00.00.0000
6862
6863
6864 \series bold
6865 -
6866 \begin_inset ERT
6867 status Collapsed
6868
6869 \layout Standard
6870
6871 \backslash
6872 /
6873 \end_inset
6874
6875 -model-medium
6876 \begin_inset LatexCommand \index{-\/-model-medium}
6877
6878 \end_inset
6879
6880
6881 \series default
6882  Generate code for Medium model programs, see section Memory Models for
6883  more details.
6884  If this option is used all source files in the project have to be compiled
6885  with this option.
6886  It must also be used when invoking the linker.
6887 \layout List
6888 \labelwidthstring 00.00.0000
6889
6890
6891 \series bold
6892 -
6893 \begin_inset ERT
6894 status Collapsed
6895
6896 \layout Standard
6897
6898 \backslash
6899 /
6900 \end_inset
6901
6902 -model-large
6903 \begin_inset LatexCommand \index{-\/-model-large}
6904
6905 \end_inset
6906
6907
6908 \series default
6909  Generate code for Large model programs, see section Memory Models for more
6910  details.
6911  If this option is used all source files in the project have to be compiled
6912  with this option.
6913  It must also be used when invoking the linker.
6914 \layout List
6915 \labelwidthstring 00.00.0000
6916
6917
6918 \series bold
6919 -
6920 \begin_inset ERT
6921 status Collapsed
6922
6923 \layout Standard
6924
6925 \backslash
6926 /
6927 \end_inset
6928
6929 -xstack
6930 \begin_inset LatexCommand \index{-\/-xstack}
6931
6932 \end_inset
6933
6934
6935 \series default
6936  Uses a pseudo stack in the pdata
6937 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
6938
6939 \end_inset
6940
6941  area (usually the first 256 bytes in the external ram) for allocating variables
6942  and passing parameters.
6943  See section
6944 \begin_inset LatexCommand \ref{sub:External-Stack}
6945
6946 \end_inset
6947
6948 \SpecialChar ~
6949  External Stack for more details.
6950 \layout List
6951 \labelwidthstring 00.00.0000
6952
6953
6954 \series bold
6955 -
6956 \begin_inset ERT
6957 status Collapsed
6958
6959 \layout Standard
6960
6961 \backslash
6962 /
6963 \end_inset
6964
6965 -iram-size
6966 \series default
6967 \SpecialChar ~
6968 <Value>
6969 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
6970
6971 \end_inset
6972
6973  Causes the linker to check if the internal ram usage is within limits of
6974  the given value.
6975 \layout List
6976 \labelwidthstring 00.00.0000
6977
6978
6979 \series bold
6980 -
6981 \begin_inset ERT
6982 status Collapsed
6983
6984 \layout Standard
6985
6986 \backslash
6987 /
6988 \end_inset
6989
6990 -xram-size
6991 \series default
6992 \SpecialChar ~
6993 <Value>
6994 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
6995
6996 \end_inset
6997
6998  Causes the linker to check if the external ram usage is within limits of
6999  the given value.
7000 \layout List
7001 \labelwidthstring 00.00.0000
7002
7003
7004 \series bold
7005 -
7006 \begin_inset ERT
7007 status Collapsed
7008
7009 \layout Standard
7010
7011 \backslash
7012 /
7013 \end_inset
7014
7015 -code-size
7016 \series default
7017 \SpecialChar ~
7018 <Value>
7019 \begin_inset LatexCommand \index{-\/-code-size <Value>}
7020
7021 \end_inset
7022
7023  Causes the linker to check if the code memory usage is within limits of
7024  the given value.
7025 \layout List
7026 \labelwidthstring 00.00.0000
7027
7028
7029 \series bold
7030 -
7031 \begin_inset ERT
7032 status Collapsed
7033
7034 \layout Standard
7035
7036 \backslash
7037 /
7038 \end_inset
7039
7040 -stack-size
7041 \series default
7042 \SpecialChar ~
7043 <Value>
7044 \begin_inset LatexCommand \index{-\/-stack-size <Value>}
7045
7046 \end_inset
7047
7048  Causes the linker to check if there is at minimum <Value> bytes for stack.
7049 \layout List
7050 \labelwidthstring 00.00.0000
7051
7052
7053 \series bold
7054 -
7055 \begin_inset ERT
7056 status Collapsed
7057
7058 \layout Standard
7059
7060 \backslash
7061 /
7062 \end_inset
7063
7064 -pack-iram
7065 \series default
7066 \SpecialChar ~
7067
7068 \begin_inset LatexCommand \index{-\/-pack-iram}
7069
7070 \end_inset
7071
7072  Causes the linker to use unused register banks for data variables and pack
7073  data, idata and stack together.
7074  This is the default now.
7075 \layout List
7076 \added_space_bottom bigskip \labelwidthstring 00.00.0000
7077
7078
7079 \series bold
7080 -
7081 \begin_inset ERT
7082 status Collapsed
7083
7084 \layout Standard
7085
7086 \backslash
7087 /
7088 \end_inset
7089
7090 -no-pack-iram
7091 \series default
7092 \SpecialChar ~
7093
7094 \begin_inset LatexCommand \index{-\/-no-pack-iram}
7095
7096 \end_inset
7097
7098  Causes the linker to use old style for allocating memory areas.
7099 \layout Subsection
7100
7101 DS390 / DS400 Options
7102 \begin_inset LatexCommand \index{Options DS390}
7103
7104 \end_inset
7105
7106
7107 \begin_inset LatexCommand \index{DS390}
7108
7109 \end_inset
7110
7111
7112 \layout List
7113 \labelwidthstring 00.00.0000
7114
7115
7116 \series bold
7117 -
7118 \begin_inset ERT
7119 status Collapsed
7120
7121 \layout Standard
7122
7123 \backslash
7124 /
7125 \end_inset
7126
7127 -model-flat24
7128 \series default
7129
7130 \begin_inset LatexCommand \index{DS390!Options!-\/-model-flat24}
7131
7132 \end_inset
7133
7134
7135 \size large
7136 \emph on
7137
7138 \size default
7139 \emph default
7140 Generate 24-bit flat mode code.
7141  This is the one and only that the ds390 code generator supports right now
7142  and is default when using
7143 \emph on
7144 -mds390
7145 \emph default
7146 .
7147  See section Memory Models for more details.
7148 \layout List
7149 \labelwidthstring 00.00.0000
7150
7151
7152 \series bold
7153 -
7154 \begin_inset ERT
7155 status Collapsed
7156
7157 \layout Standard
7158
7159 \backslash
7160 /
7161 \end_inset
7162
7163 -protect-sp-update
7164 \begin_inset LatexCommand \index{DS390!Options!-\/-protect-sp-update}
7165
7166 \end_inset
7167
7168
7169 \series default
7170  disable interrupts during ESP:SP updates.
7171 \layout List
7172 \labelwidthstring 00.00.0000
7173
7174
7175 \series bold
7176 -
7177 \begin_inset ERT
7178 status Collapsed
7179
7180 \layout Standard
7181
7182 \backslash
7183 /
7184 \end_inset
7185
7186 -stack-10bit
7187 \series default
7188
7189 \begin_inset LatexCommand \index{DS390!Options!-\/-stack-10bit}
7190
7191 \end_inset
7192
7193  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
7194  This is the one and only that the ds390 code generator supports right now
7195  and is default when using
7196 \emph on
7197 -mds390
7198 \emph default
7199 .
7200  In this mode, the stack is located in the lower 1K of the internal RAM,
7201  which is mapped to 0x400000.
7202  Note that the support is incomplete, since it still uses a single byte
7203  as the stack pointer.
7204  This means that only the lower 256 bytes of the potential 1K stack space
7205  will actually be used.
7206  However, this does allow you to reclaim the precious 256 bytes of low RAM
7207  for use for the DATA and IDATA segments.
7208  The compiler will not generate any code to put the processor into 10 bit
7209  stack mode.
7210  It is important to ensure that the processor is in this mode before calling
7211  any re-entrant functions compiled with this option.
7212  In principle, this should work with the
7213 \emph on
7214 -
7215 \begin_inset ERT
7216 status Collapsed
7217
7218 \layout Standard
7219
7220 \backslash
7221 /
7222 \end_inset
7223
7224 -stack-auto
7225 \begin_inset LatexCommand \index{-\/-stack-auto}
7226
7227 \end_inset
7228
7229
7230 \emph default
7231  option, but that has not been tested.
7232  It is incompatible with the
7233 \emph on
7234 -
7235 \begin_inset ERT
7236 status Collapsed
7237
7238 \layout Standard
7239
7240 \backslash
7241 /
7242 \end_inset
7243
7244 -xstack
7245 \begin_inset LatexCommand \index{-\/-xstack}
7246
7247 \end_inset
7248
7249
7250 \emph default
7251  option.
7252  It also only makes sense if the processor is in 24 bit contiguous addressing
7253  mode (see the
7254 \emph on
7255 -
7256 \begin_inset ERT
7257 status Collapsed
7258
7259 \layout Standard
7260
7261 \backslash
7262 /
7263 \end_inset
7264
7265 -model-flat24 option
7266 \emph default
7267 ).
7268 \layout List
7269 \labelwidthstring 00.00.0000
7270
7271
7272 \series bold
7273 -
7274 \begin_inset ERT
7275 status Collapsed
7276
7277 \layout Standard
7278
7279 \backslash
7280 /
7281 \end_inset
7282
7283 -stack-probe
7284 \begin_inset LatexCommand \index{DS390!Options!-\/-stack-probe}
7285
7286 \end_inset
7287
7288
7289 \series default
7290  insert call to function __stack_probe at each function prologue.
7291 \layout List
7292 \labelwidthstring 00.00.0000
7293
7294
7295 \series bold
7296 -
7297 \begin_inset ERT
7298 status Collapsed
7299
7300 \layout Standard
7301
7302 \backslash
7303 /
7304 \end_inset
7305
7306 -tini-libid
7307 \begin_inset LatexCommand \index{DS390!Options!-\/-tini-libid}
7308
7309 \end_inset
7310
7311
7312 \series default
7313  <nnnn> LibraryID used in -mTININative.
7314
7315 \layout List
7316 \added_space_bottom bigskip \labelwidthstring 00.00.0000
7317
7318
7319 \series bold
7320 -
7321 \begin_inset ERT
7322 status Collapsed
7323
7324 \layout Standard
7325
7326 \backslash
7327 /
7328 \end_inset
7329
7330 -use-accelerator
7331 \begin_inset LatexCommand \index{DS390!Options!-\/-use-accelerator}
7332
7333 \end_inset
7334
7335
7336 \series default
7337  generate code for DS390 Arithmetic Accelerator.
7338
7339 \layout Subsection
7340
7341 Z80 Options
7342 \begin_inset LatexCommand \index{Options Z80}
7343
7344 \end_inset
7345
7346
7347 \begin_inset LatexCommand \index{Z80}
7348
7349 \end_inset
7350
7351
7352 \layout List
7353 \labelwidthstring 00.00.0000
7354
7355
7356 \series bold
7357 -
7358 \begin_inset ERT
7359 status Collapsed
7360
7361 \layout Standard
7362
7363 \backslash
7364 /
7365 \end_inset
7366
7367 -callee-saves-bc
7368 \series default
7369
7370 \begin_inset LatexCommand \index{Z80!Options!-\/-callee-saves-bc}
7371
7372 \end_inset
7373
7374
7375 \size large
7376 \emph on
7377
7378 \size default
7379 \emph default
7380 Force a called function to always save BC.
7381 \layout List
7382 \added_space_bottom bigskip \labelwidthstring 00.00.0000
7383
7384
7385 \series bold
7386 -
7387 \begin_inset ERT
7388 status Collapsed
7389
7390 \layout Standard
7391
7392 \backslash
7393 /
7394 \end_inset
7395
7396 -no-std-crt0
7397 \series default
7398
7399 \begin_inset LatexCommand \index{Z80!Options!-\/-no-std-crt0}
7400
7401 \end_inset
7402
7403  When linking, skip the standard crt0.o object file.
7404  You must provide your own crt0.o for your system when linking.
7405
7406 \layout Subsection
7407
7408 Optimization Options
7409 \begin_inset LatexCommand \index{Options optimization}
7410
7411 \end_inset
7412
7413
7414 \begin_inset LatexCommand \index{Optimization options}
7415
7416 \end_inset
7417
7418
7419 \layout List
7420 \labelwidthstring 00.00.0000
7421
7422
7423 \series bold
7424 -
7425 \begin_inset ERT
7426 status Collapsed
7427
7428 \layout Standard
7429
7430 \backslash
7431 /
7432 \end_inset
7433
7434 -nogcse
7435 \begin_inset LatexCommand \index{-\/-nogcse}
7436
7437 \end_inset
7438
7439
7440 \series default
7441  Will not do global subexpression elimination, this option may be used when
7442  the compiler creates undesirably large stack/data spaces to store compiler
7443  temporaries (
7444 \emph on
7445 s
7446 \emph default
7447 pill
7448 \emph on
7449 loc
7450 \emph default
7451 ations, sloc
7452 \begin_inset LatexCommand \index{sloc (spill location)}
7453
7454 \end_inset
7455
7456 ).
7457  A warning message will be generated when this happens and the compiler
7458  will indicate the number of extra bytes it allocated.
7459  It is recommended that this option NOT be used, #pragma\SpecialChar ~
7460 nogcse
7461 \begin_inset LatexCommand \index{\#pragma nogcse}
7462
7463 \end_inset
7464
7465  can be used to turn off global subexpression elimination
7466 \begin_inset LatexCommand \index{Subexpression elimination}
7467
7468 \end_inset
7469
7470  for a given function only.
7471 \layout List
7472 \labelwidthstring 00.00.0000
7473
7474
7475 \series bold
7476 -
7477 \begin_inset ERT
7478 status Collapsed
7479
7480 \layout Standard
7481
7482 \backslash
7483 /
7484 \end_inset
7485
7486 -noinvariant
7487 \begin_inset LatexCommand \index{-\/-noinvariant}
7488
7489 \end_inset
7490
7491
7492 \series default
7493  Will not do loop invariant optimizations, this may be turned off for reasons
7494  explained for the previous option.
7495  For more details of loop optimizations performed see Loop Invariants in
7496  section
7497 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
7498
7499 \end_inset
7500
7501 .
7502  It is recommended that this option NOT be used, #pragma\SpecialChar ~
7503 noinvariant
7504 \begin_inset LatexCommand \index{\#pragma noinvariant}
7505
7506 \end_inset
7507
7508  can be used to turn off invariant optimizations for a given function only.
7509 \layout List
7510 \labelwidthstring 00.00.0000
7511
7512
7513 \series bold
7514 -
7515 \begin_inset ERT
7516 status Collapsed
7517
7518 \layout Standard
7519
7520 \backslash
7521 /
7522 \end_inset
7523
7524 -noinduction
7525 \begin_inset LatexCommand \index{-\/-noinduction}
7526
7527 \end_inset
7528
7529
7530 \series default
7531  Will not do loop induction optimizations, see section strength reduction
7532  for more details.
7533  It is recommended that this option is NOT used, #pragma\SpecialChar ~
7534 noinduction
7535 \begin_inset LatexCommand \index{\#pragma noinduction}
7536
7537 \end_inset
7538
7539  can be used to turn off induction optimizations for a given function only.
7540 \layout List
7541 \labelwidthstring 00.00.0000
7542
7543
7544 \series bold
7545 -
7546 \begin_inset ERT
7547 status Collapsed
7548
7549 \layout Standard
7550
7551 \backslash
7552 /
7553 \end_inset
7554
7555 -nojtbound
7556 \begin_inset LatexCommand \index{-\/-nojtbound}
7557
7558 \end_inset
7559
7560
7561 \size large
7562 \bar under
7563
7564 \series default
7565 \size default
7566 \bar default
7567  Will not generate boundary condition check when switch statements
7568 \begin_inset LatexCommand \index{switch statement}
7569
7570 \end_inset
7571
7572  are implemented using jump-tables.
7573  See section
7574 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
7575
7576 \end_inset
7577
7578 \SpecialChar ~
7579 Switch Statements for more details.
7580  It is recommended that this option is NOT used, #pragma\SpecialChar ~
7581 nojtbound
7582 \begin_inset LatexCommand \index{\#pragma nojtbound}
7583
7584 \end_inset
7585
7586  can be used to turn off boundary checking for jump tables for a given function
7587  only.
7588 \layout List
7589 \labelwidthstring 00.00.0000
7590
7591
7592 \series bold
7593 -
7594 \begin_inset ERT
7595 status Collapsed
7596
7597 \layout Standard
7598
7599 \backslash
7600 /
7601 \end_inset
7602
7603 -noloopreverse
7604 \begin_inset LatexCommand \index{-\/-noloopreverse}
7605
7606 \end_inset
7607
7608
7609 \series default
7610 \size large
7611
7612 \size default
7613 Will not do loop reversal
7614 \begin_inset LatexCommand \index{Loop reversing}
7615
7616 \end_inset
7617
7618 optimization.
7619 \layout List
7620 \labelwidthstring 00.00.0000
7621
7622 -
7623 \begin_inset ERT
7624 status Collapsed
7625
7626 \layout Standard
7627
7628 \backslash
7629 /
7630 \end_inset
7631
7632 -
7633 \series bold
7634 nolabelopt
7635 \series default
7636
7637 \begin_inset LatexCommand \index{-\/-nolabelopt }
7638
7639 \end_inset
7640
7641 Will not optimize labels (makes the dumpfiles more readable).
7642 \layout List
7643 \labelwidthstring 00.00.0000
7644
7645
7646 \series bold
7647 -
7648 \begin_inset ERT
7649 status Collapsed
7650
7651 \layout Standard
7652
7653 \backslash
7654 /
7655 \end_inset
7656
7657 -no-xinit-opt
7658 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
7659
7660 \end_inset
7661
7662
7663 \series default
7664  Will not memcpy initialized data from code space into xdata space.
7665  This saves a few bytes in code space if you don't have initialized data
7666 \begin_inset LatexCommand \index{Variable initialization}
7667
7668 \end_inset
7669
7670 .
7671 \layout List
7672 \labelwidthstring 00.00.0000
7673
7674
7675 \series bold
7676 -
7677 \begin_inset ERT
7678 status Collapsed
7679
7680 \layout Standard
7681
7682 \backslash
7683 /
7684 \end_inset
7685
7686 -nooverlay
7687 \begin_inset LatexCommand \index{-\/-nooverlay}
7688
7689 \end_inset
7690
7691
7692 \series default
7693   The compiler will not overlay parameters and local variables of any function,
7694  see section Parameters and local variables for more details.
7695 \layout List
7696 \labelwidthstring 00.00.0000
7697
7698
7699 \series bold
7700 -
7701 \begin_inset ERT
7702 status Collapsed
7703
7704 \layout Standard
7705
7706 \backslash
7707 /
7708 \end_inset
7709
7710 -no-peep
7711 \begin_inset LatexCommand \index{-\/-no-peep}
7712
7713 \end_inset
7714
7715
7716 \series default
7717  Disable peep-hole optimization with built-in rules.
7718 \layout List
7719 \labelwidthstring 00.00.0000
7720
7721
7722 \series bold
7723 -
7724 \begin_inset ERT
7725 status Collapsed
7726
7727 \layout Standard
7728
7729 \backslash
7730 /
7731 \end_inset
7732
7733 -peep-file
7734 \series default
7735
7736 \begin_inset LatexCommand \index{-\/-peep-file}
7737
7738 \end_inset
7739
7740 \SpecialChar ~
7741 <filename> This option can be used to use additional rules to be used by
7742  the peep hole optimizer.
7743  See section
7744 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
7745
7746 \end_inset
7747
7748 \SpecialChar ~
7749 Peep Hole optimizations for details on how to write these rules.
7750 \layout List
7751 \labelwidthstring 00.00.0000
7752
7753
7754 \series bold
7755 -
7756 \begin_inset ERT
7757 status Collapsed
7758
7759 \layout Standard
7760
7761 \backslash
7762 /
7763 \end_inset
7764
7765 -peep-asm
7766 \begin_inset LatexCommand \index{-\/-peep-asm}
7767
7768 \end_inset
7769
7770
7771 \series default
7772  Pass the inline assembler code through the peep hole optimizer.
7773  This can cause unexpected changes to inline assembler code, please go through
7774  the peephole optimizer
7775 \begin_inset LatexCommand \index{Peephole optimizer}
7776
7777 \end_inset
7778
7779  rules defined in the source file tree '<target>/peeph.def' before using
7780  this option.
7781 \layout List
7782 \labelwidthstring 00.00.0000
7783
7784
7785 \series bold
7786 -
7787 \begin_inset ERT
7788 status Collapsed
7789
7790 \layout Standard
7791
7792 \backslash
7793 /
7794 \end_inset
7795
7796 -opt-code-speed
7797 \begin_inset LatexCommand \index{-\/-opt-code-speed}
7798
7799 \end_inset
7800
7801
7802 \series default
7803  The compiler will optimize code generation towards fast code, possibly
7804  at the expense of code size.
7805 \layout List
7806 \added_space_bottom bigskip \labelwidthstring 00.00.0000
7807
7808
7809 \series bold
7810 -
7811 \begin_inset ERT
7812 status Collapsed
7813
7814 \layout Standard
7815
7816 \backslash
7817 /
7818 \end_inset
7819
7820 -opt-code-size
7821 \begin_inset LatexCommand \index{-\/-opt-code-size}
7822
7823 \end_inset
7824
7825
7826 \series default
7827  The compiler will optimize code generation towards compact code, possibly
7828  at the expense of code speed.
7829 \layout Subsection
7830
7831 Other Options
7832 \begin_inset LatexCommand \index{Options other}
7833
7834 \end_inset
7835
7836
7837 \layout List
7838 \labelwidthstring 00.00.0000
7839
7840
7841 \series bold
7842 -c\SpecialChar ~
7843 -
7844 \begin_inset ERT
7845 status Collapsed
7846
7847 \layout Standard
7848
7849 \backslash
7850 /
7851 \end_inset
7852
7853 -compile-only
7854 \begin_inset LatexCommand \index{-\/-compile-only}
7855
7856 \end_inset
7857
7858
7859 \begin_inset LatexCommand \index{-c -\/-compile-only}
7860
7861 \end_inset
7862
7863
7864 \series default
7865  will compile and assemble the source, but will not call the linkage editor.
7866 \layout List
7867 \labelwidthstring 00.00.0000
7868
7869
7870 \series bold
7871 -
7872 \series default
7873
7874 \begin_inset ERT
7875 status Collapsed
7876
7877 \layout Standard
7878
7879 \backslash
7880 /
7881 \end_inset
7882
7883
7884 \series bold
7885 -c1mode
7886 \begin_inset LatexCommand \index{-\/-c1mode}
7887
7888 \end_inset
7889
7890
7891 \series default
7892  reads the preprocessed source from standard input and compiles it.
7893  The file name for the assembler output must be specified using the -o option.
7894 \layout List
7895 \labelwidthstring 00.00.0000
7896
7897
7898 \series bold
7899 -E
7900 \begin_inset LatexCommand \index{-E}
7901
7902 \end_inset
7903
7904
7905 \series default
7906  Run only the C preprocessor.
7907  Preprocess all the C source files specified and output the results to standard
7908  output.
7909 \layout List
7910 \labelwidthstring 00.00.0000
7911
7912
7913 \series bold
7914 -o\SpecialChar ~
7915 <path/file>
7916 \begin_inset LatexCommand \index{-o <path/file>}
7917
7918 \end_inset
7919
7920
7921 \series default
7922 The output path resp.
7923  file where everything will be placed.
7924  If the parameter is a path, it must have a trailing slash (or backslash
7925  for the Windows binaries) to be recognized as a path.
7926
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 -stack-auto
7943 \begin_inset LatexCommand \index{-\/-stack-auto}
7944
7945 \end_inset
7946
7947
7948 \series default
7949 \size large
7950 \emph on
7951
7952 \size default
7953 \emph default
7954 All functions in the source file will be compiled as
7955 \emph on
7956 reentrant
7957 \emph default
7958
7959 \begin_inset LatexCommand \index{reentrant}
7960
7961 \end_inset
7962
7963 , i.e.
7964  the parameters and local variables will be allocated on the stack
7965 \begin_inset LatexCommand \index{stack}
7966
7967 \end_inset
7968
7969 .
7970  See section
7971 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
7972
7973 \end_inset
7974
7975  Parameters and Local Variables for more details.
7976  If this option is used all source files in the project should be compiled
7977  with this option.
7978  It automatically implies --int-long-reent and --float-reent.
7979
7980 \layout List
7981 \labelwidthstring 00.00.0000
7982
7983
7984 \series bold
7985 -
7986 \begin_inset ERT
7987 status Collapsed
7988
7989 \layout Standard
7990
7991 \backslash
7992 /
7993 \end_inset
7994
7995 -callee-saves
7996 \begin_inset LatexCommand \index{-\/-callee-saves}
7997
7998 \end_inset
7999
8000  function1[,function2][,function3]....
8001
8002 \series default
8003  The compiler by default uses a caller saves convention for register saving
8004  across function calls, however this can cause unnecessary register pushing
8005  & popping when calling small functions from larger functions.
8006  This option can be used to switch the register saving convention for the
8007  function names specified.
8008  The compiler will not save registers when calling these functions, no extra
8009  code will be generated at the entry & exit (function prologue
8010 \series bold
8011
8012 \begin_inset LatexCommand \index{function prologue}
8013
8014 \end_inset
8015
8016
8017 \series default
8018  & epilogue
8019 \series bold
8020
8021 \begin_inset LatexCommand \index{function epilogue}
8022
8023 \end_inset
8024
8025
8026 \series default
8027 ) for these functions to save & restore the registers used by these functions,
8028  this can SUBSTANTIALLY reduce code & improve run time performance of the
8029  generated code.
8030  In the future the compiler (with inter procedural analysis) will be able
8031  to determine the appropriate scheme to use for each function call.
8032  DO NOT use this option for built-in functions such as _mulint..., if this
8033  option is used for a library function the appropriate library function
8034  needs to be recompiled with the same option.
8035  If the project consists of multiple source files then all the source file
8036  should be compiled with the same -
8037 \begin_inset ERT
8038 status Collapsed
8039
8040 \layout Standard
8041
8042 \backslash
8043 /
8044 \end_inset
8045
8046 -callee-saves option string.
8047  Also see #pragma\SpecialChar ~
8048 callee_saves
8049 \begin_inset LatexCommand \index{\#pragma callee\_saves}
8050
8051 \end_inset
8052
8053 .
8054 \layout List
8055 \labelwidthstring 00.00.0000
8056
8057
8058 \series bold
8059 -
8060 \begin_inset ERT
8061 status Collapsed
8062
8063 \layout Standard
8064
8065 \backslash
8066 /
8067 \end_inset
8068
8069 -debug
8070 \begin_inset LatexCommand \index{-\/-debug}
8071
8072 \end_inset
8073
8074
8075 \bar under
8076
8077 \series default
8078 \bar default
8079 When this option is used the compiler will generate debug information.
8080  The debug information collected in a file with .cdb extension can be used
8081  with the SDCDB.
8082  For more information see documentation for SDCDB.
8083  Another file with no extension contains debug information in AOMF or AOMF51
8084 \begin_inset LatexCommand \index{AOMF, AOMF51}
8085
8086 \end_inset
8087
8088  format which is commonly used by third party tools.
8089 \layout List
8090 \labelwidthstring 00.00.0000
8091
8092
8093 \series bold
8094 -S
8095 \begin_inset LatexCommand \index{-S}
8096
8097 \end_inset
8098
8099
8100 \size large
8101 \bar under
8102
8103 \series default
8104 \size default
8105 \bar default
8106 Stop after the stage of compilation proper; do not assemble.
8107  The output is an assembler code file for the input file specified.
8108 \layout List
8109 \labelwidthstring 00.00.0000
8110
8111
8112 \series bold
8113 -
8114 \begin_inset ERT
8115 status Collapsed
8116
8117 \layout Standard
8118
8119 \backslash
8120 /
8121 \end_inset
8122
8123 -int-long-reent
8124 \begin_inset LatexCommand \index{-\/-int-long-reent}
8125
8126 \end_inset
8127
8128
8129 \series default
8130  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
8131  Note by default these libraries are compiled as non-reentrant.
8132  See section Installation for more details.
8133 \layout List
8134 \labelwidthstring 00.00.0000
8135
8136
8137 \series bold
8138 -
8139 \begin_inset ERT
8140 status Collapsed
8141
8142 \layout Standard
8143
8144 \backslash
8145 /
8146 \end_inset
8147
8148 -cyclomatic
8149 \begin_inset LatexCommand \index{-\/-cyclomatic}
8150
8151 \end_inset
8152
8153
8154 \bar under
8155
8156 \series default
8157 \bar default
8158 This option will cause the compiler to generate an information message for
8159  each function in the source file.
8160  The message contains some
8161 \emph on
8162 important
8163 \emph default
8164  information about the function.
8165  The number of edges and nodes the compiler detected in the control flow
8166  graph of the function, and most importantly the
8167 \emph on
8168 cyclomatic complexity
8169 \begin_inset LatexCommand \index{Cyclomatic complexity}
8170
8171 \end_inset
8172
8173
8174 \emph default
8175  see section on Cyclomatic Complexity for more details.
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 -float-reent
8192 \begin_inset LatexCommand \index{-\/-float-reent}
8193
8194 \end_inset
8195
8196
8197 \series default
8198  Floating point library is compiled as reentrant
8199 \begin_inset LatexCommand \index{reentrant}
8200
8201 \end_inset
8202
8203 .
8204  See section Installation for more details.
8205 \layout List
8206 \labelwidthstring 00.00.0000
8207
8208
8209 \series bold
8210 -
8211 \begin_inset ERT
8212 status Collapsed
8213
8214 \layout Standard
8215
8216 \backslash
8217 /
8218 \end_inset
8219
8220 -main-return
8221 \begin_inset LatexCommand \index{-\/-main-return}
8222
8223 \end_inset
8224
8225
8226 \series default
8227  This option can be used if the code generated is called by a monitor program
8228  or if the main routine includes an endless loop.
8229  This option results in slightly smaller code and saves two bytes of stack
8230  space.
8231  The return from the 'main'
8232 \begin_inset LatexCommand \index{main return}
8233
8234 \end_inset
8235
8236  function will return to the function calling main.
8237  The default setting is to lock up i.e.
8238  generate a '
8239 \family typewriter
8240 sjmp .
8241 \family default
8242 '.
8243 \layout List
8244 \labelwidthstring 00.00.0000
8245
8246
8247 \series bold
8248 -
8249 \begin_inset ERT
8250 status Collapsed
8251
8252 \layout Standard
8253
8254 \backslash
8255 /
8256 \end_inset
8257
8258 -nostdinc
8259 \begin_inset LatexCommand \index{-\/-nostdinc}
8260
8261 \end_inset
8262
8263
8264 \series default
8265  This will prevent the compiler from passing on the default include path
8266  to the preprocessor.
8267 \layout List
8268 \labelwidthstring 00.00.0000
8269
8270
8271 \series bold
8272 -
8273 \begin_inset ERT
8274 status Collapsed
8275
8276 \layout Standard
8277
8278 \backslash
8279 /
8280 \end_inset
8281
8282 -nostdlib
8283 \begin_inset LatexCommand \index{-\/-nostdlib}
8284
8285 \end_inset
8286
8287
8288 \series default
8289  This will prevent the compiler from passing on the default library
8290 \begin_inset LatexCommand \index{Libraries}
8291
8292 \end_inset
8293
8294  path to the linker.
8295 \layout List
8296 \labelwidthstring 00.00.0000
8297
8298
8299 \series bold
8300 -
8301 \begin_inset ERT
8302 status Collapsed
8303
8304 \layout Standard
8305
8306 \backslash
8307 /
8308 \end_inset
8309
8310 -verbose
8311 \begin_inset LatexCommand \index{-\/-verbose}
8312
8313 \end_inset
8314
8315
8316 \series default
8317  Shows the various actions the compiler is performing.
8318 \layout List
8319 \labelwidthstring 00.00.0000
8320
8321
8322 \series bold
8323 -V
8324 \begin_inset LatexCommand \index{-V}
8325
8326 \end_inset
8327
8328
8329 \series default
8330  Shows the actual commands the compiler is executing.
8331 \layout List
8332 \labelwidthstring 00.00.0000
8333
8334
8335 \series bold
8336 -
8337 \begin_inset ERT
8338 status Collapsed
8339
8340 \layout Standard
8341
8342 \backslash
8343 /
8344 \end_inset
8345
8346 -no-c-code-in-asm
8347 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
8348
8349 \end_inset
8350
8351
8352 \series default
8353  Hides your ugly and inefficient c-code from the asm file, so you can always
8354  blame the compiler :)
8355 \layout List
8356 \labelwidthstring 00.00.0000
8357
8358
8359 \series bold
8360 -
8361 \begin_inset ERT
8362 status Collapsed
8363
8364 \layout Standard
8365
8366 \backslash
8367 /
8368 \end_inset
8369
8370 -no-peep-comments
8371 \begin_inset LatexCommand \index{-\/-no-peep-comments}
8372
8373 \end_inset
8374
8375
8376 \series default
8377  Will not include peep-hole comments in the generated files.
8378 \layout List
8379 \labelwidthstring 00.00.0000
8380
8381
8382 \series bold
8383 -
8384 \begin_inset ERT
8385 status Collapsed
8386
8387 \layout Standard
8388
8389 \backslash
8390 /
8391 \end_inset
8392
8393 -i-code-in-asm
8394 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
8395
8396 \end_inset
8397
8398
8399 \series default
8400  Include i-codes in the asm file.
8401  Sounds like noise but is most helpful for debugging the compiler itself.
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 -less-pedantic
8418 \begin_inset LatexCommand \index{-\/-less-pedantic}
8419
8420 \end_inset
8421
8422
8423 \series default
8424  Disable some of the more pedantic warnings
8425 \begin_inset LatexCommand \index{Warnings}
8426
8427 \end_inset
8428
8429  (jwk burps: please be more specific here, please!).
8430 \layout List
8431 \labelwidthstring 00.00.0000
8432
8433
8434 \series bold
8435 -
8436 \begin_inset ERT
8437 status Collapsed
8438
8439 \layout Standard
8440
8441 \backslash
8442 /
8443 \end_inset
8444
8445 -disable-warning\SpecialChar ~
8446 <nnnn>
8447 \begin_inset LatexCommand \index{-\/-disable-warning}
8448
8449 \end_inset
8450
8451
8452 \series default
8453  Disable specific warning with number <nnnn>.
8454 \layout List
8455 \labelwidthstring 00.00.0000
8456
8457
8458 \series bold
8459 -
8460 \begin_inset ERT
8461 status Collapsed
8462
8463 \layout Standard
8464
8465 \backslash
8466 /
8467 \end_inset
8468
8469 -print-search-dirs
8470 \begin_inset LatexCommand \index{-\/-print-search-dirs}
8471
8472 \end_inset
8473
8474
8475 \series default
8476  Display the directories in the compiler's search path
8477 \layout List
8478 \labelwidthstring 00.00.0000
8479
8480
8481 \series bold
8482 -
8483 \begin_inset ERT
8484 status Collapsed
8485
8486 \layout Standard
8487
8488 \backslash
8489 /
8490 \end_inset
8491
8492 -vc
8493 \begin_inset LatexCommand \index{-\/-vc}
8494
8495 \end_inset
8496
8497
8498 \series default
8499  Display errors and warnings using MSVC style, so you can use SDCC with
8500  the visual studio IDE
8501 \begin_inset LatexCommand \index{IDE}
8502
8503 \end_inset
8504
8505 .
8506  With SDCC both offering a GCC-like (the default) and a MSVC-like
8507 \begin_inset LatexCommand \index{MSVC output style}
8508
8509 \end_inset
8510
8511  output style, integration into most programming editors should be straightforwa
8512 rd.
8513 \layout List
8514 \labelwidthstring 00.00.0000
8515
8516
8517 \series bold
8518 -
8519 \begin_inset ERT
8520 status Collapsed
8521
8522 \layout Standard
8523
8524 \backslash
8525 /
8526 \end_inset
8527
8528 -use-stdout
8529 \begin_inset LatexCommand \index{-\/-use-stdout}
8530
8531 \end_inset
8532
8533
8534 \series default
8535  Send errors and warnings to stdout instead of stderr.
8536 \layout List
8537 \labelwidthstring 00.00.0000
8538
8539
8540 \series bold
8541 -Wa\SpecialChar ~
8542 asmOption[,asmOption]
8543 \series default
8544
8545 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
8546
8547 \end_inset
8548
8549 ...
8550  Pass the asmOption to the assembler
8551 \begin_inset LatexCommand \index{Options assembler}
8552
8553 \end_inset
8554
8555
8556 \begin_inset LatexCommand \index{Assembler options}
8557
8558 \end_inset
8559
8560 .
8561  See file sdcc/as/doc/asxhtm.html for assembler options.cd
8562 \layout List
8563 \labelwidthstring 00.00.0000
8564
8565
8566 \series bold
8567 -
8568 \begin_inset ERT
8569 status Collapsed
8570
8571 \layout Standard
8572
8573 \backslash
8574 /
8575 \end_inset
8576
8577 -std-sdcc89
8578 \begin_inset LatexCommand \index{-\/-std-sdcc89}
8579
8580 \end_inset
8581
8582
8583 \series default
8584  Generally follow the C89 standard, but allow SDCC features that conflict
8585  with the standard (default).
8586 \layout List
8587 \labelwidthstring 00.00.0000
8588
8589
8590 \series bold
8591 -
8592 \begin_inset ERT
8593 status Collapsed
8594
8595 \layout Standard
8596
8597 \backslash
8598 /
8599 \end_inset
8600
8601 -std-c89
8602 \begin_inset LatexCommand \index{-\/-std-c89}
8603
8604 \end_inset
8605
8606
8607 \series default
8608  Follow the C89 standard and disable SDCC features that conflict with the
8609  standard.
8610 \layout List
8611 \labelwidthstring 00.00.0000
8612
8613
8614 \series bold
8615 -
8616 \begin_inset ERT
8617 status Collapsed
8618
8619 \layout Standard
8620
8621 \backslash
8622 /
8623 \end_inset
8624
8625 -std-sdcc99
8626 \begin_inset LatexCommand \index{-\/-std-sdcc99}
8627
8628 \end_inset
8629
8630
8631 \series default
8632  Generally follow the C99 standard, but allow SDCC features that conflict
8633  with the standard (incomplete support).
8634 \layout List
8635 \labelwidthstring 00.00.0000
8636
8637
8638 \series bold
8639 -
8640 \begin_inset ERT
8641 status Collapsed
8642
8643 \layout Standard
8644
8645 \backslash
8646 /
8647 \end_inset
8648
8649 -std-c99
8650 \begin_inset LatexCommand \index{-\/-std-sdcc99}
8651
8652 \end_inset
8653
8654
8655 \series default
8656  Follow the C99 standard and disable SDCC features that conflict with the
8657  standard (incomplete support).
8658 \layout List
8659 \labelwidthstring 00.00.0000
8660
8661
8662 \series bold
8663 -
8664 \begin_inset ERT
8665 status Collapsed
8666
8667 \layout Standard
8668
8669 \backslash
8670 /
8671 \end_inset
8672
8673 -codeseg
8674 \series default
8675
8676 \begin_inset LatexCommand \index{-\/-codeseg <Value>}
8677
8678 \end_inset
8679
8680 \SpecialChar ~
8681 <Name> The name to be used for the code
8682 \begin_inset LatexCommand \index{code}
8683
8684 \end_inset
8685
8686  segment, default CSEG.
8687  This is useful if you need to tell the compiler to put the code in a special
8688  segment so you can later on tell the linker to put this segment in a special
8689  place in memory.
8690  Can be used for instance when using bank switching to put the code in a
8691  bank.
8692 \layout List
8693 \labelwidthstring 00.00.0000
8694
8695
8696 \series bold
8697 -
8698 \begin_inset ERT
8699 status Collapsed
8700
8701 \layout Standard
8702
8703 \backslash
8704 /
8705 \end_inset
8706
8707 -constseg
8708 \series default
8709
8710 \begin_inset LatexCommand \index{-\/-constseg <Value>}
8711
8712 \end_inset
8713
8714 \SpecialChar ~
8715 <Name> The name to be used for the const
8716 \begin_inset LatexCommand \index{code}
8717
8718 \end_inset
8719
8720  segment, default CONST.
8721  This is useful if you need to tell the compiler to put the const data in
8722  a special segment so you can later on tell the linker to put this segment
8723  in a special place in memory.
8724  Can be used for instance when using bank switching to put the const data
8725  in a bank.
8726 \layout List
8727 \added_space_bottom bigskip \labelwidthstring 00.00.0000
8728
8729
8730 \series bold
8731 more-pedantic
8732 \series default
8733  Actually this is
8734 \series bold
8735 \emph on
8736 not
8737 \series default
8738 \emph default
8739  a SDCC compiler option but if you want
8740 \emph on
8741 more
8742 \emph default
8743  warnings you can use a separate tool dedicated to syntax checking like
8744  splint
8745 \begin_inset LatexCommand \label{lyx:more-pedantic-SPLINT}
8746
8747 \end_inset
8748
8749
8750 \begin_inset LatexCommand \index{lint (syntax checking tool)}
8751
8752 \end_inset
8753
8754
8755 \begin_inset LatexCommand \url{http://www.splint.org}
8756
8757 \end_inset
8758
8759 .
8760  To make your source files parseable by splint you will have to include
8761
8762 \family sans
8763 lint.h
8764 \family default
8765
8766 \begin_inset LatexCommand \index{splint (syntax checking tool)}
8767
8768 \end_inset
8769
8770  in your source file and add brackets around extended keywords (like
8771 \family sans
8772
8773 \begin_inset Quotes sld
8774 \end_inset
8775
8776 __at\SpecialChar ~
8777
8778 \series bold
8779 (
8780 \series default
8781 0xab
8782 \series bold
8783 )
8784 \series default
8785
8786 \begin_inset Quotes srd
8787 \end_inset
8788
8789
8790 \family default
8791  and
8792 \family sans
8793
8794 \begin_inset Quotes sld
8795 \end_inset
8796
8797 __interrupt\SpecialChar ~
8798 (2)
8799 \begin_inset Quotes srd
8800 \end_inset
8801
8802
8803 \family default
8804 ).
8805
8806 \newline
8807 Splint has an excellent on line manual at
8808 \begin_inset LatexCommand \url{http://www.splint.org/manual/}
8809
8810 \end_inset
8811
8812  and it's capabilities go beyond pure syntax checking.
8813  You'll need to tell splint the location of SDCC's include files so a typical
8814  command line could look like this:
8815 \newline
8816
8817 \family sans
8818 splint\SpecialChar ~
8819 -I\SpecialChar ~
8820 /usr/local/share/sdcc/include/mcs51/\SpecialChar ~
8821 \SpecialChar ~
8822 myprogram.c
8823 \layout Subsection
8824
8825 Intermediate Dump Options
8826 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
8827
8828 \end_inset
8829
8830
8831 \begin_inset LatexCommand \index{Options intermediate dump}
8832
8833 \end_inset
8834
8835
8836 \begin_inset LatexCommand \index{Intermediate dump options}
8837
8838 \end_inset
8839
8840
8841 \layout Standard
8842
8843 The following options are provided for the purpose of retargetting and debugging
8844  the compiler.
8845  They provide a means to dump the intermediate code (iCode
8846 \begin_inset LatexCommand \index{iCode}
8847
8848 \end_inset
8849
8850 ) generated by the compiler in human readable form at various stages of
8851  the compilation process.
8852  More on iCodes see chapter
8853 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
8854
8855 \end_inset
8856
8857
8858 \begin_inset Quotes srd
8859 \end_inset
8860
8861 The anatomy of the compiler
8862 \begin_inset Quotes srd
8863 \end_inset
8864
8865 .
8866 \layout List
8867 \labelwidthstring 00.00.0000
8868
8869
8870 \series bold
8871 -
8872 \begin_inset ERT
8873 status Collapsed
8874
8875 \layout Standard
8876
8877 \backslash
8878 /
8879 \end_inset
8880
8881 -dumpraw
8882 \begin_inset LatexCommand \index{-\/-dumpraw}
8883
8884 \end_inset
8885
8886
8887 \series default
8888  This option will cause the compiler to dump the intermediate code into
8889  a file of named
8890 \emph on
8891 <source filename>.dumpraw
8892 \emph default
8893  just after the intermediate code has been generated for a function, i.e.
8894  before any optimizations are done.
8895  The basic blocks
8896 \begin_inset LatexCommand \index{Basic blocks}
8897
8898 \end_inset
8899
8900  at this stage ordered in the depth first number, so they may not be in
8901  sequence of execution.
8902 \layout List
8903 \labelwidthstring 00.00.0000
8904
8905
8906 \series bold
8907 -
8908 \begin_inset ERT
8909 status Collapsed
8910
8911 \layout Standard
8912
8913 \backslash
8914 /
8915 \end_inset
8916
8917 -dumpgcse
8918 \begin_inset LatexCommand \index{-\/-dumpgcse}
8919
8920 \end_inset
8921
8922
8923 \series default
8924  Will create a dump of iCode's, after global subexpression elimination
8925 \begin_inset LatexCommand \index{Global subexpression elimination}
8926
8927 \end_inset
8928
8929 , into a file named
8930 \emph on
8931 <source filename>.dumpgcse.
8932 \layout List
8933 \labelwidthstring 00.00.0000
8934
8935
8936 \series bold
8937 -
8938 \begin_inset ERT
8939 status Collapsed
8940
8941 \layout Standard
8942
8943 \backslash
8944 /
8945 \end_inset
8946
8947 -dumpdeadcode
8948 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
8949
8950 \end_inset
8951
8952
8953 \series default
8954  Will create a dump of iCode's, after deadcode elimination
8955 \begin_inset LatexCommand \index{Dead-code elimination}
8956
8957 \end_inset
8958
8959 , into a file named
8960 \emph on
8961 <source filename>.dumpdeadcode.
8962 \layout List
8963 \labelwidthstring 00.00.0000
8964
8965
8966 \series bold
8967 -
8968 \begin_inset ERT
8969 status Collapsed
8970
8971 \layout Standard
8972
8973 \backslash
8974 /
8975 \end_inset
8976
8977 -dumploop
8978 \begin_inset LatexCommand \index{-\/-dumploop}
8979
8980 \end_inset
8981
8982
8983 \series default
8984 \size large
8985
8986 \size default
8987 Will create a dump of iCode's, after loop optimizations
8988 \begin_inset LatexCommand \index{Loop optimization}
8989
8990 \end_inset
8991
8992 , into a file named
8993 \emph on
8994 <source filename>.dumploop.
8995 \layout List
8996 \labelwidthstring 00.00.0000
8997
8998
8999 \series bold
9000 -
9001 \begin_inset ERT
9002 status Collapsed
9003
9004 \layout Standard
9005
9006 \backslash
9007 /
9008 \end_inset
9009
9010 -dumprange
9011 \begin_inset LatexCommand \index{-\/-dumprange}
9012
9013 \end_inset
9014
9015
9016 \series default
9017 \size large
9018
9019 \size default
9020 Will create a dump of iCode's, after live range analysis
9021 \begin_inset LatexCommand \index{Live range analysis}
9022
9023 \end_inset
9024
9025 , into a file named
9026 \emph on
9027 <source filename>.dumprange.
9028 \layout List
9029 \labelwidthstring 00.00.0000
9030
9031
9032 \series bold
9033 -
9034 \begin_inset ERT
9035 status Collapsed
9036
9037 \layout Standard
9038
9039 \backslash
9040 /
9041 \end_inset
9042
9043 -dumlrange
9044 \begin_inset LatexCommand \index{-\/-dumlrange}
9045
9046 \end_inset
9047
9048
9049 \series default
9050  Will dump the life ranges
9051 \begin_inset LatexCommand \index{Live range analysis}
9052
9053 \end_inset
9054
9055  for all symbols.
9056 \layout List
9057 \labelwidthstring 00.00.0000
9058
9059
9060 \series bold
9061 -
9062 \begin_inset ERT
9063 status Collapsed
9064
9065 \layout Standard
9066
9067 \backslash
9068 /
9069 \end_inset
9070
9071 -dumpregassign
9072 \begin_inset LatexCommand \index{-\/-dumpregassign}
9073
9074 \end_inset
9075
9076
9077 \bar under
9078
9079 \series default
9080 \bar default
9081 Will create a dump of iCode's, after register assignment
9082 \begin_inset LatexCommand \index{Register assignment}
9083
9084 \end_inset
9085
9086 , into a file named
9087 \emph on
9088 <source filename>.dumprassgn.
9089 \layout List
9090 \labelwidthstring 00.00.0000
9091
9092
9093 \series bold
9094 -
9095 \begin_inset ERT
9096 status Collapsed
9097
9098 \layout Standard
9099
9100 \backslash
9101 /
9102 \end_inset
9103
9104 -dumplrange
9105 \begin_inset LatexCommand \index{-\/-dumplrange}
9106
9107 \end_inset
9108
9109
9110 \series default
9111  Will create a dump of the live ranges of iTemp's
9112 \layout List
9113 \added_space_bottom bigskip \labelwidthstring 00.00.0000
9114
9115
9116 \series bold
9117 -
9118 \begin_inset ERT
9119 status Collapsed
9120
9121 \layout Standard
9122
9123 \backslash
9124 /
9125 \end_inset
9126
9127 -dumpall
9128 \begin_inset LatexCommand \index{-\/-dumpall}
9129
9130 \end_inset
9131
9132
9133 \size large
9134 \bar under
9135
9136 \series default
9137 \size default
9138 \bar default
9139 Will cause all the above mentioned dumps to be created.
9140 \layout Subsection
9141
9142 Redirecting output on Windows Shells
9143 \layout Standard
9144 \added_space_bottom bigskip
9145 By default SDCC writes it's error messages to
9146 \begin_inset Quotes sld
9147 \end_inset
9148
9149 standard error
9150 \begin_inset Quotes srd
9151 \end_inset
9152
9153 .
9154  To force all messages to
9155 \begin_inset Quotes sld
9156 \end_inset
9157
9158 standard output
9159 \begin_inset Quotes srd
9160 \end_inset
9161
9162  use
9163 \series bold
9164 -
9165 \series default
9166 \emph on
9167
9168 \begin_inset ERT
9169 status Collapsed
9170
9171 \layout Standard
9172
9173 \backslash
9174 /
9175 \end_inset
9176
9177
9178 \series bold
9179 \emph default
9180 -
9181 \series default
9182 use-stdout
9183 \begin_inset LatexCommand \index{-\/-use-stdout}
9184
9185 \end_inset
9186
9187 .
9188  Additionally, if you happen to have visual studio installed in your windows
9189  machine, you can use it to compile your sources using a custom build and
9190  the SDCC -
9191 \emph on
9192
9193 \begin_inset ERT
9194 status Collapsed
9195
9196 \layout Standard
9197
9198 \backslash
9199 /
9200 \end_inset
9201
9202
9203 \emph default
9204 -vc
9205 \begin_inset LatexCommand \index{-\/-vc}
9206
9207 \end_inset
9208
9209  option.
9210  Something like this should work:
9211 \newline
9212
9213 \newline
9214
9215 \series bold
9216 c:
9217 \backslash
9218 sdcc
9219 \backslash
9220 bin
9221 \backslash
9222 sdcc.exe -
9223 \series default
9224 \emph on
9225
9226 \begin_inset ERT
9227 status Collapsed
9228
9229 \layout Standard
9230
9231 \backslash
9232 /
9233 \end_inset
9234
9235
9236 \series bold
9237 \emph default
9238 -vc -
9239 \series default
9240 \emph on
9241
9242 \begin_inset ERT
9243 status Collapsed
9244
9245 \layout Standard
9246
9247 \backslash
9248 /
9249 \end_inset
9250
9251
9252 \series bold
9253 \emph default
9254 -model-large -c $(InputPath)
9255 \layout Section
9256
9257 Environment variables
9258 \begin_inset LatexCommand \index{Environment variables}
9259
9260 \end_inset
9261
9262
9263 \layout Standard
9264
9265 SDCC recognizes the following environment variables:
9266 \layout List
9267 \labelwidthstring 00.00.0000
9268
9269
9270 \series bold
9271 SDCC_LEAVE_SIGNALS
9272 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
9273
9274 \end_inset
9275
9276
9277 \series default
9278  SDCC installs a signal handler
9279 \begin_inset LatexCommand \index{signal handler}
9280
9281 \end_inset
9282
9283  to be able to delete temporary files after an user break (^C) or an exception.
9284  If this environment variable is set, SDCC won't install the signal handler
9285  in order to be able to debug SDCC.
9286 \layout List
9287 \labelwidthstring 00.00.0000
9288
9289
9290 \series bold
9291 TMP,\SpecialChar ~
9292 TEMP,\SpecialChar ~
9293 TMPDIR
9294 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
9295
9296 \end_inset
9297
9298
9299 \series default
9300  Path, where temporary files will be created.
9301  The order of the variables is the search order.
9302  In a standard *nix environment these variables are not set, and there's
9303  no need to set them.
9304  On Windows it's recommended to set one of them.
9305 \layout List
9306 \labelwidthstring 00.00.0000
9307
9308
9309 \series bold
9310 SDCC_HOME
9311 \begin_inset LatexCommand \index{SDCC\_HOME}
9312
9313 \end_inset
9314
9315
9316 \series default
9317  Path, see section
9318 \begin_inset LatexCommand \ref{sub:Install-paths}
9319
9320 \end_inset
9321
9322 \SpecialChar ~
9323
9324 \begin_inset Quotes sld
9325 \end_inset
9326
9327  Install Paths
9328 \begin_inset Quotes srd
9329 \end_inset
9330
9331 .
9332 \layout List
9333 \labelwidthstring 00.00.0000
9334
9335
9336 \series bold
9337 SDCC_INCLUDE
9338 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
9339
9340 \end_inset
9341
9342
9343 \series default
9344  Path, see section
9345 \begin_inset LatexCommand \ref{sub:Search-Paths}
9346
9347 \end_inset
9348
9349 \SpecialChar ~
9350
9351 \begin_inset Quotes sld
9352 \end_inset
9353
9354 Search Paths
9355 \begin_inset Quotes srd
9356 \end_inset
9357
9358 .
9359 \layout List
9360 \labelwidthstring 00.00.0000
9361
9362
9363 \series bold
9364 SDCC_LIB
9365 \begin_inset LatexCommand \index{SDCC\_LIB}
9366
9367 \end_inset
9368
9369
9370 \series default
9371  Path, see section
9372 \begin_inset LatexCommand \ref{sub:Search-Paths}
9373
9374 \end_inset
9375
9376 \SpecialChar ~
9377
9378 \begin_inset Quotes sld
9379 \end_inset
9380
9381 Search Paths
9382 \begin_inset Quotes srd
9383 \end_inset
9384
9385 ..
9386 \layout Standard
9387 \added_space_bottom bigskip
9388 There are some more environment variables recognized by SDCC, but these
9389  are solely used for debugging purposes.
9390  They can change or disappear very quickly, and will never be documented.
9391 \layout Section
9392
9393 Storage Class Language Extensions
9394 \layout Subsection
9395
9396 MCS51/DS390 Storage Class
9397 \begin_inset LatexCommand \index{Storage class}
9398
9399 \end_inset
9400
9401  Language Extensions
9402 \layout Standard
9403
9404 In addition to the ANSI storage classes SDCC allows the following MCS51
9405  specific storage classes:
9406 \layout Subsubsection
9407
9408 data
9409 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
9410
9411 \end_inset
9412
9413
9414 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
9415
9416 \end_inset
9417
9418  / near
9419 \begin_inset LatexCommand \index{near (storage class)}
9420
9421 \end_inset
9422
9423
9424 \begin_inset LatexCommand \index{\_\_near (storage class)}
9425
9426 \end_inset
9427
9428
9429 \layout Standard
9430
9431 This is the
9432 \series bold
9433 default
9434 \series default
9435  storage class for the Small Memory model (
9436 \emph on
9437 data
9438 \emph default
9439  and
9440 \emph on
9441 near
9442 \emph default
9443  or the more ANSI-C compliant forms
9444 \emph on
9445 __data
9446 \emph default
9447  and
9448 \emph on
9449 __near
9450 \emph default
9451  can be used synonymously).
9452  Variables declared with this storage class will be allocated in the directly
9453  addressable portion of the internal RAM of a 8051, e.g.:
9454 \layout Verse
9455
9456
9457 \family typewriter
9458 __data unsigned char test_data;
9459 \layout Standard
9460
9461 Writing 0x01 to this variable generates the assembly code:
9462 \layout Verse
9463
9464
9465 \family typewriter
9466 75*00 01\SpecialChar ~
9467 \SpecialChar ~
9468 \SpecialChar ~
9469 mov\SpecialChar ~
9470 \SpecialChar ~
9471 _test_data,#0x01
9472 \layout Subsubsection
9473
9474 xdata
9475 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9476
9477 \end_inset
9478
9479
9480 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
9481
9482 \end_inset
9483
9484  / far
9485 \begin_inset LatexCommand \index{far (storage class)}
9486
9487 \end_inset
9488
9489
9490 \begin_inset LatexCommand \index{\_\_far (storage class)}
9491
9492 \end_inset
9493
9494
9495 \layout Standard
9496
9497 Variables declared with this storage class will be placed in the external
9498  RAM.
9499  This is the
9500 \series bold
9501 default
9502 \series default
9503  storage class for the Large Memory model, e.g.:
9504 \layout Verse
9505
9506
9507 \family typewriter
9508 __xdata unsigned char test_xdata;
9509 \layout Standard
9510
9511 Writing 0x01 to this variable generates the assembly code:
9512 \layout Verse
9513
9514
9515 \family typewriter
9516 90s00r00\SpecialChar ~
9517 \SpecialChar ~
9518 \SpecialChar ~
9519 mov\SpecialChar ~
9520 \SpecialChar ~
9521 dptr,#_test_xdata
9522 \newline
9523 74\SpecialChar ~
9524 01\SpecialChar ~
9525 \SpecialChar ~
9526 \SpecialChar ~
9527 \SpecialChar ~
9528 \SpecialChar ~
9529 \SpecialChar ~
9530 mov\SpecialChar ~
9531 \SpecialChar ~
9532 a,#0x01
9533 \newline
9534 F0\SpecialChar ~
9535 \SpecialChar ~
9536 \SpecialChar ~
9537 \SpecialChar ~
9538 \SpecialChar ~
9539 \SpecialChar ~
9540 \SpecialChar ~
9541 \SpecialChar ~
9542 \SpecialChar ~
9543 movx\SpecialChar ~
9544 @dptr,a
9545 \layout Subsubsection
9546
9547 idata
9548 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
9549
9550 \end_inset
9551
9552
9553 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
9554
9555 \end_inset
9556
9557
9558 \layout Standard
9559
9560 Variables declared with this storage class will be allocated into the indirectly
9561  addressable portion of the internal ram of a 8051, e.g.:
9562 \layout Verse
9563
9564
9565 \family typewriter
9566 __idata unsigned char test_idata;
9567 \layout Standard
9568
9569 Writing 0x01 to this variable generates the assembly code:
9570 \layout Verse
9571
9572
9573 \family typewriter
9574 78r00\SpecialChar ~
9575 \SpecialChar ~
9576 \SpecialChar ~
9577 \SpecialChar ~
9578 \SpecialChar ~
9579 \SpecialChar ~
9580 \SpecialChar ~
9581 mov\SpecialChar ~
9582 \SpecialChar ~
9583 r0,#_test_idata
9584 \newline
9585 76\SpecialChar ~
9586 01\SpecialChar ~
9587 \SpecialChar ~
9588 \SpecialChar ~
9589 \SpecialChar ~
9590 \SpecialChar ~
9591 \SpecialChar ~
9592 \SpecialChar ~
9593 mov\SpecialChar ~
9594 \SpecialChar ~
9595 @r0,#0x01
9596 \layout Standard
9597
9598 Please note, the first 128 byte of idata physically access the same RAM
9599  as the data memory.
9600  The original 8051 had 128 byte idata memory, nowadays most devices have
9601  256 byte idata memory.
9602  The stack
9603 \begin_inset LatexCommand \index{stack}
9604
9605 \end_inset
9606
9607  is located in idata memory.
9608 \layout Subsubsection
9609
9610 pdata
9611 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
9612
9613 \end_inset
9614
9615
9616 \begin_inset LatexCommand \index{\_\_pdata (mcs51, ds390 storage class)}
9617
9618 \end_inset
9619
9620
9621 \layout Standard
9622
9623 Paged xdata access is just as straightforward as using the other addressing
9624  modes of a 8051.
9625  It is typically located at the start of xdata and has a maximum size of
9626  256 bytes.
9627  The following example writes 0x01 to the pdata variable.
9628  Please note, pdata access physically accesses xdata memory.
9629  The high byte of the address is determined by port P2
9630 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
9631
9632 \end_inset
9633
9634 (or in case of some 8051 variants by a separate Special Function Register,
9635  see section
9636 \begin_inset LatexCommand \ref{sub:MCS51-variants}
9637
9638 \end_inset
9639
9640 ).
9641  This is the
9642 \series bold
9643 default
9644 \series default
9645  storage class for the Medium Memory model, e.g.:
9646 \layout Verse
9647
9648
9649 \family typewriter
9650 __pdata unsigned char test_pdata;
9651 \layout Standard
9652
9653 Writing 0x01 to this variable generates the assembly code:
9654 \layout Verse
9655
9656
9657 \family typewriter
9658 78r00\SpecialChar ~
9659 \SpecialChar ~
9660 \SpecialChar ~
9661 \SpecialChar ~
9662 \SpecialChar ~
9663 \SpecialChar ~
9664 mov r0,#_test_pdata
9665 \newline
9666 74 01\SpecialChar ~
9667 \SpecialChar ~
9668 \SpecialChar ~
9669 \SpecialChar ~
9670 \SpecialChar ~
9671 \SpecialChar ~
9672 mov a,#0x01
9673 \newline
9674 F2\SpecialChar ~
9675 \SpecialChar ~
9676 \SpecialChar ~
9677 \SpecialChar ~
9678 \SpecialChar ~
9679 \SpecialChar ~
9680 \SpecialChar ~
9681 \SpecialChar ~
9682 \SpecialChar ~
9683 movx @r0,a
9684 \layout Standard
9685
9686 If the -
9687 \begin_inset ERT
9688 status Collapsed
9689
9690 \layout Standard
9691
9692 \backslash
9693 /
9694 \end_inset
9695
9696 -xstack
9697 \begin_inset LatexCommand \index{-\/-xstack}
9698
9699 \end_inset
9700
9701  option is used the pdata memory area is followed by the xstack memory area
9702  and the sum of their sizes is limited to 256 bytes.
9703 \layout Subsubsection
9704
9705 code
9706 \begin_inset LatexCommand \index{code}
9707
9708 \end_inset
9709
9710
9711 \begin_inset LatexCommand \index{\_\_code}
9712
9713 \end_inset
9714
9715
9716 \layout Standard
9717
9718 'Variables' declared with this storage class will be placed in the code
9719  memory:
9720 \layout Verse
9721
9722
9723 \family typewriter
9724 __code unsigned char test_code;
9725 \layout Standard
9726
9727 Read access to this variable generates the assembly code:
9728 \layout Verse
9729
9730
9731 \family typewriter
9732 90s00r6F\SpecialChar ~
9733 \SpecialChar ~
9734 \SpecialChar ~
9735 mov dptr,#_test_code
9736 \newline
9737 E4\SpecialChar ~
9738 \SpecialChar ~
9739 \SpecialChar ~
9740 \SpecialChar ~
9741 \SpecialChar ~
9742 \SpecialChar ~
9743 \SpecialChar ~
9744 \SpecialChar ~
9745 \SpecialChar ~
9746 clr a
9747 \newline
9748 93\SpecialChar ~
9749 \SpecialChar ~
9750 \SpecialChar ~
9751 \SpecialChar ~
9752 \SpecialChar ~
9753 \SpecialChar ~
9754 \SpecialChar ~
9755 \SpecialChar ~
9756 \SpecialChar ~
9757 movc a,@a+dptr
9758 \layout Standard
9759
9760
9761 \family typewriter
9762 char
9763 \family default
9764  indexed arrays of characters in code memory can be accessed efficiently:
9765 \layout Verse
9766
9767
9768 \family typewriter
9769 __code char test_array[] = {'c','h','e','a','p'};
9770 \layout Standard
9771
9772 Read access to this array using an 8-bit unsigned index generates the assembly
9773  code:
9774 \layout Verse
9775
9776
9777 \family typewriter
9778 E5*00\SpecialChar ~
9779 \SpecialChar ~
9780 \SpecialChar ~
9781 \SpecialChar ~
9782 \SpecialChar ~
9783 \SpecialChar ~
9784 mov a,_index
9785 \layout Verse
9786
9787
9788 \family typewriter
9789 90s00r41\SpecialChar ~
9790 \SpecialChar ~
9791 \SpecialChar ~
9792 mov dptr,#_test_array
9793 \layout Verse
9794
9795
9796 \family typewriter
9797 93\SpecialChar ~
9798 \SpecialChar ~
9799 \SpecialChar ~
9800 \SpecialChar ~
9801 \SpecialChar ~
9802 \SpecialChar ~
9803 \SpecialChar ~
9804 \SpecialChar ~
9805 \SpecialChar ~
9806 movc a,@a+dptr
9807 \layout Subsubsection
9808
9809 bit
9810 \begin_inset LatexCommand \index{bit}
9811
9812 \end_inset
9813
9814
9815 \begin_inset LatexCommand \index{\_\_bit}
9816
9817 \end_inset
9818
9819
9820 \layout Standard
9821
9822 This is a data-type and a storage class specifier.
9823  When a variable is declared as a bit, it is allocated into the bit addressable
9824  memory of 8051, e.g.:
9825 \layout Verse
9826
9827
9828 \family typewriter
9829 __bit test_bit;
9830 \layout Standard
9831
9832 Writing 1 to this variable generates the assembly code:
9833 \layout Verse
9834
9835
9836 \family typewriter
9837 D2*00\SpecialChar ~
9838 \SpecialChar ~
9839 \SpecialChar ~
9840 \SpecialChar ~
9841 \SpecialChar ~
9842 \SpecialChar ~
9843 \SpecialChar ~
9844 setb\SpecialChar ~
9845 _test_bit
9846 \layout Standard
9847
9848 The bit addressable memory consists of 128 bits which are located from 0x20
9849  to 0x2f in data memory.
9850
9851 \newline
9852 Apart from this 8051 specific storage class most architectures support ANSI-C
9853  bitfields
9854 \begin_inset LatexCommand \index{bitfields}
9855
9856 \end_inset
9857
9858
9859 \begin_inset Foot
9860 collapsed false
9861
9862 \layout Standard
9863
9864 Not really meant as examples, but nevertheless showing what bitfields are
9865  about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
9866 \end_inset
9867
9868 .
9869  In accordance with ISO/IEC 9899 bits and bitfields without an explicit
9870  signed modifier are implemented as unsigned.
9871 \layout Subsubsection
9872
9873 sfr
9874 \begin_inset LatexCommand \index{sfr}
9875
9876 \end_inset
9877
9878
9879 \begin_inset LatexCommand \index{\_\_sfr}
9880
9881 \end_inset
9882
9883  / sfr16
9884 \begin_inset LatexCommand \index{sfr16}
9885
9886 \end_inset
9887
9888
9889 \begin_inset LatexCommand \index{\_\_sfr16}
9890
9891 \end_inset
9892
9893  / sfr32
9894 \begin_inset LatexCommand \index{sfr32}
9895
9896 \end_inset
9897
9898
9899 \begin_inset LatexCommand \index{\_\_sfr32}
9900
9901 \end_inset
9902
9903  / sbit
9904 \begin_inset LatexCommand \index{\_\_sbit}
9905
9906 \end_inset
9907
9908
9909 \begin_inset LatexCommand \index{sbit}
9910
9911 \end_inset
9912
9913
9914 \layout Standard
9915
9916 Like the bit keyword,
9917 \emph on
9918 sfr / sfr16 / sfr32 / sbit
9919 \emph default
9920 signify both a data-type and storage class, they are used to describe the
9921
9922 \emph on
9923 s
9924 \emph default
9925 pecial
9926 \emph on
9927 f
9928 \emph default
9929 unction
9930 \emph on
9931 r
9932 \emph default
9933 egisters and
9934 \emph on
9935 s
9936 \emph default
9937 pecial
9938 \emph on
9939 bit
9940 \emph default
9941  variables of a 8051, eg:
9942 \layout Verse
9943
9944
9945 \family typewriter
9946 __sfr __at
9947 \begin_inset LatexCommand \index{at}
9948
9949 \end_inset
9950
9951
9952 \begin_inset LatexCommand \index{\_\_at}
9953
9954 \end_inset
9955
9956  (0x80) P0;\SpecialChar ~
9957  /* special function register P0 at location 0x80 */
9958 \newline
9959
9960 \newline
9961 /* 16 bit special function register combination for timer 0
9962 \newline
9963 \SpecialChar ~
9964 \SpecialChar ~
9965  with the high byte at location 0x8C and the low byte at location 0x8A */
9966 \newline
9967 __sfr16 __at (0x8C8A) TMR0;
9968 \newline
9969
9970 \newline
9971 __sbit __at
9972 \begin_inset LatexCommand \index{at}
9973
9974 \end_inset
9975
9976
9977 \begin_inset LatexCommand \index{\_\_at}
9978
9979 \end_inset
9980
9981  (0xd7) CY;\SpecialChar ~
9982  /* CY (Carry Flag
9983 \begin_inset LatexCommand \index{Flags}
9984
9985 \end_inset
9986
9987
9988 \begin_inset LatexCommand \index{Carry flag}
9989
9990 \end_inset
9991
9992 ) */
9993 \layout Standard
9994
9995 Special function registers which are located on an address dividable by
9996  8 are bit-addressable, an
9997 \emph on
9998  sbit
9999 \emph default
10000  addresses a specific bit within these sfr.
10001 \newline
10002 16 Bit and 32 bit special function register combinations which require a
10003  certain access order are better not declared using
10004 \emph on
10005 sfr16
10006 \emph default
10007  or
10008 \emph on
10009 sfr32.
10010
10011 \emph default
10012  Allthough SDCC usually accesses them Least Significant Byte (LSB) first,
10013  this is not guaranteed.
10014 \newline
10015
10016 \layout Standard
10017
10018 Please note, if you use a header file which was written for another compiler
10019  then the sfr / sfr16 / sfr32 / sbit Storage Class extensions will most
10020  likely be
10021 \emph on
10022 not
10023 \emph default
10024 compatible.
10025  Specifically the syntax
10026 \family typewriter
10027 \SpecialChar ~
10028 sfr P0 = 0x80;\SpecialChar ~
10029
10030 \family default
10031  is compiled
10032 \emph on
10033 without warning
10034 \emph default
10035  by SDCC to an assignment of 0x80 to a variable called P0
10036 \family typewriter
10037
10038 \begin_inset Marginal
10039 collapsed true
10040
10041 \layout Standard
10042
10043
10044 \series bold
10045 \SpecialChar ~
10046 !
10047 \end_inset
10048
10049 .
10050
10051 \family default
10052 Nevertheless it is possible to write header files
10053 \begin_inset LatexCommand \index{Header files}
10054
10055 \end_inset
10056
10057
10058 \begin_inset LatexCommand \index{Include files}
10059
10060 \end_inset
10061
10062  which can be shared among different compilers (see section
10063 \begin_inset LatexCommand \ref{sec:Porting-code-to-other-compilers}
10064
10065 \end_inset
10066
10067 ).
10068
10069 \layout Subsubsection
10070
10071 Pointers
10072 \begin_inset LatexCommand \index{Pointer}
10073
10074 \end_inset
10075
10076  to MCS51/DS390 specific memory spaces
10077 \layout Standard
10078
10079 SDCC allows (via language extensions) pointers to explicitly point to any
10080  of the memory spaces
10081 \begin_inset LatexCommand \index{Memory model}
10082
10083 \end_inset
10084
10085  of the 8051.
10086  In addition to the explicit pointers, the compiler uses (by default) generic
10087  pointers which can be used to point to any of the memory spaces.
10088 \newline
10089
10090 \newline
10091 Pointer declaration examples:
10092 \layout Verse
10093
10094
10095 \family typewriter
10096 /* pointer physically in internal ram pointing to object in external ram
10097  */
10098 \newline
10099 __xdata unsigned char * __data p;
10100 \newline
10101
10102 \newline
10103 /* pointer physically in external ram pointing to object in internal ram
10104  */
10105 \newline
10106 __data unsigned char * __xdata p;
10107 \newline
10108
10109 \newline
10110 /* pointer physically in code rom pointing to data in xdata space */
10111 \newline
10112 __xdata unsigned char * __code p;
10113 \newline
10114
10115 \newline
10116 /* pointer physically in code space pointing to data in code space */
10117 \newline
10118 __code unsigned char * __code p;
10119 \newline
10120
10121 \newline
10122 /* generic pointer physically located in xdata space */
10123 \newline
10124 unsigned char * __xdata p;
10125 \newline
10126
10127 \newline
10128 /* generic pointer physically located in default memory space */
10129 \newline
10130 unsigned char * p;
10131 \newline
10132
10133 \newline
10134 /* the following is a function pointer
10135 \begin_inset LatexCommand \index{function pointer}
10136
10137 \end_inset
10138
10139  physically located in data space */
10140 \newline
10141 char (* __data fp)(void);
10142 \layout Standard
10143
10144 Well you get the idea.
10145
10146 \newline
10147
10148 \newline
10149 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
10150 \emph on
10151 generic
10152 \emph default
10153  pointers.
10154
10155 \size small
10156
10157 \newline
10158
10159 \newline
10160
10161 \size default
10162 The highest order byte of the
10163 \emph on
10164 generic
10165 \emph default
10166  pointers contains the data space information.
10167  Assembler support routines are called whenever data is stored or retrieved
10168  using
10169 \emph on
10170 generic
10171 \emph default
10172  pointers.
10173  These are useful for developing reusable library
10174 \begin_inset LatexCommand \index{Libraries}
10175
10176 \end_inset
10177
10178  routines.
10179  Explicitly specifying the pointer
10180 \begin_inset LatexCommand \index{pointer}
10181
10182 \end_inset
10183
10184  type will generate the most efficient code.
10185 \layout Subsubsection
10186
10187 Notes on MCS51 memory
10188 \begin_inset LatexCommand \index{MCS51 memory}
10189
10190 \end_inset
10191
10192  layout
10193 \layout Standard
10194
10195 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
10196  RAM memory which is structured as follows:
10197 \newline
10198
10199 \newline
10200 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
10201
10202 \newline
10203 - Bytes 20-2F - 16 bytes to hold 128 bit
10204 \begin_inset LatexCommand \index{bit}
10205
10206 \end_inset
10207
10208  variables and,
10209 \newline
10210 - Bytes 30-7F - 80 bytes for general purpose use.
10211 \newline
10212
10213 \layout Standard
10214
10215 Additionally some members of the MCS51 family may have up to 128 bytes of
10216  additional, indirectly addressable, internal RAM memory (
10217 \emph on
10218 idata
10219 \emph default
10220
10221 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
10222
10223 \end_inset
10224
10225
10226 \begin_inset LatexCommand \index{\_\_idata (mcs51, ds390 storage class)}
10227
10228 \end_inset
10229
10230 ).
10231  Furthermore, some chips may have some built in external memory (
10232 \emph on
10233 xdata
10234 \emph default
10235
10236 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
10237
10238 \end_inset
10239
10240
10241 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
10242
10243 \end_inset
10244
10245 ) which should not be confused with the internal, directly addressable RAM
10246  memory (
10247 \emph on
10248 data
10249 \emph default
10250
10251 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
10252
10253 \end_inset
10254
10255
10256 \begin_inset LatexCommand \index{\_\_data (mcs51, ds390 storage class)}
10257
10258 \end_inset
10259
10260 ).
10261  Sometimes this built in
10262 \emph on
10263 xdata
10264 \emph default
10265  memory has to be activated before using it (you can probably find this
10266  information on the datasheet of the microcontroller your are using, see
10267  also section
10268 \begin_inset LatexCommand \ref{sub:Startup-Code}
10269
10270 \end_inset
10271
10272 \SpecialChar ~
10273 Startup-Code).
10274 \layout Standard
10275
10276 Normally SDCC will only use the first bank
10277 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
10278
10279 \end_inset
10280
10281  of registers (register bank 0), but it is possible to specify that other
10282  banks of registers (keyword
10283 \emph on
10284 using
10285 \emph default
10286
10287 \emph on
10288
10289 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10290
10291 \end_inset
10292
10293
10294 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
10295
10296 \end_inset
10297
10298
10299 \emph default
10300 ) should be used in interrupt
10301 \begin_inset LatexCommand \index{interrupt}
10302
10303 \end_inset
10304
10305
10306 \begin_inset LatexCommand \index{\_\_interrupt}
10307
10308 \end_inset
10309
10310  routines.
10311  By default, the compiler will place the stack after the last byte of allocated
10312  memory for variables.
10313  For example, if the first 2 banks of registers are used, and only four
10314  bytes are used for
10315 \emph on
10316 data
10317 \emph default
10318  variables, it will position the base of the internal stack at address 20
10319  (0x14).
10320  This implies that as the stack
10321 \begin_inset LatexCommand \index{stack}
10322
10323 \end_inset
10324
10325  grows, it will use up the remaining register banks, and the 16 bytes used
10326  by the 128 bit variables, and 80 bytes for general purpose use.
10327  If any bit variables are used, the data variables will be placed in unused
10328  register banks and after the byte holding the last bit variable.
10329  For example, if register banks 0 and 1 are used, and there are 9 bit variables
10330  (two bytes used),
10331 \emph on
10332 data
10333 \emph default
10334  variables will be placed starting from address 0x10 to 0x20 and continue
10335  at address 0x22.
10336  You can also use -
10337 \begin_inset ERT
10338 status Collapsed
10339
10340 \layout Standard
10341
10342 \backslash
10343 /
10344 \end_inset
10345
10346 -data-loc
10347 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
10348
10349 \end_inset
10350
10351  to specify the start address of the
10352 \emph on
10353 data
10354 \emph default
10355  and -
10356 \begin_inset ERT
10357 status Collapsed
10358
10359 \layout Standard
10360
10361 \backslash
10362 /
10363 \end_inset
10364
10365 -iram-size
10366 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
10367
10368 \end_inset
10369
10370  to specify the size of the total internal RAM (
10371 \emph on
10372 data
10373 \emph default
10374 +
10375 \emph on
10376 idata
10377 \emph default
10378 ).
10379
10380 \newline
10381
10382 \layout Standard
10383
10384 By default the 8051 linker will place the stack after the last byte of (i)data
10385  variables.
10386  Option -
10387 \begin_inset ERT
10388 status Collapsed
10389
10390 \layout Standard
10391
10392 \backslash
10393 /
10394 \end_inset
10395
10396 -stack-loc
10397 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
10398
10399 \end_inset
10400
10401  allows you to specify the start of the stack, i.e.
10402  you could start it after any data in the general purpose area.
10403  If your microcontroller has additional indirectly addressable internal
10404  RAM (
10405 \emph on
10406 idata
10407 \emph default
10408 ) you can place the stack on it.
10409  You may also need to use -
10410 \begin_inset ERT
10411 status Collapsed
10412
10413 \layout Standard
10414
10415 \backslash
10416 /
10417 \end_inset
10418
10419 -xdata-loc
10420 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
10421
10422 \end_inset
10423
10424  to set the start address of the external RAM (
10425 \emph on
10426 xdata
10427 \emph default
10428 ) and -
10429 \begin_inset ERT
10430 status Collapsed
10431
10432 \layout Standard
10433
10434 \backslash
10435 /
10436 \end_inset
10437
10438 -xram-size
10439 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
10440
10441 \end_inset
10442
10443  to specify its size.
10444  Same goes for the code memory, using -
10445 \begin_inset ERT
10446 status Collapsed
10447
10448 \layout Standard
10449
10450 \backslash
10451 /
10452 \end_inset
10453
10454 -code-loc
10455 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
10456
10457 \end_inset
10458
10459  and -
10460 \begin_inset ERT
10461 status Collapsed
10462
10463 \layout Standard
10464
10465 \backslash
10466 /
10467 \end_inset
10468
10469 -code-size
10470 \begin_inset LatexCommand \index{-\/-code-size <Value>}
10471
10472 \end_inset
10473
10474 .
10475  If in doubt, don't specify any options and see if the resulting memory
10476  layout is appropriate, then you can adjust it.
10477 \layout Standard
10478 \added_space_bottom bigskip
10479 The linker generates two files with memory allocation information.
10480  The first, with extension .map
10481 \begin_inset LatexCommand \index{<file>.map}
10482
10483 \end_inset
10484
10485  shows all the variables and segments.
10486  The second with extension .mem
10487 \begin_inset LatexCommand \index{<file>.mem}
10488
10489 \end_inset
10490
10491  shows the final memory layout.
10492  The linker will complain either if memory segments overlap, there is not
10493  enough memory, or there is not enough space for stack.
10494  If you get any linking warnings and/or errors related to stack or segments
10495  allocation, take a look at either the .map or .mem files to find out what
10496  the problem is.
10497  The .mem file may even suggest a solution to the problem.
10498 \layout Subsection
10499
10500 Z80/Z180 Storage Class
10501 \begin_inset LatexCommand \index{Z80!Storage class}
10502
10503 \end_inset
10504
10505  Language Extensions
10506 \layout Subsubsection
10507
10508 sfr
10509 \begin_inset LatexCommand \index{sfr}
10510
10511 \end_inset
10512
10513
10514 \begin_inset LatexCommand \index{\_\_sfr}
10515
10516 \end_inset
10517
10518  (in/out to 8-bit addresses)
10519 \layout Standard
10520
10521 The Z80
10522 \begin_inset LatexCommand \index{Z80}
10523
10524 \end_inset
10525
10526  family has separate address spaces for memory and
10527 \emph on
10528 i
10529 \emph default
10530 nput/
10531 \emph on
10532 o
10533 \emph default
10534 utput memory.
10535  I/O memory
10536 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
10537
10538 \end_inset
10539
10540
10541 \begin_inset LatexCommand \index{Z80!I/O memory}
10542
10543 \end_inset
10544
10545
10546 \begin_inset LatexCommand \index{Z180!I/O memory}
10547
10548 \end_inset
10549
10550  is accessed with special instructions, e.g.:
10551 \layout Verse
10552
10553
10554 \family typewriter
10555 sfr at 0x78 IoPort;\SpecialChar ~
10556 \SpecialChar ~
10557 /* define a var in I/O space at 78h called IoPort */
10558
10559 \layout Standard
10560
10561 Writing 0x01 to this variable generates the assembly code:
10562 \layout Verse
10563
10564
10565 \family typewriter
10566 3E 01\SpecialChar ~
10567 \SpecialChar ~
10568 \SpecialChar ~
10569 \SpecialChar ~
10570 \SpecialChar ~
10571 \SpecialChar ~
10572 ld a,#0x01
10573 \newline
10574 D3 78\SpecialChar ~
10575 \SpecialChar ~
10576 \SpecialChar ~
10577 \SpecialChar ~
10578 \SpecialChar ~
10579 \SpecialChar ~
10580 out (_IoPort),a
10581 \layout Subsubsection
10582
10583 banked sfr
10584 \begin_inset LatexCommand \index{sfr}
10585
10586 \end_inset
10587
10588
10589 \begin_inset LatexCommand \index{\_\_sfr}
10590
10591 \end_inset
10592
10593  (in/out to 16-bit addresses)
10594 \layout Standard
10595
10596 The keyword
10597 \emph on
10598 banked
10599 \emph default
10600  is used to support 16 bit addresses in I/O memory e.g.:
10601 \layout Verse
10602
10603
10604 \family typewriter
10605 sfr banked at
10606 \begin_inset LatexCommand \index{at}
10607
10608 \end_inset
10609
10610
10611 \begin_inset LatexCommand \index{\_\_at}
10612
10613 \end_inset
10614
10615  0x123 IoPort;
10616 \layout Standard
10617
10618 Writing 0x01 to this variable generates the assembly code:
10619 \layout Verse
10620
10621
10622 \family typewriter
10623 01 23 01\SpecialChar ~
10624 \SpecialChar ~
10625 \SpecialChar ~
10626 ld bc,#_IoPort
10627 \newline
10628 3E 01\SpecialChar ~
10629 \SpecialChar ~
10630 \SpecialChar ~
10631 \SpecialChar ~
10632 \SpecialChar ~
10633 \SpecialChar ~
10634 ld a,#0x01
10635 \newline
10636 ED 79\SpecialChar ~
10637 \SpecialChar ~
10638 \SpecialChar ~
10639 \SpecialChar ~
10640 \SpecialChar ~
10641 \SpecialChar ~
10642 out (c),a
10643 \layout Subsubsection
10644
10645 sfr
10646 \begin_inset LatexCommand \index{sfr}
10647
10648 \end_inset
10649
10650
10651 \begin_inset LatexCommand \index{\_\_sfr}
10652
10653 \end_inset
10654
10655  (in0/out0 to 8 bit addresses on Z180
10656 \begin_inset LatexCommand \index{Z180}
10657
10658 \end_inset
10659
10660 /HD64180
10661 \begin_inset LatexCommand \index{HD64180 (see Z180)}
10662
10663 \end_inset
10664
10665 )
10666 \layout Standard
10667 \added_space_bottom bigskip
10668 The compiler option -
10669 \begin_inset ERT
10670 status Collapsed
10671
10672 \layout Standard
10673
10674 \backslash
10675 /
10676 \end_inset
10677
10678 -portmode
10679 \begin_inset LatexCommand \index{Z180!Options!-\/-portmode}
10680
10681 \end_inset
10682
10683 =180 (80) and a compiler #pragma\SpecialChar ~
10684 portmode
10685 \begin_inset LatexCommand \index{Z180!Pragmas!\#pragma portmode}
10686
10687 \end_inset
10688
10689  z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
10690 ns
10691 \family typewriter
10692 in0/out0
10693 \family default
10694  instead of
10695 \family typewriter
10696 in/out
10697 \family default
10698 .
10699  If you include the file z180.h this will be set automatically.
10700 \layout Subsection
10701
10702 HC08 Storage Class
10703 \begin_inset LatexCommand \index{HC08!Storage class}
10704
10705 \end_inset
10706
10707  Language Extensions
10708 \layout Subsubsection
10709
10710 data
10711 \begin_inset LatexCommand \index{data (hc08 storage class)}
10712
10713 \end_inset
10714
10715
10716 \begin_inset LatexCommand \index{\_\_data (hc08 storage class)}
10717
10718 \end_inset
10719
10720
10721 \layout Standard
10722
10723 The data storage class declares a variable that resides in the first 256
10724  bytes of memory (the direct page).
10725  The HC08
10726 \begin_inset LatexCommand \index{HC08}
10727
10728 \end_inset
10729
10730  is most efficient at accessing variables (especially pointers) stored here.
10731 \layout Subsubsection
10732
10733 xdata
10734 \begin_inset LatexCommand \index{xdata (hc08 storage class)}
10735
10736 \end_inset
10737
10738
10739 \begin_inset LatexCommand \index{\_\_xdata (hc08 storage class)}
10740
10741 \end_inset
10742
10743
10744 \layout Standard
10745 \added_space_bottom bigskip
10746 The xdata storage class declares a variable that can reside anywhere in
10747  memory.
10748  This is the default if no storage class is specified.
10749
10750 \layout Section
10751
10752 Absolute Addressing
10753 \begin_inset LatexCommand \index{Absolute addressing}
10754
10755 \end_inset
10756
10757
10758 \layout Standard
10759
10760 Data items can be assigned an absolute address with the
10761 \emph on
10762 at
10763 \begin_inset LatexCommand \index{at}
10764
10765 \end_inset
10766
10767
10768 \begin_inset LatexCommand \index{\_\_at}
10769
10770 \end_inset
10771
10772  <address>
10773 \emph default
10774  keyword, in addition to a storage class, e.g.:
10775 \layout Verse
10776
10777
10778 \family typewriter
10779 xdata
10780 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
10781
10782 \end_inset
10783
10784
10785 \begin_inset LatexCommand \index{\_\_xdata (mcs51, ds390 storage class)}
10786
10787 \end_inset
10788
10789  at
10790 \begin_inset LatexCommand \index{at}
10791
10792 \end_inset
10793
10794
10795 \begin_inset LatexCommand \index{\_\_at}
10796
10797 \end_inset
10798
10799  0x7ffe unsigned int chksum;
10800 \layout Standard
10801
10802 or, better conforming to ISO/IEC 9899 C:
10803 \layout Verse
10804
10805
10806 \family typewriter
10807 __xdata __at (0x7ffe) unsigned int chksum;
10808 \layout Standard
10809
10810 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
10811  of the external ram.
10812  The compiler does
10813 \emph on
10814 not
10815 \emph default
10816  reserve any space for variables declared in this way
10817 \begin_inset Marginal
10818 collapsed true
10819
10820 \layout Standard
10821
10822
10823 \series bold
10824 \SpecialChar ~
10825 !
10826 \end_inset
10827
10828  (they are implemented with an equate in the assembler).
10829  Thus it is left to the programmer to make sure there are no overlaps with
10830  other variables that are declared without the absolute address.
10831  The assembler listing file (.lst
10832 \begin_inset LatexCommand \index{<file>.lst}
10833
10834 \end_inset
10835
10836 ) and the linker output files (.rst
10837 \begin_inset LatexCommand \index{<file>.rst}
10838
10839 \end_inset
10840
10841 ) and (.map
10842 \begin_inset LatexCommand \index{<file>.map}
10843
10844 \end_inset
10845
10846 ) are good places to look for such overlaps.
10847  Variables with an absolute address are
10848 \emph on
10849 not
10850 \begin_inset Marginal
10851 collapsed true
10852
10853 \layout Standard
10854
10855
10856 \series bold
10857 \SpecialChar ~
10858 !
10859 \end_inset
10860
10861
10862 \emph default
10863  initialized
10864 \begin_inset LatexCommand \index{Variable initialization}
10865
10866 \end_inset
10867
10868 .
10869 \layout Standard
10870
10871 In case of memory mapped I/O devices the keyword
10872 \emph on
10873 volatile
10874 \emph default
10875  has to be used to tell the compiler that accesses might not be removed:
10876 \layout Verse
10877
10878
10879 \family typewriter
10880 volatile
10881 \begin_inset LatexCommand \index{volatile}
10882
10883 \end_inset
10884
10885  __xdata
10886 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
10887
10888 \end_inset
10889
10890  __at
10891 \begin_inset LatexCommand \index{at}
10892
10893 \end_inset
10894
10895  (0x8000) unsigned char PORTA_8255;
10896 \layout Standard
10897
10898 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
10899 r) array
10900 \family typewriter
10901 \size footnotesize
10902
10903 \begin_inset LatexCommand \index{Aligned array}
10904
10905 \end_inset
10906
10907
10908 \family default
10909 \size default
10910  starts at a block (256 byte) boundary
10911 \begin_inset LatexCommand \index{block boundary}
10912
10913 \end_inset
10914
10915  (section
10916 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
10917
10918 \end_inset
10919
10920  has an example).
10921 \newline
10922 Absolute addresses can be specified for variables in all storage classes,
10923  e.g.:
10924 \layout Verse
10925
10926
10927 \family typewriter
10928 __bit
10929 \begin_inset LatexCommand \index{bit}
10930
10931 \end_inset
10932
10933  __at
10934 \begin_inset LatexCommand \index{at}
10935
10936 \end_inset
10937
10938  (0x02) bvar;
10939 \layout Standard
10940
10941 The above example will allocate the variable at offset 0x02 in the bit-addressab
10942 le space.
10943  There is no real advantage to assigning absolute addresses to variables
10944  in this manner, unless you want strict control over all the variables allocated.
10945  One possible use would be to write hardware portable code.
10946  For example, if you have a routine that uses one or more of the microcontroller
10947  I/O pins, and such pins are different for two different hardwares, you
10948  can declare the I/O pins in your routine using:
10949 \layout Verse
10950
10951
10952 \family typewriter
10953 extern volatile
10954 \begin_inset LatexCommand \index{volatile}
10955
10956 \end_inset
10957
10958  __bit MOSI;\SpecialChar ~
10959 \SpecialChar ~
10960 \SpecialChar ~
10961 \SpecialChar ~
10962 /* master out, slave in */
10963 \newline
10964 extern volatile __bit MISO;\SpecialChar ~
10965 \SpecialChar ~
10966 \SpecialChar ~
10967 \SpecialChar ~
10968 /* master in, slave out */
10969 \newline
10970 extern volatile __bit MCLK;\SpecialChar ~
10971 \SpecialChar ~
10972 \SpecialChar ~
10973 \SpecialChar ~
10974 /* master clock */
10975 \newline
10976
10977 \newline
10978 /* Input and Output of a byte on a 3-wire serial bus.
10979 \newline
10980 \SpecialChar ~
10981 \SpecialChar ~
10982 \SpecialChar ~
10983 If needed adapt polarity of clock, polarity of data and bit order
10984 \newline
10985 \SpecialChar ~
10986 */
10987 \newline
10988 unsigned char spi_io(unsigned char out_byte)
10989 \newline
10990 {
10991 \newline
10992 \SpecialChar ~
10993 \SpecialChar ~
10994 \SpecialChar ~
10995 \SpecialChar ~
10996 unsigned char i=8;
10997 \newline
10998 \SpecialChar ~
10999 \SpecialChar ~
11000 \SpecialChar ~
11001 \SpecialChar ~
11002 do {
11003 \newline
11004 \SpecialChar ~
11005 \SpecialChar ~
11006 \SpecialChar ~
11007 \SpecialChar ~
11008 \SpecialChar ~
11009 \SpecialChar ~
11010 \SpecialChar ~
11011 \SpecialChar ~
11012 MOSI = out_byte & 0x80;
11013 \newline
11014 \SpecialChar ~
11015 \SpecialChar ~
11016 \SpecialChar ~
11017 \SpecialChar ~
11018 \SpecialChar ~
11019 \SpecialChar ~
11020 \SpecialChar ~
11021 \SpecialChar ~
11022 out_byte <<= 1;
11023 \newline
11024 \SpecialChar ~
11025 \SpecialChar ~
11026 \SpecialChar ~
11027 \SpecialChar ~
11028 \SpecialChar ~
11029 \SpecialChar ~
11030 \SpecialChar ~
11031 \SpecialChar ~
11032 MCLK = 1;
11033 \newline
11034 \SpecialChar ~
11035 \SpecialChar ~
11036 \SpecialChar ~
11037 \SpecialChar ~
11038 \SpecialChar ~
11039 \SpecialChar ~
11040 \SpecialChar ~
11041 \SpecialChar ~
11042 /* _asm nop _endasm; */\SpecialChar ~
11043 \SpecialChar ~
11044 \SpecialChar ~
11045 \SpecialChar ~
11046 \SpecialChar ~
11047 \SpecialChar ~
11048 \SpecialChar ~
11049 \SpecialChar ~
11050 /* for slow peripherals */
11051 \newline
11052 \SpecialChar ~
11053 \SpecialChar ~
11054 \SpecialChar ~
11055 \SpecialChar ~
11056 \SpecialChar ~
11057 \SpecialChar ~
11058 \SpecialChar ~
11059 \SpecialChar ~
11060 if(MISO)
11061 \newline
11062 \SpecialChar ~
11063 \SpecialChar ~
11064 \SpecialChar ~
11065 \SpecialChar ~
11066 \SpecialChar ~
11067 \SpecialChar ~
11068 \SpecialChar ~
11069 \SpecialChar ~
11070 \SpecialChar ~
11071 \SpecialChar ~
11072 \SpecialChar ~
11073 \SpecialChar ~
11074 out_byte += 1;
11075 \newline
11076 \SpecialChar ~
11077 \SpecialChar ~
11078 \SpecialChar ~
11079 \SpecialChar ~
11080 \SpecialChar ~
11081 \SpecialChar ~
11082 \SpecialChar ~
11083 \SpecialChar ~
11084 MCLK = 0;
11085 \newline
11086 \SpecialChar ~
11087 \SpecialChar ~
11088 \SpecialChar ~
11089 \SpecialChar ~
11090 } while(--i);
11091 \newline
11092 \SpecialChar ~
11093 \SpecialChar ~
11094 \SpecialChar ~
11095 \SpecialChar ~
11096 return out_byte;
11097 \newline
11098 }
11099 \layout Standard
11100
11101 Then, someplace in the code for the first hardware you would use
11102 \layout Verse
11103
11104
11105 \family typewriter
11106 __bit __at
11107 \begin_inset LatexCommand \index{at}
11108
11109 \end_inset
11110
11111
11112 \begin_inset LatexCommand \index{\_\_at}
11113
11114 \end_inset
11115
11116  (0x80) MOSI;\SpecialChar ~
11117 \SpecialChar ~
11118 \SpecialChar ~
11119 \SpecialChar ~
11120 /* I/O port 0, bit 0 */
11121 \newline
11122 __bit __at (0x81) MISO;\SpecialChar ~
11123 \SpecialChar ~
11124 \SpecialChar ~
11125 \SpecialChar ~
11126 /* I/O port 0, bit 1 */
11127 \newline
11128 __bit __at (0x82) MCLK;\SpecialChar ~
11129 \SpecialChar ~
11130 \SpecialChar ~
11131 \SpecialChar ~
11132 /* I/O port 0, bit 2 */
11133 \layout Standard
11134
11135 Similarly, for the second hardware you would use
11136 \layout Verse
11137
11138
11139 \family typewriter
11140 __bit __at (0x83) MOSI;\SpecialChar ~
11141 \SpecialChar ~
11142 \SpecialChar ~
11143 \SpecialChar ~
11144 /* I/O port 0, bit 3 */
11145 \newline
11146 __bit __at (0x91) MISO;\SpecialChar ~
11147 \SpecialChar ~
11148 \SpecialChar ~
11149 \SpecialChar ~
11150 /* I/O port 1, bit 1 */
11151 \newline
11152 __bit
11153 \begin_inset LatexCommand \index{bit}
11154
11155 \end_inset
11156
11157  __at (0x92) MCLK;\SpecialChar ~
11158 \SpecialChar ~
11159 \SpecialChar ~
11160 \SpecialChar ~
11161 /* I/O port 1, bit 2 */
11162 \layout Standard
11163 \added_space_bottom bigskip
11164 and you can use the same hardware dependent routine without changes, as
11165  for example in a library.
11166  This is somehow similar to sbit, but only one absolute address has to be
11167  specified in the whole project.
11168 \layout Section
11169
11170 Parameters
11171 \begin_inset LatexCommand \index{Parameters}
11172
11173 \end_inset
11174
11175
11176 \begin_inset LatexCommand \index{function parameter}
11177
11178 \end_inset
11179
11180  & Local Variables
11181 \begin_inset LatexCommand \index{local variables}
11182
11183 \end_inset
11184
11185
11186 \begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
11187
11188 \end_inset
11189
11190
11191 \layout Standard
11192
11193 Automatic (local) variables and parameters to functions can either be placed
11194  on the stack or in data-space.
11195  The default action of the compiler is to place these variables in the internal
11196  RAM (for small model) or external RAM (for large model).
11197  This in fact makes them similar to
11198 \emph on
11199 static
11200 \begin_inset LatexCommand \index{static}
11201
11202 \end_inset
11203
11204
11205 \emph default
11206  so by default functions are non-reentrant
11207 \begin_inset LatexCommand \index{reentrant}
11208
11209 \end_inset
11210
11211 .
11212
11213 \newline
11214
11215 \newline
11216 They can be placed on the stack
11217 \begin_inset LatexCommand \index{stack}
11218
11219 \end_inset
11220
11221  by using the
11222 \emph on
11223  -
11224 \begin_inset ERT
11225 status Collapsed
11226
11227 \layout Standard
11228
11229 \backslash
11230 /
11231 \end_inset
11232
11233 -stack-auto
11234 \begin_inset LatexCommand \index{-\/-stack-auto}
11235
11236 \end_inset
11237
11238
11239 \emph default
11240  option, by using
11241 \emph on
11242 #pragma\SpecialChar ~
11243 stackauto
11244 \emph default
11245
11246 \begin_inset LatexCommand \index{\#pragma stackauto}
11247
11248 \end_inset
11249
11250  or by using the
11251 \emph on
11252 reentrant
11253 \begin_inset LatexCommand \index{reentrant}
11254
11255 \end_inset
11256
11257
11258 \emph default
11259  keyword in the function declaration, e.g.:
11260 \layout Verse
11261
11262
11263 \family typewriter
11264 unsigned char foo(char i) __reentrant
11265 \newline
11266 {
11267 \newline
11268 \SpecialChar ~
11269 \SpecialChar ~
11270 \SpecialChar ~
11271 \SpecialChar ~
11272 ...
11273
11274 \newline
11275 }
11276 \layout Standard
11277
11278 Since stack space on 8051 is limited, the
11279 \emph on
11280 reentrant
11281 \emph default
11282 keyword or the
11283 \emph on
11284  -
11285 \begin_inset ERT
11286 status Collapsed
11287
11288 \layout Standard
11289
11290 \backslash
11291 /
11292 \end_inset
11293
11294 -stack-auto
11295 \emph default
11296  option should be used sparingly.
11297  Note that the reentrant keyword just means that the parameters & local
11298  variables will be allocated to the stack, it
11299 \emph on
11300 does not
11301 \emph default
11302  mean that the function is register bank
11303 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
11304
11305 \end_inset
11306
11307  independent.
11308 \newline
11309
11310 \newline
11311 Local variables
11312 \begin_inset LatexCommand \index{local variables}
11313
11314 \end_inset
11315
11316  can be assigned storage classes and absolute
11317 \begin_inset LatexCommand \index{Absolute addressing}
11318
11319 \end_inset
11320
11321  addresses, e.g.:
11322 \layout Verse
11323
11324
11325 \family typewriter
11326 unsigned char foo()
11327 \newline
11328 {
11329 \newline
11330 \SpecialChar ~
11331 \SpecialChar ~
11332 \SpecialChar ~
11333 \SpecialChar ~
11334 __xdata unsigned char i;
11335 \newline
11336 \SpecialChar ~
11337 \SpecialChar ~
11338 \SpecialChar ~
11339 \SpecialChar ~
11340 __bit bvar;
11341 \newline
11342 \SpecialChar ~
11343 \SpecialChar ~
11344 \SpecialChar ~
11345 \SpecialChar ~
11346 __data __at
11347 \begin_inset LatexCommand \index{at}
11348
11349 \end_inset
11350
11351  (0x31) unsigned char j;
11352 \newline
11353 \SpecialChar ~
11354 \SpecialChar ~
11355 \SpecialChar ~
11356 \SpecialChar ~
11357 ...
11358
11359 \newline
11360 }
11361 \layout Standard
11362
11363 In the above example the variable
11364 \emph on
11365 i
11366 \emph default
11367  will be allocated in the external ram,
11368 \emph on
11369 bvar
11370 \emph default
11371  in bit addressable space and
11372 \emph on
11373  j
11374 \emph default
11375  in internal ram.
11376  When compiled with
11377 \emph on
11378 -
11379 \begin_inset ERT
11380 status Collapsed
11381
11382 \layout Standard
11383
11384 \backslash
11385 /
11386 \end_inset
11387
11388 -stack-auto
11389 \emph default
11390  or when a function is declared as
11391 \emph on
11392 reentrant
11393 \emph default
11394  this should only be done for static variables.
11395 \layout Standard
11396
11397 Parameters
11398 \begin_inset LatexCommand \index{function parameter}
11399
11400 \end_inset
11401
11402  however are not allowed any storage class
11403 \begin_inset LatexCommand \index{Storage class}
11404
11405 \end_inset
11406
11407 , (storage classes for parameters will be ignored), their allocation is
11408  governed by the memory model in use, and the reentrancy options.
11409 \layout Standard
11410
11411 It is however allowed to use bit parameters in reentrant functions and also
11412  non-static local bit variables are supported.
11413  Efficient use is limited to 8 semi-bitregisters in bit space.
11414  They are pushed and popped to stack
11415 \begin_inset LatexCommand \index{stack}
11416
11417 \end_inset
11418
11419  as a single byte just like the normal registers.
11420 \layout Section
11421
11422 Overlaying
11423 \begin_inset LatexCommand \label{sub:Overlaying}
11424
11425 \end_inset
11426
11427
11428 \begin_inset LatexCommand \index{Overlaying}
11429
11430 \end_inset
11431
11432
11433 \layout Standard
11434
11435 For non-reentrant
11436 \begin_inset LatexCommand \index{reentrant}
11437
11438 \end_inset
11439
11440  functions SDCC will try to reduce internal ram space usage by overlaying
11441  parameters and local variables of a function (if possible).
11442  Parameters and local variables
11443 \begin_inset LatexCommand \index{local variables}
11444
11445 \end_inset
11446
11447  of a function will be allocated to an overlayable segment if the function
11448  has
11449 \emph on
11450 no other function calls and the function is non-reentrant and the memory
11451  model
11452 \begin_inset LatexCommand \index{Memory model}
11453
11454 \end_inset
11455
11456  is small.
11457
11458 \emph default
11459  If an explicit storage class
11460 \begin_inset LatexCommand \index{Storage class}
11461
11462 \end_inset
11463
11464  is specified for a local variable, it will NOT be overlayed.
11465 \layout Standard
11466
11467 Note that the compiler (not the linkage editor) makes the decision for overlayin
11468 g the data items.
11469  Functions that are called from an interrupt service routine
11470 \begin_inset Marginal
11471 collapsed true
11472
11473 \layout Standard
11474
11475
11476 \series bold
11477 !
11478 \end_inset
11479
11480  should be preceded by a #pragma\SpecialChar ~
11481 nooverlay
11482 \begin_inset LatexCommand \index{\#pragma nooverlay}
11483
11484 \end_inset
11485
11486  if they are not reentrant.
11487 \layout Standard
11488
11489 Also note that the compiler does not do any processing of inline assembler
11490  code, so the compiler might incorrectly assign local variables and parameters
11491  of a function into the overlay segment if the inline assembler code calls
11492  other c-functions that might use the overlay.
11493  In that case the #pragma\SpecialChar ~
11494 nooverlay should be used.
11495 \layout Standard
11496
11497 Parameters and local variables of functions that contain 16 or 32 bit multiplica
11498 tion
11499 \begin_inset LatexCommand \index{Multiplication}
11500
11501 \end_inset
11502
11503  or division
11504 \begin_inset LatexCommand \index{Division}
11505
11506 \end_inset
11507
11508  will NOT be overlayed since these are implemented using external functions,
11509  e.g.:
11510 \layout Verse
11511
11512
11513 \family typewriter
11514 #pragma save
11515 \newline
11516 #pragma nooverlay
11517 \begin_inset LatexCommand \index{\#pragma nooverlay}
11518
11519 \end_inset
11520
11521
11522 \newline
11523 void set_error(unsigned char errcd)
11524 \newline
11525 {
11526 \newline
11527 \SpecialChar ~
11528 \SpecialChar ~
11529 \SpecialChar ~
11530 \SpecialChar ~
11531 P3 = errcd;
11532 \newline
11533 }
11534 \newline
11535 #pragma restore
11536 \newline
11537
11538 \newline
11539 void some_isr () __interrupt
11540 \begin_inset LatexCommand \index{interrupt}
11541
11542 \end_inset
11543
11544  (2)
11545 \newline
11546 {
11547 \newline
11548 \SpecialChar ~
11549 \SpecialChar ~
11550 \SpecialChar ~
11551 \SpecialChar ~
11552 ...
11553 \newline
11554 \SpecialChar ~
11555 \SpecialChar ~
11556 \SpecialChar ~
11557 \SpecialChar ~
11558 set_error(10);
11559 \newline
11560 \SpecialChar ~
11561 \SpecialChar ~
11562 \SpecialChar ~
11563 \SpecialChar ~
11564 ...
11565
11566 \newline
11567 }
11568 \layout Standard
11569 \added_space_bottom bigskip
11570 In the above example the parameter
11571 \emph on
11572 errcd
11573 \emph default
11574  for the function
11575 \emph on
11576 set_error
11577 \emph default
11578  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
11579 nooverlay was
11580  not present, this could cause unpredictable runtime behavior when called
11581  from an interrupt service routine.
11582  The #pragma\SpecialChar ~
11583 nooverlay ensures that the parameters and local variables for
11584  the function are NOT overlayed.
11585 \layout Section
11586
11587 Interrupt Service Routines
11588 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
11589
11590 \end_inset
11591
11592
11593 \layout Subsection
11594
11595 General Information
11596 \layout Standard
11597
11598 SDCC allows
11599 \emph on
11600 i
11601 \emph default
11602 nterrupt
11603 \emph on
11604 s
11605 \emph default
11606 ervice
11607 \emph on
11608 r
11609 \emph default
11610 outines to be coded in C, with some extended keywords.
11611 \layout Verse
11612
11613
11614 \family typewriter
11615 void timer_isr (void) __interrupt (1) __using (1)
11616 \newline
11617 {
11618 \newline
11619 \SpecialChar ~
11620 \SpecialChar ~
11621 \SpecialChar ~
11622 \SpecialChar ~
11623 ...
11624
11625 \newline
11626 }
11627 \layout Standard
11628
11629 The optional number following the
11630 \emph on
11631 interrupt
11632 \begin_inset LatexCommand \index{interrupt}
11633
11634 \end_inset
11635
11636
11637 \begin_inset LatexCommand \index{\_\_interrupt}
11638
11639 \end_inset
11640
11641
11642 \emph default
11643  keyword is the interrupt number this routine will service.
11644  When present, the compiler will insert a call to this routine in the interrupt
11645  vector table
11646 \begin_inset LatexCommand \index{interrupt vector table}
11647
11648 \end_inset
11649
11650  for the interrupt number specified.
11651  If you have multiple source files in your project, interrupt service routines
11652  can be present in any of them, but a prototype of the isr MUST be present
11653  or included in the file that contains the function
11654 \emph on
11655 main
11656 \emph default
11657 .
11658  The optional (8051 specific) keyword
11659 \emph on
11660 using
11661 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11662
11663 \end_inset
11664
11665
11666 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
11667
11668 \end_inset
11669
11670
11671 \emph default
11672  can be used to tell the compiler to use the specified register bank when
11673  generating code for this function.
11674
11675 \newline
11676 Interrupt service routines open the door for some very interesting bugs:
11677 \layout Subsubsection
11678
11679
11680 \begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-volatile}
11681
11682 \end_inset
11683
11684 Common interrupt pitfall: variable not declared
11685 \emph on
11686 volatile
11687 \layout Standard
11688
11689 If an interrupt service routine changes variables which are accessed by
11690  other functions these variables have to be declared
11691 \emph on
11692 volatile
11693 \emph default
11694
11695 \begin_inset LatexCommand \index{volatile}
11696
11697 \end_inset
11698
11699 .
11700  See
11701 \begin_inset LatexCommand \url{http://en.wikipedia.org/wiki/Volatile_variable}
11702
11703 \end_inset
11704
11705  .
11706 \layout Subsubsection
11707
11708
11709 \begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-non-atomic}
11710
11711 \end_inset
11712
11713 Common interrupt pitfall:
11714 \emph on
11715 non-atomic access
11716 \layout Standard
11717
11718 If the access to these variables is not
11719 \emph on
11720 atomic
11721 \begin_inset LatexCommand \index{atomic}
11722
11723 \end_inset
11724
11725
11726 \emph default
11727  (i.e.
11728  the processor needs more than one instruction for the access and could
11729  be interrupted while accessing the variable) the interrupt must be disabled
11730  during the access to avoid inconsistent data.
11731
11732 \newline
11733 Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs and
11734  should be protected by disabling interrupts.
11735  You're not automatically on the safe side if you use 8 bit variables though.
11736  We need an example here: f.e.
11737  on the 8051 the harmless looking
11738 \begin_inset Quotes srd
11739 \end_inset
11740
11741
11742 \family typewriter
11743 flags\SpecialChar ~
11744 |=\SpecialChar ~
11745 0x80;
11746 \family default
11747
11748 \begin_inset Quotes sld
11749 \end_inset
11750
11751  is not atomic if
11752 \family typewriter
11753 flags
11754 \family default
11755  resides in xdata.
11756  Setting
11757 \begin_inset Quotes srd
11758 \end_inset
11759
11760
11761 \family typewriter
11762 flags\SpecialChar ~
11763 |=\SpecialChar ~
11764 0x40;
11765 \family default
11766
11767 \begin_inset Quotes sld
11768 \end_inset
11769
11770  from within an interrupt routine might get lost if the interrupt occurs
11771  at the wrong time.
11772
11773 \begin_inset Quotes sld
11774 \end_inset
11775
11776
11777 \family typewriter
11778 counter\SpecialChar ~
11779 +=\SpecialChar ~
11780 8;
11781 \family default
11782
11783 \begin_inset Quotes srd
11784 \end_inset
11785
11786  is not atomic on the 8051 even if
11787 \family typewriter
11788 counter
11789 \family default
11790  is located in data memory.
11791 \newline
11792 Bugs like these are hard to reproduce and can cause a lot of trouble.
11793
11794 \layout Subsubsection
11795
11796
11797 \begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-stack-overflow}
11798
11799 \end_inset
11800
11801 Common interrupt pitfall:
11802 \emph on
11803 stack overflow
11804 \layout Standard
11805
11806 The return address and the registers used in the interrupt service routine
11807  are saved on the stack
11808 \begin_inset LatexCommand \index{stack}
11809
11810 \end_inset
11811
11812  so there must be sufficient stack space.
11813  If there isn't variables or registers (or even the return address itself)
11814  will be corrupted.
11815  This
11816 \emph on
11817 stack overflow
11818 \emph default
11819
11820 \begin_inset LatexCommand \index{stack overflow}
11821
11822 \end_inset
11823
11824  is most likely to happen if the interrupt occurs during the
11825 \begin_inset Quotes sld
11826 \end_inset
11827
11828 deepest
11829 \begin_inset Quotes srd
11830 \end_inset
11831
11832  subroutine when the stack is already in use for f.e.
11833  many return addresses.
11834 \layout Subsubsection
11835
11836
11837 \begin_inset LatexCommand \label{sub:Common-interrupt-pitfall-non-reentrant}
11838
11839 \end_inset
11840
11841 Common interrupt pitfall:
11842 \emph on
11843 use of non-reentrant functions
11844 \layout Standard
11845
11846 A special note here, int (16 bit) and long (32 bit) integer division
11847 \begin_inset LatexCommand \index{Division}
11848
11849 \end_inset
11850
11851 , multiplication
11852 \begin_inset LatexCommand \index{Multiplication}
11853
11854 \end_inset
11855
11856  & modulus
11857 \begin_inset LatexCommand \index{Modulus}
11858
11859 \end_inset
11860
11861  and floating-point
11862 \begin_inset LatexCommand \index{Floating point support}
11863
11864 \end_inset
11865
11866  operations are implemented using external support routines.
11867  If an interrupt service routine needs to do any of these operations then
11868  the support routines (as mentioned in a following section) will have to
11869  be recompiled using the
11870 \emph on
11871  -
11872 \begin_inset ERT
11873 status Collapsed
11874
11875 \layout Standard
11876
11877 \backslash
11878 /
11879 \end_inset
11880
11881 -stack-auto
11882 \begin_inset LatexCommand \index{-\/-stack-auto}
11883
11884 \end_inset
11885
11886
11887 \emph default
11888  option and the source file will need to be compiled using the
11889 \emph on
11890 -
11891 \begin_inset ERT
11892 status Collapsed
11893
11894 \layout Standard
11895
11896 \backslash
11897 /
11898 \end_inset
11899
11900 -int-long-reent
11901 \emph default
11902
11903 \begin_inset LatexCommand \index{-\/-int-long-reent}
11904
11905 \end_inset
11906
11907  compiler option.
11908
11909 \newline
11910 Note, the type promotion
11911 \begin_inset LatexCommand \index{type promotion}
11912
11913 \end_inset
11914
11915  required by ANSI C can cause 16 bit routines to be used
11916 \begin_inset Marginal
11917 collapsed true
11918
11919 \layout Standard
11920
11921
11922 \series bold
11923 \SpecialChar ~
11924 !
11925 \end_inset
11926
11927  without the programmer being aware of it.
11928  See f.e.
11929  the cast
11930 \family typewriter
11931 (unsigned char)(tail-1)
11932 \family default
11933  within the if clause in section
11934 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
11935
11936 \end_inset
11937
11938 .
11939 \layout Standard
11940 \added_space_bottom bigskip
11941 Calling other functions from an interrupt service routine is not recommended,
11942  avoid it if possible.
11943  Note that when some function is called from an interrupt service routine
11944  it should be preceded by a #pragma\SpecialChar ~
11945 nooverlay
11946 \begin_inset LatexCommand \index{\#pragma nooverlay}
11947
11948 \end_inset
11949
11950  if it is not reentrant.
11951  Furthermore nonreentrant functions should not be called from the main program
11952  while the interrupt service routine might be active.
11953  They also must not be called from low priority interrupt service routines
11954  while a high priority interrupt service routine might be active.
11955  You could use semaphores or make the function
11956 \emph on
11957  critical
11958 \emph default
11959  if all parameters are passed in registers.
11960 \newline
11961  Also see section
11962 \begin_inset LatexCommand \ref{sub:Overlaying}
11963
11964 \end_inset
11965
11966 \SpecialChar ~
11967 about Overlaying and section
11968 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
11969
11970 \end_inset
11971
11972 \SpecialChar ~
11973 about Functions using private register banks.
11974 \layout Subsection
11975
11976 MCS51/DS390 Interrupt Service Routines
11977 \layout Standard
11978
11979 Interrupt
11980 \begin_inset LatexCommand \index{interrupt}
11981
11982 \end_inset
11983
11984  numbers and the corresponding address & descriptions for the Standard 8051/8052
11985  are listed below.
11986  SDCC will automatically adjust the
11987 \begin_inset LatexCommand \index{interrupt vector table}
11988
11989 \end_inset
11990
11991  to the maximum interrupt number specified.
11992 \newline
11993
11994 \layout Standard
11995 \align center
11996
11997 \begin_inset  Tabular
11998 <lyxtabular version="3" rows="9" columns="3">
11999 <features>
12000 <column alignment="center" valignment="top" leftline="true" width="0in">
12001 <column alignment="left" valignment="top" leftline="true" width="0in">
12002 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
12003 <row topline="true" bottomline="true">
12004 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12005 \begin_inset Text
12006
12007 \layout Standard
12008
12009 Interrupt #
12010 \end_inset
12011 </cell>
12012 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12013 \begin_inset Text
12014
12015 \layout Standard
12016
12017 Description
12018 \end_inset
12019 </cell>
12020 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12021 \begin_inset Text
12022
12023 \layout Standard
12024
12025 Vector Address
12026 \end_inset
12027 </cell>
12028 </row>
12029 <row topline="true">
12030 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12031 \begin_inset Text
12032
12033 \layout Standard
12034
12035 0
12036 \end_inset
12037 </cell>
12038 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12039 \begin_inset Text
12040
12041 \layout Standard
12042
12043 External 0
12044 \end_inset
12045 </cell>
12046 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12047 \begin_inset Text
12048
12049 \layout Standard
12050
12051 0x0003
12052 \end_inset
12053 </cell>
12054 </row>
12055 <row topline="true">
12056 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12057 \begin_inset Text
12058
12059 \layout Standard
12060
12061 1
12062 \end_inset
12063 </cell>
12064 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12065 \begin_inset Text
12066
12067 \layout Standard
12068
12069 Timer 0
12070 \end_inset
12071 </cell>
12072 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12073 \begin_inset Text
12074
12075 \layout Standard
12076
12077 0x000b
12078 \end_inset
12079 </cell>
12080 </row>
12081 <row topline="true">
12082 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12083 \begin_inset Text
12084
12085 \layout Standard
12086
12087 2
12088 \end_inset
12089 </cell>
12090 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12091 \begin_inset Text
12092
12093 \layout Standard
12094
12095 External 1
12096 \end_inset
12097 </cell>
12098 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12099 \begin_inset Text
12100
12101 \layout Standard
12102
12103 0x0013
12104 \end_inset
12105 </cell>
12106 </row>
12107 <row topline="true">
12108 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12109 \begin_inset Text
12110
12111 \layout Standard
12112
12113 3
12114 \end_inset
12115 </cell>
12116 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12117 \begin_inset Text
12118
12119 \layout Standard
12120
12121 Timer 1
12122 \end_inset
12123 </cell>
12124 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12125 \begin_inset Text
12126
12127 \layout Standard
12128
12129 0x001b
12130 \end_inset
12131 </cell>
12132 </row>
12133 <row topline="true">
12134 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12135 \begin_inset Text
12136
12137 \layout Standard
12138
12139 4
12140 \end_inset
12141 </cell>
12142 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12143 \begin_inset Text
12144
12145 \layout Standard
12146
12147 Serial
12148 \end_inset
12149 </cell>
12150 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12151 \begin_inset Text
12152
12153 \layout Standard
12154
12155 0x0023
12156 \end_inset
12157 </cell>
12158 </row>
12159 <row topline="true">
12160 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12161 \begin_inset Text
12162
12163 \layout Standard
12164
12165 5
12166 \end_inset
12167 </cell>
12168 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12169 \begin_inset Text
12170
12171 \layout Standard
12172
12173 Timer 2 (8052)
12174 \end_inset
12175 </cell>
12176 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12177 \begin_inset Text
12178
12179 \layout Standard
12180
12181 0x002b
12182 \end_inset
12183 </cell>
12184 </row>
12185 <row topline="true">
12186 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12187 \begin_inset Text
12188
12189 \layout Standard
12190
12191 ...
12192 \end_inset
12193 </cell>
12194 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12195 \begin_inset Text
12196
12197 \layout Standard
12198
12199 \end_inset
12200 </cell>
12201 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12202 \begin_inset Text
12203
12204 \layout Standard
12205
12206 ...
12207 \end_inset
12208 </cell>
12209 </row>
12210 <row topline="true" bottomline="true">
12211 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12212 \begin_inset Text
12213
12214 \layout Standard
12215
12216 n
12217 \end_inset
12218 </cell>
12219 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12220 \begin_inset Text
12221
12222 \layout Standard
12223
12224 \end_inset
12225 </cell>
12226 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12227 \begin_inset Text
12228
12229 \layout Standard
12230
12231 0x0003 + 8*n
12232 \end_inset
12233 </cell>
12234 </row>
12235 </lyxtabular>
12236
12237 \end_inset
12238
12239
12240 \newline
12241
12242 \layout Standard
12243
12244 If the interrupt service routine is defined without
12245 \emph on
12246 using
12247 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
12248
12249 \end_inset
12250
12251
12252 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
12253
12254 \end_inset
12255
12256
12257 \emph default
12258  a register bank or with register bank 0 (
12259 \emph on
12260 using
12261 \emph default
12262  0), the compiler will save the registers used by itself on the stack upon
12263  entry and restore them at exit, however if such an interrupt service routine
12264  calls another function then the entire register bank will be saved on the
12265  stack.
12266  This scheme may be advantageous for small interrupt service routines which
12267  have low register usage.
12268 \layout Standard
12269 \added_space_bottom bigskip
12270 If the interrupt service routine is defined to be using a specific register
12271  bank then only
12272 \emph on
12273 a, b, dptr
12274 \emph default
12275  & psw are saved and restored, if such an interrupt service routine calls
12276  another function (using another register bank) then the entire register
12277  bank of the called function will be saved on the stack
12278 \begin_inset LatexCommand \index{stack}
12279
12280 \end_inset
12281
12282 .
12283  This scheme is recommended for larger interrupt service routines.
12284 \layout Subsection
12285
12286 HC08
12287 \begin_inset LatexCommand \index{HC08}
12288
12289 \end_inset
12290
12291  Interrupt Service Routines
12292 \layout Standard
12293 \added_space_bottom bigskip
12294 Since the number of interrupts
12295 \begin_inset LatexCommand \index{HC08!interrupt}
12296
12297 \end_inset
12298
12299  available is chip specific and the interrupt vector table always ends at
12300  the last byte of memory, the interrupt numbers corresponds to the interrupt
12301  vectors in reverse order of address.
12302  For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
12303  2 will use the interrupt vector at 0xfffa, and so on.
12304  However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
12305  this way; instead see section
12306 \begin_inset LatexCommand \ref{sub:Startup-Code}
12307
12308 \end_inset
12309
12310  for details on customizing startup.
12311 \layout Subsection
12312
12313 Z80 Interrupt Service Routines
12314 \layout Standard
12315
12316 The Z80
12317 \begin_inset LatexCommand \index{Z80}
12318
12319 \end_inset
12320
12321  uses several different methods for determining the correct interrupt
12322 \begin_inset LatexCommand \index{Z80!interrupt}
12323
12324 \end_inset
12325
12326  vector depending on the hardware implementation.
12327  Therefore, SDCC ignores the optional interrupt number and does not attempt
12328  to generate an interrupt vector table.
12329 \layout Standard
12330
12331 By default, SDCC generates code for a maskable interrupt, which uses a RETI
12332  instruction to return from the interrupt.
12333  To write an interrupt handler for the non-maskable interrupt, which needs
12334  a RETN instruction instead, add the
12335 \emph on
12336 critical
12337 \emph default
12338  keyword:
12339 \layout Verse
12340
12341
12342 \family typewriter
12343 void nmi_isr (void) critical interrupt
12344 \newline
12345 {
12346 \newline
12347 \SpecialChar ~
12348 \SpecialChar ~
12349 \SpecialChar ~
12350 \SpecialChar ~
12351 ...
12352
12353 \newline
12354 }
12355 \layout Standard
12356 \added_space_bottom bigskip
12357 However if you need to create a non-interruptable interrupt service routine
12358  you would also require the
12359 \emph on
12360 critical
12361 \emph default
12362  keyword.
12363  To distinguish between this and an nmi_isr you must provide an interrupt
12364  number.
12365 \layout Section
12366
12367 Enabling and Disabling Interrupts
12368 \layout Subsection
12369
12370 Critical Functions and Critical Statements
12371 \layout Standard
12372
12373 A special keyword may be associated with a block or a function declaring
12374  it as
12375 \emph on
12376 critical
12377 \emph default
12378 .
12379  SDCC will generate code to disable all interrupts
12380 \begin_inset LatexCommand \index{interrupt}
12381
12382 \end_inset
12383
12384  upon entry to a critical function and restore the interrupt enable to the
12385  previous state before returning.
12386  Nesting critical functions will need one additional byte on the stack
12387 \begin_inset LatexCommand \index{stack}
12388
12389 \end_inset
12390
12391  for each call.
12392 \layout Verse
12393
12394
12395 \family typewriter
12396 int foo () __critical
12397 \begin_inset LatexCommand \index{critical}
12398
12399 \end_inset
12400
12401
12402 \begin_inset LatexCommand \index{\_\_critical}
12403
12404 \end_inset
12405
12406
12407 \newline
12408 {
12409 \newline
12410 \SpecialChar ~
12411 \SpecialChar ~
12412 \SpecialChar ~
12413 \SpecialChar ~
12414 ...
12415
12416 \newline
12417 \SpecialChar ~
12418 \SpecialChar ~
12419 \SpecialChar ~
12420 \SpecialChar ~
12421 ...
12422
12423 \newline
12424 }
12425 \layout Standard
12426
12427 The critical attribute maybe used with other attributes like
12428 \emph on
12429 reentrant.
12430 \emph default
12431
12432 \newline
12433 The keyword
12434 \emph on
12435 critical
12436 \emph default
12437  may also be used to disable interrupts more locally:
12438 \layout Verse
12439
12440
12441 \family typewriter
12442 __critical{ i++; }
12443 \layout Standard
12444
12445 More than one statement could have been included in the block.
12446 \layout Subsection
12447
12448 Enabling and Disabling Interrupts directly
12449 \layout Standard
12450
12451 Interrupts
12452 \begin_inset LatexCommand \index{interrupt}
12453
12454 \end_inset
12455
12456  can also be disabled and enabled directly (8051):
12457 \layout Verse
12458
12459
12460 \family typewriter
12461 EA = 0;\SpecialChar ~
12462 \SpecialChar ~
12463 \SpecialChar ~
12464 \SpecialChar ~
12465 \SpecialChar ~
12466 \SpecialChar ~
12467 \SpecialChar ~
12468 \SpecialChar ~
12469 \SpecialChar ~
12470 \SpecialChar ~
12471 \SpecialChar ~
12472 \SpecialChar ~
12473 or:\SpecialChar ~
12474 \SpecialChar ~
12475 \SpecialChar ~
12476 \SpecialChar ~
12477 \SpecialChar ~
12478 \SpecialChar ~
12479 \SpecialChar ~
12480 \SpecialChar ~
12481 \SpecialChar ~
12482 \SpecialChar ~
12483 \SpecialChar ~
12484 EA_SAVE = EA;
12485 \layout Verse
12486
12487
12488 \family typewriter
12489 ...\SpecialChar ~
12490 \SpecialChar ~
12491 \SpecialChar ~
12492 \SpecialChar ~
12493 \SpecialChar ~
12494 \SpecialChar ~
12495 \SpecialChar ~
12496 \SpecialChar ~
12497 \SpecialChar ~
12498 \SpecialChar ~
12499 \SpecialChar ~
12500 \SpecialChar ~
12501 \SpecialChar ~
12502 \SpecialChar ~
12503 \SpecialChar ~
12504 \SpecialChar ~
12505 \SpecialChar ~
12506 \SpecialChar ~
12507 \SpecialChar ~
12508 \SpecialChar ~
12509 \SpecialChar ~
12510 \SpecialChar ~
12511 \SpecialChar ~
12512 \SpecialChar ~
12513 \SpecialChar ~
12514 \SpecialChar ~
12515 \SpecialChar ~
12516 \SpecialChar ~
12517 \SpecialChar ~
12518 \SpecialChar ~
12519 EA = 0;
12520 \layout Verse
12521
12522
12523 \family typewriter
12524 EA = 1;\SpecialChar ~
12525 \SpecialChar ~
12526 \SpecialChar ~
12527 \SpecialChar ~
12528 \SpecialChar ~
12529 \SpecialChar ~
12530 \SpecialChar ~
12531 \SpecialChar ~
12532 \SpecialChar ~
12533 \SpecialChar ~
12534 \SpecialChar ~
12535 \SpecialChar ~
12536 \SpecialChar ~
12537 \SpecialChar ~
12538 \SpecialChar ~
12539 \SpecialChar ~
12540 \SpecialChar ~
12541 \SpecialChar ~
12542 \SpecialChar ~
12543 \SpecialChar ~
12544 \SpecialChar ~
12545 \SpecialChar ~
12546 \SpecialChar ~
12547 \SpecialChar ~
12548 \SpecialChar ~
12549 \SpecialChar ~
12550 ...
12551 \layout Verse
12552
12553
12554 \family typewriter
12555 \SpecialChar ~
12556 \SpecialChar ~
12557 \SpecialChar ~
12558 \SpecialChar ~
12559 \SpecialChar ~
12560 \SpecialChar ~
12561 \SpecialChar ~
12562 \SpecialChar ~
12563 \SpecialChar ~
12564 \SpecialChar ~
12565 \SpecialChar ~
12566 \SpecialChar ~
12567 \SpecialChar ~
12568 \SpecialChar ~
12569 \SpecialChar ~
12570 \SpecialChar ~
12571 \SpecialChar ~
12572 \SpecialChar ~
12573 \SpecialChar ~
12574 \SpecialChar ~
12575 \SpecialChar ~
12576 \SpecialChar ~
12577 \SpecialChar ~
12578 \SpecialChar ~
12579 \SpecialChar ~
12580 \SpecialChar ~
12581 \SpecialChar ~
12582 \SpecialChar ~
12583 \SpecialChar ~
12584 \SpecialChar ~
12585 \SpecialChar ~
12586 \SpecialChar ~
12587 \SpecialChar ~
12588 EA = EA_SAVE;
12589 \layout Standard
12590
12591 On other architectures which have seperate opcodes for enabling and disabling
12592  interrupts you might want to make use of defines with inline assembly
12593 \begin_inset LatexCommand \index{Assembler routines}
12594
12595 \end_inset
12596
12597  (HC08
12598 \begin_inset LatexCommand \index{HC08!interrupt}
12599
12600 \end_inset
12601
12602 ):
12603 \layout Verse
12604
12605
12606 \family typewriter
12607 #define CLI _asm
12608 \begin_inset LatexCommand \index{\_asm}
12609
12610 \end_inset
12611
12612 \SpecialChar ~
12613 \SpecialChar ~
12614 cli\SpecialChar ~
12615 \SpecialChar ~
12616 _endasm
12617 \begin_inset LatexCommand \index{\_endasm}
12618
12619 \end_inset
12620
12621 ;
12622 \layout Verse
12623
12624
12625 \family typewriter
12626 #define SEI _asm\SpecialChar ~
12627 \SpecialChar ~
12628 sei\SpecialChar ~
12629 \SpecialChar ~
12630 _endasm;
12631 \layout Verse
12632
12633
12634 \family typewriter
12635 ...
12636 \layout Standard
12637
12638 Note: it is sometimes sufficient to disable only a specific interrupt source
12639  like f.e.
12640  a timer or serial interrupt by manipulating an
12641 \emph on
12642 interrupt mask
12643 \begin_inset LatexCommand \index{interrupt mask}
12644
12645 \end_inset
12646
12647
12648 \emph default
12649  register.
12650
12651 \layout Standard
12652
12653 Usually the time during which interrupts are disabled should be kept as
12654  short as possible.
12655  This minimizes both
12656 \emph on
12657 interrupt latency
12658 \emph default
12659
12660 \begin_inset LatexCommand \index{interrupt latency}
12661
12662 \end_inset
12663
12664  (the time between the occurrence of the interrupt and the execution of
12665  the first code in the interrupt routine) and
12666 \emph on
12667 interrupt jitter
12668 \emph default
12669
12670 \begin_inset LatexCommand \index{interrupt jitter}
12671
12672 \end_inset
12673
12674  (the difference between the shortest and the longest interrupt latency).
12675  These really are something different, f.e.
12676  a serial interrupt has to be served before its buffer overruns so it cares
12677  for the maximum interrupt latency, whereas it does not care about jitter.
12678  On a loudspeaker driven via a digital to analog converter which is fed
12679  by an interrupt a latency of a few milliseconds might be tolerable, whereas
12680  a much smaller jitter will be very audible.
12681 \layout Standard
12682
12683 You can reenable interrupts within an interrupt routine and on some architecture
12684 s you can make use of two (or more) levels of
12685 \emph on
12686 interrupt priorities
12687 \emph default
12688
12689 \begin_inset LatexCommand \index{interrupt priority}
12690
12691 \end_inset
12692
12693 .
12694  On some architectures which don't support interrupt priorities these can
12695  be implemented by manipulating the interrupt mask and reenabling interrupts
12696  within the interrupt routine.
12697  Check there is sufficient space on the stack
12698 \begin_inset LatexCommand \index{stack}
12699
12700 \end_inset
12701
12702  and don't add complexity unless you have to.
12703
12704 \layout Subsection
12705
12706 Semaphore
12707 \begin_inset LatexCommand \index{semaphore}
12708
12709 \end_inset
12710
12711  locking (mcs51/ds390)
12712 \layout Standard
12713
12714 Some architectures (mcs51/ds390) have an atomic
12715 \begin_inset LatexCommand \index{atomic}
12716
12717 \end_inset
12718
12719  bit test and
12720 \emph on
12721
12722 \emph default
12723 clear
12724 \emph on
12725
12726 \emph default
12727 instruction.
12728  These type of instructions are typically used in preemptive multitasking
12729  systems, where a routine f.e.
12730  claims the use of a data structure ('acquires a lock
12731 \begin_inset LatexCommand \index{lock}
12732
12733 \end_inset
12734
12735  on it'), makes some modifications and then releases the lock when the data
12736  structure is consistent again.
12737  The instruction may also be used if interrupt and non-interrupt code have
12738  to compete for a resource.
12739  With the atomic bit test and clear instruction interrupts
12740 \begin_inset LatexCommand \index{interrupt}
12741
12742 \end_inset
12743
12744  don't have to be disabled for the locking operation.
12745
12746 \layout Standard
12747
12748 SDCC generates this instruction if the source follows this pattern:
12749 \layout Verse
12750
12751
12752 \family typewriter
12753 volatile
12754 \begin_inset LatexCommand \index{volatile}
12755
12756 \end_inset
12757
12758  bit resource_is_free;
12759 \newline
12760
12761 \newline
12762 if (resource_is_free)
12763 \newline
12764 \SpecialChar ~
12765 \SpecialChar ~
12766 {
12767 \newline
12768 \SpecialChar ~
12769 \SpecialChar ~
12770 \SpecialChar ~
12771 \SpecialChar ~
12772 resource_is_free=0;
12773 \newline
12774 \SpecialChar ~
12775 \SpecialChar ~
12776 \SpecialChar ~
12777 \SpecialChar ~
12778 ...
12779
12780 \newline
12781 \SpecialChar ~
12782 \SpecialChar ~
12783 \SpecialChar ~
12784 \SpecialChar ~
12785 resource_is_free=1;
12786 \newline
12787 \SpecialChar ~
12788 \SpecialChar ~
12789 }
12790 \layout Standard
12791
12792 Note, mcs51 and ds390 support only an atomic
12793 \begin_inset LatexCommand \index{atomic}
12794
12795 \end_inset
12796
12797  bit test and
12798 \emph on
12799 clear
12800 \emph default
12801  instruction (as opposed to atomic bit test and
12802 \emph on
12803 set).
12804 \layout Section
12805
12806 Functions using private register banks
12807 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
12808
12809 \end_inset
12810
12811  (mcs51/ds390)
12812 \layout Standard
12813
12814 Some architectures have support for quickly changing register sets.
12815  SDCC supports this feature with the
12816 \emph on
12817 using
12818 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
12819
12820 \end_inset
12821
12822
12823 \begin_inset LatexCommand \index{\_\_using (mcs51, ds390 register bank)}
12824
12825 \end_inset
12826
12827
12828 \emph default
12829  attribute (which tells the compiler to use a register bank
12830 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
12831
12832 \end_inset
12833
12834  other than the default bank zero).
12835  It should only be applied to
12836 \emph on
12837 interrupt
12838 \begin_inset LatexCommand \index{interrupt}
12839
12840 \end_inset
12841
12842
12843 \emph default
12844  functions (see footnote below).
12845  This will in most circumstances make the generated ISR code more efficient
12846  since it will not have to save registers on the stack.
12847 \layout Standard
12848
12849 The
12850 \emph on
12851 using
12852 \emph default
12853  attribute will have no effect on the generated code for a
12854 \emph on
12855 non-interrupt
12856 \emph default
12857  function (but may occasionally be useful anyway
12858 \begin_inset Foot
12859 collapsed false
12860
12861 \layout Standard
12862
12863 possible exception: if a function is called ONLY from 'interrupt' functions
12864  using a particular bank, it can be declared with the same 'using' attribute
12865  as the calling 'interrupt' functions.
12866  For instance, if you have several ISRs using bank one, and all of them
12867  call memcpy(), it might make sense to create a specialized version of memcpy()
12868  'using 1', since this would prevent the ISR from having to save bank zero
12869  to the stack on entry and switch to bank zero before calling the function
12870 \end_inset
12871
12872 ).
12873 \newline
12874
12875 \emph on
12876 (pending: Note, nowadays the
12877 \emph default
12878 using
12879 \emph on
12880  attribute has an effect on
12881 \emph default
12882
12883 \emph on
12884 the generated code for a
12885 \emph default
12886 non-interrupt
12887 \emph on
12888  function
12889 \emph default
12890 .
12891 \emph on
12892 )
12893 \layout Standard
12894
12895 An
12896 \emph on
12897 interrupt
12898 \emph default
12899  function using a non-zero bank will assume that it can trash that register
12900  bank, and will not save it.
12901  Since high-priority interrupts
12902 \begin_inset LatexCommand \index{interrupts}
12903
12904 \end_inset
12905
12906
12907 \begin_inset LatexCommand \index{interrupt priority}
12908
12909 \end_inset
12910
12911  can interrupt low-priority ones on the 8051 and friends, this means that
12912  if a high-priority ISR
12913 \emph on
12914 using
12915 \emph default
12916  a particular bank occurs while processing a low-priority ISR
12917 \emph on
12918 using
12919 \emph default
12920  the same bank, terrible and bad things can happen.
12921  To prevent this, no single register bank should be
12922 \emph on
12923 used
12924 \emph default
12925  by both a high priority and a low priority ISR.
12926  This is probably most easily done by having all high priority ISRs use
12927  one bank and all low priority ISRs use another.
12928  If you have an ISR which can change priority at runtime, you're on your
12929  own: I suggest using the default bank zero and taking the small performance
12930  hit.
12931 \layout Standard
12932 \added_space_bottom bigskip
12933 It is most efficient if your ISR calls no other functions.
12934  If your ISR must call other functions, it is most efficient if those functions
12935  use the same bank as the ISR (see note 1 below); the next best is if the
12936  called functions use bank zero.
12937  It is very inefficient to call a function using a different, non-zero bank
12938  from an ISR.
12939
12940 \layout Section
12941
12942 Startup Code
12943 \begin_inset LatexCommand \label{sub:Startup-Code}
12944
12945 \end_inset
12946
12947
12948 \begin_inset LatexCommand \index{Startup code}
12949
12950 \end_inset
12951
12952
12953 \layout Subsection
12954
12955 MCS51/DS390 Startup Code
12956 \layout Standard
12957
12958 The compiler inserts a call to the C routine
12959 \emph on
12960 _sdcc_external_startup()
12961 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
12962
12963 \end_inset
12964
12965
12966 \series bold
12967 \emph default
12968
12969 \series default
12970 at the start of the CODE area.
12971  This routine is in the runtime library
12972 \begin_inset LatexCommand \index{Runtime library}
12973
12974 \end_inset
12975
12976 .
12977  By default this routine returns 0, if this routine returns a non-zero value,
12978  the static & global variable initialization will be skipped and the function
12979  main will be invoked.
12980  Otherwise static & global variables will be initialized before the function
12981  main is invoked.
12982  You could add a
12983 \emph on
12984 _sdcc_external_startup()
12985 \emph default
12986  routine to your program to override the default if you need to setup hardware
12987  or perform some other critical operation prior to static & global variable
12988  initialization
12989 \begin_inset LatexCommand \index{Variable initialization}
12990
12991 \end_inset
12992
12993 .
12994  On some mcs51 variants xdata
12995 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
12996
12997 \end_inset
12998
12999  memory has to be explicitly enabled before it can be accessed or if the
13000  watchdog
13001 \begin_inset LatexCommand \index{watchdog}
13002
13003 \end_inset
13004
13005  needs to be disabled, this is the place to do it.
13006  The startup code clears all internal data memory, 256 bytes by default,
13007  but from 0 to n-1 if
13008 \emph on
13009 -
13010 \begin_inset ERT
13011 status Collapsed
13012
13013 \layout Standard
13014
13015 \backslash
13016 /
13017 \end_inset
13018
13019 -iram-size
13020 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
13021
13022 \end_inset
13023
13024 n
13025 \emph default
13026  is used.
13027  (recommended for Chipcon CC1010).
13028 \layout Standard
13029 \added_space_bottom bigskip
13030 See also the compiler options
13031 \emph on
13032 -
13033 \begin_inset ERT
13034 status Collapsed
13035
13036 \layout Standard
13037
13038 \backslash
13039 /
13040 \end_inset
13041
13042 -no-xinit
13043 \emph default
13044 -
13045 \emph on
13046 opt
13047 \emph default
13048
13049 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
13050
13051 \end_inset
13052
13053 ,
13054 \emph on
13055 -
13056 \begin_inset ERT
13057 status Collapsed
13058
13059 \layout Standard
13060
13061 \backslash
13062 /
13063 \end_inset
13064
13065 -main-return
13066 \emph default
13067
13068 \begin_inset LatexCommand \index{-\/-main-return}
13069
13070 \end_inset
13071
13072  and section
13073 \begin_inset LatexCommand \ref{sub:MCS51-variants}
13074
13075 \end_inset
13076
13077  about MCS51-variants.
13078 \layout Subsection
13079
13080 HC08 Startup Code
13081 \layout Standard
13082 \added_space_bottom bigskip
13083 The HC08
13084 \begin_inset LatexCommand \index{HC08}
13085
13086 \end_inset
13087
13088  startup code follows the same scheme as the MCS51 startup code.
13089 \layout Subsection
13090
13091 Z80 Startup Code
13092 \layout Standard
13093 \added_space_bottom bigskip
13094 On the Z80
13095 \begin_inset LatexCommand \index{Z80}
13096
13097 \end_inset
13098
13099  the startup code is inserted by linking with crt0.o which is generated from
13100  sdcc/device/lib/z80/crt0.s.
13101  If you need a different startup code you can use the compiler option
13102 \emph on
13103 -
13104 \series bold
13105 \emph default
13106
13107 \begin_inset ERT
13108 status Collapsed
13109
13110 \layout Standard
13111
13112 \backslash
13113 /
13114 \end_inset
13115
13116
13117 \series default
13118 \emph on
13119 -no-std-crt0
13120 \emph default
13121
13122 \begin_inset LatexCommand \index{-\/-no-std-crt0}
13123
13124 \end_inset
13125
13126  and provide your own crt0.o.
13127
13128 \layout Section
13129
13130 Inline Assembler Code
13131 \begin_inset LatexCommand \index{Assembler routines}
13132
13133 \end_inset
13134
13135
13136 \layout Subsection
13137
13138 A Step by Step Introduction
13139 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
13140
13141 \end_inset
13142
13143
13144 \layout Standard
13145
13146 Starting from a small snippet of c-code this example shows for the MCS51
13147  how to use inline assembly, access variables, a function parameter and
13148  an array in xdata memory.
13149  The example uses an MCS51 here but is easily adapted for other architectures.
13150  This is a buffer routine which should be optimized:
13151 \layout Verse
13152
13153
13154 \family typewriter
13155 \size footnotesize
13156 unsigned char __far
13157 \begin_inset LatexCommand \index{far (storage class)}
13158
13159 \end_inset
13160
13161
13162 \begin_inset LatexCommand \index{\_\_far (storage class)}
13163
13164 \end_inset
13165
13166  __at
13167 \begin_inset LatexCommand \index{at}
13168
13169 \end_inset
13170
13171
13172 \begin_inset LatexCommand \index{\_\_at}
13173
13174 \end_inset
13175
13176 (0x7f00) buf[0x100];
13177 \begin_inset LatexCommand \index{Aligned array}
13178
13179 \end_inset
13180
13181
13182 \newline
13183 unsigned char head, tail;\SpecialChar ~
13184 \SpecialChar ~
13185 \SpecialChar ~
13186 \SpecialChar ~
13187 \SpecialChar ~
13188 \SpecialChar ~
13189 \SpecialChar ~
13190 \SpecialChar ~
13191 \SpecialChar ~
13192 \SpecialChar ~
13193 \SpecialChar ~
13194 \SpecialChar ~
13195 \SpecialChar ~
13196 \SpecialChar ~
13197 \SpecialChar ~
13198 \SpecialChar ~
13199 \SpecialChar ~
13200 /* if interrupts
13201 \begin_inset LatexCommand \index{interrupt}
13202
13203 \end_inset
13204
13205  are involved see
13206 \newline
13207 \SpecialChar ~
13208 \SpecialChar ~
13209 \SpecialChar ~
13210 \SpecialChar ~
13211 \SpecialChar ~
13212 \SpecialChar ~
13213 \SpecialChar ~
13214 \SpecialChar ~
13215 \SpecialChar ~
13216 \SpecialChar ~
13217 \SpecialChar ~
13218 \SpecialChar ~
13219 \SpecialChar ~
13220 \SpecialChar ~
13221 \SpecialChar ~
13222 \SpecialChar ~
13223 \SpecialChar ~
13224 \SpecialChar ~
13225 \SpecialChar ~
13226 \SpecialChar ~
13227 \SpecialChar ~
13228 \SpecialChar ~
13229 \SpecialChar ~
13230 \SpecialChar ~
13231 \SpecialChar ~
13232 \SpecialChar ~
13233 \SpecialChar ~
13234 \SpecialChar ~
13235 \SpecialChar ~
13236 \SpecialChar ~
13237 \SpecialChar ~
13238 \SpecialChar ~
13239 \SpecialChar ~
13240 \SpecialChar ~
13241 \SpecialChar ~
13242 \SpecialChar ~
13243 \SpecialChar ~
13244 \SpecialChar ~
13245 \SpecialChar ~
13246 \SpecialChar ~
13247 \SpecialChar ~
13248 \SpecialChar ~
13249 \SpecialChar ~
13250 \SpecialChar ~
13251 \SpecialChar ~
13252 section
13253 \begin_inset LatexCommand \ref{sub:Common-interrupt-pitfall-volatile}
13254
13255 \end_inset
13256
13257  about
13258 \series bold
13259  volatile
13260 \series default
13261  */
13262 \newline
13263
13264 \newline
13265 void to_buffer( unsigned char c )
13266 \newline
13267 {
13268 \newline
13269 \SpecialChar ~
13270 \SpecialChar ~
13271 \SpecialChar ~
13272 \SpecialChar ~
13273 if( head != (unsigned char)(tail-1) )\SpecialChar ~
13274 /* cast
13275 \series bold
13276 needed
13277 \series default
13278  to avoid promotion
13279 \begin_inset LatexCommand \index{promotion to signed int}
13280
13281 \end_inset
13282
13283
13284 \begin_inset LatexCommand \index{type promotion}
13285
13286 \end_inset
13287
13288  to integer */
13289 \begin_inset Marginal
13290 collapsed true
13291
13292 \layout Standard
13293
13294
13295 \series bold
13296 \SpecialChar ~
13297 !
13298 \end_inset
13299
13300
13301 \newline
13302 \SpecialChar ~
13303 \SpecialChar ~
13304 \SpecialChar ~
13305 \SpecialChar ~
13306 \SpecialChar ~
13307 \SpecialChar ~
13308 \SpecialChar ~
13309 \SpecialChar ~
13310 buf[ head++ ] = c;\SpecialChar ~
13311 \SpecialChar ~
13312 \SpecialChar ~
13313 \SpecialChar ~
13314 \SpecialChar ~
13315 \SpecialChar ~
13316 \SpecialChar ~
13317 \SpecialChar ~
13318 \SpecialChar ~
13319 \SpecialChar ~
13320 \SpecialChar ~
13321 \SpecialChar ~
13322 \SpecialChar ~
13323 \SpecialChar ~
13324 \SpecialChar ~
13325 \SpecialChar ~
13326 /* access to a 256 byte aligned array */
13327 \newline
13328 }
13329 \layout Standard
13330
13331 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
13332  then a corresponding buffer.asm file is generated.
13333  We define a new function
13334 \family typewriter
13335 to_buffer_asm()
13336 \family default
13337  in file buffer.c in which we cut and paste the generated code, removing
13338  unwanted comments and some ':'.
13339  Then add
13340 \begin_inset Quotes sld
13341 \end_inset
13342
13343 _asm
13344 \begin_inset Quotes srd
13345 \end_inset
13346
13347  and
13348 \begin_inset Quotes sld
13349 \end_inset
13350
13351 _endasm;
13352 \begin_inset Quotes srd
13353 \end_inset
13354
13355  to the beginning and the end of the function body:
13356 \layout Verse
13357
13358
13359 \family typewriter
13360 \size footnotesize
13361 /* With a cut and paste from the .asm file, we have something to start with.
13362 \newline
13363 \SpecialChar ~
13364 \SpecialChar ~
13365 \SpecialChar ~
13366 The function is not yet OK! (registers aren't saved) */
13367 \newline
13368 void to_buffer_asm( unsigned char c )
13369 \newline
13370 {
13371 \newline
13372 \SpecialChar ~
13373 \SpecialChar ~
13374 \SpecialChar ~
13375 \SpecialChar ~
13376 _asm
13377 \begin_inset LatexCommand \index{\_asm}
13378
13379 \end_inset
13380
13381
13382 \begin_inset LatexCommand \index{\_\_asm}
13383
13384 \end_inset
13385
13386
13387 \newline
13388 \SpecialChar ~
13389 \SpecialChar ~
13390 \SpecialChar ~
13391 \SpecialChar ~
13392 mov\SpecialChar ~
13393 \SpecialChar ~
13394 r2,dpl
13395 \newline
13396 ;buffer.c if( head != (unsigned char)(tail-1) ) \SpecialChar ~
13397 /* cast
13398 \series bold
13399 needed
13400 \series default
13401  to avoid promotion
13402 \begin_inset LatexCommand \index{promotion to signed int}
13403
13404 \end_inset
13405
13406
13407 \begin_inset LatexCommand \index{type promotion}
13408
13409 \end_inset
13410
13411  to integer */
13412 \newline
13413 \SpecialChar ~
13414 \SpecialChar ~
13415 \SpecialChar ~
13416 \SpecialChar ~
13417 mov\SpecialChar ~
13418 \SpecialChar ~
13419 a,_tail
13420 \newline
13421 \SpecialChar ~
13422 \SpecialChar ~
13423 \SpecialChar ~
13424 \SpecialChar ~
13425 dec\SpecialChar ~
13426 \SpecialChar ~
13427 a
13428 \newline
13429 \SpecialChar ~
13430 \SpecialChar ~
13431 \SpecialChar ~
13432 \SpecialChar ~
13433 mov\SpecialChar ~
13434 \SpecialChar ~
13435 r3,a
13436 \newline
13437 \SpecialChar ~
13438 \SpecialChar ~
13439 \SpecialChar ~
13440 \SpecialChar ~
13441 mov\SpecialChar ~
13442 \SpecialChar ~
13443 a,_head
13444 \newline
13445 \SpecialChar ~
13446 \SpecialChar ~
13447 \SpecialChar ~
13448 \SpecialChar ~
13449 cjne a,ar3,00106$
13450 \newline
13451 \SpecialChar ~
13452 \SpecialChar ~
13453 \SpecialChar ~
13454 \SpecialChar ~
13455 ret
13456 \newline
13457 00106$:
13458 \newline
13459 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
13460 \begin_inset LatexCommand \index{Aligned array}
13461
13462 \end_inset
13463
13464
13465 \newline
13466 \SpecialChar ~
13467 \SpecialChar ~
13468 \SpecialChar ~
13469 \SpecialChar ~
13470 mov\SpecialChar ~
13471 \SpecialChar ~
13472 r3,_head
13473 \newline
13474 \SpecialChar ~
13475 \SpecialChar ~
13476 \SpecialChar ~
13477 \SpecialChar ~
13478 inc\SpecialChar ~
13479 \SpecialChar ~
13480 _head
13481 \newline
13482 \SpecialChar ~
13483 \SpecialChar ~
13484 \SpecialChar ~
13485 \SpecialChar ~
13486 mov\SpecialChar ~
13487 \SpecialChar ~
13488 dpl,r3
13489 \newline
13490 \SpecialChar ~
13491 \SpecialChar ~
13492 \SpecialChar ~
13493 \SpecialChar ~
13494 mov\SpecialChar ~
13495 \SpecialChar ~
13496 dph,#(_buf >> 8)
13497 \newline
13498 \SpecialChar ~
13499 \SpecialChar ~
13500 \SpecialChar ~
13501 \SpecialChar ~
13502 mov\SpecialChar ~
13503 \SpecialChar ~
13504 a,r2
13505 \newline
13506 \SpecialChar ~
13507 \SpecialChar ~
13508 \SpecialChar ~
13509 \SpecialChar ~
13510 movx @dptr,a
13511 \newline
13512 00103$:
13513 \newline
13514 \SpecialChar ~
13515 \SpecialChar ~
13516 \SpecialChar ~
13517 \SpecialChar ~
13518 ret
13519 \newline
13520 \SpecialChar ~
13521 \SpecialChar ~
13522 \SpecialChar ~
13523 \SpecialChar ~
13524 _endasm
13525 \begin_inset LatexCommand \index{\_endasm}
13526
13527 \end_inset
13528
13529
13530 \begin_inset LatexCommand \index{\_\_endasm}
13531
13532 \end_inset
13533
13534 ;
13535 \newline
13536 }
13537 \layout Standard
13538
13539 The new file buffer.c should compile with only one warning about the unreferenced
13540  function argument 'c'.
13541  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
13542  (1) and finally have:
13543 \layout Verse
13544
13545
13546 \family typewriter
13547 \size footnotesize
13548 unsigned char __far __at(0x7f00) buf[0x100];
13549 \newline
13550 unsigned char head, tail;
13551 \newline
13552 #define USE_ASSEMBLY (1)
13553 \newline
13554
13555 \newline
13556 #if !USE_ASSEMBLY
13557 \newline
13558
13559 \newline
13560 void to_buffer( unsigned char c )
13561 \newline
13562 {
13563 \newline
13564 \SpecialChar ~
13565 \SpecialChar ~
13566 \SpecialChar ~
13567 \SpecialChar ~
13568 if( head != (unsigned char)(tail-1) )
13569 \newline
13570 \SpecialChar ~
13571 \SpecialChar ~
13572 \SpecialChar ~
13573 \SpecialChar ~
13574 \SpecialChar ~
13575 \SpecialChar ~
13576 \SpecialChar ~
13577 \SpecialChar ~
13578 buf[ head++ ] = c;
13579 \newline
13580 }
13581 \newline
13582
13583 \newline
13584 #else
13585 \newline
13586
13587 \newline
13588 void to_buffer( unsigned char c )
13589 \newline
13590 {
13591 \newline
13592 \SpecialChar ~
13593 \SpecialChar ~
13594 \SpecialChar ~
13595 \SpecialChar ~
13596 c; // to avoid warning: unreferenced function argument
13597 \newline
13598 \SpecialChar ~
13599 \SpecialChar ~
13600 \SpecialChar ~
13601 \SpecialChar ~
13602 _asm
13603 \begin_inset LatexCommand \index{\_asm}
13604
13605 \end_inset
13606
13607
13608 \begin_inset LatexCommand \index{\_\_asm}
13609
13610 \end_inset
13611
13612
13613 \newline
13614 \SpecialChar ~
13615 \SpecialChar ~
13616 \SpecialChar ~
13617 \SpecialChar ~
13618 \SpecialChar ~
13619 \SpecialChar ~
13620 \SpecialChar ~
13621 \SpecialChar ~
13622 ; save used registers here.
13623
13624 \newline
13625 \SpecialChar ~
13626 \SpecialChar ~
13627 \SpecialChar ~
13628 \SpecialChar ~
13629 \SpecialChar ~
13630 \SpecialChar ~
13631 \SpecialChar ~
13632 \SpecialChar ~
13633 ; If we were still using r2,r3 we would have to push them here.
13634
13635 \newline
13636 ; if( head != (unsigned char)(tail-1) )
13637 \newline
13638 \SpecialChar ~
13639 \SpecialChar ~
13640 \SpecialChar ~
13641 \SpecialChar ~
13642 \SpecialChar ~
13643 \SpecialChar ~
13644 \SpecialChar ~
13645 \SpecialChar ~
13646 mov\SpecialChar ~
13647  a,_tail
13648 \newline
13649 \SpecialChar ~
13650 \SpecialChar ~
13651 \SpecialChar ~
13652 \SpecialChar ~
13653 \SpecialChar ~
13654 \SpecialChar ~
13655 \SpecialChar ~
13656 \SpecialChar ~
13657 dec\SpecialChar ~
13658  a
13659 \newline
13660 \SpecialChar ~
13661 \SpecialChar ~
13662 \SpecialChar ~
13663 \SpecialChar ~
13664 \SpecialChar ~
13665 \SpecialChar ~
13666 \SpecialChar ~
13667 \SpecialChar ~
13668 xrl\SpecialChar ~
13669  a,_head
13670 \newline
13671 \SpecialChar ~
13672 \SpecialChar ~
13673 \SpecialChar ~
13674 \SpecialChar ~
13675 \SpecialChar ~
13676 \SpecialChar ~
13677 \SpecialChar ~
13678 \SpecialChar ~
13679 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
13680 \newline
13681 \SpecialChar ~
13682 \SpecialChar ~
13683 \SpecialChar ~
13684 \SpecialChar ~
13685 \SpecialChar ~
13686 \SpecialChar ~
13687 \SpecialChar ~
13688 \SpecialChar ~
13689 jz\SpecialChar ~
13690 \SpecialChar ~
13691  t_b_end$
13692 \newline
13693 \SpecialChar ~
13694 \SpecialChar ~
13695 \SpecialChar ~
13696 \SpecialChar ~
13697 \SpecialChar ~
13698 \SpecialChar ~
13699 \SpecialChar ~
13700 \SpecialChar ~
13701 ;
13702 \newline
13703 ; buf[ head++ ] = c;
13704 \newline
13705 \SpecialChar ~
13706 \SpecialChar ~
13707 \SpecialChar ~
13708 \SpecialChar ~
13709 \SpecialChar ~
13710 \SpecialChar ~
13711 \SpecialChar ~
13712 \SpecialChar ~
13713 mov\SpecialChar ~
13714  a,dpl \SpecialChar ~
13715 \SpecialChar ~
13716 \SpecialChar ~
13717 \SpecialChar ~
13718 \SpecialChar ~
13719 \SpecialChar ~
13720 \SpecialChar ~
13721 ; dpl holds lower byte of function argument
13722 \newline
13723 \SpecialChar ~
13724 \SpecialChar ~
13725 \SpecialChar ~
13726 \SpecialChar ~
13727 \SpecialChar ~
13728 \SpecialChar ~
13729 \SpecialChar ~
13730 \SpecialChar ~
13731 mov\SpecialChar ~
13732  dpl,_head \SpecialChar ~
13733 \SpecialChar ~
13734 \SpecialChar ~
13735 ; buf is 0x100 byte aligned so head can be used directly
13736 \newline
13737 \SpecialChar ~
13738 \SpecialChar ~
13739 \SpecialChar ~
13740 \SpecialChar ~
13741 \SpecialChar ~
13742 \SpecialChar ~
13743 \SpecialChar ~
13744 \SpecialChar ~
13745 mov\SpecialChar ~
13746  dph,#(_buf>>8)
13747 \newline
13748 \SpecialChar ~
13749 \SpecialChar ~
13750 \SpecialChar ~
13751 \SpecialChar ~
13752 \SpecialChar ~
13753 \SpecialChar ~
13754 \SpecialChar ~
13755 \SpecialChar ~
13756 movx @dptr,a
13757 \newline
13758 \SpecialChar ~
13759 \SpecialChar ~
13760 \SpecialChar ~
13761 \SpecialChar ~
13762 \SpecialChar ~
13763 \SpecialChar ~
13764 \SpecialChar ~
13765 \SpecialChar ~
13766 inc \SpecialChar ~
13767 _head
13768 \newline
13769 \SpecialChar ~
13770 \SpecialChar ~
13771 \SpecialChar ~
13772 \SpecialChar ~
13773 \SpecialChar ~
13774 \SpecialChar ~
13775 \SpecialChar ~
13776 \SpecialChar ~
13777 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
13778 \newline
13779 t_b_end$:
13780 \newline
13781 \SpecialChar ~
13782 \SpecialChar ~
13783 \SpecialChar ~
13784 \SpecialChar ~
13785 \SpecialChar ~
13786 \SpecialChar ~
13787 \SpecialChar ~
13788 \SpecialChar ~
13789 ; restore used registers here
13790 \newline
13791 \SpecialChar ~
13792 \SpecialChar ~
13793 \SpecialChar ~
13794 \SpecialChar ~
13795 _endasm
13796 \begin_inset LatexCommand \index{\_endasm}
13797
13798 \end_inset
13799
13800
13801 \begin_inset LatexCommand \index{\_\_endasm}
13802
13803 \end_inset
13804
13805 ;
13806 \newline
13807 }
13808 \newline
13809 #endif
13810 \layout Standard
13811
13812 The inline assembler code can contain any valid code understood by the assembler
13813 , this includes any assembler directives and comment lines.
13814  The assembler does not like some characters like ':' or ''' in comments.
13815  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
13816 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
13817
13818 \end_inset
13819
13820
13821 \begin_inset LatexCommand \index{Assembler documentation}
13822
13823 \end_inset
13824
13825  or online at
13826 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/*checkout*/sdcc/trunk/sdcc/as/doc/asxhtm.html}
13827
13828 \end_inset
13829
13830 \SpecialChar ~
13831 .
13832 \layout Standard
13833
13834 The compiler does not do any validation of the code within the
13835 \family typewriter
13836 _asm
13837 \begin_inset LatexCommand \index{\_asm}
13838
13839 \end_inset
13840
13841
13842 \begin_inset LatexCommand \index{\_\_asm}
13843
13844 \end_inset
13845
13846  ...
13847  _endasm
13848 \size footnotesize
13849
13850 \begin_inset LatexCommand \index{\_endasm}
13851
13852 \end_inset
13853
13854
13855 \begin_inset LatexCommand \index{\_\_endasm}
13856
13857 \end_inset
13858
13859
13860 \size default
13861 ;
13862 \family default
13863  keyword pair.
13864  Specifically it will not know which registers are used and thus register
13865  pushing/popping
13866 \begin_inset LatexCommand \index{push/pop}
13867
13868 \end_inset
13869
13870  has to be done manually.
13871
13872 \layout Standard
13873
13874 It is recommended that each assembly instruction (including labels) be placed
13875  in a separate line (as the example shows).
13876  When the -
13877 \begin_inset ERT
13878 status Collapsed
13879
13880 \layout Standard
13881
13882 \backslash
13883 /
13884 \end_inset
13885
13886 -
13887 \emph on
13888 peep-asm
13889 \begin_inset LatexCommand \index{-\/-peep-asm}
13890
13891 \end_inset
13892
13893
13894 \emph default
13895  command line option is used, the inline assembler code will be passed through
13896  the peephole optimizer
13897 \begin_inset LatexCommand \index{Peephole optimizer}
13898
13899 \end_inset
13900
13901 .
13902  There are only a few (if any) cases where this option makes sense, it might
13903  cause some unexpected changes in the inline assembler code.
13904  Please go through the peephole optimizer rules defined in file
13905 \emph on
13906 SDCCpeeph.def
13907 \emph default
13908  before using this option.
13909 \layout Subsection
13910
13911 Naked Functions
13912 \begin_inset LatexCommand \label{sub:Naked-Functions}
13913
13914 \end_inset
13915
13916
13917 \begin_inset LatexCommand \index{Naked functions}
13918
13919 \end_inset
13920
13921
13922 \layout Standard
13923
13924 A special keyword may be associated with a function declaring it as
13925 \emph on
13926 _naked
13927 \begin_inset LatexCommand \index{\_naked}
13928
13929 \end_inset
13930
13931
13932 \begin_inset LatexCommand \index{\_\_naked}
13933
13934 \end_inset
13935
13936 .
13937
13938 \emph default
13939 The
13940 \emph on
13941 _naked
13942 \emph default
13943  function modifier attribute prevents the compiler from generating prologue
13944 \begin_inset LatexCommand \index{function prologue}
13945
13946 \end_inset
13947
13948  and epilogue
13949 \begin_inset LatexCommand \index{function epilogue}
13950
13951 \end_inset
13952
13953  code for that function.
13954  This means that the user is entirely responsible for such things as saving
13955  any registers that may need to be preserved, selecting the proper register
13956  bank, generating the
13957 \emph on
13958 return
13959 \emph default
13960  instruction at the end, etc.
13961  Practically, this means that the contents of the function must be written
13962  in inline assembler.
13963  This is particularly useful for interrupt functions, which can have a large
13964  (and often unnecessary) prologue/epilogue.
13965  For example, compare the code generated by these two functions:
13966 \layout Verse
13967
13968
13969 \family typewriter
13970 volatile
13971 \begin_inset LatexCommand \index{volatile}
13972
13973 \end_inset
13974
13975  data unsigned char counter;
13976 \newline
13977
13978 \newline
13979 void simpleInterrupt(void) __interrupt
13980 \begin_inset LatexCommand \index{interrupt}
13981
13982 \end_inset
13983
13984
13985 \begin_inset LatexCommand \index{\_\_interrupt}
13986
13987 \end_inset
13988
13989  (1)
13990 \newline
13991 {
13992 \newline
13993 \SpecialChar ~
13994 \SpecialChar ~
13995 \SpecialChar ~
13996 \SpecialChar ~
13997 counter++;
13998 \newline
13999 }
14000 \newline
14001
14002 \newline
14003 void nakedInterrupt(void) __interrupt (2) __naked
14004 \newline
14005 {
14006 \newline
14007 \SpecialChar ~
14008 \SpecialChar ~
14009 \SpecialChar ~
14010 \SpecialChar ~
14011 _asm
14012 \begin_inset LatexCommand \index{\_asm}
14013
14014 \end_inset
14015
14016
14017 \begin_inset LatexCommand \index{\_\_asm}
14018
14019 \end_inset
14020
14021
14022 \newline
14023 \SpecialChar ~
14024 \SpecialChar ~
14025 \SpecialChar ~
14026 \SpecialChar ~
14027 \SpecialChar ~
14028 \SpecialChar ~
14029 inc\SpecialChar ~
14030 \SpecialChar ~
14031 \SpecialChar ~
14032 \SpecialChar ~
14033 \SpecialChar ~
14034 _counter ; does not change flags, no need to save psw
14035 \newline
14036 \SpecialChar ~
14037 \SpecialChar ~
14038 \SpecialChar ~
14039 \SpecialChar ~
14040 \SpecialChar ~
14041 \SpecialChar ~
14042 reti\SpecialChar ~
14043 \SpecialChar ~
14044 \SpecialChar ~
14045 \SpecialChar ~
14046 ; MUST explicitly include ret or reti in _naked function.
14047 \newline
14048 \SpecialChar ~
14049 \SpecialChar ~
14050 \SpecialChar ~
14051 \SpecialChar ~
14052 _endasm
14053 \begin_inset LatexCommand \index{\_endasm}
14054
14055 \end_inset
14056
14057
14058 \begin_inset LatexCommand \index{\_\_endasm}
14059
14060 \end_inset
14061
14062 ;
14063 \newline
14064 }
14065 \layout Standard
14066
14067 For an 8051 target, the generated simpleInterrupt looks like:
14068 \layout Verse
14069
14070
14071 \family typewriter
14072 Note, this is an
14073 \emph on
14074 outdated
14075 \emph default
14076  example, recent versions of SDCC generate
14077 \newline
14078 the
14079 \emph on
14080 same
14081 \emph default
14082  code for simpleInterrupt() and nakedInterrupt()!
14083 \newline
14084
14085 \newline
14086 _simpleInterrupt:
14087 \newline
14088 \SpecialChar ~
14089 \SpecialChar ~
14090 \SpecialChar ~
14091 \SpecialChar ~
14092 push\SpecialChar ~
14093 \SpecialChar ~
14094 \SpecialChar ~
14095 \SpecialChar ~
14096 acc
14097 \newline
14098 \SpecialChar ~
14099 \SpecialChar ~
14100 \SpecialChar ~
14101 \SpecialChar ~
14102 push\SpecialChar ~
14103 \SpecialChar ~
14104 \SpecialChar ~
14105 \SpecialChar ~
14106 b
14107 \newline
14108 \SpecialChar ~
14109 \SpecialChar ~
14110 \SpecialChar ~
14111 \SpecialChar ~
14112 push\SpecialChar ~
14113 \SpecialChar ~
14114 \SpecialChar ~
14115 \SpecialChar ~
14116 dpl
14117 \newline
14118 \SpecialChar ~
14119 \SpecialChar ~
14120 \SpecialChar ~
14121 \SpecialChar ~
14122 push\SpecialChar ~
14123 \SpecialChar ~
14124 \SpecialChar ~
14125 \SpecialChar ~
14126 dph
14127 \newline
14128 \SpecialChar ~
14129 \SpecialChar ~
14130 \SpecialChar ~
14131 \SpecialChar ~
14132 push\SpecialChar ~
14133 \SpecialChar ~
14134 \SpecialChar ~
14135 \SpecialChar ~
14136 psw
14137 \newline
14138 \SpecialChar ~
14139 \SpecialChar ~
14140 \SpecialChar ~
14141 \SpecialChar ~
14142 mov\SpecialChar ~
14143 \SpecialChar ~
14144 \SpecialChar ~
14145 \SpecialChar ~
14146 \SpecialChar ~
14147 psw,#0x00
14148 \newline
14149 \SpecialChar ~
14150 \SpecialChar ~
14151 \SpecialChar ~
14152 \SpecialChar ~
14153 inc\SpecialChar ~
14154 \SpecialChar ~
14155 \SpecialChar ~
14156 \SpecialChar ~
14157 \SpecialChar ~
14158 _counter
14159 \newline
14160 \SpecialChar ~
14161 \SpecialChar ~
14162 \SpecialChar ~
14163 \SpecialChar ~
14164 pop\SpecialChar ~
14165 \SpecialChar ~
14166 \SpecialChar ~
14167 \SpecialChar ~
14168 \SpecialChar ~
14169 psw
14170 \newline
14171 \SpecialChar ~
14172 \SpecialChar ~
14173 \SpecialChar ~
14174 \SpecialChar ~
14175 pop\SpecialChar ~
14176 \SpecialChar ~
14177 \SpecialChar ~
14178 \SpecialChar ~
14179 \SpecialChar ~
14180 dph
14181 \newline
14182 \SpecialChar ~
14183 \SpecialChar ~
14184 \SpecialChar ~
14185 \SpecialChar ~
14186 pop\SpecialChar ~
14187 \SpecialChar ~
14188 \SpecialChar ~
14189 \SpecialChar ~
14190 \SpecialChar ~
14191 dpl
14192 \newline
14193 \SpecialChar ~
14194 \SpecialChar ~
14195 \SpecialChar ~
14196 \SpecialChar ~
14197 pop\SpecialChar ~
14198 \SpecialChar ~
14199 \SpecialChar ~
14200 \SpecialChar ~
14201 \SpecialChar ~
14202 b
14203 \newline
14204 \SpecialChar ~
14205 \SpecialChar ~
14206 \SpecialChar ~
14207 \SpecialChar ~
14208 pop\SpecialChar ~
14209 \SpecialChar ~
14210 \SpecialChar ~
14211 \SpecialChar ~
14212 \SpecialChar ~
14213 acc
14214 \newline
14215 \SpecialChar ~
14216 \SpecialChar ~
14217 \SpecialChar ~
14218 \SpecialChar ~
14219 reti
14220 \layout Standard
14221
14222 whereas nakedInterrupt looks like:
14223 \layout Verse
14224
14225
14226 \family typewriter
14227 _nakedInterrupt:
14228 \newline
14229 \SpecialChar ~
14230 \SpecialChar ~
14231 \SpecialChar ~
14232 \SpecialChar ~
14233 inc\SpecialChar ~
14234 \SpecialChar ~
14235 \SpecialChar ~
14236 \SpecialChar ~
14237 _counter ; does not change flags, no need to save psw
14238 \newline
14239 \SpecialChar ~
14240 \SpecialChar ~
14241 \SpecialChar ~
14242 \SpecialChar ~
14243 reti\SpecialChar ~
14244 \SpecialChar ~
14245 \SpecialChar ~
14246 \SpecialChar ~
14247 \SpecialChar ~
14248 \SpecialChar ~
14249 \SpecialChar ~
14250 \SpecialChar ~
14251 \SpecialChar ~
14252 \SpecialChar ~
14253 \SpecialChar ~
14254 \SpecialChar ~
14255 ; MUST explicitly include ret or reti in _naked function
14256 \layout Standard
14257
14258 The related directive #pragma exclude
14259 \begin_inset LatexCommand \index{\#pragma exclude}
14260
14261 \end_inset
14262
14263  allows a more fine grained control over pushing & popping
14264 \begin_inset LatexCommand \index{push/pop}
14265
14266 \end_inset
14267
14268  the registers.
14269 \layout Standard
14270
14271 While there is nothing preventing you from writing C code inside a
14272 \family typewriter
14273 _naked
14274 \family default
14275  function, there are many ways to shoot yourself in the foot doing this,
14276  and it is recommended that you stick to inline assembler.
14277 \layout Subsection
14278
14279 Use of Labels within Inline Assembler
14280 \layout Standard
14281
14282 SDCC allows the use of in-line assembler with a few restrictions regarding
14283  labels.
14284  In older versions of the compiler all labels defined within inline assembler
14285  code
14286 \emph on
14287 had to be
14288 \emph default
14289  of the form
14290 \emph on
14291 nnnnn$
14292 \emph default
14293  where nnnn is a number less than 100 (which implies a limit of utmost 100
14294  inline assembler labels
14295 \emph on
14296 per function
14297 \emph default
14298 \noun on
14299 )
14300 \noun default
14301 .
14302
14303 \layout Verse
14304
14305
14306 \family typewriter
14307 _asm
14308 \begin_inset LatexCommand \index{\_asm}
14309
14310 \end_inset
14311
14312
14313 \begin_inset LatexCommand \index{\_\_asm}
14314
14315 \end_inset
14316
14317
14318 \newline
14319 \SpecialChar ~
14320 \SpecialChar ~
14321 \SpecialChar ~
14322 \SpecialChar ~
14323 mov\SpecialChar ~
14324 \SpecialChar ~
14325 \SpecialChar ~
14326 \SpecialChar ~
14327 \SpecialChar ~
14328 b,#10
14329 \newline
14330 00001$:
14331 \newline
14332 \SpecialChar ~
14333 \SpecialChar ~
14334 \SpecialChar ~
14335 \SpecialChar ~
14336 djnz\SpecialChar ~
14337 \SpecialChar ~
14338 \SpecialChar ~
14339 \SpecialChar ~
14340 b,00001$
14341 \newline
14342 _endasm
14343 \begin_inset LatexCommand \index{\_endasm}
14344
14345 \end_inset
14346
14347
14348 \begin_inset LatexCommand \index{\_\_endasm}
14349
14350 \end_inset
14351
14352  ;
14353 \layout Standard
14354
14355 Inline assembler code cannot reference any C-Labels, however it can reference
14356  labels
14357 \begin_inset LatexCommand \index{Labels}
14358
14359 \end_inset
14360
14361  defined by the inline assembler, e.g.:
14362 \layout Verse
14363
14364
14365 \family typewriter
14366 foo() {
14367 \newline
14368 \SpecialChar ~
14369 \SpecialChar ~
14370 \SpecialChar ~
14371 \SpecialChar ~
14372 /* some c code */
14373 \newline
14374 \SpecialChar ~
14375 \SpecialChar ~
14376 \SpecialChar ~
14377 \SpecialChar ~
14378 _asm
14379 \newline
14380 \SpecialChar ~
14381 \SpecialChar ~
14382 \SpecialChar ~
14383 \SpecialChar ~
14384 \SpecialChar ~
14385 \SpecialChar ~
14386 ; some assembler code
14387 \newline
14388 \SpecialChar ~
14389 \SpecialChar ~
14390 \SpecialChar ~
14391 \SpecialChar ~
14392 \SpecialChar ~
14393 \SpecialChar ~
14394 ljmp $0003
14395 \newline
14396 \SpecialChar ~
14397 \SpecialChar ~
14398 \SpecialChar ~
14399 \SpecialChar ~
14400 _endasm;
14401 \newline
14402 \SpecialChar ~
14403 \SpecialChar ~
14404 \SpecialChar ~
14405 \SpecialChar ~
14406 /* some more c code */
14407 \newline
14408 clabel:\SpecialChar ~
14409 \SpecialChar ~
14410 /* inline assembler cannot reference this label */
14411 \newline
14412 \SpecialChar ~
14413 \SpecialChar ~
14414 \SpecialChar ~
14415 \SpecialChar ~
14416 _asm
14417 \newline
14418 \SpecialChar ~
14419 \SpecialChar ~
14420 \SpecialChar ~
14421 \SpecialChar ~
14422 $0003: ;label (can be referenced by inline assembler only)
14423 \newline
14424 \SpecialChar ~
14425 \SpecialChar ~
14426 \SpecialChar ~
14427 \SpecialChar ~
14428 _endasm
14429 \begin_inset LatexCommand \index{\_endasm}
14430
14431 \end_inset
14432
14433
14434 \begin_inset LatexCommand \index{\_\_endasm}
14435
14436 \end_inset
14437
14438  ;
14439 \newline
14440 \SpecialChar ~
14441 \SpecialChar ~
14442 \SpecialChar ~
14443 \SpecialChar ~
14444 /* some more c code */
14445 \newline
14446 }
14447 \layout Standard
14448
14449 In other words inline assembly code can access labels defined in inline
14450  assembly within the scope of the function.
14451  The same goes the other way, i.e.
14452  labels defines in inline assembly can not be accessed by C statements.
14453 \layout Section
14454
14455 Interfacing with Assembler Code
14456 \begin_inset LatexCommand \index{Assembler routines}
14457
14458 \end_inset
14459
14460
14461 \layout Subsection
14462
14463 Global Registers used for Parameter Passing
14464 \begin_inset LatexCommand \index{Parameter passing}
14465
14466 \end_inset
14467
14468
14469 \layout Standard
14470
14471 The compiler always uses the global registers
14472 \emph on
14473 DPL, DPH
14474 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
14475
14476 \end_inset
14477
14478
14479 \begin_inset LatexCommand \index{DPTR}
14480
14481 \end_inset
14482
14483 , B
14484 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
14485
14486 \end_inset
14487
14488
14489 \emph default
14490 and
14491 \emph on
14492  ACC
14493 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
14494
14495 \end_inset
14496
14497
14498 \emph default
14499  to pass the first parameter to a routine.
14500  The second parameter onwards is either allocated on the stack (for reentrant
14501  routines or if -
14502 \begin_inset ERT
14503 status Collapsed
14504
14505 \layout Standard
14506
14507 \backslash
14508 /
14509 \end_inset
14510
14511 -stack-auto is used) or in data / xdata memory (depending on the memory
14512  model).
14513
14514 \layout Subsection
14515
14516 Assembler Routine (non-reentrant)
14517 \layout Standard
14518
14519 In the following example
14520 \begin_inset LatexCommand \index{reentrant}
14521
14522 \end_inset
14523
14524
14525 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
14526
14527 \end_inset
14528
14529  the function c_func calls an assembler routine asm_func, which takes two
14530  parameters
14531 \begin_inset LatexCommand \index{function parameter}
14532
14533 \end_inset
14534
14535 .
14536 \layout Verse
14537
14538
14539 \family typewriter
14540 extern int asm_func(unsigned char, unsigned char);
14541 \newline
14542
14543 \newline
14544 int c_func (unsigned char i, unsigned char j)
14545 \newline
14546 {
14547 \newline
14548 \SpecialChar ~
14549 \SpecialChar ~
14550 \SpecialChar ~
14551 \SpecialChar ~
14552 return asm_func(i,j);
14553 \newline
14554 }
14555 \newline
14556
14557 \newline
14558 int main()
14559 \newline
14560 {
14561 \newline
14562 \SpecialChar ~
14563 \SpecialChar ~
14564 \SpecialChar ~
14565 \SpecialChar ~
14566 return c_func(10,9);
14567 \newline
14568 }
14569 \layout Standard
14570
14571 The corresponding assembler function is:
14572 \layout Verse
14573
14574
14575 \family typewriter
14576 .globl _asm_func_PARM_2
14577 \newline
14578 \SpecialChar ~
14579 \SpecialChar ~
14580 \SpecialChar ~
14581 \SpecialChar ~
14582 \SpecialChar ~
14583 \SpecialChar ~
14584 \SpecialChar ~
14585 \SpecialChar ~
14586 .globl _asm_func
14587 \newline
14588 \SpecialChar ~
14589 \SpecialChar ~
14590 \SpecialChar ~
14591 \SpecialChar ~
14592 \SpecialChar ~
14593 \SpecialChar ~
14594 \SpecialChar ~
14595 \SpecialChar ~
14596 .area OSEG
14597 \newline
14598 _asm_func_PARM_2:
14599 \newline
14600 \SpecialChar ~
14601 \SpecialChar ~
14602 \SpecialChar ~
14603 \SpecialChar ~
14604 \SpecialChar ~
14605 \SpecialChar ~
14606 \SpecialChar ~
14607 \SpecialChar ~
14608 .ds    1
14609 \newline
14610 \SpecialChar ~
14611 \SpecialChar ~
14612 \SpecialChar ~
14613 \SpecialChar ~
14614 \SpecialChar ~
14615 \SpecialChar ~
14616 \SpecialChar ~
14617 \SpecialChar ~
14618 .area CSEG
14619 \newline
14620 _asm_func:
14621 \newline
14622 \SpecialChar ~
14623 \SpecialChar ~
14624 \SpecialChar ~
14625 \SpecialChar ~
14626 \SpecialChar ~
14627 \SpecialChar ~
14628 \SpecialChar ~
14629 \SpecialChar ~
14630 mov\SpecialChar ~
14631 \SpecialChar ~
14632 \SpecialChar ~
14633 \SpecialChar ~
14634 a,dpl
14635 \newline
14636 \SpecialChar ~
14637 \SpecialChar ~
14638 \SpecialChar ~
14639 \SpecialChar ~
14640 \SpecialChar ~
14641 \SpecialChar ~
14642 \SpecialChar ~
14643 \SpecialChar ~
14644 add\SpecialChar ~
14645 \SpecialChar ~
14646 \SpecialChar ~
14647 \SpecialChar ~
14648 a,_asm_func_PARM_2
14649 \newline
14650 \SpecialChar ~
14651 \SpecialChar ~
14652 \SpecialChar ~
14653 \SpecialChar ~
14654 \SpecialChar ~
14655 \SpecialChar ~
14656 \SpecialChar ~
14657 \SpecialChar ~
14658 mov\SpecialChar ~
14659 \SpecialChar ~
14660 \SpecialChar ~
14661 \SpecialChar ~
14662 dpl,a
14663 \newline
14664 \SpecialChar ~
14665 \SpecialChar ~
14666 \SpecialChar ~
14667 \SpecialChar ~
14668 \SpecialChar ~
14669 \SpecialChar ~
14670 \SpecialChar ~
14671 \SpecialChar ~
14672 mov\SpecialChar ~
14673 \SpecialChar ~
14674 \SpecialChar ~
14675 \SpecialChar ~
14676 dph
14677 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
14678
14679 \end_inset
14680
14681 ,#0x00
14682 \newline
14683 \SpecialChar ~
14684 \SpecialChar ~
14685 \SpecialChar ~
14686 \SpecialChar ~
14687 \SpecialChar ~
14688 \SpecialChar ~
14689 \SpecialChar ~
14690 \SpecialChar ~
14691 ret
14692 \layout Standard
14693
14694 Note here that the return values
14695 \begin_inset LatexCommand \index{return value}
14696
14697 \end_inset
14698
14699  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
14700  two byte values.
14701  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
14702 b' & 'acc' for four byte values.
14703 \layout Standard
14704
14705 The parameter naming convention is _<function_name>_PARM_<n>, where n is
14706  the parameter number starting from 1, and counting from the left.
14707  The first parameter is passed in
14708 \begin_inset Quotes eld
14709 \end_inset
14710
14711 dpl
14712 \begin_inset Quotes erd
14713 \end_inset
14714
14715  for a one byte parameter,
14716 \begin_inset Quotes eld
14717 \end_inset
14718
14719 dptr
14720 \begin_inset Quotes erd
14721 \end_inset
14722
14723  for two bytes,
14724 \begin_inset Quotes eld
14725 \end_inset
14726
14727 b,dptr
14728 \begin_inset Quotes erd
14729 \end_inset
14730
14731  for three bytes and
14732 \begin_inset Quotes eld
14733 \end_inset
14734
14735 acc,b,dptr
14736 \begin_inset Quotes erd
14737 \end_inset
14738
14739  for a four bytes parameter.
14740  The variable name for the second parameter will be _<function_name>_PARM_2.
14741 \newline
14742
14743 \newline
14744 Assemble the assembler routine with the following command:
14745 \newline
14746
14747 \newline
14748
14749 \family sans
14750 \series bold
14751 asx8051 -losg asmfunc.asm
14752 \newline
14753
14754 \newline
14755
14756 \family default
14757 \series default
14758 Then compile and link the assembler routine to the C source file with the
14759  following command:
14760 \newline
14761
14762 \newline
14763
14764 \family sans
14765 \series bold
14766 sdcc cfunc.c asmfunc.rel
14767 \layout Subsection
14768
14769 Assembler Routine (reentrant)
14770 \layout Standard
14771
14772 In this case
14773 \begin_inset LatexCommand \index{reentrant}
14774
14775 \end_inset
14776
14777
14778 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
14779
14780 \end_inset
14781
14782  the second parameter
14783 \begin_inset LatexCommand \index{function parameter}
14784
14785 \end_inset
14786
14787  onwards will be passed on the stack, the parameters are pushed from right
14788  to left i.e.
14789  after the call the leftmost parameter will be on the top of the stack.
14790  Here is an example:
14791 \layout Verse
14792
14793
14794 \family typewriter
14795 extern int asm_func(unsigned char, unsigned char);
14796 \newline
14797
14798 \newline
14799 int c_func (unsigned char i, unsigned char j) reentrant
14800 \newline
14801 {
14802 \newline
14803 \SpecialChar ~
14804 \SpecialChar ~
14805 \SpecialChar ~
14806 \SpecialChar ~
14807 return asm_func(i,j);
14808 \newline
14809 }
14810 \newline
14811
14812 \newline
14813 int main()
14814 \newline
14815 {
14816 \newline
14817 \SpecialChar ~
14818 \SpecialChar ~
14819 \SpecialChar ~
14820 \SpecialChar ~
14821 return c_func(10,9);
14822 \newline
14823 }
14824 \layout Standard
14825
14826 The corresponding assembler routine is:
14827 \layout Verse
14828
14829
14830 \family typewriter
14831 .globl _asm_func
14832 \newline
14833 _asm_func:
14834 \newline
14835 \SpecialChar ~
14836 \SpecialChar ~
14837 \SpecialChar ~
14838 \SpecialChar ~
14839 push  _bp
14840 \newline
14841 \SpecialChar ~
14842 \SpecialChar ~
14843 \SpecialChar ~
14844 \SpecialChar ~
14845 mov _bp,sp
14846 \newline
14847 \SpecialChar ~
14848 \SpecialChar ~
14849 \SpecialChar ~
14850 \SpecialChar ~
14851 mov r2,dpl
14852 \newline
14853 \SpecialChar ~
14854 \SpecialChar ~
14855 \SpecialChar ~
14856 \SpecialChar ~
14857 mov a,_bp
14858 \newline
14859 \SpecialChar ~
14860 \SpecialChar ~
14861 \SpecialChar ~
14862 \SpecialChar ~
14863 add a,#0xfd
14864 \newline
14865 \SpecialChar ~
14866 \SpecialChar ~
14867 \SpecialChar ~
14868 \SpecialChar ~
14869 mov r0,a
14870 \newline
14871 \SpecialChar ~
14872 \SpecialChar ~
14873 \SpecialChar ~
14874 \SpecialChar ~
14875 add  a,#0xfc ;?
14876 \newline
14877 \SpecialChar ~
14878 \SpecialChar ~
14879 \SpecialChar ~
14880 \SpecialChar ~
14881 mov  r1,a
14882 \newline
14883 \SpecialChar ~
14884 \SpecialChar ~
14885 \SpecialChar ~
14886 \SpecialChar ~
14887 mov  a,@r0
14888 \newline
14889 \SpecialChar ~
14890 \SpecialChar ~
14891 \SpecialChar ~
14892 \SpecialChar ~
14893 add  a,r2 ;?
14894 \newline
14895 \SpecialChar ~
14896 \SpecialChar ~
14897 \SpecialChar ~
14898 \SpecialChar ~
14899 mov  dpl,a
14900 \newline
14901 \SpecialChar ~
14902 \SpecialChar ~
14903 \SpecialChar ~
14904 \SpecialChar ~
14905 mov  dph,#0x00
14906 \newline
14907 \SpecialChar ~
14908 \SpecialChar ~
14909 \SpecialChar ~
14910 \SpecialChar ~
14911 mov  sp,_bp
14912 \newline
14913 \SpecialChar ~
14914 \SpecialChar ~
14915 \SpecialChar ~
14916 \SpecialChar ~
14917 pop  _bp
14918 \newline
14919 \SpecialChar ~
14920 \SpecialChar ~
14921 \SpecialChar ~
14922 \SpecialChar ~
14923 ret
14924 \layout Standard
14925 \added_space_bottom bigskip
14926 The compiling and linking procedure remains the same, however note the extra
14927  entry & exit linkage required for the assembler code, _bp is the stack
14928  frame pointer and is used to compute the offset into the stack for parameters
14929  and local variables.
14930 \layout Section
14931
14932 int (16 bit)
14933 \begin_inset LatexCommand \index{int (16 bit)}
14934
14935 \end_inset
14936
14937  and long (32 bit)
14938 \begin_inset LatexCommand \index{long (32 bit)}
14939
14940 \end_inset
14941
14942  Support
14943 \layout Standard
14944
14945 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
14946  multiplication and modulus operations are implemented by support routines.
14947  These support routines are all developed in ANSI-C to facilitate porting
14948  to other MCUs, although some model specific assembler optimizations are
14949  used.
14950  The following files contain the described routines, all of them can be
14951  found in <installdir>/share/sdcc/lib.
14952 \newline
14953
14954 \layout Standard
14955 \align center
14956
14957 \begin_inset  Tabular
14958 <lyxtabular version="3" rows="11" columns="2">
14959 <features>
14960 <column alignment="left" valignment="top" leftline="true" width="0">
14961 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
14962 <row topline="true" bottomline="true">
14963 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14964 \begin_inset Text
14965
14966 \layout Standard
14967
14968
14969 \series bold
14970 Function
14971 \end_inset
14972 </cell>
14973 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14974 \begin_inset Text
14975
14976 \layout Standard
14977
14978
14979 \series bold
14980 Description
14981 \end_inset
14982 </cell>
14983 </row>
14984 <row topline="true">
14985 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14986 \begin_inset Text
14987
14988 \layout Standard
14989
14990 _mulint.c
14991 \end_inset
14992 </cell>
14993 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14994 \begin_inset Text
14995
14996 \layout Standard
14997
14998 16 bit multiplication
14999 \end_inset
15000 </cell>
15001 </row>
15002 <row topline="true">
15003 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15004 \begin_inset Text
15005
15006 \layout Standard
15007
15008 _divsint.c
15009 \end_inset
15010 </cell>
15011 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15012 \begin_inset Text
15013
15014 \layout Standard
15015
15016  signed 16 bit division (calls _divuint)
15017 \end_inset
15018 </cell>
15019 </row>
15020 <row topline="true">
15021 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15022 \begin_inset Text
15023
15024 \layout Standard
15025
15026 _divuint.c
15027 \end_inset
15028 </cell>
15029 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15030 \begin_inset Text
15031
15032 \layout Standard
15033
15034  unsigned 16 bit division
15035 \end_inset
15036 </cell>
15037 </row>
15038 <row topline="true">
15039 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15040 \begin_inset Text
15041
15042 \layout Standard
15043
15044 _modsint.c
15045 \end_inset
15046 </cell>
15047 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15048 \begin_inset Text
15049
15050 \layout Standard
15051
15052 signed 16 bit modulus (calls _moduint)
15053 \end_inset
15054 </cell>
15055 </row>
15056 <row topline="true">
15057 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15058 \begin_inset Text
15059
15060 \layout Standard
15061
15062 _moduint.c
15063 \end_inset
15064 </cell>
15065 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15066 \begin_inset Text
15067
15068 \layout Standard
15069
15070 unsigned 16 bit modulus
15071 \end_inset
15072 </cell>
15073 </row>
15074 <row topline="true">
15075 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15076 \begin_inset Text
15077
15078 \layout Standard
15079
15080 _mullong.c
15081 \end_inset
15082 </cell>
15083 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15084 \begin_inset Text
15085
15086 \layout Standard
15087
15088 32 bit multiplication
15089 \end_inset
15090 </cell>
15091 </row>
15092 <row topline="true">
15093 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15094 \begin_inset Text
15095
15096 \layout Standard
15097
15098 _divslong.c
15099 \end_inset
15100 </cell>
15101 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15102 \begin_inset Text
15103
15104 \layout Standard
15105
15106  signed 32 division (calls _divulong)
15107 \end_inset
15108 </cell>
15109 </row>
15110 <row topline="true">
15111 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15112 \begin_inset Text
15113
15114 \layout Standard
15115
15116 _divulong.c
15117 \end_inset
15118 </cell>
15119 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15120 \begin_inset Text
15121
15122 \layout Standard
15123
15124 unsigned 32 division
15125 \end_inset
15126 </cell>
15127 </row>
15128 <row topline="true">
15129 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15130 \begin_inset Text
15131
15132 \layout Standard
15133
15134 _modslong.c
15135 \end_inset
15136 </cell>
15137 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15138 \begin_inset Text
15139
15140 \layout Standard
15141
15142  signed 32 bit modulus (calls _modulong)
15143 \end_inset
15144 </cell>
15145 </row>
15146 <row topline="true" bottomline="true">
15147 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15148 \begin_inset Text
15149
15150 \layout Standard
15151
15152 _modulong.c
15153 \end_inset
15154 </cell>
15155 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15156 \begin_inset Text
15157
15158 \layout Standard
15159
15160 unsigned 32 bit modulus
15161 \end_inset
15162 </cell>
15163 </row>
15164 </lyxtabular>
15165
15166 \end_inset
15167
15168
15169 \newline
15170
15171 \layout Standard
15172
15173 Since they are compiled as
15174 \emph on
15175 non-reentrant
15176 \emph default
15177
15178 \begin_inset LatexCommand \index{reentrant}
15179
15180 \end_inset
15181
15182 , interrupt
15183 \begin_inset LatexCommand \index{interrupt}
15184
15185 \end_inset
15186
15187  service routines should not do any of the above operations.
15188  If this is unavoidable then the above routines will need to be compiled
15189  with the
15190 \emph on
15191 -
15192 \begin_inset ERT
15193 status Collapsed
15194
15195 \layout Standard
15196
15197 \backslash
15198 /
15199 \end_inset
15200
15201 -stack-auto
15202 \begin_inset LatexCommand \index{-\/-stack-auto}
15203
15204 \end_inset
15205
15206
15207 \emph default
15208  option, after which the source program will have to be compiled with
15209 \emph on
15210 -
15211 \begin_inset ERT
15212 status Collapsed
15213
15214 \layout Standard
15215
15216 \backslash
15217 /
15218 \end_inset
15219
15220 -int-long-reent
15221 \begin_inset LatexCommand \index{-\/-int-long-reent}
15222
15223 \end_inset
15224
15225
15226 \emph default
15227  option.
15228  Notice that you don't have to call these routines directly.
15229  The compiler will use them automatically every time an integer operation
15230  is required.
15231 \layout Section
15232
15233 Floating Point Support
15234 \begin_inset LatexCommand \index{Floating point support}
15235
15236 \end_inset
15237
15238
15239 \layout Standard
15240
15241 SDCC supports IEEE (single precision 4 bytes) floating point numbers.
15242  The floating point support routines are derived from gcc's floatlib.c and
15243  consist of the following routines:
15244 \newline
15245
15246 \layout Standard
15247 \align center
15248
15249 \size footnotesize
15250
15251 \begin_inset  Tabular
15252 <lyxtabular version="3" rows="17" columns="2">
15253 <features>
15254 <column alignment="left" valignment="top" leftline="true" width="0">
15255 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
15256 <row topline="true" bottomline="true">
15257 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15258 \begin_inset Text
15259
15260 \layout Standard
15261
15262
15263 \family roman
15264 \series medium
15265 \shape up
15266 \size normal
15267 \emph off
15268 \bar no
15269 \noun off
15270 \color none
15271 Function
15272 \end_inset
15273 </cell>
15274 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15275 \begin_inset Text
15276
15277 \layout Standard
15278
15279 Description
15280 \end_inset
15281 </cell>
15282 </row>
15283 <row topline="true">
15284 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15285 \begin_inset Text
15286
15287 \layout Standard
15288
15289
15290 \family roman
15291 \series medium
15292 \shape up
15293 \size normal
15294 \emph off
15295 \bar no
15296 \noun off
15297 \color none
15298 _fsadd.c
15299 \end_inset
15300 </cell>
15301 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15302 \begin_inset Text
15303
15304 \layout Standard
15305
15306
15307 \family roman
15308 \series medium
15309 \shape up
15310 \size normal
15311 \emph off
15312 \bar no
15313 \noun off
15314 \color none
15315 add floating point numbers
15316 \end_inset
15317 </cell>
15318 </row>
15319 <row topline="true">
15320 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15321 \begin_inset Text
15322
15323 \layout Standard
15324
15325
15326 \family roman
15327 \series medium
15328 \shape up
15329 \size normal
15330 \emph off
15331 \bar no
15332 \noun off
15333 \color none
15334 _fssub.c
15335 \end_inset
15336 </cell>
15337 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15338 \begin_inset Text
15339
15340 \layout Standard
15341
15342
15343 \family roman
15344 \series medium
15345 \shape up
15346 \size normal
15347 \emph off
15348 \bar no
15349 \noun off
15350 \color none
15351 subtract floating point numbers
15352 \end_inset
15353 </cell>
15354 </row>
15355 <row topline="true">
15356 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15357 \begin_inset Text
15358
15359 \layout Standard
15360
15361
15362 \family roman
15363 \series medium
15364 \shape up
15365 \size normal
15366 \emph off
15367 \bar no
15368 \noun off
15369 \color none
15370 _fsdiv.c
15371 \end_inset
15372 </cell>
15373 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15374 \begin_inset Text
15375
15376 \layout Standard
15377
15378
15379 \family roman
15380 \series medium
15381 \shape up
15382 \size normal
15383 \emph off
15384 \bar no
15385 \noun off
15386 \color none
15387 divide floating point numbers
15388 \end_inset
15389 </cell>
15390 </row>
15391 <row topline="true">
15392 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15393 \begin_inset Text
15394
15395 \layout Standard
15396
15397
15398 \family roman
15399 \series medium
15400 \shape up
15401 \size normal
15402 \emph off
15403 \bar no
15404 \noun off
15405 \color none
15406 _fsmul.c
15407 \end_inset
15408 </cell>
15409 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15410 \begin_inset Text
15411
15412 \layout Standard
15413
15414
15415 \family roman
15416 \series medium
15417 \shape up
15418 \size normal
15419 \emph off
15420 \bar no
15421 \noun off
15422 \color none
15423 multiply floating point numbers
15424 \end_inset
15425 </cell>
15426 </row>
15427 <row topline="true">
15428 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15429 \begin_inset Text
15430
15431 \layout Standard
15432
15433
15434 \family roman
15435 \series medium
15436 \shape up
15437 \size normal
15438 \emph off
15439 \bar no
15440 \noun off
15441 \color none
15442 _fs2uchar.c
15443 \end_inset
15444 </cell>
15445 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15446 \begin_inset Text
15447
15448 \layout Standard
15449
15450
15451 \family roman
15452 \series medium
15453 \shape up
15454 \size normal
15455 \emph off
15456 \bar no
15457 \noun off
15458 \color none
15459 convert floating point to unsigned char
15460 \end_inset
15461 </cell>
15462 </row>
15463 <row topline="true">
15464 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15465 \begin_inset Text
15466
15467 \layout Standard
15468
15469
15470 \family roman
15471 \series medium
15472 \shape up
15473 \size normal
15474 \emph off
15475 \bar no
15476 \noun off
15477 \color none
15478 _fs2char.c
15479 \end_inset
15480 </cell>
15481 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15482 \begin_inset Text
15483
15484 \layout Standard
15485
15486
15487 \family roman
15488 \series medium
15489 \shape up
15490 \size normal
15491 \emph off
15492 \bar no
15493 \noun off
15494 \color none
15495 convert floating point to signed char
15496 \end_inset
15497 </cell>
15498 </row>
15499 <row topline="true">
15500 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15501 \begin_inset Text
15502
15503 \layout Standard
15504
15505
15506 \family roman
15507 \series medium
15508 \shape up
15509 \size normal
15510 \emph off
15511 \bar no
15512 \noun off
15513 \color none
15514 _fs2uint.c
15515 \end_inset
15516 </cell>
15517 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15518 \begin_inset Text
15519
15520 \layout Standard
15521
15522
15523 \family roman
15524 \series medium
15525 \shape up
15526 \size normal
15527 \emph off
15528 \bar no
15529 \noun off
15530 \color none
15531 convert floating point to unsigned int
15532 \end_inset
15533 </cell>
15534 </row>
15535 <row topline="true">
15536 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15537 \begin_inset Text
15538
15539 \layout Standard
15540
15541
15542 \family roman
15543 \series medium
15544 \shape up
15545 \size normal
15546 \emph off
15547 \bar no
15548 \noun off
15549 \color none
15550 _fs2int.c
15551 \end_inset
15552 </cell>
15553 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15554 \begin_inset Text
15555
15556 \layout Standard
15557
15558
15559 \family roman
15560 \series medium
15561 \shape up
15562 \size normal
15563 \emph off
15564 \bar no
15565 \noun off
15566 \color none
15567 convert floating point to signed int
15568 \end_inset
15569 </cell>
15570 </row>
15571 <row topline="true">
15572 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15573 \begin_inset Text
15574
15575 \layout Standard
15576
15577
15578 \family roman
15579 \series medium
15580 \shape up
15581 \size normal
15582 \emph off
15583 \bar no
15584 \noun off
15585 \color none
15586 _fs2ulong.
15587 \family default
15588 \series default
15589 \shape default
15590 \size default
15591 \emph default
15592 \bar default
15593 \noun default
15594 \color default
15595 c
15596 \end_inset
15597 </cell>
15598 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15599 \begin_inset Text
15600
15601 \layout Standard
15602
15603
15604 \family roman
15605 \series medium
15606 \shape up
15607 \size normal
15608 \emph off
15609 \bar no
15610 \noun off
15611 \color none
15612 convert floating point to unsigned long
15613 \end_inset
15614 </cell>
15615 </row>
15616 <row topline="true">
15617 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15618 \begin_inset Text
15619
15620 \layout Standard
15621
15622
15623 \family roman
15624 \series medium
15625 \shape up
15626 \size normal
15627 \emph off
15628 \bar no
15629 \noun off
15630 \color none
15631 _fs2long.c
15632 \end_inset
15633 </cell>
15634 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15635 \begin_inset Text
15636
15637 \layout Standard
15638
15639
15640 \family roman
15641 \series medium
15642 \shape up
15643 \size normal
15644 \emph off
15645 \bar no
15646 \noun off
15647 \color none
15648 convert floating point to signed long
15649 \end_inset
15650 </cell>
15651 </row>
15652 <row topline="true">
15653 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15654 \begin_inset Text
15655
15656 \layout Standard
15657
15658
15659 \family roman
15660 \series medium
15661 \shape up
15662 \size normal
15663 \emph off
15664 \bar no
15665 \noun off
15666 \color none
15667 _uchar2fs.c
15668 \end_inset
15669 </cell>
15670 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15671 \begin_inset Text
15672
15673 \layout Standard
15674
15675
15676 \family roman
15677 \series medium
15678 \shape up
15679 \size normal
15680 \emph off
15681 \bar no
15682 \noun off
15683 \color none
15684 convert unsigned char to floating point
15685 \end_inset
15686 </cell>
15687 </row>
15688 <row topline="true">
15689 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15690 \begin_inset Text
15691
15692 \layout Standard
15693
15694
15695 \family roman
15696 \series medium
15697 \shape up
15698 \size normal
15699 \emph off
15700 \bar no
15701 \noun off
15702 \color none
15703 _char2fs.c
15704 \end_inset
15705 </cell>
15706 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15707 \begin_inset Text
15708
15709 \layout Standard
15710
15711
15712 \family roman
15713 \series medium
15714 \shape up
15715 \size normal
15716 \emph off
15717 \bar no
15718 \noun off
15719 \color none
15720 convert char to floating point number
15721 \end_inset
15722 </cell>
15723 </row>
15724 <row topline="true">
15725 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15726 \begin_inset Text
15727
15728 \layout Standard
15729
15730
15731 \family roman
15732 \series medium
15733 \shape up
15734 \size normal
15735 \emph off
15736 \bar no
15737 \noun off
15738 \color none
15739 _uint2fs.c
15740 \end_inset
15741 </cell>
15742 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15743 \begin_inset Text
15744
15745 \layout Standard
15746
15747
15748 \family roman
15749 \series medium
15750 \shape up
15751 \size normal
15752 \emph off
15753 \bar no
15754 \noun off
15755 \color none
15756 convert unsigned int to floating point
15757 \end_inset
15758 </cell>
15759 </row>
15760 <row topline="true">
15761 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15762 \begin_inset Text
15763
15764 \layout Standard
15765
15766
15767 \family roman
15768 \series medium
15769 \shape up
15770 \size normal
15771 \emph off
15772 \bar no
15773 \noun off
15774 \color none
15775 _int2fs.c
15776 \end_inset
15777 </cell>
15778 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15779 \begin_inset Text
15780
15781 \layout Standard
15782
15783
15784 \family roman
15785 \series medium
15786 \shape up
15787 \size normal
15788 \emph off
15789 \bar no
15790 \noun off
15791 \color none
15792 convert int to floating point numbers
15793 \end_inset
15794 </cell>
15795 </row>
15796 <row topline="true">
15797 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15798 \begin_inset Text
15799
15800 \layout Standard
15801
15802
15803 \family roman
15804 \series medium
15805 \shape up
15806 \size normal
15807 \emph off
15808 \bar no
15809 \noun off
15810 \color none
15811 _ulong2fs.c
15812 \end_inset
15813 </cell>
15814 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15815 \begin_inset Text
15816
15817 \layout Standard
15818
15819
15820 \family roman
15821 \series medium
15822 \shape up
15823 \size normal
15824 \emph off
15825 \bar no
15826 \noun off
15827 \color none
15828 convert unsigned long to floating point number
15829 \end_inset
15830 </cell>
15831 </row>
15832 <row topline="true" bottomline="true">
15833 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15834 \begin_inset Text
15835
15836 \layout Standard
15837
15838
15839 \family roman
15840 \series medium
15841 \shape up
15842 \size normal
15843 \emph off
15844 \bar no
15845 \noun off
15846 \color none
15847 _long2fs.c
15848 \end_inset
15849 </cell>
15850 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15851 \begin_inset Text
15852
15853 \layout Standard
15854
15855
15856 \family roman
15857 \series medium
15858 \shape up
15859 \size normal
15860 \emph off
15861 \bar no
15862 \noun off
15863 \color none
15864 convert long to floating point number
15865 \end_inset
15866 </cell>
15867 </row>
15868 </lyxtabular>
15869
15870 \end_inset
15871
15872
15873 \newline
15874
15875 \layout Standard
15876 \added_space_bottom bigskip
15877 These support routines are developed in ANSI-C so there is room for space
15878  and speed improvement
15879 \begin_inset Foot
15880 collapsed false
15881
15882 \layout Standard
15883
15884 These floating point routines (
15885 \emph on
15886 not
15887 \emph default
15888  sinf(), cosf(), ...) for the mcs51 are implemented in assembler.
15889
15890 \end_inset
15891
15892 .
15893  Note if all these routines are used simultaneously the data space might
15894  overflow.
15895  For serious floating point usage the large model might be needed.
15896  Also notice that you don't have to call this routines directly.
15897  The compiler will use them automatically every time a floating point operation
15898  is required.
15899 \layout Section
15900
15901 Library Routines
15902 \begin_inset LatexCommand \index{Libraries}
15903
15904 \end_inset
15905
15906
15907 \layout Standard
15908
15909
15910 \emph on
15911 <pending: this is messy and incomplete - a little more information is in
15912  sdcc/doc/libdoc.txt
15913 \emph default
15914  >
15915 \layout Subsection
15916
15917 Compiler support routines (_gptrget, _mulint etc.)
15918 \layout Subsection
15919
15920 Stdclib functions (puts, printf, strcat etc.)
15921 \layout Subsubsection
15922
15923 <stdio.h>
15924 \layout Standard
15925
15926
15927 \begin_inset LatexCommand \index{<stdio.h>}
15928
15929 \end_inset
15930
15931 As usual on embedded systems you have to provide your own
15932 \family typewriter
15933 getchar()
15934 \begin_inset LatexCommand \index{getchar()}
15935
15936 \end_inset
15937
15938
15939 \family default
15940 and
15941 \family typewriter
15942 putchar()
15943 \begin_inset LatexCommand \index{putchar()}
15944
15945 \end_inset
15946
15947
15948 \family default
15949  routines.
15950  SDCC does not know whether the system connects to a serial line with or
15951  without handshake, LCD, keyboard or other device.
15952  And whether a
15953 \family typewriter
15954 lf
15955 \family default
15956  to
15957 \family typewriter
15958 crlf
15959 \family default
15960  conversion within
15961 \family typewriter
15962 putchar()
15963 \family default
15964  is intended.
15965  You'll find examples for serial routines f.e.
15966  in sdcc/device/lib.
15967 \layout Standard
15968
15969 The default
15970 \family typewriter
15971  printf()
15972 \begin_inset LatexCommand \index{printf()}
15973
15974 \end_inset
15975
15976
15977 \family default
15978 implementation in
15979 \family typewriter
15980  printf_large.c
15981 \family default
15982  does not support float (except on ds390).
15983  To enable this recompile it with the option
15984 \emph on
15985 -
15986 \begin_inset ERT
15987 status Collapsed
15988
15989 \layout Standard
15990
15991 \backslash
15992 /
15993 \end_inset
15994
15995 DUSE_FLOATS=1
15996 \begin_inset LatexCommand \index{USE\_FLOATS}
15997
15998 \end_inset
15999
16000
16001 \emph default
16002  on the command line.
16003  Use
16004 \emph on
16005  -
16006 \begin_inset ERT
16007 status Collapsed
16008
16009 \layout Standard
16010
16011 \backslash
16012 /
16013 \end_inset
16014
16015 -model-large
16016 \begin_inset LatexCommand \index{-\/-model-large}
16017
16018 \end_inset
16019
16020
16021 \emph default
16022  for the mcs51 port, since this uses a lot of memory.
16023 \layout Standard
16024
16025 If you're short on memory you might want to use
16026 \family typewriter
16027 printf_small()
16028 \begin_inset LatexCommand \index{printf\_small()}
16029
16030 \end_inset
16031
16032
16033 \family default
16034
16035 \emph on
16036 instead
16037 \emph default
16038  of
16039 \family typewriter
16040  printf().
16041
16042 \family default
16043  For the mcs51 there additionally are assembly versions
16044 \family typewriter
16045 printf_tiny()
16046 \begin_inset LatexCommand \index{printf\_tiny() (mcs51)}
16047
16048 \end_inset
16049
16050
16051 \family default
16052  (subset of printf using less than 270 bytes) and
16053 \family typewriter
16054 printf_fast()
16055 \begin_inset LatexCommand \index{printf\_fast() (mcs51)}
16056
16057 \end_inset
16058
16059
16060 \family default
16061 and
16062 \family typewriter
16063  printf_fast_f()
16064 \begin_inset LatexCommand \index{printf\_fast\_f() (mcs51)}
16065
16066 \end_inset
16067
16068
16069 \family default
16070  (floating-point aware version of printf_fast) which should fit the requirements
16071  of many embedded systems (printf_fast() can be customized by unsetting
16072  #defines to
16073 \emph on
16074 not
16075 \emph default
16076  support long variables and field widths).
16077 \layout Subsubsection
16078
16079 <malloc.h>
16080 \begin_inset LatexCommand \index{malloc.h}
16081
16082 \end_inset
16083
16084
16085 \layout Standard
16086
16087 As of SDCC 2.6.2 you no longer need to call an initialization routine before
16088  using dynamic memory allocation
16089 \begin_inset LatexCommand \index{dynamic memory allocation (malloc)}
16090
16091 \end_inset
16092
16093  and a default heap
16094 \begin_inset LatexCommand \index{heap (malloc)}
16095
16096 \end_inset
16097
16098  space of 1024 bytes is provided for malloc to allocate memory from.
16099  If you need a different heap size you need to recompile _heap.c with the
16100  required size defined in HEAP_SIZE.
16101  It is recommended to make a copy of this file into your project directory
16102  and compile it there with:
16103 \layout Verse
16104
16105
16106 \family typewriter
16107 sdcc -c _heap.c -D HEAD_SIZE=2048
16108 \newline
16109
16110 \family default
16111 And then link it with:
16112 \layout Verse
16113
16114
16115 \family typewriter
16116 sdcc main.rel _heap.rel
16117 \newline
16118
16119 \layout Subsection
16120
16121 Math functions (sinf, powf, sqrtf etc.)
16122 \layout Subsubsection
16123
16124 <math.h>
16125 \layout Standard
16126
16127 See definitions in file <math.h>.
16128 \layout Subsection
16129
16130 Other libraries
16131 \layout Standard
16132
16133 Libraries
16134 \begin_inset LatexCommand \index{Libraries}
16135
16136 \end_inset
16137
16138  included in SDCC should have a license at least as liberal as the GNU Lesser
16139  General Public License
16140 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
16141
16142 \end_inset
16143
16144
16145 \emph on
16146 LGPL
16147 \emph default
16148 .
16149 \layout Comment
16150
16151 license statements for the libraries are missing.
16152  sdcc/device/lib/ser_ir.c
16153 \layout Comment
16154
16155 or _decdptr f.e.
16156  come with a GPL (as opposed to LGPL) License - this will not be liberal
16157  enough for many embedded programmers.
16158 \layout Standard
16159
16160 If you have ported some library or want to share experience about some code
16161  which f.e.
16162  falls into any of these categories Busses (I
16163 \begin_inset Formula $^{\textrm{2}}$
16164 \end_inset
16165
16166 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
16167  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
16168  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
16169 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
16170
16171 \end_inset
16172
16173 \SpecialChar ~
16174 would certainly like to hear about it.
16175 \layout Standard
16176 \added_space_bottom bigskip
16177 Programmers coding for embedded systems are not especially famous for being
16178  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
16179 e these references are very valuable.
16180  Let's help to create a climate where information is shared.
16181 \layout Section
16182
16183 Memory Models
16184 \layout Subsection
16185
16186 MCS51 Memory Models
16187 \begin_inset LatexCommand \index{Memory model}
16188
16189 \end_inset
16190
16191
16192 \begin_inset LatexCommand \index{MCS51 memory model}
16193
16194 \end_inset
16195
16196
16197 \layout Subsubsection
16198
16199 Small, Medium and Large
16200 \layout Standard
16201
16202 SDCC allows three memory models for MCS51 code,
16203 \shape slanted
16204 small, medium
16205 \shape default
16206  and
16207 \shape slanted
16208 large
16209 \shape default
16210 .
16211  Modules compiled with different memory models should
16212 \emph on
16213 never
16214 \emph default
16215  be combined together or the results would be unpredictable.
16216  The library routines supplied with the compiler are compiled as small,
16217  medium and large.
16218  The compiled library modules are contained in separate directories as small,
16219  medium and large so that you can link to the appropriate set.
16220 \layout Standard
16221
16222 When the medium or large model is used all variables declared without a
16223  storage class will be allocated into the external ram, this includes all
16224  parameters and local variables (for non-reentrant
16225 \begin_inset LatexCommand \index{reentrant}
16226
16227 \end_inset
16228
16229  functions).
16230  When the small model is used variables without storage class are allocated
16231  in the internal ram.
16232 \layout Standard
16233
16234 Judicious usage of the processor specific storage classes
16235 \begin_inset LatexCommand \index{Storage class}
16236
16237 \end_inset
16238
16239  and the 'reentrant' function type will yield much more efficient code,
16240  than using the large model.
16241  Several optimizations are disabled when the program is compiled using the
16242  large model, it is therefore recommended that the small model be used unless
16243  absolutely required.
16244 \layout Subsubsection
16245
16246 External Stack
16247 \begin_inset LatexCommand \label{sub:External-Stack}
16248
16249 \end_inset
16250
16251
16252 \begin_inset LatexCommand \index{stack}
16253
16254 \end_inset
16255
16256
16257 \begin_inset LatexCommand \index{External stack (mcs51)}
16258
16259 \end_inset
16260
16261
16262 \layout Standard
16263
16264 The external stack (-
16265 \begin_inset ERT
16266 status Collapsed
16267
16268 \layout Standard
16269
16270 \backslash
16271 /
16272 \end_inset
16273
16274 -xstack option
16275 \begin_inset LatexCommand \index{-\/-xstack}
16276
16277 \end_inset
16278
16279 ) is located in pdata
16280 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
16281
16282 \end_inset
16283
16284  memory (usually at the start of the external ram segment) and uses all
16285  unused space in pdata (max.
16286  256 bytes).
16287  When -
16288 \begin_inset ERT
16289 status Collapsed
16290
16291 \layout Standard
16292
16293 \backslash
16294 /
16295 \end_inset
16296
16297 -xstack option is used to compile the program, the parameters and local
16298  variables
16299 \begin_inset LatexCommand \index{local variables}
16300
16301 \end_inset
16302
16303  of all reentrant functions are allocated in this area.
16304  This option is provided for programs with large stack space requirements.
16305  When used with the -
16306 \begin_inset ERT
16307 status Collapsed
16308
16309 \layout Standard
16310
16311 \backslash
16312 /
16313 \end_inset
16314
16315 -stack-auto
16316 \begin_inset LatexCommand \index{-\/-stack-auto}
16317
16318 \end_inset
16319
16320  option, all parameters and local variables are allocated on the external
16321  stack (note: support libraries will need to be recompiled with the same
16322  options.
16323  There is a predefined target in the library makefile).
16324 \layout Standard
16325
16326 The compiler outputs the higher order address byte of the external ram segment
16327  into port P2
16328 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
16329
16330 \end_inset
16331
16332  (see also section
16333 \begin_inset LatexCommand \ref{sub:MCS51-variants}
16334
16335 \end_inset
16336
16337 ), therefore when using the External Stack option, this port
16338 \emph on
16339 may not
16340 \emph default
16341  be used by the application program.
16342 \layout Subsection
16343
16344 DS390 Memory Model
16345 \begin_inset LatexCommand \index{Memory model}
16346
16347 \end_inset
16348
16349
16350 \begin_inset LatexCommand \index{DS390 memory model}
16351
16352 \end_inset
16353
16354
16355 \layout Standard
16356
16357 The only model supported is Flat 24
16358 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
16359
16360 \end_inset
16361
16362 .
16363  This generates code for the 24 bit contiguous addressing mode of the Dallas
16364  DS80C390 part.
16365  In this mode, up to four meg of external RAM or code space can be directly
16366  addressed.
16367  See the data sheets at www.dalsemi.com for further information on this part.
16368 \newline
16369
16370 \newline
16371 Note that the compiler does not generate any code to place the processor
16372  into 24 bitmode (although
16373 \emph on
16374 tinibios
16375 \emph default
16376  in the ds390 libraries will do that for you).
16377  If you don't use
16378 \emph on
16379 tinibios
16380 \emph default
16381
16382 \begin_inset LatexCommand \index{Tinibios (DS390)}
16383
16384 \end_inset
16385
16386 , the boot loader or similar code must ensure that the processor is in 24
16387  bit contiguous addressing mode before calling the SDCC startup code.
16388 \newline
16389
16390 \newline
16391 Like the
16392 \emph on
16393 -
16394 \begin_inset ERT
16395 status Collapsed
16396
16397 \layout Standard
16398
16399 \backslash
16400 /
16401 \end_inset
16402
16403 -model-large
16404 \emph default
16405  option, variables will by default be placed into the XDATA segment.
16406
16407 \newline
16408
16409 \newline
16410 Segments may be placed anywhere in the 4 meg address space using the usual
16411  -
16412 \begin_inset ERT
16413 status Collapsed
16414
16415 \layout Standard
16416
16417 \backslash
16418 /
16419 \end_inset
16420
16421 -*-loc options.
16422  Note that if any segments are located above 64K, the -r flag must be passed
16423  to the linker to generate the proper segment relocations, and the Intel
16424  HEX output format must be used.
16425  The -r flag can be passed to the linker by using the option
16426 \emph on
16427 -Wl-r
16428 \emph default
16429  on the SDCC command line.
16430  However, currently the linker can not handle code segments > 64k.
16431 \layout Section
16432
16433 Pragmas
16434 \begin_inset LatexCommand \label{sec:Pragmas}
16435
16436 \end_inset
16437
16438
16439 \begin_inset LatexCommand \index{Pragmas}
16440
16441 \end_inset
16442
16443
16444 \layout Standard
16445
16446 SDCC supports the following #pragma directives:
16447 \layout Itemize
16448
16449
16450 \series bold
16451 save
16452 \series default
16453
16454 \begin_inset LatexCommand \index{\#pragma save}
16455
16456 \end_inset
16457
16458  - this will save most current options to the save/restore stack.
16459  See #pragma\SpecialChar ~
16460 restore.
16461 \layout Itemize
16462
16463
16464 \series bold
16465 restore
16466 \series default
16467
16468 \begin_inset LatexCommand \index{\#pragma restore}
16469
16470 \end_inset
16471
16472  - will restore saved options from the last save.
16473  saves & restores can be nested.
16474  SDCC uses a save/restore stack: save pushes current options to the stack,
16475  restore pulls current options from the stack.
16476  See #pragma\SpecialChar ~
16477 save.
16478 \newline
16479
16480 \layout Itemize
16481
16482
16483 \series bold
16484 callee_saves
16485 \series default
16486
16487 \begin_inset LatexCommand \index{\#pragma callee\_saves}
16488
16489 \end_inset
16490
16491
16492 \begin_inset LatexCommand \index{function prologue}
16493
16494 \end_inset
16495
16496  function1[,function2[,function3...]] - The compiler by default uses a caller
16497  saves convention for register saving across function calls, however this
16498  can cause unnecessary register pushing & popping
16499 \begin_inset LatexCommand \index{push/pop}
16500
16501 \end_inset
16502
16503  when calling small functions from larger functions.
16504  This option can be used to switch off the register saving convention for
16505  the function names specified.
16506  The compiler will not save registers when calling these functions, extra
16507  code need to be manually inserted at the entry & exit for these functions
16508  to save & restore the registers used by these functions, this can SUBSTANTIALLY
16509  reduce code & improve run time performance of the generated code.
16510  In the future the compiler (with inter procedural analysis) may be able
16511  to determine the appropriate scheme to use for each function call.
16512  If -
16513 \begin_inset ERT
16514 status Collapsed
16515
16516 \layout Standard
16517
16518 \backslash
16519 /
16520 \end_inset
16521
16522 -callee-saves command line option is used, the function names specified
16523  in #pragma\SpecialChar ~
16524 callee_saves
16525 \begin_inset LatexCommand \index{\#pragma callee\_saves}
16526
16527 \end_inset
16528
16529  is appended to the list of functions specified in the command line.
16530 \layout Itemize
16531
16532
16533 \series bold
16534 exclude
16535 \series default
16536
16537 \begin_inset LatexCommand \index{\#pragma exclude}
16538
16539 \end_inset
16540
16541  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
16542  of pairs of push/pop
16543 \begin_inset LatexCommand \index{push/pop}
16544
16545 \end_inset
16546
16547  instructions in
16548 \emph on
16549 I
16550 \emph default
16551 nterrupt
16552 \begin_inset LatexCommand \index{interrupt}
16553
16554 \end_inset
16555
16556
16557 \emph on
16558 S
16559 \emph default
16560 ervice
16561 \emph on
16562 R
16563 \emph default
16564 outines.
16565  The directive should be placed immediately before the ISR function definition
16566  and it affects ALL ISR functions following it.
16567  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
16568 exclude\SpecialChar ~
16569 none
16570 \begin_inset LatexCommand \index{\#pragma exclude}
16571
16572 \end_inset
16573
16574 .
16575  See also the related keyword _naked
16576 \begin_inset LatexCommand \index{\_naked}
16577
16578 \end_inset
16579
16580
16581 \begin_inset LatexCommand \index{\_\_naked}
16582
16583 \end_inset
16584
16585 .
16586 \layout Itemize
16587
16588
16589 \series bold
16590 less_pedantic
16591 \series default
16592
16593 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
16594
16595 \end_inset
16596
16597  - the compiler will not warn you anymore for obvious mistakes, you'r on
16598  your own now ;-(
16599 \layout Itemize
16600
16601
16602 \series bold
16603 disable_warning
16604 \series default
16605  <nnnn>
16606 \begin_inset LatexCommand \index{\#pragma disable\_warning}
16607
16608 \end_inset
16609
16610  - the compiler will not warn you anymore about warning number <nnnn>.
16611 \layout Itemize
16612
16613
16614 \series bold
16615 nogcse
16616 \series default
16617
16618 \begin_inset LatexCommand \index{\#pragma nogcse}
16619
16620 \end_inset
16621
16622  - will stop global common subexpression elimination.
16623 \layout Itemize
16624
16625
16626 \series bold
16627 noinduction
16628 \series default
16629
16630 \begin_inset LatexCommand \index{\#pragma noinduction}
16631
16632 \end_inset
16633
16634  - will stop loop induction optimizations.
16635 \layout Itemize
16636
16637
16638 \series bold
16639 noinvariant
16640 \series default
16641
16642 \begin_inset LatexCommand \index{\#pragma noinvariant}
16643
16644 \end_inset
16645
16646  - will not do loop invariant optimizations.
16647  For more details see Loop Invariants in section
16648 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
16649
16650 \end_inset
16651
16652 .
16653 \layout Itemize
16654
16655
16656 \series bold
16657 noiv
16658 \series default
16659
16660 \begin_inset LatexCommand \index{\#pragma noiv}
16661
16662 \end_inset
16663
16664  - Do not generate interrupt
16665 \begin_inset LatexCommand \index{interrupt}
16666
16667 \end_inset
16668
16669  vector table
16670 \begin_inset LatexCommand \index{interrupt vector table}
16671
16672 \end_inset
16673
16674  entries for all ISR functions defined after the pragma.
16675  This is useful in cases where the interrupt vector table must be defined
16676  manually, or when there is a secondary, manually defined interrupt vector
16677  table (e.g.
16678  for the autovector feature of the Cypress EZ-USB FX2).
16679  More elegantly this can be achieved by obmitting the optional interrupt
16680  number after the interrupt keyword, see section
16681 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
16682
16683 \end_inset
16684
16685 \SpecialChar ~
16686 about interrupts.
16687 \layout Itemize
16688
16689
16690 \series bold
16691 nojtbound
16692 \series default
16693
16694 \begin_inset LatexCommand \index{\#pragma nojtbound}
16695
16696 \end_inset
16697
16698  - will not generate code for boundary value checking, when switch statements
16699  are turned into jump-tables (dangerous).
16700  For more details see section
16701 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
16702
16703 \end_inset
16704
16705 .
16706 \layout Itemize
16707
16708
16709 \series bold
16710 noloopreverse
16711 \series default
16712
16713 \begin_inset LatexCommand \index{\#pragma noloopreverse}
16714
16715 \end_inset
16716
16717  - Will not do loop reversal optimization
16718 \layout Itemize
16719
16720
16721 \series bold
16722 nooverlay
16723 \series default
16724
16725 \begin_inset LatexCommand \index{\#pragma nooverlay}
16726
16727 \end_inset
16728
16729  - the compiler will not overlay the parameters and local variables of a
16730  function.
16731 \layout Itemize
16732
16733
16734 \series bold
16735 stackauto
16736 \series default
16737
16738 \begin_inset LatexCommand \index{\#pragma stackauto}
16739
16740 \end_inset
16741
16742 - See option -
16743 \begin_inset ERT
16744 status Collapsed
16745
16746 \layout Standard
16747
16748 \backslash
16749 /
16750 \end_inset
16751
16752 -stack-auto
16753 \begin_inset LatexCommand \index{-\/-stack-auto}
16754
16755 \end_inset
16756
16757  and section
16758 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
16759
16760 \end_inset
16761
16762  Parameters and Local Variables.
16763 \layout Itemize
16764
16765
16766 \series bold
16767 opt_code_speed
16768 \series default
16769
16770 \begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
16771
16772 \end_inset
16773
16774 - The compiler will optimize code generation towards fast code, possibly
16775  at the expense of code size.
16776  Currently this has little effect.
16777 \layout Itemize
16778
16779
16780 \series bold
16781 opt_code_size
16782 \series default
16783
16784 \begin_inset LatexCommand \index{\#pragma opt\_code\_size}
16785
16786 \end_inset
16787
16788 - The compiler will optimize code generation towards compact code, possibly
16789  at the expense of code speed.
16790  Currently this has little effect.
16791 \layout Itemize
16792
16793
16794 \series bold
16795 opt_code_balanced
16796 \series default
16797
16798 \begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
16799
16800 \end_inset
16801
16802 - The compiler will attempt to generate code that is both compact and fast,
16803  as long as meeting one goal is not a detriment to the other (this is the
16804  default).
16805
16806 \layout Itemize
16807
16808
16809 \series bold
16810 std_sdcc89
16811 \series default
16812
16813 \begin_inset LatexCommand \index{\#pragma std\_sdcc89}
16814
16815 \end_inset
16816
16817 - Generally follow the C89 standard, but allow SDCC features that conflict
16818  with the standard (default).
16819 \layout Itemize
16820
16821
16822 \series bold
16823 std_c89
16824 \series default
16825
16826 \begin_inset LatexCommand \index{\#pragma std\_c89}
16827
16828 \end_inset
16829
16830 - Follow the C89 standard and disable SDCC features that conflict with the
16831  standard.
16832 \layout Itemize
16833
16834
16835 \series bold
16836 std_sdcc99
16837 \series default
16838
16839 \begin_inset LatexCommand \index{\#pragma std\_sdcc99}
16840
16841 \end_inset
16842
16843 - Generally follow the C99 standard, but allow SDCC features that conflict
16844  with the standard (incomplete support).
16845 \layout Itemize
16846
16847
16848 \series bold
16849 std_c99
16850 \series default
16851
16852 \begin_inset LatexCommand \index{\#pragma std\_c99}
16853
16854 \end_inset
16855
16856 - Follow the C99 standard and disable SDCC features that conflict with the
16857  standard (incomplete support).
16858 \layout Itemize
16859
16860
16861 \series bold
16862 codeseg
16863 \series default
16864  <name>
16865 \begin_inset LatexCommand \index{\#pragma codeseg}
16866
16867 \end_inset
16868
16869 - Use this name (max.
16870  8 characters) for the code segment.
16871  See option -
16872 \begin_inset ERT
16873 status Collapsed
16874
16875 \layout Standard
16876
16877 \backslash
16878 /
16879 \end_inset
16880
16881 -codeseg.
16882 \layout Itemize
16883
16884
16885 \series bold
16886 constseg
16887 \series default
16888  <name>
16889 \begin_inset LatexCommand \index{\#pragma constseg}
16890
16891 \end_inset
16892
16893 - Use this name (max.
16894  8 characters) for the const segment.
16895  See option -
16896 \begin_inset ERT
16897 status Collapsed
16898
16899 \layout Standard
16900
16901 \backslash
16902 /
16903 \end_inset
16904
16905 -constseg.
16906 \layout Standard
16907
16908 The preprocessor SDCPP
16909 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
16910
16911 \end_inset
16912
16913  supports the following #pragma directives:
16914 \layout Itemize
16915
16916
16917 \series bold
16918 pedantic_parse_number
16919 \series default
16920
16921 \begin_inset LatexCommand \index{\#pragma pedantic\_parse\_number}
16922
16923 \end_inset
16924
16925  (+ | -) - Pedantic parse numbers so that situations like 0xfe-LO_B(3) are
16926  parsed properly and the macro LO_B(3) gets expanded.
16927  Default is off.
16928  Below is an example on how to use this pragma.
16929
16930 \emph on
16931  Note: this functionality is not in conformance with standard!
16932
16933 \layout Verse
16934
16935
16936 \family typewriter
16937 #pragma pedantic_parse_number +
16938 \begin_inset LatexCommand \index{\#pragma pedantic\_parse\_number}
16939
16940 \end_inset
16941
16942
16943 \newline
16944 \newline
16945 #define LO_B(x) ((x) & 0xff)
16946 \newline
16947 \newline
16948 unsigned char foo(void)
16949 \newline
16950 \InsetSpace ~
16951 \InsetSpace ~
16952 \InsetSpace ~
16953 unsigned char c=0xfe-LO_B(3);
16954 \newline
16955 \newline
16956 \InsetSpace ~
16957 \InsetSpace ~
16958 \InsetSpace ~
16959
16960 return c;
16961 \newline
16962 }
16963 \newline
16964
16965 \layout Itemize
16966
16967
16968 \series bold
16969 preproc_asm
16970 \series default
16971
16972 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
16973
16974 \end_inset
16975
16976  (+ | -) - switch _asm _endasm block preprocessing on / off.
16977  Default is on.
16978  You use this prama to define multilines of assembly code.
16979  This will prevent the preprocessor from changing the formating required
16980  by assembly code.
16981  Below is an example on how to use this pragma.
16982 \layout Verse
16983
16984
16985 \family typewriter
16986 #pragma preproc_asm -
16987 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
16988
16989 \end_inset
16990
16991
16992 \newline
16993 #define MYDELAY _asm
16994 \newline
16995 \SpecialChar ~
16996 \SpecialChar ~
16997 \SpecialChar ~
16998 nop ;my assembly comment...
16999 \newline
17000 \SpecialChar ~
17001 \SpecialChar ~
17002 \SpecialChar ~
17003 nop
17004 \newline
17005 \SpecialChar ~
17006 \SpecialChar ~
17007 \SpecialChar ~
17008 nop
17009 \newline
17010 _endasm
17011 \newline
17012 #pragma preproc_asm +
17013 \newline
17014
17015 \newline
17016 void foo (void)
17017 \newline
17018 {
17019 \newline
17020 \SpecialChar ~
17021 \SpecialChar ~
17022 \SpecialChar ~
17023  ...
17024
17025 \newline
17026 \SpecialChar ~
17027 \SpecialChar ~
17028 \SpecialChar ~
17029  MYDELAY;
17030 \newline
17031 \SpecialChar ~
17032 \SpecialChar ~
17033 \SpecialChar ~
17034  ...
17035
17036 \newline
17037 }
17038 \newline
17039
17040 \layout Itemize
17041
17042
17043 \series bold
17044 sdcc_hash
17045 \series default
17046
17047 \begin_inset LatexCommand \index{\#pragma sdcc\_hash}
17048
17049 \end_inset
17050
17051  (+ | -) - Allow "naked" hash in macro definition, for example:
17052 \newline
17053 \family typewriter
17054 #define DIR_LO(x) #(x & 0xff)
17055 \family default
17056 \newline
17057 Default is off.
17058  Below is an example on how to use this pragma.
17059 \layout Verse
17060
17061
17062 \family typewriter
17063 #pragma preproc_asm +
17064 \newline
17065 #pragma sdcc_hash +
17066 \begin_inset LatexCommand \index{\#pragma sdcc\_hash}
17067
17068 \end_inset
17069
17070
17071 \newline
17072 \newline
17073 #define ROMCALL(x)
17074 \backslash
17075 \newline
17076 \InsetSpace ~
17077 \InsetSpace ~
17078 \InsetSpace ~
17079 mov R6_B3, #(x & 0xff)
17080 \backslash
17081 \newline
17082 \InsetSpace ~
17083 \InsetSpace ~
17084 \InsetSpace ~
17085 mov R7_B3, #((x >> 8) & 0xff)
17086 \backslash
17087 \newline
17088 \InsetSpace ~
17089 \InsetSpace ~
17090 \InsetSpace ~
17091 lcall __romcall
17092 \newline
17093 \newline
17094 ...
17095 \newline
17096 _asm
17097 \newline
17098 ROMCALL(72)
17099 \newline
17100 _endasm;
17101 \newline
17102 ...
17103 \newline
17104
17105 \layout Standard
17106
17107 The pragma's are intended to be used to turn-on or off certain optimizations
17108  which might cause the compiler to generate extra stack / data space to
17109  store compiler generated temporary variables.
17110  This usually happens in large functions.
17111  Pragma directives should be used as shown in the following example, they
17112  are used to control options & optimizations for a given function; pragmas
17113  should be placed before and/or after a function, placing pragma's inside
17114  a function body could have unpredictable results.
17115 \layout Verse
17116
17117
17118 \family typewriter
17119 #pragma save
17120 \begin_inset LatexCommand \index{\#pragma save}
17121
17122 \end_inset
17123
17124  \SpecialChar ~
17125 \SpecialChar ~
17126 \SpecialChar ~
17127 \SpecialChar ~
17128 \SpecialChar ~
17129 \SpecialChar ~
17130 \SpecialChar ~
17131 /* save the current settings */
17132 \newline
17133 #pragma nogcse
17134 \begin_inset LatexCommand \index{\#pragma nogcse}
17135
17136 \end_inset
17137
17138  \SpecialChar ~
17139 \SpecialChar ~
17140 \SpecialChar ~
17141 \SpecialChar ~
17142 \SpecialChar ~
17143 /* turnoff global subexpression elimination */
17144 \newline
17145 #pragma noinduction
17146 \begin_inset LatexCommand \index{\#pragma noinduction}
17147
17148 \end_inset
17149
17150  /* turn off induction optimizations */
17151 \newline
17152 int foo ()
17153 \newline
17154 {
17155 \newline
17156 \SpecialChar ~
17157  \SpecialChar ~
17158  ...
17159
17160 \newline
17161 \SpecialChar ~
17162  \SpecialChar ~
17163  /* large code */
17164 \newline
17165 \SpecialChar ~
17166  \SpecialChar ~
17167  ...
17168
17169 \newline
17170 }
17171 \newline
17172 #pragma restore
17173 \begin_inset LatexCommand \index{\#pragma restore}
17174
17175 \end_inset
17176
17177  /* turn the optimizations back on */
17178 \layout Standard
17179
17180 The compiler will generate a warning message when extra space is allocated.
17181  It is strongly recommended that the save and restore pragma's be used when
17182  changing options for a function.
17183 \newline
17184
17185 \newline
17186
17187 \newline
17188
17189 \layout Section
17190
17191 Defines Created by the Compiler
17192 \layout Standard
17193
17194 The compiler creates the following #defines
17195 \begin_inset LatexCommand \index{\#defines}
17196
17197 \end_inset
17198
17199
17200 \begin_inset LatexCommand \index{Defines created by the compiler}
17201
17202 \end_inset
17203
17204 :
17205 \newline
17206
17207 \layout Standard
17208
17209
17210 \begin_inset  Tabular
17211 <lyxtabular version="3" rows="11" columns="2">
17212 <features>
17213 <column alignment="left" valignment="top" leftline="true" width="3in">
17214 <column alignment="left" valignment="top" leftline="true" rightline="true" width="3in">
17215 <row topline="true" bottomline="true">
17216 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17217 \begin_inset Text
17218
17219 \layout Standard
17220
17221
17222 \series bold
17223 #define
17224 \end_inset
17225 </cell>
17226 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17227 \begin_inset Text
17228
17229 \layout Standard
17230
17231
17232 \series bold
17233 Description
17234 \end_inset
17235 </cell>
17236 </row>
17237 <row topline="true">
17238 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17239 \begin_inset Text
17240
17241 \layout Standard
17242
17243 SDCC
17244 \begin_inset LatexCommand \index{SDCC}
17245
17246 \end_inset
17247
17248
17249 \end_inset
17250 </cell>
17251 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17252 \begin_inset Text
17253
17254 \layout Standard
17255
17256 Always defined.
17257  Since version 2.5.6 the version number as an int (ex.
17258  256)
17259 \end_inset
17260 </cell>
17261 </row>
17262 <row topline="true">
17263 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17264 \begin_inset Text
17265
17266 \layout Standard
17267
17268 SDCC_mcs51
17269 \begin_inset LatexCommand \index{SDCC\_mcs51}
17270
17271 \end_inset
17272
17273  or SDCC_ds390
17274 \begin_inset LatexCommand \index{SDCC\_ds390}
17275
17276 \end_inset
17277
17278  or SDCC_z80
17279 \begin_inset LatexCommand \index{SDCC\_z80}
17280
17281 \end_inset
17282
17283 , etc.
17284 \end_inset
17285 </cell>
17286 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17287 \begin_inset Text
17288
17289 \layout Standard
17290
17291 depending on the model used (e.g.: -mds390)
17292 \end_inset
17293 </cell>
17294 </row>
17295 <row topline="true">
17296 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17297 \begin_inset Text
17298
17299 \layout Standard
17300
17301 __mcs51
17302 \begin_inset LatexCommand \index{\_\_mcs51}
17303
17304 \end_inset
17305
17306 , __ds390
17307 \begin_inset LatexCommand \index{\_\_ds390}
17308
17309 \end_inset
17310
17311 , __hc08
17312 \begin_inset LatexCommand \index{\_\_hc08}
17313
17314 \end_inset
17315
17316 , __z80
17317 \begin_inset LatexCommand \index{\_\_z80}
17318
17319 \end_inset
17320
17321 , etc
17322 \end_inset
17323 </cell>
17324 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17325 \begin_inset Text
17326
17327 \layout Standard
17328
17329 depending on the model used (e.g.
17330  -mz80)
17331 \end_inset
17332 </cell>
17333 </row>
17334 <row topline="true">
17335 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17336 \begin_inset Text
17337
17338 \layout Standard
17339
17340 SDCC_STACK_AUTO
17341 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
17342
17343 \end_inset
17344
17345
17346 \end_inset
17347 </cell>
17348 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17349 \begin_inset Text
17350
17351 \layout Standard
17352
17353 when
17354 \emph on
17355 -
17356 \begin_inset ERT
17357 status Collapsed
17358
17359 \layout Standard
17360
17361 \backslash
17362 /
17363 \end_inset
17364
17365 -stack-auto
17366 \emph default
17367  option is used
17368 \end_inset
17369 </cell>
17370 </row>
17371 <row topline="true">
17372 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17373 \begin_inset Text
17374
17375 \layout Standard
17376
17377 SDCC_MODEL_SMALL
17378 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
17379
17380 \end_inset
17381
17382
17383 \end_inset
17384 </cell>
17385 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17386 \begin_inset Text
17387
17388 \layout Standard
17389
17390 when
17391 \emph on
17392 -
17393 \begin_inset ERT
17394 status Collapsed
17395
17396 \layout Standard
17397
17398 \backslash
17399 /
17400 \end_inset
17401
17402 -model-small
17403 \emph default
17404  is used
17405 \end_inset
17406 </cell>
17407 </row>
17408 <row topline="true">
17409 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17410 \begin_inset Text
17411
17412 \layout Standard
17413
17414 SDCC_MODEL_MEDIUM
17415 \begin_inset LatexCommand \index{SDCC\_MODEL\_MEDIUM}
17416
17417 \end_inset
17418
17419
17420 \end_inset
17421 </cell>
17422 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17423 \begin_inset Text
17424
17425 \layout Standard
17426
17427 when
17428 \emph on
17429 -
17430 \begin_inset ERT
17431 status Collapsed
17432
17433 \layout Standard
17434
17435 \backslash
17436 /
17437 \end_inset
17438
17439 -model-medium
17440 \emph default
17441  is used
17442 \end_inset
17443 </cell>
17444 </row>
17445 <row topline="true">
17446 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17447 \begin_inset Text
17448
17449 \layout Standard
17450
17451 SDCC_MODEL_LARGE
17452 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
17453
17454 \end_inset
17455
17456
17457 \end_inset
17458 </cell>
17459 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17460 \begin_inset Text
17461
17462 \layout Standard
17463
17464 when
17465 \emph on
17466 -
17467 \begin_inset ERT
17468 status Collapsed
17469
17470 \layout Standard
17471
17472 \backslash
17473 /
17474 \end_inset
17475
17476 -model-large
17477 \emph default
17478  is used
17479 \end_inset
17480 </cell>
17481 </row>
17482 <row topline="true">
17483 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17484 \begin_inset Text
17485
17486 \layout Standard
17487
17488 SDCC_USE_XSTACK
17489 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
17490
17491 \end_inset
17492
17493
17494 \end_inset
17495 </cell>
17496 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17497 \begin_inset Text
17498
17499 \layout Standard
17500
17501 when
17502 \emph on
17503 -
17504 \begin_inset ERT
17505 status Collapsed
17506
17507 \layout Standard
17508
17509 \backslash
17510 /
17511 \end_inset
17512
17513 -xstack
17514 \emph default
17515  option is used
17516 \end_inset
17517 </cell>
17518 </row>
17519 <row topline="true">
17520 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17521 \begin_inset Text
17522
17523 \layout Standard
17524
17525 SDCC_STACK_TENBIT
17526 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
17527
17528 \end_inset
17529
17530
17531 \end_inset
17532 </cell>
17533 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17534 \begin_inset Text
17535
17536 \layout Standard
17537
17538 when
17539 \emph on
17540 -mds390
17541 \emph default
17542  is used
17543 \end_inset
17544 </cell>
17545 </row>
17546 <row topline="true" bottomline="true">
17547 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17548 \begin_inset Text
17549
17550 \layout Standard
17551
17552 SDCC_MODEL_FLAT24
17553 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
17554
17555 \end_inset
17556
17557
17558 \end_inset
17559 </cell>
17560 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17561 \begin_inset Text
17562
17563 \layout Standard
17564
17565 when
17566 \emph on
17567 -mds390
17568 \emph default
17569  is used
17570 \end_inset
17571 </cell>
17572 </row>
17573 </lyxtabular>
17574
17575 \end_inset
17576
17577
17578 \layout Chapter
17579
17580 Notes on supported Processors
17581 \layout Section
17582
17583 MCS51 variants
17584 \begin_inset LatexCommand \label{sub:MCS51-variants}
17585
17586 \end_inset
17587
17588
17589 \begin_inset LatexCommand \index{MCS51 variants}
17590
17591 \end_inset
17592
17593
17594 \layout Standard
17595
17596 MCS51 processors are available from many vendors and come in many different
17597  flavours.
17598  While they might differ considerably in respect to Special Function Registers
17599  the core MCS51 is usually not modified or is kept compatible.
17600
17601 \layout Subsection
17602
17603 pdata access by SFR
17604 \layout Standard
17605
17606 With the upcome of devices with internal xdata and flash memory devices
17607  using port P2
17608 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
17609
17610 \end_inset
17611
17612  as dedicated I/O port is becoming more popular.
17613  Switching the high byte for pdata
17614 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
17615
17616 \end_inset
17617
17618  access which was formerly done by port P2 is then achieved by a Special
17619  Function Register
17620 \begin_inset LatexCommand \index{sfr}
17621
17622 \end_inset
17623
17624 .
17625  In well-established MCS51 tradition the address of this
17626 \emph on
17627 sfr
17628 \emph default
17629  is where the chip designers decided to put it.
17630  Needless to say that they didn't agree on a common name either.
17631  So that the startup code can correctly initialize xdata variables, you
17632  should define an sfr with the name _XPAGE
17633 \family typewriter
17634
17635 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
17636
17637 \end_inset
17638
17639
17640 \family default
17641  at the appropriate location if the default, port P2, is not used for this.
17642  Some examples are:
17643 \layout Verse
17644
17645
17646 \family typewriter
17647 __sfr __at (0x92) _XPAGE; /* Cypress EZ-USB family */
17648 \layout Verse
17649
17650
17651 \family typewriter
17652 __sfr __at (0xaf) _XPAGE; /* some Silicon Labs (Cygnal) chips */
17653 \layout Verse
17654
17655
17656 \family typewriter
17657 __sfr __at (0xaa) _XPAGE; /* some Silicon Labs (Cygnal) chips */
17658 \layout Standard
17659
17660 For more exotic implementations further customizations may be needed.
17661  See section
17662 \begin_inset LatexCommand \ref{sub:Startup-Code}
17663
17664 \end_inset
17665
17666  for other possibilities.
17667 \layout Subsection
17668
17669 Other Features available by SFR
17670 \layout Standard
17671 \added_space_bottom bigskip
17672 Some MCS51 variants offer features like Double DPTR
17673 \begin_inset LatexCommand \index{DPTR}
17674
17675 \end_inset
17676
17677 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
17678  These are currently not used for the MCS51 port.
17679  If you absolutely need them you can fall back to inline assembly or submit
17680  a patch to SDCC.
17681 \layout Section
17682
17683 DS400 port
17684 \layout Standard
17685 \added_space_bottom bigskip
17686 The DS80C400
17687 \begin_inset LatexCommand \index{DS80C400}
17688
17689 \end_inset
17690
17691
17692 \begin_inset LatexCommand \index{DS400}
17693
17694 \end_inset
17695
17696  microcontroller has a rich set of peripherals.
17697  In its built-in ROM library it includes functions to access some of the
17698  features, among them is a TCP stack with IP4 and IP6 support.
17699  Library headers (currently in beta status) and other files are provided
17700  at
17701 \size footnotesize
17702
17703 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
17704
17705 \end_inset
17706
17707 .
17708
17709 \layout Section
17710
17711 The Z80 and gbz80 port
17712 \layout Standard
17713
17714 SDCC can target both the Zilog Z80
17715 \begin_inset LatexCommand \index{Z80}
17716
17717 \end_inset
17718
17719  and the Nintendo Gameboy's Z80-like gbz80
17720 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
17721
17722 \end_inset
17723
17724 .
17725  The Z80 port is passed through the same
17726 \emph on
17727 regressions tests
17728 \begin_inset LatexCommand \index{Regression test}
17729
17730 \end_inset
17731
17732
17733 \emph default
17734  (see section
17735 \begin_inset LatexCommand \ref{sec:Quality-control}
17736
17737 \end_inset
17738
17739 ) as the MCS51 and DS390 ports, so floating point support, support for long
17740  variables and bitfield support is fine.
17741  See mailing lists and forums about interrupt routines.
17742 \layout Standard
17743 \added_space_bottom bigskip
17744 As always, the code is the authoritative reference - see z80/ralloc.c and
17745  z80/gen.c.
17746  The stack
17747 \begin_inset LatexCommand \index{Z80!stack}
17748
17749 \end_inset
17750
17751  frame is similar to that generated by the IAR Z80 compiler.
17752  IX is used as the base pointer, HL and IY are used as a temporary registers,
17753  and BC and DE are available for holding variables.
17754  Return values
17755 \begin_inset LatexCommand \index{Z80!return value}
17756
17757 \end_inset
17758
17759  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
17760  bytes).
17761  The gbz80 port use the same set of registers for the return values, but
17762  in a different order of significance: E (one byte), DE (two bytes), or
17763  HLDE (four bytes).
17764 \layout Section
17765
17766 The HC08 port
17767 \layout Standard
17768
17769 The port to the Freescale/Motorola HC08
17770 \begin_inset LatexCommand \index{HC08}
17771
17772 \end_inset
17773
17774  family has been added in October 2003, and is still undergoing some basic
17775  development.
17776  The code generator is complete, but the register allocation is still quite
17777  unoptimized.
17778  Some of the SDCC's standard C library functions have embedded non-HC08
17779  inline assembly and so are not yet usable.
17780 \layout Standard
17781 \added_space_bottom bigskip
17782 The HC08 port passes the regression test suite (see section
17783 \begin_inset LatexCommand \ref{sec:Quality-control}
17784
17785 \end_inset
17786
17787 ).
17788 \layout Section
17789 \pagebreak_top
17790 The PIC14 port
17791 \layout Standard
17792
17793 The 14bit PIC
17794 \begin_inset LatexCommand \index{PIC14}
17795
17796 \end_inset
17797
17798  port still requires a major effort from the development community.
17799  However it can work for simple code.
17800  It passes its (smaller set of) regression tests
17801 \begin_inset LatexCommand \index{Regression test (PIC14)}
17802
17803 \end_inset
17804
17805  in the directory
17806 \shape italic
17807 sdcc/src/regression
17808 \shape default
17809 .
17810 \layout Subsection
17811
17812 C code and 14bit PIC code page
17813 \begin_inset LatexCommand \index{code page (pic14)}
17814
17815 \end_inset
17816
17817  and RAM banks
17818 \begin_inset LatexCommand \index{RAM bank (pic14)}
17819
17820 \end_inset
17821
17822
17823 \layout Standard
17824
17825 The linker organizes allocation for the code page and RAM banks.
17826  It does not have intimate knowledge of the code flow.
17827  It will put all the code section of a single asm file into a single code
17828  page.
17829  In order to make use of multiple code pages, separate asm files must be
17830  used.
17831  The compiler treats all functions of a single C file as being in the same
17832  code page unless it is non static.
17833  The compiler treats all local variables of a single C file as being in
17834  the same RAM bank unless it is an extern.
17835 \newline
17836
17837 \newline
17838 To get the best follow these guide lines:
17839 \layout Enumerate
17840
17841 make local functions static, as non static functions require code page selection
17842  overhead.
17843 \layout Enumerate
17844
17845 Make local variables static as extern variables require RAM bank selection
17846  overhead.
17847 \layout Enumerate
17848
17849 For devices that have multiple code pages it is more efficient to use the
17850  same number of files as pages, i.e.
17851  for the 16F877 use 4 separate files and i.e.
17852  for the 16F874 use 2 separate files.
17853  This way the linker can put the code for each file into different code
17854  pages and the compiler can allocate reusable variables more efficiently
17855  and there's less page selection overhead.
17856  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
17857  instruction set) use 'unsigned char' whereever possible instead of 'int'.
17858 \layout Subsection
17859
17860 Creating a device include file
17861 \layout Standard
17862
17863 For generating a device include file
17864 \begin_inset LatexCommand \index{PIC14!Header files}
17865
17866 \end_inset
17867
17868  use the support perl script inc2h.pl kept in directory support/script.
17869 \layout Subsection
17870
17871 Interrupt code
17872 \layout Standard
17873
17874 For the interrupt function, use the keyword 'interrupt'
17875 \begin_inset LatexCommand \index{PIC14!interrupt}
17876
17877 \end_inset
17878
17879  with level number of 0 (PIC14 only has 1 interrupt so this number is only
17880  there to avoid a syntax error - it ought to be fixed).
17881  E.g.:
17882 \layout Verse
17883
17884
17885 \family typewriter
17886 void Intr(void) interrupt 0
17887 \newline
17888 {
17889 \newline
17890 \SpecialChar ~
17891 \SpecialChar ~
17892 T0IF = 0; /* Clear timer interrupt */
17893 \newline
17894 }
17895 \layout Subsection
17896
17897 Linking and assembling
17898 \layout Standard
17899
17900 For assembling you can use either GPUTILS'
17901 \begin_inset LatexCommand \index{gputils (pic tools)}
17902
17903 \end_inset
17904
17905  gpasm.exe or MPLAB's mpasmwin.exe.
17906  GPUTILS is available from
17907 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
17908
17909 \end_inset
17910
17911 .
17912  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
17913  If you use MPLAB and an interrupt function then the linker script file
17914  vectors section will need to be enlarged to link with mplink.
17915 \newline
17916
17917 \newline
17918 Here is a
17919 \family typewriter
17920 Makefile
17921 \family default
17922  using GPUTILS:
17923 \layout Verse
17924
17925
17926 \family typewriter
17927 .c.o:
17928 \newline
17929 \SpecialChar ~
17930 \SpecialChar ~
17931 \SpecialChar ~
17932 \SpecialChar ~
17933 \SpecialChar ~
17934 \SpecialChar ~
17935 \SpecialChar ~
17936 \SpecialChar ~
17937 sdcc -S -V -mpic14 -p16F877 $<
17938 \newline
17939 \SpecialChar ~
17940 \SpecialChar ~
17941 \SpecialChar ~
17942 \SpecialChar ~
17943 \SpecialChar ~
17944 \SpecialChar ~
17945 \SpecialChar ~
17946 \SpecialChar ~
17947 gpasm -c $*.asm
17948 \newline
17949
17950 \newline
17951 $(PRJ).hex: $(OBJS)
17952 \newline
17953 \SpecialChar ~
17954 \SpecialChar ~
17955 \SpecialChar ~
17956 \SpecialChar ~
17957 \SpecialChar ~
17958 \SpecialChar ~
17959 \SpecialChar ~
17960 \SpecialChar ~
17961 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS) libsdcc.lib
17962 \layout Standard
17963
17964 Here is a
17965 \family typewriter
17966 Makefile
17967 \family default
17968  using MPLAB:
17969 \layout Verse
17970
17971
17972 \family typewriter
17973 .c.o:
17974 \newline
17975 \SpecialChar ~
17976 \SpecialChar ~
17977 \SpecialChar ~
17978 \SpecialChar ~
17979 \SpecialChar ~
17980 \SpecialChar ~
17981 \SpecialChar ~
17982 \SpecialChar ~
17983 sdcc -S -V -mpic14 -p16F877 $<
17984 \newline
17985 \SpecialChar ~
17986 \SpecialChar ~
17987 \SpecialChar ~
17988 \SpecialChar ~
17989 \SpecialChar ~
17990 \SpecialChar ~
17991 \SpecialChar ~
17992 \SpecialChar ~
17993 mpasmwin /q /o $*.asm
17994 \newline
17995
17996 \newline
17997 $(PRJ).hex: $(OBJS)
17998 \newline
17999 \SpecialChar ~
18000 \SpecialChar ~
18001 \SpecialChar ~
18002 \SpecialChar ~
18003 \SpecialChar ~
18004 \SpecialChar ~
18005 \SpecialChar ~
18006 \SpecialChar ~
18007 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS) libsdcc.lib
18008 \layout Standard
18009
18010 Please note that indentations within a
18011 \family typewriter
18012  Makefile
18013 \family default
18014  have to be done with a tabulator character.
18015 \layout Subsection
18016
18017 Command-line options
18018 \layout Standard
18019
18020 Besides the switches common to all SDCC backends, the PIC14 port accepts
18021  the following options (for an updated list see sdcc -
18022 \begin_inset ERT
18023 status Collapsed
18024
18025 \layout Standard
18026
18027 \backslash
18028 /
18029 \end_inset
18030
18031 -help):
18032 \layout List
18033 \labelwidthstring 00.00.0000
18034
18035 -
18036 \begin_inset ERT
18037 status Collapsed
18038
18039 \layout Standard
18040
18041 \backslash
18042 /
18043 \end_inset
18044
18045 -debug-extra
18046 \begin_inset LatexCommand \index{PIC14!Options!-\/-debug-extra}
18047
18048 \end_inset
18049
18050  emit debug info in assembly output
18051 \layout List
18052 \labelwidthstring 00.00.0000
18053
18054 -
18055 \begin_inset ERT
18056 status Collapsed
18057
18058 \layout Standard
18059
18060 \backslash
18061 /
18062 \end_inset
18063
18064 -no-pcode-opt
18065 \begin_inset LatexCommand \index{PIC14!Options!-\/-no-pcode-opt}
18066
18067 \end_inset
18068
18069  disable (slightly faulty) optimization on pCode
18070 \layout Subsection
18071
18072 The library
18073 \layout Subsubsection
18074
18075 error: missing definition for symbol
18076 \begin_inset Quotes sld
18077 \end_inset
18078
18079 __gptrget1
18080 \begin_inset Quotes srd
18081 \end_inset
18082
18083
18084 \layout Standard
18085
18086 The PIC14 port uses library routines to provide more complex operations
18087  like multiplication, division/modulus and (generic) pointer dereferencing.
18088  In order to add these routines to your project, you must link with PIC14's
18089
18090 \family typewriter
18091 libsdcc.lib
18092 \family default
18093 .
18094  For single source file projects this is done automatically, more complex
18095  projects must add
18096 \family typewriter
18097 libsdcc.lib
18098 \family default
18099  to the linker's arguments.
18100  Make sure you also add an include path for the library (using the -I switch
18101  to the linker)!
18102 \layout Subsubsection
18103
18104 Processor mismatch in file
18105 \begin_inset Quotes sld
18106 \end_inset
18107
18108 XXX
18109 \begin_inset Quotes srd
18110 \end_inset
18111
18112 .
18113 \layout Standard
18114
18115 This warning can usually be ignored due to the very good compatibility amongst
18116  14 bit PIC
18117 \begin_inset LatexCommand \index{PIC14}
18118
18119 \end_inset
18120
18121  devices.
18122 \layout Standard
18123
18124 You might also consider recompiling the library for your specific device
18125  by changing the ARCH=p16f877 (default target) entry in
18126 \family typewriter
18127 device/lib/pic/Makefile.in
18128 \family default
18129  and
18130 \family typewriter
18131 device/lib/pic/Makefile
18132 \family default
18133  to reflect your device.
18134  This might even improve performance for smaller devices as unneccesary
18135  BANKSELs migth be removed.
18136 \layout Subsection
18137
18138 Known bugs
18139 \layout Subsubsection
18140
18141 initialized data
18142 \layout Standard
18143
18144 Currently, data can only be initialized if it resides in the source file
18145  together with
18146 \emph on
18147 main()
18148 \emph default
18149 .
18150  Data in other source files will silently
18151 \series bold
18152 not
18153 \series default
18154  be initialized.
18155 \family typewriter
18156 \size footnotesize
18157
18158 \begin_inset Marginal
18159 collapsed true
18160
18161 \layout Standard
18162
18163
18164 \series bold
18165 \SpecialChar ~
18166 !
18167 \end_inset
18168
18169
18170 \layout Section
18171 \pagebreak_top
18172 The PIC16
18173 \begin_inset LatexCommand \index{PIC16}
18174
18175 \end_inset
18176
18177  port
18178 \layout Standard
18179
18180 The PIC16
18181 \begin_inset LatexCommand \index{PIC16}
18182
18183 \end_inset
18184
18185  port is the portion of SDCC that is responsible to produce code for the
18186  Microchip
18187 \begin_inset LatexCommand \index{Microchip}
18188
18189 \end_inset
18190
18191 (TM) microcontrollers with 16 bit core.
18192  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
18193  Currently supported devices are:
18194 \layout Standard
18195 \align center
18196
18197 \begin_inset  Tabular
18198 <lyxtabular version="3" rows="4" columns="6">
18199 <features>
18200 <column alignment="center" valignment="top" leftline="true" width="0">
18201 <column alignment="center" valignment="top" leftline="true" width="0">
18202 <column alignment="center" valignment="top" leftline="true" width="0">
18203 <column alignment="center" valignment="top" leftline="true" width="0">
18204 <column alignment="center" valignment="top" leftline="true" width="0">
18205 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18206 <row topline="true">
18207 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18208 \begin_inset Text
18209
18210 \layout Standard
18211
18212 18F242
18213 \end_inset
18214 </cell>
18215 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18216 \begin_inset Text
18217
18218 \layout Standard
18219
18220 18F248
18221 \end_inset
18222 </cell>
18223 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18224 \begin_inset Text
18225
18226 \layout Standard
18227
18228 18F252
18229 \end_inset
18230 </cell>
18231 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18232 \begin_inset Text
18233
18234 \layout Standard
18235
18236 18F258
18237 \end_inset
18238 </cell>
18239 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18240 \begin_inset Text
18241
18242 \layout Standard
18243
18244 18F442
18245 \end_inset
18246 </cell>
18247 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18248 \begin_inset Text
18249
18250 \layout Standard
18251
18252 18F448
18253 \end_inset
18254 </cell>
18255 </row>
18256 <row topline="true">
18257 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18258 \begin_inset Text
18259
18260 \layout Standard
18261
18262 18F452
18263 \end_inset
18264 </cell>
18265 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18266 \begin_inset Text
18267
18268 \layout Standard
18269
18270 18F458
18271 \end_inset
18272 </cell>
18273 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18274 \begin_inset Text
18275
18276 \layout Standard
18277
18278 18F1220
18279 \end_inset
18280 </cell>
18281 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18282 \begin_inset Text
18283
18284 \layout Standard
18285
18286 18F2220
18287 \end_inset
18288 </cell>
18289 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18290 \begin_inset Text
18291
18292 \layout Standard
18293
18294 18F2550
18295 \end_inset
18296 </cell>
18297 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18298 \begin_inset Text
18299
18300 \layout Standard
18301
18302 18F4331
18303 \end_inset
18304 </cell>
18305 </row>
18306 <row topline="true">
18307 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18308 \begin_inset Text
18309
18310 \layout Standard
18311
18312 18F4455
18313 \end_inset
18314 </cell>
18315 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18316 \begin_inset Text
18317
18318 \layout Standard
18319
18320 18F6520
18321 \end_inset
18322 </cell>
18323 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18324 \begin_inset Text
18325
18326 \layout Standard
18327
18328 18F6620
18329 \end_inset
18330 </cell>
18331 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18332 \begin_inset Text
18333
18334 \layout Standard
18335
18336 18F6680
18337 \end_inset
18338 </cell>
18339 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18340 \begin_inset Text
18341
18342 \layout Standard
18343
18344 18F6720
18345 \end_inset
18346 </cell>
18347 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18348 \begin_inset Text
18349
18350 \layout Standard
18351
18352 18F8520
18353 \end_inset
18354 </cell>
18355 </row>
18356 <row topline="true" bottomline="true">
18357 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18358 \begin_inset Text
18359
18360 \layout Standard
18361
18362 18F8620
18363 \end_inset
18364 </cell>
18365 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18366 \begin_inset Text
18367
18368 \layout Standard
18369
18370 18F8680
18371 \end_inset
18372 </cell>
18373 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18374 \begin_inset Text
18375
18376 \layout Standard
18377
18378 18F8720
18379 \end_inset
18380 </cell>
18381 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18382 \begin_inset Text
18383
18384 \layout Standard
18385
18386 \end_inset
18387 </cell>
18388 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18389 \begin_inset Text
18390
18391 \layout Standard
18392
18393 \end_inset
18394 </cell>
18395 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18396 \begin_inset Text
18397
18398 \layout Standard
18399
18400 \end_inset
18401 </cell>
18402 </row>
18403 </lyxtabular>
18404
18405 \end_inset
18406
18407
18408 \layout Subsection
18409
18410 Global Options
18411 \layout Standard
18412
18413 PIC16 port supports the standard command line arguments as supposed, with
18414  the exception of certain cases that will be mentioned in the following
18415  list:
18416 \layout List
18417 \labelwidthstring 00.00.0000
18418
18419 -
18420 \begin_inset ERT
18421 status Collapsed
18422
18423 \layout Standard
18424
18425 \backslash
18426 /
18427 \end_inset
18428
18429 -callee-saves
18430 \begin_inset LatexCommand \index{PIC16!Options!-\/-callee-saves}
18431
18432 \end_inset
18433
18434  See -
18435 \begin_inset ERT
18436 status Collapsed
18437
18438 \layout Standard
18439
18440 \backslash
18441 /
18442 \end_inset
18443
18444 -all-callee-saves
18445 \layout List
18446 \labelwidthstring 00.00.0000
18447
18448 -
18449 \begin_inset ERT
18450 status Collapsed
18451
18452 \layout Standard
18453
18454 \backslash
18455 /
18456 \end_inset
18457
18458 -all-callee-saves
18459 \begin_inset LatexCommand \index{PIC16!Options!-\/-all-callee-saves}
18460
18461 \end_inset
18462
18463  All function arguments are passed on stack by default.
18464
18465 \emph on
18466 There is no need to specify this in the command line.
18467 \layout List
18468 \labelwidthstring 00.00.0000
18469
18470 -
18471 \begin_inset ERT
18472 status Collapsed
18473
18474 \layout Standard
18475
18476 \backslash
18477 /
18478 \end_inset
18479
18480 -fommit-frame-pointer
18481 \begin_inset LatexCommand \index{PIC16!Options!-\/-fommit-frame-pointer}
18482
18483 \end_inset
18484
18485  Frame pointer will be omitted when the function uses no local variables.
18486 \layout Subsection
18487
18488 Port Specific Options
18489 \begin_inset LatexCommand \index{Options PIC16}
18490
18491 \end_inset
18492
18493
18494 \layout Standard
18495
18496 The port specific options appear after the global options in the sdcc --help
18497  output.
18498 \layout Subsubsection
18499
18500 General Options
18501 \layout Standard
18502
18503 General options enable certain port features and optimizations.
18504 \layout List
18505 \labelwidthstring 00.00.0000
18506
18507 -
18508 \begin_inset ERT
18509 status Collapsed
18510
18511 \layout Standard
18512
18513 \backslash
18514 /
18515 \end_inset
18516
18517 -stack-model=[model] Used in conjuction with the command above.
18518  Defines the stack model to be used, valid stack models are :
18519 \begin_deeper
18520 \layout List
18521 \labelwidthstring 00.00.0000
18522
18523
18524 \emph on
18525 small
18526 \emph default
18527  Selects small stack model.
18528  8 bit stack and frame pointers.
18529  Supports 256 bytes stack size.
18530 \layout List
18531 \labelwidthstring 00.00.0000
18532
18533
18534 \emph on
18535 large
18536 \emph default
18537  Selects large stack model.
18538  16 bit stack and frame pointers.
18539  Supports 65536 bytes stack size.
18540 \end_deeper
18541 \layout List
18542 \labelwidthstring 00.00.0000
18543
18544 -
18545 \begin_inset ERT
18546 status Collapsed
18547
18548 \layout Standard
18549
18550 \backslash
18551 /
18552 \end_inset
18553
18554 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
18555  unitialized data variables with [kword].
18556  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
18557 \layout List
18558 \labelwidthstring 00.00.0000
18559
18560 -
18561 \begin_inset ERT
18562 status Collapsed
18563
18564 \layout Standard
18565
18566 \backslash
18567 /
18568 \end_inset
18569
18570 -ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
18571  Useful for bootloaders.
18572 \layout List
18573 \labelwidthstring 00.00.0000
18574
18575 -
18576 \begin_inset ERT
18577 status Collapsed
18578
18579 \layout Standard
18580
18581 \backslash
18582 /
18583 \end_inset
18584
18585 -asm= sets the full path and name of an external assembler to call.
18586 \layout List
18587 \labelwidthstring 00.00.0000
18588
18589 -
18590 \begin_inset ERT
18591 status Collapsed
18592
18593 \layout Standard
18594
18595 \backslash
18596 /
18597 \end_inset
18598
18599 -link= sets the full path and name of an external linker to call.
18600 \layout List
18601 \labelwidthstring 00.00.0000
18602
18603 -
18604 \begin_inset ERT
18605 status Collapsed
18606
18607 \layout Standard
18608
18609 \backslash
18610 /
18611 \end_inset
18612
18613 -mplab-comp MPLAB
18614 \begin_inset LatexCommand \index{PIC16!MPLAB}
18615
18616 \end_inset
18617
18618  compatibility option.
18619  Currently only suppresses special gpasm directives.
18620 \layout Subsubsection
18621
18622 Optimization Options
18623 \layout List
18624 \labelwidthstring 00.00.0000
18625
18626 -
18627 \begin_inset ERT
18628 status Collapsed
18629
18630 \layout Standard
18631
18632 \backslash
18633 /
18634 \end_inset
18635
18636 -optimize-goto Try to use (conditional) BRA instead of GOTO
18637 \layout List
18638 \labelwidthstring 00.00.0000
18639
18640 -
18641 \begin_inset ERT
18642 status Collapsed
18643
18644 \layout Standard
18645
18646 \backslash
18647 /
18648 \end_inset
18649
18650 -optimize-cmp Try to optimize some compares.
18651 \layout List
18652 \labelwidthstring 00.00.0000
18653
18654 -
18655 \begin_inset ERT
18656 status Collapsed
18657
18658 \layout Standard
18659
18660 \backslash
18661 /
18662 \end_inset
18663
18664 -optimize-df Analyze the dataflow of the generated code and improve it.
18665 \layout List
18666 \labelwidthstring 00.00.0000
18667
18668 -
18669 \begin_inset ERT
18670 status Collapsed
18671
18672 \layout Standard
18673
18674 \backslash
18675 /
18676 \end_inset
18677
18678 -obanksel=nn Set optimization level for inserting BANKSELs.
18679 \newline
18680
18681 \begin_deeper
18682 \layout List
18683 \labelwidthstring 00.00.0000
18684
18685 0 no optimization
18686 \layout List
18687 \labelwidthstring 00.00.0000
18688
18689 1 checks previous used register and if it is the same then does not emit
18690  BANKSEL, accounts only for labels.
18691 \layout List
18692 \labelwidthstring 00.00.0000
18693
18694 2 tries to check the location of (even different) symbols and removes BANKSELs
18695  if they are in the same bank.
18696
18697 \newline
18698
18699 \emph on
18700 Important: There might be problems if the linker script has data sections
18701  across bank borders!
18702 \end_deeper
18703 \layout Subsubsection
18704
18705 Linking Options
18706 \layout List
18707 \labelwidthstring 00.00.0000
18708
18709 -
18710 \begin_inset ERT
18711 status Collapsed
18712
18713 \layout Standard
18714
18715 \backslash
18716 /
18717 \end_inset
18718
18719 -nodefaultlibs do not link default libraries when linking
18720 \layout List
18721 \labelwidthstring 00.00.0000
18722
18723 -
18724 \begin_inset ERT
18725 status Collapsed
18726
18727 \layout Standard
18728
18729 \backslash
18730 /
18731 \end_inset
18732
18733 -no-crt Don't link the default run-time modules
18734 \layout List
18735 \labelwidthstring 00.00.0000
18736
18737 -
18738 \begin_inset ERT
18739 status Collapsed
18740
18741 \layout Standard
18742
18743 \backslash
18744 /
18745 \end_inset
18746
18747 -use-crt= Use a custom run-time module instead of the defaults.
18748 \layout Subsubsection
18749
18750 Debugging Options
18751 \layout Standard
18752
18753 Debugging options enable extra debugging information in the output files.
18754 \layout List
18755 \labelwidthstring 00.00.0000
18756
18757 -
18758 \begin_inset ERT
18759 status Collapsed
18760
18761 \layout Standard
18762
18763 \backslash
18764 /
18765 \end_inset
18766
18767 -debug-xtra Similar to -
18768 \begin_inset ERT
18769 status Collapsed
18770
18771 \layout Standard
18772
18773 \backslash
18774 /
18775 \end_inset
18776
18777 -debug
18778 \begin_inset LatexCommand \index{-\/-debug}
18779
18780 \end_inset
18781
18782 , but dumps more information.
18783 \layout List
18784 \labelwidthstring 00.00.0000
18785
18786 -
18787 \begin_inset ERT
18788 status Collapsed
18789
18790 \layout Standard
18791
18792 \backslash
18793 /
18794 \end_inset
18795
18796 -debug-ralloc Force register allocator to dump <source>.d file with debugging
18797  information.
18798  <source> is the name of the file compiled.
18799 \layout List
18800 \labelwidthstring 00.00.0000
18801
18802 -
18803 \begin_inset ERT
18804 status Collapsed
18805
18806 \layout Standard
18807
18808 \backslash
18809 /
18810 \end_inset
18811
18812 -pcode-verbose Enable pcode debugging information in translation.
18813 \layout List
18814 \labelwidthstring 00.00.0000
18815
18816 -
18817 \begin_inset ERT
18818 status Collapsed
18819
18820 \layout Standard
18821
18822 \backslash
18823 /
18824 \end_inset
18825
18826 -denable-peeps Force the usage of peepholes.
18827  Use with care.
18828 \layout List
18829 \labelwidthstring 00.00.0000
18830
18831 -
18832 \begin_inset ERT
18833 status Collapsed
18834
18835 \layout Standard
18836
18837 \backslash
18838 /
18839 \end_inset
18840
18841 -gstack Trace push/pops for stack pointer overflow
18842 \layout List
18843 \labelwidthstring 00.00.0000
18844
18845 -
18846 \begin_inset ERT
18847 status Collapsed
18848
18849 \layout Standard
18850
18851 \backslash
18852 /
18853 \end_inset
18854
18855 -call-tree dump call tree in .calltree file
18856 \layout Subsection
18857
18858 Enviromental Variables
18859 \layout Standard
18860
18861 There is a number of enviromental variables that can be used when running
18862  SDCC to enable certain optimizations or force a specific program behaviour.
18863  these variables are primarily for debugging purposes so they can be enabled/dis
18864 abled at will.
18865 \layout Standard
18866
18867 Currently there is only two such variables available:
18868 \layout List
18869 \labelwidthstring 00.00.0000
18870
18871 OPTIMIZE_BITFIELD_POINTER_GET when this variable exists reading of structure
18872  bitfields is optimized by directly loading FSR0 with the address of the
18873  bitfield structure.
18874  Normally SDCC will cast the bitfield structure to a bitfield pointer and
18875  then load FSR0.
18876  This step saves data ram and code space for functions that perform heavy
18877  use of bitfields.
18878  (ie.
18879  80 bytes of code space are saved when compiling malloc.c with this option).
18880
18881 \layout List
18882 \labelwidthstring 00.00.0000
18883
18884 NO_REG_OPT do not perform pCode registers optimization.
18885  This should be used for debugging purposes.
18886  In some where bugs in the pcode optimizer are found, users can benefit
18887  from temporarily disabling the optimizer until the bug is fixed.
18888 \layout Subsection
18889
18890 Preprocessor Macros
18891 \layout Standard
18892
18893 PIC16
18894 \begin_inset LatexCommand \index{PIC16}
18895
18896 \end_inset
18897
18898  port defines the following preprocessor macros while translating a source.
18899 \layout Standard
18900 \align center
18901
18902 \begin_inset  Tabular
18903 <lyxtabular version="3" rows="6" columns="2">
18904 <features>
18905 <column alignment="center" valignment="top" leftline="true" width="0">
18906 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18907 <row topline="true" bottomline="true">
18908 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18909 \begin_inset Text
18910
18911 \layout Standard
18912
18913 Macro
18914 \end_inset
18915 </cell>
18916 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18917 \begin_inset Text
18918
18919 \layout Standard
18920
18921 Description
18922 \end_inset
18923 </cell>
18924 </row>
18925 <row topline="true">
18926 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18927 \begin_inset Text
18928
18929 \layout Standard
18930
18931 SDCC_pic16
18932 \end_inset
18933 </cell>
18934 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18935 \begin_inset Text
18936
18937 \layout Standard
18938
18939 Port identification
18940 \end_inset
18941 </cell>
18942 </row>
18943 <row topline="true">
18944 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18945 \begin_inset Text
18946
18947 \layout Standard
18948
18949 _
18950 \begin_inset ERT
18951 status Collapsed
18952
18953 \layout Standard
18954
18955 \backslash
18956 /
18957 \end_inset
18958
18959 _pic16
18960 \end_inset
18961 </cell>
18962 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18963 \begin_inset Text
18964
18965 \layout Standard
18966
18967 Port identification (same as above)
18968 \end_inset
18969 </cell>
18970 </row>
18971 <row topline="true">
18972 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18973 \begin_inset Text
18974
18975 \layout Standard
18976
18977 pic18fxxxx
18978 \end_inset
18979 </cell>
18980 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18981 \begin_inset Text
18982
18983 \layout Standard
18984
18985 MCU Identification.
18986
18987 \emph on
18988 xxxx
18989 \emph default
18990  is the microcontrol identification number, i.e.
18991  452, 6620, etc
18992 \end_inset
18993 </cell>
18994 </row>
18995 <row topline="true">
18996 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18997 \begin_inset Text
18998
18999 \layout Standard
19000
19001 _
19002 \begin_inset ERT
19003 status Collapsed
19004
19005 \layout Standard
19006
19007 \backslash
19008 /
19009 \end_inset
19010
19011 _18Fxxxx
19012 \end_inset
19013 </cell>
19014 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19015 \begin_inset Text
19016
19017 \layout Standard
19018
19019 MCU Identification (same as above)
19020 \end_inset
19021 </cell>
19022 </row>
19023 <row topline="true" bottomline="true">
19024 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19025 \begin_inset Text
19026
19027 \layout Standard
19028
19029 STACK_MODEL_nnn
19030 \end_inset
19031 </cell>
19032 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19033 \begin_inset Text
19034
19035 \layout Standard
19036
19037 nnn = SMALL or LARGE respectively according to the stack model used
19038 \end_inset
19039 </cell>
19040 </row>
19041 </lyxtabular>
19042
19043 \end_inset
19044
19045
19046 \layout Standard
19047
19048 In addition the following macros are defined when calling assembler:
19049 \layout Standard
19050 \align center
19051
19052 \begin_inset  Tabular
19053 <lyxtabular version="3" rows="4" columns="2">
19054 <features>
19055 <column alignment="center" valignment="top" leftline="true" width="0">
19056 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19057 <row topline="true" bottomline="true">
19058 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19059 \begin_inset Text
19060
19061 \layout Standard
19062
19063 Macro
19064 \end_inset
19065 </cell>
19066 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19067 \begin_inset Text
19068
19069 \layout Standard
19070
19071 Description
19072 \end_inset
19073 </cell>
19074 </row>
19075 <row topline="true">
19076 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19077 \begin_inset Text
19078
19079 \layout Standard
19080
19081 __18Fxxxx
19082 \end_inset
19083 </cell>
19084 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19085 \begin_inset Text
19086
19087 \layout Standard
19088
19089 MCU Identification.
19090
19091 \emph on
19092 xxxx
19093 \emph default
19094  is the microcontrol identification number, i.e.
19095  452, 6620, etc
19096 \end_inset
19097 </cell>
19098 </row>
19099 <row topline="true">
19100 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19101 \begin_inset Text
19102
19103 \layout Standard
19104
19105 SDCC_MODEL_nnn
19106 \end_inset
19107 </cell>
19108 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19109 \begin_inset Text
19110
19111 \layout Standard
19112
19113 nnn = SMALL or LARGE respectively according to the memory model used for
19114  SDCC
19115 \end_inset
19116 </cell>
19117 </row>
19118 <row topline="true" bottomline="true">
19119 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19120 \begin_inset Text
19121
19122 \layout Standard
19123
19124 STACK_MODEL_nnn
19125 \end_inset
19126 </cell>
19127 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19128 \begin_inset Text
19129
19130 \layout Standard
19131
19132 nnn = SMALL or LARGE respectively according to the stack model used
19133 \end_inset
19134 </cell>
19135 </row>
19136 </lyxtabular>
19137
19138 \end_inset
19139
19140
19141 \layout Subsection
19142
19143 Directories
19144 \layout Standard
19145
19146 PIC16
19147 \begin_inset LatexCommand \index{PIC16}
19148
19149 \end_inset
19150
19151  port uses the following directories for searching header files and libraries.
19152 \layout Standard
19153 \align center
19154
19155 \begin_inset  Tabular
19156 <lyxtabular version="3" rows="3" columns="4">
19157 <features>
19158 <column alignment="center" valignment="top" leftline="true" width="0">
19159 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19160 <column alignment="center" valignment="top" width="0">
19161 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19162 <row topline="true" bottomline="true">
19163 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19164 \begin_inset Text
19165
19166 \layout Standard
19167
19168 Directory
19169 \end_inset
19170 </cell>
19171 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19172 \begin_inset Text
19173
19174 \layout Standard
19175
19176 Description
19177 \end_inset
19178 </cell>
19179 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19180 \begin_inset Text
19181
19182 \layout Standard
19183
19184 Target
19185 \end_inset
19186 </cell>
19187 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19188 \begin_inset Text
19189
19190 \layout Standard
19191
19192 Command prefix
19193 \end_inset
19194 </cell>
19195 </row>
19196 <row topline="true">
19197 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19198 \begin_inset Text
19199
19200 \layout Standard
19201
19202 PREFIX/sdcc/include/pic16
19203 \end_inset
19204 </cell>
19205 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19206 \begin_inset Text
19207
19208 \layout Standard
19209
19210 PIC16 specific headers
19211 \end_inset
19212 </cell>
19213 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19214 \begin_inset Text
19215
19216 \layout Standard
19217
19218 Compiler
19219 \end_inset
19220 </cell>
19221 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19222 \begin_inset Text
19223
19224 \layout Standard
19225
19226 -I
19227 \end_inset
19228 </cell>
19229 </row>
19230 <row topline="true" bottomline="true">
19231 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19232 \begin_inset Text
19233
19234 \layout Standard
19235
19236 PREFIX/sdcc/lib/pic16
19237 \end_inset
19238 </cell>
19239 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19240 \begin_inset Text
19241
19242 \layout Standard
19243
19244 PIC16 specific libraries
19245 \end_inset
19246 </cell>
19247 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19248 \begin_inset Text
19249
19250 \layout Standard
19251
19252 Linker
19253 \end_inset
19254 </cell>
19255 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19256 \begin_inset Text
19257
19258 \layout Standard
19259
19260 -L
19261 \end_inset
19262 </cell>
19263 </row>
19264 </lyxtabular>
19265
19266 \end_inset
19267
19268
19269 \layout Subsection
19270
19271 Pragmas
19272 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
19273
19274 \end_inset
19275
19276
19277 \layout Standard
19278
19279 PIC16
19280 \begin_inset LatexCommand \index{PIC16}
19281
19282 \end_inset
19283
19284  port currently supports the following pragmas:
19285 \layout List
19286 \labelwidthstring 00.00.0000
19287
19288 stack
19289 \begin_inset LatexCommand \index{PIC16!Pragmas!\#pragma stack}
19290
19291 \end_inset
19292
19293  pragma stack
19294 \begin_inset LatexCommand \index{PIC16!stack}
19295
19296 \end_inset
19297
19298  forces the code generator to initialize the stack & frame pointers at a
19299  specific address.
19300  This is an adhoc solution for cases where no STACK directive is available
19301  in the linker script or gplink is not instructed to create a stack section.
19302 \newline
19303 The stack pragma should be used only once in a project.
19304  Multiple pragmas may result in indeterminate behaviour of the program.
19305 \begin_inset Foot
19306 collapsed false
19307
19308 \layout Standard
19309
19310 The old format (ie.
19311  #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
19312  cross page boundaries (or even exceed the available data RAM) and crash
19313  the program.
19314  Make sure that stack does not cross page boundaries when using the SMALL
19315  stack model.
19316 \end_inset
19317
19318
19319 \newline
19320 The format is as follows:
19321 \layout LyX-Code
19322
19323 #pragma stack bottom_address [stack_size]
19324 \layout Standard
19325
19326
19327 \emph on
19328 bottom_address
19329 \emph default
19330  is the lower bound of the stack section.
19331  The stack pointer initially will point at address (bottom_address+stack_size-1).
19332 \layout LyX-Code
19333
19334 Example:
19335 \layout LyX-Code
19336
19337 \layout LyX-Code
19338
19339 /* initializes stack of 100 bytes at RAM address 0x200 */
19340 \layout LyX-Code
19341
19342 #pragma stack 0x200 100
19343 \layout Standard
19344
19345 If the stack_size field is omitted then a stack is created with the default
19346  size of 64.
19347  This size might be enough for most programs, but its not enough for operations
19348  with deep function nesting or excessive stack usage.
19349 \layout List
19350 \labelwidthstring 00.00.0000
19351
19352 code
19353 \begin_inset LatexCommand \index{PIC16!Pragmas!\#pragma code}
19354
19355 \end_inset
19356
19357  place a function symbol at static FLASH address
19358 \layout LyX-Code
19359
19360 Example:
19361 \layout LyX-Code
19362
19363 \layout LyX-Code
19364
19365 /* place function test_func at 0x4000 */
19366 \layout LyX-Code
19367
19368 #pragma code test_func 0x4000
19369 \layout LyX-Code
19370
19371 \layout List
19372 \labelwidthstring 00.00.0000
19373
19374 library instructs the linker to use a library module.
19375 \newline
19376 Usage:
19377 \layout LyX-Code
19378
19379 #pragma library module_name
19380 \layout Standard
19381
19382
19383 \emph on
19384 module_name
19385 \emph default
19386  can be any library or object file (including its path).
19387  Note that there are four reserved keywords which have special meaning.
19388  These are:
19389 \layout Standard
19390 \align center
19391
19392 \begin_inset  Tabular
19393 <lyxtabular version="3" rows="6" columns="3">
19394 <features>
19395 <column alignment="center" valignment="top" leftline="true" width="0">
19396 <column alignment="block" valignment="top" leftline="true" width="20page%">
19397 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
19398 <row topline="true" bottomline="true">
19399 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19400 \begin_inset Text
19401
19402 \layout Standard
19403
19404 Keyword
19405 \end_inset
19406 </cell>
19407 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19408 \begin_inset Text
19409
19410 \layout Standard
19411
19412 Description
19413 \end_inset
19414 </cell>
19415 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19416 \begin_inset Text
19417
19418 \layout Standard
19419
19420 Module to link
19421 \end_inset
19422 </cell>
19423 </row>
19424 <row topline="true">
19425 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19426 \begin_inset Text
19427
19428 \layout Standard
19429
19430
19431 \series bold
19432 ignore
19433 \end_inset
19434 </cell>
19435 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19436 \begin_inset Text
19437
19438 \layout Standard
19439
19440 ignore all library pragmas
19441 \end_inset
19442 </cell>
19443 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19444 \begin_inset Text
19445
19446 \layout Standard
19447
19448
19449 \emph on
19450 (none)
19451 \end_inset
19452 </cell>
19453 </row>
19454 <row topline="true">
19455 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19456 \begin_inset Text
19457
19458 \layout Standard
19459
19460
19461 \series bold
19462 c
19463 \end_inset
19464 </cell>
19465 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19466 \begin_inset Text
19467
19468 \layout Standard
19469
19470 link the C library
19471 \end_inset
19472 </cell>
19473 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19474 \begin_inset Text
19475
19476 \layout Standard
19477
19478
19479 \emph on
19480 libc18f
19481 \emph default
19482 .lib
19483 \end_inset
19484 </cell>
19485 </row>
19486 <row topline="true">
19487 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19488 \begin_inset Text
19489
19490 \layout Standard
19491
19492
19493 \series bold
19494 math
19495 \end_inset
19496 </cell>
19497 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19498 \begin_inset Text
19499
19500 \layout Standard
19501
19502 link the Math libarary
19503 \end_inset
19504 </cell>
19505 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19506 \begin_inset Text
19507
19508 \layout Standard
19509
19510
19511 \emph on
19512 libm18f
19513 \emph default
19514 .lib
19515 \end_inset
19516 </cell>
19517 </row>
19518 <row topline="true">
19519 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19520 \begin_inset Text
19521
19522 \layout Standard
19523
19524
19525 \series bold
19526 io
19527 \end_inset
19528 </cell>
19529 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19530 \begin_inset Text
19531
19532 \layout Standard
19533
19534 link the I/O library
19535 \end_inset
19536 </cell>
19537 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19538 \begin_inset Text
19539
19540 \layout Standard
19541
19542
19543 \emph on
19544 libio18f*
19545 \emph default
19546 .lib
19547 \end_inset
19548 </cell>
19549 </row>
19550 <row topline="true" bottomline="true">
19551 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19552 \begin_inset Text
19553
19554 \layout Standard
19555
19556
19557 \series bold
19558 debug
19559 \end_inset
19560 </cell>
19561 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19562 \begin_inset Text
19563
19564 \layout Standard
19565
19566 link the debug library
19567 \end_inset
19568 </cell>
19569 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19570 \begin_inset Text
19571
19572 \layout Standard
19573
19574
19575 \emph on
19576 libdebug
19577 \emph default
19578 .lib
19579 \end_inset
19580 </cell>
19581 </row>
19582 </lyxtabular>
19583
19584 \end_inset
19585
19586
19587 \newline
19588 * is the device number, i.e.
19589  452 for PIC18F452 MCU.
19590 \layout Standard
19591
19592 This feature allows for linking with specific libraries withoug having to
19593  explicit name them in the command line.
19594  Note that the
19595 \noun on
19596 ignore
19597 \noun default
19598  keyword will reject all modules specified by the library pragma.
19599 \layout List
19600 \labelwidthstring 00.00.0000
19601
19602 udata pragma udata instructs the compiler to emit code so that linker will
19603  place a variable at a specific memory bank
19604 \layout LyX-Code
19605
19606 Example:
19607 \layout LyX-Code
19608
19609 \layout LyX-Code
19610
19611 /* places variable foo at bank2 */
19612 \layout LyX-Code
19613
19614 #pragma udata bank2 foo
19615 \layout LyX-Code
19616
19617 char foo;
19618 \layout Standard
19619
19620 In order for this pragma to work extra SECTION directives should be added
19621  in the .lkr script.
19622  In the following example a sample .lkr file is shown:
19623 \layout LyX-Code
19624
19625 \layout LyX-Code
19626
19627 // Sample linker script for the PIC18F452 processor
19628 \layout LyX-Code
19629
19630 LIBPATH .
19631 \layout LyX-Code
19632
19633 CODEPAGE   NAME=vectors    START=0x0            END=0x29           PROTECTED
19634 \layout LyX-Code
19635
19636 CODEPAGE   NAME=page       START=0x2A           END=0x7FFF
19637 \layout LyX-Code
19638
19639 CODEPAGE   NAME=idlocs     START=0x200000       END=0x200007       PROTECTED
19640 \layout LyX-Code
19641
19642 CODEPAGE   NAME=config     START=0x300000       END=0x30000D       PROTECTED
19643 \layout LyX-Code
19644
19645 CODEPAGE   NAME=devid      START=0x3FFFFE       END=0x3FFFFF       PROTECTED
19646 \layout LyX-Code
19647
19648 CODEPAGE   NAME=eedata     START=0xF00000       END=0xF000FF       PROTECTED
19649 \layout LyX-Code
19650
19651 ACCESSBANK NAME=accessram  START=0x0            END=0x7F
19652 \layout LyX-Code
19653
19654 \layout LyX-Code
19655
19656 DATABANK   NAME=gpr0       START=0x80           END=0xFF
19657 \layout LyX-Code
19658
19659 DATABANK   NAME=gpr1       START=0x100          END=0x1FF
19660 \layout LyX-Code
19661
19662 DATABANK   NAME=gpr2       START=0x200          END=0x2FF
19663 \layout LyX-Code
19664
19665 DATABANK   NAME=gpr3       START=0x300          END=0x3FF
19666 \layout LyX-Code
19667
19668 DATABANK   NAME=gpr4       START=0x400          END=0x4FF
19669 \layout LyX-Code
19670
19671 DATABANK   NAME=gpr5       START=0x500          END=0x5FF
19672 \layout LyX-Code
19673
19674 ACCESSBANK NAME=accesssfr  START=0xF80          END=0xFFF          PROTECTED
19675 \layout LyX-Code
19676
19677 \layout LyX-Code
19678
19679 SECTION    NAME=CONFIG     ROM=config
19680 \layout LyX-Code
19681
19682 \layout LyX-Code
19683
19684 SECTION    NAME=bank0      RAM=gpr0       # these SECTION directives
19685 \layout LyX-Code
19686
19687 SECTION    NAME=bank1      RAM=gpr1       # should be added to link
19688 \layout LyX-Code
19689
19690 SECTION    NAME=bank2      RAM=gpr2       # section name 'bank?' with
19691 \layout LyX-Code
19692
19693 SECTION    NAME=bank3      RAM=gpr3       # a specific DATABANK name
19694 \layout LyX-Code
19695
19696 SECTION    NAME=bank4      RAM=gpr4
19697 \layout LyX-Code
19698
19699 SECTION    NAME=bank5      RAM=gpr5
19700 \layout Standard
19701
19702 The linker will recognise the section name set in the pragma statement and
19703  will position the variable at the memory bank set with the RAM field at
19704  the SECTION line in the linker script file.
19705 \layout Subsection
19706
19707 Header Files
19708 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
19709
19710 \end_inset
19711
19712
19713 \layout Standard
19714
19715 There is one main header file
19716 \begin_inset LatexCommand \index{PIC16!Header files}
19717
19718 \end_inset
19719
19720  that can be included to the source files using the pic16
19721 \begin_inset LatexCommand \index{PIC16}
19722
19723 \end_inset
19724
19725  port.
19726  That file is the
19727 \series bold
19728 pic18fregs.h
19729 \series default
19730 .
19731  This header file contains the definitions for the processor special registers,
19732  so it is necessary if the source accesses them.
19733  It can be included by adding the following line in the beginning of the
19734  file:
19735 \layout LyX-Code
19736
19737 #include <pic18fregs.h>
19738 \layout Standard
19739
19740 The specific microcontroller is selected within the pic18fregs.h automatically,
19741  so the same source can be used with a variety of devices.
19742 \layout Subsection
19743
19744 Libraries
19745 \layout Standard
19746
19747 The libraries
19748 \begin_inset LatexCommand \index{PIC16!Libraries}
19749
19750 \end_inset
19751
19752  that PIC16
19753 \begin_inset LatexCommand \index{PIC16}
19754
19755 \end_inset
19756
19757  port depends on are the microcontroller device libraries which contain
19758  the symbol definitions for the microcontroller special function registers.
19759  These libraries have the format pic18fxxxx.lib, where
19760 \emph on
19761 xxxx
19762 \emph default
19763  is the microcontroller identification number.
19764  The specific library is selected automatically by the compiler at link
19765  stage according to the selected device.
19766 \layout Standard
19767
19768 Libraries are created with gplib which is part of the gputils package
19769 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
19770
19771 \end_inset
19772
19773 .
19774 \layout Subsubsection*
19775
19776 Building the libraries
19777 \layout Standard
19778
19779 Before using SDCC/pic16 there are some libraries that need to be compiled.
19780  This process is not done automatically by SDCC since not all users use
19781  SDCC for pic16 projects.
19782  So each user should compile the libraries separately.
19783 \layout Standard
19784
19785 The steps to compile the pic16 libraries under Linux are:
19786 \layout LyX-Code
19787
19788 cd device/lib/pic16
19789 \layout LyX-Code
19790
19791 ./configure
19792 \layout LyX-Code
19793
19794 make
19795 \layout LyX-Code
19796
19797 cd ..
19798 \layout LyX-Code
19799
19800 make model-pic16
19801 \layout LyX-Code
19802
19803 su -c 'make install'     # install the libraries, you need the root password
19804 \layout Standard
19805
19806 If you need to install the headers too, do:
19807 \layout LyX-Code
19808
19809 cd device/include
19810 \layout LyX-Code
19811
19812 su -c 'make install'     # install the headers, you need the root password
19813 \layout Standard
19814
19815 There exist a special target to build the I/O libraries.
19816  This target is not automatically build because it will build the I/O library
19817  for
19818 \emph on
19819 every
19820 \emph default
19821  supported device.
19822  This way building will take quite a lot of time.
19823  Users are advised to edit the
19824 \series bold
19825 device/lib/pic16/pics.build
19826 \series default
19827  file and then execute:
19828 \layout LyX-Code
19829
19830 make lib-io
19831 \layout Subsection
19832
19833 Memory Models
19834 \layout Standard
19835
19836 The following memory models are supported by the PIC16 port:
19837 \layout Itemize
19838
19839 small model
19840 \layout Itemize
19841
19842 large model
19843 \layout Standard
19844
19845 Memory model affects the default size of pointers within the source.
19846  The sizes are shown in the next table:
19847 \layout Standard
19848 \align center
19849
19850 \begin_inset  Tabular
19851 <lyxtabular version="3" rows="3" columns="3">
19852 <features>
19853 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19854 <column alignment="center" valignment="top" leftline="true" width="0">
19855 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
19856 <row topline="true" bottomline="true">
19857 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19858 \begin_inset Text
19859
19860 \layout Standard
19861
19862 Pointer sizes according to memory model
19863 \end_inset
19864 </cell>
19865 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19866 \begin_inset Text
19867
19868 \layout Standard
19869
19870 small model
19871 \end_inset
19872 </cell>
19873 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19874 \begin_inset Text
19875
19876 \layout Standard
19877
19878 large model
19879 \end_inset
19880 </cell>
19881 </row>
19882 <row topline="true" bottomline="true">
19883 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19884 \begin_inset Text
19885
19886 \layout Standard
19887
19888 code pointers
19889 \end_inset
19890 </cell>
19891 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19892 \begin_inset Text
19893
19894 \layout Standard
19895
19896 16-bits
19897 \end_inset
19898 </cell>
19899 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19900 \begin_inset Text
19901
19902 \layout Standard
19903
19904 24-bits
19905 \end_inset
19906 </cell>
19907 </row>
19908 <row topline="true" bottomline="true">
19909 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
19910 \begin_inset Text
19911
19912 \layout Standard
19913
19914 data pointers
19915 \end_inset
19916 </cell>
19917 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
19918 \begin_inset Text
19919
19920 \layout Standard
19921
19922 16-bits
19923 \end_inset
19924 </cell>
19925 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
19926 \begin_inset Text
19927
19928 \layout Standard
19929
19930 16-bits
19931 \end_inset
19932 </cell>
19933 </row>
19934 </lyxtabular>
19935
19936 \end_inset
19937
19938
19939 \layout Standard
19940
19941 It is advisable that all sources within a project are compiled with the
19942  same memory model.
19943  If one wants to override the default memory model, this can be done by
19944  declaring a pointer as
19945 \series bold
19946 far
19947 \series default
19948  or
19949 \series bold
19950 near
19951 \series default
19952 .
19953  Far selects large memory model's pointers, while near selects small memory
19954  model's pointers.
19955 \layout Standard
19956
19957 The standard device libraries (see
19958 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
19959
19960 \end_inset
19961
19962 ) contain no reference to pointers, so they can be used with both memory
19963  models.
19964 \layout Subsection
19965
19966 Stack
19967 \layout Standard
19968
19969 The stack
19970 \begin_inset LatexCommand \index{PIC16!stack}
19971
19972 \end_inset
19973
19974  implementation for the PIC16 port uses two indirect registers, FSR1 and
19975  FSR2.
19976 \layout List
19977 \labelwidthstring 00.00.0000
19978
19979 FSR1 is assigned as stack pointer
19980 \layout List
19981 \labelwidthstring 00.00.0000
19982
19983 FSR2 is assigned as frame pointer
19984 \layout Standard
19985
19986 The following stack models are supported by the PIC16 port
19987 \layout Itemize
19988
19989
19990 \noun on
19991 small
19992 \noun default
19993  model
19994 \layout Itemize
19995
19996
19997 \noun on
19998 large
19999 \noun default
20000  model
20001 \layout Standard
20002
20003
20004 \noun on
20005 Small
20006 \noun default
20007  model means that only the FSRxL byte is used to access stack and frame,
20008  while
20009 \emph on
20010 \noun on
20011 large
20012 \emph default
20013 \noun default
20014  uses both FSRxL and FSRxH registers.
20015  The following table shows the stack/frame pointers sizes according to stack
20016  model and the maximum space they can address:
20017 \layout Standard
20018 \align center
20019
20020 \begin_inset  Tabular
20021 <lyxtabular version="3" rows="3" columns="3">
20022 <features>
20023 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20024 <column alignment="center" valignment="top" leftline="true" width="0">
20025 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20026 <row topline="true" bottomline="true">
20027 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20028 \begin_inset Text
20029
20030 \layout Standard
20031
20032 Stack & Frame pointer sizes according to stack model
20033 \end_inset
20034 </cell>
20035 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20036 \begin_inset Text
20037
20038 \layout Standard
20039
20040 small
20041 \end_inset
20042 </cell>
20043 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20044 \begin_inset Text
20045
20046 \layout Standard
20047
20048 large
20049 \end_inset
20050 </cell>
20051 </row>
20052 <row topline="true">
20053 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20054 \begin_inset Text
20055
20056 \layout Standard
20057
20058 Stack pointer FSR1
20059 \end_inset
20060 </cell>
20061 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20062 \begin_inset Text
20063
20064 \layout Standard
20065
20066 8-bits
20067 \end_inset
20068 </cell>
20069 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20070 \begin_inset Text
20071
20072 \layout Standard
20073
20074 16-bits
20075 \end_inset
20076 </cell>
20077 </row>
20078 <row topline="true" bottomline="true">
20079 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20080 \begin_inset Text
20081
20082 \layout Standard
20083
20084 Frame pointer FSR2
20085 \end_inset
20086 </cell>
20087 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20088 \begin_inset Text
20089
20090 \layout Standard
20091
20092 8-bits
20093 \end_inset
20094 </cell>
20095 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20096 \begin_inset Text
20097
20098 \layout Standard
20099
20100 16-bits
20101 \end_inset
20102 </cell>
20103 </row>
20104 </lyxtabular>
20105
20106 \end_inset
20107
20108
20109 \layout Standard
20110
20111
20112 \noun on
20113 Large
20114 \noun default
20115 stack model is currently not working properly throughout the code generator.
20116  So its use is not advised.
20117  Also there are some other points that need special care:
20118 \newline
20119
20120 \layout Enumerate
20121
20122 Do not create stack sections with size more than one physical bank (that
20123  is 256 bytes)
20124 \layout Enumerate
20125
20126 Stack sections should no cross physical bank limits (i.e.
20127  #pragma stack 0x50 0x100)
20128 \layout Standard
20129
20130 These limitations are caused by the fact that only FSRxL is modified when
20131  using SMALL stack model, so no more than 256 bytes of stack can be used.
20132  This problem will disappear after LARGE model is fully implemented.
20133 \layout Subsection
20134
20135 Functions
20136 \layout Standard
20137
20138 In addition to the standard SDCC function keywords, PIC16
20139 \begin_inset LatexCommand \index{PIC16}
20140
20141 \end_inset
20142
20143  port makes available two more:
20144 \layout List
20145 \labelwidthstring 00.00.0000
20146
20147 wparam
20148 \begin_inset LatexCommand \index{PIC16!wparam}
20149
20150 \end_inset
20151
20152  Use the WREG to pass one byte of the first function argument.
20153  This improves speed but you may not use this for functions with arguments
20154  that are called via function pointers, otherwise the first byte of the
20155  first parameter will get lost.
20156  Usage:
20157 \layout LyX-Code
20158
20159 void func_wparam(int a) wparam
20160 \layout LyX-Code
20161
20162 {
20163 \layout LyX-Code
20164
20165     /* WREG hold the lower part of a */
20166 \layout LyX-Code
20167
20168     /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
20169  */
20170 \layout LyX-Code
20171
20172 ...
20173 \layout LyX-Code
20174
20175 }
20176 \layout List
20177 \labelwidthstring 00.00.0000
20178
20179 shadowregs
20180 \begin_inset LatexCommand \index{PIC16!shadowregs}
20181
20182 \end_inset
20183
20184  When entering/exiting an ISR, it is possible to take advantage of the PIC18F
20185  hardware shadow registers which hold the values of WREG, STATUS and BSR
20186  registers.
20187  This can be done by adding the keyword
20188 \emph on
20189 shadowregs
20190 \emph default
20191  before the
20192 \emph on
20193 interrupt
20194 \emph default
20195  keyword in the function's header.
20196 \layout LyX-Code
20197
20198 void isr_shadow(void) shadowregs interrupt 1
20199 \layout LyX-Code
20200
20201 {
20202 \layout LyX-Code
20203
20204 ...
20205 \layout LyX-Code
20206
20207 }
20208 \layout Standard
20209
20210
20211 \emph on
20212 shadowregs
20213 \emph default
20214  instructs the code generator not to store/restore WREG, STATUS, BSR when
20215  entering/exiting the ISR.
20216 \layout Subsection
20217
20218 Function return values
20219 \layout Standard
20220
20221 Return values from functions are placed to the appropriate registers following
20222  a modified Microchip policy optimized for SDCC.
20223  The following table shows these registers:
20224 \layout Standard
20225 \align center
20226
20227 \begin_inset  Tabular
20228 <lyxtabular version="3" rows="6" columns="2">
20229 <features>
20230 <column alignment="center" valignment="top" leftline="true" width="0">
20231 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20232 <row topline="true" bottomline="true">
20233 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20234 \begin_inset Text
20235
20236 \layout Standard
20237
20238 size
20239 \end_inset
20240 </cell>
20241 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20242 \begin_inset Text
20243
20244 \layout Standard
20245
20246 destination register
20247 \end_inset
20248 </cell>
20249 </row>
20250 <row topline="true">
20251 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20252 \begin_inset Text
20253
20254 \layout Standard
20255
20256 8 bits
20257 \end_inset
20258 </cell>
20259 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20260 \begin_inset Text
20261
20262 \layout Standard
20263
20264 WREG
20265 \end_inset
20266 </cell>
20267 </row>
20268 <row topline="true">
20269 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20270 \begin_inset Text
20271
20272 \layout Standard
20273
20274 16 bits
20275 \end_inset
20276 </cell>
20277 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20278 \begin_inset Text
20279
20280 \layout Standard
20281
20282 PRODL:WREG
20283 \end_inset
20284 </cell>
20285 </row>
20286 <row topline="true">
20287 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20288 \begin_inset Text
20289
20290 \layout Standard
20291
20292 24 bits
20293 \end_inset
20294 </cell>
20295 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20296 \begin_inset Text
20297
20298 \layout Standard
20299
20300 PRODH:PRODL:WREG
20301 \end_inset
20302 </cell>
20303 </row>
20304 <row topline="true">
20305 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20306 \begin_inset Text
20307
20308 \layout Standard
20309
20310 32 bits
20311 \end_inset
20312 </cell>
20313 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20314 \begin_inset Text
20315
20316 \layout Standard
20317
20318 FSR0L:PRODH:PRODL:WREG
20319 \end_inset
20320 </cell>
20321 </row>
20322 <row topline="true" bottomline="true">
20323 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20324 \begin_inset Text
20325
20326 \layout Standard
20327
20328 >32 bits
20329 \end_inset
20330 </cell>
20331 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20332 \begin_inset Text
20333
20334 \layout Standard
20335
20336 on stack, FSR0 points to the beginning
20337 \end_inset
20338 </cell>
20339 </row>
20340 </lyxtabular>
20341
20342 \end_inset
20343
20344
20345 \layout Subsection
20346
20347 Interrupts
20348 \layout Standard
20349
20350 An interrupt
20351 \begin_inset LatexCommand \index{PIC16!interrupt}
20352
20353 \end_inset
20354
20355  service routine (ISR) is declared using the
20356 \emph on
20357 interrupt
20358 \emph default
20359  keyword.
20360 \layout LyX-Code
20361
20362 void isr(void) interrupt
20363 \emph on
20364 n
20365 \layout LyX-Code
20366
20367 {
20368 \layout LyX-Code
20369
20370 ...
20371 \layout LyX-Code
20372
20373 }
20374 \layout Standard
20375
20376
20377 \emph on
20378 n
20379 \emph default
20380  is the interrupt number, which for PIC18F devices can be:
20381 \layout Standard
20382 \align center
20383
20384 \begin_inset  Tabular
20385 <lyxtabular version="3" rows="4" columns="3">
20386 <features>
20387 <column alignment="center" valignment="top" leftline="true" width="0">
20388 <column alignment="center" valignment="top" leftline="true" width="0">
20389 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20390 <row topline="true" bottomline="true">
20391 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20392 \begin_inset Text
20393
20394 \layout Standard
20395
20396
20397 \emph on
20398 n
20399 \end_inset
20400 </cell>
20401 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20402 \begin_inset Text
20403
20404 \layout Standard
20405
20406 Interrupt Vector
20407 \end_inset
20408 </cell>
20409 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20410 \begin_inset Text
20411
20412 \layout Standard
20413
20414 Interrupt Vector Address
20415 \end_inset
20416 </cell>
20417 </row>
20418 <row topline="true">
20419 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20420 \begin_inset Text
20421
20422 \layout Standard
20423
20424 0
20425 \end_inset
20426 </cell>
20427 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20428 \begin_inset Text
20429
20430 \layout Standard
20431
20432 RESET vector
20433 \end_inset
20434 </cell>
20435 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20436 \begin_inset Text
20437
20438 \layout Standard
20439
20440 0x000000
20441 \end_inset
20442 </cell>
20443 </row>
20444 <row topline="true">
20445 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20446 \begin_inset Text
20447
20448 \layout Standard
20449
20450
20451 \family roman
20452 \series medium
20453 \shape up
20454 \size normal
20455 \emph off
20456 \bar no
20457 \noun off
20458 \color none
20459 1
20460 \end_inset
20461 </cell>
20462 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20463 \begin_inset Text
20464
20465 \layout Standard
20466
20467
20468 \family roman
20469 \series medium
20470 \shape up
20471 \size normal
20472 \emph off
20473 \bar no
20474 \noun off
20475 \color none
20476 HIGH priority interrupts
20477 \end_inset
20478 </cell>
20479 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20480 \begin_inset Text
20481
20482 \layout Standard
20483
20484 0x000008
20485 \end_inset
20486 </cell>
20487 </row>
20488 <row topline="true" bottomline="true">
20489 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20490 \begin_inset Text
20491
20492 \layout Standard
20493
20494 2
20495 \end_inset
20496 </cell>
20497 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20498 \begin_inset Text
20499
20500 \layout Standard
20501
20502 LOW priority interrupts
20503 \end_inset
20504 </cell>
20505 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20506 \begin_inset Text
20507
20508 \layout Standard
20509
20510 0x000018
20511 \end_inset
20512 </cell>
20513 </row>
20514 </lyxtabular>
20515
20516 \end_inset
20517
20518
20519 \layout Standard
20520
20521 When generating assembly code for ISR the code generator places a
20522 \noun on
20523 goto
20524 \noun default
20525 instruction at the
20526 \emph on
20527 Interrupt Vector Address
20528 \emph default
20529  which points at the genetated ISR.
20530  This single GOTO instruction is part of an automatically generated
20531 \emph on
20532 interrupt entry point
20533 \emph default
20534  function.
20535  The actuall ISR code is placed as normally would in the code space.
20536  Upon interrupt request, the GOTO instruction is executed which jumps to
20537  the ISR code.
20538  When declaring interrupt functions as _naked this GOTO instruction is
20539 \series bold
20540 not
20541 \series default
20542  generated.
20543  The whole interrupt functions is therefore placed at the Interrupt Vector
20544  Address of the specific interrupt.
20545  This is not a problem for the LOW priority interrupts, but it is a problem
20546  for the RESET and the HIGH priority interrupts because code may be written
20547  at the next interrupt´s vector address and cause undeterminate program
20548  behaviour if that interrupt is raised.
20549 \begin_inset Foot
20550 collapsed false
20551
20552 \layout Standard
20553
20554 This is not a problem when
20555 \layout Enumerate
20556
20557 this is a HIGH interrupt ISR and LOW interrupts are
20558 \emph on
20559 disabled
20560 \emph default
20561  or not used.
20562 \layout Enumerate
20563
20564 when the ISR is small enough not to reach the next interrupt´s vector address.
20565 \end_inset
20566
20567
20568 \layout Standard
20569
20570
20571 \emph on
20572 n
20573 \emph default
20574  is possible to be omitted.
20575  This way a function is generated similar to an ISR, but it is not assigned
20576  to any interrupt.
20577 \layout Standard
20578
20579 When entering an interrupt, currently the PIC16
20580 \begin_inset LatexCommand \index{PIC16}
20581
20582 \end_inset
20583
20584  port automatically saves the following registers:
20585 \layout Itemize
20586
20587 WREG
20588 \layout Itemize
20589
20590 STATUS
20591 \layout Itemize
20592
20593 BSR
20594 \layout Itemize
20595
20596 PROD (PRODL and PRODH)
20597 \layout Itemize
20598
20599 FSR0 (FSR0L and FSR0H)
20600 \layout Standard
20601
20602 These registers are restored upon return from the interrupt routine.
20603 \begin_inset Foot
20604 collapsed false
20605
20606 \layout Standard
20607
20608 NOTE that when the _naked attribute is specified for an interrupt routine,
20609  then NO registers are stored or restored.
20610 \end_inset
20611
20612
20613 \layout Subsection
20614
20615 Generic Pointers
20616 \layout Standard
20617
20618 Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
20619  There are 3 types of generic pointers currently implemented data, code
20620  and eeprom pointers.
20621  They are differentiated by the value of the 7th and 6th bits of the upper
20622  byte:
20623 \layout Standard
20624 \align center
20625
20626 \begin_inset  Tabular
20627 <lyxtabular version="3" rows="5" columns="5">
20628 <features>
20629 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20630 <column alignment="center" valignment="top" width="0">
20631 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20632 <column alignment="center" valignment="top" width="0">
20633 <column alignment="left" valignment="top" rightline="true" width="0">
20634 <row topline="true" bottomline="true">
20635 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20636 \begin_inset Text
20637
20638 \layout Standard
20639
20640 pointer type
20641 \end_inset
20642 </cell>
20643 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20644 \begin_inset Text
20645
20646 \layout Standard
20647
20648 7th bit
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 6th bit
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 rest of the pointer
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 description
20673 \end_inset
20674 </cell>
20675 </row>
20676 <row topline="true" bottomline="true">
20677 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20678 \begin_inset Text
20679
20680 \layout Standard
20681
20682 data
20683 \end_inset
20684 </cell>
20685 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20686 \begin_inset Text
20687
20688 \layout Standard
20689
20690 1
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 0
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
20707 \family typewriter
20708 \shape slanted
20709 \emph on
20710 uuuuuu uuuuxxxx xxxxxxxx
20711 \end_inset
20712 </cell>
20713 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20714 \begin_inset Text
20715
20716 \layout Standard
20717
20718 a 12-bit data pointer in data RAM memory
20719 \end_inset
20720 </cell>
20721 </row>
20722 <row bottomline="true">
20723 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20724 \begin_inset Text
20725
20726 \layout Standard
20727
20728 code
20729 \end_inset
20730 </cell>
20731 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20732 \begin_inset Text
20733
20734 \layout Standard
20735
20736 0
20737 \end_inset
20738 </cell>
20739 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20740 \begin_inset Text
20741
20742 \layout Standard
20743
20744 0
20745 \end_inset
20746 </cell>
20747 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20748 \begin_inset Text
20749
20750 \layout Standard
20751
20752
20753 \family typewriter
20754 \shape slanted
20755 \emph on
20756 uxxxxx xxxxxxxx xxxxxxxx
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 a 21-bit code pointer in FLASH memory
20765 \end_inset
20766 </cell>
20767 </row>
20768 <row bottomline="true">
20769 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20770 \begin_inset Text
20771
20772 \layout Standard
20773
20774 eeprom
20775 \end_inset
20776 </cell>
20777 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20778 \begin_inset Text
20779
20780 \layout Standard
20781
20782 0
20783 \end_inset
20784 </cell>
20785 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20786 \begin_inset Text
20787
20788 \layout Standard
20789
20790 1
20791 \end_inset
20792 </cell>
20793 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20794 \begin_inset Text
20795
20796 \layout Standard
20797
20798
20799 \family typewriter
20800 \shape slanted
20801 \emph on
20802 uuuuuu uuuuuuxx xxxxxxxx
20803 \end_inset
20804 </cell>
20805 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20806 \begin_inset Text
20807
20808 \layout Standard
20809
20810 a 10-bit eeprom pointer in EEPROM memory
20811 \end_inset
20812 </cell>
20813 </row>
20814 <row bottomline="true">
20815 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20816 \begin_inset Text
20817
20818 \layout Standard
20819
20820 (unimplemented)
20821 \end_inset
20822 </cell>
20823 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20824 \begin_inset Text
20825
20826 \layout Standard
20827
20828 1
20829 \end_inset
20830 </cell>
20831 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20832 \begin_inset Text
20833
20834 \layout Standard
20835
20836 1
20837 \end_inset
20838 </cell>
20839 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20840 \begin_inset Text
20841
20842 \layout Standard
20843
20844
20845 \family typewriter
20846 \shape slanted
20847 \emph on
20848 xxxxxx xxxxxxxx xxxxxxxx
20849 \end_inset
20850 </cell>
20851 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20852 \begin_inset Text
20853
20854 \layout Standard
20855
20856 unimplemented pointer type
20857 \end_inset
20858 </cell>
20859 </row>
20860 </lyxtabular>
20861
20862 \end_inset
20863
20864
20865 \layout Standard
20866
20867 Generic pointer are read and written with a set of library functions which
20868  read/write 1, 2, 3, 4 bytes.
20869 \layout Subsection
20870
20871 PIC16 C Libraries
20872 \layout Subsubsection
20873
20874 Standard I/O Streams
20875 \layout Standard
20876
20877 In the
20878 \emph on
20879 stdio.h
20880 \emph default
20881  the type FILE is defined as:
20882 \layout LyX-Code
20883
20884 typedef char * FILE;
20885 \layout Standard
20886
20887 This type is the stream type implemented I/O in the PIC18F devices.
20888  Also the standard input and output streams are declared in stdio.h:
20889 \layout LyX-Code
20890
20891 extern FILE * stdin;
20892 \layout LyX-Code
20893
20894 extern FILE * stdout;
20895 \layout Standard
20896
20897 The FILE type is actually a generic pointer which defines one more type
20898  of generic pointers, the
20899 \emph on
20900 stream
20901 \emph default
20902 pointer.
20903  This new type has the format:
20904 \layout Standard
20905 \align center
20906
20907 \begin_inset  Tabular
20908 <lyxtabular version="3" rows="2" columns="7">
20909 <features>
20910 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20911 <column alignment="center" valignment="top" width="0">
20912 <column alignment="center" valignment="top" leftline="true" width="0">
20913 <column alignment="center" valignment="top" leftline="true" width="0">
20914 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
20915 <column alignment="center" valignment="top" width="0">
20916 <column alignment="left" valignment="top" rightline="true" width="0">
20917 <row topline="true" bottomline="true">
20918 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20919 \begin_inset Text
20920
20921 \layout Standard
20922
20923 pointer type
20924 \end_inset
20925 </cell>
20926 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20927 \begin_inset Text
20928
20929 \layout Standard
20930
20931 <7:6>
20932 \end_inset
20933 </cell>
20934 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20935 \begin_inset Text
20936
20937 \layout Standard
20938
20939 <5>
20940 \end_inset
20941 </cell>
20942 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20943 \begin_inset Text
20944
20945 \layout Standard
20946
20947 <4>
20948 \end_inset
20949 </cell>
20950 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20951 \begin_inset Text
20952
20953 \layout Standard
20954
20955 <3:0>
20956 \end_inset
20957 </cell>
20958 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20959 \begin_inset Text
20960
20961 \layout Standard
20962
20963 rest of the pointer
20964 \end_inset
20965 </cell>
20966 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20967 \begin_inset Text
20968
20969 \layout Standard
20970
20971 descrption
20972 \end_inset
20973 </cell>
20974 </row>
20975 <row topline="true" bottomline="true">
20976 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20977 \begin_inset Text
20978
20979 \layout Standard
20980
20981 stream
20982 \end_inset
20983 </cell>
20984 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20985 \begin_inset Text
20986
20987 \layout Standard
20988
20989 00
20990 \end_inset
20991 </cell>
20992 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20993 \begin_inset Text
20994
20995 \layout Standard
20996
20997 1
20998 \end_inset
20999 </cell>
21000 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21001 \begin_inset Text
21002
21003 \layout Standard
21004
21005 0
21006 \end_inset
21007 </cell>
21008 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21009 \begin_inset Text
21010
21011 \layout Standard
21012
21013 nnnn
21014 \end_inset
21015 </cell>
21016 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21017 \begin_inset Text
21018
21019 \layout Standard
21020
21021
21022 \family typewriter
21023 \shape slanted
21024 \emph on
21025 uuuuuuuu uuuuuuuu
21026 \end_inset
21027 </cell>
21028 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21029 \begin_inset Text
21030
21031 \layout Standard
21032
21033 upper byte high nubble is 0x2n, the rest are zeroes
21034 \end_inset
21035 </cell>
21036 </row>
21037 </lyxtabular>
21038
21039 \end_inset
21040
21041
21042 \layout Standard
21043
21044 Currently implemented there are 3 types of streams defined:
21045 \layout Standard
21046 \align center
21047
21048 \begin_inset  Tabular
21049 <lyxtabular version="3" rows="4" columns="4">
21050 <features>
21051 <column alignment="center" valignment="top" leftline="true" width="0">
21052 <column alignment="center" valignment="top" leftline="true" width="0">
21053 <column alignment="center" valignment="top" leftline="true" width="0">
21054 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
21055 <row topline="true" bottomline="true">
21056 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21057 \begin_inset Text
21058
21059 \layout Standard
21060
21061 stream type
21062 \end_inset
21063 </cell>
21064 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21065 \begin_inset Text
21066
21067 \layout Standard
21068
21069 value
21070 \end_inset
21071 </cell>
21072 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21073 \begin_inset Text
21074
21075 \layout Standard
21076
21077 module
21078 \end_inset
21079 </cell>
21080 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21081 \begin_inset Text
21082
21083 \layout Standard
21084
21085 description
21086 \end_inset
21087 </cell>
21088 </row>
21089 <row topline="true">
21090 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21091 \begin_inset Text
21092
21093 \layout Standard
21094
21095 STREAM_USART
21096 \end_inset
21097 </cell>
21098 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21099 \begin_inset Text
21100
21101 \layout Standard
21102
21103
21104 \family typewriter
21105 0x200000UL
21106 \end_inset
21107 </cell>
21108 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21109 \begin_inset Text
21110
21111 \layout Standard
21112
21113 USART
21114 \end_inset
21115 </cell>
21116 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21117 \begin_inset Text
21118
21119 \layout Standard
21120
21121 Writes/Reads characters via the USART peripheral
21122 \end_inset
21123 </cell>
21124 </row>
21125 <row topline="true">
21126 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21127 \begin_inset Text
21128
21129 \layout Standard
21130
21131 STREAM_MSSP
21132 \end_inset
21133 </cell>
21134 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21135 \begin_inset Text
21136
21137 \layout Standard
21138
21139
21140 \family typewriter
21141 0x210000UL
21142 \end_inset
21143 </cell>
21144 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21145 \begin_inset Text
21146
21147 \layout Standard
21148
21149 MSSP
21150 \end_inset
21151 </cell>
21152 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21153 \begin_inset Text
21154
21155 \layout Standard
21156
21157 Writes/Reads characters via the MSSP peripheral
21158 \end_inset
21159 </cell>
21160 </row>
21161 <row topline="true" bottomline="true">
21162 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21163 \begin_inset Text
21164
21165 \layout Standard
21166
21167 STREAM_USER
21168 \end_inset
21169 </cell>
21170 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21171 \begin_inset Text
21172
21173 \layout Standard
21174
21175
21176 \family typewriter
21177 0x2f0000UL
21178 \end_inset
21179 </cell>
21180 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21181 \begin_inset Text
21182
21183 \layout Standard
21184
21185 (none)
21186 \end_inset
21187 </cell>
21188 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21189 \begin_inset Text
21190
21191 \layout Standard
21192
21193 Writes/Reads characters via used defined functions
21194 \end_inset
21195 </cell>
21196 </row>
21197 </lyxtabular>
21198
21199 \end_inset
21200
21201
21202 \layout Standard
21203
21204 The stream identifiers are declared as macros in the stdio.h header.
21205 \layout Standard
21206
21207 In the libc library there exist the functions that are used to write to
21208  each of the above streams.
21209  These are
21210 \layout List
21211 \labelwidthstring 00.00.0000
21212
21213 _
21214 \begin_inset ERT
21215 status Collapsed
21216
21217 \layout Standard
21218
21219 \backslash
21220 /
21221 \end_inset
21222
21223 _stream_usart_putchar writes a character at the USART stream
21224 \layout List
21225 \labelwidthstring 00.00.0000
21226
21227 _
21228 \begin_inset ERT
21229 status Collapsed
21230
21231 \layout Standard
21232
21233 \backslash
21234 /
21235 \end_inset
21236
21237 _stream_mssp_putchar writes a character at the MSSP stream
21238 \layout List
21239 \labelwidthstring 00.00.0000
21240
21241 putchar dummy function.
21242  This writes a character to a user specified manner.
21243 \layout Standard
21244
21245 In order to increase performance
21246 \emph on
21247 putchar
21248 \emph default
21249 is declared in stdio.h as having its parameter in WREG (it has the wparam
21250  keyword).
21251  In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
21252  in a user-friendly way.
21253
21254 \emph on
21255 arg
21256 \emph default
21257  is the name of the variable that holds the character to print.
21258  An example follows:
21259 \layout LyX-Code
21260
21261 #include <pic18fregs.h>
21262 \newline
21263 #include <stdio.h>
21264 \newline
21265
21266 \newline
21267 PUTCHAR( c )
21268 \layout LyX-Code
21269
21270 {
21271 \layout LyX-Code
21272
21273     PORTA = c;    /* dump character c to PORTA */
21274 \layout LyX-Code
21275
21276 }
21277 \newline
21278
21279 \newline
21280 void main(void)
21281 \layout LyX-Code
21282
21283 {
21284 \layout LyX-Code
21285
21286     stdout = STREAM_USER;    /* this is not necessary, since stdout points
21287 \layout LyX-Code
21288
21289                               * by default to STREAM_USER */
21290 \layout LyX-Code
21291
21292     printf (¨This is a printf test
21293 \backslash
21294 n¨);
21295 \layout LyX-Code
21296
21297 }
21298 \layout LyX-Code
21299
21300 \layout Subsubsection
21301
21302 Printing functions
21303 \layout Standard
21304
21305 PIC16 contains an implementation of the printf-family of functions.
21306  There exist the following functions:
21307 \layout LyX-Code
21308
21309 extern unsigned int sprintf(char *buf, char *fmt, ...);
21310 \layout LyX-Code
21311
21312 extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
21313 \layout LyX-Code
21314
21315 \layout LyX-Code
21316
21317 extern unsigned int printf(char *fmt, ...);
21318 \layout LyX-Code
21319
21320 extern unsigned int vprintf(char *fmt, va_lista ap);
21321 \layout LyX-Code
21322
21323 \layout LyX-Code
21324
21325 extern unsigned int fprintf(FILE *fp, char *fmt, ...);
21326 \layout LyX-Code
21327
21328 extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
21329 \layout Standard
21330
21331 For sprintf and vsprintf
21332 \emph on
21333 buf
21334 \emph default
21335 should normally be a data pointer where the resulting string will be placed.
21336  No range checking is done so the user should allocate the necessery buffer.
21337  For fprintf and vfprintf
21338 \emph on
21339 fp
21340 \emph default
21341  should be a stream pointer (i.e.
21342  stdout, STREAM_MSSP, etc...).
21343 \layout Subsubsection
21344
21345 Signals
21346 \layout Standard
21347
21348 The PIC18F family of microcontrollers supports a number of interrupt sources.
21349  A list of these interrupts is shown in the following table:
21350 \layout Standard
21351 \align center
21352
21353 \begin_inset  Tabular
21354 <lyxtabular version="3" rows="11" columns="4">
21355 <features>
21356 <column alignment="left" valignment="top" leftline="true" width="0">
21357 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
21358 <column alignment="left" valignment="top" leftline="true" width="0">
21359 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
21360 <row topline="true" bottomline="true">
21361 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21362 \begin_inset Text
21363
21364 \layout Standard
21365
21366 signal name
21367 \end_inset
21368 </cell>
21369 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21370 \begin_inset Text
21371
21372 \layout Standard
21373
21374 description
21375 \end_inset
21376 </cell>
21377 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21378 \begin_inset Text
21379
21380 \layout Standard
21381
21382 signal name
21383 \end_inset
21384 </cell>
21385 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21386 \begin_inset Text
21387
21388 \layout Standard
21389
21390 descritpion
21391 \end_inset
21392 </cell>
21393 </row>
21394 <row topline="true">
21395 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21396 \begin_inset Text
21397
21398 \layout Standard
21399
21400 SIG_RB
21401 \end_inset
21402 </cell>
21403 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21404 \begin_inset Text
21405
21406 \layout Standard
21407
21408 PORTB change interrupt
21409 \end_inset
21410 </cell>
21411 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21412 \begin_inset Text
21413
21414 \layout Standard
21415
21416 SIG_EE
21417 \end_inset
21418 </cell>
21419 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21420 \begin_inset Text
21421
21422 \layout Standard
21423
21424 EEPROM/FLASH write complete interrupt
21425 \end_inset
21426 </cell>
21427 </row>
21428 <row topline="true">
21429 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21430 \begin_inset Text
21431
21432 \layout Standard
21433
21434 SIG_INT0
21435 \end_inset
21436 </cell>
21437 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21438 \begin_inset Text
21439
21440 \layout Standard
21441
21442 INT0 external interrupt
21443 \end_inset
21444 </cell>
21445 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21446 \begin_inset Text
21447
21448 \layout Standard
21449
21450 SIG_BCOL
21451 \end_inset
21452 </cell>
21453 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21454 \begin_inset Text
21455
21456 \layout Standard
21457
21458 Bus collision interrupt
21459 \end_inset
21460 </cell>
21461 </row>
21462 <row topline="true">
21463 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21464 \begin_inset Text
21465
21466 \layout Standard
21467
21468 SIG_INT1
21469 \end_inset
21470 </cell>
21471 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21472 \begin_inset Text
21473
21474 \layout Standard
21475
21476 INT1 external interrupt
21477 \end_inset
21478 </cell>
21479 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21480 \begin_inset Text
21481
21482 \layout Standard
21483
21484 SIG_LVD
21485 \end_inset
21486 </cell>
21487 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21488 \begin_inset Text
21489
21490 \layout Standard
21491
21492 Low voltage detect interrupt
21493 \end_inset
21494 </cell>
21495 </row>
21496 <row topline="true">
21497 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21498 \begin_inset Text
21499
21500 \layout Standard
21501
21502 SIG_INT2
21503 \end_inset
21504 </cell>
21505 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21506 \begin_inset Text
21507
21508 \layout Standard
21509
21510 INT2 external interrupt
21511 \end_inset
21512 </cell>
21513 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21514 \begin_inset Text
21515
21516 \layout Standard
21517
21518 SIG_PSP
21519 \end_inset
21520 </cell>
21521 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21522 \begin_inset Text
21523
21524 \layout Standard
21525
21526 Parallel slave port interrupt
21527 \end_inset
21528 </cell>
21529 </row>
21530 <row topline="true">
21531 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21532 \begin_inset Text
21533
21534 \layout Standard
21535
21536 SIG_CCP1
21537 \end_inset
21538 </cell>
21539 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21540 \begin_inset Text
21541
21542 \layout Standard
21543
21544 CCP1 module interrupt
21545 \end_inset
21546 </cell>
21547 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21548 \begin_inset Text
21549
21550 \layout Standard
21551
21552 SIG_AD
21553 \end_inset
21554 </cell>
21555 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21556 \begin_inset Text
21557
21558 \layout Standard
21559
21560 AD convertion complete interrupt
21561 \end_inset
21562 </cell>
21563 </row>
21564 <row topline="true">
21565 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21566 \begin_inset Text
21567
21568 \layout Standard
21569
21570 SIG_CCP2
21571 \end_inset
21572 </cell>
21573 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21574 \begin_inset Text
21575
21576 \layout Standard
21577
21578 CCP2 module interrupt
21579 \end_inset
21580 </cell>
21581 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21582 \begin_inset Text
21583
21584 \layout Standard
21585
21586 SIG_RC
21587 \end_inset
21588 </cell>
21589 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21590 \begin_inset Text
21591
21592 \layout Standard
21593
21594 USART receive interrupt
21595 \end_inset
21596 </cell>
21597 </row>
21598 <row topline="true">
21599 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21600 \begin_inset Text
21601
21602 \layout Standard
21603
21604 SIG_TMR0
21605 \end_inset
21606 </cell>
21607 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21608 \begin_inset Text
21609
21610 \layout Standard
21611
21612 TMR0 overflow interrupt
21613 \end_inset
21614 </cell>
21615 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21616 \begin_inset Text
21617
21618 \layout Standard
21619
21620 SIG_TX
21621 \end_inset
21622 </cell>
21623 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21624 \begin_inset Text
21625
21626 \layout Standard
21627
21628 USART transmit interrupt
21629 \end_inset
21630 </cell>
21631 </row>
21632 <row topline="true">
21633 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21634 \begin_inset Text
21635
21636 \layout Standard
21637
21638 SIG_TMR1
21639 \end_inset
21640 </cell>
21641 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21642 \begin_inset Text
21643
21644 \layout Standard
21645
21646 TMR1 overflow interrupt
21647 \end_inset
21648 </cell>
21649 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21650 \begin_inset Text
21651
21652 \layout Standard
21653
21654 SIG_MSSP
21655 \end_inset
21656 </cell>
21657 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21658 \begin_inset Text
21659
21660 \layout Standard
21661
21662 SSP receive/transmit interrupt
21663 \end_inset
21664 </cell>
21665 </row>
21666 <row topline="true">
21667 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21668 \begin_inset Text
21669
21670 \layout Standard
21671
21672 SIG_TMR2
21673 \end_inset
21674 </cell>
21675 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21676 \begin_inset Text
21677
21678 \layout Standard
21679
21680 TMR2 matches PR2 interrupt
21681 \end_inset
21682 </cell>
21683 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21684 \begin_inset Text
21685
21686 \layout Standard
21687
21688 \end_inset
21689 </cell>
21690 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21691 \begin_inset Text
21692
21693 \layout Standard
21694
21695 \end_inset
21696 </cell>
21697 </row>
21698 <row topline="true" bottomline="true">
21699 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21700 \begin_inset Text
21701
21702 \layout Standard
21703
21704 SIG_TMR3
21705 \end_inset
21706 </cell>
21707 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21708 \begin_inset Text
21709
21710 \layout Standard
21711
21712 TMR3 overflow interrupt
21713 \end_inset
21714 </cell>
21715 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21716 \begin_inset Text
21717
21718 \layout Standard
21719
21720 \end_inset
21721 </cell>
21722 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21723 \begin_inset Text
21724
21725 \layout Standard
21726
21727 \end_inset
21728 </cell>
21729 </row>
21730 </lyxtabular>
21731
21732 \end_inset
21733
21734
21735 \layout Standard
21736
21737 The prototypes for these names are defined in the header file
21738 \emph on
21739 signal.h
21740 \emph default
21741  .
21742 \layout Standard
21743
21744 In order to simplify signal handling, a number of macros is provided:
21745 \layout List
21746 \labelwidthstring 00.00.0000
21747
21748 DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
21749  high priority interrupts.
21750
21751 \emph on
21752 name
21753 \emph default
21754  is the function name to use.
21755 \layout List
21756 \labelwidthstring 00.00.0000
21757
21758 DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
21759  low priority interrupt.
21760
21761 \emph on
21762 name
21763 \emph default
21764  is the function name to use.
21765 \layout List
21766 \labelwidthstring 00.00.0000
21767
21768 DEF_HANDLER(sig,handler) define a handler for signal
21769 \emph on
21770 sig.
21771 \layout List
21772 \labelwidthstring 00.00.0000
21773
21774 END_DEF end the declaration of the dispatch table.
21775 \layout Standard
21776
21777 Additionally there are two more macros to simplify the declaration of the
21778  signal handler:
21779 \layout List
21780 \labelwidthstring 00.00.0000
21781
21782
21783 \series medium
21784 SIGHANDLER(handler)
21785 \series default
21786 this declares the function prototype for the
21787 \emph on
21788 handler
21789 \emph default
21790  function.
21791 \layout List
21792 \labelwidthstring 00.00.0000
21793
21794 SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
21795 \layout Standard
21796
21797 An example of using the macros above is shown below:
21798 \layout LyX-Code
21799
21800 #include <pic18fregs.h>
21801 \layout LyX-Code
21802
21803 #include <signal.h>
21804 \newline
21805
21806 \newline
21807 DEF_INTHIGH(high_int)
21808 \layout LyX-Code
21809
21810 DEF_HANDLER(SIG_TMR0, _tmr0_handler)
21811 \layout LyX-Code
21812
21813 DEF_HANDLER(SIG_BCOL, _bcol_handler)
21814 \layout LyX-Code
21815
21816 END_DEF
21817 \newline
21818
21819 \newline
21820 SIGHANDLER(_tmr0_handler)
21821 \layout LyX-Code
21822
21823 {
21824 \layout LyX-Code
21825
21826   /* action to be taken when timer 0 overflows */
21827 \layout LyX-Code
21828
21829 }
21830 \newline
21831
21832 \newline
21833 SIGHANDLERNAKED(_bcol_handler)
21834 \layout LyX-Code
21835
21836 {
21837 \layout LyX-Code
21838
21839   _asm
21840 \layout LyX-Code
21841
21842     /* action to be taken when bus collision occurs */
21843 \layout LyX-Code
21844
21845     retfie
21846 \layout LyX-Code
21847
21848  _endasm;
21849 \layout LyX-Code
21850
21851 }
21852 \layout Standard
21853
21854
21855 \series bold
21856 NOTES:
21857 \series default
21858  Special care should be taken when using the above scheme:
21859 \layout Itemize
21860
21861 do not place a colon (;) at the end of the DEF_* and END_DEF macros.
21862 \layout Itemize
21863
21864 when declaring SIGHANDLERNAKED handler never forget to use
21865 \emph on
21866 retfie
21867 \emph default
21868  for proper returning.
21869 \layout Subsection
21870
21871 PIC16 Port -- Tips
21872 \layout Standard
21873
21874 Here you can find some general tips for compiling programs with SDCC/pic16.
21875 \layout Subsubsection
21876
21877 Stack size
21878 \layout Standard
21879
21880 The default stack
21881 \begin_inset LatexCommand \index{PIC16!stack}
21882
21883 \end_inset
21884
21885  size (that is 64 bytes) probably is enough for many programs.
21886  One must take care that when there are many levels of function nesting,
21887  or there is excessive usage of stack, its size should be extended.
21888  An example of such a case is the printf/sprintf family of functions.
21889  If you encounter problems like not being able to print integers, then you
21890  need to set the stack size around the maximum (256 for small stack model).
21891  The following diagram shows what happens when calling printf to print an
21892  integer:
21893 \layout LyX-Code
21894
21895 printf () --> ltoa () --> ultoa () --> divschar ()
21896 \layout Standard
21897
21898 It is should be understood that stack is easily consumed when calling complicate
21899 d functions.
21900  Using command line arguments like -
21901 \begin_inset ERT
21902 status Collapsed
21903
21904 \layout Standard
21905
21906 \backslash
21907 /
21908 \end_inset
21909
21910 -fommit-frame-pointer might reduce stack usage by not creating unnecessery
21911  stack frames.
21912  Other ways to reduce stack usage may exist.
21913 \layout Subsection
21914
21915 Known bugs
21916 \layout Standard
21917
21918 The PIC16 Port currently does not pass SDCC's regression test
21919 \begin_inset LatexCommand \index{Regression test (PIC16)}
21920
21921 \end_inset
21922
21923  suite (see section
21924 \begin_inset LatexCommand \ref{sec:Quality-control}
21925
21926 \end_inset
21927
21928 ) and thus the nightly regression tests for the PIC16 target are currently
21929  disabled for all hosts except for
21930 \emph on
21931 Linux on Opteron.
21932
21933 \emph default
21934  This means you can see the result of the PIC16 regression tests f.e.
21935  by checking the log files in
21936 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/regression_test_results/amd64-unknown-linux2.3/}
21937
21938 \end_inset
21939
21940  (pick the most up to date file there, scroll down, lend a hand).
21941 \layout Chapter
21942
21943 Debugging
21944 \layout Standard
21945
21946 There are several approaches to debugging your code.
21947  This chapter is meant to show your options and to give detail on some of
21948  them:
21949 \newline
21950
21951 \newline
21952 When writing your code:
21953 \layout Itemize
21954
21955 write your code with debugging in mind (avoid duplicating code, put conceptually
21956  similar variables into structs, use structured code, have strategic points
21957  within your code where all variables are consistent, ...)
21958 \layout Itemize
21959
21960 run a syntax-checking tool like splint
21961 \begin_inset LatexCommand \index{splint (syntax checking tool)}
21962
21963 \end_inset
21964
21965
21966 \begin_inset LatexCommand \index{lint (syntax checking tool)}
21967
21968 \end_inset
21969
21970  (see -
21971 \begin_inset ERT
21972 status Collapsed
21973
21974 \layout Standard
21975
21976 \backslash
21977 /
21978 \end_inset
21979
21980 -more-pedantic
21981 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
21982
21983 \end_inset
21984
21985 ) over the code.
21986 \layout Itemize
21987
21988 for the high level code use a C-compiler (like f.e.
21989  GCC) to compile run and debug the code on your host.
21990  See (see -
21991 \begin_inset ERT
21992 status Collapsed
21993
21994 \layout Standard
21995
21996 \backslash
21997 /
21998 \end_inset
21999
22000 -more-pedantic
22001 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
22002
22003 \end_inset
22004
22005  ) on howto handle syntax extensions like __xdata, __at(), ...
22006
22007 \layout Itemize
22008
22009 use another C-compiler to compile code for your target.
22010  Always an option but not recommended:) And not very likely to help you.
22011  If you seriously consider walking this path you should at least occasionally
22012  check portability of your code.
22013  Most commercial compiler vendors will offer an evaluation version so you
22014  can test compile your code or snippets of your code.
22015 \layout Standard
22016
22017 Debugging on a simulator:
22018 \layout Itemize
22019
22020 there is a separate section about SDCDB (section
22021 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
22022
22023 \end_inset
22024
22025 ) below.
22026 \layout Itemize
22027
22028 or (8051 specific) use a freeware/commercial simulator which interfaces
22029  to the AOMF
22030 \begin_inset LatexCommand \index{AOMF, AOMF51}
22031
22032 \end_inset
22033
22034  file (see
22035 \begin_inset LatexCommand \ref{OMF file}
22036
22037 \end_inset
22038
22039 ) optionally generated by SDCC.
22040 \layout Standard
22041
22042 Debugging On-target:
22043 \layout Itemize
22044
22045 use a MCU port pin to serially output debug data to the RS232 port of your
22046  host.
22047  You'll probably want some level shifting device typically involving a MAX232
22048  or similar IC.
22049  If the hardware serial port of the MCU is not available search for 'Software
22050  UART' in your favourite search machine.
22051 \layout Itemize
22052
22053 use an on-target monitor.
22054  In this context a monitor is a small program which usually accepts commands
22055  via a serial line and allows to set program counter, to single step through
22056  a program and read/write memory locations.
22057  For the 8051 good examples of monitors are paulmon and cmon51 (see section
22058
22059 \begin_inset LatexCommand \ref{sec:Related-open-source-tools}
22060
22061 \end_inset
22062
22063 ).
22064 \layout Itemize
22065
22066 toggle MCU port pins at strategic points within your code and use an oscilloscop
22067 e.
22068  A
22069 \emph on
22070 digital oscilloscope
22071 \emph default
22072
22073 \begin_inset LatexCommand \index{Oscilloscope}
22074
22075 \end_inset
22076
22077  with deep trace memory is really helpful especially if you have to debug
22078  a realtime application.
22079  If you need to monitor more pins than your oscilloscope provides you can
22080  sometimes get away with a small R-2R network.
22081  On a single channel oscilloscope you could f.e.
22082  monitor 2 push-pull driven pins by connecting one via a 10\SpecialChar ~
22083 k
22084 \begin_inset Formula $\Omega$
22085 \end_inset
22086
22087  resistor and the other one by a 5\SpecialChar ~
22088 k
22089 \begin_inset Formula $\Omega$
22090 \end_inset
22091
22092  resistor to the oscilloscope probe (check output drive capability of the
22093  pins you want to monitor).
22094  If you need to monitor many more pins a
22095 \emph on
22096 logic analyzer
22097 \emph default
22098  will be handy.
22099 \layout Itemize
22100
22101 use an ICE (
22102 \emph on
22103 i
22104 \emph default
22105 n
22106 \emph on
22107 c
22108 \emph default
22109 ircuit
22110 \emph on
22111 e
22112 \emph default
22113 mulator
22114 \begin_inset LatexCommand \index{ICE (in circuit emulator)}
22115
22116 \end_inset
22117
22118 ).
22119  Usually very expensive.
22120  And very nice to have too.
22121  And usually locks you (for years...) to the devices the ICE can emulate.
22122
22123 \layout Itemize
22124
22125 use a remote debugger.
22126  In most 8-bit systems the symbol information is not available on the target,
22127  and a complete debugger is too bulky for the target system.
22128  Therefore usually a debugger on the host system connects to an on-target
22129  debugging stub which accepts only primitive commands.
22130
22131 \newline
22132 Terms to enter into your favourite search engine could be 'remote debugging',
22133  'gdb stub' or 'inferior debugger'.
22134  (is there one?)
22135 \layout Itemize
22136
22137 use an on target hardware debugger.
22138  Some of the more modern MCUs include hardware support for setting break
22139  points and monitoring/changing variables by using dedicated hardware pins.
22140  This facility doesn't require additional code to run on the target and
22141
22142 \emph on
22143 usually
22144 \emph default
22145  doesn't affect runtime behaviour until a breakpoint is hit.
22146  For the mcs51 most hardware debuggers use the AOMF
22147 \begin_inset LatexCommand \index{AOMF, AOMF51}
22148
22149 \end_inset
22150
22151  file (see
22152 \begin_inset LatexCommand \ref{OMF file}
22153
22154 \end_inset
22155
22156 ) as input file.
22157
22158 \layout Standard
22159
22160 Last not least:
22161 \layout Itemize
22162
22163 if you are not familiar with any of the following terms you're likely to
22164  run into problems rather sooner than later:
22165 \emph on
22166 volatile
22167 \emph default
22168 ,
22169 \emph on
22170 atomic
22171 \emph default
22172 ,
22173 \emph on
22174 memory map
22175 \emph default
22176 ,
22177 \emph on
22178 overlay
22179 \emph default
22180 .
22181  As an embedded programmer you
22182 \emph on
22183 have
22184 \emph default
22185  to know them so why not look them up
22186 \emph on
22187 before
22188 \emph default
22189  you have problems?)
22190 \layout Itemize
22191
22192 tell someone else about your problem (actually this is a surprisingly effective
22193  means to hunt down the bug even if the listener is not familiar with your
22194  environment).
22195  As 'failure to communicate' is probably one of the job-induced deformations
22196  of an embedded programmer this is highly encouraged.
22197 \layout Section
22198
22199 Debugging with SDCDB
22200 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
22201
22202 \end_inset
22203
22204
22205 \begin_inset LatexCommand \index{SDCDB (debugger)}
22206
22207 \end_inset
22208
22209
22210 \layout Standard
22211
22212 SDCC is distributed with a source level debugger
22213 \begin_inset LatexCommand \index{Debugger}
22214
22215 \end_inset
22216
22217 .
22218  The debugger uses a command line interface, the command repertoire of the
22219  debugger has been kept as close to gdb
22220 \begin_inset LatexCommand \index{gdb}
22221
22222 \end_inset
22223
22224  (the GNU debugger) as possible.
22225  The configuration and build process is part of the standard compiler installati
22226 on, which also builds and installs the debugger in the target directory
22227  specified during configuration.
22228  The debugger allows you debug BOTH at the C source and at the ASM source
22229  level.
22230 \layout Subsection
22231
22232 Compiling for Debugging
22233 \layout Standard
22234
22235 The -
22236 \begin_inset ERT
22237 status Collapsed
22238
22239 \layout Standard
22240
22241 \backslash
22242 /
22243 \end_inset
22244
22245 -debug
22246 \begin_inset LatexCommand \index{-\/-debug}
22247
22248 \end_inset
22249
22250  option must be specified for all files for which debug information is to
22251  be generated.
22252  The compiler generates a .adb file for each of these files.
22253  The linker creates the .cdb
22254 \begin_inset LatexCommand \index{<file>.cdb}
22255
22256 \end_inset
22257
22258  file from the .adb
22259 \begin_inset LatexCommand \index{<file>.adb}
22260
22261 \end_inset
22262
22263  files and the address information.
22264  This .cdb is used by the debugger.
22265 \layout Subsection
22266
22267 How the Debugger Works
22268 \layout Standard
22269
22270 When the -
22271 \begin_inset ERT
22272 status Collapsed
22273
22274 \layout Standard
22275
22276 \backslash
22277 /
22278 \end_inset
22279
22280 -debug option is specified the compiler generates extra symbol information
22281  some of which are put into the assembler source and some are put into the
22282  .adb file.
22283  Then the linker creates the .cdb file from the individual .adb files with
22284  the address information for the symbols.
22285  The debugger reads the symbolic information generated by the compiler &
22286  the address information generated by the linker.
22287  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
22288  execution is controlled by the debugger.
22289  When a command is issued for the debugger, it translates it into appropriate
22290  commands for the simulator.
22291  (Currently SDCDM only connects to the simulator but
22292 \emph on
22293 newcdb
22294 \emph default
22295  at
22296 \begin_inset LatexCommand \url{http://ec2drv.sf.net/}
22297
22298 \end_inset
22299
22300  is an effort to connect directly to the hardware.)
22301 \layout Subsection
22302
22303 Starting the Debugger SDCDB
22304 \layout Standard
22305
22306 The debugger can be started using the following command line.
22307  (Assume the file you are debugging has the file name foo).
22308 \newline
22309
22310 \newline
22311
22312 \family sans
22313 \series bold
22314 sdcdb foo
22315 \newline
22316
22317 \family default
22318 \series default
22319
22320 \newline
22321 The debugger will look for the following files.
22322 \layout Itemize
22323
22324 foo.c - the source file.
22325 \layout Itemize
22326
22327 foo.cdb - the debugger symbol information file.
22328 \layout Itemize
22329
22330 foo.ihx - the Intel hex format
22331 \begin_inset LatexCommand \index{Intel hex format}
22332
22333 \end_inset
22334
22335  object file.
22336 \layout Subsection
22337
22338 SDCDB Command Line Options
22339 \layout Itemize
22340
22341 -
22342 \begin_inset ERT
22343 status Collapsed
22344
22345 \layout Standard
22346
22347 \backslash
22348 /
22349 \end_inset
22350
22351 -directory=<source file directory> this option can used to specify the directory
22352  search list.
22353  The debugger will look into the directory list specified for source, cdb
22354  & ihx files.
22355  The items in the directory list must be separated by ':', e.g.
22356  if the source files can be in the directories /home/src1 and /home/src2,
22357  the -
22358 \begin_inset ERT
22359 status Collapsed
22360
22361 \layout Standard
22362
22363 \backslash
22364 /
22365 \end_inset
22366
22367 -directory option should be -
22368 \begin_inset ERT
22369 status Collapsed
22370
22371 \layout Standard
22372
22373 \backslash
22374 /
22375 \end_inset
22376
22377 -directory=/home/src1:/home/src2.
22378  Note there can be no spaces in the option.
22379
22380 \layout Itemize
22381
22382 -cd <directory> - change to the <directory>.
22383 \layout Itemize
22384
22385 -fullname - used by GUI front ends.
22386 \layout Itemize
22387
22388 -cpu <cpu-type> - this argument is passed to the simulator please see the
22389  simulator docs for details.
22390 \layout Itemize
22391
22392 -X <Clock frequency > this options is passed to the simulator please see
22393  the simulator docs for details.
22394 \layout Itemize
22395
22396 -s <serial port file> passed to simulator see the simulator docs for details.
22397 \layout Itemize
22398
22399 -S <serial in,out> passed to simulator see the simulator docs for details.
22400 \layout Itemize
22401
22402 -k <port number> passed to simulator see the simulator docs for details.
22403 \layout Subsection
22404
22405 SDCDB Debugger Commands
22406 \layout Standard
22407
22408 As mentioned earlier the command interface for the debugger has been deliberatel
22409 y kept as close the GNU debugger gdb, as possible.
22410  This will help the integration with existing graphical user interfaces
22411  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
22412  If you use a graphical user interface for the debugger you can skip this
22413  section.
22414 \layout Subsubsection*
22415
22416 break [line | file:line | function | file:function]
22417 \layout Standard
22418
22419 Set breakpoint at specified line or function:
22420 \newline
22421
22422 \newline
22423
22424 \family sans
22425 \series bold
22426 sdcdb>break 100
22427 \newline
22428 sdcdb>break foo.c:100
22429 \newline
22430 sdcdb>break funcfoo
22431 \newline
22432 sdcdb>break foo.c:funcfoo
22433 \layout Subsubsection*
22434
22435 clear [line | file:line | function | file:function ]
22436 \layout Standard
22437
22438 Clear breakpoint at specified line or function:
22439 \newline
22440
22441 \newline
22442
22443 \family sans
22444 \series bold
22445 sdcdb>clear 100
22446 \newline
22447 sdcdb>clear foo.c:100
22448 \newline
22449 sdcdb>clear funcfoo
22450 \newline
22451 sdcdb>clear foo.c:funcfoo
22452 \layout Subsubsection*
22453
22454 continue
22455 \layout Standard
22456
22457 Continue program being debugged, after breakpoint.
22458 \layout Subsubsection*
22459
22460 finish
22461 \layout Standard
22462
22463 Execute till the end of the current function.
22464 \layout Subsubsection*
22465
22466 delete [n]
22467 \layout Standard
22468
22469 Delete breakpoint number 'n'.
22470  If used without any option clear ALL user defined break points.
22471 \layout Subsubsection*
22472
22473 info [break | stack | frame | registers ]
22474 \layout Itemize
22475
22476 info break - list all breakpoints
22477 \layout Itemize
22478
22479 info stack - show the function call stack.
22480 \layout Itemize
22481
22482 info frame - show information about the current execution frame.
22483 \layout Itemize
22484
22485 info registers - show content of all registers.
22486 \layout Subsubsection*
22487
22488 step
22489 \layout Standard
22490
22491 Step program until it reaches a different source line.
22492  Note: pressing <return> repeats the last command.
22493 \layout Subsubsection*
22494
22495 next
22496 \layout Standard
22497
22498 Step program, proceeding through subroutine calls.
22499 \layout Subsubsection*
22500
22501 run
22502 \layout Standard
22503
22504 Start debugged program.
22505 \layout Subsubsection*
22506
22507 ptype variable
22508 \layout Standard
22509
22510 Print type information of the variable.
22511 \layout Subsubsection*
22512
22513 print variable
22514 \layout Standard
22515
22516 print value of variable.
22517 \layout Subsubsection*
22518
22519 file filename
22520 \layout Standard
22521
22522 load the given file name.
22523  Note this is an alternate method of loading file for debugging.
22524 \layout Subsubsection*
22525
22526 frame
22527 \layout Standard
22528
22529 print information about current frame.
22530 \layout Subsubsection*
22531
22532 set srcmode
22533 \layout Standard
22534
22535 Toggle between C source & assembly source.
22536 \layout Subsubsection*
22537
22538 ! simulator command
22539 \layout Standard
22540
22541 Send the string following '!' to the simulator, the simulator response is
22542  displayed.
22543  Note the debugger does not interpret the command being sent to the simulator,
22544  so if a command like 'go' is sent the debugger can loose its execution
22545  context and may display incorrect values.
22546 \layout Subsubsection*
22547
22548 quit
22549 \layout Standard
22550
22551 "Watch me now.
22552  Iam going Down.
22553  My name is Bobby Brown"
22554 \layout Subsection
22555
22556 Interfacing SDCDB with DDD
22557 \layout Comment
22558
22559 The screenshot was converted from png to eps with:
22560 \begin_inset Quotes sld
22561 \end_inset
22562
22563 bmeps -c -e8f -p3 ddd_example.png >ddd_example.eps
22564 \begin_inset Quotes srd
22565 \end_inset
22566
22567  which produces a pretty compact eps file which is free from compression
22568  artifacts.
22569 \layout Comment
22570
22571 The screenshot was included in sdccman.lyx cvs version 1.120 but later removed
22572  as this broke the build system on Sourceforge (pdf-file was broken.
22573  pdflatex does not accept eps files).
22574 \layout Standard
22575
22576 The
22577 \emph on
22578 p
22579 \emph default
22580 ortable
22581 \emph on
22582 n
22583 \emph default
22584 etwork
22585 \emph on
22586 g
22587 \emph default
22588 raphics File
22589 \size footnotesize
22590
22591 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/doc/figures/ddd_example.png}
22592
22593 \end_inset
22594
22595
22596 \size default
22597  shows a screenshot of a debugging session with DDD
22598 \begin_inset LatexCommand \index{DDD (debugger)}
22599
22600 \end_inset
22601
22602  (Unix only) on a simulated 8032.
22603  The debugging session might not run as smoothly as the screenshot suggests.
22604  The debugger allows setting of breakpoints, displaying and changing variables,
22605  single stepping through C and assembler code.
22606
22607 \newline
22608 The source was compiled with
22609 \family sans
22610 \series bold
22611
22612 \newline
22613
22614 \newline
22615 sdcc -
22616 \family default
22617 \series default
22618
22619 \begin_inset ERT
22620 status Collapsed
22621
22622 \layout Standard
22623
22624 \backslash
22625 /
22626 \end_inset
22627
22628
22629 \family sans
22630 \series bold
22631 -debug ddd_example.c
22632 \family default
22633 \series default
22634
22635 \family sans
22636 \series bold
22637
22638 \newline
22639
22640 \family default
22641 \series default
22642
22643 \newline
22644 and DDD was invoked with
22645 \family sans
22646 \series bold
22647
22648 \newline
22649
22650 \newline
22651 ddd -debugger 'sdcdb -cpu 8032 ddd_example'
22652 \layout Subsection
22653
22654 Interfacing SDCDB with XEmacs
22655 \begin_inset LatexCommand \index{XEmacs}
22656
22657 \end_inset
22658
22659
22660 \begin_inset LatexCommand \index{Emacs}
22661
22662 \end_inset
22663
22664
22665 \layout Standard
22666
22667 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
22668  sdcdb.el and sdcdbsrc.el.
22669  These two files can be found in the $(prefix)/bin directory after the installat
22670 ion is complete.
22671  These files need to be loaded into XEmacs for the interface to work.
22672  This can be done at XEmacs startup time by inserting the following into
22673  your '.xemacs' file (which can be found in your HOME directory):
22674 \newline
22675
22676 \newline
22677
22678 \family typewriter
22679 (load-file sdcdbsrc.el)
22680 \family default
22681
22682 \newline
22683
22684 \newline
22685 .xemacs is a lisp file so the () around the command is REQUIRED.
22686  The files can also be loaded dynamically while XEmacs is running, set the
22687  environment variable 'EMACSLOADPATH' to the installation bin directory
22688  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
22689  To start the interface enter the following command:
22690 \newline
22691
22692 \newline
22693
22694 \family sans
22695 \series bold
22696 ESC-x sdcdbsrc
22697 \family default
22698 \series default
22699
22700 \newline
22701
22702 \newline
22703 You will prompted to enter the file name to be debugged.
22704
22705 \newline
22706
22707 \newline
22708 The command line options that are passed to the simulator directly are bound
22709  to default values in the file sdcdbsrc.el.
22710  The variables are listed below, these values maybe changed as required.
22711 \layout Itemize
22712
22713 sdcdbsrc-cpu-type '51
22714 \layout Itemize
22715
22716 sdcdbsrc-frequency '11059200
22717 \layout Itemize
22718
22719 sdcdbsrc-serial nil
22720 \layout Standard
22721
22722 The following is a list of key mapping for the debugger interface.
22723 \layout Standard
22724
22725 \SpecialChar ~
22726
22727 \family typewriter
22728
22729 \newline
22730 ;;\SpecialChar ~
22731 Current Listing ::
22732 \newline
22733 ;;key\SpecialChar ~
22734 \SpecialChar ~
22735 \SpecialChar ~
22736 \SpecialChar ~
22737 \SpecialChar ~
22738 \SpecialChar ~
22739 \SpecialChar ~
22740 \SpecialChar ~
22741 \SpecialChar ~
22742 \SpecialChar ~
22743 \SpecialChar ~
22744 \SpecialChar ~
22745 \SpecialChar ~
22746 \SpecialChar ~
22747 binding\SpecialChar ~
22748 \SpecialChar ~
22749 \SpecialChar ~
22750 \SpecialChar ~
22751 \SpecialChar ~
22752 \SpecialChar ~
22753 \SpecialChar ~
22754 \SpecialChar ~
22755 \SpecialChar ~
22756 \SpecialChar ~
22757 \SpecialChar ~
22758 \SpecialChar ~
22759 \SpecialChar ~
22760 \SpecialChar ~
22761 \SpecialChar ~
22762 \SpecialChar ~
22763 \SpecialChar ~
22764 \SpecialChar ~
22765 \SpecialChar ~
22766 \SpecialChar ~
22767 \SpecialChar ~
22768 \SpecialChar ~
22769 Comment
22770 \newline
22771 ;;---\SpecialChar ~
22772 \SpecialChar ~
22773 \SpecialChar ~
22774 \SpecialChar ~
22775 \SpecialChar ~
22776 \SpecialChar ~
22777 \SpecialChar ~
22778 \SpecialChar ~
22779 \SpecialChar ~
22780 \SpecialChar ~
22781 \SpecialChar ~
22782 \SpecialChar ~
22783 \SpecialChar ~
22784 \SpecialChar ~
22785 -------\SpecialChar ~
22786 \SpecialChar ~
22787 \SpecialChar ~
22788 \SpecialChar ~
22789 \SpecialChar ~
22790 \SpecialChar ~
22791 \SpecialChar ~
22792 \SpecialChar ~
22793 \SpecialChar ~
22794 \SpecialChar ~
22795 \SpecialChar ~
22796 \SpecialChar ~
22797 \SpecialChar ~
22798 \SpecialChar ~
22799 \SpecialChar ~
22800 \SpecialChar ~
22801 \SpecialChar ~
22802 \SpecialChar ~
22803 \SpecialChar ~
22804 \SpecialChar ~
22805 \SpecialChar ~
22806 \SpecialChar ~
22807 -------
22808 \newline
22809 ;;
22810 \newline
22811 ;;\SpecialChar ~
22812 n\SpecialChar ~
22813 \SpecialChar ~
22814 \SpecialChar ~
22815 \SpecialChar ~
22816 \SpecialChar ~
22817 \SpecialChar ~
22818 \SpecialChar ~
22819 \SpecialChar ~
22820 \SpecialChar ~
22821 \SpecialChar ~
22822 \SpecialChar ~
22823 \SpecialChar ~
22824 \SpecialChar ~
22825 \SpecialChar ~
22826 \SpecialChar ~
22827 sdcdb-next-from-src\SpecialChar ~
22828 \SpecialChar ~
22829 \SpecialChar ~
22830 \SpecialChar ~
22831 \SpecialChar ~
22832 \SpecialChar ~
22833 \SpecialChar ~
22834 \SpecialChar ~
22835 \SpecialChar ~
22836 \SpecialChar ~
22837 SDCDB next command
22838 \newline
22839 ;;\SpecialChar ~
22840 b\SpecialChar ~
22841 \SpecialChar ~
22842 \SpecialChar ~
22843 \SpecialChar ~
22844 \SpecialChar ~
22845 \SpecialChar ~
22846 \SpecialChar ~
22847 \SpecialChar ~
22848 \SpecialChar ~
22849 \SpecialChar ~
22850 \SpecialChar ~
22851 \SpecialChar ~
22852 \SpecialChar ~
22853 \SpecialChar ~
22854 \SpecialChar ~
22855 sdcdb-back-from-src\SpecialChar ~
22856 \SpecialChar ~
22857 \SpecialChar ~
22858 \SpecialChar ~
22859 \SpecialChar ~
22860 \SpecialChar ~
22861 \SpecialChar ~
22862 \SpecialChar ~
22863 \SpecialChar ~
22864 \SpecialChar ~
22865 SDCDB back command
22866 \newline
22867 ;;\SpecialChar ~
22868 c\SpecialChar ~
22869 \SpecialChar ~
22870 \SpecialChar ~
22871 \SpecialChar ~
22872 \SpecialChar ~
22873 \SpecialChar ~
22874 \SpecialChar ~
22875 \SpecialChar ~
22876 \SpecialChar ~
22877 \SpecialChar ~
22878 \SpecialChar ~
22879 \SpecialChar ~
22880 \SpecialChar ~
22881 \SpecialChar ~
22882 \SpecialChar ~
22883 sdcdb-cont-from-src\SpecialChar ~
22884 \SpecialChar ~
22885 \SpecialChar ~
22886 \SpecialChar ~
22887 \SpecialChar ~
22888 \SpecialChar ~
22889 \SpecialChar ~
22890 \SpecialChar ~
22891 \SpecialChar ~
22892 \SpecialChar ~
22893 SDCDB continue command
22894 \newline
22895 ;;\SpecialChar ~
22896 s\SpecialChar ~
22897 \SpecialChar ~
22898 \SpecialChar ~
22899 \SpecialChar ~
22900 \SpecialChar ~
22901 \SpecialChar ~
22902 \SpecialChar ~
22903 \SpecialChar ~
22904 \SpecialChar ~
22905 \SpecialChar ~
22906 \SpecialChar ~
22907 \SpecialChar ~
22908 \SpecialChar ~
22909 \SpecialChar ~
22910 \SpecialChar ~
22911 sdcdb-step-from-src\SpecialChar ~
22912 \SpecialChar ~
22913 \SpecialChar ~
22914 \SpecialChar ~
22915 \SpecialChar ~
22916 \SpecialChar ~
22917 \SpecialChar ~
22918 \SpecialChar ~
22919 \SpecialChar ~
22920 \SpecialChar ~
22921 SDCDB step command
22922 \newline
22923 ;;\SpecialChar ~
22924 ?\SpecialChar ~
22925 \SpecialChar ~
22926 \SpecialChar ~
22927 \SpecialChar ~
22928 \SpecialChar ~
22929 \SpecialChar ~
22930 \SpecialChar ~
22931 \SpecialChar ~
22932 \SpecialChar ~
22933 \SpecialChar ~
22934 \SpecialChar ~
22935 \SpecialChar ~
22936 \SpecialChar ~
22937 \SpecialChar ~
22938 \SpecialChar ~
22939 sdcdb-whatis-c-sexp\SpecialChar ~
22940 \SpecialChar ~
22941 \SpecialChar ~
22942 \SpecialChar ~
22943 \SpecialChar ~
22944 \SpecialChar ~
22945 \SpecialChar ~
22946 \SpecialChar ~
22947 \SpecialChar ~
22948 \SpecialChar ~
22949 SDCDB ptypecommand for data at
22950 \newline
22951 ;;\SpecialChar ~
22952 \SpecialChar ~
22953 \SpecialChar ~
22954 \SpecialChar ~
22955 \SpecialChar ~
22956 \SpecialChar ~
22957 \SpecialChar ~
22958 \SpecialChar ~
22959 \SpecialChar ~
22960 \SpecialChar ~
22961 \SpecialChar ~
22962 \SpecialChar ~
22963 \SpecialChar ~
22964 \SpecialChar ~
22965 \SpecialChar ~
22966 \SpecialChar ~
22967 \SpecialChar ~
22968 \SpecialChar ~
22969 \SpecialChar ~
22970 \SpecialChar ~
22971 \SpecialChar ~
22972 \SpecialChar ~
22973 \SpecialChar ~
22974 \SpecialChar ~
22975 \SpecialChar ~
22976 \SpecialChar ~
22977 \SpecialChar ~
22978 \SpecialChar ~
22979 \SpecialChar ~
22980 \SpecialChar ~
22981 \SpecialChar ~
22982 \SpecialChar ~
22983 \SpecialChar ~
22984 \SpecialChar ~
22985 \SpecialChar ~
22986 \SpecialChar ~
22987 \SpecialChar ~
22988 \SpecialChar ~
22989 \SpecialChar ~
22990 \SpecialChar ~
22991 \SpecialChar ~
22992 \SpecialChar ~
22993 \SpecialChar ~
22994 \SpecialChar ~
22995 \SpecialChar ~
22996 \SpecialChar ~
22997 \SpecialChar ~
22998 buffer point
22999 \newline
23000 ;;\SpecialChar ~
23001 x\SpecialChar ~
23002 \SpecialChar ~
23003 \SpecialChar ~
23004 \SpecialChar ~
23005 \SpecialChar ~
23006 \SpecialChar ~
23007 \SpecialChar ~
23008 \SpecialChar ~
23009 \SpecialChar ~
23010 \SpecialChar ~
23011 \SpecialChar ~
23012 \SpecialChar ~
23013 \SpecialChar ~
23014 \SpecialChar ~
23015 \SpecialChar ~
23016 sdcdbsrc-delete\SpecialChar ~
23017 \SpecialChar ~
23018 \SpecialChar ~
23019 \SpecialChar ~
23020 \SpecialChar ~
23021 \SpecialChar ~
23022 \SpecialChar ~
23023 \SpecialChar ~
23024 \SpecialChar ~
23025 \SpecialChar ~
23026 \SpecialChar ~
23027 \SpecialChar ~
23028 \SpecialChar ~
23029 \SpecialChar ~
23030 SDCDB Delete all breakpoints if no arg
23031 \newline
23032 ;;\SpecialChar ~
23033 \SpecialChar ~
23034 \SpecialChar ~
23035 \SpecialChar ~
23036 \SpecialChar ~
23037 \SpecialChar ~
23038 \SpecialChar ~
23039 \SpecialChar ~
23040 \SpecialChar ~
23041 \SpecialChar ~
23042 \SpecialChar ~
23043 \SpecialChar ~
23044 \SpecialChar ~
23045 \SpecialChar ~
23046 \SpecialChar ~
23047 \SpecialChar ~
23048 \SpecialChar ~
23049 \SpecialChar ~
23050 \SpecialChar ~
23051 \SpecialChar ~
23052 \SpecialChar ~
23053 \SpecialChar ~
23054 \SpecialChar ~
23055 \SpecialChar ~
23056 \SpecialChar ~
23057 \SpecialChar ~
23058 \SpecialChar ~
23059 \SpecialChar ~
23060 \SpecialChar ~
23061 \SpecialChar ~
23062 \SpecialChar ~
23063 \SpecialChar ~
23064 \SpecialChar ~
23065 \SpecialChar ~
23066 \SpecialChar ~
23067 \SpecialChar ~
23068 \SpecialChar ~
23069 \SpecialChar ~
23070 \SpecialChar ~
23071 \SpecialChar ~
23072 \SpecialChar ~
23073 \SpecialChar ~
23074 \SpecialChar ~
23075 \SpecialChar ~
23076 \SpecialChar ~
23077 \SpecialChar ~
23078 \SpecialChar ~
23079 given or delete arg (C-u arg x)
23080 \newline
23081 ;;\SpecialChar ~
23082 m\SpecialChar ~
23083 \SpecialChar ~
23084 \SpecialChar ~
23085 \SpecialChar ~
23086 \SpecialChar ~
23087 \SpecialChar ~
23088 \SpecialChar ~
23089 \SpecialChar ~
23090 \SpecialChar ~
23091 \SpecialChar ~
23092 \SpecialChar ~
23093 \SpecialChar ~
23094 \SpecialChar ~
23095 \SpecialChar ~
23096 \SpecialChar ~
23097 sdcdbsrc-frame\SpecialChar ~
23098 \SpecialChar ~
23099 \SpecialChar ~
23100 \SpecialChar ~
23101 \SpecialChar ~
23102 \SpecialChar ~
23103 \SpecialChar ~
23104 \SpecialChar ~
23105 \SpecialChar ~
23106 \SpecialChar ~
23107 \SpecialChar ~
23108 \SpecialChar ~
23109 \SpecialChar ~
23110 \SpecialChar ~
23111 \SpecialChar ~
23112 SDCDB Display current frame if no arg,
23113 \newline
23114 ;;\SpecialChar ~
23115 \SpecialChar ~
23116 \SpecialChar ~
23117 \SpecialChar ~
23118 \SpecialChar ~
23119 \SpecialChar ~
23120 \SpecialChar ~
23121 \SpecialChar ~
23122 \SpecialChar ~
23123 \SpecialChar ~
23124 \SpecialChar ~
23125 \SpecialChar ~
23126 \SpecialChar ~
23127 \SpecialChar ~
23128 \SpecialChar ~
23129 \SpecialChar ~
23130 \SpecialChar ~
23131 \SpecialChar ~
23132 \SpecialChar ~
23133 \SpecialChar ~
23134 \SpecialChar ~
23135 \SpecialChar ~
23136 \SpecialChar ~
23137 \SpecialChar ~
23138 \SpecialChar ~
23139 \SpecialChar ~
23140 \SpecialChar ~
23141 \SpecialChar ~
23142 \SpecialChar ~
23143 \SpecialChar ~
23144 \SpecialChar ~
23145 \SpecialChar ~
23146 \SpecialChar ~
23147 \SpecialChar ~
23148 \SpecialChar ~
23149 \SpecialChar ~
23150 \SpecialChar ~
23151 \SpecialChar ~
23152 \SpecialChar ~
23153 \SpecialChar ~
23154 \SpecialChar ~
23155 \SpecialChar ~
23156 \SpecialChar ~
23157 \SpecialChar ~
23158 \SpecialChar ~
23159 \SpecialChar ~
23160 \SpecialChar ~
23161 given or display frame arg
23162 \newline
23163 ;;\SpecialChar ~
23164 \SpecialChar ~
23165 \SpecialChar ~
23166 \SpecialChar ~
23167 \SpecialChar ~
23168 \SpecialChar ~
23169 \SpecialChar ~
23170 \SpecialChar ~
23171 \SpecialChar ~
23172 \SpecialChar ~
23173 \SpecialChar ~
23174 \SpecialChar ~
23175 \SpecialChar ~
23176 \SpecialChar ~
23177 \SpecialChar ~
23178 \SpecialChar ~
23179 \SpecialChar ~
23180 \SpecialChar ~
23181 \SpecialChar ~
23182 \SpecialChar ~
23183 \SpecialChar ~
23184 \SpecialChar ~
23185 \SpecialChar ~
23186 \SpecialChar ~
23187 \SpecialChar ~
23188 \SpecialChar ~
23189 \SpecialChar ~
23190 \SpecialChar ~
23191 \SpecialChar ~
23192 \SpecialChar ~
23193 \SpecialChar ~
23194 \SpecialChar ~
23195 \SpecialChar ~
23196 \SpecialChar ~
23197 \SpecialChar ~
23198 \SpecialChar ~
23199 \SpecialChar ~
23200 \SpecialChar ~
23201 \SpecialChar ~
23202 \SpecialChar ~
23203 \SpecialChar ~
23204 \SpecialChar ~
23205 \SpecialChar ~
23206 \SpecialChar ~
23207 \SpecialChar ~
23208 \SpecialChar ~
23209 \SpecialChar ~
23210 buffer point
23211 \newline
23212 ;;\SpecialChar ~
23213 !\SpecialChar ~
23214 \SpecialChar ~
23215 \SpecialChar ~
23216 \SpecialChar ~
23217 \SpecialChar ~
23218 \SpecialChar ~
23219 \SpecialChar ~
23220 \SpecialChar ~
23221 \SpecialChar ~
23222 \SpecialChar ~
23223 \SpecialChar ~
23224 \SpecialChar ~
23225 \SpecialChar ~
23226 \SpecialChar ~
23227 \SpecialChar ~
23228 sdcdbsrc-goto-sdcdb\SpecialChar ~
23229 \SpecialChar ~
23230 \SpecialChar ~
23231 \SpecialChar ~
23232 \SpecialChar ~
23233 \SpecialChar ~
23234 \SpecialChar ~
23235 \SpecialChar ~
23236 \SpecialChar ~
23237 \SpecialChar ~
23238 Goto the SDCDB output buffer
23239 \newline
23240 ;;\SpecialChar ~
23241 p\SpecialChar ~
23242 \SpecialChar ~
23243 \SpecialChar ~
23244 \SpecialChar ~
23245 \SpecialChar ~
23246 \SpecialChar ~
23247 \SpecialChar ~
23248 \SpecialChar ~
23249 \SpecialChar ~
23250 \SpecialChar ~
23251 \SpecialChar ~
23252 \SpecialChar ~
23253 \SpecialChar ~
23254 \SpecialChar ~
23255 \SpecialChar ~
23256 sdcdb-print-c-sexp\SpecialChar ~
23257 \SpecialChar ~
23258 \SpecialChar ~
23259 \SpecialChar ~
23260 \SpecialChar ~
23261 \SpecialChar ~
23262 \SpecialChar ~
23263 \SpecialChar ~
23264 \SpecialChar ~
23265 \SpecialChar ~
23266 \SpecialChar ~
23267 SDCDB print command for data at
23268 \newline
23269 ;;\SpecialChar ~
23270 \SpecialChar ~
23271 \SpecialChar ~
23272 \SpecialChar ~
23273 \SpecialChar ~
23274 \SpecialChar ~
23275 \SpecialChar ~
23276 \SpecialChar ~
23277 \SpecialChar ~
23278 \SpecialChar ~
23279 \SpecialChar ~
23280 \SpecialChar ~
23281 \SpecialChar ~
23282 \SpecialChar ~
23283 \SpecialChar ~
23284 \SpecialChar ~
23285 \SpecialChar ~
23286 \SpecialChar ~
23287 \SpecialChar ~
23288 \SpecialChar ~
23289 \SpecialChar ~
23290 \SpecialChar ~
23291 \SpecialChar ~
23292 \SpecialChar ~
23293 \SpecialChar ~
23294 \SpecialChar ~
23295 \SpecialChar ~
23296 \SpecialChar ~
23297 \SpecialChar ~
23298 \SpecialChar ~
23299 \SpecialChar ~
23300 \SpecialChar ~
23301 \SpecialChar ~
23302 \SpecialChar ~
23303 \SpecialChar ~
23304 \SpecialChar ~
23305 \SpecialChar ~
23306 \SpecialChar ~
23307 \SpecialChar ~
23308 \SpecialChar ~
23309 \SpecialChar ~
23310 \SpecialChar ~
23311 \SpecialChar ~
23312 \SpecialChar ~
23313 \SpecialChar ~
23314 \SpecialChar ~
23315 \SpecialChar ~
23316 buffer point
23317 \newline
23318 ;;\SpecialChar ~
23319 g\SpecialChar ~
23320 \SpecialChar ~
23321 \SpecialChar ~
23322 \SpecialChar ~
23323 \SpecialChar ~
23324 \SpecialChar ~
23325 \SpecialChar ~
23326 \SpecialChar ~
23327 \SpecialChar ~
23328 \SpecialChar ~
23329 \SpecialChar ~
23330 \SpecialChar ~
23331 \SpecialChar ~
23332 \SpecialChar ~
23333 \SpecialChar ~
23334 sdcdbsrc-goto-sdcdb\SpecialChar ~
23335 \SpecialChar ~
23336 \SpecialChar ~
23337 \SpecialChar ~
23338 \SpecialChar ~
23339 \SpecialChar ~
23340 \SpecialChar ~
23341 \SpecialChar ~
23342 \SpecialChar ~
23343 \SpecialChar ~
23344 Goto the SDCDB output buffer
23345 \newline
23346 ;;\SpecialChar ~
23347 t\SpecialChar ~
23348 \SpecialChar ~
23349 \SpecialChar ~
23350 \SpecialChar ~
23351 \SpecialChar ~
23352 \SpecialChar ~
23353 \SpecialChar ~
23354 \SpecialChar ~
23355 \SpecialChar ~
23356 \SpecialChar ~
23357 \SpecialChar ~
23358 \SpecialChar ~
23359 \SpecialChar ~
23360 \SpecialChar ~
23361 \SpecialChar ~
23362 sdcdbsrc-mode\SpecialChar ~
23363 \SpecialChar ~
23364 \SpecialChar ~
23365 \SpecialChar ~
23366 \SpecialChar ~
23367 \SpecialChar ~
23368 \SpecialChar ~
23369 \SpecialChar ~
23370 \SpecialChar ~
23371 \SpecialChar ~
23372 \SpecialChar ~
23373 \SpecialChar ~
23374 \SpecialChar ~
23375 \SpecialChar ~
23376 \SpecialChar ~
23377 \SpecialChar ~
23378 Toggles Sdcdbsrc mode (turns it off)
23379 \newline
23380 ;;
23381 \newline
23382 ;;\SpecialChar ~
23383 C-c\SpecialChar ~
23384 C-f\SpecialChar ~
23385 \SpecialChar ~
23386 \SpecialChar ~
23387 \SpecialChar ~
23388 \SpecialChar ~
23389 \SpecialChar ~
23390 \SpecialChar ~
23391 \SpecialChar ~
23392 \SpecialChar ~
23393 sdcdb-finish-from-src\SpecialChar ~
23394 \SpecialChar ~
23395 \SpecialChar ~
23396 \SpecialChar ~
23397 \SpecialChar ~
23398 \SpecialChar ~
23399 \SpecialChar ~
23400 \SpecialChar ~
23401 SDCDB finish command
23402 \newline
23403 ;;
23404 \newline
23405 ;;\SpecialChar ~
23406 C-x\SpecialChar ~
23407 SPC\SpecialChar ~
23408 \SpecialChar ~
23409 \SpecialChar ~
23410 \SpecialChar ~
23411 \SpecialChar ~
23412 \SpecialChar ~
23413 \SpecialChar ~
23414 \SpecialChar ~
23415 \SpecialChar ~
23416 sdcdb-break\SpecialChar ~
23417 \SpecialChar ~
23418 \SpecialChar ~
23419 \SpecialChar ~
23420 \SpecialChar ~
23421 \SpecialChar ~
23422 \SpecialChar ~
23423 \SpecialChar ~
23424 \SpecialChar ~
23425 \SpecialChar ~
23426 \SpecialChar ~
23427 \SpecialChar ~
23428 \SpecialChar ~
23429 \SpecialChar ~
23430 \SpecialChar ~
23431 \SpecialChar ~
23432 \SpecialChar ~
23433 \SpecialChar ~
23434 Set break for line with point
23435 \newline
23436 ;;\SpecialChar ~
23437 ESC\SpecialChar ~
23438 t\SpecialChar ~
23439 \SpecialChar ~
23440 \SpecialChar ~
23441 \SpecialChar ~
23442 \SpecialChar ~
23443 \SpecialChar ~
23444 \SpecialChar ~
23445 \SpecialChar ~
23446 \SpecialChar ~
23447 \SpecialChar ~
23448 \SpecialChar ~
23449 sdcdbsrc-mode\SpecialChar ~
23450 \SpecialChar ~
23451 \SpecialChar ~
23452 \SpecialChar ~
23453 \SpecialChar ~
23454 \SpecialChar ~
23455 \SpecialChar ~
23456 \SpecialChar ~
23457 \SpecialChar ~
23458 \SpecialChar ~
23459 \SpecialChar ~
23460 \SpecialChar ~
23461 \SpecialChar ~
23462 \SpecialChar ~
23463 \SpecialChar ~
23464 \SpecialChar ~
23465 Toggle Sdcdbsrc mode
23466 \newline
23467 ;;\SpecialChar ~
23468 ESC\SpecialChar ~
23469 m\SpecialChar ~
23470 \SpecialChar ~
23471 \SpecialChar ~
23472 \SpecialChar ~
23473 \SpecialChar ~
23474 \SpecialChar ~
23475 \SpecialChar ~
23476 \SpecialChar ~
23477 \SpecialChar ~
23478 \SpecialChar ~
23479 \SpecialChar ~
23480 sdcdbsrc-srcmode\SpecialChar ~
23481 \SpecialChar ~
23482 \SpecialChar ~
23483 \SpecialChar ~
23484 \SpecialChar ~
23485 \SpecialChar ~
23486 \SpecialChar ~
23487 \SpecialChar ~
23488 \SpecialChar ~
23489 \SpecialChar ~
23490 \SpecialChar ~
23491 \SpecialChar ~
23492 \SpecialChar ~
23493 Toggle list mode
23494 \newline
23495 ;;
23496 \newline
23497
23498 \layout Chapter
23499 \pagebreak_top
23500 TIPS
23501 \layout Standard
23502
23503 Here are a few guidelines that will help the compiler generate more efficient
23504  code, some of the tips are specific to this compiler others are generally
23505  good programming practice.
23506 \layout Itemize
23507
23508 Use the smallest data type to represent your data-value.
23509  If it is known in advance that the value is going to be less than 256 then
23510  use an 'unsigned char' instead of a 'short' or 'int'.
23511  Please note, that ANSI C requires both signed and unsigned chars to be
23512  promoted to 'signed int'
23513 \begin_inset LatexCommand \index{promotion to signed int}
23514
23515 \end_inset
23516
23517
23518 \begin_inset Marginal
23519 collapsed true
23520
23521 \layout Standard
23522
23523
23524 \series bold
23525 \SpecialChar ~
23526 !
23527 \end_inset
23528
23529  before doing any operation.
23530  This promotion
23531 \begin_inset LatexCommand \index{type promotion}
23532
23533 \end_inset
23534
23535
23536 \begin_inset LatexCommand \label{type promotion}
23537
23538 \end_inset
23539
23540  can be omitted, if the result is the same.
23541  The effect of the promotion rules together with the sign-extension is often
23542  surprising:
23543 \begin_deeper
23544 \layout Verse
23545
23546
23547 \family typewriter
23548 unsigned char uc = 0xfe;
23549 \newline
23550 if (uc * uc < 0) /* this is true! */
23551 \newline
23552 {
23553 \newline
23554 \SpecialChar ~
23555 \SpecialChar ~
23556 \SpecialChar ~
23557 \SpecialChar ~
23558 ....
23559 \newline
23560 }
23561 \layout Standard
23562
23563
23564 \family typewriter
23565 uc * uc
23566 \family default
23567  is evaluated as
23568 \family typewriter
23569 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
23570 \family default
23571 .
23572
23573 \newline
23574 Another one:
23575 \layout Verse
23576
23577
23578 \family typewriter
23579 (unsigned char) -12 / (signed char) -3 = ...
23580 \layout Standard
23581
23582 No, the result is not 4:
23583 \layout Verse
23584
23585
23586 \family typewriter
23587 (int) (unsigned char) -12 / (int) (signed char) -3 =
23588 \newline
23589 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
23590 \newline
23591 (int) 0x00f4 / (int) 0xfffd =
23592 \newline
23593 (int) 0x00f4 / (int) 0xfffd =
23594 \newline
23595 (int) 244 / (int) -3 =
23596 \newline
23597 (int) -81 = (int) 0xffaf;
23598 \layout Standard
23599
23600 Don't complain, that gcc gives you a different result.
23601  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
23602  Therefore the results are different.
23603 \newline
23604 From
23605 \begin_inset Quotes sld
23606 \end_inset
23607
23608 comp.lang.c FAQ
23609 \begin_inset Quotes srd
23610 \end_inset
23611
23612 :
23613 \layout Quote
23614
23615
23616 \emph on
23617 If well-defined overflow characteristics are important and negative values
23618  are not, or if you want to steer clear of sign-extension problems when
23619  manipulating bits or bytes, use one of the corresponding unsigned types.
23620  (Beware when mixing signed and unsigned values in expressions, though.)
23621 \newline
23622 Although character types (especially unsigned char) can be used as "tiny"
23623  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
23624 ble sign extension and increased code size.
23625 \end_deeper
23626 \layout Itemize
23627
23628 Use unsigned when it is known in advance that the value is not going to
23629  be negative.
23630  This helps especially if you are doing division or multiplication, bit-shifting
23631  or are using an array index.
23632 \layout Itemize
23633
23634 NEVER jump into a LOOP.
23635 \layout Itemize
23636
23637 Declare the variables to be local
23638 \begin_inset LatexCommand \index{local variables}
23639
23640 \end_inset
23641
23642  whenever possible, especially loop control variables (induction).
23643 \layout Itemize
23644
23645 Since the compiler does not always do implicit integral promotion, the programme
23646 r should do an explicit cast when integral promotion is required.
23647 \layout Itemize
23648
23649 Reducing the size of division, multiplication & modulus operations can reduce
23650  code size substantially.
23651  Take the following code for example.
23652 \begin_deeper
23653 \layout Verse
23654
23655
23656 \family typewriter
23657 foobar(unsigned int p1, unsigned char ch)
23658 \newline
23659 {
23660 \newline
23661 \SpecialChar ~
23662 \SpecialChar ~
23663 \SpecialChar ~
23664 \SpecialChar ~
23665 unsigned char ch1 = p1 % ch ;
23666 \newline
23667 \SpecialChar ~
23668 \SpecialChar ~
23669 \SpecialChar ~
23670 \SpecialChar ~
23671 ....
23672 \newline
23673 }
23674 \layout Standard
23675
23676 For the modulus operation the variable ch will be promoted to unsigned int
23677  first then the modulus operation will be performed (this will lead to a
23678  call to support routine _moduint()), and the result will be casted to a
23679  char.
23680  If the code is changed to
23681 \layout Verse
23682
23683
23684 \family typewriter
23685 foobar(unsigned int p1, unsigned char ch)
23686 \newline
23687 {
23688 \newline
23689 \SpecialChar ~
23690 \SpecialChar ~
23691 \SpecialChar ~
23692 \SpecialChar ~
23693 unsigned char ch1 = (unsigned char)p1 % ch ;
23694 \newline
23695 \SpecialChar ~
23696 \SpecialChar ~
23697 \SpecialChar ~
23698 \SpecialChar ~
23699 ....
23700 \newline
23701 }
23702 \layout Standard
23703
23704 It would substantially reduce the code generated (future versions of the
23705  compiler will be smart enough to detect such optimization opportunities).
23706 \end_deeper
23707 \layout Itemize
23708
23709 Have a look at the assembly listing to get a
23710 \begin_inset Quotes sld
23711 \end_inset
23712
23713 feeling
23714 \begin_inset Quotes srd
23715 \end_inset
23716
23717  for the code generation.
23718 \layout Section
23719
23720 Porting code from or to other compilers
23721 \begin_inset LatexCommand \label{sec:Porting-code-to-other-compilers}
23722
23723 \end_inset
23724
23725
23726 \layout Itemize
23727
23728 check whether endianness of the compilers differs and adapt where needed.
23729 \layout Itemize
23730
23731 check the device specific header files
23732 \begin_inset LatexCommand \index{Header files}
23733
23734 \end_inset
23735
23736
23737 \begin_inset LatexCommand \index{Include files}
23738
23739 \end_inset
23740
23741  for compiler specific syntax.
23742  Eventually include the file <compiler.h
23743 \begin_inset LatexCommand \index{compiler.h (include file)}
23744
23745 \end_inset
23746
23747 >
23748 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/device/include/mcs51/compiler.h?view=markup}
23749
23750 \end_inset
23751
23752  to allow using common header files.
23753  (see f.e.
23754  cc2510fx.h
23755 \begin_inset LatexCommand \url{http://svn.sourceforge.net/viewvc/sdcc/trunk/sdcc/device/include/mcs51/cc2510fx.h?view=markup}
23756
23757 \end_inset
23758
23759 ).
23760 \layout Itemize
23761
23762 check whether the startup code contains the correct initialization (watchdog,
23763  peripherals).
23764 \layout Itemize
23765
23766 check whether the sizes of short, int, long match.
23767 \layout Itemize
23768
23769 check if some 16 or 32 bit hardware registers require a specific addressing
23770  order (least significant or most significant byte first) and adapt if needed
23771  (
23772 \emph on
23773 first
23774 \emph default
23775  and
23776 \emph on
23777 last
23778 \emph default
23779  relate to time and not to lower/upper memory location here, so this is
23780
23781 \emph on
23782 not
23783 \emph default
23784  the same as endianness).
23785 \layout Itemize
23786
23787 check whether the keyword
23788 \emph on
23789 volatile
23790 \emph default
23791  is used where needed.
23792  The compilers might differ in their optimization characteristics (as different
23793  versions of the same compiler might also use more clever optimizations
23794  this is good idea anyway).
23795  See section
23796 \begin_inset LatexCommand \ref{sub:Common-interrupt-pitfall-volatile}
23797
23798 \end_inset
23799
23800 .
23801 \layout Itemize
23802
23803 check that the compilers are not told to supress warnings.
23804 \layout Itemize
23805
23806 check and convert compiler specific extensions (interrupts, memory areas,
23807  pragmas etc.).
23808 \layout Itemize
23809
23810 check for differences in type promotion.
23811  Especially check for math operations on
23812 \family typewriter
23813 char
23814 \family default
23815  or
23816 \family typewriter
23817 unsigned char
23818 \family default
23819  variables.
23820  For the sake of C99 compatibility SDCC will probably promote these to
23821 \family typewriter
23822 int
23823 \family default
23824  more often than other compilers.
23825  Eventually insert explicit casts to
23826 \family typewriter
23827 (char)
23828 \family default
23829 or
23830 \family typewriter
23831  (unsigned char)
23832 \family default
23833 .
23834  Also check that the ~\SpecialChar ~
23835 operator
23836 \begin_inset LatexCommand \index{\~\/ Operator}
23837
23838 \end_inset
23839
23840  is not used on
23841 \family typewriter
23842 bit
23843 \begin_inset LatexCommand \index{bit}
23844
23845 \end_inset
23846
23847
23848 \family default
23849  variables, use the !\SpecialChar ~
23850 operator instead.
23851  See sections
23852 \begin_inset LatexCommand \ref{type promotion}
23853
23854 \end_inset
23855
23856  and
23857 \begin_inset LatexCommand \ref{sec:Compatibility-with-previous}
23858
23859 \end_inset
23860
23861 .
23862 \layout Itemize
23863
23864 check the assembly code generated for interrupt routines (f.e.
23865  for calls to possibly non-reentrant library functions).
23866 \layout Itemize
23867
23868 check whether timing loops result in proper timing (or preferably consider
23869  a rewrite of the code with timer based delays instead).
23870 \layout Itemize
23871
23872 check for differences in printf parameters (some compilers push (va_arg
23873 \begin_inset LatexCommand \index{vararg, va\_arg}
23874
23875 \end_inset
23876
23877 ) char variables as
23878 \family typewriter
23879 int
23880 \family default
23881  others push them as
23882 \family typewriter
23883 char
23884 \family default
23885 .
23886  See section
23887 \begin_inset LatexCommand \ref{sec:Compatibility-with-previous}
23888
23889 \end_inset
23890
23891 ).
23892 \layout Itemize
23893
23894 check the resulting memory map
23895 \begin_inset LatexCommand \index{Memory map}
23896
23897 \end_inset
23898
23899 .
23900  Usage of different memory spaces: code, stack, data (for mcs51/ds390 additional
23901 ly idata, pdata, xdata).
23902  Eventually check if unexpected library functions are included.
23903 \layout Section
23904
23905 Tools
23906 \begin_inset LatexCommand \index{Tools}
23907
23908 \end_inset
23909
23910  included in the distribution
23911 \layout Standard
23912 \align left
23913
23914 \begin_inset  Tabular
23915 <lyxtabular version="3" rows="12" columns="3">
23916 <features>
23917 <column alignment="left" valignment="top" leftline="true" width="0pt">
23918 <column alignment="left" valignment="top" leftline="true" width="0pt">
23919 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
23920 <row topline="true" bottomline="true">
23921 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23922 \begin_inset Text
23923
23924 \layout Standard
23925
23926 Name
23927 \end_inset
23928 </cell>
23929 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23930 \begin_inset Text
23931
23932 \layout Standard
23933
23934 Purpose
23935 \end_inset
23936 </cell>
23937 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23938 \begin_inset Text
23939
23940 \layout Standard
23941
23942 Directory
23943 \end_inset
23944 </cell>
23945 </row>
23946 <row topline="true">
23947 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23948 \begin_inset Text
23949
23950 \layout Standard
23951
23952 ucSsim
23953 \end_inset
23954 </cell>
23955 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23956 \begin_inset Text
23957
23958 \layout Standard
23959
23960 Simulator for various architectures
23961 \end_inset
23962 </cell>
23963 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
23964 \begin_inset Text
23965
23966 \layout Standard
23967
23968 sdcc/sim/ucsim
23969 \end_inset
23970 </cell>
23971 </row>
23972 <row topline="true">
23973 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23974 \begin_inset Text
23975
23976 \layout Standard
23977
23978 keil2sdcc.pl
23979 \end_inset
23980 </cell>
23981 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
23982 \begin_inset Text
23983
23984 \layout Standard
23985
23986 header file
23987 \begin_inset LatexCommand \index{Header files}
23988
23989 \end_inset
23990
23991
23992 \begin_inset LatexCommand \index{Include files}
23993
23994 \end_inset
23995
23996  conversion
23997 \end_inset
23998 </cell>
23999 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24000 \begin_inset Text
24001
24002 \layout Standard
24003
24004 sdcc/support/scripts
24005 \end_inset
24006 </cell>
24007 </row>
24008 <row topline="true">
24009 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24010 \begin_inset Text
24011
24012 \layout Standard
24013
24014 mh2h.c
24015 \end_inset
24016 </cell>
24017 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24018 \begin_inset Text
24019
24020 \layout Standard
24021
24022 header file conversion
24023 \end_inset
24024 </cell>
24025 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24026 \begin_inset Text
24027
24028 \layout Standard
24029
24030 sdcc/support/scripts
24031 \end_inset
24032 </cell>
24033 </row>
24034 <row topline="true">
24035 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24036 \begin_inset Text
24037
24038 \layout Standard
24039
24040 as-gbz80
24041 \end_inset
24042 </cell>
24043 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24044 \begin_inset Text
24045
24046 \layout Standard
24047
24048 Assembler
24049 \end_inset
24050 </cell>
24051 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24052 \begin_inset Text
24053
24054 \layout Standard
24055
24056
24057 \family roman
24058 \series medium
24059 \shape up
24060 \size normal
24061 \emph off
24062 \bar no
24063 \noun off
24064 \color none
24065 sdcc/bin
24066 \end_inset
24067 </cell>
24068 </row>
24069 <row topline="true">
24070 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24071 \begin_inset Text
24072
24073 \layout Standard
24074
24075 as-z80
24076 \end_inset
24077 </cell>
24078 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24079 \begin_inset Text
24080
24081 \layout Standard
24082
24083 Assembler
24084 \end_inset
24085 </cell>
24086 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24087 \begin_inset Text
24088
24089 \layout Standard
24090
24091
24092 \family roman
24093 \series medium
24094 \shape up
24095 \size normal
24096 \emph off
24097 \bar no
24098 \noun off
24099 \color none
24100 sdcc/bin
24101 \end_inset
24102 </cell>
24103 </row>
24104 <row topline="true">
24105 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24106 \begin_inset Text
24107
24108 \layout Standard
24109
24110 asx8051
24111 \end_inset
24112 </cell>
24113 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24114 \begin_inset Text
24115
24116 \layout Standard
24117
24118 Assembler
24119 \end_inset
24120 </cell>
24121 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24122 \begin_inset Text
24123
24124 \layout Standard
24125
24126
24127 \family roman
24128 \series medium
24129 \shape up
24130 \size normal
24131 \emph off
24132 \bar no
24133 \noun off
24134 \color none
24135 sdcc/bin
24136 \end_inset
24137 </cell>
24138 </row>
24139 <row topline="true">
24140 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24141 \begin_inset Text
24142
24143 \layout Standard
24144
24145 SDCDB
24146 \end_inset
24147 </cell>
24148 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24149 \begin_inset Text
24150
24151 \layout Standard
24152
24153 Simulator
24154 \end_inset
24155 </cell>
24156 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24157 \begin_inset Text
24158
24159 \layout Standard
24160
24161
24162 \family roman
24163 \series medium
24164 \shape up
24165 \size normal
24166 \emph off
24167 \bar no
24168 \noun off
24169 \color none
24170 sdcc/bin
24171 \end_inset
24172 </cell>
24173 </row>
24174 <row topline="true">
24175 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24176 \begin_inset Text
24177
24178 \layout Standard
24179
24180 aslink
24181 \end_inset
24182 </cell>
24183 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24184 \begin_inset Text
24185
24186 \layout Standard
24187
24188 Linker
24189 \end_inset
24190 </cell>
24191 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24192 \begin_inset Text
24193
24194 \layout Standard
24195
24196
24197 \family roman
24198 \series medium
24199 \shape up
24200 \size normal
24201 \emph off
24202 \bar no
24203 \noun off
24204 \color none
24205 sdcc/bin
24206 \end_inset
24207 </cell>
24208 </row>
24209 <row topline="true">
24210 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24211 \begin_inset Text
24212
24213 \layout Standard
24214
24215 link-z80
24216 \end_inset
24217 </cell>
24218 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24219 \begin_inset Text
24220
24221 \layout Standard
24222
24223 Linker
24224 \end_inset
24225 </cell>
24226 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24227 \begin_inset Text
24228
24229 \layout Standard
24230
24231
24232 \family roman
24233 \series medium
24234 \shape up
24235 \size normal
24236 \emph off
24237 \bar no
24238 \noun off
24239 \color none
24240 sdcc/bin
24241 \end_inset
24242 </cell>
24243 </row>
24244 <row topline="true">
24245 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24246 \begin_inset Text
24247
24248 \layout Standard
24249
24250 link-gbz80
24251 \end_inset
24252 </cell>
24253 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24254 \begin_inset Text
24255
24256 \layout Standard
24257
24258 Linker
24259 \end_inset
24260 </cell>
24261 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24262 \begin_inset Text
24263
24264 \layout Standard
24265
24266
24267 \family roman
24268 \series medium
24269 \shape up
24270 \size normal
24271 \emph off
24272 \bar no
24273 \noun off
24274 \color none
24275 sdcc/bin
24276 \end_inset
24277 </cell>
24278 </row>
24279 <row topline="true" bottomline="true">
24280 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24281 \begin_inset Text
24282
24283 \layout Standard
24284
24285 packihx
24286 \end_inset
24287 </cell>
24288 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24289 \begin_inset Text
24290
24291 \layout Standard
24292
24293 Intel Hex packer
24294 \begin_inset LatexCommand \index{packihx (tool)}
24295
24296 \end_inset
24297
24298
24299 \end_inset
24300 </cell>
24301 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24302 \begin_inset Text
24303
24304 \layout Standard
24305
24306
24307 \family roman
24308 \series medium
24309 \shape up
24310 \size normal
24311 \emph off
24312 \bar no
24313 \noun off
24314 \color none
24315 sdcc/bin
24316 \end_inset
24317 </cell>
24318 </row>
24319 </lyxtabular>
24320
24321 \end_inset
24322
24323
24324 \newline
24325
24326 \layout Section
24327
24328 Documentation
24329 \begin_inset LatexCommand \index{Documentation}
24330
24331 \end_inset
24332
24333  included in the distribution
24334 \layout Standard
24335 \align left
24336
24337 \begin_inset  Tabular
24338 <lyxtabular version="3" rows="10" columns="2">
24339 <features>
24340 <column alignment="left" valignment="top" leftline="true" width="0">
24341 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
24342 <row topline="true" bottomline="true">
24343 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24344 \begin_inset Text
24345
24346 \layout Standard
24347
24348 Subject / Title
24349 \end_inset
24350 </cell>
24351 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24352 \begin_inset Text
24353
24354 \layout Standard
24355
24356 Where to get / filename
24357 \end_inset
24358 </cell>
24359 </row>
24360 <row topline="true">
24361 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24362 \begin_inset Text
24363
24364 \layout Standard
24365
24366 SDCC Compiler User Guide
24367 \end_inset
24368 </cell>
24369 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24370 \begin_inset Text
24371
24372 \layout Standard
24373
24374 You're reading it right now
24375 \end_inset
24376 </cell>
24377 </row>
24378 <row topline="true">
24379 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24380 \begin_inset Text
24381
24382 \layout Standard
24383
24384 Changelog of SDCC
24385 \end_inset
24386 </cell>
24387 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24388 \begin_inset Text
24389
24390 \layout Standard
24391
24392 sdcc/Changelog
24393 \end_inset
24394 </cell>
24395 </row>
24396 <row topline="true">
24397 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24398 \begin_inset Text
24399
24400 \layout Standard
24401
24402 ASXXXX
24403 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
24404
24405 \end_inset
24406
24407
24408 \begin_inset LatexCommand \index{Assembler documentation}
24409
24410 \end_inset
24411
24412  Assemblers and ASLINK
24413 \begin_inset LatexCommand \index{aslink}
24414
24415 \end_inset
24416
24417
24418 \begin_inset LatexCommand \index{Linker documentation}
24419
24420 \end_inset
24421
24422  Relocating Linker
24423 \end_inset
24424 </cell>
24425 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24426 \begin_inset Text
24427
24428 \layout Standard
24429
24430 sdcc/as/doc/asxhtm.html
24431 \end_inset
24432 </cell>
24433 </row>
24434 <row topline="true">
24435 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24436 \begin_inset Text
24437
24438 \layout Standard
24439
24440 SDCC regression test
24441 \begin_inset LatexCommand \index{Regression test}
24442
24443 \end_inset
24444
24445
24446 \end_inset
24447 </cell>
24448 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24449 \begin_inset Text
24450
24451 \layout Standard
24452
24453 sdcc/doc/test_suite_spec.pdf
24454 \end_inset
24455 </cell>
24456 </row>
24457 <row topline="true">
24458 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24459 \begin_inset Text
24460
24461 \layout Standard
24462
24463 Various notes
24464 \end_inset
24465 </cell>
24466 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24467 \begin_inset Text
24468
24469 \layout Standard
24470
24471 sdcc/doc/*
24472 \end_inset
24473 </cell>
24474 </row>
24475 <row topline="true">
24476 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24477 \begin_inset Text
24478
24479 \layout Standard
24480
24481 Notes on debugging with SDCDB
24482 \begin_inset LatexCommand \index{SDCDB (debugger)}
24483
24484 \end_inset
24485
24486
24487 \end_inset
24488 </cell>
24489 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24490 \begin_inset Text
24491
24492 \layout Standard
24493
24494 sdcc/debugger/README
24495 \end_inset
24496 </cell>
24497 </row>
24498 <row topline="true">
24499 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24500 \begin_inset Text
24501
24502 \layout Standard
24503
24504 Software simulator for microcontrollers
24505 \end_inset
24506 </cell>
24507 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24508 \begin_inset Text
24509
24510 \layout Standard
24511
24512
24513 \family roman
24514 \series medium
24515 \shape up
24516 \size normal
24517 \emph off
24518 \bar no
24519 \noun off
24520 \color none
24521 sdcc/sim/ucsim/doc
24522 \family default
24523 \series default
24524 \shape default
24525 \size default
24526 \emph default
24527 \bar default
24528 \noun default
24529 \color default
24530 /index.html
24531 \end_inset
24532 </cell>
24533 </row>
24534 <row topline="true">
24535 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24536 \begin_inset Text
24537
24538 \layout Standard
24539
24540 Temporary notes on the pic16
24541 \begin_inset LatexCommand \index{PIC16}
24542
24543 \end_inset
24544
24545  port
24546 \end_inset
24547 </cell>
24548 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24549 \begin_inset Text
24550
24551 \layout Standard
24552
24553 sdcc/src/pic16/NOTES
24554 \end_inset
24555 </cell>
24556 </row>
24557 <row topline="true" bottomline="true">
24558 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24559 \begin_inset Text
24560
24561 \layout Standard
24562
24563 SDCC internal documentation (debugging file format)
24564 \end_inset
24565 </cell>
24566 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24567 \begin_inset Text
24568
24569 \layout Standard
24570
24571 sdcc/doc/
24572 \family roman
24573 \series medium
24574 \shape up
24575 \size normal
24576 \emph off
24577 \bar no
24578 \noun off
24579 \color none
24580 cdbfileformat.pd
24581 \family default
24582 \series default
24583 \shape default
24584 \size default
24585 \emph default
24586 \bar default
24587 \noun default
24588 \color default
24589 f
24590 \end_inset
24591 </cell>
24592 </row>
24593 </lyxtabular>
24594
24595 \end_inset
24596
24597
24598 \newline
24599
24600 \layout Section
24601
24602 Related open source tools
24603 \begin_inset LatexCommand \label{sec:Related-open-source-tools}
24604
24605 \end_inset
24606
24607
24608 \begin_inset LatexCommand \index{Related tools}
24609
24610 \end_inset
24611
24612
24613 \layout Standard
24614 \align left
24615
24616 \begin_inset  Tabular
24617 <lyxtabular version="3" rows="14" columns="3">
24618 <features>
24619 <column alignment="left" valignment="top" leftline="true" width="0pt">
24620 <column alignment="block" valignment="top" leftline="true" width="30line%">
24621 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
24622 <row topline="true" bottomline="true">
24623 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24624 \begin_inset Text
24625
24626 \layout Standard
24627
24628 Name
24629 \end_inset
24630 </cell>
24631 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24632 \begin_inset Text
24633
24634 \layout Standard
24635
24636 Purpose
24637 \end_inset
24638 </cell>
24639 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24640 \begin_inset Text
24641
24642 \layout Standard
24643
24644 Where to get
24645 \end_inset
24646 </cell>
24647 </row>
24648 <row topline="true">
24649 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24650 \begin_inset Text
24651
24652 \layout Standard
24653
24654 gpsim
24655 \begin_inset LatexCommand \index{gpsim (pic simulator)}
24656
24657 \end_inset
24658
24659
24660 \end_inset
24661 </cell>
24662 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24663 \begin_inset Text
24664
24665 \layout Standard
24666
24667 PIC simulator
24668 \end_inset
24669 </cell>
24670 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24671 \begin_inset Text
24672
24673 \layout Standard
24674
24675
24676 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
24677
24678 \end_inset
24679
24680
24681 \end_inset
24682 </cell>
24683 </row>
24684 <row topline="true">
24685 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24686 \begin_inset Text
24687
24688 \layout Standard
24689
24690 gputils
24691 \begin_inset LatexCommand \index{gputils (pic tools)}
24692
24693 \end_inset
24694
24695
24696 \end_inset
24697 </cell>
24698 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24699 \begin_inset Text
24700
24701 \layout Standard
24702
24703 GNU PIC utilities
24704 \end_inset
24705 </cell>
24706 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24707 \begin_inset Text
24708
24709 \layout Standard
24710
24711
24712 \begin_inset LatexCommand \url{http://sourceforge.net/projects/gputils}
24713
24714 \end_inset
24715
24716
24717 \end_inset
24718 </cell>
24719 </row>
24720 <row topline="true">
24721 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24722 \begin_inset Text
24723
24724 \layout Standard
24725
24726 flP5
24727 \end_inset
24728 </cell>
24729 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24730 \begin_inset Text
24731
24732 \layout Standard
24733
24734 PIC programmer
24735 \end_inset
24736 </cell>
24737 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24738 \begin_inset Text
24739
24740 \layout Standard
24741
24742
24743 \begin_inset LatexCommand \url{http://freshmeat.net/projects/flp5/}
24744
24745 \end_inset
24746
24747
24748 \end_inset
24749 </cell>
24750 </row>
24751 <row topline="true">
24752 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24753 \begin_inset Text
24754
24755 \layout Standard
24756
24757 ec2drv/newcdb
24758 \end_inset
24759 </cell>
24760 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24761 \begin_inset Text
24762
24763 \layout Standard
24764
24765 Tools for Silicon Laboratories JTAG debug adapter, partly based on SDCDB
24766  (Unix only)
24767 \end_inset
24768 </cell>
24769 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24770 \begin_inset Text
24771
24772 \layout Standard
24773
24774
24775 \begin_inset LatexCommand \url{http://sourceforge.net/projects/ec2drv}
24776
24777 \end_inset
24778
24779
24780 \end_inset
24781 </cell>
24782 </row>
24783 <row topline="true">
24784 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24785 \begin_inset Text
24786
24787 \layout Standard
24788
24789 indent
24790 \begin_inset LatexCommand \index{indent (source formatting tool)}
24791
24792 \end_inset
24793
24794
24795 \end_inset
24796 </cell>
24797 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24798 \begin_inset Text
24799
24800 \layout Standard
24801
24802 Formats C source - Master of the white spaces
24803 \end_inset
24804 </cell>
24805 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24806 \begin_inset Text
24807
24808 \layout Standard
24809
24810
24811 \begin_inset LatexCommand \url{http://directory.fsf.org/GNU/indent.html}
24812
24813 \end_inset
24814
24815
24816 \end_inset
24817 </cell>
24818 </row>
24819 <row topline="true">
24820 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24821 \begin_inset Text
24822
24823 \layout Standard
24824
24825 srecord
24826 \begin_inset LatexCommand \index{srecord (bin, hex, ... tool)}
24827
24828 \end_inset
24829
24830
24831 \end_inset
24832 </cell>
24833 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24834 \begin_inset Text
24835
24836 \layout Standard
24837
24838 Object file conversion, checksumming, ...
24839 \end_inset
24840 </cell>
24841 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24842 \begin_inset Text
24843
24844 \layout Standard
24845
24846
24847 \begin_inset LatexCommand \url{http://sourceforge.net/projects/srecord}
24848
24849 \end_inset
24850
24851
24852 \end_inset
24853 </cell>
24854 </row>
24855 <row topline="true">
24856 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24857 \begin_inset Text
24858
24859 \layout Standard
24860
24861 objdump
24862 \begin_inset LatexCommand \index{objdump (tool)}
24863
24864 \end_inset
24865
24866
24867 \end_inset
24868 </cell>
24869 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24870 \begin_inset Text
24871
24872 \layout Standard
24873
24874 Object file conversion, ...
24875 \end_inset
24876 </cell>
24877 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24878 \begin_inset Text
24879
24880 \layout Standard
24881
24882 Part of binutils (should be there anyway)
24883 \end_inset
24884 </cell>
24885 </row>
24886 <row topline="true">
24887 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24888 \begin_inset Text
24889
24890 \layout Standard
24891
24892 cmon51
24893 \end_inset
24894 </cell>
24895 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24896 \begin_inset Text
24897
24898 \layout Standard
24899
24900 8051 monitor (hex up-/download, single step, disassemble)
24901 \end_inset
24902 </cell>
24903 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24904 \begin_inset Text
24905
24906 \layout Standard
24907
24908
24909 \begin_inset LatexCommand \url{http://sourceforge.net/projects/cmon51}
24910
24911 \end_inset
24912
24913
24914 \end_inset
24915 </cell>
24916 </row>
24917 <row topline="true">
24918 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24919 \begin_inset Text
24920
24921 \layout Standard
24922
24923 doxygen
24924 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
24925
24926 \end_inset
24927
24928
24929 \end_inset
24930 </cell>
24931 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24932 \begin_inset Text
24933
24934 \layout Standard
24935
24936 Source code documentation system
24937 \end_inset
24938 </cell>
24939 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24940 \begin_inset Text
24941
24942 \layout Standard
24943
24944
24945 \begin_inset LatexCommand \url{http://www.doxygen.org}
24946
24947 \end_inset
24948
24949
24950 \end_inset
24951 </cell>
24952 </row>
24953 <row topline="true">
24954 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24955 \begin_inset Text
24956
24957 \layout Standard
24958
24959 kdevelop
24960 \end_inset
24961 </cell>
24962 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24963 \begin_inset Text
24964
24965 \layout Standard
24966
24967 IDE (has anyone tried integrating SDCC & SDCDB? Unix only)
24968 \end_inset
24969 </cell>
24970 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
24971 \begin_inset Text
24972
24973 \layout Standard
24974
24975
24976 \begin_inset LatexCommand \url{http://www.kdevelop.org}
24977
24978 \end_inset
24979
24980
24981 \end_inset
24982 </cell>
24983 </row>
24984 <row topline="true">
24985 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24986 \begin_inset Text
24987
24988 \layout Standard
24989
24990 paulmon
24991 \end_inset
24992 </cell>
24993 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
24994 \begin_inset Text
24995
24996 \layout Standard
24997
24998 8051 monitor (hex up-/download, single step, disassemble)
24999 \end_inset
25000 </cell>
25001 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25002 \begin_inset Text
25003
25004 \layout Standard
25005
25006
25007 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/paulmon2.html}
25008
25009 \end_inset
25010
25011
25012 \end_inset
25013 </cell>
25014 </row>
25015 <row topline="true">
25016 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25017 \begin_inset Text
25018
25019 \layout Standard
25020
25021 splint
25022 \begin_inset LatexCommand \index{splint (syntax checking tool)}
25023
25024 \end_inset
25025
25026
25027 \end_inset
25028 </cell>
25029 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25030 \begin_inset Text
25031
25032 \layout Standard
25033
25034 Statically checks c sources (see
25035 \begin_inset LatexCommand \ref{lyx:more-pedantic-SPLINT}
25036
25037 \end_inset
25038
25039 )
25040 \end_inset
25041 </cell>
25042 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25043 \begin_inset Text
25044
25045 \layout Standard
25046
25047
25048 \begin_inset LatexCommand \url{http://www.splint.org}
25049
25050 \end_inset
25051
25052
25053 \end_inset
25054 </cell>
25055 </row>
25056 <row topline="true" bottomline="true">
25057 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25058 \begin_inset Text
25059
25060 \layout Standard
25061
25062 ddd
25063 \begin_inset LatexCommand \index{DDD (debugger)}
25064
25065 \end_inset
25066
25067
25068 \end_inset
25069 </cell>
25070 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25071 \begin_inset Text
25072
25073 \layout Standard
25074
25075 Debugger, serves nicely as GUI to SDCDB
25076 \begin_inset LatexCommand \index{SDCDB (debugger)}
25077
25078 \end_inset
25079
25080  (Unix only)
25081 \end_inset
25082 </cell>
25083 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25084 \begin_inset Text
25085
25086 \layout Standard
25087
25088
25089 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
25090
25091 \end_inset
25092
25093
25094 \end_inset
25095 </cell>
25096 </row>
25097 </lyxtabular>
25098
25099 \end_inset
25100
25101
25102 \newline
25103
25104 \layout Section
25105
25106 Related documentation / recommended reading
25107 \layout Standard
25108 \align left
25109
25110 \begin_inset  Tabular
25111 <lyxtabular version="3" rows="7" columns="3">
25112 <features>
25113 <column alignment="left" valignment="top" leftline="true" width="0pt">
25114 <column alignment="center" valignment="top" leftline="true" width="0">
25115 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
25116 <row topline="true" bottomline="true">
25117 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25118 \begin_inset Text
25119
25120 \layout Standard
25121
25122 Name
25123 \end_inset
25124 </cell>
25125 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25126 \begin_inset Text
25127
25128 \layout Standard
25129
25130 Subject / Title
25131 \end_inset
25132 </cell>
25133 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25134 \begin_inset Text
25135
25136 \layout Standard
25137
25138 Where to get
25139 \end_inset
25140 </cell>
25141 </row>
25142 <row topline="true">
25143 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25144 \begin_inset Text
25145
25146 \layout Standard
25147
25148
25149 \family roman
25150 \series medium
25151 \shape up
25152 \size normal
25153 \emph off
25154 \bar no
25155 \noun off
25156 \color none
25157 c-refcard.pdf
25158 \end_inset
25159 </cell>
25160 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25161 \begin_inset Text
25162
25163 \layout Standard
25164
25165 C Reference Card
25166 \begin_inset LatexCommand \index{C Reference card}
25167
25168 \end_inset
25169
25170 , 2 pages
25171 \end_inset
25172 </cell>
25173 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25174 \begin_inset Text
25175
25176 \layout Standard
25177
25178
25179 \begin_inset LatexCommand \url{http://refcards.com/refcards/c/index.html}
25180
25181 \end_inset
25182
25183
25184 \end_inset
25185 </cell>
25186 </row>
25187 <row topline="true">
25188 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25189 \begin_inset Text
25190
25191 \layout Standard
25192
25193 c-faq
25194 \end_inset
25195 </cell>
25196 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25197 \begin_inset Text
25198
25199 \layout Standard
25200
25201 C-FAQ
25202 \begin_inset LatexCommand \index{C FAQ}
25203
25204 \end_inset
25205
25206
25207 \end_inset
25208 </cell>
25209 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25210 \begin_inset Text
25211
25212 \layout Standard
25213
25214
25215 \begin_inset LatexCommand \url{http://www.c-faq.com}
25216
25217 \end_inset
25218
25219
25220 \end_inset
25221 </cell>
25222 </row>
25223 <row topline="true">
25224 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25225 \begin_inset Text
25226
25227 \layout Standard
25228
25229 ISO/IEC 9899:TC2
25230 \end_inset
25231 </cell>
25232 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25233 \begin_inset Text
25234
25235 \layout Standard
25236
25237
25238 \begin_inset Quotes sld
25239 \end_inset
25240
25241 C-Standard
25242 \begin_inset Quotes srd
25243 \end_inset
25244
25245
25246 \end_inset
25247 </cell>
25248 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25249 \begin_inset Text
25250
25251 \layout Standard
25252
25253
25254 \size footnotesize
25255
25256 \begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899}
25257
25258 \end_inset
25259
25260
25261 \end_inset
25262 </cell>
25263 </row>
25264 <row topline="true">
25265 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25266 \begin_inset Text
25267
25268 \layout Standard
25269
25270 ISO/IEC DTR 18037
25271 \end_inset
25272 </cell>
25273 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25274 \begin_inset Text
25275
25276 \layout Standard
25277
25278
25279 \begin_inset Quotes sld
25280 \end_inset
25281
25282 Extensions for Embedded C
25283 \begin_inset Quotes srd
25284 \end_inset
25285
25286
25287 \end_inset
25288 </cell>
25289 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25290 \begin_inset Text
25291
25292 \layout Standard
25293
25294
25295 \size footnotesize
25296
25297 \begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1021.pdf}
25298
25299 \end_inset
25300
25301
25302 \end_inset
25303 </cell>
25304 </row>
25305 <row topline="true">
25306 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25307 \begin_inset Text
25308
25309 \layout Standard
25310
25311 \end_inset
25312 </cell>
25313 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25314 \begin_inset Text
25315
25316 \layout Standard
25317
25318 Latest datasheet of target CPU
25319 \end_inset
25320 </cell>
25321 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25322 \begin_inset Text
25323
25324 \layout Standard
25325
25326 vendor
25327 \end_inset
25328 </cell>
25329 </row>
25330 <row topline="true" bottomline="true">
25331 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25332 \begin_inset Text
25333
25334 \layout Standard
25335
25336 \end_inset
25337 </cell>
25338 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25339 \begin_inset Text
25340
25341 \layout Standard
25342
25343 Revision history of datasheet
25344 \end_inset
25345 </cell>
25346 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25347 \begin_inset Text
25348
25349 \layout Standard
25350
25351 vendor
25352 \end_inset
25353 </cell>
25354 </row>
25355 </lyxtabular>
25356
25357 \end_inset
25358
25359
25360 \newline
25361
25362 \layout Section
25363
25364 Application notes specifically for SDCC
25365 \layout Standard
25366
25367 SDCC makes no claims about the completeness of this list and about up-to-datenes
25368 s or correctness of the application notes
25369 \begin_inset LatexCommand \index{Application notes}
25370
25371 \end_inset
25372
25373 .
25374 \layout Standard
25375 \align left
25376
25377 \size footnotesize
25378
25379 \begin_inset  Tabular
25380 <lyxtabular version="3" rows="7" columns="3">
25381 <features>
25382 <column alignment="block" valignment="top" leftline="true" width="17col%">
25383 <column alignment="block" valignment="top" leftline="true" width="27col%">
25384 <column alignment="block" valignment="top" leftline="true" rightline="true" width="57col%">
25385 <row topline="true" bottomline="true">
25386 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25387 \begin_inset Text
25388
25389 \layout Standard
25390
25391
25392 \size footnotesize
25393 Vendor
25394 \end_inset
25395 </cell>
25396 <cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
25397 \begin_inset Text
25398
25399 \layout Standard
25400
25401
25402 \size footnotesize
25403 Subject / Title
25404 \end_inset
25405 </cell>
25406 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25407 \begin_inset Text
25408
25409 \layout Standard
25410
25411
25412 \size footnotesize
25413 Where to get
25414 \end_inset
25415 </cell>
25416 </row>
25417 <row topline="true">
25418 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25419 \begin_inset Text
25420
25421 \layout Standard
25422
25423
25424 \size footnotesize
25425 Maxim / Dallas
25426 \end_inset
25427 </cell>
25428 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25429 \begin_inset Text
25430
25431 \layout Standard
25432
25433
25434 \size footnotesize
25435 Using the SDCC Compiler for the DS80C400
25436 \begin_inset LatexCommand \index{DS80C400}
25437
25438 \end_inset
25439
25440
25441 \end_inset
25442 </cell>
25443 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25444 \begin_inset Text
25445
25446 \layout Standard
25447
25448
25449 \size footnotesize
25450
25451 \begin_inset LatexCommand \url{http://pdfserv.maxim-ic.com/en/an/AN3346.pdf}
25452
25453 \end_inset
25454
25455
25456 \end_inset
25457 </cell>
25458 </row>
25459 <row topline="true">
25460 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25461 \begin_inset Text
25462
25463 \layout Standard
25464
25465
25466 \size footnotesize
25467 Maxim / Dallas
25468 \end_inset
25469 </cell>
25470 <cell multicolumn="1" alignment="left" valignment="top" topline="true" leftline="true" usebox="none" width="30line%">
25471 \begin_inset Text
25472
25473 \layout Standard
25474
25475
25476 \size footnotesize
25477 Using the Free SDCC C Compiler to Develop Firmware for the DS89C420/430/440/450
25478 \begin_inset LatexCommand \index{DS89C4x0}
25479
25480 \end_inset
25481
25482  Family of Microcontrollers
25483 \end_inset
25484 </cell>
25485 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25486 \begin_inset Text
25487
25488 \layout Standard
25489
25490
25491 \size footnotesize
25492
25493 \begin_inset LatexCommand \url{http://pdfserv.maxim-ic.com/en/an/AN3477.pdf}
25494
25495 \end_inset
25496
25497
25498 \end_inset
25499 </cell>
25500 </row>
25501 <row topline="true">
25502 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25503 \begin_inset Text
25504
25505 \layout Standard
25506
25507
25508 \size footnotesize
25509 Silicon Laboratories / Cygnal
25510 \end_inset
25511 </cell>
25512 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25513 \begin_inset Text
25514
25515 \layout Standard
25516
25517
25518 \size footnotesize
25519 Integrating SDCC 8051 Tools Into The Silicon Labs IDE
25520 \begin_inset LatexCommand \index{IDE}
25521
25522 \end_inset
25523
25524
25525 \end_inset
25526 </cell>
25527 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25528 \begin_inset Text
25529
25530 \layout Standard
25531
25532
25533 \size footnotesize
25534
25535 \begin_inset LatexCommand \url{http://www.silabs.com/public/documents/tpub_doc/anote/Microcontrollers/en/an198.pdf}
25536
25537 \end_inset
25538
25539
25540 \end_inset
25541 </cell>
25542 </row>
25543 <row topline="true">
25544 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25545 \begin_inset Text
25546
25547 \layout Standard
25548
25549
25550 \size footnotesize
25551 Ramtron / Goal Semiconductor
25552 \end_inset
25553 </cell>
25554 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25555 \begin_inset Text
25556
25557 \layout Standard
25558
25559
25560 \size footnotesize
25561 Interfacing SDCC to Syn and Textpad
25562 \end_inset
25563 </cell>
25564 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25565 \begin_inset Text
25566
25567 \layout Standard
25568
25569
25570 \size footnotesize
25571
25572 \begin_inset LatexCommand \url{http://www.ramtron.com/doc/Products/Microcontroller/Support_Tools.asp}
25573
25574 \end_inset
25575
25576
25577 \end_inset
25578 </cell>
25579 </row>
25580 <row topline="true">
25581 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25582 \begin_inset Text
25583
25584 \layout Standard
25585
25586
25587 \size footnotesize
25588 Ramtron / Goal Semiconductor
25589 \end_inset
25590 </cell>
25591 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25592 \begin_inset Text
25593
25594 \layout Standard
25595
25596
25597 \size footnotesize
25598 Installing and Configuring SDCC and Crimson Editor
25599 \end_inset
25600 </cell>
25601 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25602 \begin_inset Text
25603
25604 \layout Standard
25605
25606
25607 \size footnotesize
25608
25609 \begin_inset LatexCommand \url{http://www.ramtron.com/doc/Products/Microcontroller/Support_Tools.asp}
25610
25611 \end_inset
25612
25613
25614 \end_inset
25615 </cell>
25616 </row>
25617 <row topline="true" bottomline="true">
25618 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25619 \begin_inset Text
25620
25621 \layout Standard
25622
25623
25624 \size footnotesize
25625 Texas Instruments
25626 \end_inset
25627 </cell>
25628 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
25629 \begin_inset Text
25630
25631 \layout Standard
25632
25633
25634 \size footnotesize
25635 MSC12xx Programming with SDCC
25636 \end_inset
25637 </cell>
25638 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
25639 \begin_inset Text
25640
25641 \layout Standard
25642
25643
25644 \size footnotesize
25645
25646 \begin_inset LatexCommand \url{http://focus.ti.com/general/docs/lit/getliterature.tsp?literatureNumber=sbaa109&fileType=pdf}
25647
25648 \end_inset
25649
25650
25651 \end_inset
25652 </cell>
25653 </row>
25654 </lyxtabular>
25655
25656 \end_inset
25657
25658
25659 \layout Section
25660
25661 Some Questions
25662 \layout Standard
25663
25664 Some questions answered, some pointers given - it might be time to in turn
25665  ask
25666 \emph on
25667 you
25668 \emph default
25669  some questions:
25670 \layout Itemize
25671
25672 can you solve your project with the selected microcontroller? Would you
25673  find out early or rather late that your target is too small/slow/whatever?
25674  Can you switch to a slightly better device if it doesn't fit?
25675 \layout Itemize
25676
25677 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
25678  and/or another programming language be more adequate? Would an operating
25679  system on the target device help?
25680 \layout Itemize
25681
25682 if you solved the problem, will the marketing department be happy?
25683 \layout Itemize
25684
25685 if the marketing department is happy, will customers be happy?
25686 \layout Itemize
25687
25688 if you're the project manager, marketing department and maybe even the customer
25689  in one person, have you tried to see the project from the outside?
25690 \layout Itemize
25691
25692 is the project done if you think it is done? Or is just that other interface/pro
25693 tocol/feature/configuration/option missing? How about website, manual(s),
25694  internationali(z|s)ation, packaging, labels, 2nd source for components,
25695  electromagnetic compatability/interference, documentation for production,
25696  production test software, update mechanism, patent issues?
25697 \layout Itemize
25698
25699 is your project adequately positioned in that magic triangle: fame, fortune,
25700  fun?
25701 \layout Standard
25702
25703 Maybe not all answers to these questions are known and some answers may
25704  even be
25705 \emph on
25706 no
25707 \emph default
25708 , nevertheless knowing these questions may help you to avoid burnout
25709 \begin_inset Foot
25710 collapsed false
25711
25712 \layout Standard
25713
25714 burnout is bad for electronic devices, programmers and motorcycle tyres
25715 \end_inset
25716
25717 .
25718  Chances are you didn't want to hear some of them...
25719 \layout Chapter
25720
25721 Support
25722 \begin_inset LatexCommand \index{Support}
25723
25724 \end_inset
25725
25726
25727 \layout Standard
25728
25729 SDCC has grown to be a large project.
25730  The compiler alone (without the preprocessor, assembler and linker) is
25731  well over 150,000 lines of code (blank stripped).
25732  The open source nature of this project is a key to its continued growth
25733  and support.
25734  You gain the benefit and support of many active software developers and
25735  end users.
25736  Is SDCC perfect? No, that's why we need your help.
25737  The developers take pride in fixing reported bugs.
25738  You can help by reporting the bugs and helping other SDCC users.
25739  There are lots of ways to contribute, and we encourage you to take part
25740  in making SDCC a great software package.
25741
25742 \layout Standard
25743
25744 The SDCC project is hosted on the SDCC sourceforge site at
25745 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
25746
25747 \end_inset
25748
25749 .
25750  You'll find the complete set of mailing lists
25751 \begin_inset LatexCommand \index{Mailing list(s)}
25752
25753 \end_inset
25754
25755 , forums, bug reporting system, patch submission
25756 \begin_inset LatexCommand \index{Patch submission}
25757
25758 \end_inset
25759
25760  system, download
25761 \begin_inset LatexCommand \index{download}
25762
25763 \end_inset
25764
25765  area and Subversion code repository
25766 \begin_inset LatexCommand \index{Subversion code repository}
25767
25768 \end_inset
25769
25770  there.
25771 \layout Section
25772
25773 Reporting Bugs
25774 \begin_inset LatexCommand \index{Bug reporting}
25775
25776 \end_inset
25777
25778
25779 \begin_inset LatexCommand \index{Reporting bugs}
25780
25781 \end_inset
25782
25783
25784 \layout Standard
25785
25786 The recommended way of reporting bugs is using the infrastructure of the
25787  sourceforge site.
25788  You can follow the status of bug reports there and have an overview about
25789  the known bugs.
25790 \layout Standard
25791
25792 Bug reports are automatically forwarded to the developer mailing list and
25793  will be fixed ASAP.
25794  When reporting a bug, it is very useful to include a small test program
25795  (the smaller the better) which reproduces the problem.
25796  If you can isolate the problem by looking at the generated assembly code,
25797  this can be very helpful.
25798  Compiling your program with the -
25799 \begin_inset ERT
25800 status Collapsed
25801
25802 \layout Standard
25803
25804 \backslash
25805 /
25806 \end_inset
25807
25808 -dumpall
25809 \begin_inset LatexCommand \index{-\/-dumpall}
25810
25811 \end_inset
25812
25813  option can sometimes be useful in locating optimization problems.
25814  When reporting a bug please make sure you:
25815 \layout Enumerate
25816
25817 Attach the code you are compiling with SDCC.
25818
25819 \layout Enumerate
25820
25821 Specify the exact command you use to run SDCC, or attach your Makefile.
25822
25823 \layout Enumerate
25824
25825 Specify the SDCC version (type "
25826 \family sans
25827 \series bold
25828 sdcc -v
25829 \family default
25830 \series default
25831 "), your platform, and operating system.
25832
25833 \layout Enumerate
25834
25835 Provide an exact copy of any error message or incorrect output.
25836
25837 \layout Enumerate
25838
25839 Put something meaningful in the subject of your message.
25840 \layout Standard
25841
25842 Please attempt to include these 5 important parts, as applicable, in all
25843  requests for support or when reporting any problems or bugs with SDCC.
25844  Though this will make your message lengthy, it will greatly improve your
25845  chance that SDCC users and developers will be able to help you.
25846  Some SDCC developers are frustrated by bug reports without code provided
25847  that they can use to reproduce and ultimately fix the problem, so please
25848  be sure to provide sample code if you are reporting a bug!
25849 \layout Standard
25850
25851 Please have a short check that you are using a recent version of SDCC and
25852  the bug is not yet known.
25853  This is the link for reporting bugs:
25854 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
25855
25856 \end_inset
25857
25858 .
25859  With SDCC on average having more than 200 downloads
25860 \begin_inset LatexCommand \index{download}
25861
25862 \end_inset
25863
25864  on sourceforge per day
25865 \begin_inset Foot
25866 collapsed false
25867
25868 \layout Standard
25869
25870 220 daily downloads on average Jan-Sept 2006 and about 150 daily downloads
25871  between 2002 and 2005.
25872  This does not include other methods of distribution.
25873 \end_inset
25874
25875  there must be some users.
25876  So it's not exactly easy to find a new bug.
25877  If you find one we need it:
25878 \emph on
25879 reporting bugs is good
25880 \emph default
25881 .
25882 \layout Section
25883
25884 Requesting Features
25885 \begin_inset LatexCommand \label{sub:Requesting-Features}
25886
25887 \end_inset
25888
25889
25890 \begin_inset LatexCommand \index{Feature request}
25891
25892 \end_inset
25893
25894
25895 \begin_inset LatexCommand \index{Requesting features}
25896
25897 \end_inset
25898
25899
25900 \layout Standard
25901
25902 Like bug reports feature requests are forwarded to the developer mailing
25903  list.
25904  This is the link for requesting features:
25905 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
25906
25907 \end_inset
25908
25909 .
25910 \layout Section
25911
25912 Submitting patches
25913 \layout Standard
25914
25915 Like bug reports contributed patches are forwarded to the developer mailing
25916  list.
25917  This is the link for submitting patches
25918 \begin_inset LatexCommand \index{Patch submission}
25919
25920 \end_inset
25921
25922 :
25923 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
25924
25925 \end_inset
25926
25927 .
25928 \layout Standard
25929
25930 You need to specify some parameters to the
25931 \family typewriter
25932 diff
25933 \family default
25934  command for the patches to be useful.
25935  If you modified more than one file a patch created f.e.
25936  with
25937 \family sans
25938 \series bold
25939
25940 \begin_inset Quotes sld
25941 \end_inset
25942
25943 diff -Naur unmodified_directory modified_directory >my_changes.patch
25944 \begin_inset Quotes srd
25945 \end_inset
25946
25947
25948 \family default
25949 \series default
25950  will be fine, otherwise
25951 \family sans
25952 \series bold
25953
25954 \begin_inset Quotes sld
25955 \end_inset
25956
25957 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
25958 \begin_inset Quotes srd
25959 \end_inset
25960
25961
25962 \series default
25963
25964 \family default
25965 will do.
25966 \layout Section
25967
25968 Getting Help
25969 \layout Standard
25970
25971 These links should take you directly to the
25972 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
25973
25974 \end_inset
25975
25976
25977 \begin_inset Foot
25978 collapsed false
25979
25980 \layout Standard
25981
25982 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
25983  automated messages (mid 2003)
25984 \end_inset
25985
25986  and the
25987 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
25988
25989 \end_inset
25990
25991 , lists
25992 \begin_inset LatexCommand \index{Mailing list(s)}
25993
25994 \end_inset
25995
25996  and forums are archived and searchable so if you are lucky someone already
25997  had a similar problem.
25998  While mails to the lists themselves are delivered promptly their web front
25999  end on sourceforge sometimes shows a severe time lag (up to several weeks),
26000  if you're seriously using SDCC please consider subscribing to the lists.
26001 \layout Section
26002
26003 ChangeLog
26004 \layout Standard
26005
26006 You can follow the status of the Subversion version
26007 \begin_inset LatexCommand \index{version}
26008
26009 \end_inset
26010
26011  of SDCC by watching the Changelog
26012 \begin_inset LatexCommand \index{Changelog}
26013
26014 \end_inset
26015
26016  in the Subversion repository
26017 \size footnotesize
26018
26019 \begin_inset LatexCommand \htmlurl{http://svn.sourceforge.net/viewcvs.cgi/*checkout*/sdcc/trunk/sdcc/ChangeLog}
26020
26021 \end_inset
26022
26023 .
26024 \layout Section
26025
26026 Subversion Source Code Repository
26027 \layout Standard
26028
26029 The output of
26030 \family sans
26031 \series bold
26032 sdcc --version
26033 \family default
26034 \series default
26035  or the filenames of the snapshot versions of SDCC include date and its
26036  Subversion
26037 \begin_inset LatexCommand \index{Subversion code repository}
26038
26039 \end_inset
26040
26041  number.
26042  Subversion allows to download the source of recent or previous versions
26043
26044 \begin_inset LatexCommand \url{http://sourceforge.net/svn/?group_id=599}
26045
26046 \end_inset
26047
26048  (by number or by date).
26049  An on-line source code browser and detailled instructions are also available
26050  there.
26051  SDCC versions starting from 1999 up to now are available (currently the
26052  versions prior to the conversion from cvs
26053 \begin_inset LatexCommand \index{cvs|see{Subversion}}
26054
26055 \end_inset
26056
26057  to Subversion (April 2006) are either by accessible by Subversion or by
26058  cvs).
26059 \layout Section
26060
26061 Release policy
26062 \begin_inset LatexCommand \index{Release policy}
26063
26064 \end_inset
26065
26066
26067 \layout Standard
26068
26069 Historically there often were long delays between official releases and
26070  the sourceforge download area tends to get not updated at all.
26071  Excuses in the past might have referred to problems with live range analysis,
26072  but as this was fixed a while ago, the current problem is that another
26073  excuse has to be found.
26074  Kidding aside, we have to get better there! On the other hand there are
26075  daily snapshots available at
26076 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
26077
26078 \end_inset
26079
26080 , and you can always build the very last version (hopefully with many bugs
26081  fixed, and features added) from the source code available at
26082 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
26083
26084 \end_inset
26085
26086 .
26087  A release wiki
26088 \begin_inset LatexCommand \index{wiki}
26089
26090 \end_inset
26091
26092
26093 \begin_inset LatexCommand \index{Release wiki}
26094
26095 \end_inset
26096
26097  at
26098 \begin_inset LatexCommand \url{http://sdcc.sf.net/release_wiki/}
26099
26100 \end_inset
26101
26102  also holds some information about past and future releases.
26103 \layout Section
26104
26105 Examples
26106 \begin_inset LatexCommand \index{Examples}
26107
26108 \end_inset
26109
26110
26111 \layout Standard
26112
26113 You'll find some small examples in the directory
26114 \emph on
26115 sdcc/device/examples/.
26116
26117 \emph default
26118 More examples and libraries are available at
26119 \emph on
26120  The SDCC Open Knowledge Resource
26121 \begin_inset LatexCommand \url{http://sdccokr.dl9sec.de/}
26122
26123 \end_inset
26124
26125
26126 \emph default
26127 web site or at
26128 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
26129
26130 \end_inset
26131
26132 .
26133 \layout Comment
26134
26135 I did insert a reference to Paul's web site here although it seems rather
26136  dedicated to a specific 8032 board (I think it's okay because it f.e.
26137  shows LCD/Harddisc interface and has a free 8051 monitor.
26138  Independent 8032 board vendors face hard competition of heavily subsidized
26139  development boards anyway).
26140 \layout Comment
26141
26142 Maybe we should include some links to real world applications.
26143  Preferably pointer to pointers (one for each architecture) so this stays
26144  manageable here?
26145 \layout Section
26146
26147 Quality control
26148 \begin_inset LatexCommand \label{sec:Quality-control}
26149
26150 \end_inset
26151
26152
26153 \begin_inset LatexCommand \index{Quality control}
26154
26155 \end_inset
26156
26157
26158 \layout Standard
26159
26160 The compiler is passed through nightly compile and build checks.
26161  The so called
26162 \shape italic
26163 regression tests
26164 \shape default
26165
26166 \begin_inset LatexCommand \index{Regression test}
26167
26168 \end_inset
26169
26170  check that SDCC itself compiles flawlessly on several host platforms (i386,
26171  Opteron, 64 bit Alpha, ppc64, MacOS X on PPC, Solaris on Sparc) and checks
26172  the quality of the code generated by SDCC by running the code for several
26173  target platforms through simulators.
26174  The regression test suite comprises more than 100 files which expand to
26175  more than 500 test cases which include more than 4500 tests.
26176  The results of these tests are published daily on SDCC's snapshot page
26177  (click on the red or green symbols on the right side of
26178 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
26179
26180 \end_inset
26181
26182 ).
26183 \layout Standard
26184
26185 There is a separate document
26186 \shape italic
26187 test_suite.pdf
26188 \begin_inset LatexCommand \index{Test suite}
26189
26190 \end_inset
26191
26192
26193 \shape default
26194
26195 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/test_suite_spec.pdf}
26196
26197 \end_inset
26198
26199  about the regression test suite.
26200 \layout Standard
26201
26202 You'll find the test code in the directory
26203 \shape italic
26204 sdcc/support/regression
26205 \shape default
26206 .
26207  You can run these tests manually by running
26208 \family sans
26209 make
26210 \family default
26211  in this directory (or f.e.
26212
26213 \family sans
26214 \series bold
26215
26216 \begin_inset Quotes sld
26217 \end_inset
26218
26219 make test-mcs51
26220 \begin_inset Quotes srd
26221 \end_inset
26222
26223
26224 \family default
26225 \series default
26226  if you don't want to run the complete tests).
26227  The test code might also be interesting if you want to look for examples
26228 \begin_inset LatexCommand \index{Examples}
26229
26230 \end_inset
26231
26232  checking corner cases of SDCC or if you plan to submit patches
26233 \begin_inset LatexCommand \index{Patch submission}
26234
26235 \end_inset
26236
26237 .
26238 \layout Standard
26239
26240 The 14bit pic port uses a different set of regression tests
26241 \begin_inset LatexCommand \index{Regression test (PIC14)}
26242
26243 \end_inset
26244
26245 , you'll find them in the directory
26246 \shape italic
26247 sdcc/src/regression
26248 \shape default
26249 .
26250 \layout Section
26251
26252 Use of SDCC in Education
26253 \layout Standard
26254
26255 In short:
26256 \emph on
26257 highly
26258 \emph default
26259  encouraged
26260 \begin_inset Foot
26261 collapsed false
26262
26263 \layout Standard
26264
26265 the phrase "use in education" might evoke the association "
26266 \emph on
26267 only
26268 \emph default
26269  fit for use in education".
26270  This connotation is not intended but nevertheless risked as the licensing
26271  of SDCC makes it difficult to offer educational discounts
26272 \end_inset
26273
26274 .
26275  If your rationales are to:
26276 \layout Enumerate
26277
26278 give students a chance to understand the
26279 \emph on
26280 complete
26281 \emph default
26282  steps of code generation
26283 \layout Enumerate
26284
26285 have a curriculum that can be extended for years.
26286  Then you could use an fpga board as target and your curriculum will seamlessly
26287  extend from logic synthesis (
26288 \begin_inset LatexCommand \url[http://www.opencores.org]{opencores.org}
26289
26290 \end_inset
26291
26292 ,
26293 \begin_inset LatexCommand \url[Oregano]{http://www.oregano.at/ip/ip01.htm}
26294
26295 \end_inset
26296
26297 ), over assembly programming, to C to FPGA compilers (
26298 \begin_inset LatexCommand \url[FPGAC]{http://sf.net/projects/fpgac}
26299
26300 \end_inset
26301
26302 ) and to C.
26303 \layout Enumerate
26304
26305 be able to insert excursions about skills like using a revision control
26306  system, submitting/applying patches, using a type-setting (as opposed to
26307  word-processing) engine LyX/LaTeX, using
26308 \begin_inset LatexCommand \url[SourceForge]{http://www.sf.net}
26309
26310 \end_inset
26311
26312 , following some
26313 \begin_inset LatexCommand \url[netiquette]{http://en.wikipedia.org/wiki/Netiquette}
26314
26315 \end_inset
26316
26317 , understanding BSD/LGPL/GPL/Proprietary licensing, growth models of Open
26318  Source Software, CPU simulation, compiler regression tests
26319 \begin_inset LatexCommand \index{Regression test}
26320
26321 \end_inset
26322
26323 .
26324
26325 \newline
26326 And if there should be a shortage of ideas then you can always point students
26327  to the ever-growing feature request list
26328 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
26329
26330 \end_inset
26331
26332 .
26333 \layout Enumerate
26334
26335 not tie students to a specific host platform and instead allow them to use
26336  a host platform of
26337 \emph on
26338 their
26339 \emph default
26340  choice (among them Alpha, i386, i386_64, MacOs, Mips, Sparc, Windows and
26341  eventually
26342 \begin_inset LatexCommand \url[OLPC]{http://www.laptop.org}
26343
26344 \end_inset
26345
26346 )
26347 \layout Enumerate
26348
26349 not encourage students to use illegal copies of educational software
26350 \layout Enumerate
26351
26352 be immune to licensing/availability/price changes of the chosen tool chain
26353 \layout Enumerate
26354
26355 be able to change to a new target platform without having to adopt a new
26356  tool chain
26357 \layout Enumerate
26358
26359 have complete control over and insight into the tool chain
26360 \layout Enumerate
26361
26362 make your students aware about the pros and cons of open source software
26363  development
26364 \layout Enumerate
26365
26366 give back to the public as you are probably at least partially publically
26367  funded
26368 \layout Enumerate
26369
26370 give students a chance to publically prove their skills and to possibly
26371  see a world wide impact
26372 \layout Standard
26373
26374 then SDCC is probably among the first choices.
26375  Well, probably SDCC might be the only choice.
26376 \layout Chapter
26377 \pagebreak_top
26378 SDCC Technical Data
26379 \layout Section
26380
26381 Optimizations
26382 \begin_inset LatexCommand \index{Optimizations}
26383
26384 \end_inset
26385
26386
26387 \layout Standard
26388
26389 SDCC performs a host of standard optimizations in addition to some MCU specific
26390  optimizations.
26391
26392 \layout Subsection
26393
26394 Sub-expression Elimination
26395 \begin_inset LatexCommand \index{Subexpression elimination}
26396
26397 \end_inset
26398
26399
26400 \layout Standard
26401
26402 The compiler does local and
26403 \emph on
26404 g
26405 \emph default
26406 lobal
26407 \emph on
26408 c
26409 \emph default
26410 ommon
26411 \emph on
26412 s
26413 \emph default
26414 ubexpression
26415 \emph on
26416 e
26417 \emph default
26418 limination, e.g.:
26419 \layout Verse
26420
26421
26422 \family typewriter
26423 i = x + y + 1;
26424 \newline
26425 j = x + y;
26426 \layout Standard
26427
26428 will be translated to
26429 \layout Verse
26430
26431
26432 \family typewriter
26433 iTemp = x + y;
26434 \newline
26435 i = iTemp + 1;
26436 \newline
26437 j = iTemp;
26438 \layout Standard
26439
26440 Some subexpressions are not as obvious as the above example, e.g.:
26441 \layout Verse
26442
26443
26444 \family typewriter
26445 a->b[i].c = 10;
26446 \newline
26447 a->b[i].d = 11;
26448 \layout Standard
26449
26450 In this case the address arithmetic a->b[i] will be computed only once;
26451  the equivalent code in C would be.
26452 \layout Verse
26453
26454
26455 \family typewriter
26456 iTemp = a->b[i];
26457 \newline
26458 iTemp.c = 10;
26459 \newline
26460 iTemp.d = 11;
26461 \layout Standard
26462
26463 The compiler will try to keep these temporary variables in registers.
26464 \layout Subsection
26465
26466 Dead-Code Elimination
26467 \begin_inset LatexCommand \index{Dead-code elimination}
26468
26469 \end_inset
26470
26471
26472 \layout Verse
26473
26474
26475 \family typewriter
26476 int global;
26477 \newline
26478
26479 \newline
26480 void f () {
26481 \newline
26482 \SpecialChar ~
26483 \SpecialChar ~
26484 int i;
26485 \newline
26486 \SpecialChar ~
26487 \SpecialChar ~
26488 i = 1; \SpecialChar ~
26489 \SpecialChar ~
26490 \SpecialChar ~
26491 \SpecialChar ~
26492 \SpecialChar ~
26493 /* dead store */
26494 \newline
26495 \SpecialChar ~
26496 \SpecialChar ~
26497 global = 1;\SpecialChar ~
26498 /* dead store */
26499 \newline
26500 \SpecialChar ~
26501 \SpecialChar ~
26502 global = 2;
26503 \newline
26504 \SpecialChar ~
26505 \SpecialChar ~
26506 return;
26507 \newline
26508 \SpecialChar ~
26509 \SpecialChar ~
26510 global = 3;\SpecialChar ~
26511 /* unreachable */
26512 \newline
26513 }
26514 \layout Standard
26515
26516 will be changed to
26517 \layout Verse
26518
26519
26520 \family typewriter
26521 int global;
26522 \newline
26523
26524 \newline
26525 void f () {
26526 \newline
26527 \SpecialChar ~
26528 \SpecialChar ~
26529 global = 2;
26530 \newline
26531 }
26532 \layout Subsection
26533
26534 Copy-Propagation
26535 \begin_inset LatexCommand \index{Copy propagation}
26536
26537 \end_inset
26538
26539
26540 \layout Verse
26541
26542
26543 \family typewriter
26544 int f() {
26545 \newline
26546 \SpecialChar ~
26547 \SpecialChar ~
26548 int i, j;
26549 \newline
26550 \SpecialChar ~
26551 \SpecialChar ~
26552 i = 10;
26553 \newline
26554 \SpecialChar ~
26555 \SpecialChar ~
26556 j = i;
26557 \newline
26558 \SpecialChar ~
26559 \SpecialChar ~
26560 return j;
26561 \newline
26562 }
26563 \layout Standard
26564
26565 will be changed to
26566 \layout Verse
26567
26568
26569 \family typewriter
26570 int f() {
26571 \newline
26572 \SpecialChar ~
26573 \SpecialChar ~
26574 int i, j;
26575 \newline
26576 \SpecialChar ~
26577 \SpecialChar ~
26578 i = 10;
26579 \newline
26580 \SpecialChar ~
26581 \SpecialChar ~
26582 j = 10;
26583 \newline
26584 \SpecialChar ~
26585 \SpecialChar ~
26586 return 10;
26587 \newline
26588 }
26589 \layout Standard
26590
26591 Note: the dead stores created by this copy propagation will be eliminated
26592  by dead-code elimination.
26593 \layout Subsection
26594
26595 Loop Optimizations
26596 \begin_inset LatexCommand \index{Loop optimization}
26597
26598 \end_inset
26599
26600
26601 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
26602
26603 \end_inset
26604
26605
26606 \layout Standard
26607
26608 Two types of loop optimizations are done by SDCC
26609 \emph on
26610 loop invariant
26611 \emph default
26612  lifting and
26613 \emph on
26614  strength reduction
26615 \emph default
26616  of loop induction variables.
26617  In addition to the strength reduction the optimizer marks the induction
26618  variables and the register allocator tries to keep the induction variables
26619  in registers for the duration of the loop.
26620  Because of this preference of the register allocator
26621 \begin_inset LatexCommand \index{Register allocation}
26622
26623 \end_inset
26624
26625 , loop induction optimization causes an increase in register pressure, which
26626  may cause unwanted spilling of other temporary variables into the stack
26627 \begin_inset LatexCommand \index{stack}
26628
26629 \end_inset
26630
26631  / data space.
26632  The compiler will generate a warning message when it is forced to allocate
26633  extra space either on the stack or data space.
26634  If this extra space allocation is undesirable then induction optimization
26635  can be eliminated either for the entire source file (with -
26636 \begin_inset ERT
26637 status Collapsed
26638
26639 \layout Standard
26640
26641 \backslash
26642 /
26643 \end_inset
26644
26645 -noinduction option) or for a given function only using #pragma\SpecialChar ~
26646 noinduction
26647 \begin_inset LatexCommand \index{\#pragma noinduction}
26648
26649 \end_inset
26650
26651 .
26652 \newline
26653
26654 \newline
26655 Loop Invariant:
26656 \layout Verse
26657
26658
26659 \family typewriter
26660 for (i = 0 ; i < 100 ; i ++)
26661 \newline
26662 \SpecialChar ~
26663 \SpecialChar ~
26664 \SpecialChar ~
26665 \SpecialChar ~
26666 f += k + l;
26667 \layout Standard
26668
26669 changed to
26670 \layout Verse
26671
26672
26673 \family typewriter
26674 itemp = k + l;
26675 \newline
26676 for (i = 0; i < 100; i++)
26677 \newline
26678 \SpecialChar ~
26679 \SpecialChar ~
26680 \SpecialChar ~
26681 \SpecialChar ~
26682 f += itemp;
26683 \layout Standard
26684
26685 As mentioned previously some loop invariants are not as apparent, all static
26686  address computations are also moved out of the loop.
26687 \newline
26688
26689 \newline
26690 Strength Reduction
26691 \begin_inset LatexCommand \index{Strength reduction}
26692
26693 \end_inset
26694
26695 , this optimization substitutes an expression by a cheaper expression:
26696 \layout Verse
26697
26698
26699 \family typewriter
26700 for (i=0;i < 100; i++)
26701 \newline
26702 \SpecialChar ~
26703 \SpecialChar ~
26704 \SpecialChar ~
26705 \SpecialChar ~
26706 ar[i*5] = i*3;
26707 \layout Standard
26708
26709 changed to
26710 \layout Verse
26711
26712
26713 \family typewriter
26714 itemp1 = 0;
26715 \newline
26716 itemp2 = 0;
26717 \newline
26718 for (i=0;i< 100;i++) {
26719 \newline
26720 \SpecialChar ~
26721 \SpecialChar ~
26722 \SpecialChar ~
26723 \SpecialChar ~
26724 ar[itemp1] = itemp2;
26725 \newline
26726 \SpecialChar ~
26727 \SpecialChar ~
26728 \SpecialChar ~
26729 \SpecialChar ~
26730 itemp1 += 5;
26731 \newline
26732 \SpecialChar ~
26733 \SpecialChar ~
26734 \SpecialChar ~
26735 \SpecialChar ~
26736 itemp2 += 3;
26737 \newline
26738 }
26739 \layout Standard
26740
26741 The more expensive multiplication
26742 \begin_inset LatexCommand \index{Multiplication}
26743
26744 \end_inset
26745
26746  is changed to a less expensive addition.
26747 \layout Subsection
26748
26749 Loop Reversing
26750 \begin_inset LatexCommand \index{Loop reversing}
26751
26752 \end_inset
26753
26754
26755 \layout Standard
26756
26757 This optimization is done to reduce the overhead of checking loop boundaries
26758  for every iteration.
26759  Some simple loops can be reversed and implemented using a
26760 \begin_inset Quotes eld
26761 \end_inset
26762
26763 decrement and jump if not zero
26764 \begin_inset Quotes erd
26765 \end_inset
26766
26767  instruction.
26768  SDCC checks for the following criterion to determine if a loop is reversible
26769  (note: more sophisticated compilers use data-dependency analysis to make
26770  this determination, SDCC uses a more simple minded analysis).
26771 \layout Itemize
26772
26773 The 'for' loop is of the form
26774 \newline
26775
26776 \newline
26777
26778 \family typewriter
26779 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
26780  += 1])
26781 \newline
26782 \SpecialChar ~
26783 \SpecialChar ~
26784 \SpecialChar ~
26785 \SpecialChar ~
26786 <for body>
26787 \layout Itemize
26788
26789 The <for body> does not contain
26790 \begin_inset Quotes eld
26791 \end_inset
26792
26793 continue
26794 \begin_inset Quotes erd
26795 \end_inset
26796
26797  or 'break
26798 \begin_inset Quotes erd
26799 \end_inset
26800
26801 .
26802 \layout Itemize
26803
26804 All goto's are contained within the loop.
26805 \layout Itemize
26806
26807 No function calls within the loop.
26808 \layout Itemize
26809
26810 The loop control variable <sym> is not assigned any value within the loop
26811 \layout Itemize
26812
26813 The loop control variable does NOT participate in any arithmetic operation
26814  within the loop.
26815 \layout Itemize
26816
26817 There are NO switch statements in the loop.
26818 \layout Subsection
26819
26820 Algebraic Simplifications
26821 \layout Standard
26822
26823 SDCC does numerous algebraic simplifications, the following is a small sub-set
26824  of these optimizations.
26825 \layout Verse
26826
26827
26828 \family typewriter
26829 i = j + 0;\SpecialChar ~
26830 \SpecialChar ~
26831 \SpecialChar ~
26832 \SpecialChar ~
26833  /* changed to: */\SpecialChar ~
26834 \SpecialChar ~
26835 \SpecialChar ~
26836 \SpecialChar ~
26837  i = j;
26838 \newline
26839 i /= 2;\SpecialChar ~
26840 \SpecialChar ~
26841 \SpecialChar ~
26842 \SpecialChar ~
26843 \SpecialChar ~
26844 \SpecialChar ~
26845 \SpecialChar ~
26846  /* changed to: */\SpecialChar ~
26847 \SpecialChar ~
26848 \SpecialChar ~
26849 \SpecialChar ~
26850  i >>= 1;
26851 \newline
26852 i = j - j;\SpecialChar ~
26853 \SpecialChar ~
26854 \SpecialChar ~
26855 \SpecialChar ~
26856  /* changed to: */\SpecialChar ~
26857 \SpecialChar ~
26858 \SpecialChar ~
26859 \SpecialChar ~
26860  i = 0;
26861 \newline
26862 i = j / 1;\SpecialChar ~
26863 \SpecialChar ~
26864 \SpecialChar ~
26865 \SpecialChar ~
26866  /* changed to: */\SpecialChar ~
26867 \SpecialChar ~
26868 \SpecialChar ~
26869 \SpecialChar ~
26870  i = j;
26871 \layout Standard
26872
26873 Note the subexpressions
26874 \begin_inset LatexCommand \index{Subexpression}
26875
26876 \end_inset
26877
26878  given above are generally introduced by macro expansions or as a result
26879  of copy/constant propagation.
26880 \layout Subsection
26881
26882 'switch' Statements
26883 \begin_inset LatexCommand \label{sub:'switch'-Statements}
26884
26885 \end_inset
26886
26887
26888 \begin_inset LatexCommand \index{switch statement}
26889
26890 \end_inset
26891
26892
26893 \layout Standard
26894
26895 SDCC can optimize switch statements to jump tables
26896 \begin_inset LatexCommand \index{jump tables}
26897
26898 \end_inset
26899
26900 .
26901  It makes the decision based on an estimate of the generated code size.
26902  SDCC is quite liberal in the requirements for jump table generation:
26903 \layout Itemize
26904
26905 The labels need not be in order, and the starting number need not be one
26906  or zero, the case labels are in numerical sequence or not too many case
26907  labels are missing.
26908 \begin_deeper
26909 \layout Verse
26910
26911
26912 \family typewriter
26913 switch(i) {\SpecialChar ~
26914 \SpecialChar ~
26915 \SpecialChar ~
26916 \SpecialChar ~
26917 \SpecialChar ~
26918 \SpecialChar ~
26919 \SpecialChar ~
26920 \SpecialChar ~
26921 \SpecialChar ~
26922 \SpecialChar ~
26923 \SpecialChar ~
26924 \SpecialChar ~
26925 \SpecialChar ~
26926 \SpecialChar ~
26927 \SpecialChar ~
26928 \SpecialChar ~
26929 \SpecialChar ~
26930 \SpecialChar ~
26931 \SpecialChar ~
26932 \SpecialChar ~
26933 \SpecialChar ~
26934 \SpecialChar ~
26935 \SpecialChar ~
26936 \SpecialChar ~
26937 \SpecialChar ~
26938 \SpecialChar ~
26939 switch (i) {
26940 \newline
26941 \SpecialChar ~
26942 \SpecialChar ~
26943 \SpecialChar ~
26944 case 4: ...\SpecialChar ~
26945 \SpecialChar ~
26946 \SpecialChar ~
26947 \SpecialChar ~
26948 \SpecialChar ~
26949 \SpecialChar ~
26950 \SpecialChar ~
26951 \SpecialChar ~
26952 \SpecialChar ~
26953 \SpecialChar ~
26954 \SpecialChar ~
26955 \SpecialChar ~
26956 \SpecialChar ~
26957 \SpecialChar ~
26958 \SpecialChar ~
26959 \SpecialChar ~
26960 \SpecialChar ~
26961 \SpecialChar ~
26962 \SpecialChar ~
26963 \SpecialChar ~
26964 \SpecialChar ~
26965 \SpecialChar ~
26966 \SpecialChar ~
26967 \SpecialChar ~
26968 \SpecialChar ~
26969 \SpecialChar ~
26970 case 0: ...
26971
26972 \newline
26973 \SpecialChar ~
26974 \SpecialChar ~
26975 \SpecialChar ~
26976 case 5: ...\SpecialChar ~
26977 \SpecialChar ~
26978 \SpecialChar ~
26979 \SpecialChar ~
26980 \SpecialChar ~
26981 \SpecialChar ~
26982 \SpecialChar ~
26983 \SpecialChar ~
26984 \SpecialChar ~
26985 \SpecialChar ~
26986 \SpecialChar ~
26987 \SpecialChar ~
26988 \SpecialChar ~
26989 \SpecialChar ~
26990 \SpecialChar ~
26991 \SpecialChar ~
26992 \SpecialChar ~
26993 \SpecialChar ~
26994 \SpecialChar ~
26995 \SpecialChar ~
26996 \SpecialChar ~
26997 \SpecialChar ~
26998 \SpecialChar ~
26999 \SpecialChar ~
27000 \SpecialChar ~
27001 \SpecialChar ~
27002 case 1: ...
27003
27004 \newline
27005 \SpecialChar ~
27006 \SpecialChar ~
27007 \SpecialChar ~
27008 case 3: ...\SpecialChar ~
27009 \SpecialChar ~
27010 \SpecialChar ~
27011 \SpecialChar ~
27012 \SpecialChar ~
27013 \SpecialChar ~
27014 \SpecialChar ~
27015 \SpecialChar ~
27016 \SpecialChar ~
27017 \SpecialChar ~
27018 \SpecialChar ~
27019 \SpecialChar ~
27020 \SpecialChar ~
27021 \SpecialChar ~
27022 \SpecialChar ~
27023 \SpecialChar ~
27024 \SpecialChar ~
27025 \SpecialChar ~
27026 \SpecialChar ~
27027 \SpecialChar ~
27028 \SpecialChar ~
27029 \SpecialChar ~
27030 \SpecialChar ~
27031 \SpecialChar ~
27032 \SpecialChar ~
27033 \SpecialChar ~
27034
27035 \newline
27036 \SpecialChar ~
27037 \SpecialChar ~
27038 \SpecialChar ~
27039 case 6: ...\SpecialChar ~
27040 \SpecialChar ~
27041 \SpecialChar ~
27042 \SpecialChar ~
27043 \SpecialChar ~
27044 \SpecialChar ~
27045 \SpecialChar ~
27046 \SpecialChar ~
27047 \SpecialChar ~
27048 \SpecialChar ~
27049 \SpecialChar ~
27050 \SpecialChar ~
27051 \SpecialChar ~
27052 \SpecialChar ~
27053 \SpecialChar ~
27054 \SpecialChar ~
27055 \SpecialChar ~
27056 \SpecialChar ~
27057 \SpecialChar ~
27058 \SpecialChar ~
27059 \SpecialChar ~
27060 \SpecialChar ~
27061 \SpecialChar ~
27062 \SpecialChar ~
27063 \SpecialChar ~
27064 \SpecialChar ~
27065 case 3: ...
27066
27067 \newline
27068 \SpecialChar ~
27069 \SpecialChar ~
27070 \SpecialChar ~
27071 case 7: ...\SpecialChar ~
27072 \SpecialChar ~
27073 \SpecialChar ~
27074 \SpecialChar ~
27075 \SpecialChar ~
27076 \SpecialChar ~
27077 \SpecialChar ~
27078 \SpecialChar ~
27079 \SpecialChar ~
27080 \SpecialChar ~
27081 \SpecialChar ~
27082 \SpecialChar ~
27083 \SpecialChar ~
27084 \SpecialChar ~
27085 \SpecialChar ~
27086 \SpecialChar ~
27087 \SpecialChar ~
27088 \SpecialChar ~
27089 \SpecialChar ~
27090 \SpecialChar ~
27091 \SpecialChar ~
27092 \SpecialChar ~
27093 \SpecialChar ~
27094 \SpecialChar ~
27095 \SpecialChar ~
27096 \SpecialChar ~
27097 case 4: ...
27098
27099 \newline
27100 \SpecialChar ~
27101 \SpecialChar ~
27102 \SpecialChar ~
27103 case 8: ...\SpecialChar ~
27104 \SpecialChar ~
27105 \SpecialChar ~
27106 \SpecialChar ~
27107 \SpecialChar ~
27108 \SpecialChar ~
27109 \SpecialChar ~
27110 \SpecialChar ~
27111 \SpecialChar ~
27112 \SpecialChar ~
27113 \SpecialChar ~
27114 \SpecialChar ~
27115 \SpecialChar ~
27116 \SpecialChar ~
27117 \SpecialChar ~
27118 \SpecialChar ~
27119 \SpecialChar ~
27120 \SpecialChar ~
27121 \SpecialChar ~
27122 \SpecialChar ~
27123 \SpecialChar ~
27124 \SpecialChar ~
27125 \SpecialChar ~
27126 \SpecialChar ~
27127 \SpecialChar ~
27128 \SpecialChar ~
27129 case 5: ...
27130
27131 \newline
27132 \SpecialChar ~
27133 \SpecialChar ~
27134 \SpecialChar ~
27135 case 9: ...\SpecialChar ~
27136 \SpecialChar ~
27137 \SpecialChar ~
27138 \SpecialChar ~
27139 \SpecialChar ~
27140 \SpecialChar ~
27141 \SpecialChar ~
27142 \SpecialChar ~
27143 \SpecialChar ~
27144 \SpecialChar ~
27145 \SpecialChar ~
27146 \SpecialChar ~
27147 \SpecialChar ~
27148 \SpecialChar ~
27149 \SpecialChar ~
27150 \SpecialChar ~
27151 \SpecialChar ~
27152 \SpecialChar ~
27153 \SpecialChar ~
27154 \SpecialChar ~
27155 \SpecialChar ~
27156 \SpecialChar ~
27157 \SpecialChar ~
27158 \SpecialChar ~
27159 \SpecialChar ~
27160 \SpecialChar ~
27161 case 6: ...
27162
27163 \newline
27164 \SpecialChar ~
27165 \SpecialChar ~
27166 \SpecialChar ~
27167 case 10: ...\SpecialChar ~
27168 \SpecialChar ~
27169 \SpecialChar ~
27170 \SpecialChar ~
27171 \SpecialChar ~
27172 \SpecialChar ~
27173 \SpecialChar ~
27174 \SpecialChar ~
27175 \SpecialChar ~
27176 \SpecialChar ~
27177 \SpecialChar ~
27178 \SpecialChar ~
27179 \SpecialChar ~
27180 \SpecialChar ~
27181 \SpecialChar ~
27182 \SpecialChar ~
27183 \SpecialChar ~
27184 \SpecialChar ~
27185 \SpecialChar ~
27186 \SpecialChar ~
27187 \SpecialChar ~
27188 \SpecialChar ~
27189 \SpecialChar ~
27190 \SpecialChar ~
27191 \SpecialChar ~
27192 case 7: ...
27193
27194 \newline
27195 \SpecialChar ~
27196 \SpecialChar ~
27197 \SpecialChar ~
27198 case 11: ...\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 \SpecialChar ~
27220 \SpecialChar ~
27221 \SpecialChar ~
27222 \SpecialChar ~
27223 case 8: ...
27224
27225 \newline
27226 }\SpecialChar ~
27227 \SpecialChar ~
27228 \SpecialChar ~
27229 \SpecialChar ~
27230 \SpecialChar ~
27231 \SpecialChar ~
27232 \SpecialChar ~
27233 \SpecialChar ~
27234 \SpecialChar ~
27235 \SpecialChar ~
27236 \SpecialChar ~
27237 \SpecialChar ~
27238 \SpecialChar ~
27239 \SpecialChar ~
27240 \SpecialChar ~
27241 \SpecialChar ~
27242 \SpecialChar ~
27243 \SpecialChar ~
27244 \SpecialChar ~
27245 \SpecialChar ~
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 }
27263 \layout Standard
27264
27265 Both the above switch statements will be implemented using a jump-table.
27266  The example to the right side is slightly more efficient as the check for
27267  the lower boundary of the jump-table is not needed.
27268 \end_deeper
27269 \layout Itemize
27270
27271 The number of case labels is not larger than supported by the target architectur
27272 e.
27273 \layout Itemize
27274
27275 If the case labels are not in numerical sequence ('gaps' between cases)
27276  SDCC checks whether a jump table with additionally inserted dummy cases
27277  is still attractive.
27278
27279 \layout Itemize
27280
27281 If the starting number is not zero and a check for the lower boundary of
27282  the jump-table can thus be eliminated SDCC might insert dummy cases 0,
27283  ...
27284  .
27285 \layout Standard
27286
27287 Switch statements which have large gaps in the numeric sequence or those
27288  that have too many case labels can be split into more than one switch statement
27289  for efficient code generation, e.g.:
27290 \layout Verse
27291
27292
27293 \family typewriter
27294 switch (i) {
27295 \newline
27296 \SpecialChar ~
27297 \SpecialChar ~
27298 case 1: ...
27299
27300 \newline
27301 \SpecialChar ~
27302 \SpecialChar ~
27303 case 2: ...
27304
27305 \newline
27306 \SpecialChar ~
27307 \SpecialChar ~
27308 case 3: ...
27309
27310 \newline
27311 \SpecialChar ~
27312 \SpecialChar ~
27313 case 4: ...
27314
27315 \newline
27316 \SpecialChar ~
27317 \SpecialChar ~
27318 case 5: ...
27319
27320 \newline
27321 \SpecialChar ~
27322 \SpecialChar ~
27323 case 6: ...
27324
27325 \newline
27326 \SpecialChar ~
27327 \SpecialChar ~
27328 case 7: ...
27329
27330 \newline
27331 \SpecialChar ~
27332 \SpecialChar ~
27333 case 101: ...
27334
27335 \newline
27336 \SpecialChar ~
27337 \SpecialChar ~
27338 case 102: ...
27339
27340 \newline
27341 \SpecialChar ~
27342 \SpecialChar ~
27343 case 103: ...
27344
27345 \newline
27346 \SpecialChar ~
27347 \SpecialChar ~
27348 case 104: ...
27349
27350 \newline
27351 \SpecialChar ~
27352 \SpecialChar ~
27353 case 105: ...
27354
27355 \newline
27356 \SpecialChar ~
27357 \SpecialChar ~
27358 case 106: ...
27359
27360 \newline
27361 \SpecialChar ~
27362 \SpecialChar ~
27363 case 107: ...
27364
27365 \newline
27366 }
27367 \layout Standard
27368
27369 If the above switch statement is broken down into two switch statements
27370 \layout Verse
27371
27372
27373 \family typewriter
27374 switch (i) {
27375 \newline
27376 \SpecialChar ~
27377 \SpecialChar ~
27378 case 1: ...
27379
27380 \newline
27381 \SpecialChar ~
27382 \SpecialChar ~
27383 case 2: ...
27384
27385 \newline
27386 \SpecialChar ~
27387 \SpecialChar ~
27388 case 3: ...
27389
27390 \newline
27391 \SpecialChar ~
27392 \SpecialChar ~
27393 case 4: ...
27394
27395 \newline
27396 \SpecialChar ~
27397 \SpecialChar ~
27398 case 5: ...
27399
27400 \newline
27401 \SpecialChar ~
27402 \SpecialChar ~
27403 case 6: ...
27404
27405 \newline
27406 \SpecialChar ~
27407 \SpecialChar ~
27408 case 7: ...
27409
27410 \newline
27411 }
27412 \layout Standard
27413
27414 and
27415 \layout Verse
27416
27417
27418 \family typewriter
27419 switch (i) {
27420 \newline
27421 \SpecialChar ~
27422 \SpecialChar ~
27423 case 101: ...
27424
27425 \newline
27426 \SpecialChar ~
27427 \SpecialChar ~
27428 case 102: ...
27429
27430 \newline
27431 \SpecialChar ~
27432 \SpecialChar ~
27433 case 103: ...
27434
27435 \newline
27436 \SpecialChar ~
27437 \SpecialChar ~
27438 case 104: ...
27439
27440 \newline
27441 \SpecialChar ~
27442 \SpecialChar ~
27443 case 105: ...
27444
27445 \newline
27446 \SpecialChar ~
27447 \SpecialChar ~
27448 case 106: ...
27449
27450 \newline
27451 \SpecialChar ~
27452 \SpecialChar ~
27453 case 107: ...
27454
27455 \newline
27456 }
27457 \layout Standard
27458
27459 then both the switch statements will be implemented using jump-tables whereas
27460  the unmodified switch statement will not be.
27461 \layout Comment
27462
27463 There might be reasons which SDCC cannot know about to either favour or
27464  not favour jump tables.
27465  If the target system has to be as quick for the last switch case as for
27466  the first (pro jump table), or if the switch argument is known to be zero
27467  in the majority of the cases (contra jump table).
27468 \layout Standard
27469
27470 The pragma nojtbound
27471 \begin_inset LatexCommand \index{\#pragma nojtbound}
27472
27473 \end_inset
27474
27475  can be used to turn off checking the
27476 \emph on
27477 j
27478 \emph default
27479 ump
27480 \emph on
27481 t
27482 \emph default
27483 able
27484 \emph on
27485 bound
27486 \emph default
27487 aries.
27488  It has no effect if a default label is supplied.
27489  Use of this pragma is dangerous: if the switch
27490 \begin_inset LatexCommand \index{switch statement}
27491
27492 \end_inset
27493
27494  argument is not matched by a case statement the processor will happily
27495  jump into Nirvana.
27496 \layout Subsection
27497
27498 Bit-shifting Operations
27499 \begin_inset LatexCommand \index{Bit shifting}
27500
27501 \end_inset
27502
27503 .
27504 \layout Standard
27505
27506 Bit shifting is one of the most frequently used operation in embedded programmin
27507 g.
27508  SDCC tries to implement bit-shift operations in the most efficient way
27509  possible, e.g.:
27510 \layout Verse
27511
27512
27513 \family typewriter
27514 unsigned char i;
27515 \newline
27516 ...
27517
27518 \newline
27519 i >>= 4;
27520 \newline
27521 ...
27522 \layout Standard
27523
27524 generates the following code:
27525 \layout Verse
27526
27527
27528 \family typewriter
27529 mov\SpecialChar ~
27530  a,_i
27531 \newline
27532 swap a
27533 \newline
27534 anl\SpecialChar ~
27535  a,#0x0f
27536 \newline
27537 mov\SpecialChar ~
27538  _i,a
27539 \layout Standard
27540
27541 In general SDCC will never setup a loop if the shift count is known.
27542  Another example:
27543 \layout Verse
27544
27545
27546 \family typewriter
27547 unsigned int i;
27548 \newline
27549 ...
27550
27551 \newline
27552 i >>= 9;
27553 \newline
27554 ...
27555 \layout Standard
27556
27557 will generate:
27558 \layout Verse
27559
27560
27561 \family typewriter
27562 mov\SpecialChar ~
27563 \SpecialChar ~
27564 a,(_i + 1)
27565 \newline
27566 mov\SpecialChar ~
27567 \SpecialChar ~
27568 (_i + 1),#0x00
27569 \newline
27570 clr\SpecialChar ~
27571 \SpecialChar ~
27572 c
27573 \newline
27574 rrc\SpecialChar ~
27575 \SpecialChar ~
27576 a
27577 \newline
27578 mov\SpecialChar ~
27579 \SpecialChar ~
27580 _i,a
27581 \layout Subsection
27582
27583 Bit-rotation
27584 \begin_inset LatexCommand \index{Bit rotation}
27585
27586 \end_inset
27587
27588
27589 \layout Standard
27590
27591 A special case of the bit-shift operation is bit rotation
27592 \begin_inset LatexCommand \index{rotating bits}
27593
27594 \end_inset
27595
27596 , SDCC recognizes the following expression to be a left bit-rotation:
27597 \layout Verse
27598
27599
27600 \family typewriter
27601 \series bold
27602 unsigned
27603 \series default
27604 \SpecialChar ~
27605 \SpecialChar ~
27606 char i;\SpecialChar ~
27607 \SpecialChar ~
27608 \SpecialChar ~
27609 \SpecialChar ~
27610 \SpecialChar ~
27611 \SpecialChar ~
27612 \SpecialChar ~
27613 \SpecialChar ~
27614 \SpecialChar ~
27615 \SpecialChar ~
27616 \SpecialChar ~
27617 /* unsigned is needed for rotation */
27618 \newline
27619 ...
27620
27621 \newline
27622 i = ((i << 1) | (i >> 7));
27623 \family default
27624
27625 \newline
27626
27627 \family typewriter
27628 ...
27629 \layout Standard
27630
27631 will generate the following code:
27632 \layout Verse
27633
27634
27635 \family typewriter
27636 mov\SpecialChar ~
27637 \SpecialChar ~
27638 a,_i
27639 \newline
27640 rl\SpecialChar ~
27641 \SpecialChar ~
27642 \SpecialChar ~
27643 a
27644 \newline
27645 mov\SpecialChar ~
27646 \SpecialChar ~
27647 _i,a
27648 \layout Standard
27649
27650 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
27651 ns of this case will also be recognized as bit-rotation, i.e.:
27652 \layout Verse
27653
27654
27655 \family typewriter
27656 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
27657 \layout Subsection
27658
27659 Nibble and Byte Swapping
27660 \layout Standard
27661
27662 Other special cases of the bit-shift operations are nibble or byte swapping
27663 \begin_inset LatexCommand \index{swapping nibbles/bytes}
27664
27665 \end_inset
27666
27667 , SDCC recognizes the following expressions:
27668 \layout Verse
27669
27670
27671 \family typewriter
27672 \series bold
27673 unsigned
27674 \series default
27675 \SpecialChar ~
27676 \SpecialChar ~
27677 char i;
27678 \newline
27679
27680 \series bold
27681 unsigned
27682 \series default
27683 \SpecialChar ~
27684 \SpecialChar ~
27685 int j;
27686 \newline
27687 ...
27688
27689 \newline
27690 i = ((i << 4) | (i >> 4));
27691 \family default
27692
27693 \newline
27694
27695 \family typewriter
27696 j = ((j << 8) | (j >> 8));
27697 \layout Standard
27698
27699 and generates a swap instruction for the nibble swapping
27700 \begin_inset LatexCommand \index{Nibble swapping}
27701
27702 \end_inset
27703
27704  or move instructions for the byte swapping
27705 \begin_inset LatexCommand \index{Byte swapping}
27706
27707 \end_inset
27708
27709 .
27710  The
27711 \begin_inset Quotes sld
27712 \end_inset
27713
27714 j
27715 \begin_inset Quotes srd
27716 \end_inset
27717
27718  example can be used to convert from little to big-endian or vice versa.
27719  If you want to change the endianness of a
27720 \emph on
27721 signed
27722 \emph default
27723  integer you have to cast to
27724 \family typewriter
27725 (unsigned int)
27726 \family default
27727  first.
27728 \layout Standard
27729
27730 Note that SDCC stores numbers in little-endian
27731 \begin_inset Foot
27732 collapsed false
27733
27734 \layout Standard
27735
27736 Usually 8-bit processors don't care much about endianness.
27737  This is not the case for the standard 8051 which only has an instruction
27738  to increment its
27739 \emph on
27740 dptr
27741 \emph default
27742
27743 \begin_inset LatexCommand \index{DPTR}
27744
27745 \end_inset
27746
27747 -datapointer
27748 \emph on
27749
27750 \emph default
27751 so little-endian is the more efficient byte order.
27752 \end_inset
27753
27754
27755 \begin_inset LatexCommand \index{little-endian}
27756
27757 \end_inset
27758
27759
27760 \begin_inset LatexCommand \index{Endianness}
27761
27762 \end_inset
27763
27764  format (i.e.
27765  lowest order first).
27766 \layout Subsection
27767
27768 Highest Order Bit
27769 \begin_inset LatexCommand \index{Highest Order Bit}
27770
27771 \end_inset
27772
27773  / Any Order Bit
27774 \begin_inset LatexCommand \index{Any Order Bit}
27775
27776 \end_inset
27777
27778
27779 \layout Standard
27780
27781 It is frequently required to obtain the highest order bit of an integral
27782  type (long, int, short or char types).
27783  Also obtaining any other order bit is not uncommon.
27784  SDCC recognizes the following expressions to yield the highest order bit
27785  and generates optimized code for it, e.g.:
27786 \layout Verse
27787
27788
27789 \family typewriter
27790 unsigned int gint;
27791 \newline
27792
27793 \newline
27794 foo () {
27795 \newline
27796 \SpecialChar ~
27797 \SpecialChar ~
27798 unsigned char hob1, aob1;
27799 \newline
27800 \SpecialChar ~
27801 \SpecialChar ~
27802 bit hob2, hob3, aob2, aob3;
27803 \newline
27804 \SpecialChar ~
27805 \SpecialChar ~
27806 ...
27807
27808 \newline
27809 \SpecialChar ~
27810 \SpecialChar ~
27811 hob1 = (gint >> 15) & 1;
27812 \newline
27813 \SpecialChar ~
27814 \SpecialChar ~
27815 hob2 = (gint >> 15) & 1;
27816 \newline
27817 \SpecialChar ~
27818 \SpecialChar ~
27819 hob3 = gint & 0x8000;
27820 \newline
27821 \SpecialChar ~
27822 \SpecialChar ~
27823 aob1 = (gint >> 9) & 1;
27824 \newline
27825 \SpecialChar ~
27826 \SpecialChar ~
27827 aob2 = (gint >> 8) & 1;
27828 \newline
27829 \SpecialChar ~
27830 \SpecialChar ~
27831 aob3 = gint & 0x0800;
27832 \newline
27833 \SpecialChar ~
27834 \SpecialChar ~
27835 ..
27836
27837 \newline
27838 }
27839 \layout Standard
27840
27841 will generate the following code:
27842 \layout Verse
27843
27844
27845 \family typewriter
27846 \SpecialChar ~
27847 \SpecialChar ~
27848 \SpecialChar ~
27849 \SpecialChar ~
27850 \SpecialChar ~
27851 \SpecialChar ~
27852 \SpecialChar ~
27853 \SpecialChar ~
27854 \SpecialChar ~
27855 \SpecialChar ~
27856 \SpecialChar ~
27857 \SpecialChar ~
27858 \SpecialChar ~
27859 \SpecialChar ~
27860 \SpecialChar ~
27861 \SpecialChar ~
27862 \SpecialChar ~
27863 \SpecialChar ~
27864 \SpecialChar ~
27865 \SpecialChar ~
27866 \SpecialChar ~
27867 \SpecialChar ~
27868 \SpecialChar ~
27869 \SpecialChar ~
27870 \SpecialChar ~
27871  61 ;\SpecialChar ~
27872  hob.c 7
27873 \newline
27874 000A E5*01\SpecialChar ~
27875 \SpecialChar ~
27876 \SpecialChar ~
27877 \SpecialChar ~
27878 \SpecialChar ~
27879 \SpecialChar ~
27880 \SpecialChar ~
27881 \SpecialChar ~
27882 \SpecialChar ~
27883 \SpecialChar ~
27884 \SpecialChar ~
27885 \SpecialChar ~
27886 \SpecialChar ~
27887 \SpecialChar ~
27888 \SpecialChar ~
27889  62\SpecialChar ~
27890 \SpecialChar ~
27891 \SpecialChar ~
27892 \SpecialChar ~
27893 \SpecialChar ~
27894 \SpecialChar ~
27895 \SpecialChar ~
27896 \SpecialChar ~
27897  mov\SpecialChar ~
27898 \SpecialChar ~
27899  a,(_gint + 1)
27900 \newline
27901 000C 23\SpecialChar ~
27902 \SpecialChar ~
27903 \SpecialChar ~
27904 \SpecialChar ~
27905 \SpecialChar ~
27906 \SpecialChar ~
27907 \SpecialChar ~
27908 \SpecialChar ~
27909 \SpecialChar ~
27910 \SpecialChar ~
27911 \SpecialChar ~
27912 \SpecialChar ~
27913 \SpecialChar ~
27914 \SpecialChar ~
27915 \SpecialChar ~
27916 \SpecialChar ~
27917 \SpecialChar ~
27918 \SpecialChar ~
27919  63\SpecialChar ~
27920 \SpecialChar ~
27921 \SpecialChar ~
27922 \SpecialChar ~
27923 \SpecialChar ~
27924 \SpecialChar ~
27925 \SpecialChar ~
27926 \SpecialChar ~
27927  rl\SpecialChar ~
27928 \SpecialChar ~
27929 \SpecialChar ~
27930  a
27931 \newline
27932 000D 54 01\SpecialChar ~
27933 \SpecialChar ~
27934 \SpecialChar ~
27935 \SpecialChar ~
27936 \SpecialChar ~
27937 \SpecialChar ~
27938 \SpecialChar ~
27939 \SpecialChar ~
27940 \SpecialChar ~
27941 \SpecialChar ~
27942 \SpecialChar ~
27943 \SpecialChar ~
27944 \SpecialChar ~
27945 \SpecialChar ~
27946 \SpecialChar ~
27947  64\SpecialChar ~
27948 \SpecialChar ~
27949 \SpecialChar ~
27950 \SpecialChar ~
27951 \SpecialChar ~
27952 \SpecialChar ~
27953 \SpecialChar ~
27954 \SpecialChar ~
27955  anl\SpecialChar ~
27956 \SpecialChar ~
27957  a,#0x01
27958 \newline
27959 000F F5*02\SpecialChar ~
27960 \SpecialChar ~
27961 \SpecialChar ~
27962 \SpecialChar ~
27963 \SpecialChar ~
27964 \SpecialChar ~
27965 \SpecialChar ~
27966 \SpecialChar ~
27967 \SpecialChar ~
27968 \SpecialChar ~
27969 \SpecialChar ~
27970 \SpecialChar ~
27971 \SpecialChar ~
27972 \SpecialChar ~
27973 \SpecialChar ~
27974  65\SpecialChar ~
27975 \SpecialChar ~
27976 \SpecialChar ~
27977 \SpecialChar ~
27978 \SpecialChar ~
27979 \SpecialChar ~
27980 \SpecialChar ~
27981 \SpecialChar ~
27982  mov\SpecialChar ~
27983 \SpecialChar ~
27984  _foo_hob1_1_1,a
27985 \newline
27986 \SpecialChar ~
27987 \SpecialChar ~
27988 \SpecialChar ~
27989 \SpecialChar ~
27990 \SpecialChar ~
27991 \SpecialChar ~
27992 \SpecialChar ~
27993 \SpecialChar ~
27994 \SpecialChar ~
27995 \SpecialChar ~
27996 \SpecialChar ~
27997 \SpecialChar ~
27998 \SpecialChar ~
27999 \SpecialChar ~
28000 \SpecialChar ~
28001 \SpecialChar ~
28002 \SpecialChar ~
28003 \SpecialChar ~
28004 \SpecialChar ~
28005 \SpecialChar ~
28006 \SpecialChar ~
28007 \SpecialChar ~
28008 \SpecialChar ~
28009 \SpecialChar ~
28010 \SpecialChar ~
28011  66 ;\SpecialChar ~
28012  hob.c 8
28013 \newline
28014 0011 E5*01\SpecialChar ~
28015 \SpecialChar ~
28016 \SpecialChar ~
28017 \SpecialChar ~
28018 \SpecialChar ~
28019 \SpecialChar ~
28020 \SpecialChar ~
28021 \SpecialChar ~
28022 \SpecialChar ~
28023 \SpecialChar ~
28024 \SpecialChar ~
28025 \SpecialChar ~
28026 \SpecialChar ~
28027 \SpecialChar ~
28028 \SpecialChar ~
28029  67\SpecialChar ~
28030 \SpecialChar ~
28031 \SpecialChar ~
28032 \SpecialChar ~
28033 \SpecialChar ~
28034 \SpecialChar ~
28035 \SpecialChar ~
28036 \SpecialChar ~
28037  mov\SpecialChar ~
28038 \SpecialChar ~
28039  a,(_gint + 1)
28040 \newline
28041 0013 33\SpecialChar ~
28042 \SpecialChar ~
28043 \SpecialChar ~
28044 \SpecialChar ~
28045 \SpecialChar ~
28046 \SpecialChar ~
28047 \SpecialChar ~
28048 \SpecialChar ~
28049 \SpecialChar ~
28050 \SpecialChar ~
28051 \SpecialChar ~
28052 \SpecialChar ~
28053 \SpecialChar ~
28054 \SpecialChar ~
28055 \SpecialChar ~
28056 \SpecialChar ~
28057 \SpecialChar ~
28058 \SpecialChar ~
28059  68\SpecialChar ~
28060 \SpecialChar ~
28061 \SpecialChar ~
28062 \SpecialChar ~
28063 \SpecialChar ~
28064 \SpecialChar ~
28065 \SpecialChar ~
28066 \SpecialChar ~
28067  rlc\SpecialChar ~
28068 \SpecialChar ~
28069  a
28070 \newline
28071 0014 92*00\SpecialChar ~
28072 \SpecialChar ~
28073 \SpecialChar ~
28074 \SpecialChar ~
28075 \SpecialChar ~
28076 \SpecialChar ~
28077 \SpecialChar ~
28078 \SpecialChar ~
28079 \SpecialChar ~
28080 \SpecialChar ~
28081 \SpecialChar ~
28082 \SpecialChar ~
28083 \SpecialChar ~
28084 \SpecialChar ~
28085 \SpecialChar ~
28086  69\SpecialChar ~
28087 \SpecialChar ~
28088 \SpecialChar ~
28089 \SpecialChar ~
28090 \SpecialChar ~
28091 \SpecialChar ~
28092 \SpecialChar ~
28093 \SpecialChar ~
28094  mov\SpecialChar ~
28095 \SpecialChar ~
28096  _foo_hob2_1_1,c
28097 \newline
28098 \SpecialChar ~
28099 \SpecialChar ~
28100 \SpecialChar ~
28101 \SpecialChar ~
28102 \SpecialChar ~
28103 \SpecialChar ~
28104 \SpecialChar ~
28105 \SpecialChar ~
28106 \SpecialChar ~
28107 \SpecialChar ~
28108 \SpecialChar ~
28109 \SpecialChar ~
28110 \SpecialChar ~
28111 \SpecialChar ~
28112 \SpecialChar ~
28113 \SpecialChar ~
28114 \SpecialChar ~
28115 \SpecialChar ~
28116 \SpecialChar ~
28117 \SpecialChar ~
28118 \SpecialChar ~
28119 \SpecialChar ~
28120 \SpecialChar ~
28121 \SpecialChar ~
28122 \SpecialChar ~
28123  66 ;\SpecialChar ~
28124  hob.c 9
28125 \newline
28126 0016 E5*01\SpecialChar ~
28127 \SpecialChar ~
28128 \SpecialChar ~
28129 \SpecialChar ~
28130 \SpecialChar ~
28131 \SpecialChar ~
28132 \SpecialChar ~
28133 \SpecialChar ~
28134 \SpecialChar ~
28135 \SpecialChar ~
28136 \SpecialChar ~
28137 \SpecialChar ~
28138 \SpecialChar ~
28139 \SpecialChar ~
28140 \SpecialChar ~
28141  67\SpecialChar ~
28142 \SpecialChar ~
28143 \SpecialChar ~
28144 \SpecialChar ~
28145 \SpecialChar ~
28146 \SpecialChar ~
28147 \SpecialChar ~
28148 \SpecialChar ~
28149  mov\SpecialChar ~
28150 \SpecialChar ~
28151  a,(_gint + 1)
28152 \newline
28153 0018 33\SpecialChar ~
28154 \SpecialChar ~
28155 \SpecialChar ~
28156 \SpecialChar ~
28157 \SpecialChar ~
28158 \SpecialChar ~
28159 \SpecialChar ~
28160 \SpecialChar ~
28161 \SpecialChar ~
28162 \SpecialChar ~
28163 \SpecialChar ~
28164 \SpecialChar ~
28165 \SpecialChar ~
28166 \SpecialChar ~
28167 \SpecialChar ~
28168 \SpecialChar ~
28169 \SpecialChar ~
28170 \SpecialChar ~
28171  68\SpecialChar ~
28172 \SpecialChar ~
28173 \SpecialChar ~
28174 \SpecialChar ~
28175 \SpecialChar ~
28176 \SpecialChar ~
28177 \SpecialChar ~
28178 \SpecialChar ~
28179  rlc\SpecialChar ~
28180 \SpecialChar ~
28181  a
28182 \newline
28183 0019 92*01\SpecialChar ~
28184 \SpecialChar ~
28185 \SpecialChar ~
28186 \SpecialChar ~
28187 \SpecialChar ~
28188 \SpecialChar ~
28189 \SpecialChar ~
28190 \SpecialChar ~
28191 \SpecialChar ~
28192 \SpecialChar ~
28193 \SpecialChar ~
28194 \SpecialChar ~
28195 \SpecialChar ~
28196 \SpecialChar ~
28197 \SpecialChar ~
28198  69\SpecialChar ~
28199 \SpecialChar ~
28200 \SpecialChar ~
28201 \SpecialChar ~
28202 \SpecialChar ~
28203 \SpecialChar ~
28204 \SpecialChar ~
28205 \SpecialChar ~
28206  mov\SpecialChar ~
28207 \SpecialChar ~
28208  _foo_hob3_1_1,c
28209 \newline
28210 \SpecialChar ~
28211 \SpecialChar ~
28212 \SpecialChar ~
28213 \SpecialChar ~
28214 \SpecialChar ~
28215 \SpecialChar ~
28216 \SpecialChar ~
28217 \SpecialChar ~
28218 \SpecialChar ~
28219 \SpecialChar ~
28220 \SpecialChar ~
28221 \SpecialChar ~
28222 \SpecialChar ~
28223 \SpecialChar ~
28224 \SpecialChar ~
28225 \SpecialChar ~
28226 \SpecialChar ~
28227 \SpecialChar ~
28228 \SpecialChar ~
28229 \SpecialChar ~
28230 \SpecialChar ~
28231 \SpecialChar ~
28232 \SpecialChar ~
28233 \SpecialChar ~
28234 \SpecialChar ~
28235  70 ;\SpecialChar ~
28236  hob.c 10
28237 \newline
28238 001B E5*01\SpecialChar ~
28239 \SpecialChar ~
28240 \SpecialChar ~
28241 \SpecialChar ~
28242 \SpecialChar ~
28243 \SpecialChar ~
28244 \SpecialChar ~
28245 \SpecialChar ~
28246 \SpecialChar ~
28247 \SpecialChar ~
28248 \SpecialChar ~
28249 \SpecialChar ~
28250 \SpecialChar ~
28251 \SpecialChar ~
28252 \SpecialChar ~
28253  71\SpecialChar ~
28254 \SpecialChar ~
28255 \SpecialChar ~
28256 \SpecialChar ~
28257 \SpecialChar ~
28258 \SpecialChar ~
28259 \SpecialChar ~
28260 \SpecialChar ~
28261  mov\SpecialChar ~
28262 \SpecialChar ~
28263  a,(_gint + 1)
28264 \newline
28265 001D 03\SpecialChar ~
28266 \SpecialChar ~
28267 \SpecialChar ~
28268 \SpecialChar ~
28269 \SpecialChar ~
28270 \SpecialChar ~
28271 \SpecialChar ~
28272 \SpecialChar ~
28273 \SpecialChar ~
28274 \SpecialChar ~
28275 \SpecialChar ~
28276 \SpecialChar ~
28277 \SpecialChar ~
28278 \SpecialChar ~
28279 \SpecialChar ~
28280 \SpecialChar ~
28281 \SpecialChar ~
28282 \SpecialChar ~
28283  72\SpecialChar ~
28284 \SpecialChar ~
28285 \SpecialChar ~
28286 \SpecialChar ~
28287 \SpecialChar ~
28288 \SpecialChar ~
28289 \SpecialChar ~
28290 \SpecialChar ~
28291  rr\SpecialChar ~
28292 \SpecialChar ~
28293 \SpecialChar ~
28294  a
28295 \newline
28296 001E 54 01\SpecialChar ~
28297 \SpecialChar ~
28298 \SpecialChar ~
28299 \SpecialChar ~
28300 \SpecialChar ~
28301 \SpecialChar ~
28302 \SpecialChar ~
28303 \SpecialChar ~
28304 \SpecialChar ~
28305 \SpecialChar ~
28306 \SpecialChar ~
28307 \SpecialChar ~
28308 \SpecialChar ~
28309 \SpecialChar ~
28310 \SpecialChar ~
28311  73\SpecialChar ~
28312 \SpecialChar ~
28313 \SpecialChar ~
28314 \SpecialChar ~
28315 \SpecialChar ~
28316 \SpecialChar ~
28317 \SpecialChar ~
28318 \SpecialChar ~
28319  anl\SpecialChar ~
28320 \SpecialChar ~
28321  a,#0x01
28322 \newline
28323 0020 F5*03\SpecialChar ~
28324 \SpecialChar ~
28325 \SpecialChar ~
28326 \SpecialChar ~
28327 \SpecialChar ~
28328 \SpecialChar ~
28329 \SpecialChar ~
28330 \SpecialChar ~
28331 \SpecialChar ~
28332 \SpecialChar ~
28333 \SpecialChar ~
28334 \SpecialChar ~
28335 \SpecialChar ~
28336 \SpecialChar ~
28337 \SpecialChar ~
28338  74\SpecialChar ~
28339 \SpecialChar ~
28340 \SpecialChar ~
28341 \SpecialChar ~
28342 \SpecialChar ~
28343 \SpecialChar ~
28344 \SpecialChar ~
28345 \SpecialChar ~
28346  mov\SpecialChar ~
28347 \SpecialChar ~
28348  _foo_aob1_1_1,a
28349 \newline
28350 \SpecialChar ~
28351 \SpecialChar ~
28352 \SpecialChar ~
28353 \SpecialChar ~
28354 \SpecialChar ~
28355 \SpecialChar ~
28356 \SpecialChar ~
28357 \SpecialChar ~
28358 \SpecialChar ~
28359 \SpecialChar ~
28360 \SpecialChar ~
28361 \SpecialChar ~
28362 \SpecialChar ~
28363 \SpecialChar ~
28364 \SpecialChar ~
28365 \SpecialChar ~
28366 \SpecialChar ~
28367 \SpecialChar ~
28368 \SpecialChar ~
28369 \SpecialChar ~
28370 \SpecialChar ~
28371 \SpecialChar ~
28372 \SpecialChar ~
28373 \SpecialChar ~
28374 \SpecialChar ~
28375  75 ;\SpecialChar ~
28376  hob.c 11
28377 \newline
28378 0022 E5*01\SpecialChar ~
28379 \SpecialChar ~
28380 \SpecialChar ~
28381 \SpecialChar ~
28382 \SpecialChar ~
28383 \SpecialChar ~
28384 \SpecialChar ~
28385 \SpecialChar ~
28386 \SpecialChar ~
28387 \SpecialChar ~
28388 \SpecialChar ~
28389 \SpecialChar ~
28390 \SpecialChar ~
28391 \SpecialChar ~
28392 \SpecialChar ~
28393  76\SpecialChar ~
28394 \SpecialChar ~
28395 \SpecialChar ~
28396 \SpecialChar ~
28397 \SpecialChar ~
28398 \SpecialChar ~
28399 \SpecialChar ~
28400 \SpecialChar ~
28401  mov\SpecialChar ~
28402 \SpecialChar ~
28403  a,(_gint + 1)
28404 \newline
28405 0024 13\SpecialChar ~
28406 \SpecialChar ~
28407 \SpecialChar ~
28408 \SpecialChar ~
28409 \SpecialChar ~
28410 \SpecialChar ~
28411 \SpecialChar ~
28412 \SpecialChar ~
28413 \SpecialChar ~
28414 \SpecialChar ~
28415 \SpecialChar ~
28416 \SpecialChar ~
28417 \SpecialChar ~
28418 \SpecialChar ~
28419 \SpecialChar ~
28420 \SpecialChar ~
28421 \SpecialChar ~
28422 \SpecialChar ~
28423  77\SpecialChar ~
28424 \SpecialChar ~
28425 \SpecialChar ~
28426 \SpecialChar ~
28427 \SpecialChar ~
28428 \SpecialChar ~
28429 \SpecialChar ~
28430 \SpecialChar ~
28431  rrc\SpecialChar ~
28432 \SpecialChar ~
28433  a
28434 \newline
28435 0025 92*02\SpecialChar ~
28436 \SpecialChar ~
28437 \SpecialChar ~
28438 \SpecialChar ~
28439 \SpecialChar ~
28440 \SpecialChar ~
28441 \SpecialChar ~
28442 \SpecialChar ~
28443 \SpecialChar ~
28444 \SpecialChar ~
28445 \SpecialChar ~
28446 \SpecialChar ~
28447 \SpecialChar ~
28448 \SpecialChar ~
28449 \SpecialChar ~
28450  78\SpecialChar ~
28451 \SpecialChar ~
28452 \SpecialChar ~
28453 \SpecialChar ~
28454 \SpecialChar ~
28455 \SpecialChar ~
28456 \SpecialChar ~
28457 \SpecialChar ~
28458  mov\SpecialChar ~
28459 \SpecialChar ~
28460  _foo_aob2_1_1,c
28461 \newline
28462 \SpecialChar ~
28463 \SpecialChar ~
28464 \SpecialChar ~
28465 \SpecialChar ~
28466 \SpecialChar ~
28467 \SpecialChar ~
28468 \SpecialChar ~
28469 \SpecialChar ~
28470 \SpecialChar ~
28471 \SpecialChar ~
28472 \SpecialChar ~
28473 \SpecialChar ~
28474 \SpecialChar ~
28475 \SpecialChar ~
28476 \SpecialChar ~
28477 \SpecialChar ~
28478 \SpecialChar ~
28479 \SpecialChar ~
28480 \SpecialChar ~
28481 \SpecialChar ~
28482 \SpecialChar ~
28483 \SpecialChar ~
28484 \SpecialChar ~
28485 \SpecialChar ~
28486 \SpecialChar ~
28487  79 ;\SpecialChar ~
28488  hob.c 12
28489 \newline
28490 0027 E5*01\SpecialChar ~
28491 \SpecialChar ~
28492 \SpecialChar ~
28493 \SpecialChar ~
28494 \SpecialChar ~
28495 \SpecialChar ~
28496 \SpecialChar ~
28497 \SpecialChar ~
28498 \SpecialChar ~
28499 \SpecialChar ~
28500 \SpecialChar ~
28501 \SpecialChar ~
28502 \SpecialChar ~
28503 \SpecialChar ~
28504 \SpecialChar ~
28505  80\SpecialChar ~
28506 \SpecialChar ~
28507 \SpecialChar ~
28508 \SpecialChar ~
28509 \SpecialChar ~
28510 \SpecialChar ~
28511 \SpecialChar ~
28512 \SpecialChar ~
28513  mov\SpecialChar ~
28514 \SpecialChar ~
28515  a,(_gint + 1)
28516 \newline
28517 0029 A2 E3\SpecialChar ~
28518 \SpecialChar ~
28519 \SpecialChar ~
28520 \SpecialChar ~
28521 \SpecialChar ~
28522 \SpecialChar ~
28523 \SpecialChar ~
28524 \SpecialChar ~
28525 \SpecialChar ~
28526 \SpecialChar ~
28527 \SpecialChar ~
28528 \SpecialChar ~
28529 \SpecialChar ~
28530 \SpecialChar ~
28531 \SpecialChar ~
28532  81\SpecialChar ~
28533 \SpecialChar ~
28534 \SpecialChar ~
28535 \SpecialChar ~
28536 \SpecialChar ~
28537 \SpecialChar ~
28538 \SpecialChar ~
28539 \SpecialChar ~
28540  mov\SpecialChar ~
28541 \SpecialChar ~
28542  c,acc[3]
28543 \newline
28544 002B 92*03\SpecialChar ~
28545 \SpecialChar ~
28546 \SpecialChar ~
28547 \SpecialChar ~
28548 \SpecialChar ~
28549 \SpecialChar ~
28550 \SpecialChar ~
28551 \SpecialChar ~
28552 \SpecialChar ~
28553 \SpecialChar ~
28554 \SpecialChar ~
28555 \SpecialChar ~
28556 \SpecialChar ~
28557 \SpecialChar ~
28558 \SpecialChar ~
28559  82\SpecialChar ~
28560 \SpecialChar ~
28561 \SpecialChar ~
28562 \SpecialChar ~
28563 \SpecialChar ~
28564 \SpecialChar ~
28565 \SpecialChar ~
28566 \SpecialChar ~
28567  mov\SpecialChar ~
28568 \SpecialChar ~
28569  _foo_aob3_1_1,c
28570 \layout Standard
28571
28572 Other variations of these cases however will
28573 \emph on
28574 not
28575 \emph default
28576  be recognized.
28577  They are standard C expressions, so I heartily recommend these be the only
28578  way to get the highest order bit, (it is portable).
28579  Of course it will be recognized even if it is embedded in other expressions,
28580  e.g.:
28581 \layout Verse
28582
28583
28584 \family typewriter
28585 xyz = gint + ((gint >> 15) & 1);
28586 \layout Standard
28587
28588 will still be recognized.
28589 \layout Subsection
28590
28591 Higher Order Byte
28592 \begin_inset LatexCommand \index{Higher Order Byte}
28593
28594 \end_inset
28595
28596  / Higher Order Word
28597 \begin_inset LatexCommand \index{Higher Order Word}
28598
28599 \end_inset
28600
28601
28602 \layout Standard
28603
28604 It is also frequently required to obtain a higher order byte or word of
28605  a larger integral type (long, int or short types).
28606  SDCC recognizes the following expressions to yield the higher order byte
28607  or word and generates optimized code for it, e.g.:
28608 \layout Verse
28609
28610
28611 \family typewriter
28612 unsigned int gint;
28613 \newline
28614 unsigned long int glong;
28615 \newline
28616
28617 \newline
28618 foo () {
28619 \newline
28620 \SpecialChar ~
28621 \SpecialChar ~
28622 unsigned char hob1, hob2;
28623 \newline
28624 \SpecialChar ~
28625 \SpecialChar ~
28626 unsigned int how1, how2;
28627 \newline
28628 \SpecialChar ~
28629 \SpecialChar ~
28630 ...
28631
28632 \newline
28633 \SpecialChar ~
28634 \SpecialChar ~
28635 hob1 = (gint >> 8) & 0xFF;
28636 \newline
28637 \SpecialChar ~
28638 \SpecialChar ~
28639 hob2 = glong >> 24;
28640 \newline
28641 \SpecialChar ~
28642 \SpecialChar ~
28643 how1 = (glong >> 16) & 0xFFFF;
28644 \newline
28645 \SpecialChar ~
28646 \SpecialChar ~
28647 how2 = glong >> 8;
28648 \newline
28649 \SpecialChar ~
28650 \SpecialChar ~
28651 ..
28652
28653 \newline
28654 }
28655 \layout Standard
28656
28657 will generate the following code:
28658 \layout Verse
28659
28660
28661 \family typewriter
28662 \SpecialChar ~
28663 \SpecialChar ~
28664 \SpecialChar ~
28665 \SpecialChar ~
28666 \SpecialChar ~
28667 \SpecialChar ~
28668 \SpecialChar ~
28669 \SpecialChar ~
28670 \SpecialChar ~
28671 \SpecialChar ~
28672 \SpecialChar ~
28673 \SpecialChar ~
28674 \SpecialChar ~
28675 \SpecialChar ~
28676 \SpecialChar ~
28677 \SpecialChar ~
28678 \SpecialChar ~
28679 \SpecialChar ~
28680 \SpecialChar ~
28681 \SpecialChar ~
28682 \SpecialChar ~
28683 \SpecialChar ~
28684 \SpecialChar ~
28685 \SpecialChar ~
28686 \SpecialChar ~
28687  91 ;\SpecialChar ~
28688  hob.c 15
28689 \newline
28690 0037 85*01*06\SpecialChar ~
28691 \SpecialChar ~
28692 \SpecialChar ~
28693 \SpecialChar ~
28694 \SpecialChar ~
28695 \SpecialChar ~
28696 \SpecialChar ~
28697 \SpecialChar ~
28698 \SpecialChar ~
28699 \SpecialChar ~
28700 \SpecialChar ~
28701 \SpecialChar ~
28702  92\SpecialChar ~
28703 \SpecialChar ~
28704 \SpecialChar ~
28705 \SpecialChar ~
28706 \SpecialChar ~
28707 \SpecialChar ~
28708 \SpecialChar ~
28709 \SpecialChar ~
28710  mov\SpecialChar ~
28711 \SpecialChar ~
28712  _foo_hob1_1_1,(_gint + 1)
28713 \newline
28714 \SpecialChar ~
28715 \SpecialChar ~
28716 \SpecialChar ~
28717 \SpecialChar ~
28718 \SpecialChar ~
28719 \SpecialChar ~
28720 \SpecialChar ~
28721 \SpecialChar ~
28722 \SpecialChar ~
28723 \SpecialChar ~
28724 \SpecialChar ~
28725 \SpecialChar ~
28726 \SpecialChar ~
28727 \SpecialChar ~
28728 \SpecialChar ~
28729 \SpecialChar ~
28730 \SpecialChar ~
28731 \SpecialChar ~
28732 \SpecialChar ~
28733 \SpecialChar ~
28734 \SpecialChar ~
28735 \SpecialChar ~
28736 \SpecialChar ~
28737 \SpecialChar ~
28738 \SpecialChar ~
28739  93 ;\SpecialChar ~
28740  hob.c 16
28741 \newline
28742 003A 85*05*07\SpecialChar ~
28743 \SpecialChar ~
28744 \SpecialChar ~
28745 \SpecialChar ~
28746 \SpecialChar ~
28747 \SpecialChar ~
28748 \SpecialChar ~
28749 \SpecialChar ~
28750 \SpecialChar ~
28751 \SpecialChar ~
28752 \SpecialChar ~
28753 \SpecialChar ~
28754  94\SpecialChar ~
28755 \SpecialChar ~
28756 \SpecialChar ~
28757 \SpecialChar ~
28758 \SpecialChar ~
28759 \SpecialChar ~
28760 \SpecialChar ~
28761 \SpecialChar ~
28762  mov\SpecialChar ~
28763 \SpecialChar ~
28764  _foo_hob2_1_1,(_glong + 3)
28765 \newline
28766 \SpecialChar ~
28767 \SpecialChar ~
28768 \SpecialChar ~
28769 \SpecialChar ~
28770 \SpecialChar ~
28771 \SpecialChar ~
28772 \SpecialChar ~
28773 \SpecialChar ~
28774 \SpecialChar ~
28775 \SpecialChar ~
28776 \SpecialChar ~
28777 \SpecialChar ~
28778 \SpecialChar ~
28779 \SpecialChar ~
28780 \SpecialChar ~
28781 \SpecialChar ~
28782 \SpecialChar ~
28783 \SpecialChar ~
28784 \SpecialChar ~
28785 \SpecialChar ~
28786 \SpecialChar ~
28787 \SpecialChar ~
28788 \SpecialChar ~
28789 \SpecialChar ~
28790 \SpecialChar ~
28791  95 ;\SpecialChar ~
28792  hob.c 17
28793 \newline
28794 003D 85*04*08\SpecialChar ~
28795 \SpecialChar ~
28796 \SpecialChar ~
28797 \SpecialChar ~
28798 \SpecialChar ~
28799 \SpecialChar ~
28800 \SpecialChar ~
28801 \SpecialChar ~
28802 \SpecialChar ~
28803 \SpecialChar ~
28804 \SpecialChar ~
28805 \SpecialChar ~
28806  96\SpecialChar ~
28807 \SpecialChar ~
28808 \SpecialChar ~
28809 \SpecialChar ~
28810 \SpecialChar ~
28811 \SpecialChar ~
28812 \SpecialChar ~
28813 \SpecialChar ~
28814  mov\SpecialChar ~
28815 \SpecialChar ~
28816  _foo_how1_1_1,(_glong + 2)
28817 \newline
28818 0040 85*05*09\SpecialChar ~
28819 \SpecialChar ~
28820 \SpecialChar ~
28821 \SpecialChar ~
28822 \SpecialChar ~
28823 \SpecialChar ~
28824 \SpecialChar ~
28825 \SpecialChar ~
28826 \SpecialChar ~
28827 \SpecialChar ~
28828 \SpecialChar ~
28829 \SpecialChar ~
28830  97\SpecialChar ~
28831 \SpecialChar ~
28832 \SpecialChar ~
28833 \SpecialChar ~
28834 \SpecialChar ~
28835 \SpecialChar ~
28836 \SpecialChar ~
28837 \SpecialChar ~
28838  mov\SpecialChar ~
28839 \SpecialChar ~
28840  (_foo_how1_1_1 + 1),(_glong + 3)
28841 \newline
28842 0043 85*03*0A\SpecialChar ~
28843 \SpecialChar ~
28844 \SpecialChar ~
28845 \SpecialChar ~
28846 \SpecialChar ~
28847 \SpecialChar ~
28848 \SpecialChar ~
28849 \SpecialChar ~
28850 \SpecialChar ~
28851 \SpecialChar ~
28852 \SpecialChar ~
28853 \SpecialChar ~
28854  98\SpecialChar ~
28855 \SpecialChar ~
28856 \SpecialChar ~
28857 \SpecialChar ~
28858 \SpecialChar ~
28859 \SpecialChar ~
28860 \SpecialChar ~
28861 \SpecialChar ~
28862  mov\SpecialChar ~
28863 \SpecialChar ~
28864  _foo_how2_1_1,(_glong + 1)
28865 \newline
28866 0046 85*04*0B\SpecialChar ~
28867 \SpecialChar ~
28868 \SpecialChar ~
28869 \SpecialChar ~
28870 \SpecialChar ~
28871 \SpecialChar ~
28872 \SpecialChar ~
28873 \SpecialChar ~
28874 \SpecialChar ~
28875 \SpecialChar ~
28876 \SpecialChar ~
28877 \SpecialChar ~
28878  99\SpecialChar ~
28879 \SpecialChar ~
28880 \SpecialChar ~
28881 \SpecialChar ~
28882 \SpecialChar ~
28883 \SpecialChar ~
28884 \SpecialChar ~
28885 \SpecialChar ~
28886  mov\SpecialChar ~
28887 \SpecialChar ~
28888  (_foo_how2_1_1 + 1),(_glong + 2)
28889 \layout Standard
28890
28891 Again, variations of these cases may
28892 \emph on
28893 not
28894 \emph default
28895  be recognized.
28896  They are standard C expressions, so I heartily recommend these be the only
28897  way to get the higher order byte/word, (it is portable).
28898  Of course it will be recognized even if it is embedded in other expressions,
28899  e.g.:
28900 \layout Verse
28901
28902
28903 \family typewriter
28904 xyz = gint + ((gint >> 8) & 0xFF);
28905 \layout Standard
28906
28907 will still be recognized.
28908 \layout Subsection
28909
28910 Peephole Optimizer
28911 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
28912
28913 \end_inset
28914
28915
28916 \begin_inset LatexCommand \index{Peephole optimizer}
28917
28918 \end_inset
28919
28920
28921 \layout Standard
28922
28923 The compiler uses a rule based, pattern matching and re-writing mechanism
28924  for peep-hole optimization.
28925  It is inspired by
28926 \emph on
28927 copt
28928 \emph default
28929  a peep-hole optimizer by Christopher W.
28930  Fraser (cwfraser\SpecialChar ~
28931 @\SpecialChar ~
28932 microsoft.com).
28933  A default set of rules are compiled into the compiler, additional rules
28934  may be added with the
28935 \emph on
28936 -
28937 \begin_inset ERT
28938 status Collapsed
28939
28940 \layout Standard
28941
28942 \backslash
28943 /
28944 \end_inset
28945
28946 -peep-file
28947 \begin_inset LatexCommand \index{-\/-peep-file}
28948
28949 \end_inset
28950
28951  <filename>
28952 \emph default
28953  option.
28954  The rule language is best illustrated with examples.
28955 \layout Verse
28956
28957
28958 \family typewriter
28959 replace {
28960 \newline
28961 \SpecialChar ~
28962 \SpecialChar ~
28963 mov %1,a
28964 \newline
28965 \SpecialChar ~
28966 \SpecialChar ~
28967 mov a,%1
28968 \newline
28969 } by {
28970 \newline
28971 \SpecialChar ~
28972 \SpecialChar ~
28973 mov %1,a
28974 \newline
28975 }
28976 \layout Standard
28977
28978 The above rule will change the following assembly
28979 \begin_inset LatexCommand \index{Assembler routines}
28980
28981 \end_inset
28982
28983  sequence:
28984 \layout Verse
28985
28986
28987 \family typewriter
28988 mov r1,a
28989 \newline
28990 mov a,r1
28991 \layout Standard
28992
28993 to
28994 \layout Verse
28995
28996
28997 \family typewriter
28998 mov r1,a
28999 \layout Standard
29000
29001 Note: All occurrences of a
29002 \emph on
29003 %n
29004 \emph default
29005  (pattern variable) must denote the same string.
29006  With the above rule, the assembly sequence:
29007 \layout Verse
29008
29009
29010 \family typewriter
29011 mov r1,a
29012 \newline
29013 mov a,r2
29014 \layout Standard
29015
29016 will remain unmodified.
29017 \newline
29018
29019 \newline
29020 Other special case optimizations may be added by the user (via
29021 \emph on
29022 -
29023 \begin_inset ERT
29024 status Collapsed
29025
29026 \layout Standard
29027
29028 \backslash
29029 /
29030 \end_inset
29031
29032 -peep-file option
29033 \emph default
29034 ).
29035  E.g.
29036  some variants of the 8051 MCU
29037 \begin_inset LatexCommand \index{MCS51 variants}
29038
29039 \end_inset
29040
29041  allow only
29042 \family typewriter
29043 ajmp
29044 \family default
29045  and
29046 \family typewriter
29047 acall
29048 \family default
29049 .
29050  The following two rules will change all
29051 \family typewriter
29052 ljmp
29053 \family default
29054  and
29055 \family typewriter
29056 lcall
29057 \family default
29058  to
29059 \family typewriter
29060 ajmp
29061 \family default
29062  and
29063 \family typewriter
29064 acall
29065 \layout Verse
29066
29067
29068 \family typewriter
29069 replace { lcall %1 } by { acall %1 }
29070 \newline
29071 replace { ljmp %1 } by { ajmp %1 }
29072 \layout Standard
29073
29074 The
29075 \emph on
29076 inline-assembler code
29077 \emph default
29078  is also passed through the peep hole optimizer, thus the peephole optimizer
29079  can also be used as an assembly level macro expander.
29080  The rules themselves are MCU dependent whereas the rule language infra-structur
29081 e is MCU independent.
29082  Peephole optimization rules for other MCU can be easily programmed using
29083  the rule language.
29084 \newline
29085
29086 \newline
29087 The syntax for a rule is as follows:
29088 \layout Verse
29089
29090
29091 \family typewriter
29092 rule := replace [ restart ] '{' <assembly sequence> '
29093 \backslash
29094 n'
29095 \newline
29096 \SpecialChar ~
29097  \SpecialChar ~
29098  \SpecialChar ~
29099  \SpecialChar ~
29100  \SpecialChar ~
29101  \SpecialChar ~
29102  \SpecialChar ~
29103  \SpecialChar ~
29104  \SpecialChar ~
29105  \SpecialChar ~
29106  \SpecialChar ~
29107  \SpecialChar ~
29108  \SpecialChar ~
29109  \SpecialChar ~
29110  '}' by '{' '
29111 \backslash
29112 n'
29113 \newline
29114 \SpecialChar ~
29115  \SpecialChar ~
29116  \SpecialChar ~
29117  \SpecialChar ~
29118  \SpecialChar ~
29119  \SpecialChar ~
29120  \SpecialChar ~
29121  \SpecialChar ~
29122  \SpecialChar ~
29123  \SpecialChar ~
29124  \SpecialChar ~
29125  \SpecialChar ~
29126  \SpecialChar ~
29127  \SpecialChar ~
29128  \SpecialChar ~
29129  \SpecialChar ~
29130  <assembly sequence> '
29131 \backslash
29132 n'
29133 \newline
29134 \SpecialChar ~
29135  \SpecialChar ~
29136  \SpecialChar ~
29137  \SpecialChar ~
29138  \SpecialChar ~
29139  \SpecialChar ~
29140  \SpecialChar ~
29141  \SpecialChar ~
29142  \SpecialChar ~
29143  \SpecialChar ~
29144  \SpecialChar ~
29145  \SpecialChar ~
29146  \SpecialChar ~
29147  \SpecialChar ~
29148  '}' [if <functionName> ] '
29149 \backslash
29150 n'
29151 \layout Standard
29152
29153 <assembly sequence> := assembly instruction (each instruction including
29154  labels must be on a separate line).
29155 \newline
29156
29157 \newline
29158 The optimizer will apply to the rules one by one from the top in the sequence
29159  of their appearance, it will terminate when all rules are exhausted.
29160  If the 'restart' option is specified, then the optimizer will start matching
29161  the rules again from the top, this option for a rule is expensive (performance)
29162 , it is intended to be used in situations where a transformation will trigger
29163  the same rule again.
29164  An example of this (not a good one, it has side effects) is the following
29165  rule:
29166 \layout Verse
29167
29168
29169 \family typewriter
29170 replace restart {
29171 \newline
29172 \SpecialChar ~
29173 \SpecialChar ~
29174 pop %1
29175 \newline
29176 \SpecialChar ~
29177 \SpecialChar ~
29178 push %1 } by {
29179 \newline
29180 \SpecialChar ~
29181 \SpecialChar ~
29182 ; nop
29183 \newline
29184 }
29185 \layout Standard
29186
29187 Note that the replace pattern cannot be a blank, but can be a comment line.
29188  Without the 'restart' option only the innermost 'pop' 'push' pair would
29189  be eliminated, i.e.:
29190 \layout Verse
29191
29192
29193 \family typewriter
29194 pop ar1
29195 \newline
29196 pop ar2
29197 \newline
29198 push ar2
29199 \newline
29200 push ar1
29201 \layout Standard
29202
29203 would result in:
29204 \layout Verse
29205
29206
29207 \family typewriter
29208 pop ar1
29209 \newline
29210 ; nop
29211 \newline
29212 push ar1
29213 \layout Standard
29214
29215
29216 \emph on
29217 with
29218 \emph default
29219  the restart option the rule will be applied again to the resulting code
29220  and then all the pop-push pairs will be eliminated to yield:
29221 \layout Verse
29222
29223
29224 \family typewriter
29225 ; nop
29226 \newline
29227 ; nop
29228 \layout Standard
29229
29230 A conditional function can be attached to a rule.
29231  Attaching rules are somewhat more involved, let me illustrate this with
29232  an example.
29233 \layout Verse
29234
29235
29236 \family typewriter
29237 replace {
29238 \newline
29239 \SpecialChar ~
29240  \SpecialChar ~
29241  \SpecialChar ~
29242 ljmp %5
29243 \newline
29244 %2:
29245 \newline
29246 } by {
29247 \newline
29248 \SpecialChar ~
29249  \SpecialChar ~
29250  \SpecialChar ~
29251 sjmp %5
29252 \newline
29253 %2:
29254 \newline
29255 } if labelInRange
29256 \layout Standard
29257
29258 The optimizer does a look-up of a function name table defined in function
29259
29260 \emph on
29261 callFuncByName
29262 \emph default
29263  in the source file SDCCpeeph.c, with the name
29264 \emph on
29265 labelInRange
29266 \emph default
29267 .
29268  If it finds a corresponding entry the function is called.
29269  Note there can be no parameters specified for these functions, in this
29270  case the use of
29271 \emph on
29272 %5
29273 \emph default
29274  is crucial, since the function
29275 \emph on
29276 labelInRange
29277 \emph default
29278  expects to find the label in that particular variable (the hash table containin
29279 g the variable bindings is passed as a parameter).
29280  If you want to code more such functions, take a close look at the function
29281  labelInRange and the calling mechanism in source file SDCCpeeph.c.
29282  Currently implemented are
29283 \emph on
29284 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
29285  24bitMode, portIsDS390, 24bitModeAndPortDS390
29286 \emph default
29287 and
29288 \emph on
29289  notVolatile
29290 \emph default
29291 .
29292 \layout Standard
29293
29294 I know this whole thing is a little kludgey, but maybe some day we will
29295  have some better means.
29296  If you are looking at this file, you will see the default rules that are
29297  compiled into the compiler, you can add your own rules in the default set
29298  there if you get tired of specifying the -
29299 \begin_inset ERT
29300 status Collapsed
29301
29302 \layout Standard
29303
29304 \backslash
29305 /
29306 \end_inset
29307
29308 -peep-file option.
29309 \layout Section
29310
29311 ANSI-Compliance
29312 \begin_inset LatexCommand \index{ANSI-compliance}
29313
29314 \end_inset
29315
29316
29317 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
29318
29319 \end_inset
29320
29321
29322 \layout Standard
29323
29324 The latest publically available version of the standard
29325 \emph on
29326 ISO/IEC 9899 - Programming languages - C
29327 \emph default
29328  should be available at:
29329 \begin_inset LatexCommand \url{http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899}
29330
29331 \end_inset
29332
29333 .
29334 \newline
29335
29336 \layout Standard
29337
29338 Deviations from the compliance:
29339 \layout Itemize
29340
29341 functions are not reentrant
29342 \begin_inset LatexCommand \index{reentrant}
29343
29344 \end_inset
29345
29346  unless explicitly declared as such or the
29347 \series bold
29348 -
29349 \begin_inset ERT
29350 status Collapsed
29351
29352 \layout Standard
29353
29354 \backslash
29355 /
29356 \end_inset
29357
29358 -stack-auto
29359 \begin_inset LatexCommand \index{-\/-stack-auto}
29360
29361 \end_inset
29362
29363
29364 \series default
29365  command line option is specified.
29366 \layout Itemize
29367
29368 structures
29369 \begin_inset LatexCommand \index{struct}
29370
29371 \end_inset
29372
29373  and unions
29374 \begin_inset LatexCommand \index{union}
29375
29376 \end_inset
29377
29378  cannot be assigned values directly, cannot be passed as function parameters
29379  or assigned to each other and cannot be a return value
29380 \begin_inset LatexCommand \index{return value}
29381
29382 \end_inset
29383
29384  from a function, e.g.:
29385 \begin_deeper
29386 \layout Verse
29387
29388
29389 \family typewriter
29390 struct s { ...
29391  };
29392 \newline
29393 struct s s1, s2;
29394 \newline
29395 foo()
29396 \newline
29397 {
29398 \newline
29399 \SpecialChar ~
29400 \SpecialChar ~
29401 \SpecialChar ~
29402 \SpecialChar ~
29403 ...
29404
29405 \newline
29406 \SpecialChar ~
29407 \SpecialChar ~
29408 \SpecialChar ~
29409 \SpecialChar ~
29410 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
29411 \newline
29412 \SpecialChar ~
29413 \SpecialChar ~
29414 \SpecialChar ~
29415 \SpecialChar ~
29416 ...
29417
29418 \newline
29419 }
29420 \newline
29421
29422 \series bold
29423 struct
29424 \series default
29425  s foo1 (
29426 \series bold
29427 struct
29428 \series default
29429  s parms) /* invalid in SDCC although allowed in ANSI */
29430 \newline
29431 {
29432 \newline
29433 \SpecialChar ~
29434 \SpecialChar ~
29435 \SpecialChar ~
29436 \SpecialChar ~
29437 struct s rets;
29438 \newline
29439 \SpecialChar ~
29440 \SpecialChar ~
29441 \SpecialChar ~
29442 \SpecialChar ~
29443 ...
29444
29445 \newline
29446 \SpecialChar ~
29447 \SpecialChar ~
29448 \SpecialChar ~
29449 \SpecialChar ~
29450 return rets; /* is invalid in SDCC although allowed in ANSI */
29451 \newline
29452 }
29453 \end_deeper
29454 \layout Itemize
29455
29456 initialization of structure arrays must be fully braced.
29457 \begin_deeper
29458 \layout Verse
29459
29460
29461 \family typewriter
29462 struct s { char x } a[] = {1, 2};\SpecialChar ~
29463 \SpecialChar ~
29464 \SpecialChar ~
29465 \SpecialChar ~
29466 \SpecialChar ~
29467 /* invalid in SDCC */
29468 \newline
29469 struct s { char x } a[] = {{1}, {2}}; /* OK */
29470 \end_deeper
29471 \layout Itemize
29472
29473 'long long
29474 \begin_inset LatexCommand \index{long long (not supported)}
29475
29476 \end_inset
29477
29478 ' (64 bit integers
29479 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
29480
29481 \end_inset
29482
29483 ) not supported.
29484 \layout Itemize
29485
29486 'double
29487 \begin_inset LatexCommand \index{double (not supported)}
29488
29489 \end_inset
29490
29491 ' precision floating point
29492 \begin_inset LatexCommand \index{Floating point support}
29493
29494 \end_inset
29495
29496 not supported.
29497 \layout Itemize
29498
29499 Old K&R style
29500 \begin_inset LatexCommand \index{K\&R style}
29501
29502 \end_inset
29503
29504  function declarations are NOT allowed.
29505 \begin_deeper
29506 \layout Verse
29507
29508
29509 \family typewriter
29510 foo(i,j) /* this old style of function declarations */
29511 \newline
29512 int i,j; /* are valid in ANSI but not valid in SDCC */
29513 \newline
29514 {
29515 \newline
29516 \SpecialChar ~
29517 \SpecialChar ~
29518 \SpecialChar ~
29519 \SpecialChar ~
29520 ...
29521
29522 \newline
29523 }
29524 \end_deeper
29525 \layout Itemize
29526
29527 Most enhancements in C99 are not supported, f.e.:
29528 \begin_deeper
29529 \layout Verse
29530
29531
29532 \family typewriter
29533 \series bold
29534 inline
29535 \begin_inset LatexCommand \index{inline (not supported)}
29536
29537 \end_inset
29538
29539
29540 \series default
29541  int increment (int a) { return a+1; } /* is invalid in SDCC although allowed
29542  in C99.
29543  An empty define
29544 \emph on
29545 #define inline
29546 \emph default
29547  can be used as a work around */
29548 \newline
29549
29550 \newline
29551 for (
29552 \series bold
29553 int
29554 \series default
29555  i=0; i<10; i++) /* is invalid in SDCC although allowed in C99 */
29556 \end_deeper
29557 \layout Itemize
29558
29559 Certain words that are valid identifiers in the standard may be reserved
29560  words in SDCC unless the
29561 \series bold
29562 -
29563 \begin_inset ERT
29564 status Collapsed
29565
29566 \layout Standard
29567
29568 \backslash
29569 /
29570 \end_inset
29571
29572 -std-c89
29573 \begin_inset LatexCommand \index{-\/-std-c89}
29574
29575 \end_inset
29576
29577  or -
29578 \begin_inset ERT
29579 status Collapsed
29580
29581 \layout Standard
29582
29583 \backslash
29584 /
29585 \end_inset
29586
29587 -std-c99
29588 \begin_inset LatexCommand \index{-\/-std-c99}
29589
29590 \end_inset
29591
29592
29593 \series default
29594  command line options are used.
29595  These may include (depending on the selected processor): 'at', 'banked',
29596  'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup
29597 t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs',
29598  'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and
29599  '_naked'.
29600  Compliant equivalents of these keywords are always available in a form
29601  that begin with two underscores
29602 \begin_inset LatexCommand \index{\_\_ (prefix for extended keywords)}
29603
29604 \end_inset
29605
29606 , f.e.
29607  '__data' instead of 'data'.
29608 \layout Section
29609
29610 Cyclomatic Complexity
29611 \begin_inset LatexCommand \index{Cyclomatic complexity}
29612
29613 \end_inset
29614
29615
29616 \layout Standard
29617
29618 Cyclomatic complexity of a function is defined as the number of independent
29619  paths the program can take during execution of the function.
29620  This is an important number since it defines the number test cases you
29621  have to generate to validate the function.
29622  The accepted industry standard for complexity number is 10, if the cyclomatic
29623  complexity reported by SDCC exceeds 10 you should think about simplification
29624  of the function logic.
29625  Note that the complexity level is not related to the number of lines of
29626  code in a function.
29627  Large functions can have low complexity, and small functions can have large
29628  complexity levels.
29629
29630 \newline
29631
29632 \newline
29633 SDCC uses the following formula to compute the complexity:
29634 \newline
29635
29636 \layout Standard
29637
29638 complexity = (number of edges in control flow graph) - (number of nodes
29639  in control flow graph) + 2;
29640 \newline
29641
29642 \newline
29643 Having said that the industry standard is 10, you should be aware that in
29644  some cases it be may unavoidable to have a complexity level of less than
29645  10.
29646  For example if you have switch statement with more than 10 case labels,
29647  each case label adds one to the complexity level.
29648  The complexity level is by no means an absolute measure of the algorithmic
29649  complexity of the function, it does however provide a good starting point
29650  for which functions you might look at for further optimization.
29651 \layout Section
29652
29653 Retargetting for other Processors
29654 \layout Standard
29655
29656 The issues for retargetting the compiler are far too numerous to be covered
29657  by this document.
29658  What follows is a brief description of each of the seven phases of the
29659  compiler and its MCU dependency.
29660 \layout Itemize
29661
29662 Parsing the source and building the annotated parse tree.
29663  This phase is largely MCU independent (except for the language extensions).
29664  Syntax & semantic checks are also done in this phase, along with some initial
29665  optimizations like back patching labels and the pattern matching optimizations
29666  like bit-rotation etc.
29667 \layout Itemize
29668
29669 The second phase involves generating an intermediate code which can be easy
29670  manipulated during the later phases.
29671  This phase is entirely MCU independent.
29672  The intermediate code generation assumes the target machine has unlimited
29673  number of registers, and designates them with the name iTemp.
29674  The compiler can be made to dump a human readable form of the code generated
29675  by using the -
29676 \begin_inset ERT
29677 status Collapsed
29678
29679 \layout Standard
29680
29681 \backslash
29682 /
29683 \end_inset
29684
29685 -dumpraw option.
29686 \layout Itemize
29687
29688 This phase does the bulk of the standard optimizations and is also MCU independe
29689 nt.
29690  This phase can be broken down into several sub-phases:
29691 \newline
29692
29693 \newline
29694 Break down intermediate code (iCode) into basic blocks.
29695 \newline
29696 Do control flow & data flow analysis on the basic blocks.
29697 \newline
29698 Do local common subexpression elimination, then global subexpression elimination
29699 \newline
29700 Dead code elimination
29701 \newline
29702 Loop optimizations
29703 \newline
29704 If loop optimizations caused any changes then do 'global subexpression eliminati
29705 on' and 'dead code elimination' again.
29706 \layout Itemize
29707
29708 This phase determines the live-ranges; by live range I mean those iTemp
29709  variables defined by the compiler that still survive after all the optimization
29710 s.
29711  Live range analysis
29712 \begin_inset LatexCommand \index{Live range analysis}
29713
29714 \end_inset
29715
29716  is essential for register allocation, since these computation determines
29717  which of these iTemps will be assigned to registers, and for how long.
29718 \layout Itemize
29719
29720 Phase five is register allocation.
29721  There are two parts to this process.
29722 \newline
29723
29724 \newline
29725 The first part I call 'register packing' (for lack of a better term).
29726  In this case several MCU specific expression folding is done to reduce
29727  register pressure.
29728 \newline
29729
29730 \newline
29731 The second part is more MCU independent and deals with allocating registers
29732  to the remaining live ranges.
29733  A lot of MCU specific code does creep into this phase because of the limited
29734  number of index registers available in the 8051.
29735 \layout Itemize
29736
29737 The Code generation phase is (unhappily), entirely MCU dependent and very
29738  little (if any at all) of this code can be reused for other MCU.
29739  However the scheme for allocating a homogenized assembler operand for each
29740  iCode operand may be reused.
29741 \layout Itemize
29742
29743 As mentioned in the optimization section the peep-hole optimizer is rule
29744  based system, which can reprogrammed for other MCUs.
29745 \layout Standard
29746
29747 More information is available in a wiki
29748 \begin_inset LatexCommand \index{wiki}
29749
29750 \end_inset
29751
29752  (preliminary link
29753 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/release_wiki/index.php?page=SDCC+internals+and+porting}
29754
29755 \end_inset
29756
29757 ) and in the thread
29758 \begin_inset LatexCommand \url{http://sf.net/mailarchive/message.php?msg_id=13954144}
29759
29760 \end_inset
29761
29762  .
29763 \layout Chapter
29764
29765 Compiler internals
29766 \begin_inset LatexCommand \index{Compiler internals}
29767
29768 \end_inset
29769
29770
29771 \layout Section
29772
29773 The anatomy of the compiler
29774 \begin_inset LatexCommand \label{sub:The-anatomy-of}
29775
29776 \end_inset
29777
29778
29779 \layout Standard
29780
29781
29782 \shape italic
29783 This is an excerpt from an article published in Circuit Cellar Magazine
29784  in
29785 \series bold
29786 August 2000
29787 \series default
29788 .
29789  It's a little outdated (the compiler is much more efficient now and user/develo
29790 per friendly), but pretty well exposes the guts of it all.
29791 \shape default
29792
29793 \newline
29794
29795 \newline
29796 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
29797  It is fairly easy to retarget for other 8-bit MCU.
29798  Here we take a look at some of the internals of the compiler.
29799
29800 \layout Paragraph*
29801
29802 Parsing
29803 \begin_inset LatexCommand \index{Parsing}
29804
29805 \end_inset
29806
29807
29808 \layout Standard
29809
29810 Parsing the input source file and creating an AST (Annotated Syntax Tree
29811 \begin_inset LatexCommand \index{Annotated syntax tree}
29812
29813 \end_inset
29814
29815 ).
29816  This phase also involves propagating types (annotating each node of the
29817  parse tree with type information) and semantic analysis.
29818  There are some MCU specific parsing rules.
29819  For example the storage classes, the extended storage classes are MCU specific
29820  while there may be a xdata storage class for 8051 there is no such storage
29821  class for z80 or Atmel AVR.
29822  SDCC allows MCU specific storage class extensions, i.e.
29823  xdata will be treated as a storage class specifier when parsing 8051 C
29824  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
29825  C code.
29826 \layout Paragraph*
29827
29828 Generating iCode
29829 \begin_inset LatexCommand \index{iCode}
29830
29831 \end_inset
29832
29833
29834 \layout Standard
29835
29836 Intermediate code generation.
29837  In this phase the AST is broken down into three-operand form (iCode).
29838  These three operand forms are represented as doubly linked lists.
29839  ICode is the term given to the intermediate form generated by the compiler.
29840  ICode example section shows some examples of iCode generated for some simple
29841  C source functions.
29842 \layout Paragraph*
29843
29844 Optimizations
29845 \begin_inset LatexCommand \index{Optimizations}
29846
29847 \end_inset
29848
29849 .
29850 \layout Standard
29851
29852 Bulk of the target independent optimizations is performed in this phase.
29853  The optimizations include constant propagation, common sub-expression eliminati
29854 on, loop invariant code movement, strength reduction of loop induction variables
29855  and dead-code elimination.
29856 \layout Paragraph*
29857
29858 Live range analysis
29859 \begin_inset LatexCommand \index{Live range analysis}
29860
29861 \end_inset
29862
29863
29864 \layout Standard
29865
29866 During intermediate code generation phase, the compiler assumes the target
29867  machine has infinite number of registers and generates a lot of temporary
29868  variables.
29869  The live range computation determines the lifetime of each of these compiler-ge
29870 nerated temporaries.
29871  A picture speaks a thousand words.
29872  ICode example sections show the live range annotations for each of the
29873  operand.
29874  It is important to note here, each iCode is assigned a number in the order
29875  of its execution in the function.
29876  The live ranges are computed in terms of these numbers.
29877  The from number is the number of the iCode which first defines the operand
29878  and the to number signifies the iCode which uses this operand last.
29879 \layout Paragraph*
29880
29881 Register Allocation
29882 \begin_inset LatexCommand \index{Register allocation}
29883
29884 \end_inset
29885
29886
29887 \layout Standard
29888
29889 The register allocation determines the type and number of registers needed
29890  by each operand.
29891  In most MCUs only a few registers can be used for indirect addressing.
29892  In case of 8051 for example the registers R0 & R1 can be used to indirectly
29893  address the internal ram and DPTR to indirectly address the external ram.
29894  The compiler will try to allocate the appropriate register to pointer variables
29895  if it can.
29896  ICode example section shows the operands annotated with the registers assigned
29897  to them.
29898  The compiler will try to keep operands in registers as much as possible;
29899  there are several schemes the compiler uses to do achieve this.
29900  When the compiler runs out of registers the compiler will check to see
29901  if there are any live operands which is not used or defined in the current
29902  basic block being processed, if there are any found then it will push that
29903  operand and use the registers in this block, the operand will then be popped
29904  at the end of the basic block.
29905
29906 \layout Standard
29907
29908 There are other MCU specific considerations in this phase.
29909  Some MCUs have an accumulator; very short-lived operands could be assigned
29910  to the accumulator instead of a general-purpose register.
29911 \layout Paragraph*
29912
29913 Code generation
29914 \layout Standard
29915
29916 Figure II gives a table of iCode
29917 \begin_inset LatexCommand \index{iCode}
29918
29919 \end_inset
29920
29921  operations supported by the compiler.
29922  The code generation involves translating these operations into corresponding
29923  assembly code for the processor.
29924  This sounds overly simple but that is the essence of code generation.
29925  Some of the iCode operations are generated on a MCU specific manner for
29926  example, the z80 port does not use registers to pass parameters so the
29927  SEND and RECV iCode operations will not be generated, and it also does
29928  not support JUMPTABLES.
29929
29930 \newline
29931
29932 \layout Standard
29933
29934
29935 \size footnotesize
29936 Figure II
29937 \begin_inset  Tabular
29938 <lyxtabular version="3" rows="39" columns="4">
29939 <features islongtable="true" headBottomDL="true">
29940 <column alignment="block" valignment="top" leftline="true" width="13col%">
29941 <column alignment="left" valignment="top" leftline="true" width="13col%">
29942 <column alignment="block" valignment="top" leftline="true" width="22col%">
29943 <column alignment="block" valignment="top" leftline="true" rightline="true" width="40col%">
29944 <row topline="true" bottomline="true" endhead="true">
29945 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29946 \begin_inset Text
29947
29948 \layout Standard
29949
29950
29951 \series bold
29952 iCode
29953 \series default
29954
29955 \begin_inset LatexCommand \index{iCode}
29956
29957 \end_inset
29958
29959
29960 \end_inset
29961 </cell>
29962 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29963 \begin_inset Text
29964
29965 \layout Standard
29966
29967
29968 \series bold
29969 Operands
29970 \end_inset
29971 </cell>
29972 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29973 \begin_inset Text
29974
29975 \layout Standard
29976
29977
29978 \series bold
29979 Description
29980 \end_inset
29981 </cell>
29982 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
29983 \begin_inset Text
29984
29985 \layout Standard
29986
29987
29988 \series bold
29989 C Equivalent
29990 \end_inset
29991 </cell>
29992 </row>
29993 <row topline="true">
29994 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
29995 \begin_inset Text
29996
29997 \layout Standard
29998
29999
30000 \size footnotesize
30001 '!'
30002 \end_inset
30003 </cell>
30004 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30005 \begin_inset Text
30006
30007 \layout Standard
30008
30009
30010 \size footnotesize
30011 IC_LEFT() IC_RESULT()
30012 \end_inset
30013 </cell>
30014 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30015 \begin_inset Text
30016
30017 \layout Standard
30018
30019
30020 \size footnotesize
30021 NOT operation
30022 \end_inset
30023 </cell>
30024 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30025 \begin_inset Text
30026
30027 \layout Standard
30028
30029
30030 \size footnotesize
30031 IC_RESULT = ! IC_LEFT;
30032 \end_inset
30033 </cell>
30034 </row>
30035 <row topline="true">
30036 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30037 \begin_inset Text
30038
30039 \layout Standard
30040
30041
30042 \size footnotesize
30043 '~'
30044 \end_inset
30045 </cell>
30046 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30047 \begin_inset Text
30048
30049 \layout Standard
30050
30051
30052 \size footnotesize
30053 IC_LEFT() IC_RESULT()
30054 \end_inset
30055 </cell>
30056 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30057 \begin_inset Text
30058
30059 \layout Standard
30060
30061
30062 \size footnotesize
30063 Bitwise complement of
30064 \end_inset
30065 </cell>
30066 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30067 \begin_inset Text
30068
30069 \layout Standard
30070
30071
30072 \size footnotesize
30073 IC_RESULT = ~IC_LEFT;
30074 \end_inset
30075 </cell>
30076 </row>
30077 <row topline="true">
30078 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30079 \begin_inset Text
30080
30081 \layout Standard
30082
30083
30084 \size footnotesize
30085 RRC
30086 \end_inset
30087 </cell>
30088 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30089 \begin_inset Text
30090
30091 \layout Standard
30092
30093
30094 \size footnotesize
30095 IC_LEFT() IC_RESULT()
30096 \end_inset
30097 </cell>
30098 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30099 \begin_inset Text
30100
30101 \layout Standard
30102
30103
30104 \size footnotesize
30105 Rotate right with carry
30106 \end_inset
30107 </cell>
30108 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30109 \begin_inset Text
30110
30111 \layout Standard
30112
30113
30114 \size footnotesize
30115 IC_RESULT = (IC_LEFT << 1) | (IC_LEFT >> (sizeof(IC_LEFT)*8-1));
30116 \end_inset
30117 </cell>
30118 </row>
30119 <row topline="true">
30120 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30121 \begin_inset Text
30122
30123 \layout Standard
30124
30125
30126 \size footnotesize
30127 RLC
30128 \end_inset
30129 </cell>
30130 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30131 \begin_inset Text
30132
30133 \layout Standard
30134
30135
30136 \size footnotesize
30137 IC_LEFT() IC_RESULT()
30138 \end_inset
30139 </cell>
30140 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30141 \begin_inset Text
30142
30143 \layout Standard
30144
30145
30146 \size footnotesize
30147 Rotate left with carry
30148 \end_inset
30149 </cell>
30150 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30151 \begin_inset Text
30152
30153 \layout Standard
30154
30155
30156 \size footnotesize
30157 IC_RESULT = (IC_LEFT << (sizeof(LC_LEFT)*8-1) ) | (IC_LEFT >> 1);
30158 \end_inset
30159 </cell>
30160 </row>
30161 <row topline="true">
30162 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30163 \begin_inset Text
30164
30165 \layout Standard
30166
30167
30168 \size footnotesize
30169 GETHBIT
30170 \end_inset
30171 </cell>
30172 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30173 \begin_inset Text
30174
30175 \layout Standard
30176
30177
30178 \size footnotesize
30179 IC_LEFT() IC_RESULT()
30180 \end_inset
30181 </cell>
30182 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30183 \begin_inset Text
30184
30185 \layout Standard
30186
30187
30188 \size footnotesize
30189 Get the highest order bit of IC_LEFT
30190 \end_inset
30191 </cell>
30192 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30193 \begin_inset Text
30194
30195 \layout Standard
30196
30197
30198 \size footnotesize
30199 IC_RESULT = (IC_LEFT >> (sizeof(IC_LEFT)*8 -1));
30200 \end_inset
30201 </cell>
30202 </row>
30203 <row topline="true">
30204 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30205 \begin_inset Text
30206
30207 \layout Standard
30208
30209
30210 \size footnotesize
30211 UNARYMINUS
30212 \end_inset
30213 </cell>
30214 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30215 \begin_inset Text
30216
30217 \layout Standard
30218
30219
30220 \size footnotesize
30221 IC_LEFT() IC_RESULT()
30222 \end_inset
30223 </cell>
30224 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30225 \begin_inset Text
30226
30227 \layout Standard
30228
30229
30230 \size footnotesize
30231 Unary minus
30232 \end_inset
30233 </cell>
30234 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30235 \begin_inset Text
30236
30237 \layout Standard
30238
30239
30240 \size footnotesize
30241 IC_RESULT = - IC_LEFT;
30242 \end_inset
30243 </cell>
30244 </row>
30245 <row topline="true">
30246 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30247 \begin_inset Text
30248
30249 \layout Standard
30250
30251
30252 \size footnotesize
30253 IPUSH
30254 \end_inset
30255 </cell>
30256 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30257 \begin_inset Text
30258
30259 \layout Standard
30260
30261
30262 \size footnotesize
30263 IC_LEFT()
30264 \end_inset
30265 </cell>
30266 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30267 \begin_inset Text
30268
30269 \layout Standard
30270
30271
30272 \size footnotesize
30273 Push the operand into stack
30274 \end_inset
30275 </cell>
30276 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30277 \begin_inset Text
30278
30279 \layout Standard
30280
30281
30282 \size footnotesize
30283 NONE
30284 \end_inset
30285 </cell>
30286 </row>
30287 <row topline="true">
30288 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30289 \begin_inset Text
30290
30291 \layout Standard
30292
30293
30294 \size footnotesize
30295 IPOP
30296 \end_inset
30297 </cell>
30298 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30299 \begin_inset Text
30300
30301 \layout Standard
30302
30303
30304 \size footnotesize
30305 IC_LEFT()
30306 \end_inset
30307 </cell>
30308 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30309 \begin_inset Text
30310
30311 \layout Standard
30312
30313
30314 \size footnotesize
30315 Pop the operand from the stack
30316 \end_inset
30317 </cell>
30318 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30319 \begin_inset Text
30320
30321 \layout Standard
30322
30323
30324 \size footnotesize
30325 NONE
30326 \end_inset
30327 </cell>
30328 </row>
30329 <row topline="true">
30330 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30331 \begin_inset Text
30332
30333 \layout Standard
30334
30335
30336 \size footnotesize
30337 CALL
30338 \end_inset
30339 </cell>
30340 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30341 \begin_inset Text
30342
30343 \layout Standard
30344
30345
30346 \size footnotesize
30347 IC_LEFT() IC_RESULT()
30348 \end_inset
30349 </cell>
30350 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30351 \begin_inset Text
30352
30353 \layout Standard
30354
30355
30356 \size footnotesize
30357 Call the function represented by IC_LEFT
30358 \end_inset
30359 </cell>
30360 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30361 \begin_inset Text
30362
30363 \layout Standard
30364
30365
30366 \size footnotesize
30367 IC_RESULT = IC_LEFT();
30368 \end_inset
30369 </cell>
30370 </row>
30371 <row topline="true">
30372 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30373 \begin_inset Text
30374
30375 \layout Standard
30376
30377
30378 \size footnotesize
30379 PCALL
30380 \end_inset
30381 </cell>
30382 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30383 \begin_inset Text
30384
30385 \layout Standard
30386
30387
30388 \size footnotesize
30389 IC_LEFT() IC_RESULT()
30390 \end_inset
30391 </cell>
30392 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30393 \begin_inset Text
30394
30395 \layout Standard
30396
30397
30398 \size footnotesize
30399 Call via function pointer
30400 \end_inset
30401 </cell>
30402 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30403 \begin_inset Text
30404
30405 \layout Standard
30406
30407
30408 \size footnotesize
30409 IC_RESULT = (*IC_LEFT)();
30410 \end_inset
30411 </cell>
30412 </row>
30413 <row topline="true">
30414 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30415 \begin_inset Text
30416
30417 \layout Standard
30418
30419
30420 \size footnotesize
30421 RETURN
30422 \end_inset
30423 </cell>
30424 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30425 \begin_inset Text
30426
30427 \layout Standard
30428
30429
30430 \size footnotesize
30431 IC_LEFT()
30432 \end_inset
30433 </cell>
30434 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30435 \begin_inset Text
30436
30437 \layout Standard
30438
30439
30440 \size footnotesize
30441 Return the value in operand IC_LEFT
30442 \end_inset
30443 </cell>
30444 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30445 \begin_inset Text
30446
30447 \layout Standard
30448
30449
30450 \size footnotesize
30451 return IC_LEFT;
30452 \end_inset
30453 </cell>
30454 </row>
30455 <row topline="true">
30456 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30457 \begin_inset Text
30458
30459 \layout Standard
30460
30461
30462 \size footnotesize
30463 LABEL
30464 \end_inset
30465 </cell>
30466 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30467 \begin_inset Text
30468
30469 \layout Standard
30470
30471
30472 \size footnotesize
30473 IC_LABEL()
30474 \end_inset
30475 </cell>
30476 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30477 \begin_inset Text
30478
30479 \layout Standard
30480
30481
30482 \size footnotesize
30483 Label
30484 \end_inset
30485 </cell>
30486 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30487 \begin_inset Text
30488
30489 \layout Standard
30490
30491
30492 \size footnotesize
30493 IC_LABEL:
30494 \end_inset
30495 </cell>
30496 </row>
30497 <row topline="true">
30498 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30499 \begin_inset Text
30500
30501 \layout Standard
30502
30503
30504 \size footnotesize
30505 GOTO
30506 \end_inset
30507 </cell>
30508 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30509 \begin_inset Text
30510
30511 \layout Standard
30512
30513
30514 \size footnotesize
30515 IC_LABEL()
30516 \end_inset
30517 </cell>
30518 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30519 \begin_inset Text
30520
30521 \layout Standard
30522
30523
30524 \size footnotesize
30525 Goto label
30526 \end_inset
30527 </cell>
30528 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30529 \begin_inset Text
30530
30531 \layout Standard
30532
30533
30534 \size footnotesize
30535 goto IC_LABEL();
30536 \end_inset
30537 </cell>
30538 </row>
30539 <row topline="true">
30540 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30541 \begin_inset Text
30542
30543 \layout Standard
30544
30545
30546 \size footnotesize
30547 '+'
30548 \end_inset
30549 </cell>
30550 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30551 \begin_inset Text
30552
30553 \layout Standard
30554
30555
30556 \size footnotesize
30557 IC_LEFT() IC_RIGHT() IC_RESULT()
30558 \end_inset
30559 </cell>
30560 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30561 \begin_inset Text
30562
30563 \layout Standard
30564
30565
30566 \size footnotesize
30567 Addition
30568 \end_inset
30569 </cell>
30570 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30571 \begin_inset Text
30572
30573 \layout Standard
30574
30575
30576 \size footnotesize
30577 IC_RESULT = IC_LEFT + IC_RIGHT
30578 \end_inset
30579 </cell>
30580 </row>
30581 <row topline="true">
30582 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30583 \begin_inset Text
30584
30585 \layout Standard
30586
30587
30588 \size footnotesize
30589 '-'
30590 \end_inset
30591 </cell>
30592 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30593 \begin_inset Text
30594
30595 \layout Standard
30596
30597
30598 \size footnotesize
30599 IC_LEFT() IC_RIGHT() IC_RESULT()
30600 \end_inset
30601 </cell>
30602 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30603 \begin_inset Text
30604
30605 \layout Standard
30606
30607
30608 \size footnotesize
30609 Subtraction
30610 \end_inset
30611 </cell>
30612 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30613 \begin_inset Text
30614
30615 \layout Standard
30616
30617
30618 \size footnotesize
30619 IC_RESULT = IC_LEFT - IC_RIGHT
30620 \end_inset
30621 </cell>
30622 </row>
30623 <row topline="true">
30624 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30625 \begin_inset Text
30626
30627 \layout Standard
30628
30629
30630 \size footnotesize
30631 '*'
30632 \end_inset
30633 </cell>
30634 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30635 \begin_inset Text
30636
30637 \layout Standard
30638
30639
30640 \size footnotesize
30641 IC_LEFT() IC_RIGHT() IC_RESULT()
30642 \end_inset
30643 </cell>
30644 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30645 \begin_inset Text
30646
30647 \layout Standard
30648
30649
30650 \size footnotesize
30651 Multiplication
30652 \end_inset
30653 </cell>
30654 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30655 \begin_inset Text
30656
30657 \layout Standard
30658
30659
30660 \size footnotesize
30661 IC_RESULT = IC_LEFT * IC_RIGHT;
30662 \end_inset
30663 </cell>
30664 </row>
30665 <row topline="true">
30666 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30667 \begin_inset Text
30668
30669 \layout Standard
30670
30671
30672 \size footnotesize
30673 '/'
30674 \end_inset
30675 </cell>
30676 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30677 \begin_inset Text
30678
30679 \layout Standard
30680
30681
30682 \size footnotesize
30683 IC_LEFT() IC_RIGHT() IC_RESULT()
30684 \end_inset
30685 </cell>
30686 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30687 \begin_inset Text
30688
30689 \layout Standard
30690
30691
30692 \size footnotesize
30693 Division
30694 \end_inset
30695 </cell>
30696 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30697 \begin_inset Text
30698
30699 \layout Standard
30700
30701
30702 \size footnotesize
30703 IC_RESULT = IC_LEFT / IC_RIGHT;
30704 \end_inset
30705 </cell>
30706 </row>
30707 <row topline="true">
30708 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30709 \begin_inset Text
30710
30711 \layout Standard
30712
30713
30714 \size footnotesize
30715 '%'
30716 \end_inset
30717 </cell>
30718 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30719 \begin_inset Text
30720
30721 \layout Standard
30722
30723
30724 \size footnotesize
30725 IC_LEFT() IC_RIGHT() IC_RESULT()
30726 \end_inset
30727 </cell>
30728 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30729 \begin_inset Text
30730
30731 \layout Standard
30732
30733
30734 \size footnotesize
30735 Modulus
30736 \end_inset
30737 </cell>
30738 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30739 \begin_inset Text
30740
30741 \layout Standard
30742
30743
30744 \size footnotesize
30745 IC_RESULT = IC_LEFT % IC_RIGHT;
30746 \end_inset
30747 </cell>
30748 </row>
30749 <row topline="true">
30750 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30751 \begin_inset Text
30752
30753 \layout Standard
30754
30755
30756 \size footnotesize
30757 '<'
30758 \end_inset
30759 </cell>
30760 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30761 \begin_inset Text
30762
30763 \layout Standard
30764
30765
30766 \size footnotesize
30767 IC_LEFT() IC_RIGHT() IC_RESULT()
30768 \end_inset
30769 </cell>
30770 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30771 \begin_inset Text
30772
30773 \layout Standard
30774
30775
30776 \size footnotesize
30777 Less than
30778 \end_inset
30779 </cell>
30780 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30781 \begin_inset Text
30782
30783 \layout Standard
30784
30785
30786 \size footnotesize
30787 IC_RESULT = IC_LEFT < IC_RIGHT;
30788 \end_inset
30789 </cell>
30790 </row>
30791 <row topline="true">
30792 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30793 \begin_inset Text
30794
30795 \layout Standard
30796
30797
30798 \size footnotesize
30799 '>'
30800 \end_inset
30801 </cell>
30802 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30803 \begin_inset Text
30804
30805 \layout Standard
30806
30807
30808 \size footnotesize
30809 IC_LEFT() IC_RIGHT() IC_RESULT()
30810 \end_inset
30811 </cell>
30812 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30813 \begin_inset Text
30814
30815 \layout Standard
30816
30817
30818 \size footnotesize
30819 Greater than
30820 \end_inset
30821 </cell>
30822 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30823 \begin_inset Text
30824
30825 \layout Standard
30826
30827
30828 \size footnotesize
30829 IC_RESULT = IC_LEFT > IC_RIGHT;
30830 \end_inset
30831 </cell>
30832 </row>
30833 <row topline="true">
30834 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30835 \begin_inset Text
30836
30837 \layout Standard
30838
30839
30840 \size footnotesize
30841 EQ_OP
30842 \end_inset
30843 </cell>
30844 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30845 \begin_inset Text
30846
30847 \layout Standard
30848
30849
30850 \size footnotesize
30851 IC_LEFT() IC_RIGHT() IC_RESULT()
30852 \end_inset
30853 </cell>
30854 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30855 \begin_inset Text
30856
30857 \layout Standard
30858
30859
30860 \size footnotesize
30861 Equal to
30862 \end_inset
30863 </cell>
30864 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30865 \begin_inset Text
30866
30867 \layout Standard
30868
30869
30870 \size footnotesize
30871 IC_RESULT = IC_LEFT == IC_RIGHT;
30872 \end_inset
30873 </cell>
30874 </row>
30875 <row topline="true">
30876 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30877 \begin_inset Text
30878
30879 \layout Standard
30880
30881
30882 \size footnotesize
30883 AND_OP
30884 \end_inset
30885 </cell>
30886 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30887 \begin_inset Text
30888
30889 \layout Standard
30890
30891
30892 \size footnotesize
30893 IC_LEFT() IC_RIGHT() IC_RESULT()
30894 \end_inset
30895 </cell>
30896 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30897 \begin_inset Text
30898
30899 \layout Standard
30900
30901
30902 \size footnotesize
30903 Logical and operation
30904 \end_inset
30905 </cell>
30906 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30907 \begin_inset Text
30908
30909 \layout Standard
30910
30911
30912 \size footnotesize
30913 IC_RESULT = IC_LEFT && IC_RIGHT;
30914 \end_inset
30915 </cell>
30916 </row>
30917 <row topline="true">
30918 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30919 \begin_inset Text
30920
30921 \layout Standard
30922
30923
30924 \size footnotesize
30925 OR_OP
30926 \end_inset
30927 </cell>
30928 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30929 \begin_inset Text
30930
30931 \layout Standard
30932
30933
30934 \size footnotesize
30935 IC_LEFT() IC_RIGHT() IC_RESULT()
30936 \end_inset
30937 </cell>
30938 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30939 \begin_inset Text
30940
30941 \layout Standard
30942
30943
30944 \size footnotesize
30945 Logical or operation
30946 \end_inset
30947 </cell>
30948 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30949 \begin_inset Text
30950
30951 \layout Standard
30952
30953
30954 \size footnotesize
30955 IC_RESULT = IC_LEFT || IC_RIGHT;
30956 \end_inset
30957 </cell>
30958 </row>
30959 <row topline="true">
30960 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30961 \begin_inset Text
30962
30963 \layout Standard
30964
30965
30966 \size footnotesize
30967 '^'
30968 \end_inset
30969 </cell>
30970 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30971 \begin_inset Text
30972
30973 \layout Standard
30974
30975
30976 \size footnotesize
30977 IC_LEFT() IC_RIGHT() IC_RESULT()
30978 \end_inset
30979 </cell>
30980 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
30981 \begin_inset Text
30982
30983 \layout Standard
30984
30985
30986 \size footnotesize
30987 Exclusive OR
30988 \end_inset
30989 </cell>
30990 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
30991 \begin_inset Text
30992
30993 \layout Standard
30994
30995
30996 \size footnotesize
30997 IC_RESULT = IC_LEFT ^ IC_RIGHT;
30998 \end_inset
30999 </cell>
31000 </row>
31001 <row topline="true">
31002 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31003 \begin_inset Text
31004
31005 \layout Standard
31006
31007
31008 \size footnotesize
31009 '|'
31010 \end_inset
31011 </cell>
31012 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31013 \begin_inset Text
31014
31015 \layout Standard
31016
31017
31018 \size footnotesize
31019 IC_LEFT() IC_RIGHT() IC_RESULT()
31020 \end_inset
31021 </cell>
31022 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31023 \begin_inset Text
31024
31025 \layout Standard
31026
31027
31028 \size footnotesize
31029 Bitwise OR
31030 \end_inset
31031 </cell>
31032 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31033 \begin_inset Text
31034
31035 \layout Standard
31036
31037
31038 \size footnotesize
31039 IC_RESULT = IC_LEFT | IC_RIGHT;
31040 \end_inset
31041 </cell>
31042 </row>
31043 <row topline="true">
31044 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31045 \begin_inset Text
31046
31047 \layout Standard
31048
31049
31050 \size footnotesize
31051 BITWISEAND
31052 \end_inset
31053 </cell>
31054 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31055 \begin_inset Text
31056
31057 \layout Standard
31058
31059
31060 \size footnotesize
31061 IC_LEFT() IC_RIGHT() IC_RESULT()
31062 \end_inset
31063 </cell>
31064 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31065 \begin_inset Text
31066
31067 \layout Standard
31068
31069
31070 \size footnotesize
31071 Bitwise AND
31072 \end_inset
31073 </cell>
31074 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31075 \begin_inset Text
31076
31077 \layout Standard
31078
31079
31080 \size footnotesize
31081 IC_RESULT = IC_LEFT & IC_RIGHT;
31082 \end_inset
31083 </cell>
31084 </row>
31085 <row topline="true">
31086 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31087 \begin_inset Text
31088
31089 \layout Standard
31090
31091
31092 \size footnotesize
31093 LEFT_OP
31094 \end_inset
31095 </cell>
31096 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31097 \begin_inset Text
31098
31099 \layout Standard
31100
31101
31102 \size footnotesize
31103 IC_LEFT() IC_RIGHT() IC_RESULT()
31104 \end_inset
31105 </cell>
31106 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31107 \begin_inset Text
31108
31109 \layout Standard
31110
31111
31112 \size footnotesize
31113 Left shift
31114 \end_inset
31115 </cell>
31116 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31117 \begin_inset Text
31118
31119 \layout Standard
31120
31121
31122 \size footnotesize
31123 IC_RESULT = IC_LEFT << IC_RIGHT
31124 \end_inset
31125 </cell>
31126 </row>
31127 <row topline="true">
31128 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31129 \begin_inset Text
31130
31131 \layout Standard
31132
31133
31134 \size footnotesize
31135 RIGHT_OP
31136 \end_inset
31137 </cell>
31138 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31139 \begin_inset Text
31140
31141 \layout Standard
31142
31143
31144 \size footnotesize
31145 IC_LEFT() IC_RIGHT() IC_RESULT()
31146 \end_inset
31147 </cell>
31148 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31149 \begin_inset Text
31150
31151 \layout Standard
31152
31153
31154 \size footnotesize
31155 Right shift
31156 \end_inset
31157 </cell>
31158 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31159 \begin_inset Text
31160
31161 \layout Standard
31162
31163
31164 \size footnotesize
31165 IC_RESULT = IC_LEFT >> IC_RIGHT
31166 \end_inset
31167 </cell>
31168 </row>
31169 <row topline="true">
31170 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31171 \begin_inset Text
31172
31173 \layout Standard
31174
31175
31176 \size footnotesize
31177 GET_VALUE_
31178 \newline
31179 AT_ ADDRESS
31180 \end_inset
31181 </cell>
31182 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31183 \begin_inset Text
31184
31185 \layout Standard
31186
31187
31188 \size footnotesize
31189 IC_LEFT() IC_RESULT()
31190 \end_inset
31191 </cell>
31192 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31193 \begin_inset Text
31194
31195 \layout Standard
31196
31197
31198 \size footnotesize
31199 Indirect fetch
31200 \end_inset
31201 </cell>
31202 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31203 \begin_inset Text
31204
31205 \layout Standard
31206
31207
31208 \size footnotesize
31209 IC_RESULT = (*IC_LEFT);
31210 \end_inset
31211 </cell>
31212 </row>
31213 <row topline="true">
31214 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31215 \begin_inset Text
31216
31217 \layout Standard
31218
31219
31220 \size footnotesize
31221 POINTER_SET
31222 \end_inset
31223 </cell>
31224 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31225 \begin_inset Text
31226
31227 \layout Standard
31228
31229
31230 \size footnotesize
31231 IC_RIGHT() IC_RESULT()
31232 \end_inset
31233 </cell>
31234 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31235 \begin_inset Text
31236
31237 \layout Standard
31238
31239
31240 \size footnotesize
31241 Indirect set
31242 \end_inset
31243 </cell>
31244 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31245 \begin_inset Text
31246
31247 \layout Standard
31248
31249
31250 \size footnotesize
31251 (*IC_RESULT) = IC_RIGHT;
31252 \end_inset
31253 </cell>
31254 </row>
31255 <row topline="true">
31256 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31257 \begin_inset Text
31258
31259 \layout Standard
31260
31261
31262 \size footnotesize
31263 '='
31264 \end_inset
31265 </cell>
31266 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31267 \begin_inset Text
31268
31269 \layout Standard
31270
31271
31272 \size footnotesize
31273 IC_RIGHT() IC_RESULT()
31274 \end_inset
31275 </cell>
31276 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31277 \begin_inset Text
31278
31279 \layout Standard
31280
31281
31282 \size footnotesize
31283 Assignment
31284 \end_inset
31285 </cell>
31286 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31287 \begin_inset Text
31288
31289 \layout Standard
31290
31291
31292 \size footnotesize
31293 IC_RESULT = IC_RIGHT;
31294 \end_inset
31295 </cell>
31296 </row>
31297 <row topline="true">
31298 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31299 \begin_inset Text
31300
31301 \layout Standard
31302
31303
31304 \size footnotesize
31305 IFX
31306 \end_inset
31307 </cell>
31308 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31309 \begin_inset Text
31310
31311 \layout Standard
31312
31313
31314 \size footnotesize
31315 IC_COND IC_TRUE IC_LABEL
31316 \end_inset
31317 </cell>
31318 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31319 \begin_inset Text
31320
31321 \layout Standard
31322
31323
31324 \size footnotesize
31325 Conditional jump.
31326  If true label is present then jump to true label if condition is true else
31327  jump to false label if condition is false
31328 \end_inset
31329 </cell>
31330 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31331 \begin_inset Text
31332
31333 \layout Standard
31334
31335
31336 \size footnotesize
31337 if (IC_COND) goto IC_TRUE;
31338 \newline
31339 \SpecialChar ~
31340 \SpecialChar ~
31341 Or
31342 \newline
31343 If (!IC_COND) goto IC_FALSE;
31344 \end_inset
31345 </cell>
31346 </row>
31347 <row topline="true">
31348 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31349 \begin_inset Text
31350
31351 \layout Standard
31352
31353
31354 \size footnotesize
31355 ADDRESS_OF
31356 \end_inset
31357 </cell>
31358 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31359 \begin_inset Text
31360
31361 \layout Standard
31362
31363
31364 \size footnotesize
31365 IC_LEFT() IC_RESULT()
31366 \end_inset
31367 </cell>
31368 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31369 \begin_inset Text
31370
31371 \layout Standard
31372
31373
31374 \size footnotesize
31375 Address of
31376 \end_inset
31377 </cell>
31378 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31379 \begin_inset Text
31380
31381 \layout Standard
31382
31383
31384 \size footnotesize
31385 IC_RESULT = &IC_LEFT();
31386 \end_inset
31387 </cell>
31388 </row>
31389 <row topline="true">
31390 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31391 \begin_inset Text
31392
31393 \layout Standard
31394
31395
31396 \size footnotesize
31397 JUMPTABLE
31398 \end_inset
31399 </cell>
31400 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31401 \begin_inset Text
31402
31403 \layout Standard
31404
31405
31406 \size footnotesize
31407 IC_JTCOND IC_JTLABELS
31408 \end_inset
31409 </cell>
31410 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31411 \begin_inset Text
31412
31413 \layout Standard
31414
31415
31416 \size footnotesize
31417 Jump to list of labels depending on the value of JTCOND
31418 \end_inset
31419 </cell>
31420 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31421 \begin_inset Text
31422
31423 \layout Standard
31424
31425
31426 \size footnotesize
31427 Switch statement
31428 \end_inset
31429 </cell>
31430 </row>
31431 <row topline="true">
31432 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31433 \begin_inset Text
31434
31435 \layout Standard
31436
31437
31438 \size footnotesize
31439 CAST
31440 \end_inset
31441 </cell>
31442 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31443 \begin_inset Text
31444
31445 \layout Standard
31446
31447
31448 \size footnotesize
31449 IC_RIGHT() IC_LEFT() IC_RESULT()
31450 \end_inset
31451 </cell>
31452 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31453 \begin_inset Text
31454
31455 \layout Standard
31456
31457
31458 \size footnotesize
31459 Cast types
31460 \end_inset
31461 </cell>
31462 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31463 \begin_inset Text
31464
31465 \layout Standard
31466
31467
31468 \size footnotesize
31469 IC_RESULT = (typeof IC_LEFT) IC_RIGHT;
31470 \end_inset
31471 </cell>
31472 </row>
31473 <row topline="true">
31474 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31475 \begin_inset Text
31476
31477 \layout Standard
31478
31479
31480 \size footnotesize
31481 SEND
31482 \end_inset
31483 </cell>
31484 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31485 \begin_inset Text
31486
31487 \layout Standard
31488
31489
31490 \size footnotesize
31491 IC_LEFT()
31492 \end_inset
31493 </cell>
31494 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31495 \begin_inset Text
31496
31497 \layout Standard
31498
31499
31500 \size footnotesize
31501 This is used for passing parameters in registers;
31502 \newline
31503 move IC_LEFT to the next available parameter register.
31504 \end_inset
31505 </cell>
31506 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31507 \begin_inset Text
31508
31509 \layout Standard
31510
31511
31512 \size footnotesize
31513 None
31514 \end_inset
31515 </cell>
31516 </row>
31517 <row topline="true">
31518 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31519 \begin_inset Text
31520
31521 \layout Standard
31522
31523
31524 \size footnotesize
31525 RECV
31526 \end_inset
31527 </cell>
31528 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31529 \begin_inset Text
31530
31531 \layout Standard
31532
31533
31534 \size footnotesize
31535 IC_RESULT()
31536 \end_inset
31537 </cell>
31538 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31539 \begin_inset Text
31540
31541 \layout Standard
31542
31543
31544 \size footnotesize
31545 This is used for receiving parameters passed in registers;
31546 \newline
31547 Move the values in the next parameter register to IC_RESULT
31548 \end_inset
31549 </cell>
31550 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31551 \begin_inset Text
31552
31553 \layout Standard
31554
31555
31556 \size footnotesize
31557 None
31558 \end_inset
31559 </cell>
31560 </row>
31561 <row topline="true" bottomline="true">
31562 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31563 \begin_inset Text
31564
31565 \layout Standard
31566
31567
31568 \shape slanted
31569 \size footnotesize
31570 (some more have been added)
31571 \end_inset
31572 </cell>
31573 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31574 \begin_inset Text
31575
31576 \layout Standard
31577
31578 \end_inset
31579 </cell>
31580 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
31581 \begin_inset Text
31582
31583 \layout Standard
31584
31585 \end_inset
31586 </cell>
31587 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
31588 \begin_inset Text
31589
31590 \layout Standard
31591
31592
31593 \shape slanted
31594 \size footnotesize
31595 see f.e.
31596
31597 \family typewriter
31598 gen51Code()
31599 \family default
31600  in
31601 \family typewriter
31602 src/mcs51/gen.c
31603 \end_inset
31604 </cell>
31605 </row>
31606 </lyxtabular>
31607
31608 \end_inset
31609
31610
31611 \layout Comment
31612
31613 In the original article Figure II was announced to be downloadable on
31614 \shape italic
31615 Circuit Cellar
31616 \shape default
31617 's web site.
31618  ftp://ftp.circuitcellar.com/pub/Circuit_Cellar/2000/121/dutta.ZIP
31619 \layout Paragraph*
31620
31621 ICode Example
31622 \begin_inset LatexCommand \index{iCode}
31623
31624 \end_inset
31625
31626
31627 \layout Standard
31628
31629 This section shows some details of iCode.
31630  The example C code does not do anything useful; it is used as an example
31631  to illustrate the intermediate code generated by the compiler.
31632 \layout Verse
31633
31634
31635 \family typewriter
31636 1.\SpecialChar ~
31637 xdata int * p;
31638 \newline
31639 2.\SpecialChar ~
31640 int gint;
31641 \newline
31642 3.\SpecialChar ~
31643 /* This function does nothing useful.
31644  It is used
31645 \newline
31646 4.\SpecialChar ~
31647 \SpecialChar ~
31648 \SpecialChar ~
31649 \SpecialChar ~
31650 for the purpose of explaining iCode */
31651 \newline
31652 5.\SpecialChar ~
31653 short function (data int *x)
31654 \newline
31655 6.\SpecialChar ~
31656 {
31657 \newline
31658 7.\SpecialChar ~
31659 \SpecialChar ~
31660 \SpecialChar ~
31661 short i=10; \SpecialChar ~
31662 \SpecialChar ~
31663 /* dead initialization eliminated */
31664 \newline
31665 8.\SpecialChar ~
31666 \SpecialChar ~
31667 \SpecialChar ~
31668 short sum=10; /* dead initialization eliminated */
31669 \newline
31670 9.\SpecialChar ~
31671 \SpecialChar ~
31672 \SpecialChar ~
31673 short mul;
31674 \newline
31675 10.\SpecialChar ~
31676 \SpecialChar ~
31677 int j ;
31678 \newline
31679 11.\SpecialChar ~
31680 \SpecialChar ~
31681 while (*x) *x++ = *p++;
31682 \newline
31683 12.\SpecialChar ~
31684 \SpecialChar ~
31685 \SpecialChar ~
31686 \SpecialChar ~
31687 sum = 0 ;
31688 \newline
31689 13.\SpecialChar ~
31690 \SpecialChar ~
31691 mul = 0;
31692 \newline
31693 14.\SpecialChar ~
31694 \SpecialChar ~
31695 /* compiler detects i,j to be induction variables */
31696 \newline
31697 15.\SpecialChar ~
31698 \SpecialChar ~
31699 for (i = 0, j = 10 ; i < 10 ; i++, j
31700 \family default
31701 -
31702 \begin_inset ERT
31703 status Collapsed
31704
31705 \layout Standard
31706
31707 \backslash
31708 /
31709 \end_inset
31710
31711 -
31712 \family typewriter
31713 ) {
31714 \newline
31715 16.\SpecialChar ~
31716 \SpecialChar ~
31717 \SpecialChar ~
31718 \SpecialChar ~
31719 sum += i;
31720 \newline
31721 17.\SpecialChar ~
31722 \SpecialChar ~
31723 \SpecialChar ~
31724 \SpecialChar ~
31725 mul += i * 3; \SpecialChar ~
31726 \SpecialChar ~
31727 /* this multiplication remains */
31728 \newline
31729 18.\SpecialChar ~
31730 \SpecialChar ~
31731 \SpecialChar ~
31732 \SpecialChar ~
31733 gint += j * 3;\SpecialChar ~
31734 \SpecialChar ~
31735 /* this multiplication changed to addition */
31736 \newline
31737 19.\SpecialChar ~
31738 \SpecialChar ~
31739 }
31740 \newline
31741 20.\SpecialChar ~
31742 \SpecialChar ~
31743 return sum+mul;
31744 \newline
31745 21.\SpecialChar ~
31746 }
31747 \layout Standard
31748
31749 In addition to the operands each iCode contains information about the filename
31750  and line it corresponds to in the source file.
31751  The first field in the listing should be interpreted as follows:
31752 \newline
31753
31754 \shape italic
31755 \size footnotesize
31756 Filename(linenumber: iCode Execution sequence number : ICode hash table
31757  key : loop depth of the iCode).
31758 \shape default
31759 \size default
31760
31761 \newline
31762 Then follows the human readable form of the ICode operation.
31763  Each operand of this triplet form can be of three basic types a) compiler
31764  generated temporary b) user defined variable c) a constant value.
31765  Note that local variables and parameters are replaced by compiler generated
31766  temporaries.
31767  Live ranges
31768 \begin_inset LatexCommand \index{Live range analysis}
31769
31770 \end_inset
31771
31772  are computed only for temporaries (i.e.
31773  live ranges are not computed for global variables).
31774  Registers
31775 \begin_inset LatexCommand \index{Register allocation}
31776
31777 \end_inset
31778
31779  are allocated for temporaries only.
31780  Operands are formatted in the following manner:
31781 \newline
31782
31783 \shape italic
31784 \size footnotesize
31785 Operand Name [lr live-from : live-to ] { type information } [ registers
31786  allocated ].
31787 \shape default
31788 \size default
31789
31790 \newline
31791 As mentioned earlier the live ranges are computed in terms of the execution
31792  sequence number of the iCodes, for example
31793 \newline
31794 the iTemp0 is live from (i.e.
31795  first defined in iCode with execution sequence number 3, and is last used
31796  in the iCode with sequence number 5).
31797  For induction variables such as iTemp21 the live range computation extends
31798  the lifetime from the start to the end of the loop.
31799 \newline
31800 The register allocator used the live range information to allocate registers,
31801  the same registers may be used for different temporaries if their live
31802  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
31803  iTemp17 since their live ranges do not overlap.
31804  In addition the allocator also takes into consideration the type and usage
31805  of a temporary, for example itemp6 is a pointer to near space and is used
31806  as to fetch data from (i.e.
31807  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
31808  Some short lived temporaries are allocated to special registers which have
31809  meaning to the code generator e.g.
31810  iTemp13 is allocated to a pseudo register CC which tells the back end that
31811  the temporary is used only for a conditional jump the code generation makes
31812  use of this information to optimize a compare and jump ICode.
31813 \newline
31814 There are several loop optimizations
31815 \begin_inset LatexCommand \index{Loop optimization}
31816
31817 \end_inset
31818
31819  performed by the compiler.
31820  It can detect induction variables iTemp21(i) and iTemp23(j).
31821  Also note the compiler does selective strength reduction
31822 \begin_inset LatexCommand \index{Strength reduction}
31823
31824 \end_inset
31825
31826 , i.e.
31827  the multiplication of an induction variable in line 18 (gint = j * 3) is
31828  changed to addition, a new temporary iTemp17 is allocated and assigned
31829  a initial value, a constant 3 is then added for each iteration of the loop.
31830  The compiler does not change the multiplication
31831 \begin_inset LatexCommand \index{Multiplication}
31832
31833 \end_inset
31834
31835  in line 17 however since the processor does support an 8 * 8 bit multiplication.
31836 \newline
31837 Note the dead code elimination
31838 \begin_inset LatexCommand \index{Dead-code elimination}
31839
31840 \end_inset
31841
31842  optimization eliminated the dead assignments in line 7 & 8 to I and sum
31843  respectively.
31844 \newline
31845
31846 \layout Standard
31847
31848
31849 \size footnotesize
31850 Sample.c (5:1:0:0) _entry($9) :
31851 \layout Standard
31852
31853
31854 \size footnotesize
31855 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
31856 \layout Standard
31857
31858
31859 \size footnotesize
31860 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
31861 \layout Standard
31862
31863
31864 \size footnotesize
31865 Sample.c(11:4:53:0) preHeaderLbl0($11) :
31866 \layout Standard
31867
31868
31869 \size footnotesize
31870 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
31871  * int}[r2]
31872 \layout Standard
31873
31874
31875 \size footnotesize
31876 Sample.c(11:6:5:1) _whilecontinue_0($1) :
31877 \layout Standard
31878
31879
31880 \size footnotesize
31881 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
31882  int}[r0]]
31883 \layout Standard
31884
31885
31886 \size footnotesize
31887 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
31888 \layout Standard
31889
31890
31891 \size footnotesize
31892 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
31893  * int}
31894 \layout Standard
31895
31896
31897 \size footnotesize
31898 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
31899  {short}
31900 \layout Standard
31901
31902
31903 \size footnotesize
31904 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
31905  * int}[DPTR]]
31906 \layout Standard
31907
31908
31909 \size footnotesize
31910 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
31911 }[r2 r3]
31912 \layout Standard
31913
31914
31915 \size footnotesize
31916 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
31917  * int}[r0] + 0x2 {short}
31918 \layout Standard
31919
31920
31921 \size footnotesize
31922 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
31923 \layout Standard
31924
31925
31926 \size footnotesize
31927 Sample.c(11:17:21:0)_whilebreak_0($3) :
31928 \layout Standard
31929
31930
31931 \size footnotesize
31932 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
31933 \layout Standard
31934
31935
31936 \size footnotesize
31937 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
31938 \layout Standard
31939
31940
31941 \size footnotesize
31942 Sample.c(15:20:54:0)preHeaderLbl1($13) :
31943 \layout Standard
31944
31945
31946 \size footnotesize
31947 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
31948 \layout Standard
31949
31950
31951 \size footnotesize
31952 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
31953 \layout Standard
31954
31955
31956 \size footnotesize
31957 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
31958 \layout Standard
31959
31960
31961 \size footnotesize
31962 Sample.c(15:24:26:1)_forcond_0($4) :
31963 \layout Standard
31964
31965
31966 \size footnotesize
31967 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
31968  < 0xa {short}
31969 \layout Standard
31970
31971
31972 \size footnotesize
31973 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
31974 \layout Standard
31975
31976
31977 \size footnotesize
31978 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
31979  + ITemp21 [lr21:38]{short}[r4]
31980 \layout Standard
31981
31982
31983 \size footnotesize
31984 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
31985  * 0x3 {short}
31986 \layout Standard
31987
31988
31989 \size footnotesize
31990 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
31991  + iTemp15 [lr29:30]{short}[r1]
31992 \layout Standard
31993
31994
31995 \size footnotesize
31996 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
31997  r0]- 0x3 {short}
31998 \layout Standard
31999
32000
32001 \size footnotesize
32002 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
32003 int}[r7 r0]
32004 \layout Standard
32005
32006
32007 \size footnotesize
32008 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
32009  + 0x1 {short}
32010 \layout Standard
32011
32012
32013 \size footnotesize
32014 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
32015  r6]- 0x1 {short}
32016 \layout Standard
32017
32018
32019 \size footnotesize
32020 Sample.c(19:38:47:1) goto _forcond_0($4)
32021 \layout Standard
32022
32023
32024 \size footnotesize
32025 Sample.c(19:39:48:0)_forbreak_0($7) :
32026 \layout Standard
32027
32028
32029 \size footnotesize
32030 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
32031  + ITemp11 [lr19:40]{short}[r3]
32032 \layout Standard
32033
32034
32035 \size footnotesize
32036 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
32037 \layout Standard
32038
32039
32040 \size footnotesize
32041 Sample.c(20:42:51:0)_return($8) :
32042 \layout Standard
32043
32044
32045 \size footnotesize
32046 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
32047 \size default
32048
32049 \newline
32050
32051 \newline
32052 Finally the code generated for this function:
32053 \newline
32054
32055 \layout Standard
32056
32057
32058 \size footnotesize
32059 .area DSEG (DATA)
32060 \layout Standard
32061
32062
32063 \size footnotesize
32064 _p::
32065 \layout Standard
32066
32067
32068 \size footnotesize
32069 \SpecialChar ~
32070 \SpecialChar ~
32071 .ds 2
32072 \layout Standard
32073
32074
32075 \size footnotesize
32076 _gint::
32077 \layout Standard
32078
32079
32080 \size footnotesize
32081 \SpecialChar ~
32082 \SpecialChar ~
32083 .ds 2
32084 \layout Standard
32085
32086
32087 \size footnotesize
32088 ; sample.c 5
32089 \layout Standard
32090
32091
32092 \size footnotesize
32093 ; ----------------------------------------------
32094 \layout Standard
32095
32096
32097 \size footnotesize
32098 ; function function
32099 \layout Standard
32100
32101
32102 \size footnotesize
32103 ; ----------------------------------------------
32104 \layout Standard
32105
32106
32107 \size footnotesize
32108 _function:
32109 \layout Standard
32110
32111
32112 \size footnotesize
32113 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
32114 \layout Standard
32115
32116
32117 \size footnotesize
32118 \SpecialChar ~
32119 \SpecialChar ~
32120 mov r2,dpl
32121 \layout Standard
32122
32123
32124 \size footnotesize
32125 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
32126 \layout Standard
32127
32128
32129 \size footnotesize
32130 \SpecialChar ~
32131 \SpecialChar ~
32132 mov ar0,r2
32133 \layout Standard
32134
32135
32136 \size footnotesize
32137 ;_whilecontinue_0($1) :
32138 \layout Standard
32139
32140
32141 \size footnotesize
32142 00101$:
32143 \layout Standard
32144
32145
32146 \size footnotesize
32147 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
32148 \layout Standard
32149
32150
32151 \size footnotesize
32152 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
32153 \layout Standard
32154
32155
32156 \size footnotesize
32157 \SpecialChar ~
32158 \SpecialChar ~
32159 mov ar2,@r0
32160 \layout Standard
32161
32162
32163 \size footnotesize
32164 \SpecialChar ~
32165 \SpecialChar ~
32166 inc r0
32167 \layout Standard
32168
32169
32170 \size footnotesize
32171 \SpecialChar ~
32172 \SpecialChar ~
32173 mov ar3,@r0
32174 \layout Standard
32175
32176
32177 \size footnotesize
32178 \SpecialChar ~
32179 \SpecialChar ~
32180 dec r0
32181 \layout Standard
32182
32183
32184 \size footnotesize
32185 \SpecialChar ~
32186 \SpecialChar ~
32187 mov a,r2
32188 \layout Standard
32189
32190
32191 \size footnotesize
32192 \SpecialChar ~
32193 \SpecialChar ~
32194 orl a,r3
32195 \layout Standard
32196
32197
32198 \size footnotesize
32199 \SpecialChar ~
32200 \SpecialChar ~
32201 jz 00103$
32202 \layout Standard
32203
32204
32205 \size footnotesize
32206 00114$:
32207 \layout Standard
32208
32209
32210 \size footnotesize
32211 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
32212 \layout Standard
32213
32214
32215 \size footnotesize
32216 \SpecialChar ~
32217 \SpecialChar ~
32218 mov dpl,_p
32219 \layout Standard
32220
32221
32222 \size footnotesize
32223 \SpecialChar ~
32224 \SpecialChar ~
32225 mov dph,(_p + 1)
32226 \layout Standard
32227
32228
32229 \size footnotesize
32230 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
32231 \layout Standard
32232
32233
32234 \size footnotesize
32235 \SpecialChar ~
32236 \SpecialChar ~
32237 mov a,#0x02
32238 \layout Standard
32239
32240
32241 \size footnotesize
32242 \SpecialChar ~
32243 \SpecialChar ~
32244 add a,_p
32245 \layout Standard
32246
32247
32248 \size footnotesize
32249 \SpecialChar ~
32250 \SpecialChar ~
32251 mov _p,a
32252 \layout Standard
32253
32254
32255 \size footnotesize
32256 \SpecialChar ~
32257 \SpecialChar ~
32258 clr a
32259 \layout Standard
32260
32261
32262 \size footnotesize
32263 \SpecialChar ~
32264 \SpecialChar ~
32265 addc a,(_p + 1)
32266 \layout Standard
32267
32268
32269 \size footnotesize
32270 \SpecialChar ~
32271 \SpecialChar ~
32272 mov (_p + 1),a
32273 \layout Standard
32274
32275
32276 \size footnotesize
32277 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
32278 \layout Standard
32279
32280
32281 \size footnotesize
32282 \SpecialChar ~
32283 \SpecialChar ~
32284 movx a,@dptr
32285 \layout Standard
32286
32287
32288 \size footnotesize
32289 \SpecialChar ~
32290 \SpecialChar ~
32291 mov r2,a
32292 \layout Standard
32293
32294
32295 \size footnotesize
32296 \SpecialChar ~
32297 \SpecialChar ~
32298 inc dptr
32299 \layout Standard
32300
32301
32302 \size footnotesize
32303 \SpecialChar ~
32304 \SpecialChar ~
32305 movx a,@dptr
32306 \layout Standard
32307
32308
32309 \size footnotesize
32310 \SpecialChar ~
32311 \SpecialChar ~
32312 mov r3,a
32313 \layout Standard
32314
32315
32316 \size footnotesize
32317 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
32318 \layout Standard
32319
32320
32321 \size footnotesize
32322 \SpecialChar ~
32323 \SpecialChar ~
32324 mov @r0,ar2
32325 \layout Standard
32326
32327
32328 \size footnotesize
32329 \SpecialChar ~
32330 \SpecialChar ~
32331 inc r0
32332 \layout Standard
32333
32334
32335 \size footnotesize
32336 \SpecialChar ~
32337 \SpecialChar ~
32338 mov @r0,ar3
32339 \layout Standard
32340
32341
32342 \size footnotesize
32343 ; iTemp6 [lr5:16]{_near * int}[r0] =
32344 \layout Standard
32345
32346
32347 \size footnotesize
32348 ; iTemp6 [lr5:16]{_near * int}[r0] +
32349 \layout Standard
32350
32351
32352 \size footnotesize
32353 ; 0x2 {short}
32354 \layout Standard
32355
32356
32357 \size footnotesize
32358 \SpecialChar ~
32359 \SpecialChar ~
32360 inc r0
32361 \layout Standard
32362
32363
32364 \size footnotesize
32365 ; goto _whilecontinue_0($1)
32366 \layout Standard
32367
32368
32369 \size footnotesize
32370 \SpecialChar ~
32371 \SpecialChar ~
32372 sjmp 00101$
32373 \layout Standard
32374
32375
32376 \size footnotesize
32377 ; _whilebreak_0($3) :
32378 \layout Standard
32379
32380
32381 \size footnotesize
32382 00103$:
32383 \layout Standard
32384
32385
32386 \size footnotesize
32387 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
32388 \layout Standard
32389
32390
32391 \size footnotesize
32392 \SpecialChar ~
32393 \SpecialChar ~
32394 mov r2,#0x00
32395 \layout Standard
32396
32397
32398 \size footnotesize
32399 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
32400 \layout Standard
32401
32402
32403 \size footnotesize
32404 \SpecialChar ~
32405 \SpecialChar ~
32406 mov r3,#0x00
32407 \layout Standard
32408
32409
32410 \size footnotesize
32411 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
32412 \layout Standard
32413
32414
32415 \size footnotesize
32416 \SpecialChar ~
32417 \SpecialChar ~
32418 mov r4,#0x00
32419 \layout Standard
32420
32421
32422 \size footnotesize
32423 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
32424 \layout Standard
32425
32426
32427 \size footnotesize
32428 \SpecialChar ~
32429 \SpecialChar ~
32430 mov r5,#0x0A
32431 \layout Standard
32432
32433
32434 \size footnotesize
32435 \SpecialChar ~
32436 \SpecialChar ~
32437 mov r6,#0x00
32438 \layout Standard
32439
32440
32441 \size footnotesize
32442 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
32443 \layout Standard
32444
32445
32446 \size footnotesize
32447 \SpecialChar ~
32448 \SpecialChar ~
32449 mov r7,#0x1E
32450 \layout Standard
32451
32452
32453 \size footnotesize
32454 \SpecialChar ~
32455 \SpecialChar ~
32456 mov r0,#0x00
32457 \layout Standard
32458
32459
32460 \size footnotesize
32461 ; _forcond_0($4) :
32462 \layout Standard
32463
32464
32465 \size footnotesize
32466 00104$:
32467 \layout Standard
32468
32469
32470 \size footnotesize
32471 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
32472 \layout Standard
32473
32474
32475 \size footnotesize
32476 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
32477 \layout Standard
32478
32479
32480 \size footnotesize
32481 \SpecialChar ~
32482 \SpecialChar ~
32483 clr c
32484 \layout Standard
32485
32486
32487 \size footnotesize
32488 \SpecialChar ~
32489 \SpecialChar ~
32490 mov a,r4
32491 \layout Standard
32492
32493
32494 \size footnotesize
32495 \SpecialChar ~
32496 \SpecialChar ~
32497 xrl a,#0x80
32498 \layout Standard
32499
32500
32501 \size footnotesize
32502 \SpecialChar ~
32503 \SpecialChar ~
32504 subb a,#0x8a
32505 \layout Standard
32506
32507
32508 \size footnotesize
32509 \SpecialChar ~
32510 \SpecialChar ~
32511 jnc 00107$
32512 \layout Standard
32513
32514
32515 \size footnotesize
32516 00115$:
32517 \layout Standard
32518
32519
32520 \size footnotesize
32521 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
32522 \layout Standard
32523
32524
32525 \size footnotesize
32526 ; iTemp21 [lr21:38]{short}[r4]
32527 \layout Standard
32528
32529
32530 \size footnotesize
32531 \SpecialChar ~
32532 \SpecialChar ~
32533 mov a,r4
32534 \layout Standard
32535
32536
32537 \size footnotesize
32538 \SpecialChar ~
32539 \SpecialChar ~
32540 add a,r2
32541 \layout Standard
32542
32543
32544 \size footnotesize
32545 \SpecialChar ~
32546 \SpecialChar ~
32547 mov r2,a
32548 \layout Standard
32549
32550
32551 \size footnotesize
32552 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
32553 \layout Standard
32554
32555
32556 \size footnotesize
32557 \SpecialChar ~
32558 \SpecialChar ~
32559 mov b,#0x03
32560 \layout Standard
32561
32562
32563 \size footnotesize
32564 \SpecialChar ~
32565 \SpecialChar ~
32566 mov a,r4
32567 \layout Standard
32568
32569
32570 \size footnotesize
32571 \SpecialChar ~
32572 \SpecialChar ~
32573 mul ab
32574 \layout Standard
32575
32576
32577 \size footnotesize
32578 \SpecialChar ~
32579 \SpecialChar ~
32580 mov r1,a
32581 \layout Standard
32582
32583
32584 \size footnotesize
32585 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
32586 \layout Standard
32587
32588
32589 \size footnotesize
32590 ; iTemp15 [lr29:30]{short}[r1]
32591 \layout Standard
32592
32593
32594 \size footnotesize
32595 \SpecialChar ~
32596 \SpecialChar ~
32597 add a,r3
32598 \layout Standard
32599
32600
32601 \size footnotesize
32602 \SpecialChar ~
32603 \SpecialChar ~
32604 mov r3,a
32605 \layout Standard
32606
32607
32608 \size footnotesize
32609 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
32610 \layout Standard
32611
32612
32613 \size footnotesize
32614 \SpecialChar ~
32615 \SpecialChar ~
32616 mov a,r7
32617 \layout Standard
32618
32619
32620 \size footnotesize
32621 \SpecialChar ~
32622 \SpecialChar ~
32623 add a,#0xfd
32624 \layout Standard
32625
32626
32627 \size footnotesize
32628 \SpecialChar ~
32629 \SpecialChar ~
32630 mov r7,a
32631 \layout Standard
32632
32633
32634 \size footnotesize
32635 \SpecialChar ~
32636 \SpecialChar ~
32637 mov a,r0
32638 \layout Standard
32639
32640
32641 \size footnotesize
32642 \SpecialChar ~
32643 \SpecialChar ~
32644 addc a,#0xff
32645 \layout Standard
32646
32647
32648 \size footnotesize
32649 \SpecialChar ~
32650 \SpecialChar ~
32651 mov r0,a
32652 \layout Standard
32653
32654
32655 \size footnotesize
32656 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
32657 \layout Standard
32658
32659
32660 \size footnotesize
32661 \SpecialChar ~
32662 \SpecialChar ~
32663 mov a,r7
32664 \layout Standard
32665
32666
32667 \size footnotesize
32668 \SpecialChar ~
32669 \SpecialChar ~
32670 add a,_gint
32671 \layout Standard
32672
32673
32674 \size footnotesize
32675 \SpecialChar ~
32676 \SpecialChar ~
32677 mov _gint,a
32678 \layout Standard
32679
32680
32681 \size footnotesize
32682 \SpecialChar ~
32683 \SpecialChar ~
32684 mov a,r0
32685 \layout Standard
32686
32687
32688 \size footnotesize
32689 \SpecialChar ~
32690 \SpecialChar ~
32691 addc a,(_gint + 1)
32692 \layout Standard
32693
32694
32695 \size footnotesize
32696 \SpecialChar ~
32697 \SpecialChar ~
32698 mov (_gint + 1),a
32699 \layout Standard
32700
32701
32702 \size footnotesize
32703 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
32704 \layout Standard
32705
32706
32707 \size footnotesize
32708 \SpecialChar ~
32709 \SpecialChar ~
32710 inc r4
32711 \layout Standard
32712
32713
32714 \size footnotesize
32715 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
32716 \layout Standard
32717
32718
32719 \size footnotesize
32720 \SpecialChar ~
32721 \SpecialChar ~
32722 dec r5
32723 \layout Standard
32724
32725
32726 \size footnotesize
32727 \SpecialChar ~
32728 \SpecialChar ~
32729 cjne r5,#0xff,00104$
32730 \layout Standard
32731
32732
32733 \size footnotesize
32734 \SpecialChar ~
32735 \SpecialChar ~
32736 dec r6
32737 \layout Standard
32738
32739
32740 \size footnotesize
32741 ; goto _forcond_0($4)
32742 \layout Standard
32743
32744
32745 \size footnotesize
32746 \SpecialChar ~
32747 \SpecialChar ~
32748 sjmp 00104$
32749 \layout Standard
32750
32751
32752 \size footnotesize
32753 ; _forbreak_0($7) :
32754 \layout Standard
32755
32756
32757 \size footnotesize
32758 00107$:
32759 \layout Standard
32760
32761
32762 \size footnotesize
32763 ; ret iTemp24 [lr40:41]{short}
32764 \layout Standard
32765
32766
32767 \size footnotesize
32768 \SpecialChar ~
32769 \SpecialChar ~
32770 mov a,r3
32771 \layout Standard
32772
32773
32774 \size footnotesize
32775 \SpecialChar ~
32776 \SpecialChar ~
32777 add a,r2
32778 \layout Standard
32779
32780
32781 \size footnotesize
32782 \SpecialChar ~
32783 \SpecialChar ~
32784 mov dpl,a
32785 \layout Standard
32786
32787
32788 \size footnotesize
32789 ; _return($8) :
32790 \layout Standard
32791
32792
32793 \size footnotesize
32794 00108$:
32795 \layout Standard
32796
32797
32798 \size footnotesize
32799 \SpecialChar ~
32800 \SpecialChar ~
32801 ret
32802 \newline
32803
32804 \layout Section
32805
32806 A few words about basic block successors, predecessors and dominators
32807 \layout Standard
32808
32809 Successors are basic blocks
32810 \begin_inset LatexCommand \index{Basic blocks}
32811
32812 \end_inset
32813
32814  that might execute after this basic block.
32815 \newline
32816 Predecessors are basic blocks that might execute before reaching this basic
32817  block.
32818 \newline
32819 Dominators are basic blocks that WILL execute before reaching this basic
32820  block.
32821 \newline
32822
32823 \layout Standard
32824
32825 [basic block 1]
32826 \layout Standard
32827
32828 if (something)
32829 \layout Standard
32830
32831 \SpecialChar ~
32832 \SpecialChar ~
32833 \SpecialChar ~
32834 \SpecialChar ~
32835 [basic block 2]
32836 \layout Standard
32837
32838 else
32839 \layout Standard
32840
32841 \SpecialChar ~
32842 \SpecialChar ~
32843 \SpecialChar ~
32844 \SpecialChar ~
32845 [basic block 3]
32846 \layout Standard
32847
32848 [basic block 4]
32849 \newline
32850
32851 \layout Standard
32852
32853 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
32854 \layout Standard
32855
32856 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
32857 \layout Standard
32858
32859 c) domVect of [BB4] = BB1 ...
32860  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
32861  was executed.
32862 \layout Chapter
32863
32864 Acknowledgments
32865 \layout Standard
32866
32867
32868 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
32869
32870 \end_inset
32871
32872
32873 \newline
32874
32875 \newline
32876
32877 \emph on
32878 Thanks to all the other volunteer developers who have helped with coding,
32879  testing, web-page creation, distribution sets, etc.
32880  You know who you are :-)
32881 \emph default
32882
32883 \newline
32884
32885 \newline
32886
32887 \emph on
32888 Also thanks to Sourceforge
32889 \begin_inset LatexCommand \url{http://www.sf.net}
32890
32891 \end_inset
32892
32893  which has hosted the project since 1999 and donates significant download
32894  bandwidth and probably more than
32895 \begin_inset ERT
32896 status Collapsed
32897
32898 \layout Standard
32899 $10^{13}$
32900 \end_inset
32901
32902 CPU cycles per day.
32903 \newline
32904
32905 \begin_inset Note
32906 collapsed false
32907
32908 \layout Standard
32909
32910 more than 10^13 is an estimate: on my Athlon 2800+ it takes about (0.5+6.5+20)
32911  minutes for (configure+make+regression test), and there is (i386, amd64,
32912  alpha, ppc64, (mingw32), sparc, macosx).
32913
32914 \end_inset
32915
32916
32917 \layout Standard
32918
32919 This document was initially written by Sandeep Dutta
32920 \layout Standard
32921
32922 All product names mentioned herein may be trademarks
32923 \begin_inset LatexCommand \index{Trademarks}
32924
32925 \end_inset
32926
32927  of their respective companies.
32928
32929 \layout Section*
32930
32931 Alphabetical index
32932 \layout Standard
32933
32934 To avoid confusion, the installation and building options for SDCC itself
32935  (chapter 2) are not part of the index.
32936 \layout Standard
32937
32938
32939 \begin_inset LatexCommand \printindex{}
32940
32941 \end_inset
32942
32943
32944 \the_end