iPXE
interface.h
Go to the documentation of this file.
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 */
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 */
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 */
47  /** Offset to pass-through interface, if present */
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 */
127  /** Original interface descriptor
128  *
129  * Used by intf_reinit().
130  */
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 
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  */
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  */
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 */
An object interface operation.
Definition: interface.h:17
void intf_put(struct interface *intf)
Decrement reference count on an object interface.
Definition: interface.c:144
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
void intf_nullify(struct interface *intf)
Ignore all further operations on an object interface.
Definition: interface.c:124
uint8_t type
Type.
Definition: ena.h:16
size_t offset
Offset of interface within containing object.
Definition: interface.h:42
void intf_plug(struct interface *intf, struct interface *dest)
Plug an object interface into a new destination object interface.
Definition: interface.c:83
void intf_close(struct interface *intf, int rc)
Close an object interface.
Definition: interface.c:244
void intf_restart(struct interface *intf, int rc)
Shut down and restart an object interface.
Definition: interface.c:337
static void(*) struct refcnt refcnt)
Definition: pool.h:62
void * intf_object(struct interface *intf)
Get pointer to object containing object interface.
Definition: interface.c:154
void * func
Implementing method.
Definition: interface.h:21
A reference counter.
Definition: refcnt.h:26
unsigned int num_op
Number of interface operations.
Definition: interface.h:44
struct interface * dest
Destination object interface.
Definition: interface.h:118
void intfs_vshutdown(va_list intfs, int rc)
Shut down multiple object interfaces.
Definition: interface.c:299
struct interface_operation * op
Object interface operations.
Definition: interface.h:46
An object interface.
Definition: interface.h:109
void * intf_get_dest_op_no_passthru_untyped(struct interface *intf, void *type, struct interface **dest)
Get object interface destination and operation method (without pass-through)
Definition: interface.c:182
ssize_t passthru_offset
Offset to pass-through interface, if present.
Definition: interface.h:48
void intfs_restart(int rc,...) __attribute__((sentinel))
Shut down and restart multiple object interfaces.
Definition: interface.c:380
void intfs_shutdown(int rc,...) __attribute__((sentinel))
Shut down multiple object interfaces.
Definition: interface.c:320
struct interface null_intf
The null interface.
Definition: interface.c:65
void * type
Operation type.
Definition: interface.h:19
A 16-bit general register.
Definition: registers.h:24
struct interface_descriptor null_intf_desc
Null interface descriptor.
Definition: interface.c:61
void intfs_vrestart(va_list intfs, int rc)
Shut down and restart multiple object interfaces.
Definition: interface.c:360
static void * dest
Definition: strings.h:176
An object interface descriptor.
Definition: interface.h:40
void intf_poke(struct interface *intf, void(type)(struct interface *intf))
Poke an object interface.
Definition: interface.c:397
FILE_LICENCE(GPL2_OR_LATER_OR_UBDL)
struct interface * intf_get(struct interface *intf)
Increment reference count on an object interface.
Definition: interface.c:134
void intf_unplug(struct interface *intf)
Unplug an object interface.
Definition: interface.c:112
__builtin_va_list va_list
Definition: stdarg.h:6
void intf_plug_plug(struct interface *a, struct interface *b)
Plug two object interfaces together.
Definition: interface.c:102
void * intf_get_dest_op_untyped(struct interface *intf, void *type, struct interface **dest)
Get object interface destination and operation method.
Definition: interface.c:207
Reference counting.
void intf_shutdown(struct interface *intf, int rc)
Shut down an object interface.
Definition: interface.c:273
struct interface_descriptor * desc
Interface descriptor.
Definition: interface.h:126
struct refcnt * refcnt
Reference counter.
Definition: interface.h:124
signed long ssize_t
Definition: stdint.h:7
void * __attribute__((pure)) intf_object(struct interface *intf)
static void intf_init(struct interface *intf, struct interface_descriptor *desc, struct refcnt *refcnt)
Initialise an object interface.
Definition: interface.h:173
struct interface_descriptor * original
Original interface descriptor.
Definition: interface.h:131
static void intf_reinit(struct interface *intf)
Reinitialise an object interface.
Definition: interface.h:256