1/*-
2 * Copyright (c) 1997 Doug Rabson
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 * 1. Redistributions of source code must retain the above copyright
9 *    notice, this list of conditions and the following disclaimer.
10 * 2. Redistributions in binary form must reproduce the above copyright
11 *    notice, this list of conditions and the following disclaimer in the
12 *    documentation and/or other materials provided with the distribution.
13 *
14 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24 * SUCH DAMAGE.
25 *
26 * $FreeBSD$
27 */
28
29#ifndef _SYS_MODULE_H_
30#define _SYS_MODULE_H_
31
32/*
33 * Module metadata types
34 */
35#define	MDT_DEPEND	1		/* argument is a module name */
36#define	MDT_MODULE	2		/* module declaration */
37#define	MDT_VERSION	3		/* module version(s) */
38#define	MDT_PNP_INFO	4		/* Plug and play hints record */
39
40#define	MDT_STRUCT_VERSION	1	/* version of metadata structure */
41#define	MDT_SETNAME	"modmetadata_set"
42
43typedef enum modeventtype {
44	MOD_LOAD,
45	MOD_UNLOAD,
46	MOD_SHUTDOWN,
47	MOD_QUIESCE
48} modeventtype_t;
49
50typedef struct module *module_t;
51typedef int (*modeventhand_t)(module_t, int /* modeventtype_t */, void *);
52
53/*
54 * Struct for registering modules statically via SYSINIT.
55 */
56typedef struct moduledata {
57	const char	*name;		/* module name */
58	modeventhand_t  evhand;		/* event handler */
59	void		*priv;		/* extra data */
60} moduledata_t;
61
62/*
63 * A module can use this to report module specific data to the user via
64 * kldstat(2).
65 */
66typedef union modspecific {
67	int	intval;
68	u_int	uintval;
69	long	longval;
70	u_long	ulongval;
71} modspecific_t;
72
73/*
74 * Module dependency declaration
75 */
76struct mod_depend {
77	int	md_ver_minimum;
78	int	md_ver_preferred;
79	int	md_ver_maximum;
80};
81
82/*
83 * Module version declaration
84 */
85struct mod_version {
86	int	mv_version;
87};
88
89struct mod_metadata {
90	int		md_version;	/* structure version MDTV_* */
91	int		md_type;	/* type of entry MDT_* */
92	const void	*md_data;	/* specific data */
93	const char	*md_cval;	/* common string label */
94};
95
96struct mod_pnp_match_info
97{
98	const char *descr;	/* Description of the table */
99	const char *bus;	/* Name of the bus for this table */
100	const void *table;	/* Pointer to pnp table */
101	int entry_len;		/* Length of each entry in the table (may be */
102				/*   longer than descr describes). */
103	int num_entry;		/* Number of entries in the table */
104};
105#ifdef	_KERNEL
106
107#include <sys/linker_set.h>
108
109#define	MODULE_METADATA(uniquifier, type, data, cval)			\
110	static struct mod_metadata _mod_metadata##uniquifier = {	\
111		MDT_STRUCT_VERSION,					\
112		type,							\
113		data,							\
114		cval							\
115	};								\
116	DATA_SET(modmetadata_set, _mod_metadata##uniquifier)
117
118#define	MODULE_DEPEND(module, mdepend, vmin, vpref, vmax)		\
119	static struct mod_depend _##module##_depend_on_##mdepend	\
120	    __section(".data") = {					\
121		vmin,							\
122		vpref,							\
123		vmax							\
124	};								\
125	MODULE_METADATA(_md_##module##_on_##mdepend, MDT_DEPEND,	\
126	    &_##module##_depend_on_##mdepend, #mdepend)
127
128/*
129 * Every kernel has a 'kernel' module with the version set to
130 * __FreeBSD_version.  We embed a MODULE_DEPEND() inside every module
131 * that depends on the 'kernel' module.  It uses the current value of
132 * __FreeBSD_version as the minimum and preferred versions.  For the
133 * maximum version it rounds the version up to the end of its branch
134 * (i.e. M99999 for M.x).  This allows a module built on M.x to work
135 * on M.y systems where y >= x, but fail on M.z systems where z < x.
136 */
137#define	MODULE_KERNEL_MAXVER	(roundup(__FreeBSD_version, 100000) - 1)
138
139#define	DECLARE_MODULE_WITH_MAXVER(name, data, sub, order, maxver)	\
140	MODULE_DEPEND(name, kernel, __FreeBSD_version,			\
141	    __FreeBSD_version, maxver);			\
142	MODULE_METADATA(_md_##name, MDT_MODULE, &data, #name);		\
143	SYSINIT(name##module, sub, order, module_register_init, &data);	\
144	struct __hack
145
146#define	DECLARE_MODULE(name, data, sub, order)				\
147	DECLARE_MODULE_WITH_MAXVER(name, data, sub, order, MODULE_KERNEL_MAXVER)
148
149/*
150 * The module declared with DECLARE_MODULE_TIED can only be loaded
151 * into the kernel with exactly the same __FreeBSD_version.
152 *
153 * Use it for modules that use kernel interfaces that are not stable
154 * even on STABLE/X branches.
155 */
156#define	DECLARE_MODULE_TIED(name, data, sub, order)				\
157	DECLARE_MODULE_WITH_MAXVER(name, data, sub, order, __FreeBSD_version)
158
159#define	MODULE_VERSION(module, version)					\
160	static struct mod_version _##module##_version			\
161	    __section(".data") = {					\
162		version							\
163	};								\
164	MODULE_METADATA(_##module##_version, MDT_VERSION,		\
165	    &_##module##_version, #module)
166
167/**
168 * Generic macros to create pnp info hints that modules may export
169 * to allow external tools to parse their intenral device tables
170 * to make an informed guess about what driver(s) to load.
171 */
172#define	MODULE_PNP_INFO(d, b, unique, t, l, n)				\
173	static const struct mod_pnp_match_info _module_pnp_##b##_##unique = {	\
174		.descr = d,						\
175		.bus = #b,						\
176		.table = t,						\
177		.entry_len = l,						\
178		.num_entry = n						\
179	};								\
180	MODULE_METADATA(_md_##b##_pnpinfo_##unique, MDT_PNP_INFO,	\
181	    &_module_pnp_##b##_##unique, #b);
182/**
183 * descr is a string that describes each entry in the table. The general
184 * form is (TYPE:pnp_name[/pnp_name];)*
185 * where TYPE is one of the following:
186 *	U8	uint8_t element
187 *	V8	like U8 and 0xff means match any
188 *	G16	uint16_t element, any value >= matches
189 *	L16	uint16_t element, any value <= matches
190 *	M16	uint16_t element, mask of which of the following fields to use.
191 *	U16	uint16_t element
192 *	V16	like U16 and 0xffff means match any
193 *	U32	uint32_t element
194 *	V32	like U32 and 0xffffffff means match any
195 *	W32	Two 16-bit values with first pnp_name in LSW and second in MSW.
196 *	Z	pointer to a string to match exactly
197 *	D	like Z, but is the string passed to device_set_descr()
198 *	P	A pointer that should be ignored
199 *	E	EISA PNP Identifier (in binary, but bus publishes string)
200 *	K	Key for whole table. pnp_name=value. must be last, if present.
201 *
202 * The pnp_name "#" is reserved for other fields that should be ignored.
203 */
204
205extern struct sx modules_sx;
206
207#define	MOD_XLOCK	sx_xlock(&modules_sx)
208#define	MOD_SLOCK	sx_slock(&modules_sx)
209#define	MOD_XUNLOCK	sx_xunlock(&modules_sx)
210#define	MOD_SUNLOCK	sx_sunlock(&modules_sx)
211#define	MOD_LOCK_ASSERT	sx_assert(&modules_sx, SX_LOCKED)
212#define	MOD_XLOCK_ASSERT	sx_assert(&modules_sx, SX_XLOCKED)
213
214struct linker_file;
215
216void	module_register_init(const void *);
217int	module_register(const struct moduledata *, struct linker_file *);
218module_t	module_lookupbyname(const char *);
219module_t	module_lookupbyid(int);
220int	module_quiesce(module_t);
221void	module_reference(module_t);
222void	module_release(module_t);
223int	module_unload(module_t);
224int	module_getid(module_t);
225module_t	module_getfnext(module_t);
226const char *	module_getname(module_t);
227void	module_setspecific(module_t, modspecific_t *);
228struct linker_file *module_file(module_t);
229
230#ifdef	MOD_DEBUG
231extern int mod_debug;
232#define	MOD_DEBUG_REFS	1
233
234#define	MOD_DPF(cat, args) do {						\
235	if (mod_debug & MOD_DEBUG_##cat)				\
236		printf(args);						\
237} while (0)
238
239#else	/* !MOD_DEBUG */
240
241#define	MOD_DPF(cat, args)
242#endif
243#endif	/* _KERNEL */
244
245#define	MAXMODNAME	32
246
247struct module_stat {
248	int		version;	/* set to sizeof(struct module_stat) */
249	char		name[MAXMODNAME];
250	int		refs;
251	int		id;
252	modspecific_t	data;
253};
254
255#ifndef _KERNEL
256
257#include <sys/cdefs.h>
258
259__BEGIN_DECLS
260int	modnext(int _modid);
261int	modfnext(int _modid);
262int	modstat(int _modid, struct module_stat *_stat);
263int	modfind(const char *_name);
264__END_DECLS
265
266#endif
267
268#endif	/* !_SYS_MODULE_H_ */
269