src/net/rndis.c

/*
 * Copyright (C) 2014 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 (at your option) 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 );
FILE_SECBOOT ( PERMITTED );

/** @file
 *
 * Remote Network Driver Interface Specification
 *
 */

#include <unistd.h>
#include <string.h>
#include <errno.h>
#include <byteswap.h>
#include <ipxe/iobuf.h>
#include <ipxe/netdevice.h>
#include <ipxe/ethernet.h>
#include <ipxe/device.h>
#include <ipxe/rndis.h>

/**
 * Allocate I/O buffer
 *
 * @v len		Length
 * @ret iobuf		I/O buffer, or NULL
 */
static struct io_buffer * rndis_alloc_iob ( size_t len ) {
	struct rndis_header *header;
	struct io_buffer *iobuf;

	/* Allocate I/O buffer and reserve space */
	iobuf = alloc_iob ( sizeof ( *header ) + len );
	if ( iobuf )
		iob_reserve ( iobuf, sizeof ( *header ) );

	return iobuf;
}

/**
 * Wait for completion
 *
 * @v rndis		RNDIS device
 * @v wait_id		Request ID
 * @ret rc		Return status code
 */
static int rndis_wait ( struct rndis_device *rndis, unsigned int wait_id ) {
	unsigned int i;

	/* Record query ID */
	rndis->wait_id = wait_id;

	/* Wait for operation to complete */
	for ( i = 0 ; i < RNDIS_MAX_WAIT_MS ; i++ ) {

		/* Check for completion */
		if ( ! rndis->wait_id )
			return rndis->wait_rc;

		/* Poll RNDIS device */
		rndis->op->poll ( rndis );

		/* Delay for 1ms */
		mdelay ( 1 );
	}

	DBGC ( rndis, "RNDIS %s timed out waiting for ID %#08x\n",
	       rndis->name, wait_id );
	return -ETIMEDOUT;
}

/**
 * Transmit message
 *
 * @v rndis		RNDIS device
 * @v iobuf		I/O buffer
 * @v type		Message type
 * @ret rc		Return status code
 */
static int rndis_tx_message ( struct rndis_device *rndis,
			      struct io_buffer *iobuf, unsigned int type ) {
	struct rndis_header *header;
	int rc;

	/* Prepend RNDIS header */
	header = iob_push ( iobuf, sizeof ( *header ) );
	header->type = cpu_to_le32 ( type );
	header->len = cpu_to_le32 ( iob_len ( iobuf ) );

	/* Transmit message */
	if ( ( rc = rndis->op->transmit ( rndis, iobuf ) ) != 0 ) {
		DBGC ( rndis, "RNDIS %s could not transmit: %s\n",
		       rndis->name, strerror ( rc ) );
		return rc;
	}

	return 0;
}

/**
 * Complete message transmission
 *
 * @v rndis		RNDIS device
 * @v iobuf		I/O buffer
 * @v rc		Packet status code
 */
void rndis_tx_complete_err ( struct rndis_device *rndis,
			     struct io_buffer *iobuf, int rc ) {
	struct net_device *netdev = rndis->netdev;
	struct rndis_header *header;
	size_t len = iob_len ( iobuf );

	/* Sanity check */
	if ( len < sizeof ( *header ) ) {
		DBGC ( rndis, "RNDIS %s completed underlength transmission:\n",
		       rndis->name );
		DBGC_HDA ( rndis, 0, iobuf->data, len );
		netdev_tx_err ( netdev, NULL, -EINVAL );
		return;
	}
	header = iobuf->data;

	/* Complete buffer */
	if ( header->type == cpu_to_le32 ( RNDIS_PACKET_MSG ) ) {
		netdev_tx_complete_err ( netdev, iobuf, rc );
	} else {
		free_iob ( iobuf );
	}
}

/**
 * Transmit data packet
 *
 * @v rndis		RNDIS device
 * @v iobuf		I/O buffer
 * @ret rc		Return status code
 */
static int rndis_tx_data ( struct rndis_device *rndis,
			   struct io_buffer *iobuf ) {
	struct rndis_packet_message *msg;
	size_t len = iob_len ( iobuf );
	int rc;

	/* Prepend packet message header */
	msg = iob_push ( iobuf, sizeof ( *msg ) );
	memset ( msg, 0, sizeof ( *msg ) );
	msg->data.offset = cpu_to_le32 ( sizeof ( *msg ) );
	msg->data.len = cpu_to_le32 ( len );

	/* Transmit message */
	if ( ( rc = rndis_tx_message ( rndis, iobuf, RNDIS_PACKET_MSG ) ) != 0 )
		return rc;

	return 0;
}

/**
 * Defer transmitted packet
 *
 * @v rndis		RNDIS device
 * @v iobuf		I/O buffer
 * @ret rc		Return status code
 *
 * As with netdev_tx_defer(), the caller must ensure that space in the
 * transmit descriptor ring is freed up before calling
 * rndis_tx_complete().
 *
 * Unlike netdev_tx_defer(), this call may fail.
 */
int rndis_tx_defer ( struct rndis_device *rndis, struct io_buffer *iobuf ) {
	struct net_device *netdev = rndis->netdev;
	struct rndis_header *header;
	struct rndis_packet_message *msg;

	/* Fail unless this was a packet message.  Only packet
	 * messages correspond to I/O buffers in the network device's
	 * TX queue; other messages cannot be deferred in this way.
	 */
	assert ( iob_len ( iobuf ) >= sizeof ( *header ) );
	header = iobuf->data;
	if ( header->type != cpu_to_le32 ( RNDIS_PACKET_MSG ) )
		return -ENOTSUP;

	/* Strip RNDIS header and packet message header, to return
	 * this packet to the state in which we received it.
	 */
	iob_pull ( iobuf, ( sizeof ( *header ) + sizeof ( *msg ) ) );

	/* Defer packet */
	netdev_tx_defer ( netdev, iobuf );

	return 0;
}

/**
 * Receive data packet
 *
 * @v rndis		RNDIS device
 * @v iobuf		I/O buffer
 */
static void rndis_rx_data ( struct rndis_device *rndis,
			    struct io_buffer *iobuf ) {
	struct net_device *netdev = rndis->netdev;
	struct rndis_packet_message *msg;
	size_t len = iob_len ( iobuf );
	size_t data_offset;
	size_t data_len;
	int rc;

	/* Sanity check */
	if ( len < sizeof ( *msg ) ) {
		DBGC ( rndis, "RNDIS %s received underlength data packet:\n",
		       rndis->name );
		DBGC_HDA ( rndis, 0, iobuf->data, len );
		rc = -EINVAL;
		goto err_len;
	}
	msg = iobuf->data;

	/* Locate and sanity check data buffer */
	data_offset = le32_to_cpu ( msg->data.offset );
	data_len = le32_to_cpu ( msg->data.len );
	if ( ( data_offset > len ) || ( data_len > ( len - data_offset ) ) ) {
		DBGC ( rndis, "RNDIS %s data packet data exceeds packet:\n",
		       rndis->name );
		DBGC_HDA ( rndis, 0, iobuf->data, len );
		rc = -EINVAL;
		goto err_data;
	}

	/* Strip non-data portions */
	iob_pull ( iobuf, data_offset );
	iob_unput ( iobuf, ( iob_len ( iobuf ) - data_len ) );

	/* Hand off to network stack */
	netdev_rx ( netdev, iob_disown ( iobuf ) );

	return;

 err_data:
 err_len:
	/* Report error to network stack */
	netdev_rx_err ( netdev, iob_disown ( iobuf ), rc );
}

/**
 * Transmit initialisation message
 *
 * @v rndis		RNDIS device
 * @v id		Request ID
 * @ret rc		Return status code
 */
static int rndis_tx_initialise ( struct rndis_device *rndis, unsigned int id ) {
	struct io_buffer *iobuf;
	struct rndis_initialise_message *msg;
	int rc;

	/* Allocate I/O buffer */
	iobuf = rndis_alloc_iob ( sizeof ( *msg ) );
	if ( ! iobuf ) {
		rc = -ENOMEM;
		goto err_alloc;
	}

	/* Construct message */
	msg = iob_put ( iobuf, sizeof ( *msg ) );
	memset ( msg, 0, sizeof ( *msg ) );
	msg->id = id; /* Non-endian */
	msg->major = cpu_to_le32 ( RNDIS_VERSION_MAJOR );
	msg->minor = cpu_to_le32 ( RNDIS_VERSION_MINOR );
	msg->mtu = cpu_to_le32 ( RNDIS_MTU );

	/* Transmit message */
	if ( ( rc = rndis_tx_message ( rndis, iobuf,
				       RNDIS_INITIALISE_MSG ) ) != 0 )
		goto err_tx;

	return 0;

 err_tx:
	free_iob ( iobuf );
 err_alloc:
	return rc;
}

/**
 * Receive initialisation completion
 *
 * @v rndis		RNDIS device
 * @v iobuf		I/O buffer
 */
static void rndis_rx_initialise ( struct rndis_device *rndis,
				  struct io_buffer *iobuf ) {
	struct rndis_initialise_completion *cmplt;
	size_t len = iob_len ( iobuf );
	unsigned int id;
	int rc;

	/* Sanity check */
	if ( len < sizeof ( *cmplt ) ) {
		DBGC ( rndis, "RNDIS %s received underlength initialisation "
		       "completion:\n", rndis->name );
		DBGC_HDA ( rndis, 0, iobuf->data, len );
		rc = -EINVAL;
		goto err_len;
	}
	cmplt = iobuf->data;

	/* Extract request ID */
	id = cmplt->id; /* Non-endian */

	/* Check status */
	if ( cmplt->status ) {
		DBGC ( rndis, "RNDIS %s received initialisation completion "
		       "failure %#08x\n", rndis->name,
		       le32_to_cpu ( cmplt->status ) );
		rc = -EIO;
		goto err_status;
	}

	/* Success */
	rc = 0;

 err_status:
	/* Record completion result if applicable */
	if ( id == rndis->wait_id ) {
		rndis->wait_id = 0;
		rndis->wait_rc = rc;
	}
 err_len:
	free_iob ( iobuf );
}

/**
 * Initialise RNDIS
 *
 * @v rndis		RNDIS device
 * @ret rc		Return status code
 */
static int rndis_initialise ( struct rndis_device *rndis ) {
	int rc;

	/* Transmit initialisation message */
	if ( ( rc = rndis_tx_initialise ( rndis, RNDIS_INIT_ID ) ) != 0 )
		return rc;

	/* Wait for response */
	if ( ( rc = rndis_wait ( rndis, RNDIS_INIT_ID ) ) != 0 )
		return rc;

	return 0;
}

/**
 * Transmit halt message
 *
 * @v rndis		RNDIS device
 * @ret rc		Return status code
 */
static int rndis_tx_halt ( struct rndis_device *rndis ) {
	struct io_buffer *iobuf;
	struct rndis_halt_message *msg;
	int rc;

	/* Allocate I/O buffer */
	iobuf = rndis_alloc_iob ( sizeof ( *msg ) );
	if ( ! iobuf ) {
		rc = -ENOMEM;
		goto err_alloc;
	}

	/* Construct message */
	msg = iob_put ( iobuf, sizeof ( *msg ) );
	memset ( msg, 0, sizeof ( *msg ) );

	/* Transmit message */
	if ( ( rc = rndis_tx_message ( rndis, iobuf, RNDIS_HALT_MSG ) ) != 0 )
		goto err_tx;

	return 0;

 err_tx:
	free_iob ( iobuf );
 err_alloc:
	return rc;
}

/**
 * Halt RNDIS
 *
 * @v rndis		RNDIS device
 * @ret rc		Return status code
 */
static int rndis_halt ( struct rndis_device *rndis ) {
	int rc;

	/* Transmit halt message */
	if ( ( rc = rndis_tx_halt ( rndis ) ) != 0 )
		return rc;

	return 0;
}

/**
 * Transmit OID message
 *
 * @v rndis		RNDIS device
 * @v oid		Object ID
 * @v data		New OID value (or NULL to query current value)
 * @v len		Length of new OID value
 * @ret rc		Return status code
 */
static int rndis_tx_oid ( struct rndis_device *rndis, unsigned int oid,
			  const void *data, size_t len ) {
	struct io_buffer *iobuf;
	struct rndis_oid_message *msg;
	unsigned int type;
	int rc;

	/* Allocate I/O buffer */
	iobuf = rndis_alloc_iob ( sizeof ( *msg ) + len );
	if ( ! iobuf ) {
		rc = -ENOMEM;
		goto err_alloc;
	}

	/* Construct message.  We use the OID as the request ID. */
	msg = iob_put ( iobuf, sizeof ( *msg ) );
	memset ( msg, 0, sizeof ( *msg ) );
	msg->id = oid; /* Non-endian */
	msg->oid = cpu_to_le32 ( oid );
	msg->offset = cpu_to_le32 ( sizeof ( *msg ) );
	msg->len = cpu_to_le32 ( len );
	memcpy ( iob_put ( iobuf, len ), data, len );

	/* Transmit message */
	type = ( data ? RNDIS_SET_MSG : RNDIS_QUERY_MSG );
	if ( ( rc = rndis_tx_message ( rndis, iobuf, type ) ) != 0 )
		goto err_tx;

	return 0;

 err_tx:
	free_iob ( iobuf );
 err_alloc:
	return rc;
}

/**
 * Receive query OID completion
 *
 * @v rndis		RNDIS device
 * @v iobuf		I/O buffer
 */
static void rndis_rx_query_oid ( struct rndis_device *rndis,
				 struct io_buffer *iobuf ) {
	struct net_device *netdev = rndis->netdev;
	struct rndis_query_completion *cmplt;
	size_t len = iob_len ( iobuf );
	size_t info_offset;
	size_t info_len;
	unsigned int id;
	void *info;
	uint32_t *link_status;
	int rc;

	/* Sanity check */
	if ( len < sizeof ( *cmplt ) ) {
		DBGC ( rndis, "RNDIS %s received underlength query "
		       "completion:\n", rndis->name );
		DBGC_HDA ( rndis, 0, iobuf->data, len );
		rc = -EINVAL;
		goto err_len;
	}
	cmplt = iobuf->data;

	/* Extract request ID */
	id = cmplt->id; /* Non-endian */

	/* Check status */
	if ( cmplt->status ) {
		DBGC ( rndis, "RNDIS %s received query completion failure "
		       "%#08x\n", rndis->name, le32_to_cpu ( cmplt->status ) );
		DBGC_HDA ( rndis, 0, iobuf->data, len );
		rc = -EIO;
		goto err_status;
	}

	/* Locate and sanity check information buffer */
	info_offset = le32_to_cpu ( cmplt->offset );
	info_len = le32_to_cpu ( cmplt->len );
	if ( ( info_offset > len ) || ( info_len > ( len - info_offset ) ) ) {
		DBGC ( rndis, "RNDIS %s query completion information exceeds "
		       "packet:\n", rndis->name );
		DBGC_HDA ( rndis, 0, iobuf->data, len );
		rc = -EINVAL;
		goto err_info;
	}
	info = ( ( ( void * ) cmplt ) + info_offset );

	/* Handle OID */
	switch ( id ) {

	case RNDIS_OID_802_3_PERMANENT_ADDRESS:
		if ( info_len > sizeof ( netdev->hw_addr ) )
			info_len = sizeof ( netdev->hw_addr );
		memcpy ( netdev->hw_addr, info, info_len );
		break;

	case RNDIS_OID_802_3_CURRENT_ADDRESS:
		if ( info_len > sizeof ( netdev->ll_addr ) )
			info_len = sizeof ( netdev->ll_addr );
		memcpy ( netdev->ll_addr, info, info_len );
		break;

	case RNDIS_OID_GEN_MEDIA_CONNECT_STATUS:
		if ( info_len != sizeof ( *link_status ) ) {
			DBGC ( rndis, "RNDIS %s invalid link status:\n",
			       rndis->name );
			DBGC_HDA ( rndis, 0, iobuf->data, len );
			rc = -EPROTO;
			goto err_link_status;
		}
		link_status = info;
		if ( *link_status == 0 ) {
			DBGC ( rndis, "RNDIS %s link is up\n", rndis->name );
			netdev_link_up ( netdev );
		} else {
			DBGC ( rndis, "RNDIS %s link is down: %#08x\n",
			       rndis->name, le32_to_cpu ( *link_status ) );
			netdev_link_down ( netdev );
		}
		break;

	default:
		DBGC ( rndis, "RNDIS %s unexpected query completion ID %#08x\n",
		       rndis->name, id );
		DBGC_HDA ( rndis, 0, iobuf->data, len );
		rc = -EPROTO;
		goto err_id;
	}

	/* Success */
	rc = 0;

 err_id:
 err_link_status:
 err_info:
 err_status:
	/* Record completion result if applicable */
	if ( id == rndis->wait_id ) {
		rndis->wait_id = 0;
		rndis->wait_rc = rc;
	}
 err_len:
	/* Free I/O buffer */
	free_iob ( iobuf );
}

/**
 * Receive set OID completion
 *
 * @v rndis		RNDIS device
 * @v iobuf		I/O buffer
 */
static void rndis_rx_set_oid ( struct rndis_device *rndis,
			       struct io_buffer *iobuf ) {
	struct rndis_set_completion *cmplt;
	size_t len = iob_len ( iobuf );
	unsigned int id;
	int rc;

	/* Sanity check */
	if ( len < sizeof ( *cmplt ) ) {
		DBGC ( rndis, "RNDIS %s received underlength set completion:\n",
		       rndis->name );
		DBGC_HDA ( rndis, 0, iobuf->data, len );
		rc = -EINVAL;
		goto err_len;
	}
	cmplt = iobuf->data;

	/* Extract request ID */
	id = cmplt->id; /* Non-endian */

	/* Check status */
	if ( cmplt->status ) {
		DBGC ( rndis, "RNDIS %s received set completion failure "
		       "%#08x\n", rndis->name, le32_to_cpu ( cmplt->status ) );
		DBGC_HDA ( rndis, 0, iobuf->data, len );
		rc = -EIO;
		goto err_status;
	}

	/* Success */
	rc = 0;

 err_status:
	/* Record completion result if applicable */
	if ( id == rndis->wait_id ) {
		rndis->wait_id = 0;
		rndis->wait_rc = rc;
	}
 err_len:
	/* Free I/O buffer */
	free_iob ( iobuf );
}

/**
 * Query or set OID
 *
 * @v rndis		RNDIS device
 * @v oid		Object ID
 * @v data		New OID value (or NULL to query current value)
 * @v len		Length of new OID value
 * @ret rc		Return status code
 */
static int rndis_oid ( struct rndis_device *rndis, unsigned int oid,
		       const void *data, size_t len ) {
	int rc;

	/* Transmit query */
	if ( ( rc = rndis_tx_oid ( rndis, oid, data, len ) ) != 0 )
		return rc;

	/* Wait for response */
	if ( ( rc = rndis_wait ( rndis, oid ) ) != 0 )
		return rc;

	return 0;
}

/**
 * Describe RNDIS device
 *
 * @v rndis		RNDIS device
 * @ret rc		Return status code
 */
static int rndis_describe ( struct rndis_device *rndis ) {
	struct net_device *netdev = rndis->netdev;
	int rc;

	/* Assign device name (for debugging) */
	rndis->name = netdev->dev->name;

	/* Open RNDIS device to read MAC addresses */
	if ( ( rc = rndis->op->open ( rndis ) ) != 0 ) {
		DBGC ( rndis, "RNDIS %s could not open: %s\n",
		       rndis->name, strerror ( rc ) );
		goto err_open;
	}

	/* Initialise RNDIS */
	if ( ( rc = rndis_initialise ( rndis ) ) != 0 )
		goto err_initialise;

	/* Query permanent MAC address */
	if ( ( rc = rndis_oid ( rndis, RNDIS_OID_802_3_PERMANENT_ADDRESS,
				NULL, 0 ) ) != 0 )
		goto err_query_permanent;

	/* Query current MAC address */
	if ( ( rc = rndis_oid ( rndis, RNDIS_OID_802_3_CURRENT_ADDRESS,
				NULL, 0 ) ) != 0 )
		goto err_query_current;

	/* Get link status */
	if ( ( rc = rndis_oid ( rndis, RNDIS_OID_GEN_MEDIA_CONNECT_STATUS,
				NULL, 0 ) ) != 0 )
		goto err_query_link;

	/* Halt RNDIS device */
	rndis_halt ( rndis );

	/* Close RNDIS device */
	rndis->op->close ( rndis );

	return 0;

 err_query_link:
 err_query_current:
 err_query_permanent:
	rndis_halt ( rndis );
 err_initialise:
	rndis->op->close ( rndis );
 err_open:
	return rc;
}

/**
 * Receive indicate status message
 *
 * @v rndis		RNDIS device
 * @v iobuf		I/O buffer
 */
static void rndis_rx_status ( struct rndis_device *rndis,
			      struct io_buffer *iobuf ) {
	struct net_device *netdev = rndis->netdev;
	struct rndis_indicate_status_message *msg;
	size_t len = iob_len ( iobuf );
	unsigned int status;
	int rc;

	/* Sanity check */
	if ( len < sizeof ( *msg ) ) {
		DBGC ( rndis, "RNDIS %s received underlength status message:\n",
		       rndis->name );
		DBGC_HDA ( rndis, 0, iobuf->data, len );
		rc = -EINVAL;
		goto err_len;
	}
	msg = iobuf->data;

	/* Extract status */
	status = le32_to_cpu ( msg->status );

	/* Handle status */
	switch ( msg->status ) {

	case RNDIS_STATUS_MEDIA_CONNECT:
		DBGC ( rndis, "RNDIS %s link is up\n", rndis->name );
		netdev_link_up ( netdev );
		break;

	case RNDIS_STATUS_MEDIA_DISCONNECT:
		DBGC ( rndis, "RNDIS %s link is down\n", rndis->name );
		netdev_link_down ( netdev );
		break;

	case RNDIS_STATUS_WTF_WORLD:
		/* Ignore */
		break;

	default:
		DBGC ( rndis, "RNDIS %s unexpected status %#08x:\n",
		       rndis->name, status );
		DBGC_HDA ( rndis, 0, iobuf->data, len );
		rc = -ENOTSUP;
		goto err_status;
	}

	/* Free I/O buffer */
	free_iob ( iobuf );

	return;

 err_status:
 err_len:
	/* Report error via network device statistics */
	netdev_rx_err ( netdev, iobuf, rc );
}

/**
 * Receive RNDIS message
 *
 * @v rndis		RNDIS device
 * @v iobuf		I/O buffer
 * @v type		Message type
 */
static void rndis_rx_message ( struct rndis_device *rndis,
			       struct io_buffer *iobuf, unsigned int type ) {
	struct net_device *netdev = rndis->netdev;
	int rc;

	/* Handle packet */
	switch ( type ) {

	case RNDIS_PACKET_MSG:
		rndis_rx_data ( rndis, iob_disown ( iobuf ) );
		break;

	case RNDIS_INITIALISE_CMPLT:
		rndis_rx_initialise ( rndis, iob_disown ( iobuf ) );
		break;

	case RNDIS_QUERY_CMPLT:
		rndis_rx_query_oid ( rndis, iob_disown ( iobuf ) );
		break;

	case RNDIS_SET_CMPLT:
		rndis_rx_set_oid ( rndis, iob_disown ( iobuf ) );
		break;

	case RNDIS_INDICATE_STATUS_MSG:
		rndis_rx_status ( rndis, iob_disown ( iobuf ) );
		break;

	default:
		DBGC ( rndis, "RNDIS %s received unexpected type %#08x\n",
		       rndis->name, type );
		DBGC_HDA ( rndis, 0, iobuf->data, iob_len ( iobuf ) );
		rc = -EPROTO;
		goto err_type;
	}

	return;

 err_type:
	/* Report error via network device statistics */
	netdev_rx_err ( netdev, iobuf, rc );
}

/**
 * Receive packet from underlying transport layer
 *
 * @v rndis		RNDIS device
 * @v iobuf		I/O buffer
 */
void rndis_rx ( struct rndis_device *rndis, struct io_buffer *iobuf ) {
	struct net_device *netdev = rndis->netdev;
	struct rndis_header *header;
	unsigned int type;
	int rc;

	/* Sanity check */
	if ( iob_len ( iobuf ) < sizeof ( *header ) ) {
		DBGC ( rndis, "RNDIS %s received underlength packet:\n",
		       rndis->name );
		DBGC_HDA ( rndis, 0, iobuf->data, iob_len ( iobuf ) );
		rc = -EINVAL;
		goto drop;
	}
	header = iobuf->data;

	/* Parse and strip header */
	type = le32_to_cpu ( header->type );
	iob_pull ( iobuf, sizeof ( *header ) );

	/* Handle message */
	rndis_rx_message ( rndis, iob_disown ( iobuf ), type );

	return;

 drop:
	/* Record error */
	netdev_rx_err ( netdev, iob_disown ( iobuf ), rc );
}

/**
 * Discard packet from underlying transport layer
 *
 * @v rndis		RNDIS device
 * @v iobuf		I/O buffer
 * @v rc		Packet status code
 */
void rndis_rx_err ( struct rndis_device *rndis, struct io_buffer *iobuf,
		    int rc ) {
	struct net_device *netdev = rndis->netdev;

	/* Record error */
	netdev_rx_err ( netdev, iob_disown ( iobuf ), rc );
}

/**
 * Set receive filter
 *
 * @v rndis		RNDIS device
 * @v filter		Receive filter
 * @ret rc		Return status code
 */
static int rndis_filter ( struct rndis_device *rndis, unsigned int filter ) {
	uint32_t value = cpu_to_le32 ( filter );
	int rc;

	/* Set receive filter */
	if ( ( rc = rndis_oid ( rndis, RNDIS_OID_GEN_CURRENT_PACKET_FILTER,
				&value, sizeof ( value ) ) ) != 0 ) {
		DBGC ( rndis, "RNDIS %s could not set receive filter to %#08x: "
		       "%s\n", rndis->name, filter, strerror ( rc ) );
		return rc;
	}

	return 0;
}

/**
 * Open network device
 *
 * @v netdev		Network device
 * @ret rc		Return status code
 */
static int rndis_open ( struct net_device *netdev ) {
	struct rndis_device *rndis = netdev->priv;
	int rc;

	/* Open RNDIS device */
	if ( ( rc = rndis->op->open ( rndis ) ) != 0 ) {
		DBGC ( rndis, "RNDIS %s could not open: %s\n",
		       rndis->name, strerror ( rc ) );
		goto err_open;
	}

	/* Initialise RNDIS */
	if ( ( rc = rndis_initialise ( rndis ) ) != 0 )
		goto err_initialise;

	/* Set receive filter */
	if ( ( rc = rndis_filter ( rndis, ( RNDIS_FILTER_UNICAST |
					    RNDIS_FILTER_MULTICAST |
					    RNDIS_FILTER_ALL_MULTICAST |
					    RNDIS_FILTER_BROADCAST |
					    RNDIS_FILTER_PROMISCUOUS ) ) ) != 0)
		goto err_set_filter;

	/* Update link status */
	if ( ( rc = rndis_oid ( rndis, RNDIS_OID_GEN_MEDIA_CONNECT_STATUS,
				NULL, 0 ) ) != 0 )
		goto err_query_link;

	return 0;

 err_query_link:
 err_set_filter:
	rndis_halt ( rndis );
 err_initialise:
	rndis->op->close ( rndis );
 err_open:
	return rc;
}

/**
 * Close network device
 *
 * @v netdev		Network device
 */
static void rndis_close ( struct net_device *netdev ) {
	struct rndis_device *rndis = netdev->priv;

	/* Clear receive filter */
	rndis_filter ( rndis, 0 );

	/* Halt RNDIS device */
	rndis_halt ( rndis );

	/* Close RNDIS device */
	rndis->op->close ( rndis );
}

/**
 * Transmit packet
 *
 * @v netdev		Network device
 * @v iobuf		I/O buffer
 * @ret rc		Return status code
 */
static int rndis_transmit ( struct net_device *netdev,
			    struct io_buffer *iobuf ) {
	struct rndis_device *rndis = netdev->priv;

	/* Transmit data packet */
	return rndis_tx_data ( rndis, iobuf );
}

/**
 * Poll for completed and received packets
 *
 * @v netdev		Network device
 */
static void rndis_poll ( struct net_device *netdev ) {
	struct rndis_device *rndis = netdev->priv;

	/* Poll RNDIS device */
	rndis->op->poll ( rndis );
}

/** Network device operations */
static struct net_device_operations rndis_operations = {
	.open		= rndis_open,
	.close		= rndis_close,
	.transmit	= rndis_transmit,
	.poll		= rndis_poll,
};

/**
 * Allocate RNDIS device
 *
 * @v priv_len		Length of private data
 * @ret rndis		RNDIS device, or NULL on allocation failure
 */
struct rndis_device * alloc_rndis ( size_t priv_len ) {
	struct net_device *netdev;
	struct rndis_device *rndis;

	/* Allocate and initialise structure */
	netdev = alloc_etherdev ( sizeof ( *rndis ) + priv_len );
	if ( ! netdev )
		return NULL;
	netdev_init ( netdev, &rndis_operations );
	rndis = netdev->priv;
	rndis->netdev = netdev;
	rndis->priv = ( ( ( void * ) rndis ) + sizeof ( *rndis ) );

	return rndis;
}

/**
 * Register RNDIS device
 *
 * @v rndis		RNDIS device
 * @ret rc		Return status code
 *
 * Note that this routine will open and use the RNDIS device in order
 * to query the MAC address.  The device must be immediately ready for
 * use prior to registration.
 */
int register_rndis ( struct rndis_device *rndis ) {
	struct net_device *netdev = rndis->netdev;
	int rc;

	/* Describe RNDIS device */
	if ( ( rc = rndis_describe ( rndis ) ) != 0 )
		goto err_describe;

	/* Register network device */
	if ( ( rc = register_netdev ( netdev ) ) != 0 ) {
		DBGC ( rndis, "RNDIS %s could not register: %s\n",
		       rndis->name, strerror ( rc ) );
		goto err_register;
	}

	return 0;

	unregister_netdev ( netdev );
 err_register:
 err_describe:
	return rc;
}

/**
 * Unregister RNDIS device
 *
 * @v rndis		RNDIS device
 */
void unregister_rndis ( struct rndis_device *rndis ) {
	struct net_device *netdev = rndis->netdev;

	/* Unregister network device */
	unregister_netdev ( netdev );
}

/**
 * Free RNDIS device
 *
 * @v rndis		RNDIS device
 */
void free_rndis ( struct rndis_device *rndis ) {
	struct net_device *netdev = rndis->netdev;

	/* Free network device */
	netdev_nullify ( netdev );
	netdev_put ( netdev );
}