diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/ABI/README | 77 | ||||
| -rw-r--r-- | Documentation/ABI/obsolete/devfs | 13 | ||||
| -rw-r--r-- | Documentation/ABI/stable/syscalls | 10 | ||||
| -rw-r--r-- | Documentation/ABI/stable/sysfs-module | 30 | ||||
| -rw-r--r-- | Documentation/ABI/testing/sysfs-class | 16 | ||||
| -rw-r--r-- | Documentation/ABI/testing/sysfs-devices | 25 | ||||
| -rw-r--r-- | Documentation/isdn/README.gigaset | 7 | ||||
| -rw-r--r-- | Documentation/keys.txt | 39 | ||||
| -rw-r--r-- | Documentation/power/devices.txt | 90 | ||||
| -rw-r--r-- | Documentation/power/swsusp.txt | 37 | ||||
| -rw-r--r-- | Documentation/sound/alsa/ALSA-Configuration.txt | 19 | ||||
| -rw-r--r-- | Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl | 50 | ||||
| -rw-r--r-- | Documentation/usb/usbmon.txt | 32 |
13 files changed, 292 insertions, 153 deletions
diff --git a/Documentation/ABI/README b/Documentation/ABI/README new file mode 100644 index 00000000000..9feaf16f161 --- /dev/null +++ b/Documentation/ABI/README @@ -0,0 +1,77 @@ +This directory attempts to document the ABI between the Linux kernel and +userspace, and the relative stability of these interfaces. Due to the +everchanging nature of Linux, and the differing maturity levels, these +interfaces should be used by userspace programs in different ways. + +We have four different levels of ABI stability, as shown by the four +different subdirectories in this location. Interfaces may change levels +of stability according to the rules described below. + +The different levels of stability are: + + stable/ + This directory documents the interfaces that the developer has + defined to be stable. Userspace programs are free to use these + interfaces with no restrictions, and backward compatibility for + them will be guaranteed for at least 2 years. Most interfaces + (like syscalls) are expected to never change and always be + available. + + testing/ + This directory documents interfaces that are felt to be stable, + as the main development of this interface has been completed. + The interface can be changed to add new features, but the + current interface will not break by doing this, unless grave + errors or security problems are found in them. Userspace + programs can start to rely on these interfaces, but they must be + aware of changes that can occur before these interfaces move to + be marked stable. Programs that use these interfaces are + strongly encouraged to add their name to the description of + these interfaces, so that the kernel developers can easily + notify them if any changes occur (see the description of the + layout of the files below for details on how to do this.) + + obsolete/ + This directory documents interfaces that are still remaining in + the kernel, but are marked to be removed at some later point in + time. The description of the interface will document the reason + why it is obsolete and when it can be expected to be removed. + The file Documentation/feature-removal-schedule.txt may describe + some of these interfaces, giving a schedule for when they will + be removed. + + removed/ + This directory contains a list of the old interfaces that have + been removed from the kernel. + +Every file in these directories will contain the following information: + +What: Short description of the interface +Date: Date created +KernelVersion: Kernel version this feature first showed up in. +Contact: Primary contact for this interface (may be a mailing list) +Description: Long description of the interface and how to use it. +Users: All users of this interface who wish to be notified when + it changes. This is very important for interfaces in + the "testing" stage, so that kernel developers can work + with userspace developers to ensure that things do not + break in ways that are unacceptable. It is also + important to get feedback for these interfaces to make + sure they are working in a proper way and do not need to + be changed further. + + +How things move between levels: + +Interfaces in stable may move to obsolete, as long as the proper +notification is given. + +Interfaces may be removed from obsolete and the kernel as long as the +documented amount of time has gone by. + +Interfaces in the testing state can move to the stable state when the +developers feel they are finished. They cannot be removed from the +kernel tree without going through the obsolete state first. + +It's up to the developer to place their interfaces in the category they +wish for it to start out in. diff --git a/Documentation/ABI/obsolete/devfs b/Documentation/ABI/obsolete/devfs new file mode 100644 index 00000000000..b8b87399bc8 --- /dev/null +++ b/Documentation/ABI/obsolete/devfs @@ -0,0 +1,13 @@ +What: devfs +Date: July 2005 +Contact: Greg Kroah-Hartman <gregkh@suse.de> +Description: + devfs has been unmaintained for a number of years, has unfixable + races, contains a naming policy within the kernel that is + against the LSB, and can be replaced by using udev. + The files fs/devfs/*, include/linux/devfs_fs*.h will be removed, + along with the the assorted devfs function calls throughout the + kernel tree. + +Users: + diff --git a/Documentation/ABI/stable/syscalls b/Documentation/ABI/stable/syscalls new file mode 100644 index 00000000000..c3ae3e7d6a0 --- /dev/null +++ b/Documentation/ABI/stable/syscalls @@ -0,0 +1,10 @@ +What: The kernel syscall interface +Description: + This interface matches much of the POSIX interface and is based + on it and other Unix based interfaces. It will only be added to + over time, and not have things removed from it. + + Note that this interface is different for every architecture + that Linux supports. Please see the architecture-specific + documentation for details on the syscall numbers that are to be + mapped to each syscall. diff --git a/Documentation/ABI/stable/sysfs-module b/Documentation/ABI/stable/sysfs-module new file mode 100644 index 00000000000..75be4311833 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-module @@ -0,0 +1,30 @@ +What: /sys/module +Description: + The /sys/module tree consists of the following structure: + + /sys/module/MODULENAME + The name of the module that is in the kernel. This + module name will show up either if the module is built + directly into the kernel, or if it is loaded as a + dyanmic module. + + /sys/module/MODULENAME/parameters + This directory contains individual files that are each + individual parameters of the module that are able to be + changed at runtime. See the individual module + documentation as to the contents of these parameters and + what they accomplish. + + Note: The individual parameter names and values are not + considered stable, only the fact that they will be + placed in this location within sysfs. See the + individual driver documentation for details as to the + stability of the different parameters. + + /sys/module/MODULENAME/refcnt + If the module is able to be unloaded from the kernel, this file + will contain the current reference count of the module. + + Note: If the module is built into the kernel, or if the + CONFIG_MODULE_UNLOAD kernel configuration value is not enabled, + this file will not be present. diff --git a/Documentation/ABI/testing/sysfs-class b/Documentation/ABI/testing/sysfs-class new file mode 100644 index 00000000000..4b0cb891e46 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class @@ -0,0 +1,16 @@ +What: /sys/class/ +Date: Febuary 2006 +Contact: Greg Kroah-Hartman <gregkh@suse.de> +Description: + The /sys/class directory will consist of a group of + subdirectories describing individual classes of devices + in the kernel. The individual directories will consist + of either subdirectories, or symlinks to other + directories. + + All programs that use this directory tree must be able + to handle both subdirectories or symlinks in order to + work properly. + +Users: + udev <linux-hotplug-devel@lists.sourceforge.net> diff --git a/Documentation/ABI/testing/sysfs-devices b/Documentation/ABI/testing/sysfs-devices new file mode 100644 index 00000000000..6a25671ee5f --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices @@ -0,0 +1,25 @@ +What: /sys/devices +Date: February 2006 +Contact: Greg Kroah-Hartman <gregkh@suse.de> +Description: + The /sys/devices tree contains a snapshot of the + internal state of the kernel device tree. Devices will + be added and removed dynamically as the machine runs, + and between different kernel versions, the layout of the + devices within this tree will change. + + Please do not rely on the format of this tree because of + this. If a program wishes to find different things in + the tree, please use the /sys/class structure and rely + on the symlinks there to point to the proper location + within the /sys/devices tree of the individual devices. + Or rely on the uevent messages to notify programs of + devices being added and removed from this tree to find + the location of those devices. + + Note that sometimes not all devices along the directory + chain will have emitted uevent messages, so userspace + programs must be able to handle such occurrences. + +Users: + udev <linux-hotplug-devel@lists.sourceforge.net> diff --git a/Documentation/isdn/README.gigaset b/Documentation/isdn/README.gigaset index 85a64defd38..fa0d4cca964 100644 --- a/Documentation/isdn/README.gigaset +++ b/Documentation/isdn/README.gigaset @@ -124,7 +124,8 @@ GigaSet 307x Device Driver You can use some configuration tool of your distribution to configure this "modem" or configure pppd/wvdial manually. There are some example ppp - configuration files and chat scripts in the gigaset-VERSION/ppp directory. + configuration files and chat scripts in the gigaset-VERSION/ppp directory + in the driver packages from http://sourceforge.net/projects/gigaset307x/. Please note that the USB drivers are not able to change the state of the control lines (the M105 driver can be configured to use some undocumented control requests, if you really need the control lines, though). This means @@ -164,8 +165,8 @@ GigaSet 307x Device Driver If you want both of these at once, you are out of luck. - You can also use /sys/module/<name>/parameters/cidmode for changing - the CID mode setting (<name> is usb_gigaset or bas_gigaset). + You can also use /sys/class/tty/ttyGxy/cidmode for changing the CID mode + setting (ttyGxy is ttyGU0 or ttyGB0). 3. Troubleshooting diff --git a/Documentation/keys.txt b/Documentation/keys.txt index aaa01b0e3ee..3bbe157b45e 100644 --- a/Documentation/keys.txt +++ b/Documentation/keys.txt @@ -19,6 +19,7 @@ This document has the following sections: - Key overview - Key service overview - Key access permissions + - SELinux support - New procfs files - Userspace system call interface - Kernel services @@ -232,6 +233,34 @@ For changing the ownership, group ID or permissions mask, being the owner of the key or having the sysadmin capability is sufficient. +=============== +SELINUX SUPPORT +=============== + +The security class "key" has been added to SELinux so that mandatory access +controls can be applied to keys created within various contexts. This support +is preliminary, and is likely to change quite significantly in the near future. +Currently, all of the basic permissions explained above are provided in SELinux +as well; SE Linux is simply invoked after all basic permission checks have been +performed. + +Each key is labeled with the same context as the task to which it belongs. +Typically, this is the same task that was running when the key was created. +The default keyrings are handled differently, but in a way that is very +intuitive: + + (*) The user and user session keyrings that are created when the user logs in + are currently labeled with the context of the login manager. + + (*) The keyrings associated with new threads are each labeled with the context + of their associated thread, and both session and process keyrings are + handled similarly. + +Note, however, that the default keyrings associated with the root user are +labeled with the default kernel context, since they are created early in the +boot process, before root has a chance to log in. + + ================ NEW PROCFS FILES ================ @@ -935,6 +964,16 @@ The structure has a number of fields, some of which are mandatory: It is not safe to sleep in this method; the caller may hold spinlocks. + (*) void (*revoke)(struct key *key); + + This method is optional. It is called to discard part of the payload + data upon a key being revoked. The caller will have the key semaphore + write-locked. + + It is safe to sleep in this method, though care should be taken to avoid + a deadlock against the key semaphore. + + (*) void (*destroy)(struct key *key); This method is optional. It is called to discard the payload data on a key diff --git a/Documentation/power/devices.txt b/Documentation/power/devices.txt index f987afe43e2..fba1e05c47c 100644 --- a/Documentation/power/devices.txt +++ b/Documentation/power/devices.txt @@ -135,96 +135,6 @@ HW. FREEZE -- stop DMA and interrupts, and be prepared to reinit HW from scratch. That probably means stop accepting upstream requests, the -actual policy of what to do with them beeing specific to a given -driver. It's acceptable for a network driver to just drop packets -while a block driver is expected to block the queue so no request is -lost. (Use IDE as an example on how to do that). FREEZE requires no -power state change, and it's expected for drivers to be able to -quickly transition back to operating state. - -SUSPEND -- like FREEZE, but also put hardware into low-power state. If -there's need to distinguish several levels of sleep, additional flag -is probably best way to do that. - -Transitions are only from a resumed state to a suspended state, never -between 2 suspended states. (ON -> FREEZE or ON -> SUSPEND can happen, -FREEZE -> SUSPEND or SUSPEND -> FREEZE can not). - -All events are: - -[NOTE NOTE NOTE: If you are driver author, you should not care; you -should only look at event, and ignore flags.] - -#Prepare for suspend -- userland is still running but we are going to -#enter suspend state. This gives drivers chance to load firmware from -#disk and store it in memory, or do other activities taht require -#operating userland, ability to kmalloc GFP_KERNEL, etc... All of these -#are forbiden once the suspend dance is started.. event = ON, flags = -#PREPARE_TO_SUSPEND - -Apm standby -- prepare for APM event. Quiesce devices to make life -easier for APM BIOS. event = FREEZE, flags = APM_STANDBY - -Apm suspend -- same as APM_STANDBY, but it we should probably avoid -spinning down disks. event = FREEZE, flags = APM_SUSPEND - -System halt, reboot -- quiesce devices to make life easier for BIOS. event -= FREEZE, flags = SYSTEM_HALT or SYSTEM_REBOOT - -System shutdown -- at least disks need to be spun down, or data may be -lost. Quiesce devices, just to make life easier for BIOS. event = -FREEZE, flags = SYSTEM_SHUTDOWN - -Kexec -- turn off DMAs and put hardware into some state where new -kernel can take over. event = FREEZE, flags = KEXEC - -Powerdown at end of swsusp -- very similar to SYSTEM_SHUTDOWN, except wake -may need to be enabled on some devices. This actually has at least 3 -subtypes, system can reboot, enter S4 and enter S5 at the end of -swsusp. event = FREEZE, flags = SWSUSP and one of SYSTEM_REBOOT, -SYSTEM_SHUTDOWN, SYSTEM_S4 - -Suspend to ram -- put devices into low power state. event = SUSPEND, -flags = SUSPEND_TO_RAM - -Freeze for swsusp snapshot -- stop DMA and interrupts. No need to put -devices into low power mode, but you must be able to reinitialize -device from scratch in resume method. This has two flavors, its done -once on suspending kernel, once on resuming kernel. event = FREEZE, -flags = DURING_SUSPEND or DURING_RESUME - -Device detach requested from /sys -- deinitialize device; proably same as -SYSTEM_SHUTDOWN, I do not understand this one too much. probably event -= FREEZE, flags = DEV_DETACH. - -#These are not really events sent: -# -#System fully on -- device is working normally; this is probably never -#passed to suspend() method... event = ON, flags = 0 -# -#Ready after resume -- userland is now running, again. Time to free any -#memory you ate during prepare to suspend... event = ON, flags = -#READY_AFTER_RESUME -# - - -pm_message_t meaning - -pm_message_t has two fields. event ("major"), and flags. If driver -does not know event code, it aborts the request, returning error. Some -drivers may need to deal with special cases based on the actual type -of suspend operation being done at the system level. This is why -there are flags. - -Event codes are: - -ON -- no need to do anything except special cases like broken -HW. - -# NOTIFICATION -- pretty much same as ON? - -FREEZE -- stop DMA and interrupts, and be prepared to reinit HW from -scratch. That probably means stop accepting upstream requests, the actual policy of what to do with them being specific to a given driver. It's acceptable for a network driver to just drop packets while a block driver is expected to block the queue so no request is diff --git a/Documentation/power/swsusp.txt b/Documentation/power/swsusp.txt index d7814a113ee..516c5019013 100644 --- a/Documentation/power/swsusp.txt +++ b/Documentation/power/swsusp.txt @@ -18,10 +18,11 @@ Some warnings, first. * * (*) suspend/resume support is needed to make it safe. * - * If you have any filesystems on USB devices mounted before suspend, + * If you have any filesystems on USB devices mounted before software suspend, * they won't be accessible after resume and you may lose data, as though - * you have unplugged the USB devices with mounted filesystems on them - * (see the FAQ below for details). + * you have unplugged the USB devices with mounted filesystems on them; + * see the FAQ below for details. (This is not true for more traditional + * power states like "standby", which normally don't turn USB off.) You need to append resume=/dev/your_swap_partition to kernel command line. Then you suspend by @@ -204,7 +205,7 @@ Q: There don't seem to be any generally useful behavioral distinctions between SUSPEND and FREEZE. A: Doing SUSPEND when you are asked to do FREEZE is always correct, -but it may be unneccessarily slow. If you want USB to stay simple, +but it may be unneccessarily slow. If you want your driver to stay simple, slowness may not matter to you. It can always be fixed later. For devices like disk it does matter, you do not want to spindown for @@ -357,17 +358,25 @@ Q: Is this true that if I have a mounted filesystem on a USB device and I suspend to disk, I can lose data unless the filesystem has been mounted with "sync"? -A: That's right. It depends on your hardware, and it could be true even for -suspend-to-RAM. In fact, even with "-o sync" you can lose data if your -programs have information in buffers they haven't written out to disk. +A: That's right ... if you disconnect that device, you may lose data. +In fact, even with "-o sync" you can lose data if your programs have +information in buffers they haven't written out to a disk you disconnect, +or if you disconnect before the device finished saving data you wrote. -If you're lucky, your hardware will support low-power modes for USB -controllers while the system is asleep. Lots of hardware doesn't, -however. Shutting off the power to a USB controller is equivalent to -unplugging all the attached devices. +Software suspend normally powers down USB controllers, which is equivalent +to disconnecting all USB devices attached to your system. + +Your system might well support low-power modes for its USB controllers +while the system is asleep, maintaining the connection, using true sleep +modes like "suspend-to-RAM" or "standby". (Don't write "disk" to the +/sys/power/state file; write "standby" or "mem".) We've not seen any +hardware that can use these modes through software suspend, although in +theory some systems might support "platform" or "firmware" modes that +won't break the USB connections. Remember that it's always a bad idea to unplug a disk drive containing a -mounted filesystem. With USB that's true even when your system is asleep! -The safest thing is to unmount all USB-based filesystems before suspending -and remount them after resuming. +mounted filesystem. That's true even when your system is asleep! The +safest thing is to unmount all filesystems on removable media (such USB, +Firewire, CompactFlash, MMC, external SATA, or even IDE hotplug bays) +before suspending; then remount them after resuming. diff --git a/Documentation/sound/alsa/ALSA-Configuration.txt b/Documentation/sound/alsa/ALSA-Configuration.txt index 0ee2c7dfc48..87d76a5c73d 100644 --- a/Documentation/sound/alsa/ALSA-Configuration.txt +++ b/Documentation/sound/alsa/ALSA-Configuration.txt @@ -366,7 +366,9 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for C-Media CMI8338 and 8738 PCI sound cards. - mpu_port - 0x300,0x310,0x320,0x330, 0 = disable (default) + mpu_port - 0x300,0x310,0x320,0x330 = legacy port, + 1 = integrated PCI port, + 0 = disable (default) fm_port - 0x388 (default), 0 = disable (default) soft_ac3 - Software-conversion of raw SPDIF packets (model 033 only) (default = 1) @@ -468,7 +470,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for multifunction CS5535 companion PCI device - This module supports multiple cards. + The power-management is supported. Module snd-dt019x ----------------- @@ -707,8 +709,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module snd-hda-intel -------------------- - Module for Intel HD Audio (ICH6, ICH6M, ICH7), ATI SB450, - VIA VT8251/VT8237A + Module for Intel HD Audio (ICH6, ICH6M, ESB2, ICH7, ICH8), + ATI SB450, SB600, RS600, + VIA VT8251/VT8237A, + SIS966, ULI M5461 model - force the model name position_fix - Fix DMA pointer (0 = auto, 1 = none, 2 = POSBUF, 3 = FIFO size) @@ -778,6 +782,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. AD1981 basic 3-jack (default) hp HP nx6320 + thinkpad Lenovo Thinkpad T60/X60/Z60 AD1986A 6stack 6-jack, separate surrounds (default) @@ -1633,9 +1638,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. About capture IBL, see the description of snd-vx222 module. - Note: the driver is build only when CONFIG_ISA is set. - - Note2: snd-vxp440 driver is merged to snd-vxpocket driver since + Note: snd-vxp440 driver is merged to snd-vxpocket driver since ALSA 1.0.10. The power-management is supported. @@ -1662,8 +1665,6 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for Sound Core PDAudioCF sound card. - Note: the driver is build only when CONFIG_ISA is set. - The power-management is supported. diff --git a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl index 1faf76383ba..635cbb94357 100644 --- a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl +++ b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl @@ -4215,7 +4215,7 @@ struct _snd_pcm_runtime { <programlisting> <![CDATA[ struct snd_rawmidi *rmidi; - snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, integrated, + snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags, irq, irq_flags, &rmidi); ]]> </programlisting> @@ -4242,15 +4242,36 @@ struct _snd_pcm_runtime { </para> <para> + The 5th argument is bitflags for additional information. When the i/o port address above is a part of the PCI i/o region, the MPU401 i/o port might have been already allocated - (reserved) by the driver itself. In such a case, pass non-zero - to the 5th argument - (<parameter>integrated</parameter>). Otherwise, pass 0 to it, + (reserved) by the driver itself. In such a case, pass a bit flag + <constant>MPU401_INFO_INTEGRATED</constant>, and the mpu401-uart layer will allocate the i/o ports by itself. </para> + <para> + When the controller supports only the input or output MIDI stream, + pass <constant>MPU401_INFO_INPUT</constant> or + <constant>MPU401_INFO_OUTPUT</constant> bitflag, respectively. + Then the rawmidi instance is created as a single stream. + </para> + + <para> + <constant>MPU401_INFO_MMIO</constant> bitflag is used to change + the access method to MMIO (via readb and writeb) instead of + iob and outb. In this case, you have to pass the iomapped address + to <function>snd_mpu401_uart_new()</function>. + </para> + + <para> + When <constant>MPU401_INFO_TX_IRQ</constant> is set, the output + stream isn't checked in the default interrupt handler. The driver + needs to call <function>snd_mpu401_uart_interrupt_tx()</function> + by itself to start processing the output stream in irq handler. + </para> + <para> Usually, the port address corresponds to the command port and port + 1 corresponds to the data port. If not, you may change @@ -5333,7 +5354,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - snd_info_set_text_ops(entry, chip, read_size, my_proc_read); + snd_info_set_text_ops(entry, chip, my_proc_read); ]]> </programlisting> </informalexample> @@ -5394,7 +5415,6 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - entry->c.text.write_size = 256; entry->c.text.write = my_proc_write; ]]> </programlisting> @@ -5402,22 +5422,6 @@ struct _snd_pcm_runtime { </para> <para> - The buffer size for read is set to 1024 implicitly by - <function>snd_info_set_text_ops()</function>. It should suffice - in most cases (the size will be aligned to - <constant>PAGE_SIZE</constant> anyway), but if you need to handle - very large text files, you can set it explicitly, too. - - <informalexample> - <programlisting> -<![CDATA[ - entry->c.text.read_size = 65536; -]]> - </programlisting> - </informalexample> - </para> - - <para> For the write callback, you can use <function>snd_info_get_line()</function> to get a text line, and <function>snd_info_get_str()</function> to retrieve a string from @@ -5562,7 +5566,7 @@ struct _snd_pcm_runtime { power status.</para></listitem> <listitem><para>Call <function>snd_pcm_suspend_all()</function> to suspend the running PCM streams.</para></listitem> <listitem><para>If AC97 codecs are used, call - <function>snd_ac97_resume()</function> for each codec.</para></listitem> + <function>snd_ac97_suspend()</function> for each codec.</para></listitem> <listitem><para>Save the register values if necessary.</para></listitem> <listitem><para>Stop the hardware if necessary.</para></listitem> <listitem><para>Disable the PCI device by calling diff --git a/Documentation/usb/usbmon.txt b/Documentation/usb/usbmon.txt index 63cb7edd177..e65ec828d7a 100644 --- a/Documentation/usb/usbmon.txt +++ b/Documentation/usb/usbmon.txt @@ -29,14 +29,13 @@ if usbmon is built into the kernel. # mount -t debugfs none_debugs /sys/kernel/debug # modprobe usbmon +# Verify that bus sockets are present. -[root@lembas zaitcev]# ls /sys/kernel/debug/usbmon +# ls /sys/kernel/debug/usbmon 1s 1t 2s 2t 3s 3t 4s 4t -[root@lembas zaitcev]# - -# ls /sys/kernel +# 2. Find which bus connects to the desired device @@ -76,7 +75,7 @@ that the file size is not excessive for your favourite editor. * Raw text data format -The '0t' type data consists of a stream of events, such as URB submission, +The '1t' type data consists of a stream of events, such as URB submission, URB callback, submission error. Every event is a text line, which consists of whitespace separated words. The number of position of words may depend on the event type, but there is a set of words, common for all types. @@ -97,20 +96,25 @@ Here is the list of words, from left to right: Zi Zo Isochronous input and output Ii Io Interrupt input and output Bi Bo Bulk input and output - Device address and Endpoint number are decimal numbers with leading zeroes - or 3 and 2 positions, correspondingly. -- URB Status. This field makes no sense for submissions, but is present - to help scripts with parsing. In error case, it contains the error code. - In case of a setup packet, it contains a Setup Tag. If scripts read a number - in this field, they proceed to read Data Length. Otherwise, they read - the setup packet before reading the Data Length. + Device address and Endpoint number are 3-digit and 2-digit (respectively) + decimal numbers, with leading zeroes. +- URB Status. In most cases, this field contains a number, sometimes negative, + which represents a "status" field of the URB. This field makes no sense for + submissions, but is present anyway to help scripts with parsing. When an + error occurs, the field contains the error code. In case of a submission of + a Control packet, this field contains a Setup Tag instead of an error code. + It is easy to tell whether the Setup Tag is present because it is never a + number. Thus if scripts find a number in this field, they proceed to read + Data Length. If they find something else, like a letter, they read the setup + packet before reading the Data Length. - Setup packet, if present, consists of 5 words: one of each for bmRequestType, bRequest, wValue, wIndex, wLength, as specified by the USB Specification 2.0. These words are safe to decode if Setup Tag was 's'. Otherwise, the setup packet was present, but not captured, and the fields contain filler. -- Data Length. This is the actual length in the URB. +- Data Length. For submissions, this is the requested length. For callbacks, + this is the actual length. - Data tag. The usbmon may not always capture data, even if length is nonzero. - Only if tag is '=', the data words are present. + The data words are present only if this tag is '='. - Data words follow, in big endian hexadecimal format. Notice that they are not machine words, but really just a byte stream split into words to make it easier to read. Thus, the last word may contain from one to four bytes. |