
\(progn

  (defmacro set-page (name) `(setq ,name *page-number*))
  (defun date ()
    (multiple-value-bind (sec min hour date month year) (get-decoded-time)
      (do-string
	(format nil
                "~[January~;February~;March~;April~;May~;June~;July~;~
		   August~;September~;October~;November~;December~] ~
                 ~d, ~d"
		(1- month)
                date
                year))))
  (defun fr () (setq *current-font* *font-roman*))
  (defun fi () (setq *current-font* *font-italic*))
  (defun fb () (setq *current-font* *font-bold*))
  (defun fp () (setq *current-font* *font-prop*))
  (defun fg () (setq *current-font* *font-big*))
  (defun sm () (setq *old-left-margin* *left-margin*)
	       (setq *left-margin* (+ (mark-column) *left-margin*)))
  (defun rm () (do-line-so-far) (setq *left-margin* *old-left-margin*))
  (defun ra () (right-adjust))
  (defun ce () (centering))
  (defun br () (break-line))
  (defun lm (n) (setq *left-margin* n))
  (defun bd () (setq *left-margin* 100))
  (defun endd () (do-line-so-far) (setq *left-margin* 0))
)






\(ra)Revised \(date)





\(fg) 
\(ce)A Guide to Porting Kyoto Common Lisp

\(fr)






\(fi)
\(ce)by
\(fr)

\(ce)Masami Hagiya
\(ce)Taiichi Yuasa


\(ce)Research Institute for Mathematical Sciences
\(ce)Kyoto University
\(ce)Kyoto, 606, Japan














\(ce)Copyright (C) 1984 Taiichi Yuasa and Masami Hagiya

\(fg) 

Introduction
\(fr)
     This document explains how to construct the KCL system
and how to port KCL.  It will also be useful for customizing the existing
versions of KCL.

	1. KCL/AOS
	   Machine: \(sm)Data General's Eclipse MV series super-minicomputers (MV10000, MV8000, MV6000, and MV4000)\(rm)
	   Operating System: \(sm)Data General's original AOS/VS (Advanced Operating System / Virtual Storage)\(rm)

	2. KCL/VAX
	   Machine: \(sm)Digital Equipment Corporation's VAX 11 series machines (VAX 11/780 and VAX 11/750)\(rm)
	   Operating System: UNIX 4.2 bsd

	3. KCL/SUN
	   Machine: \(sm)Sun Microsystems' Sun Workstation (MC68000/MC68020 base)\(rm)
	   Operating System: UNIX 4.2 bsd

	4. KCL/UST
	   Machine: \(sm)Sumitomo Electric Industries and Digital Computer Laboratory's personal workstation Ustation E15 (MC68000 base)\(rm)
	   Operating System: UNIX System V (Uniplus' version)

	5. KCL/DGX
	   Machine: \(sm)Data General's Eclipse MV series super-minicomputers (MV10000, MV8000, MV6000, and MV4000)\(rm)
	   Operating System: DGUX, Data General's native UNIX

	6. KCL/3B2
	   Machine: \(sm)AT&T's 3B2 series workstations\(rm)
	   Operating System: UNIX System V

	7. KCL/SEQ
	   Machine: \(sm)Sequent Balance 8000 (NS32032 base)\(rm)
	   Operating System: UNIX 4.2 bsd

	8. KCL/UTS
	   Machine: \(sm)M Series\(rm)
	   Operating System: UNIX System V

	9. KCL/NWS
	   Machine: \(sm)Sony NEWS (MC68020 base)\(rm)
	   Operating System: UNIX 4.2 bsd

Most of the source files of KCL are shared by these versions, but
some source files are specific to some versions of KCL.
In this document, we are mainly concerned with the UNIX BSD
versions, and
we explain how to port KCL to UNIX machines.  However,
this document is also helpful for those people
who want to port KCL to non-UNIX machines,
since it explains how to construct the KCL system in general.

     To port KCL to UNIX machines running under UNIX System V
(or System III, XENIX, VENIX, etc.) is much more difficult
than to port KCL to UNIX machines running under UNIX BSD.  Particularly,
the loader (fasloader)
and the memory dump routine should be rewritten.  Some of the standard
library functions of C used in KCL
may not be provided in UNIX System V.  Refer to Section 11 of
this document for the details.

     Some of the C source files of KCL contain the \(fp)#ifdef\(fr)
preprocessor command
followed by either of the following identifiers:

	\(fi)Identifier		Use\(fp)
	-----------------------------------------
	VAX		\(fr)VAX/UNIX 4.2BSD\(fp)
	SUN		\(fr)SUN-2 Releases 1.2 and 2\(fp)
	SUN2R3		\(fr)SUN-2 Release 3\(fp)
	SUN3		\(fr)SUN-3\(fp)
	ATT3B2		\(fr)3B2\(fp)
	E15		\(fr)Ustation E15 (System V)\(fp)
	NEWS		\(fr)Sony NeWS\(fp)
	MC68K		\(fr)MC68000\(fp)
	MC68020		\(fr)MC68020\(fp)
	NS32K		\(fr)NS32032\(fp)
	IEEEFLOAT	\(fr)IEEE floating format\(fp)
	UNIX		\(fr)UNIX\(fp)
	BSD		\(fr)UNIX 4.2BSD\(fp)
	ATT		\(fr)UNIX System V\(fp)
	DGUX		\(fr)DG/UX\(fp)
	AOSVS		\(fr)AOS/VS\(fp)
	AV		\(fr)Average (i.e., Non-MV) architecture\(fp)
	MV		\(fr)ECLIPSE/MV\(fp)
\(fr)

Each version of KCL has a key switch by which other switches for the
version are automatically defined.

	\(fi)Version		Key Switch	Other Switches\(fp)
	----------------------------------------------
	KCL/VAX		VAX		UNIX BSD AV
	KCL/SUN		SUN		UNIX BSD MC68K IEEEFLOAT AV
			SUN2R3		UNIX BSD MC68K IEEEFLOAT AV
			SUN3		UNIX BSD MC68020 IEEEFLOAT AV
	KCL/3B2		ATT3B2		UNIX ATT IEEEFLOAT AV
	KCL/UST		E15		UNIX MC68K IEEEFLOAT AV
	KCL/DGX		DGUX		UNIX MV
	KCL/AOS		AOSVS		MV
	KCL/SEQ		SEQ		UNIX BSD NS32K IEEEFLOAT AV
	KCL/UTS		S3000		UNIX ATT AV
	KCL/NWS		NEWS		UNIX BSD MC68020 IEEEFLOAT AV
\(fr)

     Some of the Lisp source files of KCL contain the \(fp)#+\(fr)
and \(fp)#-\(fr)
read-macros with the feature \(fp)AOS\(fr) or \(fp)UNIX\(fr).  The Common
Lisp variable \(fp)*features*\(fr) is created and initialized
in \(fp)c/main.c\(fr) (see below).  The initial value is set
according to which of the above identifiers is defined.  For the UNIX
versions, the symbol \(fp)UNIX\(fr) is in the features.

     It is desirable to make a user whose name is \(fp)kcl\(fr)
and load the distribution tape directly under his home directory,
and put the directory \(fp)bin\(fr) (see below) at the end of the search path,
since it contains the commands for system generation.  (Some of the commands
assume the C shell \(fp)csh\(fr) rather than the Bourne shell \(fp)sh\(fr).)

     Unfortunately, the C source files of KCL use identifiers much longer
than seven characters.  It will take much effort to port KCL to a poor
operating system
in which identifiers are recognized by the first seven characters,
such as the old versions of UNIX System V and System III.

     In this document,
we first discuss how to generate the KCL system,
explaining the components of KCL and how they are combined.  Then,
we give some hints for porting KCL to UNIX machines
by discussing the hardware-dependent parts
and the operating-system-dependent parts in detail.

     Although most of the KCL code was written by us, the authors of this
\(fi)Guide\(fr), several people have contributed to the development of
the current KCL.  We wish to express our thanks especially to the following
people.  Mr. Teruo Yabe and Mr. Toshiyasu Harada of Nippon Data General
helped us coding during the development of the first version of KCL.  
Dr. Skef Wholey at CMU allowed us to use their code for the function
\(fp)rationalize\(fr).  Dr. Yuuichi Ohta at the University of Tsukuba
ported KCL onto Sequent Balance 8000, writing the KCL/SEQ specific code.


\(fg)
1. Directories
\(fr)
     The distribution tape of KCL source is formatted
in the UNIX \(fp)tar\(fr) format.  The following \(fp)tar\(fr) call
will load all source files in the tape.
\(fp)
	% tar x
\(fr)
The source files of KCL are stored in four directories:

	\(fp)h	\(fr)header files
	\(fp)c	\(fr)source files in C
	\(fp)lsp	\(fr)source files in Lisp
	\(fp)cmpnew	\(fr)source files of compiler in Lisp

     The object files of C source files are placed
in the directory \(fp)o\(fr).

     The KCL itself is placed in the directory \(fp)unixport\(fr).  This
directory contains
other files needed for the system generation.

     The directory \(fp)bin\(fr) contains the commands used
in the system generation.

\(fg)
2. Makefiles
\(fr)
     Each of the directories \(fp)bin\(fr), \(fp)o\(fr), \(fp)lsp\(fr),
\(fp)cmpnew\(fr), and \(fp)unixport\(fr) has a makefile in it.

	\(fp)bin/makefile\(fr)
		to prepare the commands defined in the \(fp)bin\(fr) directory
	\(fp)o/makefile\(fr)
		to compile the source files in the \(fp)c\(fr) directory
	\(fp)lsp/makefile\(fr)
		to compile the source files in the \(fp)lsp\(fr) directory
	\(fp)cmpnew/makefile\(fr)
		to compile the source files in the \(fp)cmpnew\(fr) directory
	\(fp)unixport/makefile\(fr)
		to link and initialize KCL

There is another \(fp)makefile\(fr) in the KCL directory (i.e. the
current working directory when you read in the source tape).
This makefile does all the jobs of the above makefiles.

     These makefiles are intended for those users who are responsible
for the maintenance of KCL/VAX or KCL/SUN at their sites.  (We do not
know whether these makefiles are useful when KCL is ported to yet
another machine/os.)  The makefiles \(fp)o/makefile\(fr) and
\(fp)unixport/makefile\(fr) contain version-dependent parts, as indicated
\(fp)
  MACHINE = SUN3
  #	Select 'VAX', 'SUN', 'SUN2R3', 'SUN3', 'ISI', 'SEQ', 'IBMRT',
  #	or 'NEWS'.

  CHTAB	= sun_chtab.s
  #	Select 'char_table.s' or 'sun_chtab.s'.
  #	1) char_table.s : for VAX, SEQ and NEWS
  #	2) sun_chtab.s  : for SUN, SUN2R3 and SUN3
  #	3) isi_chtab.s  : for ISI
  #	4) ibmrt_chtab.s: for IBMRT
\(fr)
in \(fp)o/makefile\(fr) and
\(fp)
  MACHINE = SUN3
  #	Select 'VAX', 'SUN', 'SUN2R3', 'SUN3', 'ISI', 'SEQ', 'IBMRT',
  #	or 'NEWS'.
\(fr)
in \(fp)unixport/makefile\(fr).
Check these parts before using these files and, if necessary, modify them.

     To install KCL/VAX or KCL/SUN from the source for the first time,
do the following at the KCL directory.
\(fp)
	% su
	# cp h/cmpinclude.h /usr/include
	# exit
	% make
	% su
	# make install
	# exit
	%
\(fr)
To revise KCL, do the following at the KCL directory.
\(fp)
	% make
\(fr)

\(fg)
3. Header Files
\(fr)
     All the header files for C source files are stored
in the \(fp)h\(fr) directory.  The header file \(fp)include.h\(fr)
is the toplevel header file;
it includes other header files needed for compiling C source files.  It
also defines the appropriate switches
from the key switch of the version.  Since
each C source file includes \(fp)include.h\(fr)
by the preprocessor statement
\(fp)
	#include "include.h",
\(fr)
there is a copy of \(fp)include.h\(fr) in the \(fp)c\(fr) directory.

     Including \(fp)include.h\(fr) will include \(fp)stdio.h\(fr)
and \(fp)ctype.h\(fr),
which are the standard include files of C.

     The C source files that define number functions
also include \(fp)h/num_include.h\(fr) by another preprocessor statement
\(fp)
	#include "num_include.h".
\(fr)
\(fp)num_include.h\(fr) is linked to the \(fp)c\(fr) directory.

\(fg)
4. C Source Files
\(fr)
     Some of the source files in the \(fp)c\(fr) directory have
the suffix "\(fp).d\(fr)".  These files should be preprocessed
by the preprocessor called \(fp)dpp\(fr) (\(fi)D\(fr)efun \(fi)P\(fr)re\(fi)P\(fr)rocessor) before compiled by the C compiler.
The source file of \(fp)dpp\(fr) (i.e., \(fp)dpp.c\(fr)) is in
the \(fp)bin\(fr) directory.
It should be compiled (in the \(fp)bin\(fr) directory) by
\(fp)
	% cc -O -o dpp -DUNIX dpp.c
\(fr)
Or, you can use the makefile in the \(fp)bin\(fr) directory.
\(fp)
	% cd bin
	% make
\(fr)
\(fp)dpp\(fr) is called by
\(fp)
	% dpp \(fi)filename\(fr)

This will preprocess \(fi)filename\(fp).d\(fr) and
produce \(fi)filename\(fp).c\(fr).

     Each C source file (after preprocessed by \(fp)dpp\(fr)) is compiled
by the following command.
\(fp)
	% cc -D\(fi)name\(fp) -DMAXPAGE=\(fi)mp\(fp) -DVSSIZE=\(fi)vs\(fp) -O -c \(fi)filename\(fp).c
\(fr)
\(fi)name\(fr) is the key switch of the KCL version.
You are recommended to invent another name for your
machine.  \(fi)mp\(fr) is the maximum number of pages
(1 page = 2048 bytes) the KCL process will use.  It does not contain the
space for the stack segment,
but does contain the space for the text, data, and bss.  \(fi)vs\(fr) is
the size of the value stack of KCL in words.

     The object files of the C source files
should be placed in the \(fp)o\(fr) directory;
move the output of the C compiler to the \(fp)o\(fr) directory.
\(fp)
	% mv \(fi)filename\(fp).o ../o
\(fr)
     The command \(fp)bin/ccc\(fr) does all the task;
\(fp)
	% ccc \(fi)filename\(fr)

will preprocess the source file, compile the source file and move the
object file to the \(fp)o\(fr) directory.  \(fi)filename\(fr) is the file
name of the
source file without the suffix (\(fp).c\(fr) or \(fp).d\(fr)).  The values
of \(fi)mp\(fr) and \(fi)vs\(fr) used in \(fp)ccc\(fr) are
\(fp)16384\(fr) (32 Mbytes) and \(fp)2048\(fr) (words).  The command
\(fp)bin/cccall\(fr) compiles all the C source files,
assembles an assembler file (see below),
and places the output in the \(fp)o\(fr) directory.
Or, you can use the makefile in the \(fp)o\(fr) directory.
\(fp)
	% cd o
	% make
\(fr)
     Two C source files contain \(fp)asm\(fr) statements.
One is for double-word
multiplication and division (\(fp)earith.c\(fr))
and another is for bit-table operation (\(fp)bitop.c\(fr)).  Refer to
Section 10.1.

\(fg)
5. The Assembler File
\(fr)
     There is one assembler file that should be assembled
by \(fp)as\(fr).  This file allocates the table
of character objects (\(fp)character_table\(fr)).
For the VAX and SEQ versions,
it has the name \(fp)char_table.s\(fr),
for the SUN, SUN2R3 and SUN3 versions \(fp)sun_chtab.s\(fr).
The output should be placed
in \(fp)o/char_table.o\(fr) even for \(fp)sun_chtab.s\(fr).

     This file only defines the symbol \(fp)_character_table\(fr)
(in the data or bss segment)
and allocates a space of 1024 bytes and a space of 2048 bytes
before and after the symbol, respectively.  This file is needed because
of the pathological phenomenon
that C \(fp)char\(fr)'s may sometimes be signed.

\(fg)
6. Libraries
\(fr)
     Some of the Common Lisp functions are written
in Lisp (Common Lisp).  They are divided into several library files
in the \(fp)lsp\(fr) directory.
These files have been compiled by the KCL compiler,
and for each library file, the following files are prepared:

	\(fi)filename\(fp).lsp\(fr)	Lisp source file
	\(fi)filename\(fp).c\(fr)	translated C source file
	\(fi)filename\(fp).h\(fr)	header file for \(fi)filename\(fp).c\(fr)
	\(fi)filename\(fp).data\(fr)	data file in the form of text

The translated C source file \(fi)filename\(fp).c\(fr) includes
the header files \(fp)h/cmpinclude.h\(fr) and \(fi)filename\(fp).h\(fr).
Since the header file \(fp)cmpinclude.h\(fr) is included by the preprocessor
statement
\(fp)
	#include <cmpinclude.h>
\(fr)
it should be moved (or linked) to the directory that stores
standard include files of C (say, \(fp)/usr/include\(fr)).  Each
translated C source file is compiled
by the following command.
\(fp)
	% cc -O -c \(fi)filename\(fp).c
\(fr)
Note that the translated C source files
are completely independent of the version of KCL.  The data file
should be attached at the end of the object file,
using, say, the \(fp)cat\(fr) command.
\(fp)
	% cat \(fi)filename\(fp).data >> \(fi)filename\(fp).o
\(fr)
The result should \(fi)not\(fr) be moved to the \(fp)o\(fr) directory.

     These object files can be loaded by the fasloader of KCL.  But
in this case,
the text of the object will be placed in the bss segment of the KCL process
and the garbage collector of KCL should take care of it.  So, it is desirable
to link the object with the kernel of KCL;
then the text will be in the text segment and become sharable
among the users.  By default, all the library files of KCL are included
in the KCL system (refer to Section 8).

     The command \(fp)bin/libccall\(fr)
compiles all the translated C source files in the \(fp)lsp\(fr) directory
and attaches the corresponding data files to them.
Or, you can use the makefile in the \(fp)lsp\(fr) directory.
\(fp)
	% cd lsp
	% make
\(fr)

     The files \(fp)export.lsp\(fr), \(fp)autoload.lsp\(fr), and
\(fp)setdoc.lsp\(fr) in the \(fp)lsp\(fr) directory
should not be compiled; their Lisp sources are loaded at the system
initialization.  \(fp)export.lsp\(fr) exports the external symbols
in the \(fp)lisp\(fr) package.  Not all the external symbols
in the \(fp)lisp\(fr) package
are exported by \(fp)export.lsp\(fr);
some are created in the initialization routines written in C
and do not appear in \(fp)export.lsp\(fr).  \(fp)autoload.lsp\(fr) was
once used to define the autoloaded functions.  Since all the library files
are included in the system now,
it is used to define some of the non-compiled functions,
such as environment queries and editor interfaces,
which do not require efficiency, but are expected
to be customized.  Since they are not compiled,
you have only to rewrite \(fp)autoload.lsp\(fr) to modify
these functions.  (Refer to Section 12.)  \(fp)setdoc.lsp\(fr) sets the
online documentations of built-in symbols.

\(fg)
7. The Compiler
\(fr)
     The compiler source files (in the \(fp)cmpnew\(fr) directory)
should be processed in the same manner as library files
in the \(fp)lsp\(fr) directory.  The files
\(fp)cmpmain.lsp\(fr), \(fp)cmpopt.lsp\(fr), and \(fp)lfun_list.lsp\(fr)
should not be compiled.  These three files are loaded
by \(fp)init_kcl.lsp\(fr) (see below).

     The command \(fp)bin/cmpccall\(fr)
compiles all the translated C source files in the \(fp)cmpnew\(fr) directory
and attaches the corresponding data files.
Or, you can use the makefile in the \(fp)cmpnew\(fr) directory.
\(fp)
	% cd cmpnew
	% make
\(fr)

     \(fp)cmpnew/cmpmain.lsp\(fr) defines the top-level
of the compiler.  Since this file contains the code to call the C compiler,
it depends on the operating system.

\(fg)
8. Raw System
\(fr)
     The raw system (the KCL system without system initialization)
is made by linking

	object files in the \(fp)o\(fr) directory
	object files in the \(fp)lsp\(fr) directory
	object files in the \(fp)cmpnew\(fr) directory
	\(fp)sys_kcl.o\(fr) in the \(fp)unixport\(fr) directory

Not all the object files in the \(fp)lsp\(fr) directory have to be linked
in the raw
system.  Only the following four files are necessary:
\(fp)
	defmacro.o
	evalmacros.o
	module.o
	toplevel.o
\(fr)
Other library files are optional;
they may be included in the system
or loaded explicitly by the user,
or made autoloaded.  The compiler is also optional;
you can make a system that does not include the KCL compiler.
By default, all the library files and the compiler
are included in the system.

     \(fp)sys_kcl.o\(fr) contains the initialization routine written in C.
It is made by compiling \(fp)unixport/sys_kcl.c\(fr).

     Since the KCL system uses the "mathematical library" of C,
the linkage editor should be invoked with the \(fp)-lm\(fr) option.

     The command \(fp)make_kcl\(fr) in the \(fp)unixport\(fr) directory
compiles \(fp)sys_kcl.c\(fr)
and links all the above object files with the C library,
makes the raw system, initializes it,
and saves the initialized system (see below).
Or, you can use the makefile in the \(fp)unixport\(fr) directory.
\(fp)
	% cd unixport
	% make
\(fr)
The raw system is
named \(fp)raw_kcl\(fr) (in the \(fp)unixport\(fr) directory).  You should
change the current directory to \(fp)unixport\(fr)
before issuing \(fp)make_kcl\(fr).

\(fg)
9. Initialization
\(fr)
     The initialization should be done in the \(fp)unixport\(fr) directory;
you should change the current directory to \(fp)unixport\(fr).

     The raw system is invoked by typing
\(fp)
	% raw_kcl.
\(fr)
After printing the banner and initializing the raw system,
\(fp)raw_kcl\(fr) will output the prompt.
\(fp)
	>
\(fr)
You are now at the toplevel.
But the libraries and the compiler have not been initialized yet.
The initialization of the library and the compiler
is done by loading the file \(fp)unixport/init_kcl.lsp\(fr).
\(fp)
	>(load "init_kcl")
\(fr)
After the initialization,
the system is automatically saved
in the file \(fp)saved_kcl\(fr) in the \(fp)unixport\(fr) directory,
and \(fp)raw_kcl\(fr) is terminated.
Here, to save the system means to dump the whole memory
to an executable file (\(fp)saved_kcl\(fr) in this case).

     To change the configuration of the system,
i.e., to change the set of library files to be included in the system,
or to exclude the compiler,
you should rewrite the following files.
\(fp)
	sys_kcl.c
	init_kcl.lsp
	make_kcl
\(fr)
These files are all in the \(fp)unixport\(fr) directory.

     A utility called \(fi)defsystem\(fr) is prepared
for changing the configuration of the system.  It is written in KCL and
is placed in the \(fp)unixport\(fr)
directory (\(fp)defsystem.lsp\(fr)).  Actually, the above three files were
produced by defsystem.  But you cannot use defsystem until you have installed
KCL.  Refer to the separate documents of defsystem for the details.

     The saved KCL system may be invoked by a command similar to
the command in the command file \(fp)unixport/kcl\(fr).  In
\(fp)unixport/kcl\(fr), the full pathname of the saved system is specified
to let the system know the pathname of itself;
this is needed for the fasloader.  The saved system may take several
arguments.  The first one is the pathname of
the \(fp)unixport\(fr) directory (ending with '\(fp)/\(fr)');
it can be omitted if the saved system is in the \(fp)unixport\(fr) directory,
and if there are no further arguments.  Other arguments are specified
when invoking
the KCL compiler directly from the shell
(by the command \(fp)unixport/lc\(fr) etc.).

\(fg)
10. Hardware-Dependent Parts
\(fr)
     In this section, we list those parts of KCL
that depend on the hardware.

     Before that, we briefly point out
those parts of the C source files of KCL
that are influenced by the architecture of ECLIPSE/MV.

     ECLIPSE/MV is a word addressing machine;
the byte pointer and the word pointer have different formats.
Because of this peculiarity, the C source files contain many cast operators
that may seem redundant for byte machines.  For the UNIX BSD versions,
we only assume byte addressing machines.

     The user's address space on ECLIPSE/MV begins with \(fp)0x7000000\(fr)
(in word address);
each address in the user's space has the ring number 7.
The ring number should always be cleared
to get the page number of the address.
For the UNIX BSD versions, we assume that the address space begins with \(fp)0\(fr).

\(fg)
10.1. Double-word Arithmetic and Bit-table Operation
\(fr)
     \(fp)c/earith.c\(fr) contains some \(fp)asm\(fr) statements
that define the double-word multiplication routine \(fp)extended_mul\(fr)
and the double-word division routine \(fp)extended_div\(fr).  Their
formats are as follows.
\(fp)
	extended_mul(d, q, r, hp, lp)
	int d, q, r;
	int *hp, *lp;
\(fr)
\(fp)d\(fr), \(fp)q\(fr), and \(fp)r\(fr) are positive
integers (31 bits long).
The result of \(fp)d*q+r\(fr), which is 62 bits long,
is divided into two words each containing 31 bits
and the high and low words are stored into \(fp)*hp\(fr) and \(fp)*lp\(fr),
respectively.
\(fp)
	extended_div(d, h, l, qp, rp)
	int d, h, l;
	int *qp, *rp;
\(fr)
\(fp)d\(fr), \(fp)h\(fr), and \(fp)l\(fr) are
positive integers (31 bits long).  \(fp)(h<<31)+1\(fr) is divided
by \(fp)d\(fr) and the quotient and the remainder are stored
into \(fp)*qp\(fr) and \(fp)*rp\(fr), respectively.

     \(fp)c/bitop.c\(fr) defines the bit-table operations
used in the garbage collector to get or set a mark bit
in the mark table.  In the mark table, one bit is prepared
for each word (1 word = 4 bytes).  The top address of the mark table
is stored in the C global variable
\(fp)mark_table\(fr) (a pointer to \(fp)int\(fr)).
The bit for a word pointer \(fp)x\(fr) is accessed by
\(fp)
	(mark_table[x/4/32] >> (x/4%32)) & 1.
\(fr)
\(fp)c/bitop.c\(fr) defines
three functions \(fp)get_mark_bit\(fr), \(fp)set_mark_bit\(fr),
and \(fp)get_set_mark_bit\(fr),
whose argument is a pointer to a word.
\(fp)get_mark_bit\(fr) returns \(fp)0\(fr) or \(fp)1\(fr) according to
whether the bit is off or on.
\(fp)get_set_mark_bit\(fr) also returns \(fp)0\(fr) or \(fp)1\(fr),
but sets the bit as \(fp)set_mark_bit\(fr) does.

\(fg)
10.2. Floating Point Numbers
\(fr)
     Some of the Common Lisp functions depend on the representation
of floating point numbers;
they include
\(fp)
	decode-float
	scale-float
	float-radix
	float-digits
	float-precision
	integer-decode-float
\(fr)
In KCL, these functions are all defined in \(fp)c/num_co.c\(fr).
Some floating point constants are also created in \(fp)c/num_co.c\(fr).
You should look through the file \(fp)c/num_co.c\(fr) and change the code
according to the representation of floating point numbers in your machine.

     The reader routine for floating point numbers does not depend
on the hardware.
As for the output, the C library function \(fp)sprintf\(fr) is used
to get the mantissa and exponent of a floating point number.
When the \(fp)IEEEFLOAT\(fr) switch is on,
since the IEEE floating format is assumed,
the exponent of a long floating point number can be three digits long.
This affects the C function edit_double in \(fp)c/print.d\(fr).

\(fg)
10.3. The C Stack
\(fr)
     Usually, the C stack grows from the high core to the low core.
But in some machines such as ECLIPSE/MV, it grows from the low to the high.
The code to check whether the C stack has overflowed
(or is about to overflow) depends on
the direction that the C stack grows.

     In \(fp)c/main.c\(fr),
the C global variable \(fp)cs_limit\(fr) is initialized;
the initial value depends on the direction that the C stack grows.
In the C function \(fp)eval\(fr) in \(fp)c/eval.c\(fr),
\(fp)cs_limit\(fr) is compared with the address of the argument
to check the C stack overflow.  This also depends on the direction.

\(fg)
10.4. Order of Arguments
\(fr)
     The C functions
\(fp)parse_key\(fr) (in \(fp)c/bind.c\(fr)),
\(fp)list\(fr) (in \(fp)c/list.d\(fr)),
and \(fp)listA\(fr) (in \(fp)c/list.d\(fr))
accept an arbitrary number of arguments.
Usually, the first argument is placed in the lower address than other
arguments, the second argument in the lower address than the rest, and so on.
But in some machines such as ECLIPSE/MV, the order is reversed.

\(fg)
11. Operating-System-Dependent Parts

11.1. Assembler File
\(fr)
     The assembler file \(fp)c/char_table.s\(fr) (or \(fp)c/sun_chtab.s\(fr))
should be rewritten as explained in Section 5.

\(fg)
11.2. Memory Management
\(fr)
     The UNIX BSD versions of KCL use the \(fp)sbrk\(fr) system call
to extend the process space.  Heap manipulating functions provided as
the standard library of C, such as \(fp)malloc\(fr) and \(fp)calloc\(fr),
are not used.  In fact, when calling \(fp)sbrk\(fr),
KCL always checks whether the process' highest address has been changed
after the last call of \(fp)sbrk\(fr).
If the highest address has been changed,
i.e., if some heap manipulating function has allocated memory,
KCL reports a fatal error and exits immediately;
KCL always wants to control the whole memory by itself.

     In the UNIX versions of KCL (except KCL/DGX), the following
five library functions are redifined in \(fp)c/alloc.c\(fr); \(fp)malloc\(fr),
\(fp)free\(fr), \(fp)realloc\(fr), \(fp)calloc\(fr) and \(fp)cfree\(fr).  You
should check whether the redefinition is compatible with other library
functions.

\(fg)
11.3. I/O
\(fr)
     For I/O, KCL only uses the standard I/O library of C;
it does not use any low-level system calls.  You should only care about
the deviation of the library of your machine
from the standard I/O library of C.
For example, the library of AOS/VS uses the name \(fp)_start\(fr)
for the buffer address in the I/O buffer structure;
in contrast, the library of UNIX uses the name \(fp)_base\(fr).

     Usually, the standard I/O library of C
allocates the I/O buffer by calling \(fp)malloc\(fr).  In KCL,
\(fp)setbuf\(fr) is used to set the buffer
to prevent the I/O library from calling \(fp)malloc\(fr).  But
in some cases, it is impossible to call \(fp)setbuf\(fr); for example,
\(fp)getwd\(fr), which gets the current working directory,
uses the standard I/O library to read directory files.
To cope with those cases, the UNIX versions of KCL (except KCL/DGX)
redefine \(fp)malloc\(fr) and the related functions (see Section 11.2);
the redefined \(fp)malloc\(fr) allocates the I/O buffer
in the standard heap of KCL.

\(fg)
11.4. The Loader
\(fr)
     Since the KCL compiler translates a Lisp program into a C program,
KCL should have the facility
to load the object file produced by the C compiler into the memory of the
interpreter.  The UNIX BSD versions of KCL invoke the standard linkage editor
\(fp)ld\(fr) with the \(fp)-A\(fr) option (incremental loading)
to relocate the object file.
The interpreter then loads the output of \(fp)ld\(fr) into the memory.

     If \(fp)ld\(fr) in your machine does not have the facility of
incremental loading, you should write the relocation routine by yourself.
The code that calls \(fp)ld\(fr) and reads the output
of \(fp)ld\(fr) is in \(fp)c/unixfasl.c\(fr).

\(fg)
11.5. Memory Dump
\(fr)
     The KCL function \(fp)save\(fr) saves the whole memory into an
executable file.  It is defined in \(fp)c/unixsave.c\(fr).
It assumes the format of \(fp)a.out\(fr).

\(fg)
11.6. The Compiler
\(fr)
     \(fp)cmpnew/cmpmain.lsp\(fr) should be rewritten,
if the code for the UNIX versions does not work.

\(fg)
11.7. Miscellaneous
\(fr)
     Programs in the following C files are OS-dependent:

	\(fp)unixfsys.c	\(fr)file system interface
	\(fp)unixint.c	\(fr)interrupt handling
	\(fp)unixsys.c	\(fr)KCL function \(fp)system\(fr)
	\(fp)unixtime.c	\(fr)time functions

These files need not be changed when KCL is ported
to machines running under UNIX BSD.
But when porting KCL to machines running under UNIX System V,
they will require several minor changes, depending on "the" System V.

\(fg)
12. Site-Dependent Parts
\(fr)
     \(fp)lsp/autoload.lsp\(fr) should be changed to setup
site-dependent Lisp functions and variables.
\(fp)
	lisp-implementation-type
	machine-type
	machine-version
	machine-instance
	software-type
	software-version
	short-site-name
	long-site-name

	*features*

	system:*default-time-zone*

	ed

	  ...
\(fr)
You can also define other functions in \(fp)autoload.lsp\(fr),
or set up storage parameters
(by \(fp)allocate\(fr), \(fp)allocate-contiguous-pages\(fr),
or \(fp)allocate-relocatable-pages\(fr)).
     



