CedarPreBasicsInterfaceDoc.tioga
weiser, April 26, 1989 6:37:45 pm PDT
CedarPreBasicsInterfaceDoc
PCEDAR 1.2 % FOR DISTRIBUTION OUTSIDE XEROX
CedarPreBasicsInterfaceDoc
Mark Weiser
Ó Copyright 1989 Xerox Corporation. All rights reserved.
Use and copying of this software and preparation of derivative works based
upon this software are permitted. Any distribution of this software or
derivative works must comply with all applicable United States export
control laws. This software is made available AS IS, and Xerox Corporation
makes no warranty about the software, its performance or its conformity to
any specification. Any person obtaining a copy of this software is requested
to send their name and post office or electronic mail address to PCRCoordinator.pa@xerox.com, or
PCR Coordinator
Xerox PARC
3333 Coyote Hill Rd.
Palo Alto, CA 94304
Abstract: CedarPreBasics contains a number of interfaces for raw support of the Cedar language. CedarPreBasics is written in C, but is not part of PCR. By including CedarPreBasics into PCR one can then run a subset of Cedar (no signals, no ref-literals, no ropes, no processes). All the routines in CedarPreBasics are for internal use only. No routines in CedarPreBasics are for direct calling by Cedar/Mesa or C applications. CedarPreBasics contains support for installation and management of Cedar interfaces and start traps, floating-point arithmetic, bit and byte moves, runtime types, and several other miscellaneous things. CedarPreBasics also registers some additional commands with the PCR command interpreter.
Created by: Russ Atkinson, Christian Jacobi, Andy Litman, Brian Lyles, Mark Weiser
Maintained by: Jim Foote
Keywords: runtime types, REF literal, installation support, interfaces, start traps, floating-point arithmetic
XEROX   Xerox Corporation
    Palo Alto Research Center
    3333 Coyote Hill Road
    Palo Alto, California 94304

For Distribution Outside Xerox
Introduction
FOR INTERNAL USE ONLY. NO ROUTINES IN CEDARPREBASICS ARE FOR DIRECT CALLING BY CEDAR/MESA OR C APPLICATIONS.
CedarPreBasics contains a number of interfaces for raw support of the Cedar language. CedarPreBasics is written in C, but is not part of PCR. By including CedarPreBasics into PCR one can then run a subset of Cedar (no signals, no ref-literals, no ropes, no processes). To use the full Cedar language CedarCore must also be included.
The packages in CedarPreBasics are:
InstallationSupport - start traps, interfaces, cedar symbols
CompilerSingleReal - floating-point number support
cmds - register some additional commands, no procedural interface
basics - some basic routines required by the code generated by the Mimosa backend
safestorage - REF literal and storage management interfaces from Cedar to PCR
cedarextra - additional routines required by the code generated by the Mimosa backend
See also PortableCedarRuntimeSupport.mesa for documentation of the contract between the Mimosa compiler backend and the runtime.
InstallationSupport
InstallationSupport is by far the largest body of code in CedarPreBasics. It is implemented in the following bodies of C code: InstallationSupportImplA.c, InstallationSupportImplB.c, InstallationSupportImplC.c, IsBoundImpl.c, StartImpl.c, StartTrapImpl.c, SymTabImpl.c, UnboundTrapImpl.c, UnloadImpl.c. It is too complicated to document here. Documentation is in three separate places:
InstallationSupportImplA.tioga.c
InstallationNotes.tioga
InstallationSupport.mesa
CompilerSingleReal
The routines here implement the floating library assumed by code generated by Mimosa. These are C routines, not ever to be called directly by either Cedar/Mesa or C programmers. Their implementation is generally in terms of C floating point. Special care is taken in compiling the C code to force true single precision floating when necessary.
Below are the routines documented as Pseudo-Mesa:
FloatInt: PROC [i: INT32] RETURNS [REAL32];
FloatCard: PROC [c: CARD32] RETURNS [REAL32];
RealNeg: PROC [a: REAL32] RETURNS [REAL32];
RealAbs: PROC [a: REAL32] RETURNS [REAL32];
RealAdd: PROC [a, b: REAL32] RETURNS [REAL32];
RealSub: PROC [a, b: REAL32] RETURNS [REAL32];
RealMul: PROC [a, b: REAL32] RETURNS [REAL32];
RealDiv: PROC [a, b: REAL32] RETURNS [REAL32];
RealMin: PROC [a, b: REAL32] RETURNS [REAL32];
RealMax: PROC [a, b: REAL32] RETURNS [REAL32];
RealGt: PROC [a, b: REAL32] RETURNS [BOOL]; -- (a>b)
RealGe: PROC [a, b: REAL32] RETURNS [BOOL]; -- (a>=b)
RealEq: PROC [a, b: REAL32] RETURNS [BOOL];
SignedPwr: PROC [base, exp: INT32] RETURNS [INT32];
UnsignedPwr: PROC [base, exp: CARD32] RETURNS [CARD32];
RealPwr: PROC [base, exp: REAL32] RETURNS [REAL32];
Cmds
This package installs a number of additional commands into the PCR command interpreter. There is no procedural interface into those commands. Most of these commands are no longer in use, being superseded by others defined in the package CedarPreBasicsExtras. The commands defined in Cmds are:
i, install -- install a previously loaded Cedar module
lr, loadandrun -- load and then run a Cedar module (takes -d or -q switch after filename)
l, load -- load and install a Cedar module (takes -d or -q switch after filename)
loadonly -- load and do not install a Cedar module (takes -d or -q switch after filename)
r, run -- run a previously loaded Cedar module
unload -- unload a previously loaded Cedar module (unimplemented)
p, printallscopes -- print info about all the loaded cedar modules
printcpbvers, printcedarprebasicsversion -- print the version of cedar prebasics being run
silentloading -- go about the business of dynamic loading quietly (default)
verboseloading -- print lots of messages about what is happening during dynamic loading
Basics
The routines here do some basic bit and byte moving. These routines are called by the code generated by Mimosa -- they should never by called directly by clients.
XR←MoveWords(dest, src, len) -- moves len words (where a word is an 'int') from src to dest. The caller does not assure disjointness.
XR←MoveWordsDisjoint(dest, src, len) -- moves len words (where a word is an 'int') from src to dest. For efficiency, the caller assures disjointedness.
XR𡤎qualWords(src1, src2, len) -- tests the two multi-word variables for equality.
XR←MoveBytesDisjoint(dest, src, len) -- moves len bytes from src to dest, and returns src. For efficiency, the caller assures disjointedness. (Actually, the current implementation does not require disjointedness.)
XR←MoveBytes(dest, src, len) -- moves len bytes from src to dest, and returns src. No assumptions are made about disjointedness.
XR𡤎xtractField(base, offset, bits) -- extracts a bits-bit field from any base pointer (pointer to word) at any bit offset. The word returned has the bits right-justified. The other bits are set to zero. bits must be less than or equal to 32 (for larger values use XR←MoveField ).
XR�positField(base, offset, bits, word) -- deposits the rightmost bits bits of word at the bits bitfield beginning at offset from base. The other bits in word are ignored.
XR←MoveField(dst, dstOffset, src, srcOffset, bits) -- moves 'bits' bits from src to dest. Uses sun bitblt. Approximate timings on a Sun-3/260 are: Move the first bit: 80 microseconds. Each successive bit: 43 nanoseconds.
XR𡤎qualFields(x, xOffset, y, yOffset, bits) -- tests bitfields for equality.
XR𡤏illFields(dst, dstOffset, bits, times, value) -- fills contiguous fields that each are bits wide in the dst address (plus dstOffset bits) for times number of fields. The fill value will be right-justified in value.
XR𡤏illLongFields(dst, dstOffset, src, srcOffset, bits, times) -- fills contiguous fields that each are bits wide in the dst address (plus dstOffset bits) for times number of fields. The fill value is taken from the src address (plus srcOffset bits).
XR𡤏illWords(dst, times, value) -- fills times words at the destination with value.
XR𡤏illLongWords(dst, src, nWords, times) -- fills times nWords fields at the destination (dst) with the nWords field at the src.
Safestorage
This is the interface by which Cedar accesses storage. It also includes the code for low-level management of REF literals. As always for CedarPreBasics, these are not to be called directly, only by Mimosa-generated code.
REF literal support
See also the interface and implementation of RegisterRefLiteral, controlled by [pcedar1.2]<top>RegisterRefLiteral.df.
XR←RegisterRefLiteralRegistrationProc(regproc) -- makes regproc the registrar for REF literal creators.
XR←RegisterRefLiteralProc(p, typeindex) -- registers p as the REF literal creator for typeindex. Calls the regproc registered with XR←RegisterRefLiteralRegistrationProc with arguments p and typeindex.
XR←RegisterRefLiteralCallProc(refcreatorproc) -- makes refcreatorproc the procedure used to create all REF literals.
XR←GetRefLiteral(typeindex, object) -- creates a heap object with the given typeindex and value determined by object; calls the refcreatorproc registered with XR←RegisterRefLiteralCallProc with parameters typeindex and object, which in turn must call the procedure registered with XR←RegisterRefLiteralProc for the given type; returns the resulting value, which is a REF
The first three of these procedures form a private interface between safestorage.c and RegisterRefLiteralImpl in CedarCore. The last is called by Mimosa-generated code.
REF support
The following routines are for various REF-related things.
XR𡤌heckProc(proc) -- check if pointer to a procedure is ok. Return pointer if it is, raise fault if not. (Current implementation does no check.)
XR←Narrow(ref, typeindex) -- if the object referenced by ref is of type typeindex or nil, return ref, else raise NarrowFault. (Current implementation prints message "Need to raise NarrowFault".)
XR←GetReferentType(ref) -- Returns the typeindex for the object referenced by ref.
GetTypeFromRef(ref) -- same as XR←GetReferentType.
PutTypeInRef(ref, type) -- smashes the object referenced by ref to be of type type.
The following routines are called for all assignments to REF variables. The use of special routines for these assignments is leftover from the days of the old Cedar reference-counted garbage collector--they are no longer strictly needed.
XR𡤊ssignRef(dstPtr, src)
XR𡤊ssignRefInit(dstPtr, src)
XR𡤊ssignRefComposite(dst, src, type, size)
XR𡤊ssignRefCompositeInit(dst, src, type, size)
Memory management support
XR←NewObject(nAddressingUnits , type) -- allocate and return the address of an object that is nAddressingUnits long (bytes for 68020 and SPARC) and is of type type.
Cedarextra
Some leftovers, that don't fit into any other package. As always for CedarPreBasics, these are not to be called directly, only by Mimosa-generated code.
XR←NilCheck(ptr) -- raises NIL fault if ptr is nil.
XR�ugPutChar(ch) -- puts the single character to the terminal. Deprecated--leftover from early debugging.
XR𡤎xtensionAlloc(n) -- allocate n words for an extension, return the address.
XR←mesaError(n, p) -- raise the Mesa error (n,p). Deprecated, doesn't really raise the error, just prints an informative message: "**** Mesa Error".