Document revision date: 19 July 1999

There are 16 vector registers, designated V0 to V15. Each of the vector registers has 64 elements, numbered 0 to 63, and each element has 64 bits (one quadword).

To examine one or more elements of a vector register, use the same technique that you use to examine an array variable. (See Section 4.2.3.) The examples in this section use Fortran array syntax:

DBG> EXAMINE %V3 !Examine all elements of V3 DBG> EXAMINE %V3(27) !Examine element 27 of V3 DBG> EXAMINE %V3(3:14) !Examine elements 3 to 14 of V3 DBG> EXAMINE %V0(2),%V3(1:4) !Examine element 2 of V0 and !elements 1 to 4 of V3

The values of register elements are displayed in an indexed format similar to that used for an array variable. For example, the following command displays the values of elements 1 to 3 of register V1:

DBG> EXAMINE %V1(1:3) 0\%V1 (1): 3 (2): 138 (3): 51 DBG>

You cannot examine a range of vector registers. For example, the following commands are invalid:

DBG> EXAMINE %V0:%V3 DBG> EXAMINE %V2(7):%V3(12)

As with an array variable, you can deposit a value into only one element of a vector register at a time. For example, the following command deposits the integer value 8531 into element 9 of V0:

DBG> DEPOSIT %V0(9) = 8531

The current value of the vector length register (VLR) limits the highest register element that you can examine or deposit into. (See Section 16.3.3.) Therefore, the following commands are equivalent:

DBG> EXAMINE %V1 DBG> EXAMINE %V1(0:%VLR-1)

The expression 0:%VLR--1 specifies the range of register elements that are denoted by the current value of VLR.

By default, the debugger treats each element of a vector register as a longword integer and displays the value in the current radix. For example:

DBG> EXAMINE %V3(27) 0\%V3(27): 5983 DBG> DEPOSIT %V3(27) = 3625 DBG> EXAMINE %V3(27) 0\%V3(27): 3625 DBG>

However, note that a register value that is examined in the context of a vector instruction (that is, as an instruction operand) is displayed in the data type that is appropriate for the instruction (see Section 16.4.1).

To display the full (quadword) value of an element of a vector register as a quadword integer, use the EXAMINE/QUADWORD command. Similarly, to deposit a quadword integer value into a register element, use the command DEPOSIT/QUADWORD.

You can also use any of the other type qualifiers associated with the EXAMINE and DEPOSIT commands (for example, /FLOAT) to override the default type. For example:

DBG> EXAMINE %V5(2) 0\%V5(2): 0 DBG> EXAMINE/D_FLOAT %V5(2) 0\%V5(2): 0.0000000000000000 DBG>

You can use register symbols in language expressions subject to the restrictions on using aggregate data structures in language expressions. (See Section 4.1.6.1.) For example, the following expression is valid (Fortran syntax):

DBG> EVALUATE %V0(4) .EQ. %V1(4)

However, the following expression is not valid because more than one register element is specified:

DBG> EVALUATE %V0 .EQ. %V1

16.4 Examining and Depositing Vector Instructions

The techniques for manipulating vector instructions include all of those used for scalar instructions (described in Section 4.3) and additional techniques specific to vector instructions:

• You can use a screen-mode instruction display to present the scalar and vector instructions decoded from the instruction stream of your program.
• You can execute your program at the vector instruction level by using commands such as:
  • STEP/VECTOR_INSTRUCTION
  • STEP/INSTRUCTION=(opcode[,...])
  • SET STEP VECTOR_INSTRUCTION
  • SET STEP INSTRUCTION=(opcode[,...])
  • SET BREAK/VECTOR_INSTRUCTION
  • SET BREAK/INSTRUCTION=(opcode[,...])
• You can use the EXAMINE/OPERANDS command to display the instruction at the current PC value (where execution is paused), including any operand information contained in vector registers. In addition, the /TMASK and /FMASK qualifiers enable you to simulate the effect of the vector mask register (VMR) or override any masking associated with the examined instruction so that you can hide or display specific register elements.
• You can deposit a vector instruction at a particular memory address in your program.

Whether you are examining or depositing vector instructions, the debugger correctly processes the vector instruction qualifiers according to the instructions to which they apply. The following table summarizes the functions of these qualifiers. See the OpenVMS MACRO and Instruction Set Reference Manual for complete information about their use.

Instruction Qualifier	Description
/U	Enable floating underflow (vector floating-point instructions)
/V	Enable integer overflow (vector integer instructions)
/M	Modify intent (VLD x and VGATH x instructions)
/0	Perform masked operations only on elements for which the VMR bit is 0
/1	Perform masked operations only on elements for which the VMR bit is 1

16.4.1 Examining Vector Instructions and Their Operands

When you examine a program location that contains a vector instruction, the debugger decodes that instruction and translates it and its operands into their MACRO assembler form with the following restrictions (see the OpenVMS MACRO and Instruction Set Reference Manual for details about instruction opcodes):

• If the vector control word is not encoded using either immediate or short-literal mode, the debugger cannot translate the opcode and, therefore, displays the instruction and its operands in their vector architectural form rather than their MACRO assembler form.
• If the opcode is VSMERGEx, the debugger displays the instruction mnemonic as VSMERGE rather than VSMERGEF, VSMERGED, or VSMERGEG. In this case, a literal src.rq operand is displayed as a quadword integer in the current radix.

The command EXAMINE/OPERANDS .%PC enables you to display the instruction at the current PC value and its operands. (See Section 4.3.1.) When you examine a vector instruction with this command, the values of any vector register operands are displayed as for an array variable. For example (Fortran array syntax):

DBG> EXAMINE/OPERANDS .%PC PROG$MAIN\%LINE 81+19: VSTL V0,W^-572(FP),S^#4 V0 contains: 0\%V0(0): 137445504 0\%V0(1): 137445504 0\%V0(2): 137445504 W^-572(FP) 2145991456 contains 2 DBG>

As with scalar instructions, operand values are displayed in the data type that is appropriate for the examined instruction.

When you use the EXAMINE/OPERANDS command, the display of register elements depends on the following factors:

• The current value of VLR. The highest element of a vector register that is operated on (and, therefore, displayed) is limited by the value of VLR.
• Whether the examined instruction is performing a masked operation. In an unmasked operation, all register elements (up to VLR--1) are displayed. A masked operation is indicated by the presence of the /1 or /0 instruction qualifier. For example:

  VVADDF/1 V0,V1,V2

  
  In a masked operation, only the elements that correspond to the set or clear bits of VMR are operated on (depending on whether the instruction qualifier is /1 or /0, respectively).

These concepts are shown in the following two examples, which show an unmasked and a masked register-to-register operation, respectively.

In this example, the examined instruction, VVADDF, is performing an unmasked operation so that the current value of VMR is irrelevant. All elements from 0 to 5 are displayed.

DBG> EXAMINE %VLR 0\%VLR: 6 DBG> EXAMINE %VMR(0:5) 0\%VMR (0): 1 (1): 0 (2): 1 (3): 0 (4): 1 (5): 0 DBG> EXAMINE/OPERANDS .%PC PROG$MAIN\%LINE 12: VVADDF V0,V1,V2 V0 contains: 0\%V0(0): 7.0000000 0\%V0(1): 7.0000000 . . 0\%V0(5): 7.0000000 V1 contains: 0\%V1(0): 4.0000000 0\%V1(1): 4.0000000 . . 0\%V1(5): 4.0000000 V2 contains: 0\%V2(0): 5.0000000 0\%V2(1): 5.0000000 . . 0\%V2(5): 5.0000000 DBG>

In the next example, the same VVADDF instruction is performing a masked operation. The instruction qualifier /1 specifies that elements that match the set bits (bit value 1) in VMR are operated on.

DBG> EXAMINE %VLR 0\%VLR: 6 DBG> EXAMINE %VMR(0:5) 0\%VMR (0): 1 (1): 0 (2): 1 (3): 0 (4): 1 (5): 0 DBG> EXAMINE/OPERANDS .%PC PROG$MAIN\%LINE 12: VVADDF/1 V0,V1,V2 V0 contains: 0\%V0(0): 7.0000000 0\%V0(2): 7.0000000 0\%V0(4): 7.0000000 V1 contains: 0\%V0(0): 4.0000000 0\%V0(2): 4.0000000 0\%V0(4): 4.0000000 V2 contains: 0\%V0(0): 5.0000000 0\%V0(2): 5.0000000 0\%V0(4): 5.0000000 DBG>

The next example shows a masked operation that loads data from memory to a vector register. Comments, keyed to the callouts, follow the example.

DBG> EXAMINE %VLR 0\%VLR: 6 DBG> EXAMINE %VMR(0:5) 0\%VMR (0): 1 (1): 0 (2): 1 (3): 0 (4): 1 (5): 0 DBG> EXAMINE/OPERANDS .%PC (1) PROG$MAIN\%LINE 31+12: VLDL/1 ARR+8,#4,V0 (2) PROG$MAIN\ARR(3) (address 1024) contains 35 (3) V0 contains: 0\%V0(0): 0 (4) 0\%V0(2): 0 0\%V0(4): 0 DBG> EXAMINE ARR(1:8) (5) PROG$MAIN\ARR (1): 9 (2): 17 (3): 35 (4): 73 (5): 81 (6): 6 (7): 7 (8): 49 DBG>

The following comments refer to the callouts in the previous example:

1. The EXAMINE/OPERANDS command shows that a VLDL instruction is about to be executed. The instruction will load longword-integer data from array ARR, starting at ARR+8 bytes, into register V0, as shown in Figure 16-1. Figure 16-1 shows the contents of V0 after the instruction has been executed. Array ARR is indexed 1 to n, not 0 to n--1 (Fortran example).
2. The stride value (#4) of the VLDL instruction specifies the number of bytes between the start addresses of array elements.
3. The instruction operand ARR+8 denotes the start of array element 3, ARR(3). The EXAMINE/OPERANDS command displays only the first element of array ARR that is operated upon (see item ).
4. The current values of VLR and VMR will cause the VLDL instruction to load the contents of array elements ARR(3), ARR(5), and ARR(7) into register elements V0(0), V0(2), and V0(4), respectively. The EXAMINE/OPERANDS command shows the contents of V0 before the instruction has been executed.
5. For reference, the EXAMINE ARR(1:8) command displays the full range of array elements that are associated with the load operation.

Figure 16-1 Masked Loading of Array Elements from Memory into a Vector Register

16.4.2 Depositing Vector Instructions

DBG> DEPOSIT/INSTRUCTION .%PC = "VVMULF/0 V2,V3,V7"

Note the following information when depositing vector instructions (see the OpenVMS MACRO and Instruction Set Reference Manual for details about instruction opcodes):

• The regnum.rw operand of the MxVP and VSYNC instructions is generated as a short literal.
• Do not specify a vector control word when depositing a vector instruction. The debugger constructs the vector control word based on the instruction and instruction qualifiers, if any, and encodes it using immediate mode.
• The value of an immediate argument of a VSMERGEx instruction is interpreted according to the data type associated with that instruction. For example, the src argument for a VSMERGEF instruction is interpreted as a F_floating value, and so on. For VSMERGE without a type suffix, the debugger interprets a literal src operand as a quadword integer in the current radix.

Section 16.4.1 explains how the command EXAMINE/OPERANDS .%PC displays vector instruction operands, depending on whether or not the operation is masked by the vector mask register (VMR).

This section explains how to specify an arbitrary mask in order to simulate or override the effect of VMR and obtain the following results:

• Display only certain elements of a vector register or of an array in memory
• Override the operand masking (if any) that might be associated with an examined instruction

You specify a mask by using the /TMASK or /FMASK qualifier with the EXAMINE command.

The /TMASK qualifier applies the EXAMINE command only to the elements of the examined register that correspond to the set bits (bit value: 1) of the mask. The /FMASK qualifier applies the EXAMINE command only to the elements that correspond to the clear bits (bit value: 0) of the mask.

The current value of VLR limits the highest element of a vector register that you can examine. However, the value of VLR does not affect examining an array in memory.

You can optionally specify a mask (in the form of a mask address expression) with the /TMASK and /FMASK qualifiers. For more information:

• Section 16.5.1 describes using these qualifiers with the default mask, which is VMR.
• Section 16.5.2 describes using these qualifiers with some arbitrary slice of VMR as the mask.
• Section 16.5.3 describes using these qualifiers with a mask other than VMR.

By default, if you do not specify a mask with the EXAMINE/TMASK or EXAMINE/FMASK command, VMR is used as the mask. That is, the EXAMINE command is applied only to the elements of the vector register that correspond to the set bits (in the case of /TMASK) or clear bits (in the case of /FMASK) of VMR.

In the following examples, VLR has the value 6 and VMR(0:VLR--1) has the following set of values:

DBG> EXAMINE %VMR(0:%VLR-1) 0\%VMR (0): 1 (1): 0 (2): 1 (3): 0 (4): 1 (5): 0 DBG>

The following command displays the value of V3 without using a mask. All elements of V3 from 0 to VLR--1 are displayed:

DBG> EXAMINE %V3 0\%V3 (0): 17 (1): 138 (2): 3 (3): 9 (4): 51 (5): 252 DBG>

The following command displays the elements of V3 (in the range from 0 to VLR--1) for which VMR(i) has the value 1:

DBG> EXAMINE/TMASK %V3 0\%V3 (0): 17 (2): 3 (4): 51 DBG>

The following command displays the elements of V3 (in the range from 0 to VLR--1) for which VMR(i) has the value 0:

DBG> EXAMINE/FMASK %V3 0\%V3 (1): 138 (3): 9 (5): 252 DBG>

In the following example, the /FMASK qualifier is used when examining an instruction and its vector-register operands. The EXAMINE/OPERANDS/FMASK command displays the register-operand elements (in the range from 0 to VLR--1) for which VMR(i) has the value 0:

DBG> EXAMINE/OPERANDS/FMASK .%PC PROG$MAIN\%LINE 341+16: VVEQLL V0,V1 V0 contains: 0\%V0(1): 0 0\%V0(3): 0 0\%V0(5): 0 V1 contains: 0\%V1(1): 0 0\%V1(3): 0 0\%V1(5): 0 DBG>

16.5.2 Using a Slice of VMR as the Mask

If you specify a slice of VMR with the EXAMINE/TMASK or EXAMINE/FMASK command, the output is displayed according to the following conventions:

• The number of mask elements specified limits the number of register element that you can examine. For example:

  DBG> EXAMINE %VLR 0\%VLR: 12 DBG> EXAMINE %VMR(3:5) 0\%VMR (3): 1 (4): 1 (5): 1 DBG> EXAMINE/TMASK=(%VMR(3:5)) %V0(3:10) 0\%V0 (3): 9 (4): 51 (5): 252 DBG>

  
  Use parentheses when specifying a mask with the /TMASK qualifier.

• The lowest specified element of the mask is applied to the lowest specified element of the register. For example, EXAMINE/TMASK %V0(4:7) applies VMR(0) to V0(4), VMR(1) to V0(5), and so on. If the lowest specified elements of the mask and register do not match, the debugger lists both the mask elements and the register elements that are operated on and issues a message. For example:

  DBG> EXAMINE %VLR 0\%VLR: 12 DBG> EXAMINE %VMR(4:7) 0\%VMR (4): 1 (5): 0 (6): 1 (7): 1 DBG> EXAMINE/TMASK=(%VMR(4:7)) %V0(3:10) %DEBUG-I-MASKMISMATCH, mask/target subscripts do not match, displaying mask 0\%V0 %VMR(4): 1 %V0(3): 9 %VMR(6): 1 %V0(5): 252 %VMR(7): 1 %V0(6): 56 DBG>

If you specify a mask address expression other than VMR with the EXAMINE/TMASK or EXAMINE/FMASK command, the value at that address is used as the mask subject to the following conventions:

• If the mask address expression denotes a Boolean array, its values are used as the mask in the same basic way that VMR is used in the default case. In the following example, BOOL_ARR, a 4-element Boolean array variable, is used as the mask:

  DBG> EXAMINE %VLR 0\%VLR: 6 DBG> EXAMINE BOOL_ARR PROG$MAIN\BOOL_ARR (0): 0 (1): 0 (2): 1 (3): 0 DBG> EXAMINE/FMASK=(BOOL_ARR) %V0 %DEBUG-I-MASKNOTVMR, mask used is not %VMR, displaying specified mask 0\%V0 BOOL_ARR(0): 0 %V0(0): 17 BOOL_ARR(1): 0 %V0(1): 138 BOOL_ARR(3): 0 %V0(3): 9 DBG>

  
  As shown in the example, when you use a mask other than VMR, the debugger displays both the mask elements and the register elements that are operated on and issues a message.

• If the mask address expression denotes a non-Boolean array, the least significant bit of each array element is used as the mask for the corresponding element of the register.
• If the mask address expression denotes a Boolean scalar type, its value is used as the mask for the first element of the register. No other elements are examined. In the following example, BOOL_VAR, a single-element Boolean variable, is used as the mask:

  DBG> EXAMINE BOOL_VAR PROG$MAIN\BOOL_VAR: 1 DBG> EXAMINE/TMASK=(BOOL_VAR) %V0 %DEBUG-I-MASKNOTVMR, mask used is not %VMR, displaying specified mask 0\%V0 BOOL_VAR: 1 %V0(0): 17 DBG>

• If the mask address expression denotes any other type, its least significant bit value is used as the mask for the first element of the register. No other elements are examined.
• The number of mask elements specified limits the number of register elements that you can examine, as when the mask is VMR (see Section 16.5.2).
• For a multielement mask, the lowest specified element of the mask is applied to the lowest specified element of the register, as when the mask is VMR (see Section 16.5.2).

	privacy and legal statement
4538PRO_033.HTML