-

UTILITIES PUBLIC DOCUMENT CC

From HI-TECH C for CP/M Fan WIKI(EN)
Jump to: navigation, search

CC - improved control program for HiTech-C and msx-dos2

About

The program cc.com executes the passes to compile a C-program with HiTech-C automatically. The c.com from Hi-Tech does the same, but cc.com has the following advantages:

  • cc.com does not use a batchfile and stops if a pass has failed
  • cc.com sets the append-variable so that your source can be in a different directory than the compiler.

How to install

First you need to install MSX-DOS2. Then get the HI-TECH Z80 CP/M C Compiler from ftp://ftp.funet.fi/pub/msx/programming/c/hitech-?.pma and unpack with pmext. HiTech has been so kind to grant permission to use their C-compiler free of charge, see also http://www.htsoft.com/products/CPM.php .

Unpack cc.lzh to the directory that contains the C-compiler.

You should get the following files:

cc.com
replacement for c.com
libdos2.lib
IO-library using msx-dos2, source is in libdos.lzh
vsh1.o,vsh2.o,vsh3.o
variants of crt.o for programs executing other programssee vsh.txt for details
vsh.txt
text about vsh?.o
redir.obj
used in a work-around for -U bug in link.com
cc.txt
this text
cc.c
source for cc.com
vshrt.as
source for vsh?.o
redir.as
source for redir.obj
makefile
pack.bat

Using cc

You can invoke CC with:

cc <options> <files>

The following options are recognised:

-C  
keep the object file; do not link
-CR[file]  
produce cross refenerence file
-O  
optimise assembly code generated by CGEN with OPTIM
-O<file>  
put output in <file>
-I<dir>  
passed to CPP as extra search-path for include files, only works for drives, the directory where cc.com is stored is always searched via APPEND environment variable
-V  
verbose mode, print out commands of subprocesses
-F<file>  
write symbol file
-U<sym>  
undefine symbol for CPP
-D<sym>[=<def>]
define symbol for CPP
-S  
keep assembly file; do not assemble or link
-X  
strip local symbols, also passed to LINK
-P<pspec>  
define order of psect (not normally needed)
-M<file>  
write map file
-W<n>  
width for map file
-l<xx>  
pass lib<xx>.lib to LINK, order is important

All options are case insensitive.

Files

Files with no extension get the extension ".c". Files with extension ".c" are treated as C language sourcefiles. Files with extension ".as" are treated as assembly assembly language source files. All other files are passed directly to the linker.

Environment item

VSHTOP
If set, VSHTOP specifies the first page of video memory that will not be used or probed by CC. Pages 0..7 are ordinary video memory, pages 8..11 are the extended video memory. Legal values are 2..12, default is 12. Other values are silently ignored. If VSHTOP is 2, CC will not work. You can use this to protect data in higher pages. Some emulators may need vshtop=8.

Notes

CC.COM uses video memory for temporary storage, so it will corrupt the contents of a ramdisk that also uses video memory. The screen will flash between the compilation steps, this is to improve reliability of reading/writing from/to video memory and should not be cause for concern.

HiTech-C cannot handle large C-files. This is not a real problem; just split your program in to C-files of about 6 or 7 kB. The MAKE program by Arnold metselaar can be used with CC.com to compile only those modules that need to be recompiled.

See also:

  • The documantation that comes with HiTech-C
  • Documentation about the C language in general
  • vsh.txt

Authors

CC.C is based on work by HiTech and Pierre Gielen. Arnold Metselaar added the code to execute a subprogram and then continue the main program.



[1]

VSH - use video memory as stack for executing sub-programs

About VSH

The file vshrt.as contains code to start a sub-program and continue the original program afterwards. It is assembled to 3 variants vshN.o, with N in {1,2,3}. These object files are intended to be used in stead of the standard crt.o, use CCs -N option to suppress linking of crt.o, and mention vsh[123].o as the first file on the command line.

Note that vshN.o sets the highest address that can be used by the program to N*0x4000, make sure this is large enough for your program; no checks are done during linking or startup.

Another program can be called from the C-program with the function:

int _mspawn(char * subprogram, char * args)

Where subprogram is the full name of the program file, which should normally end in ".COM". This program will arrange for the state of the calling program to be stored in the N highest available block of video memory, where extended memory is considered higher than normal memory. The file named subprogram will be executed as if it were run from the command prompt with arguments args. When the subprogram finishes, the state of the calling program is restored and _mspawn returns the exit code from subprogram. The exit code can be given with the DOS2 function _TERM (0x62), or by storing at address 0x80. The value at 0x80 is only used if it has been changed by the subprogram and DOS2 reports a zero exit code. If starting the subprogram fails, _spawn will return -1, and errno will be set.

Note that _spawn changes the environment variables PROGRAM and PARAMETERS, you may want to store them before calling _spawn().

Care should be taken when running large subprograms as they may be loaded only partially.

How things work

Before doing anything else a program linked with vshN.o uses the DOS2 mapper support routines to complete a piece of code to restore the settings in the slotselect and mapper registers, for which the stack must be in page 3, then it sets the stackpointer to N*0x4000.

When _spawn is called it first searches the file subprogram and its full path is stored in the environment variable PROGRAM and args is copied to 0x81 and the environment variable PARAMETERS. Next it checks whether the launch/restore code is already installed at the top of the TPA and installs it, if it is not. This allows nesting of _spawn()s. The launch/restore code costs 256 bytes of TPA. When the launch/restore code is installed vsh looks at the environment item VSHTOP, If set, VSHTOP specifies the first page of video memory that will not be used or probed by VSH. Pages 0..7 are ordinary video memory, pages 8..11 are the extended video memory. Legal values are 2..12, default is 12. Other values are silently ignored. You can use this to protect data in higher pages. Emulators need vshtop=8 at present.

Finally _spawn forks a subprocess and opens the file subprogram. It calls the launch-code with the file handle the number of pages to store and a pointer to 'stage-2' of the restore code. The launch code checks whether there is enough space left and updates an internal 'pointer' to the lowest video memory page in use. It stores 256 bytes of 'stage-2' restore code followed by the contents of the area 100h--(#pages*4000h)-1 into the video memory. Finally it reads the program into memory and passes control to it.

The warm boot entry is deflected to 'stage 1' of the restore code at the top of the TPA. Stage-1 copies 256 bytes from video memory to the area just below itself and then passes control to the 'stage-2' just read from video memory. Stage-2 restores the mapper and slotselect settings saved at the start of the program and and continues with copying the video memory to the start of the TPA. Finally the parent process is joined and _spawn() returns the exit code of the subprogram as described above.

Screen display is turned off during transfers between normal and video memory, to enhance reliability. The flickering this produces should not be cause for alarm.

  1. VSH.TXT