PiDP-8/I SoftwareCheck-in [0316450b57]
Not logged in

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

Overview
Comment:Many improvements to the CC8 user manual. Basically, I began re-reading it from the top, improving it along the way with my new understanding of CC8.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | cc8-octal-output
Files: files | file ages | folders
SHA3-256:0316450b578536dd665578176f8118e68f92b6585e59304c574c44e5966a4cce
User & Date: tangent 2019-02-21 11:55:22
Context
2019-02-21
12:34
Updated ChangeLog check-in: a6371d4cad user: tangent tags: cc8-octal-output
11:55
Many improvements to the CC8 user manual. Basically, I began re-reading it from the top, improving it along the way with my new understanding of CC8. check-in: 0316450b57 user: tangent tags: cc8-octal-output
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
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to doc/cc8-manual.md.

37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


60
61
62
63
64
65
66
...
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

136

137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171


172
173
174
175
176
177

178


179


180


181

182
183
184
185
186
187
188
189
190







191
192
193
194
195
196
197
198
199

200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239

240
241
242
243
244
245
246
247
248
249
250
251
252
253



254

255
256
257
258
259
260









261
262
263

264
265
266
267
268
269
270
271
272



273
274
275
276

277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
...
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
...
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360

361
362
363
364
365
366
367
368
369
370


371
372
373
374
375
376
377
378
379
380
381


382
383
384
385
386
387
388
...
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
...
467
468
469
470
471
472
473
474
475
476
477
478
479




480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
....
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
....
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
....
1502
1503
1504
1505
1506
1507
1508







































1509
1510
1511
1512
1513
1514
1515
general-purpose programming language.

Although we are not likely to use CC8 to write a portable operating
system for the PDP-8, it is powerful enough to fill C’s original niche
in writing system utilities for a preexisting OS written in assembly.


## CC8’s Developmental Sparks

CC8 is a C subset implementation for the DEC PDP-8 processor.

The CC8 project’s creator (Ian Schofield) thought it was time to have a
modern language compiler running on the PDP-8. Ian actually wrote *two*
C compilers:

1.  A [cross-compiler](#cross) that builds and runs on any host computer
    with a C compiler that still understands K&R C.

2.  A [native OS/8 compiler](#native), compiled to assembly by the
    cross-compiler.

Ian also collected and wrote the [LIBC implementation](#libc) common to
both compilers.



The last high-level language compiler to be attempted for the PDP-8, as
far as this document’s authors are aware, was Pascal in 1979 by Heinz
Stegbauer.

In more recent times, Vince Slyngstad and Paolo Maffei wrote a C
cross-compiler based on Ron Cain’s Small-C using a VM approach. [This
................................................................................
independently of OS/8, but the bounds on that class of programs is not
currently clear to us.


<a id="cross" name="posix"></a>
## The Cross-Compiler

The features of the cross-compiler are basically that of Small-C itself,
being a good approximation of K&R C (1978) minus:

*   most of the standard library (see [below](#libc) for what we *do*
    have)

*   function pointers


*   `float` and `long`


The code for this is in the `src/cc8/cross` subdirectory of the PiDP-8/I
source tree, and it is built along with the top-level PiDP-8/I software.
When installed, this compiler is in your `PATH` as `cc8`.

Ian Schofield wrote the CC8 cross-compiler as a [SABR][sabr] code
generator for Ron Cain’s famous Small-C compiler, originally published
in [Dr Dobb’s Journal][ddj], with later versions published elsewhere.
William Cattey later ported this code base to Small-C 85, a living
project currently [available on GitHub][sc85].

This means the cross compiler more or less adheres to the *language*
dialect of C as published in "The C Programming Language," by Kernighan
and Ritchie, first edition, 1978. The reader is directed to the extensive
documentation of Small-C available on the web for further details. You
may also find references for K&R C 1978 helpful.

We stress *language* above because we have not attempted to clone the C
Standard Library as of K&R 1978.  CC8 has a [very limited standard
library](#libc), and it has many weaknesses relative to even early
versions of C. See that section of this manual for details about known
limitations, exclusions, and bugs.

The CC8 cross-compiler can successfully compile itself, but it produces
a SABR assembly file that is too large (28K) to be assembled on the
PDP-8.  Thus [the separate native compiler](#native).

The key module for targeting Small-C to the PDP-8 is `code8.c`. It
does the code generation to emit SABR assembly code. However, the
targeting is not confined to that one file. There is code in various
of the other modules that is specific to the PDP-8 port that should be
abstracted out and cleaned up in the fullness of time.

SABR is normally used as the second pass of the OS/8 FORTRAN II
system.



When you use the cross-compiler on a POSIX type system such as the
Raspbian PiDP-8/I environment, the resulting `*.sb` files will have
LF-only line endings, but OS/8 expects CR+LF line endings. The `txt2ptp`
utility program included with the PiDP-8/I distribution will
automatically do that conversion for you when making a SIMH paper tape

image file, which you can then read into the OS/8 environment.





[ddj]:  https://en.wikipedia.org/wiki/Dr._Dobb%27s_Journal


[sabr]: /wiki?name=A+Field+Guide+to+PDP-8+Assemblers#sabr

[sc85]: https://github.com/ncb85/SmallC-85


<a id="cpp"></a>
### The Cross-Compiler’s Preprocessor Features

The cross-compiler has rudimentary C preprocessor features:

*   Literal `#define` only.  You cannot define parameterized macros.







    There are no `-D` or `-U` flags to define and undefine macros from
    the command line.

*   `#undef` to remove a symbol previously defined with `#define`

*   `#include`, but only for files in the current directory.  There is
    no include path, either hard-coded within the compiler or modifiable
    via the traditional `-I` compiler flag. #include can appear within
    an included file but limited to 3 levels deep.


*   [Inline assembly](#asm) via `#asm`.

*   Simple `#ifdef` and `#ifndef` with direct match of symbol or macro
    names but not expressions. `#endif` is requried. `#else` is allowed.
    There is no support for `#if`.

*   **TBD:** Token pasting?

*   **TBD:** Stringization?


### <a id="nhead"></a>Necessary Headers

There are two header files shipped with CC8, intended to be used only by
users of the cross-compiler:

*   `libc.h` — Declares the entry points used by [LIBC](#libc) using
    CC8 [library linkage directives](#linkage). If your program makes
    use of any library functions, you must `#include` this at the top of
    your program.

*   `init.h` — Inserts a block of [inline assembly](#asm) startup code
    into your program, which initializes the program environment, sets
    up LIBC, and defines a few low-level routines. Certain programs may
    get away without this code, but the rules for which programs and why
    are not currently clear to us.  **TODO:** Find out the rules that
    govern whether this is necessary.

As a rule, all cross-compiler users should include both of these at the
top of every program.

Because the cross-compiler lacks an include path feature, you generally
want to symlink these files to the directory where your source files
are. This is already done for the CC8 examples and such.

If you compare the examples in the source tree (`src/cc8/examples`) to
those with uppercased versions of those same names on the OS/8 `DSK:`
volume, you’ll notice that these `#include` statements were stripped
out. This is [necessary](#os8pp); the linked documentation tells you why

and how the OS/8 version of CC8 gets away without a `#include` feature.

The tool that strips these `#includes` out for us is called
`bin/cc8-to-os8`, which you might find useful if you’re frequently
working with programs that need to work under both compilers.

Alternatively a simple `sed` script could be used:

    sed '/^#include/d' <yourfile>

<a id="native" name="os8"></a>
## The Native OS/8 Compiler

This compiler’s source code is in the `src/cc8/os8` subdirectory of the



PiDP-8/I software distribution.


Unlike in the original CC8 distribution or in past distributions of the
PiDP-8/I software, we no longer need to ship binaries for the compiler
to bootstrap the system. Due to the power of [`os8-run`][os8r] and the
PiDP-8/I software build system, we now bootstrap CC8 environment
entirely from source code unless the user passes the `--disable-os8-cc8`









option to the `configure` script.  This process is controlled by the
[`cc8-tu56.os8`][cctu] script, which you may want to examine along with
the `os8-run` documentation to understand this process better.


If you change the OS/8 CC8 source code, saying `make` at the PiDP-8/I
build root will update `bin/v3d.rk05` with new binaries automatically.

Because the CC8 native compiler is compiled by the CC8 *cross*-compiler,
the [standard memory layout](#memory) applies to both.  Among other
things, this means each pass of the native compiler requires
approximately 20&nbsp;kWords of core.




<a id="ncpass"></a>The compiler passes are:

1.  `c8.c` &rarr; `c8.sb` &rarr; `CC.SV`: The compiler driver: accepts
    the input file name from the user, and calls the first proper

    compiler pass, `CC1`.

2.  `n8.c` &rarr; `n8.sb` &rarr; `CC1.SV`: The parser/tokeniser section
    of the compiler.

3.  `p8.c` &rarr; `p8.sb` &rarr; `CC2.SV`: The token to SABR code
    converter section of the compiler.

`CC.SV` contains extremely rudimentary preprocessor features
documented [below](#os8pp).

There is also `libc.c` &rarr; `libc.sb` &rarr; `LIBC.RL`, the [C
library](#libc) linked to any program built with CC8, including the
passes above, but also to your own programs.

All of these binaries end up on the automatically-built OS/8 boot disk:
`CC?.SV` on `SYS:`, and everything else on `DSK:`, based on the defaults
our OS/8 distribution is configured to use when seeking out files.
................................................................................
1.  **Recursion:** See [`FIB.C`][fib] for an example of this.

1.  **Simple arithmetic operators:** `+`, `-`, `*`, `/`, etc.

1.  **Bitwise operators:** `&`, &brvbar;, `~` and `!`

1.  **Simple comparison operators:** False expressions evaluate as 0 and
    true as -1 in twos complement form, meaning all 1's in binary form.
    See the list of limitations below for the operators excluded by our
    "simple" qualifier.

1.  **A few 2-character operators:** `++`, `--` (postfix only) and `==`.

1.  **Limited library:** See [below](#libc) for a list of library
    functions provided, including their known limitations relative to
................................................................................

[fib]: /doc/trunk/src/cc8/examples/fib.c


<a id="nlim" name="limitations"></a>
### Known Limitations of the OS/8 CC8 Compiler

The OS/8 version of CC8 is missing many language features relative to
[the cross-compiler](#cross), and much more compared to modern C.

1.  <a id="typeless"></a>The language is typeless in that everything is
    a 12 bit integer and any variable/array can interpreted as `int`, `char`
    or pointer.  All variables and arrays must be declared as `int`.
    The return type may be left off of a function's definition; it is
    implicitly `int` in all cases, since `void` is not supported.

    **TBD** A recent update may have added void.


    Further to this point, in the OS/8 version of CC8, it is optional
    to declare the types of the arguments to a function. For example,
    the following is likely to be rejected by a strictly conforming
    K&R C compiler, but it is legal in OS/8 CC8 because the types
    are already known, there being only one data tyype in OS/8 CC8:

        myfn(n) { /* do something with n; optionally return something */ }

    This declares a function taking an `int` called `n` and returning


    an `int`. Contrast the CC8 cross-compiler, which requires the
    function's argument type to be declared, if not the return type:

        myfn(n)
        int n;
        {
            /* do something with n; optionally return something */
        }

    (The return type cannot be `void` since there is no `void` in
    K&R C as published in 1978, thus not in CC8, either.)



2.  There must be an `int main()`, and it must be the last function
    in the single input C file.

    Since OS/8 has no way to pass command line arguments to a program
    — at least, not in a way that is compatible with the Unix style
    command lines expected by C — the `main()` function is never
................................................................................
    support for preprocessor directives.

    *   Literal `#define` only: no parameterized macros, and no `#undef`.

    *   `#include` is not supported and must not appear in the C source
        code fed to the Native OS/8 Compiler.

        You cannot use `#include` directives to string multiple C modules
        into a single program.

        It also means that if you take a program that the cross-compiler
        handles correctly and just copy it straight into OS/8 and try to
        compile it, it probably still has the `#include <libc.h>` line and
        possibly one for `init.h` as well. *Such code will fail to compile.*
        You must strip such lines out when copying C files into OS/8.

        (The native compiler emits startup code automatically, and it
        hard-codes the LIBC call table in the [final compiler
        pass](#ncpass), implemented in `p8.c`, so it doesn’t need
        `#include` to make these things work.)

    *   [Broken](#os8asm) handling of [inline assmembly](#asm) via `#asm`.

    *   No support for `#if`, `#ifdef`, etc.

5.  Variables are implicitly `static`, even when local.

6.  Arrays may only be single indexed. See `PS.C` for an example.

7.  The compiler does not yet understand how to assign a variable's
    initial value as part of its declaration. This:
................................................................................
    expression to a form that is now legal in our limited C dialect. All
    of this comes from the Laws section of the linked Wikipedia article;
    if you learn nothing else about Boolean algebra, you would be well
    served to memorize those rules.

9. Dereferencing parenthesized expressions does not work: `*(<expr>)`

10. The stack, which includes all globals and literals, is only 4&nbsp;kWords.
    Stack overflow is not detected.  Literals are inlcuded in this due
    to a limitation in the way `COMMN` is implemented in SABR.

11. There is no argument list checking, not even for standard library
    functions.





12. `do/while` loops are parsed, but the code is not properly generated.
    Regular `while` loops work, as does `break`, so one workaround for a
    lack of `do/while` is:

        while (1) { /* do something useful */; if (cond) break; }

    We have no intention to fix this.

13. `switch` doesn't work.

The provided [LIBC library functions](#libc) is also quite limited and
nonstandard compared to Standard C.  See the documentation for each
individual library function for details.


<a id="warning"></a>
#### GOVERNMENT HEALTH WARNING

**You are hereby warned**: The native OS/8 compiler does not contain any
error checking whatsoever. If the source files contain an error or you
................................................................................

Another set of examples not preinstalled on the OS/8 disk are
`examples/pep001-*.c`, which are described [elsewhere][pce].

[pce]: /wiki?name=PEP001.C


## Making Executables 

Executing `CCR.BI` loads, links, and runs your C program without
producing an executable file on disk.  You need only a small variation
on this BATCH file's contents to get an executable core image that
you can run with the OS/8 `R` command:

    .R CC                   ⇠ kinda like Unix cc(1)
................................................................................
data field](#udf). That is to say, the code generated by CC8 does not
use 15-bit extended addresses; it just flips between pages depending on
what type of data or code it’s trying to access.

This means it is possible to iterate a pointer past the end of a 4096
word core memory field, causing it to wrap around to 0 and continue
blithely along.  Since the last page of the user data field [is reserved
for use by OS/8](#os8res) and the first page of each field is [reserved
by the LOADER run time system](#ldrts), programs that do this will most
likely crash and may even destroy data. Our [LIBC implementation](#libc)
generally does not try to check for such wraparound problems, much less
signal errors when it happens. The programmer is expected to avoid doing
this.

Code that operates on pointers will generally only do its work within
the user data field. You will likely need to resort to [inline
assembly](#asm) and `CIF`/`CDF` instructions to escape that field.
Getting our [LIBC](#libc) to operate on other fields may be tricky or
even more difficult than it’s worth.

................................................................................

There is no `malloc()` in this C library and no space reserved for its
heap in [the user data field](#udf). Everything in a CC8 program is
statically-allocated, if you’re using stock C-level mechanisms. If your
program needs additional dynamically-allocated memory, you’ll need to
arrange access to it some other way, such as [via inline
assembly](#asm).









































### <a id="flayout"></a>Field Layout, Concrete Example

The field layout given [at the start of this section](#memory) is not
fixed. The linking loader is free to use any layout it likes, consistent
with any constraints in the input binaries. You can use the `/M` option







|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
>
>







 







|
|
<
<
<
<
<
<
>
|
>





|
|
|
|
|
|
|
|
|
|
<
<
<
<
<
<
<











|
|
>
>

<
<
|
|
<
>
|
>
>

>
>

>
>

>









>
>
>
>
>
>
>
|


<
<


|
<
>



|
|
|
|
|
|
<




|
<








|
|
|
|
<
<
<







|
|
>
|

<
|
|

|

<




|
>
>
>
|
>

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









>
>
>



|
>
|







<
<
<







 







|







 







|
|


|
|
|
|

|
>

<
<
<
<
<
<
|


>
>
|
|




|


|
|
>
>







 







|
|












|

|







 







<
<
<
<
|
<
>
>
>
>

|







|
<
<
<
<







 







|







 







|
|
|
|
|
<







 







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







37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
...
123
124
125
126
127
128
129
130
131






132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149







150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165


166
167

168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198


199
200
201

202
203
204
205
206
207
208
209
210
211

212
213
214
215
216

217
218
219
220
221
222
223
224
225
226
227
228



229
230
231
232
233
234
235
236
237
238
239
240

241
242
243
244
245

246
247
248
249
250
251
252
253
254
255
256




257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295



296
297
298
299
300
301
302
...
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
...
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370






371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
...
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
...
474
475
476
477
478
479
480




481

482
483
484
485
486
487
488
489
490
491
492
493
494
495




496
497
498
499
500
501
502
....
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
....
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488

1489
1490
1491
1492
1493
1494
1495
....
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
general-purpose programming language.

Although we are not likely to use CC8 to write a portable operating
system for the PDP-8, it is powerful enough to fill C’s original niche
in writing system utilities for a preexisting OS written in assembly.


## What Is CC8?

The CC8 system includes two different compilers, each of which
understands a different dialect of C:

1.  A [cross-compiler](#cross) that builds and runs on any host computer
    with a C compiler that still understands K&R C. This compiler
    understands most of K&R C itself, with the exceptions documented
    below.

2.  A [native OS/8 compiler](#native), cross-compiled on the host
    machine to PDP-8 assembly code by the cross-compiler. This compiler
    is [quite limited](#nlim) compared to the cross-compiler.

CC8 also includes [a small C library](#libc) shared by both compilers.


## CC8’s Developmental Sparks

The last high-level language compiler to be attempted for the PDP-8, as
far as this document’s authors are aware, was Pascal in 1979 by Heinz
Stegbauer.

In more recent times, Vince Slyngstad and Paolo Maffei wrote a C
cross-compiler based on Ron Cain’s Small-C using a VM approach. [This
................................................................................
independently of OS/8, but the bounds on that class of programs is not
currently clear to us.


<a id="cross" name="posix"></a>
## The Cross-Compiler

The CC8 cross-compiler is the [SmallC-85 C compiler][sc85] with a PDP-8
[SABR][sabr] code generator strapped to its back end. That means the C






language dialect understood by the CC8 cross-compiler is [K&R C
(1978)][krc] minus function pointers and the `float` and `long` data
types.

The code for this is in the `src/cc8/cross` subdirectory of the PiDP-8/I
source tree, and it is built along with the top-level PiDP-8/I software.
When installed, this compiler is in your `PATH` as `cc8`.

CC8 also includes a [small C library](#libc) in the files
`src/cc8/os8/libc.[ch]`, which is shared with the [native OS/8
compiler](#native). This library covers only a small fraction of what
the K&R C library does, in part due to system resource constraints.

Ian Schofield originally wrote the SABR code generator atop a version of
Ron Cain’s famous [Small-C compiler][sc80], originally published in [Dr
Dobb’s Journal][ddj], with later versions published elsewhere.  William
Cattey later ported this code base to SmallC-85, a living project
currently [available on GitHub][sc85].








The CC8 cross-compiler can successfully compile itself, but it produces
a SABR assembly file that is too large (28K) to be assembled on the
PDP-8.  Thus [the separate native compiler](#native).

The key module for targeting Small-C to the PDP-8 is `code8.c`. It
does the code generation to emit SABR assembly code. However, the
targeting is not confined to that one file. There is code in various
of the other modules that is specific to the PDP-8 port that should be
abstracted out and cleaned up in the fullness of time.

[Currently](/tktview?name=e1f6a5e4fe), the simplest way to get SABR
outputs from the CC8 cross-compiler into the PiDP-8/I simulator is to
use our `os8-cp` program in ASCII mode to copy SABR outputs from the
cross-compiler onto the simulator’s disk image:



    $ os8-cp -a -rk0s /opt/pidp8i/share/media/os8/v3d.rk05 \
      src/cc8/examples/ps.sb dsk:


That results in a file `DSK:PS.SB` with the POSIX LF-only line endings
translated to the CRLF line endings OS/8 wants. You can then assemble,
link, and run within the simulator, as described [below](#exes).

For related ideas, see the PiDP-8/I wiki article “[Getting Text In][gti].”

[ddj]:  https://en.wikipedia.org/wiki/Dr._Dobb%27s_Journal
[gti]:  http://localhost:8080/wiki?name=Getting+Text+In
[krc]:  https://en.wikipedia.org/wiki/The_C_Programming_Language
[sabr]: /wiki?name=A+Field+Guide+to+PDP-8+Assemblers#sabr
[sc80]: https://en.wikipedia.org/wiki/Small-C
[sc85]: https://github.com/ncb85/SmallC-85


<a id="cpp"></a>
### The Cross-Compiler’s Preprocessor Features

The cross-compiler has rudimentary C preprocessor features:

*   Literal `#define` only.  You cannot define parameterized macros.

*   There are no token pasting (`##`), stringization (`#`), or
    charization (`#@`) features, there being little point to these
    featuers of the C preprocessor without parameterized macros.

*   `#undef` removes a symbol previously defined with `#define`

*   There are no `-D` or `-U` flags to define and undefine macros from
    the command line.



*   `#include`, but only for files in the current directory.  There is
    no include path, either hard-coded within the compiler or modifiable
    via the traditional `-I` compiler flag. It is legal to nest `#include`

    statements, but the depth is currently limited to 3 levels, maximum.

*   [Inline assembly](#asm) via `#asm`.

*   `#ifdef`, `#ifndef`, `#else` and `#endif` work as expected, within
    the limitations on macros given above.

*   There is no support for `#if`, not even for simple things like `#if
    0`, much less for expressions such as `#if defined(XXX) &&
    !defined(YYY)`



### <a id="nhead"></a>Necessary Headers

There are two header files, for use with the cross-compiler only:


*   `libc.h` — Declares the entry points used by [LIBC](#libc) using
    CC8 [library linkage directives](#linkage). If your program makes
    use of any library functions, you must `#include` this at the top of
    your program.

*   `init.h` — Inserts a block of [inline assembly](#asm) startup code
    into your program, which initializes the program environment, sets
    up LIBC, and defines a few low-level routines. Unless you know this
    file’s contents and have determined that you do not need any of what
    it does for you, you probably cannot write a valid CC8 program that
    does not `#include` this header.




Because the cross-compiler lacks an include path feature, you generally
want to symlink these files to the directory where your source files
are. This is already done for the CC8 examples and such.

If you compare the examples in the source tree (`src/cc8/examples`) to
those with uppercased versions of those same names on the OS/8 `DSK:`
volume, you’ll notice that these `#include` statements were stripped out
as part of the disk pack build process. This is [necessary](#os8pp); the
linked documentation tells you why and how the OS/8 version of CC8 gets
away without a `#include` feature.


If you need to write C programs that build with both compilers, you can
convert the files like so:

    sed '/^#include/d' < my-program-cross.c > MYPROG.C



<a id="native" name="os8"></a>
## The Native OS/8 Compiler

Whereas the [CC8 cross-compiler](#cross) is basically just a PDP-8 code
generator strapped to the preexisting Small-C compiler, the native OS/8
CC8 compiler was written from scratch by Ian Schofield. It gets
cross-compiled, assembled, linked, and saved to the OS/8 disk packs as
part of the PiDP-8/I software build process. Thereafter, it is a
standalone system using only OS/8 resources.





Because this compiler must work entirely within the stringent limits of
the PDP-8 computer architecture and its OS/8 operating system, it speaks
a [much simpler dialect of C](#nfeat) than the cross-compiler, which
gets to use your host’s much greater resources.

Unlike with the original CC8 software distribution, the PiDP-8/I
software project does not ship any pre-built CC8 binaries.  Instead, we
bootstrap CC8 binaries from source code with the powerful
[`os8-run`][os8r] scripting language interpreter and the PiDP-8/I
software build system.  (You can suppress this by passing the
`--disable-os8-cc8` option to the `configure` script.) This process is
controlled by the [`cc8-tu56.os8`][cctu] script, which you may want to
examine along with the `os8-run` documentation to understand this
process better.

If you change the OS/8 CC8 source code, saying `make` at the PiDP-8/I
build root will update `bin/v3d.rk05` with new binaries automatically.

Because the CC8 native compiler is compiled by the CC8 *cross*-compiler,
the [standard memory layout](#memory) applies to both.  Among other
things, this means each pass of the native compiler requires
approximately 20&nbsp;kWords of core.

The native OS/8 CC8 compiler’s source code is in the `src/cc8/os8`
subdirectory of the PiDP-8/I software distribution.

<a id="ncpass"></a>The compiler passes are:

1.  `c8.c` &rarr; `c8.sb` &rarr; `CC.SV`: The compiler driver: accepts
    the input file name from the user, does some [rudimentary
    preprocessing](#os8pp) on it, and calls the first proper compiler
    pass, `CC1`.

2.  `n8.c` &rarr; `n8.sb` &rarr; `CC1.SV`: The parser/tokeniser section
    of the compiler.

3.  `p8.c` &rarr; `p8.sb` &rarr; `CC2.SV`: The token to SABR code
    converter section of the compiler.




There is also `libc.c` &rarr; `libc.sb` &rarr; `LIBC.RL`, the [C
library](#libc) linked to any program built with CC8, including the
passes above, but also to your own programs.

All of these binaries end up on the automatically-built OS/8 boot disk:
`CC?.SV` on `SYS:`, and everything else on `DSK:`, based on the defaults
our OS/8 distribution is configured to use when seeking out files.
................................................................................
1.  **Recursion:** See [`FIB.C`][fib] for an example of this.

1.  **Simple arithmetic operators:** `+`, `-`, `*`, `/`, etc.

1.  **Bitwise operators:** `&`, &brvbar;, `~` and `!`

1.  **Simple comparison operators:** False expressions evaluate as 0 and
    true as -1 in twos complement form, meaning all 1's in binary form.
    See the list of limitations below for the operators excluded by our
    "simple" qualifier.

1.  **A few 2-character operators:** `++`, `--` (postfix only) and `==`.

1.  **Limited library:** See [below](#libc) for a list of library
    functions provided, including their known limitations relative to
................................................................................

[fib]: /doc/trunk/src/cc8/examples/fib.c


<a id="nlim" name="limitations"></a>
### Known Limitations of the OS/8 CC8 Compiler

The OS/8 version of CC8 supports a subset of the C dialect understood by
[the cross-compiler](#cross), and thus of K&R C:

1.  <a id="typeless"></a>The language is typeless in that everything is
    a 12 bit integer, and any variable/array can interpreted as `int`,
    `char` or pointer.  All variables and arrays must be declared as
    `int`. As with K&R C, the return type may be left off of a
    function's definition; it is implicitly `int` in all cases.

    Because the types are already known, it is not necessary to give
    types when declaring function arguments:







        myfn(n) { /* do something with n */ }

    This declares a function taking an `int` called `n` and returning
    an `int`.
    
    Contrast the CC8 cross-compiler, which requires function argument
    types to be declared, if not the return type, per K&R C rules:

        myfn(n)
        int n;
        {
            /* do something with n */
        }

    The cross-compiler supports `void` as an extension to K&R C, but the
    native compiler does not, and it is not yet smart enough to flag
    code including it with an error. It will simply generate bad code
    when you try to use `void`.

2.  There must be an `int main()`, and it must be the last function
    in the single input C file.

    Since OS/8 has no way to pass command line arguments to a program
    — at least, not in a way that is compatible with the Unix style
    command lines expected by C — the `main()` function is never
................................................................................
    support for preprocessor directives.

    *   Literal `#define` only: no parameterized macros, and no `#undef`.

    *   `#include` is not supported and must not appear in the C source
        code fed to the Native OS/8 Compiler.

        This means you cannot use `#include` directives to string
        multiple C modules into a single program.

        It also means that if you take a program that the cross-compiler
        handles correctly and just copy it straight into OS/8 and try to
        compile it, it probably still has the `#include <libc.h>` line and
        possibly one for `init.h` as well. *Such code will fail to compile.*
        You must strip such lines out when copying C files into OS/8.

        (The native compiler emits startup code automatically, and it
        hard-codes the LIBC call table in the [final compiler
        pass](#ncpass), implemented in `p8.c`, so it doesn’t need
        `#include` to make these things work.)

    *   No conditional compilation: `#if`, `#ifdef`, `#else`, etc.

    *   [Inline assmembly](#asm) via `#asm`.

5.  Variables are implicitly `static`, even when local.

6.  Arrays may only be single indexed. See `PS.C` for an example.

7.  The compiler does not yet understand how to assign a variable's
    initial value as part of its declaration. This:
................................................................................
    expression to a form that is now legal in our limited C dialect. All
    of this comes from the Laws section of the linked Wikipedia article;
    if you learn nothing else about Boolean algebra, you would be well
    served to memorize those rules.

9. Dereferencing parenthesized expressions does not work: `*(<expr>)`





10. There is no argument list checking, not even for functions

    previously declared in the same C file. If we did fix this, the
    problem would still exist for functions in other modules, such as
    [`LIBC`](#libc), since K&R C doesn’t have prototypes; ANSI added
    that feature to C.

11. `do/while` loops are parsed, but the code is not properly generated.
    Regular `while` loops work, as does `break`, so one workaround for a
    lack of `do/while` is:

        while (1) { /* do something useful */; if (cond) break; }

    We have no intention to fix this.

12. `switch` doesn't work.






<a id="warning"></a>
#### GOVERNMENT HEALTH WARNING

**You are hereby warned**: The native OS/8 compiler does not contain any
error checking whatsoever. If the source files contain an error or you
................................................................................

Another set of examples not preinstalled on the OS/8 disk are
`examples/pep001-*.c`, which are described [elsewhere][pce].

[pce]: /wiki?name=PEP001.C


## <a id="exes"></a>Making Executables 

Executing `CCR.BI` loads, links, and runs your C program without
producing an executable file on disk.  You need only a small variation
on this BATCH file's contents to get an executable core image that
you can run with the OS/8 `R` command:

    .R CC                   ⇠ kinda like Unix cc(1)
................................................................................
data field](#udf). That is to say, the code generated by CC8 does not
use 15-bit extended addresses; it just flips between pages depending on
what type of data or code it’s trying to access.

This means it is possible to iterate a pointer past the end of a 4096
word core memory field, causing it to wrap around to 0 and continue
blithely along.  Since the last page of the user data field [is reserved
for use by OS/8](#os8res) and the first page of the UDF has [several
special uses](#udf), programs that do this will most likely crash and
may even destroy data. Our [LIBC implementation](#libc) generally does
not try to check for such wraparound problems, much less signal errors
when it happens. The programmer is expected to avoid doing this.


Code that operates on pointers will generally only do its work within
the user data field. You will likely need to resort to [inline
assembly](#asm) and `CIF`/`CDF` instructions to escape that field.
Getting our [LIBC](#libc) to operate on other fields may be tricky or
even more difficult than it’s worth.

................................................................................

There is no `malloc()` in this C library and no space reserved for its
heap in [the user data field](#udf). Everything in a CC8 program is
statically-allocated, if you’re using stock C-level mechanisms. If your
program needs additional dynamically-allocated memory, you’ll need to
arrange access to it some other way, such as [via inline
assembly](#asm).

(Fun trivia: there was no `malloc()` in K&R C, either! An appendix in
the first edition of “[The C Programming Language”][krc] gave a function
called `alloc()` that worked in terms of the old Unix syscall
[`sbrk(2)`][sbrk]. Early parts of the book gave a trivial version of
`alloc()` that was implemented in terms of a static buffer declared at
the top of the program, which was made big enough for the program’s
needs.  Sounds a lot like the way CC8 operates, yes?)

[sbrk]: https://pubs.opengroup.org/onlinepubs/7908799/xsh/brk.html


### <a id="vonn"></a>There Are No Storage Type Distinctions

It may surprise you to learn that literals are placed in the same field
as globals and the call stack.

Other C compilers place literals in among the executable code instead, a
fact that’s especially helpful on [Harvard architecture
microcontrollers][harch] with limited RAM. We don’t do it that way in
CC8 because literals are implemented in terms of the SABR `COMMN`
feature, which in turn is how OS/8 FORTRAN II implements `COMMON`. These
subsystems have no concept of “storage type” as in modern C compilers.


### <a id="sover"></a>Stack Overflow

Since CC8 places the call stack immediately after the last literal
stored in core, a program with many globals and/or literals will have
less usable stack space than a program with fewer of each.

Neither version of CC8 generates code to detect stack overflow. If you
try to push too much onto the stack, it will simply begin overwriting
the page OS/8 is using at the top of field 1. If you manage to blow the
stack by more than a page without crashing the program or the computer
first, the [stack pointer will wrap around](#ptrwrap) and the stack will
begin overwriting the first page of field 1.

[harch]: https://en.wikipedia.org/wiki/Harvard_architecture


### <a id="flayout"></a>Field Layout, Concrete Example

The field layout given [at the start of this section](#memory) is not
fixed. The linking loader is free to use any layout it likes, consistent
with any constraints in the input binaries. You can use the `/M` option