[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

HP OpenVMS Programming Concepts Manual


Previous Contents Index

12.3 Using System Services for Memory Allocation

This section describes how to use system services to perform the following tasks:

  • Increase and decrease virtual address space with 64-bit system services
  • Increase and decrease virtual address space with 32-bit system services
  • Input and return address arrays for the 64-bit system services
  • Input and return address arrays for the 32-bit system services
  • Control page ownership and protection
  • Control working set paging
  • Control process swapping

12.3.1 Increasing and Decreasing Virtual Address Space with 64-Bit System Services

To add address space at the end of P0, P1, P2 or a user created region, use the 64-bit Expand Region (SYS$EXPREG_64) system service. SYS$EXPREG_64 returns the range of virtual addresses for the new pages. To add address space in other portions of P0, P1, P2 or user created virtual regions, use SYS$CRETVA_64.

The format for SYS$EXPREG_64 is as follows:


SYS$EXPREG_64 region_id_64, length_64, acmode, flags, return_va_64, return_length_64

The following example illustrates the addition of 4 pagelets to the 64-bit program region of a process by writing a call to the SYS$EXPREG_64 system service.


#define __NEW_STARTLET 1
#pragma pointer_size 64

#include <gen64def.h>
#include <stdio.h>
#include <ssdef.h>
#include <starlet.h>
#include <vadef.h>

int main (void) {

    int status;
    GENERIC_64 region_id = {VA$C_P2};
    void * start_va;
    unsigned __int64 length;
    unsigned int pagcnt = 4;

    /* Add 4 pagelets to P0 space */
    status = sys$expreg_64 (&region_id, pagcnt*512, 0, 0, &start_va, &length);
    if (( status&1) != 1)
        LIB$SIGNAL( status);
    else
        printf ("Starting address %016LX Length %016LX'n", start_va, length);
}

The value VA$C_P2 is passed in the region_id argument to specify that the pages are to be added to the 64-bit program region. To add the same number of pages to the 32-bit program region, you would specify VA$C_P0. To add pages to the control region, you would specify VA$C_P1. To add pages to a user created virtual region, you would specify the region_id returned by the SYS$CREATE_REGION_64 system service.

On Alpha and I64 systems the SYS$EXPREG_64 system service can add pagelets only in the direction of the growth of a particular region.

12.3.2 Increasing and Decreasing Virtual Address Space with 32-bit System Services

The system services allow you to add address space anywhere within the process's program region (P0) or control region (P1). To add address space at the end of P0 or P1, use the Expand Program/Control Region (SYS$EXPREG) system service. SYS$EXPREG optionally returns the range of virtual addresses for the new pages. To add address space in other portions of P0 or P1, use SYS$CRETVA.

The format for SYS$EXPREG is as follows:


SYS$EXPREG (pagcnt ,[retadr] ,[acmode] ,[region])

Specifying the Number of Pages

Use the pagcnt argument to specify the number of pagelets to add to the end of the region. The Alpha and I64 systems round the specified pagelet value to the next integral number of pages for the system where it is executing. To check the exact boundaries of the memory allocated by the system, specify the optional retadr argument. The retadr argument contains the start address and the end address of the memory allocated by the system service.

Specifying the Access Mode

Use the acmode argument to specify the access to be assigned to the newly created pages.

Specifying the Region

Use the region argument to specify whether to add the pages to the end of the P0 or P1 region.

To deallocate pages allocated with SYS$EXPREG and SYS$CRETVA, use SYS$DELTVA.

For Alpha systems, the following example illustrates the addition of 4 pagelets to the program region of a process by writing a call to the SYS$EXPREG system service.



#include <stdio.h>
#include <ssdef.h>


main() {
    unsigned int status, retadr[2],pagcnt=4, region=0;

/* Add 4 pages to P0 space */
    status = SYS$EXPREG( pagcnt, &retadr, 0, region);
    if (( status & 1) != 1)
        LIB$SIGNAL( status );
    else
        printf("Starting address: %d Ending address: %d\n",
               retadr[0],retadr[1];
}

The value 0 is passed in the region argument to specify that the pages are to be added to the program region. To add the same number of pages to the control region, you would specify REGION=1.

Note that the region argument to the SYS$EXPREG service is optional; if it is not specified, the pages are added to or deleted from the program region by default.

The SYS$EXPREG service can add pagelets only in the direction of the growth of a particular region. When you need to add pages to the middle of these regions, you can use the Create Virtual Address Space (SYS$CRETVA) system service. Likewise, when you need to delete pages created by either SYS$EXPREG or SYS$CRETVA, you can use the Delete Virtual Address Space (SYS$DELTVA) system service. For example, if you have used the SYS$EXPREG service twice to add pages to the program region and want to delete the first range of pages but not the second, you could use the SYS$DELTVA system service, as shown in the following example:


#include <stdio.h>
#include <ssdef.h>

struct {
    unsigned int lower, upper;
}retadr1, retadr2, retadr3;

main() {
    unsigned int status, pagcnt=4, region=0;

/* Add 4 pages to P0 space */
    status = SYS$EXPREG( pagcnt, &retadr1, 0, region);
    if (( status & 1) != 1)
        LIB$SIGNAL( status );
    else
        printf("Starting address: %d ending address: %d\n",
               retadr1.lower,retadr1.upper);

/* Add 3 more pages to P0 space */

    pagcnt = 3;
    status = SYS$EXPREG( pagcnt, &retadr2, 0, region);
    if (( status & 1) != 1)
        LIB$SIGNAL( status );
    else
        printf("Starting address: %d ending address: %d\n",
               retadr2.lower,retadr2.upper);

/* Delete original allocation */
    status = SYS$DELTVA( &retadr1, &retadr3, 0 );
    if (( status & 1) != 1)
        LIB$SIGNAL( status );
    else
        printf("Starting address: %d ending address: %d\n",
               retadr1.lower,retadr1.upper);

}

In this example, the first call to SYS$EXPREG rounds up the requested pagelet count to an integral number of CPU-specific pages and adds that number of pages to the program region; the virtual addresses of the created pages are returned in the 2-longword array at retadr1. The second request converts the pagelet count to pages, adds them to the program region, and returns the addresses at retadr2. The call to SYS$DELTVA deletes the area created by the first SYS$EXPREG call.

Caution

Be aware that using SYS$CRETVA presents some risk because it can delete pages that already exist if those pages are not owned by a more privileged access mode. Further, if those pages are deleted, notification is not sent. Therefore, unless you have complete control over an entire system, use SYS$EXPREG or the RTL routines to allocate address space.

Section 12.3.5 mentions some other possible risks in using SYS$CRETVA for allocating memory.

12.3.3 Input Address Arrays and Return Address Arrays for the 64-Bit System Services

When the SYS$EXPREG_64 system service adds pages to a region, it adds them in the normal direction of growth for the region. The return address always indicates the lowest-addressed byte in the added address range. To calculate the highest-addressed byte in the added address range, add the returned length to the returned address and subtract 1.

When the SYS$DELTVA_64 system service deletes pages from a region, it deletes them in the opposite direction of growth for the region. The return address always indicates the lowest-addressed byte in the deleted address range. To calculate the highest-addressed byte in the deleted address range, add the returned length to the returned address and subtract 1.

Table 12-1 Sample Virtual Address Arrays for 64-Bit Services
Start_va Length Return_va Return_length Number of Pages
1010 660 0 2000 1
2450 1 2000 2000 1
4200 6300 4000 8000 4
7FFEC010 90 7FFEC000 2000 1
08000A000 4000 08000A000 4000 2

12.3.4 Input Address Arrays and Return Address Arrays for the 32-Bit System Services

When the SYS$EXPREG system service adds pages to a region, it adds them in the normal direction of growth for the region. The return address array, if requested, indicates the order in which the pages were added. For example:

  • If the program region is expanded, the starting virtual address is smaller than the ending virtual address.
  • If the control region is expanded, the starting virtual address is larger than the ending virtual address.

The addresses returned indicate the first byte in the first page that was added or deleted and the last byte in the last page that was added or deleted, respectively.

When input address arrays are specified for the Create and Delete Virtual Address Space (SYS$CRETVA and SYS$DELTVA, respectively) system services, these services add or delete pages beginning with the address specified in the first longword and ending with the address specified in the second longword.

On Alpha and I64 systems, the order in which the pages are added or deleted does not have to be in the normal direction of growth for the region. Moreover, because these services add or delete only whole pages, they ignore the low-order bits of the specified virtual address (the low-order bits contain the byte offset within the page). Table 12-2 shows the page size and byte offset.

Table 12-2 Page and Byte Offset Within Pages on Alpha and I64 Systems
Page Size
(Bytes)
Byte Within Page
(Bits)
8K 13
16K 14
32K 15
64K 16

Table 12-3 shows some sample virtual addresses in hexadecimal that may be specified as input to SYS$CRETVA or SYS$DELTVA and shows the return address arrays if all pages are successfully added or deleted. Table 12-3 assumes a page size of 8 KB = 2000 hex.

Table 12-3 Sample Virtual Address Arrays on Alpha and I64 Systems
Input Array   Output Array  
Start End Region Start End Number of Pages
1010 1670 P0 0 1FFF 1
2450 2451 P0 2000 3FFF 1
4200 A500 P0 4000 BFFF 4
9450 9450 P0 8000 9FFF 1
7FFEC010 7FFEC010 P1 7FFEDFFF 7FFEC000 1
7FFEC010 7FFEBCA0 P1 7FFEDFFF 7FFEA000 2

For SYS$CRETVA and SYS$DELTVA, note that if the input virtual addresses are the same, as in the fourth and fifth items in Table 12-3, a single page is added or deleted. The return address array indicates that the page was added or deleted in the normal direction of growth for the region.

Note that for SYS$CRMPSC and SYS$MGBLSC, which are discussed in Section 12.3.9, the sample virtual address arrays in Table 12-3 do not apply. The reason is that the lower address value has to be an even multiple of the machine page size; that is, it must be rounded down to an even multiple page size. In addition, the higher address value must be one less than the even multiple page size, representing the last byte on the last page. That is, it must be rounded up to an even multiple page size, minus 1.

The procedure for determining start and end virtual addresses is as follows:

  1. Obtain the page size in bytes.
  2. Subtract 1 to obtain the byte-with-page mask.
  3. Mask the low bits of lower virtual address, which is a round-down operation to round it to the next lower page boundary.
  4. Perform a logical OR operation on the higher virtual address, which is a round-up operation to round it to the highest address in the last page.

12.3.5 Allocating Memory in Existing Virtual Address Space on Alpha and I64 Systems Using the 32-Bit System Service

Note

On Alpha and I64 systems, SYS$CRETVA_64 adds a range of demand-zero allocation pages to a process's virtual address space for the execution of the current image. The new pages are added at the virtual address specified by the caller. SYS$CRETVA_64 is the preferred method of adding these pages.

On Alpha and I64 systems, if you reallocate memory that is already in its virtual address space by using the SYS$CRETVA system service, you may need to modify the values of the following arguments to SYS$CRETVA:

  • If your application explicitly rounds the lower address specified in the inadr argument to be a multiple of 512 in order to align on a page boundary, you need to modify the address. The Alpha and I64 system's version of the SYS$CRETVA system service rounds down the start address to a CPU-specific page boundary, which varies with different implementations. It also rounds up the end address to the last byte in a CPU-specific page boundary.
  • The size of the reallocation, specified by the address range in the inadr argument, may be larger on an Alpha and I64 system than on a VAX system because the request is rounded up to CPU-specific pages. This can cause the unintended destruction of neighboring data, which may also occur with single-page allocations. (When the start address and the end address specified in the inadr argument match, a single page is allocated.)

To determine whether you must modify the address as specified in inadr, specify the optional retadr argument to determine the exact boundaries of the memory allocated by the call to SYS$CRETVA.

12.3.6 Page Ownership and Protection

Each page in the virtual address space of a process is owned by the access mode that created the page. For example, pages in the program region that initially provided for the execution of an image are owned by user mode. Pages that the image creates dynamically are also owned by user mode. Pages in the control region, except for the pages containing the user stack, are normally owned by more privileged access modes.

Only the owner access mode or a more privileged access mode can delete the page or otherwise affect it. The owner of a page can also indicate, by means of a protection code, the type of access that each access mode will be allowed.

The Set Protection on Pages (SYS$SETPRT or SYS$SETPRT_64) system service changes the protection assigned to a page or group of pages. The protection is expressed as a code that indicates the specific type of access (none, read-only, read/write) for each of the four access modes (kernel, executive, supervisor, user). Only the owner access mode or a more privileged access mode can change the protection for a page.

When an image attempts to access a page that is protected against the access attempted, a hardware exception called an access violation occurs. When an image calls a memory management system service, the service probes the pages to be used to determine whether an access violation would occur if the image attempts to read or write one of the pages. If an access violation occurs, the service exits with the status code SS$_ACCVIO.

Because the memory management services add, delete, or modify a single page at a time, one or more pages can be successfully changed before an access violation is detected. If the retadr argument is specified in the 32-bit service call, the service returns the addresses of pages changed (added, deleted, or modified) before the error. If no pages are affected, that is, if an access violation occurs on the first page specified, the service returns a -1 in both longwords of the return address array.

If the retadr argument is not specified, no information is returned.

The 64-bit system services return the address range (return_va and return_length) of the addresses of the pages changed (added, deleted, or modified) before the error.

12.3.7 Working Set Paging

On Alpha and I64 systems, when a process is executing an image, a subset of its pages resides in physical memory; these pages are called the working set of the process. The working set includes pages in both the program region and the control region. The initial size of a process's working set is defined by the process's working set default (WSDEFAULT) quota, which is specified in pagelets. When ample physical memory is available, a process's working-set upper growth limit can be expanded to its working set extent (WSEXTENT).

When the image refers to a page that is not in memory, a page fault occurs, and the page is brought into memory, possibly replacing an existing page in the working set. If the page that is going to be replaced is modified during the execution of the image, that page is written into a paging file on disk. When this page is needed again, it is brought back into memory, again replacing a current page from the working set. This exchange of pages between physical memory and secondary storage is called paging.

The paging of a process's working set is transparent to the process. However, if a program is very large or if pages in the program image that are used often are being paged in and out frequently, the overhead required for paging may decrease the program's efficiency. The SYS$ADJWSL, SYS$PURGWS, SYS$LKWSET, and SYS$LKWSET_64 system services allow a process, within limits, to counteract these potential problems.

12.3.7.1 SYS$ADJWSL System Service

The Adjust Working Set Limit (SYS$ADJWSL) system service increases or decreases the maximum number of pages that a process can have in its working set. The format for this routine is as follows:


SYS$ADJWSL ([pagcnt],[wsetlm])

Use the pagcnt argument to specify the number of pagelets to add or subtract from the current working set size. The system rounds the specified number of pagelets to a multiple of the system's page size. The new working set size is returned in wsetlm in units of pagelets.

12.3.7.2 SYS$PURGWS System Service

The Purge Working Set (SYS$PURGWS) system service removes one or more pages from the working set. The format is as follows:


SYS$PURGWS inadr

On Alpha and I64 systems, SYS$PURGE_WS removes a specified range of pages from the current working set of the calling process to make room for pages required by a new program segment The format is as follows:


SYS$PURGE_WS start_va_64 ,length_64

12.3.7.3 SYS$LKWSET and SYS$LKWSET_64 System Services

The Lock Pages in Working Set (SYS$LKWSET) system service makes one or more pages in the working set ineligible for paging by locking them in the working set. Once locked into the working set, those pages remain in the working set until they are unlocked explicitly with the Unlock Pages in Working Set (SYS$ULWSET) system service, or program execution ends. The format is as follows:


SYS$LKWSET (inadr ,[retadr] ,[acmode])

On Alpha and I64 systems, SYS$LKWSET_64 locks a range of virtual addresses in the working set. If the pages are not already in the working set, the service brings them in and locks them. A page locked in the working set does not become a candidate for replacement.


SYS$LKWSET_64 start_va_64 ,length_64 ,acmode ,return_va_64 ,return_length_64


Previous Next Contents Index