Enter your search terms Submit search form
	Web pdp-10.trailing-edge.com

		KCC Runtime Library Coding

	This file is oriented towards KCC implementors and describes
some general rules for writing C library functions, along with a more
detailed explanation of certain crucial files in the library.

	The source for all library routines is kept in <xx.LIB> where
"xx" depends on your system; on the distribution it is usually something
like "KCC-4".  Since that doesn't matter here, it will be left out of
any filenames mentioned.

    <.LIB*>	Runtime library sources:			Documented in:
	<.LIB.GEN>	General-purpose library routines.	(LIBC.DOC)
	<.LIB.MATH>	Math library routines.			(LIBC.DOC)
	<.LIB.STDIO>	Standard I/O package routines.		(LIBC.DOC)
	<.LIB.USYS>	Un*x simulation routines.		(USYS.DOC)
	<.LIB.USER>	User libraries (eg LIBTRM).		(LIBxxx.DOC)
	<.LIB.TEST>	Test routines, not part of C library.

Guidelines for writing C library modules:

	ALWAYS #include <c-env.h> before anything else, unless the
code is truly portable and completely in C.

	In general each specific library function should have its own
individual file, although several functions can be collected in the
same file if they are really tightly bound together.  Never use separate
files for different (system-dependent) versions of the same function;
keep them all together in the same file, with appropriate conditionals.

	If trying to compile for an unsupported system or CPU, invoke
the #error preprocessor command to cause a compilation error with an
appropriate message.  Alternatively, if it is important that a function
symbol exist even though it is unsupported, you can provide code for it
that simply always fails.

	Any routine that needs to use a system call should normally use
the facilities provided for that particular system (jsys.h, muuo.h, or
syscal.h) rather than using asm().  The overhead of the context switch
usually far outweighs the miniscule overhead of the C interface to the
call, and your code will be less vulnerable to changes in the C
implementation.


ASSEMBLER HACKERS:

	.FAI or .MAC source modules should never exist.  Functions
which absolutely must use assembly code should use the #asm or asm()
feature of KCC; the latter is preferable, because other C
implementations will not choke on that syntax as they would for #asm.
See the KCC user documentation for further details.

	In assembly code, always use $ or % characters in runtime-only
externals, switches, and macros, to avoid possible conflict with C
symbols.  Remember "_" in a C symbol is equivalent to "." in an
assembler symbol.
	The C runtime support has the following symbol conventions:
		$$$xxx		Major module entry name.
		$$xxxx		Global symbol value, internal to runtimes.
		$xxxxx		Global label, internal to runtimes.
		%xxxxx		Assembler macro simulating an instruction.
		%%xxxx		Assembler macro, miscellaneous function.

USYS routines:

	If writing a Un*x system-call simulation routine (which should
go into <.LIB.USYS>), there are several additional things to be careful
of, and the file USYS.DOC should be consulted.

IMPORTANT FILES:

C-ENV.H - C Environment defs.  Contains all system/CPU configuration defs.
	Location: C:

	<c-env.h> must be included by every LIBC routine which has any
system or environment dependencies.  Different versions of this file
exist for different systems/machines/configurations.  Can also be
included by user programs.  #ifndef conditionals allow testing
temporary changes by using the -D switch, although this should be done
in conjunction with the appropriate -x= switches.


CPU.C	- Load-time CPU definitions for target machine, determined by C-ENV.H.
	Location:    <.LIB.GEN>
	Entry point: $$$CPU (a dummy)
	Globals:     many!!

	This module is part of the C library and defines the values for
several symbols which depend on the specific processor that the program
is being loaded for.  The primary usefulness of this module is that it
allows the user to defer until load time the decision of whether to build
a program for extended or non-extended operation.  It also sets the right
symbols to ensure that all loaded modules are compatible with the CPU type
being loaded for.

CRT.C	- Standard C Run Time support for KCC.
	Location:    <.LIB.GEN>
	Entry point: $$$CRT (a dummy)
	Globals: $START			Startup
		__EXIT			Exit
		_END,_ETEXT,_EDATA,_EALLOC	Hack: Un*x simul (shd move)
		$RET,$RETF,$RETZ,$RETT,$RETP,$RETN	Return points
		$ZERO			Handy zero constant
		$ADJBP			ADJBP simulation
		$Bxxxx			Various byte-pointer tables

	All C programs start here.  CRT is responsible for setting up
the C environment so that C code can execute properly; this primarily
consists of initializing the memory organization and creating the C
stack.  It specifically does not do anything about setting up a UN*X
environment; that is up to whatever it is loaded with.  When the C
environment is ready, it calls the routine _runtm() which should
perform any remaining setup and then call main().  Normally this
routine is found in URT.C, the Un*x-simulation Run Time module.


URT.C	- UN*X-simulation Run Time support
	Location:     <.LIB.USYS>
	Entry points/Globals:
		_RUNTM		Startup for Un*x simulation
		EXIT		exit() call
		_EXIT		_exit() call
		ERRNO		Holds last USYS error #

	This module is called by CRT once the C environment is set up.
URT then sets up the UN*X simulation environment, parsing the command
line and setting up stdin, stdout, and stderr.  When ready, it calls
the user's main() function with the parsed command line as a normal
"argc,argv" array of char pointers.