Document revision date: 19 July 1999

A shared memory global section maps some amount of memory that can be accessed on all instances in a sharing community. These objects are also called Galaxywide shared sections. Each such object has a name, a version, and protection characteristics.

18.1 Using Shared Memory

Application programs access shared memory by mapping Galaxywide shared sections. The programming model is the same as for standard OpenVMS global sections; that is, you create, map, unmap, and delete them on each instance where you want to use them. Some shared memory global section characteristics are:

• Pages start out as demand zero with preallocated shared PFNs.
• Pages are not counted against your working set.
• Once the page is valid in your process' page table, it stays valid until it is deleted; shared memory section pages are never paged to disk.
• You must create the shared section on each instance where you want to access shared memory.
• Sections can be temporary or permanent.
• Sections can be group or system global sections.
• Galaxywide shared sections use a different name space than traditional global sections.
• Section versions specified in the ident_64 field are validated throughout the Galaxy.
• Only one shared section with a given name and UIC group can exist in a sharing community. This is different from traditional global sections, in which multiple versions can coexist.
• The SHMEM privilege is required to create a shared memory section.

From a programmer's point of view, shared memory global sections are similar to memory resident sections. You use the same system services to create Galaxywide shared sections that you would use to create memory resident sections. Setting the flag SEC$M_SHMGS lets the service operate on a shared memory global section.

In contrast to memory resident sections, the Reserved Memory Registry is not used to allocate space for Galaxywide sections. The SYSMAN RESERVE commands affect only node-private memory. Shared memory is not used for normal OpenVMS paging operations and does not need to be reserved.

There is also no user interface to specify whether shared page tables should be created for Galaxywide sections. Instead, creation of shared page tables for Galaxywide sections is tied to the section size. As of OpenVMS Version 7.2, shared page tables are created for sections of 128 pages (1MB) or more. Galaxywide shared page tables are shared between all Galaxy instances.

18.2 System Services

The following sections describe new and changed system services that support shared memory global sections.

18.2.1 Enhanced Services

The following system services have been enhanced to recognize the new shared memory global section flag SEC$M_SHMGS:

• SYS$CRMPSC_GDZRO_64
• SYS$CREATE_GDZRO
• SYS$MGBLSC_64
• SYS$DGBLSC

The following system services have been enhanced to work with shared memory, but no interfaces were changed:

• SYS$DELTVA
• SYS$DELTVA_64
• SYS$CREATE_BUFOBJ
• SYS$CREATE_BUFOBJ_64
• SYS$DELETE_BUFOBJ

The new section flag SEC$M_READ_ONLY_SHPT is recognized by the SYS$CREATE_GDZRO and SYS$CRMPSC_GDZRO_64 services. When this bit is set, it directs the system to create shared page tables for the sections that allow read access only. This feature is particularly useful in an environment where a memory resident or Galaxy shared section is used by many readers but only a single writer.

When you map a Galaxy shared section or a memory resident section that has an associated shared page table section, you have the following options for accessing data:

Shared Page Tables	Read Only	Read and Write
None created	Do not set the SEC$M_WRT flag in the map request. Private page tables will always be used, even if you are specifying a shared page table region into which to map the section.	Set the SEC$M_WRT flag in the map request. Private page tables will always be used, even if you are specifying a shared page table region into which to map the section.
Write access	Do not set the SEC$M_WRT flag in the map request. Ensure that private page tables will be used. Do not specify a shared page table region into which to map the section. If you do, the error status SS$_IVSECFLG is returned.	Set the SEC$M_WRT flag in the map request. The shared page table section will be used for mapping if you specify a shared page table region into which to map the section.
Read access	Do not set the SEC$M_WRT flag in the map request. The shared page table section will be used for mapping if you specify a shared page table region into which to map the section.	Set the SEC$M_WRT flag in the map request. Ensure that private page tables will be used. Do not specify a shared page table region into which to map the section. If you do, the error status SS$_IVSECFLG is returned.

The SHMEM privilege is required to create an object in Galaxy shared memory. The right to map to an existing section is controlled through normal access control mechanisms. SHMEM is not needed to map an existing section. Note that the VMS$MEM_RESIDENT_USER identifier, which is needed to create an ordinary memory resident section, is not required for Galaxywide sections.

Creating and mapping Galaxywide memory sections is accomplished through the same services used to create memory resident sections. The following services now recognize the SEC$M_SHMGS flag:

• SYS$CREATE_GDZRO
• SYS$CRMPSC_GDZRO_64
• SYS$MGBLSC_64
• SYS$DGBLSC

SYS$CREATE_GDZRO and SYS$CRMPSC_GDZRO_64 can also return new status codes. To be supplied---more details about these:

SS$_INV_SHMEM	Shared memory is not valid.
SS$_INSFRPGS	Insufficient free shared pages or private pages.
SS$_NOBREAK	A Galaxy lock is held by another node and was not broken.
SS$_LOCK_TIMEOUT	A Galaxy lock timed out.

$ INSTALL LIST/GLOBAL and $ SHOW MEMORY also know about Galaxywide sections.

Galaxywide sections are using their own name space. Just as you could always use the same name to identify system global sections and group global sections for various owner UICs, you can now also have Galaxywide system global sections and Galaxywide group global sections all with the same name.

Galaxywide sections also have their own security classes:

• GLXSYS_GLOBAL_SECTION
• GLXGRP_GLOBAL_SECTION

These security classes are used with the $GET_SECURITY, $SET_SECURITY system services, and the SET/SHOW SECURITY DCL commands.

These new security classes are only valid in a Galaxy environment. They are not recognized on a non-Galaxy node.

You can only retrieve and affect security attributes of Galaxywide global sections if they exist on your sharing instance.

Audit messages for Galaxywide sections look like this:

%%%%%%%%% OPCOM 20-MAR-1998 10:44:43.71 %%%%%%%% (from node GLX1 at 20-MAR-1998 10:44:43.85) Message from user AUDIT$SERVER on GLX1 Security alarm (SECURITY) on GLX1, system id: 19955 Auditable event: Object creation Event information: global section map request Event time: 20-MAR-1998 10:44:43.84 PID: 2040011A Process name: ANDY Username: ANDY Process owner: [ANDY] Terminal name: RTA1: Image name: MILKY$DKA100:[ANDY]SHM_MAP.EXE;1 Object class name: GLXGRP_GLOBAL_SECTION Object name: [47]WAY____D99DDB03_0$MY_SECTION Secondary object name: <Galaxywide global section> Access requested: READ,WRITE Deaccess key: 8450C610 Status: %SYSTEM-S-CREATED, file or section did not exist; has been created

Note the "Object name" record: the object name displayed here uniquely identifies the section in the OpenVMS Galaxy. The fields are as follows:

[47]	(only for group global sections) identifies the UIC group of the section creator.
WAY____D99DDB03_0$	An identifier for the sharing community.
MY_SECTION	The name of the section as specified by the user.

The user can only specify the section name and class for requests to set or show the security profile. The UIC is always obtained from the current process and the community identifier is obtained from the community in which the process executes.

The output for a Galaxywide system global section differs only in the fields "Object class name" and "Objects name." The object name for this type of section does not include a group identification field:

Object class name:	GLXSYS_GLOBAL_SECTION
Object name:	WAY____D99DDB03_0$SYSTEM_SECTION

19.1 SYS$CPU_TRANSITION

This service accepts 64-bit addresses. Parameter and bit definitions are resolved in $CSTDEF in the appropriate STARLET library.

Format

SYS$CPU_TRANSITION tran_code, cpu_id, nodename, node_id, flags, efn, iosb, astadr_64, astprm_64

Arguments

tran_code

OpenVMS usage:	longword
type:	longword (unsigned)
access:	read only
mechanism:	by value

Identifier specifying the type of state change to be initiated on the target CPU. The tran_code argument is a longword containing one of the following values:

Symbolic Name	Description
CST$K_CPU_STOP	The target CPU is to be removed from the active set and halted into console mode. It remains in the configure set of the current partition.
CST$K_CPU_MIGRATE	The target CPU is removed from the configure set of the local partition and the console is requested to add it to the configure set of the partition specified in node_id. If the CPU is currently in the active set, it is automatically brought to console mode through the CST$K_CPU_STOP function first.
CST$K_CPU_START	The target CPU is requested to exit console mode and join the active set of the current partition. The CPU must already be part of the configure set.
CST$K_CPU_FAILOVER	The CPU is assigned a default target partition where it will automatically migrate on system failure. This assignment persists until it is superseded. To remove an assignment or partition name, the current partition ID should be specified.

cpu_id

OpenVMS usage:	longword
type:	longword (unsigned)
access:	read only
mechanism:	by value

Identifier of the CPU whose state is to be modified. The cpu_id argument is a longword number in the supported range of individual CPUs from 0 to SYI$_MAX_CPUS - 1. In a Galaxy, this CPU must be in the configure set of the local partition or not assigned to any other partitions. The symbolic values, CST$K_ANY_LOCAL_CPU can be used in certain types of transitions to allow the next available processor of the appropriate type be used instead of a specific one.

node_id

OpenVMS usage:	longword
type:	longword (unsigned)
access:	read only
mechanism:	by value

Identifier of the target Galaxy partition in CST$K_CPU_ASSIGN, CST$K_CPU_FAILOVER, or CST$K_CPU_MIGRATE transition. The node_id argument is a longword containing a number in the supported range of IDs provided by the console for the current hardware platform. If the nodename parameter is specified, node_id is ignored.

flags

OpenVMS usage:	longword_mask
type:	longword (unsigned)
access:	read only
mechanism:	by value

Options selected for the CPU state transition. The flags argument is a longword bit vector wherein a bit corresponds to an option. Only the bits specified below are used; the remainder of the longword bits are reserved and must be 0.

Each option (bit) has a symbolic name. The flags argument is constructed by performing a logical OR operation using the symbolic names of the following options:

Symbolic Name	Description
CST$V_CPU_DEFAULT_CAPABILITIES	At the completion of the transition, the CPU's user capabilities are set back to the default system value. If this option is not specified, modified user capabilities are maintained across STOP and START transitions as long as the CPU remains in the local partition configure set.
CST$V_CPU_ALLOW_ORPHANS	The transition is to be allowed even though it will leave at least one thread in the system unable to execute on any CPU in the active set.

efn

OpenVMS usage:	ef_number
type:	longword (unsigned)
access:	read only
mechanism:	by value

The event flag to be set when the state transition attempt has completed. The efn argument is a longword specifying the number of the event flag; however, this service only uses the low-order byte.

When you invoke $CPU_TRANSITION, the specified event flag is cleared; when the operation is complete, the event flag is set.

iosb

OpenVMS usage:	io_status_area
type:	IOSB structure
access:	write only
mechanism:	by 32-bit or 64-bit reference

The I/O status area to receive the final completion status of the transition operation. The iosb argument is the 32-bit or 64-bit virtual address of the I/O status area. The I/O status area structure is 32 bytes in length; its definition can be found in $IOSBDEF in STARLET.MLB for macro and in the file IOSBDEF.H in SYS$STARLET_C.TLB for C.

When you call $CPU_TRANSITION, the I/O status area is cleared. After the transition operation is complete, the block is modified as follows:

Symbolic Name	Description
iosb$w_status	The first word contains the condition value return, indicating the final completion status of the operation.
	The first bit in the second word of the IOSB is set only if an error occurred during the operation; the remaining bits are zeroes.

astadr_64

OpenVMS usage:	ast_procedure
type:	procedure value
access:	call without stack unwinding
mechanism:	by 32-bit or 64-bit reference

The AST routine to be executed when the requested transition attempt has completed. The astadr_64 argument is the 32-bit or 64-bit virtual address of this routine. If you specify the astadr_64 argument, the AST routine executes at the access mode from which the state transition was requested.

astprm_64

OpenVMS usage:	user_arg
type:	quadword
access:	read only
mechanism:	by value

The quadword AST parameter to be passed to the AST routine.

Description

The state transition in tran_id is requested for the target cpu_id.

A CPU currently in the active set can transition:

• To the STOPPED state; removed from the active set and left in the configure set, halted in console mode

A CPU in the configure set can transition:

• To the ACTIVE state; warm rebooted and a full member of the SMP active set on the requesting partition
• To another partition through reassignment; the target CPU is removed from the configure set and added to the configure set of the partition specified by node_id

CPU state transition is a two-phase operation in the OpenVMS scheduling model. This service initiates the request in the process context of the caller and returns the setup status in the service condition value. Phase 2 proceeds asynchronously; the efn and iosb arguments can be used to indicate the completion of the transition through the standard wait system services. Additional notification of the completion can be made through the OpenVMS AST mechanisms using a routine specified in astadr_64 and a user-supplied parameter in astprm_64.

Required Privileges

The caller must have the CMKRNL privilege to call SYS$CPU_TRANSITION to modify CPU states.

Related Service: $CPU_TRANSITIONW

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_BADPARAM	One or more arguments has an invalid value or the specified CPU is not in the configuration.
SS$_ACCVIO	The service cannot access the locations specified by one or more arguments.
SS$_NOCMKRNL	Caller does not have CMKRNL privilege needed to complete operation.
SS$_INSFARG	Fewer than the required number of arguments were specified or no operation was specified.
SS$_TOO_MANY_ARGS	More arguments were specified than are allowed by the service.
SS$_INVCOMPID	The target gNode ID is not valid in this configuration.
SS$_CPUNOTACT	The specified CPU is not part of the current partition's active set.
SS$_NOSUCHCPU	The specified CPU does not exist in the current hardware configuration, or is not in the configure set of the local partition.
SS$_CPUSTARTD	The specified CPU is already in the local active set, or is in the process of joining it.
SS$_CPUSTOPPING	The specified CPU is already STOPPED or in the processing of leaving the active set.

	privacy and legal statement
6512PRO_012.HTML