In (PDR_FIG), the field marked (ACF\bold) represents the (Access Control \bold)field. This field describes how a particular page can be accessed, and whether or not a particular access should cause an abort of the current operation. The values in this field are as follows: (2\6) (Value\Meaning) (00\Nonresident page. Abort any attempt to access it.) (01\Resident read-only page. Abort any attempt to write into it. (RT--11 does not use this value.)) (10\Unused code. Abort all attempts to access this page. (RT--11 does not use this value.)) (11\Resident read/write page. All accesses are valid.)

The field marked (ED \bold)is the (Expansion Direction \bold)field. This bit indicates the direction in which a page can expand. The codes and their meanings are as follows:

(2\6) (Value\Meaning) (0\The page expands to higher addresses. (In RT--11, this field is always 0.)) (1\The page expands to lower addresses. (RT--11 does not use this value.))

The field marked (W \bold)is the (Written Into \bold)field. It indicates whether the page has been modified since it was loaded into memory. (RT--11 does not use this field.)

Some PDP-11 processors, instead of using bit 6 to indicate the page's modification status, use one or more of the reserved bits in the Page Descriptor Register. RT--11 ignores these other bits.

The field marked (PLF \bold)is the (Page Length field\bold). In indicates the length of a page, in 32-word decimal units. (Converting A 16-Bit Address To An 18- Or 22-Bit Address)

The information necessary for the Memory Management Unit to convert a 16-bit virtual address to an 18- or 22-bit physical address is contained in the virtual address and in its corresponding Active Page Register set. (VA_FIG) shows the meanings of the fields in the virtual address. These fields represent a breakdown of the virtual address that is convenient for RT--11 and the MMU to use.

(Virtual Address\VA_FIG) (20\--- Figure goes here ---)

Bits 13 through 15 of the virtual address constitute the (Active Page Field). This field determines which Active Page Register the Memory Management Unit will use to create the physical address.

Bits 0 through 12 of the virtual address are the (Displacement Field), which contains an address relative to the beginning of a page.

The rest of the information necessary to create a physical address is contained in the Page Address field of the appropriate Page Address Register. (MMUADDRCON_FIG) shows how, in a multi-job extended memory system, the Memory Management Unit converts a 16-bit virtual address to an 18- or 22-bit physical address. In this example, Page Address Register 6 contains 5460 octal, so virtual address 157746 converts to physical address 565746. Bits 12-15 of the Page Address Register are included for 22-bit addressing.

(MMU Address Conversion (Detail)\MMUADDRCON_FIG) (20\--- Figure goes here ---)

As you can see from (MMUADDRCON_FIG), bits 13, 14, and 15 of the virtual address specify which Active Page Register to use. The Memory Management Unit adds the value in bits 6 through 12 of the virtual address to the corresponding Page Address Register. The Memory Management Unit places the result of this addition in bits 6 through 17 or 6 through 21 of the physical address. The Memory Management Unit copies the value in bits 0 through 5 of the virtual address into bits 0 through 5 of the physical address to form the final 18- or 22-bit physical address. (Status Registers)

The Memory Management Unit also communicates with the RT--11 monitor through two status registers. Status Register 0, located at 777572 in the I/O page contains abort error flags, the memory management enable bit, and other essential information required by RT--11 to recover from an abort or to service a memory management trap. Status Register 2, located at 777576, is a read-only register containing the 16-bit virtual address that the Memory Management Unit is currently converting to an 18- or 22-bit physical address. (RT--11 does not use Status Register 2. However, if a memory management unit fault occurs in your system, you can examine this register yourself.) RT--11 also uses Memory Management Register 3 (MMSR3), located at 772516, to enable 22-bit addressing. (Kernel And User Processor Modes)

In addition to its primary function of managing the address space, the memory management system must provide some kind of protection for the monitor. To implement protection, the processor provides two modes of operation: (kernel mode \bold)and (user mode\bold). The two modes provide a mechanism for separating system-level functions (kernel mode) from application-level functions (user mode).

Each mode has its own set of eight Active Page Registers and its own stack pointer. Therefore, each processor mode also makes its own assignments of virtual addresses to physical locations: each mode has its own mapping. (PSWANDAPR_FIG) shows how the value in bits 14 and 15 of the Processor Status word determine in which processor mode execution takes place.

(Processor Status Word and Active Page Registers\PSWANDAPR_FIG) (20\--- Figure goes here ---)

Routines that run in (kernel mode \bold)are generally part of the run-time operating system software and must not be corrupted by other programs. RT--11 uses the processor's kernel mode for the Resident Monitor and the USR, for interrupt service routines, and for device handlers, including .SYNCH and .FORK routines. Interrupts and traps vector through kernel mapping and cause execution to continue in kernel mode.

Routines that run in (user mode \bold)are generally part of application programs. They are prevented from executing instructions that could corrupt the monitor or halt the computer. For example, a RESET instruction acts as a NOP instruction in user mode, and a HALT instruction generates a trap to 10. RT--11 uses the processor's user mode for the Keyboard Monitor, for system utility programs, and for application programs and their completion routines.

Since each processor mode uses its own set of Active Page Registers, kernel mapping is not necessarily identical to user mapping. For example, if user virtual address 20010 is associated with physical address 40210, it does not necessarily mean that kernel virtual address 20010 is also mapped to physical address 40210. In fact, kernel virtual addresses are often mapped to different sections of physical memory from user virtual addresses. The mapping depends entirely on the contents of the Active Page Registers. Thus, changing from user to kernel processor mode has some interesting implications: referencing the same virtual addresses in different modes can cause a program to access different physical locations. (1VA2PH_FIG) shows an example in which virtual address 0 in kernel mode maps to physical location 0; in user mode, virtual address 0 maps to physical location 500. This is the mapping scheme RT--11 uses for a virtual job at load time.

(Mapping the Same Virtual Addresses to Different Physical Locations\1VA2PH_FIG) (20\--- Figure goes here ---) (Default Mapping)

(Mapping \bold)is the process of associating virtual addresses with physical locations (see (AVOID32KLIM_SEC)). The RT--11 XB and XM monitors manage the virtual address space by controlling the way the virtual addresses map to physical locations. The monitors do this by putting values into the Active Page Registers, thereby controlling the Memory Management Unit.

When you first bootstrap an RT--11 extended memory system, kernel and user mapping are identical. That is, the monitor puts the same values into both the kernel and user sets of Active Page Registers. (APRCONTENTS_TAB) shows the initial values of the Active Page Registers. (DEFBMAP_FIG) shows the default mapping that results from these values. (APRCONTENTS_TAB) shows the default mapping for a typical 4K virtual background job that has no extended memory overlays and no extra regions.

(Initial Contents of Kernel and User APRs\APRCONTENTS_TAB) (#) (5\8\8\10\8) (Page and APR No.\Kernel PAR\Kernel PDR\User PAR\User PDR) (7\177600\77406\177600\77406) (6\##1400\77406\##1400\77406) (5\##1200\77406\##1200\77406) (4\##1000\77406\##1000\77406) (3\###600\77406\###600\77406) (2\###400\77406\###400\77406) (1\###200\77406\###200\77406) (0\#####0\77406\#####0\77406)

(Default Mapping at Bootstrap Time\DEFBMAP_FIG) (20\--- Figure goes here ---)

(Initial Register Contents for Virtual Job\IVJPARPDR_FIG) (#) (3\8\5\5) (Page and APR No.\User PAR\User PDR) (7\?\####0) (6\?\####0) (5\?\####0) (4\?\####0) (3\?\####0) (2\?\####0) (1\?\####0) (0\5\77406) (Software Concepts\XMSOFT_SEC)

RT--11 implements support for extended memory through the extended background, or XB, and the extended memory, or XM, monitors. One of the major design considerations for RT--11's extended memory support was that the XB monitor should closely resemble the SB monitor, and the XM monitor should closely resemble the FB monitor.

In addition, you must use a special set of device handlers that can communicate between a peripheral device and extended memory. It is part of the extended memory system design that the USR must be permanently resident.

The following sections describe the software concepts RT--11 uses in its extended memory system. (XB and XM System Memory Layout)

(XMSYSMAP_FIG) illustrates the locations of the XB and XM system components in physical memory in a 128K-word system. (Notice that the layout for the XM monitor closely resembles the FB system arrangement described in (SCM_CHAP).) When you first bootstrap an XB or XM system, the system device handler and the Resident Monitor use the available memory just below the 28K-word boundary so that extended memory -- the locations between 28K and 124K -- is not used. Other loaded device handlers occupy the space below the Resident Monitor, followed by foreground and system jobs, if any, and the USR.

The Resident Monitor executes in processor kernel mode and can access the low 28K words of memory and the I/O page. The USR also executes in kernel mode and is always memory resident in an XB or XM system. The Keyboard Monitor executes in processor user mode, but since it is a privileged background job, it uses the same mapping as the Resident Monitor. (Privileged jobs are described in (PRIVJOB_SEC).) Physical locations 0 through 500 contain the vectors.

(XB and XM System Memory Layout\XMSYSMAP_FIG) (20\--- Figure goes here ---) (How Programs Control Mapping)

Mapping -- associating virtual addresses with physical locations -- is the heart of the extended memory system. The XB and XM systems control mapping by putting values into the Active Page Registers, thus controlling the Memory Management Unit. Obviously, this level of control is elementary and requires the monitor to keep close watch over the mapping situation.

Fortunately, the monitor provides the means by which system and application programs can direct mapping operations and experience the benefits of accessing extended memory without concern for the specifics of the Memory Management Unit operations. In fact, your programs should never access the Active Page Registers or the Memory Management Unit Status Registers directly. Programs communicate their extended memory requirements to the monitor through a collection of programmed requests. These requests store or modify information in data structures within the programs. Based on the contents of these data structures, the monitor modifies its own internal control blocks and puts the correct values into the Active Page Registers to perform the appropriate mapping action.

In order to access extended memory, a program must: (UNNUMBERED) Tell the monitor how much physical address space it needs. Describe the virtual addresses it needs to the monitor. Direct the monitor to associate the virtual addresses with the physical locations. That is, it must (map \bold)the virtual addresses to the physical locations.

Background, foreground, and system jobs can all access extended memory by following the three steps described above. Note, however, that none of the jobs can share physical address space with another job.

The monitor and the programs use certain software concepts to describe the virtual addresses and the physical memory locations. The following sections describe the concepts of (physical address regions\bold), (virtual address windows\bold), and the (program's logical address space\bold). (Physical Address Regions)

A physical address region is a segment of physical memory consisting of contiguous 32 (decimal) word units. Each region must begin on a 32-word boundary.

Regions are created and allocated to programs by the resident monitor. The monitor maintains information about each region in a region control block that is located in the program's impure area.

Every program is allocated at least one region -- identified as region 0. This is a static region and cannot be altered or eliminated by the program for which it is allocated.

In addition to static region 0, a program can have up to five dynamic regions -- identified as regions 1 through 5. These regions provide a program with access to extended memory. The program describes each region it needs in a data structure called a region definition block and requests the regions by means of an RT--11 programmed request.

The monitor assigns an identification number to each region requested by the program. The region identification number is actually a pointer within your job's impure area to the start of the region's control block. (You will read more about region control blocks later.)

The purpose of a region is to describe a portion of the physical address space, thus making it available for mapping and permitting a program to use the physical addresses. Sections of physical address space that are not part of a region are unavailable to a program. (PASAND2REG_FIG) shows how memory can be divided into regions.

Information about a physical address region is contained in a 5-word data structure in your program, called a region definition block. The monitor collects information from the region definition block and stores it in a different internal data structure, called the region control block. The region control block is located in your program's impure area. (XMSTRUCT_SEC) provides more detailed information on the region definition and control blocks.

A program can request two types of region: local regions, which are controlled by programs, and global regions, which are controlled by the system.

(Local Regions)

A local region is a segment of extended memory that a program requests for its exclusive use. The program defines the region and maps its physical addresses to a range of virtual addresses. As long as the region exists, the region is the exclusive property of the program that requested it. When the local region is no longer needed, the program issues a request to eliminate it.

The data structures and programmed requests that a program uses to create, map, and eliminate a local region are described in (XMSTRUCT_SEC).

(Global Regions)

A global region is a segment of extended memory that a program can request for its exclusive use or share with other programs. The program maps the physical addresses to virtual addresses in the same way as for a local region. The monitor creates the global region and attaches the program to it. As long as the program remains attached, it has sole possession of the region. To share a region with other programs, the program issues a request to detach itself from the region. Any program can then attach itself to the global region. The operating system manages the sharing of a global region by allocating a local region within the global region to each attached program. The program that originally requested the region can reattach itself to the region but cannot regain exclusive possession.

A program can define a global region to be permanent, subject to elimination by any program that is currently attached to it, or set for automatic elimination after the last program has finished using it. An example of an address space that is located in a permanent global region is the RT--11 I/O page, which cannot be eliminated.

Up to ten global regions can exist concurrently in extended memory. A program can attach to a maximum of five global regions at the same time.

The data structures and programmed requests that a program uses to create, use, and eliminate global regions are the same ones that it uses for local regions.

In the multi-job XM system, programs can share global regions simultaneously, whereas in the background-only XB system, programs must share global regions linearly. That is, in XB, a program runs as the single background job and accesses the region. When the program exits, another program can run and attach itself to the same region, accessing the data left by the former program.

(Handler Global Regions)

Certain RT--11 handlers create global regions in extended memory. The name that a handler assigns to a handler region has the format:

(#) dd#$

where dd is the handler name.

For example, the following name identifies a global region created by the VM handler: VM#$

A program that wishes to attach to a global region created by an RT--11 handler must use this format to identify the region.

A user-written handler that wishes to create a global region should follow the RT--11 format described above for naming a handler region.

(Physical Address Space and Two Regions\PASAND2REG_FIG) (20\--- Figure goes here) (Virtual Address Windows)

A program that needs to access extended memory must also communicate to the monitor a description of the virtual addresses it plans to use. While the monitor uses the concept of pages to describe virtual addresses to the memory management unit, programs describe the virtual address space to the monitor by using the software concept of virtual address windows.

A virtual address window is a section of the 32K-word virtual address space consisting of contiguous 32-word decimal units. A window, like a page, must begin on a 4K-word boundary. However, unlike a page, whose maximum size is 4K words, a window can be as large as 32K words and can encompass one or more pages. There can be as many as eight virtual address windows or as few as one. The monitor assigns identification numbers to the windows when your program creates them.

The purpose of a window is to describe a section of virtual address space to the monitor, and thus permit a program to use those virtual addresses. Windows cannot overlap each other. (While a job can describe a new window that overlaps an existing one, the old one is eliminated when the new one is created.) And, sections of virtual address space, if any, that are not part of a window are not available for a program to use, unless the job is privileged. Each window that is less than 4K words causes a discontinuity in the program's virtual address space. A memory management fault results if the program tries to access a virtual address that does not fall within a mapped window. (A window is not useful until it is also mapped.)

The monitor can assign physical addresses to the virtual addresses encompassed by windows by calculating the number and size of the pages involved and putting values into the corresponding Active Page Registers for those pages. (VASAND3W_FIG) shows how virtual address space can be divided into windows.

(Virtual Address Space and Three Windows\VASAND3W_FIG) (20\--- Figure goes here)

Information about a virtual address window is contained in a seven-word data structure in your program, called a (window definition block). The monitor collects information from the window definition block and stores it in a different internal data structure, called the (window control block). The window control block is located in your program's impure area. (XMSTRUCT_SEC) provides more detailed information on the window definition and control blocks.

(The Static Window)

The first window, called the static window, is created for a (virtual \bold)job by the monitor at run time. ((MAPPING_SEC) describes the differences between virtual jobs and privileged jobs.) The static window begins at virtual address 0, and its size is equal to the size of your program's base segment, up to the program's high limit. The static window contains your program's root, stack, virtual vectors, overlay handler, and low memory overlays. Instructions, data, and buffers can appear in extended memory overlays or in extended memory .SETTOP buffers; they are contained in a different window and region. You can refer to the static window by using an identification of 0. Your program cannot eliminate the static window or change its mapping. (You cannot use the first window in privileged jobs, either; its data structures are reserved and currently unused.)

(The Dynamic Windows)

If your program needs to access more memory than the amount allocated at run time, it can create one or more dynamic windows and map their virtual addresses to physical locations. The static window is created by the monitor and a program can create up to seven more windows. A program can create, eliminate, map, and remap any of the dynamic windows. (Program's Logical Address Space (PLAS))

A program's logical address space is the range of physical address space effectively available to the program as a result of mapping operations. That is, all physical locations that are part of a region can be accessed by the program through mapping operations, and are thus part of its logical address space. The Program's Logical Address Space is abbreviated as PLAS, a term often used to refer to extended memory support in general. (Two Kinds Of Mapping\MAPPING_SEC)

RT--11 provides two kinds of mapping for jobs that run in an extended memory environment: (virtual mapping \bold)and (privileged mapping\bold). The following sections describe virtual jobs -- those that run with virtual mapping -- and privileged jobs -- those that run with privileged mapping. (Virtual Jobs)

Jobs that run with virtual mapping execute in the processor's user mode. Virtual jobs do not use kernel mapping; virtual background jobs load into memory at an offset of 500. Virtual jobs cannot load over the USR, the Resident Monitor, or the I/O page. Virtual mapping is the better mapping mode to use for a job that does not require privileged access to the vector area, the monitor, or the I/O page, since it protects these system areas from virtual jobs.

The first 500 bytes of each virtual job image are its virtual vector and system communication areas. The static window includes the virtual addresses between the program's virtual address 0 and its high limit. The size of the static region varies depending on whether the virtual job is a foreground or a background job and on the size of the job.

When you first run a virtual job, it can access only those virtual addresses that are within its own program bounds and that are also mapped to physical memory. However, a virtual job can use any remaining virtual address space between its own high limit and the 32K-word address boundary. It can create one or more regions in extended memory, and one or more virtual address windows. It can then map a window to a region, thus accessing extended memory. If a virtual job unmaps a window, it cannot use the virtual addresses encompassed by the window unless it remaps the window. A virtual job can also use the extended memory .SETTOP feature and extended memory overlays.

(Selecting Virtual Mapping)

You indicate that a job is to use virtual mapping by setting bit 10 of the Job Status Word before you run the program. If a particular job is always virtual, set bit 10 at assembly time. Use the following instructions to do this: .ASECT .=44 .WORD 2000 .PSECT

Or, if you prefer, select the program's mapping by running SIPP and patching location 44 in the job's .SAV or .REL file before you run the program. ()Do not change the value of bit 10 of the JSW when the program is running. Doing so interferes with accurate processing of I/O requests and can cause unpredictable results.

(A Virtual Background Job)

In an XB or XM system, use the monitor R or RUN command to start a virtual background job. You can also start the job through CCL by typing only the program name. The file should have the .SAV file type. A virtual background job loads into memory starting at physical location 500. Its highest physical address is equal to the size of the program in octal plus 500.

The static region for a virtual background job begins at physical location 500 and extends to the lowest address used by the USR. This prevents a virtual background job from ever accessing the physical vector area between locations 0 and 500. As a result, the vectors are protected from virtual jobs. (VBGJ_FIG) illustrates the mapping for a virtual background job in a 128K-word system. (VBGJM2SR_FIG) shows how a virtual background job can map a window into the static region to use the available memory just below the USR in a 128K-word system.

(Virtual Background Job\VBGJ_FIG) (20\--- Figure goes here)

(Virtual Background Job Mapping into the Static Region\VBGJM2SR_FIG) (20\--- Figure goes here)

(A Virtual Foreground or System Job (XM Only))

In the multi-job XM system, use the FRUN monitor command to start a virtual foreground job and the SRUN command to start a virtual system job. You should link these jobs as background jobs with the .SAV file type, rather than as foreground or system jobs with the .REL file type. You can FRUN or SRUN a virtual .SAV image because virtual foreground jobs require no relocation information. Thus, the .SAV files are smaller on disk than .REL files, and they load into memory faster.

When a foreground job is loaded, it uses the physical locations just below the lowest loaded handler or previously loaded system job. The USR slides down in memory, if necessary, to accommodate the foreground job. The foreground job is linked with a default base address of 1000 (unless it is a .SAV image); its virtual addresses between 0 and 500 represent the virtual vector and system communication areas. As with the background virtual job, the static window starts at virtual address 0 and extends to this foreground program's high limit, rounded up to a 32-word multiple.

The static region begins at physical location 0 and extends to the program's physical high limit. The foreground impure area is located in physical memory just below the program. However, no virtual addresses are mapped to the impure area, so a virtual foreground job cannot access the contents of the impure area. As a result, the impure area is protected from a virtual foreground job. (VFGORSYSJ_FIG) illustrates the mapping for a virtual foreground or system job.

(Virtual Foreground or System Job (XM Only)\VFGORSYSJ_FIG) (20\--- Figure goes here) (Privileged Jobs\PRIVJOB_SEC)

The default mapping in an extended memory system is privileged. To indicate a privileged job, bit 10 of the Job Status Word remains 0. The XB or XM environment appears to a privileged job to be very similar to an SB or FB environment. A privileged job can access the low 28K words of memory as well as the I/O page. All the RT--11 utility programs run as privileged jobs in an extended memory environment.

Privileged jobs, like virtual jobs, run in user processor mode. However, the monitor copies the contents of the kernel Active Page Registers into the user Active Page Registers. The default mapping for privileged jobs is thus the same as the default kernel mapping.

Privileged jobs do have all 32K words of virtual address space available to them. But much of that virtual address space is already mapped to operating system software, the I/O page, and -- in the case of a privileged foreground or system job -- to a background job or the Keyboard Monitor. A privileged job can alter its default mapping through the use of extended memory overlays or programmed requests. It can map away all or part of the operating system to obtain a full 32K words of addressable memory for itself. For example, a program that needs to access the I/O page for only a limited time can explicitly map away from the I/O page when it is done using it.

Note that the static window and static region concept does not apply to privileged jobs. However, one window and one region are reserved by the monitor. Thus, privileged jobs have seven dynamic windows and three dynamic regions available to them, just as virtual jobs do.

When a privileged job creates a window and executes the mapping programmed requests, the default privileged mapping for that virtual address space is temporarily unmapped. The monitor maps the window using the contents of the internal window control block to the new region of memory. When the privileged job unmaps the window, the monitor remaps that virtual address space according to the contents of the kernel Active Page Register set. This differs from a virtual job that unmaps a window, in which the virtual addresses encompassed by the window are unusable until the window is remapped.

Since interrupt service routines execute in kernel mapping, privileged jobs containing user interrupt service routines should not change the mapping of interrupt service routines, the I/O page, or parts of the monitor during any time period in which an interrupt could possibly occur. The monitor depends on the fact that kernel and user mapping are identical when it services user interrupts.

(Privileged Background Job)

Use the monitor R or RUN commands to start a privileged background job in an XB or XM system. (PRIVBGJ_FIG) illustrates the mapping for a privileged background job.

(Privileged Background Job\PRIVBGJ_FIG) (20\--- Figure goes here)

(Privileged Foreground or System Job (XM Only))

In the multi-job XM system, use the monitor FRUN command to start a privileged foreground job. Use the SRUN command to start a privileged system job.

(PRIVFGORSYSJ_FIG) illustrates the mapping for a privileged foreground or system job.

(Privileged Foreground or System Job (XM Only)\PRIVFGORSYSJ_FIG) (20\--- Figure goes here) (Differences Between Virtual And Privileged Jobs)

(VANDPJDIFF_TAB) summarizes the differences between virtual and privileged jobs.

(Comparison of Virtual and Privileged Jobs\VANDPJDIFF_TAB) (5\16\2\20\2) (Characteristic\\Virtual Job\\Privileged Job) (Value in bit 10 of JSW\\1\\0) (Original amount of address space available\\Accesses only the virtual addresses within its own program bounds.\\32K words. Accesses the low 28K words ofmemory plus the I/O page.) (Amount of potential address space\\32K words. Creates windows to describe the virtual address space between its own high limit and the 32K word boundary.\\32K words. If some portions of virtual address space are already in use (by a background job, for example), this job can unmap them and remap the addresses to memory above 28K words. It must leave certain areas mapped whenever a user interrupt service routine could run.) (Benefits\\Provides protection for operating system software and other programs; takes minimal physical memory away from other jobs.\\Compatible with FB and SB systems.) (Starting procedure\\BG: R, RUN, or CCL command (.SAV) FG: (XM only) FRUN or SRUN (.REL, .SAV; .SAV is recommended)\\BG: R, RUN, or CCL command (.SAV)FG: (XM only) FRUN or SRUN (.REL)) (Static window\\Extends from program's virtual address 0 to its high limit.\\None - all are dynamic.) (Static region\\BG: Extends from physical location 500 to the lowest address used by the USR. FG: (XM only) Extends from physical location 0 to the physical high limit of the job.\\None - all are dynamic.) (Possible number of windows\\7 plus the static window.\\7 (1 window reserved)) (Possible number of regions\\3 plus the static region.\\3 (1 region reserved)) (Context Switching Between Virtual And Privileged Jobs (XM Only))

In the multi-job XM systyem, the monitor saves job-dependent information when a new job replaces the one currently running. The monitor restores this information when the original job executes again. This procedure, called (context switching), is described in detail in (RMONCXW_SEC).

In an XM system, each job in memory could be either a virtual or a privileged job. The monitor, therefore, has more work to do when it switches context in an XM system.

When the monitor switches out the current job, it saves the information listed in (RMONCXW_SEC). However, the monitor never saves the contents of the Active Page Registers that the current job uses. For this reason, your programs should never manipulate the Memory Management registers directly; their contents are lost during a context switch. The monitor also ignores a .CNTXSW programmed request if it occurs in a virtual job. The entire job is saved by the switch, and the virtual job is not permitted to access the vector area in any case.

When the monitor switches in a new job, it assumes at first that the new job is privileged. It copies the contents of the kernel mapping registers into the user registers. The job can then access the low 28K words of memory plus the I/O page. Next, the monitor checks to see if the new job is the Keyboard Monitor. If it is, execution continues with no further modifications.

If the new job is a privileged job, the monitor next checks the window and region control blocks in the job's impure area. If the job defined and mapped one or more windows, the monitor restores the mapping based on the contents of the internal control blocks, thus altering the default privileged mapping for those windows.

If the new job is virtual, the monitor clears the user mapping registers. Then it scans the window and region control blocks in the job's impure area. The monitor maps only the portion of the job's virtual address space that was defined in a window and mapped to a region at the time the job was switched out. Of course, any attempt to access an unmapped address causes a memory management fault. Unused portions of virtual address space remain unmapped unless the virtual job explicitly maps them. (Typical Extended Memory Applications)

The following sections assume you understand the fundamental concepts of extended memory systems; they should help you see how to use extended memory. Some arrangements are suggested that may suit your own particular situation. As you read, keep in mind what benefits you want from an extended memory system. In other words, why do you want to use it? (Extended Memory Overlays)

The low 28K words of memory fill up rapidly with the Resident Monitor, device handlers, the USR, a foreground job, one or more system jobs, and a background job. To optimize use of this space and relieve the congestion, make the root segments of the foreground, system, and background jobs (if they are overlaid) as small as possible. Instead of segmenting the programs and using disk overlays though, you can put the overlays into extended memory. Make all the programs virtual jobs, unless they really need to access the monitor or the I/O page.

Instead of accessing the I/O page directly from your program, consider writing a device handler. .SPFUN requests allow a great deal of flexibility in writing special handlers for unusual devices.

The root segment can be minimal in size. All you need put there are queue elements, channels, interrupt service routines (if any - there are none in virtual jobs), and a JMP instruction to the first overlay. The overlay segments can be permanently resident in extended memory to speed up execution.

You can use the linker's /V option to put your overlay segments into extended memory. The Keyboard Monitor creates a region at run time, using information in the overlay handler and tables. The overlay handler creates and maps windows. (VBGJANDXMOVL_FIG) shows a simple virtual background program that uses extended memory overlays in 128K words. You can find detailed information on extended memory overlays in the (SUG_BOOK).

(Virtual Background Job with Extended Memory Overlays\VBGJANDXMOVL_FIG) (20\--- Figure goes here ----) (Large Buffers Or Arrays In Extended Memory)

In order to put a large buffer or array into extended memory, you first create a region large enough to accommodate the array. Next, decide how much virtual address space your program can commit to accessing the array and create a virtual address window of that size. Then simply write a subroutine that translates references to the array into instructions to remap the window into the correct part of the region. (VBGARRAY_FIG) illustrates this situation in 128K words. (The extended memory feature of the .SETTOP programmed request can create an extended memory buffer automatically. See (XMWORK_SEC) for information.)

(Virtual Background Job with an Array in Extended Memory\VBGARRAY_FIG) (20\--- Figure goes here ----) (Multi-User Program)

An extended memory system is ideal for implementing a multi-user application. For example, you could develop a language interpreter that several programmers could use simultaneously. To implement this application, separate your program into two sections: a pure code section that contains the interpreter, and a separate read/write work area for each user. Select part of your virtual address space to be the user scratch area, and create a window of that size. Next, decide how many users you want and create a region equal to the number of users times the size of the window. The interpreter can change user context by remapping the window. (MUVBG_FIG) shows a multi-user program in 128K words.

(Multi-User Virtual Background Program\MUVBG_FIG) (20\--- Figure goes here ----)

Your multi-user program can use extended memory overlays. In this case, use one region for the overlays and one for the work areas. (Work Space In Extended Memory\XMWORK_SEC)

Another application for you to consider is putting a work area into extended memory instead of writing it to disk.

Consider how jobs in an FB system obtain the most space possible for dynamic buffering. A background job gets extra space by issuing a .SETTOP programmed request. It can obtain the space above the job image up to the top of the USR. To obtain extra space for a foreground job, you must allocate it with the FRUN/BUFFER:n command. Once the space is reserved by FRUN, the program can determine its size and claim it with a .SETTOP programmed request. In both cases, the extra space is within the 28K words of low memory.

In XB and XM systems, extra space can be allocated from the physical space either above or below the 28K-word boundary. This feature can make jobs runnable that require too much memory for an unmapped RT--11 system. The ability to allocate extra space is most useful to virtual jobs because they can obtain space up to virtual address 177776 (32K words) by using the extended memory feature of the .SETTOP programmed request, hereafter referred to as (XM .SETTOP) or (The XM features of .SETTOP). All the memory obtained by .SETTOP is in extended memory; in XM, virtual foreground jobs do not require the FRUN/BUFFER:n command to allocate extra space. (Enabling The XM Feature Of The .SETTOP Programmed Request\ENABLXMSETTOP_SEC)

There are two ways to enable the XM feature of the .SETTOP programmed request. If your program has extended memory overlays, using the linker /V option to create them enables the XM .SETTOP programmed request automatically. It also enables the extended memory feature of the .LIMIT directive (see (XMSETTOP_SEC)), links the extended memory overlay handler (VHANDL) into your job image, and establishes an extended memory overlay structure. You use the /V option by issuing the LINK/PROMPT monitor command, and then specifying /V on a subsequent command line.

If your program has no overlays, or if it has only low memory overlays that you create with the linker /O option, you enable the XM feature of the .SETTOP programmed request by using the LINK command with the /XM option. The /XM option enables the XM .SETTOP programmed request and the XM .LIMIT directive. It does not link the extended memory overlay handler into your job image, nor does it establish an extended memory overlay structure for your program.

For all programs, the .LIMIT directive returns as its high value the next available location for the job. The extra space your program obtains with .SETTOP in an extended memory system always begins at the octal address returned as the high value from the .LIMIT directive. This is true for all programs, whether or not they enable the XM feature of the .SETTOP programmed request.

(NONXMSETTOP_SEC) describes how .SETTOP works when you execute a program in an extended memory environment without enabling the XM feature of .SETTOP. (XMSETTOP_SEC) shows how the XM feature of .SETTOP works after you enable it at link time; it also describes the XM feature of the .LIMIT directive. (Program And Virtual High Limits And The Next Free Address)

To understand XM .SETTOP, it is important that you understand the differences between the (program high limit\bold), the (virtual high limit\bold), and the (next free address\bold). (VHILIM_FIG) shows a program's virtual address space. This program has both low memory overlays created with the /O linker option, and extended memory overlays created with the /V linker option. The (program high limit \bold)is the highest virtual address used by the program's root segment and its low memory (/O) overlay regions, if any exist. The (virtual high limit \bold)is the highest virtual address used by the extended memory (/V) overlay regions, rounded up to a 32-word decimal boundary, minus 2. (In octal, the low-order two digits of the address are always 76.) This is the value that prints on the link map as (nnnnnn), as the following example shows: Virtual high address = nnnnnn = ddddd. words, next free address = mmmmmm

The linker has to calculate the value of the (next free address). For a job that enables the XM feature of .SETTOP, it rounds up the virtual high limit to the next 4K-word boundary. The next free address, then, is the last word of the virtual address space encompassed by the highest Page Address Register used by the job, plus 2. It is always on a 4K-word boundary. (In octal, the next free address is always a multiple of 20000.)

(Program and Virtual High Limits, and the Next Free Address\VHILIM_FIG) (20\--- Figure goes here ----)

As an example, consider a job with extended memory overlays whose virtual high limit is 55076. Its next free address calculated by the linker is 60000, or the start of the next 4K words of virtual address space. This is the value that prints on the link map as the (next free address). The following example shows the values in our example situation: Virtual high address = 055076 = ddddd. words, next free address = 060000

Of course, if a program has no extended memory overlays, it does not have a virtual high limit, and its program high limit is not rounded up. The link map for programs without overlays and for programs whose overlays were created solely by the /O option prints the program high limit as (mmmmmm), as the following example shows. (The following line prints on all link maps, whether or not extended memory is present.) Transfer address = nnnnnn, High limit = mmmmmm = ddddd. words (Non-XM .SETTOP\NONXMSETTOP_SEC)

If you do not enable the XM .SETTOP feature through the linker, using .SETTOP in an extended memory program has only limited value.

For a privileged job that does not alter the default mapping, .SETTOP works the way it does in an ordinary SB or FB system. If a privileged job creates a virtual address window and maps it to an extended memory region, the program high limit is not affected by the mapping. The value returned by .SETTOP still represents the highest address available to the program in the low 28K words of memory.

When the monitor performs address checking for programmed requests, it looks first to see if the address (of an argument block, a data buffer, and so on) is entirely within a mapped dynamic window. If it is not, the monitor checks to see if the address is within the job's low memory area. If the address fails both these checks, a monitor error results and the job aborts.

If the job is virtual, the program high limit at load time is set to the highest virtual address used by the root segment and any low memory (/O) overlays. If your job performs its own mapping operations, they do not affect the program high limit as far as .SETTOP is concerned. So, the .SETTOP request is meaningless to these virtual jobs. The non-XM .SETTOP request deals exclusively with the low 28K words of memory. Virtual jobs use the processor user mode and, therefore, are mapped according to the contents of the user Active Page Register set. The virtual job is prevented from accessing memory outside itself (because it is not mapped to any memory but its own dedicated physical space), so issuing a .SETTOP request in a virtual job without the LINK/XM command or the linker /V option does not obtain any extra memory. The value returned can be used by the virtual job to do its own mapping of the area available and then use it.

When the monitor performs address checking for a virtual job, it ignores the program limits and simply checks to see that the virtual address is within a window that is currently mapped. If the address is not within a mapped window, a memory management fault results. (XM .SETTOP\XMSETTOP_SEC)

When you enable the XM feature of .SETTOP, as (ENABLXMSETTOP_SEC) describes, .SETTOP becomes valuable to privileged and virtual jobs alike, although its value to privileged jobs is limited.

For virtual jobs, not only does .SETTOP obtain virtual address space above the virtual high limit starting at the program's next free address, but it also automatically maps the extra space to physical space. As a result, a job in an extended memory environment can issue a .SETTOP programmed request and obtain more usable virtual address space without concern for the details of managing extended memory.

For privileged jobs, XM .SETTOP functions the way non-XM .SETTOP does, with the following exception: in privileged jobs, the XM .SETTOP request uses the new XM .LIMIT high value as the next free address, thus always returning the start of the buffer on a 4K-word boundary. A .SETTOP to any address below this 4K-word boundary is not permitted.

For both privileged and virtual programs, the linker puts two words of information into locations 0 and 2 of the job image file. Location 0 contains the Radix-50 code for (VIR). Location 2 contains the value of the (next free address minus 2), which can be significantly different from the (virtual high limit).

(.LIMIT Directive)

For jobs in SB and FB systems, and in XB or XM systems without the XM feature of .SETTOP, the .LIMIT MACRO directive returns two values to your program. These values are: (UNNUMBERED) The lowest virtual address used by the program (usually 0) The program high limit + 2 (for example, 1644 + 2, or 1646)

In XB and XM programs that enable the XM feature of .SETTOP, .LIMIT returns a significantly different value: (UNNUMBERED) The lowest virtual address used by the program (usually 0) The next free address (always on a 4K-word boundary), which is usually not equal to the program high limit + 2.

(Gaps in Virtual Address Space)

The linker always starts each extended memory (/V) overlay region at a 4K-word boundary in your program's virtual address space. This restriction results from hardware requirements. Because of this there can be a gap between the program high limit and the start of the virtual overlay region. Your program causes an error if it attempts to reference the virtual addresses within this gap. Similarly, any extra virtual address space that XM .SETTOP obtains for your program also starts on a 4K-word boundary. This means that a gap can exist between your program's virtual high limit and the start of the extra space. Your program cannot reference the addresses within this gap. (VAGAPS_FIG) illustrates a typical program with both low memory (/O) and extended memory (/V) overlays.

(Gaps in Virtual Address Space\VAGAPS_FIG) (20\--- Figure goes here ----) (XM .SETTOP And Privileged Jobs)

When a privileged job issues a .SETTOP request, if the next free address is above the base of the USR, the program is already using the virtual address space above the start of the monitor. Since there is no free memory that can be mapped starting at the program's next free address, the monitor cannot obtain any more space for this program. Thus, a privileged job can never obtain space above SYSLOW, the base of the USR. The .SETTOP request returns the value of the next free address minus 2 to location 50 in your program and to R0. This is the highest usable address.

If there is memory available, the monitor tries to obtain it, basing the size of the area on the argument you specify with .SETTOP. The memory is always within the low 28K words. A privileged job can never obtain an amount of virtual address space less than its own next free address minus 2. In addition, the next free address obtained with XM .SETTOP is always on a 4K-word boundary, and the job cannot issue a .SETTOP for any address below that. Therefore, the job loses the space between its last used address and the next 4K-word boundary.

(Privileged Background Jobs)

(PRIVBGJS_FIG) shows a privileged background job and all its limits in 128K words. In an XB system, or in an XM system when no foreground job is present in memory, the background job can obtain some space through .SETTOP. There is often still space available in an XM system even when a foreground program is present.

(Privileged Background Job\PRIVBGJS_FIG) (20\--- Figure goes here ----)

(Privileged Foreground Jobs (XM Only))

Since foreground jobs load into memory just below the last device handler and above the USR, there is no extra space available for them through a .SETTOP request.

Because of this situation, privileged foreground jobs are prohibited from using extended memory overlays. This also means they cannot use the linker /V option (either through LINK/FOREGROUND/PROMPT or through LINK/FOREGROUND/XM) to enable the XM feature of .SETTOP and .LIMIT. (XM .SETTOP And Virtual Jobs\XMXSVJ_SEC)

The monitor checks to see if there is some extended memory available. If the next free address is 200000, the program is already using the virtual address space controlled by Page Address Register 7. The request returns the value 177776 in location 50 and in R0.

If .SETTOP can obtain virtual space starting with the next free address (on a 4K-word boundary), the monitor creates a region in extended memory for the necessary amount of space. If not enough space is available, the monitor creates as large a region as possible. (Be sure to check the value .SETTOP returns.) Then the monitor creates a window and maps it to the new region. It returns the new value of the highest available address in location 50 and in R0. If there is no space at all available, or if there are no region or window control blocks available, the request returns the value of the original highest available address in location 50 and in R0.

So, for example, if you issue a .SETTOP request with an address argument, the monitor maps the virtual address space starting at the next 4K-word boundary above the program's virtual high limit, up to and including the address you specify. It maps so that the address specified is mapped, but up to 31 decimal additional words can also be mapped.

If the address you specify in the .SETTOP request is below the highest used address, .SETTOP returns the value of the next free address minus 2 in location 50 and in R0. The static window and virtual overlay regions created with the linker /V option cannot be eliminated by using an argument to .SETTOP.

Assuming your first .SETTOP succeeded and an extended memory region exists for your program, you can issue subsequent .SETTOP requests to control the region. Note, however, that you cannot create yet another region to obtain any more space.

If the argument you specify in your next .SETTOP request is lower than the original next free address minus 2 from the link map, the monitor returns the old next free address minus 2 in location 50 and in R0 and eliminates the region and window, if present (along with any data stored there). You can, of course, issue another .SETTOP later to create a new region again. You can also adjust the size of the buffer by remapping within the same region.

To obtain a larger region, first issue a .SETTOP for a value below the current high limit, which eliminates the region and any data stored there. Then issue another .SETTOP for a larger value, which creates a new region. (Any data stored in the first buffer will be lost.) Note also that to ensure the integrity of your data, only one window exists for the .SETTOP area in an extended memory system.

To get less memory than a previous .SETTOP obtained, issue another .SETTOP with an address argument less than the first one but equal to or greater than the next free address. As a result, the size of the window still equals the size of the region, but a smaller amount of the window is mapped. This does not make any extended memory available for other users or other regions.

(Virtual Background Jobs)

Virtual background and foreground jobs are the most likely candidates for using the XM feature of the .SETTOP request. The request permits jobs to create large buffers in extended memory quickly and easily, which can help to reduce congestion in low memory. (VBGJS_FIG) shows a virtual background job in 128K words.

(Virtual Background Job\VBGJS_FIG) (20\--- Figure goes here ----)

(Virtual Foreground Job (XM Only))

In the multi-job XM sytem, the .SETTOP request works in much the same way for foreground jobs as for background jobs. For a virtual foreground job without the XM .SETTOP feature, the only extra space available is the space allocated through the FRUN/BUFFER:n command. For a job with the XM .SETTOP feature, the /BUFFER option is ignored. (The job cannot have buffers in both low and extended memory.) (VFGORSYSJS_FIG) shows a virtual foreground or system job with a large buffer in extended memory.

(Virtual Foreground or System Job (XM Only)\VFGORSYSJS_FIG) (20\--- Figure goes here ----) (Summary of .SETTOP Action)

Figures (BGSETTOP_FIG\VALUE) and (FGSETTOP_FIG\VALUE) and Tables (BGSETTOP_TAB\VALUE) and (FGHILIM_TAB\VALUE) work together to summarize the results of all possible .SETTOP requests. In (BGSETTOP_FIG), Job A is a background job whose next free address is below SYSLOW, the base of the USR. Job B is a background job whose next free address is above SYSLOW. (In the table, (next free address) is abbreviated to (NFA).) The values in parentheses represent specific ranges for .SETTOP arguments.

(Background .SETTOP Summary\BGSETTOP_FIG) (20\--- Figure goes here ----)

(Background .SETTOP Summary\BGSETTOP_TAB) (5\10\10\10\10) (1\If available; otherwise, as much extended memory as possible is obtained for the .SETTOP region.) (.SETTOPArgument\Virtual Non-XM .SETTOP\ Virtual XM.SETTOP\Privileged Non-XM .SETTOP\Privileged XM .SETTOP) ((5\LEFT)High Limit for Job A After .SETTOP) ((1)\(1)\NFA -- 2\(1)\NFA -- 2) ((2)\(2)\NFA -- 2\(2)\NFA -- 2) ((3)\(3)\map to (3)(1)\(3)\(3)) ((4)\SYSLOW -- 2\map to (4)(1)\SYSLOW -- 2\SYSLOW -- 2) (#0\0\NFA -- 2\0\NFA -- 2) (#--2\SYSLOW -- 2\map to 32K(1)\SYSLOW -- 2\SYSLOW -- 2) ((5\LEFT)High Limit for Job B After .SETTOP) ((1)\(1)\NFA -- 2\(1)\NFA -- 2) ((2)\(2)\NFA -- 2\(2)\NFA -- 2) ((3)\SYSLOW -- 2\NFA -- 2\SYSLOW -- 2\NFA -- 2) ((4)\SYSLOW -- 2\map to (4)(1)\SYSLOW -- 2\NFA -- 2) (#0\0\NFA -- 2\0\NFA -- 2) (#--2\SYSLOW -- 2\map to 32K(1)\SYSLOW -- 2\NFA -- 2)

(Foreground .SETTOP Summary (XM Only)\FGSETTOP_FIG) (20\--- Figure goes here ---)

(Summary of Foreground Job High Limit After .SETTOP (XM Only)\FGHILIM_TAB) (3\8\20) (.SETTOPArgument\Virtual JobNon-XM .SETTOP\Virtual JobXM .SETTOP) ((1)\(1)\NFA -- 2) ((2)\greater of OHIGH or BUFF\NFA -- 2) (0\0\NFA -- 2) (--2\greater of OHIGH or BUFF\Map to 32K) (Plan Your Own Application)

When you plan your own extended memory application, decide first whether the semi-automatic ways of using extended memory are useful to you. If the XM .SETTOP feature is all you need, your program will be fairly simple to write. Similarly, if you can easily segment your program into overlays, using the extended memory (/V) overlay feature of the linker may be simple for you. If you decide to handle the mapping yourself in a MACRO-11 program, sketch out diagrams ahead of time showing the arrangements of the system components, handlers, and other jobs. Unless your job needs to access the monitor routines or the I/O page, make it a virtual job. Think about the number of windows and regions you need and design the program accordingly. The following sections provide detailed information about the programmed requests and macro calls that a MACRO-11 program in extended memory can use, as well as information about extended memory restrictions. (Introduction To The Extended Memory Programmed Requests)

It is not difficult to access extended memory in a MACRO-11 program through the programmed requests, once you understand the general procedures you must follow and the tools RT--11 provides. Essentially, if your program does its own management of extended memory (rather than relying on any of the semi-automatic means described in the previous section), you must first establish window and region definition blocks. Next, you must specify the amount of physical memory the program requires, and describe the virtual addresses you plan to use. Do this by creating regions and windows. Then, associate virtual addresses with physical locations by mapping the windows to the regions. You can then remap a window to another region or part of a region. You can also eliminate a window or a region. In any case, once the initial data structures are set up, you can manipulate the mapping of windows to regions to suit your needs.

(XMHOWTO_TAB) summarizes the actions a program that uses extended memory may need to take. It also lists the appropriate procedures for the program to follow. Familiarize yourself with the procedures and the corresponding programmed requests and macro calls. The (PRM_BOOK) provides detailed information on the format of each programmed request and macro call. Study this information before you attempt to write an extended memory program.

(Summary of Activities for a Program in an Extended Memory System\XMHOWTO_TAB) (2\20) (Activity\Procedure to Follow) (Define offsets and symbols for a region definition block.\Use the .RDBDF or .RDBBK macro.) (Set up a region definition block and specify the region size.\Use the .RDBBK macro.) (Create a local region.\Use the .CRRG programmed request.) (Create and attach to a global region.\Use the .CRRG programmed request.) (Attach to an existing global region.\Use the .CRRG programmed request.) (Detach from a global region.\Use the .ELRG programmed request.) (Confirm the status of the new region.\Examine the contents of the region definition block after you use the .CRRG request to create the region. (Check the status bits in the status word.)) (Define offsets and symbols for a window definition block.\Use the .WDBDF or .WDBBK macro.) (Set up a window definition block and describe the window.\Use the .WDBBK macro.) (Create a window.\Use the .CRAW programmed request.) (Confirm the status of the new window.\ Examine the contents of the window definition block after you use the .CRAW request to create the window. (Check the status bits in the status word.)) (Associate a window with a particular region as preparation for mapping the window.\ Move the region identification from R.GID in the region definition block to W.NRID in the window definition block.) (Map a window to a region (explicitly).\Use the .MAP programmed request. ) (Map a window to a region (implicitly).\Set WS.MAP in the window definition block and load W.NRID before you issue the .CRAW request to create the window. This procedure creates the window and then maps it to a region.) (Obtain the current mapping status of a particular window.\Use the .GMCX programmed request.) (Unmap a window (explicitly).\Use the .UNMAP programmed request.) (Unmap a window (implicitly).\ Use the .MAP programmed request to map the window elsewhere. You can also unmap a window by eliminating the region to which it is mapped, or by eliminating the window itself.) (Eliminate a window.\Use the .ELAW programmed request.) (Eliminate a local or global region.\Use the .ELRG programmed request.) (Extended Memory Data Structures\XMSTRUCT_SEC)

A program in an extended memory environment communicates with the monitor through special data structures. For each region it defines, a program contains one (region definition block )to describe the size of the extended memory region. The monitor also maintains a set of internal data structures. The (region control block), located in the job's impure area, describes a region. The monitor can maintain up to four region control blocks per job. For each window it defines, a program also uses one (window definition block )to describe the virtual addresses encompassed by that window. The (window control block), located in the job's impure area, is the monitor's internal description for a window. The monitor can maintain up to eight window control blocks. The (I/O queue element )contains extra information in an extended memory system. Finally, the monitor allocates regions in extended memory based on its internal (free memory list).

The following sections describe these data structures and show, where necessary, how to create them. (Region Definition Block)

A (region definition block )is a 5-word area in your program that contains information about a region you define in extended memory. The monitor uses the region definition block to communicate with your job when you issue a .CRRG or .ELRG programmed request. You must set up the region definition block in your program and define its symbolic offsets before you can create a region in extended memory. You must then place the region's size in the region definition block. After you create the region, the monitor returns its identification and some status information to you through the region definition block. Each time your program needs to refer to this region, it uses the region identification. (Since the monitor creates the static region for you, you do not know its identification. You can always refer to the static region by using 0 as its identification.) (RDB_FIG) and (RDB_TAB) show the structure of a region definition block.

(Region Definition Block\RDB_FIG) +-------------+ | R.GID | +-------------+ | R.GSIZ | +-------------+ | R.GSTS | +-------------+ | | +-- R.NAME --+ | | +-------------+

(Region Definition Block\RDB_TAB) (4\6\8\16) (Ofset\Symbol\Modifier\Contents) (0\R.GID\Monitor's .CRRG routine\A unique region identification. Use it later to reference that region. The region identification is a pointer within the job's impure area to the region control block. The identification for the static region in a virtual job is 0.) (2\R.GSIZ\.RDBBK macro or user program\The size of the region you need, in 32-word decimal units. When attaching a local region to an existing global region, specifying a zero value obtains the whole global region.) (4\R.GSTS\Monitor's .CRRG routine\The region status word.) (6\R.NAME\.RDBBK macro\2-word global region name.) (Region Status Word)

The region status word contains information on the status of local and global regions. (RSW_TAB) shows the bits in the region status word and their meaning. Bits 0 through 6 are reserved for future use by DIGITAL.

(Region Status Word\RSW_TAB) (#) (4\6\8\8) (Bit\Name\Pattern\Meaning When Set) (15\RS.CRR\100000\The monitor created the region successfully. The .CRRG routine sets this bit; the .ELRG routine clears it.) (14\RS.UNM\#40000\One or more windows were unmapped as a result of eliminating the region. The .ELRG routine sets this bit when necessary.) (13\RS.NAL\#20000\Region was not previously allocated.) (12\RS.NEW\#10000\An attach request to a global region was made, and the global region was not found. The global region was created.) (11\RS.GBL\##4000\Create a local region within a global region. If global region is not found, returns error. (No error returned if RS.CGR is set.)) (10\RS.CGR\##2000\Create a local region within a global region. If a global region is not found, create a global region.) (#9\RS.AGE\##1000\XM only. Enable automatic global elimination. Eliminates global region when last job using global region detaches; when count in GR.SHC of global region control block is zero. RS.EGR need not be set.) (#8\RS.EGR\###400\Eliminates global region. Global region area is returned to free memory list. Count in GR.SHC of global region control block must be zero) (#7\RS.EXI\###200\Eliminate global region when exiting or aborting from job.) (.RDBDF Macro)

The .RDBDF macro defines symbols for the local and global region definition block. It defines the symbolic offset names for the definition block and the names for the region status word bit patterns. In addition, the macro defines the length of the definition block by setting up the following symbol: R.GLGH = 10.

The .RDBDF macro does not reserve space for the region definition block.

The format of the .RDBDF macro is as follows: .RDBDF

The .RDBDF macro expands as follows: R.GID = 0 R.GSIZ = 2. R.GSTS = 4. R.GNAM = 6. R.GLGH = 10. RS.CRR = 100000 RS.UNM = 40000 RS.NAL = 20000 RS.NEW = 10000 RS.GBL = 4000 RS.CGR = 2000 RS.AGE = 1000 RS.EGR = 400 RS.EXI = 200 (.RDBBK Macro)

The .RDBBK macro defines symbols for the local and global region definition block and reserves space for it. The .RDBBK macro invokes the .RDBDF macro. If you call the .RDBBK macro, you need not call the .RDBDF macro.

The format of the .RDBBK macro is as follows: .RDBBK RGSIZ,RGSTA,NAME

where: (NOHEAD) (RGSIZ) is the size of the dynamic region expressed in 32-word decimal units. (RGSTA) is the region status byte. (NAME) is the name of the global region in RAD50 characters. (Region Control Block)

A region control block is a three-word area in your job's impure area whose contents are maintained by the monitor. A virtual job dedicates one region control block to the static region. For a privileged job, one region control block is reserved by the monitor and cannot be used by a program. Thus, all jobs can have up to 5 dynamic regions whose status is maintained by the monitor in the region control blocks.

(RCB_FIG) and (RCB_TAB) show the structure of a region control block. The .ELRG programmed request clears all its fields.

(Region Control Block\RCB_FIG) ---------------------- | R.BADD | |--------------------| | R.BSIZ | |--------------------| | R.BNWD | R.BSTA | |--------------------|

(Region Control Block\RCB_TAB) (4\6\8\16) (Offset\Symbol\Modifier\Contents) (0\R.BADD\Monitor's .CRRG routine\The starting address of the region, expressed in 32-word units.) (2\R.BSIZ\Monitor's .CRRG routine\The size of the region in 32-word units. If this word is 0, this region control block is free.) (4\R.BSTA\The monitor at run time; the monitor's .CRRG routine clears this byte\ This byte is always clear unless the region was created by an XB/XM .SETTOP. The monitor then sets bit 1, called R.STOP. Bit 2 (R.SHAR) indicates that the region is a shared global region. Bit 4 (R.EXIT) indicates that the global region should be eliminated when the job exits or aborts.) (5\R.BNWD\Monitor's .CRRG routine clears this byte; .MAP increments it; .UNMAP decrements it\The number of windows currently mapped to this region.) (Global Region Control Block)

The global region control block is a 5-word area in the resident monitor (RMON). It is set up by the .CRRG programmed request and maintained by the XB or XM monitor. The global region control block contains the size, starting address, status, count of local region attachments, and name assigned to the global region. By default, RT--11 provides 10 (decimal) global region control blocks.

(GRCB_FIG) and (GRCB_TAB) describe the global region control block.

(Global Region Control Block\GRCB_FIG) +-----------------+ | GR.SIZ | +-----------------+ | GR.ADD | +-----------------+ | GR.SHC | GR.STA | +-----------------+ | | +----- GR.NAM ----+ | | +-----------------+

(Global Region Control Block\GRCB_TAB) (4\6\8\16) (Byte Offset\Symbol\Modifier\Contents) (0\GR.SIZ\Monitor's .CRRG routine\The size of the global region expressed in 32-word units. A 0 indicates the global region is not in use.) (2\GR.ADD\Monitor's .CRRG routine\The starting physical address of the global region expressed in 32-word units.) (4\GR.STA\.RDBBK macro\The global region control block status byte.) (5\GR.SHC\.RDBBK macro\A count kept of attachments to the global region. THe count is incremented with each successful .CRRG request, decremented with each successful .ELRG request. Bit 7 = 1, global region private (no new attachments honored until original attached local region is detached.) Bit 7 = 0, any job can attach to the global region.) (6\GR.NAM\.RDBBK macro\2-word name of global region in Radix-50.) (Global Region Control Block Status Byte (GR.STA))

(GRSTATBYTE_TAB) describes the global region control block status byte. Bits 0-4 are reserved for future use by DIGITAL.

(Global Region Control Block Status Byte\GRSTATBYTE_TAB) (#) (4\6\8\8) (Bit\Name\Pattern\Meaning When Set) (7\GR.AGE\200\XM only. Enables automatic global elimination. The global region area is returned to the free memory list when the last job using the global region detaches. Count is kept in GR.SHC.) (6\GR.PRM\100\The global region is permanent; it is never eliminated.) (5\GR.NRF\#40\Do not return the global region's allocated memory to the free memory list when the global region is eliminated.) (Window Definition Block)

A window definition block is a seven-word area in your program that contains information about a virtual address window you define. The monitor uses the window definition block to communicate with your program when you issue a .CRAW, .ELAW, .GMCX, or .MAP programmed request. You must set up the window definition block in your program and define its symbolic offset names before you can create a virtual address window. You must then place a description of the window you need in the window definition block. After you create the window, the monitor returns its identification and some status information to you through the window definition block. (WINDEFBLK_FIG) and (WINDEFBLK_TAB) show the structure of a window definition block.

(Window Definition Block\WINDEFBLK_FIG) ---------------------- | W.NAPR | W.NID | |--------------------| | W.NBAS | |--------------------| | W.NSIZ | |--------------------| | W.NRID | |--------------------| | W.NOFF | |--------------------| | W.NLEN | |--------------------| | W.NSTS | |--------------------|

(Window Definition Block\WINDEFBLK_TAB) (4\6\8\16) (Offset\Symbol\Modifier\Contents) (0\W.NID\Monitor's .CRAW routine\A unique window identification. Remember that you can always refer to the static window by using 0 as its identification.) (1\W.NAPR\.WDBBK macro; monitor's .GMCX routine\The number of the Active Page Register that includes the window's base address. Remember that a window must start on a 4K- word boundary. See (GRSTATBYTE_TAB) for the correspondence between Active Page Registers and virtual addresses. For privileged jobs, the valid range of values is from 0 to 7. For virtual jobs, the new window must not overlap the static window. You can find the lowest valid value for W.NAPR by issuing a .GMCX request for the static window, con- verting the high virtual address to an APR value, and incrementing it.) (2\W.NBAS\Monitor's .CRAW and .GMCX routines\The base virtual address of this window. This value should indicate the same address as W.NAPR. It is provided as a validity check. Note that it is expressed as an octal address, not in 32-word decimal units.) (4\W.NSIZ\.WDBBK macro; monitor's .GMCX routine\ The size of this window, expressed in 32-word units.) (6\W.NRID\.WDBBK macro; monitor's .GMCX routine\ Identification of the region to which this window maps. The .GMCX request returns a 0 if the window is not mapped. Otherwise, it returns the identification of the region to which it is mapped. Note that the value is also 0 if the window is mapped to the static region.) (10\W.NOFF\.WDBBK macro; monitor's .GMCX routine\ The offset, expressed in 32-word decimal units, into the region at which to start mapping this window. The .GMCX request clears this word if the window is not mapped; otherwise, it puts the offset value here.) (12\W.NLEN\.WDBBK macro; monitor's .MAP and .GMCX routines\ The amount of this window to map, expressed in 32-word units. If you put 0 here (or.CRAW with WS.MAP set), .MAP maps as much of the window as possible. On successful completion of the mapping operation, .MAP puts the actual length it mapped in W.NLEN. If you put a value here (other than 0), .MAP does not change it. The .GMCX request clears this word if the window is not mapped; otherwise, it puts the actual length mapped here.) (14\W.NSTS\.WDBBK macro; monitor's .CRAW, .ELAW, and .GMCX routines\The window status word. The .GMCX request clears this word if the window is not mapped; otherwise, it sets WS.MAP to 1.) (Correspondence Between Active Page Registers and Virtual Addresses\APRANDVA_TAB) (#) (2\16) (VirtualAddress Range\Active PageRegister Number) (######0-17776\0) (##20000-37776\1) (##40000-57776\2) (##60000-77776\3) (100000-117776\4) (120000-137776\5) (140000-157776\6) (160000-177776\7) (Window Status Word)

The window status word serves a dual purpose. First, it allows the .CRAW request to create a window and map it to a region in one step when you put a value of 1 in bit 8. Second, the window status word allows the monitor to communicate status information to your program. (WSW_TAB) shows the bits in the window status word and their meaning. Bits 0 through 7 and 9 through 12 are reserved for future use by DIGITAL.

(Window Status Word\WSW_TAB) (#) (4\6\8\8) (Bit\Name\Pattern\Meaning When Set) (#8\WS.MAP\###400\The .CRAW request should also map the new window in addition to creating it. Set this bit in the window definition block by specifying it in the .WDBBK macro. Be sure to load W.NRID before using .CRAW.) (13\WS.ELW\#20000\The monitor eliminated one or more windows as a result of the current operation. The .CRAW and .ELAW routines can set this bit.) (14\WS.UNM\#40000\The monitor unmapped one or more windows as a result of the current operation. The .CRAW and .ELAW routines can set this bit. The .MAP and .UNMAP routines set or clear this bit, as required.) (15\WS.CRW\100000\The monitor created this window successfully. The .CRAW routine sets this bit; the .ELAW routine clears it.) (.WDBDF Macro)

Use the .WDBDF macro to define symbols for the window definition block (see the description of .WDBBK in (WDBBK_SEC)). It defines the symbolic offset names for the window definition block and the names for the window status word bit patterns. In addition, this macro also defines the length of the window definition block by setting up the following symbol: W.NLGH = 16

Note that the .WDBDF macro does not reserve any space for the window definition block.

The format of the .WDBDF macro is as follows: .WDBDF

The .WDBDF macro expands as follows: W.NID = 0 W.NAPR = 1 W.NBAS = 2 W.NSIZ = 4 W.NRID = 6 W.NOFF = 10 W.NLEN = 12 W.NSTS = 14 W.NLGH = 16 WS.CRW = 100000 WS.UNM = 40000 WS.ELW = 20000 WS.MAP = 400 (.WDBBK Macro\WDBBK_SEC)

The .WDBBK macro (like the .WDBDF macro) defines symbols for the window definition block. This macro also actually reserves space for it (unlike the .WDBDF macro). The macro permits you to specify enough information about the window to simply create it. Or you can use the optional arguments to provide more information in the window definition block. The extra information allows you to create a window and map it to a region by issuing just the .CRAW programmed request. If you use .WDBBK you need not use .WDBDF, since .WDBBK automatically invokes .WDBDF.

The format of the .WDBBK macro is as follows: .WDBBK wnapr,wnsiz[,wnrid,wnoff,wnlen,wnsts]

where: (wnapr) is the number of the Active Page Register set that includes the window's base address. Remember that a window must start on a 4K-word boundary. See (APRANDVA_TAB) for the correspondence between Active Page Registers and virtual addresses. The valid range of values is from 0 through 7. (wnsiz) is the size of this window. Express it in 32-word decimal units. (wnrid) is the identification for the region to which this window maps. This argument is optional. It is usually filled in at run time, rather than at assembly time. (wnoff) is the offset into the region at which to start mapping this window. Express it in 32-word decimal units. This argument is optional; supply it if you need to map this window. The default is 0, which means that the window starts mapping at the region's base address. (wnlen) is the amount of this window to map. Express it in 32-word decimal units. This argument is optional; supply it if you need to map this window. The default value is 0, which maps as much of the window as possible. (wnsts) is the window status word. This argument is optional; supply it if you need to map this window when you issue the .CRAW request. Set bit 8, called WS.MAP, to cause .CRAW to perform an implied mapping operation.

The example in (WDBBK_FIG) uses the .WDBBK macro to create a window definition block. First it establishes a convention for expressing K-words in units of 32 decimal words each. Then it defines the window definition block, creates the window, and maps the window to a region.

The macro call sets up a window definition block for a window that is 2K words long. The window begins at address 120000, so Active Page Register set 5 controls its mapping. The .CRAW request to create this window will also map it to an area in extended memory. The window will map to the region starting 2K words from the beginning of the region, and the .CRAW request will map as much of the window as possible. Note that the program must move the region identification into this block to select the correct region before it issues the .CRAW request.

(.WDBBK Macro Example\WDBBK_FIG) .MCALL .WDBBK, .RDBBK, .CRRG, .CRAW, .EXIT KMMU= 1024./32. ;1K in 32-word units START: .CRRG #AREA,#RGADR ;Create a region ; . ; . ; . MOV RGADR+R.GID,WNADR+W.NRID ;Move region ;ID to window definition ;block .CRAW #AREA,#WNADR ;Create a window and map it ; . ; . ; . .EXIT ;Exit program RGADR: .RDBBK 2*KMMU ;Region definition block WNADR: .WDBBK 5,2*KMMU,2*KMMU,0,0,WS.MAP ;Window ;definition block AREA: .BLKW 2 ;EMT area .END START (Window Control Block)

The window control block is a seven-word area in your job's impure area whose contents are maintained by the monitor. A virtual job dedicates one window control block to the static window. For a privileged job, one window control block is reserved by the monitor and cannot be used by a program. Thus, all jobs can have up to seven dynamic windows whose status is maintained by the monitor in the window control blocks. (WCB_FIG) and (WCB_TAB) show the structure of a window control block.

(Window Control Block\WCB_FIG) ---------------------- | W.BRCB | |--------------------| | W.BLVR | |--------------------| | W.BHVR | |--------------------| | W.BSIZ | |--------------------| | W.BOFF | |--------------------| | W.BNPD | W.BFPD | |--------------------| | W.BLPD | |--------------------|

(Window Control Block\WCB_TAB) (#) (4\6\8\16) (Offset\Symbol\Modifier\Contents) (#0\W.BRCB\Monitor's .MAP routine; the .UNMAP request clears it\A pointer to the region control block of the region to which this window is mapped. If the value is 0, the window is not mapped.) (#2\W.BLVR\Monitor's .CRAW routine\The window's low virtual address limit.) (#4\W.BHVR\Monitor's .MAP routine.\The window's high virtual address limit.) (#6\W.BSIZ\Monitor's .CRAW routine; the .ELAW request clears it\The window's size, in 32-word decimal units. If the value is 0, this window control block is free.) (10\W.BOFF\Monitor's .MAP routine\The offset into the region at which this window begins to map, in 32-word decimal units.) (12\W.BFPD\Monitor's .CRAW routine\ The low byte of the address of the first Page Descriptor Register that affects this window.) (13\W.BNPD\Monitor's .MAP routine\The number of Page Descriptor Registers that affect this window.) (14\W.BLPD\Monitor's .MAP routine\The contents of the last Page Descriptor Register that affects this window.) (I/O Queue Element)

The I/O queue element in an extended memory system is ten words long, rather than seven words long as it is in FB and SB systems. (Make this a symbolic reference) Section 7.9.3 describes the XB/XM I/O queue element in detail. (Free Memory List)

The monitor maintains a data structure called the free memory list, which it uses to allocate areas of extended memory. The list consists of a table of 10 decimal doublewords. The address of the top of the table is $XMSIZ, and the table is located in p-sect XMSUBS. The high-order word of each word pair indicates the size of an available area in extended memory, expressed as a number of 32-word decimal units. The low-order word of the pair contains the address of the area, divided by 100 octal. A value of -1 ends the table.

At bootstrap time, the table contains only one entry. The high-order word of the pair contains the total amount of extended memory. The low-order word contains the value 1600. When a job requests an extended memory region, the monitor searches through the table for an area large enough to meet the request. It returns the area in extended memory that meets the size requirement and has the lowest starting address. The monitor reduces the amount of memory in the first doubleword of the free memory list, and adjusts its starting address.

The other nine words of the free memory list are used when jobs return areas of extended memory to the available pool. In a very active system, the extended memory area can become quite fragmented. (Flow Of Control Within Each Programmed Request)

This section summarizes the activities that take place internally for each programmed request your program can issue. Consult the (PRM_BOOK) for the detailed syntax of each request. (Creating A Local Region: .CRRG)

Issue the .CRRG programmed request to create a local region in physical address space.

The monitor's .CRRG routine first checks R.GSIZ in the region definition block to make sure that you have requested a region with a valid size. (The size must be between 1 and 96K.) If the size is invalid, the request returns with error code 10 in byte 52.

Next, the routine looks for a free region control block. The request returns with error code 6 in byte 52 if no region control blocks are free.

The routine attempts to allocate the appropriate amount of memory for the region, based on the amount you specified in the programmed request. To get the most memory possible, ask for 96K words. The routine scans the free memory list for a region with the correct size. The request returns with error code 7 in byte 52 if it cannot allocate a region with the size you requested. In addition, R0 contains the largest amount of memory available. Issue the .CRRG request again for this amount of memory. If this second request fails in the multi-job XM system, it means that some other job in the system just acquired some of the memory. Continue to reissue the .CRRG request with the new value from R0 until you finally obtain a region.

The request succeeds when the monitor allocates the region. The routine puts the region identification into R.GID in the region definition block. It sets RS.CRR in the region status word; it clears R.BSTA and R.BNWD in the region control block, and it puts values into R.BADD and R.BSIZ, which are also located in the region control block. The memory obtained is then removed from the monitor's free memory list and reserved for your job. (Creating And Attaching To A Global Region\CRAT_SEC)

Issue the .CCRG programmed request to create a global region in physical address space and attach to it.

There is no limit to the size of a global region other than available physical (extended) memory.

When a program creates and attaches to a global region, the program has sole possession of the global region. This exclusive use is indicated by the setting of bit 7 in the global region's control block (GR.SHC).

To make the global region available for attachment by other programs in a multi-job XM system, the program must detach from the global region with a .ELRG request. Detaching from a global region clears bit 7 of the control block GR.SHC byte. A program wishing to create and attach to a global region and make the global region available to other programs must execute a .ELRG request and then execute a .CRRG request to reattach to the global region.

In a single background job XB system, global regions are shared sequentially. If programs are to share a global region in an XB system, the job that creates the globl region must insure that the region is not automatically eliminated when the job exits. Subsequent jobs can then attach to the job and use it. (Attaching To An Existing Global Region)

The procedure for attaching to a global region is the same as the procedure for creating a global region, except that you should not specify the RS.CGR symbol in the status argument of the .RDBBK macro. The following shows the form of the .RDBBK macro for attaching to the global region created in the example shown in (CRAM_SEC). REGION: .RDBBK 4096./32.,,NAME=MYDATA

When a program attaches to a global region, RT--11 creates a local region within the global region. The area requested for the attached local region is taken from the memory allocated to the global region, not from the free memory list. The local region is attached to the global region at the base address of the global region. RS.CRR (bit 15 of status word R.GSTS in the global region definition block) is set.

In a multi-job XM system, a program cannot attach to a global region unless the program that created the global region has detached from it.

Specifying 0 for R.GSIZ (byte offset 2 of the region definition block) attaches a program to all memory allocated to an existing global region. The global region must have been previously created by another program or at boot time. Attempts to attach in this manner to a local region, or to a global region not previously created, returns error code 10 (octal), and RS.CRR is cleared.

Attempting to attach to a local region larger than the global region returns octal error code 7. Attempting to attach to a nonexistent global region returns octal error code 12. Either case clears RS.CRR.

Attaching a local region to a global region increments the count of attachments for that global region kept in GR.SHC (byte 5 in the global region control block). The reference count in GR.SHC controls automatic global elimination (see (AGE_SEC)). (Detaching From A Global Region)

Issue the .ELRG macro to detach a local region from a global region, in the same manner as you use it to eliminate a local region. Memory allocated to the local region within the global region is retained by the global region and is not returned to the free memory list.

The following example illustrates detaching the local region attached in the example shown in (CRAM_SEC). .ELRG #AREA,#REGION . . . REGION: .RDBBK 4096./32.,,NAME=MYDATA

Detaching a local region from a global region decrements the count of attachments for that global region kept in GR.SHC (byte 5 in the global region control block). In a multi-job XM system, The reference count in GR.SHC controls automatic global elimination (see (AGE_SEC)). (Creating A Window: .CRAW)

Issue the .CRAW programmed request to create a virtual address window.

First, the monitor's .CRAW routine checks W.NAPR in the window definition block for a valid value. The request returns with error code 0 in byte 52 if the number of the Active Page Register set is invalid for any reason.

Next, the routine shifts W.NAPR to set up the window's base address in W.NBAS, which is also located in the window definition block.

The routine then checks W.NSIZ in the window definition block to make sure that you requested a valid size for the window (the window cannot exceed the 32K-word boundary). If there is any problem with the size, the request returns with error code 0 in byte 52.

The routine clears bits WS.ELW, WS.UNM, and WS.CRW in the window status word.

The next check is to see if the new window will overlap with an existing window. If the job is a virtual job and the new window overlaps with the static window, the request returns with error code 0. In all other situations where the new window overlaps an existing window, the routine eliminates the existing window. If the existing window is mapped, the routine unmaps it. The .CRAW routine sets WS.ELW in the window status word if it eliminates a window to create the new one. It sets WS.UNM if it also unmaps a window as it eliminates it.

Next, the routine looks for an available window control block. The request returns with error code 1 if there are no free window control blocks.

The request succeeds when the monitor modifies the appropriate data structures. It puts values in W.BSIZ, W.BLVR, and W.BFPD in the window control block; it puts the window identification in W.NID in the window definition block, and it sets WS.CRW in the window status word.

If WS.MAP in the window status word was set when you issued the .CRAW request, the routine now maps the window to the region whose identification is stored in the window definition block. To do this, the routine follows the steps outlined in the .MAP programmed request. (Mapping A Window To A Region: .MAP)

Issue the .MAP programmed request to map a virtual address window to a physical address region. The window definition block must contain the identification of the region to which the window will map.

First, the monitor's .MAP routine finds the window control block that corresponds to the window you specify in the request. It checks W.NID to do this, and returns with error code 3 if the value is 0 or not valid.

Next, the routine finds the region control block for the region to which this window will map. The request returns with error code 2 if the region identification is invalid for any reason.

The routine looks at the offset into the region at which the window is to begin mapping. This value is contained in W.NOFF in the window definition block. If the offset is beyond the end of the region, the request returns with error code 4.

The routine checks the length of the window it is to map. This value is contained in W.NLEN in the window definition block. If the value is 0, the routine picks up the size of the region from the offset value to the end of the region. If this amount of memory is bigger than the window, the routine reduces the amount until it equals the window size, which it stores in W.NLEN. Note that if you put 0 into W.NLEN, the value that is there after the .MAP request executes is not 0, but is instead the actual length of the window that was mapped.

If the value of W.NLEN is not 0 at the start of the .MAP routine, it indicates the explicit length of the window to map. If the value is larger than the window size, or if the window would extend beyond the bounds of the region, the request returns with error code 4.

The routine increments R.BNWD in the region control block, which maintains a count of the number of windows mapped to this region.

If this window is already mapped elsewhere, this routine unmaps it and sets WS.UNM in the window status word; otherwise, this routine clears WS.UNM.

The routine next loads the user mode Active Page Register set with the correct values to map this window to this region.

Finally, the routine updates the window control block values W.BRCB, W.BHVR, W.BOFF, W.BNPD, and W.BLPD. (Getting The Mapping Status: .GMCX)

Issue the .GMCX programmed request to obtain the current mapping status of a particular virtual address window.

First, the .GMCX monitor routine looks at the corresponding window control block for this window. If you specify a window whose identification is 0, you obtain the status of the static window for a virtual job. There is no window with the identification of 0 in a privileged job. If there is any problem with the window, the request returns with error code 3.

The routine sets W.NAPR in the window definition block to be equal to the top three bits of W.BLVR in the window control block. This sets up the starting Active Page Register set number.

Next, the routine puts values into W.NBAS, W.NSIZ, and W.NRID in the window definition block.

If the window is not currently mapped, the routine clears W.NOFF, W.NLEN, and W.NSTS in the window definition block. If the window is mapped, the routine puts the offset into the region in W.NOFF, puts the length of the window in W.NLEN, and sets the bit WS.MAP in the window status word. (Unmapping A Window: .UNMAP)

Issue the .UNMAP programmed request to explicitly unmap a window from a region.

First, the monitor's .UNMAP routine finds the appropriate window control block. It checks W.NID in the window definition block. If the value is 0, or if it is invalid for any reason, the request returns with error code 3. If the window is not currrently mapped, the request returns with error code 5.

To unmap the window, the routine modifies the appropriate data structures. It clears W.BRCB in the window control block, and decrements R.BNWD in the region control block.

If the job is virtual, the routine clears the Page Descriptor Registers that correspond to this window so that your program can no longer reference the virtual addresses in this window.

If the job is privileged, the monitor copies the kernel Page Descriptor Register values into the user Page Descriptor Registers so that the mapping defaults to that of kernel mode.

Finally, the routine sets WS.UNM in the window status word. (Eliminating A Local Region: .ELRG)

Issue the .ELRG programmed request to eliminate a physical address region.

First, the monitor's .ELRG routine checks to see if the region identification you specified is 0. In a virtual job, a region identification of 0 indicates the static region, which you cannot eliminate. In a privileged job, there is no region whose identification is 0. In either case, the request returns with error code 2.

Next, the routine looks for the corresponding region control block for this region. If the region identification is invalid for any reason, the request returns with error code 2.

Then, the routine clears RS.CRR and RS.UNM in the region status word. If there are any windows mapped to this region, the routine unmaps them and sets RS.UNM.

The routine deallocates the region by returning its physical address space to the monitor's list of free memory.

Finally, the routine clears the region control block. (Eliminating A Global Region)

Issue the .ELRG macro to eliminate a global region. Specify the status argument RS.EGR in the .RDBBK macro.

The following example eliminates the global region created by the example in (CRAM_SEC). .ELRG #AREA,#REGION . . . REGION: .RDBBK 4096./32.,,NAME=MYDATA

Eliminating a global region returns the memory allocated to the global region to the free memory list.

Observe the following when you eliminate a global region: (UNNUMBERED) Your program must be attached to a global region to eliminate it. The same global region definition block used to create a global region is normally used to eliminate it. Permanent global regions cannot be eliminated. In a multi-job XM system, attempting to eliminate a global region that is in use by another job returns error code 14 (octal). The global region is not eliminated, but the program requesting the elimination is detached. (Automatic Global Region Elimination (XM Only)\AGE_SEC)

When you create a global region for use by a number of programs in a multi-job XM system, you can use the automatic global region elimination feature (AGE) to automatically eliminate the global region when the last program has finished using it.

Specify the .RDBBK status argument RS.AGE when you create the global region. As explained in (CRAT_SEC), a program that has created a global region has sole possession of that region (bit 7 of GR.SHC is set). To make the global region available to other programs, the program must clear that bit by detaching with a .ELRG request. Automatic global elimination is turned on when the next program attaches to the global region.

As programs attach and detach local regions, a reference count is incremented and decremented in GR.SHC (byte 5) in the global region control block. AGE tracks the value in GR.SHC. When the value in GR.SHC is 0, AGE automatically eliminates the global region. The allocated memory is returned to the free memory list. (Eliminating A Window: .ELAW)

Issue this programmed request to eliminate a virtual address window.

As with the .ELRG request, the .ELAW routine first finds the corresponding window control block for this window. It checks W.NID in the window definition block. If the window identification is 0, or is not valid for any reason, the request returns with error code 3.

The routine next clears WS.CRW and WS.UNM in the window status word. If the window was mapped, the routine unmaps it and sets WS.UNM. The routine eliminates the window by clearing W.BSIZ in the window control block. Finally, the routine sets WS.ELW in the window status word. (Summary Of Extended Memory Programmed Request Error Codes)

(XMERRCOD_TAB) summarizes the error codes that the extended memory programmed requests can put into byte 52. (ERRCODSUM_TAB) shows which error codes each programmed request can use.

(Extended Memory Programmed Request Error Codes and Meanings\XMERRCOD_TAB) (#) (2\6) (Byte 52\Meaning) (#0\There is a problem with the window ID. The window is too large, the value of W.NAPR is greater than 7, or you specified it incorrectly.) (#1\You tried to create more than seven windows in your program. Remember that the static window is always defined for a virtual job, and one window is always reserved by the monitor in a privileged job. You can either unmap another window and then try to create a window, or you can redefine your virtual address space into fewer windows.) (#2\The region identification was invalid for some reason.) (#3\The window identification was invalid for some reason.) (#4\The combination of the offset into the region and the size of the window to map to the region is invalid.) (#5\The window you specified was not currently mapped.) (#6\You tried to create more than three regions in your program. Remember that the static region is always defined for a virtual job, and one region is always reserved by the monitor in a privileged job. You can eliminate another region and then try to create a new one, or you can redefine your physical address space into fewer regions. Note that extended memory overlays and XM .SETTOP account for one region each.) (#7\There is not enough memory available to create a region as large as the one you requested. The routine returns the size of the largest available region in R0, but does not create it.) (10\You specified an invalid size for a region. A value of 0 or a value greater than 96K words is invalid.) (Summary of Error Codes\ERRCODSUM_TAB) (#) (2\10) (Programmed Request\#########Error Code 0###1###2###3###4###5###6###7###10) (.CRRG \########################X###X###X) (.CRAW \X###X) (.MAP \########X###X###X) (.GMCX \############X) (.UNMAP\############X######X) (.ELRG \########X) (.ELAW \############X) (Restrictions And Design Implications)

The manner in which RT--11's support for extended memory is implemented imposes some restrictions on the ways you can use the system. The following sections outline the implications of the design of the extended memory system. (PAR1 Restriction)

The RT--11 monitor sometimes (borrows) kernel Page Address Register 1 for its own use. For example, it uses PAR1 to map to the EMT area blocks when it processes a programmed request.

Because the monitor alters kernel PAR1, references to virtual addresses in the range 20000 through 37777 do not always access the corresponding physical addresses. To avoid problems due to the occasional remapping of the virtual addresses controlled by kernel PAR1, observe the following programming restrictions. (NUMBERED) Any channel areas you allocate with the .CDFN programmed request must be entirely within the low 28K words of memory. In addition, they must not be located within the addresses 20000 through 37777. Any queue elements you allocate with the .QSET programmed request must be entirely within the low 28K words of memory. In addition, they must not be located within the addresses 20000 through 37777. Remember to allow 10 decimal words per queue element. Interrupt service routines must be located entirely within the low 28K words of memory. In addition, if your XB or XM monitor has been generated without .FETCH support, they must neither reside in nor reference addresses in the range 20000 through 37777. (Make this a symbolic reference) Section 6.7 describes the factors you must take into consideration if your program includes an in-line interrupt service routine. Be sure to execute your program as a privileged job if it contains an interrupt service routine, so that it can access the monitor and the device I/O page. (Make this a symbolic reference) Section 7.9 lists the implications of the XM design restrictions on device handlers and I/O.

This aspect of RT--11's design is important for you to understand if you have a program with its own in-line interrupt service routine, if you put a data buffer for I/O in extended memory, or if you write a device handler for an XM system. (Programmed Requests)

Some of the RT--11 programmed requests have special restrictions when you use them in an extended memory system. These requests and their restrictions are as follows:

(2\12) (Programmed Request\Restriction) (.CDFN\The channel area you specify in this request must be entirely within the low 28K words of memory.) (.QSET\The queue element space you specify must be entirely within the low 28K words of memory. In addition, you must allow 10 decimal words for each queue element. ) (.CNTXSW (XM only)\Virtual jobs cannot use this request, since they have no need for it in an extended memory system.) (PAR2 Restriction (XM Only))

The MQ message handler uses Page Address Register 2. If you use the MQ handler to send and receive messages in the multi-job XM system, be sure to read (MSGHAND_SEC). If the MQ handler was built with the conditinal assembly symbol MQH$P2 set qual to 1, MQ will use kernel PAR2 to map the user buffers. In that case, all the PAR1 restrictions apply as well to the virtual addresses in the range 40000 through 57777, controlled by PAR2. Therefore, the USR, queue elements, channels, and interrupt service routines cannot reside within locations 20000 through 57777 (kernel PARs 1 and 2) in a system that is actively using the MQ handler. Note that the QUEUE program uses the MQ handler. (Synchronous System Traps)

A synchronous system trap is a software interrupt that takes place synchronously with your program's execution. For example, a TRAP instruction that a program issues is a synchronous system trap. A program that issues an illegal instruction causes a trap to 10 to occur, which is also a synchronous system trap. When a trap occurs, the PDP-11 computer pushes the current PS and PC onto the stack and loads the new PS and PC from the contents of the trap vector. (SST_TAB) lists the synchronous system traps and their corresponding vectors.

(Synchronous System Traps and Their Vectors\SST_TAB) (#) (2\6) (Vector\Synchronous System Trap) (##4\Trap to 4, caused by a reference to an odd address, or by a bus time-out.) (#10\Trap to 10, caused by an attempt to execute a reserved instruction.) (#14\Breakpoint trap, usually issued by a debugging utility program such as ODT.) (#20\I/O trap.) (#34\TRAP instruction, issued by a program to change the flow of execution.) (114\Memory parity trap, caused by a memory parity error.) (244\FPU trap, caused by a floating point unit exception or error.) (250\Memory management trap, caused by a program's attempt to reference a virtual address that is not mapped to a physical address.)

In an extended memory system, synchronous system traps, like device interrupts, take the new PS and PC from the appropriate vector in kernel space. For example, when a program issues a BPT instruction, the new PS and PC are taken from physical locations 14 and 16. As you remember, a privileged job is initially mapped to the kernel vector area, so virtual address 14 in the program maps to physical location 14. A virtual job, on the other hand, is prevented from accessing the kernel vector area. Initially, the virtual job's virtual vector area maps to physical addresses starting at location 500, not 0. For a virtual job then, the virtual vector 14 is not in physical location 14.

For each synchronous system trap, RT--11 provides a mechanism to field the trap and provide values for the new PS and PC from the virtual vector. The following sections describe the effect of the extended memory environment on specific synchronous system traps. (TRAP, BPT, And IOT Instructions)

When a program in an extended memory system issues a TRAP, BPT, or IOT instruction, execution switches to the processor's kernel mode. The hardware picks up the contents of the appropriate vector (see Table (SST_TAB\VALUE) from kernel space. However, rather than dispatching immediately to the trap handling routine specified in the kernel vector, the monitor replaces the new PS and PC with values that cause execution to continue within a monitor routine. The purpose of the monitor routine is to pick up the contents of the corresponding virtual vector in user space, and then transfer control to the routine specified by the virtual PC. The kernel and user vectors for a privileged job are identical. A virtual job cannot access the kernel vectors; you can, however, put values into the virtual vectors so that the monitor will pick them up when a trap occurs. In summary, the net effect of the monitor's trap handling routine is that control is transferred to a job's specific trap routine through the contents of the job's virtual vector.

If the virtual vector contains an even, nonzero value, the monitor does not clear the vector after the first trap. This permits recursion with no effort on the part of the program. (Traps To 4 And 10, And FPU Traps)

For traps to 4 and 10, and floating point unit exception traps, the monitor provides a mechanism that protects the vectors while still permitting you to use your own trap handling routines. The .TRPSET and .SFPA programmed requests permit your program to set up the addresses of trap handling routines without modifying either the kernel or the user virtual vector area. These two programmed requests function in extended memory systems the way they do in FB systems. Thus, you specify the address of your trap handling routine when you issue the programmed request and the monitor puts this information in the job's impure area. The monitor clears out the routine address in the impure area, so your trap handling routine should reset this area by issuing either .TRPSET or .SFPA as its last instruction before returning to the main program. (Memory Management Faults)

A memory management fault occurs when a program references a virtual address that is not mapped to a physical address. If a memory management fault occurs while execution is in system state, the entire system halts. If a memory management fault occurs while execution is in user state, the monitor fields the trap through the kernel vector and provides a new PS and PC from the user virtual vector area. Once the monitor picks up the contents of a job's virtual vector, it clears the vector. If a second fault occurs and the virtual vector is 0, the monitor prints its (?MON-F-MMU fault) message and aborts the job.

To permit recursion, your program's trap handling routine must reset the contents of the memory management fault vector (at locations 250 and 252) in the job's virtual vector area. If RT--11 permitted automatic recursion, your program could loop indefinitely on a memory management fault until you halted the processor. (Memory Parity Errors)

A hardware device that is an optional part of your PDP-11 computer system performs memory parity checking. You enable RT--11 support of this hardware option by selecting the memory parity special feature at system generation time. If you have memory parity hardware but do not generate a system with the memory parity checking special feature, a memory parity error causes a system halt.

For systems that support memory parity checking, the synchronous system trap procedure is similar to the procedure for memory management faults. Thus, the monitor fields the trap through the kernel vector at locations 114 and 116. It then picks up the contents of your program's virtual addresses 114 and 116, clears them, and passes control to your trap handling routine based on the new PS and PC.

If a second memory parity error occurs and the virtual vector is 0, the message (?MON-F-Mem err )prints and the job aborts. To enable recursion, your program's trap handling routine must reset the contents of the memory parity fault vector at virtual addresses 114 and 116. (Debugging An Extended Memory Application)

Use VDT, the Virtual Debugging Technique, to debug virtual and privileged jobs in an XB or XM system. VDT also handles correctly jobs in FB and SB systems, as well as jobs in multi-terminal systems.

Use VDT.OBJ the same way you use ODT.OBJ; link it with the program you need to debug. The transfer address for VDT is O.ODT. The syntax for VDT commands is the same as the syntax for ODT. See the (SUM_BOOK) for instructions on using ODT.

VDT.OBJ is created from a conditional assembly of ODT.MAC, with the conditional $VIRT equal to 1. VDT.OBJ is provided on the distribution kit; you need not assemble it yourself. VDT does not contain the interrupt service or priority routines that ODT does. Unlike ODT, which runs at priority 7 and performs its own terminal I/O, VDT runs at the same priority as your program, and uses .TTYIN and .TTYOUT programmed requests to perform terminal I/O.

Because VDT uses .TTYIN and .TTYOUT requests, you can run it from a job's console terminal; it is not limited to the hardware console interface. Since VDT alters the contents of the Job Status Word, it must save the original contents elsewhere. You can use the $J/ command to obtain the original contents of the JSW; you can also modify it there.

VDT runs in user, not in kernel mode. When you debug a virtual job with VDT, you are limited to accessing the job's area only. You cannot access the protected system areas such as the monitor, the vectors, and the I/O page. When you debug a privileged job with VDT, you have access to the same memory the job does. (Extended Memory Example Program)

(XMCOPY_FIG) provides an example program that uses extended memory programmed requests. This example assumes that any necessary handlers are already loaded.

(Extended Memory Example Program\XMCOPY_FIG) (\MULTIPAGE) .TITLE XMCOPY ;+ ; THIS IS AN EXAMPLE IN THE USE OF THE RT--11 EXTENDED ; MEMORY REQUESTS. THE PROGRAM COPIES FILES AND THEN ; VERIFIES THE RESULTS. IT USES EXTENDED MEMORY TO ; IMPLEMENT 4K TRANSFER BUFFERS. THIS PROGRAM USES MOST ; OF THE EXTENDED MEMORY PROGRAMMED REQUESTS, AND ; DEMONSTRATES OTHER PROGRAMMING TECHNIQUES. ;- .NLIST BEX .MCALL .UNMAP,.ELRG,.ELAW,.CRRG,.CRAW,.MAP .MCALL .PRINT,.EXIT,.CLOSE,.CSIGEN,.READW,.WRITW .MCALL .RDBBK,.WDBBK,.TTYOUT,.WDBDF,.RDBDF JSW = 44 ;JSW LOCATION J.VIRT = 2000 ;VIRTUAL JOB BIT IN JSW ERRBYT = 52 ;ERROR BYTE LOCATION APR = 2 ;PAR/PDR FOR 1ST WINDOW APR1 = 4 ;PAR/PDR FOR 2ND WINDOW BUF = WDB+W.NBAS ;VIRTUAL ADDR OF 1ST ; BUFFER BUF1 = WDB1+W.NBAS ;VIRTUAL ADDR OF 2ND ; BUFFER CORSIZ = 4096. ;SIZE OF BUFFER IN WORDS PAGSIZ = CORSIZ/256. ;PAGE SIZE IN BLOCKS WRNID = WDB+W.NRID ;REGION ID ADDR OF 1ST ; REGION WRNID1 = WDB1+W.NRID ;REGION ID ADDR OF 2ND ; REGION .ASECT ;ASSEMBLE IN THE VIRTUAL ; JOB BIT .= JSW .WORD J.VIRT ;MAKE THIS A VIRTUAL JOB .PSECT ;START CODE NOW .WDBDF ;CREATE WINDOW DEFINITION ; BLOCK SYMBOLS .RDBDF ;CREATE REGION DEFINITION ; BLOCK SYMBOLS START:: .CSIGEN #ENDCRE,#DEFLT,#0 ;GET FILESPECS, ; HANDLERS, OPEN FILES BCS START ;BRANCH IF ERROR INCB ERRNO ;ERR = 1X .CRRG #CAREA,#RDB ;CREATE A REGION BCC 10$ ;BRANCH IF SUCCESSFUL JMP ERROR ;REPORT ERROR ; (JMP DUE TO RANGE!) 10$: MOV RDB,WRNID ;MOVE REGION ID TO WINDOW ; DEFINITION BLOCK INCB ERRNO ;ERR = 2X .CRAW #CAREA,#WDB ;CREATE WINDOW... BCC 20$ ;BRANCH IF NO ERROR JMP ERROR ;REPORT ERROR... 20$: INCB ERRNO ;ERR = 3X .MAP #CAREA,#WDB ;EXPLICITLY MAP WINDOW... BCC 30$ ;BRANCH IF NO ERROR JMP ERROR ;REPORT ERROR 30$: CLR R1 ;R1 = RT11 BLOCK # ; FOR I/O MOV #CORSIZ,R2 ;R2 = # OF WORDS TO READ INCB ERRNO ;ERR = 4X READ: .READW #RAREA,#3,BUF,R2,R1 ;TRY TO READ 4K-WORTH ; OF BLOCKS BCC WRITE ;BRANCH IF NO ERROR TSTB @#ERRBYT ;EOF? BEQ PASS2 ;BRANCH IF YES JMP ERROR ;MUST BE HARD ERROR, ; REPORT IT WRITE: MOV R0,R2 ;R2 = SIZE OF BUFFER ; JUST READ .WRITW #RAREA,#0,BUF,R2,R1 ;WRITE OUT THE BUFFER BCC ADDIT ;BRANCH IF NO ERROR INCB ERRNO ;ERR = 5X JMP ERROR ;REPORT ERROR ADDIT: ADD #PAGSIZ,R1 ;ADJUST BLOCK # BR READ ;THEN GO GET ANOTHER ; BUFFER PASS2: INCB ERRNO ;ERR = 6X .CRRG #CAREA,#RDB1 ;CREATE A REGION BCC 35$ ;BRANCH IF NO ERROR JMP ERROR ;REPORT ERROR 35$: MOV RDB1,WRNID1 ;GET REGION ID TO WINDOW ; DEFINITION BLOCK ;* EXAMPLE USING THE .CRAW REQUEST DOING * ;* IMPLIED .MAP REQUEST. * INCB ERRNO ;ERR = 7X .CRAW #CAREA,#WDB1 ;CREATE WINDOW USING ; IMPLIED .MAP BCC VERIFY ;BRANCH IF NO ERROR JMP ERROR ;REPORT ERROR VERIFY:: INCB ERRNO ;ERR = 8X CLR R1 ;R1 = RT11 BLOCK # AGAIN GETBLK: MOV #CORSIZ,R2 ;R2 = 4K BUFFER SIZE .READW #RAREA,#3,BUF1,R2,R1 ;TRY TO GET 4K-WORTH ; OF INPUT FILE BCC 40$ ;BRANCH IF NO ERROR TSTB @#ERRBYT ;EOF? BEQ ENDIT ;BRANCH IF YES JMP ERROR ;REPORT HARD ERROR 40$: MOV R0,R2 ;R2 = SIZE OF BUFFER READ .READW #RAREA,#0,BUF,R2,R1 ;TRY TO GET SAME SIZE ; FROM OUTPUT FILE BCC 50$ ;BRANCH IF NO ERROR INCB ERRNO ;ERR = 9X JMP ERROR ;REPORT ERROR 50$: MOV BUF,R4 ;GET OUTPUT BUFFER ADDRESS MOV BUF1,R3 ;GET INPUT BUFFER ADDRESS 70$: CMP (R4)+,(R3)+ ;VERIFY THAT DATA IS THE ; SAME BNE ERRDAT ;IT'S NOT, REPORT ERROR DEC R2 ;ARE WE FINISHED? BNE 70$ ;BRANCH IF WE AREN'T ADD #PAGSIZ,R1 ;ADJUST BLOCK # FOR PAGE ; SIZE BR GETBLK ;GO GET ANOTHER BUFFER ; PAIR ENDIT: .PRINT #ENDPRG ;ANNOUNCE WE'RE FINISHED XCLOS: .CLOSE #0 ;CLOSE OUTPUT FILE .UNMAP #CAREA,#WDB ;EXPLICITLY UNMAP 1ST ; WINDOW .ELAW #CAREA,#WDB ;EXPLICITLY ELIMINATE 1ST ; WINDOW .ELRG #CAREA,#RDB ;ELIMIMATE 1ST REGION .ELRG #CAREA,#RDB1 ;UNMAP, ELIMINATE 2ND ; WINDOW & REGION .EXIT ;EXIT PROGRAM ERROR: MOVB @#ERRBYT,R0 ;MAKE ERROR BYTE CODE ; 2ND DIGIT ADD #'0,R0 ;OF ERROR CODE... MOVB R0,ERRNO+1 ;PUT IT IN ERROR MESSAGE .PRINT #ERR ;PRINT IT... BR XCLOS ;GO CLOSE OUTPUT FILE ERRDAT: .PRINT #ERRBUF ;REPORT VERIFY FAILED... BR XCLOS ;GO CLOSE OUTPUT FILE RDB: .RDBBK CORSIZ/32. ;.RDDBK DEFINES REGION ; DEFINITION BLOCK WDB: .WDBBK APR,CORSIZ/32. ;.WDDBK DEFINES WINDOW ; DEFINITION BLOCK RDB1: .RDBBK CORSIZ/32. ;DEFINE 2ND REGION SAME ; WAY WDB1: .WDBBK APR1,CORSIZ/32.,0,0,CORSIZ/32.,WS.MAP ; AND 2ND WINDOW ; (BUT WITH MAPPING ; STATUS SET!) CAREA: .BLKW 2 ;EMT ARGUMENT BLOCKS RAREA: .BLKW 6 DEFLT: .WORD 0,0,0,0 ;NO DEFAULT FILE TYPES ENDPRG: .ASCIZ / * END OF XM EXAMPLE PROGRAM */ ERR: .ASCII /?XM REQUEST OR I-O ERROR # / ERRNO: .ASCIZ /00/ ERRBUF: .ASCIZ /?DATA VERIFICATION ERROR?/ ENDCRE = . ;FOR CSIGEN - XM ; HANDLERS LOADED ! .END START (Procedure To Create And Map A Global Region\CRAM_SEC)

The procedure in (CRAM_FIG) creates and maps to a global region in extended memory. (NUMBERED) From a program, issue a .CRRG programmed request pointing to a global region definition block. Specify the .RDBBK macro with a decimal value for R.GSIZ in the same manner as for a local region. Specify status arguments RS.GBL (attach to a global region) and RS.CGR (create a global region).

Specify status argument RS.AGE if you want to enable automatic global elimination in a multi-job XM system.

Specify a name for the created global region. After executing .CRRG, check RS.CRR (bit 15, region definition status word R.GSTS) for success. Digital recommends that if there is any possibility of a race condition (two programs attempting to attach at exactly the same time), include a .TWAIT request in your retry code in multi-job XM systems. Map to the created region in the same manner as you map to a region local to a program. Use the .CRAW and .MAP requests. Check RS.NEW (bit 12, region definition block) to confirm that the program did in fact create the global region, and is not attaching to an already created one. If required, load the global region with data. If you want to make the global region available to other programs at creation in a multi-job XM ssytem, execute a .ELRG request. Then reattach your program to the global region using .CRRG. If you want to make the global region private to your program, do not execute a .ELRG/.CRRG reattach sequence.

Successful creation of a global region sets RS.CRR and RS.NEW (bits 15 and 12 in global region definition block status word R.GSTS).

The following example, written for a multi-job XM system, creates and maps to a 4K word global region named MYDATA and (because of the .ELRG request with a back loop) allows other programs to attach to it.

(Creating and Mapping a Global Region\CRAM_FIG) (\MULTIPAGE) .MCALL .CRAW, .CRRG, .ELRG, .EXIT, .MAP, .TWAIT .MCALL .RDBBK, .WDBBK ERRBYT = 52 USERRB = 53 FATAL$ = 10 XE.PRV = 15 REGION: .RDBBK 4096./32.,,NAME=MYDATA WINDOW: .WDBBK 1,4096./32. TIME: .WORD 0,1.*60. ;1 second (60 ticks/second) AREA: .BLKW 6. ;Programmed request area ;+ ; The following four entry points are the error handlers for the ; PLAS directives. They may be expanded as is appropriate. ;- CRRGER: CRAWER: ELRGER: MAPERR: BISB #FATAL$,@#USERRB ;Indicate severe error ;to system .EXIT ; and exit START: .CRRG #AREA,#REGION ;Create a 4K word global ;region, (MYDATA) BCC 10$ ;Branch on success CMPB #XE.PRV,@#ERRBYT ;Is global region ;privately owned? BNE CRRGER ;If not, then goto ;.CRRG error handler .TWAIT #AREA,#TIME ;Wait a second BR START ;Try again ;+ ; We have now successfully allocated/created the (MYDATA) global ; region. Now map it to a window, initialize if necessary, and ; then use it. ;- 10$: MOV REGION+R.GID,WINDOW+W.NRID ;Put region ID in the WDB .CRAW #AREA,#WINDOW ;Create a window BCS CRAWER ;If error, go handle it .MAP #AREA,#WINDOW ;Map the window to the region BCS MAPERR ;If error, go handle it BIT #RS.NEW,REGION+R.GSTS ;Did we just create the ;global region? BEQ 30$ ;Branch if not ;+ ; We just created global region (MYDATA). We now initialize the ; region with zeros. ;- MOV #4096.,R0 ;Set up word count of 4K MOV WINDOW+W.NBAS,R1 ;Get virtual address ;of base of region 20$: CLR (R1)+ ;Clear a word SOB R0,20$ ; until we're done ;+ ; Now detach from global region (MYDATA) to make it shareable. ; Then loop back and reattach to global region (MYDATA). ;- .ELRG #AREA,#REGION ;Detach from global region BCS ELRGER ;Branch if there is an error BR START ;Go attach to global ;region (MYDATA) ;+ ; We are attached to a shareable global region. If we also created ; it, we have initialized the region as well. The following code can ; use global region (MYDATA) as it sees fit. ;- 30$: . . . .END START (End of Chapter)