net: cdc_ncm: document the sysfs API

Adding documentation for all the driver specific sysfs attributes.

Cc: Peter Stuge <peter@stuge.se>
Signed-off-by: Bjørn Mork <bjorn@mork.no>
Signed-off-by: David S. Miller <davem@davemloft.net>

1 files changed, 149 insertions, 0 deletions

diff --git a/Documentation/ABI/testing/sysfs-class-net-cdc_ncm b/Documentation/ABI/testing/sysfs-class-net-cdc_ncm
new file mode 100644
index 000000000000..5cedf72df358
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-net-cdc_ncm
@@ -0,0 +1,149 @@
+What:           /sys/class/net/<iface>/cdc_ncm/min_tx_pkt
+Date:           May 2014
+KernelVersion:  3.16
+Contact:        Bjørn Mork <bjorn@mork.no>
+Description:
+                The driver will pad NCM Transfer Blocks (NTBs) longer
+                than this to tx_max, allowing the device to receive
+                tx_max sized frames with no terminating short
+                packet. NTBs shorter than this limit are transmitted
+                as-is, without any padding, and are terminated with a
+                short USB packet.
+
+                Padding to tx_max allows the driver to transmit NTBs
+                back-to-back without any interleaving short USB
+                packets.  This reduces the number of short packet
+                interrupts in the device, and represents a tradeoff
+                between USB bus bandwidth and device DMA optimization.
+
+                Set to 0 to pad all frames. Set greater than tx_max to
+                disable all padding.
+
+What:           /sys/class/net/<iface>/cdc_ncm/rx_max
+Date:           May 2014
+KernelVersion:  3.16
+Contact:        Bjørn Mork <bjorn@mork.no>
+Description:
+                The maximum NTB size for RX.  Cannot exceed the
+                maximum value supported by the device. Must allow at
+                least one max sized datagram plus headers.
+
+                The actual limits are device dependent.  See
+                dwNtbInMaxSize.
+
+                Note: Some devices will silently ignore changes to
+                this value, resulting in oversized NTBs and
+                corresponding framing errors.
+
+What:           /sys/class/net/<iface>/cdc_ncm/tx_max
+Date:           May 2014
+KernelVersion:  3.16
+Contact:        Bjørn Mork <bjorn@mork.no>
+Description:
+                The maximum NTB size for TX.  Cannot exceed the
+                maximum value supported by the device.  Must allow at
+                least one max sized datagram plus headers.
+
+                The actual limits are device dependent.  See
+                dwNtbOutMaxSize.
+
+What:           /sys/class/net/<iface>/cdc_ncm/tx_timer_usecs
+Date:           May 2014
+KernelVersion:  3.16
+Contact:        Bjørn Mork <bjorn@mork.no>
+Description:
+                Datagram aggregation timeout in µs. The driver will
+                wait up to 3 times this timeout for more datagrams to
+                aggregate before transmitting an NTB frame.
+
+                Valid range: 5 to 4000000
+
+                Set to 0 to disable aggregation.
+
+The following read-only attributes all represent fields of the
+structure defined in section 6.2.1 "GetNtbParameters" of "Universal
+Serial Bus Communications Class Subclass Specifications for Network
+Control Model Devices" (CDC NCM), Revision 1.0 (Errata 1), November
+24, 2010 from USB Implementers Forum, Inc.  The descriptions are
+quoted from table 6-3 of CDC NCM: "NTB Parameter Structure".
+
+What:           /sys/class/net/<iface>/cdc_ncm/bmNtbFormatsSupported
+Date:           May 2014
+KernelVersion:  3.16
+Contact:        Bjørn Mork <bjorn@mork.no>
+Description:
+                Bit 0: 16-bit NTB supported (set to 1)
+                Bit 1: 32-bit NTB supported
+                Bits 2 – 15: reserved (reset to zero; must be ignored by host)
+
+What:           /sys/class/net/<iface>/cdc_ncm/dwNtbInMaxSize
+Date:           May 2014
+KernelVersion:  3.16
+Contact:        Bjørn Mork <bjorn@mork.no>
+Description:
+                IN NTB Maximum Size in bytes
+
+What:           /sys/class/net/<iface>/cdc_ncm/wNdpInDivisor
+Date:           May 2014
+KernelVersion:  3.16
+Contact:        Bjørn Mork <bjorn@mork.no>
+Description:
+                Divisor used for IN NTB Datagram payload alignment
+
+What:           /sys/class/net/<iface>/cdc_ncm/wNdpInPayloadRemainder
+Date:           May 2014
+KernelVersion:  3.16
+Contact:        Bjørn Mork <bjorn@mork.no>
+Description:
+                Remainder used to align input datagram payload within
+                the NTB: (Payload Offset) mod (wNdpInDivisor) =
+                wNdpInPayloadRemainder
+
+What:           /sys/class/net/<iface>/cdc_ncm/wNdpInAlignment
+Date:           May 2014
+KernelVersion:  3.16
+Contact:        Bjørn Mork <bjorn@mork.no>
+Description:
+                NDP alignment modulus for NTBs on the IN pipe. Shall
+                be a power of 2, and shall be at least 4.
+
+What:           /sys/class/net/<iface>/cdc_ncm/dwNtbOutMaxSize
+Date:           May 2014
+KernelVersion:  3.16
+Contact:        Bjørn Mork <bjorn@mork.no>
+Description:
+                OUT NTB Maximum Size
+
+What:           /sys/class/net/<iface>/cdc_ncm/wNdpOutDivisor
+Date:           May 2014
+KernelVersion:  3.16
+Contact:        Bjørn Mork <bjorn@mork.no>
+Description:
+                OUT NTB Datagram alignment modulus
+
+What:           /sys/class/net/<iface>/cdc_ncm/wNdpOutPayloadRemainder
+Date:           May 2014
+KernelVersion:  3.16
+Contact:        Bjørn Mork <bjorn@mork.no>
+Description:
+                Remainder used to align output datagram payload
+                offsets within the NTB: Padding, shall be transmitted
+                as zero by function, and ignored by host.  (Payload
+                Offset) mod (wNdpOutDivisor) = wNdpOutPayloadRemainder
+
+What:           /sys/class/net/<iface>/cdc_ncm/wNdpOutAlignment
+Date:           May 2014
+KernelVersion:  3.16
+Contact:        Bjørn Mork <bjorn@mork.no>
+Description:
+                NDP alignment modulus for use in NTBs on the OUT
+                pipe. Shall be a power of 2, and shall be at least 4.
+
+What:           /sys/class/net/<iface>/cdc_ncm/wNtbOutMaxDatagrams
+Date:           May 2014
+KernelVersion:  3.16
+Contact:        Bjørn Mork <bjorn@mork.no>
+Description:
+                Maximum number of datagrams that the host may pack
+                into a single OUT NTB. Zero means that the device
+                imposes no limit.