|
HP OpenVMS systems documentation |
Previous | Contents | Index |
This chapter describes the following features that support 64-bit addressing:
For information about MACRO-32 programming support for 64-bit
addressing, see HP OpenVMS MACRO Compiler Porting and User's Guide.
11.1 System Services Support for 64-Bit Addressing
This chapter describes the OpenVMS Alpha and OpenVMS I64 system services that support 64-bit addressing and VLM. It explains the changes made to 32-bit services to support 64-bit addresses, and it lists the 64-bit system services.
To see examples of system services that support 64-bit addressing in an
application program, refer to Appendix B. For complete information
about the OpenVMS system services listed in this chapter, see the
HP OpenVMS System Services Reference Manual: A--GETUAI and HP OpenVMS System Services Reference Manual: GETUTC--Z.
11.1.1 System Services Terminology
The following system services definitions are used throughout this guide.
32-bit system service
A 32-bit system service is a system service that only supports 32-bit addresses on any of its arguments that specify addresses. If passed by value, on OpenVMS Alpha and OpenVMS I64 a 32-bit virtual address is actually a 64-bit address that is sign-extended from 32 bits.64-bit friendly interface
A 64-bit friendly interface is an interface that can be called with all 64-bit addresses. A 32-bit system service interface is 64-bit friendly if it needs no modification to handle 64-bit addresses. The internal code that implements the system service might need modification, but the system service interface will not.Examples of 64-bit friendly system services are $QIO, $SYNCH, $ENQ, and $FAO.
Examples of routines with 64-bit unfriendly interfaces are most of the memory management system services, such as $CRETVA, $DELTVA, and $CRMPSC. The INADR and RETADR argument arrays do not promote easily to hold 64-bit addresses.
64-bit system service
A 64-bit system service is a system service that is defined to accept all address arguments as 64-bit addresses (not necessarily 32-bit, sign-extended values). Also, a 64-bit system service uses the entire 64 bits of all virtual addresses passed to it.The 64-bit system services include the _64 suffix for services that accept 64-bit addresses by reference. For promoted services, this distinguishes the 64-bit capable version from its 32-bit counterpart. For new services, it is a visible reminder that a 64-bit wide address cell will be read/written. This is also used when a structure is passed that contains an embedded 64-bit address, if the structure is not self-identifying as a 64-bit structure. Hence, a routine name need not include "_64" simply because it receives a 64-bit descriptor. Remember that passing an arbitrary value by reference does not mean the suffix is required; passing a 64-bit address by reference does.
This section describes 32-bit and 64-bit descriptors. Descriptors are a mechanism for passing parameters where the address of a descriptor is an entry in the argument list. Descriptors contain the address of the parameter, data type, size, and any additional information needed to describe the passed data.
There are two forms of descriptors:
The two forms are compatible, because they can be identified dynamically at run time, and except for the size and placement of fields, 32-bit and 64-bit descriptors are identical in content and interpretation.
OpenVMS VAX, OpenVMS Alpha, and OpenVMS I64 systems use 32-bit descriptors. When used on OpenVMS Alpha and OpenVMS I64 systems, 32-bit descriptors provide full compatibility with their use on OpenVMS VAX. The 64-bit descriptors are used only on OpenVMS Alpha and OpenVMS I64 systems. They have no counterparts and are not recognized on OpenVMS VAX systems.
Figure 11-1 shows the general descriptor format for a 32-bit descriptor.
Figure 11-1 General Format of a 32-Bit Descriptor
Figure 11-2 shows the general descriptor format for a 64-bit descriptor.
Figure 11-2 General Format of a 64-Bit Descriptor
When 32-bit descriptors are used on OpenVMS Alpha and OpenVMS I64 systems, they have no required alignment for compatibility with OpenVMS VAX systems, even though longword alignment usually promotes better performance. The 64-bit descriptors on OpenVMS Alpha and OpenVMS I64 systems must be quadword aligned.
Table 11-1 shows the fields and meanings for both 32-bit and 64-bit descriptors. Because CLASS and DTYPE fields occupy the same offsets in both 32-bit and 64-bit descriptors, these two fields have the same definition, and can contain the same values with the same meanings in both 32-bit and 64-bit forms.
Field | Description |
---|---|
Length | The data item length specific to the descriptor class. |
MBO | In a 64-bit descriptor, this field must contain the value 1. This field overlays the length field of a 32-bit descriptor and the value 1 is necessary to distinguish correctly between the two forms. |
Dtype | A data-type code. |
Class | A descriptor class code that identifies the format and interpretation of the other fields of the descriptor. |
Pointer | The address of the first byte of the data element described. |
MBMO | In a 64-bit descriptor, this field must contain the value -1 (all 1 bits). This field overlays the pointer field of a 32-bit descriptor and the value -1 is necessary to distinguish correctly between the two forms. |
For extensive information about 32-bit and 64-bit descriptors, see Chapter 17. Section 11.4 provides serveral recommendations and guidelines on implementing 64-bit descriptors.
It is recommended programming practice to use STR$ Run-Time Library
routines when using descriptors. Using STR$ RTL procedures helps ensure
correct operation of complex language features and enforces consistent
operations on data access languages. For example, STR$ANALYZE_SDESC and
STR$ANALYZE_SDESC_64 take as input a 32-bit or 64-bit descriptor
argument and extract from the descriptor the length of the data and the
address at which the data starts for a variety of string descriptor
classes. For complete information on using STR$ routines, see the
OpenVMS RTL String Manipulation (STR$) Manual.
11.1.3 Comparison of 32-Bit and 64-Bit Item Lists
The following sections describe item lists and compare the 32-bit and 64-bit type of item lists. Item lists are a mechanism used in OpenVMS system services to pass a list of options and/or data descriptors to a service. Occasionaly, item lists are used elsewhere, such as in a single routine in LIBRTL, but they are generally considered specific to the OpenVMS system programming interface. They are not in the OpenVMS Calling Standard.
Item lists that are of the 32-bit type are structures or arrays that consist of one or more item descriptors and the list of the item is terminated by a longword containing a zero. Each item descriptor is either a two or three longword structure that contains either three or four fields.
Like 32-bit item lists, 64-bit item lists are structures or arrays that consist of one or more item descriptors, but unlike the 32-bit item lists, the list of the item is terminated by a quadword containing a zero, instead of a longword.
Item List Chaining and Segments
An item list is an array structure that occupies contiguous memory. Some system services support item codes that allow item lists that are non-contiguous and scattered throughout memory to be chained or linked together. Chained item lists are distinct item lists because they are directly linked. For example, the NSA$_CHAIN item code of the $AUDIT_EVENT system service specifies the item list to process immediately after the current one. The buffer address field in the item descriptor specifies the address of the next item list to be processed. Similarly, the LNM$_CHAIN item code of $CRELNM and JPI$_CHAIN item code of $GETJPI system services, point to another item list that the respective system service is to process immediately after it has processed the current item list.
Item lists of 32-bits and 64-bits can be chained together.
Item list segments are the elements that get linked together to form
item lists.
11.1.3.1 32-Bit Item Lists
Item lists do not have a formal definition. As a result, there is some variance in their use, but nearly every use consists of a list of one of two forms, referred to as the following:
In both forms, an item code typically identifies the data item to be set or fetched, and a buffer length and address describe the buffer to be read from or written to. The item codes are specific to the facility being called.
Figure 11-3 shows the format of the item_list_2 item list.
Figure 11-3 Item_list_2 Format
Figure 11-4 shows the format of the item_list_3 item list.
Figure 11-4 Item_list_3 Format
The following table defines the fields for 32-bit item list entries:
Field | Description |
---|---|
Buffer length | A word containing a user-supplied integer specifying the length (in bytes) of the buffer in which the service is to write the information. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor. |
Item code | A word containing a user-supplied symbolic code specifying the item of information that a service is to return. |
Buffer address | A longword containing the user-supplied 32-bit address of the buffer in which a service is to write the information. |
Return length address | A longword containing the user-supplied 32-bit address of a word in which a service writes the length (in bytes) of the information it actually returned. |
You typically use the item_list_3 format when the list describes a series of data items to be returned. This format includes a return length address longword, which is the address of a location in which to write the (word) length of data actually written to the buffer.
For item_list_3 entries, you can set the Return Length Address field to
point to the Buffer Length field in the item list entry itself. As a
result, the "descriptor-like" portion of the entry is updated by the
routine returning the value.
11.1.3.2 64-Bit Item Lists
To maintain a degree of compatibility with the 32-bit item lists, 64-bit item lists mirror the definition of 64-bit descriptors.
The names of 32-bit item lists (item_list_2 and item_list_3), which expose the number of longwords in the structure in the name itself, do not apply to 64-bit item lists. The 64-bit versions (item_list_64a and item_list_64b) do not include an element count.
Figure 11-5 shows the format of the item_list_64a item list.
Figure 11-5 Item_list_64a Format
Figure 11-6 shows the format of the item_list_64b item list.
Figure 11-6 Item_list_64b Format
The following table defines the item descriptor fields for 64-bit item list entries:
Field | Description |
---|---|
MBO | The field must contain a 1. The MBO and MBMO fields are used to distinguish 32-bit and 64-bit item list entries. |
Item code | A word containing a user-supplied symbolic code that describes the information in the buffer or the information to be returned to the buffer, pointed to by the buffer address field. |
MBMO | The field must contain a -1. The MBMO and MBO fields are used to distinguish 32-bit and 64-bit item list entries. |
Buffer length | A quadword containing a user-supplied integer specifying the length (in bytes) of the buffer in which a service is to write the information. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor. |
Buffer address | A quadword containing the user-supplied 64-bit address of the buffer in which a service is to write the information. |
Return length address | A quadword containing the user-supplied 64-bit address of a word in which a service writes the length (in bytes) of the information it actually returned. |
Because they contain quadword entries, 64-bit item lists should be quadword aligned. If a misaligned list is specified, the called routine still functions properly, but a performance penalty results due to alignment faults.
By maintaining a degree of compatibility between 32-bit and 64-bit item lists, the following advantages result:
Section 11.4 provides several recommendations and guidelines on
implementing 64-bit item lists.
11.1.4 System Services That Support 64-Bit Addresses
Table 11-2 summarizes the OpenVMS Alpha and OpenVMS I64 system services that support 64-bit addresses.
Although RMS system services provide some 64-bit addressing capabilities, they are not listed in this table because they are not full 64-bit system services. See Section 11.2 for more details.
Service | Arguments |
---|---|
Alignment System Services | |
$GET_ALIGN_FAULT_DATA | buffer_64, buffer_size, return_size_64 |
$GET_SYS_ALIGN_FAULT_DATA | buffer_64, buffer_size, return_size_64 |
$INIT_SYS_ALIGN_FAULT_REPORT | match_table_64, buffer_size, flags |
AST System Service | |
$DCLAST | astadr_64, astprm_64, acmode |
Condition Handling System Services | |
$FAO | ctrstr_64, outlen_64, outbuf_64, p1_64...pn_64 |
$FAOL | ctrstr_64, outlen_64, outbuf_64, long_prmlst_64 |
$FAOL_64 | ctrstr_64, outlen_64, outbuf_64, quad_prmlst_64 |
$GETMSG | msgid, msglen_64, bufadr_64, flags, outadr_64 |
$PUTMSG | msgvec_64, actrtn_64, facnam_64, actprm_64 |
$SIGNAL_ARRAY_64 | mcharg, sigarg_64 |
CPU Scheduling System Services | |
$CPU_CAPABILITIES | cpu_id, select_mask, modify_mask, prev_mask, flags |
$CPU_TRANSITION(W) | tran_code, cpu_id, nodename, node_id, flags, efn, iosb, astadr_64, astprm_64 |
$FREE_USER_CAPABILITY | cap_num, prev_mask, flags |
$GET_USER_CAPABILITY | cap_num, select_num, select_mask, prev_mask, flags |
$PROCESS_AFFINITY | pidadr, prcnam, select_mask, modify_mask, prev_mask, flags |
$PROCESS_CAPABILITIES | pidadr, prcnam, select_mask, modify_mask, prev_mask, flags |
$SET_IMPLICIT_AFFINITY | pidadr, prcnam, state, cpu_id, prev_mask |
Event Flag System Service | |
$READEF | efn, state_64 |
Fast-I/O System Services | |
$IO_CLEANUP | fandle |
$IO_PERFORM | fandle, chan, iosadr, bufadr, buflen, porint |
$IO_PERFORMW | fandle, chan, iosadr, bufadr, buflen, porint |
$IO_SETUP | func, bufobj, iosobj, astadr, flags, return_fandle |
Intra-Cluster Communications System Services | |
SYS$ICC_ACCEPT | conn_handle, accept_buf, accept_len, user_context, flags |
SYS$ICC_CONNECT(W) | ios_icc, astadr, astprm, assoc_handle, conn_handle, remote_assoc, remote_node, user_context, conn_buf, conn_buf_len, return_buf, return_buf_len, retlen_addr, flags |
SYS$ICC_DISCONNECT(W) | conn_handle, iosb, astadr, astprm, disc_buf, disc_buf_len |
SYS$ICC_OPEN_ASSOC | asoc_handle, assoc_name, logical_name, logical_table, conn_event_rtn, disc_event_rtn, recv_rtn, maxflowbufcut, prot |
SYS$ICC_RECEIVE(W) | conn_handle, ios_icc, astadr, astprm, recv_buf, recv_buf_len |
SYS$ICC_REJECT | conn_handle, reject_buf, reject_buf_len, reason |
SYS$ICC_REPLY(W) | conn_handle, ios_icc, astadr, astprm, reply_buf, reply_len |
SYS$ICC_TRANSCEIVE(W) | conn_handle, ios_icc, astadr, astprm, send_buf, send_len |
SYS$ICC_TRANSMIT(W) | conn_handle, ios_icc, astadr, astprm, send_buf, send_len |
I/O System Services | |
$ASSIGN | devnam, chan, acmode, mbxnam, flags |
$QIO(W) 1 | efn, chan, func, iosb_64, astadr_64, astprm_64, p1_64, p2_64, p3_64, p4_64, p5_64, p6_64 |
$SYNCH | efn, iosb_64 |
Locking System Services | |
$DEQ | lkid, vablk_64, acmode, flags |
$ENQ(W) | efn, lkmode, lksb_64, flags, resnam_64, parid, astadr_64, astprm_64, blkast_64, acmode |
Logical Name System Services | |
$CRELNM | attr, tabnam, lognam, acmode, itmlst |
$CRELNT | ttr, resnam, reslen, quota, promsk, tabnam, partab, acmode |
$DELLNM | tabnam, lognam, acmode |
$TRNLNM | attr, tabnam, lognam, acmode, itmlst |
Memory Management System Services | |
$ADJWSL | pagcnt, wsetlm_64 |
$CREATE_BUFOBJ_64 | start_va_64, length_64, acmode, flags, return_va_64, return_length_64, return_buffer_handle_64 |
$CREATE_GDZRO | gsdnam_64, ident_64, prot, length_64, acmode, flags, ... |
$CRMPSC_GDZRO_64 | gsdnam_64, ident_64, prot, length_64, region_id_64, section_offset_64, acmode, flags, return_va_64, return_length_64, ... |
$CREATE_GFILE | gsdnam_64, ident_64, file_offset_64, length_64, chan, acmode, flags, return_length_64, ... |
$CREATE_GPFILE | gsdnam_64, ident_64, prot, length_64, acmode, flags |
$CREATE_GPFN | gsdnam_64, ident_64, prot, start_pfn, page_count, acmode, flags |
$CREATE_REGION_64 | length_64, region_prot, flags, return_region_id_64, return_va_64, return_length_64, ... |
$CRETVA_64 | region_id_64, start_va_64, length_64, acmode, flags, return_va_64, return_length_64 |
$CRMPSC_FILE_64 | region_id_64, file_offset_64, length_64, chan, acmode, flags, return_va_64, return_length_64, ... |
$CRMPSC_GFILE_64 | gsdnam_64, ident_64, file_offset_64, length_64, chan, region_id_64, section_offset, acmode, flags, return_va_64, return_length_64, ... |
$CRMPSC_GPFILE_64 | gsdnam_64, ident_64, prot, length_64, region_id_64, section_offset_64, acmode, flags, return_va_64, return_length_64, ... |
$CRMPSC_GPFN_64 | gsdnam_64, ident_64, prot, start_pfn, page_count, region_id_64, relative_page, acmode, flags, return_va_64, return_length_64, ... |
$CRMPSC_PFN_64 | region_id_64, start_pfn, page_count, acmode, flags, return_va_64, return_length_64, ... |
$DELETE_BUFOBJ | buffer_handle_64 |
$DELETE_REGION_64 | region_id_64, acmode, return_va_64, return_length_64 |
$DELTVA_64 | region_id_64, start_va_64, length_64, acmode, return_va_64, return_length_64 |
$DGBLSC | flags, gsdnam_64, ident_64 |
$EXPREG_64 | region_id_64, length_64, acmode, flags, return_va_64, return_length_64 |
$GET_REGION_INFO | function_code, region_id_64, start_va_64, ,buffer_length, buffer_address_64, return_length_64 |
$LCKPAG_64 | start_va_64, length_64, acmode, return_va_64, return_length_64 |
$LKWSET_64 | start_va_64, length_64, acmode, return_va_64, return_length_64 |
$MGBLSC_64 | gsdnam_64, ident_64, region_id_64, section_offset_64, length_64, acmode, flags, return_va_64, return_length_64, ... |
$MGBLSC_GPFN_64 | gsdnam_64, ident_64, region_id_64, relative_page, page_count, acmode, flags, return_va_64, return_length_64, ... |
$PURGE_WS | start_va_64, length_64 |
$SETPRT_64 | start_va_64, length_64, acmode, prot, return_va_64, return_length_64, return_prot_64 |
$ULKPAG_64 | start_va_64, length_64, acmode, return_va_64, return_length_64 |
$ULWSET_64 | start_va_64, length_64, acmode, return_va_64, return_length_64 |
$UPDSEC_64(W) | start_va_64, length_64, acmode, updflg, efn, iosa_64, return_va_64, return_length_64, ... |
Process Control System Services | |
$GETJPI(W) | efn, pidadr, prcnam, itmlst, iosb, astadr, astprm |
$PROCESS_SCAN | pidctx, itmlst |
$WAKE | pidadr, prcnam |
Time System Services | |
$ASCTIM | timlen, timbuf, timadr, cvtflg |
$ASCUTC | timlen, timbuf, utcadr, cvtflg |
$BINTIM | timbuf, timadr |
$BINUTC | timbuf, utcadr |
$CANTIM | reqidt_64, acmode |
$GETTIM | timadr_64 |
$GETUTC | utcadr |
$NUMTIM | timbuf, timadr |
$NUMUTC | timbuf, utcadr |
$SETIME | timadr |
$SETIMR | efn, daytim_64, astadr_64, reqidt_64, flags |
$TIMCON | timadr, utcadr, cvtflg |
Other System Services | |
$ASCTOID | name, id, attrib |
$CLEAR_UNWIND_TABLE | code_base_va |
$CMEXEC_64 | routine_64, quad_arglst_64 |
$CMKRNL_64 | routine_64, quad_arglst_64 |
$FINISH_RDB | context |
$GETSYI(W) | efn, csidadr, nodename, itmlst, iosb, astadr, astprm |
$GET_UNWIND_ENTRY_INFO | pc, get_ue_block, name |
$GOTO_UNWIND_64 | target_invo, target_pc, [NewRetVal], [NewRetVal2] |
$IDTOASC | id, namlen, nambuf, resid, attrib, contxt |
$SET_UNWIND_TABLE | code_base_va, code_size, ut_base_va, ut_size, gp_value, unwind_info_base, name |
Previous | Next | Contents | Index |