iPXE
interface.h
Go to the documentation of this file.
00001 #ifndef _IPXE_INTERFACE_H
00002 #define _IPXE_INTERFACE_H
00003 
00004 /** @file
00005  *
00006  * Object interfaces
00007  *
00008  */
00009 
00010 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
00011 
00012 #include <stddef.h>
00013 #include <stdarg.h>
00014 #include <ipxe/refcnt.h>
00015 
00016 /** An object interface operation */
00017 struct interface_operation {
00018         /** Operation type */
00019         void *type;
00020         /** Implementing method */
00021         void *func;
00022 };
00023 
00024 /**
00025  * Define an object interface operation
00026  *
00027  * @v op_type           Operation type
00028  * @v object_type       Implementing method's expected object type
00029  * @v op_func           Implementing method
00030  * @ret op              Object interface operation
00031  */
00032 #define INTF_OP( op_type, object_type, op_func ) {                            \
00033                 .type = op_type,                                              \
00034                 .func = ( ( ( ( typeof ( op_func ) * ) NULL ) ==              \
00035                             ( ( op_type ## _TYPE ( object_type ) * ) NULL ) ) \
00036                           ? op_func : op_func ),                              \
00037         }
00038 
00039 /** An object interface descriptor */
00040 struct interface_descriptor {
00041         /** Offset of interface within containing object */
00042         size_t offset;
00043         /** Number of interface operations */
00044         unsigned int num_op;
00045         /** Object interface operations */
00046         struct interface_operation *op;
00047         /** Offset to pass-through interface, if present */
00048         ssize_t passthru_offset;
00049 };
00050 
00051 #define intf_offset( object_type, intf )                                      \
00052         ( ( ( ( typeof ( ( ( object_type * ) NULL )->intf ) * ) NULL )        \
00053             == ( ( struct interface * ) NULL ) )                              \
00054           ? offsetof ( object_type, intf )                                    \
00055           : offsetof ( object_type, intf ) )
00056 
00057 /**
00058  * Define an object interface descriptor
00059  *
00060  * @v object_type       Containing object data type
00061  * @v intf              Interface name (i.e. field within object data type)
00062  * @v operations        Object interface operations array
00063  * @ret desc            Object interface descriptor
00064  */
00065 #define INTF_DESC( object_type, intf, operations ) {                          \
00066                 .offset = intf_offset ( object_type, intf ),                  \
00067                 .op = operations,                                             \
00068                 .num_op = ( sizeof ( operations ) /                           \
00069                             sizeof ( operations[0] ) ),                       \
00070                 .passthru_offset = 0,                                         \
00071         }
00072 
00073 /**
00074  * Define an object interface descriptor with pass-through interface
00075  *
00076  * @v object_type       Containing object data type
00077  * @v intf              Interface name (i.e. field within object data type)
00078  * @v operations        Object interface operations array
00079  * @v passthru          Pass-through interface name
00080  * @ret desc            Object interface descriptor
00081  */
00082 #define INTF_DESC_PASSTHRU( object_type, intf, operations, passthru ) {       \
00083                 .offset = offsetof ( object_type, intf ),                     \
00084                 .op = operations,                                             \
00085                 .num_op = ( sizeof ( operations ) /                           \
00086                             sizeof ( operations[0] ) ),                       \
00087                 .passthru_offset = ( intf_offset ( object_type, passthru ) -  \
00088                                      intf_offset ( object_type, intf ) ),     \
00089         }
00090 
00091 /**
00092  * Define an object interface descriptor for a pure-interface object
00093  *
00094  * @v operations        Object interface operations array
00095  * @ret desc            Object interface descriptor
00096  *
00097  * A pure-interface object is an object that consists solely of a
00098  * single interface.
00099  */
00100 #define INTF_DESC_PURE( operations ) {                                        \
00101                 .offset = 0,                                                  \
00102                 .op = operations,                                             \
00103                 .num_op = ( sizeof ( operations ) /                           \
00104                             sizeof ( operations[0] ) ),                       \
00105                 .passthru_offset = 0,                                         \
00106         }
00107 
00108 /** An object interface */
00109 struct interface {
00110         /** Destination object interface
00111          *
00112          * When the containing object invokes an operation on this
00113          * interface, it will be executed by the destination object.
00114          *
00115          * This pointer may never be NULL.  When the interface is
00116          * unplugged, it should point to the null interface.
00117          */
00118         struct interface *dest;
00119         /** Reference counter
00120          *
00121          * If this interface is not part of a reference-counted
00122          * object, this field may be NULL.
00123          */
00124         struct refcnt *refcnt;
00125         /** Interface descriptor */
00126         struct interface_descriptor *desc;
00127         /** Original interface descriptor
00128          *
00129          * Used by intf_reinit().
00130          */
00131         struct interface_descriptor *original;
00132 };
00133 
00134 extern void intf_plug ( struct interface *intf, struct interface *dest );
00135 extern void intf_plug_plug ( struct interface *a, struct interface *b );
00136 extern void intf_unplug ( struct interface *intf );
00137 extern void intf_nullify ( struct interface *intf );
00138 extern struct interface * intf_get ( struct interface *intf );
00139 extern void intf_put ( struct interface *intf );
00140 extern void * __attribute__ (( pure )) intf_object ( struct interface *intf );
00141 extern void * intf_get_dest_op_no_passthru_untyped ( struct interface *intf,
00142                                                      void *type,
00143                                                      struct interface **dest );
00144 extern void * intf_get_dest_op_untyped ( struct interface *intf, void *type,
00145                                          struct interface **dest );
00146 
00147 extern void intf_close ( struct interface *intf, int rc );
00148 #define intf_close_TYPE( object_type ) \
00149         typeof ( void ( object_type, int rc ) )
00150 
00151 extern void intf_shutdown ( struct interface *intf, int rc );
00152 extern void intfs_vshutdown ( va_list intfs, int rc );
00153 extern void intfs_shutdown ( int rc, ... ) __attribute__ (( sentinel ));
00154 extern void intf_restart ( struct interface *intf, int rc );
00155 extern void intfs_vrestart ( va_list intfs, int rc );
00156 extern void intfs_restart ( int rc, ... ) __attribute__ (( sentinel ));
00157 
00158 extern void intf_poke ( struct interface *intf,
00159                         void ( type ) ( struct interface *intf ) );
00160 #define intf_poke_TYPE( object_type ) \
00161         typeof ( void ( object_type ) )
00162 
00163 extern struct interface_descriptor null_intf_desc;
00164 extern struct interface null_intf;
00165 
00166 /**
00167  * Initialise an object interface
00168  *
00169  * @v intf              Object interface
00170  * @v desc              Object interface descriptor
00171  * @v refcnt            Containing object reference counter, or NULL
00172  */
00173 static inline void intf_init ( struct interface *intf,
00174                                struct interface_descriptor *desc,
00175                                struct refcnt *refcnt ) {
00176         intf->dest = &null_intf;
00177         intf->refcnt = refcnt;
00178         intf->desc = desc;
00179         intf->original = desc;
00180 }
00181 
00182 /**
00183  * Initialise a static object interface
00184  *
00185  * @v descriptor        Object interface descriptor
00186  */
00187 #define INTF_INIT( descriptor ) {               \
00188                 .dest = &null_intf,             \
00189                 .refcnt = NULL,                 \
00190                 .desc = &(descriptor),          \
00191                 .original = &(descriptor),      \
00192         }
00193 
00194 /**
00195  * Get object interface destination and operation method (without pass-through)
00196  *
00197  * @v intf              Object interface
00198  * @v type              Operation type
00199  * @ret dest            Destination interface
00200  * @ret func            Implementing method, or NULL
00201  */
00202 #define intf_get_dest_op_no_passthru( intf, type, dest )                \
00203         ( ( type ## _TYPE ( void * ) * )                                \
00204           intf_get_dest_op_no_passthru_untyped ( intf, type, dest ) )
00205 
00206 /**
00207  * Get object interface destination and operation method
00208  *
00209  * @v intf              Object interface
00210  * @v type              Operation type
00211  * @ret dest            Destination interface
00212  * @ret func            Implementing method, or NULL
00213  */
00214 #define intf_get_dest_op( intf, type, dest )                            \
00215         ( ( type ## _TYPE ( void * ) * )                                \
00216           intf_get_dest_op_untyped ( intf, type, dest ) )
00217 
00218 /**
00219  * Find debugging colourisation for an object interface
00220  *
00221  * @v intf              Object interface
00222  * @ret col             Debugging colourisation
00223  *
00224  * Use as the first argument to DBGC() or equivalent macro.
00225  */
00226 #define INTF_COL( intf ) intf_object ( intf )
00227 
00228 /** printf() format string for INTF_DBG() */
00229 #define INTF_FMT "%p+%zx"
00230 
00231 /**
00232  * printf() arguments for representing an object interface
00233  *
00234  * @v intf              Object interface
00235  * @ret args            printf() argument list corresponding to INTF_FMT
00236  */
00237 #define INTF_DBG( intf ) intf_object ( intf ), (intf)->desc->offset
00238 
00239 /** printf() format string for INTF_INTF_DBG() */
00240 #define INTF_INTF_FMT INTF_FMT "->" INTF_FMT
00241 
00242 /**
00243  * printf() arguments for representing an object interface pair
00244  *
00245  * @v intf              Object interface
00246  * @v dest              Destination object interface
00247  * @ret args            printf() argument list corresponding to INTF_INTF_FMT
00248  */
00249 #define INTF_INTF_DBG( intf, dest ) INTF_DBG ( intf ), INTF_DBG ( dest )
00250 
00251 /**
00252  * Reinitialise an object interface
00253  *
00254  * @v intf              Object interface
00255  */
00256 static inline void intf_reinit ( struct interface *intf ) {
00257 
00258         /* Restore original interface descriptor */
00259         intf->desc = intf->original;
00260 }
00261 
00262 #endif /* _IPXE_INTERFACE_H */