diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index a221039ee4c9..393082c7a3a2 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -7,10 +7,9 @@ # list of DOCBOOKS. DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \ - kernel-hacking.xml kernel-locking.xml via-audio.xml \ - deviceiobook.xml procfs-guide.xml tulip-user.xml \ - writing_usb_driver.xml scsidrivers.xml sis900.xml \ - kernel-api.xml journal-api.xml lsm.xml usb.xml \ + kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ + procfs-guide.xml writing_usb_driver.xml scsidrivers.xml \ + sis900.xml kernel-api.xml journal-api.xml lsm.xml usb.xml \ gadget.xml libata.xml mtdnand.xml librs.xml ### diff --git a/Documentation/DocBook/tulip-user.tmpl b/Documentation/DocBook/tulip-user.tmpl deleted file mode 100644 index 6520d7a1b132..000000000000 --- a/Documentation/DocBook/tulip-user.tmpl +++ /dev/null @@ -1,327 +0,0 @@ - - - - - - Tulip Driver User's Guide - - - - Jeff - Garzik - -
- jgarzik@pobox.com -
- - - - - - 2001 - Jeff Garzik - - - - - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - - - - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - - - - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - - - - For more details see the file COPYING in the source - distribution of Linux. - - - - - - - - Introduction - -The Tulip Ethernet Card Driver -is maintained by Jeff Garzik (jgarzik@pobox.com). - - - -The Tulip driver was developed by Donald Becker and changed by -Jeff Garzik, Takashi Manabe and a cast of thousands. - - - -For 2.4.x and later kernels, the Linux Tulip driver is available at -http://sourceforge.net/projects/tulip/ - - - - This driver is for the Digital "Tulip" Ethernet adapter interface. - It should work with most DEC 21*4*-based chips/ethercards, as well as - with work-alike chips from Lite-On (PNIC) and Macronix (MXIC) and ASIX. - - - - The original author may be reached as becker@scyld.com, or C/O - Scyld Computing Corporation, - 410 Severn Ave., Suite 210, - Annapolis MD 21403 - - - - Additional information on Donald Becker's tulip.c - is available at http://www.scyld.com/network/tulip.html - - - - - - Driver Compatibility - - -This device driver is designed for the DECchip "Tulip", Digital's -single-chip ethernet controllers for PCI (now owned by Intel). -Supported members of the family -are the 21040, 21041, 21140, 21140A, 21142, and 21143. Similar work-alike -chips from Lite-On, Macronics, ASIX, Compex and other listed below are also -supported. - - - -These chips are used on at least 140 unique PCI board designs. The great -number of chips and board designs supported is the reason for the -driver size and complexity. Almost of the increasing complexity is in the -board configuration and media selection code. There is very little -increasing in the operational critical path length. - - - - - Board-specific Settings - - -PCI bus devices are configured by the system at boot time, so no jumpers -need to be set on the board. The system BIOS preferably should assign the -PCI INTA signal to an otherwise unused system IRQ line. - - - -Some boards have EEPROMs tables with default media entry. The factory default -is usually "autoselect". This should only be overridden when using -transceiver connections without link beat e.g. 10base2 or AUI, or (rarely!) -for forcing full-duplex when used with old link partners that do not do -autonegotiation. - - - - - Driver Operation - -Ring buffers - - -The Tulip can use either ring buffers or lists of Tx and Rx descriptors. -This driver uses statically allocated rings of Rx and Tx descriptors, set at -compile time by RX/TX_RING_SIZE. This version of the driver allocates skbuffs -for the Rx ring buffers at open() time and passes the skb->data field to the -Tulip as receive data buffers. When an incoming frame is less than -RX_COPYBREAK bytes long, a fresh skbuff is allocated and the frame is -copied to the new skbuff. When the incoming frame is larger, the skbuff is -passed directly up the protocol stack and replaced by a newly allocated -skbuff. - - - -The RX_COPYBREAK value is chosen to trade-off the memory wasted by -using a full-sized skbuff for small frames vs. the copying costs of larger -frames. For small frames the copying cost is negligible (esp. considering -that we are pre-loading the cache with immediately useful header -information). For large frames the copying cost is non-trivial, and the -larger copy might flush the cache of useful data. A subtle aspect of this -choice is that the Tulip only receives into longword aligned buffers, thus -the IP header at offset 14 isn't longword aligned for further processing. -Copied frames are put into the new skbuff at an offset of "+2", thus copying -has the beneficial effect of aligning the IP header and preloading the -cache. - - - - -Synchronization - -The driver runs as two independent, single-threaded flows of control. One -is the send-packet routine, which enforces single-threaded use by the -dev->tbusy flag. The other thread is the interrupt handler, which is single -threaded by the hardware and other software. - - - -The send packet thread has partial control over the Tx ring and 'dev->tbusy' -flag. It sets the tbusy flag whenever it's queuing a Tx packet. If the next -queue slot is empty, it clears the tbusy flag when finished otherwise it sets -the 'tp->tx_full' flag. - - - -The interrupt handler has exclusive control over the Rx ring and records stats -from the Tx ring. (The Tx-done interrupt can't be selectively turned off, so -we can't avoid the interrupt overhead by having the Tx routine reap the Tx -stats.) After reaping the stats, it marks the queue entry as empty by setting -the 'base' to zero. Iff the 'tp->tx_full' flag is set, it clears both the -tx_full and tbusy flags. - - - - - - - - Errata - - -The old DEC databooks were light on details. -The 21040 databook claims that CSR13, CSR14, and CSR15 should each be the last -register of the set CSR12-15 written. Hmmm, now how is that possible? - - - -The DEC SROM format is very badly designed not precisely defined, leading to -part of the media selection junkheap below. Some boards do not have EEPROM -media tables and need to be patched up. Worse, other boards use the DEC -design kit media table when it isn't correct for their board. - - - -We cannot use MII interrupts because there is no defined GPIO pin to attach -them. The MII transceiver status is polled using an kernel timer. - - - - - Driver Change History - - Version 0.9.14 (February 20, 2001) - - Fix PNIC problems (Manfred Spraul) - Add new PCI id for Accton comet - Support Davicom tulips - Fix oops in eeprom parsing - Enable workarounds for early PCI chipsets - IA64, hppa csr0 support - Support media types 5, 6 - Interpret a bit more of the 21142 SROM extended media type 3 - Add missing delay in eeprom reading - - - - Version 0.9.11 (November 3, 2000) - - Eliminate extra bus accesses when sharing interrupts (prumpf) - Barrier following ownership descriptor bit flip (prumpf) - Endianness fixes for >14 addresses in setup frames (prumpf) - Report link beat to kernel/userspace via netif_carrier_*. (kuznet) - Better spinlocking in set_rx_mode. - Fix I/O resource request failure error messages (DaveM catch) - Handle DMA allocation failure. - - - - Version 0.9.10 (September 6, 2000) - - Simple interrupt mitigation (via jamal) - More PCI ids - - - - Version 0.9.9 (August 11, 2000) - - More PCI ids - - - - Version 0.9.8 (July 13, 2000) - - Correct signed/unsigned comparison for dummy frame index - Remove outdated references to struct enet_statistics - - - - Version 0.9.7 (June 17, 2000) - - Timer cleanups (Andrew Morton) - Alpha compile fix (somebody?) - - - - Version 0.9.6 (May 31, 2000) - - Revert 21143-related support flag patch - Add HPPA/media-table debugging printk - - - - Version 0.9.5 (May 30, 2000) - - HPPA support (willy@puffingroup) - CSR6 bits and tulip.h cleanup (Chris Smith) - Improve debugging messages a bit - Add delay after CSR13 write in t21142_start_nway - Remove unused ETHER_STATS code - Convert 'extern inline' to 'static inline' in tulip.h (Chris Smith) - Update DS21143 support flags in tulip_chip_info[] - Use spin_lock_irq, not _irqsave/restore, in tulip_start_xmit() - Add locking to set_rx_mode() - Fix race with chip setting DescOwned bit (Hal Murray) - Request 100% of PIO and MMIO resource space assigned to card - Remove error message from pci_enable_device failure - - - - Version 0.9.4.3 (April 14, 2000) - - mod_timer fix (Hal Murray) - PNIC2 resuscitation (Chris Smith) - - - - Version 0.9.4.2 (March 21, 2000) - - Fix 21041 CSR7, CSR13/14/15 handling - Merge some PCI ids from tulip 0.91x - Merge some HAS_xxx flags and flag settings from tulip 0.91x - asm/io.h fix (submitted by many) and cleanup - s/HAS_NWAY143/HAS_NWAY/ - Cleanup 21041 mode reporting - Small code cleanups - - - - Version 0.9.4.1 (March 18, 2000) - - Finish PCI DMA conversion (davem) - Do not netif_start_queue() at end of tulip_tx_timeout() (kuznet) - PCI DMA fix (kuznet) - eeprom.c code cleanup - Remove Xircom Tulip crud - - - - - diff --git a/Documentation/DocBook/via-audio.tmpl b/Documentation/DocBook/via-audio.tmpl deleted file mode 100644 index 36e642147d6b..000000000000 --- a/Documentation/DocBook/via-audio.tmpl +++ /dev/null @@ -1,597 +0,0 @@ - - - - - - Via 686 Audio Driver for Linux - - - - Jeff - Garzik - - - - - 1999-2001 - Jeff Garzik - - - - - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - - - - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - - - - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - - - - For more details see the file COPYING in the source - distribution of Linux. - - - - - - - - Introduction - - The Via VT82C686A "super southbridge" chips contain - AC97-compatible audio logic which features dual 16-bit stereo - PCM sound channels (full duplex), plus a third PCM channel intended for use - in hardware-assisted FM synthesis. - - - The current Linux kernel audio driver for this family of chips - supports audio playback and recording, but hardware-assisted - FM features, and hardware buffer direct-access (mmap) - support are not yet available. - - - This driver supports any Linux kernel version after 2.4.10. - - - Please send bug reports to the mailing list linux-via@gtf.org. - To subscribe, e-mail majordomo@gtf.org with - - - subscribe linux-via - - - in the body of the message. - - - - - Driver Installation - - To use this audio driver, select the - CONFIG_SOUND_VIA82CXXX option in the section Sound during kernel configuration. - Follow the usual kernel procedures for rebuilding the kernel, - or building and installing driver modules. - - - To make this driver the default audio driver, you can add the - following to your /etc/conf.modules file: - - - alias sound via82cxxx_audio - - - Note that soundcore and ac97_codec support modules - are also required for working audio, in addition to - the via82cxxx_audio module itself. - - - - - Submitting a bug report - Description of problem - - Describe the application you were using to play/record sound, and how - to reproduce the problem. - - - Diagnostic output - - Obtain the via-audio-diag diagnostics program from - http://sf.net/projects/gkernel/ and provide a dump of the - audio chip's registers while the problem is occurring. Sample command line: - - - ./via-audio-diag -aps > diag-output.txt - - - Driver debug output - - Define VIA_DEBUG at the beginning of the driver, then capture and email - the kernel log output. This can be viewed in the system kernel log (if - enabled), or via the dmesg program. Sample command line: - - - dmesg > /tmp/dmesg-output.txt - - - Bigger kernel message buffer - - If you wish to increase the size of the buffer displayed by dmesg, then - change the LOG_BUF_LEN macro at the top of linux/kernel/printk.c, recompile - your kernel, and pass the LOG_BUF_LEN value to dmesg. Sample command line with - LOG_BUF_LEN == 32768: - - - dmesg -s 32768 > /tmp/dmesg-output.txt - - - - - - Known Bugs And Assumptions - - - Low volume - - - Volume too low on many systems. Workaround: use mixer program - such as xmixer to increase volume. - - - - - - - - - - Thanks - - Via for providing e-mail support, specs, and NDA'd source code. - - - MandrakeSoft for providing hacking time. - - - AC97 mixer interface fixes and debugging by Ron Cemer roncemer@gte.net. - - - Rui Sousa rui.sousa@conexant.com, for bugfixing - MMAP support, and several other notable fixes that resulted from - his hard work and testing. - - - Adrian Cox adrian@humboldt.co.uk, for bugfixing - MMAP support, and several other notable fixes that resulted from - his hard work and testing. - - - Thomas Sailer for further bugfixes. - - - - - Random Notes - - Two /proc pseudo-files provide diagnostic information. This is generally - not useful to most users. Power users can disable CONFIG_SOUND_VIA82CXXX_PROCFS, - and remove the /proc support code. Once - version 2.0.0 is released, the /proc support code will be disabled by - default. Available /proc pseudo-files: - - - /proc/driver/via/0/info - /proc/driver/via/0/ac97 - - - This driver by default supports all PCI audio devices which report - a vendor id of 0x1106, and a device id of 0x3058. Subsystem vendor - and device ids are not examined. - - - GNU indent formatting options: - --kr -i8 -ts8 -br -ce -bap -sob -l80 -pcs -cs -ss -bs -di1 -nbc -lp -psl - - - - Via has graciously donated e-mail support and source code to help further - the development of this driver. Their assistance has been invaluable - in the design and coding of the next major version of this driver. - - - The Via audio chip apparently provides a second PCM scatter-gather - DMA channel just for FM data, but does not have a full hardware MIDI - processor. I haven't put much thought towards a solution here, but it - might involve using SoftOSS midi wave table, or simply disabling MIDI - support altogether and using the FM PCM channel as a second (input? output?) - - - - - Driver ChangeLog - - -Version 1.9.1 - - - - - DSP read/write bugfixes from Thomas Sailer. - - - - - - Add new PCI id for single-channel use of Via 8233. - - - - - - Other bug fixes, tweaks, new ioctls. - - - - - - - -Version 1.1.15 - - - - - Support for variable fragment size and variable fragment number (Rui - Sousa) - - - - - - Fixes for the SPEED, STEREO, CHANNELS, FMT ioctls when in read & - write mode (Rui Sousa) - - - - - - Mmaped sound is now fully functional. (Rui Sousa) - - - - - - Make sure to enable PCI device before reading any of its PCI - config information. (fixes potential hotplug problems) - - - - - - Clean up code a bit and add more internal function documentation. - - - - - - AC97 codec access fixes (Adrian Cox) - - - - - - Big endian fixes (Adrian Cox) - - - - - - MIDI support (Adrian Cox) - - - - - - Detect and report locked-rate AC97 codecs. If your hardware only - supports 48Khz (locked rate), then your recording/playback software - must upsample or downsample accordingly. The hardware cannot do it. - - - - - - Use new pci_request_regions and pci_disable_device functions in - kernel 2.4.6. - - - - - - - -Version 1.1.14 - - - - - Use VM_RESERVE when available, to eliminate unnecessary page faults. - - - - - - -Version 1.1.12 - - - - - mmap bug fixes from Linus. - - - - - - -Version 1.1.11 - - - - - Many more bug fixes. mmap enabled by default, but may still be buggy. - - - - - - Uses new and spiffy method of mmap'ing the DMA buffer, based - on a suggestion from Linus. - - - - - - -Version 1.1.10 - - - - - Many bug fixes. mmap enabled by default, but may still be buggy. - - - - - - -Version 1.1.9 - - - - - Redesign and rewrite audio playback implementation. (faster and smaller, hopefully) - - - - - - Implement recording and full duplex (DSP_CAP_DUPLEX) support. - - - - - - Make procfs support optional. - - - - - - Quick interrupt status check, to lessen overhead in interrupt - sharing situations. - - - - - - Add mmap(2) support. Disabled for now, it is still buggy and experimental. - - - - - - Surround all syscalls with a semaphore for cheap and easy SMP protection. - - - - - - Fix bug in channel shutdown (hardware channel reset) code. - - - - - - Remove unnecessary spinlocks (better performance). - - - - - - Eliminate "unknown AFMT" message by using a different method - of selecting the best AFMT_xxx sound sample format for use. - - - - - - Support for realtime hardware pointer position reporting - (DSP_CAP_REALTIME, SNDCTL_DSP_GETxPTR ioctls) - - - - - - Support for capture/playback triggering - (DSP_CAP_TRIGGER, SNDCTL_DSP_SETTRIGGER ioctls) - - - - - - SNDCTL_DSP_SETDUPLEX and SNDCTL_DSP_POST ioctls now handled. - - - - - - Rewrite open(2) and close(2) logic to allow only one user at - a time. All other open(2) attempts will sleep until they succeed. - FIXME: open(O_RDONLY) and open(O_WRONLY) should be allowed to succeed. - - - - - - Reviewed code to ensure that SMP and multiple audio devices - are fully supported. - - - - - - - -Version 1.1.8 - - - - - Clean up interrupt handler output. Fixes the following kernel error message: - - - unhandled interrupt ... - - - - - - Convert documentation to DocBook, so that PDF, HTML and PostScript (.ps) output is readily - available. - - - - - - - -Version 1.1.7 - - - - - Fix module unload bug where mixer device left registered - after driver exit - - - - - - -Version 1.1.6 - - - - - Rewrite via_set_rate to mimic ALSA basic AC97 rate setting - - - - - Remove much dead code - - - - - Complete spin_lock_irqsave -> spin_lock_irq conversion in via_dsp_ioctl - - - - - Fix build problem in via_dsp_ioctl - - - - - Optimize included headers to eliminate headers found in linux/sound - - - - - - -Version 1.1.5 - - - - - Disable some overly-verbose debugging code - - - - - Remove unnecessary sound locks - - - - - Fix some ioctls for better time resolution - - - - - Begin spin_lock_irqsave -> spin_lock_irq conversion in via_dsp_ioctl - - - - - - -Version 1.1.4 - - - - - Completed rewrite of driver. Eliminated SoundBlaster compatibility - completely, and now uses the much-faster scatter-gather DMA engine. - - - - - - - - - Internal Functions -!Isound/oss/via82cxxx_audio.c - - - - -