KLD(3) KLD(3)
NAME
kld_load, kld_load_from_memory, kld_lookup, kld_forget_symbol, kld_unload_all, kld_load_basefile,
kld_load_basefile_from_memory, kld_address_func, kld_set_link_options - programmatically link edit
and load driver object files
SYNOPSIS
#include <kld.h>
#ifdef __DYNAMIC__
__private_extern__ long kld_load_basefile(
const char *base_filename);
__private_extern__ long kld_load(
struct mach_header **header_addr,
const char *object_filename,
const char *output_filename);
__private_extern__ long kld_load_from_memory(
struct mach_header **header_addr,
const char *object_name,
char *object_addr,
long object_size,
const char *output_filename);
#endif /* __DYNAMIC__ */
#ifdef __STATIC__
__private_extern__ long kld_load_from_memory(
struct mach_header **header_addr,
const char *object_name,
char *object_addr,
long *object_size);
#endif /* __STATIC__ */
__private_extern__ long kld_load_basefile_from_memory(
const char *base_filename,
char *base_addr,
long base_size);
__private_extern__ long kld_lookup(
const char *symbol_name,
unsigned long *value);
__private_extern__ long kld_forget_symbol(
const char *symbol_name);
__private_extern__ long kld_unload_all(
long deallocate_sets);
__private_extern__ void kld_address_func(
unsigned long (*func)(unsigned long size, unsigned long headers_size));
#define KLD_STRIP_ALL 0x00000000
#define KLD_STRIP_NONE 0x00000001
__private_extern__ void kld_set_link_options(
unsigned long link_options);
DESCRIPTION
The kld package is designed for loading kernel drivers both by the kernel for loading boot drivers
and kextload for loading other drivers. The library that contains the kld package is linked with the
-lkld linker flag. For the kernel when linked with the -static flag the -lkld linker flag will link
the library libkld.a. And for kextload when linked with the -dynamic flag the -lkld linker flag will
link the library libkld.dylib.
For the kernel the kld_load_basefile_from_memory, and kld_load_from_memory APIs are provided in the
library libkld.a compiled with the -static compiler flag. Using this library one must define the
following variable:
extern char *kld_basefile_name;
which is the the name of the base file used for error messages.
For kextload the kld_load_basefile, kld_load_basefile_from_memory, kld_load, and kld_load_from_memory
APIs are provided in the library libkld.dylib compiled with the -dynamic compiler flag.
kld_load or kld_load_from_memory link edits and loads the file specified by object_filename or memory
pointed to by obj_addr respectively to the base file that was previous loaded with a call to
kld_load_basefile or kld_load_basefile_from_memory.
If the program, in this case the kernel, is to allow the loaded object files to use symbols from
itself, it must be built with the -seglinkedit option of the link editor, ld(1), in order to have its
symbol table mapped into memory.
The symbol table may be trimmed to limit which symbols are allowed to be referenced by loaded
objects. This can be accomplished with the -s filename option to strip(1). For the routines
described here, only global symbols are used, so local symbols can be removed with the -x option to
ld(1) or strip(1). Doing so saves space in the final program and vastly decreases the time spent by
the first call to kld_load_from_memory or kld_load_basefile. (This is true of the first call in the
program, as well as the first call after an invocation of kld_unload_all). The first call to
kld_load_from_memory or kld_load_basefile must go through all the symbols of the program or basefile,
so if the program has been compiled for debugging (for example), it can take orders of magnitude
longer.
Since the objects loaded with kld_load or kld_load_from_memory can only use symbols that appear in
the executable program, if the program uses a library and wants to make all the symbols in that
library available to the loaded objects, it must force all of the library symbols into the exe-cutable. executable.
cutable. This can be done for all libraries with the -all_load option to ld(1) when building the
executable. This will copy all the library code into the executable.
The object file being loaded will only be successful if there are no link edit errors (undefined sym-bols, symbols,
bols, etc.). If an error occurs, the object file is unloaded automatically. If errors occur the
user supplied routine will be called:
extern void kld_error_vprintf(const char *format, va_list ap);
If the link editing and loading is successful, the address of the header of what was loaded is
returned through the pointer header_addr (if it isn't NULL). If kld_load is successful and the
parameter output_filename isn't NULL, an object file is written to that filename. This file can be
used with the gdb(1) add-file command to debug the code in the dynamically loaded object. The
kld_load function returns 1 for success and 0 for failure. If a fatal system error (out of memory,
etc.) occurs, all future calls to kld_load and the other routines described here will fail.
kld_load_from_memory() is similar to kld_load(), but works on memory rather than a file. The argu-ment argument
ment object_name is the name associated with the memory and is used for messages. (It must not be
NULL.) The arguments object_addr and object_size are the memory address and size of the object file.
kld_load_from_memory() only allows one thin object file (not an archive or ``universal'' file) to be
loaded.
kld_lookup() looks up the specified symbol name and returns its value indirectly through the pointer
value. It returns 1 if it finds the symbol, and 0 otherwise. If any errors occur it also calls the
user supplied kld_error_vprintf routine (For kld_lookup, only internal errors can result.)
kld_forget_symbol() causes this package to forget the existence of the specified symbol name. This
allows a new object to be loaded that defines this symbol. All objects loaded before this call will
continue to use the value of the symbol in effect at the time the object was loaded. It returns 1 if
it finds the symbol and 0 otherwise. If any errors occur it also calls the user supplied
kld_error_vprintf routine (For this routine, only internal errors can result.)
kld_unload_all() clears out all allocated data structures used by these routines. If the parameter
deallocate_sets is non-zero, the function also unloads all objects that were loaded. If deallo-cate_sets deallocate_sets
cate_sets is zero the object sets aren't unloaded, and the program can continue to use the code and
data loaded. However, further calls to the routines described here will no longer know about the
symbols in those objects. If objects aren't to be allowed access to each other's symbols, an
kld_unload_all call between calls to kld_load allows the objects to be loaded without fear of global
symbol names' clashing. kld_unload_all returns 1 if it is successful and 0 otherwise. If any errors
occur also calls the user supplied kld_error_vprintf routine.
The argument to kld_load_basefile specifies a base file, whose symbol table is taken as the basis for
subsequent kld_load's. kld_load_basefile_from_memory is an alternate interface that allows mapped
``thin'' object image to be specified rather than a file. The base file may be a ``universal'' file,
and must contain an architecture that would execute on the host; otherwise, it is an error. If the
file is a universal file, the ``best'' architecture (as defined by what the kernel exec(2) would
select) is used as the base file. kld_load_basefile must be invoked before any call to kld_load.
Alternatively, it can be called after kld_unload_all, which unloads the base file. This call is
intended to be used when a program is dynamically loading object sets into a program other than
itself, where base_filename contains the symbol table of the target program. The routine
kld_address_func, described next, would also be used.
kld_address_func is passed a pointer to a function, func, that will be called from kld_load. The
parameter values that kld_load will supply to func are the size of the memory required for the object
being loaded, and the size of the headers (which are also included in the calculation of size). The
function specified by func should return the address where the output is to be link edited.
kld_address_func is intended to be used when a program is dynamically loading objects into a program
other than itself; the function allows it to pick the place in the address space of the target pro-gram. program.
gram.
kld_set_link_options is passed a mask of options, link_options, that are used to control some aspects
of the following kld_load operations. Passing KLD_STRIP_NONE will stop kld from stripping symbols
from the output in all cases. By default all symbols are stripped for kernel loads and when out-put_filename output_filename
put_filename is NULL for kld_load() and kld_load_from_memory()
UNIVERSAL FILE SUPPORT
All functions that accept object files or archives also accept ``universal'' files, except for the
restrictions noted above for kld_load_from_memory and kld_load_basefile.
SEE ALSO
ld(1), strip(1), gdb(1)
BUGS
There exists one semantic link edit problem with respect to common symbols. If an object file is
loaded that has common symbols left after the symbols have been merged, kld_load has to allocate
storage for these symbols for the code to run without error. The problem occurs if, on a later call
to kld_load, one of the common symbols that kld_load allocated appears in an object file as a defin-ing defining
ing symbol (not a common or undefined symbol). In this case, kld_load will report the symbol as
being multiply defined. However, if this combination of object files were statically linked, no
error would occur.
Apple Computer, Inc. July 28, 2005 KLD(3)
|