k%Writing SDA Extensions.

Writing SDA Extensions


9Previous6 | Contents


DIf you specify this argument, you must also supply the len argument.

EWhen programming in MACRO-32 or BLISS, you can obtain the first four :bytes of the copied data in processor register R1 as well.

len


                
 VMS usage:  longword_unsigned
type:  longword (unsigned)
access:  read only
 mechanism:  by value

DNumber of bytes to copy. This argument must be specified unless the Bretadr argument was omitted as well. The lowest value of Blen is 4, in other words, the smallest unit to copy is a longword (on VAX and Alpha).

phyflg (Alpha only)


                
 VMS usage:  longword_unsigned
type:  longword (unsigned)
access:  read only
 mechanism:  by value

APhysical address indicator. If you set phyflg to 1, the Gaddress given in inadr/inadr64 is treated as physical address. 


DESCRIPTION

HThis callback is SDA's interface to access data from memory or from the Hdump file and write it into a user buffer where you can further process ±it. The callback is invoked by SDA$EXTEND_GETMEM and SDA$EXTEND_REQMEM; while Hthese callbacks signal all return codes as condition, SDA$EXTEND_TRYMEM Greturns the status code in cond_value only. Use this callback Hwhen data inaccessibility at the given address is an expected situation ;and you want to handle all possible memory errors yourself.

GOn the running system, you can access any location in P0, P1 and S0/S1 Hspace, assuming that the virtual address does not point to non-existent Gmemory or is currently unmapped (null pages). With SDA$EXTEND_GETMEM64 A(Alpha V7 only), you can also access data in P2 or S2 space. The Hcallback runs mainly in kernel mode, allowing you to access every valid >page in system or per-process space, regardless of their page Eprotection (except N/A (no access) pages). For addresses in Gper-process space and in system space occupied by process headers, SDA Dtriggers a special kernel AST to the target process to fault-in the *page into the target process' working set.





Note

AOn Alpha, when phyflg is set to 1, the address given in Cinadr/inadr64 is treated as physical address. Unlike with Gvirtual addresses, there is no way to check whether a physical address Fis valid (points to main memory or I/O space). Always be careful when Aspecifying physical addresses; specifying an address pointing to Fnon-existent physical memory can cause the CPU to halt with a machine !check.



GWhen analyzing a system dump, SDA copies the requested memory from the Adump file. Of course, this is possible only if the given virtual Gaddress range was valid (mapped to physical memory) at the time of the Gcrash. In addition, the page must exist in the dump file - this may or Fmay not be the case when the dump file write was not or was partially only completed.

GSDA uses a set of 'pseudo' virtual addresses to represent the contents Cof some processor registers. The following table shows this pseudo Eaddresses and the corresponding registers. Note that process context 4and CPU context will affect these registers as well. #  # #                                                                                                                                                                                                                                                                                                                                      
Register VAX Alpha V6 Alpha V7
 SP  FFFFFE00  C0000000  80000000.CFFFFFF0
KSP  FFFFFE20  C0000080  80000000.C0000000
ESP  FFFFFE24  C0000088  80000000.C0000008
SSP  FFFFFE28  C0000090  80000000.C0000010
USP  FFFFFE2C  C0000098  80000000.C0000018
 R0  FFFFFE30  D0000050  80000000.D0000050
 R1  FFFFFE34  D0000058  80000000.D0000058
 R2  FFFFFE38  D00000D0  80000000.D00000D0
 R3  FFFFFE3C  D00000D8  80000000.D00000D8
 R4  FFFFFE40  D00000E0  80000000.D00000E0
 R5  FFFFFE44  D00000E8  80000000.D00000E8
 R6  FFFFFE48  D00000F0  80000000.D00000F0
 R7  FFFFFE4C  D00000F8  80000000.D00000F8
 R8  FFFFFE50  D0000000  80000000.D0000000
 R9  FFFFFE54  D0000008  80000000.D0000008
R10  FFFFFE58  D0000010  80000000.D0000010
R11  FFFFFE5C  D0000018  80000000.D0000018
R12  FFFFFE60  D0000020  80000000.D0000020
R13  FFFFFE64  D0000028  80000000.D0000028
R14  -  D0000030  80000000.D0000030
R15  -  D0000038  80000000.D0000038
R16  -  D0000060  80000000.D0000060
R17  -  D0000068  80000000.D0000068
R18  -  D0000070  80000000.D0000070
R19  -  D0000078  80000000.D0000078
R20  -  D0000080  80000000.D0000080
R21  -  D0000088  80000000.D0000088
R22  -  D0000090  80000000.D0000090
R23  -  D0000098  80000000.D0000098
R24  -  D00000A0  80000000.D00000A0
R25  -  D00000A8  80000000.D00000A8
R26  -  D00000B0  80000000.D00000B0
R27  -  D00000B8  80000000.D00000B8
R28  -  D00000C0  80000000.D00000C0
 R29 (FP)  -  D0000040  80000000.D0000040
 R30 (SP)  -  C0000000  80000000.CFFFFFF0
R31  -  C0000008  80000000.CFFFFFF8
 PC  FFFFFE68  D0000100  80000000.D0000100
PSL/PS  FFFFFE6C  D0000108  80000000.D0000108
P0BR  FFFFFE70  -  -
P0LR  FFFFFE74  -  -
P1BR  FFFFFE78  -  -
P1LR  FFFFFE7C  -  -
PTBR  -  C00000A0  80000000.C0000020
ASN  -  C00000A8  80000000.C0000028
AST  -  C00000B0  80000000.C0000030
FEN  -  C00000B8  80000000.C0000038
FP0  -  C0000100  80000000.C0000080
FP1  -  C0000108  80000000.C0000088 .
.
.
FP29  -  C00001E8  80000000.C0000168
FP30  -  C00001F0  80000000.C0000170
FPCR  -  C00001F8  80000000.C0000178
 CYCLE_COUNTER  -  C0000080  80000000.C0000040
 PAL_RESERVED  -  C0000090  80000000.C0000050






Note

EWhen you specify one of these pseudo addresses, you must not specify Fanother length than the default value (4 on VAX, 8 on Alpha). You can Caccess one register at a time only, otherwise, SDA$_REGNOTVALID is $returned.



GOn Alpha V7, the input address (inadr64 argument) is a 64-bit Eaddress, allowing you to access every virtual address in P0, P1, P2, AS0/S1 and S2 space. To indicate this, the routine was renamed to 9SDA$EXTEND_TRYMEM64; the 32-bit version 8SDA$EXTEND_TRYMEM is not available on Alpha V7.


.

Condition values returned

                                                
 SDA$_SUCCESS ! Memory copied successfully.
 SDA$_INVLDADR G "Invalid virtual address". You have specified an invalid virtual  address.
 SDA$_INVRANGE G "Invalid address range specified". You have specified an invalid J address range. This may occur if you specify a valid base address in, inadr, but specify a value inH len which exceeds the amount of available virtual memory.
 SDA$_MEMNOTACC J "Memory locations not accessible in override mode" (Alpha V7 only). v When SDA was invoked in override mode (see Section 3.7), memory  access is not allowed.
 SDA$_MEMNOTSVD H "Specified memory not saved in dump file". You have specified the N address of a page whose contents was not written to the dump file. This ; may occur when the dump file write was not completed.
 SDA$_NOREAD L "No read access". You have specified the address of a page which does 7 not allow read access (a N/A - "no access" page).
 SDA$_NOTINPHYS K "Virtual data not in physical memory". You have specified either the E address of a null page (a page not currently mapped), or, when M analyzing a system dump, the address of a page which does not point to L physical memory (in other words, is not represented by a block in the  dump file).
 SDA$_NOTVALID I "Information not in physical memory." You have specified a virtual K address whose PTE (page table entry) is not in physical memory. This N may occur when analyzing a dump; you cannot access data at this address.
 SDA$_OUTSIDPT M "Virtual address range exceeds process page table bounds". The VAX CPU N provides three internal registers, holding the length of the P0, P1 and G system page tables. If you specify a virtual address range which 4 exceeds these lengths, this error is returned.
 SDA$_PFNNOTMPD G "PFN from PTE not mapped by memory descriptor". This indicates a ! corrupt or incomplete dump.
 SDA$_REGNOTVALID L "Register reference is invalid". You have specified a virtual address H which is used by SDA to store CPU registers (see above), but have : specified a value other than 4 (VAX) or 8 (Alpha) in len.
 SDA$_UNALIGNED H "Unaligned address specified" (Alpha only). This condition is not M returned, but is signaled as warning and displayed on screen even with L SDA$EXTEND_TRYMEM. It informs the user that the specified address was G not longword-aligned and that SDA has converted it to a longword , boundary by ANDing it with 0xFFFFFFFC.



Example


int status, clidata, ppddata;    .   .   .2status = SDA$EXTEND_TRYMEM(clidata,&ppddata);  if (!(status & 1)) { 6 SDA$EXTEND_PRINT(desc("Process has no CLI mapped"));  	 return; }  


FIn this example, a check is made to see whether the process has a CLI Hmapped - in this case, clidata is be a pointer to the CLI data Farea. If the process does not have a CLI mapped, the pointer contains ?0, resulting in a non-successful return status. This status is <detected, a message is displayed and the routine terminates.

DAs shown in the example, you can use SDA$EXTEND_TRYMEM do perform a Bparticular memory check and, in case of unavailability, display a .context-specific, more understandable message.

@The desc() function can be found in the description of KSDA$EXTEND_PRINT_COLUMNS.


1

SDA$EXTEND_TYPE



Displays a line of data.



Format

*

SDA$EXTEND_TYPE txtstr, [p1..pn]

 (VAX)*

SDA$EXTEND_TYPE txtstr, [prmlst]

(Alpha) )-

SDA$EXTEND_TYPE6 txtstr, [prmlst64]

 (Alpha V7 only)



RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


8Always SDA$_SUCCESS (0x00F48009). Any error is signaled.




ARGUMENTS



txtstr


                
 VMS usage:  char_string
type:  character string
access:  read only
 mechanism: 4 by descriptor - fixed-length string descriptor

GText to be displayed. The txtstr argument is the address of a Hcharacter string descriptor pointing to the text string. The string may 0contain FAO (Formatted ASCII Output) directives.

p1 to pn (VAX only)


                
 VMS usage:  varying_arg
type:  longword (signed)
access:  read only
 mechanism:  by value

EValues to be passed as FAO directive parameters. These arguments are Alongwords containing the parameters needed by the FAO directives Cspecified in the text string. Up to 17 parameters may be supplied; Gtheir number and contents depend on the used FAO directives. If you do @not use FAO directives in the text string, you can omit further arguments.

prmlst (Alpha only)


                
 VMS usage:  vector_longword_unsigned
type:  longword (unsigned)
access:  read only
 mechanism:  by reference

FList of FAO directive parameters. The prmlst argument is the >address of a longword vector wherein each longword contains a Hparameter. The vector must start on a longword boundary; the number and Gcontents of longwords depend on the used FAO directives. If you do not Buse FAO directives in the text string, you can omit this argument.

0This argument is used with SDA$EXTEND_TYPE only.!

prmlst64 (Alpha V7 only)


                
 VMS usage:  vector_quadword_unsigned
type:  quadword
access:  read only
 mechanism:  by reference

HList of FAO directive parameters. The prmlst64 argument is the >address of a quadword vector wherein each quadword contains a Hparameter. The vector must start on a quadword boundary; the number and Gcontents of quadwords depend on the used FAO directives. If you do not Buse FAO directives in the text string, you can omit this argument.

2This argument is used with SDA$EXTEND_TYPE64 only.




DESCRIPTION

HThis callback formats and displays a line of data on the current output >device; either on the screen or, if output was redirected via <SET OUTPUT, into the specified output file.

|Unlike SDA$EXTEND_PRINT, this callback does not provide a screen-oriented Cdisplay, the current line count is not maintained. If the Edisplay reaches the bottom of the screen, the screen scrolls; no new Gpage will be displayed and no page break is written to the output file.

zUse this callback instead of SDA$EXTEND_PRINT, when you want to display Honly few lines, for example, the result of a simple memory access. This Fwill allow the user to display data without unnecessary "Press Return 7to Continue" prompts. SDA's EVALUATE, 6EXAMINE, FORMAT and 6VALIDATE commands behave in this way.

DText formatting occurs via FAO directives. The callback invokes the GSYS$FAO (VAX) or SYS$FAOL (Alpha) system service to format the string. GMost FAO directives require parameters, they are supplied as arguments ;(VAX) or passed in a vector of longwords/quadwords (Alpha).

EOn Alpha V7, this callback exists in a version using the SYS$FAOL_64 @system service as well. This service accepts 64-bit parameters, =allowing you to display 64-bit data with the appropriate FAO Gdirectives. Note that on Alpha V7, both callbacks, SDA$EXTEND_TYPE and SDA$EXTEND_TYPE64 are available.

FSee the System Service Reference Manual for a description of Dthe SYS$FAO/SYS$FAOL/SYS$FAOL_64 system services, the available FAO (directives, and the required parameters.


/

Condition values returned

1
EReturns always SDA$_SUCCESS (0x00F48009). Conditions returned by RMS G(which is used for the write operations) are signaled and displayed on &the screen by SDA's condition handler.

FError conditions given by SYS$FAO/SYS$FAOL are not returned. FIf SYS$FAO/SYS$FAOL fails for some reason (you have specified invalid FFAO directives or insufficient directive arguments), a null string is displayed.




Example


9$DESCRIPTOR(txt_str,"Total of !UL !AZ sections found.");  char sectyp[] = "group-global";  int seccnt, prmlst[2];  :SDA$EXTEND_TYPE(&txt_str,seccnt,sectyp);    /* VAX */  8prmlst[0] = seccnt;                         /* Alpha */ 8prmlst[1] = (int) sectyp;                   /* Alpha */  <SDA$EXTEND_TYPE(&txt_str,prmlst);           /* Alpha */  


?This example shows the use of SDA$EXTEND_TYPE on VAX and Alpha.


;

SDA$EXTEND_VALIDATE_QUEUE



BValidates a double-linked queue. On Alpha V7, may also validate a singly-linked queue.



Format

1

SDA$EXTEND_VALIDATE_QUEUE options,inadr

5

SDA$EXTEND_VALIDATE_QUEUE64 options,inadr64

 (Alpha V7 only)



RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value



ARGUMENTS



options


                
 VMS usage:  mask_longword
type:  longword (unsigned)
access:  read only
 mechanism:  by value

DA longword holding a bit mask of options. The following options are defined:  "                      
Name Value Meaning
 OPT$M_SELF 0001  Queue is self-relative
 OPT$M_QUADLINK 0002 A Queue has linked list of quadword addresses (Alpha V7 only)
 OPT$M_SINGLINK 0004 3 Queue has no backward pointer (Alpha V7 only)
 OPT$M_LISTQUEUE 0008 B Display address of each element in the queue (Alpha V7 only)


HNote that the bit names shown in the table are not defined anywhere; if Ayou want to use it in your code, you must define the appropriate literals yourself.

inadr


                
 VMS usage: address
type:  longword (unsigned)
access:  read only
 mechanism:  by value

BLongword holding the virtual address of the queue head. This is a F32-bit address. If you specify OPT$M_SELF or OPT$M_QUADWORD (Alpha V7 /only), inadr must be quadword-aligned.

:This argument is used with SDA$EXTEND_VALIDATE_QUEUE only.

inadr64


                
 VMS usage: address
type:  quadword (unsigned)
access:  read only
 mechanism:  by value

FQuadword holding the 64-bit virtual address of the queue head. If you ?specify OPT$M_SELF or OPT$M_QUADWORD, inadr64 must be quadword-aligned.

<This argument is used with SDA$EXTEND_VALIDATE_QUEUE64 only.




DESCRIPTION

GThis callback is an interface to SDA's VALIDATE QUEUE Fcommand. Given the starting (header) address of a queue, the callback Cchecks the integrity of the queue. If the validation succeeds, SDA prints this message:
?Queue is complete, total of cnt elements in the queue 


:where cnt are the elements the queue consists of.

HOn VAX, a queue is a list of elements (data structures), where Fthe first longword in each element holds the base address of the next Delement (also called forward link) and the second longword =holds the base address of the previous element (backward Hlink). The queue can be accessed by its header, a pair of @longwords holding the address of the first element in the first Flongword, and the address of the last element in the second longword. CIn other words, the header is a 'dummy' element at a known address H(usually in the S0 pointer page), allowing you to 'enter' the queue and Eto traverse all its elements. Since each element is linked twice (by >its forward and backward link), a queue is sometimes called a doubly-linked list.

FThe VAX processor provides instructions to insert elements in a queue Gor remove elements from a queue in single, atomar operation. On Alpha, ,these instructions are emulated by PAL code.

DIf you set the OPT$M_SELF bit in the options argument, the Hqueue is assumed to be self-relative, meaning that forward and Bbackward links of an element are relative offsets to its Hneighboors. The VAX architecture requires the elements of self-relative Equeues starting on quadword boundaries; therefore, when setting this Hbit, the address given in inadr must be quadword-aligned. This =is also true for the emulated PAL code instructions on Alpha.

FIf the validate operation fails for some reason, a message indicating Hthe reason is displayed on screen, but SS$_NORMAL is returned. In other >words, you can use this callback to inform the user whether a Hparticular queue is valid, but you can't use it to obtain the result of Bthe check. If you must find out this, you must traverse the queue Belements yourself (the only condition returned by the callback is >SDA$_NOQUEUE, meaning that 0 was specified in inadr).

*Options bits for Alpha V7

GThe following description is meaningful for Alpha V7 only. It explains #the remaining option bits.

 




9Previous- | Next6 | Contents