Digital C

Digital C for the Sinclair QL was developed from Small C version 2.1 and sold by Digital Precision in two versions, the standard version and the Special Edition (DCSE). The source code of DCSE is now being made publicly available for anybody to use as they wish. It is not covered by any formal licence but any copyright notices must be retained.

There are three files to download from Dilwyn Jones web-site

• digic.zip - the last release of DCSE from DP
• spcmanual_zip.dat - the manual for DCSE
• dcsource.zip - the source code for DCSE, which also includes this document readme.html

DCSE is fully described in the manual and further information is given in the Quill document updates_doc in the DCSE distribution. The rest of this document describes the contents of the source code download.

This document is being written in 2009, some 20 years after DCSE was developed and there is some discrepancy over version numbers of the parser:

• notes with the source code indicate that the last version given to DP was 2.05
• the same notes give version 2.062 as the latest version and this was never issued to DP
• the last version issued by DP was 2.07

The discrepancy does not appear to be significant, my opinion is that DP altered the version number in the executable file for some unknown reason. This public release of the parser source code has been given a version number of 3.0; the other software components have similarly been raised a level.

The download contains the source code for several programs and some DCSE system files that are necessary to compile the programs:

• the parser
• the code generator/linker
• the library generator
• the libraries
• an intermediate code disassembler
• DCSE system files

The first three are fully described in the manual and updates_doc. There are brief notes on the others below. The parser

The files associated with the parser are (these are all prefixed with the QDOS directory name parser_):

• cc_mod - the history of modifications to DCSE
• ccdef_h - the header file
• cc1_c, cc2_c, cc3_c and cc4_c - the parser source code files
• stdiocc_h - a slightly different version of the usual stdio_h (the reason for use of this file rather than stdio_h is unknown)
• cc_bas - a SuperBasic program that compiles the parser

The parser was developed from version 2.1 of Small-C and hence lacks some of the features of Small-C version 2.2 such as the conditional ? : operator. One big difference is that Small-C 2.2 contains a significant amount of intermediate code optimisation.

The files associated with this are (except for ops_obj, prefixed with the QDOS directory name codegen_):

• cgdef_h - definitions for the code generator/linker (also used by the Library Generator and Disassembler)
• cg_c - variable declarations
• cg1_c - main() plus general functions
• st_c - symbol table functions
• gen_c - generates machine code
• ops_asm - an assembler source file listing intermediate instructions and their values
• ops_obj - the result from assembling ops_asm (also used by the library generator and disassembler)
• cg_bas - a SuperBasic program that compiles the code generator/linker

Small-C generated assembler code whereas the DCSE parser generates a byte oriented intermediate code. The code generator converts this intermediate code directly into 68008 machine code without the need for an assembler. This code generation is fairly rudimentary but some optimisation is carried out as the machine code is generated (see file gen_c). This optimisation is generally on pairs of instructions or values of constants. It was originally intended to develop a more extensive optimiser that would optimise longer sequences of instructions; this would be either as a separate component running between the parser and code generator or as part of the code generator. This could be a useful project if anyone is interested in implementing this. Small-C 2.2 gives examples of the types of optimisation that are possible.

The files associated this are (prefixed with the QDOS directory name libgen_):

• lg_c - the complete source code
• lg_bas - a SuperBasic program that compiles the library generator

(Note that this also uses cgdef_h and ops_obj included with the code generator)

The library generator combines object code modules into a format such that only those library functions that are required by the final executable are actually included in that executable. Library modules written in assembler have to produce code in the same format - more information on this is given in the file called updates_doc included in the Digital C distribution digic.zip.

The library source code files are (prefixed with the QDOS directory name library_):

• csyslib_c - some system functions
• stdl_c - standard C library functions written in C
• stdmcl_asm - standard C library functions written in assembler
• mcl_asm - assembler code and functions that are assembled into mc_obj which is always included in executables
• qdos_def - definitions for calling QDOS routines
• qdosl_asm - QDOS library functions written in assembler
• fpl_asm - floating point library functions

All files are assembled or compiled into _obj modules and, with the exception of file mcl_asm, are combined into file std_lib by the library generator. The file mcl_asm was the source file for mc_obj. The HiSoft assembler was used to assemble the _asm files, they will probably need to be reworked for other QL assemblers.

Disassembler files are (prefixed with the QDOS directory name disass_):

• dis_c - the source code
• dis_bas - a SuperBasic program that compiles the disassembler

To use the disassembler you will need to compile an executable file as it is not included in digic.zip.

(Note that this also uses ccdef_h and ops_obj included with the code generator)

The Disassembler is a compiler development tool that was never released as part of DCSE, therefore it is not as 'polished' or tested as the other programs. It takes an _obj file as input and generates a file of mnemonics for the intermediate code instructions. This may then be visually inspected for correctness.

The command line for the disassembler contains a list of object files to be disassembled. Output is to stdout and can be redirected to a file (see the DCSE manual for how to handle command lines). The device containing the files must be specified e.g. win1_filename_obj, the _obj extension may be ignored. There are no command line switches, any that are input are ignored. Assuming Toolkit 2 is present examples of SuperBasic commands to run the disassembler are:

EXEC win3_disass_dis

and then type the command line when the disassembler requests it

EXEC win3_disass_dis;'win3_parser_cc1_obj >win3_parser_cc1_int'

EXEC win3_dis;'win3_parser_cc1 win3_parser_cc2 >win3_parser_cc_int'

(here the _obj extension is omitted)

To compile the above programs using the supplied SuperBasic programs the following files, which are taken from the digic.zip download, are also included: mc_obj, std_lib and stdio_h.

The parser, code generator/linker, library generator and disassembler have all been compiled using the last Digital C release prior to releasing the source code into the public domain. This was done using the QL2K emulator running under Windows XP (QLAY2 was tried but failed to work properly due to the display freezing). Of these all four recompiled programs all but the library manager were tested and proved to work. The recompiled library manager was not tested (but there are unlikely to be any problems with it) as there are no existing copies of the original object files of the assembler libraries. These libraries were assembled using the HiSoft assembler which is no longer available to the author. To regenerate the _obj files the source files can be assembled using another assembler but will probably need to be modified due to syntax differences.

As indicated in the list of files for each program, there is an associated SuperBasic program that may be LRUN to compile the program. These assume that:

• Digital C executables from digic.zip are in WIN2_ and that the source code files listed above are in WIN3_. To change devices to suit your system, you only need to edit the device names in the SuperBasic programs - the Digital C source files do not need to be changed.
• That Toolkit 2 is installed on your QL.

The author of Digital C has no firm plans to develop it further and would be delighted if someone wished to do so, even making it an open source project. Suggested improvements could be small scale addition of functionality, e.g. the ? : operator, to more significant additions such as proper incorporation of floating point. As mentioned above, a useful addition would be a code optimiser. The author is willing to answer questions and offer advice but not to undertake significant code development.

Title: Digital C SE
Language: Compiled C
Author: Gerry Jackson
Publisher: Digital Precision Ltd
Year of Publication: Unknown
Platforms Suitable for: All Sinclair QLs and Compatibles
Commercial Status: Now freeware
Price: £unknown
Reviews: Unknown
Sources Available from: Sinclair QL Homepage
Latest Version available from: Sinclair QL Homepage