1 /*- 2 * SPDX-License-Identifier: BSD-2-Clause 3 * 4 * Copyright (c) 2010-2011 The FreeBSD Foundation 5 * All rights reserved. 6 * 7 * This software was developed at the Centre for Advanced Internet 8 * Architectures, Swinburne University of Technology, Melbourne, Australia by 9 * Lawrence Stewart under sponsorship from the FreeBSD Foundation. 10 * 11 * Redistribution and use in source and binary forms, with or without 12 * modification, are permitted provided that the following conditions 13 * are met: 14 * 1. Redistributions of source code must retain the above copyright 15 * notice, this list of conditions and the following disclaimer. 16 * 2. Redistributions in binary form must reproduce the above copyright 17 * notice, this list of conditions and the following disclaimer in the 18 * documentation and/or other materials provided with the distribution. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 21 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 24 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30 * SUCH DAMAGE. 31 */ 32 33 /* 34 * This example Khelp module uses the helper hook points available in the TCP 35 * stack to calculate a per-connection count of inbound and outbound packets 36 * when the connection is in the established state. The code is verbosely 37 * documented in an attempt to explain how everything fits together. 38 */ 39 40 #include <sys/param.h> 41 #include <sys/kernel.h> 42 #include <sys/hhook.h> 43 #include <sys/khelp.h> 44 #include <sys/module.h> 45 #include <sys/module_khelp.h> 46 #include <sys/socket.h> 47 #include <sys/socketvar.h> 48 49 #include <netinet/tcp_var.h> 50 51 #include <vm/uma.h> 52 53 /* 54 * Function prototype for our helper hook (man 9 hhook) compatible hook 55 * function. 56 */ 57 static int example_hook(int hhook_type, int hhook_id, void *udata, 58 void *ctx_data, void *hdata, struct osd *hosd); 59 60 /* 61 * Our per-connection persistent data storage struct. 62 */ 63 struct example { 64 uint32_t est_in_count; 65 uint32_t est_out_count; 66 }; 67 68 /* 69 * Fill in the required bits of our module's struct helper (defined in 70 * <sys/module_khelp.h>). 71 * 72 * - Our helper will be storing persistent state for each TCP connection, so we 73 * request the use the Object Specific Data (OSD) feature from the framework by 74 * setting the HELPER_NEEDS_OSD flag. 75 * 76 * - Our helper is related to the TCP subsystem, so tell the Khelp framework 77 * this by setting an appropriate class for the module. When a new TCP 78 * connection is created, the Khelp framework takes care of associating helper 79 * modules of the appropriate class with the new connection. 80 */ 81 struct helper example_helper = { 82 .h_flags = HELPER_NEEDS_OSD, 83 .h_classes = HELPER_CLASS_TCP 84 }; 85 86 /* 87 * Set which helper hook points our module wants to hook by creating an array of 88 * hookinfo structs (defined in <sys/hhook.h>). We hook the TCP established 89 * inbound/outbound hook points (TCP hhook points are defined in 90 * <netinet/tcp_var.h>) with our example_hook() function. We don't require a user 91 * data pointer to be passed to our hook function when called, so we set it to 92 * NULL. 93 */ 94 struct hookinfo example_hooks[] = { 95 { 96 .hook_type = HHOOK_TYPE_TCP, 97 .hook_id = HHOOK_TCP_EST_IN, 98 .hook_udata = NULL, 99 .hook_func = &example_hook 100 }, 101 { 102 .hook_type = HHOOK_TYPE_TCP, 103 .hook_id = HHOOK_TCP_EST_OUT, 104 .hook_udata = NULL, 105 .hook_func = &example_hook 106 } 107 }; 108 109 /* 110 * Very simple helper hook function. Here's a quick run through the arguments: 111 * 112 * - hhook_type and hhook_id are useful if you use a single function with many 113 * hook points and want to know which hook point called the function. 114 * 115 * - udata will be NULL, because we didn't elect to pass a pointer in either of 116 * the hookinfo structs we instantiated above in the example_hooks array. 117 * 118 * - ctx_data contains context specific data from the hook point call site. The 119 * data type passed is subsystem dependent. In the case of TCP, the hook points 120 * pass a pointer to a "struct tcp_hhook_data" (defined in <netinet/tcp_var.h>). 121 * 122 * - hdata is a pointer to the persistent per-object storage for our module. The 123 * pointer is allocated automagically by the Khelp framework when the connection 124 * is created, and comes from a dedicated UMA zone. It will never be NULL. 125 * 126 * - hosd can be used with the Khelp framework's khelp_get_osd() function to 127 * access data belonging to a different Khelp module. 128 */ 129 static int 130 example_hook(int hhook_type, int hhook_id, void *udata, void *ctx_data, 131 void *hdata, struct osd *hosd) 132 { 133 struct example *data; 134 135 data = hdata; 136 137 if (hhook_id == HHOOK_TCP_EST_IN) 138 data->est_in_count++; 139 else if (hhook_id == HHOOK_TCP_EST_OUT) 140 data->est_out_count++; 141 142 return (0); 143 } 144 145 /* 146 * We use a convenient macro which handles registering our module with the Khelp 147 * framework. Note that Khelp modules which set the HELPER_NEEDS_OSD flag (i.e. 148 * require persistent per-object storage) must use the KHELP_DECLARE_MOD_UMA() 149 * macro. If you don't require per-object storage, use the KHELP_DECLARE_MOD() 150 * macro instead. 151 */ 152 KHELP_DECLARE_MOD_UMA(example, &example_helper, example_hooks, 1, 153 sizeof(struct example), NULL, NULL); 154