Document revision date: 30 March 2001

The following sections explain how to examine and deposit into the vector control registers (VCR, VLR, and VMR) and the vector registers (V0 to V15).

16.3.1 Specifying the Vector Registers and Vector Control Registers

The VAX architecture provides 16 vector registers (V0 to V15) and 3 vector control registers (VCR, VLR, and VMR). When referencing any of these registers in a debugger command, use the following built-in symbols (the register name preceded by a percent sign (%)):

Symbol	Description
%V0...%V15	Vector registers (V0...V15)
%VCR	Vector count register (VCR)
%VLR	Vector length register (VLR)
%VMR	Vector mask register (VMR)

As with all debugger register symbols, you can omit the percent sign (%) prefix if your program has not declared a symbol with the same name.

16.3.2 Examining and Depositing into the Vector Count Register

The vector count register (VCR) specifies the length of the offset vector generated by the IOTA instruction.

The value of VCR is an integer from 0 to 64. By default, the debugger treats VCR as a longword integer. You can deposit values greater than 64 into VCR, but the debugger issues a diagnostic message that the value is out of bounds in such cases.

The following command sequence shows how to manipulate the value of VCR:

DBG> EXAMINE %VCR 0\%VCR: 8 DBG> DEPOSIT %VCR = 4 DBG> EXAMINE %VCR 0\%VCR: 4 DBG>

16.3.3 Examining and Depositing into the Vector Length Register

The vector length register (VLR) limits the highest element of a vector register that is processed by a vector instruction. The value of VLR is an integer from 0 to 64. This value specifies the number of register elements that are processed, starting with element 0.

In the context of a debugging session, the current value of VLR limits the highest element of a vector register that you can access with an EXAMINE or DEPOSIT debugger command.

The following command sequence shows how to manipulate the value of VLR to examine different numbers of elements of the vector register V1:

DBG> EXAMINE %VLR 0\%VLR: 4 DBG> EXAMINE %V1 0\%V1 (0): 12 (1): 3 (2): 138 (3): 51 DBG> DEPOSIT %VLR = 3 DBG> EXAMINE %VLR 0\%VLR: 3 DBG> EXAMINE %V1 0\%V1 (0): 12 (1): 3 (2): 138 DBG>

You cannot access a register element outside the range from 0 to VLR--1. In the following example, the EXAMINE command specifies element 7 of register V1, which is out of bounds (Fortran array syntax):

DBG> EXAMINE %VLR 0\%VLR: 3 DBG> EXAMINE %V1(7) %DEBUG-E-VECTSUBRNG, vector register subscript out of bounds, bounds are 0..2 DBG>

By default, the debugger treats VLR as a longword integer. You can deposit values greater than 64 into VLR, but the debugger issues a diagnostic message that the value is out of bounds in such cases.

16.3.4 Examining and Depositing into the Vector Mask Register

The vector mask register (VMR) specifies a mask (a bit pattern) that a vector instruction uses to operate on only certain elements of a vector register operand. A masked vector instruction cannot operate on an element of a vector register that is masked by VMR.

VMR has 64 bits (1 quadword) numbered 0 to 63. Each bit corresponds to an element of a vector register. The value of a particular bit (0 or 1) determines whether the corresponding register element is operated on during a masked operation.

Masked operations are explained in Section 16.4.1 and Section 16.5. This section describes how to display and change the value of VMR.

To examine one or more specific elements (bits) of VMR, use the same technique that you use to examine an array variable. (See Section 4.2.3.)

For example, the output of the following command shows that bit 5 of VMR is set (Fortran array syntax):

DBG> EXAMINE %VMR(5) 0\%VMR(5): 1 DBG>

The following command displays the values of bits 4 to 6 of VMR. Bits 4 and 5 are set, and bit 6 is clear:

DBG> EXAMINE %VMR(4:6) 0\%VMR (4): 1 (5): 1 (6): 0 DBG>

By default, when you examine VMR without specifying subscripts, the debugger displays the value of the register as a quadword integer in hexadecimal format to reduce the size of the output display. For example:

DBG> EXAMINE %VMR 0\%VMR (0): 0FFFFFFF FFFFFFFF DBG>

By specifying the EXAMINE/BIN %VMR or EXAMINE %VMR(0:63) command, you can display the value of each bit of VMR in a 64-row array format.

As with an array variable, you can deposit a value into one bit of VMR at a time. For example:

DBG> EXAMINE %VMR(37) 0\%VMR(37): 1 DBG> DEPOSIT %VMR(37) = 0 DBG> EXAMINE %VMR(37) 0\%VMR(37): 0 DBG>

You can also deposit a quadword integer value into the entire aggregate by using the DEPOSIT/QUADWORD command. For example:

DBG> DEPOSIT/QUADWORD %VMR = %HEX 0FFFFF DBG> EXAMINE %VMR 0\%VMR (0): 00000000 000FFFFF DBG>

When specifying an element of VMR in a language expression, remember that VMR is an array of bits. You might have to temporarily set the language to one that allows bit operations, such as C or BLISS. For example:

DBG> SET LANGUAGE C DBG> DEFINE/VALUE K = 0 DBG> FOR I=0 TO 63 DO (IF %VMR[I] == 1 THEN (DEF/VAL K = K + 1))

16.3.5 Examining and Depositing into the Vector Registers (V0 to V15)

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

	privacy and legal statement
4538PRO_032.HTML