8:dprobes.lang

From Linux Man Pages

NNAAMMEE Dynamic Probes Program File Format and Language Reference

DDEESSCCRRIIPPTTIIOONN The Dynamic Probes (dprobes) facility can be used to insert software probes dynamically into executing code modules. When a probe is fired, a user written probe-han- dler is executed. The probe-handler is a program written in an assembly-like language, based on the Reverse Polish Notation (RPN).

Dynamic Probes also allows probes to be fired on specific type of memory accesses(execute|write|read or write|io). This is made possible by using the debug registers avail- able on Intel x86 processors. These probes are called watchpoint probes. Watchpoint probes are not currently available for S/390.

A probe program file specifies one or more probes for an executable program. It consists of a file header followed by a set of probe definitions. A probe definition con- tains the probe's identity and a series of instructions that make up the probe handler.

The assembly-like language in which the probe handlers are written provides: - arithmetic/logical/bitwise operations - control flow instructions (conditional branch- ing/calls) - preprocessing directives (same as those in C lan- guage) Special instructions are provided for a probe handler to: - access CPU registers - access user/kernel memory contents - access key system variables - access IO ports - log data into a buffer - exit to other debug facilities

RPN instructions work on a circular stack of 1024 ele- ments. The top of the stack is the only element accessible at any time. Typical instruction to place a data item on to the top of the stack is by a ppuusshh instruction. Simi- larly, a ppoopp instructions a retrieves the data item on the top of the stack.

The stack elements are of fixed size (machine word length: 4 bytes on IA32) and instructions always operate on inte- gral number of elements. The stack pointer will always be aligned on a machine word length boundary. Thus, even if a byte is pushed on to the stack, it will be padded to size of machine word length and placed on the stack.

In addition to RPN program stack, RPN program interpreter also provides a ccaallll ssttaacckk.. Call stack is primarily pre- sent to hold the return address of the ccaallll rrppnn iinnssttrruucc-- ttiioonn..

RPN language supports EExxcceeppttiioonn HHaannddlliinngg and SSttaacckk TTrraacc-- iinngg.. Several kinds of faults can occur when rpn instruc- tions are executed. RPN program interpreter generates dif- ferent exceptions based on the type of fault. Programmer has the option of catching the exceptions and try to recover from faults by coding exception handlers. Pro- grammer has the option of masking/unmasking different exceptions. Some exceptions are non-maskable. Maskable exceptions are not generated if they are masked. Non- maskable exceptions terminate the probe program interpre- tation if they are masked.

When an exception is generated, programmer has the option to store probe program execution state (RPN stack entries, probe point details, call chain etc) in SSttaacckk ttrraaccee bbuuffffeerr.. This is called ssttaacckk ttrraacciinngg.. Stack trace buffer data is logged along with the normal dprobes log(see man page ddpprroobbeess((88)) ) when the probe program terminates. Pro- grammer can also store the execution state at arbitrary time during probe program execution by using an rpn instruction (explained later).

EExxcceeppttiioonn hhaannddlliinngg aanndd SSttaacckk TTrraacciinngg iiss pprriimmaarriillyy iinntteennddeedd ttoo bbee uusseedd bbyy HHiigghh LLeevveell LLaanngguuaaggee((HHLLLL)) DDPPrroobbeess CCoommppiilleerr.. HHLLLL ccoommppiilleerr aalllloowwss pprroobbee pprrooggrraammss ttoo bbee wwrriitttteenn iinn CC--lliikkee llaanngguuaaggee,, wwhhiicchh wwiillll tthheenn bbee ccoommppiilleedd iinnttoo RRPPNN llaanngguuaaggee..

RReeffeerr ttoo tthhee sseeccttiioonn RRPPNN EExxcceeppttiioonn HHaannddlliinngg aanndd SSttaacckk TTrraacciinngg for complete explanation.

The dprobes interpreter provides some iinntteerrnnaall rreeggiisstteerrss which the probe program can make use of. There are rpn instructions provided to access/modify these.

TToopp ooff tthhee SSttaacckk PPooiinntteerr rreeggiisstteerr((TTSSPP)) This register always contains the pointer to top of the RPN stack. This register gets modified on every push and pop rpn instruc- tion.

SSttaacckk BBaassee PPooiinntteerr rreeggiisstteerr((SSBBPP)) This register is intended to be a pointer to arbitrary locations on RPN stack. SBP is stored/restored on every call/return. Programmer can use SBP as pointer to the base of RPN stack during the call.

LLoogg PPooiinntteerr rreeggiisstteerr((LLPP)) Holds the value of the current dprobes log buffer pointer. It is initialized to the beginning of the user log area in the log buffer. Note that a few bytes in the beginning of the log buffer are used to store the log header elements.

PPrreevviioouuss LLoogg PPooiinntteerr rreeggiisstteerr((PPLLPP)) PLP will be maintained as a lagging value of LP. This will normally be the same value as LP when a logging instruction starts execution. PLP is updated to LP only if logging instruction succeeds. Using PLP, programmer has the option of backing out the partial log in the log buffer if logging fails.

PPRROOBBEE PPRROOGGRRAAMM FFIILLEE FFOORRMMAATT Probe Program file consists of the following sections: ** File Header ** Probe Point Definitions (one or more) -- Probe Point Header -- RPN Instructions

Comments can be specified anywhere in the probe program file. Comments start with two backslashes(//) and extend up to the end of the line. Blank lines are allowed anywhere in the probe program file.

File header and each probe point header consist of a num- ber of statements of the kkeeyy == vvaalluuee format.

Numeric values may be specified in decimal or hexadecimal. Hexadecimal values have to be prefixed with 00xx , as in the C language.

Except the value of nnaammee== statement in the file header, everything else is case-insensitive. The value of nnaammee== has to be case-sensitive as the executable file names in Linux are case-sensitive.

All the sections are defined below in detail.

PPRROOBBEE PPRROOGGRRAAMM FFIILLEE HHEEAADDEERR File header may comprises of one or more statements of the kkeeyy == vvaalluuee format. Any combination of the below explained statements may be specified with the nnaammee == statement being mandatory.

nnaammee == <<mmoodduulleennaammee>> <modulename> is the name of the module on which probe is to be applied. It needs to be specified within quotes if it contains any characters other than a-zA-Z0-9. For ex.: name = testapp (valid) name = /home/user/testapp (invalid) name = "/home/user/testapp" (valid) name = "a+b/testapp" (valid).

mmooddttyyppee == <<ttyyppeennaammee>> Type of the module. <typename> can take the any of the following values: kernel - the name specified above is the kernel kmod - the name specified above is a kernel module user - the name specified above is user space module. It could be an executable file or a shared library

vvaarrss == <<nn>> Probe handlers can use a specified number (<n>) of local variables. Each variable is of a fixed size of 4 bytes. Many instructions can take a variable as an operand, usu- ally referred to as "lv,index", where index is the vari- able index from 0 to <n>-1. They are all initialized to zero. Variables retain their values across probe hits. These variables are available to all the probe handlers in this probe program. Default value of <n> is 0 which implies that this probe program does not make use of vari- ables.

ggvvaarrss == <<nn>> <n> specifies the number of global variables that the probe handler can use. The use and accessing mechanisms of global variables are similar to local variables except that they are accessible across probe points. i.e., they are global in nature. Default value of <n> is 0 which implies that this probe program does not make use of global variables.

ggrroouuppddeeff == <<ggrroouupp__nnaammee>>[[ <<ggrroouupp__nnaammee>>[[ <<ggrroouupp__nnaammee>> ......]]]] This field is used to define all the valid group defini- tions which can be used by the individual probe points. The <group_name> used in the ggrroouupp field of any probe- point header should have a definition present in this field.

ttyyppeeddeeff == <<ttyyppee__nnaammee>>[[ <<ttyyppee__nnaammee>>[[ <<ttyyppee__nnaammee>> ......]]]] This field is used to define all the valid type defini- tions which can be used by the individual probe points. The <type_name> used in the ttyyppee field of any probe-point header should have definition present in this field.

mmaajjoorr == <<nn>> <n> is the number to be assigned as the probe point major code, The major code can be used for easy identification of the log generated by the probe handlers specified in this program. Default value is 0.

iidd == <<nn>> <n> is a number which can be used as probe program identi- fier. This is not validated for uniqueness. Default value is 0.

llooggmmaaxx == <<nn>> <n> is the maximum number of bytes that can be logged in the log buffer during one run of a probe handler. Default is 1024 bytes.

jjmmppmmaaxx == <<nn>> <n> is the maximum number of jumps and loop iterations allowed for one run of a probe handler. This is needed to ensure that probe handlers will not loop infinitely caus- ing the system to hang. Default is 256.

llooggoonnffaauulltt == <<yyeess||nnoo>> This specifies if the probe on faulting instruction should produce log or not. The default action is not to produce log. But if yyeess is specified, even if the probed instruc- tion faults, the log is generated. This keyword in probe program file header applies uniformly to all the probes specified in this probe program file.

PPRROOBBEE--PPOOIINNTT DDEEFFIINNIITTIIOONN

PPrroobbee--PPooiinntt HHeeaaddeerr:: Probe point header consists of statements of the kkeeyy == vvaalluuee format. The valid statements are explained below. These can be specified in any order, with the exception that ooffffsseett

<<nn>> must appear first. ooppccooddee

<<nn>> and ooffffsseett == <<nn>> statements are mandatory, remaining state- ments are

optional.

In case of kernel mode probe program files, instead of ooffffsseett == <<nn>> one can specify aaddddrreessss == statement (explained below) to specify the probe location by its absolute linear address.

ooffffsseett == <<nn>> <n> is the offset within the module where probe-point will be applied. It can also be specified symbolically using function symbol names and symbol expressions. e.g offset = main + 0x10 By default, the symbols will be looked up in the module specified on the nnaammee== line in the file header. The file to be used for looking up the symbols can also be specified on the ----iinnsseerrtt command line using

ssyymm option. Kernel symbols can only be looked up in

the SSyysstteemm..mmaapp file. The pathname of System.map should be specified using the ----ssyymm option on the command line. See man page ddpprroobbeess((88)) for more

details.

aaddddrreessss == <<nn11>>[[::<<nn22>>]] This statement may be present only in kernel mode probe program files. nn11 specifies the absolute virtual address of the probe location. For watchpoint probes, nn11 and nn22 together specify the range of memory address for which the watchpoint is active. nn11 is the lower address and nn22 is the higher address of the range. Note that if this range is not consistent with the range specified by the proces- sor, probes won't be inserted. On Intel x86 processors, the allowed memory ranges are 1, 2 and 4 bytes. Note that nn22 is an optional argument here and it has no meaning in case of breakpoint probes.

This statement is mutually exclusive with the ooffffsseett == <<nn>> statement. Only one of them should be present. Instead of specifying the probe point by offset, this statement can be used to specify it directly by its absolute linear address. However, this statement can also take symbolic expressions.

wwaattcchhppooiinntt == <<xx||ww||rrww||iioo>> This classifies the probe as watchpoint type and also specifies the type of watchpoint probe. This statement can be present only in the kernel mode probe program files. When this statement is not pre- sent, probes are meant to be of breakpoint type. (Cur- rently not implemented on S/390)

xx:: Watchpoint probes will be hit on instruction fetch from the address specified in aaddddrreessss == statement. Here the valid address range is 1 byte.

ww:: Watchpoint probes will be hit if any write is made to the address range specified in aaddddrreessss == statement. Valid address ranges are 1, 2 and 4 bytes.

rrww:: Watchpoint probes will be hit if any read or write occurs in the address range specified. Valid address ranges are 1, 2 and 4 bytes.

iioo:: Watchpoint probes will be hit if any io read or write happens in the address range specified. Valid address ranges are 1, 2 and 4 bytes.

Probes won't be applied if the address range specified is not consistent with the address range specified by the processor.

NNoottee:: If watchpoint probes are to be put on uusseerr aaddddrreessss , the user address should be specified in a kernel mode probe program file. Also note that user mode watchpoints are global. i.e., the are active across all process con- texts.

See EExxaammppllee 77 in COMPLETE EXAMPLES OF RPN for typical use of watchpoint probes.

ooppccooddee == <<nn>> <n> is the first byte of the opcode of the instruction present at the probe location (IA32), or the first two bytes of an instruction which may be the opcode, the opcode and part of the operands, or part of the opcode (S390). At the time of inserting probes, the opcode pre- sent there is compared with the one specified here and the probe is applied only if they match. This is to ensure that probe is actually being inserted in the intended location.

Opcode specification is mandatory only for breakpoint probes. For watchpoint probes, it may not be specified.

Note that only the first byte of the instruction on which a probe is desired is specified in this statement. If the instruction has a prefix, the prefix byte has to be speci- fied here.

There are a few instructions on which probes cannot be placed. They are: iinntt33,, iinntt,, iinnttoo,, wwaaiitt ((IIAA3322)) ssvvcc,, llppssww ((SS//339900)) aanndd ffllooaattiinngg ppooiinntt iinnssttrruuccttiioonnss wwhheenn FFPPUU iiss eemmuu-- llaatteedd..

WWAARRNNIINNGG:: The onus is on the user to correctly specify the offset and the opcode statements. Incorrect use may cause probes to be inserted in the middle of an instruction which could lead to a system crash and data corruption.

While Dprobes interoperates well with other debuggers, if a breakpoint is placed using another debugger at the same location where a probe already exists, the breakpoint will be ineffective.

Although probes on floating point instructions are not allowed, when the FPU is emulated, we are not explicitly disallowing probes on FFXXSSAAVVEE and FFXXSSTTOORR instructions. Putting probes on these instructions when FPU is emulated might result in unexpected behavior.

ggrroouupp == <<ggrroouupp__nnaammee>> This field classifies the probe-point under some specified group. The <<ggrroouupp__nnaammee>> specified here should be present in the <group_name> list present in the ggrroouuppddeeff field of the probe program file header. The ggrroouupp field is used by the ----aappppllyy--ppppddff option on the command line to selectively apply the probes.

ttyyppee == <<ttyyppee__nnaammee>> This field classifies the probe-point under some specified type. The <<ttyyppee__nnaammee>> specified here should be present in the <type_name> list present in the ttyyppeeddeeff field of the probe program file header. The ttyyppee field is used by the ----aappppllyy--ppppddff option on the command line to selectively apply the probes.

NNoottee:: See Example 6. in COMPLETE EXAMPLES OF RPN for usage of the keywords group, type, groupdef and typedef.

mmiinnoorr == <<nn>> <n> is the number to be assigned as the probe point minor code, The minor code can be used for easy identification of the log generated by this probe handler. Default value is 0.

iiggnnoorree == <<nn>> If this entry is present, this probe handler will not be executed the first <<nn>> times it is hit. Default value is 0. This instruction was called ppaassss__ccoouunntt in dprobes ver- sions before 3.4.0.

mmaaxxhhiittss == <<nn>> This probe point will be disabled automatically after it is hit <<nn>> times. Default value is 0x7fffffff. This instruction was called mmaaxx__hhiittss in dprobes versions before 3.4.0.

llooggoonnffaauulltt == <<yyeess||nnoo>> This keyword has the same meaning as the llooggoonnffaauulltt key- word present in the probe program file header, but here it specifies the 'log on fault' behavior for this probe. Any settings by the use of llooggoonnffaauulltt keyword in probe program file header gets over-ridden here.

IINNSSTTRRUUCCTTIIOONN SSEETT Probe handler consists of any meaningful combination of valid RPN instructions. The general format of an instruc- tion is: llaabbeell:: ooppeerraattoorr [[oopp11 [[,,oopp22 ,, .......... ]]]] //// ccoommmmeenntt //// ccoommmmeenntt

llaabbeell:: optional string used to specify "jmp" targets. It has to start with a non-numeric character and delimited by a ':' and can consist of any alpha-numeric characters. An RPN instruction has to follow a label.

ooppeerraattoorr:: any of the instructions listed below.

ooppNN:: any operands required for the instruction.

Note that TTOOSS in the following description refers to the contents of the top of the stack on which RPN instructions operate.

The Instructions in this language are classified under various categories as follows:

RRPPNN EExxeeccuuttiioonn GGrroouupp::

jjmmpp <<llaabbeell>> program control is transferred to <label>

jjlltt <<llaabbeell>> program control is transferred to <label> if TOS < 0.

jjllee <<llaabbeell>> program control is transferred to <label> if TOS <= 0.

jjggtt <<llaabbeell>> program control is transferred to <label> if TOS > 0.

jjggee <<llaabbeell>> program control is transferred to <label> if TOS >= 0.

jjzz <<llaabbeell>> program control is transferred to <label> if TOS == 0.

jjnnzz <<llaabbeell>> program control is transferred to <label> if TOS != 0.

LLoooopp <<llaabbeell>> Decrement TOS and jump to <label> if TOS != 0.

NNoottee:: If the total number of branches (jumps+loops) taken during one run of the probe handler exceeds the jmpmax value specified in the program file header, probe handler will generate a JMP_MAX exception or will terminate if this exception is masked.

ccaallll <<pprrooccnnaammee>> Call the procedure <procname>. When a procedure is called, the return addresses are stored on the call stack, If number of nested calls exceeds 32 at any point of time, CALL_MAX exception is generated. If the exception is masked, the probe handling is terminated.

rreett Return from the procedure. The address to return to is the top of the call stack. If ret doesn't have an associated call (can happen if ret is done with an empty call stack) CALL_MAX exception is generated. If the exception is masked, the probe handling is terminated.

FFoorrmmaatt ooff PPrroocceedduurree:: A procedure can be written in the probe program file using the pprroocc and eennddpprroocc instructions. These procedures are accessible to all the probe handlers in this probe program file. Procedures defined in one probe program cannot be called from a different probe program. Note that, using the preprocessor directive ##iinncclluuddee <<ffiilleennaammee>> one can write libraries of probe programs and include them in mul- tiple probe program files. The format of a procedure definition is: pprroocc <<pprrooccnnaammee>> : instructions : rreett eennddpprroocc

ccaallllkk This instruction can be used to allow one or more kernel modules to be called from the RPN command interpreter. Modules registering for this will use the GKHI mechanism and will exist as hook_exits to DProbes. A sample kernel module that registers exits to be called when ccaallllkk instruction is interpreted, callk.c, can be found in the command directory.

aabboorrtt Terminate the execution of the probe handler without sav- ing the data logged so far.

eexxiitt Terminate the execution of the probe handler, saving the data logged so far.

eexxiitt <<nn>> This facility is used to interface with other debug facil- ities. The debug facilities are invoked when this instruction is encountered in the probe handler. This instruction terminates the probe handler. The exit n instruction can be used when it is more appropriate to invoke the exit facilities when certain conditions are detected in the probe handler. The value of <<nn>> can be any one of the following: 11 == SSGGII kkddbb exit 1 invokes kdb only for kernel mode probes. For user mode probes it is equivalent to nop as user applications are not expected to use kernel debug- ger. When kdb is terminated, probe handler termi- nates. This instruction will be effective only if the kernel is configured with the kdb support.

22 == SSGGII ccrraasshh dduummpp exit 3 takes the crash dump for only kernel mode probes. This instruction will be effective only if the kernel is configured with the crash dump sup- port. Note that dump taken might not show the cor- rect back trace.

33 == CCoorree DDuummpp exit 3 dumps the core of the process which has probe in it. After core dump, the probe handler terminates. Also dumping the core of the process doesn't cause the process to stop. This instruc- tion is meaningful only in case of user probes.

Any other value of <<nn>> will result in INVALID_OPERAND exception being generated.

rreemmoovvee Remove the current probe. This can be used to remove a probe from within the probe handler when certain condi- tions are detected that may render this probe unnecessary.

nnoopp No operation.

LLooggggiinngg GGrroouupp

sseettmmiinn <<mmiinnoorr>> Override the minor code with <minor> when data for this probe point is logged to the log buffer.

sseettmmiinn Override the minor code with TOS when data for this probe point is logged to the log buffer.

sseettmmaajj <<mmaajjoorr>> Override the major code with <major> when data for this probe point is logged to the log buffer.

sseettmmaajj Override the major code with TOS when data for this probe point is logged to the log buffer.

Note that the instructions to temporarily override major and minor codes are provided to enable users to easily identify of certain log records in the log buffer.

lloogg ssttrr It pops two elements from the RPN stack ( aaddddrr and nn in that order). It logs the nn number of bytes starting at the aaddddrr.. Logging is discontinued if a NULL byte is encoun- tered. The NULL byte is not logged. If the log buffer becomes full, the program interpreter will either generate LOG_MAX exception if this exception is unmasked or will exit. In either case, the partial string is not logged.

If the log is successful, the logged string is prefixed by a token byte of 1 and a word indicating the length of the string logged. This data is intended to be used by any applications that may try to format the data collected in the log buffer.

If the logging fails due to invalid memory reference the fault record is logged. Then INVALID_ADDR exception is generated if this exception is unmasked or probe handler is terminated if it is masked. Fault record consists of a token byte of -1(0xff), an unsigned short length of 4, and the faulting address(4 bytes).

This instruction is intended to be used to log null-termi- nated strings at a known address to the log buffer. The length is only used to specify the upper limit on the string length. An example scenario would be (say we know that address of the string is in ECX) push w, 256 push R, ECX log str

lloogg aarrff This instruction has been renamed to lloogg ssttrr in dprobes v3.4.0.

lloogg aarrss This instruction providing segmented addressing mode has been removed from dprobes v3.4.0.

lloogg mmrrff It pops two elements from the RPN stack ( aaddddrr and nn in that order). It logs the nn number of bytes starting at the aaddddrr.. If the log is successful, the logged data is pre- fixed by a token byte of 0 and a word indicating the length of the data logged. This data is intended to be used by any applications that may try to format the data collected in the log buffer.

If the logging fails due to invalid memory reference, fault record is logged and INVALID_ADDR exception is gen- erated. If this exception is masked, the probe handling is terminated. Fault record consists of a token byte of -1(0xff), an unsigned short length of 4, and the faulting address(4 bytes).

This instruction is intended to be used to log any data structures at a known address to the log buffer. An exam- ple scenario to log say the first 40 bytes of the current task structure would be: push w, 40 push task log mrf

lloogg mmrrss This instruction providing segmented addressing mode has been removed from dprobes v3.4.0.

lloogg <<ccoouunntt>> Pops <<ccoouunntt>> number of elements from the RPN stack and stores them in the log buffer.

lloogg bb,, <<ccoouunntt>> lloogg ww,, <<ccoouunntt>> lloogg dd,, <<ccoouunntt>> These instructions have been replaced with the simpler lloogg <<ccoouunntt>> instruction in dprobes v3.4.0.

NNoottee that the above logging instructions will generate LOG_OVERFLOW exception if size of the log exceeds the size specified on the llooggmmaaxx== statement in the probe program file header. Exception is generated only if it is unmasked. Partial log is retained.

lloogg Pops ccoouunntt and logs count number of elements from RPN stack(by popping) to log buffer.

NNoottee:: With this instruction, the actual log is preceded by a 33 bbyyttee pprreeffiixx having a token byte of 7 and a word indi- cating number of RPN elements logged. If logging fails due to log buffer overflow, LOG_OVERFLOW exception is gen- erated(only if this exception is unmasked). Partial log is retained.

LLooccaall VVaarriiaabbllee GGrroouupp

The following instructions are provided to manipulate variables. Note that the llooccaall here means that the vari- ables defined in a probe program are not accessible from other probe programs. However, variables defined in a probe program are accessible to all the probe handlers in that program, as mentioned before.

Variables are identified by their index. An iinnddeexx must be in the range 00 to nn where nn is the number specified on the vvaarrss== statement in the probe program file header. The instructions that manipulate local variables obtain the index of the variable to operate on either as an immediate operand in the instruction or from the RPN stack (in which case the value on the top of the stack is considered as the index). When index specified as an immediate operand, if its value is not the allowed range, then a compilation error will be returned when the probe program is being applied.

ppuusshh llvv,, <<iinnddeexx>> Push the content of the specified variable on to the RPN stack.

ppuusshh llvv Pops an element ( iinnddeexx ) from the stack and pushes the content of the variable on to the RPN stack.

ppoopp llvv,, <<iinnddeexx>> Pop one element from the RPN stack and set it as the value of the specified variable.

ppoopp llvv Pops two elements ( vvaalluuee , and iinnddeexx ) from the stack and sets the specified variable to vvaalluuee

mmoovvee llvv,, <<iinnddeexx>> Set the specified variable to TOS. Note that here the con- tents of the RPN stack remain unchanged.

mmoovvee llvv Pops one element ( iinnddeexx ) from the stack and sets the specified variable to the current TOS.

iinncc llvv,, <<iinnddeexx>> Increments the specified variable.

iinncc llvv Pops one element ( iinnddeexx ) from the stack and increments the specified variable.

ddeecc llvv,, <<iinnddeexx>> Decrements the specified variable.

ddeecc llvv Pops one element ( iinnddeexx ) from the stack and decrements the specified variable.

lloogg llvv Pops two elements ((rraannggee aanndd ssttaarrttiinngg iinnddeexx in that order) and logs local variables starting from iinnddeexx==ssttaarrttiinngg iinnddeexx till iinnddeexx==ssttaarrttiinngg iinnddeexx++rraannggee to log buffer. The actual log is preceded by a 33 bbyyttee pprreeffiixx having a token byte of 5 and a word indicating number of local variables logged. If the log buffer becomes full, LOG_OVERFLOW exception is generated (only if this exception is unmasked) after logging as many variables as possible.

NNoottee:: For all the above instructions accessing local vari- ables, INVALID_OPERAND exception is generated if the iinnddeexx is exceeds the range specified by vvaarrss == statement in the file header. If this exception is masked, the probe han- dling is terminated.

GGlloobbaall VVaarriiaabbllee GGrroouupp..

Global variables can be accessed across all the probe pro- grams that are active. Probe programs are expected to use global variables in a cooperative manner. Variables are identified by their index. An iinnddeexx must be in the range 00 to nn where nn is the number specified on the ggvvaarrss== state- ment in the probe program file header. The instructions that manipulate global variables obtain the index of the variable to operate on either as an immediate operand in the instruction or from the RPN stack (in which case the value on the top of the stack is considered as the index). When index specified as an immediate operand, if its value is not the allowed range, then a compilation error will be returned when the probe program is being applied.

ppuusshh ggvv,, <<iinnddeexx>> Push the content of the specified variable on to the RPN stack.

ppuusshh ggvv Pops an element ( iinnddeexx ) from the stack and pushes the content of the variable on to the RPN stack.

ppoopp ggvv,, <<iinnddeexx>> Pop one element from the RPN stack and set it as the value of the specified variable.

ppoopp ggvv Pops two elements ( vvaalluuee , and iinnddeexx ) from the stack and sets the specified variable to vvaalluuee

mmoovvee ggvv,, <<iinnddeexx>> Set the specified variable to TOS. Note that here the con- tents of the RPN stack remain unchanged.

mmoovvee ggvv Pops one element ( iinnddeexx ) from the stack and sets the specified variable to the current TOS.

iinncc ggvv,, <<iinnddeexx>> Increments the specified variable.

iinncc ggvv Pops one element ( iinnddeexx ) from the stack and increments the specified variable.

ddeecc ggvv,, <<iinnddeexx>> Decrements the specified variable.

ddeecc ggvv Pops one element ( iinnddeexx ) from the stack and decrements the specified variable.

lloogg ggvv Pops two elements ((rraannggee aanndd ssttaarrttiinngg iinnddeexx in that order) and logs global variables starting from iinnddeexx==ssttaarrttiinngg iinnddeexx till iinnddeexx==ssttaarrttiinngg iinnddeexx++rraannggee to log buffer. The actual log is preceded by a 33 bbyyttee pprreeffiixx having a token byte of 6 and a word indicating number of global variables logged. If the log buffer becomes full, LOG_OVERFLOW exception is generated (only if this exception is unmasked) after logging as many variables as possible.

NNoottee:: For all the above instructions accessing global variables, INVALID_OPERAND exception is generated if the iinnddeexx is exceeds the range specified by ggvvaarrss == statement in the file header. If this exception is masked, the probe handling is terminated.

AArriitthhmmeettiicc && LLooggiicc GGrroouupp

aadddd Pops two elements ( vvaall11 and vvaall22 ) from the stack and pushes the result of ( vvaall11++vvaall22 ) on to the stack.

ssuubb Pops two elements ( vvaall11 and vvaall22 ) from the stack and pushes the result of ( vvaall11--vvaall22 ) on to the stack.

mmuull Pops two elements ( vvaall11 and vvaall22 ) from the stack and pushes the result of ( vvaall11**vvaall22 ) on to the stack.

ddiivv Pops two elements ( ddiivviissoorr and ddiivviiddeenndd ) from the stack and performs an uunnssiiggnneedd ddiivviissiioonn ((ddiivviiddeenndd//ddiivviissoorr)).. Pushes the rreemmaaiinnddeerr first and qquuoottiieenntt next on to the stack.

iiddiivv Pops two elements ( ddiivviissoorr and ddiivviiddeenndd ) from the stack and performs a ssiiggnneedd ddiivviissiioonn ((ddiivviiddeenndd//ddiivviissoorr)).. Pushes the rreemmaaiinnddeerr first and qquuoottiieenntt next on to the stack.

NNoottee:: The division instructions generate DIVIDE_BY_ZERO exception if divisor is zero. If this exception is masked, the probe handling is terminated.

nneegg Pops one element ( vvaall ) from the stack and pushes its 1's complement ( ~~vvaall ) on to the stack.

aanndd Pops two elements ( vvaall11 and vvaall22 ) from the stack and pushes the result of ( vvaall11 && vvaall22 ) on to the stack.

oorr Pops two elements ( vvaall11 and vvaall22 ) from the stack and pushes the result of ( vvaall11 || vvaall22 ) on to the stack.

xxoorr Pops two elements ( vvaall11 and vvaall22 ) from the stack and pushes the result of ( vvaall11 ^^ vvaall22 ) on to the stack(.

rrooll <<ccoouunntt>> Rotates left TOS by (byte operand) number of bits.

rrooll Pops two elements ( vvaall and ccoouunntt ) from the stack, rotates left vvaall by ccoouunntt number of bits and pushes the result on to the stack.

rroorr <<ccoouunntt>> Rotates right TOS by (byte operand) number of bits.

rroorr Pops two elements ( vvaall and ccoouunntt ) from the stack, rotates right vvaall by ccoouunntt number of bits and pushes the result on to the stack.

sshhll <<ccoouunntt>> Shifts left TOS by (byte operand) number of bits.

sshhll Pops two elements ( vvaall and ccoouunntt ) from the stack, shifts left vvaall by ccoouunntt number of bits and pushes the result on to the stack.

sshhrr <<ccoouunntt>> Shifts right TOS by (byte operand) number of bits.

sshhrr Pops two elements ( vvaall and ccoouunntt ) from the stack, shifts right vvaall by ccoouunntt number of bits and pushes the result on to the stack.

ppbbll Pops two elements ( bbiitt iinnddeexx nn and ooppeerraanndd ) from the stack, sets all the bits to the lleefftt of bit nn--11 of the operand to the value of the bit nn--11.. Operand is pushed back to rpn stack.

ppbbll <<nn>> Pops one element ( ooppeerraanndd ) from the stack, sets all the bits to the lleefftt of bit nn--11 of the operand to the value of the bit nn--11.. Operand is pushed back to rpn stack.

ppbbrr Pops two elements ( bbiitt iinnddeexx nn and ooppeerraanndd ) from the stack, sets all the bits to the rriigghhtt of bit nn--11 of the operand to the value of the bit nn--11.. Operand is pushed back to rpn stack.

ppbbrr <<nn>> Pops one element ( ooppeerraanndd ) from the stack, sets all the bits to the rriigghhtt of bit nn--11 of the operand to the value of the bit nn--11.. Operand is pushed back to rpn stack.

NNoottee:: For all these propagate instructions, the valid value of bbiitt iinnddeexx nn ranges between 11 and rrppnn ssttaacckk wwiiddtthh.. If the bit index n is 0 or greater than RPN stack width, INVALID_OPERAND exception is generated. If this exception is masked, the probe handling is terminated.

xxcchhgg Exchange the top two elements of the RPN stack.

dduupp <<ccoouunntt>> The TOS will be pushed on to the stack <count> times.

dduupp Pops two elements ( vvaall and ccoouunntt ) from the stack and pushes the vvaall on to the stack ccoouunntt++11 times.

rrooss <<ccoouunntt>> Rotate the RPN stack down ccoouunntt number of times. This is equivalent to popping ccoouunntt elements from the stack.

RReeggiisstteerr GGrroouupp

Inside the probe handler, access is provided to two dif- ferent kinds of register contexts, the uusseerr ccoonntteexxtt regis- ters and ccuurrrreenntt ccoonntteexxtt registers. The current context registers refer to the state of the registers at the time of the probe hit. User context registers refer to the state of the registers in the current process context just before it switched to kernel mode. For probes in user space code, user and current context registers are same. In the following instructions, rr indicates registers in the current context and uu indicates registers in the user context. Please refer to AAppppeennddiixx AA for names of the reg- isters and which registers are valid in these contexts.

ppuusshh rr,, <<nnaammee>> Pushes the contents of the nnaammee register in the current context onto the stack.

ppuusshh uu,, <<nnaammee>> Pushes the contents of the nnaammee register in the user con- text onto the stack.

ppoopp rr,, <<nnaammee>> Pops an element ( vvaalluuee ) from the stack sets the contents of the nnaammee register in the current context to it.

ppoopp uu,, <<nnaammee>> Pops an element ( vvaalluuee ) from the stack sets the contents of the nnaammee register in the user context to it.

Writing to user and current context registers ccss,, eeiipp,, ssss,, eesspp,, ccoonnttrrooll and ddeebbuugg registers is not permitted. Also writing to ggddttrr,, llddttrr,, ttrr,, iiddttrr is not permitted. Regis- ters ffss and ggss are context independent. Processor regis- ters are directly used when ffss and ggss are referenced.

WWAARRNNIINNGG Changing the contents of registers in the probe handlers is dangerous and can cause system crashes and data corruption. Use these features with caution and only when you know exactly what you are doing.

DDaattaa GGrroouupp

ppuusshh <<vvaalluuee>> Pushes vvaalluuee onto the stack.

ppuusshh bb,, <<vvaall>> ppuusshh ww,, <<vvaall>> ppuusshh dd,, <<vvaall>> These instructions have been replaced with the simpler ppuusshh <<vvaalluuee>> instruction in dprobes v3.4.0.

ppuusshh <<ssyymmbbooll>> Allowed only for Kernel Symbols. Pushes the aaddddrreessss of the ssyymmbbooll onto the stack.

ppuusshh mmeemm,, uu88 Pops one element ( aaddddrr ) from the stack and pushes a byte at aaddddrr onto the stack.

ppuusshh mmeemm,, uu1166 Pops one element ( aaddddrr ) from the stack and pushes a 16 bit value at aaddddrr onto the stack.

ppuusshh mmeemm,, uu3322 Pops one element ( aaddddrr ) from the stack and pushes a 32 bit value at aaddddrr onto the stack.

ppuusshh mmeemm,, uu6644 Pops one element ( aaddddrr ) from the stack and pushes a 64 bit value at aaddddrr onto the stack.

ppoopp mmeemm,, uu88 Pops two elements ( vvaall and aaddddrr ) from the stack and stores the least significant byte of vvaall at aaddddrr

ppoopp mmeemm,, uu1166 Pops two elements ( vvaall and aaddddrr ) from the stack and stores the least significant 16bits of vvaall at aaddddrr

ppoopp mmeemm,, uu3322 Pops two elements ( vvaall and aaddddrr ) from the stack and stores vvaall at aaddddrr

ppoopp mmeemm,, uu6644 Pops three elements ( vvaall (64 bit value, two elements) and aaddddrr ) from the stack and stores vvaall at aaddddrr

ppuusshh bbiiff ppuusshh wwiiff ppuusshh ddiiff ppuusshh qqiiff ppoopp bbiiff ppoopp wwiiff ppoopp ddiiff ppoopp qqiiff All these instructions have been renamed in dprobes v3.4.0. So, now the equivalent of ppuusshh bbiiff is ppuusshh mmeemm,, uu88 ppoopp wwiiff is ppoopp mmeemm,, uu1166

All these instructions providing segmented addressing mode have been removed in dprobes v3.4.0.

ppuusshh bbiiss ppuusshh wwiiss ppuusshh ddiiss ppuusshh qqiiss ppoopp bbiiss ppoopp wwiiss ppoopp ddiiss ppoopp qqiiss

All these instructions providing segmented addressing mode have been removed in dprobes v3.4.0.

NNoottee:: The instructions which access memory will generate INVALID_ADDR exception if the memory accessed is invalid or is currently paged out. If these exceptions are masked, the probe handling is terminated.

SSyysstteemm VVaarriiaabbllee GGrroouupp The following instructions can be used to access details of the current process (like the pid) and relevant system data structures.

ppuusshh ppiidd Pushes the pid of the current process onto the stack.

ppuusshh pprroocciidd Pushes the id of the processor, on which the current pro- cess is executing, on to the stack.

ppuusshh ttaasskk Pushes the address of the current task (system variable current) onto the stack.

IIOO GGrroouupp ((IIAA3322))

The following instructions can be used to read and write to IO ports from the probe handlers.

ppuusshh iioo,, uu88 Pops an element ( iiooppoorrtt ) from the stack, reads a byte from iiooppoorrtt and pushes it onto the stack.

ppuusshh iioo,, uu1166 Pops an element ( iiooppoorrtt ) from the stack, reads a 16 bit value from iiooppoorrtt and pushes it onto the stack.

ppuusshh iioo,, uu3322 Pops an element ( iiooppoorrtt ) from the stack, reads a d32 bit value from iiooppoorrtt and pushes it onto the stack.

ppoopp iioo,, uu88 Pops vvaall and iiooppoorrtt from the stack, writes the least significant byte of vvaall to iiooppoorrtt

ppoopp iioo,, uu1166 Pops vvaall and iiooppoorrtt from the stack, writes the least significant 16 bit value of vvaall to iiooppoorrtt

ppoopp iioo,, uu3322 Pops vvaall and iiooppoorrtt from the stack, writes the 32 bit value vvaall to iiooppoorrtt

AAddddrreessss VVeerriiffiiccaattiioonn

The following instructions can be used to verify the validity of an address before actually accessing it. If the given address is valid, a zero will be pushed onto the RPN stack. Otherwise, 1 will be pushed to indicate invalid address. Note that the execution of a probe handler can be terminated if it attempts to access any invalid address.

vvffyyrr Pops an element ( aaddddrr ) from the stack and verifies read access to a byte at aaddddrr

vvffaa This instruction has been renamed to in dprobes v3.4.0.

vvffyyrrww Pops an element ( aaddddrr ) from the stack and verifies read- write access to a byte at aaddddrr

vvssaa This instruction providing segmented addressing mode has been removed from dprobes v3.4.0.

MMiisscceellllaanneeoouuss

sseegg22lliinn Pops two elements ( ooffffsseett and sseelleeccttoorr ) from the stack and converts the segmented address sseelleeccttoorr::ooffffsseett into its equivalent flat address and pushes it onto the stack. This instruction generates SEG_FAULT exception if the selector is invalid (IA32 only)

ccnnvvrrtt ssxxff This instruction has been renamed to sseegg22lliinn in dprobes v3.4.0.

ccnnvvrrtt ssxxdd This instruction has been removed from dprobes v3.4.0.

PPRREEPPRROOCCEESSSSOORR DDIIRREECCTTIIVVEESS The RPN Compiler works in two passes. In the first pass it does all the pre-processing for the conditional and uncon- ditional directives and in the second pass it actually compiles the RPN files. All the conditional directives & macros can be specified in an RPN file in the same way as in CC language. The following types of directives are supported in an RPN file:

##ddeeffiinnee <<variable>> <<value>>

##iinncclluuddee <<RPN filename>>

##iiffddeeff <<some-condn>>

##eellsseeiiff <<other-condn>>

##eennddiiff

SSUUBBSSTTIITTUUTTIIOONN The RRPPNN ccoommppiilleerr allows for substitution of variables from the command line as provided by the GNU C Compiler((ggcccc)).. With the --DD option in the command line, the kkeeyyss to be substituted by vvaalluueess can be specified as follows:

ddpprroobbeess --ii <<rrppnn--ffiillee>> --DD kkeeyy == vvaalluuee where - kkeeyy is the string present in the RPN file and vvaalluuee is the value (string/numeral) to be substituted for key.

RRPPNN EEXXCCEEPPTTIIOONN HHAANNDDLLIINNGG AANNDD SSTTAACCKK TTRRAACCIINNGG Several RPN instructions generate faults during execution. RPN program interpreter throws exceptions when it encoun- ters RPN instruction faults. Interpreter provides infras- tructure/instructions for catching the exceptions, han- dling them, rethrowing the exceptions and propagating them up the call chain.

EExxcceeppttiioonn ccooddee identifies the type of exception. This depends on the type of RPN instruction fault. Width of exception code is equal to the RPN stack width. For IA32 and S/390, exception code is of the form:

+--------------------+--------------------+ | u-field | x-field | +--------------------+--------------------+ |31 16|15 0 |

The u-field is for user use and does not affect the mean- ing of the exception to the interpreter when the exception is re-thrown. For non-user exception the u-field is ini- tialized to zero. The x-field actually defines the excep- tion.

The values indicated by ppaarraammeetteerr 11 and ppaarraammeetteerr 22 depends on the type of exception.

The following table gives a list of exceptions, associated parameter meanings and the type of fault causing the exception.

Exceptions can be selectively masked/unmasked by using the pprroobbee hheeaaddeerr ccoonnttrrooll ssttaatteemmeenntt eexxccpptt__mmaasskk.. Masked excep- tions are not generated. Presently only LOG_OVERFLOW and USER_EX are maskable exceptions. All others are non-mask- able. By default eexxccpptt__mmaasskk is set to 00xx00FFFFFF so that these exceptions are masked. If masked non-maskable excep- tion occurs, probe handling will be terminated. Bits in eexxccpptt__mmaasskk corresponds to the bits in x-field of the exception code. An exception type can be masked by reset- ting it's corresponding bit in eexxccpptt__mmaasskk..

EExxcceeppttiioonn rreellaatteedd iinnssttrruuccttiioonnss

ssxx <<hhaannddlleerr>> // uuxx This instruction pair sets an exception handler for any exceptions generated by the instructions that follow ssxx until the instruction uuxx.. So if any exception is gener- ated by an instruction lying between sx and ux, the con- trol is transferred to the label hhaannddlleerr Note that hhaannddlleerr must be a label local to the current subroutine. If sx is not matched by a ux, the scope of the exception handler ends at the subroutine boundary.

ppuusshh xx Pushes the last exception information (ex code, parm1, parm2) on to exception stack. Note that the interpreter remembers the last exception that was generated. push x either pushes the last generated exception information, if there was any or pushes NULL information(0, 0, 0).

rrxx Raises an exception. Expects to find the exception infor- mation on the RPN stack. This instruction along with push x can be used to re-raise/ throw an exception.

EExxcceeppttiioonn hhaannddlliinngg -- ssoommee rruulleess

1. Exceptions handlers cannot nest. That is if there are nested sx/ux pairs within a subroutine scope, only the innermost one will be effective.

2. A raised(generated) exception remains handled once a handler is called.

3. On raising an exception, the handler is implicitly reset. That is, a handler to catch an exception in a group of instructions will be effective only for the 1st excep- tion generated by the group. The same handler will not be called for subsequent exceptions generated by the group.

4. Exceptions propagate up the call chain until a handler is found. That is if an exception occurs in a sub-routine which has not set any exception handlers, the exception will automatically propagate up to the calling routine. During this, an implicit return is made to the calling routine.

If the exception is not handled anywhere till the outer- most routine, the probe handling is terminated.

5. Program interpreter remembers the last generated excep- tion.

SSTTAACCKK TTRRAACCIINNGG

Interpreter provides a ssttaacckk ttrraaccee bbuuffffeerr to store ssttaacckk ttrraaccee iinnffoorrmmaattiioonn.. Stack trace buffer data is logged along with the dprobes log data using dprobes (major, minor) = (0,0) This data can be used to debug the rpn pro- gram.

The size of the stack trace buffer is governed by a file header control statement eexxccpptt__lloogg.. Default size of eexxccpptt__lloogg is 1024 bytes.

Stack trace information can be filled up in two ways. Implicitly when an exception is generated or explicitly using lloogg sstt instruction.

lloogg sstt This instruction writes ccuurrrreenntt ssttaacckk ttrraaccee iinnffoorrmmaattiioonn into the stack trace buffer.

ppuurrggee sstt This instruction clears (flushes) the stack trace buffer.

aauuttoossttaacckkttrraaccee == |nnoo This is a file header control statement. If set to yyeess stack trace information is col- lected whenever an exception is generated.

SSttaacckk ttrraaccee iinnffoorrmmaattiioonn has the following format header stack trace records(with 3 byte prefix having a token byte 2 and word indi- cating the number num- ber of records)

The hheeaaddeerr consists of name of the module(with 3 byte prefix having a token byte 1 and word indi- cating the length of the string) offset of the probe point id of the probe point major code minor code

SSttaacckk ttrraaccee rreeccoorrddss

Stack trace record contains information about the eexxeeccuu-- ttiioonn ssttaattee of the probe point. It has the following for- mat: last exception code or 0 last exception handler address or -1 last exception parameter 1 or 0 last exception parameter 2 or 0 call stack frame records (with a 3 byte prefix having a token byte of 3 and word indicating the number of records)

The number of call stack frame records depends on the num- ber of calls (nested) made at the time log st is executed (implicitly or explicitly)

FFoorrmmaatt ooff ccaallll ssttaacckk ffrraammee rreeccoorrdd called address return address RPN stack entries pre- fixed with 3 byte prefix lv entries prefixed with 3 byte prefix gv entries prefixed with 3 byte prefix

The 3 byte prefixes associated with RPN stack entries, lv entries and gv entries indicate the number of RPN stack entries, local variables and global variables logged and have token bytes of 4, 5 and 6 respectively.

Prior to the collection of stack trace information, inter- preter needs to be told about the range of RPN stack, lv, and gv entries to be logged as part of stack trace. This is achieved by the following instructions.

ttrraaccee ppvv Pops two elements ( rraannggee and iinnddeexx ). If this call stack frame is logged as part of stack trace, the interpreter logs the RPN stack entries starting from the stack pointer iinnddeexx up to iinnddeexx ++ rraannggee.. to the stack trace buffer.

ttrraaccee llvv Pops two elements ( rraannggee and iinnddeexx ). If this call stack frame is logged as part of stack trace, the interpreter logs the local variables starting from iinnddeexx up to iinnddeexx ++ rraannggee to the stack trace buffer.

ttrraaccee ggvv Pops two elements ( rraannggee and iinnddeexx ). If this call stack frame is logged as part of stack trace, the interpreter logs the global variables starting from iinnddeexx up to iinnddeexx ++ rraannggee to the stack trace buffer.

If the interpreter is not told about the range and index (i.e., if the above instructions are not present in a call scope), it logs 0 number of RPN stack, lv and gv entries, while building the call stack frame record for this call scope. So if any subroutine wants the RPN stack, lv and gv entries to be logged as part of its call stack, it should code the above three instructions.

Interpreter provides SSttaacckk TTrraaccee PPooiinntteerr rreeggiisstteerr which will always point to the stack trace buffer from where the next log starts.

IInnssttrruuccttiioonnss uussiinngg iinntteerrpprreetteerr iinntteerrnnaall rreeggiisstteerrss..

ppuusshh ssttpp Push(save) the value in stack trace pointer register to RPN stack.

ppoopp ssttpp Pop (from the RPN stack) a value to stack trace pointer register.

ppuusshh llpp Push(save) the value in log pointer register to RPN stack.

ppoopp llpp Pop(from the RPN stack) a value to log pointer register.

ppuusshh ppllpp Push the value in previous log pointer register to RPN stack.

ssaavvee ssbbpp Push (save) the value of stack base pointer register to RPN stack.

rreessttoorree ssbbpp Pop (from RPN stack) a value to stack base pointer register.

ssaavvee ttsspp Push (save) the value of top of the stack pointer register to RPN stack.

rreessttoorree ttsspp Pop (from RPN stack) a value to top of the stack pointer register.

ppuusshh ssbbpp Pops an element ( nn ) from RPN stack and pushes the stack element at ssbbpp ++ nn to the top of RPN stack. nn can be neg- ative also.

ppoopp ssbbpp Pops two elements ( vvaalluuee and nn ) from RPN stack and sets the contents of stack element at ssbbpp ++ nn to vvaalluuee.. Note that nn can be negative also.

ccooppyy ssbbpp Pops an element ( nn ) and copies (without popping) the element at RPN TOS to the location pointed by ssbbpp ++ nn in the RPN stack. nn can be negative.

ppuusshh ssbbpp,, nn Pushes the RPN stack element at ssbbpp ++ nn to RPN TOS. nn can be negative.

ppoopp ssbbpp,, nn Pops an element from RPN stack and stores it in the RPN stack at the location pointed by ssbbpp ++ nn.. Here nn can be negative.

ccooppyy ssbbpp,, nn Copies (without popping) the element at RPN TOS to the location pointed by ssbbpp ++ nn in the RPN stack. nn can be negative.

ppuusshh ttsspp Pops an element ( nn ) from RPN stack and pushes the ele- ment at ttsspp ++ nn to TOS. Here ttsspp refers to the value after nn is popped. Here nn can be negative.

ppoopp ttsspp Pops two elements ( vvaalluuee and nn ) from RPN stack and stores the vvaalluuee at the location pointed by ttsspp ++ nn in the RPN stack. Here ttsspp refers to the value after vvaalluuee and nn are popped. Here nn can be negative.

ccooppyy ttsspp Pops and element ( nn ) from RPN stack and copies the ele- ment at TOS (after popping nn ) to the location pointed by ttsspp ++ nn in the RPN stack. Here ttsspp refers to value after nn is popped. Here nn can be negative.

ppuusshh ttsspp,, nn Pushes the RPN stack element at ttsspp ++ nn to RPN TOS. Here ttsspp refers to the stack location before the instruction executes. nn can be negative.

ppoopp ttsspp,, nn Pops a RPN stack element and stores it at location pointed by ttsspp ++ nn in the RPN stack. ttsspp refers to the stack location before the instruction executes. nn can be nega- tive.

ccooppyy ttsspp,, nn Copies (without popping) the RPN stack element at TOS to the location pointed by ttsspp ++ nn in the RPN stack. Here ttsspp refers to the stack location before the instruction is executed. nn can be negative.

SSAAMMPPLLEE RRPPNN FFIILLEESS The ccoommmmeennttss in RPN Language are specified by ////.. The following examples illustrate common usage of the RPN commands:

1) Log EAX and EBX registers:

ppuusshh rr,, eeaaxx ppuusshh uu,, eebbxx lloogg 22 // logs two words from the // top of stack

2) Log the bytes after exchanging the two bytes on the stack:

ppuusshh 00xx0022 ppuusshh 00xxffff xxcchhgg lloogg 22 // logs two bytes after exchanging

3) Operations on a local variable (the vvaarr == keyword should be present in the RPN file header):

ppuusshh 00xxffffffffffffffff ppoopp llvv,, 00xx00000000 // pops the value on top of stack // into local variable iinncc llvv,, 00xx00000000 // increments the local variable // at index 0x0000 ddeecc llvv,, 00xx00000000 // decrements the local variable // at index 0x0000 ppuusshh llvv,, 00xx00000000 // pushes the local variable on // the stack lloogg 11 // logs a dword from the stack

4) Arithmetic operations:

ppuusshh 00xx0022 ppuusshh 00xx0044 aadddd lloogg 11 // logs the result of addition // from top of stack

5) Logs the cpuid data after pushing it on to the stack

ppuusshh 00xx00 ppuusshh rr,, ccppuuiidd lloogg 44 // logs 4 dwords containing the // cpuid

6) Example depicting the use of jumps and calls:

ppuusshh 00xxffff jjnnzz ddoowwnn eexxiitt

ddoowwnn:: ccaallll pprroocc11 eexxiitt

pprroocc pprroocc11 ppuusshh 00xx0011 lloogg 11 rreett eennddpprroocc

CCOOMMPPLLEETTEE EEXXAAMMPPLLEESS OOFF RRPPNN In the following examples ooffffsseett and ooppccooddeess must be veri- fied accordingly before running any of these on a LLiinnuuxx system.

1) This rpn program puts a probe on an user application.

nnaammee == aappppllnn //appln is the module on which //probe is put. mmooddttyyppee == uusseerr //appln is a user application. mmaajjoorr == 11 //major number.

ooffffsseett == mmaaiinn //probe is on function main. ooppccooddee == 00xx5555 //0x55 is the opcode present at offset. mmiinnoorr == 22 //minor number.

ppuusshh uu,, ccss //push user context code segment register. ppuusshh uu,, ddss //push user context data segment register. lloogg 22 //log the two registers. eexxiitt //exit this probe handler.

Whenever the application aappppllnn is executed the probe is hit and the log shows the values of cs and ds.

2) This rpn file puts probe on kernel nnaammee == vvmmlliinnuuxx //kernel probe mmooddttyyppee == kkeerrnneell mmaajjoorr == 22 //major point

ooffffsseett == ddoo__ffoorrkk //probe on do_fork ooppccooddee == 00xx5555 //opcode is 0x55 mmiinnoorr == 11 //minor point

ppuusshh ppiidd //push pid ppuusshh ttaasskk //push the address of the current //task_struct lloogg 22 //log the pid and task_struct eexxiitt Whenever fork occurs, this probe logs the pid and the address of the current task_struct.

2) Putting a probe on the network device driver and log- ging memory and register values.Traces the entry points to the various driver functions and logs the data.

// The module 3c59x (Ethernet module) is loaded at boot // time and for testing the probe, network services are // restarted.

##ddeeffiinnee ffuunncc11 vvoorrtteexx__ooppeenn

nnaammee == ""//lliibb//mmoodduulleess//22..22..1122--2200//nneett//33cc5599xx..oo"" mmooddttyyppee == kkmmoodd mmaajjoorr == 00

ooffffsseett == ffuunncc11 // After preprocessing "func1" is // replaced by "vortex_open" ooppccooddee == 00xx5555 mmiinnoorr == 00

ppuusshh rr,, eeiipp // push the address of the instruction // pointer ppuusshh wwiiff // push the word found at the above address lloogg 11 // log the word ppuusshh rr,, eeaaxx // also log the contents of the eax and ebx // registers ppuusshh rr,, eebbxx lloogg 22

ooffffsseett == vvoorrtteexx__ssttaarrtt__xxmmiitt ooppccooddee == 00xx5555 mmiinnoorr == 11

ppuusshh 00xx1100 ppuusshh rr,, eeiipp lloogg mmrrff // logs 10 bytes from the address pushed. eexxiitt

ooffffsseett == vvoorrtteexx__cclloossee ooppccooddee == 00xx5555 mmiinnoorr == 22 ppuusshh 00xx1100 ppuusshh rr,, eeiipp // logs 10 bytes from the address pushed lloogg mmrrff ##iinncclluuddee ""tteesstt..rrppnn"" // After preprocessing the "test.rpn"

// file is copied in this RPN file. eexxiitt

3) Monitor the number of calls to ddoo__ffoorrkk

nnaammee == vvmmlliinnuuxx mmooddttyyppee == kkeerrnneell mmaajjoorr == 00 jjmmppmmaaxx == 1155 vvaarrss == 33 // Shows that number of variables used in the // probe program is 3 (i.e. index is // from 0 to 2)

ooffffsseett == ddoo__ffoorrkk ooppccooddee == 00xx5555 mmiinnoorr == 00

iinncc llvv,, 00xx0011 // increments the local variable // at index 1 aabboorrtt

4) Dump the system registers whenever sswwaapp__oouutt function is called.

nnaammee == vvmmlliinnuuxx mmooddttyyppee == kkeerrnneell mmaajjoorr == 00 iiggnnoorree == 55 mmaaxxhhiittss == 5500

ooffffsseett == sswwaapp__oouutt ooppccooddee == 00xx5555 mmiinnoorr == 11

ppuusshh rr,, eeaaxx // dump the current registers lloogg 11 ppuusshh rr,, eebbxx lloogg 11 ppuusshh rr,, eeiipp lloogg mmrrff // log memory at the flat address pushed // previously ppuusshh uu,, eeaaxx // dump the user context registers lloogg 11 ppuusshh uu,, eebbxx lloogg 11

5) Putting probe on an interrupt handler "ddoo__ggeenneerraall__pprroo-- tteeccttiioonn" by keeping some maxhits and logging some informa- tion.

nnaammee == vvmmlliinnuuxx mmooddttyyppee == kkeerrnneell mmaajjoorr == 00 vvaarrss == 11 // index of the variable is 0

ooffffsseett == ddoo__ggeenneerraall__pprrootteeccttiioonn ooppccooddee == 00xx5555 mmiinnoorr == 00 mmaaxxhhiittss == 1100 // after getting hit for 10 times // the probe will be disabled ppuusshh rr,, ccrr00 // pushes cr0 on to the stack ppuusshh rr,, ccrr22 // push cr2 ppuusshh rr,, ccrr33 // push cr3 ppuusshh rr,, ccrr44 // push cr4 lloogg 44 // log all control registers. eexxiitt

6) Putting probes on the entry and exit points of some of the most frequently used functions in the kernel like ddoo__ffoorrkk,, kkmmaalllloocc and ddoo__ppaaggee__ffaauulltt.. This example makes use of the ggrroouupp and ttyyppee keywords in the probe program file header and ggrroouuppddeeff and ttyyppeeddeeff keywords in the RPN file header. This probe program can be used to selectively apply probes of same group and same type.

nnaammee == vvmmlliinnuuxx mmooddttyyppee == kkeerrnneell mmaajjoorr == 11 ggrroouuppddeeff == ffiilleessyyss mmeemmoorryy pprroocceessss ffaauullttss // Valid groups ttyyppee == eenntteerr lleeaavvee // Valid types

ooffffsseett == ddoo__ffoorrkk ooppccooddee == 00xx8833 // Entry point of do_fork mmiinnoorr == 00 ggrroouupp == pprroocceessss // probe point group ttyyppee == eenntteerr // probe point type ppuusshh rr,, eesspp ppuusshh rr,, ssss lloogg 22 eexxiitt

ooffffsseett == ddoo__ffoorrkk ++ 11998877 ooppccooddee == 00xxcc33 // Exit point of the do_fork function mmiinnoorr == 11 ggrroouupp == pprroocceessss // probe point group ttyyppee == lleeaavvee // probe point type ppuusshh rr,, eesspp ppuusshh rr,, ssss lloogg 22 eexxiitt

ooffffsseett == kkmmaalllloocc ooppccooddee == 00xx5555 // First instruction in kmalloc(). mmiinnoorr == 22 ggrroouupp == mmeemmoorryy // probe point group ttyyppee == eenntteerr // probe point type mmaaxxhhiittss == 110000 ppuusshh rr,, eesspp ppuusshh rr,, ssss lloogg 22 eexxiitt

ooffffsseett == kkmmaalllloocc ++ 334444 ooppccooddee == 00xxcc33 // Exit point of kmalloc(). mmiinnoorr == 44 ggrroouupp == mmeemmoorryy // probe point group ttyyppee == lleeaavvee mmaaxxhhiittss == 110000 ppuusshh rr,, eesspp ppuusshh rr,, ssss lloogg 22 eexxiitt

ooffffsseett == eexxtt22__ffiillee__wwrriittee ooppccooddee == 00xx8833 // Entry point of ext2_file_write mmiinnoorr == 55 ggrroouupp == ffiilleessyyss // probe point group ttyyppee == eenntteerr // probe point type mmaaxxhhiittss == 110000 ppuusshh rr,, eesspp ppuusshh rr,, ssss lloogg 22 eexxiitt

ooffffsseett == eexxtt22__ffiillee__wwrriittee ++ 11558833 ooppccooddee == 00xxcc33 // Entry point of ext2_file_write mmiinnoorr == 66 ggrroouupp == ffiilleessyyss // probe point group ttyyppee == lleeaavvee // probe point type mmaaxxhhiittss == 110000 ppuusshh rr,, eesspp ppuusshh rr,, ssss lloogg 22 eexxiitt

ooffffsseett == ddoo__ppaaggee__ffaauulltt ooppccooddee == 00xx8833 // Entry point of do_page_fault mmiinnoorr == 77 ggrroouupp == ffaauullttss // probe point group ttyyppee == eenntteerr // probe point type mmaaxxhhiittss == 110000 ppuusshh rr,, eesspp ppuusshh rr,, ssss lloogg 22 eexxiitt

offset = do_page_fault + 813 // Exit point of do_page_fault ooppccooddee == 00xxcc33 mmiinnoorr == 88 ggrroouupp == ffaauullttss // probe point group ttyyppee == lleeaavvee // probe point type mmaaxxhhiittss == 110000 ppuusshh rr,, eesspp ppuusshh rr,, ssss lloogg 22 eexxiitt

The above RPN file can be built and applied in the follow- ing ways: Let us call the RPN file eexxaammppllee..rrppnn

ddpprroobbeess ----bbuuiilldd--ppppddff eexxaammppllee..rrppnn --oo eexxaammppllee..ppppddff Generates ppdf file example.ppdf.

ddpprroobbeess ----aappppllyy--ppppddff eexxaammppllee..ppppddff Applies all the probes present in example.ppdf.

ddpprroobbeess ----aappppllyy--ppppddff eexxaammppllee..ppppddff ----ggrroouupp pprroocceessss

ttyyppee eenntteerr Applies probes belonging to the ggrroouupp process and ttyyppee enter.

ddpprroobbeess ----aappppllyy--ppppddff eexxaammppllee..ppppddff ----ggrroouupp == ffiilleessyyss Applies all probes belonging to the ggrroouupp filesys.

ddpprroobbeess ----aappppllyy--ppppddff eexxaammppllee..ppppddff ----ttyyppee == lleeaavvee Applies all probes belonging to ttyyppee leave.

ddpprroobbeess ----aappppllyy--ppppddff eexxaammppllee..ppppddff ----ggrroouupp pprroocceessss mmeemmoorryy ----ttyyppee lleeaavvee Applies all probes belonging to ggrroouupp process, ttyyppee lleeaavvee aanndd ggrroouupp memory, ttyyppee leave.

7) Illustration of watchpoint probes

a) This examples puts probe on a kernel data symbol and watches it whenever a 4 byte write occurs to it.

nnaammee == vvmmlliinnuuxx mmooddttyyppee == kkeerrnneell

aaddddrreessss == nnrr__ffrreeee__ppaaggeess::nnrr__ffrreeee__ppaaggeess++33 wwaattcchhppooiinntt == ww mmaaxxhhiittss == 110000

ppuusshh nnrr__ffrreeee__ppaaggeess ppuusshh ddiiff lloogg 11 eexxiitt

b) This example shows how to watch a user space address.

nnaammee == vvmmlliinnuuxx mmooddttyyppee == kkeerrnneell // note that modtype is kernel.

aaddddrreessss == 00xx00880044004400cc::00xx00880044004400ff // User data address wwaattcchhppooiinntt == rrww // readwrite type of watchpoint ppuusshh uu,, eeiipp lloogg 11 eexxiitt

AAPPPPEENNDDIIXX AA List of user and current registers for INTEL allowed/not allowed for push and pop operations.

yy -- allowed, nn -- not allowed.

+------+----------+----------+--------+-------+-------+ |IInnddeexx | RReeggiisstteerr | ppuusshh uu | ppuusshh rr | ppoopp uu | ppoopp rr | +------+----------+----------+--------+-------+-------+ |0 | cs | y | y | n | n | |1 | ds | y | y | y | y | |2 | es | y | y | y | y | |3 | fs | y | y | y | y | |4 | gs | y | y | y | y | |5 | ss | y | y | n | n | |6 | eax | y | y | y | y | |7 | ebx | y | y | y | y | |8 | ecx | y | y | y | y | |9 | edx | y | y | y | y | |a | edi | y | y | y | y | |b | esi | y | y | y | y | |c | eflags | y | y | n | n | |d | eip | y | y | n | n | |e | esp | y | y | n | n | |f | ebp | y | y | y | y | |21 | tr | n | y | n | n | |21 | ldtr | n | y | n | n | |22 | gdtr | n | y | n | n | |23 | idtr | n | y | n | n | |24 | cr0 | n | y | n | n | |25 | cr1 | RESERVED | | | | |26 | cr2 | n | y | n | n | |27 | cr3 | n | y | n | n | |28 | cr4 | n | y | n | n | |29 | cr5 | RESERVED | | | | |2a | cr6 | RESERVED | | | | |2b | cr7 | RESERVED | | | | |2c | dr0 | n | y | n | n | |2d | dr1 | n | y | n | n | |2e | dr2 | n | y | n | n | |2f | dr3 | n | y | n | n | |30 | dr4 | RESERVED | | | | |31 | dr5 | RESERVED | | | | |32 | dr6 | n | y | n | n | |33 | dr7 | n | y | n | n | +------+----------+----------+--------+-------+-------+

+------+----------+----------+--------+-------+-------+ |IInnddeexx | RReeggiisstteerr | ppuusshh uu | ppuusshh rr | ppoopp uu | ppoopp rr | +------+----------+----------+--------+-------+-------+ |34 | tr0 | RESERVED | | | | |35 | tr1 | RESERVED | | | | |36 | tr2 | RESERVED | | | | |37 | tr3 | RESERVED | | | | |38 | tr4 | RESERVED | | | | |39 | tr5 | RESERVED | | | | |3a | tr6 | RESERVED | | | | |3b | tr7 | RESERVED | | | | |3c | cpuid | y | y | n | n | |3d | msr | y | y | n | n | |3e | fr0 | y | n | n | n | |3f | fr1 | y | n | n | n | |40 | fr2 | y | n | n | n | |41 | fr3 | y | n | n | n | |42 | fr4 | y | n | n | n | |43 | fr5 | y | n | n | n | |44 | fr6 | y | n | n | n | |45 | fr7 | y | n | n | n | |46 | fcw | y | n | n | n | |47 | fsw | y | n | n | n | |48 | ftw | y | n | n | n | |49 | fip | y | n | n | n | |4a | fcs | y | n | n | n | |4b | fdp | y | n | n | n | |4c | fds | y | n | n | n | |4d | xmm0 | y | n | n | n | |4e | xmm1 | y | n | n | n | |4f | xmm2 | y | n | n | n | |50 | xmm3 | y | n | n | n | |51 | xmm4 | y | n | n | n | |52 | xmm5 | y | n | n | n | |53 | xmm6 | y | n | n | n | |54 | xmm7 | y | n | n | n | |55 | mxcsr | y | n | n | n | +------+----------+----------+--------+-------+-------+

FFllooaattiinngg PPooiinntt RReeggiisstteerrss

fr0 - fr7 Floating point data registers (Each register is 80bit wide, hence occupies 2.5 rpn stack elements)

fcw Control register

fsw Status register

ftw Tag word register

fip Instruction pointer register

fcs Code segment register

fdp Data (operand) pointer register

fds Data segment register

IInnsseerrttiinngg pprroobbeess oonn ffllooaattiinngg ppooiinntt iinnssttrruuccttiioonnss wwhheenn tthhee FFPPUU iiss eemmuullaatteedd iiss nnoott aalllloowweedd.. IIff FFPPUU iiss eemmuullaatteedd,, aacccceessssiinngg FFPPUU rreeggiisstteerrss wwiillll ggiivvee aa ddeeffaauulltt vvaalluuee ooff zzeerroo..

SSttrreeaammiinngg SSIIMMDD EExxtteennssiioonn ((SSSSEE)) RReeggiisstteerrss

xmm0 - xmm7 SSE Floating Point Registers each 128 bits wide, occupying 4 rpn stack elements

mxcsr SSE Floating Point Control/Status Register 32 bits wide

AAPPPPEENNDDIIXX BB List of user and current registers for S/390(32bit) and zSeries(64bit) Lallowed/not allowed for push and pop oper- ations.

yy -- allowed, nn -- not allowed.

+------+-----------+--------+--------+-------+-------+ |IInnddeexx | RReeggiisstteerr | ppuusshh uu | ppuusshh rr | ppoopp uu | ppoopp rr | +------+-----------+--------+--------+-------+-------+ |0x00 | PSWMASK | y | y | n | n | |0x01 | PSWADDR | y | y | n | n | +------+-----------+--------+--------+-------+-------+ |0x10 | GPR0 | y | y | y | y | |0x11 | GPR1 | y | y | y | y | |0x12 | GPR2 | y | y | y | y | |0x13 | GPR3 | y | y | y | y | |0x14 | GPR4 | y | y | y | y | |0x15 | GPR5 | y | y | y | y | |0x16 | GPR6 | y | y | y | y | |0x17 | GPR7 | y | y | y | y | |0x18 | GPR8 | y | y | y | y | |0x19 | GPR9 | y | y | y | y | |0x1a | GPR10 | y | y | y | y | |0x1b | GPR11 | y | y | y | y | |0x1c | GPR12 | y | y | y | y | |0x1d | GPR13 | y | y | y | y | |0x1e | GPR14 | y | y | y | y | |0x1f | GPR15 | y | y | y | y | +------+-----------+--------+--------+-------+-------+ +------+-----------+--------+--------+-------+-------+ |IInnddeexx | RReeggiisstteerr | ppuusshh uu | ppuusshh rr | ppoopp uu | ppoopp rr | +------+-----------+--------+--------+-------+-------+ |0x20 | ACR0 | y | y | n | n | |0x21 | ACR1 | y | y | n | n | |0x22 | ACR2 | y | y | n | n | |0x23 | ACR3 | y | y | n | n | |0x24 | ACR4 | y | y | n | n | |0x25 | ACR5 | y | y | n | n | |0x26 | ACR6 | y | y | n | n | |0x27 | ACR7 | y | y | n | n | |0x28 | ACR8 | y | y | n | n | |0x29 | ACR9 | y | y | n | n | |0x2a | ACR10 | y | y | n | n | |0x2b | ACR11 | y | y | n | n | |0x2c | ACR12 | y | y | n | n | |0x2d | ACR13 | y | y | n | n | |0x2e | ACR14 | y | y | n | n | |0x2f | ACR15 | y | y | n | n | +------+-----------+--------+--------+-------+-------+

+------+-----------+--------+--------+-------+-------+ |IInnddeexx | RReeggiisstteerr | ppuusshh uu | ppuusshh rr | ppoopp uu | ppoopp rr | +------+-----------+--------+--------+-------+-------+ |0x03 | FPC | y | n | n | n | +------+-----------+--------+--------+-------+-------+ |0x30 | FPR0 | y | n | n | n | |0x31 | FPR1 | y | n | n | n | |0x32 | FPR2 | y | n | n | n | |0x33 | FPR3 | y | n | n | n | |0x34 | FPR4 | y | n | n | n | |0x35 | FPR5 | y | n | n | n | |0x36 | FPR6 | y | n | n | n | |0x37 | FPR7 | y | n | n | n | |0x38 | FPR8 | y | n | n | n | |0x39 | FPR9 | y | n | n | n | |0x3a | FPR10 | y | n | n | n | |0x3b | FPR11 | y | n | n | n | |0x3c | FPR12 | y | n | n | n | |0x3d | FPR13 | y | n | n | n | |0x3e | FPR14 | y | n | n | n | |0x3f | FPR15 | y | n | n | n | +------+-----------+--------+--------+-------+-------+ IInnsseerrttiinngg pprroobbeess oonn ffllooaattiinngg ppooiinntt iinnssttrruuccttiioonnss wwhheenn tthhee FFPPUU iiss eemmuullaatteedd iiss nnoott aalllloowweedd.. IIff FFPPUU iiss eemmuullaatteedd,, aacccceessssiinngg FFPPUU rreeggiisstteerrss wwiillll ggiivvee aa ddeeffaauulltt vvaalluuee ooff zzeerroo..

FFPPRR00--1155 FFllooaattiinngg PPooiinntt RReeggiisstteerrss eeaacchh 6644 bbiittss wwiiddee,, ooccccuuppyyiinngg 22 rrppnn ssttaacckk eelleemmeennttss

FFPPCC FFllooaattiinngg PPooiinntt CCoonnttrrooll RReeggiisstteerr 3322 bbiittss wwiiddee +------+-----------+--------+--------+-------+-------+ |IInnddeexx | RReeggiisstteerr | ppuusshh uu | ppuusshh rr | ppoopp uu | ppoopp rr | +------+-----------+--------+--------+-------+-------+ |00xx4400 | CCRR__00 | nn | yy | nn | nn | |00xx4411 | CCRR__11 | nn | yy | nn | nn | |00xx4422 | CCRR__22 | nn | yy | nn | nn | |00xx4433 | CCRR__33 | nn | yy | nn | nn | |00xx4444 | CCRR__44 | nn | yy | nn | nn | |00xx4455 | CCRR__55 | nn | yy | nn | nn | |00xx4466 | CCRR__66 | nn | yy | nn | nn | |00xx4477 | CCRR__77 | nn | yy | nn | nn | |00xx4488 | CCRR__88 | nn | yy | nn | nn | |00xx4499 | CCRR__99 | nn | yy | nn | nn | |00xx44aa | CCRR__1100 | nn | yy | nn | nn | |00xx44bb | CCRR__1111 | nn | yy | nn | nn | |00xx44cc | CCRR__1122 | nn | yy | nn | nn | |00xx44dd | CCRR__1133 | nn | yy | nn | nn | |00xx44ee | CCRR__1144 | nn | yy | nn | nn | |00xx44ff | CCRR__1155 | nn | yy | nn | nn | +------+-----------+--------+--------+-------+-------+

AAPPPPEENNDDIIXX CC List of user and current registers for ppc and ppc64 allowed/not allowed for push and pop operations.

yy -- allowed, nn -- not allowed.

+------+-----------+--------+--------+-------+-------+ |IInnddeexx | RReeggiisstteerr | ppuusshh uu | ppuusshh rr | ppoopp uu | ppoopp rr | +------+-----------+--------+--------+-------+-------+ |0x01 | NIP | y | y | n | n | |0x02 | MSR | y | y | n | n | |0x03 | CTR | y | y | n | n | |0x04 | LNK | y | y | n | n | |0x05 | XER | y | y | n | n | |0x06 | CCR | y | y | n | n | |0x07 | MQ | y | y | n | n | |0x08 | DAR | y | y | n | n | |0x09 | DSISR | y | y | n | n | |0x0A | FPC | y | y | n | n | |0x0B | CPUID | y | y | n | n | |0x10 | R0 | y | y | y | y | |0x11 | R1 | y | y | y | y | |0x12 | R2 | y | y | y | y | | | ... | | | | | |0x2f | R31 | y | y | y | y | |0x30 | FPR0 | y | n | n | n | |0x31 | FPR1 | y | n | n | n | |0x32 | FPR2 | y | n | n | n | | | ... | | | | | |0x4f | FPR31 | y | n | n | n | +------+-----------+--------+--------+-------+-------+

AAPPPPEENNDDIIXX DD Some methods to get the opcode present at any offset.

For any user executable, oobbjjdduummpp with --DD option can be used to obtain the complete disassembly of the executable. Disassembled code can then be used to obtain the opcode.

For example, the disassembled section of the function main of a user application looks like this:

080483d0 <main>: 80483d0: 55 pushl %ebp 80483d1: 89 e5 movl %esp,%ebp 80483d3: 83 ec 0c subl $0xc,%esp . . .

If probe has to be put on mmaaiinn then ooppccooddee is 00xx5555..

For S/390 code the method is the same, but the object code looks a bit different:

004007ac <main>: 4007ac: 90 af f0 28 stm %r10,%r15,40(%r15) 4007b0: a7 d5 00 0a bras %r13,4007c4 <main+0x18> . . .

If probe has to be put on mmaaiinn then the ooppccooddee for the probe definition is 00xx9900aaff (S/390 has to use two byte opcodes in the probe point definition).

The above method can also be used for kernel probes by disassembling and obtaining the opcode from vvmmlliinnuuxx.. AApppplliiccaattiioonn ddeebbuuggggeerrss or KKeerrnneell ddeebbuuggggeerrss can also be used for the purpose.

AAUUTTHHOORR IIBBMM CCoorrppoorraattiioonn

VVEERRSSIIOONN DProbes version: 3.6.4 man pages last modified on: 27 May 2002

LLIICCEENNSSEE Dynamic Probes is licensed under GNU General Public License version 2 or later.

Copyright (c) International Business Machines Corp., 2000

Dynamic Probes Language DPROBES.LANG(8)

8:dprobes.lang

From Linux Man Pages

<<nn>> must appear first. ooppccooddee

Views

Personal tools

Navigation

Search

Toolbox