Document revision date: 19 July 1999

The Reserved Memory Registry through its interface within the SYSMAN utility allows an OpenVMS Alpha system to be configured with large amounts of memory set aside for use within memory-resident sections and by other privileged applications. The Reserved Memory Registry also allows an OpenVMS system to be properly tuned through the AUTOGEN utility, taking into account the preallocated reserved memory.

With the Reserved Memory Registry you can:

• Reserve system non-fluid memory for the memory-resident global section fault option.
• Reserve pre-allocated, contiguous, aligned physical pages as well as system non-fluid memory for the memory-resident global section allocate option.

The Reserved Memory Registry includes the ability to specify that the pre-allocated pages are to be zeroed during the booting of the system. This option reduces the time required to create the memory-resident global demand-zero section.

Another option within the Reserved Memory Registry is to include the size of the page tables required to map to the memory-resident global section in the reserved memory. If this option is specified and the reserved memory is being used for a memory-resident global section, the memory-resident global section is created with shared page tables.

4.6.1 Using the Reserved Memory Registry

OpenVMS provides a mechanism to reserve non-fluid memory for use within a memory-resident global demand-zero section. The reserved memory may either be simply a deduction from the system's non-fluid memory size or also pre-allocated as contiguous, aligned physical pages.

Using the Reserved Memory Registry ensures that AUTOGEN tunes the system properly to not include memory-resident section pages in its calculation of the system's fluid page count. AUTOGEN sizes the system pagefile, number of processes and working set maximum size based on the system's fluid page count. A system can experience severe performance problems if AUTOGEN adjusts parameters based upon a fluid page count that does not account for the physical memory that is permanently reserved for some other purpose.

Using the Reserved Memory Registry also ensures that contiguous, aligned memory is available for memory-resident sections when the allocate option is used.

Consumers of reserved, non-fluid memory enter the characteristics of the memory into a data file that is read during the system initialization (boot-time). The mechanics of manipulating the data file are similar to SYS$LOADABLE_IMAGES:VMS$SYSTEM_IMAGES.DATA (indicates installation-specific executive loaded images).

This file is called:

SYS$SYSTEM:VMS$RESERVED_MEMORY.DATA

The file is maintained by the SYSMAN utility (as is the executive loaded image data file).

4.6.1.2 AUTOGEN

The Reserved Memory Registry file, VMS$RESERVED_MEMORY.DATA, is read by the AUTOGEN feedback mechanism and factors into the setting of the system's fluid page count. AUTOGEN sizes the system pagefile, number of processes and working set maximum size based on the system's fluid page count.

4.6.1.3 Adding Entries to the Reserved Memory Registry

You add an entry to the data file by using the SYSMAN utility. The SYSMAN command is as follows:

SYSMAN RESERVED_MEMORY ADD gs_name - /GROUP = n - /SIZE = {size of reserved memory, unit: MB} - /[NO]ALLOCATE - /[NO]ZERO - /[NO]PAGE_TABLES

• The gs_name field is the name of the memory-resident global section associated with this reserved memory. A name must be specified.
• If the /GROUP qualifier is not present, the reserved memory is for a system global section (SYSGBL).
• If the /GROUP qualifier is present, the reserved memory is for a group global section. The value n UIC group number (in octal) of the process that creates the group global section. Only processes within the creator's UIC group number are allowed access to the global section. For example, if a process with the UIC of [6,100] is the creator of the group global section, the group number specified for the /GROUP qualifier would be 6.
• If the /ALLOCATE qualifier is not specified or if the /NOALLOCATE qualifier is specified, the reserved memory is not allocated during the next reboot of the system. The reserved memory is only deducted from the system's fluid page count and the creation of the memory-resident global section results in the fault option being used.
• If the /ALLOCATE qualifier is specified, contiguous, aligned pages are allocated during the next reboot of the system. The allocated memory is deducted from the system's fluid page count and the creation of the memory-resident global section results in the allocate option being used. The physical alignment of the pages is based on the maximum granularity hint factor that can be used to map the pages given the size of the reserved memory. Possible granularity hint factors are 512 pages (or 4 MB) and 64 pages (or 512 KB). Therefore, assuming an 8- KB system page size, reserved memory is physically aligned as follows:

  1. size >= 4 MB: physically aligned on a 4 Mbyte boundary 2. size < 4 MB: physically aligned on a 512 KB boundary

• If the /ZERO qualifier is not specified or if /NOZERO is specified, the pre-allocated pages are not zeroed during system initialization. The pages are zeroed at the time the global section is created.
• The /ZERO qualifier is only allowed if the /ALLOCATE qualifier is specified. If the /ZERO qualifier is specified, the pre-allocated pages are zeroed during system initialization. Zeroed pages are required for memory-resident global sections, however, the pages need not be zeroed during system initialization.
• If the /PAGE_TABLES qualifier is not specified or if /NOPAGE_TABLES is specified, additional memory is not reserved for shared page tables. When the memory-resident global section is created, shared page tables are not created for the global section.
• If the /PAGE_TABLES qualifier is specified, additional memory is reserved for shared page tables. When the memory-resident global section is created, shared page tables are created for the global section. If the /ALLOCATE qualifier is not specified or if /NOALLOCATE is specified, the additional reserved memory is only deducted from the system's fluid page count. If the /ALLOCATE qualifier is specified, additional contiguous, aligned pages are allocated during the next reboot of the system for the shared page tables and the additional reserved memory is deducted from the system's fluid page count.

You can remove a reserved memory entry by issuing the following SYSMAN command:

SYSMAN RESERVED_MEMORY REMOVE gs_name /GROUP = n

The specified gs_name is the name of the memory-resident section associated with the entry being removed from the Reserved Memory Registry. A name must be specified.

The value n specified by the /GROUP qualifier is the UIC group number (in octal) associated with the memory-resident section being removed. The /GROUP qualifier must be specified if the memory-resident global section is a group global section. The /GROUP qualifier must not be specified if the memory-resident global section is a system global section.

If page tables are reserved for the named memory-resident global section, the additional reserved memory is also removed.

The REMOVE command only removes entries from the Reserved Memory Registry data file; it does not affect memory within the running system.

4.6.2.1 Allocating Reserved Memory

During system initialization, the VMS$RESERVED_MEMORY.DATA data file is read.

For each entry in the data file, the number of megabytes is deducted from the system's fluid page count for this memory-resident global section as specified by the /SIZE qualifier on the RESERVED_MEMORY ADD command. If /PAGE_TABLES was specified, the amount of memory required for the shared page tables mapping the memory-resident global section is deducted from the system's fluid page count as well.

If /ALLOCATE was specified on the RESERVED_MEMORY ADD command, a contiguous chunk of physical pages is also allocated and set aside for the memory-resident global section. If /PAGE_TABLES was specified, an additional contiguous chunk of physical pages is allocated and set aside for the shared page tables. The pages have a physical alignment appropriate to use the largest granularity hint factor for the given sized chunk. If /ZERO was specified, the pages are zeroed during system initialization or when the system is idle. If /ZERO was not specified or if /NOZERO was specified, the pages are zeroed at the time the memory-resident global section is created.

If the system parameter STARTUP_P1 is set to MIN, entries in the Reserved Memory Registry entries are ignored and memory is not reserved.

If errors are encountered during system initialization while processing the Reserved Memory Registry data file, with reserving system fluid pages, or with allocating contiguous, aligned physical pages, an error message is issued to the console and the system continues to boot.

4.6.2.2 Freeing Reserved Memory

In the running system, you can free reserved memory by issuing the following SYSMAN command:

SYSMAN RESERVED_MEMORY FREE gs_name /GROUP = n

The specified gs_name is the name of the memory-resident section associated with the entry being freed from the Reserved Memory Registry. A name must be specified.

The value n specified by the /GROUP qualifier is the UIC group number (in octal) associated with the memory-resident section being freed. The /GROUP qualifier must be specified if the memory-resident global section is a group global section. The /GROUP qualifier must not be specified if the memory-resident global section is a system global section.

If contiguous, aligned physical pages were not pre-allocated during system initialization for this global section, the reserved memory is simply added to the system's fluid page count. Otherwise the physical pages are deallocated onto the system's free or zeroed page list. The system's fluid page count is adjusted to include the deallocated pages.

If page tables are also reserved for the named memory-resident global section, the reserved memory for the shared page tables is also freed.

If the reserved memory is in use by the named memory-resident global section, the amount of reserved memory not currently in use is freed.

The RESERVED_MEMORY FREE command does not affect the Reserved Memory Registry data file contents, it only affects the memory within the running system.

4.6.2.3 Displaying Reserved Memory

Two different places hold reserved memory information, the Reserved Memory Registry data file and the Reserved Memory Registry in the running system created during system initialization based on the entries in the data file.

Different display mechanisms may be used depending on where the information about the reserved memory originates.

There are three mechanisms for displaying the Reserved Memory Registry within the running system: SYSMAN, the DCL SHOW MEMORY command and SDA.

• SYSMAN
  You can display the Reserved Memory Registry within the running system by issuing the following SYSMAN command:

  SYSMAN RESERVED_MEMORY SHOW gs_name /GROUP = n

  
  The specified gs_name is the name of the memory-resident global section associated with the entry being displayed from within the running system. If gs_name is not specified, the reserved memory for all registered global sections is displayed.
  The value specified by the /GROUP qualifier is the UIC n group number (in octal) associated with the memory-resident section being displayed. The /GROUP qualifier must be specified if the memory-resident global section is a group global section. The /GROUP qualifier must not be specified if the memory-resident global section is a system global section. The /GROUP qualifier is allowed only if gs_name is specified.

• DCL SHOW MEMORY command
  You can display the Reserved Memory Registry within in the running system by issuing the DCL SHOW MEMORY command. This command shows all memory-related information about the running system including information about the Reserved Memory Registry.
  SHOW MEMORY /RESERVED displays just information about the Reserved Memory Registry within the running system.
  The information displayed by SHOW MEMORY includes how much memory is currently in use by the named global section. It also includes how much memory is reserved and in use (if any) for page tables.
• SDA
  SDA also includes various enhancements to display the Reserved Memory Registry within the running system as well as in crash dump files. The command interface is TBD.

The system services SYS$CREATE_GDZRO and SYS$CRMPSC_GDZRO_64 call internal kernel mode OpenVMS Alpha routines to use the reserved memory registered in the Reserved Memory Registry.

The global section need not be registered in the Reserved Memory Registry. If the global section name is registered in the Reserved Memory Registry, the size of the global section need not exactly match the size of the reserved memory. If the global section is not registered, or if /NOALLOCATE was specified when the global section was registered in the Reserved Memory Registry, the fault option is used for the memory-resident global DZRO section. If the size is greater than the size of the reserved memory, the system service call to create the memory-resident global DZRO section fails if there are not enough additional fluid pages within the system.

If /ALLOCATE was specified when the global section was registered in the Reserved Memory Registry, the allocate option is used for the memory-resident global DZRO section. The size of the global section must be less than or equal to the size of the reserved, pre-allocated memory or the error SS$_MRES_PFNSMALL is returned by the system service call.

4.6.2.5 Returning Reserved Memory

When a memory-resident global section is deleted, the physical pages used for that global section are deallocated to the free page list if contiguous, aligned physical pages were not pre-allocated for this global section. The system's fluid page count is adjusted only for those pages not reserved in the Reserved Memory Registry for this global section.

When a memory-resident global section is deleted, the physical pages used for that global section are returned to the Reserved Memory Registry if contiguous, aligned physical pages were pre-allocated for this global section. The physical pages are not deallocated to the free page list and are still reserved. No adjustment is made to the system's fluid page count.

Reserved memory may only be freed to the running system by using the RESERVED_MEMORY FREE command to the SYSMAN utility.

The configuration of an OpenVMS Alpha application that uses memory-resident global sections performs the following steps:

1. Execute the SYSMAN RESERVED_MEMORY ADD commands that specify the required use of reserved memory.
2. Run AUTOGEN with feedback to set the system's fluid page count appropriately and size the system's pagefile, number of processes and working set maximum size appropriately.
3. Reboot the system to allow for the reserved memory to be deducted from the system's fluid page count and for contiguous, aligned pages to be allocated and zeroed as necessary.

This chapter summarizes changes to the RMS interface that support 64-bit addressing and enable you to use RMS to perform input and output operations to P2 or S2 space. You can take full advantage of these RMS enhancements by making only minor modifications to existing RMS code.

For complete information about RMS support for 64-bit addressing, see the OpenVMS Record Management Services Reference Manual.

The RMS user interface consists of a number of control data structures (FAB, RAB, NAM, XABs). These are linked together with 32-bit pointers and contain embedded pointers to I/O buffers and various user data buffers, including file name strings and item lists. RMS support for 64-bit addressable regions allows 64-bit addresses for the following user I/O buffers:

• UBF (user record buffer)
• RBF (record buffer)
• RHB (fixed-length record header buffer; fixed portion of VFC record format)
• KBF (key buffer containing the key value for random access)

The prompt buffer pointed to by RAB$L_PBF is excluded because the terminal driver does not allow 64-bit addresses.

Specific enhancements to the RMS interface for 64-bit addressing are as follows:

• Data buffers can be placed in P2 or S2 space for the following user I/O services:
  • Record I/O services: $GET, $FIND, $PUT, $UPDATE
  • Block I/O services: $READ, $WRITE
• The RAB structure points to the record and data buffers used by these services.
• An extension of the existing RAB structure is used to specify 64-bit buffer pointers and sizes.
• The buffer size maximum for RMS block I/O services ($READ and $WRITE) has been increased from 64 KB to 2 GB, with two exceptions:
  • For RMS journaling, a journaled $WRITE service is restricted to the current maximum (65535 minus 99 bytes of journaling overhead). An RSZ error is returned to RAB$L_STS if the maximum is exceeded.
  • Magnetic tape is still limited to 65535 bytes at the device driver level.
  
  Buffer size maximums for RMS record I/O services ($GET, $PUT, $UPDATE) have not changed. Prior RMS on-disk record size limits still apply.

The rest of the RMS interface currently is restricted to 32-bit pointers:

• FAB, RAB, NAM, and XABs must still be allocated in 32-bit space.
• Any descriptors or embedded pointers to file names, item lists, and so on, must continue to use 32-bit pointers.
• Any arguments passed to the RMS system services remain 32-bit arguments. If you attempt to pass a 64-bit argument, the SS$_ARG_GTR_32_BITS error is returned.

The RAB64, a RMS user interface structure, is an extended RAB that can accommodate 64-bit buffer addresses. The RAB64 data structure consists of a 32-bit RAB structure followed by a 64-bit extension as shown below:

The RAB64 contains fields identical to all of the RAB fields except that field names have the RAB64 prefix instead of the RAB prefix. In addition, RAB64 has the following fields in the extension:

This field...	...is an extension of this field	Description
RAB64$Q_CTX	RAB64$L_CTX	User context. This field is not used by RMS but is available to the user. The CTX field is often used to contain a pointer. For asynchronous I/O, it provides the user with the equivalent of an AST parameter.
RAB64$PQ_KBF	RAB64$L_KBF	Key buffer address containing the key value for random access (for $GET and $FIND).
RAB64$PQ_RBF	RAB64$L_RBF	Record buffer address (for $PUT, $UPDATE, and $WRITE).
RAB64$PQ_RHB	RAB64$L_RHB	Record header buffer address (fixed portion of VFC record format).
RAB64$Q_RSZ	RAB64$W_RSZ	Record buffer size.
RAB64$PQ_UBF	RAB64$L_UBF	User buffer address (for $GET and $READ).
RAB64$Q_USZ	RAB64$W_USZ	User buffer size.

Note that the fields with the PQ tag in their names can hold either a 64-bit address or a 32-bit address sign-extended to 64 bits. Therefore, you can use the fields in all applications whether or not you are using 64-bit addresses.

For most record I/O service requests, there is an RMS internal buffer between the device and the user's data buffer. The one exception occurs with the RMS service $PUT. If the device is a unit record device and it is not being accessed over the network, RMS passes the address of the user record buffer (RBF) to the $QIO system service. If you inappropriately specify a record buffer (RBF) allocated in 64-bit address space for a $PUT to a unit record device that does not support 64-bit address space (for example, a terminal), the $QIO service returns SS$_NOT64DEVFUNC. (See Chapter 7 for more information about $QIO.) RMS returns the error status RMS$_SYS with SS$_NOT64DEVFUNC as the secondary status value in RAB64$L_STV.

RMS system services support the RAB structure as well as the RAB64 structure.

5.2 Using the 64-Bit RAB Extension

Only minimal source code changes are required for applications to use 64-bit RMS support.

RMS allows you to use the RAB64 wherever you can use a RAB. For example, a RAB64 can be used in place of a RAB as the first argument passed to any of the RMS record or block I/O services.

Because the RAB64 is an upwardly compatible extension of the existing RAB, most source modules can treat references to fields in a RAB64 as if they were references to a RAB. The 64-bit buffer address counterpart is used only if the following two conditions are met:

• The RAB64$B_BLN field has been initialized to RAB64$C_BLN64 to show that the extension is present.
• The 32-bit address field in the 32-bit portion of the RAB contains -1 .

The value in the quadword size field is used only if the contents of the 32-bit address field designate its use. For example:

If this address field contains -1	The address in this field is used	And the size in this field is used
RAB64$L_UBF	RAB64$PQ_UBF 1	RAB64$Q_USZ
RAB64$L_RBF	RAB64$PQ_RBF 1	RAB64$Q_RSZ
RAB64$L_KBF	RAB64$PQ_KBF	RAB64$B_KSZ
RAB64$L_RHB	RAB64$PQ_RHB	FAB$B_FSZ

While RMS allows you to use the RAB64 wherever you can use a RAB, some source languages may impose other restrictions. Consult the documentation for your source language for more information.

	privacy and legal statement
6467PRO_003.HTML