The 6809 microprocessor instructions for accessing memory via an index register or the stack pointer can be relatively short and fast when they are used in C programs to access “auto” (function local) variables or function arguments. The instructions for accessing global variables are normally not so nice and must be four bytes long and correspondingly slow. However, the 6809 has a nice feature which helps considerably. Memory, anywhere in a single page (256 byte block), may be accessed with fast, two byte instructions. This is called the “direct page”, and at any time its location is specified by the contents of the “direct page register” within the processor. The linkage editor sorts out where this could be, and it need not concern the programmer, who only needs to specify for the compiler which variables should be in the direct page to give the maximum benefit in code size and execution speed.

To this end, a new storage class specifier is recognized by the compiler. In the manner of K & R page 192, the sc-specifier list is extended as follows:

The new key word may be used in place of one of the other sc-specifiers, and its effect is that the variable will be placed in the direct page. “DIRECT” creates a global direct page variable. “EXTERN DIRECT” references an EXTERNAL-type direct page variable; and “STATIC DIRECT” creates a local direct page variable. These new classed may not be used to declare function arguments. “Direct” variables can be initialized but will, as with other variables not explicitly initialized, have the value zero at the start of program execution. 255 bytes are available in the direct page (the linker requires one byte). If all the direct variables occupy less than the full 255 bytes, the remaining global variables will occupy the balance and memory above if necessary. If too many bytes or storage are requested in the direct page, the linkage editor will report an error, and the programmer will have to reduce the use of DIRECT-type variables to fit the 256 bytes addressable by the 6809.

It should be kept in mind that “direct” is unique to this compiler, and it may not be possible to transport programs written using “direct” to other environments without modification.

As versatile as C is, occasionally there are some things that can only be done (or done at maximum speed) in assembly language. The OS-9 C compiler permits user-supplied assembly-language statements to be directly embedded in C source programs.

A line beginning with “#asm” switches the compiler into a mode which passes all subsequent lines directly to the assembly-language output, until a line beginning with “#endasm” is encountered. “#endasm” switches the mode back to normal. Care should be exercised when using this directive so that the correct code section is adhered to. Normal code from the compiler is in the PSECT (code) section. If your assembly code uses the VSECT (variable) section, be sure to put a ENDSECT directive at the end to leave the state correct for following compiler generated code.

The escape sequences for non-printing characters in character constants and strings (see K & R page 181) are extended as follows:

        linefeed (LF):  \l (lower case 'ell')

This is to distinguish LF (hex 0A) from \n which on OS-9 is the same as \r (hex 0D).

        bit patterns:  \NNN    (octal constant)
                       \dNNN   (decimal constant)
                       \xNN    (hexadecimal constant)

For example, the following all have a value of 255 (decimal):

             \377          \xff              \d255

Each variable type requires a specific amount of memory for storage. The sizes of the basic types in bytes are as follows:

This compiler follows the PDP-11 implementation and format in that CHARs are converted to INTs by sign extension, “SHORT” or “SHORT INT” means INT, “LONG INT” means LONG and “LONG FLOAT” means DOUBLE. The format for DOUBLE values is as follows:

(low byte)                                 (high byte)
+-+---------------------------------------+----------+
! !     seven byte                        ! 1 byte   !
! !      mantissa                         ! exponent !
+-+---------------------------------------+----------+
 ^ sign bit

The form of the mantissa is sign and magnitude with an implied “1” bit at the sign bit position. The exponent is biased by 128. The format of a FLOAT is identical, except that the mantissa is only three bytes long. Conversion from DOUBLE to FLOAT is carried out by truncating the least significant (right-most) four bytes of the mantissa. The reverse conversion is done by padding the least significant four mantissa bytes with zeros.

One register variable may be declared in each function. The only types permitted for register variables are int, unsigned and pointer. Invalid register variable declarations are ignored; i.e. the storage class is made auto. For further details see K & R page 81.

A considerable saving in code size and speed can be made by judicious use of a register variable. The most efficient use is made of it for a pointer or a counter for a loop. However, if a register variable is used for a complex arithmetic expression, there is no saving. The “U” register is assigned to register variables.

The standard C arguments “argc” and “argv” are available to “main” as described in K & R page 110. The start-up routine for C programs ensures that the parameter string passed to it by the parent process is converted into null-terminated strings as expected by the program. In addition, it will run together as a single argument any strings enclosed between single or double quotes (“'” or '"'). If either is part of the string required, then the other should be used as a delimiter.

There are hard references to /D1 in c.prep and cc1. You will have to do a couple of patches to get the C compiler to work off a hard drive. You can use the modpatch command to do these patches. The patches are as follows:

Load c.prep into memory and change the byte at offset $135C and $135D to the name of the drive you want (e.g. set $135C=68 'h' and $135D=30 '0'). Then load cc1 and do the same thing except at the offsets $0EE5 and $0EE6. Be sure to verify and save the modules back to disk. Alternatively use the command “verify u” to update the module CRC.

The system interface supports almost all the system calls of both OS-9 and UNIX. In order to facilitate the portability of programs from UNIX, some of the calls use UNIX names rather than OS-9 names for the same function. There are a few UNIX calls that do not have exactly equivalent OS-9 calls. In these cases, the library function simulates the function of the corresponding UNIX call. In cases where there are OS-9 calls that do not have UNIX equivalents, the OS-9 names are used. Details of the calls and a name cross-reference are provided in the “C System Calls” section of this manual.

The C compiler includes a very complete library of standard functions. It is essential for any program which uses functions from the standard library to have the statement:

       #include <stdio.h>

See the “C Standard Library” section of this manual for details on the standard library functions provided.

IMPORTANT NOTE: If output via printf(), fprintf() or sprintf() of long integers is required, the program MUST call “pflinit()” at some point; this is necessary so that programs not involving LONGS do not have the extra LONGs output code appended. Similarly, if FLOATs or DOUBLEs are to be printed, “pffinit()” MUST be called. These functions do nothing; existence of calls to them in a program informs the linker that the relevant routines are also needed.

Because the 6809 is an 8/16 bit microprocessor, the compiler can generate efficient code for 8 and 16 bit objects (CHARs, INTs, etc.). However, code for 32 and 64 bit values (LONGs, FLOATs, DOUBLEs) can be at least four times longer and slower. Therefore don't use LONG, FLOAT, or DOUBLE where INT or UNSIGNED will do.

The compiler can perform extensive evaluation of constant expressions provided they involve only constants of type CHAR, INT, and UNSIGNED. There is no constant expression evaluation at compile-time (except single constants and “casts” of them) where there are constants of type LONG, FLOAT, or DOUBLE, therefore, complex constant expressions involving these types are evaluated at run time by the compiled program. You should manually compute the value of constant expressions of these types if speed is essential.

The optimizer pass automatically occurs after the compilation passes. It reads the assembler source code text and removes redundant code and searches for code sequences that can be replaced by shorter and faster equivalents. The optimizer will shorten object code by about 11% with a significant increase in program execution speed. The optimizer is recommended for production versions of debugged programs. Because this pass takes additional time, the “-O” compiler option can be used to inhibit it during error-checking-only compilations.

The profiler is an optional method used to determine the frequency of execution of each function in a C program. It allows you to identify the most-frequently used functions where algorithmic or C source code programming improvements will yield the greatest gains.

When the “-P” compiler option is selected, code is generated at the beginning of each function to call the profiler module (called “_prof”), which counts invocations of each function during program execution. When the program has terminated, the profiler automatically prints a list of all functions and the number of times each was called. The profiler slightly reduces program execution speed. See “prof.c” source for more information.

A number of temporary files are created in the current data directory during compilation, and it is important to ensure that enough space is available on the disk drive. As a rough guide, at least three times the number of blocks in the largest source file (and its included files) should be free.

The identifiers “etext”, “edata”, and “end” are predefined in the linkage editor and may be used to establish the addresses of the end of executable text, initialized data, and uninitialized data respectively.

This is a standard module header with the type/language byte set to $11 (Program + 6809 Object Code), and the attribute/revision byte set to $81 (Reentrant + 1).

Used by OS-9 to locate where to start execution of the program.

Storage size is the initial default allocation of memory for data, stack, and parameter area. For a full description of memory allocation, see the section entitled “Memory Management” located elsewhere in this manual.

Module name is used by OS-9 to enter the module in the module directory. The module name is followed by the edition byte encoded in cstart. If this situation is not desired it may be overridden by the -E= option in cc.

Any strings preceded by the directive “info” in an assembly code file will be placed here. A major use of this facility is to place in the module the version number and/or a copyright notice. Note that the '#asm' pre-compiler instruction may be used in a C source file to enable the inclusion of this directive in the compiler-generated assembly code file.

The machine code instructions of the program.

Quoted string in the C source are placed here. They are in the null-terminated form expected by the functions in the Standard Library. NOTE: the definition of the C language assumes that strings are in the DATA area and are therefore subject to alteration without making the program non-reentrant. However, in order to avoid the duplication of memory requirements which would be necessary if they were to be in the data area, they are placed in the TEXT (executable) section of the module. Putting the strings in the executable section implies that no attempt should be made by a C programmer to alter string literals. They should be copied out first. The exception that proves the rule is the initialization of an array of type char like this:

               char message[] = "Hello world\n";

The string will be found in the array 'message' in the data area and can be altered.

If a C program contains initializers, the data for the initial values of the variables is placed in this section. The definition of C states that all uninitialized global and static variables have the value zero when the program starts running, so the startup routine of each C program first copies the data from the module into the data area and then clears the rest of the data memory to nulls.

No absolute addresses are known at compile time under OS-9, so where there are pointer values in the initialization data, they must be adjusted at run time so that they reflect the absolute values at that time. The startup routine uses the two data reference tables to locate the values that need alteration and adjusts them by the absolute values of the bases of the executable code and data respectively.

For example, suppose there are the following statements in the program being compiled:

        char *p = "I'm a string!";
        char **q = &p;

These declarations tell the compiler that there is to be a char pointer variable, 'p', whose initial value is the address of the string and a pointer to a char pointer, 'q', whose initial value is the address of 'p'. The variables must be in the DATA section of memory at run time because they are potentially alterable, but absolute addresses are not known until run time, so the values that 'p' and 'q' must have are not known at compile time. The string will be placed by the compiler in the TEXT section and will not be copied out to DATA memory by the startup routine. The initializing data section of the program module will contain entries for 'p' and 'q'. They will have as values the offsets of the string from the base of the TEXT section and the offset of the location of 'p' from the base of the DATA section respectively.

The startup routine will first copy all the entries in the initializing data section into their allotted places in the DATA section. Then it will scan the data-text reference table for the offsets of values that need to have the addresses of the base of the TEXT section added to them. Among these will be the “p” which, after updating, will point to the string which is in the TEXT section. Similarly, after a scan of the data-data references, “q” will point to (contain the absolute of) “p”.

A storage area is allocated by OS-9 when the C program is executed. The layout of this memory is as follows:

                       high addresses
                    |                  |  <- SBRK() adds more
                    |                  |     memory here
                    |                  |
                    !------------------!  <- memend
                    !    parameters    !
                    !------------------!
                    !                  !
Current stack       |      stack       |  <- sp register
reservation   ->    !..................!
                    !        v         !
                    !                  !  <- standard I/O buffers
                    !    free memory   !     allocated here
Current top         !                  !
of data       ->    !........^.........!  <- IBRK() changes this
                    !                  !     memory bound upward
                    ! requested memory !
                    !------------------!  <-- end
                    !  uninitialized   !
                    !      data        !
                    !------------------!  <-- edata
                    !   initialized    !
                    !      data        !
                    !------------------!
             ^      !    direct page   !
           dpsiz    !     variables    !
             v      +------------------+  <-- y,dp registers
                        low addresses

The overall size of this memory area is defined by the “storage size” value stored in the program's module header. This can be overridden to assign the program additional memory if the OS-9 Shell “#” command is used.

The parameter area is where the parameter string from the calling process (typically the OS-9 Shell) is placed by the system. The initializing routine for C programs converts the parameters into null-terminated strings and makes pointers to them available to 'main()' via 'argc' and 'argv'.

The stack area is the currently reserved memory for exclusive use of the stack. As each C function is entered, a routine in the system interface is called to reserve enough stack space for the use of the function with an addition of 64 bytes. The 64 bytes are for the use of user-written assembly code functions and/or the system interface and/or arithmetic routines. A record is kept of the lowest address so far granted for the stack. If the area requested would not bring this lower then the C function is allowed to proceed. If the new lower limit would mean that the stack area would overlap the data area, the program stops with the message:

                **** STACK OVERFLOW ****

on the standard error output. Otherwise, the new lower limit is set, and the C function resumes as before.

The direct page variables area is where variables reside that have been defined with the storage class 'direct' in the C source code or in the 'direct' segment in assembly code source. Notice that the size of this area is always at least one byte (to ensure that no pointer to a variable can have the value NULL or 0) and that it is not necessarily 256 bytes.

The uninitialized data area is where the remainder of the uninitialized program variables reside. These two areas are, in fact, cleared to all zeros by the program entry routine. The initialized data area is where the initialized variables of the program reside. There are two globally defined values which may be referred to: 'edata' and 'end', which are the addresses of one byte higher than the initialized data and one byte higher than the uninitialized data respectively. Note that these are not variables; the values are accessed in C by using the '&' operator as in:

         high = &end;
         low = &edata;

and in assembler:

         leax   end,y
         stx    high,y

The Y register points to the base of the data area and variables are addresses using Y-offset indexed instructions.

When the program starts running, the remaining memory is assigned to the “free” area. A program may call “ibrk()” to request additional working memory (initialized to zeros) from the free memory area. Alternatively, more memory can be dynamically obtained using the “sbrk()” which requests additional memory from the operating system and returns its lower bound. If this fails because OS-9 refuses to grant more memory for any reason “sbrk()” will return -1.

If not instructed otherwise, the linker will automatically allocate 1k bytes more than the total size of the program's variables and strings. This size will normally be adequate to cover the parameter area, stack requirements, and Standard Library file buffers. The allocation size may be altered when using the compiler by using the “-m” option on the command line. The memory requirements may be stated in pages, for example,

       cc prg.c -m=2

which allocates 512 bytes extra, or in kilobytes, for example:

       cc prg.c -m=10k

The linker will ignore the request if the size is less than 256 bytes.

The following rules can serve as a rough guide to estimate how much memory to specify:

A good method for getting a feel for how much memory is needed by your program is to allow the linker to set the memory size to its usually conservative value. Then, if the program runs with a variety of input satisfactorily but memory is limited on the system, try reducing the allocation at the next compilation. If a stack overflow occurs or an “ibrk()” call returns -1, then try increasing the memory next time. You cannot damage the system by getting it wrong, but data may be lost if the program runs out of space at a crucial time. It pays to be in error on the generous side.