IARV64

IARV64

64-Bit Virtual Storage Allocation

Portability: SASC

SYNOPSIS
DESCRIPTION
RETURN VALUE
IMPLEMENTATION
EXAMPLE 1
EXAMPLE 2
RELATED FUNCTIONS

SYNOPSIS

#include 	<osiarv64.h>
int IARV64(char _ _near *request, ...);

DESCRIPTION

The IARV64 function implements the functionality of the IARV64 assembler macro. The request argument is the address of a null-terminated string. The remainder of the argument list is a list of keywords followed, in most cases, by an argument specifying a value for the keyword. The list is terminated by the _Iend keyword. The request argument must be one of the following:

GETSTOR: Create a memory object.
DETACH: Free one or more memory objects.
PAGEFIX: Fix physical pages within one or more memory objects.
PAGEUNFIX: Unfix physical pages within one or more memory objects.
PAGEOUT: Notify the system that data within physical pages of one or more memory objects will not be used in the near future.
PAGEIN: Notify the system that data within physical pages of one or more memory objects are needed in the near future.
DISCARDDATA: Discard data within physical pages of one or more memory objects.
CHANGEGUARD: Request that a specified range in a memory object be changed from guard area to usable area or from usable area to guard area.
LIST: Requests a list of memory objects.

The supported keywords and their associated data are as follows. All references to pointer operands should be considered _ _near unless specifically stated as being _ _huge.

The _Ireason keyword is equivalent to the Assembler RSNCODE=, which identifies an optional output parameter to hold the reason code from register 0. The next argument should be a pointer to an int where the reason code will be placed.
The _Icond keyword is equivalent to the Assembler COND=, which specifies whether the request is conditional or uncoditional. The next argument should be the string YES for a conditional request, or NO for an unconditional request.
The _Isegments keyword is equivalent to the Assembler SEGMENTS=, which specifies the size of the memory object in megabytes. The next argument should be a long long integer.
The _Ikey keyword is equivalent to the Assembler KEY=, which specifies the storage key to be assigned to the memory object. The next argument should be a unsigned character with bits 0-3 containing the key to be used. Bits 4-7 are ignored.
The _Ifprot keyword is equivalent to the Assembler FPROT=, which idicates whether the memory should be fetch-protected. The next argument should be the string YES to fetch-protect memory, or NO to indicate that the memory will not be fetch-protected.
The _Isvcdumprgn keyword is equivalent to the Assembler SVCDUMPRGN=, which idicates whether the memory object should be included in an SVC dump or LIST request. The next argument should be the string YES to include the memory object (SDATA=RGN must be set in the dump options), or NO to indicate that the memory object will not be included in an SVC dump or LIST request.
The _Icontrol keyword is equivalent to the Assembler CONTROL=, which indicates whether the memory object must be freed by an authorized caller. The next argument should be the string AUTH to indicate that only an authorized caller can free the object (and that the object is eligible for PAGEFIX and PAGEUNFIX), or UNAUTH to indicate that the object cannot be freed by an unauthorized caller.
The _Iusertkn keyword is equivalent to the Assembler USERTKN=, which identifies a user token to be identified with a memory object. The next argument should be a long long integer.
The _Iguardsize keyword is equivalent to the Assembler GUARDSIZE=, which specifies the length in megabytes of the guard area to be created at the high or low end of the memory object. The next argument should be an unsigned int.
The _Iguardloc keyword is equivalent to the Assembler GUARDLOC=, which indicates at which end of the memory object the guard area should be placed. The next argument should be the string HIGH to place the guard area at the top of the memory object, or LOW to place the guard area at the bottom of the memory object.
The _Ittoken keyword is equivalent to the Assembler TTOKEN=, which identifies a task to be assigned ownership of the memory object. The next argument should be a pointer to a 16 byte array. The array should be set from the result of a call to the assembler TCBTOKEN macro.
The _Iorigin keyword is equivalent to the Assembler ORIGIN=, which identifies where the address of a returned memory object will be placed. The next argument should be a _ _near pointer to a _ _huge pointer (type _ _huge * _ _near *) where the address should be stored. Note that the caller does not have to be compiled with the hugeptrs option. The returned _ _huge pointer is not dereferenced by this function. If the _Iguardloc parameter indicates that the guard area is LOW, then the returned _ _huge pointer must be bumped past the guard area before it is dereferenced.
The _Imatch keyword is equivalent to the Assembler MATCH=, which specifies whether an operation should be performed on a single memory object or all memory objects associated with a given usertoken. The next argument should be the string SINGLE to indicate only one memory object, or USERTOKEN to indicate all memory objects matching the usertoken indicated in the _Iusertkn parameter.
The _Imemobjstart keyword is equivalent to the Assembler MEMOBJSTART=, which identifies the address of the first byte of a memory object. The next argument should be a _ _huge pointer to a memory object.
The _Iowner keyword is equivalent to the Assembler OWNER=, which specifies whether a task other than the owning task (or a task specifying the correct TTOKEN) may free a memory object. The next argument should be the string YES to indicate that the task freeing the memory object must be the owner, or specify the correct TTOKEN for the memory object, or NO to indicate that the task freeing the memory object doesn not have to be the owner or provide the correct TTOKEN. Only supervisor state programs or programs running with a PSW key between 0-7 inclusive may use this parameter.
The _Iranglist keyword is equivalent to the Assembler RANGLIST=, which points to a list of 16 byte entries describing memory ranges. The number of entries is specified by _Inumrange. The next argument should be a _ _huge pointer to an array of entries consisting of starting address (itself a _ _huge pointer which must address a byte on a physical page boundry) and a long long containing the number of pages for a range.
The _Inumrange keyword is equivalent to the Assembler NUMRANGE=, which identifies the number of entries contained in the associated Iranglist list. The next argument should be an int containing the number of entries.
The _Iclear keyword is equivalent to the Assembler CLEAR=, which indicates whether the storage specified in a DISCARDDATA request will be cleared to binary zeros. The next argument should be the string YES to indicate that the memory should be cleared, or NO to indicate that the memory will be indeterminate after the DISCARDDATA request has completed.
The _Iconvert keyword is equivalent to the Assembler CONVERT=, which specifies in the CHANGEGUARD request whether the memory will be converted from or to a guard area. The next argument should be the string TOGUARD to indicate that memory should be converted from virtual storage to guard area, or FROMGUARD to indicate that the memory should be converted to virtual storage from the guard area. How the memory object was created determines whether the guard area is at the top or bottom of the memory object.
The _Iconvertsize keyword is equivalent to the Assembler CONVERTSIZE=, which specifies the size in megabytes of memory to be transferred to or from the guard area. The next argument should be an int containing the number of megabytes to be transferred.

The following parameters may only be specified in an authorized program.

The _Ilong keyword is equivalent to the Assembler LONG=, which indicates whether the expected duration of a PAGEFIX is long or short. If the time is expected to be more than a few seconds, then YES should be used. The next argument should be the string YES to indicate that the PAGEFIX is expected to be of long duration, or NO to indicate that the PAGEFIX is expected to be of short duration.
The _Ialetvalue keyword is equivalent to the Assembler ALETVALUE=, which specifies an ALET for the address space to be pagefixed. The only valid ALETs are 0 (primary) and 2 (home). The next argument should be an int containing either 0 or 2.
The _Iv64listptr keyword is equivalent to the Assembler V64LISTPTR=, which points to a buffer to hold the returned information from a LIST request. The next argument should be a _ _near pointer to a buffer where the list information will be returned. osiarv64.h contains C structures converted from the IAXV64WA assembler DSECT that can be used to map the returned list.
The _Iv64listlength keyword is equivalent to the Assembler V64LISTLENGTH=, which specifies the size of the buffer to contain the results from a LIST request. The next argument should be an int containing the length of the buffer.
The _Iv64select keyword is equivalent to the Assembler V64SELECT=, which indicates whether the LIST request is for all or just a subset of the allocated memory objects. The next argument should be the string YES to indicate that the LIST request is only for a subset of the allocated memory objects, or NO to indicate that the LIST request should return all allocated memory object data.
The _Iend keyword indicates the end of the list of keywords.

RETURN VALUE

IARV64 returns the value in R15 after calling the IARV64 OS macro. If the parms are in error though, it returns -1.

IMPLEMENTATION

The IARV64 function is implemented by the source module L$UIARV.

EXAMPLE 1

This SPE example gets one megabyte of above the bar memory (compile with the HUGEPTRS option):

#include <osmain.h>
#include 	<osiarv64.h>
#include 		<oswto.h>

char *string1; //(this pointer is _ _huge due to compile option)
int rc;

void osmain()
{

	
     rc = IARV64("GETSTOR", _Isegments, 1ll,            
           			_Iorigin, (__near *) &string1,  _Iend); 


		WTP("GETSTOR rc = %i", rc);       
		strcpy(string1, "hello world.");
     WTP("string1 = %~hpX, '%s'", string1, string1);
}

EXAMPLE 2

This example gets some storage in system keys and then displays a list of memory objects via the LIST request. This example is valid only if it is compiled with hugeptrs.

int num, x, reason;                    
long long adr;              
char list[255];             
struct V64WAHEADER *pHeader;
struct V64WAENTRY *pEntry;  
char *string1;


_ldregs(R1, 0x0000000C);                           
_ossvc(107);              // switch to supervisor state
rc = IARV64("GETSTOR", _Isegments, 1ll,            
            _Ikey, 0x20,                           
            _Iorigin, (_ _near *) &string1,  _Iend);
WTP("GETSTOR rc = %i", rc);                        
rc = IARV64("GETSTOR", _Isegments, 5000ll,         
            _Ikey, 0,                              
            _Iorigin, (_ _near *) &string1,  _Iend);
rc = IARV64("LIST", _Iv64listptr, (_ _near *) list, 
            _Ireason, (_ _near *) &reason,          
            _Iv64listlength, sizeof(list), _Iend); 
_ldregs(R1, 0x00000004);                           
_ossvc(107);              // return to problem state                         
if (rc == 0)                                                  
{                                                             
   pHeader = list;                                            
   WTP("V64WARETURNCODE = %i", pHeader->V64WARETURNCODE);     
   WTP("V64WANUMDATAAREAS = %i", pHeader->V64WANUMDATAAREAS); 
   pEntry = (struct V64WAENTRY *)                             
            ((char *) pHeader + V64WAHEADER_LEN);             
   x = 1;                                                     
   memcpy(&num, &pHeader->V64WANUMDATAAREAS, 4);              
   while (num--)                                              
   {                                                          
      WTP("x = %i", x++);                                     
      WTP(" Storage key = %02hhX", pEntry->v64waflag);        
      memcpy(&adr, &pEntry->v64wastart64, 8);                 
      WTP(" Start: %016llX", adr);                            
      memcpy(&adr, &pEntry->v64waend64, 8);                   
      WTP("   End: %016llX", adr);                            
      pEntry++;                                               
   }                                                          
}

RELATED FUNCTIONS

hpcreate, hpalloc

Chapter Contents
Previous
Next
Top of Page