From: Marc Fiuczynski Date: Mon, 7 Feb 2005 21:51:36 +0000 (+0000) Subject: This commit was generated by cvs2svn to compensate for changes in r517, X-Git-Tag: before-fedora-2_6_18-1_2239_FC5-vs2_0_2_2-rc6-merge~263 X-Git-Url: http://git.onelab.eu/?a=commitdiff_plain;h=433e2af4175021d339b067f6e7ee0a4e4c4f7e2d;p=linux-2.6.git This commit was generated by cvs2svn to compensate for changes in r517, which included commits to RCS files with non-trunk default branches. --- diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 008c5471f..a8c19aa34 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -20,6 +20,8 @@ Changes - list of changes that break older software packages. CodingStyle - how the boss likes the C code in the kernel to look. +DMA-API.txt + - DMA API, pci_ API & extensions for non-consistent memory machines. DMA-mapping.txt - info for PCI drivers using DMA portably across all platforms. DocBook/ @@ -30,8 +32,12 @@ IPMI.txt - info on Linux Intelligent Platform Management Interface (IPMI) Driver. IRQ-affinity.txt - how to select which CPU(s) handle which interrupt events on SMP. +ManagementStyle + - how to (attempt to) manage kernel hackers. MSI-HOWTO.txt - the Message Signaled Interrupts (MSI) Driver Guide HOWTO and FAQ. +RCU/ + - directory with info on RCU (read-copy update). README.DAC960 - info on Mylex DAC960/DAC1100 PCI RAID Controller Driver for Linux. README.moxa @@ -46,8 +52,6 @@ VGA-softcursor.txt - how to change your VGA cursor from a blinking underscore. arm/ - directory with info about Linux on the ARM architecture. -as-iosched.txt - - info on anticipatory IO scheduler. basic_profiling.txt - basic instructions for those who wants to profile Linux kernel. binfmt_misc.txt @@ -60,20 +64,24 @@ cciss.txt - info, major/minor #'s for Compaq's SMART Array Controllers. cdrom/ - directory with information on the CD-ROM drivers that Linux has. +cli-sti-removal.txt + - cli()/sti() removal guide. computone.txt - info on Computone Intelliport II/Plus Multiport Serial Driver. cpqarray.txt - info on using Compaq's SMART2 Intelligent Disk Array Controllers. -cpufreq/ +cpu-freq/ - info on CPU frequency and voltage scaling. cris/ - directory with info about Linux on CRIS architecture. +crypto/ + - directory with info on the Crypto API. debugging-modules.txt - some notes on debugging modules after Linux 2.6.3. +device-mapper/ + - directory with info on Device Mapper. devices.txt - plain ASCII listing of all the nodes in /dev/ with major minor #'s. -digiboard.txt - - info on the Digiboard PC/X{i,e,eve} multiport boards. digiepca.txt - info on Digi Intl. {PC,PCI,EISA}Xx and Xem series cards. dnotify.txt @@ -92,6 +100,8 @@ fb/ - directory with info on the frame buffer graphics abstraction layer. filesystems/ - directory with info on the various filesystems that Linux supports. +firmware_class/ + - request_firmware() hotplug interface info. floppy.txt - notes and driver options for the floppy disk driver. ftape.txt @@ -100,10 +110,14 @@ hayes-esp.txt - info on using the Hayes ESP serial driver. highuid.txt - notes on the change from 16 bit to 32 bit user/group IDs. +hpet.txt + - High Precision Event Timer Driver for Linux. hw_random.txt - info on Linux support for random number generator in i8xx chipsets. i2c/ - directory with info about the I2C bus/protocol (2 wire, kHz speed). +i2o/ + - directory with info about the Linux I2O subsystem. i386/ - directory with info about Linux on Intel 32 bit architecture. ia64/ @@ -114,6 +128,8 @@ initrd.txt - how to use the RAM disk as an initial/temporary root filesystem. input/ - info on Linux input device support. +io_ordering.txt + - info on ordering I/O writes to memory-mapped addresses. ioctl-number.txt - how to implement and register device/driver ioctl calls. iostats.txt @@ -134,6 +150,8 @@ kernel-parameters.txt - summary listing of command line / boot prompt args for the kernel. kobject.txt - info of the kobject infrastructure of the Linux kernel. +laptop-mode.txt + - How to conserve battery power using laptop-mode. ldm.txt - a brief description of LDM (Windows Dynamic Disks). locks.txt @@ -158,8 +176,8 @@ mips/ - directory with info about Linux on MIPS architecture. mkdev.cciss - script to make /dev entries for SMART controllers (see cciss.txt). -mkdev.ida - - script to make /dev entries for Intelligent Disk Array Controllers. +mono.txt + - how to execute Mono-based .NET binaries with the help of BINFMT_MISC. moxa-smartio - info on installing/using Moxa multiport serial driver. mtrr.txt @@ -172,6 +190,8 @@ nfsroot.txt - short guide on setting up a diskless box with NFS root filesystem. nmi_watchdog.txt - info on NMI watchdog for SMP systems. +numastat.txt + - info on how to read Numa policy hit/miss statistics in sysfs. oops-tracing.txt - how to decode those nasty internal kernel error dump messages. paride.txt @@ -199,17 +219,25 @@ ramdisk.txt riscom8.txt - notes on using the RISCom/8 multi-port serial driver. rocket.txt - - info on installing/using the Comtrol RocketPort multiport serial driver. + - info on the Comtrol RocketPort multiport serial driver. rpc-cache.txt - introduction to the caching mechanisms in the sunrpc layer. rtc.txt - notes on how to use the Real Time Clock (aka CMOS clock) driver. s390/ - directory with info on using Linux on the IBM S390. +sched-coding.txt + - reference for various scheduler-related methods in the O(1) scheduler. sched-design.txt - goals, design and implementation of the Linux O(1) scheduler. +sched-domains.txt + - information on scheduling domains. +sched-stats.txt + - information on schedstats (Linux Scheduler Statistics). scsi/ - directory with info on Linux scsi support. +serial/ + - directory with info on the low level serial API. serial-console.txt - how to set up Linux with a serial line console as the default. sgi-visws.txt @@ -242,14 +270,24 @@ sysrq.txt - info on the magic SysRq key. telephony/ - directory with info on telephony (e.g. voice over IP) support. +time_interpolators.txt + - info on time interpolators. +tipar.txt + - information about Parallel link cable for Texas Instruments handhelds. +tty.txt + - guide to the locking policies of the tty layer. unicode.txt - info on the Unicode character/font mapping used in Linux. +uml/ + - directory with infomation about User Mode Linux. usb/ - directory with info regarding the Universal Serial Bus. video4linux/ - directory with info regarding video/TV/radio cards and linux. vm/ - directory with info on the Linux vm code. +voyager.txt + - guide to running Linux on the Voyager architecture. watchdog/ - how to auto-reboot Linux if it has "fallen and can't get up". ;-) x86_64/ diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 9a23eab00..fc50b1073 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -8,10 +8,10 @@ DOCBOOKS := wanbook.sgml z8530book.sgml mcabook.sgml videobook.sgml \ kernel-hacking.sgml kernel-locking.sgml via-audio.sgml \ - mousedrivers.sgml deviceiobook.sgml procfs-guide.sgml \ - tulip-user.sgml writing_usb_driver.sgml scsidrivers.sgml \ - sis900.sgml kernel-api.sgml journal-api.sgml lsm.sgml usb.sgml \ - gadget.sgml libata.sgml + deviceiobook.sgml procfs-guide.sgml tulip-user.sgml \ + writing_usb_driver.sgml scsidrivers.sgml sis900.sgml \ + kernel-api.sgml journal-api.sgml lsm.sgml usb.sgml \ + gadget.sgml libata.sgml mtdnand.sgml librs.sgml ### # The build process is as follows (targets): @@ -58,14 +58,14 @@ MAKEMAN = $(PERL) $(srctree)/scripts/makeman # The following rules are used to generate the .sgml documentation # required to generate the final targets. (ps, pdf, html). quiet_cmd_docproc = DOCPROC $@ - cmd_docproc = $(DOCPROC) doc $< >$@ + cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $< >$@ define rule_docproc set -e; \ $(if $($(quiet)cmd_$(1)),echo ' $($(quiet)cmd_$(1))';) \ $(cmd_$(1)); \ ( \ echo 'cmd_$@ := $(cmd_$(1))'; \ - echo $@: `$(DOCPROC) depend $<`; \ + echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`; \ ) > $(dir $@).$(notdir $@).cmd endef @@ -129,6 +129,9 @@ quiet_cmd_db2html = DB2HTML $@ # Rule to generate man files - output is placed in the man subdirectory %.9: %.sgml +ifneq ($(KBUILD_SRC),) + $(Q)mkdir -p $(objtree)/Documentation/DocBook/man +endif $(SPLITMAN) $< $(objtree)/Documentation/DocBook/man "$(VERSION).$(PATCHLEVEL).$(SUBLEVEL)" $(MAKEMAN) convert $(objtree)/Documentation/DocBook/man $< diff --git a/Documentation/DocBook/deviceiobook.tmpl b/Documentation/DocBook/deviceiobook.tmpl index d3f418384..0d1da8cbd 100644 --- a/Documentation/DocBook/deviceiobook.tmpl +++ b/Documentation/DocBook/deviceiobook.tmpl @@ -147,8 +147,7 @@ compiler is not permitted to reorder the I/O sequence. When the ordering can be compiler optimised, you can use __readb and friends to indicate the relaxed ordering. Use - this with care. The rmb provides a read memory - barrier. The wmb provides a write memory barrier. + this with care. @@ -159,19 +158,113 @@ asynchronously. A driver author must issue a read from the same device to ensure that writes have occurred in the specific cases the author cares. This kind of property cannot be hidden from driver - writers in the API. + writers in the API. In some cases, the read used to flush the device + may be expected to fail (if the card is resetting, for example). In + that case, the read should be done from config space, which is + guaranteed to soft-fail if the card doesn't respond. + + + + The following is an example of flushing a write to a device when + the driver would like to ensure the write's effects are visible prior + to continuing execution. + + + +static inline void +qla1280_disable_intrs(struct scsi_qla_host *ha) +{ + struct device_reg *reg; + + reg = ha->iobase; + /* disable risc and host interrupts */ + WRT_REG_WORD(&reg->ictrl, 0); + /* + * The following read will ensure that the above write + * has been received by the device before we return from this + * function. + */ + RD_REG_WORD(&reg->ictrl); + ha->flags.ints_enabled = 0; +} + + + + In addition to write posting, on some large multiprocessing systems + (e.g. SGI Challenge, Origin and Altix machines) posted writes won't + be strongly ordered coming from different CPUs. Thus it's important + to properly protect parts of your driver that do memory-mapped writes + with locks and use the mmiowb to make sure they + arrive in the order intended. Issuing a regular readX + will also ensure write ordering, but should only be used + when the driver has to be sure that the write has actually arrived + at the device (not that it's simply ordered with respect to other + writes), since a full readX is a relatively + expensive operation. + + + + Generally, one should use mmiowb prior to + releasing a spinlock that protects regions using writeb + or similar functions that aren't surrounded by + readb calls, which will ensure ordering and flushing. The + following pseudocode illustrates what might occur if write ordering + isn't guaranteed via mmiowb or one of the + readX functions. + + + +CPU A: spin_lock_irqsave(&dev_lock, flags) +CPU A: ... +CPU A: writel(newval, ring_ptr); +CPU A: spin_unlock_irqrestore(&dev_lock, flags) + ... +CPU B: spin_lock_irqsave(&dev_lock, flags) +CPU B: writel(newval2, ring_ptr); +CPU B: ... +CPU B: spin_unlock_irqrestore(&dev_lock, flags) + + + + In the case above, newval2 could be written to ring_ptr before + newval. Fixing it is easy though: + + + +CPU A: spin_lock_irqsave(&dev_lock, flags) +CPU A: ... +CPU A: writel(newval, ring_ptr); +CPU A: mmiowb(); /* ensure no other writes beat us to the device */ +CPU A: spin_unlock_irqrestore(&dev_lock, flags) + ... +CPU B: spin_lock_irqsave(&dev_lock, flags) +CPU B: writel(newval2, ring_ptr); +CPU B: ... +CPU B: mmiowb(); +CPU B: spin_unlock_irqrestore(&dev_lock, flags) + + + + See tg3.c for a real world example of how to use mmiowb + PCI ordering rules also guarantee that PIO read responses arrive - after any outstanding DMA writes on that bus, since for some devices + after any outstanding DMA writes from that bus, since for some devices the result of a readb call may signal to the driver that a DMA transaction is complete. In many cases, however, the driver may want to indicate that the next readb call has no relation to any previous DMA writes performed by the device. The driver can use readb_relaxed for these cases, although only - some platforms will honor the relaxed semantics. + some platforms will honor the relaxed semantics. Using the relaxed + read functions will provide significant performance benefits on + platforms that support it. The qla2xxx driver provides examples + of how to use readX_relaxed. In many cases, + a majority of the driver's readX calls can + safely be converted to readX_relaxed calls, since + only a few will indicate or depend on DMA completion. diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl index 5f11984a0..ef66fdda1 100644 --- a/Documentation/DocBook/kernel-api.tmpl +++ b/Documentation/DocBook/kernel-api.tmpl @@ -133,6 +133,11 @@ KAO --> Socket Filter !Enet/core/filter.c + Generic Network Statistics +!Iinclude/linux/gen_stats.h +!Enet/core/gen_stats.c +!Enet/core/gen_estimator.c + diff --git a/Documentation/DocBook/librs.tmpl b/Documentation/DocBook/librs.tmpl new file mode 100644 index 000000000..be482c030 --- /dev/null +++ b/Documentation/DocBook/librs.tmpl @@ -0,0 +1,287 @@ + + + + + Reed-Solomon Library Programming Interface + + + + Thomas + Gleixner + +
+ tglx@linutronix.de +
+ + + + + + 2004 + Thomas Gleixner + + + + + This documentation is free software; you can redistribute + it and/or modify it under the terms of the GNU General Public + License version 2 as published by the Free Software Foundation. + + + + 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 generic Reed-Solomon Library provides encoding, decoding + and error correction functions. + + + Reed-Solomon codes are used in communication and storage + applications to ensure data integrity. + + + This documentation is provided for developers who want to utilize + the functions provided by the library. + + + + + Known Bugs And Assumptions + + None. + + + + + Usage + + This chapter provides examples how to use the library. + + + Initializing + + The init function init_rs returns a pointer to a + rs decoder structure, which holds the necessary + information for encoding, decoding and error correction + with the given polynomial. It either uses an existing + matching decoder or creates a new one. On creation all + the lookup tables for fast en/decoding are created. + The function may take a while, so make sure not to + call it in critical code paths. + + +/* the Reed Solomon control structure */ +static struct rs_control *rs_decoder; + +/* Symbolsize is 10 (bits) + * Primitve polynomial is x^10+x^3+1 + * first consecutive root is 0 + * primitve element to generate roots = 1 + * generator polinomial degree (number of roots) = 6 + */ +rs_decoder = init_rs (10, 0x409, 0, 1, 6); + + + + Encoding + + The encoder calculates the Reed-Solomon code over + the given data length and stores the result in + the parity buffer. Note that the parity buffer must + be initialized before calling the encoder. + + + The expanded data can be inverted on the fly by + providing a non zero inversion mask. The expanded data is + XOR'ed with the mask. This is used e.g. for FLASH + ECC, where the all 0xFF is inverted to an all 0x00. + The Reed-Solomon code for all 0x00 is all 0x00. The + code is inverted before storing to FLASH so it is 0xFF + too. This prevent's that reading from an erased FLASH + results in ECC errors. + + + The databytes are expanded to the given symbol size + on the fly. There is no support for encoding continuous + bitstreams with a symbol size != 8 at the moment. If + it is necessary it should be not a big deal to implement + such functionality. + + +/* Parity buffer. Size = number of roots */ +uint16_t par[6]; +/* Initialize the parity buffer */ +memset(par, 0, sizeof(par)); +/* Encode 512 byte in data8. Store parity in buffer par */ +encode_rs8 (rs_decoder, data8, 512, par, 0); + + + + Decoding + + The decoder calculates the syndrome over + the given data length and the received parity symbols + and corrects errors in the data. + + + If a syndrome is available from a hardware decoder + then the syndrome calculation is skipped. + + + The correction of the data buffer can be suppressed + by providing a correction pattern buffer and an error + location buffer to the decoder. The decoder stores the + calculated error location and the correction bitmask + in the given buffers. This is useful for hardware + decoders which use a weird bit ordering scheme. + + + The databytes are expanded to the given symbol size + on the fly. There is no support for decoding continuous + bitstreams with a symbolsize != 8 at the moment. If + it is necessary it should be not a big deal to implement + such functionality. + + + + + Decoding with syndrome calculation, direct data correction + + +/* Parity buffer. Size = number of roots */ +uint16_t par[6]; +uint8_t data[512]; +int numerr; +/* Receive data */ +..... +/* Receive parity */ +..... +/* Decode 512 byte in data8.*/ +numerr = decode_rs8 (rs_decoder, data8, par, 512, NULL, 0, NULL, 0, NULL); + + + + + + Decoding with syndrome given by hardware decoder, direct data correction + + +/* Parity buffer. Size = number of roots */ +uint16_t par[6], syn[6]; +uint8_t data[512]; +int numerr; +/* Receive data */ +..... +/* Receive parity */ +..... +/* Get syndrome from hardware decoder */ +..... +/* Decode 512 byte in data8.*/ +numerr = decode_rs8 (rs_decoder, data8, par, 512, syn, 0, NULL, 0, NULL); + + + + + + Decoding with syndrome given by hardware decoder, no direct data correction. + + + Note: It's not necessary to give data and received parity to the decoder. + + +/* Parity buffer. Size = number of roots */ +uint16_t par[6], syn[6], corr[8]; +uint8_t data[512]; +int numerr, errpos[8]; +/* Receive data */ +..... +/* Receive parity */ +..... +/* Get syndrome from hardware decoder */ +..... +/* Decode 512 byte in data8.*/ +numerr = decode_rs8 (rs_decoder, NULL, NULL, 512, syn, 0, errpos, 0, corr); +for (i = 0; i < numerr; i++) { + do_error_correction_in_your_buffer(errpos[i], corr[i]); +} + + + + + Cleanup + + The function free_rs frees the allocated resources, + if the caller is the last user of the decoder. + + +/* Release resources */ +free_rs(rs_decoder); + + + + + + + Structures + + This chapter contains the autogenerated documentation of the structures which are + used in the Reed-Solomon Library and are relevant for a developer. + +!Iinclude/linux/rslib.h + + + + Public Functions Provided + + This chapter contains the autogenerated documentation of the Reed-Solomon functions + which are exported. + +!Elib/reed_solomon/reed_solomon.c + + + + Credits + + The library code for encoding and decoding was written by Phil Karn. + + + Copyright 2002, Phil Karn, KA9Q + May be used under the terms of the GNU General Public License (GPL) + + + The wrapper functions and interfaces are written by Thomas Gleixner + + + Many users have provided bugfixes, improvements and helping hands for testing. + Thanks a lot. + + + The following people have contributed to this document: + + + Thomas Gleixnertglx@linutronix.de + + + diff --git a/Documentation/DocBook/mtdnand.tmpl b/Documentation/DocBook/mtdnand.tmpl new file mode 100644 index 000000000..435bb5245 --- /dev/null +++ b/Documentation/DocBook/mtdnand.tmpl @@ -0,0 +1,1318 @@ + + + + + MTD NAND Driver Programming Interface + + + + Thomas + Gleixner + +
+ tglx@linutronix.de +
+ + + + + + 2004 + Thomas Gleixner + + + + + This documentation is free software; you can redistribute + it and/or modify it under the terms of the GNU General Public + License version 2 as published by the Free Software Foundation. + + + + 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 generic NAND driver supports almost all NAND and AG-AND based + chips and connects them to the Memory Technology Devices (MTD) + subsystem of the Linux Kernel. + + + This documentation is provided for developers who want to implement + board drivers or filesystem drivers suitable for NAND devices. + + + + + Known Bugs And Assumptions + + None. + + + + + Documentation hints + + The function and structure docs are autogenerated. Each function and + struct member has a short description which is marked with an [XXX] identifier. + The following chapters explain the meaning of those identifiers. + + + Function identifiers [XXX] + + The functions are marked with [XXX] identifiers in the short + comment. The identifiers explain the usage and scope of the + functions. Following identifiers are used: + + + + [MTD Interface] + These functions provide the interface to the MTD kernel API. + They are not replacable and provide functionality + which is complete hardware independent. + + + [NAND Interface] + These functions are exported and provide the interface to the NAND kernel API. + + + [GENERIC] + Generic functions are not replacable and provide functionality + which is complete hardware independent. + + + [DEFAULT] + Default functions provide hardware related functionality which is suitable + for most of the implementations. These functions can be replaced by the + board driver if neccecary. Those functions are called via pointers in the + NAND chip description structure. The board driver can set the functions which + should be replaced by board dependend functions before calling nand_scan(). + If the function pointer is NULL on entry to nand_scan() then the pointer + is set to the default function which is suitable for the detected chip type. + + + + + Struct member identifiers [XXX] + + The struct members are marked with [XXX] identifiers in the + comment. The identifiers explain the usage and scope of the + members. Following identifiers are used: + + + + [INTERN] + These members are for NAND driver internal use only and must not be + modified. Most of these values are calculated from the chip geometry + information which is evaluated during nand_scan(). + + + [REPLACEABLE] + Replaceable members hold hardware related functions which can be + provided by the board driver. The board driver can set the functions which + should be replaced by board dependend functions before calling nand_scan(). + If the function pointer is NULL on entry to nand_scan() then the pointer + is set to the default function which is suitable for the detected chip type. + + + [BOARDSPECIFIC] + Board specific members hold hardware related information which must + be provided by the board driver. The board driver must set the function + pointers and datafields before calling nand_scan(). + + + [OPTIONAL] + Optional members can hold information relevant for the board driver. The + generic NAND driver code does not use this information. + + + + + + + Basic board driver + + For most boards it will be sufficient to provide just the + basic functions and fill out some really board dependend + members in the nand chip description structure. + See drivers/mtd/nand/skeleton for reference. + + + Basic defines + + At least you have to provide a mtd structure and + a storage for the ioremap'ed chip address. + You can allocate the mtd structure using kmalloc + or you can allocate it statically. + In case of static allocation you have to allocate + a nand_chip structure too. + + + Kmalloc based example + + +static struct mtd_info *board_mtd; +static unsigned long baseaddr; + + + Static example + + +static struct mtd_info board_mtd; +static struct nand_chip board_chip; +static unsigned long baseaddr; + + + + Partition defines + + If you want to divide your device into parititions, then + enable the configuration switch CONFIG_MTD_PARITIONS and define + a paritioning scheme suitable to your board. + + +#define NUM_PARTITIONS 2 +static struct mtd_partition partition_info[] = { + { .name = "Flash partition 1", + .offset = 0, + .size = 8 * 1024 * 1024 }, + { .name = "Flash partition 2", + .offset = MTDPART_OFS_NEXT, + .size = MTDPART_SIZ_FULL }, +}; + + + + Hardware control function + + The hardware control function provides access to the + control pins of the NAND chip(s). + The access can be done by GPIO pins or by address lines. + If you use address lines, make sure that the timing + requirements are met. + + + GPIO based example + + +static void board_hwcontrol(struct mtd_info *mtd, int cmd) +{ + switch(cmd){ + case NAND_CTL_SETCLE: /* Set CLE pin high */ break; + case NAND_CTL_CLRCLE: /* Set CLE pin low */ break; + case NAND_CTL_SETALE: /* Set ALE pin high */ break; + case NAND_CTL_CLRALE: /* Set ALE pin low */ break; + case NAND_CTL_SETNCE: /* Set nCE pin low */ break; + case NAND_CTL_CLRNCE: /* Set nCE pin high */ break; + } +} + + + Address lines based example. It's assumed that the + nCE pin is driven by a chip select decoder. + + +static void board_hwcontrol(struct mtd_info *mtd, int cmd) +{ + struct nand_chip *this = (struct nand_chip *) mtd->priv; + switch(cmd){ + case NAND_CTL_SETCLE: this->IO_ADDR_W |= CLE_ADRR_BIT; break; + case NAND_CTL_CLRCLE: this->IO_ADDR_W &= ~CLE_ADRR_BIT; break; + case NAND_CTL_SETALE: this->IO_ADDR_W |= ALE_ADRR_BIT; break; + case NAND_CTL_CLRALE: this->IO_ADDR_W &= ~ALE_ADRR_BIT; break; + } +} + + + + Device ready function + + If the hardware interface has the ready busy pin of the NAND chip connected to a + GPIO or other accesible I/O pin, this function is used to read back the state of the + pin. The function has no arguments and should return 0, if the device is busy (R/B pin + is low) and 1, if the device is ready (R/B pin is high). + If the hardware interface does not give access to the ready busy pin, then + the function must not be defined and the function pointer this->dev_ready is set to NULL. + + + + Init function + + The init function allocates memory and sets up all the board + specific parameters and function pointers. When everything + is set up nand_scan() is called. This function tries to + detect and identify then chip. If a chip is found all the + internal data fields are initialized accordingly. + The structure(s) have to be zeroed out first and then filled with the neccecary + information about the device. + + +int __init board_init (void) +{ + struct nand_chip *this; + int err = 0; + + /* Allocate memory for MTD device structure and private data */ + board_mtd = kmalloc (sizeof(struct mtd_info) + sizeof (struct nand_chip), GFP_KERNEL); + if (!board_mtd) { + printk ("Unable to allocate NAND MTD device structure.\n"); + err = -ENOMEM; + goto out; + } + + /* Initialize structures */ + memset ((char *) board_mtd, 0, sizeof(struct mtd_info) + sizeof(struct nand_chip)); + + /* map physical adress */ + baseaddr = (unsigned long)ioremap(CHIP_PHYSICAL_ADDRESS, 1024); + if(!baseaddr){ + printk("Ioremap to access NAND chip failed\n"); + err = -EIO; + goto out_mtd; + } + + /* Get pointer to private data */ + this = (struct nand_chip *) (); + /* Link the private data with the MTD structure */ + board_mtd->priv = this; + + /* Set address of NAND IO lines */ + this->IO_ADDR_R = baseaddr; + this->IO_ADDR_W = baseaddr; + /* Reference hardware control function */ + this->hwcontrol = board_hwcontrol; + /* Set command delay time, see datasheet for correct value */ + this->chip_delay = CHIP_DEPENDEND_COMMAND_DELAY; + /* Assign the device ready function, if available */ + this->dev_ready = board_dev_ready; + this->eccmode = NAND_ECC_SOFT; + + /* Scan to find existance of the device */ + if (nand_scan (board_mtd, 1)) { + err = -ENXIO; + goto out_ior; + } + + add_mtd_partitions(board_mtd, partition_info, NUM_PARTITIONS); + goto out; + +out_ior: + iounmap((void *)baseaddr); +out_mtd: + kfree (board_mtd); +out: + return err; +} +module_init(board_init); + + + + Exit function + + The exit function is only neccecary if the driver is + compiled as a module. It releases all resources which + are held by the chip driver and unregisters the partitions + in the MTD layer. + + +#ifdef MODULE +static void __exit board_cleanup (void) +{ + /* Release resources, unregister device */ + nand_release (board_mtd); + + /* unmap physical adress */ + iounmap((void *)baseaddr); + + /* Free the MTD device structure */ + kfree (board_mtd); +} +module_exit(board_cleanup); +#endif + + + + + + Advanced board driver functions + + This chapter describes the advanced functionality of the NAND + driver. For a list of functions which can be overridden by the board + driver see the documentation of the nand_chip structure. + + + Multiple chip control + + The nand driver can control chip arrays. Therefor the + board driver must provide an own select_chip function. This + function must (de)select the requested chip. + The function pointer in the nand_chip structure must + be set before calling nand_scan(). The maxchip parameter + of nand_scan() defines the maximum number of chips to + scan for. Make sure that the select_chip function can + handle the requested number of chips. + + + The nand driver concatenates the chips to one virtual + chip and provides this virtual chip to the MTD layer. + + + Note: The driver can only handle linear chip arrays + of equally sized chips. There is no support for + parallel arrays which extend the buswidth. + + + GPIO based example + + +static void board_select_chip (struct mtd_info *mtd, int chip) +{ + /* Deselect all chips, set all nCE pins high */ + GPIO(BOARD_NAND_NCE) |= 0xff; + if (chip >= 0) + GPIO(BOARD_NAND_NCE) &= ~ (1 << chip); +} + + + Address lines based example. + Its assumed that the nCE pins are connected to an + address decoder. + + +static void board_select_chip (struct mtd_info *mtd, int chip) +{ + struct nand_chip *this = (struct nand_chip *) mtd->priv; + + /* Deselect all chips */ + this->IO_ADDR_R &= ~BOARD_NAND_ADDR_MASK; + this->IO_ADDR_W &= ~BOARD_NAND_ADDR_MASK; + switch (chip) { + case 0: + this->IO_ADDR_R |= BOARD_NAND_ADDR_CHIP0; + this->IO_ADDR_W |= BOARD_NAND_ADDR_CHIP0; + break; + .... + case n: + this->IO_ADDR_R |= BOARD_NAND_ADDR_CHIPn; + this->IO_ADDR_W |= BOARD_NAND_ADDR_CHIPn; + break; + } +} + + + + Hardware ECC support + + Functions and constants + + The nand driver supports three different types of + hardware ECC. + + NAND_ECC_HW3_256 + Hardware ECC generator providing 3 bytes ECC per + 256 byte. + + NAND_ECC_HW3_512 + Hardware ECC generator providing 3 bytes ECC per + 512 byte. + + NAND_ECC_HW6_512 + Hardware ECC generator providing 6 bytes ECC per + 512 byte. + + NAND_ECC_HW8_512 + Hardware ECC generator providing 6 bytes ECC per + 512 byte. + + + If your hardware generator has a different functionality + add it at the appropriate place in nand_base.c + + + The board driver must provide following functions: + + enable_hwecc + This function is called before reading / writing to + the chip. Reset or initialize the hardware generator + in this function. The function is called with an + argument which let you distinguish between read + and write operations. + + calculate_ecc + This function is called after read / write from / to + the chip. Transfer the ECC from the hardware to + the buffer. If the option NAND_HWECC_SYNDROME is set + then the function is only called on write. See below. + + correct_data + In case of an ECC error this function is called for + error detection and correction. Return 1 respectively 2 + in case the error can be corrected. If the error is + not correctable return -1. If your hardware generator + matches the default algorithm of the nand_ecc software + generator then use the correction function provided + by nand_ecc instead of implementing duplicated code. + + + + + + Hardware ECC with syndrome calculation + + Many hardware ECC implementations provide Reed-Solomon + codes and calculate an error syndrome on read. The syndrome + must be converted to a standard Reed-Solomon syndrome + before calling the error correction code in the generic + Reed-Solomon library. + + + The ECC bytes must be placed immidiately after the data + bytes in order to make the syndrome generator work. This + is contrary to the usual layout used by software ECC. The + seperation of data and out of band area is not longer + possible. The nand driver code handles this layout and + the remaining free bytes in the oob area are managed by + the autoplacement code. Provide a matching oob-layout + in this case. See rts_from4.c and diskonchip.c for + implementation reference. In those cases we must also + use bad block tables on FLASH, because the ECC layout is + interferring with the bad block marker positions. + See bad block table support for details. + + + + + Bad block table support + + Most NAND chips mark the bad blocks at a defined + position in the spare area. Those blocks must + not be erased under any circumstances as the bad + block information would be lost. + It is possible to check the bad block mark each + time when the blocks are accessed by reading the + spare area of the first page in the block. This + is time consuming so a bad block table is used. + + + The nand driver supports various types of bad block + tables. + + Per device + The bad block table contains all bad block information + of the device which can consist of multiple chips. + + Per chip + A bad block table is used per chip and contains the + bad block information for this particular chip. + + Fixed offset + The bad block table is located at a fixed offset + in the chip (device). This applies to various + DiskOnChip devices. + + Automatic placed + The bad block table is automatically placed and + detected either at the end or at the beginning + of a chip (device) + + Mirrored tables + The bad block table is mirrored on the chip (device) to + allow updates of the bad block table without data loss. + + + + + nand_scan() calls the function nand_default_bbt(). + nand_default_bbt() selects appropriate default + bad block table desriptors depending on the chip information + which was retrieved by nand_scan(). + + + The standard policy is scanning the device for bad + blocks and build a ram based bad block table which + allows faster access than always checking the + bad block information on the flash chip itself. + + + Flash based tables + + It may be desired or neccecary to keep a bad block table in FLASH. + For AG-AND chips this is mandatory, as they have no factory marked + bad blocks. They have factory marked good blocks. The marker pattern + is erased when the block is erased to be reused. So in case of + powerloss before writing the pattern back to the chip this block + would be lost and added to the bad blocks. Therefor we scan the + chip(s) when we detect them the first time for good blocks and + store this information in a bad block table before erasing any + of the blocks. + + + The blocks in which the tables are stored are procteted against + accidental access by marking them bad in the memory bad block + table. The bad block table managment functions are allowed + to circumvernt this protection. + + + The simplest way to activate the FLASH based bad block table support + is to set the option NAND_USE_FLASH_BBT in the option field of + the nand chip structure before calling nand_scan(). For AG-AND + chips is this done by default. + This activates the default FLASH based bad block table functionality + of the NAND driver. The default bad block table options are + + Store bad block table per chip + Use 2 bits per block + Automatic placement at the end of the chip + Use mirrored tables with version numbers + Reserve 4 blocks at the end of the chip + + + + + User defined tables + + User defined tables are created by filling out a + nand_bbt_descr structure and storing the pointer in the + nand_chip structure member bbt_td before calling nand_scan(). + If a mirror table is neccecary a second structure must be + created and a pointer to this structure must be stored + in bbt_md inside the nand_chip structure. If the bbt_md + member is set to NULL then only the main table is used + and no scan for the mirrored table is performed. + + + The most important field in the nand_bbt_descr structure + is the options field. The options define most of the + table properties. Use the predefined constants from + nand.h to define the options. + + Number of bits per block + The supported number of bits is 1, 2, 4, 8. + Table per chip + Setting the constant NAND_BBT_PERCHIP selects that + a bad block table is managed for each chip in a chip array. + If this option is not set then a per device bad block table + is used. + Table location is absolute + Use the option constant NAND_BBT_ABSPAGE and + define the absolute page number where the bad block + table starts in the field pages. If you have selected bad block + tables per chip and you have a multi chip array then the start page + must be given for each chip in the chip array. Note: there is no scan + for a table ident pattern performed, so the fields + pattern, veroffs, offs, len can be left uninitialized + Table location is automatically detected + The table can either be located in the first or the last good + blocks of the chip (device). Set NAND_BBT_LASTBLOCK to place + the bad block table at the end of the chip (device). The + bad block tables are marked and identified by a pattern which + is stored in the spare area of the first page in the block which + holds the bad block table. Store a pointer to the pattern + in the pattern field. Further the length of the pattern has to be + stored in len and the offset in the spare area must be given + in the offs member of the nand_bbt_descr stucture. For mirrored + bad block tables different patterns are mandatory. + Table creation + Set the option NAND_BBT_CREATE to enable the table creation + if no table can be found during the scan. Usually this is done only + once if a new chip is found. + Table write support + Set the option NAND_BBT_WRITE to enable the table write support. + This allows the update of the bad block table(s) in case a block has + to be marked bad due to wear. The MTD interface function block_markbad + is calling the update function of the bad block table. If the write + support is enabled then the table is updated on FLASH. + + Note: Write support should only be enabled for mirrored tables with + version control. + + Table version control + Set the option NAND_BBT_VERSION to enable the table version control. + It's highly recommended to enable this for mirrored tables with write + support. It makes sure that the risk of loosing the bad block + table information is reduced to the loss of the information about the + one worn out block which should be marked bad. The version is stored in + 4 consecutive bytes in the spare area of the device. The position of + the version number is defined by the member veroffs in the bad block table + descriptor. + Save block contents on write + + In case that the block which holds the bad block table does contain + other useful information, set the option NAND_BBT_SAVECONTENT. When + the bad block table is written then the whole block is read the bad + block table is updated and the block is erased and everything is + written back. If this option is not set only the bad block table + is written and everything else in the block is ignored and erased. + + Number of reserved blocks + + For automatic placement some blocks must be reserved for + bad block table storage. The number of reserved blocks is defined + in the maxblocks member of the babd block table description structure. + Reserving 4 blocks for mirrored tables should be a reasonable number. + This also limits the number of blocks which are scanned for the bad + block table ident pattern. + + + + + + + Spare area (auto)placement + + The nand driver implements different possibilities for + placement of filesystem data in the spare area, + + Placement defined by fs driver + Automatic placement + + The default placement function is automatic placement. The + nand driver has built in default placement schemes for the + various chiptypes. If due to hardware ECC functionality the + default placement does not fit then the board driver can + provide a own placement scheme. + + + File system drivers can provide a own placement scheme which + is used instead of the default placement scheme. + + + Placement schemes are defined by a nand_oobinfo structure + +struct nand_oobinfo { + int useecc; + int eccbytes; + int eccpos[24]; + int oobfree[8][2]; +}; + + + useecc + The useecc member controls the ecc and placement function. The header + file include/mtd/mtd-abi.h contains constants to select ecc and + placement. MTD_NANDECC_OFF switches off the ecc complete. This is + not recommended and available for testing and diagnosis only. + MTD_NANDECC_PLACE selects caller defined placement, MTD_NANDECC_AUTOPLACE + selects automatic placement. + + eccbytes + The eccbytes member defines the number of ecc bytes per page. + + eccpos + The eccpos array holds the byte offsets in the spare area where + the ecc codes are placed. + + oobfree + The oobfree array defines the areas in the spare area which can be + used for automatic placement. The information is given in the format + {offset, size}. offset defines the start of the usable area, size the + length in bytes. More than one area can be defined. The list is terminated + by an {0, 0} entry. + + + + + Placement defined by fs driver + + The calling function provides a pointer to a nand_oobinfo + structure which defines the ecc placement. For writes the + caller must provide a spare area buffer along with the + data buffer. The spare area buffer size is (number of pages) * + (size of spare area). For reads the buffer size is + (number of pages) * ((size of spare area) + (number of ecc + steps per page) * sizeof (int)). The driver stores the + result of the ecc check for each tuple in the spare buffer. + The storage sequence is + + + <spare data page 0><ecc result 0>...<ecc result n> + + + ... + + + <spare data page n><ecc result 0>...<ecc result n> + + + This is a legacy mode used by YAFFS1. + + + If the spare area buffer is NULL then only the ECC placement is + done according to the given scheme in the nand_oobinfo structure. + + + + Automatic placement + + Automatic placement uses the built in defaults to place the + ecc bytes in the spare area. If filesystem data have to be stored / + read into the spare area then the calling function must provide a + buffer. The buffer size per page is determined by the oobfree array in + the nand_oobinfo structure. + + + If the spare area buffer is NULL then only the ECC placement is + done according to the default builtin scheme. + + + + User space placement selection + + All non ecc functions like mtd->read and mtd->write use an internal + structure, which can be set by an ioctl. This structure is preset + to the autoplacement default. + + ioctl (fd, MEMSETOOBSEL, oobsel); + + oobsel is a pointer to a user supplied structure of type + nand_oobconfig. The contents of this structure must match the + criteria of the filesystem, which will be used. See an example in utils/nandwrite.c. + + + + + Spare area autoplacement default schemes + + 256 byte pagesize + + +Offset +Content +Comment + + +0x00 +ECC byte 0 +Error correction code byte 0 + + +0x01 +ECC byte 1 +Error correction code byte 1 + + +0x02 +ECC byte 2 +Error correction code byte 2 + + +0x03 +Autoplace 0 + + + +0x04 +Autoplace 1 + + + +0x05 +Bad block marker +If any bit in this byte is zero, then this block is bad. +This applies only to the first page in a block. In the remaining +pages this byte is reserved + + +0x06 +Autoplace 2 + + + +0x07 +Autoplace 3 + + + + + + 512 byte pagesize + + +Offset +Content +Comment + + +0x00 +ECC byte 0 +Error correction code byte 0 of the lower 256 Byte data in +this page + + +0x01 +ECC byte 1 +Error correction code byte 1 of the lower 256 Bytes of data +in this page + + +0x02 +ECC byte 2 +Error correction code byte 2 of the lower 256 Bytes of data +in this page + + +0x03 +ECC byte 3 +Error correction code byte 0 of the upper 256 Bytes of data +in this page + + +0x04 +reserved +reserved + + +0x05 +Bad block marker +If any bit in this byte is zero, then this block is bad. +This applies only to the first page in a block. In the remaining +pages this byte is reserved + + +0x06 +ECC byte 4 +Error correction code byte 1 of the upper 256 Bytes of data +in this page + + +0x07 +ECC byte 5 +Error correction code byte 2 of the upper 256 Bytes of data +in this page + + +0x08 - 0x0F +Autoplace 0 - 7 + + + + + + 2048 byte pagesize + + +Offset +Content +Comment + + +0x00 +Bad block marker +If any bit in this byte is zero, then this block is bad. +This applies only to the first page in a block. In the remaining +pages this byte is reserved + + +0x01 +Reserved +Reserved + + +0x02-0x27 +Autoplace 0 - 37 + + + +0x28 +ECC byte 0 +Error correction code byte 0 of the first 256 Byte data in +this page + + +0x29 +ECC byte 1 +Error correction code byte 1 of the first 256 Bytes of data +in this page + + +0x2A +ECC byte 2 +Error correction code byte 2 of the first 256 Bytes data in +this page + + +0x2B +ECC byte 3 +Error correction code byte 0 of the second 256 Bytes of data +in this page + + +0x2C +ECC byte 4 +Error correction code byte 1 of the second 256 Bytes of data +in this page + + +0x2D +ECC byte 5 +Error correction code byte 2 of the second 256 Bytes of data +in this page + + +0x2E +ECC byte 6 +Error correction code byte 0 of the third 256 Bytes of data +in this page + + +0x2F +ECC byte 7 +Error correction code byte 1 of the third 256 Bytes of data +in this page + + +0x30 +ECC byte 8 +Error correction code byte 2 of the third 256 Bytes of data +in this page + + +0x31 +ECC byte 9 +Error correction code byte 0 of the fourth 256 Bytes of data +in this page + + +0x32 +ECC byte 10 +Error correction code byte 1 of the fourth 256 Bytes of data +in this page + + +0x33 +ECC byte 11 +Error correction code byte 2 of the fourth 256 Bytes of data +in this page + + +0x34 +ECC byte 12 +Error correction code byte 0 of the fifth 256 Bytes of data +in this page + + +0x35 +ECC byte 13 +Error correction code byte 1 of the fifth 256 Bytes of data +in this page + + +0x36 +ECC byte 14 +Error correction code byte 2 of the fifth 256 Bytes of data +in this page + + +0x37 +ECC byte 15 +Error correction code byte 0 of the sixt 256 Bytes of data +in this page + + +0x38 +ECC byte 16 +Error correction code byte 1 of the sixt 256 Bytes of data +in this page + + +0x39 +ECC byte 17 +Error correction code byte 2 of the sixt 256 Bytes of data +in this page + + +0x3A +ECC byte 18 +Error correction code byte 0 of the seventh 256 Bytes of +data in this page + + +0x3B +ECC byte 19 +Error correction code byte 1 of the seventh 256 Bytes of +data in this page + + +0x3C +ECC byte 20 +Error correction code byte 2 of the seventh 256 Bytes of +data in this page + + +0x3D +ECC byte 21 +Error correction code byte 0 of the eigth 256 Bytes of data +in this page + + +0x3E +ECC byte 22 +Error correction code byte 1 of the eigth 256 Bytes of data +in this page + + +0x3F +ECC byte 23 +Error correction code byte 2 of the eigth 256 Bytes of data +in this page + + + + + + + + Filesystem support + + The NAND driver provides all neccecary functions for a + filesystem via the MTD interface. + + + Filesystems must be aware of the NAND pecularities and + restrictions. One major restrictions of NAND Flash is, that you cannot + write as often as you want to a page. The consecutive writes to a page, + before erasing it again, are restricted to 1-3 writes, depending on the + manufacturers specifications. This applies similar to the spare area. + + + Therefor NAND aware filesystems must either write in page size chunks + or hold a writebuffer to collect smaller writes until they sum up to + pagesize. Available NAND aware filesystems: JFFS2, YAFFS. + + + The spare area usage to store filesystem data is controlled by + the spare area placement functionality which is described in one + of the earlier chapters. + + + + Tools + + The MTD project provides a couple of helpful tools to handle NAND Flash. + + flasherase, flasheraseall: Erase and format FLASH partitions + nandwrite: write filesystem images to NAND FLASH + nanddump: dump the contents of a NAND FLASH partitions + + + + These tools are aware of the NAND restrictions. Please use those tools + instead of complaining about errors which are caused by non NAND aware + access methods. + + + + + Constants + + This chapter describes the constants which might be relevant for a driver developer. + + + Chip option constants + + Constants for chip id table + + These constants are defined in nand.h. They are ored together to describe + the chip functionality. + +/* Chip can not auto increment pages */ +#define NAND_NO_AUTOINCR 0x00000001 +/* Buswitdh is 16 bit */ +#define NAND_BUSWIDTH_16 0x00000002 +/* Device supports partial programming without padding */ +#define NAND_NO_PADDING 0x00000004 +/* Chip has cache program function */ +#define NAND_CACHEPRG 0x00000008 +/* Chip has copy back function */ +#define NAND_COPYBACK 0x00000010 +/* AND Chip which has 4 banks and a confusing page / block + * assignment. See Renesas datasheet for further information */ +#define NAND_IS_AND 0x00000020 +/* Chip has a array of 4 pages which can be read without + * additional ready /busy waits */ +#define NAND_4PAGE_ARRAY 0x00000040 + + + + + Constants for runtime options + + These constants are defined in nand.h. They are ored together to describe + the functionality. + +/* Use a flash based bad block table. This option is parsed by the + * default bad block table function (nand_default_bbt). */ +#define NAND_USE_FLASH_BBT 0x00010000 +/* The hw ecc generator provides a syndrome instead a ecc value on read + * This can only work if we have the ecc bytes directly behind the + * data bytes. Applies for DOC and AG-AND Renesas HW Reed Solomon generators */ +#define NAND_HWECC_SYNDROME 0x00020000 + + + + + + + ECC selection constants + + Use these constants to select the ECC algorithm. + +/* No ECC. Usage is not recommended ! */ +#define NAND_ECC_NONE 0 +/* Software ECC 3 byte ECC per 256 Byte data */ +#define NAND_ECC_SOFT 1 +/* Hardware ECC 3 byte ECC per 256 Byte data */ +#define NAND_ECC_HW3_256 2 +/* Hardware ECC 3 byte ECC per 512 Byte data */ +#define NAND_ECC_HW3_512 3 +/* Hardware ECC 6 byte ECC per 512 Byte data */ +#define NAND_ECC_HW6_512 4 +/* Hardware ECC 6 byte ECC per 512 Byte data */ +#define NAND_ECC_HW8_512 6 + + + + + + Hardware control related constants + + These constants describe the requested hardware access function when + the boardspecific hardware control function is called + +/* Select the chip by setting nCE to low */ +#define NAND_CTL_SETNCE 1 +/* Deselect the chip by setting nCE to high */ +#define NAND_CTL_CLRNCE 2 +/* Select the command latch by setting CLE to high */ +#define NAND_CTL_SETCLE 3 +/* Deselect the command latch by setting CLE to low */ +#define NAND_CTL_CLRCLE 4 +/* Select the address latch by setting ALE to high */ +#define NAND_CTL_SETALE 5 +/* Deselect the address latch by setting ALE to low */ +#define NAND_CTL_CLRALE 6 +/* Set write protection by setting WP to high. Not used! */ +#define NAND_CTL_SETWP 7 +/* Clear write protection by setting WP to low. Not used! */ +#define NAND_CTL_CLRWP 8 + + + + + + Bad block table related constants + + These constants describe the options used for bad block + table descriptors. + +/* Options for the bad block table descriptors */ + +/* The number of bits used per block in the bbt on the device */ +#define NAND_BBT_NRBITS_MSK 0x0000000F +#define NAND_BBT_1BIT 0x00000001 +#define NAND_BBT_2BIT 0x00000002 +#define NAND_BBT_4BIT 0x00000004 +#define NAND_BBT_8BIT 0x00000008 +/* The bad block table is in the last good block of the device */ +#define NAND_BBT_LASTBLOCK 0x00000010 +/* The bbt is at the given page, else we must scan for the bbt */ +#define NAND_BBT_ABSPAGE 0x00000020 +/* The bbt is at the given page, else we must scan for the bbt */ +#define NAND_BBT_SEARCH 0x00000040 +/* bbt is stored per chip on multichip devices */ +#define NAND_BBT_PERCHIP 0x00000080 +/* bbt has a version counter at offset veroffs */ +#define NAND_BBT_VERSION 0x00000100 +/* Create a bbt if none axists */ +#define NAND_BBT_CREATE 0x00000200 +/* Search good / bad pattern through all pages of a block */ +#define NAND_BBT_SCANALLPAGES 0x00000400 +/* Scan block empty during good / bad block scan */ +#define NAND_BBT_SCANEMPTY 0x00000800 +/* Write bbt if neccecary */ +#define NAND_BBT_WRITE 0x00001000 +/* Read and write back block contents when writing bbt */ +#define NAND_BBT_SAVECONTENT 0x00002000 + + + + + + + + Structures + + This chapter contains the autogenerated documentation of the structures which are + used in the NAND driver and might be relevant for a driver developer. Each + struct member has a short description which is marked with an [XXX] identifier. + See the chapter "Documentation hints" for an explanation. + +!Iinclude/linux/mtd/nand.h + + + + Public Functions Provided + + This chapter contains the autogenerated documentation of the NAND kernel API functions + which are exported. Each function has a short description which is marked with an [XXX] identifier. + See the chapter "Documentation hints" for an explanation. + +!Edrivers/mtd/nand/nand_base.c +!Edrivers/mtd/nand/nand_bbt.c +!Edrivers/mtd/nand/nand_ecc.c + + + + Internal Functions Provided + + This chapter contains the autogenerated documentation of the NAND driver internal functions. + Each function has a short description which is marked with an [XXX] identifier. + See the chapter "Documentation hints" for an explanation. + The functions marked with [DEFAULT] might be relevant for a board driver developer. + +!Idrivers/mtd/nand/nand_base.c +!Idrivers/mtd/nand/nand_bbt.c +!Idrivers/mtd/nand/nand_ecc.c + + + + Credits + + The following people have contributed to the NAND driver: + + Steven J. Hillsjhill@realitydiluted.com + David Woodhousedwmw2@infradead.org + Thomas Gleixnertglx@linutronix.de + + A lot of users have provided bugfixes, improvements and helping hands for testing. + Thanks a lot. + + + The following people have contributed to this document: + + Thomas Gleixnertglx@linutronix.de + + + + diff --git a/Documentation/DocBook/procfs-guide.tmpl b/Documentation/DocBook/procfs-guide.tmpl index 669b0466a..34206230c 100644 --- a/Documentation/DocBook/procfs-guide.tmpl +++ b/Documentation/DocBook/procfs-guide.tmpl @@ -100,8 +100,8 @@ I'd like to thank Jeff Garzik jgarzik@pobox.com and Alexander Viro - viro@math.psu.edu for their input, Tim Waugh - twaugh@redhat.com for his viro@parcelfarce.linux.theplanet.co.uk for their input, + Tim Waugh twaugh@redhat.com for his Selfdocbook, and Marc Joosen marcj@historia.et.tudelft.nl for proofreading. diff --git a/Documentation/IO-mapping.txt b/Documentation/IO-mapping.txt index ddc817346..86edb61bd 100644 --- a/Documentation/IO-mapping.txt +++ b/Documentation/IO-mapping.txt @@ -119,9 +119,10 @@ you can't use it from the bus master. So why do we care about the physical address at all? We do need the physical address in some cases, it's just not very often in normal code. The physical address is needed if you use memory mappings, for example, because the -"remap_page_range()" mm function wants the physical address of the memory to -be remapped (the memory management layer doesn't know about devices outside -the CPU, so it shouldn't need to know about "bus addresses" etc). +"remap_pfn_range()" mm function wants the physical address of the memory to +be remapped as measured in units of pages, a.k.a. the pfn (the memory +management layer doesn't know about devices outside the CPU, so it +shouldn't need to know about "bus addresses" etc). NOTE NOTE NOTE! The above is only one part of the whole equation. The above only talks about "real memory", that is, CPU memory (RAM). diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.txt index 46950afda..bda6ead69 100644 --- a/Documentation/RCU/listRCU.txt +++ b/Documentation/RCU/listRCU.txt @@ -82,7 +82,7 @@ lock might be used as follows for deletion and insertion: list_for_each_entry(e, list, list) { if (!audit_compare_rule(rule, &e->rule)) { list_del(&e->list); - call_rcu(&e->rcu, audit_free_rule, e); + write_unlock(&auditsc_lock); return 0; } } diff --git a/Documentation/arm/Booting b/Documentation/arm/Booting index a851d039a..fad566bb0 100644 --- a/Documentation/arm/Booting +++ b/Documentation/arm/Booting @@ -118,6 +118,10 @@ to store page tables. The recommended placement is 32KiB into RAM. In either case, the following conditions must be met: +- Quiesce all DMA capable devicess so that memory does not get + corrupted by bogus network packets or disk data. This will save + you many hours of debug. + - CPU register settings r0 = 0, r1 = machine type number discovered in (3) above. diff --git a/Documentation/arm/IXP2000 b/Documentation/arm/IXP2000 index 48ba502fa..969f16593 100644 --- a/Documentation/arm/IXP2000 +++ b/Documentation/arm/IXP2000 @@ -18,7 +18,7 @@ http://developer.intel.com/design/network/products/npfamily/ixp2xxx.htm 2. Linux Support -Linux currently supports the following features on the IXP2000 NPUS: +Linux currently supports the following features on the IXP2000 NPUs: - On-chip serial - PCI @@ -30,10 +30,10 @@ That is about all we can support under Linux ATM b/c the core networking components of the chip are accessed via Intel's closed source SDK. Please contact Intel directly on issues with using those. There is also a mailing list run by some folks at Princeton University that might -be of helpful: https://lists.cs.princeton.edu/mailman/listinfo/ixp2xxx +be of help: https://lists.cs.princeton.edu/mailman/listinfo/ixp2xxx WHATEVER YOU DO, DO NOT POST EMAIL TO THE LINUX-ARM OR LINUX-ARM-KERNEL -MAILINNG LISTS REGARDING THE INTEL SDK. +MAILING LISTS REGARDING THE INTEL SDK. 3. Supported Platforms @@ -47,12 +47,12 @@ MAILINNG LISTS REGARDING THE INTEL SDK. - The IXP2000 platforms ususally have rather complex PCI bus topologies with large memory space requirements. In addition, b/c of the way the - Intel SDK is designed, devices are enumerated in a vert specific + Intel SDK is designed, devices are enumerated in a very specific way. B/c of this this, we use "pci=firmware" option in the kernel command line so that we do not re-enumerate the bus. - IXDP2x01 systems have variable clock tick rates that we cannot determine - via HW registers. The "ixdp2x01_clk=XXX" cmd line options allows you + via HW registers. The "ixdp2x01_clk=XXX" cmd line options allow you to pass the clock rate to the board port. 5. Thanks diff --git a/Documentation/arm/IXP4xx b/Documentation/arm/IXP4xx index d86d818a4..2e1590b42 100644 --- a/Documentation/arm/IXP4xx +++ b/Documentation/arm/IXP4xx @@ -122,6 +122,15 @@ http://developer.intel.com/design/network/products/npfamily/ixdp425.htm also known as the Richfield board. It contains 4 PCI slots, 16MB of flash, two 10/100 ports and one ADSL port. +Intel IXDPG425 Development Platform + + This is basically and ADI Coyote board with a NEC EHCI controller + added. One issue with this board is that the mini-PCI slots only + have the 3.3v line connected, so you can't use a PCI to mini-PCI + adapter with an E100 card. So to NFS root you need to use either + the CSR or a WiFi card and a ramdisk that BOOTPs and then does + a pivot_root to NFS. + Motorola PrPMC1100 Processor Mezanine Card http://www.fountainsys.com/datasheet/PrPMC1100.pdf @@ -152,4 +161,4 @@ Robert E. Ranslam ------------------------------------------------------------------------- -Last Update: 5/13/2004 +Last Update: 11/16/2004 diff --git a/Documentation/arm/README b/Documentation/arm/README index 1dd5d6cb7..a6f718e90 100644 --- a/Documentation/arm/README +++ b/Documentation/arm/README @@ -163,9 +163,9 @@ CONFIG_MACH_ and CONFIG_ARCH_ -Kernel entry (head-armv.S) +Kernel entry (head.S) -------------------------- - The initial entry into the kernel is via head-armv.S, which uses machine + The initial entry into the kernel is via head.S, which uses machine independent code. The machine is selected by the value of 'r1' on entry, which must be kept unique. diff --git a/Documentation/arm/Samsung-S3C24XX/EB2410ITX.txt b/Documentation/arm/Samsung-S3C24XX/EB2410ITX.txt index 831b98c73..000e3d7a7 100644 --- a/Documentation/arm/Samsung-S3C24XX/EB2410ITX.txt +++ b/Documentation/arm/Samsung-S3C24XX/EB2410ITX.txt @@ -15,7 +15,7 @@ Configuration ------------- To set the default configuration, use `make bast_defconfig` which - supports the commonly used features of this board + supports the commonly used features of this board. Support @@ -23,15 +23,23 @@ Support Official support information can be found on the Simtec Electronics website, at the product page http://www.simtec.co.uk/products/EB2410ITX/ - and http://www.simtec.co.uk/products/EB2410ITX/resources.html + + Useful links: + + - Resources Page http://www.simtec.co.uk/products/EB2410ITX/resources.html + + - Board FAQ at http://www.simtec.co.uk/products/EB2410ITX/faq.html + + - Bootloader info http://www.simtec.co.uk/products/SWABLE/resources.html + and FAQ http://www.simtec.co.uk/products/SWABLE/faq.html MTD --- - The NAND and NOR onboard are currently supported in the linux-mtd cvs, - and are awaiting merge in the mainline. see the linux-mtd project at - http://www.linux-mtd.infradead.org/ for more information. + The NAND and NOR support has been merged from the linux-mtd project. + Any prolbems, see http://www.linux-mtd.infradead.org/ for more + information or up-to-date versions of linux-mtd. IDE @@ -41,4 +49,10 @@ IDE changing speed of devices, PIO Mode 4 capable drives should be used. +Maintainers +----------- + + This board is maintained by Simtec Electronics. + + (c) 2004 Ben Dooks, Simtec Electronics diff --git a/Documentation/arm/Samsung-S3C24XX/Overview.txt b/Documentation/arm/Samsung-S3C24XX/Overview.txt index aa3f83aa2..b8ba49250 100644 --- a/Documentation/arm/Samsung-S3C24XX/Overview.txt +++ b/Documentation/arm/Samsung-S3C24XX/Overview.txt @@ -48,9 +48,9 @@ Machines NAND ---- - The current kernels do not have direct support for the NAND - controller, the latest linux-mtd CVS has support for this. - See http://www.linux-mtd.infradead.org/ + The current kernels now have support for the s3c2410 NAND + controller. If there are any problems the latest linux-mtd + CVS can be found from http://www.linux-mtd.infradead.org/ Serial @@ -84,12 +84,21 @@ Clock Management Port Contributors ----------------- - Ben Dooks + Ben Dooks (BJD) Vincent Sanders Herbert Potzl - Arnaud Patard + Arnaud Patard (RTP) Roc Wu + Klaus Fetscher + Dimitry Andric +Document Changes +---------------- + + 05 Sep 2004 - BJD - Added Document Changes section + 05 Sep 2004 - BJD - Added Klaus Fetscher to list of contributors + 25 Oct 2004 - BJD - Added Dimitry Andric to list of contributors + 25 Oct 2004 - BJD - Updated the MTD from the 2.6.9 merge Document Author --------------- diff --git a/Documentation/arm/Samsung-S3C24XX/Suspend.txt b/Documentation/arm/Samsung-S3C24XX/Suspend.txt new file mode 100644 index 000000000..e12bc3284 --- /dev/null +++ b/Documentation/arm/Samsung-S3C24XX/Suspend.txt @@ -0,0 +1,106 @@ + S3C24XX Suspend Support + ======================= + + +Introduction +------------ + + The S3C2410 supports a low-power suspend mode, where the SDRAM is kept + in Self-Refresh mode, and all but the essential peripheral blocks are + powered down. For more information on how this works, please look + at the S3C2410 datasheets from Samsung. + + +Requirements +------------ + + 1) A bootloader that can support the necessary resume operation + + 2) Support for at least 1 source for resume + + 3) CONFIG_PM enabled in the kernel + + 4) Any peripherals that are going to be powered down at the same + time require suspend/resume support. + + +Resuming +-------- + + The S3C2410 user manual defines the process of sending the CPU to + sleep and how it resumes. The default behaviour of the Linux code + is to set the GSTATUS3 register to the physical address of the + code to resume Linux operation. + + GSTATUS4 is currently left alone by the sleep code, and is free to + use for any other purposes (for example, the EB2410ITX uses this to + save memory configuration in). + + +Machine Support +--------------- + + The machine specific functions must call the s3c2410_pm_init() function + to say that its bootloader is capable of resuming. This can be as + simple as adding the following to the machine's definition: + + INITMACHINE(s3c2410_pm_init) + + A board can do its own setup before calling s3c2410_pm_init, if it + needs to setup anything else for power management support. + + There is currently no support for over-riding the default method of + saving the resume address, if your board requires it, then contact + the maintainer and discuss what is required. + + Note, the original method of adding an late_initcall() is wrong, + and will end up initialising all compiled machines' pm init! + + +Debugging +--------- + + There are several important things to remember when using PM suspend: + + 1) The uart drivers will disable the clocks to the UART blocks when + suspending, which means that use of printascii() or similar direct + access to the UARTs will cause the debug to stop. + + 2) Whilst the pm code itself will attempt to re-enable the UART clocks, + care should be taken that any external clock sources that the UARTs + rely on are still enabled at that point. + + +Configuration +------------- + + The S3C2410 specific configuration in `System Type` defines various + aspects of how the S3C2410 suspend and resume support is configured + + `S3C2410 PM Suspend debug` + + This option prints messages to the serial console before and after + the actual suspend, giving detailed information on what is + happening + + + `S3C2410 PM Suspend Memory CRC` + + Allows the entire memory to be checksummed before and after the + suspend to see if there has been any corruption of the contents. + + This support requires the CRC32 function to be enabled. + + + `S3C2410 PM Suspend CRC Chunksize (KiB)` + + Defines the size of memory each CRC chunk covers. A smaller value + will mean that the CRC data block will take more memory, but will + identify any faults with better precision + + +Document Author +--------------- + +Ben Dooks, (c) 2004 Simtec Electronics + diff --git a/Documentation/arm/Sharp-LH/IOBarrier b/Documentation/arm/Sharp-LH/IOBarrier index bf34e046e..c0d885367 100644 --- a/Documentation/arm/Sharp-LH/IOBarrier +++ b/Documentation/arm/Sharp-LH/IOBarrier @@ -5,7 +5,7 @@ Due to an unfortunate oversight when the Card Engines were designed, the signals that control access to some peripherals, most notably the SMC91C9111 ethernet controller, are not properly handled. -The symptom is that back to back IO with the peripheral returns +The symptom is that some back to back IO with the peripheral returns unreliable data. With the SMC chip, you'll see errors about the bank register being 'screwed'. @@ -13,20 +13,33 @@ The cause is that the AEN signal to the SMC chip does not transition for every memory access. It is driven through the CPLD from the CS7 line of the CPU's static memory controller which is optimized to eliminate unnecessary transitions. Yet, the SMC requires a transition -for every access. The Sharp website has more information on the -effect of this power conservation feature on peripheral interfacing. +for every write access. The Sharp website has more information about +the effect this power-conserving feature has on peripheral +interfacing. -The solution is to follow every access to the SMC chip with an access -to another memory region that will force the CPU to release the chip -select line. Note that it is important to guarantee that the access -will force the CPU off-chip. We map a page of SDRAM as if it were an -uncacheable IO device and read from it after every SMC IO operation. +The solution is to follow every write access to the SMC chip with an +access to another memory region that will force the CPU to release the +chip select line. It is important to guarantee that this access +forces the CPU off-chip. We map a page of SDRAM as if it were an +uncacheable IO device and read from it after every SMC IO write +operation. SMC IO BARRIER IO -You might be tempted to believe that we must access another device +Only this sequence is important. It does not matter that there is no +BARRIER IO before the access to the SMC chip because the AEN latch +only needs occurs after the SMC IO write cycle. The routines that +implement this work-around make an additional concession which is to +disable interrupts during the IO sequence. Other hardware devices +(the LogicPD CPLD) have registers in the same the physical memory +region as the SMC chip. An interrupt might allow an access to one of +those registers while SMC IO is being performed. + +You might be tempted to think that we have to access another device attached to the static memory controller, but the empirical evidence indicates that this is not so. Mapping 0x00000000 (flash) and 0xc0000000 (SDRAM) appear to have the same effect. Using SDRAM seems -to be faster. +to be faster. Choosing to access an undecoded memory region is not +desirable as there is no way to know how that chip select will be used +in the future. diff --git a/Documentation/block/as-iosched.txt b/Documentation/block/as-iosched.txt index fd763cc48..6f47332c8 100644 --- a/Documentation/block/as-iosched.txt +++ b/Documentation/block/as-iosched.txt @@ -132,7 +132,7 @@ a combination of IO behavior from all those devices. Tuning the anticipatory IO scheduler ------------------------------------ When using 'as', the anticipatory IO scheduler there are 5 parameters under -/sys/block/*/iosched/. All are units of milliseconds. +/sys/block/*/queue/iosched/. All are units of milliseconds. The parameters are: * read_expire diff --git a/Documentation/block/biodoc.txt b/Documentation/block/biodoc.txt index f24dbcaca..6dd274d7e 100644 --- a/Documentation/block/biodoc.txt +++ b/Documentation/block/biodoc.txt @@ -1172,8 +1172,7 @@ PIO drivers (or drivers that need to revert to PIO transfer once in a while (IDE for example)), where the CPU is doing the actual data transfer a virtual mapping is needed. If the driver supports highmem I/O, (Sec 1.1, (ii) ) it needs to use __bio_kmap_atomic and bio_kmap_irq to -temporarily map a bio into the virtual address space. See how IDE handles -this with ide_map_buffer. +temporarily map a bio into the virtual address space. 8. Prior/Related/Impacted patches diff --git a/Documentation/block/deadline-iosched.txt b/Documentation/block/deadline-iosched.txt index 2b1318600..c918b3a60 100644 --- a/Documentation/block/deadline-iosched.txt +++ b/Documentation/block/deadline-iosched.txt @@ -9,7 +9,7 @@ Each io queue has a set of io scheduler tunables associated with it. These tunables control how the io scheduler works. You can find these entries in: -/sys/block//iosched +/sys/block//queue/iosched assuming that you have sysfs mounted on /sys. If you don't have sysfs mounted, you can do so by typing: diff --git a/Documentation/cdrom/00-INDEX b/Documentation/cdrom/00-INDEX index eae689667..916dafe29 100644 --- a/Documentation/cdrom/00-INDEX +++ b/Documentation/cdrom/00-INDEX @@ -22,6 +22,8 @@ mcdx - info on improved Mitsumi CD-ROM driver. optcd - info on the Optics Storage 8000 AT CD-ROM driver +packet-writing.txt + - Info on the CDRW packet writing module sbpcd - info on the SoundBlaster/Panasonic CD-ROM interface driver. sjcd diff --git a/Documentation/cdrom/packet-writing.txt b/Documentation/cdrom/packet-writing.txt new file mode 100644 index 000000000..d34fcbca9 --- /dev/null +++ b/Documentation/cdrom/packet-writing.txt @@ -0,0 +1,86 @@ +Getting started quick +--------------------- + +- Select packet support in the block device section and UDF support in + the file system section. + +- Compile and install kernel and modules, reboot. + +- You need the udftools package (pktsetup, mkudffs, cdrwtool). + Download from http://sourceforge.net/projects/linux-udf/ + +- Grab a new CD-RW disc and format it (assuming CD-RW is hdc, substitute + as appropriate): + # cdrwtool -d /dev/hdc -q + +- Setup your writer + # pktsetup dev_name /dev/hdc + +- Now you can mount /dev/pktcdvd/dev_name and copy files to it. Enjoy! + # mount /dev/pktcdvd/dev_name /cdrom -t udf -o rw,noatime + + +Packet writing for DVD-RW media +------------------------------- + +DVD-RW discs can be written to much like CD-RW discs if they are in +the so called "restricted overwrite" mode. To put a disc in restricted +overwrite mode, run: + + # dvd+rw-format /dev/hdc + +You can then use the disc the same way you would use a CD-RW disc: + + # pktsetup dev_name /dev/hdc + # mount /dev/pktcdvd/dev_name /cdrom -t udf -o rw,noatime + + +Packet writing for DVD+RW media +------------------------------- + +According to the DVD+RW specification, a drive supporting DVD+RW discs +shall implement "true random writes with 2KB granularity", which means +that it should be possible to put any filesystem with a block size >= +2KB on such a disc. For example, it should be possible to do: + + # mkudffs /dev/hdc + # mount /dev/hdc /cdrom -t udf -o rw,noatime + +However, some drives don't follow the specification and expect the +host to perform aligned writes at 32KB boundaries. Other drives do +follow the specification, but suffer bad performance problems if the +writes are not 32KB aligned. + +Both problems can be solved by using the pktcdvd driver, which always +generates aligned writes. + + # pktsetup dev_name /dev/hdc + # mkudffs /dev/pktcdvd/dev_name + # mount /dev/pktcdvd/dev_name /cdrom -t udf -o rw,noatime + + +Notes +----- + +- CD-RW media can usually not be overwritten more than about 1000 + times, so to avoid unnecessary wear on the media, you should always + use the noatime mount option. + +- Defect management (ie automatic remapping of bad sectors) has not + been implemented yet, so you are likely to get at least some + filesystem corruption if the disc wears out. + +- Since the pktcdvd driver makes the disc appear as a regular block + device with a 2KB block size, you can put any filesystem you like on + the disc. For example, run: + + # /sbin/mke2fs /dev/pktcdvd/dev_name + + to create an ext2 filesystem on the disc. + + +Links +----- + +See http://fy.chalmers.se/~appro/linux/DVD+RW/ for more information +about DVD writing. diff --git a/Documentation/computone.txt b/Documentation/computone.txt index ea2b5d3e3..b1cf59b84 100644 --- a/Documentation/computone.txt +++ b/Documentation/computone.txt @@ -1,3 +1,13 @@ +NOTE: This is an unmaintained driver. It is not guaranteed to work due to +changes made in the tty layer in 2.6. If you wish to take over maintenance of +this driver, contact Michael Warfield . + +Changelog: +---------- +11-01-2001: Original Document + +10-29-2004: Minor misspelling & format fix, update status of driver. + James Nelson Computone Intelliport II/Plus Multiport Serial Driver ----------------------------------------------------- @@ -146,7 +156,7 @@ selects polled mode). If no base addresses are specified the defaults in ip2.c are used. If you are autoloading the driver module with kerneld or kmod the base addresses and interrupt number must also be set in ip2.c and recompile or just insert and options line in /etc/modprobe.conf or both. -The options line is equivalent to the command line and takes precidence over +The options line is equivalent to the command line and takes precedence over what is in ip2.c. /etc/modprobe.conf sample: @@ -166,7 +176,8 @@ The equivalent for the kernel command line (in lilo.conf): Note: Both io and irq should be updated to reflect YOUR system. An "io" - address of 1 or 2 indicates a PCI or EISA card in the board table. The PCI or EISA irq will be assigned automatically. + address of 1 or 2 indicates a PCI or EISA card in the board table. + The PCI or EISA irq will be assigned automatically. Specifying an invalid or in-use irq will default the driver into running in polled mode for that card. If all irq entries are 0 then diff --git a/Documentation/cpqarray.txt b/Documentation/cpqarray.txt index d0e185f7c..c7154e20e 100644 --- a/Documentation/cpqarray.txt +++ b/Documentation/cpqarray.txt @@ -26,31 +26,13 @@ unable to test against these cards: * IDA-2 * IAES -Installing: ------------ - -You need to build a new kernel to use this device, even if you want to -use a loadable module. - -Apply the patch to a 2.2.x kernel: - -# cd linux -# patch -p1 + + +1999 : Original Document diff --git a/Documentation/cpu-freq/cpufreq-nforce2.txt b/Documentation/cpu-freq/cpufreq-nforce2.txt new file mode 100644 index 000000000..9188337d8 --- /dev/null +++ b/Documentation/cpu-freq/cpufreq-nforce2.txt @@ -0,0 +1,19 @@ + +The cpufreq-nforce2 driver changes the FSB on nVidia nForce2 plattforms. + +This works better than on other plattforms, because the FSB of the CPU +can be controlled independently from the PCI/AGP clock. + +The module has two options: + + fid: multiplier * 10 (for example 8.5 = 85) + min_fsb: minimum FSB + +If not set, fid is calculated from the current CPU speed and the FSB. +min_fsb defaults to FSB at boot time - 50 MHz. + +IMPORTANT: The available range is limited downwards! + Also the minimum available FSB can differ, for systems + booting with 200 MHz, 150 should always work. + + diff --git a/Documentation/cpu-freq/user-guide.txt b/Documentation/cpu-freq/user-guide.txt index 5e6391ca9..7fedc00c3 100644 --- a/Documentation/cpu-freq/user-guide.txt +++ b/Documentation/cpu-freq/user-guide.txt @@ -65,6 +65,7 @@ Intel Pentium 4, Intel Xeon Intel Pentium M (Centrino) National Semiconductors Geode GX Transmeta Crusoe +Transmeta Efficeon VIA Cyrix 3 / C3 various processors on some ACPI 2.0-compatible systems [*] diff --git a/Documentation/crypto/api-intro.txt b/Documentation/crypto/api-intro.txt index 62778c57f..fa0c8b974 100644 --- a/Documentation/crypto/api-intro.txt +++ b/Documentation/crypto/api-intro.txt @@ -231,6 +231,9 @@ Whirlpool algorithm contributors: Aaron Grothe Jean-Luc Cooke +Anubis algorithm contributors: + Aaron Grothe + Generic scatterwalk code by Adam J. Richter Please send any credits updates or corrections to: diff --git a/Documentation/digiepca.txt b/Documentation/digiepca.txt index 01c4adc59..88820fe38 100644 --- a/Documentation/digiepca.txt +++ b/Documentation/digiepca.txt @@ -1,3 +1,11 @@ +NOTE: This driver is obsolete. Digi provides a 2.6 driver (dgdm) at +http://www.digi.com for PCI cards. They no longer maintain this driver, +and have no 2.6 driver for ISA cards. + +This driver requires a number of user-space tools. They can be aquired from +http://www.digi.com, but only works with 2.4 kernels. + + The Digi Intl. epca driver. ---------------------------- The Digi Intl. epca driver for Linux supports the following boards: @@ -64,9 +72,6 @@ drivers/char/README.epca for more details. Note, this driver REQUIRES that digiDload be executed prior to it being used. Failure to do this will result in an ENODEV error. -The latest version of the tool package is available at: -ftp://ftp.dgii.com/drivers/linux/released/async/ - Documentation: -------------- Complete documentation for this product may be found in the tool package. @@ -74,14 +79,8 @@ Complete documentation for this product may be found in the tool package. Sources of information and support: ----------------------------------- Digi Intl. support site for this product: --> digilnux@dgii.com -Related information and information concerning other drivers supporting -Digi Intl. products: - --> FTP: ftp://dgii.com --> Webpage: http://www.dgii.com --> Webpage: http://lameter.com/digi +-> http://www.digi.com Acknowledgments: ---------------- @@ -90,3 +89,10 @@ supporting the original public domain DigiBoard driver Copyright (C) 1994,1995 Troy De Jongh. Many thanks to Christoph Lameter (christoph@lameter.com) and Mike McLagan (mike.mclagan@linux.org) who authored and contributed to the original document. + +Changelog: +---------- +10-29-04: Update status of driver, remove dead links in document + James Nelson + +2000 (?) Original Document diff --git a/Documentation/dnotify.txt b/Documentation/dnotify.txt index 3434cb3d1..6984fca60 100644 --- a/Documentation/dnotify.txt +++ b/Documentation/dnotify.txt @@ -54,6 +54,12 @@ directory "b". Also, files that are unlinked, will still cause notifications in the last directory that they were linked to. +Configuration +------------- + +Dnotify is controlled via the CONFIG_DNOTIFY configuration option. When +disabled, fcntl(fd, F_NOTIFY, ...) will return -EINVAL. + Example ------- diff --git a/Documentation/dvb/README.dibusb b/Documentation/dvb/README.dibusb new file mode 100644 index 000000000..e3d650b81 --- /dev/null +++ b/Documentation/dvb/README.dibusb @@ -0,0 +1,247 @@ +Documentation for dib3000mb frontend driver and dibusb device driver +==================================================================== + +Copyright (C) 2004 Patrick Boettcher (patrick.boettcher@desy.de), + +dibusb and dib3000mb/mc drivers based on GPL code, which has + +Copyright (C) 2004 Amaury Demol for DiBcom (ademol@dibcom.fr) + +This program 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, version 2. + + +Supported devices USB1.1 +======================== + +Produced and reselled by Twinhan: +--------------------------------- +- TwinhanDTV USB-Ter DVB-T Device (VP7041) + http://www.twinhan.com/product_terrestrial_3.asp + +- TwinhanDTV Magic Box (VP7041e) + http://www.twinhan.com/product_terrestrial_4.asp + +- HAMA DVB-T USB device + http://www.hama.de/portal/articleId*110620/action*2598 + +- CTS Portable (Chinese Television System) + http://www.2cts.tv/ctsportable/ + +- Unknown USB DVB-T device with vendor ID Hyper-Paltek + + +Produced and reselled by KWorld: +-------------------------------- +- KWorld V-Stream XPERT DTV DVB-T USB + http://www.kworld.com.tw/en/product/DVBT-USB/DVBT-USB.html + +- JetWay DTV DVB-T USB + http://www.jetway.com.tw/evisn/product/lcd-tv/DVT-USB/dtv-usb.htm + +- ADSTech Instant TV DVB-T USB + http://www.adstech.com/products/PTV-333/intro/PTV-333_intro.asp?pid=PTV-333 + + +Others: +------- +- Ultima Electronic/Artec T1 USB TVBOX (AN2135 and AN2235) + http://82.161.246.249/products-tvbox.html + +- Compro Videomate DVB-U2000 - DVB-T USB + http://www.comprousa.com/products/vmu2000.htm + +- Grandtec USB DVB-T + http://www.grand.com.tw/ + +- Avermedia AverTV DVBT USB + http://www.avermedia.com/ + +- DiBcom USB DVB-T reference device (non-public) + + +Supported devices USB2.0 +======================== +- Twinhan MagicBox II + http://www.twinhan.com/product_terrestrial_7.asp + +- Yakumo DVB-T mobile + http://www.yakumo.de/produkte/index.php?pid=1&ag=DVB-T + +- DiBcom USB2.0 DVB-T reference device (non-public) + + +0. NEWS: + 2004-12-06 - possibility for demod i2c-address probing + - new usb IDs (Compro,Artec) + 2004-11-23 - merged changes from DiB3000MC_ver2.1 + - revised the debugging + - possibility to deliver the complete TS for USB2.0 + 2004-11-21 - first working version of the dib3000mc/p frontend driver. + 2004-11-12 - added additional remote control keys. Thanks to Uwe Hanke. + 2004-11-07 - added remote control support. Thanks to David Matthews. + 2004-11-05 - added support for a new devices (Grandtec/Avermedia/Artec) + - merged my changes (for dib3000mb/dibusb) to the FE_REFACTORING, because it became HEAD + - moved transfer control (pid filter, fifo control) from usb driver to frontend, it seems + better settled there (added xfer_ops-struct) + - created a common files for frontends (mc/p/mb) + 2004-09-28 - added support for a new device (Unkown, vendor ID is Hyper-Paltek) + 2004-09-20 - added support for a new device (Compro DVB-U2000), thanks + to Amaury Demol for reporting + - changed usb TS transfer method (several urbs, stopping transfer + before setting a new pid) + 2004-09-13 - added support for a new device (Artec T1 USB TVBOX), thanks + to Christian Motschke for reporting + 2004-09-05 - released the dibusb device and dib3000mb-frontend driver + + (old news for vp7041.c) + 2004-07-15 - found out, by accident, that the device has a TUA6010XS for + PLL + 2004-07-12 - figured out, that the driver should also work with the + CTS Portable (Chinese Television System) + 2004-07-08 - firmware-extraction-2.422-problem solved, driver is now working + properly with firmware extracted from 2.422 + - #if for 2.6.4 (dvb), compile issue + - changed firmware handling, see vp7041.txt sec 1.1 + 2004-07-02 - some tuner modifications, v0.1, cleanups, first public + 2004-06-28 - now using the dvb_dmx_swfilter_packets, everything + runs fine now + 2004-06-27 - able to watch and switching channels (pre-alpha) + - no section filtering yet + 2004-06-06 - first TS received, but kernel oops :/ + 2004-05-14 - firmware loader is working + 2004-05-11 - start writing the driver + +1. How to use? +NOTE: This driver was developed using Linux 2.6.6., +it is working with 2.6.7, 2.6.8.1, 2.6.9 . + +Linux 2.4.x support is not planned, but patches are very welcome. + +NOTE: I'm using Debian testing, so the following explaination (especially +the hotplug-path) needn't match your system, but probably it will :). + +1.1. Firmware + +The USB driver needs to download a firmware to start working. + +You can either use "get_dvb_firmware dibusb" to download the firmware or you +can get it directly via + +for USB1.1 (AN2135) +http://linuxtv.org/cgi-bin/cvsweb.cgi/dvb-kernel/firmware/dvb-dibusb-5.0.0.11.fw?rev=1.1&content-type=text/plain + +for USB1.1 (AN2235) (a few Artec T1 devices) +http://linuxtv.org/cgi-bin/cvsweb.cgi/dvb-kernel/firmware/dvb-dibusb-an2235-1.fw?rev=1.1&content-type=text/plain + +for USB2.0 (FX2) +http://linuxtv.org/cgi-bin/cvsweb.cgi/dvb-kernel/firmware/dvb-dibusb-6.0.0.5.fw?rev=1.1&content-type=text/plain + +1.2. Compiling + +Since the driver is in the linux kernel, activating the driver in +your favorite config-environment should sufficient. I recommend +to compile the driver as module. Hotplug does the rest. + +1.3. Loading the drivers + +Hotplug is able to load the driver, when it is needed (because you plugged +in the device). + +If you want to enable debug output, you have to load the driver manually and +from withing the dvb-kernel cvs repository. + +first have a look, which debug level are available: + +modinfo dib3000mb +modinfo dvb-dibusb + +modprobe dib3000mb debug= +modprobe dvb-dibusb debug= + +should do the trick. + +When the driver is loaded successfully, the firmware file was in +the right place and the device is connected, the "Power"-LED should be +turned on. + +At this point you should be able to start a dvb-capable application. For myself +I used mplayer, dvbscan, tzap and kaxtv, they are working. Using the device +as a slave device in vdr, was not working for me. Some work has to be done +(patches and comments are very welcome). + +2. Known problems and bugs + +TODO: +- signal-quality and strength calculations + +2.1. Adding support for devices + +It is not possible to determine the range of devices based on the DiBcom +reference designs. This is because the reference design of DiBcom can be sold +to thirds, without telling DiBcom (so done with the Twinhan VP7041 and +the HAMA device). + +When you think you have a device like this and the driver does not recognizes it, +please send the ****load*.inf and the ****cap*.inf of the Windows driver to me. + +Sometimes the Vendor or Product ID is identical to the ones of Twinhan, even +though it is not a Twinhan device (e.g. HAMA), then please send me the name +of the device. I will add it to this list in order to make this clear to +others. + +If you are familar with C you can also add the VID and PID of the device to +the dvb-dibusb.h-file and create a patch and send it over to me or to +the linux-dvb mailing list, _after_ you have tried compiling and modprobing +it. + +2.2. USB1.1 Bandwidth limitation + +Most of the current supported devices are USB1.1 and thus they have a +maximum bandwidth of about 5-6 MBit/s when connected to a USB2.0 hub. +This is not enough for receiving the complete transport stream of a +DVB-T channel (which can be about 16 MBit/s). Normally this is not a +problem, if you only want to watch TV, but watching a channel while +recording another channel on the same frequency simply does not work. +This applies to all USB1.1 DVB-T devices. + +A special problem of the dibusb for the USB1.1 is, that the USB control +IC has a problem with write accesses while having MPEG2-streaming +enabled. When you set another pid while receiving MPEG2-TS it happens, that +the stream is disturbed and probably data is lost (results in distortions of +the video or strange beeps within the audio stream). DiBcom is preparing a +firmware especially for Linux which perhaps solves the problem. + +Especially VDR users are victoms of this bug. VDR frequently requests new PIDs +due the automatic scanning (introduced in 1.3.x, afaik) and epg-scan. Disabling +these features is maybe a solution. Additionally this behaviour of VDR exceeds +the USB1.1 bandwidth. + +2.3. Comments + +Patches, comments and suggestions are very very welcome + +3. Acknowledgements + Amaury Demol (ademol@dibcom.fr) and Francois Kanounnikoff from DiBcom for + providing specs, code and help, on which the dvb-dibusb and dib3000mb are + based. + + David Matthews for identifying a new device type (Artec T1 with AN2235) + and for extending dibusb with remote control event handling. Thank you. + + Alex Woods for frequently answering question about usb and dvb + stuff, a big thank you + + Bernd Wagner for helping with huge bug reports and discussions. + + Some guys on the linux-dvb mailing list for encouraging me + + Peter Schildmann >peter.schildmann-nospam-at-web.de< for his + user-level firmware loader, which saves a lot of time + (when writing the vp7041 driver) + + Ulf Hermenau for helping me out with traditional chinese. + + André Smoktun and Christian Frömmel for supporting me with + hardware and listening to my problems very patient diff --git a/Documentation/dvb/avermedia.txt b/Documentation/dvb/avermedia.txt index 5d8dbdada..09020ebd2 100644 --- a/Documentation/dvb/avermedia.txt +++ b/Documentation/dvb/avermedia.txt @@ -6,7 +6,6 @@ HOWTO: Get An Avermedia DVB-T working under Linux Assumptions and Introduction The Avermedia DVB-T Getting the card going - Getting the Firmware Receiving DVB-T in Australia Known Limitations Further Update @@ -149,28 +148,9 @@ Getting the card going to start accessing the card with utilities such as scan, tzap, dvbstream etc. - The current version of the frontend module sp887x.o, contains - no firmware drivers?, so the first time you open it with a DVB - utility the driver will try to download some initial firmware - to the card. You will need to download this firmware from the - web, or copy it from an installation of the Windows drivers - that probably came with your card, before you can use it. - - The default Linux filesystem location for this firmware is - /usr/lib/hotplug/firmware/sc_main.mc . - _________________________________________________________ - -Getting the Firmware - - As the firmware for the card is no longer contained within the - driver, it is necessary to extract it from the windows - drivers. - - The Windows drivers for the Avermedia DVB-T can be obtained - from: http://babyurl.com/H3U970 and you can get an application - to extract the firmware from: - http://www.kyz.uklinux.net/cabextract.php. - _________________________________________________________ + The frontend module sp887x.o, requires an external firmware. + Please use the command "get_dvb_firmware sp887x" to download + it. Then copy it to /usr/lib/hotplug/firmware. Receiving DVB-T in Australia diff --git a/Documentation/dvb/cards.txt b/Documentation/dvb/cards.txt index 695f174d8..efdc4ee9d 100644 --- a/Documentation/dvb/cards.txt +++ b/Documentation/dvb/cards.txt @@ -38,6 +38,7 @@ o Frontends drivers: Comtech DVBT-6k07 (SP5730 PLL) (NxtWave Communications NXT6000 demodulator) - sp887x : Microtune 7202D + - dib3000mb : DiBcom 3000-MB demodulator DVB-S/C/T: - dst : TwinHan DST Frontend @@ -49,7 +50,7 @@ o Cards based on the Phillips saa7146 multimedia PCI bridge chip: - "budget" cards (i.e. without hardware MPEG decoder): - Technotrend Budget / Hauppauge WinTV-Nova PCI Cards - SATELCO Multimedia PCI - - KNC1 DVB-S + - KNC1 DVB-S, Typhoon DVB-S, Terratec Cinergy 1200 DVB-S (no CI support) - Typhoon DVB-S budget - Fujitsu-Siemens Activy DVB-S budget card @@ -66,4 +67,19 @@ o Technotrend / Hauppauge DVB USB devices: - Nova USB - DEC 2000-T, 3000-S, 2540-T +o DiBcom DVB-T USB based devices: + - Twinhan VisionPlus VisionDTV USB-Ter DVB-T Device + - HAMA DVB-T USB device + - CTS Portable (Chinese Television System) + - KWorld V-Stream XPERT DTV DVB-T USB + - JetWay DTV DVB-T USB + - ADSTech Instant TV DVB-T USB + - Ultima Electronic/Artec T1 USB TVBOX (AN2135 and AN2235) + - Compro Videomate DVB-U2000 - DVB-T USB + - Grandtec USB DVB-T + - Avermedia AverTV DVBT USB + - DiBcom USB DVB-T reference device (non-public) + - Yakumo DVB-T mobile USB2.0 + - DiBcom USB2.0 DVB-T reference device (non-public) + o Experimental support for the analog module of the Siemens DVB-C PCI card diff --git a/Documentation/dvb/contributors.txt b/Documentation/dvb/contributors.txt index 12026e933..dd40ad665 100644 --- a/Documentation/dvb/contributors.txt +++ b/Documentation/dvb/contributors.txt @@ -69,6 +69,8 @@ Andreas 'randy' Weinberger Kenneth Aafløy for adding support for Typhoon DVB-S budget card +Ernst Peinlich + for tuning/DiSEqC support for the DEC 3000-s (If you think you should be in this list, but you are not, drop a line to the DVB mailing list) diff --git a/Documentation/dvb/get_dvb_firmware b/Documentation/dvb/get_dvb_firmware new file mode 100644 index 000000000..e9964b71e --- /dev/null +++ b/Documentation/dvb/get_dvb_firmware @@ -0,0 +1,339 @@ +#!/usr/bin/perl +# DVB firmware extractor +# +# (c) 2004 Andrew de Quincey +# +# This program 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., 675 Mass Ave, Cambridge, MA 02139, USA. + +use File::Temp qw/ tempdir /; +use IO::Handle; + +@components = ( "sp8870", "sp887x", "tda10045", "tda10046", "av7110", "dec2000t", "dec2540t", "dec3000s", "vp7041", "dibusb" ); + +# Check args +syntax() if (scalar(@ARGV) != 1); +$cid = $ARGV[0]; + +# Do it! +for($i=0; $i < scalar(@components); $i++) { + if ($cid eq $components[$i]) { + $outfile = eval($cid); + die $@ if $@; + print STDERR "Firmware $outfile extracted successfully. Now copy it to either /lib/firmware or /usr/lib/hotplug/firmware/ (depending on your hotplug version).\n"; + exit(0); + } +} + +# If we get here, it wasn't found +print STDERR "Unknown component \"$cid\"\n"; +syntax(); + + + + +# --------------------------------------------------------------- +# Firmware-specific extraction subroutines + +sub sp8870 { + my $sourcefile = "tt_Premium_217g.zip"; + my $url = "http://www.technotrend.de/new/217g/$sourcefile"; + my $hash = "53970ec17a538945a6d8cb608a7b3899"; + my $outfile = "dvb-fe-sp8870.fw"; + my $tmpdir = tempdir(DIR => "/tmp", CLEANUP => 1); + + checkstandard(); + + wgetfile($sourcefile, $url); + unzip($sourcefile, $tmpdir); + verify("$tmpdir/software/OEM/HE/App/boot/SC_MAIN.MC", $hash); + copy("$tmpdir/software/OEM/HE/App/boot/SC_MAIN.MC", $outfile); + + $outfile; +} + +sub sp887x { + my $sourcefile = "Dvbt1.3.57.6.zip"; + my $url = "http://www.avermedia.com/software/$sourcefile"; + my $cabfile = "DVBT Net Ver1.3.57.6/disk1/data1.cab"; + my $hash = "237938d53a7f834c05c42b894ca68ac3"; + my $outfile = "dvb-fe-sp887x.fw"; + my $tmpdir = tempdir(DIR => "/tmp", CLEANUP => 1); + + checkstandard(); + checkunshield(); + + wgetfile($sourcefile, $url); + unzip($sourcefile, $tmpdir); + unshield("$tmpdir/$cabfile", $tmpdir); + verify("$tmpdir/sc_main.mc", $hash); + copy("$tmpdir/sc_main.mc", $outfile); + + $outfile; +} + +sub tda10045 { + my $sourcefile = "tt_budget_217g.zip"; + my $url = "http://www.technotrend.de/new/217g/$sourcefile"; + my $hash = "2105fd5bf37842fbcdfa4bfd58f3594a"; + my $outfile = "dvb-fe-tda10045.fw"; + my $tmpdir = tempdir(DIR => "/tmp", CLEANUP => 1); + + checkstandard(); + + wgetfile($sourcefile, $url); + unzip($sourcefile, $tmpdir); + extract("$tmpdir/software/OEM/PCI/App/ttlcdacc.dll", 0x37ef9, 30555, "$tmpdir/fwtmp"); + verify("$tmpdir/fwtmp", $hash); + copy("$tmpdir/fwtmp", $outfile); + + $outfile; +} + +sub tda10046 { + my $sourcefile = "tt_budget_217g.zip"; + my $url = "http://www.technotrend.de/new/217g/$sourcefile"; + my $hash = "a25b579e37109af60f4a36c37893957c"; + my $outfile = "dvb-fe-tda10046.fw"; + my $tmpdir = tempdir(DIR => "/tmp", CLEANUP => 1); + + checkstandard(); + + wgetfile($sourcefile, $url); + unzip($sourcefile, $tmpdir); + extract("$tmpdir/software/OEM/PCI/App/ttlcdacc.dll", 0x3f731, 24479, "$tmpdir/fwtmp"); + verify("$tmpdir/fwtmp", $hash); + copy("$tmpdir/fwtmp", $outfile); + + $outfile; +} + +sub av7110 { + my $sourcefile = "dvb-ttpci-01.fw-261c"; + my $url = "http://www.linuxtv.org/download/dvb/firmware/$sourcefile"; + my $hash = "7b263de6b0b92d2347319c65adc7d4fb"; + my $outfile = "dvb-ttpci-01.fw"; + + checkstandard(); + + wgetfile($sourcefile, $url); + verify($sourcefile, $hash); + copy($sourcefile, $outfile); + + $outfile; +} + +sub dec2000t { + my $sourcefile = "dec217g.exe"; + my $url = "http://hauppauge.lightpath.net/de/$sourcefile"; + my $hash = "bd86f458cee4a8f0a8ce2d20c66215a9"; + my $outfile = "dvb-ttusb-dec-2000t.fw"; + my $tmpdir = tempdir(DIR => "/tmp", CLEANUP => 1); + + checkstandard(); + + wgetfile($sourcefile, $url); + unzip($sourcefile, $tmpdir); + verify("$tmpdir/software/OEM/STB/App/Boot/STB_PC_T.bin", $hash); + copy("$tmpdir/software/OEM/STB/App/Boot/STB_PC_T.bin", $outfile); + + $outfile; +} + +sub dec2540t { + my $sourcefile = "dec217g.exe"; + my $url = "http://hauppauge.lightpath.net/de/$sourcefile"; + my $hash = "53e58f4f5b5c2930beee74a7681fed92"; + my $outfile = "dvb-ttusb-dec-2540t.fw"; + my $tmpdir = tempdir(DIR => "/tmp", CLEANUP => 1); + + checkstandard(); + + wgetfile($sourcefile, $url); + unzip($sourcefile, $tmpdir); + verify("$tmpdir/software/OEM/STB/App/Boot/STB_PC_X.bin", $hash); + copy("$tmpdir/software/OEM/STB/App/Boot/STB_PC_X.bin", $outfile); + + $outfile; +} + +sub dec3000s { + my $sourcefile = "dec217g.exe"; + my $url = "http://hauppauge.lightpath.net/de/$sourcefile"; + my $hash = "b013ececea83f4d6d8d2a29ac7c1b448"; + my $outfile = "dvb-ttusb-dec-3000s.fw"; + my $tmpdir = tempdir(DIR => "/tmp", CLEANUP => 1); + + checkstandard(); + + wgetfile($sourcefile, $url); + unzip($sourcefile, $tmpdir); + verify("$tmpdir/software/OEM/STB/App/Boot/STB_PC_S.bin", $hash); + copy("$tmpdir/software/OEM/STB/App/Boot/STB_PC_S.bin", $outfile); + + $outfile; +} + +sub vp7041 { + my $sourcefile = "2.422.zip"; + my $url = "http://www.twinhan.com/files/driver/USB-Ter/$sourcefile"; + my $hash = "e88c9372d1f66609a3e7b072c53fbcfe"; + my $outfile = "dvb-vp7041-2.422.fw"; + my $tmpdir = tempdir(DIR => "/tmp", CLEANUP => 1); + + checkstandard(); + + wgetfile($sourcefile, $url); + unzip($sourcefile, $tmpdir); + extract("$tmpdir/VisionDTV/Drivers/Win2K&XP/UDTTload.sys", 12503, 3036, "$tmpdir/fwtmp1"); + extract("$tmpdir/VisionDTV/Drivers/Win2K&XP/UDTTload.sys", 2207, 10274, "$tmpdir/fwtmp2"); + + my $CMD = "\000\001\000\222\177\000"; + my $PAD = "\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000"; + my ($FW); + open $FW, ">$tmpdir/fwtmp3"; + print $FW "$CMD\001$PAD"; + print $FW "$CMD\001$PAD"; + appendfile($FW, "$tmpdir/fwtmp1"); + print $FW "$CMD\000$PAD"; + print $FW "$CMD\001$PAD"; + appendfile($FW, "$tmpdir/fwtmp2"); + print $FW "$CMD\001$PAD"; + print $FW "$CMD\000$PAD"; + close($FW); + + verify("$tmpdir/fwtmp3", $hash); + copy("$tmpdir/fwtmp3", $outfile); + + $outfile; +} + +sub dibusb { + my $url = "http://linuxtv.org/cgi-bin/cvsweb.cgi/dvb-kernel/firmware/dvb-dibusb-5.0.0.11.fw?rev=1.1&content-type=text/plain"; + my $outfile = "dvb-dibusb-5.0.0.11.fw"; + my $hash = "fa490295a527360ca16dcdf3224ca243"; + + checkstandard(); + + wgetfile($outfile, $url); + verify($outfile,$hash); + + $outfile; +} + +# --------------------------------------------------------------- +# Utilities + +sub checkstandard { + if (system("which unzip > /dev/null 2>&1")) { + die "This firmware requires the unzip command - see ftp://ftp.info-zip.org/pub/infozip/UnZip.html\n"; + } + if (system("which md5sum > /dev/null 2>&1")) { + die "This firmware requires the md5sum command - see http://www.gnu.org/software/coreutils/\n"; + } + if (system("which wget > /dev/null 2>&1")) { + die "This firmware requires the wget command - see http://wget.sunsite.dk/\n"; + } +} + +sub checkunshield { + if (system("which unshield > /dev/null 2>&1")) { + die "This firmware requires the unshield command - see http://sourceforge.net/projects/synce/\n"; + } +} + +sub wgetfile { + my ($sourcefile, $url) = @_; + + if (! -f $sourcefile) { + system("wget -O \"$sourcefile\" \"$url\"") and die "wget failed - unable to download firmware"; + } +} + +sub unzip { + my ($sourcefile, $todir) = @_; + + $status = system("unzip -q -o -d \"$todir\" \"$sourcefile\" 2>/dev/null" ); + if ((($status >> 8) > 2) || (($status & 0xff) != 0)) { + die ("unzip failed - unable to extract firmware"); + } +} + +sub unshield { + my ($sourcefile, $todir) = @_; + + system("unshield -d \"$todir\" \"$sourcefile\" > /dev/null" ) and die ("unshield failed - unable to extract firmware"); +} + +sub verify { + my ($filename, $hash) = @_; + my ($testhash); + + open(CMD, "md5sum \"$filename\"|"); + $testhash = ; + $testhash =~ /([a-zA-Z0-9]*)/; + $testhash = $1; + close CMD; + die "Hash of extracted file does not match!\n" if ($testhash ne $hash); +} + +sub copy { + my ($from, $to) = @_; + + system("cp -f \"$from\" \"$to\"") and die ("cp failed"); +} + +sub extract { + my ($infile, $offset, $length, $outfile) = @_; + my ($chunklength, $buf, $rcount); + + open INFILE, "<$infile"; + open OUTFILE, ">$outfile"; + sysseek(INFILE, $offset, SEEK_SET); + while($length > 0) { + # Calc chunk size + $chunklength = 2048; + $chunklength = $length if ($chunklength > $length); + + $rcount = sysread(INFILE, $buf, $chunklength); + die "Ran out of data\n" if ($rcount != $chunklength); + syswrite(OUTFILE, $buf); + $length -= $rcount; + } + close INFILE; + close OUTFILE; +} + +sub appendfile { + my ($FH, $infile) = @_; + my ($buf); + + open INFILE, "<$infile"; + while(1) { + $rcount = sysread(INFILE, $buf, 2048); + last if ($rcount == 0); + print $FH $buf; + } + close(INFILE); +} + +sub syntax() { + print STDERR "syntax: get_dvb_firmware \n"; + print STDERR "Supported components:\n"; + for($i=0; $i < scalar(@components); $i++) { + print STDERR "\t" . $components[$i] . "\n"; + } + exit(1); +} diff --git a/Documentation/dvb/readme.txt b/Documentation/dvb/readme.txt index 720aa8ce0..a60c27d43 100644 --- a/Documentation/dvb/readme.txt +++ b/Documentation/dvb/readme.txt @@ -28,9 +28,9 @@ is the who-is-who of DVB development "faq.txt" contains frequently asked questions and their answers. -"firmware.txt" -contains informations for required external firmware -files and where to get them. +"get_dvb_firmware" +script to download and extract firmware for those devices +that require it. "ttusb-dec.txt" contains detailed informations about the @@ -41,4 +41,11 @@ contains detailed installation instructions for the various bt8xx based "budget" DVB cards (Nebula, Pinnacle PCTV, Twinhan DST) +"README.dibusb" +contains detailed information about adapters +based on DiBcom reference design. + +"udev.txt" +how to get DVB and udev up and running. + Good luck and have fun! diff --git a/Documentation/dvb/ttusb-dec.txt b/Documentation/dvb/ttusb-dec.txt index 4a547fba7..5c1e984c2 100644 --- a/Documentation/dvb/ttusb-dec.txt +++ b/Documentation/dvb/ttusb-dec.txt @@ -6,6 +6,8 @@ Driver Status Supported: DEC2000-t + DEC2450-t + DEC3000-s Linux Kernels 2.4 and 2.6 Video Streaming Audio Streaming @@ -13,52 +15,30 @@ Supported: Channel Zapping Hotplug firmware loader under 2.6 kernels -In Progress: - DEC2540-t - DEC3000-s - To Do: Tuner status information DVB network interface Streaming video PC->DEC + Conax support for 2450-t Getting the Firmware -------------------- -The firmware can be found in the software update zip files on this page: -http://www.hauppauge.de/sw_dec.htm - -The firmwares are named as follows: -DEC2000-t: STB_PC_T.bin -DEC2540-t: STB_PC_X.bin -DEC3000-s: STB_PC_S.bin - -Note that firmwares since version 2.16 beta2 for the DEC2000-t give the device -the USB ID of the DEC3000-s. The driver copes with this. - -Instructions follow for retrieving version 2.16 of the firmware: - -wget http://hauppauge.lightpath.net/de/dec216.exe -unzip -j dec216.exe software/OEM/STB/App/Boot/STB_PC_T.bin -unzip -j dec216.exe software/OEM/STB/App/Boot/STB_PC_X.bin -unzip -j dec216.exe software/OEM/STB/App/Boot/STB_PC_S.bin +To download the firmware, use the following commands: +"get_dvb_firmware dec2000t" +"get_dvb_firmware dec2540t" +"get_dvb_firmware dec3000s" Compilation Notes for 2.4 kernels --------------------------------- For 2.4 kernels the firmware for the DECs is compiled into the driver itself. -The firmwares are expected to be in the build-2.4 directory at compilation -time. -mv STB_PC_T.bin build-2.4/dvb-ttusb-dec-2000t.fw -mv STB_PC_X.bin build-2.4/dvb-ttusb-dec-2540t.fw -mv STB_PC_S.bin build-2.4/dvb-ttusb-dec-3000s.fw +Copy the three files downloaded above into the build-2.4 directory. Hotplug Firmware Loading for 2.6 kernels ---------------------------------------- For 2.6 kernels the firmware is loaded at the point that the driver module is -loaded. See Documentation/dvb/firmware.txt for more information. +loaded. See linux/Documentation/dvb/firmware.txt for more information. -mv STB_PC_T.bin /usr/lib/hotplug/firmware/dvb-ttusb-dec-2000t.fw -mv STB_PC_X.bin /usr/lib/hotplug/firmware/dvb-ttusb-dec-2540t.fw -mv STB_PC_S.bin /usr/lib/hotplug/firmware/dvb-ttusb-dec-3000s.fw +Copy the three files downloaded above into the /usr/lib/hotplug/firmware directory. diff --git a/Documentation/dvb/udev.txt b/Documentation/dvb/udev.txt new file mode 100644 index 000000000..68ee224b6 --- /dev/null +++ b/Documentation/dvb/udev.txt @@ -0,0 +1,46 @@ +The DVB subsystem currently registers to the sysfs subsystem using the +"class_simple" interface. + +This means that only the basic informations like module loading parameters +are presented through sysfs. Other things that might be interesting are +currently *not* available. + +Nevertheless it's now possible to add proper udev rules so that the +DVB device nodes are created automatically. + +We assume that you have udev already up and running and that have been +creating the DVB device nodes manually up to now due to the missing sysfs +support. + +0. Don't forget to disable your current method of creating the +device nodes manually. + +1. Unfortunately, you'll need a helper script to transform the kernel +sysfs device name into the well known dvb adapter / device naming scheme. +The script should be called "dvb.sh" and should be placed into a script +dir where udev can execute it, most likely /etc/udev/scripts/ + +So, create a new file /etc/udev/scripts/dvb.sh and add the following: +------------------------------schnipp------------------------------------------------ +#!/bin/sh +/bin/echo $1 | /bin/sed -e 's,dvb\([0-9]\)\.\([^0-9]*\)\([0-9]\),dvb/adapter\1/\2\3,' +------------------------------schnipp------------------------------------------------ + +Don't forget to make the script executable with "chmod". + +1. You need to create a proper udev rule that will create the device nodes +like you know them. All real distributions out there scan the /etc/udev/rules.d +directory for rule files. The main udev configuration file /etc/udev/udev.conf +will tell you the directory where the rules are, most likely it's /etc/udev/rules.d/ + +Create a new rule file in that directory called "dvb.rule" and add the following line: +------------------------------schnipp------------------------------------------------ +KERNEL="dvb*", PROGRAM="/etc/udev/scripts/dvb.sh %k", NAME="%c" +------------------------------schnipp------------------------------------------------ + +If you want more control over the device nodes (for example a special group membership) +have a look at "man udev". + +For every device that registers to the sysfs subsystem with a "dvb" prefix, +the helper script /etc/udev/scripts/dvb.sh is invoked, which will then +create the proper device node in your /dev/ directory. diff --git a/Documentation/fb/matroxfb.txt b/Documentation/fb/matroxfb.txt index 621e3b3e4..ad7a67707 100644 --- a/Documentation/fb/matroxfb.txt +++ b/Documentation/fb/matroxfb.txt @@ -223,6 +223,13 @@ dfp:X - use settings X for digital flat panel interface. X is number from selects who is source of display clocks, whether G400, or panel. Default value is now read back from hardware - so you should specify this value only if you are also using `init' parameter. +outputs:XYZ - set mapping between CRTC and outputs. Each letter can have value + of 0 (for no CRTC), 1 (CRTC1) or 2 (CRTC2), and first letter corresponds + to primary analog output, second letter to the secondary analog output + and third letter to the DVI output. Default setting is 100 for + cards below G400 or G400 without DFP, 101 for G400 with DFP, and + 111 for G450 and G550. You can set mapping only on first card, + use matroxset for setting up other devices. vesa:X - selects startup videomode. X is number from 0 to 0x1FF, see table above for detailed explanation. Default is 640x480x8bpp if driver has 8bpp support. Otherwise first available of 640x350x4bpp, diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking index f1c2cee13..570ef5db0 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/Locking @@ -295,13 +295,19 @@ fl_release_private: yes yes prototypes: int (*fl_compare_owner)(struct file_lock *, struct file_lock *); void (*fl_notify)(struct file_lock *); /* unblock callback */ + void (*fl_copy_lock)(struct file_lock *, struct file_lock *); + void (*fl_release_private)(struct file_lock *); + void (*fl_break)(struct file_lock *); /* break_lease callback */ locking rules: BKL may block fl_compare_owner: yes no fl_notify: yes no +fl_copy_lock: yes no +fl_release_private: yes yes +fl_break: yes no - Currently only NLM provides instances of this class. None of the + Currently only NFSD and NLM provide instances of this class. None of the them block. If you have out-of-tree instances - please, show up. Locking in that area will change. --------------------------- buffer_head ----------------------------------- @@ -311,8 +317,8 @@ prototypes: locking rules: called from interrupts. In other words, extreme care is needed here. bh is locked, but that's all warranties we have here. Currently only RAID1, -highmem and fs/buffer.c are providing these. Block devices call this method -upon the IO completion. +highmem, fs/buffer.c, and fs/ntfs/aops.c are providing these. Block devices +call this method upon the IO completion. --------------------------- block_device_operations ----------------------- prototypes: diff --git a/Documentation/filesystems/devfs/ChangeLog b/Documentation/filesystems/devfs/ChangeLog index 12583144e..e5aba5246 100644 --- a/Documentation/filesystems/devfs/ChangeLog +++ b/Documentation/filesystems/devfs/ChangeLog @@ -1632,7 +1632,7 @@ Changes for patch v177 - Fixed bugs in handling symlinks: could leak or cause Oops - Cleaned up directory handling by separating fops - Thanks to Alexander Viro + Thanks to Alexander Viro =============================================================================== Changes for patch v178 diff --git a/Documentation/filesystems/devfs/README b/Documentation/filesystems/devfs/README index 3ef858266..54366ecc2 100644 --- a/Documentation/filesystems/devfs/README +++ b/Documentation/filesystems/devfs/README @@ -1349,47 +1349,6 @@ This will cause devfsd to create (and destroy) symbolic links which point to the kernel-supplied names. -SCSI Host Probing Issues - -Devfs allows you to identify SCSI discs based in part on SCSI host -numbers. If you have only one SCSI host (card) in your computer, then -clearly it will be given host number 0. Life is not always that easy -is you have multiple SCSI hosts. Unfortunately, it can sometimes be -difficult to guess what the probing order of SCSI hosts is. You need -to know the probe order before you can use device names. To make this -easy, there is a kernel boot parameter called "scsihosts". This allows -you to specify the probe order for different types of SCSI hosts. The -syntax of this parameter is: - -scsihosts=:::...: - -where ,,..., are the names -of drivers used in the /proc filesystem. For example: - - scsihosts=aha1542:ppa:aha1542::ncr53c7xx - - -means that devices connected to - -- first aha1542 controller - will be /dev/scsi/host0/bus#/target#/lun# -- first parallel port ZIP - will be /dev/scsi/host1/bus#/target#/lun# -- second aha1542 controller - will be /dev/scsi/host2/bus#/target#/lun# -- first NCR53C7xx controller - will be /dev/scsi/host4/bus#/target#/lun# -- any extra controller - will be /dev/scsi/host5/bus#/target#/lun#, - /dev/scsi/host6/bus#/target#/lun#, etc -- if any of above controllers will not be found - the reserved names will - not be used by any other device. -- /dev/scsi/host3/bus#/target#/lun# names will never be used - - -You can use ',' instead of ':' as the separator character if you -wish. I have used the devfsd naming scheme -here. - -Note that this scheme does not address the SCSI host order if you have -multiple cards of the same type (such as NCR53c8xx). In this case you -need to use the driver-specific boot parameters to control this. - ----------------------------------------------------------------------------- @@ -1952,12 +1911,6 @@ explores the SCSI subsystem and how it interacts with devfs Douglas Gilbert has written another useful document at -http://www.torque.net/scsi/scsihosts.html which -discusses the scsihosts= boot option - - -Douglas Gilbert has written yet another useful document at - http://www.torque.net/scsi/SCSI-2.4-HOWTO/ which discusses the Linux SCSI subsystem in 2.4. diff --git a/Documentation/filesystems/ext2.txt b/Documentation/filesystems/ext2.txt index 23a4d98f9..b5cb9110c 100644 --- a/Documentation/filesystems/ext2.txt +++ b/Documentation/filesystems/ext2.txt @@ -11,57 +11,53 @@ for NetBSD, FreeBSD, the GNU HURD, Windows 95/98/NT, OS/2 and RISC OS. Options ======= -When mounting an ext2 filesystem, the following options are accepted. -Defaults are marked with (*). +Most defaults are determined by the filesystem superblock, and can be +set using tune2fs(8). Kernel-determined defaults are indicated by (*). bsddf (*) Makes `df' act like BSD. minixdf Makes `df' act like Minix. -barrier=1 This enables/disables barriers. barrier=0 disables it, - barrier=1 enables it. - -orlov (*) This enables the new Orlov block allocator. It's - enabled by default. - -oldalloc This disables the Orlov block allocator and - enables the old block allocator. Orlov should - have better performance, we'd like to get some - feedback if it's the contrary for you. - -user_xattr (*) Enables POSIX Extended Attributes. It's enabled by - default, however you need to confifure its support - (CONFIG_EXT2_FS_XATTR). This is neccesary if you want - to use POSIX Acces Control Lists support. You can visit - http://acl.bestbits.at to know more about POSIX Extended - attributes. - -nouser_xattr Disables POSIX Extended Attributes. - -acl (*) Enables POSIX Access Control Lists support. This is - enabled by default, however you need to configure - its support (CONFIG_EXT2_FS_POSIX_ACL). If you want - to know more about ACLs visit http://acl.bestbits.at - -noacl This option disables POSIX Access Control List support. - +check Check block and inode bitmaps at mount time + (requires CONFIG_EXT2_CHECK). check=none, nocheck (*) Don't do extra checking of bitmaps on mount (check=normal and check=strict options removed) debug Extra debugging information is sent to the kernel syslog. Useful for developers. -errors=continue (*) Keep going on a filesystem error. +errors=continue Keep going on a filesystem error. errors=remount-ro Remount the filesystem read-only on an error. errors=panic Panic and halt the machine if an error occurs. grpid, bsdgroups Give objects the same group ID as their parent. -nogrpid, sysvgroups (*) New objects have the group ID of their creator. +nogrpid, sysvgroups New objects have the group ID of their creator. + +nouid32 Use 16-bit UIDs and GIDs. + +oldalloc Enable the old block allocator. Orlov should + have better performance, we'd like to get some + feedback if it's the contrary for you. +orlov (*) Use the Orlov block allocator. + (See http://lwn.net/Articles/14633/ and + http://lwn.net/Articles/14446/.) resuid=n The user ID which may use the reserved blocks. -resgid=n The group ID which may use the reserved blocks. +resgid=n The group ID which may use the reserved blocks. sb=n Use alternate superblock at this location. +user_xattr Enable "user." POSIX Extended Attributes + (requires CONFIG_EXT2_FS_XATTR). + See also http://acl.bestbits.at +nouser_xattr Don't support "user." extended attributes. + +acl Enable POSIX Access Control Lists support + (requires CONFIG_EXT2_FS_POSIX_ACL). + See also http://acl.bestbits.at +noacl Don't support POSIX ACLs. + +nobh Do not attach buffer_heads to file pagecache. + grpquota,noquota,quota,usrquota Quota options are silently ignored by ext2. diff --git a/Documentation/filesystems/ufs.txt b/Documentation/filesystems/ufs.txt index bdedb9fff..2b5a56a6a 100644 --- a/Documentation/filesystems/ufs.txt +++ b/Documentation/filesystems/ufs.txt @@ -15,13 +15,15 @@ ufstype=type_of_ufs ufs manually by mount option ufstype. Possible values are: old old format of ufs - default value, supported os read-only + default value, supported as read-only 44bsd used in FreeBSD, NetBSD, OpenBSD - supported os read-write + supported as read-write + + ufs2 used in FreeBSD 5.x + supported as read-only - ufs2 used in FreeBSD 5.x - supported os read-only + 5xbsd synonym for ufs2 sun used in SunOS (Solaris) supported as read-write @@ -29,6 +31,9 @@ ufstype=type_of_ufs sunx86 used in SunOS for Intel (Solarisx86) supported as read-write + hp used in HP-UX + supported as read-only + nextstep used in NextStep supported as read-only @@ -46,7 +51,7 @@ POSSIBLE PROBLEMS ================= There is still bug in reallocation of fragment, in file fs/ufs/balloc.c, -line 364. But it seem working on current buffer cache configuration. +line 364. But it seems working on current buffer cache configuration. BUG REPORTS diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt index 5be10c915..3f318dd44 100644 --- a/Documentation/filesystems/vfs.txt +++ b/Documentation/filesystems/vfs.txt @@ -44,7 +44,7 @@ Opening a File The VFS implements the open(2), stat(2), chmod(2) and similar system calls. The pathname argument is used by the VFS to search through the directory entry cache (dentry cache or "dcache"). This provides a very -fast lookup mechanism to translate a pathname (filename) into a +fast look-up mechanism to translate a pathname (filename) into a specific dentry. An individual dentry usually has a pointer to an inode. Inodes are the @@ -64,7 +64,7 @@ resolve your pathname into a dentry, the VFS may have to resort to creating dentries along the way, and then loading the inode. This is done by looking up the inode. -To lookup an inode (usually read from disc) requires that the VFS +To look up an inode (usually read from disc) requires that the VFS calls the lookup() method of the parent directory inode. This method is installed by the specific filesystem implementation that the inode lives in. There will be more on this later. @@ -286,7 +286,7 @@ otherwise noted. dentry). Here you will probably call d_instantiate() with the dentry and the newly created inode - lookup: called when the VFS needs to lookup an inode in a parent + lookup: called when the VFS needs to look up an inode in a parent directory. The name to look for is found in the dentry. This method must call d_add() to insert the found inode into the dentry. The "i_count" field in the inode structure should be @@ -405,7 +405,10 @@ from device node to device driver (this is an unofficial kernel patch). -struct dentry_operations
+Directory Entry Cache (dcache)
+------------------------------ + +struct dentry_operations ======================== This describes how a filesystem can overload the standard dentry @@ -425,7 +428,7 @@ struct dentry_operations { }; d_revalidate: called when the VFS needs to revalidate a dentry. This - is called whenever a name lookup finds a dentry in the + is called whenever a name look-up finds a dentry in the dcache. Most filesystems leave this as NULL, because all their dentries in the dcache are valid @@ -448,6 +451,9 @@ Each dentry has a pointer to its parent dentry, as well as a hash list of child dentries. Child dentries are basically like files in a directory. +Directory Entry Cache APIs +-------------------------- + There are a number of functions defined which permit a filesystem to manipulate dentries: @@ -482,3 +488,184 @@ manipulate dentries: pointer is NULL, the dentry is called a "negative dentry". This function is commonly called when an inode is created for an existing negative dentry + + d_lookup: look up a dentry given its parent and path name component + It looks up the child of that given name from the dcache + hash table. If it is found, the reference count is incremented + and the dentry is returned. The caller must use d_put() + to free the dentry when it finishes using it. + + +RCU-based dcache locking model +------------------------------ + +On many workloads, the most common operation on dcache is +to look up a dentry, given a parent dentry and the name +of the child. Typically, for every open(), stat() etc., +the dentry corresponding to the pathname will be looked +up by walking the tree starting with the first component +of the pathname and using that dentry along with the next +component to look up the next level and so on. Since it +is a frequent operation for workloads like multiuser +environments and webservers, it is important to optimize +this path. + +Prior to 2.5.10, dcache_lock was acquired in d_lookup and thus +in every component during path look-up. Since 2.5.10 onwards, +fastwalk algorithm changed this by holding the dcache_lock +at the beginning and walking as many cached path component +dentries as possible. This signficantly decreases the number +of acquisition of dcache_lock. However it also increases the +lock hold time signficantly and affects performance in large +SMP machines. Since 2.5.62 kernel, dcache has been using +a new locking model that uses RCU to make dcache look-up +lock-free. + +The current dcache locking model is not very different from the existing +dcache locking model. Prior to 2.5.62 kernel, dcache_lock +protected the hash chain, d_child, d_alias, d_lru lists as well +as d_inode and several other things like mount look-up. RCU-based +changes affect only the way the hash chain is protected. For everything +else the dcache_lock must be taken for both traversing as well as +updating. The hash chain updations too take the dcache_lock. +The significant change is the way d_lookup traverses the hash chain, +it doesn't acquire the dcache_lock for this and rely on RCU to +ensure that the dentry has not been *freed*. + + +Dcache locking details +---------------------- +For many multi-user workloads, open() and stat() on files are +very frequently occurring operations. Both involve walking +of path names to find the dentry corresponding to the +concerned file. In 2.4 kernel, dcache_lock was held +during look-up of each path component. Contention and +cacheline bouncing of this global lock caused significant +scalability problems. With the introduction of RCU +in linux kernel, this was worked around by making +the look-up of path components during path walking lock-free. + + +Safe lock-free look-up of dcache hash table +=========================================== + +Dcache is a complex data structure with the hash table entries +also linked together in other lists. In 2.4 kernel, dcache_lock +protected all the lists. We applied RCU only on hash chain +walking. The rest of the lists are still protected by dcache_lock. +Some of the important changes are : + +1. The deletion from hash chain is done using hlist_del_rcu() macro which + doesn't initialize next pointer of the deleted dentry and this + allows us to walk safely lock-free while a deletion is happening. + +2. Insertion of a dentry into the hash table is done using + hlist_add_head_rcu() which take care of ordering the writes - + the writes to the dentry must be visible before the dentry + is inserted. This works in conjuction with hlist_for_each_rcu() + while walking the hash chain. The only requirement is that + all initialization to the dentry must be done before hlist_add_head_rcu() + since we don't have dcache_lock protection while traversing + the hash chain. This isn't different from the existing code. + +3. The dentry looked up without holding dcache_lock by cannot be + returned for walking if it is unhashed. It then may have a NULL + d_inode or other bogosity since RCU doesn't protect the other + fields in the dentry. We therefore use a flag DCACHE_UNHASHED to + indicate unhashed dentries and use this in conjunction with a + per-dentry lock (d_lock). Once looked up without the dcache_lock, + we acquire the per-dentry lock (d_lock) and check if the + dentry is unhashed. If so, the look-up is failed. If not, the + reference count of the dentry is increased and the dentry is returned. + +4. Once a dentry is looked up, it must be ensured during the path + walk for that component it doesn't go away. In pre-2.5.10 code, + this was done holding a reference to the dentry. dcache_rcu does + the same. In some sense, dcache_rcu path walking looks like + the pre-2.5.10 version. + +5. All dentry hash chain updations must take the dcache_lock as well as + the per-dentry lock in that order. dput() does this to ensure + that a dentry that has just been looked up in another CPU + doesn't get deleted before dget() can be done on it. + +6. There are several ways to do reference counting of RCU protected + objects. One such example is in ipv4 route cache where + deferred freeing (using call_rcu()) is done as soon as + the reference count goes to zero. This cannot be done in + the case of dentries because tearing down of dentries + require blocking (dentry_iput()) which isn't supported from + RCU callbacks. Instead, tearing down of dentries happen + synchronously in dput(), but actual freeing happens later + when RCU grace period is over. This allows safe lock-free + walking of the hash chains, but a matched dentry may have + been partially torn down. The checking of DCACHE_UNHASHED + flag with d_lock held detects such dentries and prevents + them from being returned from look-up. + + +Maintaining POSIX rename semantics +================================== + +Since look-up of dentries is lock-free, it can race against +a concurrent rename operation. For example, during rename +of file A to B, look-up of either A or B must succeed. +So, if look-up of B happens after A has been removed from the +hash chain but not added to the new hash chain, it may fail. +Also, a comparison while the name is being written concurrently +by a rename may result in false positive matches violating +rename semantics. Issues related to race with rename are +handled as described below : + +1. Look-up can be done in two ways - d_lookup() which is safe + from simultaneous renames and __d_lookup() which is not. + If __d_lookup() fails, it must be followed up by a d_lookup() + to correctly determine whether a dentry is in the hash table + or not. d_lookup() protects look-ups using a sequence + lock (rename_lock). + +2. The name associated with a dentry (d_name) may be changed if + a rename is allowed to happen simultaneously. To avoid memcmp() + in __d_lookup() go out of bounds due to a rename and false + positive comparison, the name comparison is done while holding the + per-dentry lock. This prevents concurrent renames during this + operation. + +3. Hash table walking during look-up may move to a different bucket as + the current dentry is moved to a different bucket due to rename. + But we use hlists in dcache hash table and they are null-terminated. + So, even if a dentry moves to a different bucket, hash chain + walk will terminate. [with a list_head list, it may not since + termination is when the list_head in the original bucket is reached]. + Since we redo the d_parent check and compare name while holding + d_lock, lock-free look-up will not race against d_move(). + +4. There can be a theoritical race when a dentry keeps coming back + to original bucket due to double moves. Due to this look-up may + consider that it has never moved and can end up in a infinite loop. + But this is not any worse that theoritical livelocks we already + have in the kernel. + + +Important guidelines for filesystem developers related to dcache_rcu +==================================================================== + +1. Existing dcache interfaces (pre-2.5.62) exported to filesystem + don't change. Only dcache internal implementation changes. However + filesystems *must not* delete from the dentry hash chains directly + using the list macros like allowed earlier. They must use dcache + APIs like d_drop() or __d_drop() depending on the situation. + +2. d_flags is now protected by a per-dentry lock (d_lock). All + access to d_flags must be protected by it. + +3. For a hashed dentry, checking of d_count needs to be protected + by d_lock. + + +Papers and other documentation on dcache locking +================================================ + +1. Scaling dcache with RCU (http://linuxjournal.com/article.php?sid=7124). + +2. http://lse.sourceforge.net/locking/dcache/dcache.html diff --git a/Documentation/floppy.txt b/Documentation/floppy.txt index 99d3ad3b3..6fb10fcd8 100644 --- a/Documentation/floppy.txt +++ b/Documentation/floppy.txt @@ -13,15 +13,20 @@ LILO configuration options (Thinkpad users, read this) The floppy driver is configured using the 'floppy=' option in lilo. This option can be typed at the boot prompt, or entered in the lilo configuration file. - Example: If your kernel is called linux-2.2.13, type the following line + + Example: If your kernel is called linux-2.6.9, type the following line at the lilo boot prompt (if you have a thinkpad): - linux-2.2.13 floppy=thinkpad + + linux-2.6.9 floppy=thinkpad + You may also enter the following line in /etc/lilo.conf, in the description -of linux-2.2.13: +of linux-2.6.9: + append = "floppy=thinkpad" Several floppy related options may be given, example: - linux-2.2.13 floppy=daring floppy=two_fdc + + linux-2.6.9 floppy=daring floppy=two_fdc append = "floppy=daring floppy=two_fdc" If you give options both in the lilo config file and on the boot @@ -29,17 +34,25 @@ prompt, the option strings of both places are concatenated, the boot prompt options coming last. That's why there are also options to restore the default behavior. + +Module configuration options +============================ + If you use the floppy driver as a module, use the following syntax: - insmod floppy +modprobe floppy Example: - insmod floppy daring two_fdc + modprobe floppy omnibook messages + + If you need certain options enabled every time you load the floppy driver, +you can put: + + options floppy omnibook messages + +in /etc/modprobe.conf. - Some versions of insmod are buggy in one way or another. If you have -any problems (options not being passed correctly, segfaults during -insmod), first check whether there is a more recent version. - The floppy related options include: + The floppy driver related options are: floppy=asus_pci Sets the bit mask to allow only units 0 and 1. (default) @@ -99,7 +112,7 @@ insmod), first check whether there is a more recent version. master arbitration error" messages from your Ethernet card (or from other devices) while accessing the floppy. - floppy=fifo + floppy=usefifo Enables the FIFO. (default) floppy=,fifo_depth @@ -110,6 +123,7 @@ insmod), first check whether there is a more recent version. lower, the interrupt latency should be lower too (faster processor). The benefit of a lower threshold is less interrupts. + To tune the fifo threshold, switch on over/underrun messages using 'floppycontrol --messages'. Then access a floppy disk. If you get a huge amount of "Over/Underrun - retrying" @@ -120,6 +134,7 @@ insmod), first check whether there is a more recent version. fifo values without rebooting the machine for each test. Note that you need to do 'floppycontrol --messages' every time you re-insert the module. + Usually, tuning the fifo threshold should not be needed, as the default (0xa) is reasonable. @@ -128,6 +143,7 @@ insmod), first check whether there is a more recent version. you have more than two floppy drives (only two can be described in the physical CMOS), or if your BIOS uses non-standard CMOS types. The CMOS types are: + 0 - Use the value of the physical CMOS 1 - 5 1/4 DD 2 - 5 1/4 HD @@ -136,6 +152,7 @@ insmod), first check whether there is a more recent version. 5 - 3 1/2 ED 6 - 3 1/2 ED 16 - unknown or not installed + (Note: there are two valid types for ED drives. This is because 5 was initially chosen to represent floppy *tapes*, and 6 for ED drives. AMI ignored this, and used 5 for ED drives. That's why the floppy @@ -188,7 +205,6 @@ insmod), first check whether there is a more recent version. in some more extreme cases." - Supporting utilities and additional documentation: ================================================== @@ -219,3 +235,11 @@ sure to mention also the type of the filesystem in the subject line. Be sure to read the FAQ before mailing/posting any bug reports! Alain + +Changelog +========= + +10-30-2004 : Cleanup, updating, add reference to module configuration. + James Nelson + +6-3-2000 : Original Document diff --git a/Documentation/ftape.txt b/Documentation/ftape.txt index 9cc814a55..7d8bb3384 100644 --- a/Documentation/ftape.txt +++ b/Documentation/ftape.txt @@ -2,26 +2,21 @@ Intro ===== This file describes some issues involved when using the "ftape" -floppy tape device driver that comes with the Linux kernel. This -document deals with ftape-3.04 and later. Please read the section -"Changes" for the most striking differences between version 3.04 and -2.08; the latter was the version of ftape delivered with the kernel -until kernel version 2.0.30 and 2.1.57. ftape-3.x developed as the -re-unification of ftape-2.x and zftape. zftape was developed in -parallel with the stock ftape-2.x driver sharing the same hardware -support but providing an enhanced file system interface. zftape also -provided user transparent block-wise on-the-fly compression (regard it -as a feature or bug of zftape). +floppy tape device driver that comes with the Linux kernel. ftape has a home page at -http://www-math.math.rwth-aachen.de/~LBFM/claus/ftape +http://ftape.dot-heine.de/ which contains further information about ftape. Please cross check this WWW address against the address given (if any) in the MAINTAINERS file located in the top level directory of the Linux kernel source tree. +NOTE: This is an unmaintained set of drivers, and it is not guaranteed to work. +If you are interested in taking over maintenance, contact Claus-Justus Heine +, the former maintainer. + Contents ======== @@ -31,9 +26,8 @@ A. Changes 1. Goal 2. I/O Block Size 3. Write Access when not at EOD (End Of Data) or BOT (Begin Of Tape) - 4. MTBSF - backspace over file mark and position at its EOT side - 5. Formatting - 6. Interchanging cartridges with other operating systems + 4. Formatting + 5. Interchanging cartridges with other operating systems B. Debugging Output 1. Introduction @@ -58,7 +52,7 @@ changed. Up to date documentation as well as recent development versions of ftape and useful links to related topics can be found at the ftape home page at -http://www-math.math.rwth-aachen.de/~LBFM/claus/ftape +http://ftape.dot-heine.de/ ******************************************************************************* @@ -70,7 +64,7 @@ A. Changes The goal of all that incompatibilities was to give ftape an interface that resembles the interface provided by SCSI tape drives as close as possible. Thus any Unix backup program that is known to work - with SCSI tape drives should also work with ftape-3.04 and above. + with SCSI tape drives should also work. The concept of a fixed block size for read/write transfers is rather unrelated to this SCSI tape compatibility at the file system @@ -81,14 +75,8 @@ A. Changes 2. I/O Block Size ~~~~~~~~~~~~~~ - The probably most striking difference between ftape-2.x and - ftape-3.x with the zftape file system interface is the concept of a - fixed block size: data must be written to or read from the tape in - multiples of a fixed block size. The block size defaults to 10k - which is the default block size of GNU tar. While this is quite - usual for SCSI tapes (block size of 32k?) and the QIC-150 driver - `./drivers/char/tpqic02.c' ftape-2.x allowed data to be written in - arbitrary portions to the tape. + The block size defaults to 10k which is the default block size of + GNU tar. The block size can be tuned either during kernel configuration or at runtime with the MTIOCTOP ioctl using the MTSETBLK operation @@ -109,53 +97,41 @@ A. Changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ zftape (the file system interface of ftape-3.x) denies write access to the tape cartridge when it isn't positioned either at BOT or - EOD. This inconvenience has been introduced as it was reported that - the former behavior of ftape-2.x which allowed write access at - arbitrary locations already has caused data loss with some backup - programs. - -4. MTBSF - backspace over file mark and position at its EOT side - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ftape-2.x didn't handle the MTBSF tape operation correctly. A MTBSF - call (i.e. "mt -f /dev/nqft0 bsf #COUNT") should space over #COUNT - file marks and then position at the EOT tape side of the file - mark. This has to be taken literally, i.e. "mt -f /dev/nqft0 bsf 1" - should simply position at the start of the current volume. - -5. Formatting + EOD. + +4. Formatting ~~~~~~~~~~ - ftape-3.x DOES support formatting of floppy tape cartridges. You - need the `ftformat' program that is shipped with the modules version - of ftape-3.x. Please get the latest version of ftape from + ftape DOES support formatting of floppy tape cartridges. You need the + `ftformat' program that is shipped with the modules version of ftape. + Please get the latest version of ftape from ftp://sunsite.unc.edu/pub/Linux/kernel/tapes or from the ftape home page at - http://www-math.math.rwth-aachen.de/~LBFM/claus/ftape + http://ftape.dot-heine.de/ `ftformat' is contained in the `./contrib/' subdirectory of that separate ftape package. -6. Interchanging cartridges with other operating systems +5. Interchanging cartridges with other operating systems ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The internal emulation of Unix tape device file marks has changed - completely. ftape-3.x now uses the volume table segment as specified + completely. ftape now uses the volume table segment as specified by the QIC-40/80/3010/3020/113 standards to emulate file marks. As a consequence there is limited support to interchange cartridges with other operating systems. To be more precise: ftape will detect volumes written by other OS's programs and other OS's programs will detect volumes written by - ftape-3.x. + ftape. However, it isn't possible to extract the data dumped to the tape - by some MSDOG program with ftape-3.x. This exceeds the scope of a + by some MSDOS program with ftape. This exceeds the scope of a kernel device driver. If you need such functionality, then go ahead - and write a user space utility that is able to do - that. ftape-3.x/zftape already provides all kernel level support - necessary to do that. + and write a user space utility that is able to do that. ftape already + provides all kernel level support necessary to do that. ******************************************************************************* @@ -200,7 +176,7 @@ B. Debugging Output ii) trim the debugging output at module load time with - insmod ftape.o ft_tracing=#DBGLVL + modprobe ftape ft_tracing=#DBGLVL Of course, this applies only if you have configured ftape to be compiled as a module. @@ -240,7 +216,7 @@ C. Boot and load time configuration 2. Module load time parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Module parameters can be specified either directly when invoking - the program 'insmod' at the shell prompt: + the program 'modprobe' at the shell prompt: modprobe ftape ft_tracing=4 @@ -277,6 +253,12 @@ C. Boot and load time configuration line documentation provided during that kernel configuration process. + ft_probe_fc10 is set to a non-zero value if you wish for ftape to + probe for a Colorado FC-10 or FC-20 controller. + + ft_mach2 is set to a non-zero value if you wish for ftape to probe + for a Mountain MACH-2 controller. + module | kernel command line -----------------------|---------------------- ft_fdc_base=BASE | ftape=BASE,ioport @@ -316,10 +298,10 @@ D. Support and contacts page to query for the most recent documentation, related work and development versions of ftape. + Changelog: + ========== + +~1996: Original Document - LocalWords: ftape Linux zftape http www rwth aachen LBFM claus EOD config - LocalWords: datarate LocalWords BOT MTBSF EOT HOWTO QIC tpqic menuconfig - LocalWords: MTIOCTOP MTSETBLK mt dev qft setblk BLKSZ bsf zftape's xconfig - LocalWords: nqft ftformat ftp sunsite unc edu contrib ft MSDOG fdc - LocalWords: dma setdensity DBGLVL insmod lilo LI nux ader conf txt - LocalWords: modprobe IRQ BOOL ioport irq fc mach THR +10-24-2004: General cleanup and updating, noting additional module options. + James Nelson diff --git a/Documentation/hw_random.txt b/Documentation/hw_random.txt index 20be482b6..bb58c36b5 100644 --- a/Documentation/hw_random.txt +++ b/Documentation/hw_random.txt @@ -67,72 +67,3 @@ Driver details: Special thanks to Matt Sottek. I did the "guts", he did the "brains" and all the testing. - -Change history: - - Version 1.0.0: - * Merge Intel, AMD, VIA RNG drivers into one. - Further changelog in BitKeeper. - - Version 0.9.8: - * Support other i8xx chipsets by adding 82801E detection - * 82801DB detection is the same as for 82801CA. - - Version 0.9.7: - * Support other i8xx chipsets too (by adding 82801BA(M) and - 82801CA(M) detection) - - Version 0.9.6: - * Internal driver cleanups, prep for 1.0.0 release. - - Version 0.9.5: - * Rip out entropy injection via timer. It never ever worked, - and a better solution (rngd) is now available. - - Version 0.9.4: - * Fix: Remove request_mem_region - * Fix: Horrible bugs in FIPS calculation and test execution - - Version 0.9.3: - * Clean up rng_read a bit. - * Update i810_rng driver Web site URL. - * Increase default timer interval to 4 samples per second. - * Abort if mem region is not available. - * BSS zero-initialization cleanup. - * Call misc_register() from rng_init_one. - * Fix O_NONBLOCK to occur before we schedule. - - Version 0.9.2: - * Simplify open blocking logic - - Version 0.9.1: - * Support i815 chipsets too (Matt Sottek) - * Fix reference counting when statically compiled (prumpf) - * Rewrite rng_dev_read (prumpf) - * Make module races less likely (prumpf) - * Small miscellaneous bug fixes (prumpf) - * Use pci table for PCI id list - - Version 0.9.0: - * Don't register a pci_driver, because we are really - using PCI bridge vendor/device ids, and someone - may want to register a driver for the bridge. (bug fix) - * Don't let the usage count go negative (bug fix) - * Clean up spinlocks (bug fix) - * Enable PCI device, if necessary (bug fix) - * iounmap on module unload (bug fix) - * If RNG chrdev is already in use when open(2) is called, - sleep until it is available. - * Remove redundant globals rng_allocated, rng_use_count - * Convert numeric globals to unsigned - * Module unload cleanup - - Version 0.6.2: - * Clean up spinlocks. Since we don't have any interrupts - to worry about, but we do have a timer to worry about, - we use spin_lock_bh everywhere except the timer function - itself. - * Fix module load/unload. - * Fix timer function and h/w enable/disable logic - * New timer interval sysctl - * Clean up sysctl names diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface index 4fe882cb4..09d6cda2a 100644 --- a/Documentation/i2c/dev-interface +++ b/Documentation/i2c/dev-interface @@ -3,7 +3,7 @@ possible to access all devices on an adapter from userspace, through the /dev interface. You need to load module i2c-dev for this. Each registered i2c adapter gets a number, counting from 0. You can -examine /proc/bus/i2c to see what number corresponds to which adapter. +examine /sys/class/i2c-dev/ to see what number corresponds to which adapter. I2C device files are character device files with major device number 89 and a minor device number corresponding to the number assigned as explained above. They should be called "i2c-%d" (i2c-0, i2c-1, ..., @@ -19,7 +19,7 @@ Yes, I know, you should never include kernel header files, but until glibc knows about i2c, there is not much choice. Now, you have to decide which adapter you want to access. You should -inspect /proc/bus/i2c to decide this. Adapter numbers are assigned +inspect /sys/class/i2c-dev/ to decide this. Adapter numbers are assigned somewhat dynamically, so you can not even assume /dev/i2c-0 is the first adapter. diff --git a/Documentation/i2c/i2c-stub b/Documentation/i2c/i2c-stub new file mode 100644 index 000000000..2626ba926 --- /dev/null +++ b/Documentation/i2c/i2c-stub @@ -0,0 +1,33 @@ +MODULE: i2c-stub + +DESCRIPTION: + +This module is a very simple fake I2C/SMBus driver. It implements three +types of SMBus commands: write quick, (r/w) byte data, and (r/w) word data. + +No hardware is needed nor associated with this module. It will accept write +quick commands to all addresses; it will respond to the other commands (also +to all addresses) by reading from or writing to an array in memory. It will +also spam the kernel logs for every command it handles. + +The typical use-case is like this: + 1. load this module + 2. use i2cset (from lm_sensors project) to pre-load some data + 3. load the target sensors chip driver module + 4. observe its behavior in the kernel log + +CAVEATS: + +There are independent arrays for byte/data and word/data commands. Depending +on if/how a target driver mixes them, you'll need to be careful. + +If your target driver polls some byte or word waiting for it to change, the +stub could lock it up. Use i2cset to unlock it. + +If the hardware for your driver has banked registers (e.g. Winbond sensors +chips) this module will not work well - although it could be extended to +support that pretty easily. + +If you spam it hard enough, printk can be lossy. This module really wants +something like relayfs. + diff --git a/Documentation/i2c/sysfs-interface b/Documentation/i2c/sysfs-interface index 3e74daeb9..346400519 100644 --- a/Documentation/i2c/sysfs-interface +++ b/Documentation/i2c/sysfs-interface @@ -135,18 +135,44 @@ fan[1-3]_div Fan divisor. Note that this is actually an internal clock divisor, which affects the measurable speed range, not the read value. -fan[1-3]_pwm Pulse width modulation fan control. +******* +* PWM * +******* + +pwm[1-3] Pulse width modulation fan control. Integer value in the range 0 to 255 Read/Write 255 is max or 100%. -fan[1-3]_pwm_enable +pwm[1-3]_enable Switch PWM on and off. Not always present even if fan*_pwm is. 0 to turn off - 1 to turn on + 1 to turn on in manual mode + 2 to turn on in automatic mode Read/Write +pwm[1-*]_auto_channels_temp + Select which temperature channels affect this PWM output in + auto mode. Bitfield, 1 is temp1, 2 is temp2, 4 is temp3 etc... + Which values are possible depend on the chip used. + +pwm[1-*]_auto_point[1-*]_pwm +pwm[1-*]_auto_point[1-*]_temp +pwm[1-*]_auto_point[1-*]_temp_hyst + Define the PWM vs temperature curve. Number of trip points is + chip-dependent. Use this for chips which associate trip points + to PWM output channels. + +OR + +temp[1-*]_auto_point[1-*]_pwm +temp[1-*]_auto_point[1-*]_temp +temp[1-*]_auto_point[1-*]_temp_hyst + Define the PWM vs temperature curve. Number of trip points is + chip-dependent. Use this for chips which associate trip points + to temperature channels. + **************** * Temperatures * diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients index a45421284..011e92094 100644 --- a/Documentation/i2c/writing-clients +++ b/Documentation/i2c/writing-clients @@ -24,22 +24,24 @@ all clients from it. Remember, a driver structure contains general access routines, a client structure specific information like the actual I2C address. - static struct i2c_driver foo_driver = { - .owner = THIS_MODULE, - .name = "Foo version 2.3 driver", - .id = I2C_DRIVERID_FOO, /* usually from i2c-id.h */ - .flags = I2C_DF_NOTIFY, - .attach_adapter = &foo_attach_adapter, - .detach_client = &foo_detach_client, - .command = &foo_command /* may be NULL */ - } +static struct i2c_driver foo_driver = { + .owner = THIS_MODULE, + .name = "Foo version 2.3 driver", + .id = I2C_DRIVERID_FOO, /* from i2c-id.h, optional */ + .flags = I2C_DF_NOTIFY, + .attach_adapter = &foo_attach_adapter, + .detach_client = &foo_detach_client, + .command = &foo_command /* may be NULL */ +} The name can be chosen freely, and may be upto 40 characters long. Please use something descriptive here. -The id should be a unique ID. The range 0xf000 to 0xffff is reserved for -local use, and you can use one of those until you start distributing the -driver. Before you do that, contact the i2c authors to get your own ID(s). +If used, the id should be a unique ID. The range 0xf000 to 0xffff is +reserved for local use, and you can use one of those until you start +distributing the driver, at which time you should contact the i2c authors +to get your own ID(s). Note that most of the time you don't need an ID +at all so you can just omit it. Don't worry about the flags field; just put I2C_DF_NOTIFY into it. This means that your driver will be notified when new adapters are found. @@ -569,7 +571,7 @@ the driver module is usually enough. have to be cleaned up! */ static int __initdata foo_initialized = 0; - int __init foo_init(void) + static int __init foo_init(void) { int res; printk("foo version %s (%s)\n",FOO_VERSION,FOO_DATE); @@ -583,41 +585,27 @@ the driver module is usually enough. return 0; } - int __init foo_cleanup(void) + void foo_cleanup(void) { - int res; if (foo_initialized == 1) { if ((res = i2c_del_driver(&foo_driver))) { printk("foo: Driver registration failed, module not removed.\n"); - return res; + return; } foo_initialized --; } - return 0; } - #ifdef MODULE - /* Substitute your own name and email address */ MODULE_AUTHOR("Frodo Looijaard " MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices"); - int init_module(void) - { - return foo_init(); - } - - int cleanup_module(void) - { - return foo_cleanup(); - } - - #endif /* def MODULE */ + module_init(foo_init); + module_exit(foo_cleanup); Note that some functions are marked by `__init', and some data structures -by `__init_data'. If this driver is compiled as part of the kernel (instead -of as a module), those functions and structures can be removed after -kernel booting is completed. +by `__init_data'. Hose functions and structures can be removed after +kernel booting (or module loading) is completed. Command function ================ @@ -688,14 +676,26 @@ SMBus communication extern s32 i2c_smbus_read_word_data(struct i2c_client * client, u8 command); extern s32 i2c_smbus_write_word_data(struct i2c_client * client, u8 command, u16 value); - extern s32 i2c_smbus_process_call(struct i2c_client * client, - u8 command, u16 value); - extern s32 i2c_smbus_read_block_data(struct i2c_client * client, - u8 command, u8 *values); extern s32 i2c_smbus_write_block_data(struct i2c_client * client, u8 command, u8 length, u8 *values); +These ones were removed in Linux 2.6.10 because they had no users, but could +be added back later if needed: + + extern s32 i2c_smbus_read_i2c_block_data(struct i2c_client * client, + u8 command, u8 *values); + extern s32 i2c_smbus_read_block_data(struct i2c_client * client, + u8 command, u8 *values); + extern s32 i2c_smbus_write_i2c_block_data(struct i2c_client * client, + u8 command, u8 length, + u8 *values); + extern s32 i2c_smbus_process_call(struct i2c_client * client, + u8 command, u16 value); + extern s32 i2c_smbus_block_process_call(struct i2c_client *client, + u8 command, u8 length, + u8 *values) + All these transactions return -1 on failure. The 'write' transactions return 0 on success; the 'read' transactions return the read value, except for read_block, which returns the number of values read. The block buffers diff --git a/Documentation/ia64/serial.txt b/Documentation/ia64/serial.txt new file mode 100644 index 000000000..f51eb4bc2 --- /dev/null +++ b/Documentation/ia64/serial.txt @@ -0,0 +1,144 @@ +SERIAL DEVICE NAMING + + As of 2.6.10, serial devices on ia64 are named based on the + order of ACPI and PCI enumeration. The first device in the + ACPI namespace (if any) becomes /dev/ttyS0, the second becomes + /dev/ttyS1, etc., and PCI devices are named sequentially + starting after the ACPI devices. + + Prior to 2.6.10, there were confusing exceptions to this: + + - Firmware on some machines (mostly from HP) provides an HCDP + table[1] that tells the kernel about devices that can be used + as a serial console. If the user specified "console=ttyS0" + or the EFI ConOut path contained only UART devices, the + kernel registered the device described by the HCDP as + /dev/ttyS0. + + - If there was no HCDP, we assumed there were UARTs at the + legacy COM port addresses (I/O ports 0x3f8 and 0x2f8), so + the kernel registered those as /dev/ttyS0 and /dev/ttyS1. + + Any additional ACPI or PCI devices were registered sequentially + after /dev/ttyS0 as they were discovered. + + With an HCDP, device names changed depending on EFI configuration + and "console=" arguments. Without an HCDP, device names didn't + change, but we registered devices that might not really exist. + + For example, an HP rx1600 with a single built-in serial port + (described in the ACPI namespace) plus an MP[2] (a PCI device) has + these ports: + + pre-2.6.10 pre-2.6.10 + MMIO (EFI console (EFI console + address on builtin) on MP port) 2.6.10 + ========== ========== ========== ====== + builtin 0xff5e0000 ttyS0 ttyS1 ttyS0 + MP UPS 0xf8031000 ttyS1 ttyS2 ttyS1 + MP Console 0xf8030000 ttyS2 ttyS0 ttyS2 + MP 2 0xf8030010 ttyS3 ttyS3 ttyS3 + MP 3 0xf8030038 ttyS4 ttyS4 ttyS4 + +CONSOLE SELECTION + + EFI knows what your console devices are, but it doesn't tell the + kernel quite enough to actually locate them. The DIG64 HCDP + table[1] does tell the kernel where potential serial console + devices are, but not all firmware supplies it. Also, EFI supports + multiple simultaneous consoles and doesn't tell the kernel which + should be the "primary" one. + + So how do you tell Linux which console device to use? + + - If your firmware supplies the HCDP, it is simplest to + configure EFI with a single device (either a UART or a VGA + card) as the console. Then you don't need to tell Linux + anything; the kernel will automatically use the EFI console. + + (This works only in 2.6.6 or later; prior to that you had + to specify "console=ttyS0" to get a serial console.) + + - Without an HCDP, Linux defaults to a VGA console unless you + specify a "console=" argument. + + NOTE: Don't assume that a serial console device will be /dev/ttyS0. + It might be ttyS1, ttyS2, etc. Make sure you have the appropriate + entries in /etc/inittab (for getty) and /etc/securetty (to allow + root login). + +EARLY SERIAL CONSOLE + + The kernel can't start using a serial console until it knows where + the device lives. Normally this happens when the driver enumerates + all the serial devices, which can happen a minute or more after the + kernel starts booting. + + 2.6.10 and later kernels have an "early uart" driver that works + very early in the boot process. The kernel will automatically use + this if the user supplies an argument like "console=uart,io,0x3f8", + or if the EFI console path contains only a UART device and the + firmware supplies an HCDP. + +TROUBLESHOOTING SERIAL CONSOLE PROBLEMS + + No kernel output after elilo prints "Uncompressing Linux... done": + + - You specified "console=ttyS0" but Linux changed the device + to which ttyS0 refers. Configure exactly one EFI console + device[3] and remove the "console=" option. + + - The EFI console path contains both a VGA device and a UART. + EFI and elilo use both, but Linux defaults to VGA. Remove + the VGA device from the EFI console path[3]. + + - Multiple UARTs selected as EFI console devices. EFI and + elilo use all selected devices, but Linux uses only one. + Make sure only one UART is selected in the EFI console + path[3]. + + - You're connected to an HP MP port[2] but have a non-MP UART + selected as EFI console device. EFI uses the MP as a + console device even when it isn't explicitly selected. + Either move the console cable to the non-MP UART, or change + the EFI console path[3] to the MP UART. + + Long pause (60+ seconds) between "Uncompressing Linux... done" and + start of kernel output: + + - No early console because you used "console=ttyS". Remove + the "console=" option if your firmware supplies an HCDP. + + - If you don't have an HCDP, the kernel doesn't know where + your console lives until the driver discovers serial + devices. Use "console=uart, io,0x3f8" (or appropriate + address for your machine). + + Kernel and init script output works fine, but no "login:" prompt: + + - Add getty entry to /etc/inittab for console tty. Look for + the "Adding console on ttyS" message that tells you which + device is the console. + + "login:" prompt, but can't login as root: + + - Add entry to /etc/securetty for console tty. + + + +[1] http://www.dig64.org/specifications/DIG64_PCDPv20.pdf + The table was originally defined as the "HCDP" for "Headless + Console/Debug Port." The current version is the "PCDP" for + "Primary Console and Debug Port Devices." + +[2] The HP MP (management processor) is a PCI device that provides + several UARTs. One of the UARTs is often used as a console; the + EFI Boot Manager identifies it as "Acpi(HWP0002,700)/Pci(...)/Uart". + The external connection is usually a 25-pin connector, and a + special dongle converts that to three 9-pin connectors, one of + which is labelled "Console." + +[3] EFI console devices are configured using the EFI Boot Manager + "Boot option maintenance" menu. You may have to interrupt the + boot sequence to use this menu, and you will have to reset the + box after changing console configuration. diff --git a/Documentation/ibm-acpi.txt b/Documentation/ibm-acpi.txt new file mode 100644 index 000000000..c437b1aef --- /dev/null +++ b/Documentation/ibm-acpi.txt @@ -0,0 +1,474 @@ + IBM ThinkPad ACPI Extras Driver + + Version 0.8 + 8 November 2004 + + Borislav Deianov + http://ibm-acpi.sf.net/ + + +This is a Linux ACPI driver for the IBM ThinkPad laptops. It aims to +support various features of these laptops which are accessible through +the ACPI framework but not otherwise supported by the generic Linux +ACPI drivers. + + +Status +------ + +The features currently supported are the following (see below for +detailed description): + + - Fn key combinations + - Bluetooth enable and disable + - video output switching, expansion control + - ThinkLight on and off + - limited docking and undocking + - UltraBay eject + - Experimental: CMOS control + - Experimental: LED control + - Experimental: ACPI sounds + +A compatibility table by model and feature is maintained on the web +site, http://ibm-acpi.sf.net/. I appreciate any success or failure +reports, especially if they add to or correct the compatibility table. +Please include the following information in your report: + + - ThinkPad model name + - a copy of your DSDT, from /proc/acpi/dsdt + - which driver features work and which don't + - the observed behavior of non-working features + +Any other comments or patches are also more than welcome. + + +Installation +------------ + +If you are compiling this driver as included in the Linux kernel +sources, simply enable the CONFIG_ACPI_IBM option (Power Management / +ACPI / IBM ThinkPad Laptop Extras). The rest of this section describes +how to install this driver when downloaded from the web site. + +First, you need to get a kernel with ACPI support up and running. +Please refer to http://acpi.sourceforge.net/ for help with this +step. How successful you will be depends a lot on you ThinkPad model, +the kernel you are using and any additional patches applied. The +kernel provided with your distribution may not be good enough. I +needed to compile a 2.6.7 kernel with the 20040715 ACPI patch to get +ACPI working reliably on my ThinkPad X40. Old ThinkPad models may not +be supported at all. + +Assuming you have the basic ACPI support working (e.g. you can see the +/proc/acpi directory), follow the following steps to install this +driver: + + - unpack the archive: + + tar xzvf ibm-acpi-x.y.tar.gz; cd ibm-acpi-x.y + + - compile the driver: + + make + + - install the module in your kernel modules directory: + + make install + + - load the module: + + modprobe ibm_acpi + +After loading the module, check the "dmesg" output for any error messages. + + +Features +-------- + +The driver creates the /proc/acpi/ibm directory. There is a file under +that directory for each feature described below. Note that while the +driver is still in the alpha stage, the exact proc file format and +commands supported by the various features is guaranteed to change +frequently. + +Driver Version -- /proc/acpi/ibm/driver +-------------------------------------- + +The driver name and version. No commands can be written to this file. + +Hot Keys -- /proc/acpi/ibm/hotkey +--------------------------------- + +Without this driver, only the Fn-F4 key (sleep button) generates an +ACPI event. With the driver loaded, the hotkey feature enabled and the +mask set (see below), the various hot keys generate ACPI events in the +following format: + + ibm/hotkey HKEY 00000080 0000xxxx + +The last four digits vary depending on the key combination pressed. +All labeled Fn-Fx key combinations generate distinct events. In +addition, the lid microswitch and some docking station buttons may +also generate such events. + +The following commands can be written to this file: + + echo enable > /proc/acpi/ibm/hotkey -- enable the hot keys feature + echo disable > /proc/acpi/ibm/hotkey -- disable the hot keys feature + echo 0xffff > /proc/acpi/ibm/hotkey -- enable all possible hot keys + echo 0x0000 > /proc/acpi/ibm/hotkey -- disable all possible hot keys + ... any other 4-hex-digit mask ... + echo reset > /proc/acpi/ibm/hotkey -- restore the original mask + +The bit mask allows some control over which hot keys generate ACPI +events. Not all bits in the mask can be modified. Not all bits that +can be modified do anything. Not all hot keys can be individually +controlled by the mask. Most recent ThinkPad models honor the +following bits (assuming the hot keys feature has been enabled): + + key bit behavior when set behavior when unset + + Fn-F3 always generates ACPI event + Fn-F4 always generates ACPI event + Fn-F5 0010 generate ACPI event enable/disable Bluetooth + Fn-F7 0040 generate ACPI event switch LCD and external display + Fn-F8 0080 generate ACPI event expand screen or none + Fn-F9 0100 generate ACPI event none + Fn-F12 always generates ACPI event + +Some models do not support all of the above. For example, the T30 does +not support Fn-F5 and Fn-F9. Other models do not support the mask at +all. On those models, hot keys cannot be controlled individually. + +Note that enabling ACPI events for some keys prevents their default +behavior. For example, if events for Fn-F5 are enabled, that key will +no longer enable/disable Bluetooth by itself. This can still be done +from an acpid handler for the ibm/hotkey event. + +Note also that not all Fn key combinations are supported through +ACPI. For example, on the X40, the brightness, volume and "Access IBM" +buttons do not generate ACPI events even with this driver. They *can* +be used through the "ThinkPad Buttons" utility, see +http://www.nongnu.org/tpb/ + +Bluetooth -- /proc/acpi/ibm/bluetooth +------------------------------------- + +This feature shows the presence and current state of a Bluetooth +device. If Bluetooth is installed, the following commands can be used: + + echo enable > /proc/acpi/ibm/bluetooth + echo disable > /proc/acpi/ibm/bluetooth + +Video output control -- /proc/acpi/ibm/video +-------------------------------------------- + +This feature allows control over the devices used for video output - +LCD, CRT or DVI (if available). The following commands are available: + + echo lcd_enable > /proc/acpi/ibm/video + echo lcd_disable > /proc/acpi/ibm/video + echo crt_enable > /proc/acpi/ibm/video + echo crt_disable > /proc/acpi/ibm/video + echo dvi_enable > /proc/acpi/ibm/video + echo dvi_disable > /proc/acpi/ibm/video + echo auto_enable > /proc/acpi/ibm/video + echo auto_disable > /proc/acpi/ibm/video + echo expand_toggle > /proc/acpi/ibm/video + echo video_switch > /proc/acpi/ibm/video + +Each video output device can be enabled or disabled individually. +Reading /proc/acpi/ibm/video shows the status of each device. + +Automatic video switching can be enabled or disabled. When automatic +video switching is enabled, certain events (e.g. opening the lid, +docking or undocking) cause the video output device to change +automatically. While this can be useful, it also causes flickering +and, on the X40, video corruption. By disabling automatic switching, +the flickering or video corruption can be avoided. + +The video_switch command cycles through the available video outputs +(it sumulates the behavior of Fn-F7). + +Video expansion can be toggled through this feature. This controls +whether the display is expanded to fill the entire LCD screen when a +mode with less than full resolution is used. Note that the current +video expansion status cannot be determined through this feature. + +Note that on many models (particularly those using Radeon graphics +chips) the X driver configures the video card in a way which prevents +Fn-F7 from working. This also disables the video output switching +features of this driver, as it uses the same ACPI methods as +Fn-F7. Video switching on the console should still work. + +ThinkLight control -- /proc/acpi/ibm/light +------------------------------------------ + +The current status of the ThinkLight can be found in this file. A few +models which do not make the status available will show it as +"unknown". The available commands are: + + echo on > /proc/acpi/ibm/light + echo off > /proc/acpi/ibm/light + +Docking / Undocking -- /proc/acpi/ibm/dock +------------------------------------------ + +Docking and undocking (e.g. with the X4 UltraBase) requires some +actions to be taken by the operating system to safely make or break +the electrical connections with the dock. + +The docking feature of this driver generates the following ACPI events: + + ibm/dock GDCK 00000003 00000001 -- eject request + ibm/dock GDCK 00000003 00000002 -- undocked + ibm/dock GDCK 00000000 00000003 -- docked + +NOTE: These events will only be generated if the laptop was docked +when originally booted. This is due to the current lack of support for +hot plugging of devices in the Linux ACPI framework. If the laptop was +booted while not in the dock, the following message is shown in the +logs: "ibm_acpi: dock device not present". No dock-related events are +generated but the dock and undock commands described below still +work. They can be executed manually or triggered by Fn key +combinations (see the example acpid configuration files included in +the driver tarball package available on the web site). + +When the eject request button on the dock is pressed, the first event +above is generated. The handler for this event should issue the +following command: + + echo undock > /proc/acpi/ibm/dock + +After the LED on the dock goes off, it is safe to eject the laptop. +Note: if you pressed this key by mistake, go ahead and eject the +laptop, then dock it back in. Otherwise, the dock may not function as +expected. + +When the laptop is docked, the third event above is generated. The +handler for this event should issue the following command to fully +enable the dock: + + echo dock > /proc/acpi/ibm/dock + +The contents of the /proc/acpi/ibm/dock file shows the current status +of the dock, as provided by the ACPI framework. + +The docking support in this driver does not take care of enabling or +disabling any other devices you may have attached to the dock. For +example, a CD drive plugged into the UltraBase needs to be disabled or +enabled separately. See the provided example acpid configuration files +for how this can be accomplished. + +There is no support yet for PCI devices that may be attached to a +docking station, e.g. in the ThinkPad Dock II. The driver currently +does not recognize, enable or disable such devices. This means that +the only docking stations currently supported are the X-series +UltraBase docks and "dumb" port replicators like the Mini Dock (the +latter don't need any ACPI support, actually). + +UltraBay Eject -- /proc/acpi/ibm/bay +------------------------------------ + +Inserting or ejecting an UltraBay device requires some actions to be +taken by the operating system to safely make or break the electrical +connections with the device. + +This feature generates the following ACPI events: + + ibm/bay MSTR 00000003 00000000 -- eject request + ibm/bay MSTR 00000001 00000000 -- eject lever inserted + +NOTE: These events will only be generated if the UltraBay was present +when the laptop was originally booted (on the X series, the UltraBay +is in the dock, so it may not be present if the laptop was undocked). +This is due to the current lack of support for hot plugging of devices +in the Linux ACPI framework. If the laptop was booted without the +UltraBay, the following message is shown in the logs: "ibm_acpi: bay +device not present". No bay-related events are generated but the eject +command described below still works. It can be executed manually or +triggered by a hot key combination. + +Sliding the eject lever generates the first event shown above. The +handler for this event should take whatever actions are necessary to +shut down the device in the UltraBay (e.g. call idectl), then issue +the following command: + + echo eject > /proc/acpi/ibm/bay + +After the LED on the UltraBay goes off, it is safe to pull out the +device. + +When the eject lever is inserted, the second event above is +generated. The handler for this event should take whatever actions are +necessary to enable the UltraBay device (e.g. call idectl). + +The contents of the /proc/acpi/ibm/bay file shows the current status +of the UltraBay, as provided by the ACPI framework. + +Experimental Features +--------------------- + +The following features are marked experimental because using them +involves guessing the correct values of some parameters. Guessing +incorrectly may have undesirable effects like crashing your +ThinkPad. USE THESE WITH CAUTION! To activate them, you'll need to +supply the experimental=1 parameter when loading the module. + +Experimental: CMOS control - /proc/acpi/ibm/cmos +------------------------------------------------ + +This feature is used internally by the ACPI firmware to control the +ThinkLight on most newer ThinkPad models. It appears that it can also +control LCD brightness, sounds volume and more, but only on some +models. + +The commands are non-negative integer numbers: + + echo 0 >/proc/acpi/ibm/cmos + echo 1 >/proc/acpi/ibm/cmos + echo 2 >/proc/acpi/ibm/cmos + ... + +The range of numbers which are used internally by various models is 0 +to 21, but it's possible that numbers outside this range have +interesting behavior. Here is the behavior on the X40 (tpb is the +ThinkPad Buttons utility): + + 0 - no effect but tpb reports "Volume down" + 1 - no effect but tpb reports "Volume up" + 2 - no effect but tpb reports "Mute on" + 3 - simulate pressing the "Access IBM" button + 4 - LCD brightness up + 5 - LCD brightness down + 11 - toggle screen expansion + 12 - ThinkLight on + 13 - ThinkLight off + 14 - no effect but tpb reports ThinkLight status change + +If you try this feature, please send me a report similar to the +above. On models which allow control of LCD brightness or sound +volume, I'd like to provide this functionality in an user-friendly +way, but first I need a way to identify the models which this is +possible. + +Experimental: LED control - /proc/acpi/ibm/LED +---------------------------------------------- + +Some of the LED indicators can be controlled through this feature. The +available commands are: + + echo on >/proc/acpi/ibm/led + echo off >/proc/acpi/ibm/led + echo blink >/proc/acpi/ibm/led + +The parameter is a non-negative integer. The range of LED +numbers used internally by various models is 0 to 7 but it's possible +that numbers outside this range are also valid. Here is the mapping on +the X40: + + 0 - power + 1 - battery (orange) + 2 - battery (green) + 3 - UltraBase + 4 - UltraBay + 7 - standby + +All of the above can be turned on and off and can be made to blink. + +If you try this feature, please send me a report similar to the +above. I'd like to provide this functionality in an user-friendly way, +but first I need to identify the which numbers correspond to which +LEDs on various models. + +Experimental: ACPI sounds - /proc/acpi/ibm/beep +----------------------------------------------- + +The BEEP method is used internally by the ACPI firmware to provide +audible alerts in various situtation. This feature allows the same +sounds to be triggered manually. + +The commands are non-negative integer numbers: + + echo 0 >/proc/acpi/ibm/beep + echo 1 >/proc/acpi/ibm/beep + echo 2 >/proc/acpi/ibm/beep + ... + +The range of numbers which are used internally by various models is 0 +to 17, but it's possible that numbers outside this range are also +valid. Here is the behavior on the X40: + + 2 - two beeps, pause, third beep + 3 - single beep + 4 - "unable" + 5 - single beep + 6 - "AC/DC" + 7 - high-pitched beep + 9 - three short beeps + 10 - very long beep + 12 - low-pitched beep + +(I've only been able to identify a couple of them). + +If you try this feature, please send me a report similar to the +above. I'd like to provide this functionality in an user-friendly way, +but first I need to identify the which numbers correspond to which +sounds on various models. + + +Multiple Command, Module Parameters +----------------------------------- + +Multiple commands can be written to the proc files in one shot by +separating them with commas, for example: + + echo enable,0xffff > /proc/acpi/ibm/hotkey + echo lcd_disable,crt_enable > /proc/acpi/ibm/video + +Commands can also be specified when loading the ibm_acpi module, for +example: + + modprobe ibm_acpi hotkey=enable,0xffff video=auto_disable + + +Example Configuration +--------------------- + +The ACPI support in the kernel is intended to be used in conjunction +with a user-space daemon, acpid. The configuration files for this +daemon control what actions are taken in response to various ACPI +events. An example set of configuration files are included in the +config/ directory of the tarball package available on the web +site. Note that these are provided for illustration purposes only and +may need to be adapted to your particular setup. + +The following utility scripts are used by the example action +scripts (included with ibm-acpi for completeness): + + /usr/local/sbin/idectl -- from the hdparm source distribution, + see http://www.ibiblio.org/pub/Linux/system/hardware + /usr/local/sbin/laptop_mode -- from the Linux kernel source + distribution, see Documentation/laptop-mode.txt + /sbin/service -- comes with Redhat/Fedora distributions + +Toan T Nguyen has written a SuSE powersave +script for the X20, included in config/usr/sbin/ibm_hotkeys_X20 + +Henrik Brix Andersen has written a Gentoo ACPI event +handler script for the X31. You can get the latest version from +http://dev.gentoo.org/~brix/files/x31.sh + +David Schweikert has written an alternative blank.sh +script which works on Debian systems, included in +configs/etc/acpi/actions/blank-debian.sh + + +TODO +---- + +I'd like to implement the following features but haven't yet found the +time and/or I don't yet know how to implement them: + +- UltraBay floppy drive support + diff --git a/Documentation/ide.txt b/Documentation/ide.txt index 58853a4ef..12c7a2fd6 100644 --- a/Documentation/ide.txt +++ b/Documentation/ide.txt @@ -248,13 +248,6 @@ Summary of ide driver parameters for kernel command line allowing ide-floppy, ide-tape, and ide-cdrom|writers to use ide-scsi emulation on a device specific option. - "hdx=stroke" : Should you have a system w/ an AWARD Bios and your - drives are larger than 32GB and it will not boot, - one is required to perform a few OEM operations first. - The option is called "stroke" because it allows one - to "soft clip" the drive to work around a barrier - limit. - "idebus=xx" : inform IDE driver of VESA/PCI bus speed in MHz, where "xx" is between 20 and 66 inclusive, used when tuning chipset PIO modes. @@ -304,7 +297,7 @@ Summary of ide driver parameters for kernel command line "ide=reverse" : formerly called to pci sub-system, but now local. -The following are valid ONLY on ide0 (except dc4030), which usually corresponds +The following are valid ONLY on ide0, which usually corresponds to the first ATA interface found on the particular host, and the defaults for the base,ctl ports must not be altered. @@ -315,7 +308,7 @@ the base,ctl ports must not be altered. "ide0=qd65xx" : probe/support qd65xx interface "ide0=ali14xx" : probe/support ali14xx chipsets (ALI M1439/M1443/M1445) "ide0=umc8672" : probe/support umc8672 chipsets - "idex=dc4030" : probe/support Promise DC4030VL interface + "ide=doubler" : probe/support IDE doublers on Amiga There may be more options than shown -- use the source, Luke! diff --git a/Documentation/ioctl/cdrom.txt b/Documentation/ioctl/cdrom.txt new file mode 100644 index 000000000..4ccdcc6fe --- /dev/null +++ b/Documentation/ioctl/cdrom.txt @@ -0,0 +1,966 @@ + Summary of CDROM ioctl calls. + ============================ + + Edward A. Falk + + November, 2004 + +This document attempts to describe the ioctl(2) calls supported by +the CDROM layer. These are by-and-large implemented (as of Linux 2.6) +in drivers/cdrom/cdrom.c and drivers/block/scsi_ioctl.c + +ioctl values are listed in . As of this writing, they +are as follows: + + CDROMPAUSE Pause Audio Operation + CDROMRESUME Resume paused Audio Operation + CDROMPLAYMSF Play Audio MSF (struct cdrom_msf) + CDROMPLAYTRKIND Play Audio Track/index (struct cdrom_ti) + CDROMREADTOCHDR Read TOC header (struct cdrom_tochdr) + CDROMREADTOCENTRY Read TOC entry (struct cdrom_tocentry) + CDROMSTOP Stop the cdrom drive + CDROMSTART Start the cdrom drive + CDROMEJECT Ejects the cdrom media + CDROMVOLCTRL Control output volume (struct cdrom_volctrl) + CDROMSUBCHNL Read subchannel data (struct cdrom_subchnl) + CDROMREADMODE2 Read CDROM mode 2 data (2336 Bytes) + (struct cdrom_read) + CDROMREADMODE1 Read CDROM mode 1 data (2048 Bytes) + (struct cdrom_read) + CDROMREADAUDIO (struct cdrom_read_audio) + CDROMEJECT_SW enable(1)/disable(0) auto-ejecting + CDROMMULTISESSION Obtain the start-of-last-session + address of multi session disks + (struct cdrom_multisession) + CDROM_GET_MCN Obtain the "Universal Product Code" + if available (struct cdrom_mcn) + CDROM_GET_UPC Deprecated, use CDROM_GET_MCN instead. + CDROMRESET hard-reset the drive + CDROMVOLREAD Get the drive's volume setting + (struct cdrom_volctrl) + CDROMREADRAW read data in raw mode (2352 Bytes) + (struct cdrom_read) + CDROMREADCOOKED read data in cooked mode + CDROMSEEK seek msf address + CDROMPLAYBLK scsi-cd only, (struct cdrom_blk) + CDROMREADALL read all 2646 bytes + CDROMGETSPINDOWN return 4-bit spindown value + CDROMSETSPINDOWN set 4-bit spindown value + CDROMCLOSETRAY pendant of CDROMEJECT + CDROM_SET_OPTIONS Set behavior options + CDROM_CLEAR_OPTIONS Clear behavior options + CDROM_SELECT_SPEED Set the CD-ROM speed + CDROM_SELECT_DISC Select disc (for juke-boxes) + CDROM_MEDIA_CHANGED Check is media changed + CDROM_DRIVE_STATUS Get tray position, etc. + CDROM_DISC_STATUS Get disc type, etc. + CDROM_CHANGER_NSLOTS Get number of slots + CDROM_LOCKDOOR lock or unlock door + CDROM_DEBUG Turn debug messages on/off + CDROM_GET_CAPABILITY get capabilities + CDROMAUDIOBUFSIZ set the audio buffer size + DVD_READ_STRUCT Read structure + DVD_WRITE_STRUCT Write structure + DVD_AUTH Authentication + CDROM_SEND_PACKET send a packet to the drive + CDROM_NEXT_WRITABLE get next writable block + CDROM_LAST_WRITTEN get last block written on disc + + +The information that follows was determined from reading kernel source +code. It is likely that some corrections will be made over time. + + + + + + + +General: + + Unless otherwise specified, all ioctl calls return 0 on success + and -1 with errno set to an appropriate value on error. (Some + ioctls return non-negative data values.) + + Unless otherwise specified, all ioctl calls return -1 and set + errno to EFAULT on a failed attempt to copy data to or from user + address space. + + Individual drivers may return error codes not listed here. + + Unless otherwise specified, all data structures and constants + are defined in + + + + +CDROMPAUSE Pause Audio Operation + + usage: + + ioctl(fd, CDROMPAUSE, 0); + + inputs: none + + outputs: none + + error return: + ENOSYS cd drive not audio-capable. + + +CDROMRESUME Resume paused Audio Operation + + usage: + + ioctl(fd, CDROMRESUME, 0); + + inputs: none + + outputs: none + + error return: + ENOSYS cd drive not audio-capable. + + +CDROMPLAYMSF Play Audio MSF (struct cdrom_msf) + + usage: + + struct cdrom_msf msf; + ioctl(fd, CDROMPLAYMSF, &msf); + + inputs: + cdrom_msf structure, describing a segment of music to play + + outputs: none + + error return: + ENOSYS cd drive not audio-capable. + + notes: + MSF stands for minutes-seconds-frames + LBA stands for logical block address + + Segment is described as start and end times, where each time + is described as minutes:seconds:frames. A frame is 1/75 of + a second. + + +CDROMPLAYTRKIND Play Audio Track/index (struct cdrom_ti) + + usage: + + struct cdrom_ti ti; + ioctl(fd, CDROMPLAYTRKIND, &ti); + + inputs: + cdrom_ti structure, describing a segment of music to play + + outputs: none + + error return: + ENOSYS cd drive not audio-capable. + + notes: + Segment is described as start and end times, where each time + is described as a track and an index. + + + +CDROMREADTOCHDR Read TOC header (struct cdrom_tochdr) + + usage: + + cdrom_tochdr header; + ioctl(fd, CDROMREADTOCHDR, &header); + + inputs: + cdrom_tochdr structure + + outputs: + cdrom_tochdr structure + + error return: + ENOSYS cd drive not audio-capable. + + + +CDROMREADTOCENTRY Read TOC entry (struct cdrom_tocentry) + + usage: + + struct cdrom_tocentry entry; + ioctl(fd, CDROMREADTOCENTRY, &entry); + + inputs: + cdrom_tocentry structure + + outputs: + cdrom_tocentry structure + + error return: + ENOSYS cd drive not audio-capable. + EINVAL entry.cdte_format not CDROM_MSF or CDROM_LBA + EINVAL requested track out of bounds + EIO I/O error reading TOC + + notes: + TOC stands for Table Of Contents + MSF stands for minutes-seconds-frames + LBA stands for logical block address + + + +CDROMSTOP Stop the cdrom drive + + usage: + + ioctl(fd, CDROMSTOP, 0); + + inputs: none + + outputs: none + + error return: + ENOSYS cd drive not audio-capable. + + notes: + Exact interpretation of this ioctl depends on the device, + but most seem to spin the drive down. + + +CDROMSTART Start the cdrom drive + + usage: + + ioctl(fd, CDROMSTART, 0); + + inputs: none + + outputs: none + + error return: + ENOSYS cd drive not audio-capable. + + notes: + Exact interpretation of this ioctl depends on the device, + but most seem to spin the drive up and/or close the tray. + Other devices ignore the ioctl completely. + + +CDROMEJECT Ejects the cdrom media + + usage: + + ioctl(fd, CDROMEJECT, 0); + + inputs: none + + outputs: none + + error returns: + ENOSYS cd drive not capable of ejecting + EBUSY other processes are accessing drive, or door is locked + + notes: + See CDROM_LOCKDOOR, below. + + + +CDROMCLOSETRAY pendant of CDROMEJECT + + usage: + + ioctl(fd, CDROMEJECT, 0); + + inputs: none + + outputs: none + + error returns: + ENOSYS cd drive not capable of ejecting + EBUSY other processes are accessing drive, or door is locked + + notes: + See CDROM_LOCKDOOR, below. + + + +CDROMVOLCTRL Control output volume (struct cdrom_volctrl) + + usage: + + struct cdrom_volctrl volume; + ioctl(fd, CDROMVOLCTRL, &volume); + + inputs: + cdrom_volctrl structure containing volumes for up to 4 + channels. + + outputs: none + + error return: + ENOSYS cd drive not audio-capable. + + + +CDROMVOLREAD Get the drive's volume setting + (struct cdrom_volctrl) + + usage: + + struct cdrom_volctrl volume; + ioctl(fd, CDROMVOLREAD, &volume); + + inputs: none + + outputs: + The current volume settings. + + error return: + ENOSYS cd drive not audio-capable. + + + +CDROMSUBCHNL Read subchannel data (struct cdrom_subchnl) + + usage: + + struct cdrom_subchnl q; + ioctl(fd, CDROMSUBCHNL, &q); + + inputs: + cdrom_subchnl structure + + outputs: + cdrom_subchnl structure + + error return: + ENOSYS cd drive not audio-capable. + EINVAL format not CDROM_MSF or CDROM_LBA + + notes: + Format is converted to CDROM_MSF on return + + + +CDROMREADRAW read data in raw mode (2352 Bytes) + (struct cdrom_read) + + usage: + + union { + struct cdrom_msf msf; /* input */ + char buffer[CD_FRAMESIZE_RAW]; /* return */ + } arg; + ioctl(fd, CDROMREADRAW, &arg); + + inputs: + cdrom_msf structure indicating an address to read. + Only the start values are significant. + + outputs: + Data written to address provided by user. + + error return: + EINVAL address less than 0, or msf less than 0:2:0 + ENOMEM out of memory + + notes: + As of 2.6.8.1, comments in indicate that this + ioctl accepts a cdrom_read structure, but actual source code + reads a cdrom_msf structure and writes a buffer of data to + the same address. + + MSF values are converted to LBA values via this formula: + + lba = (((m * CD_SECS) + s) * CD_FRAMES + f) - CD_MSF_OFFSET; + + + + +CDROMREADMODE1 Read CDROM mode 1 data (2048 Bytes) + (struct cdrom_read) + + notes: + Identical to CDROMREADRAW except that block size is + CD_FRAMESIZE (2048) bytes + + + +CDROMREADMODE2 Read CDROM mode 2 data (2336 Bytes) + (struct cdrom_read) + + notes: + Identical to CDROMREADRAW except that block size is + CD_FRAMESIZE_RAW0 (2336) bytes + + + +CDROMREADAUDIO (struct cdrom_read_audio) + + usage: + + struct cdrom_read_audio ra; + ioctl(fd, CDROMREADAUDIO, &ra); + + inputs: + cdrom_read_audio structure containing read start + point and length + + outputs: + audio data, returned to buffer indicated by ra + + error return: + EINVAL format not CDROM_MSF or CDROM_LBA + EINVAL nframes not in range [1 75] + ENXIO drive has no queue (probably means invalid fd) + ENOMEM out of memory + + +CDROMEJECT_SW enable(1)/disable(0) auto-ejecting + + usage: + + int val; + ioctl(fd, CDROMEJECT_SW, val); + + inputs: + Flag specifying auto-eject flag. + + outputs: none + + error return: + ENOSYS Drive is not capable of ejecting. + EBUSY Door is locked + + + + +CDROMMULTISESSION Obtain the start-of-last-session + address of multi session disks + (struct cdrom_multisession) + usage: + + struct cdrom_multisession ms_info; + ioctl(fd, CDROMMULTISESSION, &ms_info); + + inputs: + cdrom_multisession structure containing desired + format. + + outputs: + cdrom_multisession structure is filled with last_session + information. + + error return: + EINVAL format not CDROM_MSF or CDROM_LBA + + +CDROM_GET_MCN Obtain the "Universal Product Code" + if available (struct cdrom_mcn) + + usage: + + struct cdrom_mcn mcn; + ioctl(fd, CDROM_GET_MCN, &mcn); + + inputs: none + + outputs: + Universal Product Code + + error return: + ENOSYS Drive is not capable of reading MCN data. + + notes: + Source code comments state: + + The following function is implemented, although very few + audio discs give Universal Product Code information, which + should just be the Medium Catalog Number on the box. Note, + that the way the code is written on the CD is /not/ uniform + across all discs! + + + + +CDROM_GET_UPC CDROM_GET_MCN (deprecated) + + Not implemented, as of 2.6.8.1 + + + +CDROMRESET hard-reset the drive + + usage: + + ioctl(fd, CDROMRESET, 0); + + inputs: none + + outputs: none + + error return: + EACCES Access denied: requires CAP_SYS_ADMIN + ENOSYS Drive is not capable of resetting. + + + + +CDROMREADCOOKED read data in cooked mode + + usage: + + u8 buffer[CD_FRAMESIZE] + ioctl(fd, CDROMREADCOOKED, buffer); + + inputs: none + + outputs: + 2048 bytes of data, "cooked" mode. + + notes: + Not implemented on all drives. + + + + +CDROMREADALL read all 2646 bytes + + Same as CDROMREADCOOKED, but reads 2646 bytes. + + + +CDROMSEEK seek msf address + + usage: + + struct cdrom_msf msf; + ioctl(fd, CDROMSEEK, &msf); + + inputs: + MSF address to seek to. + + outputs: none + + + +CDROMPLAYBLK scsi-cd only, (struct cdrom_blk) + + usage: + + struct cdrom_blk blk; + ioctl(fd, CDROMPLAYBLK, &blk); + + inputs: + Region to play + + outputs: none + + + +CDROMGETSPINDOWN + + usage: + + char spindown; + ioctl(fd, CDROMGETSPINDOWN, &spindown); + + inputs: none + + outputs: + The value of the current 4-bit spindown value. + + + + +CDROMSETSPINDOWN + + usage: + + char spindown + ioctl(fd, CDROMSETSPINDOWN, &spindown); + + inputs: + 4-bit value used to control spindown (TODO: more detail here) + + outputs: none + + + + + +CDROM_SET_OPTIONS Set behavior options + + usage: + + int options; + ioctl(fd, CDROM_SET_OPTIONS, options); + + inputs: + New values for drive options. The logical 'or' of: + CDO_AUTO_CLOSE close tray on first open(2) + CDO_AUTO_EJECT open tray on last release + CDO_USE_FFLAGS use O_NONBLOCK information on open + CDO_LOCK lock tray on open files + CDO_CHECK_TYPE check type on open for data + + outputs: + Returns the resulting options settings in the + ioctl return value. Returns -1 on error. + + error return: + ENOSYS selected option(s) not supported by drive. + + + + +CDROM_CLEAR_OPTIONS Clear behavior options + + Same as CDROM_SET_OPTIONS, except that selected options are + turned off. + + + +CDROM_SELECT_SPEED Set the CD-ROM speed + + usage: + + int speed; + ioctl(fd, CDROM_SELECT_SPEED, speed); + + inputs: + New drive speed. + + outputs: none + + error return: + ENOSYS speed selection not supported by drive. + + + +CDROM_SELECT_DISC Select disc (for juke-boxes) + + usage: + + int disk; + ioctl(fd, CDROM_SELECT_DISC, disk); + + inputs: + Disk to load into drive. + + outputs: none + + error return: + EINVAL Disk number beyond capacity of drive + + + +CDROM_MEDIA_CHANGED Check is media changed + + usage: + + int slot; + ioctl(fd, CDROM_MEDIA_CHANGED, slot); + + inputs: + Slot number to be tested, always zero except for jukeboxes. + May also be special values CDSL_NONE or CDSL_CURRENT + + outputs: + Ioctl return value is 0 or 1 depending on whether the media + has been changed, or -1 on error. + + error returns: + ENOSYS Drive can't detect media change + EINVAL Slot number beyond capacity of drive + ENOMEM Out of memory + + + +CDROM_DRIVE_STATUS Get tray position, etc. + + usage: + + int slot; + ioctl(fd, CDROM_DRIVE_STATUS, slot); + + inputs: + Slot number to be tested, always zero except for jukeboxes. + May also be special values CDSL_NONE or CDSL_CURRENT + + outputs: + Ioctl return value will be one of the following values + from : + + CDS_NO_INFO Information not available. + CDS_NO_DISC + CDS_TRAY_OPEN + CDS_DRIVE_NOT_READY + CDS_DISC_OK + -1 error + + error returns: + ENOSYS Drive can't detect drive status + EINVAL Slot number beyond capacity of drive + ENOMEM Out of memory + + + + +CDROM_DISC_STATUS Get disc type, etc. + + usage: + + ioctl(fd, CDROM_DISC_STATUS, 0); + + inputs: none + + outputs: + Ioctl return value will be one of the following values + from : + CDS_NO_INFO + CDS_AUDIO + CDS_MIXED + CDS_XA_2_2 + CDS_XA_2_1 + CDS_DATA_1 + + error returns: none at present + + notes: + Source code comments state: + + Ok, this is where problems start. The current interface for + the CDROM_DISC_STATUS ioctl is flawed. It makes the false + assumption that CDs are all CDS_DATA_1 or all CDS_AUDIO, etc. + Unfortunatly, while this is often the case, it is also + very common for CDs to have some tracks with data, and some + tracks with audio. Just because I feel like it, I declare + the following to be the best way to cope. If the CD has + ANY data tracks on it, it will be returned as a data CD. + If it has any XA tracks, I will return it as that. Now I + could simplify this interface by combining these returns with + the above, but this more clearly demonstrates the problem + with the current interface. Too bad this wasn't designed + to use bitmasks... -Erik + + Well, now we have the option CDS_MIXED: a mixed-type CD. + User level programmers might feel the ioctl is not very + useful. + ---david + + + + +CDROM_CHANGER_NSLOTS Get number of slots + + usage: + + ioctl(fd, CDROM_CHANGER_NSLOTS, 0); + + inputs: none + + outputs: + The ioctl return value will be the number of slots in a + CD changer. Typically 1 for non-multi-disk devices. + + error returns: none + + + +CDROM_LOCKDOOR lock or unlock door + + usage: + + int lock; + ioctl(fd, CDROM_LOCKDOOR, lock); + + inputs: + Door lock flag, 1=lock, 0=unlock + + outputs: none + + error returns: + EDRIVE_CANT_DO_THIS Door lock function not supported. + EBUSY Attempt to unlock when multiple users + have the drive open and not CAP_SYS_ADMIN + + notes: + As of 2.6.8.1, the lock flag is a global lock, meaning that + all CD drives will be locked or unlocked together. This is + probably a bug. + + The EDRIVE_CANT_DO_THIS value is defined in + and is currently (2.6.8.1) the same as EOPNOTSUPP + + + +CDROM_DEBUG Turn debug messages on/off + + usage: + + int debug; + ioctl(fd, CDROM_DEBUG, debug); + + inputs: + Cdrom debug flag, 0=disable, 1=enable + + outputs: + The ioctl return value will be the new debug flag. + + error return: + EACCES Access denied: requires CAP_SYS_ADMIN + + + +CDROM_GET_CAPABILITY get capabilities + + usage: + + ioctl(fd, CDROM_GET_CAPABILITY, 0); + + inputs: none + + outputs: + The ioctl return value is the current device capability + flags. See CDC_CLOSE_TRAY, CDC_OPEN_TRAY, etc. + + + +CDROMAUDIOBUFSIZ set the audio buffer size + + usage: + + int arg; + ioctl(fd, CDROMAUDIOBUFSIZ, val); + + inputs: + New audio buffer size + + outputs: + The ioctl return value is the new audio buffer size, or -1 + on error. + + error return: + ENOSYS Not supported by this driver. + + notes: + Not supported by all drivers. + + + +DVD_READ_STRUCT Read structure + + usage: + + dvd_struct s; + ioctl(fd, DVD_READ_STRUCT, &s); + + inputs: + dvd_struct structure, containing: + type specifies the information desired, one of + DVD_STRUCT_PHYSICAL, DVD_STRUCT_COPYRIGHT, + DVD_STRUCT_DISCKEY, DVD_STRUCT_BCA, + DVD_STRUCT_MANUFACT + physical.layer_num desired layer, indexed from 0 + copyright.layer_num desired layer, indexed from 0 + disckey.agid + + outputs: + dvd_struct structure, containing: + physical for type == DVD_STRUCT_PHYSICAL + copyright for type == DVD_STRUCT_COPYRIGHT + disckey.value for type == DVD_STRUCT_DISCKEY + bca.{len,value} for type == DVD_STRUCT_BCA + manufact.{len,valu} for type == DVD_STRUCT_MANUFACT + + error returns: + EINVAL physical.layer_num exceeds number of layers + EIO Recieved invalid response from drive + + + +DVD_WRITE_STRUCT Write structure + + Not implemented, as of 2.6.8.1 + + + +DVD_AUTH Authentication + + usage: + + dvd_authinfo ai; + ioctl(fd, DVD_AUTH, &ai); + + inputs: + dvd_authinfo structure. See + + outputs: + dvd_authinfo structure. + + error return: + ENOTTY ai.type not recognized. + + + +CDROM_SEND_PACKET send a packet to the drive + + usage: + + struct cdrom_generic_command cgc; + ioctl(fd, CDROM_SEND_PACKET, &cgc); + + inputs: + cdrom_generic_command structure containing the packet to send. + + outputs: none + cdrom_generic_command structure containing results. + + error return: + EIO command failed. + EPERM Operation not permitted, either because a + write command was attempted on a drive which + is opened read-only, or because the command + requires CAP_SYS_RAWIO + EINVAL cgc.data_direction not set + + + +CDROM_NEXT_WRITABLE get next writable block + + usage: + + long next; + ioctl(fd, CDROM_NEXT_WRITABLE, &next); + + inputs: none + + outputs: + The next writable block. + + notes: + If the device does not support this ioctl directly, the + ioctl will return CDROM_LAST_WRITTEN + 7. + + + +CDROM_LAST_WRITTEN get last block written on disc + + usage: + + long last; + ioctl(fd, CDROM_LAST_WRITTEN, &last); + + inputs: none + + outputs: + The last block written on disc + + notes: + If the device does not support this ioctl directly, the + result is derived from the disc's table of contents. If the + table of contents can't be read, this ioctl returns an + error. diff --git a/Documentation/ioctl/hdio.txt b/Documentation/ioctl/hdio.txt new file mode 100644 index 000000000..c42d3b685 --- /dev/null +++ b/Documentation/ioctl/hdio.txt @@ -0,0 +1,965 @@ + Summary of HDIO_ ioctl calls. + ============================ + + Edward A. Falk + + November, 2004 + +This document attempts to describe the ioctl(2) calls supported by +the HD/IDE layer. These are by-and-large implemented (as of Linux 2.6) +in drivers/ide/ide.c and drivers/block/scsi_ioctl.c + +ioctl values are listed in . As of this writing, they +are as follows: + + ioctls that pass argument pointers to user space: + + HDIO_GETGEO get device geometry + HDIO_GET_UNMASKINTR get current unmask setting + HDIO_GET_MULTCOUNT get current IDE blockmode setting + HDIO_GET_QDMA get use-qdma flag + HDIO_SET_XFER set transfer rate via proc + HDIO_OBSOLETE_IDENTITY OBSOLETE, DO NOT USE + HDIO_GET_KEEPSETTINGS get keep-settings-on-reset flag + HDIO_GET_32BIT get current io_32bit setting + HDIO_GET_NOWERR get ignore-write-error flag + HDIO_GET_DMA get use-dma flag + HDIO_GET_NICE get nice flags + HDIO_GET_IDENTITY get IDE identification info + HDIO_GET_WCACHE get write cache mode on|off + HDIO_GET_ACOUSTIC get acoustic value + HDIO_GET_ADDRESS get sector addressing mode + HDIO_GET_BUSSTATE get the bus state of the hwif + HDIO_TRISTATE_HWIF execute a channel tristate + HDIO_DRIVE_RESET execute a device reset + HDIO_DRIVE_TASKFILE execute raw taskfile + HDIO_DRIVE_TASK execute task and special drive command + HDIO_DRIVE_CMD execute a special drive command + HDIO_DRIVE_CMD_AEB HDIO_DRIVE_TASK + + ioctls that pass non-pointer values: + + HDIO_SET_MULTCOUNT change IDE blockmode + HDIO_SET_UNMASKINTR permit other irqs during I/O + HDIO_SET_KEEPSETTINGS keep ioctl settings on reset + HDIO_SET_32BIT change io_32bit flags + HDIO_SET_NOWERR change ignore-write-error flag + HDIO_SET_DMA change use-dma flag + HDIO_SET_PIO_MODE reconfig interface to new speed + HDIO_SCAN_HWIF register and (re)scan interface + HDIO_SET_NICE set nice flags + HDIO_UNREGISTER_HWIF unregister interface + HDIO_SET_WCACHE change write cache enable-disable + HDIO_SET_ACOUSTIC change acoustic behavior + HDIO_SET_BUSSTATE set the bus state of the hwif + HDIO_SET_QDMA change use-qdma flag + HDIO_SET_ADDRESS change lba addressing modes + + HDIO_SET_IDE_SCSI Set scsi emulation mode on/off + HDIO_SET_SCSI_IDE not implemented yet + + +The information that follows was determined from reading kernel source +code. It is likely that some corrections will be made over time. + + + + + + + +General: + + Unless otherwise specified, all ioctl calls return 0 on success + and -1 with errno set to an appropriate value on error. + + Unless otherwise specified, all ioctl calls return -1 and set + errno to EFAULT on a failed attempt to copy data to or from user + address space. + + Unless otherwise specified, all data structures and constants + are defined in + + + +HDIO_GETGEO get device geometry + + usage: + + struct hd_geometry geom; + ioctl(fd, HDIO_GETGEO, &geom); + + + inputs: none + + outputs: + + hd_geometry structure containing: + + heads number of heads + sectors number of sectors/track + cylinders number of cylinders, mod 65536 + start starting sector of this partition. + + + error returns: + EINVAL if the device is not a disk drive or floppy drive, + or if the user passes a null pointer + + + notes: + + Not particularly useful with modern disk drives, whose geometry + is a polite fiction anyway. Modern drives are addressed + purely by sector number nowadays (lba addressing), and the + drive geometry is an abstraction which is actually subject + to change. Currently (as of Nov 2004), the geometry values + are the "bios" values -- presumably the values the drive had + when Linux first booted. + + In addition, the cylinders field of the hd_geometry is an + unsigned short, meaning that on most architectures, this + ioctl will not return a meaningful value on drives with more + than 65535 tracks. + + The start field is unsigned long, meaning that it will not + contain a meaningful value for disks over 219 Gb in size. + + + + +HDIO_GET_UNMASKINTR get current unmask setting + + usage: + + long val; + ioctl(fd, HDIO_GET_UNMASKINTR, &val); + + inputs: none + + outputs: + The value of the drive's current unmask setting + + + +HDIO_SET_UNMASKINTR permit other irqs during I/O + + usage: + + unsigned long val; + ioctl(fd, HDIO_SET_UNMASKINTR, val); + + inputs: + New value for unmask flag + + outputs: none + + error return: + EINVAL (bdev != bdev->bd_contains) (not sure what this means) + EACCES Access denied: requires CAP_SYS_ADMIN + EINVAL value out of range [0 1] + EBUSY Controller busy + + + + +HDIO_GET_MULTCOUNT get current IDE blockmode setting + + usage: + + long val; + ioctl(fd, HDIO_GET_MULTCOUNT, &val); + + inputs: none + + outputs: + The value of the current IDE block mode setting. This + controls how many sectors the drive will transfer per + interrupt. + + + +HDIO_SET_MULTCOUNT change IDE blockmode + + usage: + + int val; + ioctl(fd, HDIO_SET_MULTCOUNT, val); + + inputs: + New value for IDE block mode setting. This controls how many + sectors the drive will transfer per interrupt. + + outputs: none + + error return: + EINVAL (bdev != bdev->bd_contains) (not sure what this means) + EACCES Access denied: requires CAP_SYS_ADMIN + EINVAL value out of range supported by disk. + EBUSY Controller busy or blockmode already set. + EIO Drive did not accept new block mode. + + notes: + + Source code comments read: + + This is tightly woven into the driver->do_special can not + touch. DON'T do it again until a total personality rewrite + is committed. + + If blockmode has already been set, this ioctl will fail with + EBUSY + + + +HDIO_GET_QDMA get use-qdma flag + + Not implemented, as of 2.6.8.1 + + + +HDIO_SET_XFER set transfer rate via proc + + Not implemented, as of 2.6.8.1 + + + +HDIO_OBSOLETE_IDENTITY OBSOLETE, DO NOT USE + + Same as HDIO_GET_IDENTITY (see below), except that it only + returns the first 142 bytes of drive identity information. + + + +HDIO_GET_IDENTITY get IDE identification info + + usage: + + unsigned char identity[512]; + ioctl(fd, HDIO_GET_IDENTITY, identity); + + inputs: none + + outputs: + + ATA drive identity information. For full description, see + the IDENTIFY DEVICE and IDENTIFY PACKET DEVICE commands in + the ATA specification. + + error returns: + EINVAL (bdev != bdev->bd_contains) (not sure what this means) + ENOMSG IDENTIFY DEVICE information not available + + notes: + + Returns information that was obtained when the drive was + probed. Some of this information is subject to change, and + this ioctl does not re-probe the drive to update the + information. + + This information is also available from /proc/ide/hdX/identify + + + +HDIO_GET_KEEPSETTINGS get keep-settings-on-reset flag + + usage: + + long val; + ioctl(fd, HDIO_GET_KEEPSETTINGS, &val); + + inputs: none + + outputs: + The value of the current "keep settings" flag + + notes: + + When set, indicates that kernel should restore settings + after a drive reset. + + + +HDIO_SET_KEEPSETTINGS keep ioctl settings on reset + + usage: + + long val; + ioctl(fd, HDIO_SET_KEEPSETTINGS, val); + + inputs: + New value for keep_settings flag + + outputs: none + + error return: + EINVAL (bdev != bdev->bd_contains) (not sure what this means) + EACCES Access denied: requires CAP_SYS_ADMIN + EINVAL value out of range [0 1] + EBUSY Controller busy + + + +HDIO_GET_32BIT get current io_32bit setting + + usage: + + long val; + ioctl(fd, HDIO_GET_32BIT, &val); + + inputs: none + + outputs: + The value of the current io_32bit setting + + notes: + + 0=16-bit, 1=32-bit, 2,3 = 32bit+sync + + + +HDIO_GET_NOWERR get ignore-write-error flag + + usage: + + long val; + ioctl(fd, HDIO_GET_NOWERR, &val); + + inputs: none + + outputs: + The value of the current ignore-write-error flag + + + +HDIO_GET_DMA get use-dma flag + + usage: + + long val; + ioctl(fd, HDIO_GET_DMA, &val); + + inputs: none + + outputs: + The value of the current use-dma flag + + + +HDIO_GET_NICE get nice flags + + usage: + + long nice; + ioctl(fd, HDIO_GET_NICE, &nice); + + inputs: none + + outputs: + + The drive's "nice" values. + + notes: + + Per-drive flags which determine when the system will give more + bandwidth to other devices sharing the same IDE bus. + See , near symbol IDE_NICE_DSC_OVERLAP. + + + + +HDIO_SET_NICE set nice flags + + usage: + + unsigned long nice; + ... + ioctl(fd, HDIO_SET_NICE, nice); + + inputs: + bitmask of nice flags. + + outputs: none + + error returns: + EACCES Access denied: requires CAP_SYS_ADMIN + EPERM Flags other than DSC_OVERLAP and NICE_1 set. + EPERM DSC_OVERLAP specified but not supported by drive + + notes: + + This ioctl sets the DSC_OVERLAP and NICE_1 flags from values + provided by the user. + + Nice flags are listed in , starting with + IDE_NICE_DSC_OVERLAP. These values represent shifts. + + + + + +HDIO_GET_WCACHE get write cache mode on|off + + usage: + + long val; + ioctl(fd, HDIO_GET_WCACHE, &val); + + inputs: none + + outputs: + The value of the current write cache mode + + + +HDIO_GET_ACOUSTIC get acoustic value + + usage: + + long val; + ioctl(fd, HDIO_GET_ACOUSTIC, &val); + + inputs: none + + outputs: + The value of the current acoustic settings + + notes: + + See HDIO_SET_ACOUSTIC + + + +HDIO_GET_ADDRESS + + usage: + + long val; + ioctl(fd, HDIO_GET_ADDRESS, &val); + + inputs: none + + outputs: + The value of the current addressing mode: + 0 = 28-bit + 1 = 48-bit + 2 = 48-bit doing 28-bit + 3 = 64-bit + + + +HDIO_GET_BUSSTATE get the bus state of the hwif + + usage: + + long state; + ioctl(fd, HDIO_SCAN_HWIF, &state); + + inputs: none + + outputs: + Current power state of the IDE bus. One of BUSSTATE_OFF, + BUSSTATE_ON, or BUSSTATE_TRISTATE + + error returns: + EACCES Access denied: requires CAP_SYS_ADMIN + + + + +HDIO_SET_BUSSTATE set the bus state of the hwif + + usage: + + int state; + ... + ioctl(fd, HDIO_SCAN_HWIF, state); + + inputs: + Desired IDE power state. One of BUSSTATE_OFF, BUSSTATE_ON, + or BUSSTATE_TRISTATE + + outputs: none + + error returns: + EACCES Access denied: requires CAP_SYS_RAWIO + EOPNOTSUPP Hardware interface does not support bus power control + + + + +HDIO_TRISTATE_HWIF execute a channel tristate + + Not implemented, as of 2.6.8.1. See HDIO_SET_BUSSTATE + + + +HDIO_DRIVE_RESET execute a device reset + + usage: + + int args[3] + ... + ioctl(fd, HDIO_DRIVE_RESET, args); + + inputs: none + + outputs: none + + error returns: + EACCES Access denied: requires CAP_SYS_ADMIN + + notes: + + Abort any current command, prevent anything else from being + queued, execute a reset on the device, and issue BLKRRPART + ioctl on the block device. + + Executes an ATAPI soft reset if applicable, otherwise + executes an ATA soft reset on the controller. + + + +HDIO_DRIVE_TASKFILE execute raw taskfile + + Note: If you don't have a copy of the ANSI ATA specification + handy, you should probably ignore this ioctl. + + Execute an ATA disk command directly by writing the "taskfile" + registers of the drive. Requires ADMIN and RAWIO access + privileges. + + usage: + + struct { + ide_task_request_t req_task; + u8 outbuf[OUTPUT_SIZE]; + u8 inbuf[INPUT_SIZE]; + } task; + memset(&task.req_task, 0, sizeof(task.req_task)); + task.req_task.out_size = sizeof(task.outbuf); + task.req_task.in_size = sizeof(task.inbuf); + ... + ioctl(fd, HDIO_DRIVE_TASKFILE, &task); + ... + + inputs: + + (See below for details on memory area passed to ioctl.) + + io_ports[8] values to be written to taskfile registers + hob_ports[8] high-order bytes, for extended commands. + out_flags flags indicating which registers are valid + in_flags flags indicating which registers should be returned + data_phase see below + req_cmd command type to be executed + out_size size of output buffer + outbuf buffer of data to be transmitted to disk + inbuf buffer of data to be received from disk (see [1]) + + outputs: + + io_ports[] values returned in the taskfile registers + hob_ports[] high-order bytes, for extended commands. + out_flags flags indicating which registers are valid (see [2]) + in_flags flags indicating which registers should be returned + outbuf buffer of data to be transmitted to disk (see [1]) + inbuf buffer of data to be received from disk + + error returns: + EACCES CAP_SYS_ADMIN or CAP_SYS_RAWIO privilege not set. + ENOMSG Device is not a disk drive. + ENOMEM Unable to allocate memory for task + EFAULT req_cmd == TASKFILE_IN_OUT (not implemented as of 2.6.8) + EPERM req_cmd == TASKFILE_MULTI_OUT and drive + multi-count not yet set. + + + notes: + + [1] Currently (2.6.8), both the input and output buffers are + copied from the user and written back to the user, even when + not used. This may be a bug. + + [2] The out_flags and in_flags are returned to the user after + the ioctl completes. Currently (2.6.8) these are the same + as the input values, unchanged. In the future, they may have + more significance. + + Extreme caution should be used with using this ioctl. A + mistake can easily corrupt data or hang the system. + + The argument to the ioctl is a pointer to a region of memory + containing a ide_task_request_t structure, followed by an + optional buffer of data to be transmitted to the drive, + followed by an optional buffer to receive data from the drive. + + Command is passed to the disk drive via the ide_task_request_t + structure, which contains these fields: + + io_ports[8] values for the taskfile registers + hob_ports[8] high-order bytes, for extended commands + out_flags flags indicating which entries in the + io_ports[] and hob_ports[] arrays + contain valid values. Type ide_reg_valid_t. + in_flags flags indicating which entries in the + io_ports[] and hob_ports[] arrays + are expected to contain valid values + on return. + data_phase See below + req_cmd Command type, see below + out_size output (user->drive) buffer size, bytes + in_size input (drive->user) buffer size, bytes + + This ioctl does not necessarily respect all flags in the + out_flags and in_flags values -- some taskfile registers + may be written or read even if not requested in the flags. + Unused fields of io_ports[] and hob_ports[] should be set + to zero. + + The data_phase field describes the data transfer to be + performed. Value is one of: + + TASKFILE_IN + TASKFILE_MULTI_IN + TASKFILE_OUT + TASKFILE_MULTI_OUT + TASKFILE_IN_OUT + TASKFILE_IN_DMA + TASKFILE_IN_DMAQ + TASKFILE_OUT_DMA + TASKFILE_OUT_DMAQ + TASKFILE_P_IN + TASKFILE_P_IN_DMA + TASKFILE_P_IN_DMAQ + TASKFILE_P_OUT + TASKFILE_P_OUT_DMA + TASKFILE_P_OUT_DMAQ + + The req_cmd field classifies the command type. It may be + one of: + + IDE_DRIVE_TASK_NO_DATA + IDE_DRIVE_TASK_SET_XFER + IDE_DRIVE_TASK_IN + IDE_DRIVE_TASK_OUT + IDE_DRIVE_TASK_RAW_WRITE + + + + + + +HDIO_DRIVE_CMD execute a special drive command + + Note: If you don't have a copy of the ANSI ATA specification + handy, you should probably ignore this ioctl. + + usage: + + u8 args[4+XFER_SIZE]; + ... + ioctl(fd, HDIO_DRIVE_CMD, args); + + inputs: + + Taskfile register values: + args[0] COMMAND + args[1] SECTOR + args[2] FEATURE + args[3] NSECTOR + + outputs: + + args[] buffer is filled with register values followed by any + data returned by the disk. + args[0] status + args[1] error + args[2] NSECTOR + args[3] undefined + args[4+] NSECTOR * 512 bytes of data returned by the command. + + error returns: + EACCES Access denied: requires CAP_SYS_RAWIO + ENOMEM Unable to allocate memory for task + + notes: + + Taskfile registers IDE_LCYL, IDE_HCYL, and IDE_SELECT are + set to zero before executing the command. + + + +HDIO_DRIVE_TASK execute task and special drive command + + Note: If you don't have a copy of the ANSI ATA specification + handy, you should probably ignore this ioctl. + + usage: + + u8 args[7]; + ... + ioctl(fd, HDIO_DRIVE_TASK, args); + + inputs: + + Taskfile register values: + args[0] COMMAND + args[1] FEATURE + args[2] NSECTOR + args[3] SECTOR + args[4] LCYL + args[5] HCYL + args[6] SELECT + + outputs: + + Taskfile register values: + args[0] status + args[1] error + args[2] NSECTOR + args[3] SECTOR + args[4] LCYL + args[5] HCYL + args[6] SELECT + + error returns: + EACCES Access denied: requires CAP_SYS_RAWIO + ENOMEM Unable to allocate memory for task + + + + +HDIO_DRIVE_CMD_AEB HDIO_DRIVE_TASK + + Not implemented, as of 2.6.8.1 + + + +HDIO_SET_32BIT change io_32bit flags + + usage: + + int val; + ioctl(fd, HDIO_SET_32BIT, val); + + inputs: + New value for io_32bit flag + + outputs: none + + error return: + EINVAL (bdev != bdev->bd_contains) (not sure what this means) + EACCES Access denied: requires CAP_SYS_ADMIN + EINVAL value out of range [0 3] + EBUSY Controller busy + + + + +HDIO_SET_NOWERR change ignore-write-error flag + + usage: + + int val; + ioctl(fd, HDIO_SET_NOWERR, val); + + inputs: + New value for ignore-write-error flag. Used for ignoring + WRERR_STAT + + outputs: none + + error return: + EINVAL (bdev != bdev->bd_contains) (not sure what this means) + EACCES Access denied: requires CAP_SYS_ADMIN + EINVAL value out of range [0 1] + EBUSY Controller busy + + + +HDIO_SET_DMA change use-dma flag + + usage: + + long val; + ioctl(fd, HDIO_SET_DMA, val); + + inputs: + New value for use-dma flag + + outputs: none + + error return: + EINVAL (bdev != bdev->bd_contains) (not sure what this means) + EACCES Access denied: requires CAP_SYS_ADMIN + EINVAL value out of range [0 1] + EBUSY Controller busy + + + +HDIO_SET_PIO_MODE reconfig interface to new speed + + usage: + + long val; + ioctl(fd, HDIO_SET_PIO_MODE, val); + + inputs: + New interface speed. + + outputs: none + + error return: + EINVAL (bdev != bdev->bd_contains) (not sure what this means) + EACCES Access denied: requires CAP_SYS_ADMIN + EINVAL value out of range [0 255] + EBUSY Controller busy + + + +HDIO_SCAN_HWIF register and (re)scan interface + + usage: + + int args[3] + ... + ioctl(fd, HDIO_SCAN_HWIF, args); + + inputs: + args[0] io address to probe + args[1] control address to probe + args[2] irq number + + outputs: none + + error returns: + EACCES Access denied: requires CAP_SYS_RAWIO + EIO Probe failed. + + notes: + + This ioctl initializes the addresses and irq for a disk + controller, probes for drives, and creates /proc/ide + interfaces as appropiate. + + + +HDIO_UNREGISTER_HWIF unregister interface + + usage: + + int index; + ioctl(fd, HDIO_UNREGISTER_HWIF, index); + + inputs: + index index of hardware interface to unregister + + outputs: none + + error returns: + EACCES Access denied: requires CAP_SYS_RAWIO + + notes: + + This ioctl removes a hardware interface from the kernel. + + Currently (2.6.8) this ioctl silently fails if any drive on + the interface is busy. + + + +HDIO_SET_WCACHE change write cache enable-disable + + usage: + + int val; + ioctl(fd, HDIO_SET_WCACHE, val); + + inputs: + New value for write cache enable + + outputs: none + + error return: + EINVAL (bdev != bdev->bd_contains) (not sure what this means) + EACCES Access denied: requires CAP_SYS_ADMIN + EINVAL value out of range [0 1] + EBUSY Controller busy + + + +HDIO_SET_ACOUSTIC change acoustic behavior + + usage: + + int val; + ioctl(fd, HDIO_SET_ACOUSTIC, val); + + inputs: + New value for drive acoustic settings + + outputs: none + + error return: + EINVAL (bdev != bdev->bd_contains) (not sure what this means) + EACCES Access denied: requires CAP_SYS_ADMIN + EINVAL value out of range [0 254] + EBUSY Controller busy + + + +HDIO_SET_QDMA change use-qdma flag + + Not implemented, as of 2.6.8.1 + + + +HDIO_SET_ADDRESS change lba addressing modes + + usage: + + int val; + ioctl(fd, HDIO_SET_ADDRESS, val); + + inputs: + New value for addressing mode + 0 = 28-bit + 1 = 48-bit + 2 = 48-bit doing 28-bit + + outputs: none + + error return: + EINVAL (bdev != bdev->bd_contains) (not sure what this means) + EACCES Access denied: requires CAP_SYS_ADMIN + EINVAL value out of range [0 2] + EBUSY Controller busy + EIO Drive does not support lba48 mode. + + +HDIO_SET_IDE_SCSI + + usage: + + long val; + ioctl(fd, HDIO_SET_IDE_SCSI, val); + + inputs: + New value for scsi emulation mode (?) + + outputs: none + + error return: + EINVAL (bdev != bdev->bd_contains) (not sure what this means) + EACCES Access denied: requires CAP_SYS_ADMIN + EINVAL value out of range [0 1] + EBUSY Controller busy + + + +HDIO_SET_SCSI_IDE + + Not implemented, as of 2.6.8.1 + + diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt index 1075e4de2..2616a58a5 100644 --- a/Documentation/kbuild/makefiles.txt +++ b/Documentation/kbuild/makefiles.txt @@ -6,7 +6,7 @@ This document describes the Linux kernel Makefiles. === 1 Overview === 2 Who does what - === 3 The kbuild Makefiles + === 3 The kbuild files --- 3.1 Goal definitions --- 3.2 Built-in object goals - obj-y --- 3.3 Loadable module goals - obj-m @@ -101,11 +101,14 @@ These people need to know about all aspects of the kernel Makefiles. This document is aimed towards normal developers and arch developers. -=== 3 The kbuild Makefiles +=== 3 The kbuild files Most Makefiles within the kernel are kbuild Makefiles that use the kbuild infrastructure. This chapter introduce the syntax used in the kbuild makefiles. +The preferred name for the kbuild files is 'Kbuild' but 'Makefile' will +continue to be supported. All new developmen is expected to use the +Kbuild filename. Section 3.1 "Goal definitions" is a quick intro, further chapters provide more details, with real examples. @@ -707,15 +710,17 @@ When kbuild executes the following steps are followed (roughly): probe supported options: #arch/i386/Makefile - check_gcc = $(shell if $(CC) $(1) -S -o /dev/null -xc \ - /dev/null\ > /dev/null 2>&1; then echo "$(1)"; \ - else echo "$(2)"; fi) - cflags-$(CONFIG_MCYRIXIII) += $(call check_gcc,\ - -march=c3,-march=i486) - CFLAGS += $(cflags-y) + ... + cflags-$(CONFIG_MPENTIUMII) += $(call cc-option,\ + -march=pentium2,-march=i686) + ... + # Disable unit-at-a-time mode ... + CFLAGS += $(call cc-option,-fno-unit-at-a-time) + ... + - The above examples both utilise the trick that a config option expands + The first examples utilises the trick that a config option expands to 'y' when selected. CFLAGS_KERNEL $(CC) options specific for built-in @@ -997,6 +1002,21 @@ When kbuild executes the following steps are followed (roughly): option. When $(biarch) equals to y the expanded variables $(aflags-y) and $(cflags-y) will be assigned the values -a32 and -m32. + cc-option-align + gcc version >= 3.0 shifted type of options used to speify + alignment of functions, loops etc. $(cc-option-align) whrn used + as prefix to the align options will select the right prefix: + gcc < 3.00 + cc-option-align = -malign + gcc >= 3.00 + cc-option-align = -falign + + Example: + CFLAGS += $(cc-option-align)-functions=4 + + In the above example the option -falign-functions=4 is used for + gcc >= 3.00. For gcc < 3.00 -malign-functions=4 is used. + cc-version cc-version return a numerical version of the $(CC) compiler version. The format is where both are two digits. So for example diff --git a/Documentation/kbuild/modules.txt b/Documentation/kbuild/modules.txt index b8933206f..c91caf7eb 100644 --- a/Documentation/kbuild/modules.txt +++ b/Documentation/kbuild/modules.txt @@ -1,68 +1,419 @@ -For now this is a raw copy from the old Documentation/kbuild/modules.txt, -which was removed in 2.6.0-test5. -The information herein is correct but not complete. - -Installing modules in a non-standard location ---------------------------------------------- -When the modules needs to be installed under another directory -the INSTALL_MOD_PATH can be used to prefix "/lib/modules" as seen -in the following example: - -make INSTALL_MOD_PATH=/frodo modules_install - -This will install the modules in the directory /frodo/lib/modules. -/frodo can be a NFS mounted filesystem on another machine, allowing -out-of-the-box support for installation on remote machines. - - -Compiling modules outside the official kernel ---------------------------------------------- - -Often modules are developed outside the official kernel. To keep up -with changes in the build system the most portable way to compile a -module outside the kernel is to use the kernel build system, -kbuild. Use the following command-line: - -make -C path/to/kernel/src M=$PWD modules - -This requires that a makefile exits made in accordance to -Documentation/kbuild/makefiles.txt. Read that file for more details on -the build system. - -The following is a short summary of how to write your Makefile to get -you up and running fast. Assuming your module will be called -yourmodule.ko, your code should be in yourmodule.c and your Makefile -should include - -obj-m := yourmodule.o - -If the code for your module is in multiple files that need to be -linked, you need to tell the build system which files to compile. In -the case of multiple files, none of these files can be named -yourmodule.c because doing so would cause a problem with the linking -step. Assuming your code exists in file1.c, file2.c, and file3.c and -you want to build yourmodule.ko from them, your Makefile should -include - -obj-m := yourmodule.o -yourmodule-objs := file1.o file2.o file3.o - -Now for a final example to put it all together. Assuming the -KERNEL_SOURCE environment variable is set to the directory where you -compiled the kernel, a simple Makefile that builds yourmodule.ko as -described above would look like - -# Tells the build system to build yourmodule.ko. -obj-m := yourmodule.o - -# Tells the build system to build these object files and link them as -# yourmodule.o, before building yourmodule.ko. This line can be left -# out if all the code for your module is in one file, yourmodule.c. If -# you are using multiple files, none of these files can be named -# yourmodule.c. -yourmodule-objs := file1.o file2.o file3.o - -# Invokes the kernel build system to come back to the current -# directory and build yourmodule.ko. -default: - make -C ${KERNEL_SOURCE} M=`pwd` modules + +In this document you will find information about: +- how to build external modules +- how to make your module use kbuild infrastructure +- how kbuild will install a kernel +- how to install modules in a non-standard location + +=== Table of Contents + + === 1 Introduction + === 2 How to build external modules + --- 2.1 Building external modules + --- 2.2 Available targets + --- 2.3 Available options + --- 2.4 Preparing the kernel tree for module build + === 3. Example commands + === 4. Creating a kbuild file for an external module + === 5. Include files + --- 5.1 How to include files from the kernel include dir + --- 5.2 External modules using an include/ dir + === 6. Module installation + --- 6.1 INSTALL_MOD_PATH + --- 6.2 INSTALL_MOD_DIR + === 7. Module versioning + === 8. Tips & Tricks + --- 8.1 Testing for CONFIG_FOO_BAR + + + +=== 1. Introduction + +kbuild includes functionality for building modules both +within the kernel source tree and outside the kernel source tree. +The latter is usually referred to as external modules and is used +both during development and for modules that are not planned to be +included in the kernel tree. + +What is covered within this file is mainly information to authors +of modules. The author of an external modules should supply +a makefile that hides most of the complexity so one only has to type +'make' to buld the module. A complete example will be present in +chapter ¤. Creating a kbuild file for an external module". + + +=== 2. How to build external modules + +kbuild offers functionality to build external modules, with the +prerequisite that there is a pre-built kernel available with full source. +A subset of the targets available when building the kernel is available +when building an external module. + +--- 2.1 Building external modules + + Use the following command to build an external module: + + make -C M=`pwd` + + For the running kernel use: + make -C /lib/modules/`uname -r`/build M=`pwd` + + For the above command to succeed the kernel must have been built with + modules enabled. + + To install the modules that were just built: + + make -C M=`pwd` modules_install + + More complex examples later, the above should get you going. + +--- 2.2 Available targets + + $KDIR refers to path to kernel source top-level directory + + make -C $KDIR M=`pwd` + Will build the module(s) located in current directory. + All output files will be located in the same directory + as the module source. + No attempts are made to update the kernel source, and it is + a precondition that a successful make has been executed + for the kernel. + + make -C $KDIR M=`pwd` modules + The modules target is implied when no target is given. + Same functionality as if no target was specified. + See description above. + + make -C $KDIR M=$PWD modules_install + Install the external module(s). + Installation default is in /lib/modules//extra, + but may be prefixed with INSTALL_MOD_PATH - see separate chater. + + make -C $KDIR M=$PWD clean + Remove all generated files for the module - the kernel + source directory is not moddified. + + make -C $KDIR M=`pwd` help + help will list the available target when building external + modules. + +--- 2.3 Available options: + + $KDIR refer to path to kernel src + + make -C $KDIR + Used to specify where to find the kernel source. + '$KDIR' represent the directory where the kernel source is. + Make will actually change directory to the specified directory + when executed but change back when finished. + + make -C $KDIR M=`pwd` + M= is used to tell kbuild that an external module is + being built. + The option given to M= is the directory where the external + module (kbuild file) is located. + When an external module is being built only a subset of the + usual targets are available. + + make -C $KDIR SUBDIRS=`pwd` + Same as M=. The SUBDIRS= syntax is kept for backwards + compatibility. + +--- 2.4 Preparing the kernel tree for module build + + To make sure the kernel contains the information required to + build external modules the target 'modules_prepare' must be used. + 'module_prepare' solely exists as a simple way to prepare + a kernel for building external modules. + Note: modules_prepare will not build Module.symvers even if + CONFIG_MODULEVERSIONING is set. + Therefore a full kernel build needs to be executed to make + module versioning work. + + +=== 3. Example commands + +This example shows the actual commands to be executed when building +an external module for the currently running kernel. +In the example below the distribution is supposed to use the +facility to locate output files for a kernel compile in a different +directory than the kernel source - but the examples will also work +when the source and the output files are mixed in the same directory. + +# Kernel source +/lib/modules//source -> /usr/src/linux- + +# Output from kernel compile +/lib/modules//build -> /usr/src/linux--up + +Change to the directory where the kbuild file is located and execute +the following commands to build the module: + + cd /home/user/src/module + make -C /usr/src/`uname -r`/source \ + O=/lib/modules/`uname-r`/build \ + M=`pwd` + +Then to install the module use the following command: + + make -C /usr/src/`uname -r`/source \ + O=/lib/modules/`uname-r`/build \ + M=`pwd` \ + modules_install + +If one looks closely you will see that this is the same commands as +listed before - with the directories spelled out. + +The above are rather long commands, and the following chapter +lists a few tricks to make it all easier. + + +=== 4. Creating a kbuild file for an external module + +kbuild is the build system for the kernel, and external modules +must use kbuild to stay compatible with changes in the build system +and to pick up the right flags to gcc etc. + +The kbuild file used as input shall follow the syntax described +in Documentation/kbuild/makefiles.txt. This chapter will introduce a few +more tricks to be used when dealing with external modules. + +In the following a Makefile will be created for a module with the +following files: + 8123_if.c + 8123_if.h + 8123_pci.c + 8123_bin.o_shipped <= Binary blob + +--- 4.1 Shared Makefile for module and kernel + + An external module always includes a wrapper Makefile supporting + building the module using 'make' with no arguments. + The Makefile provided will most likely include additional + functionality such as test targets etc. and this part shall + be filtered away from kbuild since it may impact kbuild if + name clashes occurs. + + Example 1: + --> filename: Makefile + ifneq ($(KERNELRELEASE),) + # kbuild part of makefile + obj-m := 8123.o + 8123-y := 8123_if.o 8123_pci.o 8123_bin.o + + else + # Normal Makefile + + KERNELDIR := /lib/modules/`uname -r`/build + all:: + $(MAKE) -C $KERNELDIR M=`pwd` $@ + + # Module specific targets + genbin: + echo "X" > 8123_bini.o_shipped + + endif + + In example 1 the check for KERNELRELEASE is used to separate + the two parts of the Makefile. kbuild will only see the two + assignments whereas make will see everything except the two + kbuild assignments. + + In recent versions of the kernel, kbuild will look for a file named + Kbuild and as second option look for a file named Makefile. + Utilising the Kbuild file makes us split up the Makefile in example 1 + into two files as shown in example 2: + + Example 2: + --> filename: Kbuild + obj-m := 8123.o + 8123-y := 8123_if.o 8123_pci.o 8123_bin.o + + --> filename: Makefile + KERNELDIR := /lib/modules/`uname -r`/build + all:: + $(MAKE) -C $KERNELDIR M=`pwd` $@ + + # Module specific targets + genbin: + echo "X" > 8123_bin_shipped + + + In example 2 we are down to two fairly simple files and for simple + files as used in this example the split is questionable. But some + external modules use Makefiles of several hundred lines and here it + really pays off to separate the kbuild part from the rest. + Example 3 shows a backward compatible version. + + Example 3: + --> filename: Kbuild + obj-m := 8123.o + 8123-y := 8123_if.o 8123_pci.o 8123_bin.o + + --> filename: Makefile + ifneq ($(KERNELRELEASE),) + include Kbuild + else + # Normal Makefile + + KERNELDIR := /lib/modules/`uname -r`/build + all:: + $(MAKE) -C $KERNELDIR M=`pwd` $@ + + # Module specific targets + genbin: + echo "X" > 8123_bin_shipped + + endif + + The trick here is to include the Kbuild file from Makefile so + if an older version of kbuild picks up the Makefile the Kbuild + file will be included. + +--- 4.2 Binary blobs included in a module + + Some external modules needs to include a .o as a blob. kbuild + has support for this, but requires the blob file to be named + _shipped. In our example the blob is named + 8123_bin.o_shipped and when the kbuild rules kick in the file + 8123_bin.o is created as a simple copy off the 8213_bin.o_shipped file + with the _shipped part stripped of the filename. + This allows the 8123_bin.o filename to be used in the assignment to + the module. + + Example 4: + obj-m := 8123.o + 8123-y := 8123_if.o 8123_pci.o 8123_bin.o + + In example 4 there is no distinction between the ordinary .c/.h files + and the binary file. But kbuild will pick up different rules to create + the .o file. + + +=== 5. Include files + +Include files are a necessity when a .c file uses something from another .c +files (not strictly in the sense of .c but if good programming practice is +used). Any module that consist of more than one .c file will have a .h file +for one of the .c files. +- If the .h file only describes a module internal interface then the .h file + shall be placed in the same directory as the .c files. +- If the .h files describe an interface used by other parts of the kernel + located in different directories, the .h files shall be located in + include/linux/ or other include/ directories as appropriate. + +One exception for this rule is larger subsystems that have their own directory +under include/ such as include/scsi. Another exception is arch-specific +.h files which are located under include/asm-$(ARCH)/*. + +External modules have a tendency to locate include files in a separate include/ +directory and therefore needs to deal with this in their kbuild file. + +--- 5.1 How to include files from the kernel include dir + + When a module needs to include a file from include/linux/ then one + just uses: + + #include + + kbuild will make sure to add options to gcc so the relevant + directories are searched. + Likewise for .h files placed in the same directory as the .c file. + + #include "8123_if.h" + + will do the job. + +--- 5.2 External modules using an include/ dir + + External modules often locate their .h files in a separate include/ + directory although this is not usual kernel style. When an external + module uses an include/ dir then kbuild needs to be told so. + The trick here is to use either EXTRA_CFLAGS (take effect for all .c + files) or CFLAGS_$F.o (take effect only for a single file). + + In our example if we move 8123_if.h to a subdirectory named include/ + the resulting Kbuild file would look like: + + --> filename: Kbuild + obj-m := 8123.o + + EXTRA_CFLAGS := -Iinclude + 8123-y := 8123_if.o 8123_pci.o 8123_bin.o + + Note that in the assingment there is no space between -I and the path. + This is a kbuild limitation and no space must be present. + + +=== 6. Module installation + +Modules which are included in the kernel is installed in the directory: + + /lib/modules/$(KERNELRELEASE)/kernel + +External modules are installed in the directory: + + /lib/modules/$(KERNELRELEASE)/extra + +--- 6.1 INSTALL_MOD_PATH + + Above are the default directories, but as always some level of + customization is possible. One can prefix the path using the variable + INSTALL_MOD_PATH: + + $ make INSTALL_MOD_PATH=/frodo modules_install + => Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel + + INSTALL_MOD_PATH may be set as an ordinary shell variable or as in the + example above be specified on the commandline when calling make. + INSTALL_MOD_PATH has effect both when installing modules included in + the kernel as well as when installing external modules. + +--- 6.2 INSTALL_MOD_DIR + + When installing external modules they are default installed in a + directory under /lib/modules/$(KERNELRELEASE)/extra, but one may wish + to locate modules for a specific functionality in a separate + directory. For this purpose one can use INSTALL_MOD_DIR to specify an + alternative name than 'extra'. + + $ make INSTALL_MOD_DIR=gandalf -C KERNELDIR \ + M=`pwd` modules_install + => Install dir: /lib/modules/$(KERNELRELEASE)/gandalf + + +=== 7. Module versioning + +Module versioning are enabled by the CONFIG_MODVERSIONS tag. + +Module versioning is used as a simple ABI consistency check. The Module +versioning creates a CRC value of the full prototype for an exported symbol and +when a module is loaded/used then the CRC values contained in the kernel are +compared with similar values in the module. If they are not equal then the +kernel refuses to load the module. + +During a kernel build a file named Module.symvers will be generated. This +file includes the symbol version of all symbols within the kernel. If the +Module.symvers file is saved from the last full kernel compile one does not +have to do a full kernel compile to build a module version's compatible module. + +=== 8. Tips & Tricks + +--- 8.1 Testing for CONFIG_FOO_BAR + + Modules often needs to check for certain CONFIG_ options to decide if + a specific feature shall be included in the module. When kbuild is used + this is done by referencing the CONFIG_ variable directly. + + #fs/ext2/Makefile + obj-$(CONFIG_EXT2_FS) += ext2.o + + ext2-y := balloc.o bitmap.o dir.o + ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o + + External modules have traditionally used grep to check for specific + CONFIG_ settings directly in .config. This usage is broken. + As introduced before external modules shall use kbuild when building + and therefore can use the same methods as in-kernel modules when testing + for CONFIG_ definitions. + diff --git a/Documentation/keys.txt b/Documentation/keys.txt new file mode 100644 index 000000000..36cbb0dd0 --- /dev/null +++ b/Documentation/keys.txt @@ -0,0 +1,836 @@ + ============================ + KERNEL KEY RETENTION SERVICE + ============================ + +This service allows cryptographic keys, authentication tokens, cross-domain +user mappings, and similar to be cached in the kernel for the use of +filesystems other kernel services. + +Keyrings are permitted; these are a special type of key that can hold links to +other keys. Processes each have three standard keyring subscriptions that a +kernel service can search for relevant keys. + +The key service can be configured on by enabling: + + "Security options"/"Enable access key retention support" (CONFIG_KEYS) + +This document has the following sections: + + - Key overview + - Key service overview + - Key access permissions + - New procfs files + - Userspace system call interface + - Kernel services + - Defining a key type + - Request-key callback service + - Key access filesystem + + +============ +KEY OVERVIEW +============ + +In this context, keys represent units of cryptographic data, authentication +tokens, keyrings, etc.. These are represented in the kernel by struct key. + +Each key has a number of attributes: + + - A serial number. + - A type. + - A description (for matching a key in a search). + - Access control information. + - An expiry time. + - A payload. + - State. + + + (*) Each key is issued a serial number of type key_serial_t that is unique + for the lifetime of that key. All serial numbers are positive non-zero + 32-bit integers. + + Userspace programs can use a key's serial numbers as a way to gain access + to it, subject to permission checking. + + (*) Each key is of a defined "type". Types must be registered inside the + kernel by a kernel service (such as a filesystem) before keys of that + type can be added or used. Userspace programs cannot define new types + directly. + + Key types are represented in the kernel by struct key_type. This defines + a number of operations that can be performed on a key of that type. + + Should a type be removed from the system, all the keys of that type will + be invalidated. + + (*) Each key has a description. This should be a printable string. The key + type provides an operation to perform a match between the description on + a key and a criterion string. + + (*) Each key has an owner user ID, a group ID and a permissions mask. These + are used to control what a process may do to a key from userspace, and + whether a kernel service will be able to find the key. + + (*) Each key can be set to expire at a specific time by the key type's + instantiation function. Keys can also be immortal. + + (*) Each key can have a payload. This is a quantity of data that represent + the actual "key". In the case of a keyring, this is a list of keys to + which the keyring links; in the case of a user-defined key, it's an + arbitrary blob of data. + + Having a payload is not required; and the payload can, in fact, just be a + value stored in the struct key itself. + + When a key is instantiated, the key type's instantiation function is + called with a blob of data, and that then creates the key's payload in + some way. + + Similarly, when userspace wants to read back the contents of the key, if + permitted, another key type operation will be called to convert the key's + attached payload back into a blob of data. + + (*) Each key can be in one of a number of basic states: + + (*) Uninstantiated. The key exists, but does not have any data + attached. Keys being requested from userspace will be in this state. + + (*) Instantiated. This is the normal state. The key is fully formed, and + has data attached. + + (*) Negative. This is a relatively short-lived state. The key acts as a + note saying that a previous call out to userspace failed, and acts as + a throttle on key lookups. A negative key can be updated to a normal + state. + + (*) Expired. Keys can have lifetimes set. If their lifetime is exceeded, + they traverse to this state. An expired key can be updated back to a + normal state. + + (*) Revoked. A key is put in this state by userspace action. It can't be + found or operated upon (apart from by unlinking it). + + (*) Dead. The key's type was unregistered, and so the key is now useless. + + +==================== +KEY SERVICE OVERVIEW +==================== + +The key service provides a number of features besides keys: + + (*) The key service defines two special key types: + + (+) "keyring" + + Keyrings are special keys that contain a list of other keys. Keyring + lists can be modified using various system calls. Keyrings should not + be given a payload when created. + + (+) "user" + + A key of this type has a description and a payload that are arbitrary + blobs of data. These can be created, updated and read by userspace, + and aren't intended for use by kernel services. + + (*) Each process subscribes to three keyrings: a thread-specific keyring, a + process-specific keyring, and a session-specific keyring. + + The thread-specific keyring is discarded from the child when any sort of + clone, fork, vfork or execve occurs. A new keyring is created only when + required. + + The process-specific keyring is replaced with an empty one in the child + on clone, fork, vfork unless CLONE_THREAD is supplied, in which case it + is shared. execve also discards the process's process keyring and creates + a new one. + + The session-specific keyring is persistent across clone, fork, vfork and + execve, even when the latter executes a set-UID or set-GID binary. A + process can, however, replace its current session keyring with a new one + by using PR_JOIN_SESSION_KEYRING. It is permitted to request an anonymous + new one, or to attempt to create or join one of a specific name. + + The ownership of the thread and process-specific keyrings changes when + the real UID and GID of the thread changes. + + (*) Each user ID resident in the system holds two special keyrings: a user + specific keyring and a default user session keyring. The default session + keyring is initialised with a link to the user-specific keyring. + + When a process changes its real UID, if it used to have no session key, it + will be subscribed to the default session key for the new UID. + + If a process attempts to access its session key when it doesn't have one, + it will be subscribed to the default for its current UID. + + (*) Each user has two quotas against which the keys they own are tracked. One + limits the total number of keys and keyrings, the other limits the total + amount of description and payload space that can be consumed. + + The user can view information on this and other statistics through procfs + files. + + Process-specific and thread-specific keyrings are not counted towards a + user's quota. + + If a system call that modifies a key or keyring in some way would put the + user over quota, the operation is refused and error EDQUOT is returned. + + (*) There's a system call interface by which userspace programs can create + and manipulate keys and keyrings. + + (*) There's a kernel interface by which services can register types and + search for keys. + + (*) There's a way for the a search done from the kernel to call back to + userspace to request a key that can't be found in a process's keyrings. + + (*) An optional filesystem is available through which the key database can be + viewed and manipulated. + + +====================== +KEY ACCESS PERMISSIONS +====================== + +Keys have an owner user ID, a group access ID, and a permissions mask. The +mask has up to eight bits each for user, group and other access. Only five of +each set of eight bits are defined. These permissions granted are: + + (*) View + + This permits a key or keyring's attributes to be viewed - including key + type and description. + + (*) Read + + This permits a key's payload to be viewed or a keyring's list of linked + keys. + + (*) Write + + This permits a key's payload to be instantiated or updated, or it allows + a link to be added to or removed from a keyring. + + (*) Search + + This permits keyrings to be searched and keys to be found. Searches can + only recurse into nested keyrings that have search permission set. + + (*) Link + + This permits a key or keyring to be linked to. To create a link from a + keyring to a key, a process must have Write permission on the keyring and + Link permission on the key. + +For changing the ownership, group ID or permissions mask, being the owner of +the key or having the sysadmin capability is sufficient. + + +================ +NEW PROCFS FILES +================ + +Two files have been added to procfs by which an administrator can find out +about the status of the key service: + + (*) /proc/keys + + This lists all the keys on the system, giving information about their + type, description and permissions. The payload of the key is not + available this way: + + SERIAL FLAGS USAGE EXPY PERM UID GID TYPE DESCRIPTION: SUMMARY + 00000001 I----- 39 perm 1f0000 0 0 keyring _uid_ses.0: 1/4 + 00000002 I----- 2 perm 1f0000 0 0 keyring _uid.0: empty + 00000007 I----- 1 perm 1f0000 0 0 keyring _pid.1: empty + 0000018d I----- 1 perm 1f0000 0 0 keyring _pid.412: empty + 000004d2 I--Q-- 1 perm 1f0000 32 -1 keyring _uid.32: 1/4 + 000004d3 I--Q-- 3 perm 1f0000 32 -1 keyring _uid_ses.32: empty + 00000892 I--QU- 1 perm 1f0000 0 0 user metal:copper: 0 + 00000893 I--Q-N 1 35s 1f0000 0 0 user metal:silver: 0 + 00000894 I--Q-- 1 10h 1f0000 0 0 user metal:gold: 0 + + The flags are: + + I Instantiated + R Revoked + D Dead + Q Contributes to user's quota + U Under contruction by callback to userspace + N Negative key + + This file must be enabled at kernel configuration time as it allows anyone + to list the keys database. + + (*) /proc/key-users + + This file lists the tracking data for each user that has at least one key + on the system. Such data includes quota information and statistics: + + [root@andromeda root]# cat /proc/key-users + 0: 46 45/45 1/100 13/10000 + 29: 2 2/2 2/100 40/10000 + 32: 2 2/2 2/100 40/10000 + 38: 2 2/2 2/100 40/10000 + + The format of each line is + : User ID to which this applies + Structure refcount + / Total number of keys and number instantiated + / Key count quota + / Key size quota + + +=============================== +USERSPACE SYSTEM CALL INTERFACE +=============================== + +Userspace can manipulate keys directly through three new syscalls: add_key, +request_key and keyctl. The latter provides a number of functions for +manipulating keys. + +When referring to a key directly, userspace programs should use the key's +serial number (a positive 32-bit integer). However, there are some special +values available for referring to special keys and keyrings that relate to the +process making the call: + + CONSTANT VALUE KEY REFERENCED + ============================== ====== =========================== + KEY_SPEC_THREAD_KEYRING -1 thread-specific keyring + KEY_SPEC_PROCESS_KEYRING -2 process-specific keyring + KEY_SPEC_SESSION_KEYRING -3 session-specific keyring + KEY_SPEC_USER_KEYRING -4 UID-specific keyring + KEY_SPEC_USER_SESSION_KEYRING -5 UID-session keyring + KEY_SPEC_GROUP_KEYRING -6 GID-specific keyring + + +The main syscalls are: + + (*) Create a new key of given type, description and payload and add it to the + nominated keyring: + + key_serial_t add_key(const char *type, const char *desc, + const void *payload, size_t plen, + key_serial_t keyring); + + If a key of the same type and description as that proposed already exists + in the keyring, this will try to update it with the given payload, or it + will return error EEXIST if that function is not supported by the key + type. The process must also have permission to write to the key to be + able to update it. The new key will have all user permissions granted and + no group or third party permissions. + + Otherwise, this will attempt to create a new key of the specified type + and description, and to instantiate it with the supplied payload and + attach it to the keyring. In this case, an error will be generated if the + process does not have permission to write to the keyring. + + The payload is optional, and the pointer can be NULL if not required by + the type. The payload is plen in size, and plen can be zero for an empty + payload. + + A new keyring can be generated by setting type "keyring", the keyring + name as the description (or NULL) and setting the payload to NULL. + + User defined keys can be created by specifying type "user". It is + recommended that a user defined key's description by prefixed with a type + ID and a colon, such as "krb5tgt:" for a Kerberos 5 ticket granting + ticket. + + Any other type must have been registered with the kernel in advance by a + kernel service such as a filesystem. + + The ID of the new or updated key is returned if successful. + + + (*) Search the process's keyrings for a key, potentially calling out to + userspace to create it. + + key_serial_t request_key(const char *type, const char *description, + const char *callout_info, + key_serial_t dest_keyring); + + This function searches all the process's keyrings in the order thread, + process, session for a matching key. This works very much like + KEYCTL_SEARCH, including the optional attachment of the discovered key to + a keyring. + + If a key cannot be found, and if callout_info is not NULL, then + /sbin/request-key will be invoked in an attempt to obtain a key. The + callout_info string will be passed as an argument to the program. + + +The keyctl syscall functions are: + + (*) Map a special key ID to a real key ID for this process: + + key_serial_t keyctl(KEYCTL_GET_KEYRING_ID, key_serial_t id, + int create); + + The special key specified by "id" is looked up (with the key being + created if necessary) and the ID of the key or keyring thus found is + returned if it exists. + + If the key does not yet exist, the key will be created if "create" is + non-zero; and the error ENOKEY will be returned if "create" is zero. + + + (*) Replace the session keyring this process subscribes to with a new one: + + key_serial_t keyctl(KEYCTL_JOIN_SESSION_KEYRING, const char *name); + + If name is NULL, an anonymous keyring is created attached to the process + as its session keyring, displacing the old session keyring. + + If name is not NULL, if a keyring of that name exists, the process + attempts to attach it as the session keyring, returning an error if that + is not permitted; otherwise a new keyring of that name is created and + attached as the session keyring. + + To attach to a named keyring, the keyring must have search permission for + the process's ownership. + + The ID of the new session keyring is returned if successful. + + + (*) Update the specified key: + + long keyctl(KEYCTL_UPDATE, key_serial_t key, const void *payload, + size_t plen); + + This will try to update the specified key with the given payload, or it + will return error EOPNOTSUPP if that function is not supported by the key + type. The process must also have permission to write to the key to be + able to update it. + + The payload is of length plen, and may be absent or empty as for + add_key(). + + + (*) Revoke a key: + + long keyctl(KEYCTL_REVOKE, key_serial_t key); + + This makes a key unavailable for further operations. Further attempts to + use the key will be met with error EKEYREVOKED, and the key will no longer + be findable. + + + (*) Change the ownership of a key: + + long keyctl(KEYCTL_CHOWN, key_serial_t key, uid_t uid, gid_t gid); + + This function permits a key's owner and group ID to be changed. Either + one of uid or gid can be set to -1 to suppress that change. + + Only the superuser can change a key's owner to something other than the + key's current owner. Similarly, only the superuser can change a key's + group ID to something other than the calling process's group ID or one of + its group list members. + + + (*) Change the permissions mask on a key: + + long keyctl(KEYCTL_SETPERM, key_serial_t key, key_perm_t perm); + + This function permits the owner of a key or the superuser to change the + permissions mask on a key. + + Only bits the available bits are permitted; if any other bits are set, + error EINVAL will be returned. + + + (*) Describe a key: + + long keyctl(KEYCTL_DESCRIBE, key_serial_t key, char *buffer, + size_t buflen); + + This function returns a summary of the key's attributes (but not its + payload data) as a string in the buffer provided. + + Unless there's an error, it always returns the amount of data it could + produce, even if that's too big for the buffer, but it won't copy more + than requested to userspace. If the buffer pointer is NULL then no copy + will take place. + + A process must have view permission on the key for this function to be + successful. + + If successful, a string is placed in the buffer in the following format: + + ;;;; + + Where type and description are strings, uid and gid are decimal, and perm + is hexadecimal. A NUL character is included at the end of the string if + the buffer is sufficiently big. + + This can be parsed with + + sscanf(buffer, "%[^;];%d;%d;%o;%s", type, &uid, &gid, &mode, desc); + + + (*) Clear out a keyring: + + long keyctl(KEYCTL_CLEAR, key_serial_t keyring); + + This function clears the list of keys attached to a keyring. The calling + process must have write permission on the keyring, and it must be a + keyring (or else error ENOTDIR will result). + + + (*) Link a key into a keyring: + + long keyctl(KEYCTL_LINK, key_serial_t keyring, key_serial_t key); + + This function creates a link from the keyring to the key. The process + must have write permission on the keyring and must have link permission + on the key. + + Should the keyring not be a keyring, error ENOTDIR will result; and if + the keyring is full, error ENFILE will result. + + The link procedure checks the nesting of the keyrings, returning ELOOP if + it appears to deep or EDEADLK if the link would introduce a cycle. + + + (*) Unlink a key or keyring from another keyring: + + long keyctl(KEYCTL_UNLINK, key_serial_t keyring, key_serial_t key); + + This function looks through the keyring for the first link to the + specified key, and removes it if found. Subsequent links to that key are + ignored. The process must have write permission on the keyring. + + If the keyring is not a keyring, error ENOTDIR will result; and if the + key is not present, error ENOENT will be the result. + + + (*) Search a keyring tree for a key: + + key_serial_t keyctl(KEYCTL_SEARCH, key_serial_t keyring, + const char *type, const char *description, + key_serial_t dest_keyring); + + This searches the keyring tree headed by the specified keyring until a + key is found that matches the type and description criteria. Each keyring + is checked for keys before recursion into its children occurs. + + The process must have search permission on the top level keyring, or else + error EACCES will result. Only keyrings that the process has search + permission on will be recursed into, and only keys and keyrings for which + a process has search permission can be matched. If the specified keyring + is not a keyring, ENOTDIR will result. + + If the search succeeds, the function will attempt to link the found key + into the destination keyring if one is supplied (non-zero ID). All the + constraints applicable to KEYCTL_LINK apply in this case too. + + Error ENOKEY, EKEYREVOKED or EKEYEXPIRED will be returned if the search + fails. On success, the resulting key ID will be returned. + + + (*) Read the payload data from a key: + + key_serial_t keyctl(KEYCTL_READ, key_serial_t keyring, char *buffer, + size_t buflen); + + This function attempts to read the payload data from the specified key + into the buffer. The process must have read permission on the key to + succeed. + + The returned data will be processed for presentation by the key type. For + instance, a keyring will return an array of key_serial_t entries + representing the IDs of all the keys to which it is subscribed. The user + defined key type will return its data as is. If a key type does not + implement this function, error EOPNOTSUPP will result. + + As much of the data as can be fitted into the buffer will be copied to + userspace if the buffer pointer is not NULL. + + On a successful return, the function will always return the amount of + data available rather than the amount copied. + + + (*) Instantiate a partially constructed key. + + key_serial_t keyctl(KEYCTL_INSTANTIATE, key_serial_t key, + const void *payload, size_t plen, + key_serial_t keyring); + + If the kernel calls back to userspace to complete the instantiation of a + key, userspace should use this call to supply data for the key before the + invoked process returns, or else the key will be marked negative + automatically. + + The process must have write access on the key to be able to instantiate + it, and the key must be uninstantiated. + + If a keyring is specified (non-zero), the key will also be linked into + that keyring, however all the constraints applying in KEYCTL_LINK apply + in this case too. + + The payload and plen arguments describe the payload data as for add_key(). + + + (*) Negatively instantiate a partially constructed key. + + key_serial_t keyctl(KEYCTL_NEGATE, key_serial_t key, + unsigned timeout, key_serial_t keyring); + + If the kernel calls back to userspace to complete the instantiation of a + key, userspace should use this call mark the key as negative before the + invoked process returns if it is unable to fulfil the request. + + The process must have write access on the key to be able to instantiate + it, and the key must be uninstantiated. + + If a keyring is specified (non-zero), the key will also be linked into + that keyring, however all the constraints applying in KEYCTL_LINK apply + in this case too. + + +=============== +KERNEL SERVICES +=============== + +The kernel services for key managment are fairly simple to deal with. They can +be broken down into two areas: keys and key types. + +Dealing with keys is fairly straightforward. Firstly, the kernel service +registers its type, then it searches for a key of that type. It should retain +the key as long as it has need of it, and then it should release it. For a +filesystem or device file, a search would probably be performed during the +open call, and the key released upon close. How to deal with conflicting keys +due to two different users opening the same file is left to the filesystem +author to solve. + +When accessing a key's payload data, the key->lock should be at least read +locked, or else the data may be changed by update during the access. + +(*) To search for a key, call: + + struct key *request_key(const struct key_type *type, + const char *description, + const char *callout_string); + + This is used to request a key or keyring with a description that matches + the description specified according to the key type's match function. This + permits approximate matching to occur. If callout_string is not NULL, then + /sbin/request-key will be invoked in an attempt to obtain the key from + userspace. In that case, callout_string will be passed as an argument to + the program. + + Should the function fail error ENOKEY, EKEYEXPIRED or EKEYREVOKED will be + returned. + + +(*) When it is no longer required, the key should be released using: + + void key_put(struct key *key); + + This can be called from interrupt context. If CONFIG_KEYS is not set then + the argument will not be parsed. + + +(*) Extra references can be made to a key by calling the following function: + + struct key *key_get(struct key *key); + + These need to be disposed of by calling key_put() when they've been + finished with. The key pointer passed in will be returned. If the pointer + is NULL or CONFIG_KEYS is not set then the key will not be dereferenced and + no increment will take place. + + +(*) A key's serial number can be obtained by calling: + + key_serial_t key_serial(struct key *key); + + If key is NULL or if CONFIG_KEYS is not set then 0 will be returned (in the + latter case without parsing the argument). + + +(*) If a keyring was found in the search, this can be further searched by: + + struct key *keyring_search(struct key *keyring, + const struct key_type *type, + const char *description) + + This searches the keyring tree specified for a matching key. Error ENOKEY + is returned upon failure. If successful, the returned key will need to be + released. + + +(*) To check the validity of a key, this function can be called: + + int validate_key(struct key *key); + + This checks that the key in question hasn't expired or and hasn't been + revoked. Should the key be invalid, error EKEYEXPIRED or EKEYREVOKED will + be returned. If the key is NULL or if CONFIG_KEYS is not set then 0 will be + returned (in the latter case without parsing the argument). + + +(*) To register a key type, the following function should be called: + + int register_key_type(struct key_type *type); + + This will return error EEXIST if a type of the same name is already + present. + + +(*) To unregister a key type, call: + + void unregister_key_type(struct key_type *type); + + +=================== +DEFINING A KEY TYPE +=================== + +A kernel service may want to define its own key type. For instance, an AFS +filesystem might want to define a Kerberos 5 ticket key type. To do this, it +author fills in a struct key_type and registers it with the system. + +The structure has a number of fields, some of which are mandatory: + + (*) const char *name + + The name of the key type. This is used to translate a key type name + supplied by userspace into a pointer to the structure. + + + (*) size_t def_datalen + + This is optional - it supplies the default payload data length as + contributed to the quota. If the key type's payload is always or almost + always the same size, then this is a more efficient way to do things. + + The data length (and quota) on a particular key can always be changed + during instantiation or update by calling: + + int key_payload_reserve(struct key *key, size_t datalen); + + With the revised data length. Error EDQUOT will be returned if this is + not viable. + + + (*) int (*instantiate)(struct key *key, const void *data, size_t datalen); + + This method is called to attach a payload to a key during + construction. The payload attached need not bear any relation to the data + passed to this function. + + If the amount of data attached to the key differs from the size in + keytype->def_datalen, then key_payload_reserve() should be called. + + + (*) int (*duplicate)(struct key *key, const struct key *source); + + If this type of key can be duplicated, then this method should be + provided. It is called to copy the payload attached to the source into + the new key. The data length on the new key will have been updated and + the quota adjusted already. + + The source key will be locked against change on the source->sem, so it is + safe to sleep here. + + + (*) int (*update)(struct key *key, const void *data, size_t datalen); + + If this type of key can be updated, then this method should be + provided. It is called to update a key's payload from the blob of data + provided. + + key_payload_reserve() should be called if the data length might change + before any changes are actually made. Note that if this succeeds, the + type is committed to changing the key because it's already been altered, + so all memory allocation must be done first. + + The key will be locked against other changers on key->sem, so it is safe + to sleep here. + + key_payload_reserve() should be called with the key->lock write locked, + and the changes to the key's attached payload should be made before the + key is locked. + + + (*) int (*match)(const struct key *key, const void *desc); + + This method is called to match a key against a description. It should + return non-zero if the two match, zero if they don't. + + + (*) void (*destroy)(struct key *key); + + This method is optional. It is called to discard the payload data on a + key when it is being destroyed. + + + (*) void (*describe)(const struct key *key, struct seq_file *p); + + This method is optional. It is called during /proc/keys reading to + summarise a key in text form. + + + (*) long (*read)(const struct key *key, char __user *buffer, size_t buflen); + + This method is optional. It is called by KEYCTL_READ to translate the + key's payload into something a blob of data for userspace to deal + with. Ideally, the blob should be in the same format as that passed in to + the instantiate and update methods. + + If successful, the blob size that could be produced should be returned + rather than the size copied. + + +============================ +REQUEST-KEY CALLBACK SERVICE +============================ + +To create a new key, the kernel will attempt to execute the following command +line: + + /sbin/request-key create \ + + + is the key being constructed, and the three keyrings are the process +keyrings from the process that caused the search to be issued. These are +included for two reasons: + + (1) There may be an authentication token in one of the keyrings that is + required to obtain the key, eg: a Kerberos Ticket-Granting Ticket. + + (2) The new key should probably be cached in one of these rings. + +This program should set it UID and GID to those specified before attempting to +access any more keys. It may then look around for a user specific process to +hand the request off to (perhaps a path held in placed in another key by, for +example, the KDE desktop manager). + +The program (or whatever it calls) should finish construction of the key by +calling KEYCTL_INSTANTIATE, which also permits it to cache the key in one of +the keyrings (probably the session ring) before returning. Alternatively, the +key can be marked as negative with KEYCTL_NEGATE; this also permits the key to +be cached in one of the keyrings. + +If it returns with the key remaining in the unconstructed state, the key will +be marked as being negative, it will be added to the session keyring, and an +error will be returned to the key requestor. + +Supplementary information may be provided from whoever or whatever invoked +this service. This will be passed as the parameter. If no such +information was made available, then "-" will be passed as this parameter +instead. + + +Similarly, the kernel may attempt to update an expired or a soon to expire key +by executing: + + /sbin/request-key update \ + + +In this case, the program isn't required to actually attach the key to a ring; +the rings are provided for reference. diff --git a/Documentation/memory.txt b/Documentation/memory.txt index 7af1709e8..2b3dedd39 100644 --- a/Documentation/memory.txt +++ b/Documentation/memory.txt @@ -21,6 +21,8 @@ systems. All of these problems can be addressed with the "mem=XXXM" boot option (where XXX is the size of RAM to use in megabytes). It can also tell Linux to use less memory than is actually installed. +If you use "mem=" on a machine with PCI, consider using "memmap=" to avoid +physical address space collisions. See the documentation of your boot loader (LILO, loadlin, etc.) about how to pass options to the kernel. @@ -44,7 +46,9 @@ Try: * Disabling the cache from the BIOS. * Try passing the "mem=4M" option to the kernel to limit - Linux to using a very small amount of memory. + Linux to using a very small amount of memory. Use "memmap="-option + together with "mem=" on systems with PCI to avoid physical address + space collisions. Other tricks: diff --git a/Documentation/networking/e100.txt b/Documentation/networking/e100.txt index 0b2b7051a..e4b6c7afc 100644 --- a/Documentation/networking/e100.txt +++ b/Documentation/networking/e100.txt @@ -1,14 +1,16 @@ Linux* Base Driver for the Intel(R) PRO/100 Family of Adapters ============================================================== -March 15, 2004 +September 13, 2004 Contents ======== - In This Release -- Supported Adapters +- Identifying Your Adapter +- Driver Configuration Parameters +- Additional Configurations - Support @@ -16,26 +18,140 @@ In This Release =============== This file describes the Linux* Base Driver for the Intel(R) PRO/100 Family of -Adapters, version 3.x.x. This driver includes support for Itanium(TM)-based -systems. +Adapters, version 3.2.x. This driver includes support for Itanium(TM)2 and +EM64T systems. -Supported Adapters -================== - -To verify that your adapter is supported, find the board ID number on the -adapter. Look for a label that has a barcode and a number in the format -A12345-001. Match this to the list of numbers above. +Identifying Your Adapter +======================== For more information on how to identify your adapter, go to the Adapter & Driver ID Guide at: http://support.intel.com/support/network/adapter/pro100/21397.htm -For the latest Intel PRO/100 network driver for Linux, see: +For the latest Intel network drivers for Linux, refer to the following +website. In the search field, enter your adapter name or type, or use the +networking link on the left to search for your adapter: http://downloadfinder.intel.com/scripts-df/support_intel.asp +Driver Configuration Parameters +=============================== + +The default value for each parameter is generally the recommended setting, +unless otherwise noted. + +Rx Descriptors: Number of receive descriptors. A receive descriptor is a data + structure that describes a receive buffer and its attributes to the network + controller. The data in the descriptor is used by the controller to write + data from the controller to host memory. In the 3.0.x driver the valid + range for this parameter is 64-256. The default value is 64. This parameter + can be changed using the command + + ethtool -G eth? rx n, where n is the number of desired rx descriptors. + +Tx Descriptors: Number of transmit descriptors. A transmit descriptor is a + data structure that describes a transmit buffer and its attributes to the + network controller. The data in the descriptor is used by the controller to + read data from the host memory to the controller. In the 3.0.x driver the + valid range for this parameter is 64-256. The default value is 64. This + parameter can be changed using the command + + ethtool -G eth? tx n, where n is the number of desired tx descriptors. + +Speed/Duplex: The driver auto-negotiates the link speed and duplex settings by + default. Ethtool can be used as follows to force speed/duplex. + + ethtool -s eth? autoneg off speed {10|100} duplex {full|half} + + NOTE: setting the speed/duplex to incorrect values will cause the link to + fail. + +Event Log Message Level: The driver uses the message level flag to log events + to syslog. The message level can be set at driver load time. It can also be + set using the command + + ethtool -s eth? msglvl n + +Additional Configurations +========================= + + Configuring the Driver on Different Distributions + ------------------------------------------------- + + Configuring a network driver to load properly when the system is started is + distribution dependent. Typically, the configuration process involves adding + an alias line to /etc/modules.conf as well as editing other system startup + scripts and/or configuration files. Many popular Linux distributions ship + with tools to make these changes for you. To learn the proper way to + configure a network device for your system, refer to your distribution + documentation. If during this process you are asked for the driver or module + name, the name for the Linux Base Driver for the Intel PRO/100 Family of + Adapters is e100. + + As an example, if you install the e100 driver for two PRO/100 adapters + (eth0 and eth1), add the following to modules.conf: + + alias eth0 e100 + alias eth1 e100 + + Viewing Link Messages + --------------------- + In order to see link messages and other Intel driver information on your + console, you must set the dmesg level up to six. This can be done by + entering the following on the command line before loading the e100 driver: + + dmesg -n 8 + + If you wish to see all messages issued by the driver, including debug + messages, set the dmesg level to eight. + + NOTE: This setting is not saved across reboots. + + Ethtool + ------- + + The driver utilizes the ethtool interface for driver configuration and + diagnostics, as well as displaying statistical information. Ethtool + version 1.6 or later is required for this functionality. + + The latest release of ethtool can be found at: + http://sf.net/projects/gkernel. + + After ethtool is installed, ethtool-copy.h must be copied and renamed to + ethtool.h in your kernel source tree at /include/linux. + Backup the original ethtool.h as needed before copying. The driver then + must be recompiled in order to take advantage of the latest ethtool + features. + + NOTE: This driver uses mii support from the kernel. As a result, when + there is no link, ethtool will report speed/duplex to be 10/half. + + NOTE: Ethtool 1.6 only supports a limited set of ethtool options. Support + for a more complete ethtool feature set can be enabled by upgrading + ethtool to ethtool-1.8.1. + + Enabling Wake on LAN* (WoL) + --------------------------- + WoL is provided through the Ethtool* utility. Ethtool is included with Red + Hat* 8.0. For other Linux distributions, download and install Ethtool from + the following website: http://sourceforge.net/projects/gkernel. + + For instructions on enabling WoL with Ethtool, refer to the Ethtool man + page. + + WoL will be enabled on the system during the next shut down or reboot. For + this driver version, in order to enable WoL, the e100 driver must be + loaded when shutting down or rebooting the system. + + NAPI + ---- + + NAPI (Rx polling mode) is supported in the e100 driver. NAPI is enabled + or disabled based on the configuration of the kernel. + + See www.cyberus.ca/~hadi/usenix-paper.tgz for more information on NAPI. Support ======= diff --git a/Documentation/networking/e1000.txt b/Documentation/networking/e1000.txt index 9b2329f99..794c92542 100644 --- a/Documentation/networking/e1000.txt +++ b/Documentation/networking/e1000.txt @@ -1,14 +1,14 @@ Linux* Base Driver for the Intel(R) PRO/1000 Family of Adapters =============================================================== -January 8, 2003 +September 13, 2004 Contents ======== - In This Release -- Supported Adapters +- Identifying Your Adapter - Command Line Parameters - Speed and Duplex Configuration - Additional Configurations @@ -20,63 +20,29 @@ In This Release =============== This file describes the Linux* Base Driver for the Intel(R) PRO/1000 Family -of Adapters, version 5.0.x. This driver includes support for -Itanium(TM)-based systems. +of Adapters, version 5.x.x. This driver includes support for Itanium(TM)2 +and EM64T systems. +For questions related to hardware requirements, refer to the documentation +supplied with your Intel PRO/1000 adapter. All hardware requirements listed +apply to use with Linux. Native VLANs are now available with supported kernels. - -Supported Adapters -================== - -The following Intel network adapters are compatible with the drivers in this -release: - - Controller Adapter Name Board IDs - ---------- ------------ --------- - - 82542 PRO/1000 Gigabit Server Adapter 700262-xxx, 717037-xxx - - 82543 PRO/1000 F Server Adapter 738640-xxx, A38888-xxx - - 82543 PRO/1000 T Server Adapter A19845-xxx, A33948-xxx - - 82544 PRO/1000 XT Server Adapter A51580-xxx - - 82544 PRO/1000 XF Server Adapter A50484-xxx - - 82544 PRO/1000 T Desktop Adapter A62947-xxx - - 82540 PRO/1000 MT Desktop Adapter A78408-xxx - 82541 C91016-xxx - - 82545 PRO/1000 MT Server Adapter A92165-xxx - - 82546 PRO/1000 MT Dual Port Server Adapter A92111-xxx - - 82545 PRO/1000 MF Server Adapter A91622-xxx - - 82545 PRO/1000 MF Server Adapter(LX) A91624-xxx - - 82546 PRO/1000 MF Dual Port Server Adapter A91620-xxx - - - -To verify your Intel adapter is supported, find the board ID number on the -adapter. Look for a label that has a barcode and a number in the format -A12345-001. Match this to the list of numbers above. +Identifying Your Adapter +======================== For more information on how to identify your adapter, go to the Adapter & Driver ID Guide at: http://support.intel.com/support/network/adapter/pro100/21397.htm -For the latest Intel network drivers for Linux, refer to the following +For the latest Intel network drivers for Linux, refer to the following +website. In the search field, enter your adapter name or type, or use the +networking link on the left to search for your adapter: http://downloadfinder.intel.com/scripts-df/support_intel.asp - Command Line Parameters ======================= @@ -92,27 +58,39 @@ For example, with two PRO/1000 PCI adapters, entering: insmod e1000 TxDescriptors=80,128 -loads the e1000 driver with 80 TX resources for the first adapter and 128 TX -resources for the second adapter. +loads the e1000 driver with 80 TX descriptors for the first adapter and 128 TX +descriptors for the second adapter. The default value for each parameter is generally the recommended setting, -unless otherwise noted. +unless otherwise noted. Also, if the driver is statically built into the +kernel, the driver is loaded with the default values for all the parameters. +Ethtool can be used to change some of the parameters at runtime. + + NOTES: For more information about the AutoNeg, Duplex, and Speed + parameters, see the "Speed and Duplex Configuration" section in + this document. -For more information about the AutoNeg, Duplex, and Speed parameters, see the -"Speed and Duplex Configuration" section in this document. + For more information about the InterruptThrottleRate, RxIntDelay, + TxIntDelay, RxAbsIntDelay, and TxAbsIntDelay parameters, see the + application note at: + http://www.intel.com/design/network/applnots/ap450.htm + A descriptor describes a data buffer and attributes related to the + data buffer. This information is accessed by the hardware. AutoNeg (adapters using copper connections only) Valid Range: 0x01-0x0F, 0x20-0x2F Default Value: 0x2F This parameter is a bit mask that specifies which speed and duplex settings the board advertises. When this parameter is used, the Speed and - Duplex parameters must not be specified. + Duplex parameters must not be specified. + NOTE: Refer to the Speed and Duplex section of this readme for more + information on the AutoNeg parameter. Duplex (adapters using copper connections only) Valid Range: 0-2 (0=auto-negotiate, 1=half, 2=full) Default Value: 0 - Defines the direction in which data is allowed to flow. Can by either one + Defines the direction in which data is allowed to flow. Can be either one or two-directional. If both Duplex and the link partner are set to auto- negotiate, the board auto-detects the correct duplex. If the link partner is forced (either full or half), Duplex defaults to half-duplex. @@ -125,22 +103,46 @@ Default: Read flow control settings from the EEPROM InterruptThrottleRate Valid Range: 100-100000 (0=off, 1=dynamic) -Default Value: 1 +Default Value: 8000 This value represents the maximum number of interrupts per second the controller generates. InterruptThrottleRate is another setting used in interrupt moderation. Dynamic mode uses a heuristic algorithm to adjust InterruptThrottleRate based on the current traffic load. +Un-supported Adapters: InterruptThrottleRate is NOT supported by 82542, 82543 + or 82544-based adapters. NOTE: InterruptThrottleRate takes precedence over the TxAbsIntDelay and RxAbsIntDelay parameters. In other words, minimizing the receive and/or transmit absolute delays does not force the controller to generate more interrupts than what the Interrupt Throttle Rate allows. + CAUTION: If you are using the Intel PRO/1000 CT Network Connection + (controller 82547), setting InterruptThrottleRate to a value + greater than 75,000, may hang (stop transmitting) adapters under + certain network conditions. If this occurs a NETDEV WATCHDOG + message is logged in the system event log. In addition, the + controller is automatically reset, restoring the network + connection. To eliminate the potential for the hang, ensure + that InterruptThrottleRate is set no greater than 75,000 and is + not set to 0. + NOTE: When e1000 is loaded with default settings and multiple adapters are + in use simultaneously, the CPU utilization may increase non-linearly. + In order to limit the CPU utilization without impacting the overall + throughput, we recommend that you load the driver as follows: + + insmod e1000.o InterruptThrottleRate=3000,3000,3000 + + This sets the InterruptThrottleRate to 3000 interrupts/sec for the + first, second, and third instances of the driver. The range of 2000 to + 3000 interrupts per second works on a majority of systems and is a + good starting point, but the optimal value will be platform-specific. + If CPU utilization is not a concern, use RX_POLLING (NAPI) and default + driver settings. RxDescriptors Valid Range: 80-256 for 82542 and 82543-based adapters - 80-4096 for 82540, 82544, 82545, and 82546-based adapters -Default Value: 80 + 80-4096 for all other supported adapters +Default Value: 256 This value is the number of receive descriptors allocated by the driver. Increasing this value allows the driver to buffer more incoming packets. Each descriptor is 16 bytes. A receive buffer is also allocated for each @@ -149,6 +151,9 @@ Default Value: 80 NOTE: MTU designates the frame size. It only needs to be set for Jumbo Frames. + NOTE: Depending on the available system resources, the request for a + higher number of receive descriptors may be denied. In this case, + use a lower number. RxIntDelay Valid Range: 0-65535 (0=off) @@ -168,11 +173,11 @@ Default Value: 0 restoring the network connection. To eliminate the potential for the hang ensure that RxIntDelay is set to 0. -RxAbsIntDelay (82540, 82545, and 82546-based adapters only) +RxAbsIntDelay (82540, 82545 and later adapters only) Valid Range: 0-65535 (0=off) Default Value: 128 This value, in units of 1.024 microseconds, limits the delay in which a - transmit interrupt is generated. Useful only if RxIntDelay is non-zero, + receive interrupt is generated. Useful only if RxIntDelay is non-zero, this value ensures that an interrupt is generated after the initial packet is received within the set amount of time. Proper tuning, along with RxIntDelay, may improve traffic throughput in specific network @@ -188,12 +193,16 @@ Default Value: 0 (auto-negotiate at all supported speeds) TxDescriptors Valid Range: 80-256 for 82542 and 82543-based adapters - 80-4096 for 82540, 82544, 82545, and 82546-based adapters + 80-4096 for all other supported adapters Default Value: 256 This value is the number of transmit descriptors allocated by the driver. Increasing this value allows the driver to queue more transmits. Each descriptor is 16 bytes. + NOTE: Depending on the available system resources, the request for a + higher number of transmit descriptors may be denied. In this case, + use a lower number. + TxIntDelay Valid Range: 0-65535 (0=off) Default Value: 64 @@ -203,7 +212,7 @@ Default Value: 64 system is reporting dropped transmits, this value may be set too high causing the driver to run out of available transmit descriptors. -TxAbsIntDelay (82540, 82545, and 82546-based adapters only) +TxAbsIntDelay (82540, 82545 and later adapters only) Valid Range: 0-65535 (0=off) Default Value: 64 This value, in units of 1.024 microseconds, limits the delay in which a @@ -219,7 +228,6 @@ Default Value: 1 A value of '1' indicates that the driver should enable IP checksum offload for received packets (both UDP and TCP) to the adapter hardware. - Speed and Duplex Configuration ============================== @@ -251,6 +259,10 @@ Bit 7 6 5 4 3 2 1 0 Speed (Mbps) N/A N/A 1000 N/A 100 100 10 10 Duplex Full Full Half Full Half +For example to limit the negotiated speed/duplex on the interface to 10 Mbps +Half or Full duplex, set AutoNeg to 0x02: + insmod e1000 AutoNeg=0x02 + Note that setting AutoNeg does not guarantee that the board will link at the highest specified speed or duplex mode, but the board will link at the highest possible speed/duplex of the link partner IF the link partner is also @@ -261,6 +273,38 @@ adapter MUST be forced to the same speed/duplex. Additional Configurations ========================= + Configuring the Driver on Different Distributions + ------------------------------------------------- + + Configuring a network driver to load properly when the system is started is + distribution dependent. Typically, the configuration process involves adding + an alias line to /etc/modules.conf as well as editing other system startup + scripts and/or configuration files. Many popular Linux distributions ship + with tools to make these changes for you. To learn the proper way to + configure a network device for your system, refer to your distribution + documentation. If during this process you are asked for the driver or module + name, the name for the Linux Base Driver for the Intel PRO/1000 Family of + Adapters is e1000. + + As an example, if you install the e1000 driver for two PRO/1000 adapters + (eth0 and eth1) and set the speed and duplex to 10full and 100half, add the + following to modules.conf: + + alias eth0 e1000 + alias eth1 e1000 + options e1000 Speed=10,100 Duplex=2,1 + + Viewing Link Messages + --------------------- + + Link messages will not be displayed to the console if the distribution is + restricting system messages. In order to see network driver link messages on + your console, set dmesg to eight by entering the following: + + dmesg -n 8 + + NOTE: This setting is not saved across reboots. + Jumbo Frames ------------ @@ -278,6 +322,51 @@ Additional Configurations 10 or 100 Mbps may result in poor performance or loss of link. + NOTE: MTU designates the frame size. To enable Jumbo Frames, increase the + MTU size on the interface beyond 1500. + + Ethtool + ------- + + The driver utilizes the ethtool interface for driver configuration and + diagnostics, as well as displaying statistical information. Ethtool + version 1.6 or later is required for this functionality. + + The latest release of ethtool can be found from + http://sf.net/projects/gkernel. After ethtool is installed, + ethtool-copy.h must be copied and renamed to ethtool.h in your kernel + source tree at /include/linux. Backup the original + ethtool.h as needed before copying. The driver then must be recompiled + in order to take advantage of the latest ethtool features. + + NOTE: Ethtool 1.6 only supports a limited set of ethtool options. Support + for a more complete ethtool feature set can be enabled by upgrading + ethtool to ethtool-1.8.1. + + Enabling Wake on LAN* (WoL) + --------------------------- + + WoL is configured through the Ethtool* utility. Ethtool is included with + all versions of Red Hat after Red Hat 7.2. For other Linux distributions, + download and install Ethtool from the following website: + http://sourceforge.net/projects/gkernel. + + For instructions on enabling WoL with Ethtool, refer to the website listed + above. + + WoL will be enabled on the system during the next shut down or reboot. + For this driver version, in order to enable WoL, the e1000 driver must be + loaded when shutting down or rebooting the system. + + NAPI + ---- + + NAPI (Rx polling mode) is supported in the e1000 driver. NAPI is enabled + or disabled based on the configuration of the kernel. + + See www.cyberus.ca/~hadi/usenix-paper.tgz for more information on NAPI. + + Known Issues ============ @@ -285,9 +374,9 @@ Known Issues ------------------------------- Memory allocation failures have been observed on Linux systems with 64 MB - of RAM or less that are running Jumbo Frames. If you are using Jumbo - Frames, your system may require more than the advertised minimum - requirement of 64 MB of system memory. + of RAM or less that are running Jumbo Frames. If you are using Jumbo Frames, + your system may require more than the advertised minimum requirement of 64 MB + of system memory. Support diff --git a/Documentation/networking/ixgb.txt b/Documentation/networking/ixgb.txt index 993090c41..c62d588ed 100644 --- a/Documentation/networking/ixgb.txt +++ b/Documentation/networking/ixgb.txt @@ -1,14 +1,14 @@ Linux* Base Driver for the Intel(R) PRO/10GbE Family of Adapters ================================================================ -January 06, 2003 +September 13, 2004 Contents ======== - In This Release -- Supported Adapters +- Identifying Your Adapter - Command Line Parameters - Improving Performance - Support @@ -18,36 +18,23 @@ In This Release =============== This file describes the Linux* Base Driver for the Intel(R) PRO/10GbE Family -of Adapters, version 1.0.x. This driver is intended for 2.4.x kernels; it is -known to build properly on 2.4.x kernels through 2.4.18. Intel focused -testing on Intel architectures running kernels 2.4.18. This driver includes -support for Itanium(TM)-based systems. +of Adapters, version 1.0.x. This driver includes support for Itanium(TM)2 and +EM64T systems. For questions related to hardware requirements, refer to the documentation supplied with your Intel PRO/10GbE adapter. All hardware requirements listed apply to use with Linux. - -Supported Adapters -================== - -The following Intel network adapters are compatible with the drivers in this -release: - - Controller Adapter Name Board IDs - ---------- ------------ --------- - - 82597EX Intel(R) PRO/10GbE LR Server Adapter A82505-xxx - +Identifying Your Adapter +======================== To verify your Intel adapter is supported, find the board ID number on the adapter. Look for a label that has a barcode and a number in the format -A12345-001. Match this to the list of numbers above. +A12345-001. -For more information on how to identify your adapter, go to the Adapter & -Driver ID Guide at: +Use the above information and the Adapter & Driver ID Guide at: - http://support.intel.com/support/network/adapter/pro100/21397.htm + http://support.intel.com/support/network/adapter/pro100/21397.htm For the latest Intel network drivers for Linux, go to: @@ -72,8 +59,9 @@ loads the ixgb driver with 80 TX resources for the first adapter and 128 TX resources for the second adapter. The default value for each parameter is generally the recommended setting, -unless otherwise noted. - +unless otherwise noted. Also, if the driver is statically built into the +kernel, the driver is loaded with the default values for all the parameters. +Ethtool can be used to change some of the parameters at runtime. FlowControl Valid Range: 0-3 (0=none, 1=Rx only, 2=Tx only, 3=Rx&Tx) @@ -125,7 +113,6 @@ Default Value: 1 offload for transmitted packets (both UDP and TCP) to the adapter hardware. - Improving Performance ===================== diff --git a/Documentation/networking/proc_net_tcp.txt b/Documentation/networking/proc_net_tcp.txt new file mode 100644 index 000000000..59cb915c3 --- /dev/null +++ b/Documentation/networking/proc_net_tcp.txt @@ -0,0 +1,47 @@ +This document describes the interfaces /proc/net/tcp and /proc/net/tcp6. + +These /proc interfaces provide information about currently active TCP +connections, and are implemented by tcp_get_info() in net/ipv4/tcp_ipv4.c and +tcp6_get_info() in net/ipv6/tcp_ipv6.c, respectively. + +It will first list all listening TCP sockets, and next list all established +TCP connections. A typical entry of /proc/net/tcp would look like this (split +up into 3 parts because of the length of the line): + + 46: 010310AC:9C4C 030310AC:1770 01 + | | | | | |--> connection state + | | | | |------> remote TCP port number + | | | |-------------> remote IPv4 address + | | |--------------------> local TCP port number + | |---------------------------> local IPv4 address + |----------------------------------> number of entry + + 00000150:00000000 01:00000019 00000000 + | | | | |--> number of unrecovered RTO timeouts + | | | |----------> number of jiffies until timer expires + | | |----------------> timer_active (see below) + | |----------------------> receive-queue + |-------------------------------> transmit-queue + + 1000 0 54165785 4 cd1e6040 25 4 27 3 -1 + | | | | | | | | | |--> slow start size threshold, + | | | | | | | | | or -1 if the treshold + | | | | | | | | | is >= 0xFFFF + | | | | | | | | |----> sending congestion window + | | | | | | | |-------> (ack.quick<<1)|ack.pingpong + | | | | | | |---------> Predicted tick of soft clock + | | | | | | (delayed ACK control data) + | | | | | |------------> retransmit timeout + | | | | |------------------> location of socket in memory + | | | |-----------------------> socket reference count + | | |-----------------------------> inode + | |----------------------------------> unanswered 0-window probes + |---------------------------------------------> uid + +timer_active: + 0 no timer is pending + 1 retransmit-timer is pending + 2 another timer (e.g. delayed ack or keepalive) is pending + 3 this is a socket in TIME_WAIT state. Not all fields will contain + data (or even exist) + 4 zero window probe timer is pending diff --git a/Documentation/nmi_watchdog.txt b/Documentation/nmi_watchdog.txt index 6cad46e8a..c025a4561 100644 --- a/Documentation/nmi_watchdog.txt +++ b/Documentation/nmi_watchdog.txt @@ -54,6 +54,20 @@ then the system has crashed so hard (eg. hardware-wise) that either it cannot even accept NMI interrupts, or the crash has made the kernel unable to print messages. +Be aware that when using local APIC, the frequency of NMI interrupts +it generates, depends on the system load. The local APIC NMI watchdog, +lacking a better source, uses the "cycles unhalted" event. As you may +guess it doesn't tick when the CPU is in the halted state (which happens +when the system is idle), but if your system locks up on anything but the +"hlt" processor instruction, the watchdog will trigger very soon as the +"cycles unhalted" event will happen every clock tick. If it locks up on +"hlt", then you are out of luck -- the event will not happen at all and the +watchdog won't trigger. This is a shortcoming of the local APIC watchdog +-- unfortunately there is no "clock ticks" event that would work all the +time. The I/O APIC watchdog is driven externally and has no such shortcoming. +But its NMI frequency is much higher, resulting in a more significant hit +to the overall system performance. + NOTE: starting with 2.4.2-ac18 the NMI-oopser is disabled by default, you have to enable it with a boot time parameter. Prior to 2.4.2-ac18 the NMI-oopser is enabled unconditionally on x86 SMP boxes. diff --git a/Documentation/parisc/registers b/Documentation/parisc/registers index 08b9f558d..dd3caddd1 100644 --- a/Documentation/parisc/registers +++ b/Documentation/parisc/registers @@ -35,8 +35,8 @@ CR31 (TR 7) Temporary register, used in various places SR0 temporary space register SR4-SR7 set to 0 SR1 temporary space register -SR2 unused -SR3 used for userspace accesses (current process)* +SR2 kernel should not clobber this +SR3 used for userspace accesses (current process) Space Registers (user mode) @@ -78,13 +78,8 @@ Shadow Registers used by interruption handler code TOC enable bit 1 ========================================================================= -Info from John Marvin: - -From: "John Marvin" -To: randolf@tausq.org -Subject: Re: parisc asm questions - -[...] +Register usage notes, originally from John Marvin, with some additional +notes from Randolph Chung. For the general registers: @@ -111,9 +106,10 @@ that you should be aware of: don't care about the values that were passed in anymore. r28,r29: are ret0 and ret1. They are what you pass return values - in. r28 is the primary return. I'm not sure I remember - under what circumstances stuff is returned in r29 (millicode - perhaps). + in. r28 is the primary return. When returning small structures + r29 may also be used to pass data back to the caller. + + r30: stack pointer r31: the ble instruction puts the return pointer in here. @@ -123,6 +119,3 @@ r3-r18,r27,r30 need to be saved and restored. r3-r18 are just used to make references to global variables easier. r30 is the stack pointer. -John - - diff --git a/Documentation/pm.txt b/Documentation/pm.txt index 483d2a5d1..008ac7d2d 100644 --- a/Documentation/pm.txt +++ b/Documentation/pm.txt @@ -36,8 +36,8 @@ system the associated daemon will exit gracefully. apmd: http://worldvisions.ca/~apenwarr/apmd/ acpid: http://acpid.sf.net/ -Driver Interface ----------------- +Driver Interface -- OBSOLETE, DO NOT USE! +----------------************************* If you are writing a new driver or maintaining an old driver, it should include power management support. Without power management support, a single driver may prevent a system with power management @@ -262,8 +262,8 @@ Q: Who do I contact for additional information about ACPI Development mailing list: acpi-devel@lists.sourceforge.net -System Interface ----------------- +System Interface -- OBSOLETE, DO NOT USE! +----------------************************* If you are providing new power management support to Linux (ie. adding support for something like APM or ACPI), you should communicate with drivers through the existing generic power diff --git a/Documentation/power/kernel_threads.txt b/Documentation/power/kernel_threads.txt new file mode 100644 index 000000000..60b548105 --- /dev/null +++ b/Documentation/power/kernel_threads.txt @@ -0,0 +1,41 @@ +KERNEL THREADS + + +Freezer + +Upon entering a suspended state the system will freeze all +tasks. This is done by delivering pseudosignals. This affects +kernel threads, too. To successfully freeze a kernel thread +the thread has to check for the pseudosignal and enter the +refrigerator. Code to do this looks like this: + + do { + hub_events(); + wait_event_interruptible(khubd_wait, !list_empty(&hub_event_list)); + if (current->flags & PF_FREEZE) + refrigerator(PF_FREEZE); + } while (!signal_pending(current)); + +from drivers/usb/core/hub.c::hub_thread() + + +The Unfreezable + +Some kernel threads however, must not be frozen. The kernel must +be able to finish pending IO operations and later on be able to +write the memory image to disk. Kernel threads needed to do IO +must stay awake. Such threads must mark themselves unfreezable +like this: + + /* + * This thread doesn't need any user-level access, + * so get rid of all our resources. + */ + daemonize("usb-storage"); + + current->flags |= PF_NOFREEZE; + +from drivers/usb/storage/usb.c::usb_stor_control_thread() + +Such drivers are themselves responsible for staying quiet during +the actual snapshotting. diff --git a/Documentation/power/video_extension.txt b/Documentation/power/video_extension.txt new file mode 100644 index 000000000..8e33d7c82 --- /dev/null +++ b/Documentation/power/video_extension.txt @@ -0,0 +1,34 @@ +This driver implement the ACPI Extensions For Display Adapters +for integrated graphics devices on motherboard, as specified in +ACPI 2.0 Specification, Appendix B, allowing to perform some basic +control like defining the video POST device, retrieving EDID information +or to setup a video output, etc. Note that this is an ref. implementation only. +It may or may not work for your integrated video device. + +Interfaces exposed to userland through /proc/acpi/video: + +VGA/info : display the supported video bus device capability like ,Video ROM, CRT/LCD/TV. +VGA/ROM : Used to get a copy of the display devices' ROM data (up to 4k). +VGA/POST_info : Used to determine what options are implemented. +VGA/POST : Used to get/set POST device. +VGA/DOS : Used to get/set ownership of output switching: + Please refer ACPI spec B.4.1 _DOS +VGA/CRT : CRT output +VGA/LCD : LCD output +VGA/TV : TV output +VGA/*/brightness : Used to get/set brightness of output device + +Notify event through /proc/acpi/event: + +#define ACPI_VIDEO_NOTIFY_SWITCH 0x80 +#define ACPI_VIDEO_NOTIFY_PROBE 0x81 +#define ACPI_VIDEO_NOTIFY_CYCLE 0x82 +#define ACPI_VIDEO_NOTIFY_NEXT_OUTPUT 0x83 +#define ACPI_VIDEO_NOTIFY_PREV_OUTPUT 0x84 + +#define ACPI_VIDEO_NOTIFY_CYCLE_BRIGHTNESS 0x82 +#define ACPI_VIDEO_NOTIFY_INC_BRIGHTNESS 0x83 +#define ACPI_VIDEO_NOTIFY_DEC_BRIGHTNESS 0x84 +#define ACPI_VIDEO_NOTIFY_ZERO_BRIGHTNESS 0x85 +#define ACPI_VIDEO_NOTIFY_DISPLAY_OFF 0x86 + diff --git a/Documentation/prio_tree.txt b/Documentation/prio_tree.txt new file mode 100644 index 000000000..2fbb0c49b --- /dev/null +++ b/Documentation/prio_tree.txt @@ -0,0 +1,107 @@ +The prio_tree.c code indexes vmas using 3 different indexes: + * heap_index = vm_pgoff + vm_size_in_pages : end_vm_pgoff + * radix_index = vm_pgoff : start_vm_pgoff + * size_index = vm_size_in_pages + +A regular radix-priority-search-tree indexes vmas using only heap_index and +radix_index. The conditions for indexing are: + * ->heap_index >= ->left->heap_index && + ->heap_index >= ->right->heap_index + * if (->heap_index == ->left->heap_index) + then ->radix_index < ->left->radix_index; + * if (->heap_index == ->right->heap_index) + then ->radix_index < ->right->radix_index; + * nodes are hashed to left or right subtree using radix_index + similar to a pure binary radix tree. + +A regular radix-priority-search-tree helps to store and query +intervals (vmas). However, a regular radix-priority-search-tree is only +suitable for storing vmas with different radix indices (vm_pgoff). + +Therefore, the prio_tree.c extends the regular radix-priority-search-tree +to handle many vmas with the same vm_pgoff. Such vmas are handled in +2 different ways: 1) All vmas with the same radix _and_ heap indices are +linked using vm_set.list, 2) if there are many vmas with the same radix +index, but different heap indices and if the regular radix-priority-search +tree cannot index them all, we build an overflow-sub-tree that indexes such +vmas using heap and size indices instead of heap and radix indices. For +example, in the figure below some vmas with vm_pgoff = 0 (zero) are +indexed by regular radix-priority-search-tree whereas others are pushed +into an overflow-subtree. Note that all vmas in an overflow-sub-tree have +the same vm_pgoff (radix_index) and if necessary we build different +overflow-sub-trees to handle each possible radix_index. For example, +in figure we have 3 overflow-sub-trees corresponding to radix indices +0, 2, and 4. + +In the final tree the first few (prio_tree_root->index_bits) levels +are indexed using heap and radix indices whereas the overflow-sub-trees below +those levels (i.e. levels prio_tree_root->index_bits + 1 and higher) are +indexed using heap and size indices. In overflow-sub-trees the size_index +is used for hashing the nodes to appropriate places. + +Now, an example prio_tree: + + vmas are represented [radix_index, size_index, heap_index] + i.e., [start_vm_pgoff, vm_size_in_pages, end_vm_pgoff] + +level prio_tree_root->index_bits = 3 +----- + _ + 0 [0,7,7] | + / \ | + ------------------ ------------ | Regular + / \ | radix priority + 1 [1,6,7] [4,3,7] | search tree + / \ / \ | + ------- ----- ------ ----- | heap-and-radix + / \ / \ | indexed + 2 [0,6,6] [2,5,7] [5,2,7] [6,1,7] | + / \ / \ / \ / \ | + 3 [0,5,5] [1,5,6] [2,4,6] [3,4,7] [4,2,6] [5,1,6] [6,0,6] [7,0,7] | + / / / _ + / / / _ + 4 [0,4,4] [2,3,5] [4,1,5] | + / / / | + 5 [0,3,3] [2,2,4] [4,0,4] | Overflow-sub-trees + / / | + 6 [0,2,2] [2,1,3] | heap-and-size + / / | indexed + 7 [0,1,1] [2,0,2] | + / | + 8 [0,0,0] | + _ + +Note that we use prio_tree_root->index_bits to optimize the height +of the heap-and-radix indexed tree. Since prio_tree_root->index_bits is +set according to the maximum end_vm_pgoff mapped, we are sure that all +bits (in vm_pgoff) above prio_tree_root->index_bits are 0 (zero). Therefore, +we only use the first prio_tree_root->index_bits as radix_index. +Whenever index_bits is increased in prio_tree_expand, we shuffle the tree +to make sure that the first prio_tree_root->index_bits levels of the tree +is indexed properly using heap and radix indices. + +We do not optimize the height of overflow-sub-trees using index_bits. +The reason is: there can be many such overflow-sub-trees and all of +them have to be suffled whenever the index_bits increases. This may involve +walking the whole prio_tree in prio_tree_insert->prio_tree_expand code +path which is not desirable. Hence, we do not optimize the height of the +heap-and-size indexed overflow-sub-trees using prio_tree->index_bits. +Instead the overflow sub-trees are indexed using full BITS_PER_LONG bits +of size_index. This may lead to skewed sub-trees because most of the +higher significant bits of the size_index are likely to be be 0 (zero). In +the example above, all 3 overflow-sub-trees are skewed. This may marginally +affect the performance. However, processes rarely map many vmas with the +same start_vm_pgoff but different end_vm_pgoffs. Therefore, we normally +do not require overflow-sub-trees to index all vmas. + +From the above discussion it is clear that the maximum height of +a prio_tree can be prio_tree_root->index_bits + BITS_PER_LONG. +However, in most of the common cases we do not need overflow-sub-trees, +so the tree height in the common cases will be prio_tree_root->index_bits. + +It is fair to mention here that the prio_tree_root->index_bits +is increased on demand, however, the index_bits is not decreased when +vmas are removed from the prio_tree. That's tricky to do. Hence, it's +left as a home work problem. + + diff --git a/Documentation/ramdisk.txt b/Documentation/ramdisk.txt index 1f937c3b3..7c25584e0 100644 --- a/Documentation/ramdisk.txt +++ b/Documentation/ramdisk.txt @@ -5,115 +5,66 @@ Contents: 1) Overview 2) Kernel Command Line Parameters - 3) Using "rdev -r" With New Kernels + 3) Using "rdev -r" 4) An Example of Creating a Compressed RAM Disk 1) Overview ----------- -As of kernel v1.3.48, the RAM disk driver was substantially changed. +The RAM disk driver is a way to use main system memory as a block device. It +is required for initrd, an initial filesystem used if you need to load modules +in order to access the root filesystem (see Documentation/initrd.txt). It can +also be used for a temporary filesystem for crypto work, since the contents +are erased on reboot. -The older versions would grab a chunk of memory off the top before -handing the remainder to the kernel at boot time. Thus a size parameter -had to be specified via "ramdisk=1440" or "rdev -r /dev/fd0 1440" so -that the driver knew how much memory to grab. +The RAM disk dynamically grows as more space is required. It does this by using +RAM from the buffer cache. The driver marks the buffers it is using as dirty +so that the VM subsystem does not try to reclaim them later. -Now the RAM disk dynamically grows as more space is required. It does -this by using RAM from the buffer cache. The driver marks the buffers -it is using with a new "BH_Protected" flag so that the kernel does -not try to reuse them later. This means that the old size parameter -is no longer used, new command line parameters exist, and the behavior -of the "rdev -r" or "ramsize" (usually a symbolic link to "rdev") -command has changed. +Also, the RAM disk supports up to 16 RAM disks out of the box, and can +be reconfigured to support up to 255 RAM disks - change "#define NUM_RAMDISKS" +in drivers/block/rd.c. To use RAM disk support with your system, run +'./MAKEDEV ram' from the /dev directory. RAM disks are all major number 1, and +start with minor number 0 for /dev/ram0, etc. If used, modern kernels use +/dev/ram0 for an initrd. -Also, the new RAM disk supports up to 16 RAM disks out of the box, and can -be reconfigured in rd.c to support up to 255 RAM disks. To use multiple -RAM disk support with your system, run 'mknod /dev/ramX b 1 X' and chmod -(to change its permissions) it to your liking. The default /dev/ram(disk) -uses minor #1, so start with ram2 and go from there. - -The old "ramdisk=" has been changed to "ramdisk_size=" -to make it clearer. The original "ramdisk=" has been kept around -for compatibility reasons, but it will probably be removed in 2.1.x. +The old "ramdisk=" has been changed to "ramdisk_size=" to +make it clearer. The original "ramdisk=" has been kept around for +compatibility reasons, but it may be removed in the future. The new RAM disk also has the ability to load compressed RAM disk images, allowing one to squeeze more programs onto an average installation or rescue floppy disk. -Notes: You may have "/dev/ram" or "/dev/ramdisk" or both. They are -equivalent from the standpoint of this document. Also, the new RAM disk -is a config option. When running "make config", make sure you enable -RAM disk support for the kernel with which you intend to use the RAM disk. - 2) Kernel Command Line Parameters --------------------------------- - ramdisk_start=NNN - ================= - -To allow a kernel image to reside on a floppy disk along with a compressed -RAM disk image, the "ramdisk_start=" command was added. The kernel -can't be included into the compressed RAM disk filesystem image, because -it needs to be stored starting at block zero so that the BIOS can load the -boot sector and then the kernel can bootstrap itself to get going. - -Note: If you are using an uncompressed RAM disk image, then the kernel can -be a part of the filesystem image that is being loaded into the RAM disk, -and the floppy can be booted with LILO, or the two can be separate as -is done for the compressed images. - -If you are using a two-disk boot/root setup (kernel on #1, RAM disk image -on #2) then the RAM disk would start at block zero, and an offset of -zero would be used. Since this is the default value, you would not need -to actually use the command at all. - -If instead, you have a "zImage" of about 350 kB, and a "fs_image.gz" of -say about 1 MB, and you want them both on the same disk, then you -would use an offset. If you stored the "fs_image.gz" onto the floppy -starting at an offset of 400 kB, you would use "ramdisk_start=400". - - - load_ramdisk=N + ramdisk_size=N ============== -This parameter tells the kernel whether it is to try to load a -RAM disk image or not. Specifying "load_ramdisk=1" will tell the -kernel to load a floppy into the RAM disk. The default value is -zero, meaning that the kernel should not try to load a RAM disk. - +This parameter tells the RAM disk driver to set up RAM disks of N k size. The +default is 4096 (4 MB) (8192 (8 MB) on S390). - prompt_ramdisk=N - ================ + ramdisk_blocksize=N + =================== -This parameter tells the kernel whether or not to give you a prompt -asking you to insert the floppy containing the RAM disk image. In -a single floppy configuration the RAM disk image is on the same floppy -as the kernel that just finished loading/booting and so a prompt -is not needed. In this case one can use "prompt_ramdisk=0". In a -two floppy configuration, you will need the chance to switch disks, -and thus "prompt_ramdisk=1" can be used. Since this is the default -value, it doesn't really need to be specified. +This parameter tells the RAM disk driver how many bytes to use per block. The +default is 512. - ramdisk_size=N - ============== - -This parameter tells the RAM disk driver to set up RAM disks of N k size. The -default is 4096 (4 MB). -3) Using "rdev -r" With New Kernels ------------------------------------ +3) Using "rdev -r" +------------------ -The usage of the word (two bytes) that "rdev -r" sets in the kernel image -has changed. The low 11 bits (0 -> 10) specify an offset (in 1 k blocks) -of up to 2 MB (2^11) of where to find the RAM disk (this used to be the -size). Bit 14 indicates that a RAM disk is to be loaded, and bit 15 -indicates whether a prompt/wait sequence is to be given before trying -to read the RAM disk. Since the RAM disk dynamically grows as data is -being written into it, a size field is no longer required. Bits 11 -to 13 are not currently used and may as well be zero. These numbers -are no magical secrets, as seen below: +The usage of the word (two bytes) that "rdev -r" sets in the kernel image is +as follows. The low 11 bits (0 -> 10) specify an offset (in 1 k blocks) of up +to 2 MB (2^11) of where to find the RAM disk (this used to be the size). Bit +14 indicates that a RAM disk is to be loaded, and bit 15 indicates whether a +prompt/wait sequence is to be given before trying to read the RAM disk. Since +the RAM disk dynamically grows as data is being written into it, a size field +is not required. Bits 11 to 13 are not currently used and may as well be zero. +These numbers are no magical secrets, as seen below: ./arch/i386/kernel/setup.c:#define RAMDISK_IMAGE_START_MASK 0x07FF ./arch/i386/kernel/setup.c:#define RAMDISK_PROMPT_FLAG 0x8000 @@ -152,10 +103,10 @@ Since the default start = 0 and the default prompt = 1, you could use: To create a RAM disk image, you will need a spare block device to construct it on. This can be the RAM disk device itself, or an unused disk partition (such as an unmounted swap partition). For this -example, we will use the RAM disk device, "/dev/ram". +example, we will use the RAM disk device, "/dev/ram0". Note: This technique should not be done on a machine with less than 8 MB -of RAM. If using a spare disk partition instead of /dev/ram, then this +of RAM. If using a spare disk partition instead of /dev/ram0, then this restriction does not apply. a) Decide on the RAM disk size that you want. Say 2 MB for this example. @@ -164,11 +115,11 @@ a) Decide on the RAM disk size that you want. Say 2 MB for this example. area (esp. for disks) so that maximal compression is achieved for the unused blocks of the image that you are about to create. - dd if=/dev/zero of=/dev/ram bs=1k count=2048 + dd if=/dev/zero of=/dev/ram0 bs=1k count=2048 b) Make a filesystem on it. Say ext2fs for this example. - mke2fs -vm0 /dev/ram 2048 + mke2fs -vm0 /dev/ram0 2048 c) Mount it, copy the files you want to it (eg: /etc/* /dev/* ...) and unmount it again. @@ -177,7 +128,7 @@ d) Compress the contents of the RAM disk. The level of compression will be approximately 50% of the space used by the files. Unused space on the RAM disk will compress to almost nothing. - dd if=/dev/ram bs=1k count=2048 | gzip -v9 > /tmp/ram_image.gz + dd if=/dev/ram0 bs=1k count=2048 | gzip -v9 > /tmp/ram_image.gz e) Put the kernel onto the floppy @@ -203,4 +154,14 @@ That is it. You now have your boot/root compressed RAM disk floppy. Some users may wish to combine steps (d) and (f) by using a pipe. -------------------------------------------------------------------------- - Paul Gortmaker 12/95 + Paul Gortmaker 12/95 + +Changelog: +---------- + +10-22-04 : Updated to reflect changes in command line options, remove + obsolete references, general cleanup. + James Nelson (james4765@gmail.com) + + +12-95 : Original Document diff --git a/Documentation/rocket.txt b/Documentation/rocket.txt index f9345cd14..a10678004 100644 --- a/Documentation/rocket.txt +++ b/Documentation/rocket.txt @@ -20,8 +20,27 @@ or installing it into kernels which do not have the driver configured into them. Installations instructions for the external module are in the included README and HW_INSTALL files. -RocketPort ISA and RocketModem II PCI boards are also supported by this -driver, but must use the external module driver for configuration reasons. +RocketPort ISA and RocketModem II PCI boards currently are only supported by +this driver in module form. + +The RocketPort ISA board requires I/O ports to be configured by the DIP +switches on the board. See the section "ISA Rocketport Boards" below for +information on how to set the DIP switches. + +You pass the I/O port to the driver using the following module parameters: + +board1 : I/O port for the first ISA board +board2 : I/O port for the second ISA board +board3 : I/O port for the third ISA board +board4 : I/O port for the fourth ISA board + +There is a set of utilities and scripts provided with the external driver +( downloadable from http://www.comtrol.com ) that ease the configuration and +setup of the ISA cards. + +The RocketModem II PCI boards require firmware to be loaded into the card +before it will function. The driver has only been tested as a module for this +board. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- @@ -55,12 +74,95 @@ create the RocketPort/RocketModem device names, use the command >mknod /dev/ttyR1 c 46 1 >mknod /dev/ttyR2 c 46 2 -The Linux script MAKEDEV will create the first 16 ttyRx device names (nodes) for you: +The Linux script MAKEDEV will create the first 16 ttyRx device names (nodes) +for you: >/dev/MAKEDEV ttyR =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +ISA Rocketport Boards +--------------------- + +You must assign and configure the I/O addresses used by the ISA Rocketport +card before installing and using it. This is done by setting a set of DIP +switches on the Rocketport board. + + +SETTING THE I/O ADDRESS +----------------------- + +Before installing RocketPort(R) or RocketPort RA boards, you must find +a range of I/O addresses for it to use. The first RocketPort card +requires a 68-byte contiguous block of I/O addresses, starting at one +of the following: 0x100h, 0x140h, 0x180h, 0x200h, 0x240h, 0x280h, +0x300h, 0x340h, 0x380h. This I/O address must be reflected in the DIP +switiches of *all* of the Rocketport cards. + +The second, third, and fourth RocketPort cards require a 64-byte +contiguous block of I/O addresses, starting at one of the following +I/O addresses: 0x100h, 0x140h, 0x180h, 0x1C0h, 0x200h, 0x240h, 0x280h, +0x2C0h, 0x300h, 0x340h, 0x380h, 0x3C0h. The I/O address used by the +second, third, and fourth Rocketport cards (if present) are set via +software control. The DIP switch settings for the I/O address must be +set to the value of the first Rocketport cards. + +In order to destinguish each of the card from the others, each card +must have a unique board ID set on the dip switches. The first +Rocketport board must be set with the DIP switches corresponding to +the first board, the second board must be set with the DIP switches +corresponding to the second board, etc. IMPORTANT: The board ID is +the only place where the DIP switch settings should differ between the +various Rocketport boards in a system. + +The I/O address range used by any of the RocketPort cards must not +conflict with any other cards in the system, including other +RocketPort cards. Below, you will find a list of commonly used I/O +address ranges which may be in use by other devices in your system. +On a Linux system, "cat /proc/ioports" will also be helpful in +identifying what I/O addresses are being used by devics on your +system. + +Remember, the FIRST RocketPort uses 68 I/O addresses. So, if you set it +for 0x100, it will occupy 0x100 to 0x143. This would mean that you +CAN NOT set the second, third or fourth board for address 0x140 since +the first 4 bytes of that range are used by the first board. You would +need to set the second, third, or fourth board to one of the next available +blocks such as 0x180. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- + +RocketPort and RocketPort RA SW1 Settings: + + +-------------------------------+ + | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | + +-------+-------+---------------+ + | Unused| Card | I/O Port Block| + +-------------------------------+ + +DIP Switches DIP Switches +7 8 6 5 +=================== =================== +On On UNUSED, MUST BE ON. On On First Card <==== Default + On Off Second Card + Off On Third Card + Off Off Fourth Card + +DIP Switches I/O Address Range +4 3 2 1 Used by the First Card +===================================== +On Off On Off 100-143 +On Off Off On 140-183 +On Off Off Off 180-1C3 <==== Default +Off On On Off 200-243 +Off On Off On 240-283 +Off On Off Off 280-2C3 +Off Off On Off 300-343 +Off Off Off On 340-383 +Off Off Off Off 380-3C3 + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- + REPORTING BUGS -------------- diff --git a/Documentation/s390/monreader.txt b/Documentation/s390/monreader.txt new file mode 100644 index 000000000..d843bb049 --- /dev/null +++ b/Documentation/s390/monreader.txt @@ -0,0 +1,197 @@ + +Date : 2004-Nov-26 +Author: Gerald Schaefer (geraldsc@de.ibm.com) + + + Linux API for read access to z/VM Monitor Records + ================================================= + + +Description +=========== +This item delivers a new Linux API in the form of a misc char device that is +useable from user space and allows read access to the z/VM Monitor Records +collected by the *MONITOR System Service of z/VM. + + +User Requirements +================= +The z/VM guest on which you want to access this API needs to be configured in +order to allow IUCV connections to the *MONITOR service, i.e. it needs the +IUCV *MONITOR statement in its user entry. If the monitor DCSS to be used is +restricted (likely), you also need the NAMESAVE statement. +This item will use the IUCV device driver to access the z/VM services, so you +need a kernel with IUCV support. You also need z/VM version 4.4 or 5.1. + +There are two options for being able to load the monitor DCSS (examples assume +that the monitor DCSS begins at 144 MB and ends at 152 MB). You can query the +location of the monitor DCSS with the Class E privileged CP command Q NSS MAP +(the values BEGPAG and ENDPAG are given in units of 4K pages). + +See also "CP Command and Utility Reference" (SC24-6081-00) for more information +on the DEF STOR and Q NSS MAP commands, as well as "Saved Segments Planning +and Administration" (SC24-6116-00) for more information on DCSSes. + +1st option: +----------- +You can use the CP command DEF STOR CONFIG to define a "memory hole" in your +guest virtual storage around the address range of the DCSS. + +Example: DEF STOR CONFIG 0.140M 200M.200M + +This defines two blocks of storage, the first is 140MB in size an begins at +address 0MB, the second is 200MB in size and begins at address 200MB, +resulting in a total storage of 340MB. Note that the first block should +always start at 0 and be at least 64MB in size. + +2nd option: +----------- +Your guest virtual storage has to end below the starting address of the DCSS +and you have to specify the "mem=" kernel parameter in your parmfile with a +value greater than the ending address of the DCSS. + +Example: DEF STOR 140M + +This defines 140MB storage size for your guest, the parameter "mem=160M" is +added to the parmfile. + + +User Interface +============== +The char device is implemented as a kernel module named "monreader", +which can be loaded via the modprobe command, or it can be compiled into the +kernel instead. There is one optional module (or kernel) parameter, "mondcss", +to specify the name of the monitor DCSS. If the module is compiled into the +kernel, the kernel parameter "monreader.mondcss=" can be specified +in the parmfile. + +The default name for the DCSS is "MONDCSS" if none is specified. In case that +there are other users already connected to the *MONITOR service (e.g. +Performance Toolkit), the monitor DCSS is already defined and you have to use +the same DCSS. The CP command Q MONITOR (Class E privileged) shows the name +of the monitor DCSS, if already defined, and the users connected to the +*MONITOR service. +Refer to the "z/VM Performance" book (SC24-6109-00) on how to create a monitor +DCSS if your z/VM doesn't have one already, you need Class E privileges to +define and save a DCSS. + +Example: +-------- +modprobe monreader mondcss=MYDCSS + +This loads the module and sets the DCSS name to "MYDCSS". + +NOTE: +----- +This API provides no interface to control the *MONITOR service, e.g. specifiy +which data should be collected. This can be done by the CP command MONITOR +(Class E privileged), see "CP Command and Utility Reference". + +Device nodes with udev: +----------------------- +After loading the module, a char device will be created along with the device +node //monreader. + +Device nodes without udev: +-------------------------- +If your distribution does not support udev, a device node will not be created +automatically and you have to create it manually after loading the module. +Therefore you need to know the major and minor numbers of the device. These +numbers can be found in /sys/class/misc/monreader/dev. +Typing cat /sys/class/misc/monreader/dev will give an output of the form +:. The device node can be created via the mknod command, enter +mknod c , where is the name of the device node +to be created. + +Example: +-------- +# modprobe monreader +# cat /sys/class/misc/monreader/dev +10:63 +# mknod /dev/monreader c 10 63 + +This loads the module with the default monitor DCSS (MONDCSS) and creates a +device node. + +File operations: +---------------- +The following file operations are supported: open, release, read, poll. +There are two alternative methods for reading: either non-blocking read in +conjunction with polling, or blocking read without polling. IOCTLs are not +supported. + +Read: +----- +Reading from the device provides a 12 Byte monitor control element (MCE), +followed by a set of one or more contiguous monitor records (similar to the +output of the CMS utility MONWRITE without the 4K control blocks). The MCE +contains information on the type of the following record set (sample/event +data), the monitor domains contained within it and the start and end address +of the record set in the monitor DCSS. The start and end address can be used +to determine the size of the record set, the end address is the address of the +last byte of data. The start address is needed to handle "end-of-frame" records +correctly (domain 1, record 13), i.e. it can be used to determine the record +start offset relative to a 4K page (frame) boundary. + +See "Appendix A: *MONITOR" in the "z/VM Performance" document for a description +of the monitor control element layout. The layout of the monitor records can +be found here (z/VM 5.1): http://www.vm.ibm.com/pubs/mon510/index.html + +The layout of the data stream provided by the monreader device is as follows: +... +<0 byte read> + \ + | +... |- data set + | + / +<0 byte read> +... + +There may be more than one combination of MCE and corresponding record set +within one data set and the end of each data set is indicated by a successful +read with a return value of 0 (0 byte read). +Any received data must be considered invalid until a complete set was +read successfully, including the closing 0 byte read. Therefore you should +always read the complete set into a buffer before processing the data. + +The maximum size of a data set can be as large as the size of the +monitor DCSS, so design the buffer adequately or use dynamic memory allocation. +The size of the monitor DCSS will be printed into syslog after loading the +module. You can also use the (Class E privileged) CP command Q NSS MAP to +list all available segments and information about them. + +As with most char devices, error conditions are indicated by returning a +negative value for the number of bytes read. In this case, the errno variable +indicates the error condition: + +EIO: reply failed, read data is invalid and the application + should discard the data read since the last successful read with 0 size. +EFAULT: copy_to_user failed, read data is invalid and the application should + discard the data read since the last successful read with 0 size. +EAGAIN: occurs on a non-blocking read if there is no data available at the + moment. There is no data missing or corrupted, just try again or rather + use polling for non-blocking reads. +EOVERFLOW: message limit reached, the data read since the last successful + read with 0 size is valid but subsequent records may be missing. + +In the last case (EOVERFLOW) there may be missing data, in the first two cases +(EIO, EFAULT) there will be missing data. It's up to the application if it will +continue reading subsequent data or rather exit. + +Open: +----- +Only one user is allowed to open the char device. If it is already in use, the +open function will fail (return a negative value) and set errno to EBUSY. +The open function may also fail if an IUCV connection to the *MONITOR service +cannot be established. In this case errno will be set to EIO and an error +message with an IPUSER SEVER code will be printed into syslog. The IPUSER SEVER +codes are described in the "z/VM Performance" book, Appendix A. + +NOTE: +----- +As soon as the device is opened, incoming messages will be accepted and they +will account for the message limit, i.e. opening the device without reading +from it will provoke the "message limit reached" error (EOVERFLOW error code) +eventually. + diff --git a/Documentation/s390/s390dbf.txt b/Documentation/s390/s390dbf.txt index 692cc26cf..2d1cd939b 100644 --- a/Documentation/s390/s390dbf.txt +++ b/Documentation/s390/s390dbf.txt @@ -78,6 +78,23 @@ Example: > echo "-" > /proc/s390dbf/dasd/level +It is also possible to deactivate the debug feature globally for every +debug log. You can change the behavior using 2 sysctl parameters in +/proc/sys/s390dbf: +There are currently 2 possible triggers, which stop the debug feature +globally. The first possbility is to use the "debug_active" sysctl. If +set to 1 the debug feature is running. If "debug_active" is set to 0 the +debug feature is turned off. +The second trigger which stops the debug feature is an kernel oops. +That prevents the debug feature from overwriting debug information that +happened before the oops. After an oops you can reactivate the debug feature +by piping 1 to /proc/sys/s390dbf/debug_active. Nevertheless, its not +suggested to use an oopsed kernel in an production environment. +If you want to disallow the deactivation of the debug feature, you can use +the "debug_stoppable" sysctl. If you set "debug_stoppable" to 0 the debug +feature cannot be stopped. If the debug feature is already stopped, it +will stay deactivated. + Kernel Interfaces: ------------------ @@ -115,6 +132,17 @@ Parameter: id: handle for debug log Return Value: none Description: Sets new actual debug level if new_level is valid. + +--------------------------------------------------------------------------- ++void debug_stop_all(void); + +Parameter: none + +Return Value: none + +Description: stops the debug feature if stopping is allowed. Currently + used in case of a kernel oops. + --------------------------------------------------------------------------- debug_entry_t* debug_event (debug_info_t* id, int level, void* data, int length); @@ -271,12 +299,12 @@ Examples * hex_ascii- + raw-view Example */ -#include +#include #include static debug_info_t* debug_info; -int init_module(void) +static int init(void) { /* register 4 debug areas with one page each and 4 byte data field */ @@ -291,23 +319,26 @@ int init_module(void) return 0; } -void cleanup_module(void) +static void cleanup(void) { debug_unregister (debug_info); } +module_init(init); +module_exit(cleanup); + --------------------------------------------------------------------------- /* * sprintf-view Example */ -#include +#include #include static debug_info_t* debug_info; -int init_module(void) +static int init(void) { /* register 4 debug areas with one page each and data field for */ /* format string pointer + 2 varargs (= 3 * sizeof(long)) */ @@ -321,11 +352,14 @@ int init_module(void) return 0; } -void cleanup_module(void) +static void cleanup(void) { debug_unregister (debug_info); } +module_init(init); +module_exit(cleanup); + ProcFS Interface @@ -377,6 +411,15 @@ Examples: 2. Flush all debug areas: > echo "-" > /proc/s390dbf/dasd/flush +Stooping the debug feature +-------------------------- +Example: + +1. Check if stopping is allowed +> cat /proc/sys/s390dbf/debug_stoppable +2. Stop debug feature +> echo 0 > /proc/sys/s390dbf/debug_active + lcrash Interface ---------------- It is planned that the dump analysis tool lcrash gets an additional command diff --git a/Documentation/scsi/ChangeLog.megaraid b/Documentation/scsi/ChangeLog.megaraid index 431e3983e..79a9aed8e 100644 --- a/Documentation/scsi/ChangeLog.megaraid +++ b/Documentation/scsi/ChangeLog.megaraid @@ -1,3 +1,27 @@ +Release Date : Thu Dec 9 19:02:14 EST 2004 - Sreenivas Bagalkote + +Current Version : 2.20.4.1 (scsi module), 2.20.2.3 (cmm module) +Older Version : 2.20.4.1 (scsi module), 2.20.2.2 (cmm module) + +i. Fix a bug in kioc's dma buffer deallocation + +Release Date : Thu Nov 4 18:24:56 EST 2004 - Sreenivas Bagalkote + +Current Version : 2.20.4.1 (scsi module), 2.20.2.2 (cmm module) +Older Version : 2.20.4.0 (scsi module), 2.20.2.1 (cmm module) + +i. Handle IOCTL cmd timeouts more properly. + +ii. pci_dma_sync_{sg,single}_for_cpu was introduced into megaraid_mbox + incorrectly (instead of _for_device). Changed to appropriate + pci_dma_sync_{sg,single}_for_device. + +Release Date : Wed Oct 06 11:15:29 EDT 2004 - Sreenivas Bagalkote +Current Version : 2.20.4.0 (scsi module), 2.20.2.1 (cmm module) +Older Version : 2.20.4.0 (scsi module), 2.20.2.0 (cmm module) + +i. Remove CONFIG_COMPAT around register_ioctl32_conversion + Release Date : Mon Sep 27 22:15:07 EDT 2004 - Atul Mukker Current Version : 2.20.4.0 (scsi module), 2.20.2.0 (cmm module) Older Version : 2.20.3.1 (scsi module), 2.20.2.0 (cmm module) diff --git a/Documentation/scsi/sym53c8xx_2.txt b/Documentation/scsi/sym53c8xx_2.txt index f13415a3a..af9abe291 100644 --- a/Documentation/scsi/sym53c8xx_2.txt +++ b/Documentation/scsi/sym53c8xx_2.txt @@ -4,7 +4,9 @@ Written by Gerard Roudier 21 Rue Carnot 95170 DEUIL LA BARRE - FRANCE -Decembre 28 2000 +Updated by Matthew Wilcox + +2004-10-09 =============================================================================== 1. Introduction @@ -29,26 +31,20 @@ Decembre 28 2000 10. Boot setup commands 10.1 Syntax 10.2 Available arguments - 10.2.1 Master parity checking - 10.2.2 Scsi parity checking - 10.2.3 Default number of tagged commands - 10.2.4 Default synchronous period factor - 10.2.5 Verbosity level - 10.2.6 Debug mode - 10.2.7 Burst max - 10.2.8 LED support - 10.2.9 Max wide - 10.2.10 Differential mode - 10.2.11 IRQ mode - 10.2.12 Reverse probe - 10.2.13 Fix up PCI configuration space - 10.2.14 Serial NVRAM - 10.2.15 Check SCSI BUS - 10.2.16 Exclude a host from being attached - 10.2.17 Suggest a default SCSI id for hosts - 10.3 PCI configuration fix-up boot option - 10.4 Serial NVRAM support boot option - 10.5 SCSI BUS checking boot option + 10.2.1 Default number of tagged commands + 10.2.2 Burst max + 10.2.3 LED support + 10.2.4 Differential mode + 10.2.5 IRQ mode + 10.2.6 Check SCSI BUS + 10.2.7 Suggest a default SCSI id for hosts + 10.2.8 Verbosity level + 10.2.9 Debug mode + 10.2.10 Settle delay + 10.2.11 Serial NVRAM + 10.2.12 Exclude a host from being attached + 10.3 Converting from old options + 10.4 SCSI BUS checking boot option 11. SCSI problem troubleshooting 15.1 Problem tracking 15.2 Understanding hardware error reports @@ -94,6 +90,9 @@ The history of this driver can be summerized as follows: Write a glue code for Linux. Gerard Roudier +2004: Remove FreeBSD compatibility code. Remove support for versions of + Linux before 2.6. Start using Linux facilities. + This README file addresses the Linux version of the driver. Under FreeBSD, the driver documentation is the sym.8 man page. @@ -279,11 +278,10 @@ setting verbose level to zero, as follow: 6. Parity checking The driver supports SCSI parity checking and PCI bus master parity -checking. These features must be enabled in order to ensure safe data -transfers. However, some flawed devices or mother boards will have -problems with parity. You can disable either PCI parity or SCSI parity -checking by entering appropriate options from the boot command line. -(See 10: Boot setup commands). +checking. These features must be enabled in order to ensure safe +data transfers. Some flawed devices or mother boards may have problems +with parity. The options to defeat parity checking have been removed +from the driver. 7. Profiling information @@ -428,77 +426,90 @@ Synchronous transfers frequency (default answer: 80) 10.1 Syntax -Setup commands can be passed to the driver either at boot time or as a -string variable using 'insmod'. - -A boot setup command for this driver begins with the driver name "sym53c8xx=". -The kernel syntax parser then expects an optionnal list of integers separated -with comma followed by an optional list of comma-separated strings. +Setup commands can be passed to the driver either at boot time or as +parameters to modprobe, as described in Documentation/kernel-parameters.txt Example of boot setup command under lilo prompt: -lilo: linux root=/dev/sda2 sym53c8xx=tags:4,sync:10,debug:0x200 +lilo: linux root=/dev/sda2 sym53c8xx.cmd_per_lun=4 sym53c8xx.sync=10 sym53c8xx.debug=0x200 - enable tagged commands, up to 4 tagged commands queued. - set synchronous negotiation speed to 10 Mega-transfers / second. - set DEBUG_NEGO flag. -Since comma seems not to be allowed when defining a string variable using -'insmod', the driver also accepts as option separator. -The following command will install driver module with the same options as -above. - - insmod sym53c8xx.o sym53c8xx="tags:4 sync:10 debug:0x200" +The following command will install the driver module with the same +options as above. -The integer list of arguments is discarded by the driver. - -Each string argument must be specified as "keyword:value". Only lower-case -characters and digits are allowed. + modprobe sym53c8xx cmd_per_lun=4 sync=10 debug=0x200" 10.2 Available arguments -10.2.1 Master parity checking - mpar:y enabled - mpar:n disabled - -10.2.2 Scsi parity checking - spar:y enabled - spar:n disabled - -10.2.3 Default number of tagged commands - tags:0 (or tags:1 ) tagged command queuing disabled - tags:#tags (#tags > 1) tagged command queuing enabled +10.2.1 Default number of tagged commands + cmd_per_lun=0 (or cmd_per_lun=1) tagged command queuing disabled + cmd_per_lun=#tags (#tags > 1) tagged command queuing enabled #tags will be truncated to the max queued commands configuration parameter. - This option also allows to specify a command queue depth for each device - that support tagged command queueing. + +10.2.2 Detailed control of tagged commands + This option allows you to specify a command queue depth for each device + that supports tagged command queueing. Example: - sym53c8xx=tags:10/t2t3q16-t5q24/t1u2q32 - will set devices queue depth as follow: + tag_ctrl=10/t2t3q16-t5q24/t1u2q32 + will set devices queue depth as follow: - controller #0 target #2 and target #3 -> 16 commands, - controller #0 target #5 -> 24 commands, - controller #1 target #1 logical unit #2 -> 32 commands, - all other logical units (all targets, all controllers) -> 10 commands. -10.2.4 Default synchronous period factor - sync:255 disabled (asynchronous transfer mode) - sync:#factor - #factor = 9 Ultra-3 SCSI 80 Mega-transfers / second (Wide only) - #factor = 10 Ultra-2 SCSI 40 Mega-transfers / second - #factor = 11 Ultra-2 SCSI 33 Mega-transfers / second - #factor < 25 Ultra SCSI 20 Mega-transfers / second - #factor < 50 Fast SCSI-2 - - In all cases, the driver will use the minimum transfer period supported by - controllers according to SYM53C8XX chip type. - -10.2.5 Verbosity level - verb:0 minimal - verb:1 normal - verb:2 too much - -10.2.6 Debug mode - debug:0 clear debug flags - debug:#x set debug flags +10.2.3 Burst max + burst=0 burst disabled + burst=255 get burst length from initial IO register settings. + burst=#x burst enabled (1<<#x burst transfers max) + #x is an integer value which is log base 2 of the burst transfers max. + By default the driver uses the maximum value supported by the chip. + +10.2.4 LED support + led=1 enable LED support + led=0 disable LED support + Do not enable LED support if your scsi board does not use SDMS BIOS. + (See 'Configuration parameters') + +10.2.4 Differential mode + diff=0 never set up diff mode + diff=1 set up diff mode if BIOS set it + diff=2 always set up diff mode + diff=3 set diff mode if GPIO3 is not set + +10.2.5 IRQ mode + irqm=0 always open drain + irqm=1 same as initial settings (assumed BIOS settings) + irqm=2 always totem pole + +10.2.6 Check SCSI BUS + buschk=