sys/sys/hhook.h

   1 /*-
   2  * SPDX-License-Identifier: BSD-2-Clause-FreeBSD
   3  *
   4  * Copyright (c) 2010,2013 Lawrence Stewart <lstewart@freebsd.org>
   5  * Copyright (c) 2010 The FreeBSD Foundation
   6  * All rights reserved.
   7  *
   8  * This software was developed by Lawrence Stewart while studying at the Centre
   9  * for Advanced Internet Architectures, Swinburne University of Technology, made
  10  * possible in part by grants from the FreeBSD Foundation and Cisco University
  11  * Research Program Fund at Community Foundation Silicon Valley.
  12  *
  13  * Portions of this software were developed at the Centre for Advanced
  14  * Internet Architectures, Swinburne University of Technology, Melbourne,
  15  * Australia by Lawrence Stewart under sponsorship from the FreeBSD Foundation.
  16  *
  17  * Redistribution and use in source and binary forms, with or without
  18  * modification, are permitted provided that the following conditions
  19  * are met:
  20  * 1. Redistributions of source code must retain the above copyright
  21  *    notice, this list of conditions and the following disclaimer.
  22  * 2. Redistributions in binary form must reproduce the above copyright
  23  *    notice, this list of conditions and the following disclaimer in the
  24  *    documentation and/or other materials provided with the distribution.
  25  *
  26  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  27  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  28  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  29  * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  30  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  31  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  32  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  33  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  34  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  35  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  36  * SUCH DAMAGE.
  37  *
  38  * $FreeBSD$
  39  */
  40
  41 /*
  42  * A KPI modelled on the pfil framework for instantiating helper hook points
  43  * within the kernel for use by Khelp modules. Originally released as part of
  44  * the NewTCP research project at Swinburne University of Technology's Centre
  45  * for Advanced Internet Architectures, Melbourne, Australia, which was made
  46  * possible in part by a grant from the Cisco University Research Program Fund
  47  * at Community Foundation Silicon Valley. More details are available at:
  48  *   http://caia.swin.edu.au/urp/newtcp/
  49  */
  50
  51 #ifndef _SYS_HHOOK_H_
  52 #define _SYS_HHOOK_H_
  53
  54 /* XXXLAS: Is there a way around this? */
  55 #include <sys/lock.h>
  56 #include <sys/rmlock.h>
  57
  58 /* hhook_head flags. */
  59 #define HHH_ISINVNET            0x00000001 /* Is the hook point in a vnet? */
  60
  61 /* Flags common to  all register functions. */
  62 #define HHOOK_WAITOK            0x00000001 /* Sleeping allowed. */
  63 #define HHOOK_NOWAIT            0x00000002 /* Sleeping disallowed. */
  64 /* Flags only relevant to hhook_head_register() and hhook_head_is_virtual(). */
  65 #define HHOOK_HEADISINVNET      0x00000100 /* Public proxy for HHH_ISINVNET. */
  66
  67 /* Helper hook types. */
  68 #define HHOOK_TYPE_TCP          1
  69 #define HHOOK_TYPE_SOCKET       2
  70 #define HHOOK_TYPE_IPSEC_IN     3
  71 #define HHOOK_TYPE_IPSEC_OUT    4
  72
  73 struct helper;
  74 struct osd;
  75
  76 /* Signature for helper hook functions. */
  77 typedef int (*hhook_func_t)(int32_t hhook_type, int32_t hhook_id, void *udata,
  78     void *ctx_data, void *hdata, struct osd *hosd);
  79
  80 /*
  81  * Information required to add/remove a helper hook function to/from a helper
  82  * hook point.
  83  */
  84 struct hookinfo {
  85         hhook_func_t    hook_func;
  86         struct helper   *hook_helper;
  87         void            *hook_udata;
  88         int32_t         hook_id;
  89         int32_t         hook_type;
  90 };
  91
  92 /*
  93  * Ideally this would be private but we need access to the hhh_nhooks member
  94  * variable in order to make the HHOOKS_RUN_IF() macro low impact.
  95  */
  96 struct hhook_head {
  97         STAILQ_HEAD(hhook_list, hhook)  hhh_hooks;
  98         struct rmlock                   hhh_lock;
  99         uintptr_t                       hhh_vid;
 100         int32_t                         hhh_id;
 101         int32_t                         hhh_nhooks;
 102         int32_t                         hhh_type;
 103         uint32_t                        hhh_flags;
 104         volatile uint32_t               hhh_refcount;
 105         LIST_ENTRY(hhook_head)          hhh_next;
 106         LIST_ENTRY(hhook_head)          hhh_vnext;
 107 };
 108
 109 /* Public KPI functions. */
 110 void    hhook_run_hooks(struct hhook_head *hhh, void *ctx_data, struct osd *hosd);
 111
 112 int     hhook_add_hook(struct hhook_head *hhh, struct hookinfo *hki,
 113     uint32_t flags);
 114
 115 int     hhook_add_hook_lookup(struct hookinfo *hki, uint32_t flags);
 116
 117 int     hhook_remove_hook(struct hhook_head *hhh, struct hookinfo *hki);
 118
 119 int     hhook_remove_hook_lookup(struct hookinfo *hki);
 120
 121 int     hhook_head_register(int32_t hhook_type, int32_t hhook_id,
 122     struct hhook_head **hhh, uint32_t flags);
 123
 124 int     hhook_head_deregister(struct hhook_head *hhh);
 125
 126 int     hhook_head_deregister_lookup(int32_t hhook_type, int32_t hhook_id);
 127
 128 struct hhook_head * hhook_head_get(int32_t hhook_type, int32_t hhook_id);
 129
 130 void    hhook_head_release(struct hhook_head *hhh);
 131
 132 uint32_t hhook_head_is_virtualised(struct hhook_head *hhh);
 133
 134 uint32_t hhook_head_is_virtualised_lookup(int32_t hook_type, int32_t hook_id);
 135
 136 /*
 137  * A wrapper around hhook_run_hooks() that only calls the function if at least
 138  * one helper hook function is registered for the specified helper hook point.
 139  */
 140 #define HHOOKS_RUN_IF(hhh, ctx_data, hosd) do {                         \
 141         if (hhh != NULL && hhh->hhh_nhooks > 0)                         \
 142                 hhook_run_hooks(hhh, ctx_data, hosd);                   \
 143 } while (0)
 144
 145 /*
 146  * WARNING: This macro should only be used in code paths that execute
 147  * infrequently, otherwise the refcounting overhead would be excessive.
 148  *
 149  * A similar wrapper to HHOOKS_RUN_IF() for situations where the caller prefers
 150  * not to lookup and store the appropriate hhook_head pointer themselves.
 151  */
 152 #define HHOOKS_RUN_LOOKUP_IF(hhook_type, hhook_id, ctx_data, hosd) do { \
 153         struct hhook_head *_hhh;                                        \
 154                                                                         \
 155         _hhh = hhook_head_get(hhook_type, hhook_id);                    \
 156         if (_hhh != NULL) {                                             \
 157                 if (_hhh->hhh_nhooks > 0)                               \
 158                         hhook_run_hooks(_hhh, ctx_data, hosd);          \
 159                 hhook_head_release(_hhh);                               \
 160         }                                                               \
 161 } while (0)
 162
 163 #endif /* _SYS_HHOOK_H_ */