lee@ariel.unm.edu (lee) (03/03/90)
Note- Abacus Research and Development, is in no way affiliated with the
====> University of New Mexico. Abacus Research and Development has had
====> a UUCP link to the University and since that link currently down,
====> this note is being posted from unmvax, rather than iclone.
====> Please do not electronically reply to the sender of this message,
====> as it is a courtesy account and responses will not be forwarded to ARDI.
Abacus Research and Development, Inc. (ARDI) is pleased to announce the
impending release of ROMlib(tm) V1.0, a set of C library routines with the
same syntax and semantics as the routines available on Apple Computer Inc.'s
Macintosh(tm) Plus computer. ROMlib-V1.0 provides all the routines documented
in "Inside Macintosh" Volumes I-IV with a few exceptions noted below. Although
ROMlib-V1.0 will only be available for use in X11 environments, there is little
dependence on X11, and experimental versions exist that write directly to
Sun "bwtwo"s and IBM PC "VGA"s. ROMlib-V1.0, ARDI's first product is useful
for company's whose IS departments wish to run programs that were developed
in-house on Macintoshes on the myriad of UNIX(tm)/X11 available. ROMlib-V1.0
is also useful for Independent Software Vendors that have written applications
on the Macintosh and would like to be out in front, shipping applications
into the UNIX market without the delay of a complete or partial rewrite.
ARDI is looking for beta sites for ROMlib-V1.0. Read the following
technical details, and if you have the C source to programs written on the
Macintosh, and UNIX machines running X11 (R3 or later) and you'd like to
be a beta site, please contact:
Cliff Matthews
Abacus Research and Development
1650 University Blvd.
Albuquerque, NM 87102
(505) 821-3877
Please do not electronically reply to the sender of this message,
as it is a courtesy account and responses will not be forwarded to ARDI.
__________________
Macintosh is a trademark of Apple Computer Inc.
ROMlib is a trademark of Abacus Research and Development, Inc.
UNIX is a trademark of AT&T Information Systems
ROMlib-V1.0
Compatibility Table
===================
The following table lists each of the routines described in Inside
Macintosh ("IM") and the level of compatibility that ROMlib provides. The
major sets of routines that will not be supported in the first version of
ROMlib (V1.0) are: the Desk Manager, the Print Manager, the Sound
Manager, AppleTalk and the Disk Driver, the SCSI Manager and the Disk
Initialization Package. This means that programs ported with ROMlib will
not be able to support desk accessories, printing or sound with Macintosh
style calls. Multiple ROMlib programs can be run simultaneously on the
same machine since UNIX is a multitasking operating system; this
significantly lessens the need for Desk Accessories. Printing and Sound may
be possible using UNIX vendor supplied routines, which have yet to be
standardized. Most UNIX systems support TCP/IP for networking and all
prohibit regular users from directly accessing the disk drives which is why
AppleTalk and low-level disk routines are not provided.
In the following table "FULL" means that every aspect of the routine
as documented in Inside Macintosh is supported. "MOST" is used where the
routine should function perfectly in programs that do not count on the low-
level implementation of the routine but use the routine for it's stated high
level purpose (the reasons for labeling routines "MOST" instead of "FULL"
follow the table). The Device Driver routines are labeled "SOME" because
Macintosh style drivers will not work with the ROMlib Device Driver, but it
is possible to write your own "ROMlib drivers" and communicate with them
via the standard Device Driver calls. A few routines are labeled "NOP" which
means that this routine does nothing in ROMlib, but that shouldn't affect
your program since in the UNIX environment the particular routine is not
needed (e.g. SetUpA5). NONE means there is no support for the routine in
question, which with but a few exceptions means that the routine is one
from the unsupported sets of routines mentioned above.
All internal data structures that are documented in Inside Macintosh
are used as described therein. In addition the region data structure, which
has been documented in other books, is the same in ROMlib as it is in the
Macintosh. ROMlib-V1.0 reads both V1 and V2 pictures, but writes only V2
pictures. Although none of the calls documented in Inside Macintosh Volume
V are supported, ROMlib will cheerfully ignore color op codes and the data
that follows them in V2 pictures.
***********************************************************************
*** To save space, most routines are not explicitly mentioned below ***
*** If you don't see a routine mentioned, that means the level of ***
*** compatibility provided is FULL ***
***********************************************************************
Resource Manager, IM-I
RsrcZoneInit NOP
GetResource MOST
QuickDraw, IM-I
SetCursor MOST X doesn't allow cursors to invert
Font Mgr, IM-I
ToolEvent Mgr, IM-I
GetNextEvent MOST Desk Accessory events aren't supported
EventAvail MOST Desk Accessory events aren't supported
Window Mgr, IM-I FULL
Control Mgr, IM-I FULL
Menu Mgr, IM-I FULL
TextEdit, IM-I FULL
Dialog Mgr, IM-I FULL
Desk Mgr, IM-I NONE
Scrap Mgr, IM-I FULL
Tool Utilities, IM-I FULL
Package Mgr, IM-I
InitPack NOP The routines in packages are in the ROMlib.a
InitAllPacks NOP
Binary-Decimal, IM-I FULL
Intl Utilities, IM-I FULL
Standard File, IM-I FULL
Memory Mgr, IM-II See below
InitApplZone MOST
SetApplBase NOP
InitZone MOST
GetApplLimit MOST
SetApplLimit MOST
MaxApplZone MOST
GetZone MOST
SetZone MOST
SystemZone MOST
ApplicZone MOST
HandleZone MOST
PtrZone MOST
FreeMem MOST
MaxMem MOST
CompactMem MOST
ResrvMem MOST
PurgeMem MOST
SetGrowZone MOST
GZSaveHnd MOST
TopMem MOST
MoveHHi MOST
Segment Loader, IM-II
CountAppFiles MOST
GetAppFiles MOST
ClrAppFiles MOST
GetAppParms MOST
UnloadSet NOP
OS Event, IM-II FULL
File Mgr, IM-II (See File Mgr, IM-IV)
Printing Mgr, IM-II NONE
Device Mgr, IM-II See below
OpenDriver SOME
CloseDriver SOME
FSRead SOME
FSWrite SOME
Control SOME
Status SOME
KillIO SOME
PBOpen SOME
PBClose SOME
PBRead SOME
PBWrite SOME
PBControl SOME
PBStatus SOME
PBKillIO SOME
GetDCtlEntry SOME
Disk Driver, IM-II NONE
Sound Driver, IM-II NONE
Serial Driver, IM-II See below
RAMSDOpen MOST
RAMSDClose MOST
SerReset MOST
SerSetBuf MOST
SerHShake MOST
SerSetBrk MOST
SerClrBrk MOST
SerGetBuf MOST
SerStatus MOST
AppleTalk, IM-II NONE
Vert. Retrace, IM-II
VInstall MOST Granularity system dependent
(not linked to "Vertical Blanking")
System Error, IM-II
SysError MOST
OS Utilities, IM-II
SetTrapAddress NONE
GetTrapAddress NONE
SysBeep SOME emits control-g
Environs SOME
Restart SOME
SetUpA5 NOP
RestoreA5 NOP
Disk Init Pack, IM-II NONE
Resource Mgr, IM-IV FULL
QuickDraw, IM-IV FULL
Font Mgr, IM-IV FULL
Window Mgr, IM-IV FULL
Control Mgr, IM-IV FULL
Menu Mgr, IM-IV FULL
TextEdit, IM-IV FULL
Dialog Mgr, IM-IV FULL
Tool Utilities, IM-IV FULL
Memory Mgr, IM-IV See below
MaxBlock MOST
PurgeSpace MOST
StackSpace MOST
OS Event, IM-IV FULL
File Mgr, IM-IV See below
GetVInfo MOST
GetVRefNum MOST
Eject MOST
SetEOF MOST
SetFLock MOST
RstFlock MOST
FInitQueue MOST
PBMountVol MOST
PBGetVInfo MOST
PBHGetVInfo MOST
PBSSetVInfo MOST
PBEject SOME
PBLockRange MOST
PBUnlockRange MOST
PBSetEOF MOST
PBAllocContig MOST
PBSetFLock MOST
PBHSetFLock MOST
PBRstFlock MOST
PBHRstFlock MOST
PBSetFVers NOP
PBRename MOST
PBGetCatInfo MOST
PBSetCatInfo MOST
GetFSQHdr MOST
GetVCBQHdr MOST
GetDrvQHdr MOST
PBGetFCBInfo MOST
Device Mgr, IM-IV NONE
OS Utilities, IM-IV
NGetTrapAddress NONE
NSetTrapAddress NONE
Environs MOST
List Mgr, IM-IV FULL
SCSI Mgr, IM-IV NONE
Time Mgr, IM-IV FULL
Resource Manager:
The resource manager is built on top of ROMlib's Hierarchical
Filesystem, so look there to see how and where the resource fork is actually
stored. Currently the standard xDEF code resources are not read out of the
System File by GetResource. This is because there is no trap facility so the
dynamic linking required would be a mess. It is possible to overwrite the
standard definition procs by changing an array that contains the pointers to
the appropriate functions. The level of compatibility is sufficient that
resource forks created on Macs should be readable under ROMlib and vice
versa. Unfortunately, not all UNIX machines are big endian, so a utility is
provided to do byte swapping for you, should you be on a little endian
machine.
QuickDraw:
All drawing in ROMlib is done to the "virtual mac X-Window", which is
an offscreen one bit deep bitmap. Whenever a graphic primitive changes
part of the screen, the change is performed off-screen and the bitmap
within the bounding rectangle(s) is/are shipped via XPutImage. This sounds
hopelessly inefficient, but between clever code within ROMlib and the
ability to defer screen writes (with the additional routines
"DeferScreenWrites" and "UnblockScreenWrites") most graphic operations
run noticeably faster on a Sun3/60 than on a Macintosh Plus. It is possible
to directly write to the screen yourself, but if you want the change to be
visible immediately you must call the routine "ScreenChanged" to keep X
current. Color is not supported, although it is possible to invert black and
white by making calls to "ForeColor" and "BackColor". ColorBit sets the
appropriate field pointed to by thePort, but no other code in ROMlib cares
about that field.
Toolbox Event Manager:
Since Desk Accessories are not supported, you never get desk
accessory events, hence GetNextEvent and EventAvail are marked "MOST."
Memory Manager:
It is impractical to divide virtual memory up into zones, so ROMlib's
memory manager doesn't do much more than call malloc() and realloc() and
do enough bookkeeping so that routines such as "GetPtrSize" and
"SetHandleSize" do the right thing. Internally, most of the memory that is
needed on the fly is allocated with alloca for speed. If programs insist on
creating zones, ROMlib's Memory Manager will cheerfully fill in some of the
zone structure but will continue to allocate memory with malloc(). In
general this should cause no trouble, but one exception would be where
someone creates a zone on the stack and expects all the space allocated in
that zone to automatically be freed when the current subroutine exists.
Segment Loader:
Parameters can be passed in on the command line. ROMlib's segment
loader attempts to locate files named as parameters. UnloadSet doesn't do
anything, but on a virtual memory system that only means that swap space
will continue to be used as the unloaded set gets paged out.
File Manager:
Resource forks are stored as separate files within the subdirectory
".Rsrc" that exists in the directory that the data-fork exists in. In order to
map back and forth between directory names and directory id numbers,
ndbm is used to keep a database of all subdirectories of a given ROMlib
"volume." The volume can be rooted anywhere on the UNIX filesystem, but
only ROMlib programs should move or delete directories unless you wish to
rebuild the mapping information after any changes. A program is provided
to do just that. The resource fork files have 512 bytes prepended to them in
anticipation of eventual TOPS compatibility. However the top-most bytes in
the 512 area are actually used to store information and may conflict with
TOPS (it hasn't been tested yet). Very few of the low-level data structures
are compatible, since UNIX is responsible for doing the actual file
manipulation. Setting EOF is allowed, but don't expect the relation between
logical EOF and physical EOF that is documented in Inside Macintosh to hold
true, files never shrink under ROMlib.
Serial Driver:
ROMlib attempts to map the UNIX serial driver into the requirements
of the Macintosh Serial Driver. Don't expect anything that can't be delivered
with termio(4).
Vertical Retrace:
The vertical retrace manager is supported, however the timing is
approximate and not tied to the refresh of the screen. In addition it is a bit
costly to have the kernel signaling your process every 60 seconds, so it is
possible to turn the vertical retrace interrupt off (the clock will continue to
tick).
System Error:
Since no executable code is read from resource files, the executable
portions of the the system error tables are compiled in. Instead of
"Welcome to Macintosh" you get a copyright notice when a ROMlib based
program starts up.
OS Utilities:
ROMlib V1.0 will not support system traps, so {Set,Get}TrapAddress
are not supported. SysBeep prints a control-g on the terminal that is
running the ROMlib process since ROMlib V1.0 has no sound manager
support. Restart kills the currently running process. Environs says the ROM
type is -1. Maybe Apple will give ARDI a range of ROM types so programs can
be more portable; don't hold your breath.
Time Manager:
The UNIX routine "setitimer" is used and has a different granularity
than the Time Manager wants, so times are not as precise. Additionally,
since the ROMlib process is potentially competing for CPU time there is no
guarantee that it will even be running when the timer expires.
Performance
===========
The Macintosh ROMs were written in assembler by very talented people
who were able to optimize for a particular processor. ROMlib V1.0 is written
entirely in C, has to go through X, yet still performs impressively. Using a
Macintosh + and a Sun3/60 for comparisons you will find that most graphics
code at the same speed or up to two times faster on the 3/60, and simple calls
run three to four times faster. These are estimates that have been made by
running benchmarks in real time, so they count the cost of having to go through
X (they would look better if only the CPU time used by the application was
examined, because the X server eats time as well) is counted.
Porting Problems
======= ========
ARDI is committed to seeing programs written on the Macintosh running
under UNIX. Because UNIX runs on a wide variety of machines, ROMlib alone
will not allow programs to be ported instantly. The mc680x0 line of cpus
are big-endian and don't require quad-alignment. ROMlib has been tested on
little-endian architectures (DEC MicroVax, an experimental version under
SCO Xenix that didn't use X) and machines that require quad alignment (Sun
Sparcstation, and a Stellar computer), but your application may not
immediately be so tolerant. ARDI can help with advice should alignment or
byte ordering be a problem.
Two porting tools help:
a post cpp pre cc1 processor (to take care of things like 'abcd'
and "\pstring" and whether an int is a long or a short)
a program that byte swaps resource files for use on little-endian
architectures
Thank you for the time you've spent reading this.
Even if ROMlib-V1.0 isn't for you, I hope the knowledge of it's existence
makes your day a little brighter.
Sincerely,
Clifford T. Matthews
President,
Abacus Research and Development