Solaris Modular Debugger Guide
|
|||
|
4. Using MDB Commands Interactively 9. Debugging With the Kernel Memory Allocator |
API Functionsmdb_pwalk()int mdb_pwalk(const char *name, mdb_walk_cb_t func, void *data,
uintptr_t addr);Initiate a local walk starting at addr using the walker specified by name, and invoke the callback function func at each step. If addr is NULL, a global walk is performed (that is, the mdb_pwalk() invocation is equivalent to the identical call to mdb_walk() without the trailing addr parameter). This function returns 0 for success, or -1 for error. The mdb_pwalk() function fails if the walker itself returns a fatal error, or if the specified walker name is not known to the debugger. The walker name may be scoped using the backquote (`) operator if there are naming conflicts. The data parameter is an opaque argument that has meaning only to the caller; it is passed back to func at each step of the walk. mdb_walk()int mdb_walk(const char *name, mdb_walk_cb_t func, void *data); Initiate a global walk starting at addr using the walker specified by name, and invoke the callback function func at each step. This function returns 0 for success, or -1 for error. The mdb_walk() function fails if the walker itself returns a fatal error, or if the specified walker name is not known to the debugger. The walker name can be scoped using the backquote (`) operator if there are naming conflicts. The data parameter is an opaque argument that has meaning only to the caller; it is passed back to func at each step of the walk. mdb_pwalk_dcmd()int mdb_pwalk_dcmd(const char *wname, const char *dcname, int argc,
const mdb_arg_t *argv, uintptr_t addr);Initiate a local walk starting at addr using the walker specified by wname, and invoke the dcmd specified by dcname with the specified argc and argv at each step. This function returns 0 for success, or -1 for error. The function fails if the walker itself returns a fatal error, if the specified walker name or dcmd name is not known to the debugger, or if the dcmd itself returns DCMD_ABORT or DCMD_USAGE to the walker. The walker name and dcmd name can each be scoped using the backquote (`) operator if there are naming conflicts. When invoked from mdb_pwalk_dcmd(), the dcmd will have the DCMD_LOOP and DCMD_ADDRSPEC bits set in its flags parameter, and the first call will have DCMD_LOOPFIRST set. mdb_walk_dcmd()int mdb_walk_dcmd(const char *wname, const char *dcname, int argc,
const mdb_arg_t *argv);Initiate a global walk using the walker specified by wname, and invoke the dcmd specified by dcname with the specified argc and argv at each step. This function returns 0 for success, or -1 for error. The function fails if the walker itself returns a fatal error, if the specified walker name or dcmd name is not known to the debugger, or if the dcmd itself returns DCMD_ABORT or DCMD_USAGE to the walker. The walker name and dcmd name can each be scoped using the backquote (`) operator if there are naming conflicts. When invoked from mdb_walk_dcmd(), the dcmd will have the DCMD_LOOP and DCMD_ADDRSPEC bits set in its flags parameter, and the first call will have DCMD_LOOPFIRST set. mdb_call_dcmd()int mdb_call_dcmd(const char *name, uintptr_t addr, uint_t flags,
int argc, const mdb_arg_t *argv);Invoke the specified dcmd name with the given parameters. The dot variable is reset to addr, and addr, flags, argc, and argv are passed to the dcmd. The function returns 0 for success, or -1 for error. The function fails if the dcmd returns DCMD_ERR, DCMD_ABORT, or DCMD_USAGE, or if the specified dcmd name is not known to the debugger. The dcmd name can be scoped using the backquote (`) operator if there are naming conflicts. mdb_layered_walk()int mdb_layered_walk(const char *name, mdb_walk_state_t *wsp); Layer the walk denoted by wsp on top of a walk initiated using the specified walker name. The name can be scoped using the backquote (`) operator if there are naming conflicts. Layered walks can be used, for example, to facilitate constructing walkers for data structures that are embedded in other data structures. For example, suppose that each CPU structure in the kernel contains a pointer to an embedded structure. To write a walker for the embedded structure type, you could replicate the code to iterate over CPU structures and dereference the appropriate member of each CPU structure, or you could layer the embedded structure's walker on top of the existing CPU walker. The mdb_layered_walk() function is used from within a walker's init routine to add a new layer to the current walk. The underlying layer is initialized as part of the call to mdb_layered_walk(). The calling walk routine passes in a pointer to its current walk state; this state is used to construct the layered walk. Each layered walk is cleaned up after the caller's walk fini function is called. If more than one layer is added to a walk, the caller's walk step function will step through each element returned by the first layer, then the second layer, and so forth. The mdb_layered_walk() function returns 0 for success, or -1 for error. The function fails if the specified walker name is not known to the debugger, if the wsp pointer is not a valid, active walk state pointer, if the layered walker itself fails to initialize, or if the caller attempts to layer the walker on top of itself. mdb_add_walker()int mdb_add_walker(const mdb_walker_t *w); Register a new walker with the debugger. The walker is added to the module's namespace, and to the debugger's global namespace according to the name resolution rules described in Dcmd and Walker Name Resolution. This function returns 0 for success, or -1 for error if the given walker name is already registered by this module, or if the walker structure w is improperly constructed. The information in the mdb_walker_t w is copied to internal debugger structures, so the caller can reuse or free this structure after the call to mdb_add_walker(). mdb_remove_walker()int mdb_remove_walker(const char *name); Remove the walker with the specified name. This function returns 0 for success, or -1 for error. The walker is removed from the current module's namespace. The function fails if the walker name is unknown, or is registered only in another module's namespace. The mdb_remove_walker() function can be used to remove walkers that were added dynamically using mdb_add_walker(), or walkers that were added statically as part of the module's linkage structure. The scoping operator cannot be used in the walker name; it is not legal for the caller of mdb_remove_walker() to attempt to remove a walker exported by a different module. mdb_vread() and mdb_vwrite()ssize_t mdb_vread(void *buf, size_t nbytes, uintptr_t addr); ssize_t mdb_vwrite(const void *buf, size_t nbytes, uintptr_t addr); These functions provide the ability to read and write data from a given target virtual address, specified by the addr parameter. The mdb_vread() function returns nbytes for success, or -1 for error; if a read is truncated because only a portion of the data can be read from the specified address, -1 is returned. The mdb_vwrite() function returns the number of bytes actually written upon success; -1 is returned upon error. mdb_fread() and mdb_fwrite()ssize_t mdb_fread(void *buf, size_t nbytes, uintptr_t addr); ssize_t mdb_fwrite(const void *buf, size_t nbytes, uintptr_t addr); These functions provide the ability to read and write data from the object file location corresponding to the given target virtual address, specified by the addr parameter. The mdb_fread() function returns nbytes for success, or -1 for error; if a read is truncated because only a portion of the data can be read from the specified address, -1 is returned. The mdb_fwrite() function returns the number of bytes actually written upon success; -1 is returned upon error. mdb_pread() and mdb_pwrite()ssize_t mdb_pread(void *buf, size_t nbytes, uint64_t addr); ssize_t mdb_pwrite(const void *buf, size_t nbytes, uint64_t addr); These functions provide the ability to read and write data from a given target physical address, specified by the addr parameter. The mdb_pread() function returns nbytes for success, or -1 for error; if a read is truncated because only a portion of the data can be read from the specified address, -1 is returned. The mdb_pwrite() function returns the number of bytes actually written upon success; -1 is returned upon error. mdb_readstr()ssize_t mdb_readstr(char *s, size_t nbytes, uintptr_t addr); The mdb_readstr() function reads a null-terminated C string beginning at the target virtual address addr into the buffer addressed by s. The size of the buffer is specified by nbytes. If the string is longer than can fit in the buffer, the string is truncated to the buffer size and a null byte is stored at s[nbytes - 1]. The length of the string stored in s (not including the terminating null byte) is returned upon success; otherwise -1 is returned to indicate an error. mdb_writestr()ssize_t mdb_writestr(const char *s, uintptr_t addr); The mdb_writestr() function writes a null-terminated C string from s (including the trailing null byte) to the target's virtual address space at the address specified by addr. The number of bytes written (not including the terminating null byte) is returned upon success; otherwise, -1 is returned to indicate an error. mdb_readsym()ssize_t mdb_readsym(void *buf, size_t nbytes, const char *name); mdb_readsym() is similar to mdb_vread(), except that the virtual address at which reading begins is obtained from the value of the symbol specified by name. If no symbol by that name is found or a read error occurs, -1 is returned; otherwise nbytes is returned for success. The caller can first look up the symbol separately if it is necessary to distinguish between symbol lookup failure and read failure. The primary executable's symbol table is used for the symbol lookup; if the symbol resides in another symbol table, you must first apply mdb_lookup_by_obj(), then mdb_vread(). mdb_writesym()ssize_t mdb_writesym(const void *buf, size_t nbytes, const char *name); mdb_writesym() is identical to mdb_vwrite(), except that the virtual address at which writing begins is obtained from the value of the symbol specified by name. If no symbol by that name is found, -1 is returned. Otherwise, the number of bytes successfully written is returned on success, and -1 is returned on error. The primary executable's symbol table is used for the symbol lookup; if the symbol resides in another symbol table, you must first apply mdb_lookup_by_obj(), then mdb_vwrite(). mdb_readvar() and mdb_writevar()ssize_t mdb_readvar(void *buf, const char *name); ssize_t mdb_writevar(const void *buf, const char *name); mdb_readvar() is similar to mdb_vread(), except that the virtual address at which reading begins and the number of bytes to read are obtained from the value and size of the symbol specified by name. If no symbol by that name is found, -1 is returned. The symbol size (the number of bytes read) is returned on success; -1 is returned on error. This is useful for reading well-known variables whose sizes are fixed. For example: int hz; /* system clock rate */
mdb_readvar(&hz, "hz");The caller can first look up the symbol separately if it is necessary to distinguish between symbol lookup failure and read failure. The caller must also carefully check the definition of the symbol of interest in order to make sure that the local declaration is the exact same type as the target's definition. For example, if the caller declares an int, and the symbol of interest is actually a long, and the debugger is examining a 64-bit kernel target, mdb_readvar() copies back 8 bytes to the caller's buffer, corrupting the 4 bytes following the storage for the int. mdb_writevar() is identical to mdb_vwrite(), except that the virtual address at which writing begins and the number of bytes to write are obtained from the value and size of the symbol specified by name. If no symbol by that name is found, -1 is returned. Otherwise, the number of bytes successfully written is returned on success, and -1 is returned on error. For both functions, the primary executable's symbol table is used for the symbol lookup; if the symbol resides in another symbol table, you must first apply mdb_lookup_by_obj(), then mdb_vread() or mdb_vwrite(). mdb_lookup_by_name() and mdb_lookup_by_obj()int mdb_lookup_by_name(const char *name, GElf_Sym *sym); int mdb_lookup_by_obj(const char *object, const char *name, GElf_Sym *sym); Look up the specified symbol name and copy the ELF symbol information into the GElf_Sym pointed to by sym. If the symbol is found, the function returns 0; otherwise, -1 is returned. The name parameter specifies the symbol name. The object parameter tells the debugger where to look for the symbol. For the mdb_lookup_by_name() function, the object file defaults to MDB_OBJ_EXEC. For mdb_lookup_by_obj(), the object name should be one of the following:
mdb_lookup_by_addr()int mdb_lookup_by_addr(uintptr_t addr, uint_t flag, char *buf,
size_t len, GElf_Sym *sym);Locate the symbol corresponding to the specified address and copy the ELF symbol information into the GElf_Sym pointed to by sym and the symbol name into the character array addressed by buf. If a corresponding symbol is found, the function returns 0; otherwise -1 is returned. The flag parameter specifies the lookup mode and should be one of the following:
If a symbol match occurs, the name of the symbol is copied into the buf supplied by the caller. The len parameter specifies the length of this buffer in bytes. The caller's buf should be at least of size MDB_SYM_NAMLEN bytes. The debugger copies the name to this buffer and appends a trailing null byte. If the name length exceeds the length of the buffer, the name is truncated but always includes a trailing null byte. mdb_getopts()int mdb_getopts(int argc, const mdb_arg_t *argv, ...); Parse and process options and option arguments from the specified argument array (argv). The argc parameter denotes the length of the argument array. This function processes each argument in order, and stops and returns the array index of the first argument that could not be processed. If all arguments are processed successfully, argc is returned. Following the argc and argv parameters, the mdb_getopts() function accepts a variable list of arguments describing the options that are expected to appear in the argv array. Each option is described by an option letter (char argument), an option type (uint_t argument), and one or two additional arguments, as shown in the table below. The list of option arguments is terminated with a NULL argument. The type should be one of one of the following:
For example, the following source code: int
dcmd(uintptr_t addr, uint_t flags, int argc, const mdb_arg_t *argv)
{
uint_t opt_v = FALSE;
const char *opt_s = NULL;
if (mdb_getopts(argc, argv,
'v', MDB_OPT_SETBITS, TRUE, &opt_v,
's', MDB_OPT_STR, &opt_s, NULL) != argc)
return (DCMD_USAGE);
/* ... */
}demonstrates how mdb_getopts() might be used in a dcmd to accept a boolean option “-v” that sets the opt_v variable to TRUE, and an option “-s” that accepts a string argument that is stored in the opt_s variable. The mdb_getopts() function also automatically issues warning messages if it detects an invalid option letter or missing option argument before returning to the caller. The storage for argument strings and the argv array is automatically garbage-collected by the debugger upon completion of the dcmd. mdb_strtoull()u_longlong_t mdb_strtoull(const char *s); Convert the specified string s to an unsigned long long representation. This function is intended for use in processing and converting string arguments in situations where mdb_getopts() is not appropriate. If the string argument cannot be converted to a valid integer representation, the function fails by printing an appropriate error message and aborting the dcmd. Therefore, error checking code is not required. The string can be prefixed with any of the valid base specifiers (0i, 0I, 0o, 0O, 0t, 0T, 0x, or 0X); otherwise, it is interpreted using the default base. The function will fail and abort the dcmd if any of the characters in s are not appropriate for the base, or if integer overflow occurs. mdb_alloc(), mdb_zalloc() and mdb_free()void *mdb_alloc(size_t size, uint_t flags); void *mdb_zalloc(size_t size, uint_t flags); void mdb_free(void *buf, size_t size); mdb_alloc() allocates size bytes of debugger memory and returns a pointer to the allocated memory. The allocated memory is at least double-word aligned, so it can hold any C data structure. No greater alignment can be assumed. The flags parameter should be the bitwise OR of one or more of the following values:
mdb_zalloc() is like mdb_alloc(), but the allocated memory is filled with zeroes before returning it to the caller. No guarantees are made about the initial contents of memory returned by mdb_alloc(). mdb_free() is used to free previously allocated memory (unless it was allocated UM_GC). The buffer address and size must exactly match the original allocation. It is not legal to free only a portion of an allocation with mdb_free(). It is not legal to free an allocation more than once. An allocation of zero bytes always returns NULL; freeing a NULL pointer with size zero always succeeds. mdb_printf()void mdb_printf(const char *format, ...); Print formatted output using the specified format string and arguments. Module writers should use mdb_printf() for all output, except for warning and error messages. This function automatically triggers the built-in output pager when appropriate. The mdb_printf() function is similar to printf(3C), with certain exceptions: the %C, %S, and %ws specifiers for wide character strings are not supported, the %f floating-point format is not supported, the %e, %E, %g, and %G specifiers for alternative double formats produce only a single style of output, and precision specifications of the form %.n are not supported. The list of specifiers that are supported follows: Flag Specifiers
Field Width Specifiers
Integer Specifiers
Terminal Attribute SpecifiersIf standard output for the debugger is a terminal, and terminal attributes can be obtained by the terminfo database, the following terminal escape constructs can be used:
If no terminal information is available, each terminal attribute construct is ignored by mdb_printf(). For more information on terminal attributes, see terminfo(4). The available terminfo attributes are:
Format Specifiers
mdb_snprintf()size_t mdb_snprintf(char *buf, size_t len, const char *format, ...); Construct a formatted string based on the specified format string and arguments, and store the resulting string into the specified buf. The mdb_snprintf() function accepts the same format specifiers and arguments as the mdb_printf() function. The len parameter specifies the size of buf in bytes. No more than len - 1 formatted bytes are placed in buf; mdb_snprintf() always terminates buf with a null byte. The function returns the number of bytes required for the complete formatted string, not including the terminating null byte. If the buf parameter is NULL and len is set to zero, the function will not store any characters to buf and returns the number of bytes required for the complete formatted string; this technique can be used to determine the appropriate size of a buffer for dynamic memory allocation. mdb_warn()void mdb_warn(const char *format, ...); Print an error or warning message to standard error. The mdb_warn() function accepts a format string and variable argument list that can contain any of the specifiers documented for mdb_printf(). However, the output of mdb_warn() is sent to standard error, which is not buffered and is not sent through the output pager or processed as part of a dcmd pipeline. All error messages are automatically prefixed with the string “mdb:”. In addition, if the format parameter does not contain a newline (\n) character, the format string is implicitly suffixed with the string “: %s\n”, where %s is replaced by the error message string corresponding to the last error recorded by a module API function. For example, the following source code: if (mdb_lookup_by_name("no_such_symbol", &sym) == -1)
mdb_warn("lookup_by_name failed");produces this output: mdb: lookup_by_name failed: unknown symbol name mdb_flush()void mdb_flush(void); Flush all currently buffered output. Normally, mdb's standard output is line-buffered; output generated using mdb_printf() is not flushed to the terminal (or other standard output destination) until a newline is encountered, or at the end of the current dcmd. However, in some situations you might want to explicitly flush standard output prior to printing a newline; mdb_flush() can be used for this purpose. mdb_nhconvert()void mdb_nhconvert(void *dst, const void *src, size_t nbytes); Convert a sequence of nbytes bytes stored at the address specified by src from network byte order to host byte order and store the result at the address specified by dst. The src and dst parameters may be the same, in which case the object is converted in place. This function may be used to convert from host order to network order or from network order to host order, since the conversion is the same in either case. mdb_dumpptr() and mdb_dump64()int mdb_dumpptr(uintptr_t addr, size_t nbytes, uint_t flags,
mdb_dumpptr_cb_t func, void *data);
int mdb_dump64(uint64_t addr, uint64_t nbytes, uint_t flags,
mdb_dump64_cb_t func, void *data);These functions can be used to generate formatted hexadecimal and ASCII data dumps that are printed to standard output. Each function accepts an addr parameter specifying the starting location, a nbytes parameter specifying the number of bytes to display, a set of flags described below, a func callback function to use to read the data to display, and a data parameter that is passed to each invocation of the callback func as its last argument. The functions are identical in every regard except that mdb_dumpptr uses uintptr_t for its address parameters and mdb_dump64 uses uint64_t. This distinction is useful when combining mdb_dump64 with mdb_pread, for example. The built-in ::dump dcmd uses these functions to perform its data display. The flags parameter should be the bitwise OR of one or more of the following values:
mdb_one_bit()const char *mdb_one_bit(int width, int bit, int on); The mdb_one_bit() function can be used to print a graphical representation of a bit field in which a single bit of interest is turned on or off. This function is useful for creating verbose displays of bit fields similar to the output from snoop(1M) -v. For example, the following source code: #define FLAG_BUSY 0x1
uint_t flags;
/* ... */
mdb_printf("%s = BUSY\n", mdb_one_bit(8, 0, flags & FLAG_BUSY));produces this output: .... ...1 = BUSY Each bit in the bit field is printed as a period (.), with each 4-bit sequence separated by a white space. The bit of interest is printed as 1 or 0, depending on the setting of the on parameter. The total width of the bit field in bits is specified by the width parameter, and the bit position of the bit of interest is specified by the bit parameter. Bits are numbered starting from zero. The function returns a pointer to an appropriately sized, null-terminated string containing the formatted bit representation. The string is automatically garbage-collected upon completion of the current dcmd. mdb_inval_bits()const char *mdb_inval_bits(int width, int start, int stop); The mdb_inval_bits() function is used, along with mdb_one_bit(), to print a graphical representation of a bit field. This function marks a sequence of bits as invalid or reserved by displaying an 'x' at the appropriate bit location. Each bit in the bit field is represented as a period (.), except for those bits in the range of bit positions specified by the start and stop parameters. Bits are numbered starting from zero. For example, the following source code: mdb_printf("%s = reserved\n", mdb_inval_bits(8, 7, 7));produces this output: x... .... = reserved The function returns a pointer to an appropriately sized, null-terminated string containing the formatted bit representation. The string is automatically garbage-collected upon completion of the current dcmd. mdb_inc_indent() and mdb_dec_indent()ulong_t mdb_inc_indent(ulong_t n); ulong_t mdb_dec_indent(ulong_t n); These functions increment and decrement the numbers of columns that MDB will auto-indent with white space before printing a line of output. The size of the delta is specified by n, a number of columns. Each function returns the previous absolute value of the indent. Attempts to decrement the indent below zero have no effect. Following a call to either function, subsequent calls to mdb_printf() are indented appropriately. If the dcmd completes or is forcibly terminated by the user, the indent is restored automatically to its default setting by the debugger. mdb_eval()int mdb_eval(const char *s); Evaluate and execute the specified command string s, as if it had been read from standard input by the debugger. This function returns 0 for success, or -1 for error. mdb_eval() fails if the command string contains a syntax error, or if the command string executed by mdb_eval() is forcibly aborted by the user using the pager or by issuing an interrupt. mdb_set_dot() and mdb_get_dot()void mdb_set_dot(uintmax_t dot); uintmax_t mdb_get_dot(void); Set or get the current value of dot (the “.” variable). Module developers might want to reposition dot so that, for example, it refers to the address following the last address read by the dcmd. mdb_get_pipe()void mdb_get_pipe(mdb_pipe_t *p); Retrieve the contents of the pipeline input buffer for the current dcmd. The mdb_get_pipe() function is intended to be used by dcmds that want to consume the complete set of pipe input and execute only once, instead of being invoked repeatedly by the debugger for each pipe input element. Once mdb_get_pipe() is invoked, the dcmd will not be invoked again by the debugger as part of the current command. This can be used, for example, to construct a dcmd that sorts a set of input values. The pipe contents are placed in an array that is garbage-collected upon termination of the dcmd, and the array pointer is stored in p->pipe_data. The length of the array is placed in p->pipe_len. If the dcmd was not executed on the right-hand side of a pipeline (that is, the DCMD_PIPE flag was not set in its flags parameter), p->pipe_data is set to NULL and p->pipe_len is set to zero. mdb_set_pipe()void mdb_set_pipe(const mdb_pipe_t *p); Set the pipeline output buffer to the contents described by the pipe structure p. The pipe values are placed in the array p->pipe_data, and the length of the array is stored in p->pipe_len. The debugger makes its own copy of this information, so the caller must remember to free p->pipe_data if necessary. If the pipeline output buffer was previously non-empty, its contents are replaced by the new array. If the dcmd was not executed on the left side of a pipeline (that is, the DCMD_PIPE_OUT flag was not set in its flags parameter), this function has no effect. mdb_get_xdata()ssize_t mdb_get_xdata(const char *name, void *buf, size_t nbytes); Read the contents of the target external data buffer specified by name into the buffer specified by buf. The size of buf is specified by the nbytes parameter; no more than nbytes will be copied to the caller's buffer. The total number of bytes read will be returned upon success; -1 will be returned upon error. If the caller wants to determine the size of a particular named buffer, buf should be specified as NULL and nbytes should be specified as zero. In this case, mdb_get_xdata() will return the total size of the buffer in bytes but no data will be read. External data buffers provide module writers access to target data that is not otherwise accessible through the module API. The set of named buffers exported by the current target can be viewed using the ::xdata built-in dcmd. Additional FunctionsAdditionally, module writers can use the following string(3C) and bstring(3C) functions. They are guaranteed to have the same semantics as the functions described in the corresponding Solaris man page. strcat() strcpy() strncpy() strchr() strrchr() strcmp() strncmp() strcasecmp() strncasecmp() strlen() bcmp() bcopy() bzero() bsearch() qsort() |
||
|