2 * Host Side support for RNDIS Networking Links
3 * Copyright (C) 2005 by David Brownell
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License
16 * along with this program; if not, write to the Free Software
17 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20 // #define DEBUG // error path messages, extra info
21 // #define VERBOSE // more; success messages
23 #include <linux/module.h>
24 #include <linux/sched.h>
25 #include <linux/init.h>
26 #include <linux/netdevice.h>
27 #include <linux/etherdevice.h>
28 #include <linux/ethtool.h>
29 #include <linux/workqueue.h>
30 #include <linux/mii.h>
31 #include <linux/usb.h>
32 #include <linux/usb/cdc.h>
38 * RNDIS is NDIS remoted over USB. It's a MSFT variant of CDC ACM ... of
39 * course ACM was intended for modems, not Ethernet links! USB's standard
40 * for Ethernet links is "CDC Ethernet", which is significantly simpler.
42 * NOTE that Microsoft's "RNDIS 1.0" specification is incomplete. Issues
44 * - Power management in particular relies on information that's scattered
45 * through other documentation, and which is incomplete or incorrect even
47 * - There are various undocumented protocol requirements, such as the
48 * need to send unused garbage in control-OUT messages.
49 * - In some cases, MS-Windows will emit undocumented requests; this
50 * matters more to peripheral implementations than host ones.
52 * For these reasons and others, ** USE OF RNDIS IS STRONGLY DISCOURAGED ** in
53 * favor of such non-proprietary alternatives as CDC Ethernet or the newer (and
54 * currently rare) "Ethernet Emulation Model" (EEM).
58 * CONTROL uses CDC "encapsulated commands" with funky notifications.
59 * - control-out: SEND_ENCAPSULATED
60 * - interrupt-in: RESPONSE_AVAILABLE
61 * - control-in: GET_ENCAPSULATED
63 * We'll try to ignore the RESPONSE_AVAILABLE notifications.
65 struct rndis_msg_hdr
{
66 __le32 msg_type
; /* RNDIS_MSG_* */
68 // followed by data that varies between messages
72 } __attribute__ ((packed
));
74 /* RNDIS defines this (absurdly huge) control timeout */
75 #define RNDIS_CONTROL_TIMEOUT_MS (10 * 1000)
78 #define ccpu2 __constant_cpu_to_le32
80 #define RNDIS_MSG_COMPLETION ccpu2(0x80000000)
82 /* codes for "msg_type" field of rndis messages;
83 * only the data channel uses packet messages (maybe batched);
84 * everything else goes on the control channel.
86 #define RNDIS_MSG_PACKET ccpu2(0x00000001) /* 1-N packets */
87 #define RNDIS_MSG_INIT ccpu2(0x00000002)
88 #define RNDIS_MSG_INIT_C (RNDIS_MSG_INIT|RNDIS_MSG_COMPLETION)
89 #define RNDIS_MSG_HALT ccpu2(0x00000003)
90 #define RNDIS_MSG_QUERY ccpu2(0x00000004)
91 #define RNDIS_MSG_QUERY_C (RNDIS_MSG_QUERY|RNDIS_MSG_COMPLETION)
92 #define RNDIS_MSG_SET ccpu2(0x00000005)
93 #define RNDIS_MSG_SET_C (RNDIS_MSG_SET|RNDIS_MSG_COMPLETION)
94 #define RNDIS_MSG_RESET ccpu2(0x00000006)
95 #define RNDIS_MSG_RESET_C (RNDIS_MSG_RESET|RNDIS_MSG_COMPLETION)
96 #define RNDIS_MSG_INDICATE ccpu2(0x00000007)
97 #define RNDIS_MSG_KEEPALIVE ccpu2(0x00000008)
98 #define RNDIS_MSG_KEEPALIVE_C (RNDIS_MSG_KEEPALIVE|RNDIS_MSG_COMPLETION)
100 /* codes for "status" field of completion messages */
101 #define RNDIS_STATUS_SUCCESS ccpu2(0x00000000)
102 #define RNDIS_STATUS_FAILURE ccpu2(0xc0000001)
103 #define RNDIS_STATUS_INVALID_DATA ccpu2(0xc0010015)
104 #define RNDIS_STATUS_NOT_SUPPORTED ccpu2(0xc00000bb)
105 #define RNDIS_STATUS_MEDIA_CONNECT ccpu2(0x4001000b)
106 #define RNDIS_STATUS_MEDIA_DISCONNECT ccpu2(0x4001000c)
109 struct rndis_data_hdr
{
110 __le32 msg_type
; /* RNDIS_MSG_PACKET */
111 __le32 msg_len
; // rndis_data_hdr + data_len + pad
112 __le32 data_offset
; // 36 -- right after header
113 __le32 data_len
; // ... real packet size
115 __le32 oob_data_offset
; // zero
116 __le32 oob_data_len
; // zero
117 __le32 num_oob
; // zero
118 __le32 packet_data_offset
; // zero
120 __le32 packet_data_len
; // zero
121 __le32 vc_handle
; // zero
122 __le32 reserved
; // zero
123 } __attribute__ ((packed
));
125 struct rndis_init
{ /* OUT */
127 __le32 msg_type
; /* RNDIS_MSG_INIT */
128 __le32 msg_len
; // 24
130 __le32 major_version
; // of rndis (1.0)
131 __le32 minor_version
;
132 __le32 max_transfer_size
;
133 } __attribute__ ((packed
));
135 struct rndis_init_c
{ /* IN */
137 __le32 msg_type
; /* RNDIS_MSG_INIT_C */
141 __le32 major_version
; // of rndis (1.0)
142 __le32 minor_version
;
144 __le32 medium
; // zero == 802.3
145 __le32 max_packets_per_message
;
146 __le32 max_transfer_size
;
147 __le32 packet_alignment
; // max 7; (1<<n) bytes
148 __le32 af_list_offset
; // zero
149 __le32 af_list_size
; // zero
150 } __attribute__ ((packed
));
152 struct rndis_halt
{ /* OUT (no reply) */
154 __le32 msg_type
; /* RNDIS_MSG_HALT */
157 } __attribute__ ((packed
));
159 struct rndis_query
{ /* OUT */
161 __le32 msg_type
; /* RNDIS_MSG_QUERY */
167 /*?*/ __le32 handle
; // zero
168 } __attribute__ ((packed
));
170 struct rndis_query_c
{ /* IN */
172 __le32 msg_type
; /* RNDIS_MSG_QUERY_C */
178 } __attribute__ ((packed
));
180 struct rndis_set
{ /* OUT */
182 __le32 msg_type
; /* RNDIS_MSG_SET */
188 /*?*/ __le32 handle
; // zero
189 } __attribute__ ((packed
));
191 struct rndis_set_c
{ /* IN */
193 __le32 msg_type
; /* RNDIS_MSG_SET_C */
197 } __attribute__ ((packed
));
199 struct rndis_reset
{ /* IN */
201 __le32 msg_type
; /* RNDIS_MSG_RESET */
204 } __attribute__ ((packed
));
206 struct rndis_reset_c
{ /* OUT */
208 __le32 msg_type
; /* RNDIS_MSG_RESET_C */
211 __le32 addressing_lost
;
212 } __attribute__ ((packed
));
214 struct rndis_indicate
{ /* IN (unrequested) */
216 __le32 msg_type
; /* RNDIS_MSG_INDICATE */
221 /**/ __le32 diag_status
;
224 } __attribute__ ((packed
));
226 struct rndis_keepalive
{ /* OUT (optionally IN) */
228 __le32 msg_type
; /* RNDIS_MSG_KEEPALIVE */
231 } __attribute__ ((packed
));
233 struct rndis_keepalive_c
{ /* IN (optionally OUT) */
235 __le32 msg_type
; /* RNDIS_MSG_KEEPALIVE_C */
239 } __attribute__ ((packed
));
241 /* NOTE: about 30 OIDs are "mandatory" for peripherals to support ... and
242 * there are gobs more that may optionally be supported. We'll avoid as much
243 * of that mess as possible.
245 #define OID_802_3_PERMANENT_ADDRESS ccpu2(0x01010101)
246 #define OID_GEN_CURRENT_PACKET_FILTER ccpu2(0x0001010e)
249 * RNDIS notifications from device: command completion; "reverse"
252 static void rndis_status(struct usbnet
*dev
, struct urb
*urb
)
254 devdbg(dev
, "rndis status urb, len %d stat %d",
255 urb
->actual_length
, urb
->status
);
256 // FIXME for keepalives, respond immediately (asynchronously)
257 // if not an RNDIS status, do like cdc_status(dev,urb) does
261 * RPC done RNDIS-style. Caller guarantees:
262 * - message is properly byteswapped
263 * - there's no other request pending
264 * - buf can hold up to 1KB response (required by RNDIS spec)
265 * On return, the first few entries are already byteswapped.
267 * Call context is likely probe(), before interface name is known,
268 * which is why we won't try to use it in the diagnostics.
270 static int rndis_command(struct usbnet
*dev
, struct rndis_msg_hdr
*buf
)
272 struct cdc_state
*info
= (void *) &dev
->data
;
276 u32 xid
= 0, msg_len
, request_id
;
278 /* REVISIT when this gets called from contexts other than probe() or
279 * disconnect(): either serialize, or dispatch responses on xid
282 /* Issue the request; don't bother byteswapping our xid */
283 if (likely(buf
->msg_type
!= RNDIS_MSG_HALT
284 && buf
->msg_type
!= RNDIS_MSG_RESET
)) {
288 buf
->request_id
= (__force __le32
) xid
;
290 retval
= usb_control_msg(dev
->udev
,
291 usb_sndctrlpipe(dev
->udev
, 0),
292 USB_CDC_SEND_ENCAPSULATED_COMMAND
,
293 USB_TYPE_CLASS
| USB_RECIP_INTERFACE
,
294 0, info
->u
->bMasterInterface0
,
295 buf
, le32_to_cpu(buf
->msg_len
),
296 RNDIS_CONTROL_TIMEOUT_MS
);
297 if (unlikely(retval
< 0 || xid
== 0))
300 // FIXME Seems like some devices discard responses when
301 // we time out and cancel our "get response" requests...
302 // so, this is fragile. Probably need to poll for status.
304 /* ignore status endpoint, just poll the control channel;
305 * the request probably completed immediately
307 rsp
= buf
->msg_type
| RNDIS_MSG_COMPLETION
;
308 for (count
= 0; count
< 10; count
++) {
309 memset(buf
, 0, 1024);
310 retval
= usb_control_msg(dev
->udev
,
311 usb_rcvctrlpipe(dev
->udev
, 0),
312 USB_CDC_GET_ENCAPSULATED_RESPONSE
,
313 USB_DIR_IN
| USB_TYPE_CLASS
| USB_RECIP_INTERFACE
,
314 0, info
->u
->bMasterInterface0
,
316 RNDIS_CONTROL_TIMEOUT_MS
);
317 if (likely(retval
>= 8)) {
318 msg_len
= le32_to_cpu(buf
->msg_len
);
319 request_id
= (__force u32
) buf
->request_id
;
320 if (likely(buf
->msg_type
== rsp
)) {
321 if (likely(request_id
== xid
)) {
322 if (unlikely(rsp
== RNDIS_MSG_RESET_C
))
324 if (likely(RNDIS_STATUS_SUCCESS
327 dev_dbg(&info
->control
->dev
,
328 "rndis reply status %08x\n",
329 le32_to_cpu(buf
->status
));
332 dev_dbg(&info
->control
->dev
,
333 "rndis reply id %d expected %d\n",
335 /* then likely retry */
336 } else switch (buf
->msg_type
) {
337 case RNDIS_MSG_INDICATE
: { /* fault */
338 // struct rndis_indicate *msg = (void *)buf;
339 dev_info(&info
->control
->dev
,
340 "rndis fault indication\n");
343 case RNDIS_MSG_KEEPALIVE
: { /* ping */
344 struct rndis_keepalive_c
*msg
= (void *)buf
;
346 msg
->msg_type
= RNDIS_MSG_KEEPALIVE_C
;
347 msg
->msg_len
= ccpu2(sizeof *msg
);
348 msg
->status
= RNDIS_STATUS_SUCCESS
;
349 retval
= usb_control_msg(dev
->udev
,
350 usb_sndctrlpipe(dev
->udev
, 0),
351 USB_CDC_SEND_ENCAPSULATED_COMMAND
,
352 USB_TYPE_CLASS
| USB_RECIP_INTERFACE
,
353 0, info
->u
->bMasterInterface0
,
355 RNDIS_CONTROL_TIMEOUT_MS
);
356 if (unlikely(retval
< 0))
357 dev_dbg(&info
->control
->dev
,
358 "rndis keepalive err %d\n",
363 dev_dbg(&info
->control
->dev
,
364 "unexpected rndis msg %08x len %d\n",
365 le32_to_cpu(buf
->msg_type
), msg_len
);
368 /* device probably issued a protocol stall; ignore */
369 dev_dbg(&info
->control
->dev
,
370 "rndis response error, code %d\n", retval
);
374 dev_dbg(&info
->control
->dev
, "rndis response timeout\n");
378 static int rndis_bind(struct usbnet
*dev
, struct usb_interface
*intf
)
381 struct net_device
*net
= dev
->net
;
384 struct rndis_msg_hdr
*header
;
385 struct rndis_init
*init
;
386 struct rndis_init_c
*init_c
;
387 struct rndis_query
*get
;
388 struct rndis_query_c
*get_c
;
389 struct rndis_set
*set
;
390 struct rndis_set_c
*set_c
;
394 /* we can't rely on i/o from stack working, or stack allocation */
395 u
.buf
= kmalloc(1024, GFP_KERNEL
);
398 retval
= usbnet_generic_cdc_bind(dev
, intf
);
402 net
->hard_header_len
+= sizeof (struct rndis_data_hdr
);
404 /* initialize; max transfer is 16KB at full speed */
405 u
.init
->msg_type
= RNDIS_MSG_INIT
;
406 u
.init
->msg_len
= ccpu2(sizeof *u
.init
);
407 u
.init
->major_version
= ccpu2(1);
408 u
.init
->minor_version
= ccpu2(0);
409 u
.init
->max_transfer_size
= ccpu2(net
->mtu
+ net
->hard_header_len
);
411 retval
= rndis_command(dev
, u
.header
);
412 if (unlikely(retval
< 0)) {
413 /* it might not even be an RNDIS device!! */
414 dev_err(&intf
->dev
, "RNDIS init failed, %d\n", retval
);
416 usb_driver_release_interface(driver_of(intf
),
417 ((struct cdc_state
*)&(dev
->data
))->data
);
420 dev
->hard_mtu
= le32_to_cpu(u
.init_c
->max_transfer_size
);
421 /* REVISIT: peripheral "alignment" request is ignored ... */
422 dev_dbg(&intf
->dev
, "hard mtu %u, align %d\n", dev
->hard_mtu
,
423 1 << le32_to_cpu(u
.init_c
->packet_alignment
));
425 /* get designated host ethernet address */
426 memset(u
.get
, 0, sizeof *u
.get
);
427 u
.get
->msg_type
= RNDIS_MSG_QUERY
;
428 u
.get
->msg_len
= ccpu2(sizeof *u
.get
);
429 u
.get
->oid
= OID_802_3_PERMANENT_ADDRESS
;
431 retval
= rndis_command(dev
, u
.header
);
432 if (unlikely(retval
< 0)) {
433 dev_err(&intf
->dev
, "rndis get ethaddr, %d\n", retval
);
436 tmp
= le32_to_cpu(u
.get_c
->offset
);
437 if (unlikely((tmp
+ 8) > (1024 - ETH_ALEN
)
438 || u
.get_c
->len
!= ccpu2(ETH_ALEN
))) {
439 dev_err(&intf
->dev
, "rndis ethaddr off %d len %d ?\n",
440 tmp
, le32_to_cpu(u
.get_c
->len
));
444 memcpy(net
->dev_addr
, tmp
+ (char *)&u
.get_c
->request_id
, ETH_ALEN
);
446 /* set a nonzero filter to enable data transfers */
447 memset(u
.set
, 0, sizeof *u
.set
);
448 u
.set
->msg_type
= RNDIS_MSG_SET
;
449 u
.set
->msg_len
= ccpu2(4 + sizeof *u
.set
);
450 u
.set
->oid
= OID_GEN_CURRENT_PACKET_FILTER
;
451 u
.set
->len
= ccpu2(4);
452 u
.set
->offset
= ccpu2((sizeof *u
.set
) - 8);
453 *(__le32
*)(u
.buf
+ sizeof *u
.set
) = ccpu2(DEFAULT_FILTER
);
455 retval
= rndis_command(dev
, u
.header
);
456 if (unlikely(retval
< 0)) {
457 dev_err(&intf
->dev
, "rndis set packet filter, %d\n", retval
);
467 static void rndis_unbind(struct usbnet
*dev
, struct usb_interface
*intf
)
469 struct rndis_halt
*halt
;
471 /* try to clear any rndis state/activity (no i/o from stack!) */
472 halt
= kcalloc(1, sizeof *halt
, SLAB_KERNEL
);
474 halt
->msg_type
= RNDIS_MSG_HALT
;
475 halt
->msg_len
= ccpu2(sizeof *halt
);
476 (void) rndis_command(dev
, (void *)halt
);
480 return usbnet_cdc_unbind(dev
, intf
);
484 * DATA -- host must not write zlps
486 static int rndis_rx_fixup(struct usbnet
*dev
, struct sk_buff
*skb
)
488 /* peripheral may have batched packets to us... */
489 while (likely(skb
->len
)) {
490 struct rndis_data_hdr
*hdr
= (void *)skb
->data
;
491 struct sk_buff
*skb2
;
492 u32 msg_len
, data_offset
, data_len
;
494 msg_len
= le32_to_cpu(hdr
->msg_len
);
495 data_offset
= le32_to_cpu(hdr
->data_offset
);
496 data_len
= le32_to_cpu(hdr
->data_len
);
498 /* don't choke if we see oob, per-packet data, etc */
499 if (unlikely(hdr
->msg_type
!= RNDIS_MSG_PACKET
500 || skb
->len
< msg_len
501 || (data_offset
+ data_len
+ 8) > msg_len
)) {
502 dev
->stats
.rx_frame_errors
++;
503 devdbg(dev
, "bad rndis message %d/%d/%d/%d, len %d",
504 le32_to_cpu(hdr
->msg_type
),
505 msg_len
, data_offset
, data_len
, skb
->len
);
508 skb_pull(skb
, 8 + data_offset
);
510 /* at most one packet left? */
511 if (likely((data_len
- skb
->len
) <= sizeof *hdr
)) {
512 skb_trim(skb
, data_len
);
516 /* try to return all the packets in the batch */
517 skb2
= skb_clone(skb
, GFP_ATOMIC
);
520 skb_pull(skb
, msg_len
- sizeof *hdr
);
521 skb_trim(skb2
, data_len
);
522 usbnet_skb_return(dev
, skb2
);
525 /* caller will usbnet_skb_return the remaining packet */
529 static struct sk_buff
*
530 rndis_tx_fixup(struct usbnet
*dev
, struct sk_buff
*skb
, gfp_t flags
)
532 struct rndis_data_hdr
*hdr
;
533 struct sk_buff
*skb2
;
534 unsigned len
= skb
->len
;
536 if (likely(!skb_cloned(skb
))) {
537 int room
= skb_headroom(skb
);
539 /* enough head room as-is? */
540 if (unlikely((sizeof *hdr
) <= room
))
543 /* enough room, but needs to be readjusted? */
544 room
+= skb_tailroom(skb
);
545 if (likely((sizeof *hdr
) <= room
)) {
546 skb
->data
= memmove(skb
->head
+ sizeof *hdr
,
548 skb
->tail
= skb
->data
+ len
;
553 /* create a new skb, with the correct size (and tailpad) */
554 skb2
= skb_copy_expand(skb
, sizeof *hdr
, 1, flags
);
555 dev_kfree_skb_any(skb
);
560 /* fill out the RNDIS header. we won't bother trying to batch
561 * packets; Linux minimizes wasted bandwidth through tx queues.
564 hdr
= (void *) __skb_push(skb
, sizeof *hdr
);
565 memset(hdr
, 0, sizeof *hdr
);
566 hdr
->msg_type
= RNDIS_MSG_PACKET
;
567 hdr
->msg_len
= cpu_to_le32(skb
->len
);
568 hdr
->data_offset
= ccpu2(sizeof(*hdr
) - 8);
569 hdr
->data_len
= cpu_to_le32(len
);
571 /* FIXME make the last packet always be short ... */
576 static const struct driver_info rndis_info
= {
577 .description
= "RNDIS device",
578 .flags
= FLAG_ETHER
| FLAG_FRAMING_RN
,
580 .unbind
= rndis_unbind
,
581 .status
= rndis_status
,
582 .rx_fixup
= rndis_rx_fixup
,
583 .tx_fixup
= rndis_tx_fixup
,
589 /*-------------------------------------------------------------------------*/
591 static const struct usb_device_id products
[] = {
593 /* RNDIS is MSFT's un-official variant of CDC ACM */
594 USB_INTERFACE_INFO(USB_CLASS_COMM
, 2 /* ACM */, 0x0ff),
595 .driver_info
= (unsigned long) &rndis_info
,
599 MODULE_DEVICE_TABLE(usb
, products
);
601 static struct usb_driver rndis_driver
= {
602 .name
= "rndis_host",
603 .id_table
= products
,
604 .probe
= usbnet_probe
,
605 .disconnect
= usbnet_disconnect
,
606 .suspend
= usbnet_suspend
,
607 .resume
= usbnet_resume
,
610 static int __init
rndis_init(void)
612 return usb_register(&rndis_driver
);
614 module_init(rndis_init
);
616 static void __exit
rndis_exit(void)
618 usb_deregister(&rndis_driver
);
620 module_exit(rndis_exit
);
622 MODULE_AUTHOR("David Brownell");
623 MODULE_DESCRIPTION("USB Host side RNDIS driver");
624 MODULE_LICENSE("GPL");