diff options
Diffstat (limited to 'Documentation')
27 files changed, 842 insertions, 71 deletions
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index 9069189e78ef..afc286775891 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -160,6 +160,21 @@ supply of new-lines on your screen is not a renewable resource (think 25-line terminal screens here), you have more empty lines to put comments on. +Do not unnecessarily use braces where a single statement will do. + +if (condition) + action(); + +This does not apply if one branch of a conditional statement is a single +statement. Use braces in both branches. + +if (condition) { + do_this(); + do_that(); +} else { + otherwise(); +} + 3.1: Spaces Linux kernel style for use of spaces depends (mostly) on @@ -625,7 +640,7 @@ language. There appears to be a common misperception that gcc has a magic "make me faster" speedup option called "inline". While the use of inlines can be -appropriate (for example as a means of replacing macros, see Chapter 11), it +appropriate (for example as a means of replacing macros, see Chapter 12), it very often is not. Abundant use of the inline keyword leads to a much bigger kernel, which in turn slows the system as a whole down, due to a bigger icache footprint for the CPU and simply because there is less memory diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 10b5cd6c54a0..6fd1646d3204 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -43,6 +43,7 @@ pdfdocs: $(PDF) HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS))) htmldocs: $(HTML) + $(call build_main_index) MAN := $(patsubst %.xml, %.9, $(BOOKS)) mandocs: $(MAN) @@ -132,10 +133,17 @@ quiet_cmd_db2pdf = PDF $@ %.pdf : %.xml $(call cmd,db2pdf) + +main_idx = Documentation/DocBook/index.html +build_main_index = rm -rf $(main_idx) && \ + echo '<h1>Linux Kernel HTML Documentation</h1>' >> $(main_idx) && \ + echo '<h2>Kernel Version: $(KERNELVERSION)</h2>' >> $(main_idx) && \ + cat $(HTML) >> $(main_idx) + quiet_cmd_db2html = HTML $@ cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \ echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \ - Goto $(patsubst %.html,%,$(notdir $@))</a><p>' > $@ + $(patsubst %.html,%,$(notdir $@))</a><p>' > $@ %.html: %.xml @(which xmlto > /dev/null 2>&1) || \ diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl index b61dfc79e1b8..a2b2b4d187c5 100644 --- a/Documentation/DocBook/kernel-api.tmpl +++ b/Documentation/DocBook/kernel-api.tmpl @@ -576,4 +576,67 @@ X!Idrivers/video/console/fonts.c !Edrivers/input/ff-core.c !Edrivers/input/ff-memless.c </chapter> + + <chapter id="spi"> + <title>Serial Peripheral Interface (SPI)</title> + <para> + SPI is the "Serial Peripheral Interface", widely used with + embedded systems because it is a simple and efficient + interface: basically a multiplexed shift register. + Its three signal wires hold a clock (SCK, often in the range + of 1-20 MHz), a "Master Out, Slave In" (MOSI) data line, and + a "Master In, Slave Out" (MISO) data line. + SPI is a full duplex protocol; for each bit shifted out the + MOSI line (one per clock) another is shifted in on the MISO line. + Those bits are assembled into words of various sizes on the + way to and from system memory. + An additional chipselect line is usually active-low (nCS); + four signals are normally used for each peripheral, plus + sometimes an interrupt. + </para> + <para> + The SPI bus facilities listed here provide a generalized + interface to declare SPI busses and devices, manage them + according to the standard Linux driver model, and perform + input/output operations. + At this time, only "master" side interfaces are supported, + where Linux talks to SPI peripherals and does not implement + such a peripheral itself. + (Interfaces to support implementing SPI slaves would + necessarily look different.) + </para> + <para> + The programming interface is structured around two kinds of driver, + and two kinds of device. + A "Controller Driver" abstracts the controller hardware, which may + be as simple as a set of GPIO pins or as complex as a pair of FIFOs + connected to dual DMA engines on the other side of the SPI shift + register (maximizing throughput). Such drivers bridge between + whatever bus they sit on (often the platform bus) and SPI, and + expose the SPI side of their device as a + <structname>struct spi_master</structname>. + SPI devices are children of that master, represented as a + <structname>struct spi_device</structname> and manufactured from + <structname>struct spi_board_info</structname> descriptors which + are usually provided by board-specific initialization code. + A <structname>struct spi_driver</structname> is called a + "Protocol Driver", and is bound to a spi_device using normal + driver model calls. + </para> + <para> + The I/O model is a set of queued messages. Protocol drivers + submit one or more <structname>struct spi_message</structname> + objects, which are processed and completed asynchronously. + (There are synchronous wrappers, however.) Messages are + built from one or more <structname>struct spi_transfer</structname> + objects, each of which wraps a full duplex SPI transfer. + A variety of protocol tweaking options are needed, because + different chips adopt very different policies for how they + use the bits transferred with SPI. + </para> +!Iinclude/linux/spi/spi.h +!Fdrivers/spi/spi.c spi_register_board_info +!Edrivers/spi/spi.c + </chapter> + </book> diff --git a/Documentation/DocBook/librs.tmpl b/Documentation/DocBook/librs.tmpl index 3ff39bafc00e..94f21361e0ed 100644 --- a/Documentation/DocBook/librs.tmpl +++ b/Documentation/DocBook/librs.tmpl @@ -79,12 +79,12 @@ <chapter id="usage"> <title>Usage</title> <para> - This chapter provides examples how to use the library. + This chapter provides examples of how to use the library. </para> <sect1> <title>Initializing</title> <para> - The init function init_rs returns a pointer to a + The init function init_rs returns a pointer to an rs decoder structure, which holds the necessary information for encoding, decoding and error correction with the given polynomial. It either uses an existing @@ -98,10 +98,10 @@ static struct rs_control *rs_decoder; /* Symbolsize is 10 (bits) - * Primitve polynomial is x^10+x^3+1 + * Primitive 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 + * primitive element to generate roots = 1 + * generator polynomial degree (number of roots) = 6 */ rs_decoder = init_rs (10, 0x409, 0, 1, 6); </programlisting> @@ -116,12 +116,12 @@ rs_decoder = init_rs (10, 0x409, 0, 1, 6); </para> <para> The expanded data can be inverted on the fly by - providing a non zero inversion mask. The expanded data is + 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 + too. This prevents that reading from an erased FLASH results in ECC errors. </para> <para> @@ -273,7 +273,7 @@ free_rs(rs_decoder); May be used under the terms of the GNU General Public License (GPL) </programlisting> <para> - The wrapper functions and interfaces are written by Thomas Gleixner + The wrapper functions and interfaces are written by Thomas Gleixner. </para> <para> Many users have provided bugfixes, improvements and helping hands for testing. diff --git a/Documentation/SubmittingDrivers b/Documentation/SubmittingDrivers index 58bead05eabb..d7e26427e426 100644 --- a/Documentation/SubmittingDrivers +++ b/Documentation/SubmittingDrivers @@ -87,6 +87,21 @@ Clarity: It helps if anyone can see how to fix the driver. It helps driver that intentionally obfuscates how the hardware works it will go in the bitbucket. +PM support: Since Linux is used on many portable and desktop systems, your + driver is likely to be used on such a system and therefore it + should support basic power management by implementing, if + necessary, the .suspend and .resume methods used during the + system-wide suspend and resume transitions. You should verify + that your driver correctly handles the suspend and resume, but + if you are unable to ensure that, please at least define the + .suspend method returning the -ENOSYS ("Function not + implemented") error. You should also try to make sure that your + driver uses as little power as possible when it's not doing + anything. For the driver testing instructions see + Documentation/power/drivers-testing.txt and for a relatively + complete overview of the power management issues related to + drivers see Documentation/power/devices.txt . + Control: In general if there is active maintainance of a driver by the author then patches will be redirected to them unless they are totally obvious and without need of checking. diff --git a/Documentation/accounting/getdelays.c b/Documentation/accounting/getdelays.c index e9126e794ed7..71acc28ed0d1 100644 --- a/Documentation/accounting/getdelays.c +++ b/Documentation/accounting/getdelays.c @@ -61,8 +61,6 @@ __u64 stime, utime; #define MAX_MSG_SIZE 1024 /* Maximum number of cpus expected to be specified in a cpumask */ #define MAX_CPUS 32 -/* Maximum length of pathname to log file */ -#define MAX_FILENAME 256 struct msgtemplate { struct nlmsghdr n; @@ -72,6 +70,16 @@ struct msgtemplate { char cpumask[100+6*MAX_CPUS]; +static void usage(void) +{ + fprintf(stderr, "getdelays [-dilv] [-w logfile] [-r bufsize] " + "[-m cpumask] [-t tgid] [-p pid]\n"); + fprintf(stderr, " -d: print delayacct stats\n"); + fprintf(stderr, " -i: print IO accounting (works only with -p)\n"); + fprintf(stderr, " -l: listen forever\n"); + fprintf(stderr, " -v: debug on\n"); +} + /* * Create a raw netlink socket and bind */ @@ -221,13 +229,13 @@ int main(int argc, char *argv[]) int count = 0; int write_file = 0; int maskset = 0; - char logfile[128]; + char *logfile = NULL; int loop = 0; struct msgtemplate msg; while (1) { - c = getopt(argc, argv, "diw:r:m:t:p:v:l"); + c = getopt(argc, argv, "diw:r:m:t:p:vl"); if (c < 0) break; @@ -241,7 +249,7 @@ int main(int argc, char *argv[]) print_io_accounting = 1; break; case 'w': - strncpy(logfile, optarg, MAX_FILENAME); + logfile = strdup(optarg); printf("write to file %s\n", logfile); write_file = 1; break; @@ -277,7 +285,7 @@ int main(int argc, char *argv[]) loop = 1; break; default: - printf("Unknown option %d\n", c); + usage(); exit(-1); } } diff --git a/Documentation/cciss.txt b/Documentation/cciss.txt index f74affe5c829..e65736c6b8bc 100644 --- a/Documentation/cciss.txt +++ b/Documentation/cciss.txt @@ -22,14 +22,21 @@ This driver is known to work with the following cards: * SA E200i * SA E500 -If nodes are not already created in the /dev/cciss directory, run as root: +Detecting drive failures: +------------------------- -# cd /dev -# ./MAKEDEV cciss +To get the status of logical volumes and to detect physical drive +failures, you can use the cciss_vol_status program found here: +http://cciss.sourceforge.net/#cciss_utils Device Naming: -------------- +If nodes are not already created in the /dev/cciss directory, run as root: + +# cd /dev +# ./MAKEDEV cciss + You need some entries in /dev for the cciss device. The MAKEDEV script can make device nodes for you automatically. Currently the device setup is as follows: diff --git a/Documentation/fb/deferred_io.txt b/Documentation/fb/deferred_io.txt new file mode 100644 index 000000000000..73cf9fb7cf60 --- /dev/null +++ b/Documentation/fb/deferred_io.txt @@ -0,0 +1,75 @@ +Deferred IO +----------- + +Deferred IO is a way to delay and repurpose IO. It uses host memory as a +buffer and the MMU pagefault as a pretrigger for when to perform the device +IO. The following example may be a useful explaination of how one such setup +works: + +- userspace app like Xfbdev mmaps framebuffer +- deferred IO and driver sets up nopage and page_mkwrite handlers +- userspace app tries to write to mmaped vaddress +- we get pagefault and reach nopage handler +- nopage handler finds and returns physical page +- we get page_mkwrite where we add this page to a list +- schedule a workqueue task to be run after a delay +- app continues writing to that page with no additional cost. this is + the key benefit. +- the workqueue task comes in and mkcleans the pages on the list, then + completes the work associated with updating the framebuffer. this is + the real work talking to the device. +- app tries to write to the address (that has now been mkcleaned) +- get pagefault and the above sequence occurs again + +As can be seen from above, one benefit is roughly to allow bursty framebuffer +writes to occur at minimum cost. Then after some time when hopefully things +have gone quiet, we go and really update the framebuffer which would be +a relatively more expensive operation. + +For some types of nonvolatile high latency displays, the desired image is +the final image rather than the intermediate stages which is why it's okay +to not update for each write that is occuring. + +It may be the case that this is useful in other scenarios as well. Paul Mundt +has mentioned a case where it is beneficial to use the page count to decide +whether to coalesce and issue SG DMA or to do memory bursts. + +Another one may be if one has a device framebuffer that is in an usual format, +say diagonally shifting RGB, this may then be a mechanism for you to allow +apps to pretend to have a normal framebuffer but reswizzle for the device +framebuffer at vsync time based on the touched pagelist. + +How to use it: (for applications) +--------------------------------- +No changes needed. mmap the framebuffer like normal and just use it. + +How to use it: (for fbdev drivers) +---------------------------------- +The following example may be helpful. + +1. Setup your structure. Eg: + +static struct fb_deferred_io hecubafb_defio = { + .delay = HZ, + .deferred_io = hecubafb_dpy_deferred_io, +}; + +The delay is the minimum delay between when the page_mkwrite trigger occurs +and when the deferred_io callback is called. The deferred_io callback is +explained below. + +2. Setup your deferred IO callback. Eg: +static void hecubafb_dpy_deferred_io(struct fb_info *info, + struct list_head *pagelist) + +The deferred_io callback is where you would perform all your IO to the display +device. You receive the pagelist which is the list of pages that were written +to during the delay. You must not modify this list. This callback is called +from a workqueue. + +3. Call init + info->fbdefio = &hecubafb_defio; + fb_deferred_io_init(info); + +4. Call cleanup + fb_deferred_io_cleanup(info); diff --git a/Documentation/fb/s3fb.txt b/Documentation/fb/s3fb.txt index 8a04c0da0c91..2c97770bdbaa 100644 --- a/Documentation/fb/s3fb.txt +++ b/Documentation/fb/s3fb.txt @@ -35,10 +35,12 @@ Supported Features * suspend/resume support * DPMS support -Text mode is supported even in higher resolutions, but there is limitation -to lower pixclocks (maximum between 50-60 MHz, depending on specific hardware). -This limitation is not enforced by driver. Text mode supports 8bit wide fonts -only (hardware limitation) and 16bit tall fonts (driver limitation). +Text mode is supported even in higher resolutions, but there is limitation to +lower pixclocks (maximum usually between 50-60 MHz, depending on specific +hardware, i get best results from plain S3 Trio32 card - about 75 MHz). This +limitation is not enforced by driver. Text mode supports 8bit wide fonts only +(hardware limitation) and 16bit tall fonts (driver limitation). Text mode +support is broken on S3 Trio64 V2/DX. There are two 4 bpp modes. First mode (selected if nonstd == 0) is mode with packed pixels, high nibble first. Second mode (selected if nonstd == 1) is mode @@ -73,6 +75,8 @@ Known bugs ========== * cursor disable in text mode doesn't work + * text mode broken on S3 Trio64 V2/DX + -- Ondrej Zajicek <santiago@crfreenet.org> diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index 5f96cb33743e..2291ff620d93 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -6,6 +6,14 @@ be removed from this file. --------------------------- +What: MXSER +When: December 2007 +Why: Old mxser driver is obsoleted by the mxser_new. Give it some time yet + and remove it. +Who: Jiri Slaby <jirislaby@gmail.com> + +--------------------------- + What: V4L2 VIDIOC_G_MPEGCOMP and VIDIOC_S_MPEGCOMP When: October 2007 Why: Broken attempt to set MPEG compression parameters. These ioctls are @@ -117,18 +125,6 @@ Who: Adrian Bunk <bunk@stusta.de> --------------------------- -What: Usage of invalid timevals in setitimer -When: March 2007 -Why: POSIX requires to validate timevals in the setitimer call. This - was never done by Linux. The invalid (e.g. negative timevals) were - silently converted to more or less random timeouts and intervals. - Until the removal a per boot limited number of warnings is printed - and the timevals are sanitized. - -Who: Thomas Gleixner <tglx@linutronix.de> - ---------------------------- - What: Unused EXPORT_SYMBOL/EXPORT_SYMBOL_GPL exports (temporary transition config option provided until then) The transition config option will also be removed at the same time. @@ -156,7 +152,7 @@ Who: Greg Kroah-Hartman <gregkh@suse.de> --------------------------- What: Interrupt only SA_* flags -When: Januar 2007 +When: September 2007 Why: The interrupt related SA_* flags are replaced by IRQF_* to move them out of the signal namespace. @@ -323,3 +319,11 @@ Why: Obsolete. The new i2c-gpio driver replaces all hardware-specific Who: Jean Delvare <khali@linux-fr.org> --------------------------- + +What: drivers depending on OSS_OBSOLETE +When: options in 2.6.23, code in 2.6.25 +Why: obsolete OSS drivers +Who: Adrian Bunk <bunk@stusta.de> + +--------------------------- + diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking index 28bfea75bcf2..59c14159cc47 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/Locking @@ -15,6 +15,7 @@ prototypes: int (*d_delete)(struct dentry *); void (*d_release)(struct dentry *); void (*d_iput)(struct dentry *, struct inode *); + char *(*d_dname)((struct dentry *dentry, char *buffer, int buflen); locking rules: none have BKL @@ -25,6 +26,7 @@ d_compare: no yes no no d_delete: yes no yes no d_release: no no no yes d_iput: no no no yes +d_dname: no no no no --------------------------- inode_operations --------------------------- prototypes: diff --git a/Documentation/filesystems/jfs.txt b/Documentation/filesystems/jfs.txt index bae128663748..26ebde77e821 100644 --- a/Documentation/filesystems/jfs.txt +++ b/Documentation/filesystems/jfs.txt @@ -29,7 +29,13 @@ errors=continue Keep going on a filesystem error. errors=remount-ro Default. Remount the filesystem read-only on an error. errors=panic Panic and halt the machine if an error occurs. -Please send bugs, comments, cards and letters to shaggy@austin.ibm.com. +uid=value Override on-disk uid with specified value +gid=value Override on-disk gid with specified value +umask=value Override on-disk umask with specified octal value. For + directories, the execute bit will be set if the corresponding + read bit is set. + +Please send bugs, comments, cards and letters to shaggy@linux.vnet.ibm.com. The JFS mailing list can be subscribed to by using the link labeled "Mail list Subscribe" at our web page http://jfs.sourceforge.net/ diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index 3f4b226572e7..4f3e84c520a5 100644 --- a/Documentation/filesystems/proc.txt +++ b/Documentation/filesystems/proc.txt @@ -1138,6 +1138,13 @@ determine whether or not they are still functioning properly. Because the NMI watchdog shares registers with oprofile, by disabling the NMI watchdog, oprofile may have more registers to utilize. +maps_protect +------------ + +Enables/Disables the protection of the per-process proc entries "maps" and +"smaps". When enabled, the contents of these files are visible only to +readers that are allowed to ptrace() the given process. + 2.4 /proc/sys/vm - The virtual memory subsystem ----------------------------------------------- diff --git a/Documentation/filesystems/vfat.txt b/Documentation/filesystems/vfat.txt index 069cb1094300..fcc123ffa252 100644 --- a/Documentation/filesystems/vfat.txt +++ b/Documentation/filesystems/vfat.txt @@ -57,6 +57,13 @@ nonumtail=<bool> -- When creating 8.3 aliases, normally the alias will currently exist in the directory, 'longfile.txt' will be the short alias instead of 'longfi~1.txt'. +usefree -- Use the "free clusters" value stored on FSINFO. It'll + be used to determine number of free clusters without + scanning disk. But it's not used by default, because + recent Windows don't update it correctly in some + case. If you are sure the "free clusters" on FSINFO is + correct, by this option you can avoid scanning disk. + quiet -- Stops printing certain warning messages. check=s|r|n -- Case sensitivity checking setting. diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt index ea271f2d3954..a47cc819f37b 100644 --- a/Documentation/filesystems/vfs.txt +++ b/Documentation/filesystems/vfs.txt @@ -827,7 +827,7 @@ This describes how a filesystem can overload the standard dentry operations. Dentries and the dcache are the domain of the VFS and the individual filesystem implementations. Device drivers have no business here. These methods may be set to NULL, as they are either optional or -the VFS uses a default. As of kernel 2.6.13, the following members are +the VFS uses a default. As of kernel 2.6.22, the following members are defined: struct dentry_operations { @@ -837,6 +837,7 @@ struct dentry_operations { int (*d_delete)(struct dentry *); void (*d_release)(struct dentry *); void (*d_iput)(struct dentry *, struct inode *); + char *(*d_dname)(struct dentry *, char *, int); }; d_revalidate: called when the VFS needs to revalidate a dentry. This @@ -859,6 +860,26 @@ struct dentry_operations { VFS calls iput(). If you define this method, you must call iput() yourself + d_dname: called when the pathname of a dentry should be generated. + Usefull for some pseudo filesystems (sockfs, pipefs, ...) to delay + pathname generation. (Instead of doing it when dentry is created, + its done only when the path is needed.). Real filesystems probably + dont want to use it, because their dentries are present in global + dcache hash, so their hash should be an invariant. As no lock is + held, d_dname() should not try to modify the dentry itself, unless + appropriate SMP safety is used. CAUTION : d_path() logic is quite + tricky. The correct way to return for example "Hello" is to put it + at the end of the buffer, and returns a pointer to the first char. + dynamic_dname() helper function is provided to take care of this. + +Example : + +static char *pipefs_dname(struct dentry *dent, char *buffer, int buflen) +{ + return dynamic_dname(dentry, buffer, buflen, "pipe:[%lu]", + dentry->d_inode->i_ino); +} + 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. diff --git a/Documentation/ioctl-number.txt b/Documentation/ioctl-number.txt index 8f750c0efed5..3de7d379cf07 100644 --- a/Documentation/ioctl-number.txt +++ b/Documentation/ioctl-number.txt @@ -138,7 +138,8 @@ Code Seq# Include File Comments 'm' 00-1F net/irda/irmod.h conflict! 'n' 00-7F linux/ncp_fs.h 'n' E0-FF video/matrox.h matroxfb -'p' 00-3F linux/mc146818rtc.h +'p' 00-0F linux/phantom.h conflict! (OpenHaptics needs this) +'p' 00-3F linux/mc146818rtc.h conflict! 'p' 40-7F linux/nvram.h 'p' 80-9F user-space parport <mailto:tim@cyberelk.net> diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 38d7db3262c7..6b8ad06846c4 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -496,6 +496,30 @@ and is between 256 and 4096 characters. It is defined in the file Format: <area>[,<node>] See also Documentation/networking/decnet.txt. + default_blu= [VT] + Format: <blue0>,<blue1>,<blue2>,...,<blue15> + Change the default blue palette of the console. + This is a 16-member array composed of values + ranging from 0-255. + + default_grn= [VT] + Format: <green0>,<green1>,<green2>,...,<green15> + Change the default green palette of the console. + This is a 16-member array composed of values + ranging from 0-255. + + default_red= [VT] + Format: <red0>,<red1>,<red2>,...,<red15> + Change the default red palette of the console. + This is a 16-member array composed of values + ranging from 0-255. + + default_utf8= [VT] + Format=<0|1> + Set system-wide default UTF-8 mode for all tty's. + Default is 0 and by setting to 1, it enables UTF-8 + mode for all newly opened or allocated terminals. + dhash_entries= [KNL] Set number of hash buckets for dentry cache. @@ -816,6 +840,11 @@ and is between 256 and 4096 characters. It is defined in the file lasi= [HW,SCSI] PARISC LASI driver for the 53c700 chip Format: addr:<io>,irq:<irq> + legacy_serial.force [HW,IA-32,X86-64] + Probe for COM ports at legacy addresses even + if PNPBIOS or ACPI should describe them. This + is for working around firmware defects. + llsc*= [IA64] See function print_params() in arch/ia64/sn/kernel/llsc4.c. @@ -1578,6 +1607,17 @@ and is between 256 and 4096 characters. It is defined in the file smp-alt-once [IA-32,SMP] On a hotplug CPU system, only attempt to substitute SMP alternatives once at boot. + smsc-ircc2.nopnp [HW] Don't use PNP to discover SMC devices + smsc-ircc2.ircc_cfg= [HW] Device configuration I/O port + smsc-ircc2.ircc_sir= [HW] SIR base I/O port + smsc-ircc2.ircc_fir= [HW] FIR base I/O port + smsc-ircc2.ircc_irq= [HW] IRQ line + smsc-ircc2.ircc_dma= [HW] DMA channel + smsc-ircc2.ircc_transceiver= [HW] Transceiver type: + 0: Toshiba Satellite 1800 (GP data pin select) + 1: Fast pin select (default) + 2: ATC IRMode + snd-ad1816a= [HW,ALSA] snd-ad1848= [HW,ALSA] diff --git a/Documentation/kprobes.txt b/Documentation/kprobes.txt index d71fafffce90..da5404ab7569 100644 --- a/Documentation/kprobes.txt +++ b/Documentation/kprobes.txt @@ -14,6 +14,7 @@ CONTENTS 8. Kprobes Example 9. Jprobes Example 10. Kretprobes Example +Appendix A: The kprobes debugfs interface 1. Concepts: Kprobes, Jprobes, Return Probes @@ -349,9 +350,12 @@ for instrumentation and error reporting.) If the number of times a function is called does not match the number of times it returns, registering a return probe on that function may -produce undesirable results. We have the do_exit() case covered. -do_execve() and do_fork() are not an issue. We're unaware of other -specific cases where this could be a problem. +produce undesirable results. In such a case, a line: +kretprobe BUG!: Processing kretprobe d000000000041aa8 @ c00000000004f48c +gets printed. With this information, one will be able to correlate the +exact instance of the kretprobe that caused the problem. We have the +do_exit() case covered. do_execve() and do_fork() are not an issue. +We're unaware of other specific cases where this could be a problem. If, upon entry to or exit from a function, the CPU is running on a stack other than that of the current task, registering a return @@ -614,3 +618,27 @@ http://www-106.ibm.com/developerworks/library/l-kprobes.html?ca=dgr-lnxw42Kprobe http://www.redhat.com/magazine/005mar05/features/kprobes/ http://www-users.cs.umn.edu/~boutcher/kprobes/ http://www.linuxsymposium.org/2006/linuxsymposium_procv2.pdf (pages 101-115) + + +Appendix A: The kprobes debugfs interface + +With recent kernels (> 2.6.20) the list of registered kprobes is visible +under the /debug/kprobes/ directory (assuming debugfs is mounted at /debug). + +/debug/kprobes/list: Lists all registered probes on the system + +c015d71a k vfs_read+0x0 +c011a316 j do_fork+0x0 +c03dedc5 r tcp_v4_rcv+0x0 + +The first column provides the kernel address where the probe is inserted. +The second column identifies the type of probe (k - kprobe, r - kretprobe +and j - jprobe), while the third column specifies the symbol+offset of +the probe. If the probed function belongs to a module, the module name +is also specified. + +/debug/kprobes/enabled: Turn kprobes ON/OFF + +Provides a knob to globally turn registered kprobes ON or OFF. By default, +all kprobes are enabled. By echoing "0" to this file, all registered probes +will be disarmed, till such time a "1" is echoed to this file. diff --git a/Documentation/laptop-mode.txt b/Documentation/laptop-mode.txt index 6f639e3473af..eeedee11c8c2 100644 --- a/Documentation/laptop-mode.txt +++ b/Documentation/laptop-mode.txt @@ -33,7 +33,7 @@ or anything. Simply install all the files included in this document, and laptop mode will automatically be started when you're on battery. For your convenience, a tarball containing an installer can be downloaded at: -http://www.xs4all.nl/~bsamwel/laptop_mode/tools/ +http://www.samwel.tk/laptop_mode/laptop_mode/ To configure laptop mode, you need to edit the configuration file, which is located in /etc/default/laptop-mode on Debian-based systems, or in diff --git a/Documentation/oops-tracing.txt b/Documentation/oops-tracing.txt index ea55ea8bc8ef..7d5b60dea551 100644 --- a/Documentation/oops-tracing.txt +++ b/Documentation/oops-tracing.txt @@ -234,9 +234,6 @@ characters, each representing a particular tainted value. 6: 'B' if a page-release function has found a bad page reference or some unexpected page flags. - 7: 'U' if a user specifically requested that the Tainted flag be set, - ' ' otherwise. - 7: 'U' if a user or user application specifically requested that the Tainted flag be set, ' ' otherwise. diff --git a/Documentation/power/basic-pm-debugging.txt b/Documentation/power/basic-pm-debugging.txt new file mode 100644 index 000000000000..1a85e2b964dc --- /dev/null +++ b/Documentation/power/basic-pm-debugging.txt @@ -0,0 +1,106 @@ +Debugging suspend and resume + (C) 2007 Rafael J. Wysocki <rjw@sisk.pl>, GPL + +1. Testing suspend to disk (STD) + +To verify that the STD works, you can try to suspend in the "reboot" mode: + +# echo reboot > /sys/power/disk +# echo disk > /sys/power/state + +and the system should suspend, reboot, resume and get back to the command prompt +where you have started the transition. If that happens, the STD is most likely +to work correctly, but you need to repeat the test at least a couple of times in +a row for confidence. This is necessary, because some problems only show up on +a second attempt at suspending and resuming the system. You should also test +the "platform" and "shutdown" modes of suspend: + +# echo platform > /sys/power/disk +# echo disk > /sys/power/state + +or + +# echo shutdown > /sys/power/disk +# echo disk > /sys/power/state + +in which cases you will have to press the power button to make the system +resume. If that does not work, you will need to identify what goes wrong. + +a) Test mode of STD + +To verify if there are any drivers that cause problems you can run the STD +in the test mode: + +# echo test > /sys/power/disk +# echo disk > /sys/power/state + +in which case the system should freeze tasks, suspend devices, disable nonboot +CPUs (if any), wait for 5 seconds, enable nonboot CPUs, resume devices, thaw +tasks and return to your command prompt. If that fails, most likely there is +a driver that fails to either suspend or resume (in the latter case the system +may hang or be unstable after the test, so please take that into consideration). +To find this driver, you can carry out a binary search according to the rules: +- if the test fails, unload a half of the drivers currently loaded and repeat +(that would probably involve rebooting the system, so always note what drivers +have been loaded before the test), +- if the test succeeds, load a half of the drivers you have unloaded most +recently and repeat. + +Once you have found the failing driver (there can be more than just one of +them), you have to unload it every time before the STD transition. In that case +please make sure to report the problem with the driver. + +It is also possible that a cycle can still fail after you have unloaded +all modules. In that case, you would want to look in your kernel configuration +for the drivers that can be compiled as modules (testing again with them as +modules), and possibly also try boot time options such as "noapic" or "noacpi". + +b) Testing minimal configuration + +If the test mode of STD works, you can boot the system with "init=/bin/bash" +and attempt to suspend in the "reboot", "shutdown" and "platform" modes. If +that does not work, there probably is a problem with a driver statically +compiled into the kernel and you can try to compile more drivers as modules, +so that they can be tested individually. Otherwise, there is a problem with a +modular driver and you can find it by loading a half of the modules you normally +use and binary searching in accordance with the algorithm: +- if there are n modules loaded and the attempt to suspend and resume fails, +unload n/2 of the modules and try again (that would probably involve rebooting +the system), +- if there are n modules loaded and the attempt to suspend and resume succeeds, +load n/2 modules more and try again. + +Again, if you find the offending module(s), it(they) must be unloaded every time +before the STD transition, and please report the problem with it(them). + +c) Advanced debugging + +In case the STD does not work on your system even in the minimal configuration +and compiling more drivers as modules is not practical or some modules cannot +be unloaded, you can use one of the more advanced debugging techniques to find +the problem. First, if there is a serial port in your box, you can set the +CONFIG_DISABLE_CONSOLE_SUSPEND kernel configuration option and try to log kernel +messages using the serial console. This may provide you with some information +about the reasons of the suspend (resume) failure. Alternatively, it may be +possible to use a FireWire port for debugging with firescope +(ftp://ftp.firstfloor.org/pub/ak/firescope/). On i386 it is also possible to +use the PM_TRACE mechanism documented in Documentation/s2ram.txt . + +2. Testing suspend to RAM (STR) + +To verify that the STR works, it is generally more convenient to use the s2ram +tool available from http://suspend.sf.net and documented at +http://en.opensuse.org/s2ram . However, before doing that it is recommended to +carry out the procedure described in section 1. + +Assume you have resolved the problems with the STD and you have found some +failing drivers. These drivers are also likely to fail during the STR or +during the resume, so it is better to unload them every time before the STR +transition. Now, you can follow the instructions at +http://en.opensuse.org/s2ram to test the system, but if it does not work +"out of the box", you may need to boot it with "init=/bin/bash" and test +s2ram in the minimal configuration. In that case, you may be able to search +for failing drivers by following the procedure analogous to the one described in +1b). If you find some failing drivers, you will have to unload them every time +before the STR transition (ie. before you run s2ram), and please report the +problems with them. diff --git a/Documentation/power/drivers-testing.txt b/Documentation/power/drivers-testing.txt new file mode 100644 index 000000000000..33016c2f18dd --- /dev/null +++ b/Documentation/power/drivers-testing.txt @@ -0,0 +1,42 @@ +Testing suspend and resume support in device drivers + (C) 2007 Rafael J. Wysocki <rjw@sisk.pl>, GPL + +1. Preparing the test system + +Unfortunately, to effectively test the support for the system-wide suspend and +resume transitions in a driver, it is necessary to suspend and resume a fully +functional system with this driver loaded. Moreover, that should be done +several times, preferably several times in a row, and separately for the suspend +to disk (STD) and the suspend to RAM (STR) transitions, because each of these +cases involves different ordering of operations and different interactions with +the machine's BIOS. + +Of course, for this purpose the test system has to be known to suspend and +resume without the driver being tested. Thus, if possible, you should first +resolve all suspend/resume-related problems in the test system before you start +testing the new driver. Please see Documents/power/basic-pm-debugging.txt for +more information about the debugging of suspend/resume functionality. + +2. Testing the driver + +Once you have resolved the suspend/resume-related problems with your test system +without the new driver, you are ready to test it: + +a) Build the driver as a module, load it and try the STD in the test mode (see: +Documents/power/basic-pm-debugging.txt, 1a)). + +b) Load the driver and attempt to suspend to disk in the "reboot", "shutdown" +and "platform" modes (see: Documents/power/basic-pm-debugging.txt, 1). + +c) Compile the driver directly into the kernel and try the STD in the test mode. + +d) Attempt to suspend to disk with the driver compiled directly into the kernel +in the "reboot", "shutdown" and "platform" modes. + +e) Attempt to suspend to RAM using the s2ram tool with the driver loaded (see: +Documents/power/basic-pm-debugging.txt, 2). As far as the STR tests are +concerned, it should not matter whether or not the driver is built as a module. + +Each of the above tests should be repeated several times and the STD tests +should be mixed with the STR tests. If any of them fails, the driver cannot be +regarded as suspend/resume-safe. diff --git a/Documentation/powerpc/booting-without-of.txt b/Documentation/powerpc/booting-without-of.txt index 033a3f3b3ab7..d4bfae75c946 100644 --- a/Documentation/powerpc/booting-without-of.txt +++ b/Documentation/powerpc/booting-without-of.txt @@ -1560,6 +1560,9 @@ platforms are moved over to use the flattened-device-tree model. network device. This is used by the bootwrapper to interpret MAC addresses passed by the firmware when no information other than indices is available to associate an address with a device. + - phy-connection-type : a string naming the controller/PHY interface type, + i.e., "mii" (default), "rmii", "gmii", "rgmii", "rgmii-id", "tbi", + or "rtbi". Example: ucc@2000 { @@ -1574,6 +1577,7 @@ platforms are moved over to use the flattened-device-tree model. rx-clock = "none"; tx-clock = "clk9"; phy-handle = <212000>; + phy-connection-type = "gmii"; pio-handle = <140001>; }; diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt index 1ef6bb88cd00..7c701b88d6d5 100644 --- a/Documentation/rtc.txt +++ b/Documentation/rtc.txt @@ -147,7 +147,7 @@ RTC class framework, but can't be supported by the older driver. * RTC_AIE_ON, RTC_AIE_OFF, RTC_ALM_SET, RTC_ALM_READ ... when the RTC is connected to an IRQ line, it can often issue an alarm IRQ up to - 24 hours in the future. + 24 hours in the future. (Use RTC_WKALM_* by preference.) * RTC_WKALM_SET, RTC_WKALM_RD ... RTCs that can issue alarms beyond the next 24 hours use a slightly more powerful API, which supports @@ -175,10 +175,7 @@ driver returns ENOIOCTLCMD. Some common examples: called with appropriate values. * RTC_ALM_SET, RTC_ALM_READ, RTC_WKALM_SET, RTC_WKALM_RD: the - set_alarm/read_alarm functions will be called. To differentiate - between the ALM and WKALM, check the larger fields of the rtc_wkalrm - struct (like tm_year). These will be set to -1 when using ALM and - will be set to proper values when using WKALM. + set_alarm/read_alarm functions will be called. * RTC_IRQP_SET, RTC_IRQP_READ: the irq_set_freq function will be called to set the frequency while the framework will handle the read for you diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary index ecc7c9eb9f29..795fbb48ffa7 100644 --- a/Documentation/spi/spi-summary +++ b/Documentation/spi/spi-summary @@ -8,7 +8,7 @@ What is SPI? The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial link used to connect microcontrollers to sensors, memory, and peripherals. -The three signal wires hold a clock (SCLK, often on the order of 10 MHz), +The three signal wires hold a clock (SCK, often on the order of 10 MHz), and parallel data lines with "Master Out, Slave In" (MOSI) or "Master In, Slave Out" (MISO) signals. (Other names are also used.) There are four clocking modes through which data is exchanged; mode-0 and mode-3 are most @@ -22,7 +22,7 @@ other signals, often including an interrupt to the master. Unlike serial busses like USB or SMBUS, even low level protocols for SPI slave functions are usually not interoperable between vendors -(except for cases like SPI memory chips). +(except for commodities like SPI memory chips). - SPI may be used for request/response style device protocols, as with touchscreen sensors and memory chips. @@ -77,8 +77,9 @@ cards without needing a special purpose MMC/SD/SDIO controller. How do these driver programming interfaces work? ------------------------------------------------ The <linux/spi/spi.h> header file includes kerneldoc, as does the -main source code, and you should certainly read that. This is just -an overview, so you get the big picture before the details. +main source code, and you should certainly read that chapter of the +kernel API document. This is just an overview, so you get the big +picture before those details. SPI requests always go into I/O queues. Requests for a given SPI device are always executed in FIFO order, and complete asynchronously through @@ -88,7 +89,7 @@ a command and then reading its response. There are two types of SPI driver, here called: - Controller drivers ... these are often built in to System-On-Chip + Controller drivers ... controllers may be built in to System-On-Chip processors, and often support both Master and Slave roles. These drivers touch hardware registers and may use DMA. Or they can be PIO bitbangers, needing just GPIO pins. @@ -108,18 +109,18 @@ those two types of driver. At this writing, Linux has no slave side programming interface. There is a minimal core of SPI programming interfaces, focussing on -using driver model to connect controller and protocol drivers using +using the driver model to connect controller and protocol drivers using device tables provided by board specific initialization code. SPI shows up in sysfs in several locations: - /sys/devices/.../CTLR/spiB.C ... spi_device for on bus "B", + /sys/devices/.../CTLR/spiB.C ... spi_device on bus "B", chipselect C, accessed through CTLR. /sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver that should be used with this device (for hotplug/coldplug) /sys/bus/spi/devices/spiB.C ... symlink to the physical - spiB-C device + spiB.C device /sys/bus/spi/drivers/D ... driver for one or more spi*.* devices @@ -240,7 +241,7 @@ The board_info should provide enough information to let the system work without the chip's driver being loaded. The most troublesome aspect of that is likely the SPI_CS_HIGH bit in the spi_device.mode field, since sharing a bus with a device that interprets chipselect "backwards" is -not possible. +not possible until the infrastructure knows how to deselect it. Then your board initialization code would register that table with the SPI infrastructure, so that it's available later when the SPI master controller @@ -268,16 +269,14 @@ board info based on the board that was hotplugged. Of course, you'd later call at least spi_unregister_device() when that board is removed. When Linux includes support for MMC/SD/SDIO/DataFlash cards through SPI, those -configurations will also be dynamic. Fortunately, those devices all support -basic device identification probes, so that support should hotplug normally. +configurations will also be dynamic. Fortunately, such devices all support +basic device identification probes, so they should hotplug normally. How do I write an "SPI Protocol Driver"? ---------------------------------------- -All SPI drivers are currently kernel drivers. A userspace driver API -would just be another kernel driver, probably offering some lowlevel -access through aio_read(), aio_write(), and ioctl() calls and using the -standard userspace sysfs mechanisms to bind to a given SPI device. +Most SPI drivers are currently kernel drivers, but there's also support +for userspace drivers. Here we talk only about kernel drivers. SPI protocol drivers somewhat resemble platform device drivers: @@ -319,7 +318,8 @@ might look like this unless you're creating a class_device: As soon as it enters probe(), the driver may issue I/O requests to the SPI device using "struct spi_message". When remove() returns, -the driver guarantees that it won't submit any more such messages. +or after probe() fails, the driver guarantees that it won't submit +any more such messages. - An spi_message is a sequence of protocol operations, executed as one atomic sequence. SPI driver controls include: @@ -368,7 +368,8 @@ the driver guarantees that it won't submit any more such messages. Some drivers may need to modify spi_device characteristics like the transfer mode, wordsize, or clock rate. This is done with spi_setup(), which would normally be called from probe() before the first I/O is -done to the device. +done to the device. However, that can also be called at any time +that no message is pending for that device. While "spi_device" would be the bottom boundary of the driver, the upper boundaries might include sysfs (especially for sensor readings), @@ -445,11 +446,15 @@ SPI MASTER METHODS This sets up the device clock rate, SPI mode, and word sizes. Drivers may change the defaults provided by board_info, and then call spi_setup(spi) to invoke this routine. It may sleep. + Unless each SPI slave has its own configuration registers, don't + change them right away ... otherwise drivers could corrupt I/O + that's in progress for other SPI devices. master->transfer(struct spi_device *spi, struct spi_message *message) This must not sleep. Its responsibility is arrange that the - transfer happens and its complete() callback is issued; the two - will normally happen later, after other transfers complete. + transfer happens and its complete() callback is issued. The two + will normally happen later, after other transfers complete, and + if the controller is idle it will need to be kickstarted. master->cleanup(struct spi_device *spi) Your controller driver may use spi_device.controller_state to hold diff --git a/Documentation/spi/spidev b/Documentation/spi/spidev new file mode 100644 index 000000000000..5c8e1b988a08 --- /dev/null +++ b/Documentation/spi/spidev @@ -0,0 +1,307 @@ +SPI devices have a limited userspace API, supporting basic half-duplex +read() and write() access to SPI slave devices. Using ioctl() requests, +full duplex transfers and device I/O configuration are also available. + + #include <fcntl.h> + #include <unistd.h> + #include <sys/ioctl.h> + #include <linux/types.h> + #include <linux/spi/spidev.h> + +Some reasons you might want to use this programming interface include: + + * Prototyping in an environment that's not crash-prone; stray pointers + in userspace won't normally bring down any Linux system. + + * Developing simple protocols used to talk to microcontrollers acting + as SPI slaves, which you may need to change quite often. + +Of course there are drivers that can never be written in userspace, because +they need to access kernel interfaces (such as IRQ handlers or other layers +of the driver stack) that are not accessible to userspace. + + +DEVICE CREATION, DRIVER BINDING +=============================== +The simplest way to arrange to use this driver is to just list it in the +spi_board_info for a device as the driver it should use: the "modalias" +entry is "spidev", matching the name of the driver exposing this API. +Set up the other device characteristics (bits per word, SPI clocking, +chipselect polarity, etc) as usual, so you won't always need to override +them later. + +(Sysfs also supports userspace driven binding/unbinding of drivers to +devices. That mechanism might be supported here in the future.) + +When you do that, the sysfs node for the SPI device will include a child +device node with a "dev" attribute that will be understood by udev or mdev. +(Larger systems will have "udev". Smaller ones may configure "mdev" into +busybox; it's less featureful, but often enough.) For a SPI device with +chipselect C on bus B, you should see: + + /dev/spidevB.C ... character special device, major number 153 with + a dynamically chosen minor device number. This is the node + that userspace programs will open, created by "udev" or "mdev". + + /sys/devices/.../spiB.C ... as usual, the SPI device node will + be a child of its SPI master controller. + + /sys/class/spidev/spidevB.C ... created when the "spidev" driver + binds to that device. (Directory or symlink, based on whether + or not you enabled the "deprecated sysfs files" Kconfig option.) + +Do not try to manage the /dev character device special file nodes by hand. +That's error prone, and you'd need to pay careful attention to system +security issues; udev/mdev should already be configured securely. + +If you unbind the "spidev" driver from that device, those two "spidev" nodes +(in sysfs and in /dev) should automatically be removed (respectively by the +kernel and by udev/mdev). You can unbind by removing the "spidev" driver +module, which will affect all devices using this driver. You can also unbind +by having kernel code remove the SPI device, probably by removing the driver +for its SPI controller (so its spi_master vanishes). + +Since this is a standard Linux device driver -- even though it just happens +to expose a low level API to userspace -- it can be associated with any number +of devices at a time. Just provide one spi_board_info record for each such +SPI device, and you'll get a /dev device node for each device. + + +BASIC CHARACTER DEVICE API +========================== +Normal open() and close() operations on /dev/spidevB.D files work as you +would expect. + +Standard read() and write() operations are obviously only half-duplex, and +the chipselect is deactivated between those operations. Full-duplex access, +and composite operation without chipselect de-activation, is available using +the SPI_IOC_MESSAGE(N) request. + +Several ioctl() requests let your driver read or override the device's current +settings for data transfer parameters: + + SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ... pass a pointer to a byte which will + return (RD) or assign (WR) the SPI transfer mode. Use the constants + SPI_MODE_0..SPI_MODE_3; or if you prefer you can combine SPI_CPOL + (clock polarity, idle high iff this is set) or SPI_CPHA (clock phase, + sample on trailing edge iff this is set) flags. + + SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... pass a pointer to a byte + which will return (RD) or assign (WR) the bit justification used to + transfer SPI words. Zero indicates MSB-first; other values indicate + the less common LSB-first encoding. In both cases the specified value + is right-justified in each word, so that unused (TX) or undefined (RX) + bits are in the MSBs. + + SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ... pass a pointer to + a byte which will return (RD) or assign (WR) the number of bits in + each SPI transfer word. The value zero signifies eight bits. + + SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ... pass a pointer to a + u32 which will return (RD) or assign (WR) the maximum SPI transfer + speed, in Hz. The controller can't necessarily assign that specific + clock speed. + +NOTES: + + - At this time there is no async I/O support; everything is purely + synchronous. + + - There's currently no way to report the actual bit rate used to + shift data to/from a given device. + + - From userspace, you can't currently change the chip select polarity; + that could corrupt transfers to other devices sharing the SPI bus. + Each SPI device is deselected when it's not in active use, allowing + other drivers to talk to other devices. + + - There's a limit on the number of bytes each I/O request can transfer + to the SPI device. It defaults to one page, but that can be changed + using a module parameter. + + - Because SPI has no low-level transfer acknowledgement, you usually + won't see any I/O errors when talking to a non-existent device. + + +FULL DUPLEX CHARACTER DEVICE API +================================ + +See the sample program below for one example showing the use of the full +duplex programming interface. (Although it doesn't perform a full duplex +transfer.) The model is the same as that used in the kernel spi_sync() +request; the individual transfers offer the same capabilities as are +available to kernel drivers (except that it's not asynchronous). + +The example shows one half-duplex RPC-style request and response message. +These requests commonly require that the chip not be deselected between +the request and response. Several such requests could be chained into +a single kernel request, even allowing the chip to be deselected after +each response. (Other protocol options include changing the word size +and bitrate for each transfer segment.) + +To make a full duplex request, provide both rx_buf and tx_buf for the +same transfer. It's even OK if those are the same buffer. + + +SAMPLE PROGRAM +============== + +-------------------------------- CUT HERE +#include <stdio.h> +#include <unistd.h> +#include <stdlib.h> +#include <fcntl.h> +#include <string.h> + +#include <sys/ioctl.h> +#include <sys/types.h> +#include <sys/stat.h> + +#include <linux/types.h> +#include <linux/spi/spidev.h> + + +static int verbose; + +static void do_read(int fd, int len) +{ + unsigned char buf[32], *bp; + int status; + + /* read at least 2 bytes, no more than 32 */ + if (len < 2) + len = 2; + else if (len > sizeof(buf)) + len = sizeof(buf); + memset(buf, 0, sizeof buf); + + status = read(fd, buf, len); + if (status < 0) { + perror("read"); + return; + } + if (status != len) { + fprintf(stderr, "short read\n"); + return; + } + + printf("read(%2d, %2d): %02x %02x,", len, status, + buf[0], buf[1]); + status -= 2; + bp = buf + 2; + while (status-- > 0) + printf(" %02x", *bp++); + printf("\n"); +} + +static void do_msg(int fd, int len) +{ + struct spi_ioc_transfer xfer[2]; + unsigned char buf[32], *bp; + int status; + + memset(xfer, 0, sizeof xfer); + memset(buf, 0, sizeof buf); + + if (len > sizeof buf) + len = sizeof buf; + + buf[0] = 0xaa; + xfer[0].tx_buf = (__u64) buf; + xfer[0].len = 1; + + xfer[1].rx_buf = (__u64) buf; + xfer[1].len = len; + + status = ioctl(fd, SPI_IOC_MESSAGE(2), xfer); + if (status < 0) { + perror("SPI_IOC_MESSAGE"); + return; + } + + printf("response(%2d, %2d): ", len, status); + for (bp = buf; len; len--) + printf(" %02x", *bp++); + printf("\n"); +} + +static void dumpstat(const char *name, int fd) +{ + __u8 mode, lsb, bits; + __u32 speed; + + if (ioctl(fd, SPI_IOC_RD_MODE, &mode) < 0) { + perror("SPI rd_mode"); + return; + } + if (ioctl(fd, SPI_IOC_RD_LSB_FIRST, &lsb) < 0) { + perror("SPI rd_lsb_fist"); + return; + } + if (ioctl(fd, SPI_IOC_RD_BITS_PER_WORD, &bits) < 0) { + perror("SPI bits_per_word"); + return; + } + if (ioctl(fd, SPI_IOC_RD_MAX_SPEED_HZ, &speed) < 0) { + perror("SPI max_speed_hz"); + return; + } + + printf("%s: spi mode %d, %d bits %sper word, %d Hz max\n", + name, mode, bits, lsb ? "(lsb first) " : "", speed); +} + +int main(int argc, char **argv) +{ + int c; + int readcount = 0; + int msglen = 0; + int fd; + const char *name; + + while ((c = getopt(argc, argv, "hm:r:v")) != EOF) { + switch (c) { + case 'm': + msglen = atoi(optarg); + if (msglen < 0) + goto usage; + continue; + case 'r': + readcount = atoi(optarg); + if (readcount < 0) + goto usage; + continue; + case 'v': + verbose++; + continue; + case 'h': + case '?': +usage: + fprintf(stderr, + "usage: %s [-h] [-m N] [-r N] /dev/spidevB.D\n", + argv[0]); + return 1; + } + } + + if ((optind + 1) != argc) + goto usage; + name = argv[optind]; + + fd = open(name, O_RDWR); + if (fd < 0) { + perror("open"); + return 1; + } + + dumpstat(name, fd); + + if (msglen) + do_msg(fd, msglen); + + if (readcount) + do_read(fd, readcount); + + close(fd); + return 0; +} diff --git a/Documentation/tty.txt b/Documentation/tty.txt index 5f799e612e03..048a8762cfb5 100644 --- a/Documentation/tty.txt +++ b/Documentation/tty.txt @@ -108,7 +108,9 @@ hardware driver through the function pointers within the tty->driver structure: write() Write a block of characters to the tty device. - Returns the number of characters accepted. + Returns the number of characters accepted. The + character buffer passed to this method is already + in kernel space. put_char() Queues a character for writing to the tty device. If there is no room in the queue, the character is |