src/core/interface.c - ipxe - Git at Google

 /*
  * Copyright (C) 2007 Michael Brown <mbrown@fensystems.co.uk>.
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License as
  * published by the Free Software Foundation; either version 2 of the
  * License, or any later version.
  *
  * This program is distributed in the hope that it will be useful, but
  * WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * General Public License for more details.
  *
  * You should have received a copy of the GNU General Public License
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  * 02110-1301, USA.
  *
  * You can also choose to distribute this program under the terms of
  * the Unmodified Binary Distribution Licence (as given in the file
  * COPYING.UBDL), provided that you have satisfied its requirements.
  */

 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );

 #include <string.h>
 #include <ipxe/interface.h>

 /** @file
  *
  * Object interfaces
  *
  */

 /*****************************************************************************
  *
  * The null interface
  *
  */

 /**
  * Close null interface
  *
  * @v intf		Null interface
  * @v rc		Reason for close
  */
 static void null_intf_close ( struct interface *intf __unused,
 			      int rc __unused ) {

 	/* Do nothing.  In particular, do not call intf_restart(),
 	 * since that would result in an infinite loop.
 	 */
 }

 /** Null interface operations */
 static struct interface_operation null_intf_op[] = {
 	INTF_OP ( intf_close, struct interface *, null_intf_close ),
 };

 /** 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 object interface into a new destination object 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
  * interface is updated to point to the new destination interface.
  */
 void intf_plug ( struct interface *intf, struct interface *dest ) {

 	if ( intf == &null_intf )
 		return;

 	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 = dest;
 }

 /**
  * Plug two object interfaces together
  *
  * @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 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 ) {
 	DBGC ( INTF_COL ( intf ), "INTF " INTF_INTF_FMT " unplug\n",
 	       INTF_INTF_DBG ( intf, intf->dest ) );
 	intf_put ( intf->dest );
 	intf->dest = &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 (without pass-through)
  *
  * @v intf		Object interface
  * @v type		Operation type
  * @ret dest		Destination interface
  * @ret func		Implementing method, or NULL
  */
 void * intf_get_dest_op_no_passthru_untyped ( struct interface *intf,
 					      void *type,
 					      struct interface **dest ) {
 	struct interface_descriptor *desc;
 	struct interface_operation *op;
 	unsigned int i;

 	*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;
 	}

 	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 ) {
 	void *func;

 	while ( 1 ) {

 		/* Search for an implementing method provided by the
 		 * current destination interface.
 		 */
 		func = intf_get_dest_op_no_passthru_untyped( intf, type, dest );
 		if ( func )
 			return 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 restart the interface */
 		intf_restart ( dest, rc );
 	}

 	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 ) {
 	struct interface tmp;

 	DBGC ( INTF_COL ( intf ), "INTF " INTF_FMT " shutting down (%s)\n",
 	       INTF_DBG ( intf ), strerror ( rc ) );

 	/* Block further operations */
 	intf_nullify ( intf );

 	/* Transfer destination to temporary interface */
 	intf_temp_init ( &tmp, intf );
 	tmp.dest = intf->dest;
 	intf->dest = &null_intf;

 	/* Notify destination of close via temporary interface */
 	intf_close ( &tmp, rc );

 	/* Unplug temporary interface */
 	intf_unplug ( &tmp );
 }

 /**
  * Shut down multiple object interfaces
  *
  * @v intfs		Object interfaces
  * @v rc		Reason for close
  */
 void intfs_vshutdown ( va_list intfs, int rc ) {
 	struct interface *intf;
 	va_list tmp;

 	/* Nullify all interfaces to avoid potential loops */
 	va_copy ( tmp, intfs );
 	while ( ( intf = va_arg ( tmp, struct interface * ) ) )
 		intf_nullify ( intf );
 	va_end ( tmp );

 	/* Shut down all interfaces */
 	while ( ( intf = va_arg ( intfs, struct interface * ) ) )
 		intf_shutdown ( intf, rc );
 }

 /**
  * Shut down multiple object interfaces
  *
  * @v rc		Reason for close
  * @v ...		Object interfaces
  */
 void intfs_shutdown ( int rc, ... ) {
 	va_list intfs;

 	va_start ( intfs, rc );
 	intfs_vshutdown ( intfs, rc );
 	va_end ( intfs );
 }

 /**
  * 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 ) {

 	/* 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_reinit ( intf );
 }

 /**
  * Shut down and restart multiple object interfaces
  *
  * @v intfs		Object interfaces
  * @v rc		Reason for close
  */
 void intfs_vrestart ( va_list intfs, int rc ) {
 	struct interface *intf;
 	va_list tmp;

 	/* Shut down all interfaces */
 	va_copy ( tmp, intfs );
 	intfs_vshutdown ( tmp, rc );
 	va_end ( tmp );

 	/* Reinitialise all interfaces */
 	while ( ( intf = va_arg ( intfs, struct interface * ) ) )
 		intf_reinit ( intf );
 }

 /**
  * Shut down and restart multiple object interfaces
  *
  * @v rc		Reason for close
  * @v ...		Object interfaces
  */
 void intfs_restart ( int rc, ... ) {
 	va_list intfs;

 	va_start ( intfs, rc );
 	intfs_vrestart ( intfs, rc );
 	va_end ( intfs );
 }

 /**
  * Insert a filter interface
  *
  * @v intf		Object interface
  * @v upper		Upper end of filter
  * @v lower		Lower end of filter
  */
 void intf_insert ( struct interface *intf, struct interface *upper,
 		   struct interface *lower ) {
 	struct interface *dest = intf->dest;

 	intf_get ( dest );
 	intf_plug_plug ( intf, upper );
 	intf_plug_plug ( lower, dest );
 	intf_put ( dest );
 }

 /**
  * Poke an object interface
  *
  * @v intf		Object interface
  * @v type		Operation type
  *
  * This is a helper function to implement methods which take no
  * parameters and return nothing.
  */
 void intf_poke ( struct interface *intf,
 		 void ( type ) ( struct interface *intf ) ) {
 	struct interface *dest;
 	intf_poke_TYPE ( void * ) *op =
 		intf_get_dest_op_untyped ( intf, type, &dest );
 	void *object = intf_object ( dest );

 	if ( op ) {
 		op ( object );
 	} else {
 		/* Default is to do nothing */
 	}

 	intf_put ( dest );
 }
	/*
	* Copyright (C) 2007 Michael Brown <mbrown@fensystems.co.uk>.
	*
	* This program is free software; you can redistribute it and/or
	* modify it under the terms of the GNU General Public License as
	* published by the Free Software Foundation; either version 2 of the
	* License, or any later version.
	*
	* This program is distributed in the hope that it will be useful, but
	* WITHOUT ANY WARRANTY; without even the implied warranty of
	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	* General Public License for more details.
	*
	* You should have received a copy of the GNU General Public License
	* along with this program; if not, write to the Free Software
	* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
	* 02110-1301, USA.
	*
	* You can also choose to distribute this program under the terms of
	* the Unmodified Binary Distribution Licence (as given in the file
	* COPYING.UBDL), provided that you have satisfied its requirements.
	*/

	FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );

	#include <string.h>
	#include <ipxe/interface.h>

	/** @file
	*
	* Object interfaces
	*
	*/

	/*****************************************************************************
	*
	* The null interface
	*
	*/

	/**
	* Close null interface
	*
	* @v intf Null interface
	* @v rc Reason for close
	*/
	static void null_intf_close ( struct interface *intf __unused,
	int rc __unused ) {

	/* Do nothing. In particular, do not call intf_restart(),
	* since that would result in an infinite loop.
	*/
	}

	/** Null interface operations */
	static struct interface_operation null_intf_op[] = {
	INTF_OP ( intf_close, struct interface *, null_intf_close ),
	};

	/** 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 object interface into a new destination object 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
	* interface is updated to point to the new destination interface.
	*/
	void intf_plug ( struct interface intf, struct interface dest ) {

	if ( intf == &null_intf )
	return;

	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 = dest;
	}

	/**
	* Plug two object interfaces together
	*
	* @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 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 ) {
	DBGC ( INTF_COL ( intf ), "INTF " INTF_INTF_FMT " unplug\n",
	INTF_INTF_DBG ( intf, intf->dest ) );
	intf_put ( intf->dest );
	intf->dest = &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 (without pass-through)
	*
	* @v intf Object interface
	* @v type Operation type
	* @ret dest Destination interface
	* @ret func Implementing method, or NULL
	*/
	void * intf_get_dest_op_no_passthru_untyped ( struct interface *intf,
	void *type,
	struct interface **dest ) {
	struct interface_descriptor *desc;
	struct interface_operation *op;
	unsigned int i;

	*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;
	}

	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 ) {
	void *func;

	while ( 1 ) {

	/* Search for an implementing method provided by the
	* current destination interface.
	*/
	func = intf_get_dest_op_no_passthru_untyped( intf, type, dest );
	if ( func )
	return 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 restart the interface */
	intf_restart ( dest, rc );
	}

	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 ) {
	struct interface tmp;

	DBGC ( INTF_COL ( intf ), "INTF " INTF_FMT " shutting down (%s)\n",
	INTF_DBG ( intf ), strerror ( rc ) );

	/* Block further operations */
	intf_nullify ( intf );

	/* Transfer destination to temporary interface */
	intf_temp_init ( &tmp, intf );
	tmp.dest = intf->dest;
	intf->dest = &null_intf;

	/* Notify destination of close via temporary interface */
	intf_close ( &tmp, rc );

	/* Unplug temporary interface */
	intf_unplug ( &tmp );
	}

	/**
	* Shut down multiple object interfaces
	*
	* @v intfs Object interfaces
	* @v rc Reason for close
	*/
	void intfs_vshutdown ( va_list intfs, int rc ) {
	struct interface *intf;
	va_list tmp;

	/* Nullify all interfaces to avoid potential loops */
	va_copy ( tmp, intfs );
	while ( ( intf = va_arg ( tmp, struct interface * ) ) )
	intf_nullify ( intf );
	va_end ( tmp );

	/* Shut down all interfaces */
	while ( ( intf = va_arg ( intfs, struct interface * ) ) )
	intf_shutdown ( intf, rc );
	}

	/**
	* Shut down multiple object interfaces
	*
	* @v rc Reason for close
	* @v ... Object interfaces
	*/
	void intfs_shutdown ( int rc, ... ) {
	va_list intfs;

	va_start ( intfs, rc );
	intfs_vshutdown ( intfs, rc );
	va_end ( intfs );
	}

	/**
	* 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 ) {

	/* 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_reinit ( intf );
	}

	/**
	* Shut down and restart multiple object interfaces
	*
	* @v intfs Object interfaces
	* @v rc Reason for close
	*/
	void intfs_vrestart ( va_list intfs, int rc ) {
	struct interface *intf;
	va_list tmp;

	/* Shut down all interfaces */
	va_copy ( tmp, intfs );
	intfs_vshutdown ( tmp, rc );
	va_end ( tmp );

	/* Reinitialise all interfaces */
	while ( ( intf = va_arg ( intfs, struct interface * ) ) )
	intf_reinit ( intf );
	}

	/**
	* Shut down and restart multiple object interfaces
	*
	* @v rc Reason for close
	* @v ... Object interfaces
	*/
	void intfs_restart ( int rc, ... ) {
	va_list intfs;

	va_start ( intfs, rc );
	intfs_vrestart ( intfs, rc );
	va_end ( intfs );
	}

	/**
	* Insert a filter interface
	*
	* @v intf Object interface
	* @v upper Upper end of filter
	* @v lower Lower end of filter
	*/
	void intf_insert ( struct interface intf, struct interface upper,
	struct interface *lower ) {
	struct interface *dest = intf->dest;

	intf_get ( dest );
	intf_plug_plug ( intf, upper );
	intf_plug_plug ( lower, dest );
	intf_put ( dest );
	}

	/**
	* Poke an object interface
	*
	* @v intf Object interface
	* @v type Operation type
	*
	* This is a helper function to implement methods which take no
	* parameters and return nothing.
	*/
	void intf_poke ( struct interface *intf,
	void ( type ) ( struct interface *intf ) ) {
	struct interface *dest;
	intf_poke_TYPE ( void * ) *op =
	intf_get_dest_op_untyped ( intf, type, &dest );
	void *object = intf_object ( dest );

	if ( op ) {
	op ( object );
	} else {
	/* Default is to do nothing */
	}

	intf_put ( dest );
	}