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_OR_UBDL );
  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 void intf_poke ( struct interface *intf,
 149                         void ( type ) ( struct interface *intf ) );
 150 #define intf_poke_TYPE( object_type ) \
 151         typeof ( void ( object_type ) )
 152
 153 extern struct interface_descriptor null_intf_desc;
 154 extern struct interface null_intf;
 155
 156 /**
 157  * Initialise an object interface
 158  *
 159  * @v intf              Object interface
 160  * @v desc              Object interface descriptor
 161  * @v refcnt            Containing object reference counter, or NULL
 162  */
 163 static inline void intf_init ( struct interface *intf,
 164                                struct interface_descriptor *desc,
 165                                struct refcnt *refcnt ) {
 166         intf->dest = &null_intf;
 167         intf->refcnt = refcnt;
 168         intf->desc = desc;
 169 }
 170
 171 /**
 172  * Initialise a static object interface
 173  *
 174  * @v descriptor        Object interface descriptor
 175  */
 176 #define INTF_INIT( descriptor ) {               \
 177                 .dest = &null_intf,             \
 178                 .refcnt = NULL,                 \
 179                 .desc = &(descriptor),          \
 180         }
 181
 182 /**
 183  * Get object interface destination and operation method (without pass-through)
 184  *
 185  * @v intf              Object interface
 186  * @v type              Operation type
 187  * @ret dest            Destination interface
 188  * @ret func            Implementing method, or NULL
 189  */
 190 #define intf_get_dest_op_no_passthru( intf, type, dest )                \
 191         ( ( type ## _TYPE ( void * ) * )                                \
 192           intf_get_dest_op_no_passthru_untyped ( intf, type, dest ) )
 193
 194 /**
 195  * Get object interface destination and operation method
 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( intf, type, dest )                            \
 203         ( ( type ## _TYPE ( void * ) * )                                \
 204           intf_get_dest_op_untyped ( intf, type, dest ) )
 205
 206 /**
 207  * Find debugging colourisation for an object interface
 208  *
 209  * @v intf              Object interface
 210  * @ret col             Debugging colourisation
 211  *
 212  * Use as the first argument to DBGC() or equivalent macro.
 213  */
 214 #define INTF_COL( intf ) intf_object ( intf )
 215
 216 /** printf() format string for INTF_DBG() */
 217 #define INTF_FMT "%p+%zx"
 218
 219 /**
 220  * printf() arguments for representing an object interface
 221  *
 222  * @v intf              Object interface
 223  * @ret args            printf() argument list corresponding to INTF_FMT
 224  */
 225 #define INTF_DBG( intf ) intf_object ( intf ), (intf)->desc->offset
 226
 227 /** printf() format string for INTF_INTF_DBG() */
 228 #define INTF_INTF_FMT INTF_FMT "->" INTF_FMT
 229
 230 /**
 231  * printf() arguments for representing an object interface pair
 232  *
 233  * @v intf              Object interface
 234  * @v dest              Destination object interface
 235  * @ret args            printf() argument list corresponding to INTF_INTF_FMT
 236  */
 237 #define INTF_INTF_DBG( intf, dest ) INTF_DBG ( intf ), INTF_DBG ( dest )
 238
 239 #endif /* _IPXE_INTERFACE_H */