src/drivers/net/ncm.h

#ifndef _NCM_H
#define _NCM_H

/** @file
 *
 * CDC-NCM USB Ethernet driver
 *
 */

FILE_LICENCE ( GPL2_OR_LATER );

#include <stdint.h>
#include <ipxe/usb.h>
#include <ipxe/cdc.h>
#include <byteswap.h>
#include "ecm.h"

/** CDC-NCM subclass */
#define USB_SUBCLASS_CDC_NCM 0x0d

/** CDC-NCM interfaces */
enum ncm_interfaces {
	/** Communications interface */
	NCM_INTERFACE_COMMS = 0,
	/** Data interface */
	NCM_INTERFACE_DATA,
	NCM_INTERFACE_COUNT
};

/** Alternate setting for CDC-NCM data interface */
#define NCM_DATA_ALTERNATE 1

/** Get NTB parameters */
#define NCM_GET_NTB_PARAMETERS						\
	( USB_DIR_IN | USB_TYPE_CLASS | USB_RECIP_INTERFACE |		\
	  USB_REQUEST_TYPE ( 0x80 ) )

/** NTB datagram parameters */
struct ncm_ntb_datagram_parameters {
	/** Maximum size */
	uint32_t mtu;
	/** Alignment divisor */
	uint16_t divisor;
	/** Alignment remainder */
	uint16_t remainder;
	/** Alignment modulus */
	uint16_t modulus;
} __attribute__ (( packed ));

/** NTB parameters */
struct ncm_ntb_parameters {
	/** Length */
	uint16_t len;
	/** Supported formats */
	uint16_t formats;
	/** IN datagram parameters */
	struct ncm_ntb_datagram_parameters in;
	/** Reserved */
	uint16_t reserved;
	/** OUT datagram parameters */
	struct ncm_ntb_datagram_parameters out;
	/** Maximum number of datagrams per OUT NTB */
	uint16_t max;
} __attribute__ (( packed ));

/** Set NTB input size */
#define NCM_SET_NTB_INPUT_SIZE						\
	( USB_DIR_OUT | USB_TYPE_CLASS | USB_RECIP_INTERFACE |		\
	  USB_REQUEST_TYPE ( 0x86 ) )

/** Set NTB input size */
struct ncm_set_ntb_input_size {
	/** Maximum size */
	uint32_t mtu;
} __attribute__ (( packed ));

/** Minimum allowed NTB input size */
#define NCM_MIN_NTB_INPUT_SIZE 2048

/** Maximum allowed NTB input size (16-bit) */
#define NCM_MAX_NTB_INPUT_SIZE 65536

/** CDC-NCM transfer header (16-bit) */
struct ncm_transfer_header {
	/** Signature */
	uint32_t magic;
	/** Header length */
	uint16_t header_len;
	/** Sequence number */
	uint16_t sequence;
	/** Total length */
	uint16_t len;
	/** Offset of first datagram pointer */
	uint16_t offset;
} __attribute__ (( packed ));

/** CDC-NCM transfer header magic */
#define NCM_TRANSFER_HEADER_MAGIC 0x484d434eUL

/** CDC-NCM datagram descriptor (16-bit) */
struct ncm_datagram_descriptor {
	/** Starting offset */
	uint16_t offset;
	/** Length */
	uint16_t len;
} __attribute__ (( packed ));

/** CDC-NCM datagram pointer (16-bit) */
struct ncm_datagram_pointer {
	/** Signature */
	uint32_t magic;
	/** Header length */
	uint16_t header_len;
	/** Offset of next datagram pointer */
	uint16_t offset;
	/** Datagram descriptors
	 *
	 * Must be terminated by an empty descriptor.
	 */
	struct ncm_datagram_descriptor desc[0];
} __attribute__ (( packed ));

/** CDC-NCM datagram pointer magic */
#define NCM_DATAGRAM_POINTER_MAGIC 0x304d434eUL

/** CDC-NCM datagram pointer CRC present flag */
#define NCM_DATAGRAM_POINTER_MAGIC_CRC 0x01000000UL

/** NTB constructed for transmitted packets (excluding padding)
 *
 * This is a policy decision.
 */
struct ncm_ntb_header {
	/** Transfer header */
	struct ncm_transfer_header nth;
	/** Datagram pointer */
	struct ncm_datagram_pointer ndp;
	/** Datagram descriptors */
	struct ncm_datagram_descriptor desc[2];
} __attribute__ (( packed ));

/** A CDC-NCM receive ring */
struct ncm_rx_ring {
	/** USB endpoint */
	struct usb_endpoint ep;
	/** I/O buffer size */
	size_t mtu;
	/** Recycled buffer list */
	struct list_head list;
};

/** A CDC-NCM transmit ring */
struct ncm_tx_ring {
	/** USB endpoint */
	struct usb_endpoint ep;
	/** Transmitted packet sequence number */
	uint16_t sequence;
	/** Alignment padding required on transmitted packets */
	size_t padding;
};

/** A CDC-NCM network device */
struct ncm_device {
	/** USB device */
	struct usb_device *usb;
	/** USB bus */
	struct usb_bus *bus;
	/** Network device */
	struct net_device *netdev;

	/** Communications interface */
	unsigned int comms;
	/** Data interface */
	unsigned int data;

	/** Maximum supported NTB input size */
	size_t mtu;

	/** Interrupt ring */
	struct ncm_rx_ring intr;
	/** Bulk IN ring */
	struct ncm_rx_ring in;
	/** Bulk OUT ring */
	struct ncm_tx_ring out;
};

/** Bulk IN ring minimum buffer count
 *
 * This is a policy decision.
 */
#define NCM_IN_MIN_COUNT 3

/** Bulk IN ring minimum total buffer size
 *
 * This is a policy decision.
 */
#define NCM_IN_MIN_SIZE 16384

/** Bulk IN ring maximum total buffer size
 *
 * This is a policy decision.
 */
#define NCM_IN_MAX_SIZE 131072

/** Interrupt ring buffer count
 *
 * This is a policy decision.
 */
#define NCM_INTR_COUNT 2

#endif /* _NCM_H */