Heading:qjk40(635)
Mesa for Extended Memory Altosy756qjk40\b30B
Page Numbers: Yes  X: 527  Y: 10.5"qjk40
Inter-Office Memorandumz18592l4445y762\f5b
To	Distribution	Date	April 18, 1979z18592l4445d2998e21(0,65535)(1,4445)(5,11684)(6,14146)\f7 2f0t2 1t0 12t6 1f7t0 4f0t7 1t0
From	Roy Levin	Location	Palo Altoz18592l4445d2998y716e25\f7 4f0t2 1t0 9t6 1f7t0 8f0t7 1t0
Subject	Mesa for Extended Memory Altos	Organization	PARC/CSL
(version 4)z18592l4445d2998e25\f7 7f0t2 1t0 30t6 1f7t0 12f0t7 1t0
XEROX       z18592l508y644e14(2116)\f2 5f0
Filed on: [Ivy]<XMesa>Doc>XMesa.bravo (and .press)e30(0,16510)(1,65535)(5,65535)(6,65535)\f7 50f1
x2e12(2116)
XMesa is a version of the Mesa runtime system that can exploit in certain ways the extended memory option of the Alto II.  This document describes the facilities provided by this system, its limitations, and its compatibility with other current Mesa systems.x2e12jk40(1799)
Overview of XMesax2e18jk80\b17B
XMesa uses the extended memory of an Alto II XM as additional swapping space for code.  This means that code and data need not co-exist in the primary 64K of memory.  XMesa takes advantage of any available extra space automatically; standard Alto programs do not need to be modified to run with XMesa.  XMesa does not simplify the task of managing data structures that are too large to fit in 64K, but it does free (most of) the 64K primary address space for use by data. x2e12jk40
Because XMesa uses extra memory for code segments, it includes a page-level storage allocator for the additional banks.  Client programs may request storage in the additional banks by using this allocator; the interface is public.  XMesa provides primitive mechanisms to read and write words in extended memory and to copy blocks of data between banks of memory, but gives no other assistance in accessing information in the extended memory.  In particular, arbitrary use of LONG POINTERs is not supported.x2e12jk40\475f7b12f0B5i3I
Clients should understand that, while XMesa is interface-compatible with Mesa 5.0 the implementation of certain system components (e.g., the page-level memory allocator and segment swapper) has changed substantially.  Client programs that assume undocumented properties of these components do so at their peril.  Information about incompatibilities in the implementation appears later in this document.x2e12jk40\f1
Compatibility with Mesa 5.0x2e12jk80\i
Considerable efforts have been made to ensure that XMesa is compatible with Mesa 5.0.  Exceptions are minor and typically affect only those programs that depend upon the format of global frames (details appear below).  To enhance the value of compatibility and because wide-bodied Altos are not universally available, XMesa will execute properly (though with some performance degradation) on a normal Alto (I or II) without recompilation or rebinding.  Indeed, XMesa requires no special compiler or binder.  Both BCDs and image files are compatible across machines.  Thus a Mesa disk containing the XMesa versions of XMesa.image (or BasicXMesa.image), and the debugger can be used without alteration on any Alto, XM or otherwise.  Specifically,x2e12jk40\617f8 11f0 5f8 16f0
1)	Mesa 5.0 BCDs will load and execute under XMesa,l3776x2e12jk40(0,4576)
2)	Mesa 5.0 image files will run correctly under XMesa,l3776x2e2jk40
3)	Image files created with XMesa will run (under XMesa) on any Alto,l3776x2e2jk40
4)	Files created with Mesa 5.0 and XMesa may be debugged (under XMesa) on any Alto.l3776x2e2jk40
Of course, these properties can be guaranteed only for programs that do not assume the existence of extended memory.x2e12jk40(1799)
Note!  Compatibility is assured only for Mesa 5.0.  BCDs compiled or bound by previous releases of the Mesa system will NOT work properly under XMesa.x2e12jk40\i150I
The Public Interface to XMesax2e18jk80\b29B
[Previous releases of XMesa provided their services exclusively through the XMesaDefs interface.  In Mesa 5.0, some of the facilities previously available only in XMesa have been incorporated into standard system interfaces.  To aid users of XMesa 4.1 in converting to XMesa 5.0, these facilities are still documented here.  In some cases, however, the interfaces have changed slightly.]x2e12jk40\76f6b9f0B
XMesa provides most of its services through the XMesaDefs interface.  However, the facilities supplied logically belong in other existing interfaces, notably SegmentDefs and AltoDefs.  Thus, XMesaDefs actually includes several semi-independent interfaces.  Unless otherwise stated, everything defined in this section comes from XMesaDefs.x2e12jk40\48f6b9f0B10f1 1f0 90f6b11f0B5f6b8f1B3f0 6f6b9f0B128f6b9f0B
Xmesa is being used by the Cedar project and certain definitions in the interface are intended exclusively for Cedar.  These facilities are not described in this document; clients other than Cedar should not use them.x2e12jk40\f1 217f0
Configuration Informationx2e24ck80\i
The facilities described in this section are defined in the MemoryOps interface, and therefore are available in both standard Mesa 5.0 and XMesa.x2e12jk40\60f6b9f0B
The Mesa runtime system has an internal data structure that contains information about the hardware configuration of the Alto on which it is running.  Clients may obtain a copy of this data structure by writingx2e12jk40
memoryConfig: MemoryConfig _ GetMemoryConfig[];l5088d3872x2e12k80\f6b12f7 2f6 13f7 1f6 16f7 3f6
and should normally test for the existence of extended memory by examining memoryConfig.useXM.  The extant banks of memory are indicated by memoryConfig.banks, which is a bit mask (e.g., memoryConfig.banks=14B => banks 0 and 1 exist).x2e12jk40\75f6b12f0 1f6 5f0B47f6b12f0 1f6 5f0B23i5I1f6b12f0 1f6 5f7 1f6 3f0B
BankIndex: TYPE = [0..3];l5088d3872x2e12k80\f6b9f7 10f6 1f7 2f6 1f7 2f6
MachineType: TYPE = {unknown0, AltoI, AltoII, AltoIIXM, D0, Dorado, AltoIV, unknown7};l5088d3872x2e12k80\f6b11f7 10f6 8f7 1f6 6f7 1f6 7f7 1f6 9f7 1f6 3f7 1f6 25f7 2f6
MemoryConfig: TYPE = MACHINE DEPENDENT RECORD[
reserved: [0..37B],
AltoType: MachineType,
useXM: BOOLEAN,
mdsBank: BankIndex,		-- for Cedar only
secondROM: BOOLEAN,
banks: [0..17B],
mesaMicrocodeVersion: [0..377B],
XMMicrocodeVersion: [0..377B]];l5088d3872x2e12k80\f6b12f7 34f6 9f7 3f6 6f7 2f6 9f7 2f6 11f7 1f6 6f7 10f6 8f7 2f6 9f7 1f0Bi19f6bI10f7 10f6 6f7 3f6 6f7 3f6 20f7 3f6 7f7 3f6 18f7 3f6 7f7 3f6
GetMemoryConfig: PROCEDURE RETURNS[MemoryConfig];l5088d3872x2e12k80\f6b15f7 20f6 12f7 2f6
useXM is true if and only if the following conditions hold:x2e12jk40\f6b5f0B
1)	the machine is an Alto II with XM modifications (AltoType = AltoIIXM),
2)	the Alto has more than one memory bank installed (banks ~= 10B),
3)	the Alto has a second ROM (secondROM is true), and
4)	the second ROM contains the current version of the XMesa microcode.l3872x2e12jk40(0,4576)\52f6b8f0B1f7b1f0B1f6b8f0B56f6b5f0B1f7b2f0B1f6b3f0B33f6b9f0B
The microcode version fields tell only the microcode version, not the Mesa release number.  (For example, for Mesa 5.0, mesaMicrocodeVersion is 39.)  XMMicrocodeVersion will be non-zero if and only if XMesa microcode is installed in the second ROM.x2e12jk40(1799)\43i9I10i3I55f6b20f0B10f6b18f0B
The procedure IsXMesa in MemoryOps provides a convenient way for a client BCD to determine if it has been loaded into an XMesa runtime system.  The return value TRUE from IsXMesa does not guarantee that XMesa is running on a wide-bodied Alto; the client should use GetMemoryConfig to verify the existence of extended memory (see below).x2e12jk40\14f6b7f0B4f6b9f0B127f7b4f0B6f6b7f0B6i3I78f6b15f0B
IsXMesa: PROCEDURE RETURNS [BOOLEAN];l5088d3872x2e12k80\f6b7f7 1f6 1f7 9f6 1f7 7f6 1f7 10f6
Unless otherwise noted, the facilities described in subsequent sections are usable only when the following expression, henceforth called "the XM condition", is TRUE:x2e12jk40\160f7b4f0B
IsXMesa[] AND GetMemoryConfig[].useXMl5088d3872x2e12k80\f6b7f7 7f6 15f7 3f6
Extended Memory Managementx2e24ck80\i
The facilities described in this section are defined in the XMesaDefs interface and should be used only when MemoryOps.IsXMesa[] is TRUE.x2e12jk40\60f6b9f0B40f6b9f7 1f6 7f7 2f0B4f7b4f0B
Segments in extended memory are created with the usual primitives in SegmentDefs.  However, XMesa recognizes additional "default" parameter values for those procedures that expect a VM base page number.  DefaultBase0, DefaultBase1, DefaultBase2, and DefaultBase3 request allocation in a specific memory bank.  DefaultXMBase requests allocation anywhere in the extended memory banks (banks 1-3, except for Cedar).  DefaultBase (defined in SegmentDefs) requests allocation anywhere in memory (banks 0-3) if the segment is a code segment, otherwise, it is equivalent to DefaultBase0.  DefaultMDSBase is equivalent (and preferred to) DefaultBase0 (except for Cedar).x2e12jk40\69f6b11f0B124f6b12f7 2f6 12f7 2f6 12f7 2f0B4f6b12f0B48f6b13f7 1f0B70f1 16f0 4f6b11f0B13f6b11f0B53i32I33f6b12f0B3f6b14f0B34f6b12f0B1f1 18f0
The following procedures logically belong in SegmentDefs.  They convert between segment handles and long pointers, and work for segments anywhere in the 18-bit address space.x2e12jk40\45f6b11f0B
XVMtoSegment: PROCEDURE [a: LONG POINTER] RETURNS [SegmentHandle];l5088d3872x2e12k80\f6b12f7 1f6 1f7 9f6 1f7 1f6 1f7 1f6 1f7 13f6 1f7 7f6 1f7 1f6 13f7 2f6
XSegmentAddress: PROCEDURE [seg: SegmentHandle] RETURNS [LONG POINTER];l5088d3872x2e12k80\f6b15f7 1f6 1f7 9f6 1f7 1f6 3f7 1f6 14f7 1f6 1f7 7f6 1f7 15f6
XVMtoDataSegment: PROCEDURE [a: LONG POINTER] RETURNS [DataSegmentHandle];l5088d3872x2e12k80\f6b16f7 1f6 1f7 9f6 1f7 1f6 1f7 1f6 1f7 13f6 1f7 7f6 1f7 1f6 17f7 2f6
XDataSegmentAddress: PROCEDURE [seg: DataSegmentHandle]
RETURNS [LONG POINTER];l5088d3872x2e12k80\f6b19f7 1f6 1f7 9f6 1f7 1f6 3f7 1f6 18f7 1f6 1f7 7f6 1f7 15f6
XVMtoFileSegment: PROCEDURE [a: LONG POINTER] RETURNS [FileSegmentHandle];l5088d3872x2e12k80\f6b16f7 1f6 1f7 9f6 1f7 1f6 1f7 1f6 1f7 13f6 1f7 7f6 1f7 1f6 17f7 2f6
XFileSegmentAddress: PROCEDURE [seg: FileSegmentHandle]
RETURNS [LONG POINTER];l5088d3872x2e12k80\f6b19f7 1f6 1f7 9f6 1f7 1f6 3f7 1f6 18f7 1f6 1f7 7f6 1f7 15f6
The following definitions logically belong in AltoDefs.  They define parameters of the extended memory system.x2e12jk40\46f6b8f0B
PagesPerBank: PageCount = . . . ;
MaxXPage: PageNumber = 1777B;		-- analogous to MaxVMPagel3872x2e12k80\f6b12f7 1f6 11f7 1f6 1f7 7f6 9f7 1f6 12f7 1f6 6f7 3f0Bi25f6bI
The following signal logically belongs in ImageDefs, and is raised when MakeImage (or CheckPoint) discovers a segment in the extended memory banks that cannot be swapped out.  (See the section on restrictions, below, for more information about image files).  If this signal is RESUMEd, MakeImage assumes that the segment in question has been removed from high memory by the client; failure to do so may result in an image file that cannot be restarted.x2e12jk80\42f6b9f0B205f1 1f6b2f0B18f7b6f0B169f6b
ImmovableSegmentInHighBank: SIGNAL [SegmentDefs.SegmentHandle];l5088d3872x2e12k80\f6b26f7 1f6 1f7 6f6 1f7 1f6 25f7 2f6
Long Pointer Supportx2e24ck80\i
The facilities described in this section are defined in the XMesaDefs interface and should be used only when the XM condition (see above) is TRUE.x2e12jk40\60f6b9f0B72f7b4f0B
XCOPY is analogous to COPY in InlineDefs, but accepts long pointers instead of pointers and moves data across memory bank boundaries.  The restrictions imposed on XCOPY in XMesa 4.1 have been eliminated; all combinations of source and destination banks are now legitimate.  XCOPY makes no attempt to validate the long pointers; if they exceed 18 bits or reference non-existent memory, XCOPY will have unpredictable results.x2e12jk40\f6b5f0B17f6b4f0B4f6b10f0B95f1 138f0 1f6b5f0B106f6b5f0B33f6b
XCOPY: PROCEDURE[from: LONG POINTER, nwords: CARDINAL, to: LONG POINTER];l5088d3872x2e12k80\f6b7f7 10f6 4f7 16f6 6f7 11f6 3f7 16f6
The implementation of XMesa prohibits client programs from manipulating the emulator bank register directly (see section on restrictions, below).  Clients wishing to perform a BitBlt across bank boundaries must therefore use the XBitBlt procedure, which verifies that the requested extended memory bank is available (raising XMNotAvailable if it isn't), then loads the emulator's alternate bank register with bank and performs a BitBlt.  Because the BitBlt microcode does not support arbitrary 18-bit addresses, XBitBlt can only be used to move data within a single bank or between the MDS bank (bank 0) and some other bank.x2e12jk40\229f6b7f0B89f6b14f0B70f6b4f0B23f6b2f1B186f6b
XBitBlt: PROCEDURE[bbt: BitBltDefs.BBptr, bank: MemoryOps.BankIndex];l5088d3872x2e12k80\f6b7f7 12f6 3f7 1f6 17f7 1f6 5f7 1f6 20f7 2f6
XMNotAvailable: ERROR;l5088d3872x2e12k80\f6b14f7 8f6
The following procedures convert between page numbers and long pointers, and are analogous to AddressFromPage and PageFromAddress in SegmentDefs.  Illegal parameters are detected and cause the indicated signals to be raised.x2e12jk40\94f6b15f0B5f6b15f0B4f6b11f0B80f6b
LongAddressFromPage: PROCEDURE[page: AltoDefs.PageNumber]
RETURNS[lp: LONG POINTER];l5088d3872x2e12k80\f6b19f7 12f6 25f7 10f6 2f7 16f6
InvalidXMPage: ERROR [page: AltoDefs.PageNumber];l5088d3872x2e12k80\f6b13f7 9f6 4f7 1f6 20f7 2f6
PageFromLongAddress: PROCEDURE[lp: LONG POINTER]
RETURNS[page: AltoDefs.PageNumber];l5088d3872x2e12k80\f6b19f7 12f6 2f7 24f6 4f7 1f6 20f7 2f6
InvalidLongPointer: ERROR [lp: LONG POINTER];l5088d3872x2e12k80\f6b18f7 9f6 2f7 16f6
For wizards only:  the bytecodes RBL, WBL, and BLTL (defined in Mopcodes) may be used in XMesa if the XM condition is TRUE.  However, if client-supplied special microcode is used, BLTL may not be available even then.  See [Ivy]<XMesa>Doc>Microcode.press for details.x2e12jk40\f1 33b3B2b3B6b4B67b4B58b4B82f0
How to Obtain and Use XMesax2e18jk80\b27B
The files for XMesa reside on [Ivy]<XMesa>.  The subdirectory structure parallels that used on [Iris]<Mesa>, but only those files that supersede or supplement Mesa 5.0 are stored on <XMesa>.  The files on <XMesa> are organized as follows:x2e12jk40
<XMesa>
XMesa.image, .symbols, and .signals
BasicXMesa.image,. symbols, and .signals
XMesa.cm, BasicXMesa.cm, and MakeXMDebug.cm
miscellaneous command filesl4512d3552x2e12jk40\8f8 11f0 3f8 7f0 6f8 8f0 1f8 16f0 3f8 7f0 6f8 8f0 1f8 8f0 1f8 14f0 5f8 15f0
<XMesa>System>
system definitions and program modules (.mesa and .bcd)
source and object code for microcode (in a .dm file)
miscellaneous command filesl4512d3552x2e12jk40\55f8 5f0 5f8 4f0 45f8 3f0
<XMesa>Doc>
XMesa.press and .bravo
Microcode.press and .bravol4512d3552x2e12jk40\12f8 11f0 6f8 21f0 6f8 5f0
<XMesa>XDebug>
modules to be installed in the Mesa 5.0 debugger (.mesa and .bcd)l4512d3552x2e12jk40\65f8 5f0 5f8 4f0
The standard Mesa 5.0 version of RunMesa.run will run XMesa programs; no special version of RunMesa is required.x2e12jk40\33f8 11f0 68f8
The microcode that must be installed in the second control ROM is stored in <XMesa>System>XMesaROM.mb.  This file is in suitable form for use by the PROM blaster.x2e12jk40\76f8 25f0 1f1 60f0
XMesa.cm and BasicXMesa.cm retrieve the corresponding image files, the debugger, and related supporting files.  MakeXMDebug.cm installs the debugger, including the modules required for debugging the XMesa environment.  (XMesa.cm and BasicXMesa.cm implicitly execute MakeXMDebug.cm as well.)x2e12jk40\f8 8f0 5f8 13f0 86f8 14f0 94f8 8f0 5f8 13f0 20f8 14f0
Note to BasicXMesa users:  The standard Mesa 5.0 version of ImageMaker.bcd may be used with XMesa programs.  (XMesa 4.1 supplied its own.)x2e12jk40\60f8 14f0 35f1 29f0
Restrictions, Limitations, and "Features"x2e18jk80\b41B
Images and Checkpoints.  MakeImage cannot preserve the contents of extended memory in the image file it constructs.  If MakeImage is invoked when the XM condition is TRUE, it will swap out all unlocked file segements in extended memory.  (It will also move any locked code segments to primary memory.)  If any segments then remain in extended memory, MakeImage will refuse to build the image file.  Analogous comments apply to CheckPoint.x2e12jk40\i25I141f7b4f0B
Bank Registers.  XMesa assumes it has exclusive control of the emulator bank register.  Client programs must not attempt to alter the bank register, but rather must use the public interfaces for moving data to and from extended memory (see XCOPY and XBitBlt, above).x2e12jk40\i15I225f6b5f0B5f6b7f0B
Global Frame Format.  XMesa exploits the full generality of the global frame format defined in ControlDefs.  Client programs should not assume that the code segment associated with a global frame can be obtained by writingx2e12jk40\i20I75f6b11f0B
frame.code.handle    .l7200x2e4jk40\f6b17f0B
The constructx2e4jk40
FrameOps.CodeHandle[frame]l7200x2e4jk40\f6b19f7 1f6 5f7 1f0B
should be used instead.x2e4jk40
Segment Object Format.  The format of segment objects has changed slightly, although (for compatibility) SegmentDefs has not been recompiled.  The format assumed by XMesa appears in XMesaOps.  Clients should be unaffected by this change.x2e12jk40\i21I84f6b11f0B66f6b8f0B47i
Segment Alignment.  Segments may not cross bank boundaries.x2e12jk40\i18I
Resident Code.  The amount of resident code in XMesa is 4 pages greater than in Mesa 5.0.  XMesa (and BasicXMesa) also have a larger process limit (75) than the standard Mesa system, and therefore consume an additional page of resident data.  Accordingly, XMesa may exhibit slightly poorer swapping performance on non-XM Altos than Mesa 5.0 does.x2e12jk40\i14I
Debugger Incompatibilities.  The Mesa 5.0 version of XDebug cannot be used with XMesa unless the module XMDebug.bcd is loaded when the debugger is installed.  In addition, the debugger's CoreMap command does not work at all under XMesa.  The UserProc XCoreMap should be installed in the debugger and used instead.  The command file MakeXMDebug.cm will install the debugger properly for use with XMesa.x2e12jk40\i27I77f8 11f0 136f8 8f0 73f8 14f0
Microcode in the RAM.  The microcode to support XMesa occupies more than 1K of control memory space.  Most of it resides in the second 1K of control ROM (ROM1), with the excess overflowing into the RAM.  The remaining RAM space is available to users who wish to write their own microcode, but certain conventions must be observed.  Those who need to execute special microcode from Mesa programs should consult [Ivy]<XMesa>Doc>Microcode.press (and .bravo).  Note to XMesa 4.1 clients who provide special microcode:  the amount of overflow into the RAM has increased in XMesa 5.0.  If you are short of microcode space, the document previously referenced describes ways to increase the amount of available RAM.x2e12jk40\i21I433f1 1f0 2f1 250f0
Swapper Algorithms.  The XMesa swapper loads a segment into extended memory by first swapping it into primary memory, then copying it to extended memory and releasing the primary memory space.  Thus, if primary memory is so full that the requested segment cannot be swapped in, InsufficientVM will be raised, even though sufficient space for the segment may exist in other banks.  (Analogous comments apply when swapping out segments that must be written to disk.)x2e12jk40\i19I259f6b14f0B
x2e12jk40(2116)
Distribution:
XMesa Users
Cedar Group
Mesa Groupl3528d2998x2e12k80