#ifndef _IPXE_INTERFACE_H
#define _IPXE_INTERFACE_H
/** @file
*
* Object interfaces
*
*/
FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
#include <stddef.h>
#include <stdarg.h>
#include <ipxe/refcnt.h>
/** An object interface operation */
struct interface_operation {
/** Operation type */
void *type;
/** Implementing method */
void *func;
};
/**
* Define an object interface operation
*
* @v op_type Operation type
* @v object_type Implementing method's expected object type
* @v op_func Implementing method
* @ret op Object interface operation
*/
#define INTF_OP( op_type, object_type, op_func ) { \
.type = op_type, \
.func = ( ( ( ( typeof ( op_func ) * ) NULL ) == \
( ( op_type ## _TYPE ( object_type ) * ) NULL ) ) \
? op_func : op_func ), \
}
/** An object interface descriptor */
struct interface_descriptor {
/** Offset of interface within containing object */
size_t offset;
/** Number of interface operations */
unsigned int num_op;
/** Object interface operations */
struct interface_operation *op;
/** Offset to pass-through interface, if present */
ssize_t passthru_offset;
};
#define intf_offset( object_type, intf ) \
( ( ( ( typeof ( ( ( object_type * ) NULL )->intf ) * ) NULL ) \
== ( ( struct interface * ) NULL ) ) \
? offsetof ( object_type, intf ) \
: offsetof ( object_type, intf ) )
/**
* Define an object interface descriptor
*
* @v object_type Containing object data type
* @v intf Interface name (i.e. field within object data type)
* @v operations Object interface operations array
* @ret desc Object interface descriptor
*/
#define INTF_DESC( object_type, intf, operations ) { \
.offset = intf_offset ( object_type, intf ), \
.op = operations, \
.num_op = ( sizeof ( operations ) / \
sizeof ( operations[0] ) ), \
.passthru_offset = 0, \
}
/**
* Define an object interface descriptor with pass-through interface
*
* @v object_type Containing object data type
* @v intf Interface name (i.e. field within object data type)
* @v operations Object interface operations array
* @v passthru Pass-through interface name
* @ret desc Object interface descriptor
*/
#define INTF_DESC_PASSTHRU( object_type, intf, operations, passthru ) { \
.offset = offsetof ( object_type, intf ), \
.op = operations, \
.num_op = ( sizeof ( operations ) / \
sizeof ( operations[0] ) ), \
.passthru_offset = ( intf_offset ( object_type, passthru ) - \
intf_offset ( object_type, intf ) ), \
}
/**
* Define an object interface descriptor for a pure-interface object
*
* @v operations Object interface operations array
* @ret desc Object interface descriptor
*
* A pure-interface object is an object that consists solely of a
* single interface.
*/
#define INTF_DESC_PURE( operations ) { \
.offset = 0, \
.op = operations, \
.num_op = ( sizeof ( operations ) / \
sizeof ( operations[0] ) ), \
.passthru_offset = 0, \
}
/** An object interface */
struct interface {
/** Destination object interface
*
* When the containing object invokes an operation on this
* interface, it will be executed by the destination object.
*
* This pointer may never be NULL. When the interface is
* unplugged, it should point to the null interface.
*/
struct interface *dest;
/** Reference counter
*
* If this interface is not part of a reference-counted
* object, this field may be NULL.
*/
struct refcnt *refcnt;
/** Interface descriptor */
struct interface_descriptor *desc;
/** Original interface descriptor
*
* Used by intf_reinit().
*/
struct interface_descriptor *original;
};
extern void intf_plug ( struct interface *intf, struct interface *dest );
extern void intf_plug_plug ( struct interface *a, struct interface *b );
extern void intf_unplug ( struct interface *intf );
extern void intf_nullify ( struct interface *intf );
extern struct interface * intf_get ( struct interface *intf );
extern void intf_put ( struct interface *intf );
extern void * __attribute__ (( pure )) intf_object ( struct interface *intf );
extern void * intf_get_dest_op_no_passthru_untyped ( struct interface *intf,
void *type,
struct interface **dest );
extern void * intf_get_dest_op_untyped ( struct interface *intf, void *type,
struct interface **dest );
extern void intf_close ( struct interface *intf, int rc );
#define intf_close_TYPE( object_type ) \
typeof ( void ( object_type, int rc ) )
extern void intf_shutdown ( struct interface *intf, int rc );
extern void intfs_vshutdown ( va_list intfs, int rc );
extern void intfs_shutdown ( int rc, ... ) __attribute__ (( sentinel ));
extern void intf_restart ( struct interface *intf, int rc );
extern void intfs_vrestart ( va_list intfs, int rc );
extern void intfs_restart ( int rc, ... ) __attribute__ (( sentinel ));
extern void intf_poke ( struct interface *intf,
void ( type ) ( struct interface *intf ) );
#define intf_poke_TYPE( object_type ) \
typeof ( void ( object_type ) )
extern struct interface_descriptor null_intf_desc;
extern struct interface null_intf;
/**
* Initialise an object interface
*
* @v intf Object interface
* @v desc Object interface descriptor
* @v refcnt Containing object reference counter, or NULL
*/
static inline void intf_init ( struct interface *intf,
struct interface_descriptor *desc,
struct refcnt *refcnt ) {
intf->dest = &null_intf;
intf->refcnt = refcnt;
intf->desc = desc;
intf->original = desc;
}
/**
* Initialise a static object interface
*
* @v descriptor Object interface descriptor
*/
#define INTF_INIT( descriptor ) { \
.dest = &null_intf, \
.refcnt = NULL, \
.desc = &(descriptor), \
.original = &(descriptor), \
}
/**
* Get object interface destination and operation method (without pass-through)
*
* @v intf Object interface
* @v type Operation type
* @ret dest Destination interface
* @ret func Implementing method, or NULL
*/
#define intf_get_dest_op_no_passthru( intf, type, dest ) \
( ( type ## _TYPE ( void * ) * ) \
intf_get_dest_op_no_passthru_untyped ( intf, type, dest ) )
/**
* Get object interface destination and operation method
*
* @v intf Object interface
* @v type Operation type
* @ret dest Destination interface
* @ret func Implementing method, or NULL
*/
#define intf_get_dest_op( intf, type, dest ) \
( ( type ## _TYPE ( void * ) * ) \
intf_get_dest_op_untyped ( intf, type, dest ) )
/**
* Find debugging colourisation for an object interface
*
* @v intf Object interface
* @ret col Debugging colourisation
*
* Use as the first argument to DBGC() or equivalent macro.
*/
#define INTF_COL( intf ) intf_object ( intf )
/** printf() format string for INTF_DBG() */
#define INTF_FMT "%p+%zx"
/**
* printf() arguments for representing an object interface
*
* @v intf Object interface
* @ret args printf() argument list corresponding to INTF_FMT
*/
#define INTF_DBG( intf ) intf_object ( intf ), (intf)->desc->offset
/** printf() format string for INTF_INTF_DBG() */
#define INTF_INTF_FMT INTF_FMT "->" INTF_FMT
/**
* printf() arguments for representing an object interface pair
*
* @v intf Object interface
* @v dest Destination object interface
* @ret args printf() argument list corresponding to INTF_INTF_FMT
*/
#define INTF_INTF_DBG( intf, dest ) INTF_DBG ( intf ), INTF_DBG ( dest )
/**
* Reinitialise an object interface
*
* @v intf Object interface
*/
static inline void intf_reinit ( struct interface *intf ) {
/* Restore original interface descriptor */
intf->desc = intf->original;
}
#endif /* _IPXE_INTERFACE_H */
