HHOOKS_RUN_LOOKUP_IF (9)

Leading comments

Copyright (c) 2010-2011 The FreeBSD Foundation
All rights reserved.

This documentation was written at the Centre for Advanced Internet
Architectures, Swinburne University of Technology, Melbourne, Australia by
David Hayes and Lawrence Stewart under sponsorship from the FreeBSD
Foundation.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyri...

(The comments found at the beginning of the groff file "man9/HHOOKS_RUN_LOOKUP_IF.9freebsd".)

NAME

hhook hhook_head_register hhook_head_deregister hhook_head_deregister_lookup hhook_run_hooks HHOOKS_RUN_IF HHOOKS_RUN_LOOKUP_IF - Helper Hook Framework

SYNOPSIS

In sys/hhook.h Ft typedef int Fn *hhook_func_t int32_t hhook_type int32_t hhook_id void *udata void *ctx_data void *hdata struct osd *hosd Fn int hhook_head_register int32_t hhook_type int32_t hhook_id struct hhook_head **hhh uint32_t flags Fn int hhook_head_deregister struct hhook_head *hhh Fn int hhook_head_deregister_lookup int32_t hhook_type int32_t hhook_id Fn void hhook_run_hooks struct hhook_head *hhh void *ctx_data struct osd *hosd Fn HHOOKS_RUN_IF hhh ctx_data hosd Fn HHOOKS_RUN_LOOKUP_IF hhook_type hhook_id ctx_data hosd

DESCRIPTION

provides a framework for managing and running arbitrary hook functions at defined hook points within the kernel. The KPI was inspired by pfil(9), and in many respects can be thought of as a more generic superset of pfil.

The khelp(9) and frameworks are tightly integrated. Khelp is responsible for registering and deregistering Khelp module hook functions with points. The KPI functions used by khelp(9) to do this are not documented here as they are not relevant to consumers wishing to instantiate hook points.

Information for Khelp Module Implementors

Khelp modules indirectly interact with by defining appropriate hook functions for insertion into hook points. Hook functions must conform to the Ft hhook_func_t function pointer declaration outlined in the Sx SYNOPSIS .

The Fa hhook_type and Fa hhook_id arguments identify the hook point which has called into the hook function. These are useful when a single hook function is registered for multiple hook points and wants to know which hook point has called into it. In sys/hhook.h lists available Fa hhook_type defines and subsystems which export hook points are responsible for defining the Fa hhook_id value in appropriate header files.

The Fa udata argument will be passed to the hook function if it was specified in the Vt struct hookinfo at hook registration time.

The Fa ctx_data argument contains context specific data from the hook point call site. The data type passed is subsystem dependent.

The Fa hdata argument is a pointer to the persistent per-object storage allocated for use by the module if required. The pointer will only ever be NULL if the module did not request per-object storage.

The Fa hosd argument can be used with the khelp(9) framework's Fn khelp_get_osd function to access data belonging to a different Khelp module.

Khelp modules instruct the Khelp framework to register their hook functions with points by creating a Vt struct hookinfo per hook point, which contains the following members:

struct hookinfo {
        hhook_func_t    hook_func;
        struct helper   *hook_helper;
        void            *hook_udata;
        int32_t         hook_id;
        int32_t         hook_type;
};

Khelp modules are responsible for setting all members of the struct except hook_helper which is handled by the Khelp framework.

Creating and Managing Hook Points

Kernel subsystems that wish to provide points typically need to make four and possibly five key changes to their implementation:

• Define a list of hhook_id mappings in an appropriate subsystem header.
• Register each hook point with the Fn hhook_head_register function during initialisation of the subsystem.
• Select or create a standardised data type to pass to hook functions as contextual data.
• Add a call to Fn HHOOKS_RUN_IF or Fn HHOOKS_RUN_IF_LOOKUP at the point in the subsystem's code where the hook point should be executed.
• If the subsystem can be dynamically added/removed at runtime, each hook point registered with the Fn hhook_head_register function when the subsystem was initialised needs to be deregistered with the Fn hhook_head_deregister or Fn hhook_head_deregister_lookup functions when the subsystem is being deinitialised prior to removal.

The Fn hhook_head_register function registers a hook point with the framework. The Fa hook_type argument defines the high level type for the hook point. Valid types are defined in In sys/hhook.h and new types should be added as required. The Fa hook_id argument specifies a unique, subsystem specific identifier for the hook point. The Fa hhh argument will, if not NULL, be used to store a reference to the Vt struct hhook_head created as part of the registration process. Subsystems will generally want to store a local copy of the Vt struct hhook_head so that they can use the Fn HHOOKS_RUN_IF macro to instantiate hook points. The HHOOK_WAITOK flag may be passed in via the Fa flags argument if malloc(9) is allowed to sleep waiting for memory to become available. If the hook point is within a virtualised subsystem (e.g. the network stack), the HHOOK_HEADISINVNET flag should be passed in via the Fa flags argument so that the Vt struct hhook_head created during the registration process will be added to a virtualised list.

The Fn hhook_head_deregister function deregisters a previously registered hook point from the framework. The Fa hhh argument is the pointer to the Vt struct hhook_head returned by Fn hhoook_head_register when the hook point was registered.

The Fn hhook_head_deregister_lookup function can be used instead of Fn hhook_head_deregister in situations where the caller does not have a cached copy of the Vt struct hhook_head and wants to deregister a hook point using the appropriate Fa hook_type and Fa hook_id identifiers instead.

The Fn hhook_run_hooks function should normally not be called directly and should instead be called indirectly via the Fn HHOOKS_RUN_IF macro. However, there may be circumstances where it is preferable to call the function directly, and so it is documented here for completeness. The Fa hhh argument references the point to call all registered hook functions for. The Fa ctx_data argument specifies a pointer to the contextual hook point data to pass into the hook functions. The Fa hosd argument should be the pointer to the appropriate object's Vt struct osd if the subsystem provides the ability for Khelp modules to associate per-object data. Subsystems which do not should pass NULL.

The Fn HHOOKS_RUN_IF macro is the preferred way to implement hook points. It only calls the Fn hhook_run_hooks function if at least one hook function is registered for the hook point. By checking for registered hook functions, the macro minimises the cost associated with adding hook points to frequently used code paths by reducing to a simple if test in the common case where no hook functions are registered. The arguments are as described for the Fn hhook_run_hooks function.

The Fn HHOOKS_RUN_IF_LOOKUP macro performs the same function as the Fn HHOOKS_RUN_IF macro, but performs an additional step to look up the Vt struct hhook_head for the specified Fa hook_type and Fa hook_id identifiers. It should not be used except in code paths which are infrequently executed because of the reference counting overhead associated with the look up.

IMPLEMENTATION NOTES

Each Vt struct hhook_head protects its internal list of hook functions with a rmlock(9). Therefore, anytime Fn hhook_run_hooks is called directly or indirectly via the Fn HHOOKS_RUN_IF or Fn HHOOKS_RUN_IF_LOOKUP macros, a non-sleepable read lock will be acquired and held across the calls to all registered hook functions.

RETURN VALUES

Fn hhook_head_register returns 0 if no errors occurred. It returns EEXIST if a hook point with the same Fa hook_type and Fa hook_id is already registered. It returns EINVAL if the HHOOK_HEADISINVNET flag is not set in Fa flags because the implementation does not yet support hook points in non-virtualised subsystems (see the Sx BUGS section for details). It returns ENOMEM if malloc(9) failed to allocate memory for the new Vt struct hhook_head .

Fn hhook_head_deregister and Fn hhook_head_deregister_lookup return 0 if no errors occurred. They return ENOENT if Fa hhh is NULL. They return EBUSY if the reference count of Fa hhh is greater than one.

EXAMPLES

A well commented example Khelp module can be found at: /usr/share/examples/kld/khelp/h_example.c

The tcp(4) implementation provides two points which are called for packets sent/received when a connection is in the established phase. Search for HHOOK in the following files: sys/netinet/tcp_var.h sys/netinet/tcp_input.c sys/netinet/tcp_output.c and sys/netinet/tcp_subr.c

SEE ALSO

khelp(9)

ACKNOWLEDGEMENTS

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.

HISTORY

The framework first appeared in Fx 9.0 .

The 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:

caia.swin.edu.au/urp/newtcp

AUTHORS

An -nosplit The framework was written by An Lawrence Stewart Aq Mt lstewart@FreeBSD.org .

This manual page was written by An David Hayes Aq Mt david.hayes@ieee.org and An Lawrence Stewart Aq Mt lstewart@FreeBSD.org .