<<>> <> <> <<>> 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_EqualWords(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_ExtractField(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_DepositField(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_EqualFields(x, xOffset, y, yOffset, bits) -- tests bitfields for equality. XR_FillFields(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_FillLongFields(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_FillWords(dst, times, value) -- fills times words at the destination with value. XR_FillLongWords(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]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_CheckProc(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_AssignRef(dstPtr, src) XR_AssignRefInit(dstPtr, src) XR_AssignRefComposite(dst, src, type, size) XR_AssignRefCompositeInit(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_DebugPutChar(ch) -- puts the single character to the terminal. Deprecated--leftover from early debugging. XR_ExtensionAlloc(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".