PiDP-8/I SoftwareCheck-in [84f718936e]
Not logged in

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Updated the CC8 user manual to cover the new octal output default.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | cc8-octal-output
Files: files | file ages | folders
SHA3-256:84f718936e3440fe4d6692c1f9afc604670008bcc5efaf056d6f8bae6f2dca79
User & Date: tangent 2019-02-21 08:55:33
Context
2019-02-21
09:08
Rewrote the history section at the top of the CC8 manual to give a better arc. check-in: 694c027652 user: tangent tags: cc8-octal-output
08:55
Updated the CC8 user manual to cover the new octal output default. check-in: 84f718936e user: tangent tags: cc8-octal-output
08:12
Squished the bug that prevents this branch from generating code that runs properly: I overlooked the #defines in libc.h which are treated by the compiler as text, not as C integers, so that integer indices emitted in the generated SABR code for calling into LIBC were in decimal but were then interpreted by SABR as octal. If this gave syntactically correct code, it would call the wrong function for every function past index 7. The fact that we never saw it generate syntactically incorrect code merely reflects the fact that we didn't happen to call any functions that used decimal indexes that have no corresponding octal interpretation, a possibility only 1/5 of the time. (e.g. 29) check-in: d5ab8f91d9 user: tangent tags: cc8-octal-output
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to doc/cc8-manual.md.

1722
1723
1724
1725
1726
1727
1728






















1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
....
1761
1762
1763
1764
1765
1766
1767
1768

1769
1770

1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799

1800
1801
1802
1803
1804
1805
1806
That example is based on real code, the implementation of
[`itoa()`](#itoa) for radices beyond 10: we tried it both ways and ended
up doing it the obscure way to save code space in LIBC.

For the most part, CC8 currently leaves the task of optimization to the
end user.
























### <a id="linkage" name="varargs"></a>Library Linkage and Varargs

CC8 has some non-standard features to enable the interface between the
main program and the C library. This constitutes a compile time linkage
system to allow for standard and vararg functions to be called in the
library.

**TODO:** Explain this.


### <a id="os8asm"></a>Inline Assembly in the Native CC8 Compiler

#### Limitations

The native compiler has some significant limitations in the way it
handles inline assembly.

The primary one is that snippets of inline assembly are gathered by the
[first pass](#ncpass) of the compiler in a core memory buffer that’s
only 1024 characters in size. If the total amount of inline assembly in
................................................................................
[`fopen()`](#fopen) is limited to a [single output file at a
time](#fiolim) and it cannot append to an existing file, it’s got one
shot to write everything it collected.

This is one reason the CC8 LIBC has to be cross-compiled: its inline
assembly is over 6&times; the size of this buffer.



#### Incompatibilities


The only known incompatibility between the compilers in the way they
handle inline assembly is that the native compiler inserts a `DECIM`
directive early in its SABR output, so all constants in inline assembly
that aren’t specifically given a radix are treated as decimal numbers:

    #asm
        TAD (42
    #endasm

That instruction adds 42 decimal to AC when compiled with the native
compiler, but it adds 34 decimal (42₈) with the cross-compiler because
the cross-compiler leaves SABR in its default octal mode!

If you want code to work with both, use the SABR-specific `D` and `K`
prefix feature on constants:

    #asm
        TAD (D42      / add 42 *decimal* to AC
    #endasm

We cannot recommend using the `DECIM` and `OCTAL` SABR pseudo-ops in
code that has to work with both compilers because there’s no way to tell
what directive to give at the end of the `#asm` block to restore prior
behavior. If you switch the mode without switching it back properly,
SABR code emitted by the compiler itself will be misinterpreted.

There’s a `DECIM` directive high up in the implementation of LIBC, but
that’s fine since it knows it will be compiled by the cross-compiler
only.



### <a id="opdef"></a>Predefined OPDEFs

In addition to the op-codes predefined for SABR — which you can find in
[Appendix C of the OS/8 Handbook, 1974 edition][os8hac] — the following
`OPDEF` directives are inserted at the top of every SABR file output







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>











|
<
<







 







<
>
|
<
>
|
|
|
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
>







1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762


1763
1764
1765
1766
1767
1768
1769
....
1781
1782
1783
1784
1785
1786
1787

1788
1789

1790
1791
1792
1793
1794

























1795
1796
1797
1798
1799
1800
1801
1802
That example is based on real code, the implementation of
[`itoa()`](#itoa) for radices beyond 10: we tried it both ways and ended
up doing it the obscure way to save code space in LIBC.

For the most part, CC8 currently leaves the task of optimization to the
end user.


### <a id="asmoct"></a>Inline Assembly is in Octal

Like the OS/8 FORTRAN II compiler, the CC8 compilers leave SABR in its
default octal mode. All integer constants emited by both compilers are
in octal.  (Even those in generated labels and in error output
messages!) This means integer constants in your inline assembly also get
interpreted as octal, by default.

If you use the `DECIM` SABR pseudo-op to get around this, you must be
careful to add an `OCTAL` op before the block ends to shift the mode
back. The compiler doesn’t detect use of `DECIM`, and it doesn’t blindly
inject `OCTAL` ops after every inline assembly block to force the mode
back on the off chance that the user had shifted the assembler into
decimal mode. If you leave the assembler in `DECIM` mode at the end of
an inline assembly block, the resulting SABR output will probably
assemble but won’t run correctly because all integer constants from that
point on will be misinterpreted.

It’s safer, if you wan a given constant to be interpreted as decimal, to
prefix it with a `D`. See the SABR manual for more details on this.


### <a id="linkage" name="varargs"></a>Library Linkage and Varargs

CC8 has some non-standard features to enable the interface between the
main program and the C library. This constitutes a compile time linkage
system to allow for standard and vararg functions to be called in the
library.

**TODO:** Explain this.


### <a id="os8asm"></a>Inline Assembly Limitations in the Native CC8 Compiler



The native compiler has some significant limitations in the way it
handles inline assembly.

The primary one is that snippets of inline assembly are gathered by the
[first pass](#ncpass) of the compiler in a core memory buffer that’s
only 1024 characters in size. If the total amount of inline assembly in
................................................................................
[`fopen()`](#fopen) is limited to a [single output file at a
time](#fiolim) and it cannot append to an existing file, it’s got one
shot to write everything it collected.

This is one reason the CC8 LIBC has to be cross-compiled: its inline
assembly is over 6&times; the size of this buffer.


Another problem to watch out for is that this inline assembly buffer is
broken into sections with `!` and `$` characters so that the final pass

of the compiler can break the `CASM.TX` file up into sections for
insertion into the SABR output. It is therefore unsafe to use these
characters in your inline assembly, lest they be seen as separators,
causing incorrect output.  This is especially easy to do in comments;
watch out! (See how easy it is to use an exclamation point when making

























comments?)


### <a id="opdef"></a>Predefined OPDEFs

In addition to the op-codes predefined for SABR — which you can find in
[Appendix C of the OS/8 Handbook, 1974 edition][os8hac] — the following
`OPDEF` directives are inserted at the top of every SABR file output