1/*-
2 * SPDX-License-Identifier: BSD-2-Clause
3 *
4 * Copyright (c) 2000,2003 Doug Rabson
5 * All rights reserved.
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
9 * are met:
10 * 1. Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
12 * 2. Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 * SUCH DAMAGE.
27 */
28
29#ifndef _SYS_KOBJ_H_
30#define _SYS_KOBJ_H_
31
32/*
33 * Forward declarations
34 */
35typedef struct kobj *kobj_t;
36typedef struct kobj_class *kobj_class_t;
37typedef const struct kobj_method kobj_method_t;
38typedef void (*kobjop_t)(void);
39typedef struct kobj_ops *kobj_ops_t;
40typedef struct kobjop_desc *kobjop_desc_t;
41struct malloc_type;
42
43struct kobj_method {
44 kobjop_desc_t desc;
45 kobjop_t func;
46};
47
48/*
49 * A class is simply a method table and a sizeof value. When the first
50 * instance of the class is created, the method table will be compiled
51 * into a form more suited to efficient method dispatch. This compiled
52 * method table is always the first field of the object.
53 */
54#define KOBJ_CLASS_FIELDS \
55 const char *name; /* class name */ \
56 kobj_method_t *methods; /* method table */ \
57 size_t size; /* object size */ \
58 kobj_class_t *baseclasses; /* base classes */ \
59 u_int refs; /* reference count */ \
60 kobj_ops_t ops /* compiled method table */
61
62struct kobj_class {
63 KOBJ_CLASS_FIELDS;
64};
65
66/*
67 * Implementation of kobj.
68 */
69#define KOBJ_FIELDS \
70 kobj_ops_t ops
71
72struct kobj {
73 KOBJ_FIELDS;
74};
75
76/*
77 * The ops table is used as a cache of results from kobj_lookup_method().
78 */
79
80#define KOBJ_CACHE_SIZE 256
81
82struct kobj_ops {
83 kobj_method_t *cache[KOBJ_CACHE_SIZE];
84 kobj_class_t cls;
85};
86
87struct kobjop_desc {
88 unsigned int id; /* unique ID */
89 kobj_method_t deflt; /* default implementation */
90};
91
92/*
93 * Shorthand for constructing method tables.
94 * The ternary operator is (ab)used to provoke a warning when FUNC
95 * has a signature that is not compatible with kobj method signature.
96 */
97#define KOBJMETHOD(NAME, FUNC) \
98 { &NAME##_desc, (kobjop_t) (1 ? FUNC : (NAME##_t *)NULL) }
99
100/*
101 *
102 */
103#define KOBJMETHOD_END { NULL, NULL }
104
105/*
106 * Declare a class (which should be defined in another file.
107 */
108#define DECLARE_CLASS(name) extern struct kobj_class name
109
110/*
111 * Define a class with no base classes (api backward-compatible. with
112 * FreeBSD-5.1 and earlier).
113 */
114#define DEFINE_CLASS(name, methods, size) \
115DEFINE_CLASS_0(name, name ## _class, methods, size)
116
117/*
118 * Define a class with no base classes. Use like this:
119 *
120 * DEFINE_CLASS_0(foo, foo_class, foo_methods, sizeof(foo_softc));
121 */
122#define DEFINE_CLASS_0(name, classvar, methods, size) \
123 \
124struct kobj_class classvar = { \
125 #name, methods, size, NULL \
126}
127
128/*
129 * Define a class inheriting a single base class. Use like this:
130 *
131 * DEFINE_CLASS_1(foo, foo_class, foo_methods, sizeof(foo_softc),
132 * bar);
133 */
134#define DEFINE_CLASS_1(name, classvar, methods, size, \
135 base1) \
136 \
137static kobj_class_t name ## _baseclasses[] = \
138 { &base1, NULL }; \
139struct kobj_class classvar = { \
140 #name, methods, size, name ## _baseclasses \
141}
142
143/*
144 * Define a class inheriting two base classes. Use like this:
145 *
146 * DEFINE_CLASS_2(foo, foo_class, foo_methods, sizeof(foo_softc),
147 * bar, baz);
148 */
149#define DEFINE_CLASS_2(name, classvar, methods, size, \
150 base1, base2) \
151 \
152static kobj_class_t name ## _baseclasses[] = \
153 { &base1, \
154 &base2, NULL }; \
155struct kobj_class classvar = { \
156 #name, methods, size, name ## _baseclasses \
157}
158
159/*
160 * Define a class inheriting three base classes. Use like this:
161 *
162 * DEFINE_CLASS_3(foo, foo_class, foo_methods, sizeof(foo_softc),
163 * bar, baz, foobar);
164 */
165#define DEFINE_CLASS_3(name, classvar, methods, size, \
166 base1, base2, base3) \
167 \
168static kobj_class_t name ## _baseclasses[] = \
169 { &base1, \
170 &base2, \
171 &base3, NULL }; \
172struct kobj_class classvar = { \
173 #name, methods, size, name ## _baseclasses \
174}
175
176/*
177 * Compile the method table in a class.
178 */
179void kobj_class_compile(kobj_class_t cls);
180
181/*
182 * Compile the method table, with the caller providing the space for
183 * the ops table.(for use before malloc is initialised).
184 */
185void kobj_class_compile_static(kobj_class_t cls, kobj_ops_t ops);
186
187/*
188 * Free the compiled method table in a class.
189 */
190void kobj_class_free(kobj_class_t cls);
191
192/*
193 * Allocate memory for and initialise a new object.
194 */
195kobj_t kobj_create(kobj_class_t cls,
196 struct malloc_type *mtype,
197 int mflags);
198
199/*
200 * Initialise a pre-allocated object.
201 */
202void kobj_init(kobj_t obj, kobj_class_t cls);
203void kobj_init_static(kobj_t obj, kobj_class_t cls);
204
205/*
206 * Delete an object. If mtype is non-zero, free the memory.
207 */
208void kobj_delete(kobj_t obj, struct malloc_type *mtype);
209
210/*
211 * Maintain stats on hits/misses in lookup caches.
212 */
213#ifdef KOBJ_STATS
214extern u_int kobj_lookup_hits;
215extern u_int kobj_lookup_misses;
216#endif
217
218/*
219 * Lookup the method in the cache and if it isn't there look it up the
220 * slow way.
221 */
222#ifdef KOBJ_STATS
223#define KOBJOPLOOKUP(OPS,OP) do { \
224 kobjop_desc_t _desc = &OP##_##desc; \
225 kobj_method_t **_cep = \
226 &OPS->cache[_desc->id & (KOBJ_CACHE_SIZE-1)]; \
227 kobj_method_t *_ce = *_cep; \
228 if (_ce->desc != _desc) { \
229 _ce = kobj_lookup_method(OPS->cls, \
230 _cep, _desc); \
231 kobj_lookup_misses++; \
232 } else \
233 kobj_lookup_hits++; \
234 _m = _ce->func; \
235} while (0)
236#else
237#define KOBJOPLOOKUP(OPS,OP) do { \
238 kobjop_desc_t _desc = &OP##_##desc; \
239 kobj_method_t **_cep = \
240 &OPS->cache[_desc->id & (KOBJ_CACHE_SIZE-1)]; \
241 kobj_method_t *_ce = *_cep; \
242 if (_ce->desc != _desc) \
243 _ce = kobj_lookup_method(OPS->cls, \
244 _cep, _desc); \
245 _m = _ce->func; \
246} while (0)
247#endif
248
249kobj_method_t* kobj_lookup_method(kobj_class_t cls,
250 kobj_method_t **cep,
251 kobjop_desc_t desc);
252
253/*
254 * Default method implementation. Returns ENXIO.
255 */
256int kobj_error_method(void);
257
258#endif /* !_SYS_KOBJ_H_ */