Plan for the use of freemained frames

Description

To enhance system performance on the IBM z13™, there might be cases where the system does not free the real frame that is backing a virtual page following a FREEMAIN, that is, when the page no longer contains any GETMAIN-assigned storage ranges. If so, the system will clear or "dirty" the frame to ensure that sensitive information is removed. Such a frame is referred to as a freemained frame. Freemained frames do not cause the count of frames owned by the address space (RAXFMCT) to be decremented (as they would have previously), nor do they cause the count of available frames within the system (RCEAFC) to be incremented (as they would have previously). Instead, the system uses a new counter, RAX_FREEMAINEDFRAMES, to keep track of the number of frames backing freemained pages in the address space with which the RAX is associated.

This feature is active by default on the IBM z13 and only applies to region private "low" storage (below 2GB), which is defined as subpools 0-127, 129-132, 240, 244, 250-252. Storage subpools define the characteristics of virtual storage below 2 GB and are discussed in detail in z/OS MVS Diagnosis: Reference .

The SYSEVENT STGTEST API reports on the current usage of real storage, returning a three-word value:
Word 1
Use of this number affects system performance very little, if at all.
Word 2
Use of this number affects performance to some degree.
Word 3
Use of this number may substantially affect performance.

To maintain compatibility with prior releases, SYSEVENT STGTEST will include most of Rce_FreemainedFrames in word 1 and all of it in words 2 and 3 for z/OS® V2R1 (HBB7790) and z/OS V1R13 (JBB778H). For z/OS V2R2 (HBB77A0), SYSEVENT STGTEST is changed to exclude Rce_FreemainedFrames from word 1.

Programs that reference or issue TPROT instructions against region private storage that is not GETMAIN assigned might not experience an 0C4 system abend nor get a non-zero condition code where they previously would have. This applies to the subpools listed earlier.

The following new parameters in the DIAGxx member of parmlib allow you to disable this feature, if necessary:
FREEMAINEDFRAMES(NO)
Disables the freemained frames feature on a system-wide basis.
FREEMAINEDFRAMES(YES) [EXCLUDEJOBLIST(job1[,job2,...])]
Enables the freemained frames feature, except for the specified jobs. Up to eight job names may be specified. The job names may include the * and ? wildcard characters, where the * character is allowed in any position.

Reissuing the SET DIAG command with different EXCLUDEJOBLIST values will not increase the total number of excluded jobs; the last EXCLUDEJOBLIST specification overrides any previous specifications.

Disabling this feature for selected jobs will cause performance degradation for the entire system, not just for the specified jobs.

You can use the DISPLAY DIAG command to verify that the system is using the requested FREEMAINEDFRAMES statement.

Note: The DISPLAY DIAG command does not report the default value. The FREEMAINEDFRAMES statement only appears in the IGV007I message when it has been specified in the DIAGxx member. Therefore, you can use the DISPLAY DIAG command to verify that the system is using the specified FREEMAINEDFRAMES statement.

Table 1 provides more details about the migration action. Use this information to plan your changes to the system.

Table 1. Information about this migration action
Element or feature: BCP.
When change was introduced: z/OS V2R2. z/OS V2R1 and z/OS V1R13 (with the RSM web deliverable), both with APAR OA46291 applied.
Applies to migration from: z/OS V2R1 and z/OS V1R13 (with the RSM web deliverable).
Timing: Before the first IPL of z/OS V2R2.
Is the migration action required? Yes, unless you disable this feature. Otherwise, installations that use software tools that monitor real storage usage must install updates to accommodate the advent of freemained frames.

Applications that invoke the TPROT instruction to determine whether pages of region private storage have been GETMAIN assigned should change to use the VSMLOC or VSMLIST services. The IARQDUMP service may also be applicable in some cases.

If none of these services meet the performance requirements of the application, then the application should use the new IARBRVER and IARBRVEA services provided with APAR OA46291 and z/OS V2R2.
Target system hardware requirements: IBM z13.
Target system software requirements: None.
Other system (coexistence or fallback) requirements: None.
Restrictions: None.
System impacts:
  • Address spaces may appear to be using more storage than before the feature is enabled or by default.
  • The system may appear to have less available storage than before the feature is enabled or by default.
  • References to non-GETMAIN assigned storage may not result in a 0C4 system abend.
  • The TPROT instruction may not return a condition code of 3 in cases where it previously would have done so.
Related IBM® Health Checker for z/OS check: None.

Steps to take

Follow these steps:
  • Verify that the value of RceOA46291Applied is B'1' before using any other new fields in the RCE or RAX data areas, as the new fields are not guaranteed to be initialized otherwise.
  • Programs that reference RAXFMCT can subtract Rax_FreemainedFrames to determine how much real storage the address space is currently using.
  • Programs that reference RCEAFC can add RCE_FreemainedFrames to determine how much storage is not currently in use. If an application is referencing RCEAFC to determine how much storage is available to be used by the application, a better solution is to use SYSEVENT STGTEST.
  • If an application needs to determine whether a virtual address range is GETMAIN assigned, it should use the VSMLOC or VSMLIST services, instead of using the LRAG or TPROT assembly language instructions. These services are documented in z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO and can be invoked regardless of whether the caller is running in a cross-memory environment (although they would only be applicable to the primary address space).

    The IARQDUMP callable service can be used to determine whether there is some virtual storage backing a given page and is documented in z/OS MVS Programming: Authorized Assembler Services Guide .

    If neither of these approaches are feasible, perhaps due to concerns about performance, the following new callable services provide the same results as the TPROT instruction while also taking freemained frames into account:
    • IARBRVER takes in general purpose register (GPR) 1 the virtual address of the page and returns one of the following codes in GPR 15:
      Code
      Meaning
      0
      Caller has write access to the data.
      1
      Caller has Read-only access (no write access) to the data.
      2
      Caller has neither read nor write access to the data.
      3
      The page either cannot be translated or is backed by a freemained frame.
    • IARBRVEA is similar to IARBRVER except that it is invoked in AR mode and access register (AR) 1 contains the ALET associated with the virtual address to be tested. This entry should be used when the page to be tested does not reside in the primary address space.

    These services are available when the value of RceOA46291Applied is B'1' and can be invoked on all supported hardware, not just the z13™.

Reference information

The documentation updates for APAR OA46291 are described in the file, OA46291.PDF, which is available at: http://publibz.boulder.ibm.com/zoslib/pdf/OA46291.pdf .

The following table provides a list of references for various aspects of the freemained frames feature.
Table 2. Reference information for freemained frames
For information about… See…
User region private storage and the freemained frames feature z/OS MVS Initialization and Tuning Guide
The FREEMAINEDFRAMES parameter in DIAGxx z/OS MVS Initialization and Tuning Reference
The IARQDUMP service z/OS MVS Programming: Authorized Assembler Services Guide
The IARBRVEA and IARBRVER services z/OS MVS Programming: Authorized Assembler Services Reference EDT-IXG
The VSMLOC and VSMLIST services z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO
The PVT, RAX, and RCE data areas z/OS MVS Data Areas in the z/OS Internet library
Parent topic: BCP actions to perform before the first IPL of z/OS V2R2