CP/M

home *** CD-ROM | disk | FTP | other *** search

/ CP/M / CPM_CDROM.iso / simtel / cpmug / cpmug048.ark / BDS-C.DOC < prev next >

Wrap

Text File | 1984-04-29 | 16.9 KB | 395 lines

********************************************************** * * * The BD Software C Compiler v1.41 10/9/80 * * * * written by: Leor Zolman * * BD Software * * 173 Hampshire st. #2 * * Cambridge, Mass. 02139 * * (617) 492-3038 evenings * * * ********************************************************** This flier represents most of the BDS C Handbook that comes with each copy of the compiler (in addition to the User's Guide). The BDS C package is available only from: Lifeboat Associates Price: $145 on 8" CP/M disks; 1651 Third Ave. Contact Lifeboat for the New York, NY 10028 prices on other formats. (212) 860-0300 There is NO restriction on use of COM files generated by the BDS C Compiler; Users are free to place such items on the market without paying any royalty for use of run-time routines provided with the compiler package. The main components of the BDS C package are: four executable COM files (CC1.COM, CC2.COM, CLINK.COM and CLIB.COM), two standard library files (DEFF.CRL and DEFF2.CRL), and a run-time package module (C.CCC). For customization purposes, sources are provided for C.CCC (CCC.ASM) and all library functions written in assembler (DEFF2.ASM and DEFF2A.ASM). There are also various sample source programs and utility packages included. A description of each follows: CC1: The first phase of the compiler: accepts a C source file with any filename and extension (say, "foo.c") and produces a temporary file containing a symbol table and an encoded form of the source code. By default, CC1 leaves the temporary file in ram and attempts to load in the next phase of the compiler (CC2) from the currently logged in disk (unless errors occur); see the"-a" option below for control details. The file extension".C" is NOT assumed for the source file name, so saying"foo" when you mean "foo.c" would not work. If the source file name is preceded by a disk designation, then the input is taken from the specified disk, and the output (if no errors) is written to that disk. Following the name of the source file on the command line, you may specify a list of options, each"optionally" preceded by a dash. The recognized options are: -o causes speed-optimization to be performed instead of space-optimization. I.e., causes the final generated code to be longer but faster. Will ONLY work if CC2 is auto-loaded by CC1. -p causes the result of the preprocessor phase of compilation (i.e., the result of #define and #include text substitutions) to be written to the CP/M console output, with lines numbers generated. If you type a control-P before hitting return on the command line, output will also go to the list device. -e xxxx Specifies an explicit, absolute address for the external data area, letting the compiler generate direct loads and stores (using"lhld" and "shld") for external variables. Will ONLY work if CC2 is auto-loaded by CC1. -m xxxx Specifies the starting address of C.CCC package at run-time. Normally (under CP/M) this defaults to the base of the TPA; use -m when generating code for a customized environment. See the"CRL Format" section of the User's Guide for details on customization. Will ONLY work if CC2 is auto-loaded by CC1. -r n Reserves nK bytes for the symbol table. Default value for n is 8 (6 for 4200h-based versions.) Minimum symbol table size is 5K. -a x Causes CC2.COM to be auto-loaded from disk x, where x may be "a", "b", "c", etc...or "z" to force a .CCI file to be written to disk (under control of the "-d" option below.) You'd use this option when the disk on which your BDS C commands reside is NOT the currently logged disk; In the absence of this option, CC1 will auto- load CC2 from the currently logged disk. -d x Specifies to which disk the .CRL file output of the compiler is to be written. The default is the disk from which the source was taken. Again, x can be"a", "b", "c", etc. If auto-loading of CC2 is not performed (i.e., if the"-a z" option is used), then this option controls which disk the .CCI file output is to be written to. -c Disables the comment-nesting feature; When this is used, then the first"*/" after any "/*" is encountered closes the comment. If"-c" is NOT used, then each occurence of "/*" requires a matching "*/" before a comment is considered terminated. On a 2 MHz 8080, processing speed (not counting disk waiting) is about 15 lines of source/second. On a 4 MHz Z80, speed is about 35 lines/sec. CC2: This is the second phase of the compiler. CC2 accepts a".CCI" file as input, and writes out a".CRL" file if no errors are detected. (CRL is mnemonic for 'C ReLocatable'.) Normally CC2.COM is automatically loaded in (by CC1) and operates on the CCI file left in memory by CC1; If invoked explicitly, then the .CCI file is loaded from disk. If all goes well, writing out of the CRL file is followed by deletion of the"CCI" file (if it exits), and compilation is complete. On an 8080, execution speed = about 35 lines/sec. On a 4 MHz Z80, speed is about 90 lines/sec. CLINK: This program links a"main" function from a given CRL file in with C.CCC (for common system subroutines) and any subordinate functions which "main" may require (from perhaps many CRL files). Alternately, CLINK may be used to prepare a code segment which can be swapped in at run time by the root module. A successful linkage causes a".COM" file to be generated, at which point the 8080 absolute machine code file is ready to be executed (for better or worse) as a transient command by CP/M (or swapped in by another COM file.) The first argument on the command line must be the name of a CRL file containing a"main" function; it may be preceded by a disk designation, to state where all .CRL files (except DEFF*.CRL) are to be searched for if further disk designators are omitted. Any other CRL files to search may also be specified on the command line (WITHOUT their".CRL" extensions), causing them to be searched in the order specified. The default disk to search will be the same disk from which the original CRL file was taken; this default can be overridden by specifying an explicit disk designation for any appropriate CRL file name needing it. For example, A>clink c:foo bar a:zot fraz causes disk C to be searched for the files FOO.CRL, BAR.CRL and FRAZ.CRL, and disk A to be searched to find ZOT.CRL. Note that C.CCC, DEFF.CRL and DEFF2.CRL are expected to reside on the currently-logged disk, unless the -c option is used (see below.) After all given CRL files have been searched once, CLINK will automatically search DEFF.CRL and then DEFF2.CRL. If there are still some unresolved references, then CLINK will ask for input from the keyboard to try resolving them. This situation is likely to arise in the case where a function becomes "needed" AFTER the CRL file containing it has already been searched. When yanking functions out of a CRL file, CLINK will only take those which are already known to be needed (due to a prior reference.) Thus, it will save you some pain to order the CRL filenames on the command line in such a way as to minimize undefined backward references. This ONLY applies to multiple CRL files; the order of functions within a single CRL file makes no difference. There are several options which may be specified on the CLINK command line. Each option must be preceded by a dash (-); the space between options and their argument (if needed) is optional. The presently supported options are: -s Prints out load statistics. -d ["args"] Use this to run the code immediately after linking, for debugging purposes, instead of writing a COM file out to disk. If a quoted string is given, then that string is treated as a list of command line arguments and is passed to the executing program as if via the CCP. -t nnnn Reserves location nnnn (hex) and above for user; default is to reserve no space. What this really does is to cause the first op in the object file to become lxi sp,nnnn instead of the usual lhld BASE+6 sphl -o name Causes the .COM file generated to (or) -o name. be called"name.COM", "name" or (or) -o name.ext"name.ext" respectively. If omitted, the name of the "main" .CRL file is used by default, with the extension".COM". The name may also have a disk designator to direct the output to any disk (in lieu of the special extension code on the"main" CRL filename). If a disk designator ALONE is given (e.g.,"-o b:") then the output is directed to the specified disk without affecting the filename. -e xxxx Sets start of data area to address xxxx, to maintain consistency between several separate .COM files when chaining (via the library function "exec") is used and external data need to be shared. If the program will be swapping in segments, then the value given MUST BE GREATER THAN THE HIGHEST ADDRESS THAT WILL EVER BE OCCUPIED BY SWAPPED-IN CODE. Note that the "Stack space" statistic, printed upon completion of linkage if "-s" is given, may be incorrect when this option is used. -c x Tells CLINK to obtain the files C.CCC, DEFF.CRL and DEFF2.CRL from disk "x". By default, these files are assumed to reside on the currently logged disk. -y name Yanks in the symbol table file"name.SYM" from disk, and defines all the symbols found therein. This is used when linking an overlay segment, to pre-define the function addresses resident in the root node and accessible by the segment. See the -w option below. -w Causes a SID-compatible symbol table file to be written to disk for use either by SID or by CLINK later on when linking overlay segments (see the -y option above.) -v Specifies that the resultant COM file is to be swapped in as an overlay segment by another command at run time, so the run-time package (C.CCC) is not linked into the code. The"-l" (letter ell) option should always be used with"-v". Note that this option replaces the awkward"foo.aaS" scheme of previous versions. -l xxxx (letter ell) Sets the starting (load) address of the generated code. Normally, this defaults to the base of the TPA; If used with the"-v" option, this generates an overlay segment to load in at address xxxx. If the"-v" option is not given, then the run-time package (C.CCC) must have been previously re-assembled to run at location xxxx (since the run-time package always resides at the base of the root segment.) For detailed info on generating code to run at an arbitrary starting address and/or to be ROMable, see the"CRL Format" section of the User's Guide. -r xxxx Reserve xxxx bytes (in HEX) for the internal CLINK forward function reference table. This table's not being big enough (and my faulty tests for table overflow) were responsible for CLINK's previous tendency to crash on big linkages. While CLINK won't crash anymore, it may give you a"Ref table overflow" message and quit; if this happens, use this option with an argument larger than the 600h default for regular CP/M, or the 400h default for 4200h-based CP/M systems, to enlarge the table area. Of course, this reduces the space available for linked code...if CLINK gives you an"Out of memory" message, use the "-r" option to reduce the reserved table space and provide more code space. Chances are, though, that you won't be able to reduce the table space by much before running out of it. Time for overlays... CLIB: This program maintains .CRL files, allows transfer of functions from one CRL file to another, etc. To invoke CLIB, just type A>clib CLIB will print a line such as Function buffer size = nnnnn specifying the largest function size that can be handled. Attempting to"transfer" or "extract" a function larger than this size could be destructive. Next CLIB will prompt with a "*". Typing "h" at this point will give you a command summary. Basically, you work CLIB by opening one to six CRL files (which then become associated with"file numbers"), diddling the files to your hearts content, closing all files which you altered, and typing control-C. The old version of any CRL file you change with CLIB is renamed to name.BRL (for Backup ReLative). A sample session of CLIB to, say, transfer the functions named"FOO", "BAR", and "ZOT" from a CRL file named "DSSR" on disk B: to one named "RTS" on disk A: would go as follows: A>clib BD Sofware C Librarian v1.4 Function buffer size = xxxxx bytes * open 0 b:dssr * open 1 rts * t 0 1 foo * t 0 1 bar * t 0 1 zot * c 1 * ^C A> ... The"open" commands prepare to do work on a .CRL file, and associate each .CRL file opened with a digit (0-9). The"transfer" commands tell CLIB to transfer the named function from the first file (named by file #) to the second file (also named by number). The "close" command need only be given for files which have been altered; since DSSR wasn't written to in the above example, it didn't need to be closed, but RTS did need to be closed. DEFF.CRL: Contains all compiled functions from STDLIB1.C and STDLIB2.C. See the BDS C User's Guide, STDLIB1.C and STDLIB2.C for documentation on these functions. DEFF2.CRL: Contains all library functions coded in assembly language; the sources to all of these functions (except"fp") are in DEFF2.ASM and DEFF2A.ASM. C.CCC: The run-time package, containing code for processing the command line (generating argc and argv, for you Unix [1] lovers), room for file I/O buffers, some math subroutines, etc. This run-time package is always linked in at the beginning of root segment COM files generated by CLINK. The source to C.CCC is CCC.ASM. OTHER THINGS YOU GET WITH THE PACKAGE: STDLIB1.C Source for library functions which are written in C and present, in compiled form, within DEFF.CRL. STDLIB2.C More DEFF.CRL library function sources. OTHELLO.C Game program. Serves as a good example of modular coding, passing arrays as arguments to functions, and the "qsort" library function. RALLY.C Arcade game, for H19 terminal only (uses files RALLY.MAP and R2.MAP). PPONG.C Polish Pong, for the H19. Very interesting little hack. TELNET.C Program to let a system be used as a terminal, optionally routing stuff from modem to disk and vice- versa. Nice hanshaking and check- summing features. Hairy but useful. CONVERT.C Converts unprintable characters (for systems having upper-case only and/or incomplete special symbol set) into special 2-character sequences beginning with the character '#'. See also CC0T.C CC0T.C Converts C source files containing the special sequences generated by the CONVERT program back into a form that can be compiled. FLOAT.DOC, Bob Mathias's contributed floating FLOAT.C point package (uses the"fp" function which resides in DEFF2.CRL.) FLOATSUM.C Sample program using the floating point package. CMAC.LIB, Macro package for use with Digital Research's"mac" macro assembler to create CRL files painlessly from assembly programs. CCC.ASM Source to the C.CCC run-time package. DEFF2.ASM Source to the machine-language library functions. Uses the CMAC.LIB macro package, requiring Digital Research's MAC for assembly. DEFF2A.ASM More of the above BDS.LIB Global header file for FNS.ASM.