VNet Dynamic Resources API
--------------------------

Release binding: Patch
Interface Taxonmy: Project Private

0. Introduction
---------------

The LDoms vnet provides the capability to dynamically add and subtract
resources (LDC channels and Hybrid I/O resources) to provide additional
I/O capability for better perfomance. 


1. Overview
-----------

The pluggable vnet resources interface allows for the dynamic re-plumbing
of the I/O portion of the vnet driver while not requiring the re-plumbing
of the IP stack above the vnet deivce.  Hence, the switching between virtual
I/O operation and Hybrid I/O operation of the vnet is handled cleanly and
smoothly with the upper layers not being aware of the switch in operations.
The Hybrid I/O pluggability of this interfaces offers guest domains direct
access to a portion of a network device plumbed directly under the vnet.

Operation of the interface is rather simple.  The client (vnet) registers
with the providers each of the resources (LDC channels or the Hybrid I/O
NIU client domain driver).  Each provider is a GLDv3 device that provides
a GLDv3 compliant device interface.

Below is a complete description of the interface.

2. VNet Resources
-----------------

/*
 * Vio network resource types.
 * VIO_NET_RES_LDC_SERVICE:
 *			An LDC based resource corresonding to vswitch
 *			service. This means, all broadcast pakets need
 *			to be sent via this resource. Unicast packets
 *			that have no known end point will also be sent
 *			via this resource, but only if no Hybrid resource
 *			is available.
 *
 * VIO_NET_RES_LDC_GUEST:
 *			An LDC based resource corresponding to another
 *			guest domain. This means, unicast packets to that
 *			guest's mac addres will be sent via this resource.
 *
 * VIO_NET_RES_HYBRID:
 *			A Hybrid resource. Even though this resource may 
 *			be capable of transmitting the broadcast/multicast
 *			traffic, it will be used only for transmitting
 *			uni-cast traffic.
 *			This is because the broadcast/multicast traffic needs
 *			to be sent to the vswitch so that those packets
 *			are sent to other guest domains and vswitch interface.
 */
typedef enum {
	VIO_NET_RES_LDC_SERVICE,
	VIO_NET_RES_LDC_GUEST,
	VIO_NET_RES_HYBRID
} vio_net_res_type_t;

/* A handle returned by vio_net_resource_reg() interface */
typedef void *vio_net_handle_t;

/*
 * Callback functions returned via the reg() interfce.
 *
 * vio_net_rx_cb: 	Used for passing the packets that are received
 *			by a device. This is equivalent of mac_rx().
 *
 * vio_net_tx_update:   Used for re-starting the transmission. This
 *			is an equivalent of mac_tx_update().
 */
typedef void (*vio_net_rx_cb_t)(vio_net_handle_t, mblk_t *);
typedef void (*vio_net_tx_update_t)(vio_net_handle_t);

typedef enum {
	VIO_NET_RES_DOWN,		/* Resource down */
	VIO_VNET_RES_ERR		/* Resource encountered an error */
} vio_net_err_val_t;

typedef void (*vio_net_report_err_t)(vio_net_handle_t,
    uint64_t vio_net_err_val_t);

typedef struct vio_net_callbacks_s {
	vio_net_rx_cb_t		vio_net_rx_cb;
	vio_net_tx_update_t	vio_net_tx_update;
	vio_net_report_err_t	vio_net_report_err;
} vio_net_callbacks_t;

/*
 * vio_net_resource_reg -- An interface to register a resource with vnet.
 *
 *	macp: 		A mac_register_t structure representing the
 *			device and its MAC driver callbacks.
 *	type: 		Type of the device.
 *
 *	local-macaddr: 	A MAC address to which this resource belongs to.
 *
 *	rem_macaddr: 	A MAC address of the peer. This is only applicable
 *			to LDC based resource. This argument is ignored
 *			for HYBRID resource.
 *	vhp: 		A handle returned by this interface. After a
 *			successful return of this interface,
 *			all other interaction will use this handle.
 *
 *	vcb: 		A set of callbacks returned by this interface
 *			for the use of the devices to pass packets etc.
 *
 * Return value: 0 for success, non-zero errno value appropriate for the error.
 */
int vio_net_resource_reg(mac_register_t *macp, vio_net_res_type_t type,
    ether_addr_t local_maddr, ether_addr_t rem_maddr, vio_net_handle_t *vhp,
    vio_net_callbacks_t *vcb);

/*
 * vio_net_resource_unreg -- Unregisters a resource.
 *
 *	vhp:  handle that was returned by the resource_reg() interface.
 */
void vio_net_resource_unreg(vio_net_handle_t vhp);

3. References
-------------

1. Hybrid NIU Architecture Specification,
   http://www.opensolaris.org/os/project/crossbow/Docs/virtual_resources.pdf

2. PSARC/2006/248 Nemo MAC-Type Plugin Architecture
   http://sac.sfbay/Archives/CaseLog/arc/PSARC/2006/248