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/config.h>
24 #include <linux/module.h>
25 #include <linux/sched.h>
26 #include <linux/init.h>
27 #include <linux/netdevice.h>
28 #include <linux/etherdevice.h>
29 #include <linux/ethtool.h>
30 #include <linux/workqueue.h>
31 #include <linux/mii.h>
32 #include <linux/usb.h>
33 #include <linux/usb/cdc.h>
39 * RNDIS is NDIS remoted over USB. It's a MSFT variant of CDC ACM ... of
40 * course ACM was intended for modems, not Ethernet links! USB's standard
41 * for Ethernet links is "CDC Ethernet", which is significantly simpler.
43 * NOTE that Microsoft's "RNDIS 1.0" specification is incomplete. Issues
45 * - Power management in particular relies on information that's scattered
46 * through other documentation, and which is incomplete or incorrect even
48 * - There are various undocumented protocol requirements, such as the
49 * need to send unused garbage in control-OUT messages.
50 * - In some cases, MS-Windows will emit undocumented requests; this
51 * matters more to peripheral implementations than host ones.
53 * For these reasons and others, ** USE OF RNDIS IS STRONGLY DISCOURAGED ** in
54 * favor of such non-proprietary alternatives as CDC Ethernet or the newer (and
55 * currently rare) "Ethernet Emulation Model" (EEM).
59 * CONTROL uses CDC "encapsulated commands" with funky notifications.
60 * - control-out: SEND_ENCAPSULATED
61 * - interrupt-in: RESPONSE_AVAILABLE
62 * - control-in: GET_ENCAPSULATED
64 * We'll try to ignore the RESPONSE_AVAILABLE notifications.
66 struct rndis_msg_hdr
{
67 __le32 msg_type
; /* RNDIS_MSG_* */
69 // followed by data that varies between messages
73 } __attribute__ ((packed
));
75 /* RNDIS defines this (absurdly huge) control timeout */
76 #define RNDIS_CONTROL_TIMEOUT_MS (10 * 1000)
79 #define ccpu2 __constant_cpu_to_le32
81 #define RNDIS_MSG_COMPLETION ccpu2(0x80000000)
83 /* codes for "msg_type" field of rndis messages;
84 * only the data channel uses packet messages (maybe batched);
85 * everything else goes on the control channel.
87 #define RNDIS_MSG_PACKET ccpu2(0x00000001) /* 1-N packets */
88 #define RNDIS_MSG_INIT ccpu2(0x00000002)
89 #define RNDIS_MSG_INIT_C (RNDIS_MSG_INIT|RNDIS_MSG_COMPLETION)
90 #define RNDIS_MSG_HALT ccpu2(0x00000003)
91 #define RNDIS_MSG_QUERY ccpu2(0x00000004)
92 #define RNDIS_MSG_QUERY_C (RNDIS_MSG_QUERY|RNDIS_MSG_COMPLETION)
93 #define RNDIS_MSG_SET ccpu2(0x00000005)
94 #define RNDIS_MSG_SET_C (RNDIS_MSG_SET|RNDIS_MSG_COMPLETION)
95 #define RNDIS_MSG_RESET ccpu2(0x00000006)
96 #define RNDIS_MSG_RESET_C (RNDIS_MSG_RESET|RNDIS_MSG_COMPLETION)
97 #define RNDIS_MSG_INDICATE ccpu2(0x00000007)
98 #define RNDIS_MSG_KEEPALIVE ccpu2(0x00000008)
99 #define RNDIS_MSG_KEEPALIVE_C (RNDIS_MSG_KEEPALIVE|RNDIS_MSG_COMPLETION)
101 /* codes for "status" field of completion messages */
102 #define RNDIS_STATUS_SUCCESS ccpu2(0x00000000)
103 #define RNDIS_STATUS_FAILURE ccpu2(0xc0000001)
104 #define RNDIS_STATUS_INVALID_DATA ccpu2(0xc0010015)
105 #define RNDIS_STATUS_NOT_SUPPORTED ccpu2(0xc00000bb)
106 #define RNDIS_STATUS_MEDIA_CONNECT ccpu2(0x4001000b)
107 #define RNDIS_STATUS_MEDIA_DISCONNECT ccpu2(0x4001000c)
110 struct rndis_data_hdr
{
111 __le32 msg_type
; /* RNDIS_MSG_PACKET */
112 __le32 msg_len
; // rndis_data_hdr + data_len + pad
113 __le32 data_offset
; // 36 -- right after header
114 __le32 data_len
; // ... real packet size
116 __le32 oob_data_offset
; // zero
117 __le32 oob_data_len
; // zero
118 __le32 num_oob
; // zero
119 __le32 packet_data_offset
; // zero
121 __le32 packet_data_len
; // zero
122 __le32 vc_handle
; // zero
123 __le32 reserved
; // zero
124 } __attribute__ ((packed
));
126 struct rndis_init
{ /* OUT */
128 __le32 msg_type
; /* RNDIS_MSG_INIT */
129 __le32 msg_len
; // 24
131 __le32 major_version
; // of rndis (1.0)
132 __le32 minor_version
;
133 __le32 max_transfer_size
;
134 } __attribute__ ((packed
));
136 struct rndis_init_c
{ /* IN */
138 __le32 msg_type
; /* RNDIS_MSG_INIT_C */
142 __le32 major_version
; // of rndis (1.0)
143 __le32 minor_version
;
145 __le32 medium
; // zero == 802.3
146 __le32 max_packets_per_message
;
147 __le32 max_transfer_size
;
148 __le32 packet_alignment
; // max 7; (1<<n) bytes
149 __le32 af_list_offset
; // zero
150 __le32 af_list_size
; // zero
151 } __attribute__ ((packed
));
153 struct rndis_halt
{ /* OUT (no reply) */
155 __le32 msg_type
; /* RNDIS_MSG_HALT */
158 } __attribute__ ((packed
));
160 struct rndis_query
{ /* OUT */
162 __le32 msg_type
; /* RNDIS_MSG_QUERY */
168 /*?*/ __le32 handle
; // zero
169 } __attribute__ ((packed
));
171 struct rndis_query_c
{ /* IN */
173 __le32 msg_type
; /* RNDIS_MSG_QUERY_C */
179 } __attribute__ ((packed
));
181 struct rndis_set
{ /* OUT */
183 __le32 msg_type
; /* RNDIS_MSG_SET */
189 /*?*/ __le32 handle
; // zero
190 } __attribute__ ((packed
));
192 struct rndis_set_c
{ /* IN */
194 __le32 msg_type
; /* RNDIS_MSG_SET_C */
198 } __attribute__ ((packed
));
200 struct rndis_reset
{ /* IN */
202 __le32 msg_type
; /* RNDIS_MSG_RESET */
205 } __attribute__ ((packed
));
207 struct rndis_reset_c
{ /* OUT */
209 __le32 msg_type
; /* RNDIS_MSG_RESET_C */
212 __le32 addressing_lost
;
213 } __attribute__ ((packed
));
215 struct rndis_indicate
{ /* IN (unrequested) */
217 __le32 msg_type
; /* RNDIS_MSG_INDICATE */
222 /**/ __le32 diag_status
;
225 } __attribute__ ((packed
));
227 struct rndis_keepalive
{ /* OUT (optionally IN) */
229 __le32 msg_type
; /* RNDIS_MSG_KEEPALIVE */
232 } __attribute__ ((packed
));
234 struct rndis_keepalive_c
{ /* IN (optionally OUT) */
236 __le32 msg_type
; /* RNDIS_MSG_KEEPALIVE_C */
240 } __attribute__ ((packed
));
242 /* NOTE: about 30 OIDs are "mandatory" for peripherals to support ... and
243 * there are gobs more that may optionally be supported. We'll avoid as much
244 * of that mess as possible.
246 #define OID_802_3_PERMANENT_ADDRESS ccpu2(0x01010101)
247 #define OID_GEN_CURRENT_PACKET_FILTER ccpu2(0x0001010e)
250 * RNDIS notifications from device: command completion; "reverse"
253 static void rndis_status(struct usbnet
*dev
, struct urb
*urb
)
255 devdbg(dev
, "rndis status urb, len %d stat %d",
256 urb
->actual_length
, urb
->status
);
257 // FIXME for keepalives, respond immediately (asynchronously)
258 // if not an RNDIS status, do like cdc_status(dev,urb) does
262 * RPC done RNDIS-style. Caller guarantees:
263 * - message is properly byteswapped
264 * - there's no other request pending
265 * - buf can hold up to 1KB response (required by RNDIS spec)
266 * On return, the first few entries are already byteswapped.
268 * Call context is likely probe(), before interface name is known,
269 * which is why we won't try to use it in the diagnostics.
271 static int rndis_command(struct usbnet
*dev
, struct rndis_msg_hdr
*buf
)
273 struct cdc_state
*info
= (void *) &dev
->data
;
277 u32 xid
= 0, msg_len
, request_id
;
279 /* REVISIT when this gets called from contexts other than probe() or
280 * disconnect(): either serialize, or dispatch responses on xid
283 /* Issue the request; don't bother byteswapping our xid */
284 if (likely(buf
->msg_type
!= RNDIS_MSG_HALT
285 && buf
->msg_type
!= RNDIS_MSG_RESET
)) {
289 buf
->request_id
= (__force __le32
) xid
;
291 retval
= usb_control_msg(dev
->udev
,
292 usb_sndctrlpipe(dev
->udev
, 0),
293 USB_CDC_SEND_ENCAPSULATED_COMMAND
,
294 USB_TYPE_CLASS
| USB_RECIP_INTERFACE
,
295 0, info
->u
->bMasterInterface0
,
296 buf
, le32_to_cpu(buf
->msg_len
),
297 RNDIS_CONTROL_TIMEOUT_MS
);
298 if (unlikely(retval
< 0 || xid
== 0))
301 // FIXME Seems like some devices discard responses when
302 // we time out and cancel our "get response" requests...
303 // so, this is fragile. Probably need to poll for status.
305 /* ignore status endpoint, just poll the control channel;
306 * the request probably completed immediately
308 rsp
= buf
->msg_type
| RNDIS_MSG_COMPLETION
;
309 for (count
= 0; count
< 10; count
++) {
310 memset(buf
, 0, 1024);
311 retval
= usb_control_msg(dev
->udev
,
312 usb_rcvctrlpipe(dev
->udev
, 0),
313 USB_CDC_GET_ENCAPSULATED_RESPONSE
,
314 USB_DIR_IN
| USB_TYPE_CLASS
| USB_RECIP_INTERFACE
,
315 0, info
->u
->bMasterInterface0
,
317 RNDIS_CONTROL_TIMEOUT_MS
);
318 if (likely(retval
>= 8)) {
319 msg_len
= le32_to_cpu(buf
->msg_len
);
320 request_id
= (__force u32
) buf
->request_id
;
321 if (likely(buf
->msg_type
== rsp
)) {
322 if (likely(request_id
== xid
)) {
323 if (unlikely(rsp
== RNDIS_MSG_RESET_C
))
325 if (likely(RNDIS_STATUS_SUCCESS
328 dev_dbg(&info
->control
->dev
,
329 "rndis reply status %08x\n",
330 le32_to_cpu(buf
->status
));
333 dev_dbg(&info
->control
->dev
,
334 "rndis reply id %d expected %d\n",
336 /* then likely retry */
337 } else switch (buf
->msg_type
) {
338 case RNDIS_MSG_INDICATE
: { /* fault */
339 // struct rndis_indicate *msg = (void *)buf;
340 dev_info(&info
->control
->dev
,
341 "rndis fault indication\n");
344 case RNDIS_MSG_KEEPALIVE
: { /* ping */
345 struct rndis_keepalive_c
*msg
= (void *)buf
;
347 msg
->msg_type
= RNDIS_MSG_KEEPALIVE_C
;
348 msg
->msg_len
= ccpu2(sizeof *msg
);
349 msg
->status
= RNDIS_STATUS_SUCCESS
;
350 retval
= usb_control_msg(dev
->udev
,
351 usb_sndctrlpipe(dev
->udev
, 0),
352 USB_CDC_SEND_ENCAPSULATED_COMMAND
,
353 USB_TYPE_CLASS
| USB_RECIP_INTERFACE
,
354 0, info
->u
->bMasterInterface0
,
356 RNDIS_CONTROL_TIMEOUT_MS
);
357 if (unlikely(retval
< 0))
358 dev_dbg(&info
->control
->dev
,
359 "rndis keepalive err %d\n",
364 dev_dbg(&info
->control
->dev
,
365 "unexpected rndis msg %08x len %d\n",
366 le32_to_cpu(buf
->msg_type
), msg_len
);
369 /* device probably issued a protocol stall; ignore */
370 dev_dbg(&info
->control
->dev
,
371 "rndis response error, code %d\n", retval
);
375 dev_dbg(&info
->control
->dev
, "rndis response timeout\n");
379 static int rndis_bind(struct usbnet
*dev
, struct usb_interface
*intf
)
382 struct net_device
*net
= dev
->net
;
385 struct rndis_msg_hdr
*header
;
386 struct rndis_init
*init
;
387 struct rndis_init_c
*init_c
;
388 struct rndis_query
*get
;
389 struct rndis_query_c
*get_c
;
390 struct rndis_set
*set
;
391 struct rndis_set_c
*set_c
;
395 /* we can't rely on i/o from stack working, or stack allocation */
396 u
.buf
= kmalloc(1024, GFP_KERNEL
);
399 retval
= usbnet_generic_cdc_bind(dev
, intf
);
403 net
->hard_header_len
+= sizeof (struct rndis_data_hdr
);
405 /* initialize; max transfer is 16KB at full speed */
406 u
.init
->msg_type
= RNDIS_MSG_INIT
;
407 u
.init
->msg_len
= ccpu2(sizeof *u
.init
);
408 u
.init
->major_version
= ccpu2(1);
409 u
.init
->minor_version
= ccpu2(0);
410 u
.init
->max_transfer_size
= ccpu2(net
->mtu
+ net
->hard_header_len
);
412 retval
= rndis_command(dev
, u
.header
);
413 if (unlikely(retval
< 0)) {
414 /* it might not even be an RNDIS device!! */
415 dev_err(&intf
->dev
, "RNDIS init failed, %d\n", retval
);
417 usb_driver_release_interface(driver_of(intf
),
418 ((struct cdc_state
*)&(dev
->data
))->data
);
421 dev
->hard_mtu
= le32_to_cpu(u
.init_c
->max_transfer_size
);
422 /* REVISIT: peripheral "alignment" request is ignored ... */
423 dev_dbg(&intf
->dev
, "hard mtu %u, align %d\n", dev
->hard_mtu
,
424 1 << le32_to_cpu(u
.init_c
->packet_alignment
));
426 /* get designated host ethernet address */
427 memset(u
.get
, 0, sizeof *u
.get
);
428 u
.get
->msg_type
= RNDIS_MSG_QUERY
;
429 u
.get
->msg_len
= ccpu2(sizeof *u
.get
);
430 u
.get
->oid
= OID_802_3_PERMANENT_ADDRESS
;
432 retval
= rndis_command(dev
, u
.header
);
433 if (unlikely(retval
< 0)) {
434 dev_err(&intf
->dev
, "rndis get ethaddr, %d\n", retval
);
437 tmp
= le32_to_cpu(u
.get_c
->offset
);
438 if (unlikely((tmp
+ 8) > (1024 - ETH_ALEN
)
439 || u
.get_c
->len
!= ccpu2(ETH_ALEN
))) {
440 dev_err(&intf
->dev
, "rndis ethaddr off %d len %d ?\n",
441 tmp
, le32_to_cpu(u
.get_c
->len
));
445 memcpy(net
->dev_addr
, tmp
+ (char *)&u
.get_c
->request_id
, ETH_ALEN
);
447 /* set a nonzero filter to enable data transfers */
448 memset(u
.set
, 0, sizeof *u
.set
);
449 u
.set
->msg_type
= RNDIS_MSG_SET
;
450 u
.set
->msg_len
= ccpu2(4 + sizeof *u
.set
);
451 u
.set
->oid
= OID_GEN_CURRENT_PACKET_FILTER
;
452 u
.set
->len
= ccpu2(4);
453 u
.set
->offset
= ccpu2((sizeof *u
.set
) - 8);
454 *(__le32
*)(u
.buf
+ sizeof *u
.set
) = ccpu2(DEFAULT_FILTER
);
456 retval
= rndis_command(dev
, u
.header
);
457 if (unlikely(retval
< 0)) {
458 dev_err(&intf
->dev
, "rndis set packet filter, %d\n", retval
);
468 static void rndis_unbind(struct usbnet
*dev
, struct usb_interface
*intf
)
470 struct rndis_halt
*halt
;
472 /* try to clear any rndis state/activity (no i/o from stack!) */
473 halt
= kcalloc(1, sizeof *halt
, SLAB_KERNEL
);
475 halt
->msg_type
= RNDIS_MSG_HALT
;
476 halt
->msg_len
= ccpu2(sizeof *halt
);
477 (void) rndis_command(dev
, (void *)halt
);
481 return usbnet_cdc_unbind(dev
, intf
);
485 * DATA -- host must not write zlps
487 static int rndis_rx_fixup(struct usbnet
*dev
, struct sk_buff
*skb
)
489 /* peripheral may have batched packets to us... */
490 while (likely(skb
->len
)) {
491 struct rndis_data_hdr
*hdr
= (void *)skb
->data
;
492 struct sk_buff
*skb2
;
493 u32 msg_len
, data_offset
, data_len
;
495 msg_len
= le32_to_cpu(hdr
->msg_len
);
496 data_offset
= le32_to_cpu(hdr
->data_offset
);
497 data_len
= le32_to_cpu(hdr
->data_len
);
499 /* don't choke if we see oob, per-packet data, etc */
500 if (unlikely(hdr
->msg_type
!= RNDIS_MSG_PACKET
501 || skb
->len
< msg_len
502 || (data_offset
+ data_len
+ 8) > msg_len
)) {
503 dev
->stats
.rx_frame_errors
++;
504 devdbg(dev
, "bad rndis message %d/%d/%d/%d, len %d",
505 le32_to_cpu(hdr
->msg_type
),
506 msg_len
, data_offset
, data_len
, skb
->len
);
509 skb_pull(skb
, 8 + data_offset
);
511 /* at most one packet left? */
512 if (likely((data_len
- skb
->len
) <= sizeof *hdr
)) {
513 skb_trim(skb
, data_len
);
517 /* try to return all the packets in the batch */
518 skb2
= skb_clone(skb
, GFP_ATOMIC
);
521 skb_pull(skb
, msg_len
- sizeof *hdr
);
522 skb_trim(skb2
, data_len
);
523 usbnet_skb_return(dev
, skb2
);
526 /* caller will usbnet_skb_return the remaining packet */
530 static struct sk_buff
*
531 rndis_tx_fixup(struct usbnet
*dev
, struct sk_buff
*skb
, gfp_t flags
)
533 struct rndis_data_hdr
*hdr
;
534 struct sk_buff
*skb2
;
535 unsigned len
= skb
->len
;
537 if (likely(!skb_cloned(skb
))) {
538 int room
= skb_headroom(skb
);
540 /* enough head room as-is? */
541 if (unlikely((sizeof *hdr
) <= room
))
544 /* enough room, but needs to be readjusted? */
545 room
+= skb_tailroom(skb
);
546 if (likely((sizeof *hdr
) <= room
)) {
547 skb
->data
= memmove(skb
->head
+ sizeof *hdr
,
549 skb
->tail
= skb
->data
+ len
;
554 /* create a new skb, with the correct size (and tailpad) */
555 skb2
= skb_copy_expand(skb
, sizeof *hdr
, 1, flags
);
556 dev_kfree_skb_any(skb
);
561 /* fill out the RNDIS header. we won't bother trying to batch
562 * packets; Linux minimizes wasted bandwidth through tx queues.
565 hdr
= (void *) __skb_push(skb
, sizeof *hdr
);
566 memset(hdr
, 0, sizeof *hdr
);
567 hdr
->msg_type
= RNDIS_MSG_PACKET
;
568 hdr
->msg_len
= cpu_to_le32(skb
->len
);
569 hdr
->data_offset
= ccpu2(sizeof(*hdr
) - 8);
570 hdr
->data_len
= cpu_to_le32(len
);
572 /* FIXME make the last packet always be short ... */
577 static const struct driver_info rndis_info
= {
578 .description
= "RNDIS device",
579 .flags
= FLAG_ETHER
| FLAG_FRAMING_RN
,
581 .unbind
= rndis_unbind
,
582 .status
= rndis_status
,
583 .rx_fixup
= rndis_rx_fixup
,
584 .tx_fixup
= rndis_tx_fixup
,
590 /*-------------------------------------------------------------------------*/
592 static const struct usb_device_id products
[] = {
594 /* RNDIS is MSFT's un-official variant of CDC ACM */
595 USB_INTERFACE_INFO(USB_CLASS_COMM
, 2 /* ACM */, 0x0ff),
596 .driver_info
= (unsigned long) &rndis_info
,
600 MODULE_DEVICE_TABLE(usb
, products
);
602 static struct usb_driver rndis_driver
= {
603 .name
= "rndis_host",
604 .id_table
= products
,
605 .probe
= usbnet_probe
,
606 .disconnect
= usbnet_disconnect
,
607 .suspend
= usbnet_suspend
,
608 .resume
= usbnet_resume
,
611 static int __init
rndis_init(void)
613 return usb_register(&rndis_driver
);
615 module_init(rndis_init
);
617 static void __exit
rndis_exit(void)
619 usb_deregister(&rndis_driver
);
621 module_exit(rndis_exit
);
623 MODULE_AUTHOR("David Brownell");
624 MODULE_DESCRIPTION("USB Host side RNDIS driver");
625 MODULE_LICENSE("GPL");