Hi all,
I've written up the following ARC case for my ::whatis rewrite, and wanted
to see if there were any comments before I submit it for PSARC review.
What do you all think?
Thanks,
- jonathan
-------------- next part --------------
Introduction/Background
-----------------------
A workhorse in the kernel debugging toolchest is the "::whatis" dcmd,
which is provided by the "genunix" dmod, and is described as "given a
virtual address, return information."
There are a few problems with the current state of ::whatis:
1. When used in a pipeline (as it often is), ::whatis can be
slow; for each address, a search of the allocation metadata
is done, leading to O(slow) behavior.
2. The lack of extensibility means that we have hacks like the
sun4u 'unix' dmod's overriding of "::whatis" to identify
traptrace records.
3. The support in userland is anemic; the libumem.so dmod
provides a minimal version, but things like identifying
mappings or thread stacks is not done.
This case moves ::whatis into the built-in dcmds. The stability level
is Evolving, and this case seeks micro/patch binding.
The Solution
------------
This case moves the ::whatis dcmd from genunix/libumem.so into the
built-in "mdb" module, and makes it an Evolving interface (as the rest
of the built-in dcmds are). "Chapter 5: Built-in commands" of the
Modular Debugger Guide will have a new entry:
address ::whatis [-aikqv]
Find information about <b>address</a>. When fed multiple addresses from
a pipeline, ::whatis will report information as it finds it unless the
<b>-k</b> flag is given. If the <b>-a</b> option is given, all information
is given for each address; without <b>-a</b>, only the first (most specific)
match is reported. With <b>-i</b>, <b>address</b> is treated as an
identifier instead of a virtual address. With the <b>-q</b>, reports
will be single-line reports; without <b>-q</b>, reports can be multi-line,
if stack traces, etc. are available. With <b>-v</b>, information on the
progress of the search is reported.
And the help message for ::whatis will read:
> ::help whatis
NAME
whatis - given an address, return information
SYNOPSIS
addr ::whatis [-aikqv]
DESCRIPTION
Given a virtual address (with -i, an identifier), report where it came
from.
When fed from a pipeline, ::whatis will not maintain the order the input
comes in; addresses will be reported as it finds them. (-k prevents this;
the output will be in the same order as the input)
OPTIONS
-a Report all information about each address/identifier. The default
behavior is to report only the first (most specific) source for each
address/identifier.
-i addr is an identifier, not a virtual address.
-k Do not re-order the input. (may be slower)
-q Quiet; don't print multi-line reports. (stack traces, etc.)
-v Verbose output; display information about the progress of the search
SOURCES
The following information sources will be used:
module`sourcename
...
mdb`mappings
ATTRIBUTES
Target: [target]
Module: mdb
Interface Stability: Evolving
>
The sources list and their behavior is all Volatile. Each entry in the list
consists of "module name"`"source name", and they are listed in the order they
will be searched.
The sources are registered and implemented using a Project Private interface.
In the future when we have more experience with it, the interface could be
added to the MDB Module interface, so that third-parties dmods could add to it.
3. Aside: Implementation details (for-your-information only)
For the kernel, the list will start out as:
genunix`modules
genunix`threads
genunix`pages
unix`traptrace (sun4[uv] only)
genunix`kmem
genunix`vmem
mdb`mappings
And for userland, the list will start out as:
libc.so.1`threads
libumem.so.1`umem (if libumem.so is loaded)
libumem.so.1`vmem (if libumem.so is loaded)
mdb`mappings
The "libc.so.1`threads" and "mdb`mappings" sources represent new behavior;
mdb`mappings reports which mapping the address is in (using the same
data as ::mappings), and libc.so.1`threads reports on thread stacks;
the combination of the two brings userland ::whatis functionality to
the same level as the kernel's.
4. Interface Tables
Exported Interfaces
+-------------------------------------------------------+-----------------+
| Interface | Stability |
+-------------------------------------------------------+-----------------+
| ::whatis dcmd and command-line arguments | Committed |
| ::whatis dcmd output and search behavior | Volatile |
| Contents of ::whatis source list | Volatile |
| MDB ::whatis source interface | Project Private |
+-------------------------------------------------------+-----------------+
Imported Interfaces
None.
5. See also
PSARC/1999/583 MDB Module API
