aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--src/core/interface.c236
-rw-r--r--src/include/ipxe/interface.h203
-rw-r--r--src/include/ipxe/job.h6
-rw-r--r--src/include/ipxe/resolv.h6
-rw-r--r--src/include/ipxe/xfer.h6
5 files changed, 413 insertions, 44 deletions
diff --git a/src/core/interface.c b/src/core/interface.c
index d1583a8a9..f0c0ae643 100644
--- a/src/core/interface.c
+++ b/src/core/interface.c
@@ -18,19 +18,42 @@
FILE_LICENCE ( GPL2_OR_LATER );
+#include <string.h>
#include <ipxe/interface.h>
/** @file
*
- * Object communication interfaces
+ * Object interfaces
+ *
+ */
+
+/*****************************************************************************
+ *
+ * The null interface
+ *
+ */
+
+/** Null interface operations */
+static struct interface_operation null_intf_op[] = {};
+
+/** Null interface descriptor */
+struct interface_descriptor null_intf_desc =
+ INTF_DESC_PURE ( null_intf_op );
+
+/** The null interface */
+struct interface null_intf = INTF_INIT ( null_intf_desc );
+
+/*****************************************************************************
+ *
+ * Object interface plumbing
*
*/
/**
- * Plug an interface into a new destination interface
+ * Plug an object interface into a new destination object interface
*
- * @v intf Interface
- * @v dest New destination interface
+ * @v intf Object interface
+ * @v dest New destination object interface
*
* The reference to the existing destination interface is dropped, a
* reference to the new destination interface is obtained, and the
@@ -39,24 +62,209 @@ FILE_LICENCE ( GPL2_OR_LATER );
* Note that there is no "unplug" call; instead you must plug the
* interface into a null interface.
*/
-void plug ( struct interface *intf, struct interface *dest ) {
- DBGC ( intf, "INTF %p moving from INTF %p to INTF %p\n",
- intf, intf->dest, dest );
+void intf_plug ( struct interface *intf, struct interface *dest ) {
+ DBGC ( INTF_COL ( intf ),
+ "INTF " INTF_INTF_FMT " replug to " INTF_FMT "\n",
+ INTF_INTF_DBG ( intf, intf->dest ), INTF_DBG ( dest ) );
+ intf_get ( dest );
intf_put ( intf->dest );
- intf->dest = intf_get ( dest );
+ intf->dest = dest;
}
/**
- * Plug two interfaces together
+ * Plug two object interfaces together
*
- * @v a Interface A
- * @v b Interface B
+ * @v a Object interface A
+ * @v b Object interface B
*
* Plugs interface A into interface B, and interface B into interface
* A. (The basic plug() function is unidirectional; this function is
* merely a shorthand for two calls to plug(), hence the name.)
*/
-void plug_plug ( struct interface *a, struct interface *b ) {
- plug ( a, b );
- plug ( b, a );
+void intf_plug_plug ( struct interface *a, struct interface *b ) {
+ intf_plug ( a, b );
+ intf_plug ( b, a );
+}
+
+/**
+ * Unplug an object interface
+ *
+ * @v intf Object interface
+ */
+void intf_unplug ( struct interface *intf ) {
+ intf_plug ( intf, &null_intf );
+}
+
+/**
+ * Ignore all further operations on an object interface
+ *
+ * @v intf Object interface
+ */
+void intf_nullify ( struct interface *intf ) {
+ intf->desc = &null_intf_desc;
+}
+
+/**
+ * Increment reference count on an object interface
+ *
+ * @v intf Object interface
+ * @ret intf Object interface
+ */
+struct interface * intf_get ( struct interface *intf ) {
+ ref_get ( intf->refcnt );
+ return intf;
+}
+
+/**
+ * Decrement reference count on an object interface
+ *
+ * @v intf Object interface
+ */
+void intf_put ( struct interface *intf ) {
+ ref_put ( intf->refcnt );
+}
+
+/**
+ * Get pointer to object containing object interface
+ *
+ * @v intf Object interface
+ * @ret object Containing object
+ */
+void * intf_object ( struct interface *intf ) {
+ return ( ( ( void * ) intf ) - intf->desc->offset );
+}
+
+/**
+ * Get pass-through interface
+ *
+ * @v intf Object interface
+ * @ret passthru Pass-through interface, or NULL
+ */
+static struct interface * intf_get_passthru ( struct interface *intf ) {
+ struct interface_descriptor *desc = intf->desc;
+
+ if ( desc->passthru_offset ) {
+ return ( ( ( void * ) intf ) + desc->passthru_offset );
+ } else {
+ return NULL;
+ }
+}
+
+/**
+ * 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
+ */
+void * intf_get_dest_op_untyped ( struct interface *intf, void *type,
+ struct interface **dest ) {
+ struct interface_descriptor *desc;
+ struct interface_operation *op;
+ unsigned int i;
+
+ while ( 1 ) {
+ /* Search for an implementing method provided by the
+ * current destination interface.
+ */
+ *dest = intf_get ( intf->dest );
+ desc = (*dest)->desc;
+ for ( i = desc->num_op, op = desc->op ; i ; i--, op++ ) {
+ if ( op->type == type )
+ return op->func;
+ }
+
+ /* Pass through to the underlying interface, if applicable */
+ if ( ! ( intf = intf_get_passthru ( *dest ) ) )
+ return NULL;
+ intf_put ( *dest );
+ }
+}
+
+/*****************************************************************************
+ *
+ * Generic interface operations
+ *
+ */
+
+/**
+ * Close an object interface
+ *
+ * @v intf Object interface
+ * @v rc Reason for close
+ *
+ * Note that this function merely informs the destination object that
+ * the interface is about to be closed; it doesn't actually disconnect
+ * the interface. In most cases, you probably want to use
+ * intf_shutdown() or intf_restart() instead.
+ */
+void intf_close ( struct interface *intf, int rc ) {
+ struct interface *dest;
+ intf_close_TYPE ( void * ) *op =
+ intf_get_dest_op ( intf, intf_close, &dest );
+ void *object = intf_object ( dest );
+
+ DBGC ( INTF_COL ( intf ), "INTF " INTF_INTF_FMT " close (%s)\n",
+ INTF_INTF_DBG ( intf, dest ), strerror ( rc ) );
+
+ if ( op ) {
+ op ( object, rc );
+ } else {
+ /* Default is to ignore intf_close() */
+ }
+
+ intf_put ( dest );
+}
+
+/**
+ * Shut down an object interface
+ *
+ * @v intf Object interface
+ * @v rc Reason for close
+ *
+ * Blocks further operations from being received via the interface,
+ * executes a close operation on the destination interface, and
+ * unplugs the interface.
+ */
+void intf_shutdown ( struct interface *intf, int rc ) {
+
+ DBGC ( INTF_COL ( intf ), "INTF " INTF_FMT " shutting down (%s)\n",
+ INTF_DBG ( intf ), strerror ( rc ) );
+
+ /* Block further operations */
+ intf_nullify ( intf );
+
+ /* Notify destination of close */
+ intf_close ( intf, rc );
+
+ /* Unplug interface */
+ intf_unplug ( intf );
+}
+
+/**
+ * Shut down and restart an object interface
+ *
+ * @v intf Object interface
+ * @v rc Reason for close
+ *
+ * Shuts down the interface, then unblocks operations that were
+ * blocked during shutdown.
+ */
+void intf_restart ( struct interface *intf, int rc ) {
+ struct interface_descriptor *desc = intf->desc;
+
+ /* Shut down the interface */
+ intf_shutdown ( intf, rc );
+
+ DBGC ( INTF_COL ( intf ), "INTF " INTF_FMT " restarting\n",
+ INTF_DBG ( intf ) );
+
+ /* Restore the interface descriptor. Must be done after
+ * shutdown (rather than inhibiting intf_shutdown() from
+ * nullifying the descriptor) in order to avoid a potential
+ * infinite loop as the intf_close() operations on each side
+ * of the link call each other recursively.
+ */
+ intf->desc = desc;
}
diff --git a/src/include/ipxe/interface.h b/src/include/ipxe/interface.h
index 41041054c..49add3306 100644
--- a/src/include/ipxe/interface.h
+++ b/src/include/ipxe/interface.h
@@ -3,23 +3,116 @@
/** @file
*
- * Object communication interfaces
+ * Object interfaces
*
*/
FILE_LICENCE ( GPL2_OR_LATER );
+#include <stddef.h>
#include <ipxe/refcnt.h>
-/** An object communication interface */
+/** 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 interface
+ /** Destination object interface
*
- * When messages are sent via this interface, they will be
- * delivered to the destination 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 a null interface.
+ * unplugged, it should point to the null interface.
*/
struct interface *dest;
/** Reference counter
@@ -28,31 +121,99 @@ struct interface {
* object, this field may be NULL.
*/
struct refcnt *refcnt;
+ /** Interface descriptor */
+ struct interface_descriptor *desc;
};
+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_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 intf_restart ( struct interface *intf, int rc );
+
+extern struct interface_descriptor null_intf_desc;
+extern struct interface null_intf;
+
/**
- * Increment reference count on an interface
+ * Initialise an object interface
*
- * @v intf Interface
- * @ret intf Interface
+ * @v intf Object interface
+ * @v desc Object interface descriptor
+ * @v refcnt Containing object reference counter, or NULL
*/
-static inline __attribute__ (( always_inline )) struct interface *
-intf_get ( struct interface *intf ) {
- ref_get ( intf->refcnt );
- return intf;
+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;
}
/**
- * Decrement reference count on an interface
+ * Initialise a static object interface
*
- * @v intf Interface
+ * @v descriptor Object interface descriptor
*/
-static inline __attribute__ (( always_inline )) void
-intf_put ( struct interface *intf ) {
- ref_put ( intf->refcnt );
-}
+#define INTF_INIT( descriptor ) { \
+ .dest = &null_intf, \
+ .refcnt = NULL, \
+ .desc = &(descriptor), \
+ }
+
+/**
+ * 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"
-extern void plug ( struct interface *intf, struct interface *dest );
-extern void plug_plug ( struct interface *a, struct interface *b );
+/**
+ * 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 )
#endif /* _IPXE_INTERFACE_H */
diff --git a/src/include/ipxe/job.h b/src/include/ipxe/job.h
index 893a7901b..870b2e83d 100644
--- a/src/include/ipxe/job.h
+++ b/src/include/ipxe/job.h
@@ -131,7 +131,7 @@ job_put ( struct job_interface *job ) {
*/
static inline void job_plug ( struct job_interface *job,
struct job_interface *dest ) {
- plug ( &job->intf, &dest->intf );
+ intf_plug ( &job->intf, &dest->intf );
}
/**
@@ -142,7 +142,7 @@ static inline void job_plug ( struct job_interface *job,
*/
static inline void job_plug_plug ( struct job_interface *a,
struct job_interface *b ) {
- plug_plug ( &a->intf, &b->intf );
+ intf_plug_plug ( &a->intf, &b->intf );
}
/**
@@ -151,7 +151,7 @@ static inline void job_plug_plug ( struct job_interface *a,
* @v job Job control interface
*/
static inline void job_unplug ( struct job_interface *job ) {
- plug ( &job->intf, &null_job.intf );
+ intf_plug ( &job->intf, &null_job.intf );
}
/**
diff --git a/src/include/ipxe/resolv.h b/src/include/ipxe/resolv.h
index c7d61998a..767614bd2 100644
--- a/src/include/ipxe/resolv.h
+++ b/src/include/ipxe/resolv.h
@@ -94,7 +94,7 @@ resolv_put ( struct resolv_interface *resolv ) {
*/
static inline __attribute__ (( always_inline )) void
resolv_plug ( struct resolv_interface *resolv, struct resolv_interface *dest ) {
- plug ( &resolv->intf, &dest->intf );
+ intf_plug ( &resolv->intf, &dest->intf );
}
/**
@@ -105,7 +105,7 @@ resolv_plug ( struct resolv_interface *resolv, struct resolv_interface *dest ) {
*/
static inline __attribute__ (( always_inline )) void
resolv_plug_plug ( struct resolv_interface *a, struct resolv_interface *b ) {
- plug_plug ( &a->intf, &b->intf );
+ intf_plug_plug ( &a->intf, &b->intf );
}
/**
@@ -115,7 +115,7 @@ resolv_plug_plug ( struct resolv_interface *a, struct resolv_interface *b ) {
*/
static inline __attribute__ (( always_inline )) void
resolv_unplug ( struct resolv_interface *resolv ) {
- plug ( &resolv->intf, &null_resolv.intf );
+ intf_plug ( &resolv->intf, &null_resolv.intf );
}
/**
diff --git a/src/include/ipxe/xfer.h b/src/include/ipxe/xfer.h
index ad41e932c..8a3f9bb1c 100644
--- a/src/include/ipxe/xfer.h
+++ b/src/include/ipxe/xfer.h
@@ -238,7 +238,7 @@ xfer_put ( struct xfer_interface *xfer ) {
*/
static inline __attribute__ (( always_inline )) void
xfer_plug ( struct xfer_interface *xfer, struct xfer_interface *dest ) {
- plug ( &xfer->intf, &dest->intf );
+ intf_plug ( &xfer->intf, &dest->intf );
}
/**
@@ -249,7 +249,7 @@ xfer_plug ( struct xfer_interface *xfer, struct xfer_interface *dest ) {
*/
static inline __attribute__ (( always_inline )) void
xfer_plug_plug ( struct xfer_interface *a, struct xfer_interface *b ) {
- plug_plug ( &a->intf, &b->intf );
+ intf_plug_plug ( &a->intf, &b->intf );
}
/**
@@ -259,7 +259,7 @@ xfer_plug_plug ( struct xfer_interface *a, struct xfer_interface *b ) {
*/
static inline __attribute__ (( always_inline )) void
xfer_unplug ( struct xfer_interface *xfer ) {
- plug ( &xfer->intf, &null_xfer.intf );
+ intf_plug ( &xfer->intf, &null_xfer.intf );
}
/**
generated by cgit (git 2.34.1) at 2025-02-24 14:08:34 +0000