HP OpenVMS systems documentation

The overall design of the watchpoint facility uses protection attributes on system pages and the access violation fault mechanism. To establish a watchpoint within a page of system space, the WPDRIVER changes the protection of the page to disallow writes. The WPDRIVER modifies the access violation vector to point to its own routine, WP$ACCVIO.

Any subsequent write to this page causes an access violation and dispatch to WP$ACCVIO. Thus, the WPDRIVER gains control on all write references to watchpoints and can monitor such accesses.

When WP$ACCVIO is entered, it raises IPL to 31 to block all other threads of execution. It first must determine whether the faulting address (whose reference caused the access violation) is within a page containing a watchpoint. However, any major amount of CPU processing at this point might access an area in system space whose protection has been altered to establish watchpoints. As a result, such processing might cause a reentry into WP$ACCVIO. To avoid recursive reentry, WP$ACCVIO first restores all SPTEs that it had modified to their values prior to the establishment of any watchpoints. From this point until this set of SPTEs are remodified, no watchpoints are in effect. Now WP$ACCVIO can determine whether the reference was to a page containing a watchpoint.

To determine whether the reference is to a watchpoint page, WP$ACCVIO compares the faulting address to addresses of pages whose protection has been altered by WPDRIVER. If the faulting address is not in one of these pages, then WP$ACCVIO passes the access violation to the usual OpenVMS service routine, EXE$ACVIOLAT. If the faulting address is within a page containing a watchpoint, more extensive processing is required.

As a temporary measure, WP$ACCVIO first records all data related to the reference in its UCB. It cannot immediately associate the access violation with a particular watchpoint. This ambiguity arises from imprecision in the faulting virtual address recorded at the access violation. The CPU need merely place on the stack "some virtual address in the faulting page."

As a result, when a reference to a page with a watchpoint results in an access violation, the watchpoint driver first merely captures the data in its UCB. The data captured at this point includes the following:

• PC and PSL of the faulting instruction
• Current system time
• Values of all the general registers from R0 through SP
• A copy of up to 15 bytes of the instruction stream, beginning at the PC previously captured

If the reference later turns out not to be one to a watchpoint, the captured data is discarded. If the reference is to a watchpoint, the data is copied to the WPCB and circular trace buffer.

The watchpoint driver distinguishes between these two possibilities by reexecuting the faulting instruction under a controlled set of circumstances.

Once the instruction has reexecuted, WP$TBIT can determine whether watchpoint data has been modified by comparing the current contents of all watchpoints within the page of interest to the contents that they had prior to this reference. Because the driver has run at IPL 31 since the write access that caused an access violation, any change in the contents is attributable to the reexecuted instruction. If the contents of a watchpoint are different, WP$TBIT copies the data temporarily saved in its UCB to the WPCB associated with this watchpoint and records a subset of this data in a WPTTE.

The driver can cause either or both an XDELTA breakpoint or a bugcheck, depending on what action was requested with the watchpoint definition. If an XDELTA breakpoint was requested, the driver invokes XDELTA. After the user proceeds from the XDELTA breakpoint, if a bugcheck was not requested, the driver restores the SPTEs of pages containing watchpoints, the saved registers and IPL, and REIs to dismiss the exception.

13.7 Restrictions

The WPDRIVER can monitor only those write references to system space addresses that arise in a CPU. I/O devices can write to memory and thereby modify watchpoints without the WPDRIVER's becoming aware of the write.

Because a write access to a watchpoint is determined by comparing the contents of the watchpoint before and after the write, a write of data identical to the original contents is undetectable.

Because the WPDRIVER modifies SPTEs, a device page that directly interprets tables may experience access violations when it attempts to write into a memory page whose protection has been modified to monitor watchpoints. In other words, a page containing a watchpoint should not also contain a buffer for such a controller.

When you create a watchpoint, you should ensure that the system is quiet with respect to activity affecting the watchpoint area. Otherwise, an inconsistent copy of the original contents of the watchpoint area may be saved. WPDRIVER raises IPL to 11 to copy the watchpoint area's original contents. This means that if the area is modified from a thread of execution running as the result of an interrupt above 11, WPDRIVER can copy inconsistent contents. An inconsistent copy of the original contents may result in spuriously detected writes and missed writes.

If the page containing the watchpoint area is written by an instruction that incurs a page fault, the system can crash with a fatal PGFIPLHI bugcheck. As described in the previous section, after detecting an attempt to write to a page with a watchpoint, the WPDRIVER re-executes the writing instruction at IPL 31. Page faults at IPL 31 are not allowed.

If an outer access mode reference to a watchpointed page causes an access violation, the system will likely crash. When an access violation occurs on a page with a watchpoint, the current driver does not probe the intended access and faulting mode against the page's original protection code. Instead, it assumes that any access violation to that page represents a kernel mode instruction that can be reexecuted at IPL 31. The driver's subsequent attempt to REI, restoring a program status longword (PSL) with an outer mode and IPL 31, causes a reserved operand fault and, generally, a fatal INVEXCEPTN bugcheck.

You must be knowledgeable about the accesses to the page with the watchpoint and careful in using the driver. You should test the watchpoint creation on a standalone system. You should leave the watchpoint in effect long enough to have some confidence that pagefaults in instructions accessing that page are unlikely.

An attempt to CONNECT a WPA unit other than zero results in a fatal WPDRVRERR bugcheck.

The WPDRIVER is suitable for use only on a single CPU system. That is, it should not be used on a symmetric multiprocessing system. There are no plans to remove this restriction in the near future.

• Start logging
• Stop logging
• Display logged information

This chapter presents an overview of the System Service Logging utility and describes the System Service Logging commands.

14.1 Overview

System service logging (SSLOG) is used to record system service activity in a process. Its primary purpose is to troubleshoot process failure or misbehavior. This utility is available on OpenVMS Alpha and I64 platforms.

Once enabled, the SSLOG mechanism records information about system services requested by code running in the context of that process. The system services logged are:

• Executive and kernel-mode services
• Within privileged shareable image services
• Within the OpenVMS executive

SSLOG information is initially recorded in process space buffers. When a buffer is full, it is written to a disk file in the process's default disk and directory. After the disk file is closed, you can analyze it with the ANALYZE/SSLOG utility.

Recorded Information

SSLOG records the following information for each service:

• Service identification
• Location of service request - image and offset
• Access mode of requestor
• Service arguments (passed by value; only the addresses of arguments passed by reference)
• Timestamp
• Completion status

The information is recorded as follows:

• Initially in a ring of P2 space buffers (each process has its own P2 space buffers)
• A full buffer is written to the file SSLOG.DAT in the current default disk and directory

To enable any system service logging, check that the dynamic system parameter SYSSER_LOGGING is 1. If not, set it to a value of 1. Once logging is enabled, you can start system service logging for a particular process by DCL command, as shown in the following example.

$ SET PROC/SSLOG=(STATE=ON,COUNT=4,SIZE=%XFE00)

By default, execution of this command affects the current process. To target another process, use the /ID qualifier or specify the process by name.

To specify P2 space buffers of the process you are logging:

• Specify the number with COUNT
• Specify the size in bytes with SIZE (larger is better)

Buffers:

• Are pageable and thus charged against PGFLQUOTA
• Are not deallocated until process deletion

For additional information on this command, see the command SET PROCESS/SSLOG.

14.3 Disabling Logging

To disable logging, use the SET PROCESS DCL command:

$ SET PROC/SSLOG=(STATE=OFF)

or

$ SET PROC/SSLOG=(STATE=UNLOAD)

STATE=OFF stops logging, but it can be re-enabled again. STATE=UNLOAD stops logging and closes SSLOG.DAT

14.4 Displaying Logged Information

You display logged information with the DCL command ANALYZE/SSLOG filename , where the default filename is SSLOG.DAT. For additional information on this command and examples, see the command ANALYZE/SSLOG .

Displays the collected data.

Format

ANALYZE/SSLOG [/BRIEF | /FULL | /NORMAL | /STATISTICS] [/OUTPUT=filename] [/SELECT=(option[,...])] [/WIDE] [filespec]

Parameters

filespec

Optional name of the log file to be analyzed. The default filename is SSLOG.DAT.

option

Keyword for data to be displayed with the /SELECT qualifier. Table 14-1 lists the keywords that may be used, with their meanings.

Qualifiers

/BRIEF

Displays abbreviated logged information.

/FULL

Displays logged information, error status messages and sequence numbers.

/NORMAL

Displays basic logged information. This is the default.

/OUTPUT=filename

Identifies the output file for storing the results of the log analysis. An asterisk (*) and percent sign (%) are not allowed as wildcards in the file specification. There is no default file type or filename. If you omit the qualifier, results are output to the current SYS$OUTPUT device.

/SELECT=([option[,...]])

Selects entries based on choice of ACCESS_MODE, IMAGE, STATUS or SYSSER options. See Table 14-1 for the options and their meanings. At least one must be supplied.

/STATISTICS[=BY_STATUS]

Displays statistics on system services usage; accepts BY_STATUS keyword. Outputs a summary of the services logged with a breakdown by access mode. Output is ordered with the most frequently requested services first. If BY_STATUS is included, the summary is further separated by completion status. Output is displayed up to 132 columns wide.

/WIDE

Provides for a display of logged information up to 132 columns wide.

Description

The ANALYZE/SSLOG command displays the collected logged data. Note that a system service log must be analyzed on the same platform type as the one on which it was created; for example, a log created on an OpenVMS Alpha system must be analyzed on an OpenVMS Alpha system.

Table 14-1 describes the available options.

Table 14-1 SELECT Qualifer Keywords

Keyword	Meaning
ACCESS_MODE= mode	Selects data by access mode.
IMAGE= imagename	Selects data by imagename.
STATUS[= n]	Selects data by status. n is optional. /SELECT=STATUS displays all entries that have error statuses.
SYSSER= servicename	Selects data by servicename.

Enables or disables System Service Logging.

Format

SET PROCESS/SSLOG=(STATE={ON|OFF|UNLOAD}[,COUNT=n] [,SIZE=n] [,FLAGS=[NO]ARGS]) [/ID=id_number] [process-name]

Parameters

process-name

Specifies the name of the process for which logging is to be enabled or disabled.

COUNT=n

Specifies how many P2-space buffers to log. The default is 2.

FLAGS=[NO]ARGS

Specifies whether or not service argument values are to be logged. The default is ARGS, which requires privileges. If the value is ARGS but you lack privilege, no argument values are logged.

STATE=OFF

Disables (turns off) system service logging. Can be reenabled.

STATE=ON

Enables system service logging.

STATE=UNLOAD

Stops logging and closes SSLOG.DAT.

SIZE=n

Specifies P2-buffer size. The default value for size is 65,024₁₀ or FE00₁₆.

Qualifier

/IDENTIFICATION=identification_number

Specify to target a specific process by number.

Description

The SET PROCESS/SSLOG command:

• Enables or disables system service logging
• Opens the file SSLOG.DAT used to log data
• Can specify a specific process by name or ID (identification number)
• Can stop logging and close the file of logged data

When enabling SSLOG for a process, you specify the number and size of buffers to be used for logging. The buffers are allocated in P2 space and are charged against the process's paging file quota. The buffer space remains allocated and the quota charged until the process is deleted.

Between the time SSLOG is first enabled and SSLOG.DAT is closed, logging can be stopped and resumed.

Before the process is deleted, logging should be stopped and the log file closed. The log file is not closed automatically.

Required Privileges

Requires GROUP privilege to change other processes in the same group. Requires WORLD privilege to change processes outside your group.

To get argument values logged, you need either SETPRV, CMKRNL, or CMEXEC privilege.

Examples

$ SET PROC/SSLOG=(STATE=ON,COUNT=4,SIZE=%XFE00)
      

This command turns on system service logging with four P2 space buffers each having a size of FE00₁₆ bytes. If the process has SETPRV, CMKRNL, or CMEXEC priviledge, argument values are logged.

$ SET PROC/SSLOG=(STATE=UNLOAD)
      

This command stops logging and closes the file SSLOG.DAT.