Manual Pages  — HHOOK

The khelp(9) and hhook frameworks are tightly integrated. Khelp is responsible for registering and deregistering Khelp module hook functions with hhook 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.

The hosd argument can be used with the khelp(9) framework's 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 hhook points by creating a 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.

The hhook_head_register() function registers a hook point with the hhook framework. The hook_type argument defines the high level type for the hook point. Valid types are defined in <sys/hhook.h> and new types should be added as required. The hook_id argument specifies a unique, subsystem specific identifier for the hook point. The hhh argument will, if not NULL, be used to store a reference to the struct hhook_head created as part of the registration process. Subsystems will generally want to store a local copy of the struct hhook_head so that they can use the HHOOKS_RUN_IF() macro to instantiate hook points. The HHOOK_WAITOK flag may be passed in via the 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 flags argument so that the struct hhook_head created during the registration process will be added to a virtualised list.

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

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

The hhook_run_hooks() function should normally not be called directly and should instead be called indirectly via the 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 hhh argument references the hhook point to call all registered hook functions for. The ctx_data argument specifies a pointer to the contextual hook point data to pass into the hook functions. The hosd argument should be the pointer to the appropriate object's struct osd if the subsystem provides the ability for Khelp modules to associate per-object data. Subsystems which do not should pass NULL.

The HHOOKS_RUN_IF() macro is the preferred way to implement hook points. It only calls the 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 hhook_run_hooks() function.

The HHOOKS_RUN_IF_LOOKUP() macro performs the same function as the HHOOKS_RUN_IF() macro, but performs an additional step to look up the struct hhook_head for the specified hook_type and 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.

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

The tcp(4) implementation provides two hhook 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.

http://caia.swin.edu.au/urp/newtcp/