linux_dsm_epyc7002/Documentation
Bjørn Mork 3edce1cf81 USB: cdc-wdm: implement IOCTL_WDM_MAX_COMMAND
Userspace applications need to know the maximum supported message
size.

The cdc-wdm driver translates between a character device stream
and a message based protocol.  Each message is transported as a
usb control message with no further encapsulation or syncronization.
Each read or write on the character device should translate to
exactly one usb control message to ensure that message boundaries
are kept intact.  That means that the userspace application must
know the maximum message size supported by the device and driver,
making this size a vital part of the cdc-wdm character device API.

CDC WDM and CDC MBIM functions export the maximum supported
message size through CDC functional descriptors.  The cdc-wdm and
cdc_mbim drivers will parse these descriptors and use the value
chosen by the device.  The only current way for a userspace
application to retrive the value is by duplicating the descriptor
parsing. This is an unnecessary complex task, and application
writers are likely to postpone it, using a fixed value and adding
a "todo" item.

QMI functions have no way to tell the host what message size they
support.  The qmi_wwan driver use a fixed value based on protocol
recommendations and observed device behaviour.  Userspace
applications must know and hard code the same value.  This scheme
will break if we ever encounter a QMI device needing a device
specific message size quirk.  We are currently unable to support
such a device because using a non default size would break the
implicit userspace API.

The message size is currently a hidden attribute of the cdc-wdm
userspace API.  Retrieving it is unnecessarily complex, increasing
the possibility of drivers and applications using different limits.
The resulting errors are hard to debug, and can only be replicated
on identical hardware.

Exporting the maximum message size from the driver simplifies the
task for the userspace application, and creates a unified
information source independent of device and function class. It also
serves to document that the message size is part of the cdc-wdm
userspace API.

This proposed API extension has been presented for the authors of
userspace applications and libraries using the current API: libmbim,
libqmi, uqmi, oFono and ModemManager.  The replies were:

Aleksander Morgado:
 "We do really need max message size for MBIM; and as you say, it may be
  good to have the max message size info also for QMI, so the new ioctl
  seems a good addition. So +1 from my side, for what it's worth."

Dan Williams:
 "Yeah, +1 here.  I'd prefer the sysfs file, but the fact that that
  doesn't work for fd passing pretty much kills it."

No negative replies are so far received.

Cc: Aleksander Morgado <aleksander@lanedo.com>
Cc: Dan Williams <dcbw@redhat.com>
Signed-off-by: Bjørn Mork <bjorn@mork.no>
Acked-by: Oliver Neukum <oliver@neukum.org>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2013-03-25 13:32:20 -07:00
..
ABI Merge branch 'for_linus' of git://cavan.codon.org.uk/platform-drivers-x86 2013-03-03 10:16:19 -08:00
accounting
acpi
aoe
arm
arm64
auxdisplay
backlight backlight: lp855x_bl: support new LP8557 device 2013-02-21 17:22:25 -08:00
blackfin
block
blockdev nbd: update documentation and link to mailinglist 2013-02-27 19:10:22 -08:00
bus-devices
cdrom
cgroups Merge branch 'for-3.9/core' of git://git.kernel.dk/linux-block 2013-02-28 12:52:24 -08:00
connector
console
cpu-freq
cpuidle
cris
crypto
development-process
device-mapper md updates for 3.9 2013-03-05 17:22:08 -08:00
devicetree Merge 3.9-rc4 into usb-next 2013-03-25 10:05:37 -07:00
DocBook Merge branch 'drm-next' of git://people.freedesktop.org/~airlied/linux 2013-02-25 16:46:44 -08:00
driver-model
dvb
early-userspace
EDID
extcon
fault-injection
fb
filesystems Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/viro/vfs 2013-02-26 20:16:07 -08:00
firmware_class
frv
hid
hwmon hwmon: (lm75) Fix tcn75 prefix 2013-03-18 21:19:49 +01:00
i2c i2c: Fix my e-mail address in drivers and documentation 2013-03-22 11:18:34 +01:00
i2o
ia64
ide
infiniband
input Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/dtor/input 2013-03-11 07:49:37 -07:00
ioctl USB: cdc-wdm: implement IOCTL_WDM_MAX_COMMAND 2013-03-25 13:32:20 -07:00
isdn
ja_JP
kbuild Merge branch 'kconfig' of git://git.kernel.org/pub/scm/linux/kernel/git/mmarek/kbuild 2013-02-27 12:28:30 -08:00
kdump
ko_KR
laptops
leds
m68k
make
memory-devices
metag metag: Basic documentation 2013-03-02 20:09:50 +00:00
mips
misc-devices
mmc
mn10300
mtd
namespaces
netlabel
networking net: docs: document multiqueue tuntap API 2013-03-06 14:56:10 -05:00
nfc
parisc
PCI
pcmcia
power PM / OPP: improve introductory documentation 2013-03-04 14:23:11 +01:00
powerpc
pps
prctl
pti
ptp
rapidio
RCU
s390
scheduler
scsi [SCSI] megaraid_sas: Version and Changelog update 2013-02-22 15:37:15 +00:00
security
serial
sh
sound ALSA: documentation: Fix typo in Documentation/sound 2013-03-17 10:12:13 +01:00
spi
sysctl
target
thermal Merge branch 'release' of git://git.kernel.org/pub/scm/linux/kernel/git/rzhang/linux 2013-02-28 19:48:26 -08:00
timers
trace Merge branch 'perf-urgent-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip 2013-03-11 07:54:29 -07:00
usb
vDSO
video4linux
virtual Merge tag 'kvm-3.9-1' of git://git.kernel.org/pub/scm/virt/kvm/kvm 2013-02-24 13:07:18 -08:00
vm ksm: add some comments 2013-02-23 17:50:23 -08:00
w1
watchdog watchdog: core: dt: add support for the timeout-sec dt property 2013-03-01 12:48:36 +01:00
wimax
x86 Merge branch 'x86/microcode' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip 2013-02-22 19:22:52 -08:00
xtensa
zh_CN Driver core patches for 3.9-rc1 2013-02-21 12:05:51 -08:00
.gitignore
00-INDEX ImgTec Meta architecture changes for v3.9-rc1 2013-03-03 12:06:09 -08:00
applying-patches.txt
atomic_ops.txt
bad_memory.txt
basic_profiling.txt
binfmt_misc.txt
braille-console.txt
bt8xxgpio.txt
btmrvl.txt
BUG-HUNTING
bus-virt-phys-mapping.txt
cachetlb.txt
Changes
circular-buffers.txt
clk.txt
coccinelle.txt coccicheck: Allow the user to give a V= (verbose) argument 2013-02-22 11:39:13 +01:00
CodingStyle
cpu-hotplug.txt
cpu-load.txt
cputopology.txt
crc32.txt
dcdbas.txt
debugging-modules.txt
debugging-via-ohci1394.txt
dell_rbu.txt
devices.txt
digsig.txt
DMA-API-HOWTO.txt Documentation/DMA-API-HOWTO.txt: fix typo 2013-02-27 19:10:23 -08:00
DMA-API.txt
DMA-attributes.txt
dma-buf-sharing.txt dma-buf: implement vmap refcounting in the interface logic 2013-02-27 15:13:36 +05:30
DMA-ISA-LPC.txt
dmaengine.txt
dontdiff
dynamic-debug-howto.txt
edac.txt
eisa.txt
email-clients.txt
flexible-arrays.txt
futex-requeue-pi.txt
gcov.txt
gpio.txt
highuid.txt
HOWTO
hw_random.txt
hwspinlock.txt
init.txt
initrd.txt
intel_txt.txt
Intel-IOMMU.txt
io_ordering.txt
io-mapping.txt
iostats.txt
IPMI.txt ipmi: add options to disable openfirmware and PCI scanning 2013-02-27 19:10:21 -08:00
IRQ-affinity.txt
IRQ-domain.txt
IRQ.txt
irqflags-tracing.txt
isapnp.txt
java.txt
kernel-doc-nano-HOWTO.txt
kernel-docs.txt
kernel-parameters.txt ImgTec Meta architecture changes for v3.9-rc1 2013-03-03 12:06:09 -08:00
kmemcheck.txt
kmemleak.txt
kobject.txt
kprobes.txt
kref.txt
ldm.txt
local_ops.txt
lockdep-design.txt
lockstat.txt
lockup-watchdogs.txt
logo.gif
logo.txt
magic-number.txt
Makefile
ManagementStyle
md.txt
media-framework.txt
memory-barriers.txt
memory-hotplug.txt
mono.txt
mutex-design.txt
nommu-mmap.txt
numastat.txt
oops-tracing.txt
padata.txt
parport-lowlevel.txt
parport.txt
percpu-rw-semaphore.txt
pi-futex.txt
pinctrl.txt
pnp.txt
preempt-locking.txt
printk-formats.txt Randy has moved 2013-03-08 15:05:34 -08:00
pwm.txt
ramoops.txt
rbtree.txt
remoteproc.txt
rfkill.txt
robust-futex-ABI.txt
robust-futexes.txt
rpmsg.txt
rt-mutex-design.txt
rt-mutex.txt
rtc.txt
SAK.txt
SecurityBugs
serial-console.txt
sgi-ioc4.txt
sgi-visws.txt
SM501.txt
smsc_ece1099.txt
sparse.txt
spinlocks.txt
stable_api_nonsense.txt
stable_kernel_rules.txt
static-keys.txt
SubmitChecklist
SubmittingDrivers
SubmittingPatches Randy has moved 2013-03-08 15:05:34 -08:00
svga.txt
sysfs-rules.txt
sysrq.txt
unaligned-memory-access.txt
unicode.txt
unshare.txt
vfio.txt
VGA-softcursor.txt
vgaarbiter.txt
video-output.txt
vme_api.txt
volatile-considered-harmful.txt
workqueue.txt
xz.txt
zorro.txt