net_fd(8)

SYNOPSIS

insmod net_fd [vendor_id=nnnn] [product_id=nnnn] [dbg=
    dbgstring ]

/etc/hotplug/usbd.agent

DESCRIPTION
This module is a USB function module. It operates 802.3 over USB in conjunction with a cooperating USB Class driver. Depending on the way the module is built, it may support two configurations: safe and CDC (communications device class). The latter cooperates better with the typical MS Windows Class drivers.

This driver implements a 32 bit CRC across all Bulk Data Transfers. The CRC is appended to the end of the Bulk Data Transfer.

While USB has a CRC guarding all USB packet sent across the bus this has proved insufficent to guard against all errors on an end-to-end basis. For example some systems can corrupt data being loaded or unloaded from the transmit and receive FIFO's. Adding the CRC allows the receiving driver to drop frames that are received incorrectly. This is the correct behaviour for a network device. Higher level protocols (such as TCP) will ensure that the data is retransmitted.

A Linux Class driver, safe-net.c, is available to use with this Function driver.

HOTPLUG AGENT

The hotplug agent script /etc/hotplug/usbd.agent is called with two parameters:

    INTERFACE = interface name

    ACTION = register
        Called when the network interface is registered.

    ACTION = unregister
        called when the network interface is unregistered.

    ACTION = attach
        Called when the usb device is attached to the network interface.

    ACTION = detach
        Called when the usb device is detached from the network interface.

    ACTION = configured
        Called when the configure setup packet has been processed.

    ACTION = set_interface
        Called when the configure set interface setup packet has been processed.

    ACTION = bus_inactive
        Called when the bus is inactive (no SOF frames for 3ms).

    ACTION = bus_activity
        Called when the bus is active again.

    ACTION = device_destroy
        Called when the device is destroyed.

SAFENET USB CONFIGURATION

For the default safe configuration the following USB device and interface configuration variables are used:
    bDeviceClass        0xff	Vendor Device Class
    bInterfaceClass     0x01	Lineo Interface Class
    bInterfaceSubClass  0x01	Lineo Safe Net Subclass

The bInterfaceProtocol field is used to control the following:
    bInterfaceProtocol  0x01	CRC
    bInterfaceProtocol  0x01	CRC and padding

CDC USB CONFIGURATION

For the CDC safe configuration the following USB device configuration variables are used:
    bDeviceClass        0x02	Communications Device Class

The bInterfaceProtocol field is used to control the following:
    bInterfaceProtocol  0x01	CRC
    bInterfaceProtocol  0x01	CRC and padding

LINUX CONFIGURATION PARAMETERS

These compilation parameters can be used to control the detailed behaviour of the net module.

CONFIG_USBD_NET_VENDORID
    This hex parameter Override VendorID , can be used to set a idVendor device descriptor value which supersedes the default value from the master USB configuration. However, this value itself can be superseded by the vendor_id parameter when the module is loaded. Specific architectures with a known vendor id are pre-set (itsy, calypso, collie, iris).

CONFIG_USD_NET_PRODUCTID
    This hex parameter Override ProductID, can be used to set a idProduct device descriptor value which supersedes the default value from the master USB configuration. However, this value itself is superseded by the product_id parameter when the module is loaded. Specific architectures with a known product id are pre-set (itsy, calypso, collie, iris).

CONFIG_USBD_NET_IFNAME
    This string parameter specifies the interface prefix for the network interface. The default and recommended value is "usb". This creates an interface called usb0. if this value is set to "eth", then the name of the interface is not predictable.

CONFIG_USBD_NET_CDC
    This boolean parameter controls whether the Network Function driver will implement the Communications Device Class configuration. This is used to when support is required for Windows host drivers that implement this.

CONFIG_USBD_NET_OUT_ENDPOINT
    This int parameter is used to set the address of the OUT endpoint. Bulk data is received from the USB host on this endpoint.

CONFIG_USBD_NET_IN_ENDPOINT
    This int parameter is used to set the address of the IN endpoint. Bulk data is transmitted to the USB host on this endpoint.

CONFIG_USBD_NET_INT_ENDPOINT
    This int parameter is used to set the address of the OUT endpoint. Interrupt data is transmitted and received from the USB host on this endpoint.

CONFIG_USBD_NET_OUT_PKTSIZE
    This int parameter sets the maximum size of packets to use on the OUT endpoint.

CONFIG_USBD_NET_IN_PKTSIZE
    This int parameter sets the maximum size of packets to use on the IN endpoint.

CONFIG_USBD_NET_INT_PKTSIZE
    This int parameter sets the maximum size of packets to use on the INT endpoint.

CONFIG_USBD_NO_ZLP_SUPPORT
    This boolean parameter enables the addition of a extra null byte to terminate Bulk Transfers that are an exact multiple of the packetsize.

MODULE PARAMETERS
The following parameters can be set at the time this module is loaded:

dbg This parameter as the format of a colon-separated list of debug levels for various items. There is a sample: dbg="2:init=3:rx" This example sets the default debug level to 2 (normally it is 0), the debug level to 3 for the init (setup) phase and the debug level for rx to 1 (instead of 2, the default set earlier). The exact meaning of the debug output can be determined by comparing the debug output to the source code. By default, this information goes to the console. This behaviour may be changed by appropriate setup of klog(8)and syslog(8).

vendor_id
    This parameter, if supplied, supersedes both the override Vendor ID specified as part of this module, and the master USB vendor ID.

product_id
    This parameter, if supplied, supersedes both the override Product ID specified as part of this module, and the master USB Product ID. Different product ID's should be used to distinguish amongst variants of the net_fd module created by certain kernel configuration parameters (see below).

if_name
    This parameter, if specified, overrides the name of the network device specified. Otherwise, the parameter is taken from the Linux kernel configuration. See below for more information

out_pk_sz
    This sets the maximum size of the received USB data packets.

in_pk_sz
    This sets the maximum size of the transmited USB data packets.

remote_mac_address
    This is the MAC address that the host assigns the interface

local_mac_address
    The USB cable is viewed as a bridge, with the remote_mac_address at the far (host) end,and local_mac_address at the near (peripheral) end.

EXAMPLE

CONFIG_USBD_NET=m
CONFIG_USBD_NET_VENDORID=03f0
CONFIG_USBD_NET_PRODUCTID=2101
CONFIG_USBD_NET_IFNAME="usbd"
CONFIG_USBD_NET_OUT_ENDPOINT=1
CONFIG_USBD_NET_IN_ENDPOINT=2
CONFIG_USBD_NET_INT_ENDPOINT=3
CONFIG_USBD_NET_OUT_PKTSIZE=64
CONFIG_USBD_NET_IN_PKTSIZE=64
CONFIG_USBD_NET_INT_PKTSIZE=16
CONFIG_USBD_NET_CDC=y

BUGS

AUTHOR

Stuart Lynne <sl@lineo.com>

Bruce Balden <balden@lineo.com>

Tom Rushworth <tbr@lineo.com>

SEE ALSO

usbdcore(7), usbdfunc(7), usbdbus(7)

Universal Serial Bus Specification, Revision 2.0

Universal Serial Bus Class Definitions for Communications Devices, Version 1.1