2 * f_ncm.c -- USB CDC Network (NCM) link function driver
4 * Copyright (C) 2010 Nokia Corporation
5 * Contact: Yauheni Kaliuta <yauheni.kaliuta@nokia.com>
7 * The driver borrows from f_ecm.c which is:
9 * Copyright (C) 2003-2005,2008 David Brownell
10 * Copyright (C) 2008 Nokia Corporation
12 * This program is free software; you can redistribute it and/or modify
13 * it under the terms of the GNU General Public License as published by
14 * the Free Software Foundation; either version 2 of the License, or
15 * (at your option) any later version.
17 * This program is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 * GNU General Public License for more details.
22 * You should have received a copy of the GNU General Public License
23 * along with this program; if not, write to the Free Software
24 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
27 #include <linux/kernel.h>
28 #include <linux/device.h>
29 #include <linux/etherdevice.h>
30 #include <linux/crc32.h>
32 #include <linux/usb/cdc.h>
37 * This function is a "CDC Network Control Model" (CDC NCM) Ethernet link.
38 * NCM is intended to be used with high-speed network attachments.
40 * Note that NCM requires the use of "alternate settings" for its data
41 * interface. This means that the set_alt() method has real work to do,
42 * and also means that a get_alt() method is required.
45 /* to trigger crc/non-crc ndp signature */
47 #define NCM_NDP_HDR_CRC_MASK 0x01000000
48 #define NCM_NDP_HDR_CRC 0x01000000
49 #define NCM_NDP_HDR_NOCRC 0x00000000
52 struct usb_endpoint_descriptor
*in
;
53 struct usb_endpoint_descriptor
*out
;
54 struct usb_endpoint_descriptor
*notify
;
57 enum ncm_notify_state
{
58 NCM_NOTIFY_NONE
, /* don't notify */
59 NCM_NOTIFY_CONNECT
, /* issue CONNECT next */
60 NCM_NOTIFY_SPEED
, /* issue SPEED_CHANGE next */
69 struct ncm_ep_descs fs
;
70 struct ncm_ep_descs hs
;
72 struct usb_ep
*notify
;
73 struct usb_request
*notify_req
;
77 struct ndp_parser_opts
*parser_opts
;
81 * for notification, it is accessed from both
82 * callback and ethernet open/close
87 static inline struct f_ncm
*func_to_ncm(struct usb_function
*f
)
89 return container_of(f
, struct f_ncm
, port
.func
);
92 /* peak (theoretical) bulk transfer rate in bits-per-second */
93 static inline unsigned ncm_bitrate(struct usb_gadget
*g
)
95 if (gadget_is_dualspeed(g
) && g
->speed
== USB_SPEED_HIGH
)
96 return 13 * 512 * 8 * 1000 * 8;
98 return 19 * 64 * 1 * 1000 * 8;
101 /*-------------------------------------------------------------------------*/
104 * We cannot group frames so use just the minimal size which ok to put
105 * one max-size ethernet frame.
106 * If the host can group frames, allow it to do that, 16K is selected,
107 * because it's used by default by the current linux host driver
109 #define NTB_DEFAULT_IN_SIZE USB_CDC_NCM_NTB_MIN_IN_SIZE
110 #define NTB_OUT_SIZE 16384
113 * skbs of size less than that will not be aligned
114 * to NCM's dwNtbInMaxSize to save bus bandwidth
117 #define MAX_TX_NONFIXED (512 * 3)
119 #define FORMATS_SUPPORTED (USB_CDC_NCM_NTB16_SUPPORTED | \
120 USB_CDC_NCM_NTB32_SUPPORTED)
122 static struct usb_cdc_ncm_ntb_parameters ntb_parameters
= {
123 .wLength
= sizeof ntb_parameters
,
124 .bmNtbFormatsSupported
= cpu_to_le16(FORMATS_SUPPORTED
),
125 .dwNtbInMaxSize
= cpu_to_le32(NTB_DEFAULT_IN_SIZE
),
126 .wNdpInDivisor
= cpu_to_le16(4),
127 .wNdpInPayloadRemainder
= cpu_to_le16(0),
128 .wNdpInAlignment
= cpu_to_le16(4),
130 .dwNtbOutMaxSize
= cpu_to_le32(NTB_OUT_SIZE
),
131 .wNdpOutDivisor
= cpu_to_le16(4),
132 .wNdpOutPayloadRemainder
= cpu_to_le16(0),
133 .wNdpOutAlignment
= cpu_to_le16(4),
137 * Use wMaxPacketSize big enough to fit CDC_NOTIFY_SPEED_CHANGE in one
138 * packet, to simplify cancellation; and a big transfer interval, to
139 * waste less bandwidth.
142 #define LOG2_STATUS_INTERVAL_MSEC 5 /* 1 << 5 == 32 msec */
143 #define NCM_STATUS_BYTECOUNT 16 /* 8 byte header + data */
145 static struct usb_interface_assoc_descriptor ncm_iad_desc __initdata
= {
146 .bLength
= sizeof ncm_iad_desc
,
147 .bDescriptorType
= USB_DT_INTERFACE_ASSOCIATION
,
149 /* .bFirstInterface = DYNAMIC, */
150 .bInterfaceCount
= 2, /* control + data */
151 .bFunctionClass
= USB_CLASS_COMM
,
152 .bFunctionSubClass
= USB_CDC_SUBCLASS_NCM
,
153 .bFunctionProtocol
= USB_CDC_PROTO_NONE
,
154 /* .iFunction = DYNAMIC */
157 /* interface descriptor: */
159 static struct usb_interface_descriptor ncm_control_intf __initdata
= {
160 .bLength
= sizeof ncm_control_intf
,
161 .bDescriptorType
= USB_DT_INTERFACE
,
163 /* .bInterfaceNumber = DYNAMIC */
165 .bInterfaceClass
= USB_CLASS_COMM
,
166 .bInterfaceSubClass
= USB_CDC_SUBCLASS_NCM
,
167 .bInterfaceProtocol
= USB_CDC_PROTO_NONE
,
168 /* .iInterface = DYNAMIC */
171 static struct usb_cdc_header_desc ncm_header_desc __initdata
= {
172 .bLength
= sizeof ncm_header_desc
,
173 .bDescriptorType
= USB_DT_CS_INTERFACE
,
174 .bDescriptorSubType
= USB_CDC_HEADER_TYPE
,
176 .bcdCDC
= cpu_to_le16(0x0110),
179 static struct usb_cdc_union_desc ncm_union_desc __initdata
= {
180 .bLength
= sizeof(ncm_union_desc
),
181 .bDescriptorType
= USB_DT_CS_INTERFACE
,
182 .bDescriptorSubType
= USB_CDC_UNION_TYPE
,
183 /* .bMasterInterface0 = DYNAMIC */
184 /* .bSlaveInterface0 = DYNAMIC */
187 static struct usb_cdc_ether_desc ecm_desc __initdata
= {
188 .bLength
= sizeof ecm_desc
,
189 .bDescriptorType
= USB_DT_CS_INTERFACE
,
190 .bDescriptorSubType
= USB_CDC_ETHERNET_TYPE
,
192 /* this descriptor actually adds value, surprise! */
193 /* .iMACAddress = DYNAMIC */
194 .bmEthernetStatistics
= cpu_to_le32(0), /* no statistics */
195 .wMaxSegmentSize
= cpu_to_le16(ETH_FRAME_LEN
),
196 .wNumberMCFilters
= cpu_to_le16(0),
197 .bNumberPowerFilters
= 0,
200 #define NCAPS (USB_CDC_NCM_NCAP_ETH_FILTER | USB_CDC_NCM_NCAP_CRC_MODE)
202 static struct usb_cdc_ncm_desc ncm_desc __initdata
= {
203 .bLength
= sizeof ncm_desc
,
204 .bDescriptorType
= USB_DT_CS_INTERFACE
,
205 .bDescriptorSubType
= USB_CDC_NCM_TYPE
,
207 .bcdNcmVersion
= cpu_to_le16(0x0100),
208 /* can process SetEthernetPacketFilter */
209 .bmNetworkCapabilities
= NCAPS
,
212 /* the default data interface has no endpoints ... */
214 static struct usb_interface_descriptor ncm_data_nop_intf __initdata
= {
215 .bLength
= sizeof ncm_data_nop_intf
,
216 .bDescriptorType
= USB_DT_INTERFACE
,
218 .bInterfaceNumber
= 1,
219 .bAlternateSetting
= 0,
221 .bInterfaceClass
= USB_CLASS_CDC_DATA
,
222 .bInterfaceSubClass
= 0,
223 .bInterfaceProtocol
= USB_CDC_NCM_PROTO_NTB
,
224 /* .iInterface = DYNAMIC */
227 /* ... but the "real" data interface has two bulk endpoints */
229 static struct usb_interface_descriptor ncm_data_intf __initdata
= {
230 .bLength
= sizeof ncm_data_intf
,
231 .bDescriptorType
= USB_DT_INTERFACE
,
233 .bInterfaceNumber
= 1,
234 .bAlternateSetting
= 1,
236 .bInterfaceClass
= USB_CLASS_CDC_DATA
,
237 .bInterfaceSubClass
= 0,
238 .bInterfaceProtocol
= USB_CDC_NCM_PROTO_NTB
,
239 /* .iInterface = DYNAMIC */
242 /* full speed support: */
244 static struct usb_endpoint_descriptor fs_ncm_notify_desc __initdata
= {
245 .bLength
= USB_DT_ENDPOINT_SIZE
,
246 .bDescriptorType
= USB_DT_ENDPOINT
,
248 .bEndpointAddress
= USB_DIR_IN
,
249 .bmAttributes
= USB_ENDPOINT_XFER_INT
,
250 .wMaxPacketSize
= cpu_to_le16(NCM_STATUS_BYTECOUNT
),
251 .bInterval
= 1 << LOG2_STATUS_INTERVAL_MSEC
,
254 static struct usb_endpoint_descriptor fs_ncm_in_desc __initdata
= {
255 .bLength
= USB_DT_ENDPOINT_SIZE
,
256 .bDescriptorType
= USB_DT_ENDPOINT
,
258 .bEndpointAddress
= USB_DIR_IN
,
259 .bmAttributes
= USB_ENDPOINT_XFER_BULK
,
262 static struct usb_endpoint_descriptor fs_ncm_out_desc __initdata
= {
263 .bLength
= USB_DT_ENDPOINT_SIZE
,
264 .bDescriptorType
= USB_DT_ENDPOINT
,
266 .bEndpointAddress
= USB_DIR_OUT
,
267 .bmAttributes
= USB_ENDPOINT_XFER_BULK
,
270 static struct usb_descriptor_header
*ncm_fs_function
[] __initdata
= {
271 (struct usb_descriptor_header
*) &ncm_iad_desc
,
272 /* CDC NCM control descriptors */
273 (struct usb_descriptor_header
*) &ncm_control_intf
,
274 (struct usb_descriptor_header
*) &ncm_header_desc
,
275 (struct usb_descriptor_header
*) &ncm_union_desc
,
276 (struct usb_descriptor_header
*) &ecm_desc
,
277 (struct usb_descriptor_header
*) &ncm_desc
,
278 (struct usb_descriptor_header
*) &fs_ncm_notify_desc
,
279 /* data interface, altsettings 0 and 1 */
280 (struct usb_descriptor_header
*) &ncm_data_nop_intf
,
281 (struct usb_descriptor_header
*) &ncm_data_intf
,
282 (struct usb_descriptor_header
*) &fs_ncm_in_desc
,
283 (struct usb_descriptor_header
*) &fs_ncm_out_desc
,
287 /* high speed support: */
289 static struct usb_endpoint_descriptor hs_ncm_notify_desc __initdata
= {
290 .bLength
= USB_DT_ENDPOINT_SIZE
,
291 .bDescriptorType
= USB_DT_ENDPOINT
,
293 .bEndpointAddress
= USB_DIR_IN
,
294 .bmAttributes
= USB_ENDPOINT_XFER_INT
,
295 .wMaxPacketSize
= cpu_to_le16(NCM_STATUS_BYTECOUNT
),
296 .bInterval
= LOG2_STATUS_INTERVAL_MSEC
+ 4,
298 static struct usb_endpoint_descriptor hs_ncm_in_desc __initdata
= {
299 .bLength
= USB_DT_ENDPOINT_SIZE
,
300 .bDescriptorType
= USB_DT_ENDPOINT
,
302 .bEndpointAddress
= USB_DIR_IN
,
303 .bmAttributes
= USB_ENDPOINT_XFER_BULK
,
304 .wMaxPacketSize
= cpu_to_le16(512),
307 static struct usb_endpoint_descriptor hs_ncm_out_desc __initdata
= {
308 .bLength
= USB_DT_ENDPOINT_SIZE
,
309 .bDescriptorType
= USB_DT_ENDPOINT
,
311 .bEndpointAddress
= USB_DIR_OUT
,
312 .bmAttributes
= USB_ENDPOINT_XFER_BULK
,
313 .wMaxPacketSize
= cpu_to_le16(512),
316 static struct usb_descriptor_header
*ncm_hs_function
[] __initdata
= {
317 (struct usb_descriptor_header
*) &ncm_iad_desc
,
318 /* CDC NCM control descriptors */
319 (struct usb_descriptor_header
*) &ncm_control_intf
,
320 (struct usb_descriptor_header
*) &ncm_header_desc
,
321 (struct usb_descriptor_header
*) &ncm_union_desc
,
322 (struct usb_descriptor_header
*) &ecm_desc
,
323 (struct usb_descriptor_header
*) &ncm_desc
,
324 (struct usb_descriptor_header
*) &hs_ncm_notify_desc
,
325 /* data interface, altsettings 0 and 1 */
326 (struct usb_descriptor_header
*) &ncm_data_nop_intf
,
327 (struct usb_descriptor_header
*) &ncm_data_intf
,
328 (struct usb_descriptor_header
*) &hs_ncm_in_desc
,
329 (struct usb_descriptor_header
*) &hs_ncm_out_desc
,
333 /* string descriptors: */
335 #define STRING_CTRL_IDX 0
336 #define STRING_MAC_IDX 1
337 #define STRING_DATA_IDX 2
338 #define STRING_IAD_IDX 3
340 static struct usb_string ncm_string_defs
[] = {
341 [STRING_CTRL_IDX
].s
= "CDC Network Control Model (NCM)",
342 [STRING_MAC_IDX
].s
= NULL
/* DYNAMIC */,
343 [STRING_DATA_IDX
].s
= "CDC Network Data",
344 [STRING_IAD_IDX
].s
= "CDC NCM",
345 { } /* end of list */
348 static struct usb_gadget_strings ncm_string_table
= {
349 .language
= 0x0409, /* en-us */
350 .strings
= ncm_string_defs
,
353 static struct usb_gadget_strings
*ncm_strings
[] = {
359 * Here are options for NCM Datagram Pointer table (NDP) parser.
360 * There are 2 different formats: NDP16 and NDP32 in the spec (ch. 3),
361 * in NDP16 offsets and sizes fields are 1 16bit word wide,
362 * in NDP32 -- 2 16bit words wide. Also signatures are different.
363 * To make the parser code the same, put the differences in the structure,
364 * and switch pointers to the structures when the format is changed.
367 struct ndp_parser_opts
{
372 unsigned ndplen_align
;
373 /* sizes in u16 units */
374 unsigned dgram_item_len
; /* index or length */
375 unsigned block_length
;
379 unsigned next_fp_index
;
382 #define INIT_NDP16_OPTS { \
383 .nth_sign = USB_CDC_NCM_NTH16_SIGN, \
384 .ndp_sign = USB_CDC_NCM_NDP16_NOCRC_SIGN, \
385 .nth_size = sizeof(struct usb_cdc_ncm_nth16), \
386 .ndp_size = sizeof(struct usb_cdc_ncm_ndp16), \
388 .dgram_item_len = 1, \
393 .next_fp_index = 1, \
397 #define INIT_NDP32_OPTS { \
398 .nth_sign = USB_CDC_NCM_NTH32_SIGN, \
399 .ndp_sign = USB_CDC_NCM_NDP32_NOCRC_SIGN, \
400 .nth_size = sizeof(struct usb_cdc_ncm_nth32), \
401 .ndp_size = sizeof(struct usb_cdc_ncm_ndp32), \
403 .dgram_item_len = 2, \
408 .next_fp_index = 2, \
411 static struct ndp_parser_opts ndp16_opts
= INIT_NDP16_OPTS
;
412 static struct ndp_parser_opts ndp32_opts
= INIT_NDP32_OPTS
;
414 static inline void put_ncm(__le16
**p
, unsigned size
, unsigned val
)
418 put_unaligned_le16((u16
)val
, *p
);
421 put_unaligned_le32((u32
)val
, *p
);
431 static inline unsigned get_ncm(__le16
**p
, unsigned size
)
437 tmp
= get_unaligned_le16(*p
);
440 tmp
= get_unaligned_le32(*p
);
450 /*-------------------------------------------------------------------------*/
452 static inline void ncm_reset_values(struct f_ncm
*ncm
)
454 ncm
->parser_opts
= &ndp16_opts
;
456 ncm
->port
.cdc_filter
= DEFAULT_FILTER
;
458 /* doesn't make sense for ncm, fixed size used */
459 ncm
->port
.header_len
= 0;
461 ncm
->port
.fixed_out_len
= le32_to_cpu(ntb_parameters
.dwNtbOutMaxSize
);
462 ncm
->port
.fixed_in_len
= NTB_DEFAULT_IN_SIZE
;
466 * Context: ncm->lock held
468 static void ncm_do_notify(struct f_ncm
*ncm
)
470 struct usb_request
*req
= ncm
->notify_req
;
471 struct usb_cdc_notification
*event
;
472 struct usb_composite_dev
*cdev
= ncm
->port
.func
.config
->cdev
;
476 /* notification already in flight? */
481 switch (ncm
->notify_state
) {
482 case NCM_NOTIFY_NONE
:
485 case NCM_NOTIFY_CONNECT
:
486 event
->bNotificationType
= USB_CDC_NOTIFY_NETWORK_CONNECTION
;
488 event
->wValue
= cpu_to_le16(1);
490 event
->wValue
= cpu_to_le16(0);
492 req
->length
= sizeof *event
;
494 DBG(cdev
, "notify connect %s\n",
495 ncm
->is_open
? "true" : "false");
496 ncm
->notify_state
= NCM_NOTIFY_NONE
;
499 case NCM_NOTIFY_SPEED
:
500 event
->bNotificationType
= USB_CDC_NOTIFY_SPEED_CHANGE
;
501 event
->wValue
= cpu_to_le16(0);
502 event
->wLength
= cpu_to_le16(8);
503 req
->length
= NCM_STATUS_BYTECOUNT
;
505 /* SPEED_CHANGE data is up/down speeds in bits/sec */
506 data
= req
->buf
+ sizeof *event
;
507 data
[0] = cpu_to_le32(ncm_bitrate(cdev
->gadget
));
510 DBG(cdev
, "notify speed %d\n", ncm_bitrate(cdev
->gadget
));
511 ncm
->notify_state
= NCM_NOTIFY_CONNECT
;
514 event
->bmRequestType
= 0xA1;
515 event
->wIndex
= cpu_to_le16(ncm
->ctrl_id
);
517 ncm
->notify_req
= NULL
;
519 * In double buffering if there is a space in FIFO,
520 * completion callback can be called right after the call,
523 spin_unlock(&ncm
->lock
);
524 status
= usb_ep_queue(ncm
->notify
, req
, GFP_ATOMIC
);
525 spin_lock(&ncm
->lock
);
527 ncm
->notify_req
= req
;
528 DBG(cdev
, "notify --> %d\n", status
);
533 * Context: ncm->lock held
535 static void ncm_notify(struct f_ncm
*ncm
)
538 * NOTE on most versions of Linux, host side cdc-ethernet
539 * won't listen for notifications until its netdevice opens.
540 * The first notification then sits in the FIFO for a long
541 * time, and the second one is queued.
543 * If ncm_notify() is called before the second (CONNECT)
544 * notification is sent, then it will reset to send the SPEED
545 * notificaion again (and again, and again), but it's not a problem
547 ncm
->notify_state
= NCM_NOTIFY_SPEED
;
551 static void ncm_notify_complete(struct usb_ep
*ep
, struct usb_request
*req
)
553 struct f_ncm
*ncm
= req
->context
;
554 struct usb_composite_dev
*cdev
= ncm
->port
.func
.config
->cdev
;
555 struct usb_cdc_notification
*event
= req
->buf
;
557 spin_lock(&ncm
->lock
);
558 switch (req
->status
) {
560 VDBG(cdev
, "Notification %02x sent\n",
561 event
->bNotificationType
);
565 ncm
->notify_state
= NCM_NOTIFY_NONE
;
568 DBG(cdev
, "event %02x --> %d\n",
569 event
->bNotificationType
, req
->status
);
572 ncm
->notify_req
= req
;
574 spin_unlock(&ncm
->lock
);
577 static void ncm_ep0out_complete(struct usb_ep
*ep
, struct usb_request
*req
)
579 /* now for SET_NTB_INPUT_SIZE only */
581 struct usb_function
*f
= req
->context
;
582 struct f_ncm
*ncm
= func_to_ncm(f
);
583 struct usb_composite_dev
*cdev
= ep
->driver_data
;
586 if (req
->status
|| req
->actual
!= req
->length
) {
587 DBG(cdev
, "Bad control-OUT transfer\n");
591 in_size
= get_unaligned_le32(req
->buf
);
592 if (in_size
< USB_CDC_NCM_NTB_MIN_IN_SIZE
||
593 in_size
> le32_to_cpu(ntb_parameters
.dwNtbInMaxSize
)) {
594 DBG(cdev
, "Got wrong INPUT SIZE (%d) from host\n", in_size
);
598 ncm
->port
.fixed_in_len
= in_size
;
599 VDBG(cdev
, "Set NTB INPUT SIZE %d\n", in_size
);
607 static int ncm_setup(struct usb_function
*f
, const struct usb_ctrlrequest
*ctrl
)
609 struct f_ncm
*ncm
= func_to_ncm(f
);
610 struct usb_composite_dev
*cdev
= f
->config
->cdev
;
611 struct usb_request
*req
= cdev
->req
;
612 int value
= -EOPNOTSUPP
;
613 u16 w_index
= le16_to_cpu(ctrl
->wIndex
);
614 u16 w_value
= le16_to_cpu(ctrl
->wValue
);
615 u16 w_length
= le16_to_cpu(ctrl
->wLength
);
618 * composite driver infrastructure handles everything except
619 * CDC class messages; interface activation uses set_alt().
621 switch ((ctrl
->bRequestType
<< 8) | ctrl
->bRequest
) {
622 case ((USB_DIR_OUT
| USB_TYPE_CLASS
| USB_RECIP_INTERFACE
) << 8)
623 | USB_CDC_SET_ETHERNET_PACKET_FILTER
:
625 * see 6.2.30: no data, wIndex = interface,
626 * wValue = packet filter bitmap
628 if (w_length
!= 0 || w_index
!= ncm
->ctrl_id
)
630 DBG(cdev
, "packet filter %02x\n", w_value
);
632 * REVISIT locking of cdc_filter. This assumes the UDC
633 * driver won't have a concurrent packet TX irq running on
634 * another CPU; or that if it does, this write is atomic...
636 ncm
->port
.cdc_filter
= w_value
;
641 * case USB_CDC_SEND_ENCAPSULATED_COMMAND:
642 * case USB_CDC_GET_ENCAPSULATED_RESPONSE:
643 * case USB_CDC_SET_ETHERNET_MULTICAST_FILTERS:
644 * case USB_CDC_SET_ETHERNET_PM_PATTERN_FILTER:
645 * case USB_CDC_GET_ETHERNET_PM_PATTERN_FILTER:
646 * case USB_CDC_GET_ETHERNET_STATISTIC:
649 case ((USB_DIR_IN
| USB_TYPE_CLASS
| USB_RECIP_INTERFACE
) << 8)
650 | USB_CDC_GET_NTB_PARAMETERS
:
652 if (w_length
== 0 || w_value
!= 0 || w_index
!= ncm
->ctrl_id
)
654 value
= w_length
> sizeof ntb_parameters
?
655 sizeof ntb_parameters
: w_length
;
656 memcpy(req
->buf
, &ntb_parameters
, value
);
657 VDBG(cdev
, "Host asked NTB parameters\n");
660 case ((USB_DIR_IN
| USB_TYPE_CLASS
| USB_RECIP_INTERFACE
) << 8)
661 | USB_CDC_GET_NTB_INPUT_SIZE
:
663 if (w_length
< 4 || w_value
!= 0 || w_index
!= ncm
->ctrl_id
)
665 put_unaligned_le32(ncm
->port
.fixed_in_len
, req
->buf
);
667 VDBG(cdev
, "Host asked INPUT SIZE, sending %d\n",
668 ncm
->port
.fixed_in_len
);
671 case ((USB_DIR_OUT
| USB_TYPE_CLASS
| USB_RECIP_INTERFACE
) << 8)
672 | USB_CDC_SET_NTB_INPUT_SIZE
:
674 if (w_length
!= 4 || w_value
!= 0 || w_index
!= ncm
->ctrl_id
)
676 req
->complete
= ncm_ep0out_complete
;
677 req
->length
= w_length
;
684 case ((USB_DIR_IN
| USB_TYPE_CLASS
| USB_RECIP_INTERFACE
) << 8)
685 | USB_CDC_GET_NTB_FORMAT
:
689 if (w_length
< 2 || w_value
!= 0 || w_index
!= ncm
->ctrl_id
)
691 format
= (ncm
->parser_opts
== &ndp16_opts
) ? 0x0000 : 0x0001;
692 put_unaligned_le16(format
, req
->buf
);
694 VDBG(cdev
, "Host asked NTB FORMAT, sending %d\n", format
);
698 case ((USB_DIR_OUT
| USB_TYPE_CLASS
| USB_RECIP_INTERFACE
) << 8)
699 | USB_CDC_SET_NTB_FORMAT
:
701 if (w_length
!= 0 || w_index
!= ncm
->ctrl_id
)
705 ncm
->parser_opts
= &ndp16_opts
;
706 DBG(cdev
, "NCM16 selected\n");
709 ncm
->parser_opts
= &ndp32_opts
;
710 DBG(cdev
, "NCM32 selected\n");
718 case ((USB_DIR_IN
| USB_TYPE_CLASS
| USB_RECIP_INTERFACE
) << 8)
719 | USB_CDC_GET_CRC_MODE
:
723 if (w_length
< 2 || w_value
!= 0 || w_index
!= ncm
->ctrl_id
)
725 is_crc
= ncm
->is_crc
? 0x0001 : 0x0000;
726 put_unaligned_le16(is_crc
, req
->buf
);
728 VDBG(cdev
, "Host asked CRC MODE, sending %d\n", is_crc
);
732 case ((USB_DIR_OUT
| USB_TYPE_CLASS
| USB_RECIP_INTERFACE
) << 8)
733 | USB_CDC_SET_CRC_MODE
:
737 if (w_length
!= 0 || w_index
!= ncm
->ctrl_id
)
742 ndp_hdr_crc
= NCM_NDP_HDR_NOCRC
;
743 DBG(cdev
, "non-CRC mode selected\n");
747 ndp_hdr_crc
= NCM_NDP_HDR_CRC
;
748 DBG(cdev
, "CRC mode selected\n");
753 ncm
->parser_opts
->ndp_sign
&= ~NCM_NDP_HDR_CRC_MASK
;
754 ncm
->parser_opts
->ndp_sign
|= ndp_hdr_crc
;
759 /* and disabled in ncm descriptor: */
760 /* case USB_CDC_GET_NET_ADDRESS: */
761 /* case USB_CDC_SET_NET_ADDRESS: */
762 /* case USB_CDC_GET_MAX_DATAGRAM_SIZE: */
763 /* case USB_CDC_SET_MAX_DATAGRAM_SIZE: */
767 DBG(cdev
, "invalid control req%02x.%02x v%04x i%04x l%d\n",
768 ctrl
->bRequestType
, ctrl
->bRequest
,
769 w_value
, w_index
, w_length
);
772 /* respond with data transfer or status phase? */
774 DBG(cdev
, "ncm req%02x.%02x v%04x i%04x l%d\n",
775 ctrl
->bRequestType
, ctrl
->bRequest
,
776 w_value
, w_index
, w_length
);
779 value
= usb_ep_queue(cdev
->gadget
->ep0
, req
, GFP_ATOMIC
);
781 ERROR(cdev
, "ncm req %02x.%02x response err %d\n",
782 ctrl
->bRequestType
, ctrl
->bRequest
,
786 /* device either stalls (value < 0) or reports success */
791 static int ncm_set_alt(struct usb_function
*f
, unsigned intf
, unsigned alt
)
793 struct f_ncm
*ncm
= func_to_ncm(f
);
794 struct usb_composite_dev
*cdev
= f
->config
->cdev
;
796 /* Control interface has only altsetting 0 */
797 if (intf
== ncm
->ctrl_id
) {
801 if (ncm
->notify
->driver_data
) {
802 DBG(cdev
, "reset ncm control %d\n", intf
);
803 usb_ep_disable(ncm
->notify
);
805 DBG(cdev
, "init ncm ctrl %d\n", intf
);
806 ncm
->notify
->desc
= ep_choose(cdev
->gadget
,
810 usb_ep_enable(ncm
->notify
);
811 ncm
->notify
->driver_data
= ncm
;
813 /* Data interface has two altsettings, 0 and 1 */
814 } else if (intf
== ncm
->data_id
) {
818 if (ncm
->port
.in_ep
->driver_data
) {
819 DBG(cdev
, "reset ncm\n");
820 gether_disconnect(&ncm
->port
);
821 ncm_reset_values(ncm
);
825 * CDC Network only sends data in non-default altsettings.
826 * Changing altsettings resets filters, statistics, etc.
829 struct net_device
*net
;
831 if (!ncm
->port
.in_ep
->desc
) {
832 DBG(cdev
, "init ncm\n");
833 ncm
->port
.in_ep
->desc
= ep_choose(cdev
->gadget
,
836 ncm
->port
.out_ep
->desc
= ep_choose(cdev
->gadget
,
842 /* Enable zlps by default for NCM conformance;
843 * override for musb_hdrc (avoids txdma ovhead)
845 ncm
->port
.is_zlp_ok
= !(
846 gadget_is_musbhdrc(cdev
->gadget
)
848 ncm
->port
.cdc_filter
= DEFAULT_FILTER
;
849 DBG(cdev
, "activate ncm\n");
850 net
= gether_connect(&ncm
->port
);
855 spin_lock(&ncm
->lock
);
857 spin_unlock(&ncm
->lock
);
867 * Because the data interface supports multiple altsettings,
868 * this NCM function *MUST* implement a get_alt() method.
870 static int ncm_get_alt(struct usb_function
*f
, unsigned intf
)
872 struct f_ncm
*ncm
= func_to_ncm(f
);
874 if (intf
== ncm
->ctrl_id
)
876 return ncm
->port
.in_ep
->driver_data
? 1 : 0;
879 static struct sk_buff
*ncm_wrap_ntb(struct gether
*port
,
882 struct f_ncm
*ncm
= func_to_ncm(&port
->func
);
883 struct sk_buff
*skb2
;
886 int div
= ntb_parameters
.wNdpInDivisor
;
887 int rem
= ntb_parameters
.wNdpInPayloadRemainder
;
889 int ndp_align
= ntb_parameters
.wNdpInAlignment
;
891 unsigned max_size
= ncm
->port
.fixed_in_len
;
892 struct ndp_parser_opts
*opts
= ncm
->parser_opts
;
893 unsigned crc_len
= ncm
->is_crc
? sizeof(uint32_t) : 0;
895 ncb_len
+= opts
->nth_size
;
896 ndp_pad
= ALIGN(ncb_len
, ndp_align
) - ncb_len
;
898 ncb_len
+= opts
->ndp_size
;
899 ncb_len
+= 2 * 2 * opts
->dgram_item_len
; /* Datagram entry */
900 ncb_len
+= 2 * 2 * opts
->dgram_item_len
; /* Zero datagram entry */
901 pad
= ALIGN(ncb_len
, div
) + rem
- ncb_len
;
904 if (ncb_len
+ skb
->len
+ crc_len
> max_size
) {
905 dev_kfree_skb_any(skb
);
909 skb2
= skb_copy_expand(skb
, ncb_len
,
910 max_size
- skb
->len
- ncb_len
- crc_len
,
912 dev_kfree_skb_any(skb
);
918 tmp
= (void *) skb_push(skb
, ncb_len
);
919 memset(tmp
, 0, ncb_len
);
921 put_unaligned_le32(opts
->nth_sign
, tmp
); /* dwSignature */
924 put_unaligned_le16(opts
->nth_size
, tmp
++);
925 tmp
++; /* skip wSequence */
926 put_ncm(&tmp
, opts
->block_length
, skb
->len
); /* (d)wBlockLength */
928 /* the first pointer is right after the NTH + align */
929 put_ncm(&tmp
, opts
->fp_index
, opts
->nth_size
+ ndp_pad
);
931 tmp
= (void *)tmp
+ ndp_pad
;
934 put_unaligned_le32(opts
->ndp_sign
, tmp
); /* dwSignature */
937 put_unaligned_le16(ncb_len
- opts
->nth_size
- pad
, tmp
++);
939 tmp
+= opts
->reserved1
;
940 tmp
+= opts
->next_fp_index
; /* skip reserved (d)wNextFpIndex */
941 tmp
+= opts
->reserved2
;
949 put_unaligned_le32(crc
, skb
->data
+ skb
->len
);
950 skb_put(skb
, crc_len
);
953 /* (d)wDatagramIndex[0] */
954 put_ncm(&tmp
, opts
->dgram_item_len
, ncb_len
);
955 /* (d)wDatagramLength[0] */
956 put_ncm(&tmp
, opts
->dgram_item_len
, skb
->len
- ncb_len
);
957 /* (d)wDatagramIndex[1] and (d)wDatagramLength[1] already zeroed */
959 if (skb
->len
> MAX_TX_NONFIXED
)
960 memset(skb_put(skb
, max_size
- skb
->len
),
961 0, max_size
- skb
->len
);
966 static int ncm_unwrap_ntb(struct gether
*port
,
968 struct sk_buff_head
*list
)
970 struct f_ncm
*ncm
= func_to_ncm(&port
->func
);
971 __le16
*tmp
= (void *) skb
->data
;
972 unsigned index
, index2
;
973 unsigned dg_len
, dg_len2
;
975 struct sk_buff
*skb2
;
977 unsigned max_size
= le32_to_cpu(ntb_parameters
.dwNtbOutMaxSize
);
978 struct ndp_parser_opts
*opts
= ncm
->parser_opts
;
979 unsigned crc_len
= ncm
->is_crc
? sizeof(uint32_t) : 0;
983 if (get_unaligned_le32(tmp
) != opts
->nth_sign
) {
984 INFO(port
->func
.config
->cdev
, "Wrong NTH SIGN, skblen %d\n",
986 print_hex_dump(KERN_INFO
, "HEAD:", DUMP_PREFIX_ADDRESS
, 32, 1,
987 skb
->data
, 32, false);
993 if (get_unaligned_le16(tmp
++) != opts
->nth_size
) {
994 INFO(port
->func
.config
->cdev
, "Wrong NTB headersize\n");
997 tmp
++; /* skip wSequence */
999 /* (d)wBlockLength */
1000 if (get_ncm(&tmp
, opts
->block_length
) > max_size
) {
1001 INFO(port
->func
.config
->cdev
, "OUT size exceeded\n");
1005 index
= get_ncm(&tmp
, opts
->fp_index
);
1007 if (((index
% 4) != 0) && (index
< opts
->nth_size
)) {
1008 INFO(port
->func
.config
->cdev
, "Bad index: %x\n",
1013 /* walk through NDP */
1014 tmp
= ((void *)skb
->data
) + index
;
1015 if (get_unaligned_le32(tmp
) != opts
->ndp_sign
) {
1016 INFO(port
->func
.config
->cdev
, "Wrong NDP SIGN\n");
1021 ndp_len
= get_unaligned_le16(tmp
++);
1025 * item size is 16/32 bits, opts->dgram_item_len * 2 bytes
1026 * minimal: struct usb_cdc_ncm_ndpX + normal entry + zero entry
1028 if ((ndp_len
< opts
->ndp_size
+ 2 * 2 * (opts
->dgram_item_len
* 2))
1029 || (ndp_len
% opts
->ndplen_align
!= 0)) {
1030 INFO(port
->func
.config
->cdev
, "Bad NDP length: %x\n", ndp_len
);
1033 tmp
+= opts
->reserved1
;
1034 tmp
+= opts
->next_fp_index
; /* skip reserved (d)wNextFpIndex */
1035 tmp
+= opts
->reserved2
;
1037 ndp_len
-= opts
->ndp_size
;
1038 index2
= get_ncm(&tmp
, opts
->dgram_item_len
);
1039 dg_len2
= get_ncm(&tmp
, opts
->dgram_item_len
);
1045 if (dg_len
< 14 + crc_len
) { /* ethernet header + crc */
1046 INFO(port
->func
.config
->cdev
, "Bad dgram length: %x\n",
1053 crc
= get_unaligned_le32(skb
->data
+
1054 index
+ dg_len
- crc_len
);
1055 crc2
= ~crc32_le(~0,
1059 INFO(port
->func
.config
->cdev
, "Bad CRC\n");
1064 index2
= get_ncm(&tmp
, opts
->dgram_item_len
);
1065 dg_len2
= get_ncm(&tmp
, opts
->dgram_item_len
);
1067 if (index2
== 0 || dg_len2
== 0) {
1070 skb2
= skb_clone(skb
, GFP_ATOMIC
);
1075 if (!skb_pull(skb2
, index
)) {
1080 skb_trim(skb2
, dg_len
- crc_len
);
1081 skb_queue_tail(list
, skb2
);
1083 ndp_len
-= 2 * (opts
->dgram_item_len
* 2);
1087 if (index2
== 0 || dg_len2
== 0)
1089 } while (ndp_len
> 2 * (opts
->dgram_item_len
* 2)); /* zero entry */
1091 VDBG(port
->func
.config
->cdev
,
1092 "Parsed NTB with %d frames\n", dgram_counter
);
1095 skb_queue_purge(list
);
1096 dev_kfree_skb_any(skb
);
1100 static void ncm_disable(struct usb_function
*f
)
1102 struct f_ncm
*ncm
= func_to_ncm(f
);
1103 struct usb_composite_dev
*cdev
= f
->config
->cdev
;
1105 DBG(cdev
, "ncm deactivated\n");
1107 if (ncm
->port
.in_ep
->driver_data
)
1108 gether_disconnect(&ncm
->port
);
1110 if (ncm
->notify
->driver_data
) {
1111 usb_ep_disable(ncm
->notify
);
1112 ncm
->notify
->driver_data
= NULL
;
1113 ncm
->notify
->desc
= NULL
;
1117 /*-------------------------------------------------------------------------*/
1120 * Callbacks let us notify the host about connect/disconnect when the
1121 * net device is opened or closed.
1123 * For testing, note that link states on this side include both opened
1124 * and closed variants of:
1126 * - disconnected/unconfigured
1127 * - configured but inactive (data alt 0)
1128 * - configured and active (data alt 1)
1130 * Each needs to be tested with unplug, rmmod, SET_CONFIGURATION, and
1131 * SET_INTERFACE (altsetting). Remember also that "configured" doesn't
1132 * imply the host is actually polling the notification endpoint, and
1133 * likewise that "active" doesn't imply it's actually using the data
1134 * endpoints for traffic.
1137 static void ncm_open(struct gether
*geth
)
1139 struct f_ncm
*ncm
= func_to_ncm(&geth
->func
);
1141 DBG(ncm
->port
.func
.config
->cdev
, "%s\n", __func__
);
1143 spin_lock(&ncm
->lock
);
1144 ncm
->is_open
= true;
1146 spin_unlock(&ncm
->lock
);
1149 static void ncm_close(struct gether
*geth
)
1151 struct f_ncm
*ncm
= func_to_ncm(&geth
->func
);
1153 DBG(ncm
->port
.func
.config
->cdev
, "%s\n", __func__
);
1155 spin_lock(&ncm
->lock
);
1156 ncm
->is_open
= false;
1158 spin_unlock(&ncm
->lock
);
1161 /*-------------------------------------------------------------------------*/
1163 /* ethernet function driver setup/binding */
1166 ncm_bind(struct usb_configuration
*c
, struct usb_function
*f
)
1168 struct usb_composite_dev
*cdev
= c
->cdev
;
1169 struct f_ncm
*ncm
= func_to_ncm(f
);
1173 /* allocate instance-specific interface IDs */
1174 status
= usb_interface_id(c
, f
);
1177 ncm
->ctrl_id
= status
;
1178 ncm_iad_desc
.bFirstInterface
= status
;
1180 ncm_control_intf
.bInterfaceNumber
= status
;
1181 ncm_union_desc
.bMasterInterface0
= status
;
1183 status
= usb_interface_id(c
, f
);
1186 ncm
->data_id
= status
;
1188 ncm_data_nop_intf
.bInterfaceNumber
= status
;
1189 ncm_data_intf
.bInterfaceNumber
= status
;
1190 ncm_union_desc
.bSlaveInterface0
= status
;
1194 /* allocate instance-specific endpoints */
1195 ep
= usb_ep_autoconfig(cdev
->gadget
, &fs_ncm_in_desc
);
1198 ncm
->port
.in_ep
= ep
;
1199 ep
->driver_data
= cdev
; /* claim */
1201 ep
= usb_ep_autoconfig(cdev
->gadget
, &fs_ncm_out_desc
);
1204 ncm
->port
.out_ep
= ep
;
1205 ep
->driver_data
= cdev
; /* claim */
1207 ep
= usb_ep_autoconfig(cdev
->gadget
, &fs_ncm_notify_desc
);
1211 ep
->driver_data
= cdev
; /* claim */
1215 /* allocate notification request and buffer */
1216 ncm
->notify_req
= usb_ep_alloc_request(ep
, GFP_KERNEL
);
1217 if (!ncm
->notify_req
)
1219 ncm
->notify_req
->buf
= kmalloc(NCM_STATUS_BYTECOUNT
, GFP_KERNEL
);
1220 if (!ncm
->notify_req
->buf
)
1222 ncm
->notify_req
->context
= ncm
;
1223 ncm
->notify_req
->complete
= ncm_notify_complete
;
1225 /* copy descriptors, and track endpoint copies */
1226 f
->descriptors
= usb_copy_descriptors(ncm_fs_function
);
1227 if (!f
->descriptors
)
1230 ncm
->fs
.in
= usb_find_endpoint(ncm_fs_function
,
1231 f
->descriptors
, &fs_ncm_in_desc
);
1232 ncm
->fs
.out
= usb_find_endpoint(ncm_fs_function
,
1233 f
->descriptors
, &fs_ncm_out_desc
);
1234 ncm
->fs
.notify
= usb_find_endpoint(ncm_fs_function
,
1235 f
->descriptors
, &fs_ncm_notify_desc
);
1238 * support all relevant hardware speeds... we expect that when
1239 * hardware is dual speed, all bulk-capable endpoints work at
1242 if (gadget_is_dualspeed(c
->cdev
->gadget
)) {
1243 hs_ncm_in_desc
.bEndpointAddress
=
1244 fs_ncm_in_desc
.bEndpointAddress
;
1245 hs_ncm_out_desc
.bEndpointAddress
=
1246 fs_ncm_out_desc
.bEndpointAddress
;
1247 hs_ncm_notify_desc
.bEndpointAddress
=
1248 fs_ncm_notify_desc
.bEndpointAddress
;
1250 /* copy descriptors, and track endpoint copies */
1251 f
->hs_descriptors
= usb_copy_descriptors(ncm_hs_function
);
1252 if (!f
->hs_descriptors
)
1255 ncm
->hs
.in
= usb_find_endpoint(ncm_hs_function
,
1256 f
->hs_descriptors
, &hs_ncm_in_desc
);
1257 ncm
->hs
.out
= usb_find_endpoint(ncm_hs_function
,
1258 f
->hs_descriptors
, &hs_ncm_out_desc
);
1259 ncm
->hs
.notify
= usb_find_endpoint(ncm_hs_function
,
1260 f
->hs_descriptors
, &hs_ncm_notify_desc
);
1264 * NOTE: all that is done without knowing or caring about
1265 * the network link ... which is unavailable to this code
1266 * until we're activated via set_alt().
1269 ncm
->port
.open
= ncm_open
;
1270 ncm
->port
.close
= ncm_close
;
1272 DBG(cdev
, "CDC Network: %s speed IN/%s OUT/%s NOTIFY/%s\n",
1273 gadget_is_dualspeed(c
->cdev
->gadget
) ? "dual" : "full",
1274 ncm
->port
.in_ep
->name
, ncm
->port
.out_ep
->name
,
1280 usb_free_descriptors(f
->descriptors
);
1282 if (ncm
->notify_req
) {
1283 kfree(ncm
->notify_req
->buf
);
1284 usb_ep_free_request(ncm
->notify
, ncm
->notify_req
);
1287 /* we might as well release our claims on endpoints */
1289 ncm
->notify
->driver_data
= NULL
;
1290 if (ncm
->port
.out_ep
->desc
)
1291 ncm
->port
.out_ep
->driver_data
= NULL
;
1292 if (ncm
->port
.in_ep
->desc
)
1293 ncm
->port
.in_ep
->driver_data
= NULL
;
1295 ERROR(cdev
, "%s: can't bind, err %d\n", f
->name
, status
);
1301 ncm_unbind(struct usb_configuration
*c
, struct usb_function
*f
)
1303 struct f_ncm
*ncm
= func_to_ncm(f
);
1305 DBG(c
->cdev
, "ncm unbind\n");
1307 if (gadget_is_dualspeed(c
->cdev
->gadget
))
1308 usb_free_descriptors(f
->hs_descriptors
);
1309 usb_free_descriptors(f
->descriptors
);
1311 kfree(ncm
->notify_req
->buf
);
1312 usb_ep_free_request(ncm
->notify
, ncm
->notify_req
);
1314 ncm_string_defs
[1].s
= NULL
;
1319 * ncm_bind_config - add CDC Network link to a configuration
1320 * @c: the configuration to support the network link
1321 * @ethaddr: a buffer in which the ethernet address of the host side
1322 * side of the link was recorded
1323 * Context: single threaded during gadget setup
1325 * Returns zero on success, else negative errno.
1327 * Caller must have called @gether_setup(). Caller is also responsible
1328 * for calling @gether_cleanup() before module unload.
1330 int __init
ncm_bind_config(struct usb_configuration
*c
, u8 ethaddr
[ETH_ALEN
])
1335 if (!can_support_ecm(c
->cdev
->gadget
) || !ethaddr
)
1338 /* maybe allocate device-global string IDs */
1339 if (ncm_string_defs
[0].id
== 0) {
1341 /* control interface label */
1342 status
= usb_string_id(c
->cdev
);
1345 ncm_string_defs
[STRING_CTRL_IDX
].id
= status
;
1346 ncm_control_intf
.iInterface
= status
;
1348 /* data interface label */
1349 status
= usb_string_id(c
->cdev
);
1352 ncm_string_defs
[STRING_DATA_IDX
].id
= status
;
1353 ncm_data_nop_intf
.iInterface
= status
;
1354 ncm_data_intf
.iInterface
= status
;
1357 status
= usb_string_id(c
->cdev
);
1360 ncm_string_defs
[STRING_MAC_IDX
].id
= status
;
1361 ecm_desc
.iMACAddress
= status
;
1364 status
= usb_string_id(c
->cdev
);
1367 ncm_string_defs
[STRING_IAD_IDX
].id
= status
;
1368 ncm_iad_desc
.iFunction
= status
;
1371 /* allocate and initialize one new instance */
1372 ncm
= kzalloc(sizeof *ncm
, GFP_KERNEL
);
1376 /* export host's Ethernet address in CDC format */
1377 snprintf(ncm
->ethaddr
, sizeof ncm
->ethaddr
,
1378 "%02X%02X%02X%02X%02X%02X",
1379 ethaddr
[0], ethaddr
[1], ethaddr
[2],
1380 ethaddr
[3], ethaddr
[4], ethaddr
[5]);
1381 ncm_string_defs
[1].s
= ncm
->ethaddr
;
1383 spin_lock_init(&ncm
->lock
);
1384 ncm_reset_values(ncm
);
1385 ncm
->port
.is_fixed
= true;
1387 ncm
->port
.func
.name
= "cdc_network";
1388 ncm
->port
.func
.strings
= ncm_strings
;
1389 /* descriptors are per-instance copies */
1390 ncm
->port
.func
.bind
= ncm_bind
;
1391 ncm
->port
.func
.unbind
= ncm_unbind
;
1392 ncm
->port
.func
.set_alt
= ncm_set_alt
;
1393 ncm
->port
.func
.get_alt
= ncm_get_alt
;
1394 ncm
->port
.func
.setup
= ncm_setup
;
1395 ncm
->port
.func
.disable
= ncm_disable
;
1397 ncm
->port
.wrap
= ncm_wrap_ntb
;
1398 ncm
->port
.unwrap
= ncm_unwrap_ntb
;
1400 status
= usb_add_function(c
, &ncm
->port
.func
);
1402 ncm_string_defs
[1].s
= NULL
;