 |
HP OpenVMS System Services Reference Manual
$CREATE_GALAXY_LOCK (Alpha Only)
Allocates an OpenVMS Galaxy lock block from a lock table created with
the $CREATE_GALAXY_LOCK_TABLE service.
Note that this system service is supported only in an OpenVMS Alpha
Galaxy environment.
For more information about programming with OpenVMS Galaxy system
services, refer to the HP OpenVMS Alpha Partitioning and Galaxy Guide.
Format
SYS$CREATE_GALAXY_LOCK lcktbl_handle ,name ,size ,timeout ,ipl ,rank
,handle
C Prototype
int sys$create_galaxy_lock (unsigned int lcktbl_handle, void *name,
unsigned int size, unsigned int timeout, unsigned int ipl, unsigned int
rank, unsigned __int64 *lock_handle);
Arguments
lcktbl_handle
| OpenVMS usage: |
lock table handle |
| type: |
longword (unsigned) |
| access: |
read |
| mechanism: |
input by value |
The 32-bit lock table handle that identifies the lock table in which to
create the lock. This value is returned by SYS$CREATE_GALAXY_LOCK_TABLE.
name
| OpenVMS usage: |
address |
| type: |
ASCID string |
| access: |
read |
| mechanism: |
input by reference |
The name parameter is a pointer to an ASCID string
(passed by descriptor). The name can be a maximum of 15 characters.
Lock names are not checked for uniqueness; therefore, multiple locks
can be created with the same name.
timeout
| OpenVMS usage: |
wait timeout |
| type: |
longword (unsigned) |
| access: |
read |
| mechanism: |
input by value |
The 32-bit wait or spin timeout specified in 10 microsecond units. If
not specified, the timeout defaults to 10 microseconds.
size
| OpenVMS usage: |
byte count |
| type: |
longword (unsigned) |
| access: |
read |
| mechanism: |
input by value |
The size of the galaxy lock in bytes. Galaxy locks have two legal
sizes. These values are returned by SYS$GET_GALAXY_LOCK_SIZE. The value
passed to SYS$CREATE_GALAXY_LOCK must be equal to the value passed to
the call to SYS$CREATE_GALAXY_LOCK_TABLE.
ipl
| OpenVMS usage: |
IPL of lock |
| type: |
longword (unsigned) |
| access: |
read |
| mechanism: |
input by value |
For galaxy locks acquired in kernel mode, the IPL to raise to while the
lock is held. This parameter is ignored for all other access mode.
rank
| OpenVMS usage: |
rank of lock |
| type: |
longword (unsigned) |
| access: |
read |
| mechanism: |
input by value |
Rank applied to a galaxy lock. Ranking is used to detect potential
deadlocks. This parameter is currently ignored.
handle
| OpenVMS usage: |
address |
| type: |
quadword (unsigned) |
| access: |
write |
| mechanism: |
output by reference |
The handle parameter is a pointer to a quadword. The value returned is
a 64-bit handle that uniquely identifies the lock galaxy-wide.
Description
This service allocates an OpenVMS Galaxy lock block from a lock table
created with the $CREATE_GALAXY_LOCK_TABLE service.
Required Access or Privileges
For System Lock: CMKRNL, SHMEM
For User Lock: SHMEM
Write access to Lock Table
Required Quota
None
Related Services
$ACQUIRE_GALAXY_LOCK, $CREATE_GALAXY_LOCK_TABLE, $DELETE_GALAXY_LOCK,
$DELETE_GALAXY_LOCK_TABLE, $GET_GALAXY_LOCK_INFO,
$GET_GALAXY_LOCK_SIZE, $RELEASE_GALAXY_LOCK
Condition Values Returned
|
SS$_NORMAL
|
Normal completion.
|
|
SS$_ACCVIO
|
Access violation on parameter.
|
|
SS$_BADLCKTBL
|
OpenVMS Galaxy lock table is corrupt.
|
|
SS$_BADPARAM
|
Bad parameter value.
|
|
SS$_IVLOCKID
|
Invalid lock id.
|
|
SS$_IVLOCKTBL
|
Invalid lock table.
|
|
SS$_INSFMEM
|
Insufficient memory in lock table.
|
|
SS$_NOCMKRNL
|
Operation requires CMKRNL privilege.
|
|
SS$_NOSHMEM
|
Operation requires SHMEM privilege.
|
$CREATE_GALAXY_LOCK_TABLE (Alpha Only)
Allocates an OpenVMS Galaxy lock table.
Note that this system service is supported only in an OpenVMS Alpha
Galaxy environment.
For more information about programming with OpenVMS Galaxy system
services, refer to the HP OpenVMS Alpha Partitioning and Galaxy Guide.
Format
SYS$CREATE_GALAXY_LOCK_TABLE name ,accmode ,section_size ,section_type
,prot ,lock_size ,lcktbl_handle
C Prototype
int sys$create_galaxy_lock_table (void *name, unsigned int accmode,
unsigned __int64 section_size, unsigned int section_type, unsigned int
prot, unsigned int lock_size, unsigned int *lcktbl_handle);
Arguments
name
| OpenVMS usage: |
address |
| type: |
ASCID string |
| access: |
read |
| mechanism: |
input by reference |
The name parameter is a pointer to an ASCID string (passed by
descriptor). The name is given to the global section that is created to
contain the galaxy locks.
accmode
| OpenVMS usage: |
access mode |
| type: |
longword (unsigned) |
| access: |
read |
| mechanism: |
input by value |
Access mode that is to be the owner of the pages created during the
mapping. The accmode argument is a longword containing
the access mode.
section_size
| OpenVMS usage: |
byte count |
| type: |
quadword (unsigned) |
| access: |
read |
| mechanism: |
input by value |
Length of the global section to be created, in bytes. The size must be
specified as a multiple of the CPU-specific page size. A size of zero
is illegal.
section_type
| OpenVMS usage: |
bit mask |
| type: |
longword (unsigned) |
| access: |
read |
| mechanism: |
input by value |
Used to control where in virtual memory the global section is created.
If GLCKTBL$C_PROCESS is specified, the section is created in P2
(process) space. If GLCKTBL$C_SYSTEM is specified, the section is
created in S0/S1 (system) space. These constants are defined in the
GLOCKDEF macro.
prot
| OpenVMS usage: |
protection |
| type: |
longword (unsigned) |
| access: |
read |
| mechanism: |
input by value |
Protection to be applied to the global section.
The mask contains four 4-bit fields. Bits are read from right to left
in each field. The following diagram depicts the mask:
Cleared bits indicate that read, write, execute, and delete access, in
that order, are granted to the particular category of user.
Only read and write access are meaningful for lock section protection.
Delete access bits are ignored.
lock_size
| OpenVMS usage: |
byte count |
| type: |
longword (unsigned) |
| access: |
read |
| mechanism: |
input by value |
The size of the galaxy lock in bytes. Galaxy locks have two sizes. The
legal values are returned by SYS$GET_GALAXY_LOCK_SIZE.
lcktbl_handle
| OpenVMS usage: |
address |
| type: |
longword |
| access: |
write |
| mechanism: |
output by reference |
Pointer to a longword. The value returned is a 32-bit handle that
uniquely identifies the lock table galaxy-wide.
Description
This service allocates an OpenVMS Galaxy lock table. This structure is
used to maintain information about a shared memory section, which this
service also creates. The first caller of the service with a unique
lock table name creates the section. Additional callers map it. This
shared memory section contains a set of Galaxy locks. All locks
residing in the section are of the same size. Once the lock table is
created, the $CREATE_GALAXY_LOCK service can be used to create and
allocate a lock from the table.
The flags GLCKTBL$C_PROCESS and GLCKTBL$C_SYSTEM specify whether the
shared memory region is mapped into system space or process space.
Creation of process space sections requires the SHMEM privilege.
Creation of system space sections requires the SHMEM and CMKRNL
privileges.
Required Access or Privileges
CMKRNL, SHMEM
Required Quota
None
Related Services
$ACQUIRE_GALAXY_LOCK, $CREATE_GALAXY_LOCK, $DELETE_GALAXY_LOCK,
$DELETE_GALAXY_LOCK_TABLE, $GET_GALAXY_LOCK_INFO,
$GET_GALAXY_LOCK_SIZE, $RELEASE_GALAXY_LOCK
Condition Values Returned
|
SS$_NORMAL
|
Normal completion.
|
|
SS$_ACCVIO
|
Access violation on parameter.
|
|
SS$_BADPARAM
|
Bad parameter value.
|
|
SS$_CREATED
|
File or section did not exist; has been created.
|
|
SS$_IVLOCKID
|
Invalid lock id.
|
|
SS$_NOPRIV
|
No privilege for attempted operation.
|
|
SS$_NOCMKRNL
|
Operation requires CMKRNL privilege.
|
|
SS$_NOSHMEM
|
Operation requires SHMEM privilege.
|
$CREATE_GDZRO (Alpha and I64)
On Alpha and I64 systems, creates a permanent, memory-resident, global
demand-zero section to which processes can map. Shared page table
sections can also be created.
This service accepts 64-bit addresses.
Format
SYS$CREATE_GDZRO gs_name_64 ,ident_64 ,prot ,length_64 ,acmode ,flags
[,reserved_length_64] [,rad_mask]
C Prototype
int sys$create_gdzro (void *gs_name_64, struct _secid *ident_64,
unsigned int prot, unsigned __int64 length_64, unsigned int acmode,
unsigned int flags,...);
Arguments
gs_name_64
| OpenVMS usage: |
section_name |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by 32- or 64-bit descriptor--fixed-length string
descriptor |
Name of the global section. The gs_name_64 argument is
the 32- or 64-bit virtual address of a naturally aligned 32- or 64-bit
string descriptor pointing to this name string.
ident_64
| OpenVMS usage: |
section_id |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference |
Identification value specifying the version number of the global
section. The ident_64 argument is a quadword
containing three fields. The ident_64 argument is the
32- or 64-bit virtual address of a naturally aligned quadword that
contains the identification value.
The first longword specifies the matching criteria in its low-order 2
bits. Their meanings are as follows:
| Value |
Symbolic Name |
Match Criteria |
|
0
|
SEC$K_MATALL
|
Match all versions of the section.
|
|
1
|
SEC$K_MATEQU
|
Match only if major and minor identifications match.
|
|
2
|
SEC$K_MATLEQ
|
Match if the major identifications are equal and the minor
identification of the mapper is less than or equal to the minor
identification of the global section.
|
If you specify the ident_64 argument as 0, the version
number and match control fields default to 0.
The version number is in the second longword. The version number
contains two fields: a minor identification in the low-order 24 bits
and a major identification in the high-order 8 bits. You can assign
values for these fields by installation convention to differentiate
versions of global sections. If no version number is specified when a
section is created, processes that specify a version number when
mapping cannot access the global section.
prot
| OpenVMS usage: |
file_protection |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Protection to be applied to the global demand-zero section. The mask
contains four 4-bit fields. Bits are read from right to left in each
field. The following diagram depicts the mask:
Cleared bits indicate that read, write, execute, and delete access, in
that order, are granted to the particular category of user. Only read,
write, and execute access are meaningful for section protection. Delete
access bits are ignored. Read access also grants execute access for
those situations where execute access applies. If 0 is specified, read
access and write access are granted to all users.
length_64
| OpenVMS usage: |
byte count |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Length, in bytes, of the global demand-zero section to be created. The
length_64 argument must be specified as a multiple of
the CPU-specific page size. A length of 0 cannot be specified.
Note
Creating a memory-resident global section with shared page tables does
not imply that the global section must have a length that is an even
multiple of CPU-specific page table pages. The global section might not
fully use the last shared page table page.
|
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode that is to be the owner of the pages created during the
mapping. The acmode argument is a longword containing
the access mode.
If the memory-resident global section is created with shared page
tables, this is the access mode that is stored in the owner, read, and
write fields of the corresponding shared page table entries (PTEs).
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values for the
four access modes:
| Value |
Symbolic Name |
Access Mode |
|
0
|
PSL$C_KERNEL
|
Kernel
|
|
1
|
PSL$C_EXEC
|
Executive
|
|
2
|
PSL$C_SUPER
|
Supervisor
|
|
3
|
PSL$C_USER
|
User
|
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Flag mask specifying the type of global section to be created as well
as its characteristics. The flags argument is a
longword bit vector in which each bit corresponds to a flag. The
$SECDEF macro and the SECDEF.H file define a symbolic name for each
flag. You construct the flags argument by performing a
logical OR operation on the symbol names for all desired flags.
The following table describes the flags that are valid for the
$CREATE_GDZRO service:
| Flag |
Description |
|
SEC$M_DZRO
|
Pages are demand-zero pages. By default, this flag is always present in
this service and cannot be disabled.
|
|
SEC$M_GBL
|
Pages form a global section. By default, this flag is always present in
this service and cannot be disabled.
|
|
SEC$M_MRES
|
Pages form a memory-resident section. By default, this flag is always
present in this service and cannot be disabled.
|
|
SEC$M_PERM
|
Global section is permanent. By default, this flag is always present in
this service and cannot be disabled.
|
|
SEC$M_RAD_HINT
|
When set, the argument
rad_mask is used as a mask of RADs from which to
allocate memory. See the
rad_mask argument description for more information.
|
|
SEC$M_READ_ONLY_SHPT
|
Create shared table pages for the section that allow read access only.
|
|
SEC$M_SHMGS
|
Create a shared-memory global section.
|
|
SEC$M_SYSGBL
|
Pages form a system global section. By default, pages form a group
global section.
|
|
SEC$M_WRT
|
Pages form a read/write section. By default, this flag is always
present in this service and cannot be disabled.
|
All other bits in the flags argument are reserved for
future use by HP and should be specified as 0. The condition value
SS$_IVSECFLG is returned if any undefined bits are set.
reserved_length_64
| OpenVMS usage: |
byte count |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
32- or 64-bit reference |
Length, in bytes, of the global section as currently registered in the
Reserved Memory Registry. The reserved_length_64
argument is the 32- or 64-bit virtual address of a naturally aligned
quadword into which the service returns the reserved length.
If reserved_length_64 is not specified or is specified
as 0, no reserved length is returned to the caller.
If the memory-resident global section is not registered,
reserved_length_64 is written with the value 0.
rad_mask
| OpenVMS usage: |
mask_quadword |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Use the rad_mask argument to specify from which RADs
to allocate memory. Currently only one bit may be set. The specified
RAD must contain memory. This argument is only a hint. Memory may be
obtained from other RADs if no free memory is available at the time of
allocation.
The rad_mask argument is considered only if the
SEC$M_RAD_HINT flag is specified. Otherwise, this argument is ignored.
On a system that does not support resource affinity domains (RADs),
specifying 1 for the rad_mask argument is allowed.
Note: OpenVMS support for RADs is available only on the AlphaServer GS series systems. For more information about using RADs, refer to the HP OpenVMS Alpha Partitioning and Galaxy Guide.
Description
The Create Permanent Global Demand-Zero Section service allows a
process to create a permanent, memory-resident, global demand-zero
section. If you set the SEC$M_SHMGS flag, the section is created as a
Galaxy-wide global demand-zero section in shared memory.
You must call either the $CREATE_GDZRO service or the $CRMPSC_GDZRO_64
service on each instance where the Galaxy shared memory will be
accessed.
Memory-resident or Galaxy-wide global sections contain demand-zero
allocation pages that are writable and memory resident. All pages in
these types of global section are shared by all processes that map to
the global section.
The pages are always resident in memory and are not backed up by any
file on any disk. The pages are not placed into the process's working
set list when the process maps to the global section and the virtual
memory is referenced by the process. The pages are also not charged
against the process's working set quota or against any page-file quota.
To create a memory-resident section, the process must have the rights
identifier, VMS$MEM_RESIDENT_USER. The error status, SS$_NOMEMRESID, is
returned if the caller has not been granted this identifier. To create
a Galaxy-wide shared section, the process must have the SHMEM privilege.
Only memory-resident sections can be registered with the Reserved
Memory Registry in the SYSMAN facility. Memory for Galaxy-wide shared
sections is reserved through appropriate settings of the console
environment parameters.
If the section is not registered in the Reserved Memory Registry, or if
the /NOALLOCATE qualifier was specified when the global section was
registered in the Reserved Memory Registry, invalid global PTEs are
written to the global page table. When the global section is mapped,
invalid page table entries are placed in the process page table.
Physical memory is not allocated until the pages are referenced.
If the global section is registered in the Reserved Memory Registry,
the size of the global section need not match the reserved size. If the
global section is not registered in the Reserved Memory Registry, or if
the reserved size is smaller than the size of the global section, the
error status SS$_INSFLPGS is returned if there are not enough fluid
pages in the system to satisfy the request.
If the /ALLOCATE qualifier was specified when the global section was
registered in the Reserved Memory Registry, contiguous, aligned,
physical pages are preallocated during system initialization for this
global section. Valid page table entries are placed in the global page
table and when the global section is mapped, valid page table entries
are placed in the process page table. With the proper virtual
alignment, granularity hints (GH) are used to map to the global pages.
If the global section is not registered in the Reserved Memory
Registry, or if the /PAGE_TABLES qualifier was specified when the
global section was registered, shared page tables are created for the
memory-resident global section.
If the /ALLOCATE and /PAGE_TABLE qualifiers were specified when the
global section was registered in the Reserved Memory Registry,
contiguous, aligned physical pages are preallocated during system
initialization for this global section, and granularity hints are used
to map to the shared page table sections.
The following table lists the factors affecting the creation of shared
page tables for memory-resident global sections. The /ALLOCATE and the
/PAGE_TABLES qualifiers pertain to the Reserved Memory Registry command
RESERVED_MEMORY ADD entered for the memory-resident global section
being created. For more information about using the SYSMAN utility to
create entries to the Reserved Memory Registry, refer to the
HP OpenVMS System Management Utilities Reference Manual.
| /ALLOCATE |
/PAGE_TABLES |
Outcome |
|
Not registered
|
Not registered
|
Shared page tables created.
Shared page tables cannot use GH.
Returns SS$_CREATED_SHPT.
|
|
No
|
No
|
No shared page tables created.
Returns SS$_CREATED.
|
|
No
|
Yes
|
Shared page tables created.
Shared page tables cannot use GH.
Returns SS$CREATED_SHPT.
|
|
Yes
|
No
|
No shared page tables created.
Returns SS$_CREATED.
|
|
Yes
|
Yes
|
Shared page tables created.
Shared page tables can use GH.
Returns SS$_CREATED_SHPT.
|
|
