1 #ifndef _IPXE_INTERFACE_H
2 #define _IPXE_INTERFACE_H
10 FILE_LICENCE ( GPL2_OR_LATER );
13 #include <ipxe/refcnt.h>
15 /** An object interface operation */
16 struct interface_operation {
19 /** Implementing method */
24 * Define an object interface operation
26 * @v op_type Operation type
27 * @v object_type Implementing method's expected object type
28 * @v op_func Implementing method
29 * @ret op Object interface operation
31 #define INTF_OP( op_type, object_type, op_func ) { \
33 .func = ( ( ( ( typeof ( op_func ) * ) NULL ) == \
34 ( ( op_type ## _TYPE ( object_type ) * ) NULL ) ) \
35 ? op_func : op_func ), \
38 /** An object interface descriptor */
39 struct interface_descriptor {
40 /** Offset of interface within containing object */
42 /** Number of interface operations */
44 /** Object interface operations */
45 struct interface_operation *op;
46 /** Offset to pass-through interface, if present */
47 ssize_t passthru_offset;
50 #define intf_offset( object_type, intf ) \
51 ( ( ( ( typeof ( ( ( object_type * ) NULL )->intf ) * ) NULL ) \
52 == ( ( struct interface * ) NULL ) ) \
53 ? offsetof ( object_type, intf ) \
54 : offsetof ( object_type, intf ) )
57 * Define an object interface descriptor
59 * @v object_type Containing object data type
60 * @v intf Interface name (i.e. field within object data type)
61 * @v operations Object interface operations array
62 * @ret desc Object interface descriptor
64 #define INTF_DESC( object_type, intf, operations ) { \
65 .offset = intf_offset ( object_type, intf ), \
67 .num_op = ( sizeof ( operations ) / \
68 sizeof ( operations[0] ) ), \
69 .passthru_offset = 0, \
73 * Define an object interface descriptor with pass-through interface
75 * @v object_type Containing object data type
76 * @v intf Interface name (i.e. field within object data type)
77 * @v operations Object interface operations array
78 * @v passthru Pass-through interface name
79 * @ret desc Object interface descriptor
81 #define INTF_DESC_PASSTHRU( object_type, intf, operations, passthru ) { \
82 .offset = offsetof ( object_type, intf ), \
84 .num_op = ( sizeof ( operations ) / \
85 sizeof ( operations[0] ) ), \
86 .passthru_offset = ( intf_offset ( object_type, passthru ) - \
87 intf_offset ( object_type, intf ) ), \
91 * Define an object interface descriptor for a pure-interface object
93 * @v operations Object interface operations array
94 * @ret desc Object interface descriptor
96 * A pure-interface object is an object that consists solely of a
99 #define INTF_DESC_PURE( operations ) { \
102 .num_op = ( sizeof ( operations ) / \
103 sizeof ( operations[0] ) ), \
104 .passthru_offset = 0, \
107 /** An object interface */
109 /** Destination object interface
111 * When the containing object invokes an operation on this
112 * interface, it will be executed by the destination object.
114 * This pointer may never be NULL. When the interface is
115 * unplugged, it should point to the null interface.
117 struct interface *dest;
118 /** Reference counter
120 * If this interface is not part of a reference-counted
121 * object, this field may be NULL.
123 struct refcnt *refcnt;
124 /** Interface descriptor */
125 struct interface_descriptor *desc;
128 extern void intf_plug ( struct interface *intf, struct interface *dest );
129 extern void intf_plug_plug ( struct interface *a, struct interface *b );
130 extern void intf_unplug ( struct interface *intf );
131 extern void intf_nullify ( struct interface *intf );
132 extern struct interface * intf_get ( struct interface *intf );
133 extern void intf_put ( struct interface *intf );
134 extern void * __attribute__ (( pure )) intf_object ( struct interface *intf );
135 extern void * intf_get_dest_op_no_passthru_untyped ( struct interface *intf,
137 struct interface **dest );
138 extern void * intf_get_dest_op_untyped ( struct interface *intf, void *type,
139 struct interface **dest );
141 extern void intf_close ( struct interface *intf, int rc );
142 #define intf_close_TYPE( object_type ) \
143 typeof ( void ( object_type, int rc ) )
145 extern void intf_shutdown ( struct interface *intf, int rc );
146 extern void intf_restart ( struct interface *intf, int rc );
148 extern struct interface_descriptor null_intf_desc;
149 extern struct interface null_intf;
152 * Initialise an object interface
154 * @v intf Object interface
155 * @v desc Object interface descriptor
156 * @v refcnt Containing object reference counter, or NULL
158 static inline void intf_init ( struct interface *intf,
159 struct interface_descriptor *desc,
160 struct refcnt *refcnt ) {
161 intf->dest = &null_intf;
162 intf->refcnt = refcnt;
167 * Initialise a static object interface
169 * @v descriptor Object interface descriptor
171 #define INTF_INIT( descriptor ) { \
172 .dest = &null_intf, \
174 .desc = &(descriptor), \
178 * Get object interface destination and operation method (without pass-through)
180 * @v intf Object interface
181 * @v type Operation type
182 * @ret dest Destination interface
183 * @ret func Implementing method, or NULL
185 #define intf_get_dest_op_no_passthru( intf, type, dest ) \
186 ( ( type ## _TYPE ( void * ) * ) \
187 intf_get_dest_op_no_passthru_untyped ( intf, type, dest ) )
190 * Get object interface destination and operation method
192 * @v intf Object interface
193 * @v type Operation type
194 * @ret dest Destination interface
195 * @ret func Implementing method, or NULL
197 #define intf_get_dest_op( intf, type, dest ) \
198 ( ( type ## _TYPE ( void * ) * ) \
199 intf_get_dest_op_untyped ( intf, type, dest ) )
202 * Find debugging colourisation for an object interface
204 * @v intf Object interface
205 * @ret col Debugging colourisation
207 * Use as the first argument to DBGC() or equivalent macro.
209 #define INTF_COL( intf ) intf_object ( intf )
211 /** printf() format string for INTF_DBG() */
212 #define INTF_FMT "%p+%zx"
215 * printf() arguments for representing an object interface
217 * @v intf Object interface
218 * @ret args printf() argument list corresponding to INTF_FMT
220 #define INTF_DBG( intf ) intf_object ( intf ), (intf)->desc->offset
222 /** printf() format string for INTF_INTF_DBG() */
223 #define INTF_INTF_FMT INTF_FMT "->" INTF_FMT
226 * printf() arguments for representing an object interface pair
228 * @v intf Object interface
229 * @v dest Destination object interface
230 * @ret args printf() argument list corresponding to INTF_INTF_FMT
232 #define INTF_INTF_DBG( intf, dest ) INTF_DBG ( intf ), INTF_DBG ( dest )
234 #endif /* _IPXE_INTERFACE_H */