Add virtual_ptr (vptr) Command/AF interface for invoking cv_ptr_ subroutine from an exec_com

[Gary Dixon]

When writing an exec_com, it is often necessary to initiate a segment to locate particular data (rather than initiating it to invoke a particular command, AF, subroutine, etc).

This ticket suggests adding a new virtual_ptr (vptr) command/AF that will invoke the cv_ptr_ subroutine to initiate a particular data segment within the current process; and return or display a SEGNO|OFFSET virtual_ptr value locating that data segment, and a particular entrypoint_name or offset within that segment.

The suggested interface for the virtual_ptr (vptr) command/AF is shown below.

2025-12-10  virtual_pointer, vptr

Syntax as a command:  vptr VIRTUAL_PTR {-ctl_args}

Syntax as an active function:  [ vptr VIRTUAL_PTR {-ctl_args} ]

Function:  Converts a VIRTUAL_PTR string to a pointer value by
initiating the referenced segment will a null reference name.  A
VIRTUAL_PTR string is a pathname, reference_name or segment number,
with an optional offset (a number of words or bits) or an
entrypoint_name.  Then vptr displays or returns a character
representation of the virtual pointer which locates the data bit within
the referenced segment as shown below.

   Control_args given       Displayed or Returned Pointer
   -------------------      ---------------------------------------
     -ring                    segno|wordno(bit_offset)[ring_number]
     -no_ring -bit            segno|wordno(bit_offset)
     -bit                     segno|wordno(bit_offset)
     -no_bit                  segno|wordno

If neither -bit nor -no_bit is given, a bit_offset component is
displayed or returned only when the given bit_offset value is nonzero.
If neither -ring nor -no_ring is given, a ring_number component is
displayed or returned only when ring_number < ring-of-execution in
which the virtual_pointer command or active function is called.

This normalized representation is useful when creating an abbreviation
or exec_com that examines contents of the location identified by the
virtual pointer.

Upon completion of the abbreviation or exec_com, the virtual_pointer
command may be called a second time with an identical VIRTUAL_PTR
argument and the -terminate control argument.  This terminates any
segment initiated by the earlier call to vptr.

Arguments:
VIRTUAL_PTR
   Character string representation of a pointer.  Format is one of
   those described in the "List of virtual pointer formats" section
   below.

Control arguments (output):
-bit
   Include a decimal bit_offset number in the returned result.
-nonzero_bit, -nzbit
   Include a decimal bit_offset number in the returned result if it is
   nonzero. (default)
-no_bit, -nbit
   Exclude any bit number from the returned result.

-null
   Return a null pointer value as the word: null
-no_null, -nnull
   Return a null pointer value as a segno and wordno: -1|1
   (default)

-ring
   Always include a ring number in the returned result.
-no_ring, -nring
   Never include a ring number in the returned result.

Control arguments (termination):
   These control arguments may only be given when invoking
   virtual_pointer as a command.
-terminate, -tm
   Terminate the segment referenced by the given VIRTUAL_PTR
   representation in the current ring of the user's process.
   For details, see the: "Notes on terminating the segment" section
   below.
-no_terminate, -ntm
   Do not terminate the segment referenced by the given VIRTUAL_PTR
   representation. (default)

List of virtual pointer components:
segno
   segment number of a segment known to the process.  It is an octal
   number from 0 to 7777 inclusive; or one of the null pointer segment
   numbers (-1 or 77777 or 777777).
ref_name
   reference name for a segment.  It has the format of a PL/1
   identifier up to 32 characters in length.  See "Notes" below.
path
   absolute or relative pathname of a segment or multi-segment file
   (MSF).  It may also use the archive convention (path::component) to
   select one archive component.

entry_pt
   named location within an object segment; or an object MSF
   (multi-segment object file).  It is a PL1 identifier from 1 to 256
   characters in length.  The name designates the location of a word
   somewhere within the object file.  See "Notes" below.

W
   octal word offset from the beginning of the segment.  It may have a
   value from 0 to 777777 inclusive.
B
   decimal bit offset within the selected word of a segment.  It may
   have a value from 0 to 35 inclusive.
R, r
   effective ring number of a pointer to a segment.  A program
   executing in any ring <= R may reference through that pointer to
   locate a selected data word or bit.  R or r is an octal digit from
   0 to 7 inclusive.  Any ring number must appear after the W word
   number or the entry_pt name of the virtual pointer.  See the section
   "Notes on ring number" for more details.

List of virtual pointer formats:
   The VIRTUAL_PTR argument must follow one of the formats listed
   below.
segno|W(B)[R]
   points to octal word W, decimal bit B within that word, of the
   segment whose octal segment number is segno.  R gives a desired ring
   number to be used in the pointer.
segno|W(B)
   same as segno|W(B)[r] where r is the current ring in which vptr
   was invoked.
segno|W
   same as segno|W(0)[r].
segno|, segno
   same as segno|0(0)[r].

segno|entry_pt[R]
   points to the word located by entry point entry_pt in the object
   file whose octal segment number is segno.  For an object MSF, segno
   must identify component 0 in which all definitions are stored.  If
   entry_pt locates a word in some other component of that object MSF,
   that component's segno will be returned in the resultant
   VIRTUAL_PTR.  R gives a desired ring number to be used in the
   resultant pointer.
segno|entry_pt
   same as segno|entry_pt[r] where r is the current ring in which vptr
   was invoked.

-name segno|...,
-nm segno|...
   treat a segment identifier which looks like a segment number as an
   entryname.  The ... may be any of the OFFSET formats shown earlier.
   Search for a segment with that entryname using linker search paths,
   and make that segment known to the user process.

ref_name$entry_pt[R]
   points to word located by entry point entry_pt in an object file
   whose reference name is ref_name.  R gives the desired ring number
   to be used in the pointer.
ref_name$entry_pt
   same as ref_name$entry_pt[r] where r is the current ring in which
   vptr was invoked.

ref_name$W(B)[R]
   points to octal word W, decimal bit B of segment or MSF whose
   reference name is ref_name.  If ref_name is a reference name on a
   multisegment file (a reference name on component 0 of the MSF), the
   word and bit offsets are applied within component 0.  R gives the
   desired ring number to be used in the pointer.
ref_name$W(B)
   same as ref_name$W(B)[r] where r is the current ring in which vptr
   was invoked.
ref_name$W
   same as ref_name$W(0)[r].
ref_name$
   same as ref_name$0(0)[r].

-name ref_name$...,
-nm ref_name$...
   treat a segment identifier which looks like a reference name as an
   entryname.  The ... may be any of the OFFSET formats shown earlier.
   Search for a segment with that entryname using linker search paths,
   and make that segment known to the user process.

path|W(B)[R]
   points to octal word W, decimal bit B of segment or MSF identified
   by absolute or relative pathname path.  If the path given identifies
   a multisegment file, the offset given is in component 0 of the MSF.
   path may be an absolute or relative pathname, or it may be an
   archive pathname (path::component) identifying one archive
   component.  R gives the desired ring number to be used in the
   pointer.
path|W(B)
   same as path|W(B)[r] where r is the current ring in which vptr was
   invoked.
path|W
   same as path|W(0)[r].
path|, path
   same as path|0(0)[r].

path|entry_pt[R]
   points to word identified by entry point entry_pt in the object file
   (segment or MSF) identified by path.  R gives the desired ring
   number to be used in the pointer.
path|entry_pt
   same as path|entry_pt[r] where r is the current ring in which vptr
   was invoked.

dir>entry$entry_pt
   points to word identified by entry point entry_pt in the object file
   identified by pathname dir>entry.
<dir>entry$entry_pt
   points to word identified by entry point entry_pt in the object file
   identified by pathname <dir>entry.
<entry$entry_pt
   points to word identified by entry point entry_pt in the object file
   identified by pathname <entry.

List of input null pointer formats:
   In the VIRTUAL_PTR input, a null pointer is represented by one of
   the virtual pointer representations:
-1|1
-1
77777|1
77777
777777|1
777777
null
null()

List of output null pointer formats:
   In the displayed or returned output, a null pointer is represented
   in one of two formats:
null  (if -null control is given)
-1|1  (default)

Notes:
If VIRTUAL_PTR begins with a pathname, either a relative and an
absolute pathname may be given.  Archive pathnames are supported.

A ref_name or entry_pt must be in the form of a PL1 <identifier>.

 <identifier> ::= <letter>[<letter>|<digit>|_]...

 <letter>     ::= A|B|C|D|E|F|G|H|I|J|K|L|M|N|O|P|Q|R|S|T|U|V|W|X|Y|Z|
                  a|b|c|d|e|f|g|h|i|j|k|l|m|n|o|p|q|r|s|t|u|v|w|x|y|z

 <digit>:     ::= 0|1|2|3|4|5|6|7|8|9

A ref_name <identifier> may not be longer than 32 characters.  An
entry_pt <identifier> may not be longer than 256 characters.  Thus, a
VIRTUAL_PTR with the format  ref_name$entry_pt  may not be longer than
289 characters.

Notes on terminating the segment:
The segment identified by a pathname is initiated with a null
reference name to make it known to the process address space.  This
assigns a segment number which can be displayed in the virtual_pointer
result.

When operation on that pathname is complete, invoke the vptr command
with that same VIRTUAL_PTR (starting with a pathname) and the
-terminate control to reduce the null reference name counter for the
segment.  If the counter reaches zero and the segment has no real
reference names in the process, it will be removed from the process
address space.

A vptr -terminate operation will not attempt to terminate a null
pointer or a ring-0 segment.  It will silently fail to terminate an
inner-ring segment.

Notes on ring number:
The vptr command converts a VIRTUAL_PTR to a result:

   - A segment number of the segment containing the data item located
     by the pointer.
   - A word number locating the start of the data item within the
     segment;
   - A bit offset number of the first bit of data within that word;
   - A ring number in which that was initiated in order to construct
     the pointer.

This result is displayed or returned as a character representation:
   segno|W(B)[R]

The R ring number is usually displayed by tools like ring_zero_dump
(rzd) if displaying a pointer in an inner-ring data segment.  Such
tools usually do not display R if it is greater than the current ring
number.

A null pointer value always has a ring number of 0.  This permits a
pointer set to null() to be passed to another ring of execution while
having a binary content that matches the null() built-in function.

The pointer value returned by the cv_ptr_ function must have its ring
number R >= current ring of execution (the number of the protection
ring in which the caller of cv_ptr_ is executing) unless a null pointer
is returned.  If its input VIRTUAL_PTR has R < current ring, the
pointer display or returned has an effective ring set by the hardware
to the ring of execution of the caller of cv_ptr_.

[Eric Swenson]

​https://s3.amazonaws.com/eswenson-multics/public/mcrs/MCR10162.pdf

[Eric Swenson]

Installed as MR12.9-1037.