vm_pattr System Call and kvm_pattr Kernel Service

The range is specified through the following vm_pa_range structure:

 struct vm_pa_range
              {
                     ptr64_t  rng_start;
                     size64_t rng_size;
              };

The range specified must be in the target process's address space and must correspond to one of these process areas:

• Main program data (initialized, bss, or heap).
• Shared library data or private module load area data.
• Privately loaded text.
• Initial thread stack area.
• Anonymous shared memory (System V shared memory, extended System V shared through EXTSHM, and POSIX real-time shared memory). The target process must have write access to the memory in order to change the attributes of the shared memory range.
• Anonymous mmap memory.

If the memory range specified includes shared memory or mmap memory, the calling process must have write access to the memory according to the shared memory descriptor or mapping attributes in order to change the attributes of the range. The range can have additional restrictions based on the following commands.

The structure specified through the attr parameter must be a pointer to one of the following structures:

VM_PA_SET_PSIZE or VM_PA_GET_PSIZE

These commands take a pointer to the following structure:

struct vm_pa_psize
              {
                     struct vm_pa_range pa_range;
                     psize_t            pa_psize;
              };

For the VM_PA_SET_PSIZE command, the pa_psize parameter is the page size (in bytes) to use for the given range. This is an advisory setting that might or might not be used at the operating system's discretion. This must be a valid page size between the minimum and maximum page sizes of all segments in the range. Additionally, the range must start and end on a multiple of the specified page size. If an error occurs during the processing of this command, any successfully altered page size settings can remain set.

For the VM_PA_GET_PSIZE command, the page size (in bytes) backing the specified memory range is returned in the pa_psize parameter. The range must start and end on a multiple of the smallest page size supported as reported by the sysconf(_SC_PAGE_SIZE) subroutine. If the range is using multiple page sizes, the smallest page size in the range is reported. Unlike the VM_PAGE_INFO command of the vmgetinfo subroutine that reports the segment's base page size, the page size reported by the VM_PA_GET_PSIZE command is the actual page size being used at the time the vm_pattr system call was called. The page size reported is transient because the operating system can change the backing page size at any time. Therefore, the page size reported must be for informational purposes only.

VM_PA_SET_PSIZE_EXTENDED

This command takes a pointer to the following structure:

struct vm_pa_psize_extended
				{
					struct vm_pa_range   pa_range;
					psize_t              pa_psize;
					size_t               pa_info_size;
					uint64_t            *pa_info;
				}

This command is essentially the same as VM_PA_SET_PSIZE except that pa_psize must be 16 MB and, if not NULL, pa_info can be used to pass additional information specifying one or more affinity domains.

The info passed by the parameter is advisory request, and the system might choose to ignore it.

The pa_range is scanned for subregions that begin and end on a 16 MB boundary, are fully backed with 4 KB or 64 KB pages, and have uniform page attributes. The page attributes include read or write page protection, storage key protection, and no-execute protection.

The data in qualifying 16 MB subregions is colocated to a 16 MB contiguous block of physical memory, and it uses 16 MB hardware translations.

If the pa_info pointer is NULL, the memory for collocation is allocated from any memory SRAD, affinity domain chosen by the operating system.

If parameter value is not NULL, pa_info must point to an rsethandle_t that describes a set of affinity domains from which the physical memory for the collocation must be allocated. The object should be allocated by a call to rs_alloc (RS_EMPTY). It must then be initialized with one rs_op(RS_ADDRESOURCE, ..., R_MEMPS, srad#) call per affinity domain being requested.

This command can potentially affect system performance and is not generally recommended; therefore, this command requires you to have either the CAP_BYPASS_RAC_VMM and CAP_PROPAGATE capabilities or root authority.

VM_PA_GET_PSIZE_EXTENDED

This command is essentially the same as the VM_PA_GET_PSIZE command except that it can also return the 64 KB and 16 MB subregions that are using an hardware translation page size different from the underlying segments default page size.

VM_PA_GET_RMUSAGE

This command takes a pointer to the following structure:

struct vm_pa_rmusage
              {
                     struct vm_pa_range pa_range;
                     size64_t           pa_rbytes;
              };

This command reports the amount of real memory (in bytes) used for the given range in the pa_rbytes field. This can help an application decide whether it needs to use a large page size for a specific range based on how much real memory the range is using. For example, if a 64KB range is only using 4KB of real memory, then it does not make sense to try to use a 64KB page size for that range. But if it is using all 64KB or some large percentage of it, then the application might decide to use a 64KB page size. The range specified for this command has no alignment requirements for this command, and the command includes only those bytes in the range that are using real memory.

VM_PA_SET_PSPA or VM_PA_GET_PSPA

These commands take a pointer to the following structure:

struct vm_pa_pspa
              {
                     struct vm_pa_range pa_range;
                     int    pa_pspa;
              };

The VM_PA_SET_PSPA command can set the page size promotion aggressiveness for the specified range. The pa_pspa setting is in the same units as the vmm_default_pspa vmo tunable. This setting is the inverse of the real memory occupancy threshold needed to promote to a large page size and ranges from -1 to 100. The value of -1 indicates that no page promotion can occur regardless of the occupancy of the memory range. A value of 0 indicates a page size promotion can only be done when the memory range is fully occupied. A value of 100 indicates a page promotion must be done at the first reference to the memory range.

This setting is only supported at a segment granularity, so the range must start and end on a segment boundary. The alignment requirement for the range can be found using the VM_PA_GET_PSPA_ALIGN command with the vm_pattr system call.

If an error occurs during the processing of the VM_PA_SET_PSPA command, the vm_pattr system call can return after altering the page size promotion thresholds for part of the specified range.

The VM_PA_GET_PSPA command retrieves the page size promotion aggressiveness factor for the specified range. If the range spans multiple segments consisting of different page promotion thresholds, the pa_pspa field is updated with the least aggressive PSPA setting (the smallest PSPA setting across all of the segments).

The PSPA commands are not supported on mmap or EXTSHM memory ranges.

VM_PA_GET_PSPA_ALIGN

This command takes a pointer to the following structure:

 struct vm_pa_pspa_align
              {
                     struct vm_pa_range pa_range;
                     size64_t pa_pspa_align;
              };

The VM_PA_GET_PSPA_ALIGN command returns the minimum memory alignment requirements of a memory range for the VM_PA_SET_PSPA command in the pa_pspa_align field based on what segments are contained in the specified memory range. If a memory range spans segments with different alignment requirements, this command returns the largest of the alignment requirements.

The alignment requirements for the VM_PA_SET_PSPA command are as follows:

VM_PA_SET_LSA_POLICY

This command takes a pointer to the following structure:

struct vm_pa_lsa_options
 {
 u_int64_t setting;
 size64_t value;
 };

The following settings are allowed:

VM_PA_SHM_1TB_SHARED

This setting controls the threshold of the number of 256 MB segments required before a SHM object is considered big enough to be placed in its own 1 TB region to be promoted to the large alias segments. Values can range from 0 to 4 KB.

VM_PA_SHM_1TB_UNSHARED

This setting controls the threshold of the number of 256 MB segments required before a group of SHM object packed in a 1 TB aligned group is promoted to the large alias segments. Values can range from 0 to 4 KB.