id summary reporter owner description type status priority milestone component version resolution keywords cc 389 Add virtual_ptr (vptr) Command/AF interface for invoking cv_ptr_ subroutine from an exec_com Gary Dixon 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. entry$entry_pt points to word identified by entry point entry_pt in the object file identified by pathname entry. . ::= [||_]... ::= 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 : ::= 0|1|2|3|4|5|6|7|8|9 A ref_name may not be longer than 32 characters. An entry_pt 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_. }}} " enhancement closed major MR12.9 General MR12.8 fixed