ksyms pseudo driver

[Stacey Son]

Hi,

I have created a ksyms pseudo driver for FreeBSD. Included below is the 
man page.  The diff's to kernel source, the main source files, etc. can 
be found at:

     http://people.FreeBSD.org/~sson/ksyms/

The reason I created this driver is for dtrace and the port of the 
opensolaris lockstat(1M) command to FreeBSD.  The ksyms driver allows a 
process to get a quick
snapshot of the kernel symbol table including the symbols from any 
loaded modules.

Unlike most other implementations, this ksyms driver maps memory in the 
process space to store the snapshot at the time /dev/ksyms is opened.  
It also checks to see if the process has already a snapshot open and 
won't allow it to open /dev/ksyms it again until it closes (and unmaps) 
its already opened snapshot first. Of course, this requires the read() 
handler to bounce the buffer into the kernel first before it is written 
back out to userspace.  (Maybe there is a simple way to do an userspace 
to userspace copy instead?) The reason I went to all this trouble is to 
keep /dev/ksyms from turning into an easy way to exhaust all the kernel 
memory (unintentionally or intentionally).

Let me know if you have any questions, comments, suggestions, and/or 
reasons why something like this should never be included in FreeBSD.

Best Regards,

-stacey.

-----------------------------------------------------------------------------------
KSYMS(4)               FreeBSD Kernel Interfaces Manual               
KSYMS(4)

NAME
      ksyms -- kernel symbol table interface

SYNOPSIS
      device ksyms

DESCRIPTION
      The /dev/ksyms character device provides a read-only interface to 
a snap-
      shot of the kernel symbol table.  The in-kernel symbol manager is
      designed to be able to handle many types of symbols tables, 
however, only
      elf(5) symbol tables are supported by this device.  The ELF format 
image
      contains two sections: a symbol table and a corresponding string 
table.

            Symbol Table
                    The SYMTAB section contains the symbol table entries
                    present in the current running kernel, including the 
symbol
                    table entries of any loaded modules. The symbols are
                    ordered by the kernel module load time starting with 
kernel
                    file symbols first, followed by the first loaded 
module's
                    symbols and so on.

            String Table
                    The STRTAB section contains the symbol name strings from
                    the kernel and any loaded modules that the symbol table
                    entries reference.

      Elf formatted symbol table data read from the /dev/ksyms file 
represents
      the state of the kernel at the time when the device is opened.  Since
      /dev/ksyms has no text or data, most of the fields are initialized to
      NULL.  The ksyms driver does not block the loading or unloading of 
mod-
      ules into the kernel while the /dev/ksyms file is open but may contain
      stale data.

IOCTLS
      The ioctl(2) command codes below are defined in <sys/ksyms.h>.

      The (third) argument to the ioctl(2) should be a pointer to the type
      indicated.

            KIOCGSIZE (size_t)
                    Returns the total size of the current symbol table.  
This
                    can be used when allocating a buffer to make a copy 
of the
                    kernel symbol table.

            KIOCGADDR (void *)
                    Returns the address of the kernel symbol table mapped in
                    the process memory.

FILES
      /dev/ksyms

ERRORS
      An open(2) of /dev/ksyms will fail if:

      [EBUSY]            The device is already open.  A process must close
                         /dev/ksyms before it can be opened again.

      [ENOMEM]           There is a resource shortage in the kernel.

      [ENXIO]            The driver was unsuccessful in creating a 
snapshot of
                         the kernel symbol table.  This may occur if the 
kernel
                         was in the process of loading or unloading a 
module.

SEE ALSO
      ioctl(2), nlist(3), elf(5), kldload(8)

HISTORY
      A ksyms device exists in many different operating systems.  This 
imple-
      mentation is similar in function to the Solaris and NetBSD ksyms 
driver.

      The ksyms driver first appeared in FreeBSD 8.0 to support lockstat(1).

BUGS
      Because files can be dynamically linked into the kernel at any 
time the
      symbol information can vary.  When you open the /dev/ksyms file, 
you have
      access to an ELF image which represents a snapshot of the state of the
      kernel symbol information at that instant in time. Keeping the device
      open does not block the loading or unloading of kernel modules.  
To get a
      new snapshot you must close and re-open the device.

      A process is only allowed to open the /dev/ksyms file once at a time.
      The process must close the /dev/ksyms before it is allowed to open it
      again.

      The ksyms driver uses the calling process' memory address space to 
store
      the snapshot.  ioctl(2) can be used to get the memory address 
where the
      symbol table is stored to save kernel memory.  mmap(2) may also be 
used
      but it will map it to another address.

AUTHORS
      The ksyms driver was written by Stacey Son <sson at freebsd.org> 
under the
      direction of John Birrell.

FreeBSD 8.0                      April 5, 2008                     
FreeBSD 8.0