1 #ifndef _IPXE_INTERFACE_H
2 #define _IPXE_INTERFACE_H
3
4 /** @file
5 *
6 * Object interfaces
7 *
8 */
9
10 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
11
12 #include <stddef.h>
13 #include <stdarg.h>
14 #include <ipxe/refcnt.h>
15
16 /** An object interface operation */
17 struct interface_operation {
18 /** Operation type */
19 void *type;
20 /** Implementing method */
21 void *func;
22 };
23
24 /**
25 * Define an object interface operation
26 *
27 * @v op_type Operation type
28 * @v object_type Implementing method's expected object type
29 * @v op_func Implementing method
30 * @ret op Object interface operation
31 */
32 #define INTF_OP( op_type, object_type, op_func ) { \
33 .type = op_type, \
34 .func = ( ( ( ( typeof ( op_func ) * ) NULL ) == \
35 ( ( op_type ## _TYPE ( object_type ) * ) NULL ) ) \
36 ? op_func : op_func ), \
37 }
38
39 /** An object interface descriptor */
40 struct interface_descriptor {
41 /** Offset of interface within containing object */
42 size_t offset;
43 /** Number of interface operations */
44 unsigned int num_op;
45 /** Object interface operations */
46 struct interface_operation *op;
47 /** Offset to pass-through interface, if present */
48 ssize_t passthru_offset;
49 };
50
51 #define intf_offset( object_type, intf ) \
52 ( ( ( ( typeof ( ( ( object_type * ) NULL )->intf ) * ) NULL ) \
53 == ( ( struct interface * ) NULL ) ) \
54 ? offsetof ( object_type, intf ) \
55 : offsetof ( object_type, intf ) )
56
57 /**
58 * Define an object interface descriptor
59 *
60 * @v object_type Containing object data type
61 * @v intf Interface name (i.e. field within object data type)
62 * @v operations Object interface operations array
63 * @ret desc Object interface descriptor
64 */
65 #define INTF_DESC( object_type, intf, operations ) { \
66 .offset = intf_offset ( object_type, intf ), \
67 .op = operations, \
68 .num_op = ( sizeof ( operations ) / \
69 sizeof ( operations[0] ) ), \
70 .passthru_offset = 0, \
71 }
72
73 /**
74 * Define an object interface descriptor with pass-through interface
75 *
76 * @v object_type Containing object data type
77 * @v intf Interface name (i.e. field within object data type)
78 * @v operations Object interface operations array
79 * @v passthru Pass-through interface name
80 * @ret desc Object interface descriptor
81 */
82 #define INTF_DESC_PASSTHRU( object_type, intf, operations, passthru ) { \
83 .offset = offsetof ( object_type, intf ), \
84 .op = operations, \
85 .num_op = ( sizeof ( operations ) / \
86 sizeof ( operations[0] ) ), \
87 .passthru_offset = ( intf_offset ( object_type, passthru ) - \
88 intf_offset ( object_type, intf ) ), \
89 }
90
91 /**
92 * Define an object interface descriptor for a pure-interface object
93 *
94 * @v operations Object interface operations array
95 * @ret desc Object interface descriptor
96 *
97 * A pure-interface object is an object that consists solely of a
98 * single interface.
99 */
100 #define INTF_DESC_PURE( operations ) { \
101 .offset = 0, \
102 .op = operations, \
103 .num_op = ( sizeof ( operations ) / \
104 sizeof ( operations[0] ) ), \
105 .passthru_offset = 0, \
106 }
107
108 /** An object interface */
109 struct interface {
110 /** Destination object interface
111 *
112 * When the containing object invokes an operation on this
113 * interface, it will be executed by the destination object.
114 *
115 * This pointer may never be NULL. When the interface is
116 * unplugged, it should point to the null interface.
117 */
118 struct interface *dest;
119 /** Reference counter
120 *
121 * If this interface is not part of a reference-counted
122 * object, this field may be NULL.
123 */
124 struct refcnt *refcnt;
125 /** Interface descriptor */
126 struct interface_descriptor *desc;
127 /** Original interface descriptor
128 *
129 * Used by intf_reinit().
130 */
131 struct interface_descriptor *original;
132 };
133
134 extern void intf_plug ( struct interface *intf, struct interface *dest );
135 extern void intf_plug_plug ( struct interface *a, struct interface *b );
136 extern void intf_unplug ( struct interface *intf );
137 extern void intf_nullify ( struct interface *intf );
138 extern struct interface * intf_get ( struct interface *intf );
139 extern void intf_put ( struct interface *intf );
140 extern void * __attribute__ (( pure )) intf_object ( struct interface *intf );
141 extern void * intf_get_dest_op_no_passthru_untyped ( struct interface *intf,
142 void *type,
143 struct interface **dest );
144 extern void * intf_get_dest_op_untyped ( struct interface *intf, void *type,
145 struct interface **dest );
146
147 extern void intf_close ( struct interface *intf, int rc );
148 #define intf_close_TYPE( object_type ) \
149 typeof ( void ( object_type, int rc ) )
150
151 extern void intf_shutdown ( struct interface *intf, int rc );
152 extern void intfs_vshutdown ( va_list intfs, int rc );
153 extern void intfs_shutdown ( int rc, ... ) __attribute__ (( sentinel ));
154 extern void intf_restart ( struct interface *intf, int rc );
155 extern void intfs_vrestart ( va_list intfs, int rc );
156 extern void intfs_restart ( int rc, ... ) __attribute__ (( sentinel ));
157
158 extern void intf_poke ( struct interface *intf,
159 void ( type ) ( struct interface *intf ) );
160 #define intf_poke_TYPE( object_type ) \
161 typeof ( void ( object_type ) )
162
163 extern struct interface_descriptor null_intf_desc;
164 extern struct interface null_intf;
165
166 /**
167 * Initialise an object interface
168 *
169 * @v intf Object interface
170 * @v desc Object interface descriptor
171 * @v refcnt Containing object reference counter, or NULL
172 */
intf_init(struct interface * intf,struct interface_descriptor * desc,struct refcnt * refcnt)173 static inline void intf_init ( struct interface *intf,
174 struct interface_descriptor *desc,
175 struct refcnt *refcnt ) {
176 intf->dest = &null_intf;
177 intf->refcnt = refcnt;
178 intf->desc = desc;
179 intf->original = desc;
180 }
181
182 /**
183 * Initialise a static object interface
184 *
185 * @v descriptor Object interface descriptor
186 */
187 #define INTF_INIT( descriptor ) { \
188 .dest = &null_intf, \
189 .refcnt = NULL, \
190 .desc = &(descriptor), \
191 .original = &(descriptor), \
192 }
193
194 /**
195 * Get object interface destination and operation method (without pass-through)
196 *
197 * @v intf Object interface
198 * @v type Operation type
199 * @ret dest Destination interface
200 * @ret func Implementing method, or NULL
201 */
202 #define intf_get_dest_op_no_passthru( intf, type, dest ) \
203 ( ( type ## _TYPE ( void * ) * ) \
204 intf_get_dest_op_no_passthru_untyped ( intf, type, dest ) )
205
206 /**
207 * Get object interface destination and operation method
208 *
209 * @v intf Object interface
210 * @v type Operation type
211 * @ret dest Destination interface
212 * @ret func Implementing method, or NULL
213 */
214 #define intf_get_dest_op( intf, type, dest ) \
215 ( ( type ## _TYPE ( void * ) * ) \
216 intf_get_dest_op_untyped ( intf, type, dest ) )
217
218 /**
219 * Find debugging colourisation for an object interface
220 *
221 * @v intf Object interface
222 * @ret col Debugging colourisation
223 *
224 * Use as the first argument to DBGC() or equivalent macro.
225 */
226 #define INTF_COL( intf ) intf_object ( intf )
227
228 /** printf() format string for INTF_DBG() */
229 #define INTF_FMT "%p+%zx"
230
231 /**
232 * printf() arguments for representing an object interface
233 *
234 * @v intf Object interface
235 * @ret args printf() argument list corresponding to INTF_FMT
236 */
237 #define INTF_DBG( intf ) intf_object ( intf ), (intf)->desc->offset
238
239 /** printf() format string for INTF_INTF_DBG() */
240 #define INTF_INTF_FMT INTF_FMT "->" INTF_FMT
241
242 /**
243 * printf() arguments for representing an object interface pair
244 *
245 * @v intf Object interface
246 * @v dest Destination object interface
247 * @ret args printf() argument list corresponding to INTF_INTF_FMT
248 */
249 #define INTF_INTF_DBG( intf, dest ) INTF_DBG ( intf ), INTF_DBG ( dest )
250
251 /**
252 * Reinitialise an object interface
253 *
254 * @v intf Object interface
255 */
intf_reinit(struct interface * intf)256 static inline void intf_reinit ( struct interface *intf ) {
257
258 /* Restore original interface descriptor */
259 intf->desc = intf->original;
260 }
261
262 #endif /* _IPXE_INTERFACE_H */
263