├── specification ├── oneliner.pdf ├── oneliner.graffle ├── toplevelarch.pdf ├── dtrace-lifecycle.pdf ├── toplevelarch.graffle ├── ctf-stable-format.pdf ├── dof-stable-format.pdf ├── ctf-stable-format.graffle ├── dof-stable-format.graffle ├── vars │ ├── auto │ │ ├── id.el │ │ ├── args.el │ │ ├── cpu.el │ │ ├── epid.el │ │ ├── gid.el │ │ ├── pid.el │ │ ├── tid.el │ │ ├── uid.el │ │ ├── arg09.el │ │ ├── errno.el │ │ ├── uregs.el │ │ ├── caller.el │ │ ├── ucaller.el │ │ ├── vcycles.el │ │ ├── cpucycles.el │ │ ├── cpuinstrs.el │ │ ├── curthread.el │ │ ├── execname.el │ │ ├── stackdepth.el │ │ ├── vtimestamp.el │ │ ├── dispatchaddr.el │ │ └── machtimestamp.el │ ├── tid.tex │ ├── uregs.tex │ ├── vcycles.tex │ ├── vinstrs.tex │ ├── probe.tex │ ├── dispatchaddr.tex │ ├── gid.tex │ ├── cpucycles.tex │ ├── cpuinstrs.tex │ ├── uid.tex │ ├── execname.tex │ ├── ipl.tex │ ├── vtimestamp.tex │ ├── walltimestamp.tex │ ├── id.tex │ ├── machtimestamp.tex │ ├── epid.tex │ ├── stackdepth.tex │ ├── ustackdepth.tex │ ├── ucaller.tex │ ├── pid.tex │ ├── errno.tex │ ├── ppid.tex │ ├── curthread.tex │ ├── cpu.tex │ ├── caller.tex │ ├── arg09.tex │ └── args.tex ├── dtrace-lifecycle.graffle │ ├── data.plist │ └── image1.png ├── subr │ ├── uuidstr.tex │ ├── random.tex │ ├── inet_ntoa.tex │ ├── inet_ntoa6.tex │ ├── ntohl.tex │ ├── progenyof.tex │ ├── strtoll.tex │ ├── getf.tex │ ├── rand.tex │ ├── lltostr.tex │ ├── mutex_owner.tex │ ├── speculation.tex │ ├── htonll.tex │ ├── htons.tex │ ├── copyout.tex │ ├── ntohs.tex │ ├── mutex_owned.tex │ ├── cleanpath.tex │ ├── dirname.tex │ ├── getminor.tex │ ├── htonl.tex │ ├── ntohll.tex │ ├── copyin.tex │ ├── copyinstr.tex │ ├── getmajor.tex │ ├── copyinto.tex │ ├── copyoutstr.tex │ ├── mutex_type_adaptive.tex │ ├── rw_read_held.tex │ ├── rw_write_held.tex │ ├── rw_iswriter.tex │ ├── mutex_type_spin.tex │ ├── alloca.tex │ ├── index.tex │ ├── ddi_pathname.tex │ ├── inet_ntop.tex │ ├── msgsize.tex │ ├── msgdsize.tex │ ├── json.tex │ ├── basename.tex │ ├── strlen.tex │ ├── rindex.tex │ ├── sx_shared_held.tex │ ├── copyoutmbuf.tex │ ├── sx_exclusive_held.tex │ ├── memstr.tex │ ├── sx_isexclusive.tex │ ├── strchr.tex │ ├── strrchr.tex │ ├── memref.tex │ ├── strtok.tex │ ├── toupper.tex │ ├── strstr.tex │ ├── tolower.tex │ ├── substr.tex │ ├── strjoin.tex │ └── bcopy.tex ├── chap-opendtrace-providers.tex ├── chap-opendtrace-api-boundries.tex ├── instr │ ├── ldta.tex │ ├── ldls.tex │ ├── stls.tex │ ├── nop.tex │ ├── stgaa.tex │ ├── sttaa.tex │ ├── flushts.tex │ ├── xlate.tex │ ├── xlarg.tex │ ├── ldgaa.tex │ ├── setx.tex │ ├── ldtaa.tex │ ├── sets.tex │ ├── call.tex │ ├── popts.tex │ ├── ldts.tex │ ├── stts.tex │ ├── ret.tex │ ├── ba.tex │ ├── pushtv.tex │ ├── mov.tex │ ├── be.tex │ ├── bg.tex │ ├── bne.tex │ ├── not.tex │ ├── add.tex │ ├── or.tex │ ├── and.tex │ ├── bgu.tex │ ├── mul.tex │ ├── bl.tex │ ├── stb.tex │ ├── udiv.tex │ ├── sub.tex │ ├── xor.tex │ ├── blu.tex │ ├── sll.tex │ ├── sth.tex │ ├── stw.tex │ ├── stx.tex │ ├── copys.tex │ ├── urem.tex │ ├── bge.tex │ ├── ble.tex │ ├── bleu.tex │ ├── ldga.tex │ ├── bgeu.tex │ ├── pushtr.tex │ ├── tst.tex │ ├── sra.tex │ ├── rldx.tex │ ├── rldsb.tex │ ├── rldsh.tex │ ├── rldsw.tex │ ├── rldub.tex │ ├── rlduh.tex │ ├── rlduw.tex │ ├── srl.tex │ ├── allocs.tex │ ├── sdiv.tex │ ├── uldub.tex │ ├── ulduh.tex │ ├── ulduw.tex │ ├── uldx.tex │ ├── uldsb.tex │ ├── uldsh.tex │ ├── uldsw.tex │ ├── cmp.tex │ ├── ldub.tex │ ├── ldx.tex │ ├── lduh.tex │ ├── lduw.tex │ ├── scmp.tex │ ├── ldsb.tex │ ├── ldsh.tex │ ├── ldsw.tex │ ├── srem.tex │ ├── ldgs.tex │ └── stgs.tex ├── chap-opendtrace-global-vars.tex ├── acknowledgments.tex ├── abstract.tex ├── chap-opendtrace-code.tex ├── opendtrace-specification.tex ├── preamble.tex ├── Makefile └── chap-opendtrace-object-format.tex ├── README.md ├── LICENSE ├── .gitignore └── cheatsheet.tex /specification/oneliner.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/opendtrace/documentation/HEAD/specification/oneliner.pdf -------------------------------------------------------------------------------- /specification/oneliner.graffle: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/opendtrace/documentation/HEAD/specification/oneliner.graffle -------------------------------------------------------------------------------- /specification/toplevelarch.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/opendtrace/documentation/HEAD/specification/toplevelarch.pdf -------------------------------------------------------------------------------- /specification/dtrace-lifecycle.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/opendtrace/documentation/HEAD/specification/dtrace-lifecycle.pdf -------------------------------------------------------------------------------- /specification/toplevelarch.graffle: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/opendtrace/documentation/HEAD/specification/toplevelarch.graffle -------------------------------------------------------------------------------- /specification/ctf-stable-format.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/opendtrace/documentation/HEAD/specification/ctf-stable-format.pdf -------------------------------------------------------------------------------- /specification/dof-stable-format.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/opendtrace/documentation/HEAD/specification/dof-stable-format.pdf -------------------------------------------------------------------------------- /specification/ctf-stable-format.graffle: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/opendtrace/documentation/HEAD/specification/ctf-stable-format.graffle -------------------------------------------------------------------------------- /specification/dof-stable-format.graffle: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/opendtrace/documentation/HEAD/specification/dof-stable-format.graffle -------------------------------------------------------------------------------- /specification/vars/auto/id.el: -------------------------------------------------------------------------------- 1 | (TeX-add-style-hook 2 | "id" 3 | (lambda () 4 | (LaTeX-add-labels 5 | "vars:id")) 6 | :latex) 7 | 8 | -------------------------------------------------------------------------------- /specification/vars/auto/args.el: -------------------------------------------------------------------------------- 1 | (TeX-add-style-hook 2 | "args" 3 | (lambda () 4 | (LaTeX-add-labels 5 | "vars:args")) 6 | :latex) 7 | 8 | -------------------------------------------------------------------------------- /specification/vars/auto/cpu.el: -------------------------------------------------------------------------------- 1 | (TeX-add-style-hook 2 | "cpu" 3 | (lambda () 4 | (LaTeX-add-labels 5 | "vars:cpu")) 6 | :latex) 7 | 8 | -------------------------------------------------------------------------------- /specification/vars/auto/epid.el: -------------------------------------------------------------------------------- 1 | (TeX-add-style-hook 2 | "epid" 3 | (lambda () 4 | (LaTeX-add-labels 5 | "vars:epid")) 6 | :latex) 7 | 8 | -------------------------------------------------------------------------------- /specification/vars/auto/gid.el: -------------------------------------------------------------------------------- 1 | (TeX-add-style-hook 2 | "gid" 3 | (lambda () 4 | (LaTeX-add-labels 5 | "vars:gid")) 6 | :latex) 7 | 8 | -------------------------------------------------------------------------------- /specification/vars/auto/pid.el: -------------------------------------------------------------------------------- 1 | (TeX-add-style-hook 2 | "pid" 3 | (lambda () 4 | (LaTeX-add-labels 5 | "vars:pid")) 6 | :latex) 7 | 8 | -------------------------------------------------------------------------------- /specification/vars/auto/tid.el: -------------------------------------------------------------------------------- 1 | (TeX-add-style-hook 2 | "tid" 3 | (lambda () 4 | (LaTeX-add-labels 5 | "vars:tid")) 6 | :latex) 7 | 8 | -------------------------------------------------------------------------------- /specification/vars/auto/uid.el: -------------------------------------------------------------------------------- 1 | (TeX-add-style-hook 2 | "uid" 3 | (lambda () 4 | (LaTeX-add-labels 5 | "vars:uid")) 6 | :latex) 7 | 8 | -------------------------------------------------------------------------------- /specification/vars/auto/arg09.el: -------------------------------------------------------------------------------- 1 | (TeX-add-style-hook 2 | "arg09" 3 | (lambda () 4 | (LaTeX-add-labels 5 | "vars:arg09")) 6 | :latex) 7 | 8 | -------------------------------------------------------------------------------- /specification/vars/auto/errno.el: -------------------------------------------------------------------------------- 1 | (TeX-add-style-hook 2 | "errno" 3 | (lambda () 4 | (LaTeX-add-labels 5 | "vars:errno")) 6 | :latex) 7 | 8 | -------------------------------------------------------------------------------- /specification/vars/auto/uregs.el: -------------------------------------------------------------------------------- 1 | (TeX-add-style-hook 2 | "uregs" 3 | (lambda () 4 | (LaTeX-add-labels 5 | "vars:uregs")) 6 | :latex) 7 | 8 | -------------------------------------------------------------------------------- /specification/dtrace-lifecycle.graffle/data.plist: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/opendtrace/documentation/HEAD/specification/dtrace-lifecycle.graffle/data.plist -------------------------------------------------------------------------------- /specification/dtrace-lifecycle.graffle/image1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/opendtrace/documentation/HEAD/specification/dtrace-lifecycle.graffle/image1.png -------------------------------------------------------------------------------- /specification/vars/auto/caller.el: -------------------------------------------------------------------------------- 1 | (TeX-add-style-hook 2 | "caller" 3 | (lambda () 4 | (LaTeX-add-labels 5 | "vars:caller")) 6 | :latex) 7 | 8 | -------------------------------------------------------------------------------- /specification/vars/auto/ucaller.el: -------------------------------------------------------------------------------- 1 | (TeX-add-style-hook 2 | "ucaller" 3 | (lambda () 4 | (LaTeX-add-labels 5 | "vars:ucaller")) 6 | :latex) 7 | 8 | -------------------------------------------------------------------------------- /specification/vars/auto/vcycles.el: -------------------------------------------------------------------------------- 1 | (TeX-add-style-hook 2 | "vcycles" 3 | (lambda () 4 | (LaTeX-add-labels 5 | "vars:vcycles")) 6 | :latex) 7 | 8 | -------------------------------------------------------------------------------- /specification/vars/auto/cpucycles.el: -------------------------------------------------------------------------------- 1 | (TeX-add-style-hook 2 | "cpucycles" 3 | (lambda () 4 | (LaTeX-add-labels 5 | "vars:cpucycles")) 6 | :latex) 7 | 8 | -------------------------------------------------------------------------------- /specification/vars/auto/cpuinstrs.el: -------------------------------------------------------------------------------- 1 | (TeX-add-style-hook 2 | "cpuinstrs" 3 | (lambda () 4 | (LaTeX-add-labels 5 | "vars:cpuinstrs")) 6 | :latex) 7 | 8 | -------------------------------------------------------------------------------- /specification/vars/auto/curthread.el: -------------------------------------------------------------------------------- 1 | (TeX-add-style-hook 2 | "curthread" 3 | (lambda () 4 | (LaTeX-add-labels 5 | "vars:curthread")) 6 | :latex) 7 | 8 | -------------------------------------------------------------------------------- /specification/vars/auto/execname.el: -------------------------------------------------------------------------------- 1 | (TeX-add-style-hook 2 | "execname" 3 | (lambda () 4 | (LaTeX-add-labels 5 | "vars:execname")) 6 | :latex) 7 | 8 | -------------------------------------------------------------------------------- /specification/vars/auto/stackdepth.el: -------------------------------------------------------------------------------- 1 | (TeX-add-style-hook 2 | "stackdepth" 3 | (lambda () 4 | (LaTeX-add-labels 5 | "vars:stackdepth")) 6 | :latex) 7 | 8 | -------------------------------------------------------------------------------- /specification/vars/auto/vtimestamp.el: -------------------------------------------------------------------------------- 1 | (TeX-add-style-hook 2 | "vtimestamp" 3 | (lambda () 4 | (LaTeX-add-labels 5 | "vars:vtimestamp")) 6 | :latex) 7 | 8 | -------------------------------------------------------------------------------- /specification/vars/auto/dispatchaddr.el: -------------------------------------------------------------------------------- 1 | (TeX-add-style-hook 2 | "dispatchaddr" 3 | (lambda () 4 | (LaTeX-add-labels 5 | "vars:dispatchaddr")) 6 | :latex) 7 | 8 | -------------------------------------------------------------------------------- /specification/vars/auto/machtimestamp.el: -------------------------------------------------------------------------------- 1 | (TeX-add-style-hook 2 | "machtimestamp" 3 | (lambda () 4 | (LaTeX-add-labels 5 | "vars:machtimestamp")) 6 | :latex) 7 | 8 | -------------------------------------------------------------------------------- /specification/vars/tid.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{tid} 4 | \label{vars:tid} 5 | \subsection*{tid: thread ID} 6 | 7 | \subsubsection*{Description} 8 | 9 | The \verb|tid| contains the ID of the kernel thread being traced by 10 | the currently executing probe. 11 | 12 | -------------------------------------------------------------------------------- /specification/vars/uregs.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{uregs} 4 | \label{vars:uregs} 5 | \subsection*{uregs: user process registers} 6 | 7 | \subsubsection*{Description} 8 | 9 | The \verb|uregs[]| array contains the current threads user space 10 | register data. 11 | 12 | -------------------------------------------------------------------------------- /specification/vars/vcycles.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{vcycles} 4 | \label{vars:vcycles} 5 | \subsection*{vcycles: } 6 | 7 | \subsubsection*{Description} 8 | 9 | The \verb|vcycles| variable is \emph{only} available on Darwin kernels 10 | at the time of this writing. 11 | 12 | -------------------------------------------------------------------------------- /specification/vars/vinstrs.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{vinstr} 4 | \label{vars:vinstr} 5 | \subsection*{vinstr: } 6 | 7 | \subsubsection*{Description} 8 | 9 | The \verb|vinstr| variable is \emph{only} available on Darwin kernels 10 | at the time of this writing. 11 | 12 | -------------------------------------------------------------------------------- /specification/vars/probe.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{XOR} 4 | \label{varsprobe} 5 | \subsection*{probe: the name of the probe currently firing} 6 | 7 | \subsubsection*{Description} 8 | 9 | The \verb|probe| variable contains the string name of the probe 10 | currently firing. 11 | 12 | -------------------------------------------------------------------------------- /specification/vars/dispatchaddr.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{distpatchaddr} 4 | \label{vars:dispatchaddr} 5 | \subsection*{dispatchaddr:} 6 | 7 | \subsubsection*{Description} 8 | 9 | The \verb|dispatchaddr| variable is \emph{only} available on Darwin kernels 10 | at the time of this writing. 11 | 12 | -------------------------------------------------------------------------------- /specification/vars/gid.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{gid} 4 | \label{vars:gid} 5 | \subsection*{gid: group ID of the current process} 6 | 7 | \subsubsection*{Description} 8 | 9 | The \verb|gid| variable contains the group ID of the process being 10 | traced by the currently executing probe. 11 | 12 | 13 | -------------------------------------------------------------------------------- /specification/vars/cpucycles.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{cpucycles} 4 | \label{vars:cpucycles} 5 | \subsection*{cpucycles: number of cycles elapsed on current CPU core} 6 | 7 | \subsubsection*{Description} 8 | 9 | \emph{NOTE:} The \verb|cpucycles| variable is only available on Darwin 10 | kernels. 11 | 12 | -------------------------------------------------------------------------------- /specification/vars/cpuinstrs.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{cpuinstrs} 4 | \label{vars:cpuinstrs} 5 | \subsection*{cpuinstrs: number of instructions elapsed on current CPU core} 6 | 7 | \subsubsection*{Description} 8 | 9 | \emph{NOTE:} The \verb|cpuinstrs| variable is only available on Darwin 10 | kernels. 11 | 12 | -------------------------------------------------------------------------------- /specification/vars/uid.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{uid} 4 | \label{vars:uid} 5 | \subsection*{uid: user ID} 6 | 7 | \subsubsection*{Description} 8 | 9 | The \verb|uid| variable contains the numeric ID of the user which is 10 | the owner of the process being traced by the currently executing probe. 11 | 12 | 13 | -------------------------------------------------------------------------------- /specification/vars/execname.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{execname} 4 | \label{vars:execname} 5 | \subsection*{execname: name of the currently executing process} 6 | 7 | \subsubsection*{Description} 8 | 9 | The \verb|execname| variable contains a string that is the name of the 10 | currently executing process. 11 | 12 | 13 | -------------------------------------------------------------------------------- /specification/vars/ipl.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{ipl} 4 | \label{vars:ipl} 5 | \subsection*{ipl: interrupt level} 6 | 7 | \subsubsection*{Description} 8 | 9 | \emph{NOTE:} Thh \verb|ipl| variable is only available on Darwin 10 | kernels. 11 | 12 | The \verb|ipl| variable contains the current interrupt level. 13 | 14 | -------------------------------------------------------------------------------- /specification/vars/vtimestamp.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{timestamp} 4 | \label{vars:vtimestamp} 5 | \subsection*{vtimestamp: timestamp in nanosecconds} 6 | 7 | \subsubsection*{Description} 8 | 9 | The \verb|vtimestamp| variable contains the number of nanoseconds 10 | that the current thread has spent running on any core. 11 | 12 | -------------------------------------------------------------------------------- /specification/vars/walltimestamp.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{walltimestamp} 4 | \label{vars:walltimestamp} 5 | \subsection*{walltimestamp: human readable timestamp} 6 | 7 | \subsubsection*{Description} 8 | 9 | The \verb|walltimestamp| contains a string describing the current time 10 | as it would be seen by a human operator. 11 | 12 | -------------------------------------------------------------------------------- /specification/vars/id.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{id} 4 | \label{vars:id} 5 | \subsection*{id: id of the current probe} 6 | 7 | \subsubsection*{Description} 8 | 9 | The \verb|id| variable contains the numeric id of the currently 10 | executing probe. 11 | 12 | \subsubsection*{Failure modes} 13 | 14 | The \verb|id| variable is always valid. 15 | -------------------------------------------------------------------------------- /specification/vars/machtimestamp.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{machtimestamp} 4 | \label{vars:machtimestamp} 5 | \subsection*{machtimestamp: current mach\_absolute\_time value} 6 | 7 | \subsubsection*{Description} 8 | 9 | \emph{NOTE:}The \verb|machtimestamp| variable is \emph{only} available 10 | on Darwin kernels at the time of this writing. 11 | 12 | -------------------------------------------------------------------------------- /specification/vars/epid.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{epid} 4 | \label{vars:epid} 5 | \subsection*{epid: } 6 | 7 | \subsubsection*{Description} 8 | 9 | The \verb|epid| variable contains the integer value of the effective 10 | probe ID. Each probe enabled during tracing is assigned an effecitve 11 | probe ID starting from 1 and increasing monotonically. 12 | 13 | 14 | -------------------------------------------------------------------------------- /specification/vars/stackdepth.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{stackdepth} 4 | \label{vars:stackdepth} 5 | \subsection*{stackdepth: depth of the kernel stack} 6 | 7 | \subsubsection*{Description} 8 | 9 | The \verb|stackdepth| variable contains the integer depth of the 10 | kernel stack for the thread which is being traced by the currently 11 | executing probe. 12 | 13 | -------------------------------------------------------------------------------- /specification/vars/ustackdepth.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{ustackdepth} 4 | \label{vars:ustackdepth} 5 | \subsection*{ustackdepth: depth of the user stack} 6 | 7 | \subsubsection*{Description} 8 | 9 | The \verb|ustackdepth| variable contains the integer depth of the user 10 | proces stack for the thread which is being traced by the currently 11 | executing probe. 12 | 13 | -------------------------------------------------------------------------------- /specification/vars/ucaller.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{ucaller} 4 | \label{vars:ucaller} 5 | \subsection*{ucaller: user space address} 6 | 7 | \subsubsection*{Description} 8 | 9 | The \verb|ucaller| variable contains the user space address of the 10 | function that caused the currently executing probe point to fire. If 11 | the probe was called from the kernel then this value is 0. 12 | 13 | -------------------------------------------------------------------------------- /specification/vars/pid.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{pid} 4 | \label{vars:pid} 5 | \subsection*{pid: process ID} 6 | 7 | \subsubsection*{Description} 8 | 9 | The \verb|pid| variable contains the process ID of the process which 10 | is being traced by the currently executing probe. A process ID of 11 | zero (0) indicates that the currently running process is the operating 12 | system kernel. 13 | 14 | -------------------------------------------------------------------------------- /specification/vars/errno.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{errno} 4 | \label{vars:errno} 5 | \subsection*{errno: error number} 6 | 7 | \subsubsection*{Description} 8 | 9 | The \verb|errno| variable contains the numeric value of the error 10 | number returned by the most recent system call in the program that is 11 | executing when the probe fires. The program may be the kernel or a 12 | user space program. 13 | 14 | 15 | -------------------------------------------------------------------------------- /specification/vars/ppid.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{ppid} 4 | \label{vars:ppid} 5 | \subsection*{ppid: parent process ID} 6 | 7 | \subsubsection*{Description} 8 | 9 | The \verb|ppid| variable contains the process ID of the parent process 10 | to the one which is being traced by the currently executing probe. A 11 | parent process ID of zero (0) indicates that the parent of the 12 | currently running process is the operating system kernel. 13 | 14 | -------------------------------------------------------------------------------- /specification/vars/curthread.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{cuthread} 4 | \label{vars:curthread} 5 | \subsection*{curthread: pointer to the thread structure for the 6 | current probe} 7 | 8 | \subsubsection*{Description} 9 | 10 | The \verb|curthread| variable points to the kernel's structure that 11 | describes the thread which triggered the currently running probe. 12 | 13 | \subsubsection*{Failure modes} 14 | 15 | The \verb|curthread| variable is always valid. 16 | -------------------------------------------------------------------------------- /specification/vars/cpu.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{cpu} 4 | \label{vars:cpu} 5 | \subsection*{cpu: The CPU core on which the probe is executing} 6 | 7 | \subsubsection*{Description} 8 | 9 | The \verb|cpu| variable contains an integer value indicating the CPU 10 | core, on which the probe is executing. CPU cores are numbered from 0 11 | through the maximum present in the system. 12 | 13 | \subsubsection*{Failure modes} 14 | 15 | The \verb|cpu| variable always contains a valid value. 16 | -------------------------------------------------------------------------------- /specification/vars/caller.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{caller} 4 | \label{vars:caller} 5 | \subsection*{caller: kernel address of the instruction that called 6 | this probe} 7 | 8 | \subsubsection*{Description} 9 | 10 | The \verb|caller| variable contains the kernel address of the 11 | instruction that caused the currently executing probe to fire. 12 | 13 | \subsubsection*{Failure modes} 14 | 15 | No known failure modes, \verb|caller| always contains a valid address, 16 | even when probes fire in user space. 17 | -------------------------------------------------------------------------------- /specification/vars/arg09.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{arg09} 4 | \label{vars:arg09} 5 | \subsection*{arg0-9: arguments to the current probe} 6 | 7 | \subsubsection*{Description} 8 | 9 | The variables arg0 through arg9 contain the arguments to the currently 10 | executing probe point. 11 | 12 | \subsubsection*{Failure modes} 13 | 14 | Incorrectly dereferencing the probe arguments will result in a run 15 | time error in a D program. The program will not exit, but an error 16 | will be output on the user's terminal 17 | -------------------------------------------------------------------------------- /specification/subr/uuidstr.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{uuidstr} 4 | \label{subr:uuidstr} 5 | \subsection*{uuidstr: convert a UUID to a string} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] string representation of a UUID 11 | \item[\registerop{arg0}] UUID to be converted 12 | \end{description} 13 | 14 | \subsubsection*{Description} 15 | 16 | The \subroutine{uuidstr} subroutine converts a numeric UUID into a string. 17 | 18 | \subsubsection*{Failure modes} 19 | 20 | This subroutine has no run-time failure modes beyond its constraints. 21 | -------------------------------------------------------------------------------- /specification/subr/random.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{random} 4 | \label{subr:random} 5 | \subsection*{random: return a better pseudo-random number than rand()} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] A pseudo-random number 11 | \end{description} 12 | 13 | \subsubsection*{Description} 14 | 15 | The \subroutine{random} subroutine returns a better pseudo-random 16 | number than the originala \subroutine{rand} subroutine provided by DTrace. 17 | 18 | \subsubsection*{Failure modes} 19 | 20 | This subroutine has no run-time failure modes beyond its constraints. 21 | -------------------------------------------------------------------------------- /specification/chap-opendtrace-providers.tex: -------------------------------------------------------------------------------- 1 | A significant portion of the user facing functionality of OpenDTrace 2 | is presented via a set of \emph{providers} which expose probe points 3 | and data structures that are specific to a particular type of 4 | code or subsystem. This appendix lists the currently existing set of 5 | providers along with the rules they use for exposing data to the user. 6 | Providers that are stable, which is to say they do not change after 7 | each recompilation of the code, we list and describe the probe points 8 | and their arguments. 9 | 10 | %%% Local Variables: 11 | %%% mode: latex 12 | %%% TeX-master: "dtrace-specification" 13 | %%% End: 14 | -------------------------------------------------------------------------------- /specification/vars/args.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{args} 4 | \label{vars:args} 5 | \subsection*{args[]: array of arguments to the current probe} 6 | 7 | \subsubsection*{Description} 8 | 9 | The \verb|args[]| array contains typed versions of all the arguments 10 | to the currently executing probe. When a probe has a pointer to a 11 | stucture as an argument it must be accessed via the \verb|args[]| 12 | array. 13 | 14 | \subsubsection*{Failure modes} 15 | 16 | Incorrectly dereferencing the probe arguments will result in a run 17 | time error in a D program. The program will not exit, but an error 18 | will be output on the user's terminal 19 | -------------------------------------------------------------------------------- /specification/subr/inet_ntoa.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{inet-ntoa} 4 | \label{subr:inet-ntoa} 5 | \subsection*{inet\_ntoa: convert a 32 bit IPv4 address to a string} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] IPv4 address as a string 11 | \item[\registerop{arg0}] IPv4 address as structure 12 | \end{description} 13 | 14 | \subsubsection*{Description} 15 | 16 | The \subroutine{inet_ntoa} subroutine takes a 32 bit, IPv4, address 17 | and converts it to a string suitable for humans. 18 | 19 | \subsubsection*{Failure modes} 20 | 21 | This subroutine has no run-time failure modes beyond its constraints. 22 | -------------------------------------------------------------------------------- /specification/subr/inet_ntoa6.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{inet-ntoa6} 4 | \label{subr:inet-ntoa6} 5 | \subsection*{inet\_ntoa6: convert a 128 bit IPv6 address to a string} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] IPv6 address as a string 11 | \item[\registerop{arg0}] IPv6 address as a structure 12 | \end{description} 13 | 14 | \subsubsection*{Description} 15 | 16 | The \subroutine{inet_ntoa6} subroutine takes a 128 bit, IPv6, address 17 | and converts it to a string suitable for humans. 18 | 19 | \subsubsection*{Failure modes} 20 | 21 | This subroutine has no run-time failure modes beyond its constraints. 22 | -------------------------------------------------------------------------------- /specification/subr/ntohl.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{ntohl} 4 | \label{subr:ntohl} 5 | \subsection*{ntohl: convert long (32 bit) value from network to host 6 | byte order} 7 | 8 | \subsubsection*{Calling convention} 9 | 10 | \begin{description} 11 | \item[\registerop{rd}] value in host byte order 12 | \item[\registerop{arg0}] value in network byte order 13 | \end{description} 14 | 15 | \subsubsection*{Description} 16 | 17 | The \subroutine{ntohl} routine takes a 32 bit value as its only 18 | argument and returns that value in host byte order. 19 | 20 | \subsubsection*{Failure modes} 21 | 22 | This subroutine has no run-time failure modes beyond its constraints. 23 | -------------------------------------------------------------------------------- /specification/subr/progenyof.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{progenyof} 4 | \label{subr:progenyof} 5 | \subsection*{progenyof:is this process the child of a particular PID} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] Boolean value 11 | \item[\registerop{arg0}] PID 12 | \end{description} 13 | 14 | \subsubsection*{Description} 15 | 16 | The \subroutine{progenyof} subroutine returns a boolean value that 17 | indicates if the current process is a child of the PID passed in the 18 | only argument. 19 | 20 | \subsubsection*{Failure modes} 21 | 22 | This subroutine has no run-time failure modes beyond its constraints. 23 | -------------------------------------------------------------------------------- /specification/subr/strtoll.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{strtoll} 4 | \label{subr:strtoll} 5 | \subsection*{strtoll: convert a string representing a number to a 6 | long long (64 bit) value} 7 | 8 | \subsubsection*{Calling convention} 9 | 10 | \begin{description} 11 | \item[\registerop{rd}] a long long (64 bit) value 12 | \item[\registerop{arg0}] string to convert 13 | \end{description} 14 | 15 | \subsubsection*{Description} 16 | 17 | The \subroutine{strtoll} takes a number encoding in a string and 18 | converts it to a long long (64 bit) value. 19 | 20 | \subsubsection*{Failure modes} 21 | 22 | This subroutine has no run-time failure modes beyond its constraints. 23 | -------------------------------------------------------------------------------- /specification/subr/getf.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{getf} 4 | \label{subr:getf} 5 | \subsection*{getf: Return a file structure based on a file descriptor} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] Pointer to a valid file structure. 11 | \item[\registerop{arg0}] File descriptor. 12 | \end{description} 13 | 14 | \subsubsection*{Description} 15 | 16 | The \subroutine{getf} subroutine takes a file descriptor as its 17 | argument and returns a file pointer based on the supplied file 18 | descriptor. 19 | 20 | \subsubsection*{Failure modes} 21 | 22 | This subroutine has no run-time failure modes beyond its constraints. 23 | -------------------------------------------------------------------------------- /specification/subr/rand.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{rand} 4 | \label{subr:rand} 5 | \subsection*{rand(): Get Random} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] Target for 64 bits of random(ish) data 11 | \end{description} 12 | 13 | \subsubsection*{Description} 14 | 15 | This subroutine returns 64 bits of random(ish) data, placing the result in 16 | \registerop{rd}. 17 | On supporting systems, stronger randomness can be obtained uing the 18 | \hyperref[subr:random]{\subroutine{random}} subroutine. 19 | 20 | \subsubsection*{Failure modes} 21 | 22 | This subroutine has no run-time failure modes beyond its constraints. 23 | -------------------------------------------------------------------------------- /specification/subr/lltostr.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{lltostr} 4 | \label{subr:lltostr} 5 | \subsection*{lltostr: convert a long long (64 bit) value to a string} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] string representation of passed value 11 | \item[\registerop{arg0}] 64 bit value to be converted 12 | \end{description} 13 | 14 | \subsubsection*{Description} 15 | 16 | The \subroutine{lltostr} subroutine takes a 64 bit value as its only 17 | argument and returns that value as a human readable string. 18 | 19 | \subsubsection*{Failure modes} 20 | 21 | This subroutine has no run-time failure modes beyond its constraints. 22 | -------------------------------------------------------------------------------- /specification/chap-opendtrace-api-boundries.tex: -------------------------------------------------------------------------------- 1 | 2 | \section{Existing API Boundries} 3 | 4 | % Main Boundries 5 | % Provider to Framework 6 | % Framework to Provider 7 | % ioctls 8 | % D Language scripts 9 | 10 | \section{DTrace Component Functional Dependencies} 11 | 12 | % To remove D language you would need to replace compiler 13 | % Needs to produce ECB in DIF/DIFO/DOF 14 | % Needs to implement ioctl for querying framework 15 | 16 | % To replace the CLI 17 | % Need a compiler to generate ECBs 18 | % Need to implement comms via ioctl 19 | % Need a mechanism to display results 20 | % %%% Think more about how the display could be separated, using RPC for buffer %%% 21 | % Uninfied display for the distributed use case 22 | -------------------------------------------------------------------------------- /specification/subr/mutex_owner.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{mutex-owner} 4 | \label{subr:mutex_owner} 5 | \subsection*{mutex\_owner: Report which thread owns a mutex} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{retval}] The kernel thread which owns the mutex 11 | \item[\registerop{arg0}] Pointer to the mutex structure 12 | \end{description} 13 | 14 | \subsubsection*{Description} 15 | 16 | The \subroutine{mutex_owner} subroutine returns the kernel thread 17 | structure which owns the mutex passed at the only argument. 18 | 19 | \subsubsection*{Failure modes} 20 | 21 | This subroutine has no run-time failure modes beyond its constraints. 22 | -------------------------------------------------------------------------------- /specification/subr/speculation.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{speculation} 4 | \label{subr:speculation} 5 | \subsection*{speculation: Activate an inactive speculation} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] Either an active speculation or 0. 11 | \end{description} 12 | 13 | \subsubsection*{Description} 14 | 15 | The \subroutine{speculation} subroutine transitions an inactive 16 | speculation to the active state, and returns it to the caller, or 17 | returns 0 if there are no inactive speculations available. 18 | 19 | \subsubsection*{Failure modes} 20 | 21 | This subroutine has no run-time failure modes beyond its constraints. 22 | -------------------------------------------------------------------------------- /specification/subr/htonll.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{hotnll} 4 | \label{subr:htonll} 5 | \subsection*{hotnll: convert a long long (64 bit) value from host to network byte order} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] A 64 bit value in network byte order 11 | \item[\registerop{arg0}] A 64 bit value in host byte order 12 | \end{description} 13 | 14 | \subsubsection*{Description} 15 | 16 | The \subroutine{htonll} routine takes a 64 bit value as its only 17 | argument and returns that value in network byte order. 18 | 19 | \subsubsection*{Failure modes} 20 | 21 | This subroutine has no run-time failure modes beyond its constraints. 22 | -------------------------------------------------------------------------------- /specification/subr/htons.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{htons} 4 | \label{subr:htons} 5 | \subsection*{htons: convert a short (16 bit) value from host to network 6 | byte order} 7 | 8 | \subsubsection*{Calling convention} 9 | 10 | \begin{description} 11 | \item[\registerop{rd}] A 16 bit value in network byte order 12 | \item[\registerop{rd}] A 16 bit value in host byte order 13 | \end{description} 14 | 15 | \subsubsection*{Description} 16 | 17 | The \subroutine{htons} subroutine takes a 16 bit value as its only 18 | argument and returns that value in network byte order. 19 | 20 | \subsubsection*{Failure modes} 21 | 22 | This subroutine has no run-time failure modes beyond its constraints. 23 | -------------------------------------------------------------------------------- /specification/subr/copyout.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{copyout} 4 | \label{subr:copyout} 5 | \subsection*{copyout: copy data from a buffer into process address space} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] void 11 | \item[\registerop{arg0}] Pointer to buffer 12 | \item[\registerop{arg1}] Pointer to memory 13 | \item[\registerop{arg2}] Length 14 | \end{description} 15 | 16 | \subsubsection*{Description} 17 | 18 | The \subroutine{copyout} subroutine copies data from a buffer supplied 19 | by the caller into a process's address space. 20 | 21 | \subsubsection*{Failure modes} 22 | 23 | This subroutine has no run-time failure modes beyond its constraints. 24 | -------------------------------------------------------------------------------- /specification/subr/ntohs.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{ntohs} 4 | \label{subr:ntohs} 5 | \subsection*{ntohs: convert a short (16 bit) value from network to 6 | host byte order} 7 | 8 | \subsubsection*{Calling convention} 9 | 10 | \begin{description} 11 | \item[\registerop{rd}] short (16 bit) value in host byte order 12 | \item[\registerop{arg0}] short (16 bit) value in network byte order 13 | \end{description} 14 | 15 | \subsubsection*{Description} 16 | 17 | The \subroutine{ntohs} subroutine takes a short (16 bit) value as its 18 | only argument and returns the same value in host byte order. 19 | 20 | \subsubsection*{Failure modes} 21 | 22 | This subroutine has no run-time failure modes beyond its constraints. 23 | -------------------------------------------------------------------------------- /specification/instr/ldta.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{LDTA} 4 | \label{insn:ldta} 5 | \subsection*{LDTA: Load thread local array UNIMPLEMENTED} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{LDTA \%rd, var, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x2B} 15 | \bitbox{8}{var} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{ldta} instruction is unimplemented and reserved for 24 | future use. 25 | 26 | \subsubsection*{Failure modes} 27 | 28 | This instruction has no run-time failure modes beyond its constraints. 29 | -------------------------------------------------------------------------------- /specification/subr/mutex_owned.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{mutex-owned} 4 | \label{subr:mutex_owned} 5 | \subsection*{mutex\_owned: Is this mutex owned by a thread} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] Boolean value indicating mutex ownership. 11 | \item[\registerop{arg0}] Pointer to the mutex structure 12 | \end{description} 13 | 14 | \subsubsection*{Description} 15 | 16 | The \subroutine{mutex_owned} subroutine takes a mutex as its argument 17 | and returns a boolean value indicating whether the mutex is currently 18 | owned by a thread. 19 | 20 | \subsubsection*{Failure modes} 21 | 22 | This subroutine has no run-time failure modes beyond its constraints. 23 | -------------------------------------------------------------------------------- /specification/subr/cleanpath.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{cleanpath} 4 | \label{subr:cleanpath} 5 | \subsection*{cleanpath: return the cleaned up pathname} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] A pointer to the scratch space string containing the 11 | cleaned up pathname. 12 | \item[\registerop{arg0}] Path to clean 13 | \end{description} 14 | 15 | \subsubsection*{Description} 16 | 17 | The \subroutine{cleanpath} subroutine takes a single string argument, containing 18 | a path, and returns a pointer to a string containing the cleaned up pathname. 19 | 20 | \subsubsection*{Failure modes} 21 | 22 | This subroutine has no run-time failure modes beyond its constraints. 23 | -------------------------------------------------------------------------------- /specification/subr/dirname.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{dirname} 4 | \label{subr:dirname} 5 | \subsection*{dirname: return the directory component of a pathname} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] A string pointing to the directory component of 11 | a pathname. 12 | \item[\registerop{arg0}] Path from which to extact the directory name 13 | \end{description} 14 | 15 | \subsubsection*{Description} 16 | 17 | The \subroutine{dirname} subroutine returns a string containing the 18 | directory component of a pathname, without the terminating filename. 19 | 20 | \subsubsection*{Failure modes} 21 | 22 | This subroutine has no run-time failure modes beyond its constraints. 23 | -------------------------------------------------------------------------------- /specification/subr/getminor.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{getminor} 4 | \label{subr:getminor} 5 | \subsection*{getminor: Get the minor device number from a device structure} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] Minor device number 11 | \end{description} 12 | 13 | \subsubsection*{Description} 14 | 15 | The \subroutine{getminor} subroutine returns the minor number from a 16 | device structure. 17 | 18 | \subsubsection*{Constraints} 19 | 20 | The \subroutine{getminor} subroutine is only available on Illumos and 21 | systems derivice from OpenSolaris. 22 | 23 | \subsubsection*{Failure modes} 24 | 25 | This subroutine has no run-time failure modes beyond its constraints. 26 | -------------------------------------------------------------------------------- /specification/subr/htonl.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{htonl} 4 | \label{subr:htonl} 5 | \subsection*{htonl: convert a long (32 bit) value from host to network byte order} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] Long value in network byte order 11 | \item[\registerop{arg0}] Long value in host byte order 12 | \end{description} 13 | 14 | \subsubsection*{Description} 15 | 16 | The \subroutine{htonl} subroutine takes a long value as its only 17 | argument and returns the same long value in network byte order, 18 | suitable for use in network protocols. 19 | 20 | \subsubsection*{Failure modes} 21 | 22 | This subroutine has no run-time failure modes beyond its constraints. 23 | -------------------------------------------------------------------------------- /specification/subr/ntohll.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{ntohll} 4 | \label{subr:ntohll} 5 | \subsection*{ntohll: convert a long long (64 bit) value from network 6 | to host byte order} 7 | 8 | \subsubsection*{Calling convention} 9 | 10 | \begin{description} 11 | \item[\registerop{rd}] long long (64 bit) value in host byte order 12 | \item[\registerop{arg0}] long long (64 bit) value in network byte order 13 | \end{description} 14 | 15 | \subsubsection*{Description} 16 | 17 | The \subroutine{ntohll} subroutine takes a long long (64 bit) value as 18 | its only argument and returns that value in host byte order. 19 | 20 | \subsubsection*{Failure modes} 21 | 22 | This subroutine has no run-time failure modes beyond its constraints. 23 | -------------------------------------------------------------------------------- /specification/subr/copyin.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{copyin} 4 | \label{subr:copyin} 5 | \subsection*{copyin: Copy data from user space to kernel space} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] void 11 | \item[\registerop{arg0}] Address to copy from 12 | \item[\registerop{arg1}] Length of data to copy 13 | \end{description} 14 | 15 | \subsubsection*{Description} 16 | 17 | The \subroutine{copyin} returns a pointer to a buffer which contains 18 | kernel data copied from the area pointed to by its first argument, up 19 | to the limit denoted by its second argument. 20 | 21 | \subsubsection*{Failure modes} 22 | 23 | This subroutine has no run-time failure modes beyond its constraints. 24 | -------------------------------------------------------------------------------- /specification/subr/copyinstr.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{copyinstr} 4 | \label{subr:copyinstr} 5 | \subsection*{copyinstr: Copy kernel data as a string} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] Pointer to the returned string. 11 | \item[\registerop{arg0}] Address to copy from 12 | \item[\registerop{arg1}] \emph{Optional} max length 13 | \end{description} 14 | 15 | \subsubsection*{Description} 16 | 17 | The \subroutine{copyinstr} subroutine returns a pointer to string of 18 | kernel data which is located at the first argument and bounded by the 19 | second argument. 20 | 21 | \subsubsection*{Failure modes} 22 | 23 | This subroutine has no run-time failure modes beyond its constraints. 24 | -------------------------------------------------------------------------------- /specification/subr/getmajor.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{getmajor} 4 | \label{subr:getmajor} 5 | \subsection*{getmajor: return major device number} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] Major device number 11 | \end{description} 12 | 13 | \subsubsection*{Description} 14 | 15 | The \subroutine{getmajor} subroutine returns the major device number 16 | from a device structure supplied as the first argument. 17 | 18 | \subsubsection*{Constraints} 19 | 20 | The \subroutine{getmajor} subroutine is only available on Illumos and 21 | systems derivice from OpenSolaris. 22 | 23 | \subsubsection*{Failure modes} 24 | 25 | This subroutine has no run-time failure modes beyond its constraints. 26 | -------------------------------------------------------------------------------- /specification/subr/copyinto.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{copyinto} 4 | \label{subr:copyinto} 5 | \subsection*{copyinto: copy data from a source to a destination} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] void 11 | \item[\registerop{arg0}] Address to copy from 12 | \item[\registerop{arg1}] Length of data 13 | \item[\registerop{arg2}] Destination address 14 | \end{description} 15 | 16 | \subsubsection*{Description} 17 | 18 | The \subroutine{copyinto} subroutine copies data from a source pointer 19 | into a destination pointer bounded by a size given in the second argument. 20 | 21 | \subsubsection*{Failure modes} 22 | 23 | This subroutine has no run-time failure modes beyond its constraints. 24 | -------------------------------------------------------------------------------- /specification/subr/copyoutstr.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{copyoutstr} 4 | \label{subr:copyoutstr} 5 | \subsection*{copyoutstr: copy data from kernel to user space, as a string} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] void 11 | \item[\registerop{arg0}] Pointer to buffer 12 | \item[\registerop{arg1}] Address in memory 13 | \item[\registerop{arg2}] Length 14 | \end{description} 15 | 16 | \subsubsection*{Description} 17 | 18 | The \subroutine{copyoutstr} subroutine copies data from kernel space 19 | to user space as a string value, bounded by the routine's third argument. 20 | 21 | \subsubsection*{Failure modes} 22 | 23 | This subroutine has no run-time failure modes beyond its constraints. 24 | -------------------------------------------------------------------------------- /specification/subr/mutex_type_adaptive.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{mutex-type-adaptive} 4 | \label{subr:mutex_type_adaptive} 5 | \subsection*{mutex\_type\_adaptive: Is the mutex adaptive} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{retval}] Boolean indication of whether or not the 11 | mutex is adaptive. 12 | \item[\registerop{arg0}] Pointer to the mutex structure 13 | \end{description} 14 | 15 | \subsubsection*{Description} 16 | 17 | The \subroutine{mutex_type_adaptive} subroutine takes a mutex as its 18 | only arugment and returns a boolean value indicating whether or not 19 | the mutex is adaptive. 20 | 21 | \subsubsection*{Failure modes} 22 | 23 | This subroutine has no run-time failure modes beyond its constraints. 24 | -------------------------------------------------------------------------------- /specification/subr/rw_read_held.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{rw-read-held} 4 | \label{subr:rw_read_held} 5 | \subsection*{rw\_read\_held: Is this read/write mutex currently held by 6 | a reader} 7 | 8 | \subsubsection*{Calling convention} 9 | 10 | \begin{description} 11 | \item[\registerop{rd}] Boolean value indicating if this read/write 12 | mutex is currently held. 13 | \item[\registerop{arg0}] Mutex structure 14 | \end{description} 15 | 16 | \subsubsection*{Description} 17 | 18 | The \subroutine{rw_read_held} subroutine takes a read/write mutex as its 19 | only argument and returns a boolean value indicating if the mutex is 20 | currently held by a reader. 21 | 22 | \subsubsection*{Failure modes} 23 | 24 | This subroutine has no run-time failure modes beyond its constraints. 25 | -------------------------------------------------------------------------------- /specification/subr/rw_write_held.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{rw-write-held} 4 | \label{subr:rw-write-held} 5 | \subsection*{rw\_write\_held: Is this read/write mutex held by a writer} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] Boolean value indicating whether or not a 11 | read/write mutex is held by a writer. 12 | \item[\registerop{arg0}] Mutex structure 13 | \end{description} 14 | 15 | \subsubsection*{Description} 16 | 17 | The \subroutine{rw_write_held} subroutine takes a read/write mutex as 18 | its only argument and returns a boolean value indicating whether or 19 | not the mutex is held by a writer. 20 | 21 | \subsubsection*{Failure modes} 22 | 23 | This subroutine has no run-time failure modes beyond its constraints. 24 | -------------------------------------------------------------------------------- /specification/instr/ldls.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{LDLS} 4 | \label{insn:ldls} 5 | \subsection*{LDLS: load local variable} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{LDLS variable, \%rd} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x48} 15 | \bitbox{16}{variable} 16 | \bitbox{8}{rd} 17 | \end{bytefield} 18 | \end{center} 19 | 20 | \subsubsection*{Description} 21 | 22 | The \instruction{ldls} instruction loads a local variable into the 23 | \registerop{rd} register. 24 | 25 | \subsubsection*{Pseudocode} 26 | 27 | \begin{verbatim} 28 | %rd = var 29 | \end{verbatim} 30 | 31 | \subsubsection*{Failure modes} 32 | 33 | This instruction has no run-time failure modes beyond its constraints. 34 | -------------------------------------------------------------------------------- /specification/subr/rw_iswriter.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{rw-iswriter} 4 | \label{subr:rw_iswriter} 5 | \subsection*{rw\_iswriter: Does the current thread hold a r/w mutex as 6 | a writer} 7 | 8 | \subsubsection*{Calling convention} 9 | 10 | \begin{description} 11 | \item[\registerop{rd}] Boolean value indicating if the current thread 12 | holds a read/write mutex as a writer. 13 | \item[\registerop{arg0}] Mutex structure 14 | \end{description} 15 | 16 | \subsubsection*{Description} 17 | 18 | The \subroutine{rw_iswriter} function takes a read/write mutex as its 19 | only arugment and returns a boolean value indicating if the current 20 | rhead holds the mutex as a writer. 21 | 22 | \subsubsection*{Failure modes} 23 | 24 | This subroutine has no run-time failure modes beyond its constraints. 25 | -------------------------------------------------------------------------------- /specification/subr/mutex_type_spin.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{mutex-type-spin} 4 | \label{subr:mutex_type_spin} 5 | \subsection*{mutex\_type\_spin: Spin mutex detection} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] Boolean value indicating whether or not the 11 | mutex passed as this subroutine's only argument is a spin mutex. 12 | \item[\registerop{arg0}] Pointer to the mutex structure 13 | \end{description} 14 | 15 | \subsubsection*{Description} 16 | 17 | The \subroutine{mutex_type_spin} subroutine takes a mutex as its only 18 | arugment and returns a boolean value indicating wether or not the 19 | mutex is a spin mutex. 20 | 21 | \subsubsection*{Failure modes} 22 | 23 | This subroutine has no run-time failure modes beyond its constraints. 24 | -------------------------------------------------------------------------------- /specification/instr/stls.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{STLS} 4 | \label{insn:stls} 5 | \subsection*{STLS: store a value in a local variable} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{STLS variable, \%rd} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,23,24,31} \\ 14 | \bitbox{8}{0x49} 15 | \bitbox{16}{variable} 16 | \bitbox{8}{rd} 17 | \end{bytefield} 18 | \end{center} 19 | 20 | \subsubsection*{Description} 21 | 22 | The \instruction{stls} instruction takes a value from the 23 | \registerop{rd} register and stores it in a variable. 24 | 25 | \subsubsection*{Pseudocode} 26 | 27 | \begin{verbatim} 28 | var = %rd 29 | \end{verbatim} 30 | 31 | \subsubsection*{Failure modes} 32 | 33 | This instruction has no run-time failure modes beyond its constraints. 34 | -------------------------------------------------------------------------------- /specification/instr/nop.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{NOP} 4 | \label{insn:nop} 5 | \subsection*{NOP: no operation} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{NOP} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,31} \\ 14 | \bitbox{8}{0x24} 15 | \bitbox{24}{0} 16 | \end{bytefield} 17 | \end{center} 18 | 19 | \subsubsection*{Description} 20 | 21 | The \instruction{nop} does nothing and has no side effects on the 22 | DTrace virtual machine. 23 | \subsubsection*{Pseudocode} 24 | 25 | \begin{verbatim} 26 | nop 27 | \end{verbatim} 28 | 29 | \subsubsection*{Load-time constraints} 30 | The \instruction{nop} instruction has no load-time constraints. 31 | 32 | \subsubsection*{Failure modes} 33 | 34 | This instruction has no run-time failure modes beyond its constraints. 35 | -------------------------------------------------------------------------------- /specification/instr/stgaa.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{STGAA} 4 | \label{insn:stgaa} 5 | \subsection*{STGAA: store a value into a hash by key} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{STGAA key, \%rd} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,23,24,31} \\ 14 | \bitbox{8}{0x46} 15 | \bitbox{16}{key} 16 | \bitbox{8}{rd} 17 | \end{bytefield} 18 | \end{center} 19 | 20 | \subsubsection*{Description} 21 | 22 | The \instruction{stgaa} instruction stores a value, contained in the 23 | \registerop{rd} register into a hash map based on a key. 24 | \subsubsection*{Pseudocode} 25 | 26 | \begin{verbatim} 27 | map[key] = %rd 28 | \end{verbatim} 29 | 30 | \subsubsection*{Failure modes} 31 | 32 | This instruction has no run-time failure modes beyond its constraints. 33 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # OpenDTrace Documentation Repository 2 | 3 | Papers, technical reports, and other documentation covering OpenDTrace. 4 | 5 | ## OpenDTrace Specification 6 | 7 | ### Published versions 8 | 9 | [v1.0](https://github.com/opendtrace/documentation/releases/tag/v1.0) 10 | : https://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-924.html 11 | 12 | ### Current version 13 | 14 | In order to checkout and build the specification you will need a full 15 | installation of a modern (La)TeX system including the following 16 | packages: 17 | 18 | * algpseudocode 19 | * amsmath 20 | * appendix 21 | * booktabs 22 | * bytefield 23 | * color 24 | * fullpage 25 | * graphicx 26 | * hyperref 27 | * marginnote 28 | * listings 29 | * setspace 30 | * times 31 | 32 | Once LaTeX and the packages are installed you can build the document 33 | by typing `make` in the `specification/` directory. 34 | -------------------------------------------------------------------------------- /specification/instr/sttaa.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{STTAA} 4 | \label{insn:sttaa} 5 | \subsection*{STTAA: store a value into a thread private, hash by key} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{STTAA key, \%rd} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,23,24,31} \\ 14 | \bitbox{8}{0x47} 15 | \bitbox{16}{key} 16 | \bitbox{8}{rd} 17 | \end{bytefield} 18 | \end{center} 19 | 20 | \subsubsection*{Description} 21 | 22 | The \instruction{sttaa} instruction stores a value, contained in the 23 | \registerop{rd} register into a thread private, hash map based on a key. 24 | \subsubsection*{Pseudocode} 25 | 26 | \begin{verbatim} 27 | map[key] = %rd 28 | \end{verbatim} 29 | 30 | \subsubsection*{Failure modes} 31 | 32 | This instruction has no run-time failure modes beyond its constraints. 33 | -------------------------------------------------------------------------------- /specification/instr/flushts.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{FLUSHTS} 4 | \label{insn:flushts} 5 | \subsection*{FLUSHTS: flush the stack} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{FLUSHTS} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,31} \\ 14 | \bitbox{8}{0x33} 15 | \bitbox{24}{0} 16 | \end{bytefield} 17 | \end{center} 18 | 19 | \subsubsection*{Description} 20 | 21 | The \instruction{flushts} instruction flushes the stack, by resetting 22 | the stack pointer to 0. 23 | \subsubsection*{Pseudocode} 24 | 25 | \begin{verbatim} 26 | %sp = 0; 27 | \end{verbatim} 28 | 29 | \subsubsection*{Load-time constraints} 30 | The \instruction{flushts} instruction has no load-time constraints. 31 | 32 | \subsubsection*{Failure modes} 33 | 34 | This instruction has no run-time failure modes beyond its constraints. 35 | -------------------------------------------------------------------------------- /specification/instr/xlate.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{XLATE} 4 | \label{insn:xlate} 5 | \subsection*{XLATE: } 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{XLATE \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x4E} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{xlate} instruction extracts translated data indicated 24 | at the current translation index and returns the data in 25 | \registerop{rd}. 26 | 27 | \emph{NOTE:} This instruction is not used by the kernel as all 28 | translations are handled in user space. 29 | 30 | \subsubsection*{Failure modes} 31 | 32 | This instruction has no run-time failure modes beyond its constraints. 33 | -------------------------------------------------------------------------------- /specification/subr/alloca.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{alloca} 4 | \label{subr:alloca} 5 | \subsection*{alloca: allocate temporary space} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] void 11 | \item[\registerop{arg0}] Pointer to allocated data or NULL. 12 | \end{description} 13 | 14 | \subsubsection*{Description} 15 | 16 | The \subroutine{alloca} subroutine allocates scratch space in the 17 | DTrace state machine structure. Although this subroutine does not 18 | allocate space on the process stack, it does act similarly to the 19 | alloca macro, in that the space disappears without an explicit call to 20 | a \subroutine{free} routine, once the DTrace machine state structure 21 | is deallocated. 22 | 23 | \subsubsection*{Failure modes} 24 | 25 | This subroutine has no run-time failure modes beyond its constraints. 26 | -------------------------------------------------------------------------------- /specification/instr/xlarg.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{XLARG} 4 | \label{insn:xlarg} 5 | \subsection*{XLARG: translation argument} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{XLARG \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x4F} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{xlarg} instruction translates a single argument from 24 | a structure and returns the tranlsated value in \registerop{rd}. 25 | 26 | \emph{NOTE:} This instruction is not used by the kernel as all 27 | translations are handled in user space. 28 | 29 | \subsubsection*{Failure modes} 30 | 31 | This instruction has no run-time failure modes beyond its constraints. 32 | -------------------------------------------------------------------------------- /specification/instr/ldgaa.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{LDGAA} 4 | \label{insn:ldgaa} 5 | \subsection*{LDGAA: load a value from a hash map} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{LDGAA key, \%rd} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,23,24,31} \\ 14 | \bitbox{8}{0x34} 15 | \bitbox{16}{key} 16 | \bitbox{8}{rd} 17 | \end{bytefield} 18 | \end{center} 19 | 20 | \subsubsection*{Description} 21 | 22 | The \instruction{ldgaa} instruction loads a value into the 23 | \registerop{rd} register based on a key. The key is used to lookup 24 | the value in a hash map data structure. 25 | 26 | \subsubsection*{Pseudocode} 27 | 28 | \begin{verbatim} 29 | %rd = map[key] 30 | \end{verbatim} 31 | 32 | \subsubsection*{Failure modes} 33 | 34 | This instruction has no run-time failure modes beyond its constraints. 35 | -------------------------------------------------------------------------------- /specification/subr/index.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{index} 4 | \label{subr:index} 5 | \subsection*{index: return the byte position of a character in a string} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] Position of character or -1 11 | \item[\registerop{arg0}] String to search 12 | \end{description} 13 | 14 | \subsubsection*{Description} 15 | 16 | The \subroutine{index} subroutine searches from the beginning of a 17 | string pointed to by its first argument, for a character supplied as 18 | the second argument. The search proceeds until the character is 19 | found, or an optional limit, supplied as the third argument is 20 | reached. If the character is not found then -1 is returned to the 21 | caller. 22 | 23 | \subsubsection*{Failure modes} 24 | 25 | This subroutine has no run-time failure modes beyond its constraints. 26 | -------------------------------------------------------------------------------- /specification/subr/ddi_pathname.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{ddi\_pathname} 4 | \label{subr:ddi_pathname} 5 | \subsection*{ddi\_pathname: look up device driver by name} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{arg0}] Pointer to a device node. 11 | \item[\registerop{arg1}] Device minor number. 12 | \item[\registerop{rd}] Path within the /devices tree. 13 | \end{description} 14 | 15 | \subsubsection*{Description} 16 | 17 | The \subroutine{ddi_pathname} subroutine returns a string describing 18 | the device driver that implements a device in the system. 19 | 20 | \subsubsection*{Constraints} 21 | 22 | The \subroutine{ddi_pathname} subroutine is only available on Illumos and 23 | systems derivice from OpenSolaris. 24 | 25 | \subsubsection*{Failure modes} 26 | 27 | This subroutine has no run-time failure modes beyond its constraints. 28 | -------------------------------------------------------------------------------- /specification/subr/inet_ntop.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{inet-ntop} 4 | \label{subr:inet-ntop} 5 | \subsection*{inet\_ntop: convert an arbitrary Internet address to a string} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] Internet address as a string 11 | \item[\registerop{arg0}] Address Family 12 | \item[\registerop{arg1}] Pointer to address structure 13 | \end{description} 14 | 15 | \subsubsection*{Description} 16 | 17 | The \subroutine{inet_ntop} subroutine takes either a 128 bit, IPv6, 18 | address or a 32 bit, IPv4 address, and converts it to a string 19 | suitable for humans. The type of address supplied is indeicated by 20 | the second argument, which must either be \verb|AF_INET| or 21 | \verb|AF_INET6|. 22 | 23 | \subsubsection*{Failure modes} 24 | 25 | This subroutine has no run-time failure modes beyond its constraints. 26 | -------------------------------------------------------------------------------- /specification/subr/msgsize.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{msgsize} 4 | \label{subr:msgsize} 5 | \subsection*{msgsize: return the size data in a STREAMS message block} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] The size of the data contained in the 11 | message block. 12 | \item[\registerop{arg0}] Pointer to the message block structure 13 | \end{description} 14 | 15 | \subsubsection*{Description} 16 | 17 | The \subroutine{msgsize} subroutine returns the size of the data 18 | contained in a message block stucture. Message blocks are specific to 19 | the STREAMS system. 20 | 21 | \subsubsection*{Constraints} 22 | 23 | The \subroutine{msgsize} subroutine is only available on the Illumos 24 | operating system. 25 | 26 | \subsubsection*{Failure modes} 27 | 28 | This subroutine has no run-time failure modes beyond its constraints. 29 | -------------------------------------------------------------------------------- /specification/subr/msgdsize.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{msgdsize} 4 | \label{subr:msgdsize} 5 | \subsection*{msgdsize: return the size data in a STREAMS message block } 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] The size of the data contained in the 11 | message block. 12 | \item[\registerop{arg0}] Pointer to the message block structure 13 | \end{description} 14 | 15 | \subsubsection*{Description} 16 | 17 | The \subroutine{msgdsize} subroutine returns the size of the data 18 | contained in a message block stucture. Message blocks are specific to 19 | the STREAMS system. 20 | 21 | \subsubsection*{Constraints} 22 | 23 | The \subroutine{msdgsize} subroutine is only available on the Illumos 24 | operating system. 25 | 26 | \subsubsection*{Failure modes} 27 | 28 | This subroutine has no run-time failure modes beyond its constraints. 29 | -------------------------------------------------------------------------------- /specification/subr/json.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{json} 4 | \label{subr:json} 5 | \subsection*{json: extract a single value from a JSON string} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] A string containing the value or NULL 11 | \item[\registerop{arg0}] JSON formatted string 12 | \item[\registerop{rd}] Key to search for 13 | \end{description} 14 | 15 | \subsubsection*{Description} 16 | 17 | The \subroutine{json} subroutine extracts a value from a JSON string 18 | based on one or more keys supplied via a list in which NULL is used as 19 | a key separator, e.g. \verb|"name" NULL "age" NULL| where the keys are 20 | \emph{name} and \emph{age} and the number of elements in the list 21 | (\verb|nelems|) is equal to two (2). 22 | 23 | \subsubsection*{Failure modes} 24 | 25 | This subroutine has no run-time failure modes beyond its constraints. 26 | -------------------------------------------------------------------------------- /specification/instr/setx.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{SETX} 4 | \label{insn:setx} 5 | \subsection*{SETX: retrieve an integer from the integer table} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{SETX \%rd, intindex} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,31} \\ 14 | \bitbox{8}{0x25} 15 | \bitbox{8}{rd} 16 | \bitbox{16}{index} 17 | \end{bytefield} 18 | \end{center} 19 | 20 | \subsubsection*{Description} 21 | 22 | The \instruction{setx} instruction looks up an integer value stored in 23 | the DIF integer table and places it into \registerop{rd}. This instruction 24 | performs no bounds checking. 25 | \subsubsection*{Pseudocode} 26 | 27 | \begin{verbatim} 28 | %rd = inttab[index] 29 | \end{verbatim} 30 | 31 | \subsubsection*{Failure modes} 32 | 33 | This instruction has no run-time failure modes beyond its constraints. 34 | -------------------------------------------------------------------------------- /specification/subr/basename.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{basename} 4 | \label{subr:basename} 5 | \subsection*{basename: return the file name portion of a pathname} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] A pointer to a scratch space string containing 11 | the filename. 12 | \item[\registerop{arg0}] Pathname from which to extract the basename 13 | \end{description} 14 | 15 | \subsubsection*{Description} 16 | 17 | The \subroutine{basename} subroutine takes a single string argument, 18 | containing a path, and returns a pointer to the file name portion of 19 | the supplied string. The space for the resulting string is contained 20 | in the DTrace machine state structure, \verb|mstate| which is 21 | automatically de-allocated. 22 | 23 | \subsubsection*{Failure modes} 24 | 25 | This subroutine has no run-time failure modes beyond its constraints. 26 | -------------------------------------------------------------------------------- /specification/instr/ldtaa.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{LDTAA} 4 | \label{insn:ldtaa} 5 | \subsection*{LDTAA: load a value from a thread private hash map} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{LDTAA var, \%rd} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,23,24,31} \\ 14 | \bitbox{8}{0x35} 15 | \bitbox{16}{key} 16 | \bitbox{8}{rd} 17 | \end{bytefield} 18 | \end{center} 19 | 20 | \subsubsection*{Description} 21 | 22 | The \instruction{ldtaa} instruction loads a value into the 23 | \registerop{rd} register based on a key. The key is used to lookup 24 | the value in a thread private, hash map, data structure. 25 | 26 | \subsubsection*{Pseudocode} 27 | 28 | \begin{verbatim} 29 | %rd = map[key] 30 | \end{verbatim} 31 | 32 | \subsubsection*{Failure modes} 33 | 34 | This instruction has no run-time failure modes beyond its constraints. 35 | -------------------------------------------------------------------------------- /specification/instr/sets.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{SETS} 4 | \label{insn:sets} 5 | \subsection*{SETS: retrieve string from the string table} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{SETS \%rd, strindex} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,31} \\ 14 | \bitbox{8}{0x26} 15 | \bitbox{8}{rd} 16 | \bitbox{16}{index} 17 | \end{bytefield} 18 | \end{center} 19 | 20 | \subsubsection*{Description} 21 | 22 | The \instruction{sets} instruction looks up a string stored in the DIF 23 | string table and places a pointer to the value into \registerop{rd}. This 24 | instruction performs no bounds checking. 25 | \subsubsection*{Pseudocode} 26 | 27 | \begin{verbatim} 28 | %rd = strtab + index 29 | \end{verbatim} 30 | 31 | \subsubsection*{Failure modes} 32 | 33 | This instruction has no run-time failure modes beyond its constraints. 34 | -------------------------------------------------------------------------------- /specification/instr/call.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{CALL} 4 | \label{insn:call} 5 | \subsection*{CALL: subroutine call} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{CALL \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,23,24,31} \\ 14 | \bitbox{8}{0x2F} 15 | \bitbox{16}{subroutine} 16 | \bitbox{8}{rd} 17 | \end{bytefield} 18 | \end{center} 19 | 20 | \subsubsection*{Description} 21 | 22 | The \instruction{call} instruction executes a known DTrace subroutine, 23 | such as copyinstr(), copyout() etc. and returns any value into 24 | \registerop{rd}. Valid subroutines are documented in 25 | \ref{sec:subroutines}. 26 | 27 | \subsubsection*{Pseudocode} 28 | 29 | \begin{verbatim} 30 | %rd = subr() 31 | \end{verbatim} 32 | 33 | \subsubsection*{Failure modes} 34 | 35 | This instruction has no run-time failure modes beyond its constraints. 36 | -------------------------------------------------------------------------------- /specification/instr/popts.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{POPTS} 4 | \label{insn:popts} 5 | \subsection*{POPTS: pop a value from the stack} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{POPTS} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,31} \\ 14 | \bitbox{8}{0x32} 15 | \bitbox{24}{0} 16 | \end{bytefield} 17 | \end{center} 18 | 19 | \subsubsection*{Description} 20 | 21 | The \instruction{popts} pops the stack, moving the stack's index to 22 | next position down from the top, without returning any value. 23 | 24 | \subsubsection*{Pseudocode} 25 | 26 | \begin{verbatim} 27 | stack[index--] 28 | \end{verbatim} 29 | 30 | \subsubsection*{Load-time constraints} 31 | The \instruction{popts} instruction has no load-time constraints. 32 | 33 | \subsubsection*{Failure modes} 34 | 35 | This instruction has no run-time failure modes beyond its constraints. 36 | -------------------------------------------------------------------------------- /specification/subr/strlen.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{strlen} 4 | \label{subr:strlen} 5 | \subsection*{strlen: DTrace version of the strlen function} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] Length of the string passed as the only argument 11 | \item[\registerop{arg0}] Pointer to the string 12 | \end{description} 13 | 14 | \subsubsection*{Description} 15 | 16 | The \subroutine{strlen} subroutine is DTrace's version of the well 17 | known C library function. It returns the length, in bytes, of the string 18 | pointed to by the pointer passed in as its first argument. The string must be 19 | NULL terminated. 20 | 21 | \subsubsection*{Pseudocode} 22 | 23 | \begin{verbatim} 24 | string = stack[0].value 25 | %rd = strlen(string) 26 | \end{verbatim} 27 | 28 | \subsubsection*{Failure modes} 29 | 30 | This subroutine has no run-time failure modes beyond its constraints. 31 | -------------------------------------------------------------------------------- /specification/instr/ldts.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{LDTS} 4 | \label{insn:ldts} 5 | \subsection*{LDTS: load a value from a thread local variable} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{LDTS \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,23,24,31} \\ 14 | \bitbox{8}{0x2C} 15 | \bitbox{16}{variable} 16 | \bitbox{8}{rd} 17 | \end{bytefield} 18 | \end{center} 19 | 20 | \subsubsection*{Description} 21 | 22 | The \instruction{ldts} instruction loads data from a thread local 23 | variable into the \registerop{rd} register by reference or by value. 24 | The \verb|DIF_TF_BYREF| flag is used to determine the appropriate lookup. 25 | 26 | \subsubsection*{Pseudocode} 27 | 28 | \begin{verbatim} 29 | %rd = var 30 | \end{verbatim} 31 | 32 | \subsubsection*{Failure modes} 33 | 34 | This instruction has no run-time failure modes beyond its constraints. 35 | -------------------------------------------------------------------------------- /specification/subr/rindex.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{rindex} 4 | \label{subr:rindex} 5 | \subsection*{rindex: locate the last matching character in a a string} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] The position of the character or -1 if the 11 | character is not found. 12 | \item[\registerop{arg0}] The string to search. 13 | \end{description} 14 | 15 | \subsubsection*{Description} 16 | 17 | The \subroutine{rindex} subroutine searches from the end of a string 18 | pointed to by its first argument, for the first instance character 19 | supplied as its second argument. The search proceeds until the 20 | character is found, or an optional limit, supplied as the third 21 | argument is reached. If the character is not found then -1 is 22 | returned to the caller. 23 | 24 | \subsubsection*{Failure modes} 25 | 26 | This subroutine has no run-time failure modes beyond its constraints. 27 | -------------------------------------------------------------------------------- /specification/instr/stts.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{STTS} 4 | \label{insn:stts} 5 | \subsection*{STTS: Store a value into thread local storage} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{STTS \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,23,24,31} \\ 14 | \bitbox{8}{0x2D} 15 | \bitbox{8}{variable} 16 | \bitbox{8}{rd} 17 | \end{bytefield} 18 | \end{center} 19 | 20 | \subsubsection*{Description} 21 | 22 | The \instruction{stts} instruction takes the value stored in 23 | \registerop{rd} and stores it directly, or by reference into a thread 24 | local variable. The \verb|DIF_TF_BYREF| flag is used to determine the 25 | appropriate lookup. 26 | 27 | \subsubsection*{Pseudocode} 28 | 29 | \begin{verbatim} 30 | var = %rd 31 | \end{verbatim} 32 | 33 | \subsubsection*{Failure modes} 34 | 35 | This instruction has no run-time failure modes beyond its constraints. 36 | -------------------------------------------------------------------------------- /specification/subr/sx_shared_held.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{sx-read-held} 4 | \label{subr:sx-read-held} 5 | \subsection*{sx\_shared\_held: Is this shared mutex currently held by 6 | a reader} 7 | 8 | \subsubsection*{Calling convention} 9 | 10 | \begin{description} 11 | \item[\registerop{rd}] Boolean value indicating if this read/write 12 | mutex is currently held. 13 | \item[\registerop{arg0}] shared lock structure 14 | \end{description} 15 | 16 | \subsubsection*{Description} 17 | 18 | The \subroutine{sx_shared_held} subroutine takes an sx shared mutex as 19 | its only argument and returns a boolean value indicating if the mutex 20 | is currently held by a reader. 21 | 22 | \subsubsection*{Constraints} 23 | 24 | The \subroutine{sx_shared_held} subroutine is only available on Illumos and 25 | systems derivice from OpenSolaris. 26 | 27 | \subsubsection*{Failure modes} 28 | 29 | This subroutine has no run-time failure modes beyond its constraints. 30 | -------------------------------------------------------------------------------- /specification/subr/copyoutmbuf.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{copyoutmbuf} 4 | \label{subr:copyoutmbuf} 5 | \subsection*{copyoutmbuf: copy data from an mbuf chain} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] pointer to copied data 11 | \item[\registerop{arg0}] pointer to mbuf 12 | \item[\registerop{arg1}] amount of data to copy 13 | \end{description} 14 | 15 | \subsubsection*{Description} 16 | 17 | The \subroutine{copyoutmbuf} subroutine copies data from an mbuf 18 | chain out a destination pointer bounded by a size given in the second 19 | argument. If the second argument exceeds the size of the data in the 20 | mbuf chain then it is reduced to the correct length. 21 | 22 | \subsubsection*{Constraints} 23 | 24 | The \subroutine{copyoutmbuf} subroutine is only supported on FreeBSD. 25 | 26 | \subsubsection*{Failure modes} 27 | 28 | This subroutine has no run-time failure modes beyond its constraints. 29 | -------------------------------------------------------------------------------- /specification/subr/sx_exclusive_held.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{sx-exclusive-held} 4 | \label{subr:sx-exclusive-held} 5 | \subsection*{sx\_exclusive\_held: Is this sx mutex held exclusively } 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] Boolean value indicating whether or not a 11 | the mutex is held exclusively.. 12 | \item[\registerop{arg0}] shared lock structure 13 | \end{description} 14 | 15 | \subsubsection*{Description} 16 | 17 | The \subroutine{sx_exclusive_held} subroutine takes an sx shared mutex 18 | as its only argument and returns a boolean value indicating whether or 19 | not the mutex is held exclusively. 20 | 21 | \subsubsection*{Constraints} 22 | 23 | The \subroutine{sx_exclusive_held} subroutine is only available on Illumos and 24 | systems derivice from OpenSolaris. 25 | 26 | \subsubsection*{Failure modes} 27 | 28 | This subroutine has no run-time failure modes beyond its constraints. 29 | -------------------------------------------------------------------------------- /specification/instr/ret.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{RET} 4 | \label{insn:ret} 5 | \subsection*{RET: return} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{RET \%rd} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,31} \\ 14 | \bitbox{8}{0x23} 15 | \bitbox{24}{rd} 16 | \end{bytefield} 17 | \end{center} 18 | 19 | \subsubsection*{Description} 20 | 21 | The \instruction{ret} instruction returns the value in \registerop{rd}. This 22 | instruction also sets the \register{pc} register to the length of the DIFO text 23 | section. 24 | 25 | \subsubsection*{Pseudocode} 26 | \begin{verbatim} 27 | %pc = textlen 28 | \end{verbatim} 29 | 30 | \subsubsection*{Load-time constraints} 31 | The registers \registerop{r1} and \registerop{r2} must be \registerop{r0} and 32 | \registerop{rd} must be a valid register. 33 | 34 | \subsubsection*{Failure modes} 35 | 36 | This instruction has no run-time failure modes beyond its constraints. 37 | -------------------------------------------------------------------------------- /specification/subr/memstr.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{memstr} 4 | \label{subr:memstr} 5 | \subsection*{memstr: convert NULL separated strings to one string} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{arg0}] pointer to memory 11 | \item[\registerop{arg1}] separation character 12 | \item[\registerop{arg2}] length of memory to convert 13 | \item[\registerop{rd}] converted string 14 | \end{description} 15 | 16 | \subsubsection*{Description} 17 | 18 | The \subroutine{memstr} subroutine converts a set of NULL separated 19 | strings into a single string. The string is bounded by the caller. 20 | 21 | 22 | \subsubsection*{Constraints} 23 | 24 | The maximum length of string to be converted is limited to 4096 bytes 25 | by default. The \subroutine{memstr} subroutine is only available on 26 | the FreeBSD operating system. 27 | 28 | \subsubsection*{Failure modes} 29 | 30 | This subroutine has no run-time failure modes beyond its constraints. 31 | -------------------------------------------------------------------------------- /specification/subr/sx_isexclusive.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{sx-isexclusive} 4 | \label{subr:sx-isexclusive} 5 | \subsection*{sx\_isexclusive: Is the current thread the only one to 6 | hold a shared mutex } 7 | 8 | \subsubsection*{Calling convention} 9 | 10 | \begin{description} 11 | \item[\registerop{rd}] Boolean value indicating if the current thread 12 | is the only one holding a shared mutex. 13 | \item[\registerop{arg0}] shared lock structure 14 | \end{description} 15 | 16 | \subsubsection*{Description} 17 | 18 | The \subroutine{sx_isexclusie} subroutine takes a shared mutex as 19 | its only arugment and returns a boolean value indicating if the 20 | current thread is the only one holding it. 21 | 22 | \subsubsection*{Constraints} 23 | 24 | The \subroutine{sx_isexclusive} subroutine is only available on 25 | Illumos and systems derivice from OpenSolaris. 26 | 27 | \subsubsection*{Failure modes} 28 | 29 | This subroutine has no run-time failure modes beyond its constraints. 30 | -------------------------------------------------------------------------------- /specification/instr/ba.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{BA} 4 | \label{insn:ba} 5 | \subsection*{BA: branch absolute} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{BA label} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,23,24,31} \\ 14 | \bitbox{8}{0x11} 15 | \bitbox{24}{label} 16 | \end{bytefield} 17 | \end{center} 18 | 19 | \subsubsection*{Description} 20 | 21 | The \instruction{ba} instruction branches to the label indicated by 22 | setting the Program Counter (\verb+pc+) to the instruction indicated 23 | at the \verb+label+. 24 | 25 | \subsubsection*{Pseudocode} 26 | 27 | \begin{verbatim} 28 | %pc = label 29 | \end{verbatim} 30 | 31 | \subsubsection*{Load-time constraints} 32 | \verb+label+ must be greater than \verb+pc+. Moreover, \verb+label+ must 33 | not go past the last address of the current DIF object. 34 | 35 | \subsubsection*{Failure modes} 36 | 37 | This instruction has no run-time failure modes beyond its constraints. 38 | -------------------------------------------------------------------------------- /specification/subr/strchr.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{strchr} 4 | \label{subr:strchr} 5 | \subsection*{strchr: locate a character in a string} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] pointer to the character or NULL if not found 11 | \item[\registerop{arg0}] string to search 12 | \end{description} 13 | 14 | \subsubsection*{Description} 15 | 16 | The \subroutine{strchr} subroutine searches a string, supplied as the 17 | first argument, for the first instance of the character passed as the 18 | second and returns a pointer to the location of the character in the 19 | string. If the charaacter is not present in the string then NULL is 20 | returned. 21 | 22 | \subsubsection*{Pseudocode} 23 | 24 | \begin{verbatim} 25 | addr = stack[0].value 26 | target = stack[1].value 27 | %rd = strchr(addr, target) 28 | \end{verbatim} 29 | 30 | \subsubsection*{Failure modes} 31 | 32 | This subroutine has no run-time failure modes beyond its constraints. 33 | -------------------------------------------------------------------------------- /specification/subr/strrchr.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{strrchr} 4 | \label{subr:strrchr} 5 | \subsection*{strrchr: reverse search a string} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] pointer to the character or NULL if not found 11 | \item[\registerop{arg0}] string to search 12 | \end{description} 13 | 14 | \subsubsection*{Description} 15 | 16 | The \subroutine{strrchr} subroutine searches a string, supplied as the 17 | first argument, for the last instance of the character passed as the 18 | second and returns a pointer to the location of the character in the 19 | string. If the charaacter is not present in the string then NULL is 20 | returned. 21 | 22 | \subsubsection*{Pseudocode} 23 | 24 | \begin{verbatim} 25 | addr = stack[0].value 26 | target = stack[1].value 27 | %rd = strrchr(addr, target) 28 | \end{verbatim} 29 | 30 | \subsubsection*{Failure modes} 31 | 32 | This subroutine has no run-time failure modes beyond its constraints. 33 | -------------------------------------------------------------------------------- /specification/instr/pushtv.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{PUSHTV} 4 | \label{insn:pushtv} 5 | \subsection*{PUSHTV: push a value onto the stack} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{PUSHTV \%rs} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x31} 15 | \bitbox{8}{r0} 16 | \bitbox{8}{r0} 17 | \bitbox{8}{rs} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{pushtv} instruction takes the value contained in 24 | \registerop{rs} register and pushes it onto the stack. Unlike the 25 | \verb|PUSHTR| instruction, the size of the value is \emph{not} stored 26 | along with the value. 27 | 28 | \subsubsection*{Pseudocode} 29 | 30 | \begin{verbatim} 31 | stack[++index].value = %rs 32 | stack[index].size = 0; 33 | \end{verbatim} 34 | 35 | \subsubsection*{Failure modes} 36 | 37 | This instruction has no run-time failure modes beyond its constraints. 38 | -------------------------------------------------------------------------------- /specification/instr/mov.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{MOV} 4 | \label{insn:mov} 5 | \subsection*{MOV: move a value} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{MOV \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x0D} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{mov} instruction places the value found in 24 | \registerop{r1} into \registerop{rd}. 25 | 26 | \subsubsection*{Pseudocode} 27 | 28 | \begin{verbatim} 29 | %rd = %r1 30 | \end{verbatim} 31 | 32 | \subsubsection*{Load-time constraints} 33 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 34 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 35 | \registerop{r0}. 36 | 37 | \subsubsection*{Failure modes} 38 | 39 | This instruction has no run-time failure modes beyond its constraints. 40 | -------------------------------------------------------------------------------- /specification/instr/be.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{BE} 4 | \label{insn:be} 5 | \subsection*{BE: branch equal} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{BE label} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,23,24,31} \\ 14 | \bitbox{8}{0x12} 15 | \bitbox{24}{label} 16 | \end{bytefield} 17 | \end{center} 18 | 19 | \subsubsection*{Description} 20 | 21 | The \instruction{be} instruction sets the PC to a new label if, and 22 | only if the result of the last \instruction{cmp} or \instruction{tst} 23 | set the zero bit (cc\_z) to a value other than 0. 24 | 25 | \subsubsection*{Pseudocode} 26 | 27 | \begin{verbatim} 28 | if (cc_z) 29 | %pc = label 30 | \end{verbatim} 31 | 32 | \subsubsection*{Load-time constraints} 33 | \verb+label+ must be greater than \verb+pc+. Moreover, \verb+label+ must 34 | not go past the last address of the current DIF object. 35 | 36 | \subsubsection*{Failure modes} 37 | 38 | This instruction has no run-time failure modes beyond its constraints. 39 | -------------------------------------------------------------------------------- /specification/instr/bg.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{BG} 4 | \label{insn:bg} 5 | \subsection*{BG: branch greater than} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{BG label} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,23,24,31} \\ 14 | \bitbox{8}{0x14} 15 | \bitbox{24}{label} 16 | \end{bytefield} 17 | \end{center} 18 | 19 | \subsubsection*{Description} 20 | 21 | The \instruction{bg} instruction sets the PC to a new label if, and 22 | only if the result of the last \instruction{cmp} resulted in the zero bit 23 | (cc\_z) being set to a value other than 0. 24 | 25 | \subsubsection*{Pseudocode} 26 | 27 | \begin{verbatim} 28 | if (cc_z) 29 | %pc = label 30 | \end{verbatim} 31 | 32 | \subsubsection*{Load-time constraints} 33 | \verb+label+ must be greater than \verb+pc+. Moreover, \verb+label+ must 34 | not go past the last address of the current DIF object. 35 | 36 | \subsubsection*{Failure modes} 37 | 38 | This instruction has no run-time failure modes beyond its constraints. 39 | -------------------------------------------------------------------------------- /specification/instr/bne.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{BNE} 4 | \label{insn:bne} 5 | \subsection*{BNE: branch not equal} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{BNE label} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,23,24,31} \\ 14 | \bitbox{8}{0x13} 15 | \bitbox{24}{label} 16 | \end{bytefield} 17 | \end{center} 18 | 19 | \subsubsection*{Description} 20 | 21 | The \instruction{bne} instruction sets the PC to a new label if, and 22 | only if the result of the last \instruction{cmp} resulted in the zero 23 | bit (cc\_z) being cleared, or set to 0. 24 | 25 | \subsubsection*{Pseudocode} 26 | 27 | \begin{verbatim} 28 | if (cc_z == 0) 29 | %pc = label 30 | \end{verbatim} 31 | 32 | \subsubsection*{Load-time constraints} 33 | \verb+label+ must be greater than \verb+pc+. Moreover, \verb+label+ must 34 | not go past the last address of the current DIF object. 35 | 36 | \subsubsection*{Failure modes} 37 | 38 | This instruction has no run-time failure modes beyond its constraints. 39 | -------------------------------------------------------------------------------- /specification/instr/not.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{NOT} 4 | \label{insn:not} 5 | \subsection*{NOT: negate a value} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{NOT \%rd, \%r1} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x0C} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{not} instruction negates the value found in 24 | \registerop{r1} and places the result into \registerop{rd}. 25 | \subsubsection*{Pseudocode} 26 | 27 | \begin{verbatim} 28 | %rd = ~%r1 29 | \end{verbatim} 30 | 31 | \subsubsection*{Load-time constraints} 32 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 33 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 34 | \registerop{r0}. 35 | 36 | \subsubsection*{Failure modes} 37 | 38 | This instruction has no run-time failure modes beyond its constraints. 39 | -------------------------------------------------------------------------------- /specification/instr/add.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{ADD} 4 | \label{insn:add} 5 | \subsection*{ADD: add two values} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{add \%r1, \%r2, \%rd} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x07} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | The \instruction{add} instruction adds the the values in 23 | \registerop{r1} and \registerop{r2} and pace the results in register 24 | \registerop{rd}. 25 | 26 | \subsubsection*{Pseudocode} 27 | 28 | \begin{verbatim} 29 | %rd = %r1 + %r2 30 | \end{verbatim} 31 | 32 | \subsubsection*{Load-time constraints} 33 | The registers \registerop{r1}, \registerop{r2} and \registerop{rd} must be 34 | valid registers and \registerop{rd} must not be \registerop{r0}. 35 | 36 | \subsubsection*{Failure modes} 37 | 38 | This instruction has no run-time failure modes beyond its constraints. 39 | -------------------------------------------------------------------------------- /specification/instr/or.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{OR} 4 | \label{insn:or} 5 | \subsection*{OR: Bitwise Or} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{OR \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x01} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | This instruction calculates the bitwise \emph{or} of the values found 24 | in registers \register{r1} and \register{r2}, placing the results in 25 | register \register{rd}. 26 | 27 | \subsubsection*{Pseudocode} 28 | 29 | \begin{verbatim} 30 | %rd = %r1 | %r2 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | The registers \registerop{r1}, \registerop{r2} and \registerop{rd} must be 35 | valid registers and \registerop{rd} must not be \registerop{r0}. 36 | 37 | \subsubsection*{Failure modes} 38 | 39 | This instruction has no run-time failure modes beyond its constraints. 40 | -------------------------------------------------------------------------------- /specification/instr/and.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{AND} 4 | \label{insn:and} 5 | \subsection*{AND: Bitwise And} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{AND \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x03} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | This instruction calculates the bitwise \emph{and} of the values found 24 | in registers \registerop{r1} and \registerop{r2}, placing the results 25 | in register \registerop{rd}. 26 | 27 | \subsubsection*{Pseudocode} 28 | 29 | \begin{verbatim} 30 | %rd = %r1 & %r2 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | The registers \registerop{r1}, \registerop{r2} and \registerop{rd} must be 35 | valid registers and \registerop{rd} must not be \registerop{r0}. 36 | 37 | \subsubsection*{Failure modes} 38 | 39 | This instruction has no run-time failure modes beyond its constraints. 40 | -------------------------------------------------------------------------------- /specification/instr/bgu.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{BGU} 4 | \label{insn:bgu} 5 | \subsection*{BGU: branch greater than, unsigned} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{BGU label} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,23,24,31} \\ 14 | \bitbox{8}{0x15} 15 | \bitbox{24}{label} 16 | \end{bytefield} 17 | \end{center} 18 | 19 | \subsubsection*{Description} 20 | 21 | The \instruction{bgu} instruction sets the \registerop{pc} to the new 22 | label if, and only if, the result of the previous comparison shows 23 | that \registerop{r1} was greater than \registerop{r2}. 24 | 25 | \subsubsection*{Pseudocode} 26 | 27 | \begin{verbatim} 28 | if ((cc_c | cc_z) == 0) 29 | pc = label; 30 | \end{verbatim} 31 | 32 | \subsubsection*{Load-time constraints} 33 | \verb+label+ must be greater than \verb+pc+. Moreover, \verb+label+ must 34 | not go past the last address of the current DIF object. 35 | 36 | \subsubsection*{Failure modes} 37 | 38 | This instruction has no run-time failure modes beyond its constraints. 39 | -------------------------------------------------------------------------------- /specification/instr/mul.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{MUL} 4 | \label{insn:mul} 5 | \subsection*{MUL: multiply two numbers} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{MUL \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x08} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{mul} instruction multiplies two numbers, contained in 24 | \registerop{r1} and \registerop{r2}, together and places the result in 25 | \registerop{rd}. 26 | 27 | \subsubsection*{Pseudocode} 28 | 29 | \begin{verbatim} 30 | %rd = %r1 * %r2 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | The registers \registerop{r1}, \registerop{r2} and \registerop{rd} must be 35 | valid registers and \registerop{rd} must not be \registerop{r0}. 36 | 37 | \subsubsection*{Failure modes} 38 | 39 | This instruction has no run-time failure modes beyond its constraints. 40 | -------------------------------------------------------------------------------- /specification/instr/bl.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{BL} 4 | \label{insn:bl} 5 | \subsection*{BL: branch less than} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{BL label} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,23,24,31} \\ 14 | \bitbox{8}{0x18} 15 | \bitbox{24}{label} 16 | \end{bytefield} 17 | \end{center} 18 | 19 | \subsubsection*{Description} 20 | 21 | The \instruction{bl} instruction jumps to the specified label if and 22 | only if the result of the previous comparison instruction indicated 23 | that the value in \registerop{r1} was strictly less than the value in 24 | \registerop{r2}. 25 | \subsubsection*{Pseudocode} 26 | 27 | \begin{verbatim} 28 | if (cc_n ^ cc_v) 29 | pc = label 30 | \end{verbatim} 31 | 32 | \subsubsection*{Load-time constraints} 33 | \verb+label+ must be greater than \verb+pc+. Moreover, \verb+label+ must 34 | not go past the last address of the current DIF object. 35 | 36 | \subsubsection*{Failure modes} 37 | 38 | This instruction has no run-time failure modes beyond its constraints. 39 | -------------------------------------------------------------------------------- /specification/instr/stb.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{STB} 4 | \label{insn:stb} 5 | \subsection*{STB: store a byte into memory} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{STB \%rd, \%r1} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x3C} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{stb} instruction takes a byte from \registerop{r1} 24 | and stores it into the memory location pointed to by \registerop{rd}. 25 | \subsubsection*{Pseudocode} 26 | 27 | \begin{verbatim} 28 | mem[%rd] = %r1 29 | \end{verbatim} 30 | 31 | \subsubsection*{Load-time constraints} 32 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 33 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 34 | \registerop{r0}. 35 | 36 | \subsubsection*{Failure modes} 37 | 38 | \textbf{XXXDS: This depends on dtrace\_canstore(). We have to enumerate these.} 39 | -------------------------------------------------------------------------------- /specification/instr/udiv.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{UDIV} 4 | \label{insn:udiv} 5 | \subsection*{UDIV: unsigned division} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{UDIV \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x0A} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{udiv} instruction divides the value contained in 24 | \registerop{r2} into that contained in \registerop{r1} placing the 25 | results into \registerop{rd}. 26 | 27 | \subsubsection*{Pseudocode} 28 | 29 | \begin{verbatim} 30 | %rd = %r1 / %r2 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | The registers \registerop{r1}, \registerop{r2} and \registerop{rd} must be 35 | valid registers and \registerop{rd} must not be \registerop{r0}. 36 | 37 | \subsubsection*{Failure modes} 38 | 39 | This instruction has no run-time failure modes beyond its constraints. 40 | -------------------------------------------------------------------------------- /specification/subr/memref.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{memref} 4 | \label{subr:memref} 5 | \subsection*{memref: return scratch memory} 6 | 7 | \subsubsection*{Subroutine prototype} 8 | 9 | \begin{verbatim} 10 | uintptr_t * memref(uintptr_t ptr, size_t length); 11 | \end{verbatim} 12 | 13 | \subsubsection*{Calling convention} 14 | 15 | \begin{description} 16 | \item[\registerop{arg0}] Pointer to memory 17 | \item[\registerop{arg1}] Length of scratch memory to use 18 | \item[\registerop{rd}] Pointer to a fixed size of scratch memory 19 | \end{description} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \subroutine{memref} subroutine allocates memory from scratch 24 | space and returns that memory to the caller. 25 | 26 | \subsubsection*{Pseudocode} 27 | 28 | \begin{verbatim} 29 | size = sizeof(uintptr_t) * 2 30 | memref = scratch_space 31 | memref[0] = stack[0].value 32 | memref[1] = stack[1].value 33 | scratch_space += size 34 | %rd = memref 35 | \end{verbatim} 36 | 37 | \subsubsection*{Failure modes} 38 | 39 | This subroutine has no run-time failure modes beyond its constraints. 40 | -------------------------------------------------------------------------------- /specification/subr/strtok.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{strtok} 4 | \label{subr:strtok} 5 | \subsection*{strtok: string tokenizing subroutine} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] pointer to the next token or NULL 11 | \item[\registerop{arg0}] string to tokenize 12 | \end{description} 13 | 14 | \subsubsection*{Description} 15 | 16 | The \subroutine{strtok} subroutine returns a sequential set of tokens 17 | from a string passed as its first argument, based on a separator 18 | passed as its second. Once the string has been exhausted NULL is 19 | returned. In order to find subsequent tokens NULL is passed as the 20 | first argument. See this operating system's \subroutine{strtok} 21 | manual page (strtok(3)) for an example. 22 | 23 | \subsubsection*{Pseudocode} 24 | 25 | \begin{verbatim} 26 | string = stack[0].value 27 | separator = stack[1].value 28 | %rd = strtok(string, separator) 29 | \end{verbatim} 30 | 31 | \subsubsection*{Failure modes} 32 | 33 | This subroutine has no run-time failure modes beyond its constraints. 34 | -------------------------------------------------------------------------------- /specification/instr/sub.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{SUB} 4 | \label{insn:sub} 5 | \subsection*{SUB: subtract the value in r2 from that in r1} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{SUB \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x06} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{sub} instruction takes the value in \registerop{r2} 24 | and subtracts it from that in \registerop{r1} placing the result in 25 | \registerop{rd}. 26 | 27 | \subsubsection*{Pseudocode} 28 | 29 | \begin{verbatim} 30 | %rd = %r1 - %r2 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | The registers \registerop{r1}, \registerop{r2} and \registerop{rd} must be 35 | valid registers and \registerop{rd} must not be \registerop{r0}. 36 | 37 | \subsubsection*{Failure modes} 38 | 39 | This instruction has no run-time failure modes beyond its constraints. 40 | -------------------------------------------------------------------------------- /specification/instr/xor.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{XOR} 4 | \label{insn:xor} 5 | \subsection*{XOR: Bitwise Exclusive Or} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{XOR \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x02} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | This instruction calculates the bitwise \emph{exclusive or} of the 24 | values found in registers \register{r1} and \register{r2}, placing the 25 | results in register \register{rd}. 26 | 27 | \subsubsection*{Pseudocode} 28 | 29 | \begin{verbatim} 30 | %rd = %r1 ^ %r2 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | The registers \registerop{r1}, \registerop{r2} and \registerop{rd} must be 35 | valid registers and \registerop{rd} must not be \registerop{r0}. 36 | 37 | \subsubsection*{Failure modes} 38 | 39 | This instruction has no run-time failure modes beyond its constraints. 40 | -------------------------------------------------------------------------------- /specification/instr/blu.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{BLU} 4 | \label{insn:blu} 5 | \subsection*{BLU: branch less than, unsigned} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{BL label} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,23,24,31} \\ 14 | \bitbox{8}{0x19} 15 | \bitbox{24}{label} 16 | \end{bytefield} 17 | \end{center} 18 | 19 | \subsubsection*{Description} 20 | 21 | The \instruction{blu} instruction jumps to the specified label if and 22 | only if the result of the previous comparison instruction indicated 23 | that the value in \registerop{r1} was strictly less than the value in 24 | \registerop{r2}. 25 | 26 | \subsubsection*{Pseudocode} 27 | 28 | \begin{verbatim} 29 | if (cc_c) 30 | pc = label 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | \verb+label+ must be greater than \verb+pc+. Moreover, \verb+label+ must 35 | not go past the last address of the current DIF object. 36 | 37 | \subsubsection*{Failure modes} 38 | 39 | This instruction has no run-time failure modes beyond its constraints. 40 | -------------------------------------------------------------------------------- /specification/instr/sll.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{SLL} 4 | \label{insn:sll} 5 | \subsection*{SLL: Shift Left Logical} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{SLL \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x04} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | This instruction shifts the value found in register \register{r1} 24 | \emph{left} by the number of bits found in register \register{r2}, 25 | placing the results in register \register{rd}. 26 | 27 | \subsubsection*{Pseudocode} 28 | 29 | \begin{verbatim} 30 | %rd = %r1 << %r2 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | The registers \registerop{r1}, \registerop{r2} and \registerop{rd} must be 35 | valid registers and \registerop{rd} must not be \registerop{r0}. 36 | 37 | \subsubsection*{Failure modes} 38 | 39 | This instruction has no run-time failure modes beyond its constraints. 40 | -------------------------------------------------------------------------------- /specification/instr/sth.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{STH} 4 | \label{insn:sth} 5 | \subsection*{STH: store a 16 bit value into memory} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{STH \%rd, \%r1} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x3D} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{sth} instruction takes a 16 bit value from \registerop{r1} 24 | and stores it into the memory location pointed to by \registerop{rd}. 25 | \subsubsection*{Pseudocode} 26 | 27 | \begin{verbatim} 28 | mem[%rd] = %r1 29 | \end{verbatim} 30 | 31 | \subsubsection*{Load-time constraints} 32 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 33 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 34 | \registerop{r0}. 35 | 36 | \subsubsection*{Failure modes} 37 | 38 | \textbf{XXXDS: This depends on dtrace\_canstore(). We have to enumerate these.} 39 | -------------------------------------------------------------------------------- /specification/instr/stw.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{STW} 4 | \label{insn:stw} 5 | \subsection*{STW: store a 32 bit value into memory} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{STW \%rd, \%r1} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x3E} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{stw} instruction takes a 32 bit value from \registerop{r1} 24 | and stores it into the memory location pointed to by \registerop{rd}. 25 | \subsubsection*{Pseudocode} 26 | 27 | \begin{verbatim} 28 | mem[%rd] = %r1 29 | \end{verbatim} 30 | 31 | \subsubsection*{Load-time constraints} 32 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 33 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 34 | \registerop{r0}. 35 | 36 | \subsubsection*{Failure modes} 37 | 38 | \textbf{XXXDS: This depends on dtrace\_canstore(). We have to enumerate these.} 39 | -------------------------------------------------------------------------------- /specification/instr/stx.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{STX} 4 | \label{insn:stx} 5 | \subsection*{STX: store a 64 bit value into memory} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{STX \%rd, \%r1} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x3F} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{stx} instruction takes a 64 bit value from \registerop{r1} 24 | and stores it into the memory location pointed to by \registerop{rd}. 25 | \subsubsection*{Pseudocode} 26 | 27 | \begin{verbatim} 28 | mem[%rd] = %r1 29 | \end{verbatim} 30 | 31 | \subsubsection*{Load-time constraints} 32 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 33 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 34 | \registerop{r0}. 35 | 36 | \subsubsection*{Failure modes} 37 | 38 | \textbf{XXXDS: This depends on dtrace\_canstore(). We have to enumerate these.} 39 | -------------------------------------------------------------------------------- /specification/instr/copys.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{COPYS} 4 | \label{insn:copys} 5 | \subsection*{COPYS: copy a string} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{COPYS \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x3B} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{copys} instruction copies bytes from the string 24 | pointed to by \registerop{r1} and returns them in \registerop{rd} 25 | bounded by a size placed into \registerop{r2}. 26 | 27 | \subsubsection*{Pseudocode} 28 | 29 | \begin{verbatim} 30 | %rd = copy(r1, r2) 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | The registers \registerop{r1}, \registerop{r2} and \registerop{rd} must be 35 | valid registers and \registerop{rd} must not be \registerop{r0}. 36 | 37 | \subsubsection*{Failure modes} 38 | 39 | This instruction has no run-time failure modes beyond its constraints. 40 | -------------------------------------------------------------------------------- /specification/instr/urem.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{UREM} 4 | \label{insn:urem} 5 | \subsection*{UREM: divide two numbers and store the remainder} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{UREM \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x0C} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{urem} instruction divides the value contained in 24 | \registerop{r2} into that contained in \registerop{r1} placing the 25 | remainder into \registerop{rd}. 26 | 27 | \subsubsection*{Pseudocode} 28 | 29 | \begin{verbatim} 30 | %rd = %r1 % %r2 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | The registers \registerop{r1}, \registerop{r2} and \registerop{rd} must be 35 | valid registers and \registerop{rd} must not be \registerop{r0}. 36 | 37 | \subsubsection*{Failure modes} 38 | 39 | This instruction has no run-time failure modes beyond its constraints. 40 | -------------------------------------------------------------------------------- /specification/instr/bge.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{BGE} 4 | \label{insn:bge} 5 | \subsection*{BGE: branch greater than or equal to} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{BGE label} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,23,24,31} \\ 14 | \bitbox{8}{0x16} 15 | \bitbox{24}{label} 16 | \end{bytefield} 17 | \end{center} 18 | 19 | \subsubsection*{Description} 20 | 21 | The \instruction{bge} instruction jumps to the supplied label if and 22 | only if the result of the previous comparison indicates that the 23 | value in register \registerop{r1} was greater than or equal to the 24 | value in \registerop{r2}. 25 | 26 | \subsubsection*{Pseudocode} 27 | 28 | \begin{verbatim} 29 | if ((cc_n ^ cc_v) == 0) 30 | pc = label; 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | \verb+label+ must be greater than \verb+pc+. Moreover, \verb+label+ must 35 | not go past the last address of the current DIF object. 36 | 37 | \subsubsection*{Failure modes} 38 | 39 | This instruction has no run-time failure modes beyond its constraints. 40 | -------------------------------------------------------------------------------- /specification/instr/ble.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{BLE} 4 | \label{insn:ble} 5 | \subsection*{BLE: branch less than or equal} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{BL label} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,23,24,31} \\ 14 | \bitbox{8}{0x1A} 15 | \bitbox{24}{label} 16 | \end{bytefield} 17 | \end{center} 18 | 19 | \subsubsection*{Description} 20 | 21 | The \instruction{ble} instruction jumps to the specified label if and 22 | only if the result of the previous comparison instruction indicated 23 | that the value in \registerop{r1} was less than, or equal to, the 24 | value in \registerop{r2}. 25 | 26 | \subsubsection*{Pseudocode} 27 | 28 | \begin{verbatim} 29 | if (cc_z | (cc_n ^ cc_v)) 30 | pc = label 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | \verb+label+ must be greater than \verb+pc+. Moreover, \verb+label+ must 35 | not go past the last address of the current DIF object. 36 | 37 | \subsubsection*{Failure modes} 38 | 39 | This instruction has no run-time failure modes beyond its constraints. 40 | -------------------------------------------------------------------------------- /specification/instr/bleu.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{BLEU} 4 | \label{insn:bleu} 5 | \subsection*{BLEU: branch less than or equal, unsigned} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{BLEU label} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,23,24,31} \\ 14 | \bitbox{8}{0x1B} 15 | \bitbox{24}{label} 16 | \end{bytefield} 17 | \end{center} 18 | 19 | \subsubsection*{Description} 20 | 21 | The \instruction{bleu} instruction jumps to the specified label if and 22 | only if the result of the previous comparison instruction indicated 23 | that the value in \registerop{r1} was less than, or equal to, the 24 | value in \registerop{r2}. 25 | 26 | \subsubsection*{Pseudocode} 27 | 28 | \begin{verbatim} 29 | if (cc_c | cc_z) 30 | pc = label 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | \verb+label+ must be greater than \verb+pc+. Moreover, \verb+label+ must 35 | not go past the last address of the current DIF object. 36 | 37 | \subsubsection*{Failure modes} 38 | 39 | This instruction has no run-time failure modes beyond its constraints. 40 | -------------------------------------------------------------------------------- /specification/instr/ldga.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{LDGA} 4 | \label{insn:ldga} 5 | \subsection*{LDGA: load a DTrace built-in variable} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{LDGA \%rd, var, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31}\\ 14 | \bitbox{8}{op} 15 | \bitbox{8}{var} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{ldga} instruction looks up the value of a DTrace 24 | built-in variable based on the value in \registerop{var} with an 25 | optional array index in the register \register{r2}. \\ 26 | 27 | Unlike the \instruction{ldgs}, the variable identifier is 8 bits long, and 28 | the other 8 bits are used to identify the register which contains the index of 29 | the array. 30 | 31 | \subsubsection*{Pseudocode} 32 | 33 | \begin{verbatim} 34 | index = %r2 35 | %rd = var[index] 36 | \end{verbatim} 37 | 38 | \subsubsection*{Failure modes} 39 | 40 | This instruction has no run-time failure modes beyond its constraints. 41 | -------------------------------------------------------------------------------- /specification/instr/bgeu.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{BGEU} 4 | \label{insn:bgeu} 5 | \subsection*{BGEU: branch greater than or equal to, unsigned} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{BGEU label} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,23,24,31} \\ 14 | \bitbox{8}{0x17} 15 | \bitbox{24}{label} 16 | \end{bytefield} 17 | \end{center} 18 | 19 | \subsubsection*{Description} 20 | 21 | The \instruction{bgeu} instruction jumps to the supplied label if and 22 | only if the result of the previous comparison indicates that the 23 | value in register \registerop{r1} was greater than or equal to the 24 | value in \registerop{r2}. 25 | 26 | \subsubsection*{Pseudocode} 27 | 28 | \begin{verbatim} 29 | if (cc_c == 0) 30 | pc = label; 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | \verb+label+ must be greater than \verb+pc+. Moreover, \verb+label+ must 35 | not go past the last address of the current DIF object. 36 | 37 | \subsubsection*{Failure modes} 38 | 39 | This instruction has no run-time failure modes beyond its constraints. 40 | -------------------------------------------------------------------------------- /specification/instr/pushtr.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{PUSHTR} 4 | \label{insn:pushtr} 5 | \subsection*{PUSHTR: push a reference onto the stack} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{PUSHTR type, \%r2, \%rs} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x30} 15 | \bitbox{8}{type} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rs} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{pushtr} instruction pushes a reference, contained in 24 | the \registerop{rs} register onto the stack. The length is stored for 25 | a string along with the value. For a numeric value the size of that 26 | value is stored. 27 | 28 | \subsubsection*{Pseudocode} 29 | 30 | \begin{verbatim} 31 | value = %rs 32 | if type is string: 33 | size = strlen(value) 34 | else: 35 | size = %r2 36 | 37 | stack[++index].size = size 38 | stack[index].value = value 39 | \end{verbatim} 40 | 41 | \subsubsection*{Failure modes} 42 | 43 | This instruction has no run-time failure modes beyond its constraints. 44 | -------------------------------------------------------------------------------- /specification/instr/tst.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{TST} 4 | \label{insn:tst} 5 | \subsection*{TST: Test the value in r1} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{TST \%r1} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x0F} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{tst} instruction checks the value in \registerop{r1} 24 | to see if it is zero (0). Only the Z bit (cc\_z) is set by this 25 | instruction, all other comparison result registers, listed in 26 | Table\ref{tbl:cmp-vars} are cleared. 27 | 28 | \subsubsection*{Pseudocode} 29 | 30 | \begin{verbatim} 31 | cc_n = cc_v = cc_c = 0; 32 | cc_z = %r1 == 0; 33 | \end{verbatim} 34 | 35 | \subsubsection*{Load-time constraints} 36 | The register \registerop{r1} be a valid register, \registerop{rd} and 37 | \registerop{r2} must be \registerop{r0}. 38 | 39 | \subsubsection*{Failure modes} 40 | 41 | This instruction has no run-time failure modes beyond its constraints. 42 | -------------------------------------------------------------------------------- /specification/instr/sra.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{SRA} 4 | \label{insn:sra} 5 | \subsection*{SRA: Shift Right Arithmetic} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{SRA \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x2E} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{sra} instruction shifts the value in \registerop{r1} right by 24 | the number of bits indicated in \registerop{r2}, placing the results in register 25 | \registerop{rd}. This instruction only operates on \textbf{signed} integers. 26 | 27 | \subsubsection*{Pseudocode} 28 | 29 | \begin{verbatim} 30 | %rd = %r1 >> %r2 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | The registers \registerop{r1}, \registerop{r2} and \registerop{rd} must be 35 | valid registers and \registerop{rd} must not be \registerop{r0}. 36 | 37 | \subsubsection*{Failure modes} 38 | 39 | This instruction has no run-time failure modes beyond its constraints. 40 | -------------------------------------------------------------------------------- /specification/instr/rldx.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{RLDX} 4 | \label{insn:rldx} 5 | \subsection*{RLDX: restricted load of a 64 bit quantity } 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{RLDX \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x4D} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{rldx} instruction performs a privilege check on the 24 | memory it is about to read from before loading a 64 bit quantity into 25 | \registerop{rd}, indexed by \registerop{r1}. 26 | 27 | \subsubsection*{Pseudocode} 28 | 29 | \begin{verbatim} 30 | %rd = mem[%r1] 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 35 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 36 | \registerop{r0}. 37 | 38 | \subsubsection*{Failure modes} 39 | 40 | \textbf{XXXDS: This depends on dtrace\_canload(). We have to enumerate these.} 41 | -------------------------------------------------------------------------------- /specification/subr/toupper.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{toupper} 4 | \label{subr:toupper} 5 | \subsection*{toupper: convert a string to upper case} 6 | 7 | \subsubsection*{Subroutine prototype} 8 | 9 | \begin{verbatim} 10 | char * toupper(const char *string); 11 | \end{verbatim} 12 | 13 | \subsubsection*{Calling convention} 14 | 15 | \begin{description} 16 | \item[\registerop{rd}] A string with only upper case letters 17 | \item[\registerop{arg0}] Pointer to the string 18 | \end{description} 19 | 20 | \subsubsection*{Description} 21 | 22 | The \subroutine{toupper} subroutine converts the characters of the 23 | string supplied as its only argument into upper case and returns the 24 | resulting string. 25 | 26 | \subsubsection*{Pseudocode} 27 | 28 | \begin{verbatim} 29 | string = stack[0].value 30 | destination = scratch_space 31 | 32 | for i = 0 ... len(string): 33 | c = string[i] 34 | if c is lowercase: 35 | c = uppercase(c) 36 | destination[i] = c 37 | 38 | scratch_space += len(string) 39 | %rd = destination 40 | \end{verbatim} 41 | 42 | \subsubsection*{Failure modes} 43 | 44 | This subroutine has no run-time failure modes beyond its constraints. 45 | -------------------------------------------------------------------------------- /specification/instr/rldsb.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{RLDSB} 4 | \label{insn:rldsb} 5 | \subsection*{RLDSB: restricted load of a signed 8 bit quantity} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{RLDSB \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x47} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{rldsb} instruction performs a privilege check on the 24 | memory it is about to read from before loading a signed, 8 bit, 25 | quantity into \registerop{rd}, indexed by \registerop{r1}. 26 | 27 | \subsubsection*{Pseudocode} 28 | 29 | \begin{verbatim} 30 | %rd = mem[%r1] 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 35 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 36 | \registerop{r0}. 37 | 38 | \subsubsection*{Failure modes} 39 | 40 | \textbf{XXXDS: This depends on dtrace\_canload(). We have to enumerate these.} 41 | -------------------------------------------------------------------------------- /specification/instr/rldsh.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{RLDSH} 4 | \label{insn:rldsh} 5 | \subsection*{RLDSH: restricted load of a signed 16 bit quantity} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{RLDSH \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x48} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{rldsh} instruction performs a privilege check on the 24 | memory it is about to read from before loading a signed, 16 bit, 25 | quantity into \registerop{rd}, indexed by \registerop{r1}. 26 | 27 | \subsubsection*{Pseudocode} 28 | 29 | \begin{verbatim} 30 | %rd = mem[%r1] 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 35 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 36 | \registerop{r0}. 37 | 38 | \subsubsection*{Failure modes} 39 | 40 | \textbf{XXXDS: This depends on dtrace\_canload(). We have to enumerate these.} 41 | -------------------------------------------------------------------------------- /specification/instr/rldsw.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{RLDSW} 4 | \label{insn:rldsw} 5 | \subsection*{RLDSW: restricted load of a signed 32 bit quantity} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{RLDSW \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x49} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{rldsw} instruction performs a privilege check on the 24 | memory it is about to read from before loading a signed, 32 bit, 25 | quantity into \registerop{rd}, indexed by \registerop{r1}. 26 | 27 | \subsubsection*{Pseudocode} 28 | 29 | \begin{verbatim} 30 | %rd = mem[%r1] 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 35 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 36 | \registerop{r0}. 37 | 38 | \subsubsection*{Failure modes} 39 | 40 | \textbf{XXXDS: This depends on dtrace\_canload(). We have to enumerate these.} 41 | -------------------------------------------------------------------------------- /specification/subr/strstr.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{strstr} 4 | \label{subr:strstr} 5 | \subsection*{strstr: locate a string within a string} 6 | 7 | \subsubsection*{Subroutine prototype} 8 | 9 | \begin{verbatim} 10 | char * strstr(const char *big, const char *little); 11 | \end{verbatim} 12 | 13 | \subsubsection*{Calling convention} 14 | 15 | \begin{description} 16 | \item[\registerop{arg0}] Pointer to the string to be searched through 17 | \item[\registerop{arg1}] Pointer to the string to search for 18 | \item[\registerop{rd}] Pointer to the string located or NULL if not found 19 | \end{description} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \subroutine{strstr} subroutine search a string, passed as its first 24 | argument, for a sub-string, passed as the second argument. If the 25 | sub-string is found a pointer to it is returned to the caller, 26 | otherwise NULL is returned. 27 | 28 | \subsubsection*{Pseudocode} 29 | 30 | \begin{verbatim} 31 | big = stack[0].value 32 | little = stack[1].value 33 | %rd = strstr(big, little) 34 | \end{verbatim} 35 | 36 | \subsubsection*{Failure modes} 37 | 38 | This subroutine has no run-time failure modes beyond its constraints. 39 | -------------------------------------------------------------------------------- /specification/instr/rldub.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{RLDUB} 4 | \label{insn:rldub} 5 | \subsection*{RLDUB: restricted load of an unsigned 8 bit quantity} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{RLDUB \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x4A} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{rldub} instruction performs a privilege check on the 24 | memory it is about to read from before loading an unsigned, 8 bit, 25 | quantity into \registerop{rd}, indexed by \registerop{r1}. 26 | 27 | \subsubsection*{Pseudocode} 28 | 29 | \begin{verbatim} 30 | %rd = mem[%r1] 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 35 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 36 | \registerop{r0}. 37 | 38 | \subsubsection*{Failure modes} 39 | 40 | \textbf{XXXDS: This depends on dtrace\_canload(). We have to enumerate these.} 41 | -------------------------------------------------------------------------------- /specification/instr/rlduh.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{RLDUH} 4 | \label{insn:rlduh} 5 | \subsection*{RLDUH: restricted load of an unsigned 16 bit quantity} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{RLDUH \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x4B} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{rlduh} instruction performs a privilege check on the 24 | memory it is about to read from before loading an unsigned, 16 bit, 25 | quantity into \registerop{rd}, indexed by \registerop{r1}. 26 | 27 | \subsubsection*{Pseudocode} 28 | 29 | \begin{verbatim} 30 | %rd = mem[%r1] 31 | \end{verbatim} 32 | \subsubsection*{Load-time constraints} 33 | 34 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 35 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 36 | \registerop{r0}. 37 | 38 | \subsubsection*{Failure modes} 39 | 40 | \textbf{XXXDS: This depends on dtrace\_canload(). We have to enumerate these.} 41 | -------------------------------------------------------------------------------- /specification/instr/rlduw.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{RLDUW} 4 | \label{insn:rlduw} 5 | \subsection*{RLDUW: restricted load of an unsigned 32 bit quantity} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{RLDUW \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x4C} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{rlduw} instruction performs a privilege check on the 24 | memory it is about to read from before loading an unsigned, 32 bit, 25 | quantity into \registerop{rd}, indexed by \registerop{r1}. 26 | 27 | \subsubsection*{Pseudocode} 28 | 29 | \begin{verbatim} 30 | %rd = mem[%r1] 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 35 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 36 | \registerop{r0}. 37 | 38 | \subsubsection*{Failure modes} 39 | 40 | \textbf{XXXDS: This depends on dtrace\_canload(). We have to enumerate these.} 41 | -------------------------------------------------------------------------------- /specification/subr/tolower.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{tolower} 4 | \label{subr:tolower} 5 | \subsection*{tolower: convert a string to all lower case characters} 6 | 7 | \subsubsection*{Subroutine prototype} 8 | 9 | \begin{verbatim} 10 | char * tolower(const char *string); 11 | \end{verbatim} 12 | 13 | \subsubsection*{Calling convention} 14 | 15 | \begin{description} 16 | \item[\registerop{rd}] An all lower case string 17 | \item[\registerop{arg0}] Pointer to the string 18 | \end{description} 19 | 20 | \subsubsection*{Description} 21 | 22 | The \subroutine{tolower} subroutine returns a string converts the 23 | characters of the string supplied as its only argument into lower case 24 | and returns the resulting string. 25 | 26 | \subsubsection*{Pseudocode} 27 | 28 | \begin{verbatim} 29 | string = stack[0].value 30 | destination = scratch_space 31 | 32 | for i = 0 ... len(string): 33 | c = string[i] 34 | if c is uppercase: 35 | c = lowercase(c) 36 | destination[i] = c 37 | 38 | scratch_space += len(string) 39 | %rd = destination 40 | \end{verbatim} 41 | 42 | \subsubsection*{Failure modes} 43 | 44 | This subroutine has no run-time failure modes beyond its constraints. 45 | -------------------------------------------------------------------------------- /specification/instr/srl.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{SRL} 4 | \label{insn:srl} 5 | \subsection*{SRL: Shift Right Logical} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{SRL \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x05} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | This instruction shifts the value found in register \register{r1} 24 | \emph{right} by the number of bits found in register \register{r2}, 25 | placing the results in register \register{rd}. This instruction only 26 | operates on \textbf{unsigned} integers. 27 | 28 | \subsubsection*{Pseudocode} 29 | 30 | \begin{verbatim} 31 | %rd = %r1 >> %r2 32 | \end{verbatim} 33 | 34 | \subsubsection*{Constraints} 35 | 36 | \subsubsection*{Load-time constraints} 37 | The registers \registerop{r1}, \registerop{r2} and \registerop{rd} must be 38 | valid registers and \registerop{rd} must not be \registerop{r0}. 39 | 40 | \subsubsection*{Failure modes} 41 | 42 | This instruction has no run-time failure modes beyond its constraints. 43 | -------------------------------------------------------------------------------- /specification/instr/allocs.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{ALLOCS} 4 | \label{insn:allocs} 5 | \subsection*{ALLOCS: allocate a string} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{ALLOCS \%rd, \%r1} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x3A} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{allocs} instruction allocates a string in the DIF 24 | scratch space, based on the size in \registerop{r1} and returns the 25 | pointer to that string in register \registerop{rd}. A failed 26 | allocation returns a 0. 27 | 28 | \subsubsection*{Pseudocode} 29 | 30 | \begin{verbatim} 31 | ptr = scratch_space; 32 | scratch_space += size; 33 | %rd = ptr 34 | \end{verbatim} 35 | 36 | \subsubsection*{Load-time constraints} 37 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 38 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 39 | \registerop{r0}. 40 | 41 | \subsubsection*{Failure modes} 42 | 43 | This instruction has no run-time failure modes beyond its constraints. 44 | -------------------------------------------------------------------------------- /specification/subr/substr.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{substr} 4 | \label{subr:substr} 5 | \subsection*{substr: return a sub string of a string} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] a string representing the substring 11 | \item[\registerop{arg0}] string from which to derive a sub-string 12 | \item[\registerop{arg2}] index of substring 13 | \item[\registerop{arg2}] length of substring 14 | \end{description} 15 | 16 | \subsubsection*{Description} 17 | 18 | The \subroutine{substr} routine returns a sub-string of a string, 19 | passed as the first argument, starting from a byte index passed as the 20 | second argument. An optional third argument can be used to bound the 21 | resulting string. If the optional bounding argument is not supplied 22 | then the sub-string includes all bytes up to and including the 23 | terminating NUL character. 24 | 25 | \subsubsection*{Pseudocode} 26 | 27 | \begin{verbatim} 28 | string = stack[0].value 29 | index = stack[1].value 30 | length = stack[2].value 31 | %rd = substr(string, index, length) 32 | \end{verbatim} 33 | 34 | \subsubsection*{Failure modes} 35 | 36 | This subroutine has no run-time failure modes beyond its constraints. 37 | -------------------------------------------------------------------------------- /specification/instr/sdiv.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{SDIV} 4 | \label{insn:sdiv} 5 | \subsection*{SDIV: signed division} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{SDIV \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x09} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{sdiv} instruction divides the value contained in 24 | \registerop{r2} into that contained in \registerop{r1} placing the 25 | results into \registerop{rd}. The values in both \registerop{r1} and 26 | \registerop{r2} are first promoted to signed, 64 bit values, before 27 | the division operation is carried out. 28 | 29 | \subsubsection*{Pseudocode} 30 | 31 | \begin{verbatim} 32 | %rd = (int64_t)%r1 / (inst64_t)%r2 33 | \end{verbatim} 34 | 35 | \subsubsection*{Load-time constraints} 36 | The registers \registerop{r1}, \registerop{r2} and \registerop{rd} must be 37 | valid registers and \registerop{rd} must not be \registerop{r0}. 38 | 39 | \subsubsection*{Failure modes} 40 | 41 | This instruction has no run-time failure modes beyond its constraints. 42 | -------------------------------------------------------------------------------- /specification/subr/strjoin.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{strjoin} 4 | \label{subr:strjoin} 5 | \subsection*{strjoin: join two strings and return the result} 6 | 7 | \subsubsection*{Calling convention} 8 | 9 | \begin{description} 10 | \item[\registerop{rd}] Pointer to the combined string 11 | \item[\registerop{arg0}] Pointer to the first string 12 | \item[\registerop{arg1}] Pointer to the second string 13 | \end{description} 14 | 15 | \subsubsection*{Description} 16 | 17 | The \subroutine{strjoin} subroutine concatenates the two strings 18 | passed to it as arguments and returns the combined string to the 19 | caller. 20 | 21 | \subsubsection*{Pseudocode} 22 | 23 | \begin{verbatim} 24 | first = stack[0].value 25 | second = stack[1].value 26 | combined = scratch_space 27 | 28 | if (not can_load(first)) or (not can_load(second)): 29 | %rd = 0 30 | return 31 | 32 | if no room in scratch: 33 | %rd = 0 34 | return 35 | 36 | for i = 0 ... len(first): 37 | combined[i] = first[i] 38 | 39 | for j = 0 ... len(second): 40 | combined[i + j] = second[j] 41 | 42 | scratch_space += len(combined) 43 | %rd = combined 44 | \end{verbatim} 45 | 46 | \subsubsection*{Failure modes} 47 | 48 | This subroutine has no run-time failure modes beyond its constraints. 49 | -------------------------------------------------------------------------------- /specification/instr/uldub.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{ULDUB} 4 | \label{insn:uldub} 5 | \subsection*{ULDUB: load unsigned 8 bit quantity from user space} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{ULDUB \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x43} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{uldub} instruction loads a unsigned 8 bit quantity from memory 24 | in a user space process into the \registerop{rd} register indexed by 25 | \registerop{r1}. This is an \textbf{unsigned} instruction and will not perform 26 | sign extension in any case. 27 | 28 | 29 | \subsubsection*{Pseudocode} 30 | 31 | \begin{verbatim} 32 | %rd = umem[r1] 33 | \end{verbatim} 34 | 35 | \subsubsection*{Load-time constraints} 36 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 37 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 38 | \registerop{r0}. 39 | 40 | \subsubsection*{Failure modes} 41 | 42 | This instruction can cause a page fault if the memory it is trying to access 43 | is not paged in. 44 | -------------------------------------------------------------------------------- /specification/instr/ulduh.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{ULDUH} 4 | \label{insn:ulduh} 5 | \subsection*{ULDUH: load an unsigned 16 bit quantity from user space} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{ULDUH \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x44} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{ulduh} instruction loads an unsigned, 16 bit, quantity from 24 | memory in a user space process into the \registerop{rd} register, indexed by 25 | \registerop{r1}. This is an \textbf{unsigned} instruction and will not perform 26 | sign extension in any case. 27 | 28 | 29 | \subsubsection*{Pseudocode} 30 | 31 | \begin{verbatim} 32 | %rd = umem[r1] 33 | \end{verbatim} 34 | 35 | \subsubsection*{Load-time constraints} 36 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 37 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 38 | \registerop{r0}. 39 | 40 | \subsubsection*{Failure modes} 41 | 42 | This instruction can cause a page fault if the memory it is trying to access 43 | is not paged in. 44 | -------------------------------------------------------------------------------- /specification/instr/ulduw.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{ULDUW} 4 | \label{insn:ulduw} 5 | \subsection*{ULDUW: load an unsigned 32 bit quantity from user space} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{ULDUW \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x45} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{ulduw} instruction loads an unsigned 32 bit quantity from 24 | memory in a user space process into the \registerop{rd} register, indexed by 25 | \registerop{r1}. This is an \textbf{unsigned} instruction and will not perform 26 | sign extension in any case. 27 | 28 | 29 | \subsubsection*{Pseudocode} 30 | 31 | \begin{verbatim} 32 | %rd = umem[r1] 33 | \end{verbatim} 34 | 35 | \subsubsection*{Load-time constraints} 36 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 37 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 38 | \registerop{r0}. 39 | 40 | \subsubsection*{Failure modes} 41 | 42 | This instruction can cause a page fault if the memory it is trying to access 43 | is not paged in. 44 | -------------------------------------------------------------------------------- /specification/instr/uldx.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{ULDX} 4 | \label{insn:uldx} 5 | \subsection*{ULDX: load a 64 bit value from user program memory} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{ULDX \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x46} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{uldx} instruction loads a 64 bit value from a user space 24 | program's memory into the \registerop{rd} register, indexed by \registerop{r1}. 25 | Much like conventional RISC architectures, it does not perform sign extension, 26 | as this is considered the widest type. 27 | 28 | \subsubsection*{Pseudocode} 29 | 30 | \begin{verbatim} 31 | %rd = umem[r1] 32 | \end{verbatim} 33 | 34 | \subsubsection*{Load-time constraints} 35 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 36 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 37 | \registerop{r0}. 38 | 39 | \subsubsection*{Failure modes} 40 | 41 | This instruction can cause a page fault if the memory it is trying to access 42 | is not paged in. 43 | -------------------------------------------------------------------------------- /specification/instr/uldsb.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{ULDSB} 4 | \label{insn:uldsb} 5 | \subsection*{ULDSB: load signed 8 bit quantity from user space} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{ULDSB \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x40} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{uldsb} instruction loads a signed 8 bit quantity from memory in 24 | a user space process into the \registerop{rd} register, indexed by 25 | \registerop{r1}. This instruction is a \textbf{signed} instruction and will 26 | perform sign extension on the resulting register when applicable. 27 | 28 | \subsubsection*{Pseudocode} 29 | 30 | \begin{verbatim} 31 | %rd = umem[r1] 32 | \end{verbatim} 33 | 34 | \subsubsection*{Load-time constraints} 35 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 36 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 37 | \registerop{r0}. 38 | 39 | \subsubsection*{Failure modes} 40 | 41 | This instruction can cause a page fault if the memory it is trying to access 42 | is not paged in. 43 | -------------------------------------------------------------------------------- /specification/instr/uldsh.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{ULDSH} 4 | \label{insn:uldsh} 5 | \subsection*{ULDSH: load a signed 16 bit quantity from user space} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{ULDSH \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x41} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{uldsh} instruction loads a signed, 16 bit, quantity from memory 24 | in a user space process into the \registerop{rd} register, indexed by 25 | \registerop{r1}. This instruction is a \textbf{signed} instruction and will 26 | perform sign extension on the resulting register when applicable. 27 | 28 | \subsubsection*{Pseudocode} 29 | 30 | \begin{verbatim} 31 | %rd = umem[r1] 32 | \end{verbatim} 33 | 34 | \subsubsection*{Load-time constraints} 35 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 36 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 37 | \registerop{r0}. 38 | 39 | \subsubsection*{Failure modes} 40 | 41 | This instruction can cause a page fault if the memory it is trying to access 42 | is not paged in. 43 | -------------------------------------------------------------------------------- /specification/instr/uldsw.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{ULDSW} 4 | \label{insn:uldsw} 5 | \subsection*{ULDSW: load a signed 32 bit quantity from user space} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{ULDSW \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x42} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{uldsw} instruction loads a signed 32 bit quantity from memory 24 | in a user space process into the \registerop{rd} register, indexed by 25 | \registerop{r1}. This instruction is a \textbf{signed} instruction and will 26 | perform sign extension on the resulting register when applicable. 27 | 28 | \subsubsection*{Pseudocode} 29 | 30 | \begin{verbatim} 31 | %rd = umem[r1] 32 | \end{verbatim} 33 | 34 | \subsubsection*{Load-time constraints} 35 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 36 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 37 | \registerop{r0}. 38 | 39 | \subsubsection*{Failure modes} 40 | 41 | This instruction can cause a page fault if the memory it is trying to access 42 | is not paged in. 43 | -------------------------------------------------------------------------------- /specification/instr/cmp.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{CMP} 4 | \label{insn:cmp} 5 | \subsection*{CMP: compare two values} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{CMP \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x0E} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{cmp} instruction compares the values in 24 | \registerop{r1} and \registerop{r2}, via subtraction, and sets the 25 | various comparison bits based on the results. The comparison bits, 26 | shown in Table\ref{tbl:cmp-vars}, are used by the branch instructions 27 | to make decisions about where the program will execute next. 28 | 29 | \subsubsection*{Pseudocode} 30 | 31 | \begin{verbatim} 32 | cc_r = %r1 - %r2; 33 | cc_n = cc_r < 0; 34 | cc_z = cc_r == 0; 35 | cc_v = 0; 36 | cc_c = %r1 < %r2; 37 | \end{verbatim} 38 | 39 | \subsubsection*{Load-time constraints} 40 | The registers \registerop{r1} and \registerop{r2} must be valid registers, 41 | \registerop{rd} must be \registerop{r0}. 42 | 43 | \subsubsection*{Failure modes} 44 | 45 | This instruction has no run-time failure modes beyond its constraints. 46 | -------------------------------------------------------------------------------- /specification/instr/ldub.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{LDUB} 4 | \label{insn:ldub} 5 | \subsection*{LDUB: load an unsigned 8 bit value} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{LDUB \%rd, \%r1} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x1F} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{ldub} instruction loads the value pointed to by \registerop{r1} 24 | into \registerop{rd}, the results register. This is an \textbf{unsigned} 25 | instruction and will not perform sign extension in any case. 26 | 27 | \subsubsection*{Pseudocode} 28 | 29 | \begin{verbatim} 30 | %rd = %r1 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 35 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 36 | \registerop{r0}. 37 | 38 | This instruction is \textbf{privileged} and thus performs no access control 39 | checks. It is up to the OpenDTrace implementation to implement that constraint. 40 | 41 | \subsubsection*{Failure modes} 42 | 43 | This instruction has no run-time failure modes beyond its constraints. 44 | -------------------------------------------------------------------------------- /specification/instr/ldx.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{LDX} 4 | \label{insn:ldx} 5 | \subsection*{LDX: load 64 bit value} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{LDX \%rd, \%r1} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x22} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{ldx} instruction loads a 64 bit value pointed to by 24 | \registerop{r1} into \registerop{rd}. Much like conventional RISC architectures, 25 | it does not perform sign extension, as this is considered to be the widest type. 26 | 27 | \subsubsection*{Pseudocode} 28 | 29 | \begin{verbatim} 30 | %rd = %r1 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 35 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 36 | \registerop{r0}. 37 | 38 | This instruction is \textbf{privileged} and thus performs no access control 39 | checks. It is up to the OpenDTrace implementation to implement that constraint. 40 | 41 | \subsubsection*{Failure modes} 42 | 43 | This instruction has no run-time failure modes beyond its constraints. 44 | -------------------------------------------------------------------------------- /specification/instr/lduh.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{LDUH} 4 | \label{insn:lduh} 5 | \subsection*{LDUH: load an unsigned 16 bit value} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{LDSB \%rd, \%r1} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x20} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{lduh} instruction loads a 16-bit value pointed to by 24 | \registerop{r1} into \registerop{rd}, the results register. This is an 25 | \textbf{unsigned} instruction and will not perform sign extension in any case. 26 | 27 | \subsubsection*{Pseudocode} 28 | 29 | \begin{verbatim} 30 | %rd = %r1 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 35 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 36 | \registerop{r0}. 37 | 38 | This instruction is \textbf{privileged} and thus performs no access control 39 | checks. It is up to the OpenDTrace implementation to implement that constraint. 40 | 41 | \subsubsection*{Failure modes} 42 | 43 | This instruction has no run-time failure modes beyond its constraints. 44 | -------------------------------------------------------------------------------- /specification/instr/lduw.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{LDUW} 4 | \label{insn:lduw} 5 | \subsection*{LDUW: load an unsigned 32 bit value} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{LDSB \%rd, \%r1} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x21} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{lduw} instruction loads a 32-bit value pointed to by 24 | \registerop{r1} into \registerop{rd}, the results register. This is an 25 | \textbf{unsigned} instruction and will not perform sign extension in any case. 26 | 27 | \subsubsection*{Pseudocode} 28 | 29 | \begin{verbatim} 30 | %rd = %r1 31 | \end{verbatim} 32 | 33 | \subsubsection*{Load-time constraints} 34 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 35 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 36 | \registerop{r0}. 37 | 38 | This instruction is \textbf{privileged} and thus performs no access control 39 | checks. It is up to the OpenDTrace implementation to implement that constraint. 40 | 41 | \subsubsection*{Failure modes} 42 | 43 | This instruction has no run-time failure modes beyond its constraints. 44 | -------------------------------------------------------------------------------- /specification/instr/scmp.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{SCMP} 4 | \label{insn:scmp} 5 | \subsection*{SCMP: compare two strings} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{SCMP \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x27} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{scmp} intruction compares the strings pointed to by 24 | \registerop{r1} and \registerop{r2} and sets the comparison bits for 25 | the DIF interpreter based on the result. The length of the the 26 | strings is derived by DTrace itself and the comparison is bounded by 27 | the \verb|DTRACEOPT_STRSIZE| option set for the system. 28 | 29 | \subsubsection*{Pseudocode} 30 | 31 | \begin{verbatim} 32 | cc_r = strncmp(r1, r2, size); 33 | 34 | cc_n = cc_r < 0; 35 | cc_z = cc_r == 0; 36 | cc_v = cc_c = 0; 37 | \end{verbatim} 38 | 39 | \subsubsection*{Load-time constraints} 40 | The registers \registerop{r1} and \registerop{r2} must be valid registers, 41 | \registerop{rd} must be \registerop{r0}. 42 | 43 | \subsubsection*{Failure modes} 44 | 45 | The memory locations in \registerop{r1} or \registerop{r2} may be paged out, 46 | which causes a page fault. 47 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | BSD 2-Clause License 2 | 3 | Copyright (c) 2017, opendtrace 4 | All rights reserved. 5 | 6 | Redistribution and use in source and binary forms, with or without 7 | modification, are permitted provided that the following conditions are met: 8 | 9 | * Redistributions of source code must retain the above copyright notice, this 10 | list of conditions and the following disclaimer. 11 | 12 | * Redistributions in binary form must reproduce the above copyright notice, 13 | this list of conditions and the following disclaimer in the documentation 14 | and/or other materials provided with the distribution. 15 | 16 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 19 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 20 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 22 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 23 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 24 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 25 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26 | -------------------------------------------------------------------------------- /specification/instr/ldsb.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{LDSB} 4 | \label{insn:ldsb} 5 | \subsection*{LDSB: load an 8 bit value} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{LDSB \%rd, \%r1} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x1C} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{ldsb} instruction loads the value pointed to by \registerop{r1} 24 | into \registerop{rd}, the results register. This instruction is a 25 | \textbf{signed} instruction and will perform sign extension on the resulting 26 | register when applicable. 27 | 28 | \subsubsection*{Pseudocode} 29 | 30 | \begin{verbatim} 31 | %rd = %r1 32 | \end{verbatim} 33 | 34 | \subsubsection*{Load-time constraints} 35 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 36 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 37 | \registerop{r0}. 38 | 39 | This instruction is \textbf{privileged} and thus performs no access control 40 | checks. It is up to the OpenDTrace implementation to implement that constraint. 41 | 42 | \subsubsection*{Failure modes} 43 | 44 | This instruction has no run-time failure modes beyond its constraints. 45 | -------------------------------------------------------------------------------- /specification/subr/bcopy.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{bcopy} 4 | \label{subr:bcopy} 5 | \subsection*{bcopy: copy bytes from source to destination bounded by a 6 | size} 7 | 8 | \subsubsection*{Subroutine prototype} 9 | 10 | \begin{verbatim} 11 | void bcopy(const void *source, void *destination, size_t length); 12 | \end{verbatim} 13 | 14 | \subsubsection*{Calling convention} 15 | 16 | \begin{description} 17 | \item[\registerop{rd}] void 18 | \item[\registerop{arg0}] Pointer to the source memory 19 | \item[\registerop{arg1}] Pointer to the destination scratch memory 20 | \item[\registerop{arg2}] Amount of bytes to copy 21 | \end{description} 22 | 23 | \subsubsection*{Description} 24 | 25 | The \subroutine{bcopy} subroutine copies bytes from a source pointer 26 | to a destination pointer, within the DTrace machine state scratch 27 | region, up to the size supplied in the third argument. 28 | \subsubsection*{Pseudocode} 29 | 30 | \begin{verbatim} 31 | source = stack[0].value 32 | destination = stack[1].value 33 | length = stack[2].value 34 | 35 | if destination not in scratch: 36 | return 37 | 38 | if not can_load(source): 39 | %rd = 0 40 | return 41 | 42 | for i = 0 ... length: 43 | destination[i] = source[i] 44 | \end{verbatim} 45 | 46 | \subsubsection*{Failure modes} 47 | 48 | This subroutine has no run-time failure modes beyond its constraints. 49 | -------------------------------------------------------------------------------- /specification/instr/ldsh.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{LDSH} 4 | \label{insn:ldsh} 5 | \subsection*{LDSH: load a 16 bit value} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{LDSB \%rd, \%r1} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x1D} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{ldsh} instruction loads a 16-bit value pointed to by 24 | \registerop{r1} into \registerop{rd}, the results register. This instruction is 25 | a \textbf{signed} instruction and will perform sign extenstion on the resulting 26 | register when applicable. 27 | 28 | \subsubsection*{Pseudocode} 29 | 30 | \begin{verbatim} 31 | %rd = %r1 32 | \end{verbatim} 33 | 34 | \subsubsection*{Load-time constraints} 35 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 36 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 37 | \registerop{r0}. 38 | 39 | This instruction is \textbf{privileged} and thus performs no access control 40 | checks. It is up to the OpenDTrace implementation to implement that constraint. 41 | 42 | \subsubsection*{Failure modes} 43 | 44 | This instruction has no run-time failure modes beyond its constraints. 45 | -------------------------------------------------------------------------------- /specification/instr/ldsw.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{LDSW} 4 | \label{insn:ldsw} 5 | \subsection*{LDSW: load a 32 bit value} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{LDSB \%rd, \%r1} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x1E} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{ldsw} instruction loads a 32-bit value pointed to by 24 | \registerop{r1} into \registerop{rd}, the results register. This instruction is 25 | a \textbf{signed} instruction and will perform sign extension on the resulting 26 | register when applicable. 27 | 28 | \subsubsection*{Pseudocode} 29 | 30 | \begin{verbatim} 31 | %rd = %r1 32 | \end{verbatim} 33 | 34 | \subsubsection*{Load-time constraints} 35 | The registers \registerop{r1} and \registerop{rd} must be valid registers, 36 | \registerop{r2} must be \registerop{r0} and \registerop{rd} must not be 37 | \registerop{r0}. 38 | 39 | This instruction is \textbf{privileged} and thus performs no access control 40 | checks. It is up to the OpenDTrace implementation to implement that constraint. 41 | 42 | \subsubsection*{Failure modes} 43 | 44 | This instruction has no run-time failure modes beyond its constraints. 45 | -------------------------------------------------------------------------------- /specification/chap-opendtrace-global-vars.tex: -------------------------------------------------------------------------------- 1 | 2 | The D language provides a set of built-in global variables that are 3 | available to D scripts from within probe context. The built-in global 4 | variables are meant to help script writers and expose information that 5 | is commonly uses within C and C++ programs, such as \verb|errno| for 6 | the error number set by the most recent system call, and the 7 | \verb|pid| for the Process Identifier of the currently running 8 | process. All global variables in D are read only, including in 9 | destructive mode. 10 | 11 | \section{Built-in Variables reference} 12 | \label{sec:builtin-variables-ref} 13 | 14 | The following is a list of all of the global variables available to D 15 | programs. 16 | 17 | \input{vars/arg09} 18 | \input{vars/args} 19 | \input{vars/caller} 20 | \input{vars/cpu} 21 | \input{vars/cpucycles} 22 | \input{vars/cpuinstrs} 23 | \input{vars/curthread} 24 | \input{vars/dispatchaddr} 25 | \input{vars/epid} 26 | \input{vars/errno} 27 | \input{vars/execname} 28 | \input{vars/gid} 29 | \input{vars/id} 30 | \input{vars/ipl} 31 | \input{vars/machtimestamp} 32 | \input{vars/pid} 33 | \input{vars/ppid} 34 | \input{vars/probe} 35 | \input{vars/stackdepth} 36 | \input{vars/tid} 37 | \input{vars/ucaller} 38 | \input{vars/uid} 39 | \input{vars/uregs} 40 | \input{vars/ustackdepth} 41 | \input{vars/vcycles} 42 | \input{vars/vinstrs} 43 | \input{vars/vtimestamp} 44 | \input{vars/walltimestamp} 45 | -------------------------------------------------------------------------------- /specification/instr/srem.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{SREM} 4 | \label{insn:srem} 5 | \subsection*{SREM: divide two numbers and store the remainder} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{SREM \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,15,16,23,24,31} \\ 14 | \bitbox{8}{0x0B} 15 | \bitbox{8}{r1} 16 | \bitbox{8}{r2} 17 | \bitbox{8}{rd} 18 | \end{bytefield} 19 | \end{center} 20 | 21 | \subsubsection*{Description} 22 | 23 | The \instruction{srem} instruction divides the value contained in 24 | \registerop{r2} into that contained in \registerop{r1} placing the remainder 25 | into \registerop{rd}. The values in both \registerop{r1} and \registerop{r2} 26 | are first promoted to signed, 64 bit values, before the division operation is 27 | carried out. The \instruction{srem} instruction follows the remainder definition 28 | in C99 and will return a negative remainder if applicable. 29 | 30 | \subsubsection*{Pseudocode} 31 | 32 | \begin{verbatim} 33 | %rd = (int64_t)%r1 % (inst64_t)%r2 34 | \end{verbatim} 35 | 36 | \subsubsection*{Load-time constraints} 37 | The registers \registerop{r1}, \registerop{r2} and \registerop{rd} must be 38 | valid registers and \registerop{rd} must not be \registerop{r0}. 39 | 40 | \subsubsection*{Failure modes} 41 | 42 | This instruction has no run-time failure modes beyond its constraints. 43 | -------------------------------------------------------------------------------- /specification/instr/ldgs.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{LDGS} 4 | \label{insn:ldgs} 5 | \subsection*{LDGS: Load a user defined variable} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{LDGS \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,23,24,31} \\ 14 | \bitbox{8}{0x29} 15 | \bitbox{16}{var} 16 | \bitbox{8}{rd} 17 | \end{bytefield} 18 | \end{center} 19 | 20 | \subsubsection*{Description} 21 | 22 | The \instruction{ldgs} instruction has two modes of operation and is intended to 23 | be used only for scalar values. The first mode of operation is when the value 24 | provided in \registerop{var} is less than DIF\_VAR\_OTHER\_UBASE. This will 25 | cause DTrace to look up a pre-defined scalar variable such as curthread, while 26 | the second mode of operation will result in looking up a user defined variable 27 | in a DIF program. The result of this instruction will be put into the register 28 | \registerop{rd}. \\ 29 | 30 | Unlike the \instruction{ldga} instruction, the \registerop{var} field is 31 | 16 bits long, as opposed to 8 bits due to the fact that the variable that is 32 | being loaded is a scalar and does not require indexing operations. 33 | \subsubsection*{Pseudocode} 34 | 35 | \begin{verbatim} 36 | %rd = var 37 | \end{verbatim} 38 | 39 | \subsubsection*{Failure modes} 40 | 41 | This instruction has no run-time failure modes beyond its constraints. 42 | -------------------------------------------------------------------------------- /specification/instr/stgs.tex: -------------------------------------------------------------------------------- 1 | \clearpage 2 | \phantomsection 3 | \addcontentsline{toc}{subsection}{STGS} 4 | \label{insn:stgs} 5 | \subsection*{STGS: store a value into a variable} 6 | 7 | \subsubsection*{Format} 8 | 9 | \textrm{STGS \%rd, \%r1, \%r2} 10 | 11 | \begin{center} 12 | \begin{bytefield}[endianness=big,bitformatting=\scriptsize]{32} 13 | \bitheader{0,7,8,23,24,31} \\ 14 | \bitbox{8}{0x2A} 15 | \bitbox{16}{var} 16 | \bitbox{8}{rd} 17 | \end{bytefield} 18 | \end{center} 19 | 20 | \subsubsection*{Description} 21 | 22 | Similar to \instruction{ldgs}, the instruction \instruction{stgs} operates 23 | exclusively on scalar variables and can not contain indices. However, the 24 | instruction may allow loading of data by reference using the DIF\_TF\_BYREF 25 | flag, which allows loading of data bounded by the limits found in the 26 | dtrace\_vcanload() function. Unlike \instruction{ldgs}, \instruction{stgs} can 27 | not store to pre-defined variables in DTrace, and instead allows access only to 28 | user defined variables. The variable is accessed by the \registerop{var} field 29 | and is required to be large or equal to DIF\_VAR\_OTHER\_UBASE. The result of 30 | this operation is stored in the \registerop{rd} register. 31 | 32 | \subsubsection*{Pseudocode} 33 | 34 | \begin{verbatim} 35 | assert(var >= DIF_VAR_OTHER_UBASE) 36 | var -= DIF_VAR_OTHER_UBASE 37 | if (flags & DIF_TF_BYREF) 38 | var = copyin(%rd) 39 | else 40 | var = %rd 41 | \end{verbatim} 42 | 43 | \subsubsection*{Failure modes} 44 | 45 | This instruction will fail if the supplied value in the \registerop{var} field 46 | is less than DIF\_VAR\_OTHER\_UBASE. 47 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | ## Core latex/pdflatex auxiliary files: 2 | *.aux 3 | *.lof 4 | *.log 5 | *.lot 6 | *.fls 7 | *.out 8 | *.toc 9 | 10 | ## Intermediate documents: 11 | *.dvi 12 | *-converted-to.* 13 | # these rules might exclude image files for figures etc. 14 | # *.ps 15 | # *.eps 16 | # *.pdf 17 | 18 | ## Bibliography auxiliary files (bibtex/biblatex/biber): 19 | *.bbl 20 | *.bcf 21 | *.blg 22 | *-blx.aux 23 | *-blx.bib 24 | *.brf 25 | *.run.xml 26 | 27 | ## Build tool auxiliary files: 28 | *.fdb_latexmk 29 | *.synctex.gz 30 | *.synctex.gz(busy) 31 | *.pdfsync 32 | 33 | ## Auxiliary and intermediate files from other packages: 34 | 35 | # algorithms 36 | *.alg 37 | *.loa 38 | 39 | # achemso 40 | acs-*.bib 41 | 42 | # amsthm 43 | *.thm 44 | 45 | # beamer 46 | *.nav 47 | *.snm 48 | *.vrb 49 | 50 | #(e)ledmac/(e)ledpar 51 | *.end 52 | *.[1-9] 53 | *.[1-9][0-9] 54 | *.[1-9][0-9][0-9] 55 | *.[1-9]R 56 | *.[1-9][0-9]R 57 | *.[1-9][0-9][0-9]R 58 | *.eledsec[1-9] 59 | *.eledsec[1-9]R 60 | *.eledsec[1-9][0-9] 61 | *.eledsec[1-9][0-9]R 62 | *.eledsec[1-9][0-9][0-9] 63 | *.eledsec[1-9][0-9][0-9]R 64 | 65 | # glossaries 66 | *.acn 67 | *.acr 68 | *.glg 69 | *.glo 70 | *.gls 71 | 72 | # hyperref 73 | *.brf 74 | 75 | # listings 76 | *.lol 77 | 78 | # makeidx 79 | *.idx 80 | *.ilg 81 | *.ind 82 | *.ist 83 | 84 | # minitoc 85 | *.maf 86 | *.mtc 87 | *.mtc0 88 | 89 | # minted 90 | *.pyg 91 | 92 | # morewrites 93 | *.mw 94 | 95 | # nomencl 96 | *.nlo 97 | 98 | # sagetex 99 | *.sagetex.sage 100 | *.sagetex.py 101 | *.sagetex.scmd 102 | 103 | # sympy 104 | *.sout 105 | *.sympy 106 | sympy-plots-for-*.tex/ 107 | 108 | # todonotes 109 | *.tdo 110 | 111 | # xindy 112 | *.xdy 113 | 114 | auto 115 | -------------------------------------------------------------------------------- /specification/acknowledgments.tex: -------------------------------------------------------------------------------- 1 | \section*{Acknowledgments} 2 | The authors of this report thank the creators of DTrace, including 3 | Bryan Cantril, Adam Leventhal and Michael Shapiro for a spectacular 4 | contribution to the field of operating-system design, and in 5 | particular for designing the data structures, instructions, and other 6 | elements of DTrace described in this specification. Some of the text 7 | in this specification has been excerpted from the excellent comments 8 | present in the original source code. 9 | 10 | One cannot work with DTrace without running across the work of Brendan 11 | Gregg, author of the DTrace Toolkit, as well as \emph{DTrace: Dynamic 12 | Tracing in Oracle Solaris, macOS and FreeBSD}, and to him we also 13 | owe a debt of thanks. 14 | 15 | Several people, including some of the original developers of DTrace, 16 | reviewed this report during various stages of its development and so 17 | we'd like to extend our thanks to Matthew Ahrens, Mark Johnston, 18 | Samuel Lepetit, Adam Leventhal, and David Pacheco. 19 | 20 | The authors of this report also thank other members of the CADETS team, and 21 | our past and current research collaborators at BAE Systems, the University of 22 | Cambridge, and Memorial University Newfoundland: 23 | 24 | % 25 | % Various folk including interns and co-authors on papers supported in part by 26 | % CADETS. 27 | % 28 | \begin{tabular}{llll} 29 | David Chisnall & Silviu Chiricescu & Brooks Davis Khilan Gudka \\ 30 | Ben Laurie & Ilias Marinos & Peter G. Neumann & Greg Sullivan \\ 31 | Rip Sohan & Amanda Strnad & Bjoern Zeeb 32 | \end{tabular} 33 | 34 | \bigskip 35 | 36 | %\noindent 37 | %The CADETS team also thanks past and current members of its external 38 | %oversight group for significant support and contributions: 39 | % 40 | %\bigskip 41 | % 42 | %\begin{tabular}{llll} 43 | %\end{tabular} 44 | % 45 | %\bigskip 46 | 47 | The port of DTrace to FreeBSD was carried out in 2007 by John Birrell 48 | who, sadly, passed away in 2009, and we dedicate this report to his 49 | memory. 50 | 51 | \noindent 52 | Finally, we are grateful to Angelos Keromytis, DARPA Transparent Computing 53 | program manager, who has offered both technical insight and support throughout 54 | this work. 55 | -------------------------------------------------------------------------------- /specification/abstract.tex: -------------------------------------------------------------------------------- 1 | \section*{Abstract} 2 | 3 | OpenDTrace is a dynamic tracing facility offering full-system instrumentation, 4 | a high degree of flexibility, and portable semantics across a range of 5 | operating systems. 6 | Originally designed and implemented by Sun Microsystems (now Oracle), 7 | user-facing aspects of OpenDTrace, such as the D language and 8 | command-line tools, 9 | are well defined and documented. 10 | However, OpenDTrace's internal formats -- 11 | the DTrace Intermediate Format (DIF), 12 | DTrace Object Format (DOF) and Compact C Trace Format (CTF) 13 | -- have primarily been documented through 14 | source-code comments rather than a structured specification. 15 | This technical report specifies these formats in order to better support the 16 | development of more comprehensive tests, new underlying execution substrates 17 | (such as just-in-time compilation), and future extensions. 18 | We not only cover the data structures present in \texttt{OpenDTrace} 19 | but also include a complete reference of all the low level 20 | instructions that are used by the byte code interpreter, 21 | all the built in global variables and subroutines. 22 | Our goal with this report is to provide not only a list of 23 | what is present in the code at any point in time, the \emph{what}, 24 | but also explanations of how the system works as a whole, 25 | the \emph{how}, and motivations for various design decisions 26 | that have been made along the way, the \emph{why}. 27 | Throughout this report we use the name \texttt{OpenDTrace} to refer 28 | to the open-source project but retain the name \texttt{DTrace} when 29 | referring to data structures such as the DTrace Intermediate Format. 30 | OpenDTrace builds upon the foundations of the original DTrace code but 31 | provides new features, which were not present in the original. 32 | This document acts as a single source of truth for the current state 33 | of OpenDTrace as it is currently implemented and deployed. 34 | %DIF is a RISC bytecode into which D scripts are compiled, describing the 35 | %specific executable actions in a script. 36 | %DOF is the container format containing a set of headers and sections for 37 | %variables, probe implementations, constants, and other content required to 38 | %represent a complete script. 39 | -------------------------------------------------------------------------------- /specification/chap-opendtrace-code.tex: -------------------------------------------------------------------------------- 1 | \section{Open Solaris} 2 | \label{sec:open-solaris-code} 3 | 4 | DTrace was originally developed on \pathname{OpenSolaris}. As this 5 | was the original place that the code resided there was no reason to 6 | split things along OS or license boundaries, concerns which cropped up 7 | in subsequent ports of the system. The main DTrace command resides in 8 | \pathname{cmd}, the supporting libraries are in 9 | \pathname{lib/libdtrace} and the kernel code is in the 10 | \pathname{uts/common}, \pathname{uts/intel}, \pathname{uts/sparc}, and 11 | related directories. One key thing to note is that there are 12 | \emph{two different} \pathname{dtrace.h} include files, one for the 13 | kernel and one for the user space code. 14 | 15 | \section{Illumos} 16 | \label{sec:illumos-code} 17 | 18 | The original source of DTrace came from OpenSolaris which has morphed 19 | into \pathname{Illumos}. The \pathname{Illumos} tree continues to use 20 | the same directory and file layout as was used in 21 | \pathname{OpenSolaris} 22 | 23 | \section{FreeBSD} 24 | \label{sec:freebsd-code} 25 | 26 | Within FreeBSD the DTrace code has been split between that which came 27 | from Sun's OpenSolaris (now Illumos) and is therefore under the CDDL 28 | and the code which has been written natively on FreeBSD, and is 29 | therefore under a BSD license. There are two locations for the cddl 30 | code, one in the root of the tree, \pathname{/usr/src} and one in the 31 | kernel directory \pathname{/usr/src/sys}. Native FreeBSD scripts are 32 | located in the \pathname{/usr/share/dtrace} directory. 33 | 34 | Because of the user space and kernel split for the cddl code the 35 | FreeBSD tree has three, separate, \pathname{dtrace.h} files: 36 | 37 | \begin{figure} 38 | \centering 39 | \begin{description} 40 | \item [sys/cddl/contrib/opensolaris/uts/common/sys/dtrace.h] The one 41 | you care about. 42 | \item [cddl/contrib/opensolaris/lib/libdtrace/common/dtrace.h] Library APIs 43 | \item [cddl/compat/opensolaris/include/dtrace.h] Compatibility include 44 | \end{description} 45 | \caption{The various versions of dtrace.h} 46 | \label{fig:freebsd-dtrace-h} 47 | \end{figure} 48 | 49 | \section{macOS} 50 | \label{sec:macos-code} 51 | 52 | Open source code from Apple is supplied in discrete packages. The 53 | DTrace code on macOS is split between the \pathname{xnu} kernel and 54 | the rest of the code which is contained in a \pathname{dtrace} code 55 | drop. The kernel includes a very small number of files that are 56 | absolutely necessary to build the kernel itself, including the driver 57 | code. All of the kernel code is collected into the 58 | \pathname{xnu/bsd/dev/dtrace/} directory with the macOS translators, 59 | the D files that know about the internals of kernel data structures, 60 | are contained in the \pathname{scripts} sub-directory. In the 61 | \pathname{OpenDTrace} repositories there macOS kernel code resides in 62 | \url{https://github.com/opendtrace/xnu} while the rest of the code 63 | resides in \url{https://github.com/opendtrace/macos-dtrace}. These 64 | repositories are updated as soon as Apple drops their tarballs onto 65 | \url{https://opensource.apple.com/tarballs/}. 66 | 67 | %%% Local Variables: 68 | %%% mode: latex 69 | %%% TeX-master: "dtrace-specification" 70 | %%% End: 71 | -------------------------------------------------------------------------------- /specification/opendtrace-specification.tex: -------------------------------------------------------------------------------- 1 | \include{preamble} 2 | 3 | \begin{document} 4 | \title{OpenDTrace Specification\\ 5 | {\large Version 1.0} 6 | } 7 | 8 | \date{August 16, 2018} 9 | 10 | \author{ 11 | George Neville-Neil, Jonathan Anderson, Graeme Jenkinson, Brian Kidney, \\ 12 | Domagoj Stolfa, Arun Thomas, Robert N. M. Watson \\ 13 | \\ 14 | BAE Systems, The University of Cambridge, \\ 15 | and Memorial University Newfoundland } 16 | 17 | %% CL tech-report format provides its own cover page 18 | \begin{minipage}[h]{\textwidth} 19 | \maketitle 20 | 21 | \vspace{2in} 22 | {\small 23 | Approved for public release; distribution is unlimited. 24 | Sponsored by the Defense Advanced Research Projects Agency (DARPA) and the 25 | Air Force Research Laboratory (AFRL), under contracts FA8650-15-C-7558 26 | (``CADETS'') as part of the DARPA Transparent Computing research program. 27 | The views, opinions, and/or findings contained in this report are those of the 28 | authors and should not be interpreted as representing the official views or 29 | policies, either expressed or implied, of the Department of Defense 30 | or the U.S. Government.} 31 | \end{minipage} 32 | %% 33 | 34 | \normalsize 35 | 36 | %% CL tech-report format requires page numbering to start at 3 37 | %\setcounter{page}{3} 38 | %% 39 | 40 | %% For revisions sent for editing, prefer double spacing. 41 | %\doublespacing 42 | %% 43 | 44 | \clearpage 45 | 46 | \input{abstract} 47 | 48 | \clearpage 49 | 50 | \input{acknowledgments} 51 | 52 | \clearpage 53 | 54 | \tableofcontents 55 | 56 | \clearpage 57 | 58 | \chapter{Introduction} 59 | \label{chap:introduction} 60 | \input{chap-intro} 61 | 62 | \chapter{OpenDTrace Architecture} 63 | \label{chap:opendtrace-arch} 64 | \input{chap-opendtrace-arch} 65 | 66 | \chapter{The D Language} 67 | \label{chap:opendtrace-dlang} 68 | \input{chap-opendtrace-dlang} 69 | 70 | \chapter{Compact C Type Format (CTF)} 71 | \label{chap:opendtrace-ctf} 72 | \input{chap-opendtrace-ctf} 73 | 74 | \chapter{Trace buffer} 75 | \label{chap:opendtrace-trace-buffer} 76 | \input{chap-opendtrace-trace-buffer} 77 | 78 | \chapter{OpenDTrace Object Format (DOF)} 79 | \label{chap:opendtrace-object-format} 80 | \input{chap-opendtrace-object-format} 81 | 82 | \chapter{OpenDTrace Intermediate Format (DIF)} 83 | \label{chap:opendtrace-intermediate-format} 84 | \input{chap-opendtrace-intermediate-format} 85 | 86 | \chapter{Instruction Reference} 87 | \label{chap:opendtrace-instruction-reference} 88 | \input{chap-opendtrace-instruction-reference} 89 | 90 | \chapter{Built-in Global Variables} 91 | \label{chap:opendtrace-global-vars} 92 | \input{chap-opendtrace-global-vars} 93 | 94 | \chapter{Built-in Subroutines} 95 | \label{chap:opendtrace-subroutines} 96 | \input{chap-opendtrace-subroutines} 97 | 98 | \begin{appendices} 99 | \chapter{Code Organization} 100 | \label{chap:opendtrace-code} 101 | \input{chap-opendtrace-code} 102 | 103 | %\chapter{Providers} 104 | %\label{chap:opendtrace-providers} 105 | %\input{chap-opendtrace-providers} 106 | 107 | \end{appendices} 108 | 109 | \bibliographystyle{abbrv} 110 | \bibliography{opendtrace-specification} 111 | 112 | %\chapter*{Index} 113 | 114 | \end{document} 115 | -------------------------------------------------------------------------------- /specification/preamble.tex: -------------------------------------------------------------------------------- 1 | %%%% University of Cambridge tech-report formatting; enable when producing 2 | %%%% tech-report versions of these documents; otherwise, disable. 3 | \documentclass[12pt,twoside,openright,a4paper]{report} 4 | \setlength{\oddsidemargin}{-0.4mm} % 25 mm left margin 5 | \setlength{\evensidemargin}{\oddsidemargin} 6 | \setlength{\textwidth}{160mm} % 25 mm right margin 7 | \setlength{\topmargin}{-5.4mm} % 20 mm top margin 8 | \setlength{\headheight}{5mm} 9 | \setlength{\headsep}{5mm} 10 | \setlength{\footskip}{10mm} 11 | \setlength{\textheight}{237mm} % 20 mm bottom margin 12 | %%%% .. or regular document 13 | %\documentclass[12pt,letterpaper,twoside,openright,fleqn]{report} 14 | %%%% End of tech-report vs. regular 15 | %%%% 16 | 17 | %\renewcommand{\baselinestretch}{2} % double space for editors 18 | \usepackage{fullpage} 19 | \usepackage{graphicx} 20 | \usepackage{marginnote} 21 | \usepackage{appendix} 22 | \usepackage{booktabs} 23 | \usepackage{bytefield} 24 | \usepackage{color} 25 | \definecolor{lightgray}{gray}{0.8} 26 | \usepackage{times} 27 | \usepackage{algpseudocode} 28 | \newcommand{\note}[2]{{\color{blue}[ Note: #1 - #2]}} 29 | \usepackage{listings} 30 | \usepackage{setspace} 31 | \usepackage{amsmath} 32 | \usepackage{longtable} 33 | \usepackage{amsmath} 34 | \usepackage[cal=boondoxo]{mathalfa} 35 | \usepackage[nounderscore]{syntax} 36 | % Must be included later than setspace, otherwise all footnote hyperlinks 37 | % point to the title page. 38 | \usepackage{hyperref} 39 | \definecolor{CodeColour}{rgb}{0.9,0.9,0.9} %Light grey 40 | \lstset{basicstyle=\small\ttfamily, 41 | stringstyle=\textit, %italic strings 42 | keywordstyle=\color{red}\textbf, %Bold keywords 43 | commentstyle=\color{blue}, 44 | breaklines=true, % Wrap long lines 45 | numbers=left, % Line numbers on the left 46 | frame=l, %Border on the left 47 | framerule=0.8pt, % Thick border 48 | backgroundcolor=\color{CodeColour}, %Coloured code listings 49 | numberstyle={\small \oldstylenums}, %tiny, old style line numbers 50 | %stepnumber=5, % Number every fifth line 51 | numbersep=5pt, % Five points between the line numbers and the text 52 | tabsize=4 53 | } 54 | \lstdefinelanguage{llvm} 55 | { 56 | morekeywords={private, constant, i8, i32, define, icmp, label, i64, call, void, ret, getelementptr, br, load, align, nounwind}, 57 | morekeywords={addrspace, inttoptr, ptrtoint, tail}, 58 | morecomment=[l]; 59 | }% 60 | 61 | \lstnewenvironment{ccodelisting}{\lstset{language=C}}{} 62 | \lstnewenvironment{llvmlisting}{\lstset{language={llvm}}}{} 63 | \newcommand{\ccode}[1]{\lstinline[backgroundcolor=\color{white},language=C]|#1|} 64 | \newcommand{\llvmir}[1]{\lstinline[backgroundcolor=\color{white},language={llvm}]|#1|} 65 | \newcommand{\asm}[1]{\lstinline[backgroundcolor=\color{white},language={}]|#1|} 66 | \lstnewenvironment{asmcode}{\lstset{language=}}{} 67 | \newcommand{\regname}[1]{{\small\ttfamily\$#1}} 68 | 69 | \hyphenation{CADETS} 70 | 71 | \reversemarginpar 72 | \setlength{\marginparwidth}{1.2in} 73 | \let\oldmarginpar\marginpar 74 | \renewcommand\marginpar[1]{\-\oldmarginpar[\raggedright\footnotesize #1]% 75 | {\raggedright\footnotesize #1}} 76 | 77 | \newcommand{\pathname}[1]{{\texttt{\detokenize{#1}}}} 78 | \newcommand{\literal}[1]{{\texttt{\detokenize{#1}}}} 79 | \newcommand{\function}[1]{{\texttt{\detokenize{#1}}}} 80 | \newcommand{\instruction}[1]{{\texttt{#1}}} 81 | \newcommand{\register}[1]{{\texttt{\%#1}}} 82 | \newcommand{\registerop}[1]{{\texttt{\textbf{#1}}}} 83 | \newcommand{\nregs}{{\texttt{\textbf{NREGS}}}} 84 | \newcommand{\subroutine}[1]{{\texttt{\detokenize{#1}}}} 85 | \newcommand{\struct}[1]{{\texttt{\detokenize{#1}}}} 86 | 87 | \usepackage{tikz} 88 | \usetikzlibrary{shapes} 89 | \usetikzlibrary{positioning} 90 | \usetikzlibrary{decorations.pathreplacing} 91 | \usetikzlibrary{shapes.multipart} 92 | \usetikzlibrary{arrows.meta} 93 | \usetikzlibrary{matrix} 94 | \usetikzlibrary{fit} 95 | 96 | \tikzstyle{nn} = [inner sep=0pt,outer sep=0pt, align=center] 97 | \tikzstyle{db} = [decoration={brace,mirror,raise=5pt},decorate] 98 | 99 | 100 | -------------------------------------------------------------------------------- /specification/Makefile: -------------------------------------------------------------------------------- 1 | TARGET=opendtrace-specification.pdf 2 | 3 | MAIN_TEX=opendtrace-specification.tex 4 | 5 | SOURCE= \ 6 | ${MAIN_TEX} \ 7 | abstract.tex \ 8 | acknowledgments.tex \ 9 | chap-intro.tex \ 10 | chap-opendtrace-arch.tex \ 11 | chap-opendtrace-ctf.tex \ 12 | chap-opendtrace-trace-buffer.tex \ 13 | chap-opendtrace-instruction-reference.tex \ 14 | chap-opendtrace-intermediate-format.tex \ 15 | chap-opendtrace-object-format.tex \ 16 | chap-opendtrace-subroutines.tex \ 17 | chap-opendtrace-global-vars.tex \ 18 | chap-opendtrace-code.tex \ 19 | chap-opendtrace-dlang.tex \ 20 | chap-opendtrace-providers.tex \ 21 | preamble.tex \ 22 | instr/add.tex \ 23 | instr/allocs.tex \ 24 | instr/and.tex \ 25 | instr/ba.tex \ 26 | instr/be.tex \ 27 | instr/bg.tex \ 28 | instr/bge.tex \ 29 | instr/bgeu.tex \ 30 | instr/bgu.tex \ 31 | instr/bl.tex \ 32 | instr/ble.tex \ 33 | instr/bleu.tex \ 34 | instr/blu.tex \ 35 | instr/bne.tex \ 36 | instr/call.tex \ 37 | instr/cmp.tex \ 38 | instr/copys.tex \ 39 | instr/flushts.tex \ 40 | instr/ldga.tex \ 41 | instr/ldgaa.tex \ 42 | instr/ldgs.tex \ 43 | instr/ldls.tex \ 44 | instr/ldsb.tex \ 45 | instr/ldsh.tex \ 46 | instr/ldsw.tex \ 47 | instr/ldta.tex \ 48 | instr/ldtaa.tex \ 49 | instr/ldts.tex \ 50 | instr/ldub.tex \ 51 | instr/lduh.tex \ 52 | instr/lduw.tex \ 53 | instr/ldx.tex \ 54 | instr/mov.tex \ 55 | instr/mul.tex \ 56 | instr/nop.tex \ 57 | instr/not.tex \ 58 | instr/or.tex \ 59 | instr/popts.tex \ 60 | instr/pushtr.tex \ 61 | instr/pushtv.tex \ 62 | instr/ret.tex \ 63 | instr/rldsb.tex \ 64 | instr/rldsh.tex \ 65 | instr/rldsw.tex \ 66 | instr/rldub.tex \ 67 | instr/rlduh.tex \ 68 | instr/rlduw.tex \ 69 | instr/rldx.tex \ 70 | instr/scmp.tex \ 71 | instr/sdiv.tex \ 72 | instr/sets.tex \ 73 | instr/setx.tex \ 74 | instr/sll.tex \ 75 | instr/sra.tex \ 76 | instr/srem.tex \ 77 | instr/srl.tex \ 78 | instr/stb.tex \ 79 | instr/stgaa.tex \ 80 | instr/stgs.tex \ 81 | instr/sth.tex \ 82 | instr/stls.tex \ 83 | instr/sttaa.tex \ 84 | instr/stts.tex \ 85 | instr/stw.tex \ 86 | instr/stx.tex \ 87 | instr/sub.tex \ 88 | instr/tst.tex \ 89 | instr/udiv.tex \ 90 | instr/uldsb.tex \ 91 | instr/uldsh.tex \ 92 | instr/uldsw.tex \ 93 | instr/uldub.tex \ 94 | instr/ulduh.tex \ 95 | instr/ulduw.tex \ 96 | instr/uldx.tex \ 97 | instr/urem.tex \ 98 | instr/xlarg.tex \ 99 | instr/xlate.tex \ 100 | instr/xor.tex \ 101 | subr/alloca.tex \ 102 | subr/basename.tex \ 103 | subr/bcopy.tex \ 104 | subr/cleanpath.tex \ 105 | subr/copyin.tex \ 106 | subr/copyinstr.tex \ 107 | subr/copyinto.tex \ 108 | subr/copyout.tex \ 109 | subr/copyoutstr.tex \ 110 | subr/copyoutmbuf.tex \ 111 | subr/ddi_pathname.tex \ 112 | subr/dirname.tex \ 113 | subr/getf.tex \ 114 | subr/getmajor.tex \ 115 | subr/getminor.tex \ 116 | subr/htonl.tex \ 117 | subr/htonll.tex \ 118 | subr/htons.tex \ 119 | subr/index.tex \ 120 | subr/inet_ntoa.tex \ 121 | subr/inet_ntoa6.tex \ 122 | subr/inet_ntop.tex \ 123 | subr/json.tex \ 124 | subr/lltostr.tex \ 125 | subr/memref.tex \ 126 | subr/memstr.tex \ 127 | subr/msgdsize.tex \ 128 | subr/msgsize.tex \ 129 | subr/mutex_owned.tex \ 130 | subr/mutex_owner.tex \ 131 | subr/mutex_type_adaptive.tex \ 132 | subr/mutex_type_spin.tex \ 133 | subr/ntohl.tex \ 134 | subr/ntohll.tex \ 135 | subr/ntohs.tex \ 136 | subr/progenyof.tex \ 137 | subr/rand.tex \ 138 | subr/random.tex \ 139 | subr/rindex.tex \ 140 | subr/rw_iswriter.tex \ 141 | subr/rw_read_held.tex \ 142 | subr/rw_write_held.tex \ 143 | subr/speculation.tex \ 144 | subr/strchr.tex \ 145 | subr/strjoin.tex \ 146 | subr/strlen.tex \ 147 | subr/strrchr.tex \ 148 | subr/strstr.tex \ 149 | subr/strtok.tex \ 150 | subr/strtoll.tex \ 151 | subr/substr.tex \ 152 | subr/sx_exclusive_held.tex \ 153 | subr/sx_isexclusive.tex \ 154 | subr/sx_shared_held.tex \ 155 | subr/tolower.tex \ 156 | subr/toupper.tex \ 157 | subr/uuidstr.tex \ 158 | vars/arg09.tex \ 159 | vars/args.tex \ 160 | vars/caller.tex \ 161 | vars/cpu.tex \ 162 | vars/cpucycles.tex \ 163 | vars/cpuinstrs.tex \ 164 | vars/curthread.tex \ 165 | vars/dispatchaddr.tex \ 166 | vars/epid.tex \ 167 | vars/errno.tex \ 168 | vars/execname.tex \ 169 | vars/gid.tex \ 170 | vars/id.tex \ 171 | vars/ipl.tex \ 172 | vars/machtimestamp.tex \ 173 | vars/pid.tex \ 174 | vars/ppid.tex \ 175 | vars/probe.tex \ 176 | vars/stackdepth.tex \ 177 | vars/tid.tex \ 178 | vars/ucaller.tex \ 179 | vars/uid.tex \ 180 | vars/uregs.tex \ 181 | vars/ustackdepth.tex \ 182 | vars/vcycles.tex \ 183 | vars/vinstrs.tex \ 184 | vars/vtimestamp.tex \ 185 | vars/walltimestamp.tex 186 | 187 | ${TARGET}: ${SOURCE} 188 | latexmk -pdf -bibtex ${MAIN_TEX} 189 | 190 | clean: 191 | latexmk -C 192 | -------------------------------------------------------------------------------- /specification/chap-opendtrace-object-format.tex: -------------------------------------------------------------------------------- 1 | \section{Introduction} 2 | \label{sec:dof-intro} 3 | 4 | OpenDTrace programs are persistently encoded in the DOF format so that 5 | they may be embedded in other programs (for example, in an ELF file) 6 | or in the DTrace driver configuration file for use in anonymous 7 | tracing. The DOF format is versioned and extensible so that it can be 8 | revised and so that internal data structures can be modified or 9 | extended compatibly. All DOF structures use fixed-size types, so the 10 | 32-bit and 64-bit representations are identical and consumers can use 11 | either data model transparently. 12 | 13 | \subsection{Stable Storage Format} 14 | \label{sec:dof-stable-storage} 15 | 16 | \begin{figure}[h] 17 | \centering 18 | \includegraphics[width=.8\textwidth]{dof-stable-format} 19 | \caption{Stable Storage Format} 20 | \label{fig:dof-stable-storage-format} 21 | \end{figure} 22 | 23 | When a DOF file resides on stable storage it is stored in the format 24 | shown in Figure~\ref{fig:dof-stable-storage-format}. The file header 25 | stores meta-data including a magic number, data model for the 26 | instrumentation, data encoding, and properties of the DIF code within. 27 | The header describes its own size and the size of the section headers. 28 | By convention, an array of section headers follows the file header, 29 | and then the data for all loadable sections and sections which cannot 30 | be loaded, also called unloadable sections. This data layout permits 31 | consumer code to easily download the headers and all loadable data 32 | into the DTrace driver in one contiguous chunk, omitting other 33 | extraneous sections. DOF sections are used both for stable storage 34 | and to pass data between user and kernel space, e.g. D programs are 35 | sent into the kernel as a \verb|dof_prog_rt| section. 36 | 37 | The section headers describe the size, offset, alignment, and section 38 | type for each section. Sections are described using a set of \verb|#defines| 39 | that tell the consumer what kind of data is expected. Sections can 40 | contain links to other sections by storing a \verb|dof_secidx_t|, an index 41 | into the section header array, inside of the section data structures. 42 | The section header includes an entry size so that sections with data 43 | arrays can grow their structures. 44 | 45 | The DOF data itself can contain many snippets of DIF (i.e. more than 46 | one DIF object or DIFO), which are represented themselves as a 47 | collection of related DOF sections. This allows us to change the set 48 | of sections associated with a DIFO over time, and also allows us to 49 | encode DIFOs that contain different sets of sections. When a DOF 50 | section wants to refer to a DIFO, it stores the \verb|dof_secidx_t| of 51 | a section of type \verb|DOF_SECT_DIFOHDR|. This section's data is 52 | then an array of \verb|dof_secidx_t|'s which in turn denote the 53 | sections associated with this DIFO. 54 | 55 | This loose coupling of the file structure (header and sections) to the 56 | structure of the DTrace program itself (enabling control block 57 | descriptions, action descriptions, and DIFOs) permits activities such 58 | as relocation processing to occur in a single pass without having to 59 | understand D program structure. 60 | 61 | Finally, strings are always stored in ELF-style string tables along 62 | with a string table section index and string table offset. Therefore 63 | strings in DOF are always arbitrary-length and not bound to the 64 | current implementation. 65 | 66 | % Note from Samuel Lepetit 67 | % A graph of which sections depend on which would be more useful I 68 | % think here compared to just a list of sections (the dof.py lldb 69 | % macros I wrote that you can find in the userspace Darwin repo are a 70 | % bit easier to read than the code). Which sections are currently 71 | % unused as well would be useful. 72 | 73 | \begin{table} 74 | \centering 75 | \begin{tabular}{|l|l|l|} 76 | \hline 77 | Name & Loadable & Comment\\ 78 | \hline 79 | \verb|DOF_SECT_NONE| & N & null section\\ 80 | \verb|DOF_SECT_COMMENTS| & N & compiler comments\\ 81 | \verb|DOF_SECT_SOURCE| & N & D program source code\\ 82 | \verb|DOF_SECT_ECBDESC| & Y & \verb|dof_ecbdesc_t|\\ 83 | \verb|DOF_SECT_PROBEDESC| & Y & \verb|dof_probedesc_t|\\ 84 | \verb|DOF_SECT_ACTDESC| & Y & \verb|dof_actdesc_t| array\\ 85 | \verb|DOF_SECT_DIFOHDR| & Y & \verb|dof_difohdr_t| (variable length)\\ 86 | \verb|DOF_SECT_DIF| & Y & \verb|uint32_t array| of byte code\\ 87 | \verb|DOF_SECT_STRTAB| & Y & string table\\ 88 | \verb|DOF_SECT_VARTAB| & Y & \verb|dtrace_difv_t| array\\ 89 | \verb|DOF_SECT_RELTAB| & Y & \verb|dof_relodesc_t| array\\ 90 | \verb|DOF_SECT_TYPTAB| & Y & \verb|dtrace_diftype_t| array\\ 91 | \verb|DOF_SECT_URELHDR| & Y & \verb|dof_relohdr_t| (user relocations)\\ 92 | \verb|DOF_SECT_KRELHDR| & Y & \verb|dof_relohdr_t| (kernel relocations)\\ 93 | \verb|DOF_SECT_OPTDESC| & Y & \verb|dof_optdesc_t| array\\ 94 | \verb|DOF_SECT_PROVIDER| & Y & \verb|dof_provider_t|\\ 95 | \verb|DOF_SECT_PROBES| & Y & \verb|dof_probe_t| array\\ 96 | \verb|DOF_SECT_PRARGS| & Y & \verb|uint8_t array| (probe arg mappings)\\ 97 | \verb|DOF_SECT_PROFFS| & Y & \verb|uint32_t array| (probe arg offsets)\\ 98 | \verb|DOF_SECT_INTTAB| & Y & \verb|uint64_t array|\\ 99 | \verb|DOF_SECT_UTSNAME| & N & \verb|struct utsname| structure\\ 100 | \verb|DOF_SECT_XLTAB| & Y & \verb|dof_xlref_t| array\\ 101 | \verb|DOF_SECT_XLMEMBERS| & Y & \verb|dof_xlmember_t| array\\ 102 | \verb|DOF_SECT_XLIMPORT| & Y & \verb|dof_xlator_t|\\ 103 | \verb|DOF_SECT_XLEXPORT| & Y & \verb|dof_xlator_t|\\ 104 | \verb|DOF_SECT_PREXPORT| & Y & \verb|dof_secidx_t| array (exported objs)\\ 105 | \verb|DOF_SECT_PRENOFFS| & Y & \verb|uint32_t array| (enabled offsets)\\ 106 | \hline 107 | \end{tabular} 108 | \caption{DOF Section Descriptions} 109 | \label{tab:dof-sections} 110 | \end{table} 111 | 112 | 113 | %%% Local Variables: 114 | %%% mode: latex 115 | %%% TeX-master: "dtrace-specification" 116 | %%% End: 117 | -------------------------------------------------------------------------------- /cheatsheet.tex: -------------------------------------------------------------------------------- 1 | \documentclass[10pt,landscape]{article} 2 | \usepackage{multicol} 3 | \usepackage{calc} 4 | \usepackage{ifthen} 5 | \usepackage[landscape]{geometry} 6 | \usepackage{hyperref} 7 | \usepackage{listings} 8 | \usepackage[default]{sourcecodepro} 9 | \usepackage[T1]{fontenc} 10 | 11 | % To make this come out properly in landscape mode, do one of the following 12 | % 1. 13 | % pdflatex latexsheet.tex 14 | % 15 | % 2. 16 | % latex latexsheet.tex 17 | % dvips -P pdf -t landscape latexsheet.dvi 18 | % ps2pdf latexsheet.ps 19 | 20 | 21 | % If you're reading this, be prepared for confusion. Making this was 22 | % a learning experience for me, and it shows. Much of the placement 23 | % was hacked in; if you make it better, let me know... 24 | 25 | 26 | % 2008-04 27 | % Changed page margin code to use the geometry package. Also added code for 28 | % conditional page margins, depending on paper size. Thanks to Uwe Ziegenhagen 29 | % for the suggestions. 30 | 31 | % 2006-08 32 | % Made changes based on suggestions from Gene Cooperman. 33 | 34 | 35 | % To Do: 36 | % \listoffigures \listoftables 37 | % \setcounter{secnumdepth}{0} 38 | 39 | 40 | % This sets page margins to .5 inch if using letter paper, and to 1cm 41 | % if using A4 paper. (This probably isn't strictly necessary.) 42 | % If using another size paper, use default 1cm margins. 43 | \ifthenelse{\lengthtest { \paperwidth = 11in}} 44 | { \geometry{top=.5in,left=.5in,right=.5in,bottom=.5in} } 45 | {\ifthenelse{ \lengthtest{ \paperwidth = 297mm}} 46 | {\geometry{top=1cm,left=1cm,right=1cm,bottom=1cm} } 47 | {\geometry{top=1cm,left=1cm,right=1cm,bottom=1cm} } 48 | } 49 | 50 | % Turn off header and footer 51 | \pagestyle{empty} 52 | 53 | 54 | % Redefine section commands to use less space 55 | \makeatletter 56 | \renewcommand{\section}{\@startsection{section}{1}{0mm}% 57 | {-1ex plus -.5ex minus -.2ex}% 58 | {0.5ex plus .2ex}%x 59 | {\normalfont\large\bfseries}} 60 | \renewcommand{\subsection}{\@startsection{subsection}{2}{0mm}% 61 | {-1explus -.5ex minus -.2ex}% 62 | {0.5ex plus .2ex}% 63 | {\normalfont\normalsize\bfseries}} 64 | \renewcommand{\subsubsection}{\@startsection{subsubsection}{3}{0mm}% 65 | {-1ex plus -.5ex minus -.2ex}% 66 | {1ex plus .2ex}% 67 | {\normalfont\small\bfseries}} 68 | \makeatother 69 | 70 | % Define BibTeX command 71 | \def\BibTeX{{\rm B\kern-.05em{\sc i\kern-.025em b}\kern-.08em 72 | T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}} 73 | 74 | % Don't print section numbers 75 | \setcounter{secnumdepth}{0} 76 | 77 | 78 | \setlength{\parindent}{0pt} 79 | \setlength{\parskip}{0pt plus 0.5ex} 80 | 81 | 82 | % ----------------------------------------------------------------------- 83 | 84 | \begin{document} 85 | 86 | \raggedright 87 | \footnotesize 88 | \begin{multicols}{2} 89 | 90 | 91 | % multicol parameters 92 | % These lengths are set only within the two main columns 93 | %\setlength{\columnseprule}{0.25pt} 94 | \setlength{\premulticols}{1pt} 95 | \setlength{\postmulticols}{1pt} 96 | \setlength{\multicolsep}{1pt} 97 | \setlength{\columnsep}{2pt} 98 | 99 | \begin{center} 100 | \Large{\textbf{DTrace Cheat Sheet}} \\ 101 | \small{\verb|dtrace -n 'probe /predicate/ { action; }'|} 102 | \end{center} 103 | 104 | \section{FINDING PROBES} 105 | \begin{tabular}{@{}ll@{}} 106 | \verb+dtrace -l | grep foo+ & keyword search\\ 107 | \verb|dtrace -n 'fbt:::entry { @[probefunc] = count(); }'| & frequency count \\ 108 | \end{tabular} 109 | 110 | 111 | \section{PROBE ARGUMENTS} 112 | \begin{tabular}{@{}ll@{}} 113 | \verb|syscall:::| & \verb|man syscallname|\\ 114 | \verb|fbt:::| & Kernel functions 115 | \end{tabular} 116 | 117 | \section{PROBES} 118 | \begin{tabular}{@{}ll@{}} 119 | \verb|BEGIN| & D program start\\ 120 | \verb|END| & D program end\\ 121 | \verb|tick-1sec| & run once per sec, one CPU only\\ 122 | \verb|syscall::read*:entry| & process reads\\ 123 | \verb|syscall::write*:entry| & process writes\\ 124 | \verb|syscall::open*:entry| & file open\\ 125 | \verb|proc:::exec-success| & process create\\ 126 | \verb|io:::start,io:::done| & storage I/O\\ 127 | \verb|lockstat:::adaptive-block| & kernel blocking mutex\\ 128 | \verb|sched:::off-cpu| & thread leaves a CPU\\ 129 | \verb|fbt:::entry| & all kernel functions\\ 130 | \verb|profile-123 | & sample at 123Hz\\ 131 | \end{tabular} 132 | 133 | \section{D VARIABLES} 134 | \begin{tabular}{@{}ll@{}} 135 | \verb|execname| & on-CPU process name \\ 136 | \verb|pid, tid| & on-CPU PID, Thread ID\\ 137 | \verb|cpu| & CPU ID\\ 138 | \verb|timestamp| & time, nanoseconds\\ 139 | \verb|vtimestamp| & time thread was on-CPU (ns)\\ 140 | \verb|arg0...N| & probe args (uint64)\\ 141 | \verb|args[0]...[N]| & probe args (type'd)\\ 142 | \verb|curthread| & pointer to current thread \\ 143 | \verb|probemod| & module name\\ 144 | \verb|probefunc| & function name\\ 145 | \verb|probename| & probe name\\ 146 | \verb|self->foo| & thread local variable\\ 147 | \verb|this->foo| & clause local variable\\ 148 | \verb|$1...$N| & arguments as integers\\ 149 | \verb|$$1...$$N| & arguments as strings\\ 150 | \verb|$target| & -p PID, -c command\\ 151 | \verb|curpsinfo| & process information\\ 152 | \end{tabular} 153 | 154 | \section{ACTIONS} 155 | \begin{tabular}{@{}ll@{}} 156 | \verb|@agg[key1, key2] = count()| & frequency count\\ 157 | \verb|@agg[key1, key2] = sum(var)| & sum variable\\ 158 | \verb|@agg[key1, key2] = quantize(var)| & power of 2 quanization\\ 159 | \verb|printf("format", var0...varN)| & print vars\\ 160 | \verb|stack(num), ustack(num)| & print num lines of kernel or user 161 | stack\\ 162 | \verb|func(pc), ufunc(pc)| & return kernel/user function name from a 163 | PC\\ 164 | \verb|clear(@)| & clear an aggregation\\ 165 | \verb|trunc(@, 5)| & truncate aggreation to top 5 entries\\ 166 | \verb|stringof(ptr)| & string from kernel address\\ 167 | \verb|copyinstr(ptr)| & string from user address\\ 168 | \verb|exit(0);| & exit dtrace\\ 169 | \end{tabular} 170 | 171 | \section{SWITCHES} 172 | \begin{tabular}{@{}ll@{}} 173 | \verb|-n| & trace the given probe point\\ 174 | \verb|-l| & list probes instead of tracing\\ 175 | \verb|-q| & quiet; don't print default output\\ 176 | \verb|-s | & invoke a D script file\\ 177 | \verb|-w| & allow destructive actions\\ 178 | \verb|-p PID| & allow \verb|pid:::| provider to trace this pid; it's also \verb|$target|\\ 179 | \verb|-c 'command'| & have dtrace invoke a command\\ 180 | \verb|-o file| & send trace output to a file\\ 181 | \verb|-x options| & set various DTrace options (switchrate, bufsize...)\\ 182 | \end{tabular} 183 | 184 | \section{PRAGMAS} 185 | \begin{tabular}{@{}ll@{}} 186 | \verb|#pragma D option quiet| & same as \verb|-q|, quiet output\\ 187 | \verb|#pragma D option destructive| & same as \verb|-w|, allow 188 | destructive actions\\ 189 | \verb|#pragma D option switchrate=10hz| & print at 10Hz instead of 190 | 1Hz\\ 191 | \verb|#pragma D option bufsize=16m| & set per-CPU buffer size\\ 192 | \verb|#pragma D option defaultargs| & \verb|$1| is 0, \verb|$$1| is ""\\ 193 | \end{tabular} 194 | 195 | \section{ONE-LINERS} 196 | \begin{lstlisting} 197 | dtrace -n 'proc:::exec-success{ trace(curpsinfo->pr_psargs); }' 198 | dtrace -n 'syscall:::entry { @num[execname] = count(); }' 199 | dtrace -n 'syscall::open*:entry { printf("%s %s", execname, copyinstr(arg0)); }' dtrace -n 'io:::start { @size = quantize(args[0]->b_bcount); }' 200 | dtrace -n 'fbt:::entry { @calls[probemod] = count(); }' 201 | dtrace -n 'sysinfo:::xcalls { @num[execname] = count(); }' 202 | dtrace -n 'profile-1001 { @[stack()] = count() }' 203 | dtrace -n 'profile-101 /pid == $target/ { @[ustack()] = count() }' -p PID dtrace -n 'syscall:::entry { @num[probefunc] = count(); }' 204 | dtrace -n 'syscall::read*:entry { @[fds[arg0].fi_pathname] = count(); }' 205 | dtrace -n 'vminfo:::as_fault { @mem[execname] = sum(arg0); }' 206 | dtrace -n 'sched:::off-cpu /pid == $target/ { @[stack()] = count(); }' -p PID dtrace -n 'pid$target:libfoo::entry { @[probefunc] = count(); }' -p PID 207 | \end{lstlisting} 208 | \end{multicols} 209 | \end{document} 210 | 211 | %%% Local Variables: 212 | %%% mode: latex 213 | %%% TeX-master: t 214 | %%% End: 215 | --------------------------------------------------------------------------------