xref: /freebsd/share/man/man9/DRIVER_MODULE.9 (revision fa9896e082a1046ff4fbc75fcba4d18d1f2efc19)
172f8c78bSAlexander Langer.\" -*- nroff -*-
272f8c78bSAlexander Langer.\"
372f8c78bSAlexander Langer.\" Copyright (c) 2000 Alexander Langer
472f8c78bSAlexander Langer.\"
572f8c78bSAlexander Langer.\" All rights reserved.
672f8c78bSAlexander Langer.\"
772f8c78bSAlexander Langer.\" This program is free software.
872f8c78bSAlexander Langer.\"
972f8c78bSAlexander Langer.\" Redistribution and use in source and binary forms, with or without
1072f8c78bSAlexander Langer.\" modification, are permitted provided that the following conditions
1172f8c78bSAlexander Langer.\" are met:
1272f8c78bSAlexander Langer.\" 1. Redistributions of source code must retain the above copyright
1372f8c78bSAlexander Langer.\"    notice, this list of conditions and the following disclaimer.
1472f8c78bSAlexander Langer.\" 2. Redistributions in binary form must reproduce the above copyright
1572f8c78bSAlexander Langer.\"    notice, this list of conditions and the following disclaimer in the
1672f8c78bSAlexander Langer.\"    documentation and/or other materials provided with the distribution.
1772f8c78bSAlexander Langer.\"
1872f8c78bSAlexander Langer.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
1972f8c78bSAlexander Langer.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
2072f8c78bSAlexander Langer.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
2172f8c78bSAlexander Langer.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
2272f8c78bSAlexander Langer.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
2372f8c78bSAlexander Langer.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
2472f8c78bSAlexander Langer.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
2572f8c78bSAlexander Langer.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
2672f8c78bSAlexander Langer.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
2772f8c78bSAlexander Langer.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
2872f8c78bSAlexander Langer.\"
29*b7d41925SJohn Baldwin.Dd April 19, 2022
3072f8c78bSAlexander Langer.Dt DRIVER_MODULE 9
3172f8c78bSAlexander Langer.Os
3272f8c78bSAlexander Langer.Sh NAME
33988a1851SJohn Baldwin.Nm DRIVER_MODULE ,
34988a1851SJohn Baldwin.Nm DRIVER_MODULE_ORDERED ,
35988a1851SJohn Baldwin.Nm EARLY_DRIVER_MODULE ,
36988a1851SJohn Baldwin.Nm EARLY_DRIVER_MODULE_ORDERED
3772f8c78bSAlexander Langer.Nd kernel driver declaration macro
3872f8c78bSAlexander Langer.Sh SYNOPSIS
39f16b3c0dSChad David.In sys/param.h
40f16b3c0dSChad David.In sys/kernel.h
4132eef9aeSRuslan Ermilov.In sys/bus.h
4232eef9aeSRuslan Ermilov.In sys/module.h
432a99dd30SJohn Baldwin.Fn DRIVER_MODULE name busname "driver_t driver" "modeventhand_t evh" "void *arg"
442a99dd30SJohn Baldwin.Fn DRIVER_MODULE_ORDERED name busname "driver_t driver" "modeventhand_t evh" "void *arg" "int order"
452a99dd30SJohn Baldwin.Fn EARLY_DRIVER_MODULE name busname "driver_t driver" "modeventhand_t evh" "void *arg" "int pass"
462a99dd30SJohn Baldwin.Fn EARLY_DRIVER_MODULE_ORDERED name busname "driver_t driver" "modeventhand_t evh" "void *arg" "enum sysinit_elem_order order" "int pass"
4772f8c78bSAlexander Langer.Sh DESCRIPTION
4872f8c78bSAlexander LangerThe
4972f8c78bSAlexander Langer.Fn DRIVER_MODULE
5072f8c78bSAlexander Langermacro declares a kernel driver.
5172f8c78bSAlexander Langer.Fn DRIVER_MODULE
5272f8c78bSAlexander Langerexpands to the real driver declaration, where the phrase
5372f8c78bSAlexander Langer.Fa name
5472f8c78bSAlexander Langeris used as the naming prefix for the driver and its functions.
554dad593aSAlexander LangerNote that it is supplied as plain text, and not a
5672f8c78bSAlexander Langer.Li char
5772f8c78bSAlexander Langeror
5872f8c78bSAlexander Langer.Li char * .
5972f8c78bSAlexander Langer.Pp
6072f8c78bSAlexander Langer.Fa busname
6157e4378bSRuslan Ermilovis the parent bus of the driver (PCI, ISA, PPBUS and others), e.g.\&
6272f8c78bSAlexander Langer.Ql pci ,
6372f8c78bSAlexander Langer.Ql isa ,
6472f8c78bSAlexander Langeror
6572f8c78bSAlexander Langer.Ql ppbus .
6672f8c78bSAlexander Langer.Pp
6772f8c78bSAlexander LangerThe identifier used in
6872f8c78bSAlexander Langer.Fn DRIVER_MODULE
6972f8c78bSAlexander Langercan be different from the driver name.
70db4fcadfSConrad MeyerAlso, the same driver identifier can exist on different buses,
7172f8c78bSAlexander Langerwhich is a pretty clean way of making front ends for different cards
72db4fcadfSConrad Meyerusing the same driver on the same or different buses.
7372f8c78bSAlexander LangerFor example, the following is allowed:
7472f8c78bSAlexander Langer.Pp
752a99dd30SJohn Baldwin.Fn DRIVER_MODULE foo isa foo_driver NULL NULL ;
7672f8c78bSAlexander Langer.Pp
772a99dd30SJohn Baldwin.Fn DRIVER_MODULE foo pci foo_driver NULL NULL ;
7872f8c78bSAlexander Langer.Pp
7972f8c78bSAlexander Langer.Fa driver
8072f8c78bSAlexander Langeris the driver of type
8172f8c78bSAlexander Langer.Li driver_t ,
8272f8c78bSAlexander Langerwhich contains the information about the driver and is therefore one of the
8372f8c78bSAlexander Langertwo most important parts of the call to
8472f8c78bSAlexander Langer.Fn DRIVER_MODULE .
8572f8c78bSAlexander Langer.Pp
8672f8c78bSAlexander LangerThe
8772f8c78bSAlexander Langer.Fa evh
8872f8c78bSAlexander Langerargument is the event handler which is called when the driver (or module)
893dca0e13SAlexander Langeris loaded or unloaded (see
903dca0e13SAlexander Langer.Xr module 9 ) .
9172f8c78bSAlexander Langer.Pp
9272f8c78bSAlexander LangerThe
9372f8c78bSAlexander Langer.Fa arg
9472f8c78bSAlexander Langeris unused at this time and should be a
9572f8c78bSAlexander Langer.Dv NULL
9672f8c78bSAlexander Langerpointer.
97988a1851SJohn Baldwin.Pp
98988a1851SJohn BaldwinThe
99988a1851SJohn Baldwin.Fn DRIVER_MODULE_ORDERED
100988a1851SJohn Baldwinmacro allows a driver to be registered in a specific order.
101988a1851SJohn BaldwinThis can be useful if a single kernel module contains multiple drivers
102988a1851SJohn Baldwinthat are inter-dependent.
103988a1851SJohn BaldwinThe
104988a1851SJohn Baldwin.Fa order
105988a1851SJohn Baldwinargument should be one of the
106988a1851SJohn Baldwin.Xr SYSINIT 9
107988a1851SJohn Baldwininitialization ordering constants
108988a1851SJohn Baldwin.Pq Dv SI_ORDER_* .
109988a1851SJohn BaldwinThe default order for a driver module is
110988a1851SJohn Baldwin.Dv SI_ORDER_MIDDLE .
111988a1851SJohn BaldwinTypically a module will specify an order of
112988a1851SJohn Baldwin.Dv SI_ORDER_ANY
113988a1851SJohn Baldwinfor a single driver to ensure it is registered last.
114988a1851SJohn Baldwin.Pp
115988a1851SJohn BaldwinThe
116988a1851SJohn Baldwin.Fn EARLY_DRIVER_MODULE
117988a1851SJohn Baldwinmacro allows a driver to be registered for a specific pass level.
118988a1851SJohn BaldwinThe boot time probe and attach process makes multiple passes over the
119988a1851SJohn Baldwindevice tree.
120988a1851SJohn BaldwinCertain critical drivers that provide basic services needed by other
1219747e453SMark Johnstondevices are attached during earlier passes.
122988a1851SJohn BaldwinMost drivers are attached in a final general pass.
123988a1851SJohn BaldwinA driver that attaches during an early pass must register for a specific
124988a1851SJohn Baldwinpass level
125988a1851SJohn Baldwin.Pq BUS_PASS_*
126988a1851SJohn Baldwinvia the
127988a1851SJohn Baldwin.Fa pass
128988a1851SJohn Baldwinargument.
129988a1851SJohn BaldwinOnce a driver is registered it is available to attach to devices for
130988a1851SJohn Baldwinall subsequent passes.
131988a1851SJohn Baldwin.Pp
132988a1851SJohn BaldwinThe
133988a1851SJohn Baldwin.Fn EARLY_DRIVER_MODULE_ORDERED
134988a1851SJohn Baldwinmacro allows a driver to be registered both in a specific order and
135988a1851SJohn Baldwinfor a specific pass level.
13672f8c78bSAlexander Langer.Sh SEE ALSO
1373dca0e13SAlexander Langer.Xr device 9 ,
1385521ff5aSRuslan Ermilov.Xr driver 9 ,
139988a1851SJohn Baldwin.Xr module 9 ,
1404777ab97SConrad Meyer.Xr MODULE_PNP_INFO 9 ,
141988a1851SJohn Baldwin.Xr SYSINIT 9
1422a99dd30SJohn Baldwin.Sh HISTORY
1432a99dd30SJohn BaldwinPrior to
1442a99dd30SJohn Baldwin.Fx 14.0 ,
1452a99dd30SJohn Baldwinthese macros accepted an additional
1462a99dd30SJohn Baldwin.Vt devclass_t
1472a99dd30SJohn Baldwinargument after
1482a99dd30SJohn Baldwin.Fa driver .
14972f8c78bSAlexander Langer.Sh AUTHORS
15072f8c78bSAlexander LangerThis manual page was written by
1518a7314fcSBaptiste Daroussin.An Alexander Langer Aq Mt alex@FreeBSD.org .
152