qemu/roms/ipxe/src/include/ipxe/interface.h

   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 );
  11
  12 #include <stddef.h>
  13 #include <ipxe/refcnt.h>
  14
  15 /** An object interface operation */
  16 struct interface_operation {
  17         /** Operation type */
  18         void *type;
  19         /** Implementing method */
  20         void *func;
  21 };
  22
  23 /**
  24  * Define an object interface operation
  25  *
  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
  30  */
  31 #define INTF_OP( op_type, object_type, op_func ) {                            \
  32                 .type = op_type,                                              \
  33                 .func = ( ( ( ( typeof ( op_func ) * ) NULL ) ==              \
  34                             ( ( op_type ## _TYPE ( object_type ) * ) NULL ) ) \
  35                           ? op_func : op_func ),                              \
  36         }
  37
  38 /** An object interface descriptor */
  39 struct interface_descriptor {
  40         /** Offset of interface within containing object */
  41         size_t offset;
  42         /** Number of interface operations */
  43         unsigned int num_op;
  44         /** Object interface operations */
  45         struct interface_operation *op;
  46         /** Offset to pass-through interface, if present */
  47         ssize_t passthru_offset;
  48 };
  49
  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 ) )
  55
  56 /**
  57  * Define an object interface descriptor
  58  *
  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
  63  */
  64 #define INTF_DESC( object_type, intf, operations ) {                          \
  65                 .offset = intf_offset ( object_type, intf ),                  \
  66                 .op = operations,                                             \
  67                 .num_op = ( sizeof ( operations ) /                           \
  68                             sizeof ( operations[0] ) ),                       \
  69                 .passthru_offset = 0,                                         \
  70         }
  71
  72 /**
  73  * Define an object interface descriptor with pass-through interface
  74  *
  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
  80  */
  81 #define INTF_DESC_PASSTHRU( object_type, intf, operations, passthru ) {       \
  82                 .offset = offsetof ( object_type, intf ),                     \
  83                 .op = operations,                                             \
  84                 .num_op = ( sizeof ( operations ) /                           \
  85                             sizeof ( operations[0] ) ),                       \
  86                 .passthru_offset = ( intf_offset ( object_type, passthru ) -  \
  87                                      intf_offset ( object_type, intf ) ),     \
  88         }
  89
  90 /**
  91  * Define an object interface descriptor for a pure-interface object
  92  *
  93  * @v operations        Object interface operations array
  94  * @ret desc            Object interface descriptor
  95  *
  96  * A pure-interface object is an object that consists solely of a
  97  * single interface.
  98  */
  99 #define INTF_DESC_PURE( operations ) {                                        \
 100                 .offset = 0,                                                  \
 101                 .op = operations,                                             \
 102                 .num_op = ( sizeof ( operations ) /                           \
 103                             sizeof ( operations[0] ) ),                       \
 104                 .passthru_offset = 0,                                         \
 105         }
 106
 107 /** An object interface */
 108 struct interface {
 109         /** Destination object interface
 110          *
 111          * When the containing object invokes an operation on this
 112          * interface, it will be executed by the destination object.
 113          *
 114          * This pointer may never be NULL.  When the interface is
 115          * unplugged, it should point to the null interface.
 116          */
 117         struct interface *dest;
 118         /** Reference counter
 119          *
 120          * If this interface is not part of a reference-counted
 121          * object, this field may be NULL.
 122          */
 123         struct refcnt *refcnt;
 124         /** Interface descriptor */
 125         struct interface_descriptor *desc;
 126 };
 127
 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,
 136                                                      void *type,
 137                                                      struct interface **dest );
 138 extern void * intf_get_dest_op_untyped ( struct interface *intf, void *type,
 139                                          struct interface **dest );
 140
 141 extern void intf_close ( struct interface *intf, int rc );
 142 #define intf_close_TYPE( object_type ) \
 143         typeof ( void ( object_type, int rc ) )
 144
 145 extern void intf_shutdown ( struct interface *intf, int rc );
 146 extern void intf_restart ( struct interface *intf, int rc );
 147
 148 extern struct interface_descriptor null_intf_desc;
 149 extern struct interface null_intf;
 150
 151 /**
 152  * Initialise an object interface
 153  *
 154  * @v intf              Object interface
 155  * @v desc              Object interface descriptor
 156  * @v refcnt            Containing object reference counter, or NULL
 157  */
 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;
 163         intf->desc = desc;
 164 }
 165
 166 /**
 167  * Initialise a static object interface
 168  *
 169  * @v descriptor        Object interface descriptor
 170  */
 171 #define INTF_INIT( descriptor ) {               \
 172                 .dest = &null_intf,             \
 173                 .refcnt = NULL,                 \
 174                 .desc = &(descriptor),          \
 175         }
 176
 177 /**
 178  * Get object interface destination and operation method (without pass-through)
 179  *
 180  * @v intf              Object interface
 181  * @v type              Operation type
 182  * @ret dest            Destination interface
 183  * @ret func            Implementing method, or NULL
 184  */
 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 ) )
 188
 189 /**
 190  * Get object interface destination and operation method
 191  *
 192  * @v intf              Object interface
 193  * @v type              Operation type
 194  * @ret dest            Destination interface
 195  * @ret func            Implementing method, or NULL
 196  */
 197 #define intf_get_dest_op( intf, type, dest )                            \
 198         ( ( type ## _TYPE ( void * ) * )                                \
 199           intf_get_dest_op_untyped ( intf, type, dest ) )
 200
 201 /**
 202  * Find debugging colourisation for an object interface
 203  *
 204  * @v intf              Object interface
 205  * @ret col             Debugging colourisation
 206  *
 207  * Use as the first argument to DBGC() or equivalent macro.
 208  */
 209 #define INTF_COL( intf ) intf_object ( intf )
 210
 211 /** printf() format string for INTF_DBG() */
 212 #define INTF_FMT "%p+%zx"
 213
 214 /**
 215  * printf() arguments for representing an object interface
 216  *
 217  * @v intf              Object interface
 218  * @ret args            printf() argument list corresponding to INTF_FMT
 219  */
 220 #define INTF_DBG( intf ) intf_object ( intf ), (intf)->desc->offset
 221
 222 /** printf() format string for INTF_INTF_DBG() */
 223 #define INTF_INTF_FMT INTF_FMT "->" INTF_FMT
 224
 225 /**
 226  * printf() arguments for representing an object interface pair
 227  *
 228  * @v intf              Object interface
 229  * @v dest              Destination object interface
 230  * @ret args            printf() argument list corresponding to INTF_INTF_FMT
 231  */
 232 #define INTF_INTF_DBG( intf, dest ) INTF_DBG ( intf ), INTF_DBG ( dest )
 233
 234 #endif /* _IPXE_INTERFACE_H */