diff options
Diffstat (limited to 'static/freebsd/man9/khelp.9 3.html')
| -rw-r--r-- | static/freebsd/man9/khelp.9 3.html | 309 |
1 files changed, 0 insertions, 309 deletions
diff --git a/static/freebsd/man9/khelp.9 3.html b/static/freebsd/man9/khelp.9 3.html deleted file mode 100644 index 1dd082c7..00000000 --- a/static/freebsd/man9/khelp.9 3.html +++ /dev/null @@ -1,309 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">KHELP(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">KHELP(9)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">khelp</code>, - <code class="Nm">khelp_init_osd</code>, - <code class="Nm">khelp_destroy_osd</code>, - <code class="Nm">khelp_get_id</code>, <code class="Nm">khelp_get_osd</code>, - <code class="Nm">khelp_add_hhook</code>, - <code class="Nm">khelp_remove_hhook</code>, - <code class="Nm">KHELP_DECLARE_MOD</code>, - <code class="Nm">KHELP_DECLARE_MOD_UMA</code> — - <span class="Nd">Kernel Helper Framework</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="In">#include - <<a class="In">sys/khelp.h</a>></code> - <br/> - <code class="In">#include - <<a class="In">sys/module_khelp.h</a>></code></p> -<p class="Pp"><var class="Ft">int</var> - <code class="Fn">khelp_init_osd</code>(<var class="Fa" style="white-space: nowrap;">uint32_t - classes</var>, <var class="Fa" style="white-space: nowrap;">struct osd - *hosd</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <code class="Fn">khelp_destroy_osd</code>(<var class="Fa" style="white-space: nowrap;">struct - osd *hosd</var>);</p> -<p class="Pp"><var class="Ft">int32_t</var> - <code class="Fn">khelp_get_id</code>(<var class="Fa" style="white-space: nowrap;">char - *hname</var>);</p> -<p class="Pp"><var class="Ft">void *</var> - <code class="Fn">khelp_get_osd</code>(<var class="Fa" style="white-space: nowrap;">struct - osd *hosd</var>, <var class="Fa" style="white-space: nowrap;">int32_t - id</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <code class="Fn">khelp_add_hhook</code>(<var class="Fa" style="white-space: nowrap;">const - struct hookinfo *hki</var>, - <var class="Fa" style="white-space: nowrap;">uint32_t flags</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <code class="Fn">khelp_remove_hhook</code>(<var class="Fa" style="white-space: nowrap;">const - struct hookinfo *hki</var>);</p> -<p class="Pp"><code class="Fn">KHELP_DECLARE_MOD</code>(<var class="Fa" style="white-space: nowrap;">hname</var>, - <var class="Fa" style="white-space: nowrap;">hdata</var>, - <var class="Fa" style="white-space: nowrap;">hhooks</var>, - <var class="Fa" style="white-space: nowrap;">version</var>);</p> -<p class="Pp"><code class="Fn">KHELP_DECLARE_MOD_UMA</code>(<var class="Fa" style="white-space: nowrap;">hname</var>, - <var class="Fa" style="white-space: nowrap;">hdata</var>, - <var class="Fa" style="white-space: nowrap;">hhooks</var>, - <var class="Fa" style="white-space: nowrap;">version</var>, - <var class="Fa" style="white-space: nowrap;">ctor</var>, - <var class="Fa" style="white-space: nowrap;">dtor</var>);</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp"><code class="Nm">khelp</code> provides a framework for managing - <code class="Nm">khelp</code> modules, which indirectly use the - <a class="Xr">hhook(9)</a> KPI to register their hook functions with hook - points of interest within the kernel. Khelp modules aim to provide a - structured way to dynamically extend the kernel at runtime in an ABI - preserving manner. Depending on the subsystem providing hook points, a - <code class="Nm">khelp</code> module may be able to associate per-object - data for maintaining relevant state between hook calls. The - <a class="Xr">hhook(9)</a> and <code class="Nm">khelp</code> frameworks are - tightly integrated and anyone interested in <code class="Nm">khelp</code> - should also read the <a class="Xr">hhook(9)</a> manual page thoroughly.</p> -<section class="Ss"> -<h2 class="Ss" id="Information_for_Khelp_Module_Implementors"><a class="permalink" href="#Information_for_Khelp_Module_Implementors">Information - for Khelp Module Implementors</a></h2> -<p class="Pp"><code class="Nm">khelp</code> modules are represented within the - <code class="Nm">khelp</code> framework by a <var class="Vt">struct - helper</var> which has the following members:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>struct helper { - int (*mod_init) (void); - int (*mod_destroy) (void); -#define HELPER_NAME_MAXLEN 16 - char h_name[HELPER_NAME_MAXLEN]; - uma_zone_t h_zone; - struct hookinfo *h_hooks; - uint32_t h_nhooks; - uint32_t h_classes; - int32_t h_id; - volatile uint32_t h_refcount; - uint16_t h_flags; - TAILQ_ENTRY(helper) h_next; -};</pre> -</div> -<p class="Pp">Modules must instantiate a <var class="Vt">struct helper</var>, - but are only required to set the <var class="Va">h_classes</var> field, and - may optionally set the <var class="Va">h_flags</var>, - <var class="Va">mod_init</var> and <var class="Va">mod_destroy</var> fields - where required. The framework takes care of all other fields and modules - should refrain from manipulating them. Using the C99 designated initialiser - feature to set fields is encouraged.</p> -<p class="Pp">If specified, the <var class="Va">mod_init</var> function will be - run by the <code class="Nm">khelp</code> framework prior to completing the - registration process. Returning a non-zero value from the - <var class="Va">mod_init</var> function will abort the registration process - and fail to load the module. If specified, the - <var class="Va">mod_destroy</var> function will be run by the - <code class="Nm">khelp</code> framework during the deregistration process, - after the module has been deregistered by the <code class="Nm">khelp</code> - framework. The return value is currently ignored. Valid - <code class="Nm">khelp</code> classes are defined in - <code class="In"><<a class="In">sys/khelp.h</a>></code>. Valid flags - are defined in - <code class="In"><<a class="In">sys/module_khelp.h</a>></code>. The - HELPER_NEEDS_OSD flag should be set in the <var class="Va">h_flags</var> - field if the <code class="Nm">khelp</code> module requires persistent - per-object data storage. There is no programmatic way (yet) to check if a - <code class="Nm">khelp</code> class provides the ability for - <code class="Nm">khelp</code> modules to associate persistent per-object - data, so a manual check is required.</p> -<p class="Pp" id="KHELP_DECLARE_MOD">The - <a class="permalink" href="#KHELP_DECLARE_MOD"><code class="Fn">KHELP_DECLARE_MOD</code></a>() - and <code class="Fn">KHELP_DECLARE_MOD_UMA</code>() macros provide - convenient wrappers around the <a class="Xr">DECLARE_MODULE(9)</a> macro, - and are used to register a <code class="Nm">khelp</code> module with the - <code class="Nm">khelp</code> framework. - <code class="Fn">KHELP_DECLARE_MOD_UMA</code>() should only be used by - modules which require the use of persistent per-object storage i.e. modules - which set the HELPER_NEEDS_OSD flag in their <var class="Vt">struct - helper</var>'s <var class="Va">h_flags</var> field.</p> -<p class="Pp" id="KHELP_DECLARE_MOD_UMA">The first four arguments common to both - macros are as follows. The <var class="Fa">hname</var> argument specifies - the unique <a class="Xr">ascii(7)</a> name for the - <code class="Nm">khelp</code> module. It should be no longer than - HELPER_NAME_MAXLEN-1 characters in length. The <var class="Fa">hdata</var> - argument is a pointer to the module's <var class="Vt">struct helper</var>. - The <var class="Fa">hhooks</var> argument points to a static array of - <var class="Vt">struct hookinfo</var> structures. The array should contain a - <var class="Vt">struct hookinfo</var> for each <a class="Xr">hhook(9)</a> - point the module wishes to hook, even when using the same hook function - multiple times for different <a class="Xr">hhook(9)</a> points. The - <var class="Fa">version</var> argument specifies a version number for the - module which will be passed to <a class="Xr">MODULE_VERSION(9)</a>. The - <a class="permalink" href="#KHELP_DECLARE_MOD_UMA"><code class="Fn">KHELP_DECLARE_MOD_UMA</code></a>() - macro takes the additional <var class="Fa">ctor</var> and - <var class="Fa">dtor</var> arguments, which specify optional - <a class="Xr">uma(9)</a> constructor and destructor functions. NULL should - be passed where the functionality is not required.</p> -<p class="Pp" id="khelp_get_id">The - <a class="permalink" href="#khelp_get_id"><code class="Fn">khelp_get_id</code></a>() - function returns the numeric identifier for the - <code class="Nm">khelp</code> module with name - <var class="Fa">hname</var>.</p> -<p class="Pp" id="khelp_get_osd">The - <a class="permalink" href="#khelp_get_osd"><code class="Fn">khelp_get_osd</code></a>() - function is used to obtain the per-object data pointer for a specified - <code class="Nm">khelp</code> module. The <var class="Fa">hosd</var> - argument is a pointer to the underlying subsystem object's - <var class="Vt">struct osd</var>. This is provided by the - <a class="Xr">hhook(9)</a> framework when calling into a - <code class="Nm">khelp</code> module's hook function. The - <var class="Fa">id</var> argument specifies the numeric identifier for the - <code class="Nm">khelp</code> module to extract the data pointer from - <var class="Fa">hosd</var> for. The <var class="Fa">id</var> is obtained - using the <code class="Fn">khelp_get_id</code>() function.</p> -<p class="Pp" id="khelp_add_hhook">The - <a class="permalink" href="#khelp_add_hhook"><code class="Fn">khelp_add_hhook</code></a>() - and - <a class="permalink" href="#khelp_remove_hhook"><code class="Fn" id="khelp_remove_hhook">khelp_remove_hhook</code></a>() - functions allow a <code class="Nm">khelp</code> module to dynamically - hook/unhook <a class="Xr">hhook(9)</a> points at run time. The - <var class="Fa">hki</var> argument specifies a pointer to a - <var class="Vt">struct hookinfo</var> which encapsulates the required - information about the <a class="Xr">hhook(9)</a> point and hook function - being manipulated. The HHOOK_WAITOK flag may be passed in via the - <var class="Fa">flags</var> argument of - <code class="Fn">khelp_add_hhook</code>() if <a class="Xr">malloc(9)</a> is - allowed to sleep waiting for memory to become available.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Integrating_Khelp_Into_a_Kernel_Subsystem"><a class="permalink" href="#Integrating_Khelp_Into_a_Kernel_Subsystem">Integrating - Khelp Into a Kernel Subsystem</a></h2> -<p class="Pp">Most of the work required to allow <code class="Nm">khelp</code> - modules to do useful things relates to defining and instantiating suitable - <a class="Xr">hhook(9)</a> points for <code class="Nm">khelp</code> modules - to hook into. The only additional decision a subsystem needs to make is - whether it wants to allow <code class="Nm">khelp</code> modules to associate - persistent per-object data. Providing support for persistent data storage - can allow <code class="Nm">khelp</code> modules to perform more complex - functionality which may be desirable. Subsystems which want to allow Khelp - modules to associate persistent per-object data with one of the subsystem's - data structures need to make the following two key changes:</p> -<ul class="Bl-bullet"> - <li>Embed a <var class="Vt">struct osd</var> pointer in the structure - definition for the object.</li> - <li>Add calls to <code class="Fn">khelp_init_osd</code>() and - <code class="Fn">khelp_destroy_osd</code>() to the subsystem code paths - which are responsible for respectively initialising and destroying the - object.</li> -</ul> -<p class="Pp" id="khelp_init_osd">The - <a class="permalink" href="#khelp_init_osd"><code class="Fn">khelp_init_osd</code></a>() - function initialises the per-object data storage for all currently loaded - <code class="Nm">khelp</code> modules of appropriate classes which have set - the HELPER_NEEDS_OSD flag in their <var class="Va">h_flags</var> field. The - <var class="Fa">classes</var> argument specifies a bitmask of - <code class="Nm">khelp</code> classes which this subsystem associates with. - If a <code class="Nm">khelp</code> module matches any of the classes in the - bitmask, that module will be associated with the object. The - <var class="Fa">hosd</var> argument specifies the pointer to the object's - <var class="Vt">struct osd</var> which will be used to provide the - persistent storage for use by <code class="Nm">khelp</code> modules.</p> -<p class="Pp" id="khelp_destroy_osd">The - <a class="permalink" href="#khelp_destroy_osd"><code class="Fn">khelp_destroy_osd</code></a>() - function frees all memory that was associated with an object's - <var class="Vt">struct osd</var> by a previous call to - <code class="Fn">khelp_init_osd</code>(). The <var class="Fa">hosd</var> - argument specifies the pointer to the object's <var class="Vt">struct - osd</var> which will be purged in preparation for destruction.</p> -</section> -</section> -<section class="Sh"> -<h1 class="Sh" id="IMPLEMENTATION_NOTES"><a class="permalink" href="#IMPLEMENTATION_NOTES">IMPLEMENTATION - NOTES</a></h1> -<p class="Pp"><code class="Nm">khelp</code> modules are protected from being - prematurely unloaded by a reference count. The count is incremented each - time a subsystem calls <code class="Fn">khelp_init_osd</code>() causing - persistent storage to be allocated for the module, and decremented for each - corresponding call to <code class="Fn">khelp_destroy_osd</code>(). Only when - a module's reference count has dropped to zero can the module be - unloaded.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN - VALUES</a></h1> -<p class="Pp">The <code class="Fn">khelp_init_osd</code>() function returns zero - if no errors occurred. It returns ENOMEM if a <code class="Nm">khelp</code> - module which requires per-object storage fails to allocate the necessary - memory.</p> -<p class="Pp">The <code class="Fn">khelp_destroy_osd</code>() function only - returns zero to indicate that no errors occurred.</p> -<p class="Pp">The <code class="Fn">khelp_get_id</code>() function returns the - unique numeric identifier for the registered <code class="Nm">khelp</code> - module with name <var class="Fa">hname</var>. It return -1 if no module with - the specified name is currently registered.</p> -<p class="Pp">The <code class="Fn">khelp_get_osd</code>() function returns the - pointer to the <code class="Nm">khelp</code> module's persistent object - storage memory. If the module identified by <var class="Fa">id</var> does - not have persistent object storage registered with the object's - <var class="Fa">hosd</var> <var class="Vt">struct osd</var>, NULL is - returned.</p> -<p class="Pp">The <code class="Fn">khelp_add_hhook</code>() function returns - zero if no errors occurred. It returns ENOENT if it could not find the - requested <a class="Xr">hhook(9)</a> point. It returns ENOMEM if - <a class="Xr">malloc(9)</a> failed to allocate memory. It returns EEXIST if - attempting to register the same hook function more than once for the same - <a class="Xr">hhook(9)</a> point.</p> -<p class="Pp">The <code class="Fn">khelp_remove_hhook</code>() function returns - zero if no errors occurred. It returns ENOENT if it could not find the - requested <a class="Xr">hhook(9)</a> point.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> -<p class="Pp">A well commented example Khelp module can be found at: - <span class="Pa">/usr/share/examples/kld/khelp/h_example.c</span></p> -<p class="Pp">The Enhanced Round Trip Time (ERTT) <a class="Xr">h_ertt(4)</a> - <code class="Nm">khelp</code> module provides a more complex example of what - is possible.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">h_ertt(4)</a>, <a class="Xr">hhook(9)</a>, - <a class="Xr">osd(9)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="ACKNOWLEDGEMENTS"><a class="permalink" href="#ACKNOWLEDGEMENTS">ACKNOWLEDGEMENTS</a></h1> -<p class="Pp">Development and testing of this software were made possible in - part by grants from the FreeBSD Foundation and Cisco University Research - Program Fund at Community Foundation Silicon Valley.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">The <code class="Nm">khelp</code> kernel helper framework first - appeared in <span class="Ux">FreeBSD 9.0</span>.</p> -<p class="Pp">The <code class="Nm">khelp</code> framework was first released in - 2010 by Lawrence Stewart whilst studying at Swinburne University of - Technology's Centre for Advanced Internet Architectures, Melbourne, - Australia. More details are available at:</p> -<p class="Pp">http://caia.swin.edu.au/urp/newtcp/</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp">The <code class="Nm">khelp</code> framework was written by - <span class="An">Lawrence Stewart</span> - <<a class="Mt" href="mailto:lstewart@FreeBSD.org">lstewart@FreeBSD.org</a>>.</p> -<p class="Pp">This manual page was written by <span class="An">David - Hayes</span> - <<a class="Mt" href="mailto:david.hayes@ieee.org">david.hayes@ieee.org</a>> - and <span class="An">Lawrence Stewart</span> - <<a class="Mt" href="mailto:lstewart@FreeBSD.org">lstewart@FreeBSD.org</a>>.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">October 1, 2024</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |