|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
OpenVMS system services not listed in Table 11-2 and all
user-written system services that are not explicitly enhanced to accept
64-bit addresses will receive sign-extension checking. Any argument
passed to these services that is not properly sign-extended will cause
the error status SS$_ARG_GTR_32_BITS to be returned.
11.1.6 Language Support for 64-Bit System Services
C function prototypes for system services are available in SYS$LIBRARY:SYS$STARLET_C.TLB (or STARLET).
No 64-bit MACRO-32 macros are available for system services. The
MACRO-32 caller must use the AMACRO built-in EVAX_CALLG_64 or the
$CALL64 macro. For more information about MACRO-32 programming support
for 64-bit addressing, see HP OpenVMS MACRO Compiler Porting and User's Guide.
11.2 RMS Interface Features for 64-Bit Addressing
This section summarizes features that support 64-bit addressing and enable you to use RMS to perform input and output operations to P2 or S2 space. You can take full advantage of these RMS features by making only minor modifications to existing RMS code.
For complete information about RMS support for 64-bit addressing, see the OpenVMS Record Management Services Reference Manual.
The RMS user interface consists of a number of control data structures (FAB, RAB, NAM, XABs). These are linked together with 32-bit pointers and contain embedded pointers to I/O buffers and various user data buffers, including file name strings and item lists. RMS support for 64-bit addressable regions allows 64-bit addresses for the following user I/O buffers:
The prompt buffer pointed to by RAB$L_PBF is excluded because the terminal driver does not allow 64-bit addresses.
Specific features of the RMS interface for 64-bit addressing are as follows:
The rest of the RMS interface currently is restricted to 32-bit pointers:
The RAB64, a RMS user interface structure, is an extended RAB that can accommodate 64-bit buffer addresses. The RAB64 data structure consists of a 32-bit RAB structure followed by a 64-bit extension.
The RAB64 contains fields identical to all of the RAB fields except that field names have the RAB64 prefix instead of the RAB prefix. In addition, RAB64 has the following fields in the extension:
| This field... | Is an extension of this field |
Description |
|---|---|---|
| RAB64$Q_CTX | RAB64$L_CTX | User context. This field is not used by RMS but is available to the user. The CTX field is often used to contain a pointer. For asynchronous I/O, it provides the user with the equivalent of an AST parameter. |
| RAB64$PQ_KBF | RAB64$L_KBF | Key buffer address containing the key value for random access (for $GET and $FIND). |
| RAB64$PQ_RBF | RAB64$L_RBF | Record buffer address (for $PUT, $UPDATE, and $WRITE). |
| RAB64$PQ_RHB | RAB64$L_RHB | Record header buffer address (fixed portion of VFC record format). |
| RAB64$Q_RSZ | RAB64$W_RSZ | Record buffer size. |
| RAB64$PQ_UBF | RAB64$L_UBF | User buffer address (for $GET and $READ). |
| RAB64$Q_USZ | RAB64$W_USZ | User buffer size. |
Note that the fields with the PQ tag in their names can hold either a 64-bit address or a 32-bit address sign-extended to 64 bits. Therefore, you can use the fields in all applications whether or not you are using 64-bit addresses.
For most record I/O service requests, there is an RMS internal buffer between the device and the user's data buffer. The one exception occurs with the RMS service $PUT. If the device is a unit record device and it is not being accessed over the network, RMS passes the address of the user record buffer (RBF) to the $QIO system service. If you inappropriately specify a record buffer (RBF) allocated in 64-bit address space for a $PUT to a unit record device that does not support 64-bit address space (for example, a terminal), the $QIO service returns SS$_NOT64DEVFUNC. (See Writing OpenVMS Alpha Device Drivers in C and HP OpenVMS Guide to Upgrading Privileged-Code Applications for more information about $QIO.) RMS returns the error status RMS$_SYS with SS$_NOT64DEVFUNC as the secondary status value in RAB64$L_STV.
RMS system services support the RAB structure as well as the RAB64
structure.
11.2.2 Using the 64-Bit RAB Extension
Only minimal source code changes are required for applications to use 64-bit RMS support.
RMS allows you to use the RAB64 wherever you can use a RAB. For example, you can use RAB64 in place of a RAB as the first argument passed to any of the RMS record or block I/O services.
Because the RAB64 is an upwardly compatible extension of the existing RAB, most source modules can treat references to fields in a RAB64 as if they were references to a RAB. The 64-bit buffer address counterpart is used by the source module only if the following two conditions are met:
The source module uses the value in the quadword size field only if the contents of the 32-bit address field designate its use. For example:
| If this address field contains -1 | The address in this field is used |
And the size in this field is used |
|---|---|---|
| RAB64$L_UBF | RAB64$PQ_UBF 1 | RAB64$Q_USZ |
| RAB64$L_RBF | RAB64$PQ_RBF 1 | RAB64$Q_RSZ |
| RAB64$L_KBF | RAB64$PQ_KBF | RAB64$B_KSZ |
| RAB64$L_RHB | RAB64$PQ_RHB | FAB$B_FSZ |
While RMS allows you to use the RAB64 wherever you can use a RAB, some
source languages may impose other restrictions. Consult the
documentation for your source language for more information.
11.2.3 Macros to Support User RAB Structure
The following MACRO-32 and BLISS macros support the 64-bit extension to the user RAB structure:
The Extended QIO Processor (XQP) file system, which implements the Files-11 On-Disk Structure Level 2 (ODS-2), and the Magnetic Tape Ancillary Control Process (ACP) both provide support for the use of 64-bit buffer addresses for virtual read and write functions.
The XQP and ACP translate a virtual I/O request to a file into one or more logical I/O requests to a device. Because the buffer specified with the XQP or ACP request is passed on to the device driver, the support for buffers in P2 or S2 space is also dependent on the device driver used by the XQP and ACP.
All OpenVMS supplied disk and tape drivers support 64-bit addresses for data transfers to and from disk and tape devices on the virtual, logical, and physical read and write functions. Therefore, the XQP and Magnetic Tape ACP support buffers in P2 or S2 space on the virtual read and write functions.
The XQP and ACP do not support buffer addresses in P2 or S2 space on the control functions (IO$_ACCESS, IO$_DELETE, IO$_MODIFY, and so on).
For more information about device drivers that support 64-bit buffer
addresses, see Writing OpenVMS Alpha Device Drivers in C.
11.4 OpenVMS Alpha and OpenVMS I64 64-Bit API Guidelines
This section describes the guidelines used to develop 64-bit interfaces to support OpenVMS Alpha and OpenVMS I64 64-bit virtual addressing. Application programmers who are developing their own 64-bit application programming interfaces (APIs) might find this information useful.
These recommendations are not hard and fast rules. Most are examples of good programming practices.
For more information about C pointer pragmas, see the HP C User's Guide for OpenVMS Systems.
11.4.1 Quadword/Longword Argument Pointer Guidelines
Because OpenVMS Alpha and OpenVMS I64 64-bit adressing support allows application programs to access data in 64-bit address spaces, pointers that are not 32-bit sign-extended values (64-bit pointers) will become more common within applications. Existing 32-bit APIs will continue to be supported, and the existence of 64-bit pointers creates some potential pitfalls that programmers must be aware of.
For example, 64-bit addresses may be inadvertently passed to a routine that can handle only a 32-bit address. Another dimension of this would be a new API that includes 64-bit pointers embedded in data structures. Such pointers might be restricted to point to 32-bit address spaces initially, residing within the new data structure as a sign-extended 32-bit value.
Routines should guard against programming errors where 64-bit addresses are being passed instead of 32-bit addresses. This type of checking is called sign-extension checking, which means that the address is checked to ensure that the upper 32 bits are all zeros or all ones, matching the value of bit 31. This checking can be performed at the routine interface that is imposing this restriction.
When defining a new routine interface, you should consider the ease of programming a call to the routine from a 32-bit source module. You should also consider calls written in all OpenVMS programming languages, not just those languages initially supporting 64-bit addressing. To avoid promoting awkward programming practices for the 32-bit caller of a new routine, you should accommodate 32-bit callers as well as 64-bit callers.
The OpenVMS Calling Standard requires that 32-bit values passed to a routine be sign-extended to 64-bits before the routine is called. Therefore, the called routine always receives 64-bit values. A 32-bit routine cannot tell if its caller correctly called the routine with a 32-bit address, unless the reference to the argument is checked for sign-extension.
This sign-extension checking would also apply to the reference to a descriptor when data is being passed to a routine by descriptor.
The called routine should return the error status SS$_ARG_GTR_32_BITS if the sign-extension check fails.
Alternately, if you want the called routine to accept the data being passed in a 64-bit location without error and if the sign-extension check fails, the data can be copied by the called routine to a 32-bit address space. The 32-bit address space to which the routine copies the data can be local routine storage (that is, the current stack). If the data is copied to a 32-bit location other than local storage, memory leaks and reentrancy issues must be considered.
When new routines are developed, pointers to code and all data pointers passed to the new routines should be accommodated in 64-bit address spaces where possible. This is desirable even if the data is a routine or is typically considered static data, which the programmer, compiler, or linker would not normally put in a 64-bit address space. When code and static data is supported in 64-bit address spaces, this routine should not need additional changes.
32-bit descriptor arguments should be validated to be 32-bit descriptors.
Routines that accept descriptors should test the fields that allow you to distinguish the 32-bit and 64-bit descriptor forms. If a 64-bit descriptor is received, the routine should return an error.
Most existing 32-bit routines will return or signal the error status SS$_ACCVIO when incorrectly presented with a 64-bit descriptor for the following reasons:
New routines should accommodate 32-bit and 64-bit descriptors within the same routine. The same argument can point to either a 32-bit or 64-bit descriptor. The 64-bit descriptor MBO word at offset 0 should be tested for 1, and the 64-bit descriptor MBMO longword at offset 4 should be tested for a -1 to distinguish between a 64-bit and 32-bit descriptor.
Consider an existing 32-bit routine that is being converted to handle 64-bit as well as 32-bit descriptors. If the input descriptor is determined to be a 64-bit descriptor, the data being pointed to by the 64-bit descriptor can first be copied to a 32-bit memory location, then a 32-bit descriptor would be created in 32-bit memory. This new 32-bit descriptor can then be passed to the existing 32-bit code, so that no further modifications need to be made internally to the routine.
32-bit item list arguments should be validated to be 32-bit item lists.
Two forms of item lists are defined: item_list_2 and item_list_3. The item_list_2 form of an item list consists of two longwords with the first longword containing a length and item code fields, while the second longword typically contains a buffer address.
The item_list_3 form of an item list consists of three longwords with the first longword containing a length and item code fields, while the second and third longwords typically contain a buffer address and a return length address field.
Since two forms of 32-bit item lists exist, two forms of a 64-bit item list are defined. Dubbed item_list_64a and item_list_64b, these item list forms parallel their 32-bit counterparts. Both forms of item list contain the MBO and MBMO fields at offsets 0 and 4 respectively. They also each contain a word-sized item code field, a quadword-sized length field, and a quadword-sized buffer address field. The item_list_64b form of an item list contains an additional quadword for the return length address field. The returned length is 64-bits.
Routines that accept item lists should test the fields that allow you to distinguish the 32-bit and 64-bit item list forms. If a 64-bit item list is received, the routine should return an error.
Most existing 32-bit routines will return or signal the error status SS$_ACCVIO when incorrectly presented with a 64-bit item list for the following reasons:
Figure 11-7 item_list_64a
Figure 11-8 item_list_64b
New routines should accommodate 32-bit and 64-bit item lists within the same routine. The same argument can point to either a 32-bit or 64-bit item list. The 64-bit item list MBO word at offset 0 should be tested for 1, and the 64-bit item list MBMO longword at offset 4 should be tested for a -1 to distinguish between a 64-bit and 32-bit item list.
Avoid passing pointers by reference.
If passing a pointer by reference is necessary, as with certain memory management routines, the pointer should be defined to be 64-bit wide.
Mixing 32-bit and 64-bit pointers can cause programming errors when the caller incorrectly passes a 32-bit wide pointer by reference when a 64-bit wide pointer is expected.
If the called routine reads a 64-bit wide pointer that was allocated only one longword by the programmer, the wrong address could be used by the routine.
If the called routine returns a 64-bit pointer, and therefore writes a 64-bit wide address into a longword allocated by the programmer, data corruption can occur.
Existing routines that are passed pointers by reference require new interfaces for 64-bit support. Old routine interfaces would still be passed the pointer in a 32-bit wide memory location and the new routine interface would require that the pointer be passed in a 64-bit wide memory location. Keeping the same interface and passing it 64-bit wide pointers would break existing programs.
Example: The return virtual address used in the SYS$CRETVA_64 service is an example of when it is acceptable to pass a pointer by reference. Virtual addresses created in P0 and P1 space are guaranteed to have only 32 bits of significance, however all 64 bits are returned. SYS$CRETVA_64 can also create address space in 64-bit space and thus return a 64-bit address. The value that is returned must always be 64 bits because a 64-bit address can be returned.
Memory allocation routines should return the pointer to the data allocated by value (that is, in R0), if possible. The C allocation routines, malloc, calloc, and realloc are examples of this.
New interfaces for routines that are not memory management routines should avoid defining output arguments to receive addresses. Problems will arise whenever a 64-bit subsystem allocates memory and then returns a pointer back to a 32-bit caller in an output argument. The caller may not be able to support or express a 64-bit pointer. Instead of returning a pointer to some data, the caller should provide a pointer to a buffer and the called routine should copy the data into the user's buffer.
A 64-bit pointer passed by reference should be defined by the programmer in such a way that a call to the routine can be written in a 64-bit language or a 32-bit language. It should be clearly indicated that a 64-bit pointer is required to be passed by all callers.
Routines must not return 64-bit addresses unless they are specifically requested.
It is extremely important that routines that allocate memory and return an address to their callers always allocate 32-bit addressable memory, unless it is known absolutely that the caller is capable of handling 64-bit addresses. This is true for both function return values and output parameters. This rule prevents 64-bit addresses from creeping in to applications that do not expect them. As a result, programmers developing callable libraries should be particularly careful to follow this rule.
Suppose an existing routine returns the address of memory it has allocated, such as the routine value. If the routine accepts an input parameter that in some way allows it to determine that the caller is 64-bit capable, it is safe to return a 64-bit address. Otherwise, it must continue to return a 32-bit, sign-extended address. In the latter case, a new version of the routine could be provided, which 64-bit callers could invoke instead of the existing version if they prefer that 64-bit memory be allocated.
Example: The routines in LIBRTL that manipulate string descriptors can be sure that a caller is 64-bit capable if the descriptor passed in is in the new 64-bit format. As a result, it is safe for them to allocate 64-bit memory for string data, in that case. Otherwise, they will continue to use only 32-bit addressable memory.
Avoid embedded pointers in data structures in public interfaces.
If embedded pointers are necessary for a new structure in a new interface, provide storage within the structure for a 64-bit pointer (quadword aligned). The called routine, which may have to read the pointer from the structure, simply reads all 64 bits.
If the pointer must be a 32-bit, sign-extended address (for example, because the pointer will be passed to a 32-bit routine) a sign-extension check should be performed on the 64-bit pointer at the entrance to the routine. If the sign-extension check fails, the error status SS$_ARG_GTR_32_BITS may be returned to the caller, or the data in a 64-bit address space may be copied to a 32-bit address space.
The new structure should be defined by the programmer in such a way that a 64-bit caller or a 32-bit caller does not contain awkward code. The structure should provide a quadword field for the 64-bit caller overlaid with two longword fields for the 32-bit caller. The first of these longwords is the 32-bit pointer field and the next is an MBSE (must be sign-extension) field. For most 32-bit callers, the MBSE field will be zero because the pointer will be a 32-bit process space address. The key here is to define the pointer as a 64-bit value and make it clear to the 32-bit caller that the full quadword must be filled in.
In the following example, both 64-bit and 32-bit callers would pass a pointer to the block structure and use the same function prototype when calling the function routine. (Assume data is an unknown structure defined in another module.)
#pragma required_pointer_size save
#pragma required_pointer_size 32
typedef struct block {
int blk_l_size;
int blk_l_flags;
union {
#pragma required_pointer_size 64
struct data *blk_pq_pointer;
#pragma required_pointer_size 32
struct {
struct data *blk_ps_pointer;
int blk_l_mbse;
} blk_r_long_struct;
} blk_r_pointer_union;
} BLOCK;
#define blk_pq_pointer blk_r_pointer_union.blk_pq_pointer
#define blk_r_long_struct blk_r_pointer_union.blk_r_long_struct
#define blk_ps_pointer blk_r_long_struct.blk_ps_pointer
#define blk_l_mbse blk_r_long_struct.blk_l_mbse
/* Routine accepts 64-bit pointer to the "block" structure */
#pragma required_pointer_size 64
int routine(struct block*);
#pragma required_pointer_size restore
|
For an existing 32-bit routine specifying an input argument, which is a structure that embeds a pointer, you can use a different approach to preserve the existing 32-bit interface. You can develop a 64-bit form of the data structure that is distinguished from the 32-bit form of the structure at run time. Existing code that accepts only the 32-bit form of the structure should automatically fail when presented with the 64-bit form.
The structure definition for the new 64-bit structure should contain the 32-bit form of the structure. Including the 32-bit form of the structure allows the called routine to declare the input argument as a pointer to the 64-bit form of the structure and cleanly handle both cases.
Two different function prototypes can be provided for languages that provide type checking. The default function prototype should specify the argument as a pointer to the 32-bit form of the structure. The programmer can select the 64-bit form of the function prototype by defining a symbol, specified by documentation.
The 64-bit versus 32-bit descriptor is an example of how this can be done.
Example: In the following example, the state of the symbol FOODEF64 selects the 64-bit form of the structure along with the proper function prototype. If the symbol FOODEF64 is undefined, the old 32-bit structure is defined and the old 32-bit function prototype is used.
The source module that implements the function foo_print would define the symbol FOODEF64 and be able to handle calls from 32-bit and 64-bit callers. The 64-bit caller would set the field foo64$l_mbmo to -1. The routine foo_print would test the field foo64$l_mbmo for -1 to determine if the caller used either the 64-bit form of the structure or the 32-bit form of the structure.
#pragma required_pointer_size save
#pragma required_pointer_size 32
typedef struct foo {
short int foo$w_flags;
short int foo$w_type;
struct data * foo$ps_pointer;
} FOO;
#ifndef FOODEF64
/* Routine accepts 32-bit pointer to "foo" structure */
int foo_print(struct foo * foo_ptr);
#endif
#ifdef FOODEF64
typedef struct foo64 {
union {
struct {
short int foo64$w_flags;
short int foo64$w_type;
int foo64$l_mbmo;
#pragma required_pointer_size 64
struct data * foo64$pq_pointer;
#pragma required_pointer_size 32
} foo64$r_foo64_struct;
FOO foo64$r_foo32;
} foo64$r_foo_union;
} FOO64;
#define foo64$w_flags foo64$r_foo_union.foo64$r_foo64_struct.foo64$w_flags
#define foo64$w_type foo64$r_foo_union.foo64$r_foo64_struct.foo64$w_type
#define foo64$l_mbmo foo64$r_foo_union.foo64$r_foo64_struct.foo64$l_mbmo
#define foo64$pq_pointer foo64$r_foo_union.foo64$r_foo64_struct.foo64$pq_pointer
#define foo64$r_foo32 foo64$r_foo_union.foo64$r_foo32
/* Routine accepts 64-bit pointer to "foo64" structure */
#pragma required_pointer_size 64
int foo_print(struct foo64 * foo64_ptr);
#endif
#pragma required_pointer_size restore
|
| Previous | Next | Contents | Index |