2 * Copyright (C) 2014 Michael Brown <mbrown@fensystems.co.uk>.
4 * This program is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU General Public License as
6 * published by the Free Software Foundation; either version 2 of the
7 * License, or (at your option) any later version.
9 * This program is distributed in the hope that it will be useful, but
10 * WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * General Public License for more details.
14 * You should have received a copy of the GNU General Public License
15 * along with this program; if not, write to the Free Software
16 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
19 * You can also choose to distribute this program under the terms of
20 * the Unmodified Binary Distribution Licence (as given in the file
21 * COPYING.UBDL), provided that you have satisfied its requirements.
24 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
28 #include <ipxe/netdevice.h>
29 #include <ipxe/ethernet.h>
30 #include <ipxe/if_ether.h>
31 #include <ipxe/profile.h>
33 #include <ipxe/usbnet.h>
39 * CDC-NCM USB Ethernet driver
43 /** Interrupt completion profiler */
44 static struct profiler ncm_intr_profiler __profiler =
45 { .name = "ncm.intr" };
47 /** Bulk IN completion profiler */
48 static struct profiler ncm_in_profiler __profiler =
51 /** Bulk IN per-datagram profiler */
52 static struct profiler ncm_in_datagram_profiler __profiler =
53 { .name = "ncm.in_dgram" };
55 /** Bulk OUT profiler */
56 static struct profiler ncm_out_profiler __profiler =
57 { .name = "ncm.out" };
59 /******************************************************************************
61 * CDC-NCM communications interface
63 ******************************************************************************
67 * Complete interrupt transfer
71 * @v rc Completion status code
73 static void ncm_intr_complete ( struct usb_endpoint *ep,
74 struct io_buffer *iobuf, int rc ) {
75 struct ncm_device *ncm = container_of ( ep, struct ncm_device,
77 struct net_device *netdev = ncm->netdev;
78 struct usb_setup_packet *message;
79 size_t len = iob_len ( iobuf );
81 /* Profile completions */
82 profile_start ( &ncm_intr_profiler );
84 /* Ignore packets cancelled when the endpoint closes */
88 /* Ignore packets with errors */
90 DBGC ( ncm, "NCM %p interrupt failed: %s\n",
91 ncm, strerror ( rc ) );
92 DBGC_HDA ( ncm, 0, iobuf->data, iob_len ( iobuf ) );
96 /* Extract message header */
97 if ( len < sizeof ( *message ) ) {
98 DBGC ( ncm, "NCM %p underlength interrupt:\n", ncm );
99 DBGC_HDA ( ncm, 0, iobuf->data, iob_len ( iobuf ) );
103 message = iobuf->data;
105 /* Parse message header */
106 switch ( message->request ) {
108 case cpu_to_le16 ( CDC_NETWORK_CONNECTION ) :
109 if ( message->value ) {
110 DBGC ( ncm, "NCM %p link up\n", ncm );
111 netdev_link_up ( netdev );
113 DBGC ( ncm, "NCM %p link down\n", ncm );
114 netdev_link_down ( netdev );
118 case cpu_to_le16 ( CDC_CONNECTION_SPEED_CHANGE ) :
123 DBGC ( ncm, "NCM %p unrecognised interrupt:\n", ncm );
124 DBGC_HDA ( ncm, 0, iobuf->data, iob_len ( iobuf ) );
128 /* Free I/O buffer */
130 profile_stop ( &ncm_intr_profiler );
135 netdev_rx_err ( netdev, iob_disown ( iobuf ), rc );
141 /** Interrupt endpoint operations */
142 static struct usb_endpoint_driver_operations ncm_intr_operations = {
143 .complete = ncm_intr_complete,
146 /******************************************************************************
148 * CDC-NCM data interface
150 ******************************************************************************
154 * Prefill bulk IN endpoint
156 * @v ncm CDC-NCM device
157 * @ret rc Return status code
159 static int ncm_in_prefill ( struct ncm_device *ncm ) {
160 struct usb_bus *bus = ncm->bus;
165 /* Some devices have a very small number of internal buffers,
166 * and rely on being able to pack multiple packets into each
167 * buffer. We therefore want to use large buffers if
168 * possible. However, large allocations have a reasonable
169 * chance of failure, especially if this is not the first or
170 * only device to be opened.
172 * We therefore attempt to find a usable buffer size, starting
173 * large and working downwards until allocation succeeds.
174 * Smaller buffers will still work, albeit with a higher
175 * chance of packet loss and so lower overall throughput.
177 for ( mtu = ncm->mtu ; mtu >= NCM_MIN_NTB_INPUT_SIZE ; mtu >>= 1 ) {
179 /* Attempt allocation at this MTU */
180 if ( mtu > NCM_MAX_NTB_INPUT_SIZE )
182 if ( mtu > bus->mtu )
184 count = ( NCM_IN_MIN_SIZE / mtu );
185 if ( count < NCM_IN_MIN_COUNT )
186 count = NCM_IN_MIN_COUNT;
187 if ( ( count * mtu ) > NCM_IN_MAX_SIZE )
189 usb_refill_init ( &ncm->usbnet.in, mtu, count );
190 if ( ( rc = usb_prefill ( &ncm->usbnet.in ) ) != 0 ) {
191 DBGC ( ncm, "NCM %p could not prefill %dx %zd-byte "
192 "buffers for bulk IN\n", ncm, count, mtu );
196 DBGC ( ncm, "NCM %p using %dx %zd-byte buffers for bulk IN\n",
201 DBGC ( ncm, "NCM %p could not prefill bulk IN endpoint\n", ncm );
206 * Complete bulk IN transfer
209 * @v iobuf I/O buffer
210 * @v rc Completion status code
212 static void ncm_in_complete ( struct usb_endpoint *ep, struct io_buffer *iobuf,
214 struct ncm_device *ncm = container_of ( ep, struct ncm_device,
216 struct net_device *netdev = ncm->netdev;
217 struct ncm_transfer_header *nth;
218 struct ncm_datagram_pointer *ndp;
219 struct ncm_datagram_descriptor *desc;
220 struct io_buffer *pkt;
221 unsigned int remaining;
229 /* Profile overall bulk IN completion */
230 profile_start ( &ncm_in_profiler );
232 /* Ignore packets cancelled when the endpoint closes */
236 /* Record USB errors against the network device */
238 DBGC ( ncm, "NCM %p bulk IN failed: %s\n",
239 ncm, strerror ( rc ) );
243 /* Locate transfer header */
244 len = iob_len ( iobuf );
245 if ( sizeof ( *nth ) > len ) {
246 DBGC ( ncm, "NCM %p packet too short for NTH:\n", ncm );
252 /* Locate datagram pointer */
253 ndp_offset = le16_to_cpu ( nth->offset );
254 if ( ( ndp_offset + sizeof ( *ndp ) ) > len ) {
255 DBGC ( ncm, "NCM %p packet too short for NDP:\n", ncm );
259 ndp = ( iobuf->data + ndp_offset );
260 ndp_len = le16_to_cpu ( ndp->header_len );
261 if ( ndp_len < offsetof ( typeof ( *ndp ), desc ) ) {
262 DBGC ( ncm, "NCM %p NDP header length too short:\n", ncm );
266 if ( ( ndp_offset + ndp_len ) > len ) {
267 DBGC ( ncm, "NCM %p packet too short for NDP:\n", ncm );
272 /* Process datagrams */
273 remaining = ( ( ndp_len - offsetof ( typeof ( *ndp ), desc ) ) /
274 sizeof ( ndp->desc[0] ) );
275 for ( desc = ndp->desc ; remaining && desc->offset ; remaining-- ) {
277 /* Profile individual datagrams */
278 profile_start ( &ncm_in_datagram_profiler );
280 /* Locate datagram */
281 pkt_offset = le16_to_cpu ( desc->offset );
282 pkt_len = le16_to_cpu ( desc->len );
283 if ( pkt_len < ETH_HLEN ) {
284 DBGC ( ncm, "NCM %p underlength datagram:\n", ncm );
288 if ( ( pkt_offset + pkt_len ) > len ) {
289 DBGC ( ncm, "NCM %p datagram exceeds packet:\n", ncm );
294 /* Move to next descriptor */
297 /* Copy data to a new I/O buffer. Our USB buffers may
298 * be very large and so we choose to recycle the
299 * buffers directly rather than attempt reallocation
300 * while the device is running. We therefore copy the
301 * data to a new I/O buffer even if this is the only
302 * (or last) packet within the buffer.
304 * We reserve enough space at the start of each buffer
305 * to allow for our own transmission header, to
306 * support protocols such as ARP which may modify the
307 * received packet and reuse the same I/O buffer for
310 headroom = ( sizeof ( struct ncm_ntb_header ) + ncm->padding );
311 pkt = alloc_iob ( headroom + pkt_len );
313 /* Record error and continue */
314 netdev_rx_err ( netdev, NULL, -ENOMEM );
317 iob_reserve ( pkt, headroom );
318 memcpy ( iob_put ( pkt, pkt_len ),
319 ( iobuf->data + pkt_offset ), pkt_len );
321 /* Strip CRC, if present */
322 if ( ndp->magic & cpu_to_le32 ( NCM_DATAGRAM_POINTER_MAGIC_CRC))
323 iob_unput ( pkt, 4 /* CRC32 */ );
325 /* Hand off to network stack */
326 netdev_rx ( netdev, pkt );
327 profile_stop ( &ncm_in_datagram_profiler );
330 /* Recycle I/O buffer */
331 usb_recycle ( &ncm->usbnet.in, iobuf );
332 profile_stop ( &ncm_in_profiler );
337 /* Record error against network device */
338 DBGC_HDA ( ncm, 0, iobuf->data, iob_len ( iobuf ) );
339 netdev_rx_err ( netdev, NULL, rc );
341 usb_recycle ( &ncm->usbnet.in, iobuf );
344 /** Bulk IN endpoint operations */
345 static struct usb_endpoint_driver_operations ncm_in_operations = {
346 .complete = ncm_in_complete,
352 * @v ncm CDC-NCM device
353 * @v iobuf I/O buffer
354 * @ret rc Return status code
356 static int ncm_out_transmit ( struct ncm_device *ncm,
357 struct io_buffer *iobuf ) {
358 struct ncm_ntb_header *header;
359 size_t len = iob_len ( iobuf );
360 size_t header_len = ( sizeof ( *header ) + ncm->padding );
363 /* Profile transmissions */
364 profile_start ( &ncm_out_profiler );
367 if ( ( rc = iob_ensure_headroom ( iobuf, header_len ) ) != 0 )
369 header = iob_push ( iobuf, header_len );
371 /* Populate header */
372 header->nth.magic = cpu_to_le32 ( NCM_TRANSFER_HEADER_MAGIC );
373 header->nth.header_len = cpu_to_le16 ( sizeof ( header->nth ) );
374 header->nth.sequence = cpu_to_le16 ( ncm->sequence );
375 header->nth.len = cpu_to_le16 ( iob_len ( iobuf ) );
377 cpu_to_le16 ( offsetof ( typeof ( *header ), ndp ) );
378 header->ndp.magic = cpu_to_le32 ( NCM_DATAGRAM_POINTER_MAGIC );
379 header->ndp.header_len = cpu_to_le16 ( sizeof ( header->ndp ) +
380 sizeof ( header->desc ) );
381 header->ndp.offset = cpu_to_le16 ( 0 );
382 header->desc[0].offset = cpu_to_le16 ( header_len );
383 header->desc[0].len = cpu_to_le16 ( len );
384 memset ( &header->desc[1], 0, sizeof ( header->desc[1] ) );
386 /* Enqueue I/O buffer */
387 if ( ( rc = usb_stream ( &ncm->usbnet.out, iobuf, 0 ) ) != 0 )
390 /* Increment sequence number */
393 profile_stop ( &ncm_out_profiler );
398 * Complete bulk OUT transfer
401 * @v iobuf I/O buffer
402 * @v rc Completion status code
404 static void ncm_out_complete ( struct usb_endpoint *ep, struct io_buffer *iobuf,
406 struct ncm_device *ncm = container_of ( ep, struct ncm_device,
408 struct net_device *netdev = ncm->netdev;
410 /* Report TX completion */
411 netdev_tx_complete_err ( netdev, iobuf, rc );
414 /** Bulk OUT endpoint operations */
415 static struct usb_endpoint_driver_operations ncm_out_operations = {
416 .complete = ncm_out_complete,
419 /******************************************************************************
421 * Network device interface
423 ******************************************************************************
427 * Open network device
429 * @v netdev Network device
430 * @ret rc Return status code
432 static int ncm_open ( struct net_device *netdev ) {
433 struct ncm_device *ncm = netdev->priv;
434 struct usb_device *usb = ncm->usb;
435 struct ncm_set_ntb_input_size size;
438 /* Reset sequence number */
441 /* Prefill I/O buffers */
442 if ( ( rc = ncm_in_prefill ( ncm ) ) != 0 )
445 /* Set maximum input size */
446 memset ( &size, 0, sizeof ( size ) );
447 size.mtu = cpu_to_le32 ( ncm->usbnet.in.len );
448 if ( ( rc = usb_control ( usb, NCM_SET_NTB_INPUT_SIZE, 0,
449 ncm->usbnet.comms, &size,
450 sizeof ( size ) ) ) != 0 ) {
451 DBGC ( ncm, "NCM %p could not set input size to %zd: %s\n",
452 ncm, ncm->usbnet.in.len, strerror ( rc ) );
453 goto err_set_ntb_input_size;
456 /* Open USB network device */
457 if ( ( rc = usbnet_open ( &ncm->usbnet ) ) != 0 ) {
458 DBGC ( ncm, "NCM %p could not open: %s\n",
459 ncm, strerror ( rc ) );
465 usbnet_close ( &ncm->usbnet );
467 err_set_ntb_input_size:
468 usb_flush ( &ncm->usbnet.in );
474 * Close network device
476 * @v netdev Network device
478 static void ncm_close ( struct net_device *netdev ) {
479 struct ncm_device *ncm = netdev->priv;
481 /* Close USB network device */
482 usbnet_close ( &ncm->usbnet );
488 * @v netdev Network device
489 * @v iobuf I/O buffer
490 * @ret rc Return status code
492 static int ncm_transmit ( struct net_device *netdev,
493 struct io_buffer *iobuf ) {
494 struct ncm_device *ncm = netdev->priv;
497 /* Transmit packet */
498 if ( ( rc = ncm_out_transmit ( ncm, iobuf ) ) != 0 )
505 * Poll for completed and received packets
507 * @v netdev Network device
509 static void ncm_poll ( struct net_device *netdev ) {
510 struct ncm_device *ncm = netdev->priv;
514 usb_poll ( ncm->bus );
516 /* Refill endpoints */
517 if ( ( rc = usbnet_refill ( &ncm->usbnet ) ) != 0 )
518 netdev_rx_err ( netdev, NULL, rc );
522 /** CDC-NCM network device operations */
523 static struct net_device_operations ncm_operations = {
526 .transmit = ncm_transmit,
530 /******************************************************************************
534 ******************************************************************************
540 * @v func USB function
541 * @v config Configuration descriptor
542 * @ret rc Return status code
544 static int ncm_probe ( struct usb_function *func,
545 struct usb_configuration_descriptor *config ) {
546 struct usb_device *usb = func->usb;
547 struct net_device *netdev;
548 struct ncm_device *ncm;
549 struct usb_interface_descriptor *comms;
550 struct ecm_ethernet_descriptor *ethernet;
551 struct ncm_ntb_parameters params;
554 /* Allocate and initialise structure */
555 netdev = alloc_etherdev ( sizeof ( *ncm ) );
560 netdev_init ( netdev, &ncm_operations );
561 netdev->dev = &func->dev;
563 memset ( ncm, 0, sizeof ( *ncm ) );
565 ncm->bus = usb->port->hub->bus;
566 ncm->netdev = netdev;
567 usbnet_init ( &ncm->usbnet, func, &ncm_intr_operations,
568 &ncm_in_operations, &ncm_out_operations );
569 usb_refill_init ( &ncm->usbnet.intr, 0, NCM_INTR_COUNT );
570 DBGC ( ncm, "NCM %p on %s\n", ncm, func->name );
572 /* Describe USB network device */
573 if ( ( rc = usbnet_describe ( &ncm->usbnet, config ) ) != 0 ) {
574 DBGC ( ncm, "NCM %p could not describe: %s\n",
575 ncm, strerror ( rc ) );
579 /* Locate Ethernet descriptor */
580 comms = usb_interface_descriptor ( config, ncm->usbnet.comms, 0 );
581 assert ( comms != NULL );
582 ethernet = ecm_ethernet_descriptor ( config, comms );
584 DBGC ( ncm, "NCM %p has no Ethernet descriptor\n", ncm );
589 /* Fetch MAC address */
590 if ( ( rc = ecm_fetch_mac ( usb, ethernet, netdev->hw_addr ) ) != 0 ) {
591 DBGC ( ncm, "NCM %p could not fetch MAC address: %s\n",
592 ncm, strerror ( rc ) );
596 /* Get NTB parameters */
597 if ( ( rc = usb_control ( usb, NCM_GET_NTB_PARAMETERS, 0,
598 ncm->usbnet.comms, ¶ms,
599 sizeof ( params ) ) ) != 0 ) {
600 DBGC ( ncm, "NCM %p could not get NTB parameters: %s\n",
601 ncm, strerror ( rc ) );
602 goto err_ntb_parameters;
605 /* Get maximum supported input size */
606 ncm->mtu = le32_to_cpu ( params.in.mtu );
607 DBGC2 ( ncm, "NCM %p maximum IN size is %zd bytes\n", ncm, ncm->mtu );
609 /* Calculate transmit padding */
610 ncm->padding = ( ( le16_to_cpu ( params.out.remainder ) -
611 sizeof ( struct ncm_ntb_header ) - ETH_HLEN ) &
612 ( le16_to_cpu ( params.out.divisor ) - 1 ) );
613 DBGC2 ( ncm, "NCM %p using %zd-byte transmit padding\n",
615 assert ( ( ( sizeof ( struct ncm_ntb_header ) + ncm->padding +
616 ETH_HLEN ) % le16_to_cpu ( params.out.divisor ) ) ==
617 le16_to_cpu ( params.out.remainder ) );
619 /* Register network device */
620 if ( ( rc = register_netdev ( netdev ) ) != 0 )
623 usb_func_set_drvdata ( func, ncm );
626 unregister_netdev ( netdev );
632 netdev_nullify ( netdev );
633 netdev_put ( netdev );
641 * @v func USB function
643 static void ncm_remove ( struct usb_function *func ) {
644 struct ncm_device *ncm = usb_func_get_drvdata ( func );
645 struct net_device *netdev = ncm->netdev;
647 unregister_netdev ( netdev );
648 netdev_nullify ( netdev );
649 netdev_put ( netdev );
652 /** CDC-NCM device IDs */
653 static struct usb_device_id ncm_ids[] = {
656 .vendor = USB_ANY_ID,
657 .product = USB_ANY_ID,
659 .class = USB_CLASS_CDC,
660 .subclass = USB_SUBCLASS_CDC_NCM,
666 /** CDC-NCM driver */
667 struct usb_driver ncm_driver __usb_driver = {
669 .id_count = ( sizeof ( ncm_ids ) / sizeof ( ncm_ids[0] ) ),
671 .remove = ncm_remove,