diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/HOWTO | 1 | ||||
| -rw-r--r-- | Documentation/feature-removal-schedule.txt | 17 | ||||
| -rw-r--r-- | Documentation/s390/Debugging390.txt | 2 | ||||
| -rw-r--r-- | Documentation/usb/proc_usb_info.txt | 21 | ||||
| -rw-r--r-- | Documentation/usb/usbmon.txt | 152 | ||||
| -rw-r--r-- | Documentation/video-output.txt | 34 |
6 files changed, 213 insertions, 14 deletions
diff --git a/Documentation/HOWTO b/Documentation/HOWTO index 8d51c148f72..48123dba5e6 100644 --- a/Documentation/HOWTO +++ b/Documentation/HOWTO @@ -30,6 +30,7 @@ are not a good substitute for a solid C education and/or years of experience, the following books are good for, if anything, reference: - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] - "Practical C Programming" by Steve Oualline [O'Reilly] + - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] The kernel is written using GNU C and the GNU toolchain. While it adheres to the ISO C89 standard, it uses a number of extensions that are diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index 0ba6af02cda..2dc5e5da8f8 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -274,6 +274,7 @@ Who: Venkatesh Pallipadi <venkatesh.pallipadi@intel.com> --------------------------- +<<<<<<< test:Documentation/feature-removal-schedule.txt What: ACPI hotkey driver (CONFIG_ACPI_HOTKEY) When: 2.6.21 Why: hotkey.c was an attempt to consolidate multiple drivers that use @@ -306,11 +307,18 @@ Why: The ACPI namespace is effectively the symbol list for the BIOS can be extracted and disassembled with acpidump and iasl as documented in the pmtools package here: http://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/utils - Who: Len Brown <len.brown@intel.com> --------------------------- +What: ACPI procfs interface +When: July 2007 +Why: After ACPI sysfs conversion, ACPI attributes will be duplicated + in sysfs and the ACPI procfs interface should be removed. +Who: Zhang Rui <rui.zhang@intel.com> + +--------------------------- + What: /proc/acpi/button When: August 2007 Why: /proc/acpi/button has been replaced by events to the input layer @@ -325,3 +333,10 @@ Why: Unmaintained for years, superceded by JFFS2 for years. Who: Jeff Garzik <jeff@garzik.org> --------------------------- + +What: sk98lin network driver +When: July 2007 +Why: In kernel tree version of driver is unmaintained. Sk98lin driver + replaced by the skge driver. +Who: Stephen Hemminger <shemminger@osdl.org> + diff --git a/Documentation/s390/Debugging390.txt b/Documentation/s390/Debugging390.txt index 3f9ddbc23b2..0993969609c 100644 --- a/Documentation/s390/Debugging390.txt +++ b/Documentation/s390/Debugging390.txt @@ -480,7 +480,7 @@ r2 argument 0 / return value 0 call-clobbered r3 argument 1 / return value 1 (if long long) call-clobbered r4 argument 2 call-clobbered r5 argument 3 call-clobbered -r6 argument 5 saved +r6 argument 4 saved r7 pointer-to arguments 5 to ... saved r8 this & that saved r9 this & that saved diff --git a/Documentation/usb/proc_usb_info.txt b/Documentation/usb/proc_usb_info.txt index 22c5331260c..077e9032d0c 100644 --- a/Documentation/usb/proc_usb_info.txt +++ b/Documentation/usb/proc_usb_info.txt @@ -213,15 +213,16 @@ C:* #Ifs=dd Cfg#=dd Atr=xx MPwr=dddmA Interface descriptor info (can be multiple per Config): -I: If#=dd Alt=dd #EPs=dd Cls=xx(sssss) Sub=xx Prot=xx Driver=ssss -| | | | | | | |__Driver name -| | | | | | | or "(none)" -| | | | | | |__InterfaceProtocol -| | | | | |__InterfaceSubClass -| | | | |__InterfaceClass -| | | |__NumberOfEndpoints -| | |__AlternateSettingNumber -| |__InterfaceNumber +I:* If#=dd Alt=dd #EPs=dd Cls=xx(sssss) Sub=xx Prot=xx Driver=ssss +| | | | | | | | |__Driver name +| | | | | | | | or "(none)" +| | | | | | | |__InterfaceProtocol +| | | | | | |__InterfaceSubClass +| | | | | |__InterfaceClass +| | | | |__NumberOfEndpoints +| | | |__AlternateSettingNumber +| | |__InterfaceNumber +| |__ "*" indicates the active altsetting (others are " ") |__Interface info tag A given interface may have one or more "alternate" settings. @@ -277,7 +278,7 @@ of the USB devices on a system's root hub. (See more below on how to do this.) The Interface lines can be used to determine what driver is -being used for each device. +being used for each device, and which altsetting it activated. The Configuration lines could be used to list maximum power (in milliamps) that a system's USB devices are using. diff --git a/Documentation/usb/usbmon.txt b/Documentation/usb/usbmon.txt index e65ec828d7a..0f6808abd61 100644 --- a/Documentation/usb/usbmon.txt +++ b/Documentation/usb/usbmon.txt @@ -77,7 +77,7 @@ that the file size is not excessive for your favourite editor. 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 +of whitespace separated words. The number or position of words may depend on the event type, but there is a set of words, common for all types. Here is the list of words, from left to right: @@ -170,4 +170,152 @@ dd65f0e8 4128379808 C Bo:005:02 0 31 > * Raw binary format and API -TBD +The overall architecture of the API is about the same as the one above, +only the events are delivered in binary format. Each event is sent in +the following structure (its name is made up, so that we can refer to it): + +struct usbmon_packet { + u64 id; /* 0: URB ID - from submission to callback */ + unsigned char type; /* 8: Same as text; extensible. */ + unsigned char xfer_type; /* ISO (0), Intr, Control, Bulk (3) */ + unsigned char epnum; /* Endpoint number and transfer direction */ + unsigned char devnum; /* Device address */ + u16 busnum; /* 12: Bus number */ + char flag_setup; /* 14: Same as text */ + char flag_data; /* 15: Same as text; Binary zero is OK. */ + s64 ts_sec; /* 16: gettimeofday */ + s32 ts_usec; /* 24: gettimeofday */ + int status; /* 28: */ + unsigned int length; /* 32: Length of data (submitted or actual) */ + unsigned int len_cap; /* 36: Delivered length */ + unsigned char setup[8]; /* 40: Only for Control 'S' */ +}; /* 48 bytes total */ + +These events can be received from a character device by reading with read(2), +with an ioctl(2), or by accessing the buffer with mmap. + +The character device is usually called /dev/usbmonN, where N is the USB bus +number. Number zero (/dev/usbmon0) is special and means "all buses". +However, this feature is not implemented yet. Note that specific naming +policy is set by your Linux distribution. + +If you create /dev/usbmon0 by hand, make sure that it is owned by root +and has mode 0600. Otherwise, unpriviledged users will be able to snoop +keyboard traffic. + +The following ioctl calls are available, with MON_IOC_MAGIC 0x92: + + MON_IOCQ_URB_LEN, defined as _IO(MON_IOC_MAGIC, 1) + +This call returns the length of data in the next event. Note that majority of +events contain no data, so if this call returns zero, it does not mean that +no events are available. + + MON_IOCG_STATS, defined as _IOR(MON_IOC_MAGIC, 3, struct mon_bin_stats) + +The argument is a pointer to the following structure: + +struct mon_bin_stats { + u32 queued; + u32 dropped; +}; + +The member "queued" refers to the number of events currently queued in the +buffer (and not to the number of events processed since the last reset). + +The member "dropped" is the number of events lost since the last call +to MON_IOCG_STATS. + + MON_IOCT_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 4) + +This call sets the buffer size. The argument is the size in bytes. +The size may be rounded down to the next chunk (or page). If the requested +size is out of [unspecified] bounds for this kernel, the call fails with +-EINVAL. + + MON_IOCQ_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 5) + +This call returns the current size of the buffer in bytes. + + MON_IOCX_GET, defined as _IOW(MON_IOC_MAGIC, 6, struct mon_get_arg) + +This call waits for events to arrive if none were in the kernel buffer, +then returns the first event. Its argument is a pointer to the following +structure: + +struct mon_get_arg { + struct usbmon_packet *hdr; + void *data; + size_t alloc; /* Length of data (can be zero) */ +}; + +Before the call, hdr, data, and alloc should be filled. Upon return, the area +pointed by hdr contains the next event structure, and the data buffer contains +the data, if any. The event is removed from the kernel buffer. + + MON_IOCX_MFETCH, defined as _IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg) + +This ioctl is primarily used when the application accesses the buffer +with mmap(2). Its argument is a pointer to the following structure: + +struct mon_mfetch_arg { + uint32_t *offvec; /* Vector of events fetched */ + uint32_t nfetch; /* Number of events to fetch (out: fetched) */ + uint32_t nflush; /* Number of events to flush */ +}; + +The ioctl operates in 3 stages. + +First, it removes and discards up to nflush events from the kernel buffer. +The actual number of events discarded is returned in nflush. + +Second, it waits for an event to be present in the buffer, unless the pseudo- +device is open with O_NONBLOCK. + +Third, it extracts up to nfetch offsets into the mmap buffer, and stores +them into the offvec. The actual number of event offsets is stored into +the nfetch. + + MON_IOCH_MFLUSH, defined as _IO(MON_IOC_MAGIC, 8) + +This call removes a number of events from the kernel buffer. Its argument +is the number of events to remove. If the buffer contains fewer events +than requested, all events present are removed, and no error is reported. +This works when no events are available too. + + FIONBIO + +The ioctl FIONBIO may be implemented in the future, if there's a need. + +In addition to ioctl(2) and read(2), the special file of binary API can +be polled with select(2) and poll(2). But lseek(2) does not work. + +* Memory-mapped access of the kernel buffer for the binary API + +The basic idea is simple: + +To prepare, map the buffer by getting the current size, then using mmap(2). +Then, execute a loop similar to the one written in pseudo-code below: + + struct mon_mfetch_arg fetch; + struct usbmon_packet *hdr; + int nflush = 0; + for (;;) { + fetch.offvec = vec; // Has N 32-bit words + fetch.nfetch = N; // Or less than N + fetch.nflush = nflush; + ioctl(fd, MON_IOCX_MFETCH, &fetch); // Process errors, too + nflush = fetch.nfetch; // This many packets to flush when done + for (i = 0; i < nflush; i++) { + hdr = (struct ubsmon_packet *) &mmap_area[vec[i]]; + if (hdr->type == '@') // Filler packet + continue; + caddr_t data = &mmap_area[vec[i]] + 64; + process_packet(hdr, data); + } + } + +Thus, the main idea is to execute only one ioctl per N events. + +Although the buffer is circular, the returned headers and data do not cross +the end of the buffer, so the above pseudo-code does not need any gathering. diff --git a/Documentation/video-output.txt b/Documentation/video-output.txt new file mode 100644 index 00000000000..e517011be4f --- /dev/null +++ b/Documentation/video-output.txt @@ -0,0 +1,34 @@ + + Video Output Switcher Control + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + 2006 luming.yu@intel.com + +The output sysfs class driver provides an abstract video output layer that +can be used to hook platform specific methods to enable/disable video output +device through common sysfs interface. For example, on my IBM ThinkPad T42 +laptop, The ACPI video driver registered its output devices and read/write +method for 'state' with output sysfs class. The user interface under sysfs is: + +linux:/sys/class/video_output # tree . +. +|-- CRT0 +| |-- device -> ../../../devices/pci0000:00/0000:00:01.0 +| |-- state +| |-- subsystem -> ../../../class/video_output +| `-- uevent +|-- DVI0 +| |-- device -> ../../../devices/pci0000:00/0000:00:01.0 +| |-- state +| |-- subsystem -> ../../../class/video_output +| `-- uevent +|-- LCD0 +| |-- device -> ../../../devices/pci0000:00/0000:00:01.0 +| |-- state +| |-- subsystem -> ../../../class/video_output +| `-- uevent +`-- TV0 + |-- device -> ../../../devices/pci0000:00/0000:00:01.0 + |-- state + |-- subsystem -> ../../../class/video_output + `-- uevent + |