HP OpenVMS Systems Documentation

OpenVMS Programming Concepts Manual

This chapter describes the following features that support 64-bit addressing:

• System services, descriptors, and item lists
• RMS interfaces
• File systems
• OpenVMS Alpha 64-bit API guidelines
• OpenVMS Alpha tools and utilities
• Language and pointers
• Compaq C RTLs

New OpenVMS system services are available, and many existing services have been enhanced to manage 64-bit address space. This chapter describes the OpenVMS Alpha 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 new 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 OpenVMS System Services Reference Manual: A--GETUAI and 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 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.

The majority of OpenVMS Alpha system services prior to OpenVMS Alpha Version 7.0 have 64-bit friendly interfaces for the following reasons:

• Chapter 17 defines arguments to standard routines to be 64 bits wide. The caller of a routine sign-extends 32-bit arguments to be 64 bits.
• 64-bit string descriptors can be distinguished from 32-bit string descriptors at run time. (See Chapter 17 for more information about 64-bit descriptors.)
• User-visible RMS data structures contain embedded type information such that the RMS routines can tell whether an extended form of a structure is being used. (See Section 11.2 for more details about RMS 64-bit addressing support.)

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:

• One form for use with 32-bit addresses
• One form for use with 64-bit addresses

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.

Both OpenVMS VAX and OpenVMS Alpha systems use 32-bit descriptors. When used on OpenVMS Alpha systems, 32-bit descriptors provide full compatibility with their use on OpenVMS VAX. The 64-bit descriptors are used only on OpenVMS Alpha systems. They have no counterparts and are not recognized on OpenVMS VAX systems.

The following figure shows the general descriptor format for a 32-bit descriptor.

Figure 11-1 General Format of a 32-Bit Descriptor

The following figure 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 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 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.

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 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:

• item_list_2
• item_list_3

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.

The following figure shows the format of the item_list_2 item entry.

Figure 11-3 Item_list_2 Format

The following figure shows the format of the item_list_3 item entry.

Figure 11-4 Item_list_3 Format

The following table defines the fields for 32-bit item list entries:

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.

The following figure shows the format of the item_list_64a item entry.

Figure 11-5 Item_list_64a Format

The following shows the format of the item_list_64b item entry.

Figure 11-6 Item_list_64b Format

The following table defines the item descriptor fields for 64-bit item list entries:

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:

• The 64-bit form is easily distinguished from the 32-bit form by routines receiving them as arguments.
• The item lists continue to demonstrate the behavior that if a 32-bit facility is incorrectly handed as a 64-bit item list, it fails predictably. The buffer address of -1 and the length field of 1 are guaranteed to result in an access violation. The same result comes from passing a 64-bit item list entry to a routine expecting a 32-bit string descriptor. Passing a 64-bit item list element to a routine expecting a 64-bit descriptor is as reliable as it is for their 32-bit counterparts.

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 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.