share/man/man9/DECLARE_MODULE.9

   1 .\" -*- nroff -*-
   2 .\"
   3 .\" Copyright (c) 2000 Alexander Langer
   4 .\"
   5 .\" All rights reserved.
   6 .\"
   7 .\" This program is free software.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  19 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  20 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  21 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  22 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  23 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  24 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  25 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  26 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  27 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd February 13, 2018
  32 .Dt DECLARE_MODULE 9
  33 .Os
  34 .Sh NAME
  35 .Nm DECLARE_MODULE
  36 .Nd kernel module declaration macro
  37 .Sh SYNOPSIS
  38 .In sys/param.h
  39 .In sys/kernel.h
  40 .In sys/module.h
  41 .Fn DECLARE_MODULE "name" "moduledata_t data" "sub" "order"
  42 .Fn DECLARE_MODULE_TIED "name" "moduledata_t data" "sub" "order"
  43 .Sh DESCRIPTION
  44 The
  45 .Fn DECLARE_MODULE
  46 macro declares a generic kernel module.
  47 It is used to register the module with the system, using the
  48 .Fn SYSINIT
  49 macro.
  50 .Fn DECLARE_MODULE
  51 is usually used within other macros, such as
  52 .Xr DRIVER_MODULE 9 ,
  53 .Xr DEV_MODULE 9
  54 and
  55 .Xr SYSCALL_MODULE 9 .
  56 Of course, it can also be called directly, for example in
  57 order to implement dynamic sysctls.
  58 .Pp
  59 A module declared with
  60 .Fn DECLARE_MODULE_TIED
  61 will load only if the running kernel version
  62 (as specified by
  63 .Dv __FreeBSD_version )
  64 is identical to that on which it was built.
  65 This declaration should be used by modules which depend on interfaces beyond
  66 the stable kernel KBI (such as ABI emulators or hypervisors that rely on
  67 internal kernel structures).
  68 .Fn DECLARE_MODULE
  69 will behave like
  70 .Fn DECLARE_MODULE_TIED
  71 when compiled with modules built with the kernel.
  72 This allows locks and other synchronization primitives
  73 to be inlined safely.
  74 .Pp
  75 The arguments are:
  76 .Bl -tag -width indent
  77 .It Fa name
  78 The module name, which will be used in the
  79 .Fn SYSINIT
  80 call to identify the module.
  81 .It Fa data
  82 A
  83 .Vt moduledata_t
  84 structure, which contains two main items, the official name of the
  85 module name, which will be used in the
  86 .Vt module_t
  87 structure and a pointer to the event handler function of type
  88 .Vt modeventhand_t .
  89 .It Fa sub
  90 An argument directed to the
  91 .Fn SYSINIT
  92 macro.
  93 Valid values for this are contained in the
  94 .Vt sysinit_sub_id
  95 enumeration
  96 (see
  97 .In sys/kernel.h )
  98 and specify the type of system startup interfaces.
  99 The
 100 .Xr DRIVER_MODULE 9
 101 macro uses a value of
 102 .Dv SI_SUB_DRIVERS
 103 here for example, since these modules contain a driver for a device.
 104 For kernel modules that are loaded at runtime, a value of
 105 .Dv SI_SUB_EXEC
 106 is common.
 107 .It Fa order
 108 An argument for
 109 .Fn SYSINIT .
 110 It represents the KLDs order of initialization within the subsystem.
 111 Valid values are defined in the
 112 .Vt sysinit_elem_order
 113 enumeration
 114 .Pq In sys/kernel.h .
 115 .El
 116 .Sh SEE ALSO
 117 .Xr DEV_MODULE 9 ,
 118 .Xr DRIVER_MODULE 9 ,
 119 .Xr module 9 ,
 120 .Xr SYSCALL_MODULE 9
 121 .Pp
 122 .Pa /usr/include/sys/kernel.h ,
 123 .Pa /usr/share/examples/kld
 124 .Sh AUTHORS
 125 .An -nosplit
 126 This manual page was written by
 127 .An Alexander Langer Aq Mt alex@FreeBSD.org ,
 128 inspired by the KLD Facility Programming Tutorial by
 129 .An Andrew Reiter Aq Mt arr@watson.org .