Trailing-Edge
-
PDP-10 Archives
-
SRI_NIC_PERM_FS_1_19910112
-
c/kcc/port.doc
There are 7 other files named port.doc in the archive. Click here to see a list.
INSTALLING AND PORTING KCC
This file tries to document various things about porting KCC to other
systems; including how to bring up new versions on systems which already have
KCC.
A "port" involves two major things: the KCC compiler itself, and
the C library (LIBC). They are interdependent, and since the compiler is used
to compile itself, things have to be done carefully.
KCC supports all CPUs: KA, KI, KS, KL, KX. System is irrelevant.
LIBC supports only TOPS-20. There is partial (but not complete)
support for TOPS-10, WAITS, and ITS.
The usual situations are these:
(1) Installing KCC and the library for the first time.
(2) Installing a new version of the C library or KCC.
(3) Using KCC as a cross-compiler for another CPU or system.
(4) Porting KCC and the library to a different CPU or system.
Other references:
For (1) see the distribution INSTAL.DOC file.
The KCC USER.DOC section about cross-compiling.
The C library file LIBC.DOC.
Building and installing a compatible new version of KCC/LIBC for your current
system:
If the new version has exactly the same site-dependent parameters
(C-ENV.H and CCSITE.H) then you can simply install the new binary, without
bothering to recompile from the sources.
If your site-dependent parameters are different from that of the
distributed KCC then you will need to recompile from the sources. To do
this,
1. Make sure that the C-ENV.H in the KCC source directory is correct
(or, if it doesn't exist, that the version in the include directory
is correct). Ditto your CCSITE.H or whatever is different.
2. On TOPS-20, simply invoke CC.MIC, as in "DO CC". Or do it by hand.
Then install the resulting NCC.EXE on your system as "CC".
NOTE: if the new version of KCC makes some changes in its runtime
assumptions, you may need to change some other things. The most that may be
required is to follow the cross-compilation procedure as if porting to a new
system. If you know what is going on, you may be able to get by with less
than a full new installation.
Using KCC as a cross-compiler:
This assumes you want to set things up on your source system so
that you can compile programs into binaries which can then be moved to
a target system and executed there. This can sometimes be useful if the
target system is not really able to run KCC itself for whatever reason.
Also, we assume that the source system is a TOPS-20, since KCC is fully
supported for that system and the existence of logical names makes things
easier.
[1] Set up a new directory to serve as the standard include (and library)
directory for the target system's files. For the sake of the following
discussion, call this directory NC:.
[2] Install in NC: an appropriately editted copy of C-ENV.H.
In particular, CPU_xxx and SYS_xxx must be set properly.
[3] Build a program called, for example, XCC which passes its arguments on
to an invoked CC with the addition of appropriate switches.
See the program TCC.C in the KCC source directory for a sample;
this program runs on TOPS-20 and compiles code for TENEX.
The following switches should be set:
-L to specify the library directory path (NC:)
-H to specify the standard include file directory path (NC:)
-x to specify the target CPU, system, and assembler
And others such as -A if necessary.
[4] Use XCC to recompile and rebuild the entire C library. Install the
new LIBC.REL in NC:.
[5] That's it. KCC does not need to be rebuilt, since XCC will simply
invoke KCC with the appropriate switches set. Whenever making
a program to run on the target machine, just use XCC.
KCC/LIBC Cross-compilation (using logical names):
These are the complete steps to follow when building a new KCC and
LIBC for another CPU or system. You may be able to get by with doing less,
if you know what is going on and what the changes are. You may have to
do more, if the new CPU or system is not fully supported.
This procedure for cross-compiling KCC/LIBC for a different CPU/system
relies on TOPS-20 logical names, and assumes that the logical name C: is used
by the source machine's KCC to refer to both the standard include directory
and the library directory. If some other logical name is used, substitute
that for C: in the following discussion.
[0] Redefine C: to be a search path pointing FIRST to a "new" standard
directory, and SECOND to KCC's standard directory (normally
this is the system-wide logical name C:).
This requires the user to:
@define C: <new-dir>, C:
[1] Edit C:C-ENV.H for new configuration; write out to C: (new dir).
In particular make sure that the SYS_xxx and CPU_xxx defaults are set.
Make sure that any local copies of C-ENV.H (in the KCC or LIBC
source directories) are identical.
The same applies to any other .H files that need to be changed; new
versions should be put in C: (new dir) and local copies made identical
or flushed.
[2] Connect to the LIBC source directory.
Delete all .REL files (@DEL *.REL,<.*>*.REL)
[3] Rebuild entire library with the LIBC.MIC file (@DO LIBC).
Edit LIBC.MIC beforehand to add any -x= switches that are necessary,
for example -x=ki, -x=klx. These switches should match with
the definitions in C-ENV.H!!!
[4] Install new LIBC.REL into C: (@COPY LIBC.REL.0 C:*.*.*)
[5] Also install the new LIBCKX.REL file into C:. This is necessary in
order to allow loading of extended-addressing programs. If your
machine does not support extended addressing, of course, you can
ignore this file.
--- At this point the new library is ready! ---
[6] Build a new KCC:
Connect to the KCC source directory.
Make sure that the site-dependent defaults in CCSITE.H are okay.
Other parameters can be changed in CCPARM.H if necessary.
Make sure that the local copy of C-ENV.H is either flushed or
is the same as the version in the new C:.
[7] Delete all the old .REL files (@DEL *.REL).
[8] Compile and load all the C modules with the CC.MIC file (@DO CC).
Edit CC.MIC beforehand to add any -x= switches that are necessary,
for example -x=ki, -x=klx.
This will automatically load up some library routines from the new
LIBC. You now have a binary KCC for the target system.
[9] To install on your own system:
you can replace the old C: by new C: in either of two ways:
A. (quick) Copy all new C: files over to old C:
Then undefine your job-wide C:.
B. (cautious) Copy all remaining files from old C: to new C:.
Test it out. If no problems, then revise the system-wide
logical name. If problems, swap the names back.
[10] To install on another system:
On target system, set up the include directory.
Copy all files from new C: to target (.H files plus LIBC.REL),
then all remaining files from old C: to target.
Copy the new CC binary to whereever the target's system progs live.
If desired, copy the LIBC and KCC sources too.
Cross-compilation without logical names:
This is a little harder because the source and target directories have
to be more explicitly specified. In the following discussion, the strings OLD
and NEW are assumed to represent the paths for the old (existing) standard
directory, and the new directory where the new .H files and library will be
written and stored.
[1] Edit C-ENV.H for new configuration; write out to NEW.
In particular make sure that the SYS_xxx and CPU_xxx defaults are set.
Make sure that any local copies of C-ENV.H (in the KCC or LIBC
source directories) are identical.
The same applies to any other .H files that need to be changed; new
versions should be put in NEW (new dir) and local copies made identical
or flushed.
[2] Connect to the LIBC source directory.
Delete all .REL files.
[3] Rebuild entire library. The LIBC.MIC file shows which files need
to be compiled and loaded into a library.
All compilations should be of this form:
CC -c -LNEWLIB -INEW -IOLD -x=ki module.C
Where:
"-x=ki" illustrates how a specific CPU must be selected.
"module" is the library module being compiled.
"NEWLIB" is the path for library modules in NEW, e.g. -LC:LIB=.REL
The need to specify this is an unfortunate artifact of
the way library load requests are inserted into the code.
[4] Build all the .REL files together into a library; the first two
files must be CPU.REL and CRT.REL. Move this file into the NEW
directory.
--- Now start building the new KCC ---
[5] Build a new KCC:
Connect to the KCC source directory.
Make sure that the site-dependent defaults in CCSITE.H are okay.
In particular make sure that LIBPREFIX and LIBPOSTFIX match
what was given in the -LNEWLIB switch while compiling LIBC.
Other parameters can be changed in CCPARM.H if necessary.
Make sure that the local copy of C-ENV.H is either flushed or
is the same as the version in NEW.
[6] Delete all the old .REL files.
[7] Compile and load all the C modules specified by the CC.MIC file.
Use the same form as for compiling the LIBC modules, including
the -L, -I, -x, and -A switches.
You will then have a binary KCC suitable for the target system.
[8] To install on your own system:
you can replace OLD by NEW in either of two ways:
A. (quick) Copy all NEW files over to OLD. Install the KCC binary.
B. (cautious) Copy all remaining files from OLD to NEW.
Test it out. If OK, install the KCC binary.
[9] To install on another system:
On target system, set up the include directory.
Copy all files from NEW to target (.H files plus LIBC.REL),
then all remaining files from OLD to target.
Copy the new CC binary to whereever the target's system progs live.
If desired, copy the LIBC and KCC sources too.
Thoughts on future port to ITS:
The main problem is that the only linking loader available on
ITS is STINK, which only understands STINK format REL files. There
may be an old version of the DEC linker available, but this is
non-supported and painful to use. Getting KCC to run on ITS is not
difficult; establishing a scheme for the C compilation environment (so
users can compile their C programs on ITS) is what needs to be figured
out.
Here is a map of the players. "..." marks links that don't currently
exist but could.
/.......................>|
| |
|-> MAC --[MACRO]------->|--> DECREL --[T20LINK]------> DECSAV
| /---->| | /..................|
C --[KCC]-->| | /->| | |
|-> FAI --[FAIL]-->| | | \...[CNV]...>|
| \---->| \.......[ITSLNK]...>|
| | | |
|-> MID --[MIDAS]-----|->|--> STKREL --[STINK]---->|--> SBLK
| |
\...........................> newREL ..[newLNK]...>|
As the diagram shows, both FAIL and MIDAS can produce either DECREL or
STKREL format. (The ITS version of FAIL uses a separate module called
STKTRN to achieve the latter).
NOTE! If KCC is ever improved to bypass the assembler phase by
outputting relocatable files directly, it will almost certainly NOT know
about STKREL format. Using this on ITS will require either further
modifications to generate STINK format, or the ITS loader will have to
know about DECREL format. The latter is most general.
Two handy programs that could be created would be:
CNV (or whatever) to convert DEC format SAVE files into ITS SBLK files.
ITSLNK (or whatever) to gobble relocatable files in DECREL (or some
other, better, format) and produce ITS SBLK files.
Actual porting:
Several different approaches can be used:
[1] Build C program elsewhere (T20), dump in old DECSAV format.
FTP over and convert to SBLK executable format. Needs CNV program.
[2] Generate complete set of .FAI files and FTP them.
Run ITS FAIL to generate STINK format rels, then load with STINK.
[3] Generate complete set of .MID files and FTP them.
Run ITS MIDAS to generate STINK format rels, then load with STINK.
[4] Generate complete set of .REL files and FTP them.
Modify STINK (NEWLNK) to understand DECREL format, use that.
Fixing KCC to produce valid MIDAS output will require:
(1) Fixing KCC to produce common assembler subset. Should be OK now.
(2) Modifying the syntax of all library assembler runtimes.
Now that #asm and asm() exist, this can be fixed up by hand as needed.
Further comments:
Library routines required by KCC:
(this list can be generated by loading all .REL modules and then
giving the /UNDEF switch to LINK)
$$$CPU 0
$$$CRT 0 ; * C Runtime stuff, in CRT.C
$BPCNT 413166
$BYTE 517604
$DFIX 437543
$NSPOP 472623
$NSPUS 472615
$START 403165
$SUBBP 413303
$ZERO 463273
Sys-dependent routines
CLOCK ; * CC for runtime reporting
CTIME, TIME ; * CCPP for __DATE__, __TIME__
EXIT ; *
FORKEX ; T20,10X,T10,CSI - CCASMB for asm/link invoke
STAT ; * CC for checking last time assembled
GETPID ; * CCASMB for temp files
JSYS ; T20 CCASMB for PRARG%
OPEN, READ, CLOSE, FSTAT ; * CCASMB for _KCCsymfind()
STRERR ; * CCERR for sys error messages
UNLINK ; * CC to flush asm files
STDIO ; * STDIO stuff. Should not be sys-dep
.SIOS 0
FCLOSE 517443
FFLUSH 517666
FGETC 517212
FOPEN 517417
FPRINT 516663
FPUTC 515464
FPUTS 517440
FWRITE 516627
SPRINT 517407
UNGETC 412045
Stg alloc ; * Depends on S/BRK, all sys supported.
FREE 442156
MALLOC 517154
REALLO 517235
STRING ; * (no sys-dep stuff)
STRCAT 414767
STRCMP 417712
STRCPY 517371
STRLEN 517335
Misc library
QSORT 457226 ; * (no sys-dep stuff)
New listing (built during T10 port) of system calls or OS-dependent
functions that KCC needs:
ACCESS usedby STDIO: MKTEMP, TMPNAM
CLOCK usedby CC
CLOSE usedby CCASMB
CLOSE usedby STDIO: FCLOSE
CTIME usedby CCINP - __DATE__ and __TIME__
EXIT usedby various
but needs wait()...
FCNTL usedby STDIO: FREOPE
FORKEX usedby CCASMB
FSTAT usedby CCASMB
GETPID usedby CCASMB
GETPID usedby STDIO: MKTEMP, TMPFIL, TMPNAM
JSYS usedby CCASMB - T20 PRARG%
LSEEK usedby STDIO: FFLUSH, FGETC, FILBUF, FREOPE, FSEEK
OPEN usedby CCASMB
OPEN usedby STDIO: FREOPE
READ usedby CCASMB
READ usedby STDIO: FGETC, FILBUF
STAT usedby CC
STRERR usedby CCASMB - OS error message feature
STRERR usedby STDIO: PERROR (but uses normal errno)
TIME usedby CCINP - __DATE__ and __TIME__
TIME usedby STDIO: TMPFIL, TMPNAM
UNLINK usedby CC and CCASMB
UNLINK usedby STDIO: REMOVE
WAIT usedby exit()
WRITE usedby STDIO: FFLUSH, FPUTC, FPUTS
STDIO syms that KCC needs:
FCLOSE FFLUSH FGETC FOPEN FPRINT FPUTC FPUTS FWRITE SPRINT UNGETC