diff options
Diffstat (limited to 'Documentation')
78 files changed, 3645 insertions, 694 deletions
diff --git a/Documentation/ABI/testing/debugfs-pktcdvd b/Documentation/ABI/testing/debugfs-pktcdvd new file mode 100644 index 00000000000..03dbd883cc4 --- /dev/null +++ b/Documentation/ABI/testing/debugfs-pktcdvd @@ -0,0 +1,20 @@ +What: /debug/pktcdvd/pktcdvd[0-7] +Date: Oct. 2006 +KernelVersion: 2.6.19 +Contact: Thomas Maier <balagi@justmail.de> +Description: + +debugfs interface +----------------- + +The pktcdvd module (packet writing driver) creates +these files in debugfs: + +/debug/pktcdvd/pktcdvd[0-7]/ + info (0444) Lots of human readable driver + statistics and infos. Multiple lines! + +Example: +------- + +cat /debug/pktcdvd/pktcdvd0/info diff --git a/Documentation/ABI/testing/sysfs-class-pktcdvd b/Documentation/ABI/testing/sysfs-class-pktcdvd new file mode 100644 index 00000000000..c4c55edc9a5 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-pktcdvd @@ -0,0 +1,72 @@ +What: /sys/class/pktcdvd/ +Date: Oct. 2006 +KernelVersion: 2.6.19 +Contact: Thomas Maier <balagi@justmail.de> +Description: + +sysfs interface +--------------- + +The pktcdvd module (packet writing driver) creates +these files in the sysfs: +(<devid> is in format major:minor ) + +/sys/class/pktcdvd/ + add (0200) Write a block device id (major:minor) + to create a new pktcdvd device and map + it to the block device. + + remove (0200) Write the pktcdvd device id (major:minor) + to it to remove the pktcdvd device. + + device_map (0444) Shows the device mapping in format: + pktcdvd[0-7] <pktdevid> <blkdevid> + +/sys/class/pktcdvd/pktcdvd[0-7]/ + dev (0444) Device id + uevent (0200) To send an uevent. + +/sys/class/pktcdvd/pktcdvd[0-7]/stat/ + packets_started (0444) Number of started packets. + packets_finished (0444) Number of finished packets. + + kb_written (0444) kBytes written. + kb_read (0444) kBytes read. + kb_read_gather (0444) kBytes read to fill write packets. + + reset (0200) Write any value to it to reset + pktcdvd device statistic values, like + bytes read/written. + +/sys/class/pktcdvd/pktcdvd[0-7]/write_queue/ + size (0444) Contains the size of the bio write + queue. + + congestion_off (0644) If bio write queue size is below + this mark, accept new bio requests + from the block layer. + + congestion_on (0644) If bio write queue size is higher + as this mark, do no longer accept + bio write requests from the block + layer and wait till the pktcdvd + device has processed enough bio's + so that bio write queue size is + below congestion off mark. + A value of <= 0 disables congestion + control. + + +Example: +-------- +To use the pktcdvd sysfs interface directly, you can do: + +# create a new pktcdvd device mapped to /dev/hdc +echo "22:0" >/sys/class/pktcdvd/add +cat /sys/class/pktcdvd/device_map +# assuming device pktcdvd0 was created, look at stat's +cat /sys/class/pktcdvd/pktcdvd0/stat/kb_written +# print the device id of the mapped block device +fgrep pktcdvd0 /sys/class/pktcdvd/device_map +# remove device, using pktcdvd0 device id 253:0 +echo "253:0" >/sys/class/pktcdvd/remove diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index 29c18966b05..9069189e78e 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -35,12 +35,37 @@ In short, 8-char indents make things easier to read, and have the added benefit of warning you when you're nesting your functions too deep. Heed that warning. +The preferred way to ease multiple indentation levels in a switch statement is +to align the "switch" and its subordinate "case" labels in the same column +instead of "double-indenting" the "case" labels. E.g.: + + switch (suffix) { + case 'G': + case 'g': + mem <<= 30; + break; + case 'M': + case 'm': + mem <<= 20; + break; + case 'K': + case 'k': + mem <<= 10; + /* fall through */ + default: + break; + } + + Don't put multiple statements on a single line unless you have something to hide: if (condition) do_this; do_something_everytime; +Don't put multiple assignments on a single line either. Kernel coding style +is super simple. Avoid tricky expressions. + Outside of comments, documentation and except in Kconfig, spaces are never used for indentation, and the above example is deliberately broken. @@ -69,7 +94,7 @@ void fun(int a, int b, int c) next_statement; } - Chapter 3: Placing Braces + Chapter 3: Placing Braces and Spaces The other issue that always comes up in C styling is the placement of braces. Unlike the indent size, there are few technical reasons to @@ -81,6 +106,20 @@ brace last on the line, and put the closing brace first, thusly: we do y } +This applies to all non-function statement blocks (if, switch, for, +while, do). E.g.: + + switch (action) { + case KOBJ_ADD: + return "add"; + case KOBJ_REMOVE: + return "remove"; + case KOBJ_CHANGE: + return "change"; + default: + return NULL; + } + However, there is one special case, namely functions: they have the opening brace at the beginning of the next line, thus: @@ -121,6 +160,49 @@ 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. + 3.1: Spaces + +Linux kernel style for use of spaces depends (mostly) on +function-versus-keyword usage. Use a space after (most) keywords. The +notable exceptions are sizeof, typeof, alignof, and __attribute__, which look +somewhat like functions (and are usually used with parentheses in Linux, +although they are not required in the language, as in: "sizeof info" after +"struct fileinfo info;" is declared). + +So use a space after these keywords: + if, switch, case, for, do, while +but not with sizeof, typeof, alignof, or __attribute__. E.g., + s = sizeof(struct file); + +Do not add spaces around (inside) parenthesized expressions. This example is +*bad*: + + s = sizeof( struct file ); + +When declaring pointer data or a function that returns a pointer type, the +preferred use of '*' is adjacent to the data name or function name and not +adjacent to the type name. Examples: + + char *linux_banner; + unsigned long long memparse(char *ptr, char **retptr); + char *match_strdup(substring_t *s); + +Use one space around (on each side of) most binary and ternary operators, +such as any of these: + + = + - < > * / % | & ^ <= >= == != ? : + +but no space after unary operators: + & * + - ~ ! sizeof typeof alignof __attribute__ defined + +no space before the postfix increment & decrement unary operators: + ++ -- + +no space after the prefix increment & decrement unary operators: + ++ -- + +and no space around the '.' and "->" structure member operators. + Chapter 4: Naming @@ -152,7 +234,7 @@ variable that is used to hold a temporary value. If you are afraid to mix up your local variable names, you have another problem, which is called the function-growth-hormone-imbalance syndrome. -See next chapter. +See chapter 6 (Functions). Chapter 5: Typedefs @@ -258,6 +340,20 @@ generally easily keep track of about 7 different things, anything more and it gets confused. You know you're brilliant, but maybe you'd like to understand what you did 2 weeks from now. +In source files, separate functions with one blank line. If the function is +exported, the EXPORT* macro for it should follow immediately after the closing +function brace line. E.g.: + +int system_is_up(void) +{ + return system_state == SYSTEM_RUNNING; +} +EXPORT_SYMBOL(system_is_up); + +In function prototypes, include parameter names with their data types. +Although this is not required by the C language, it is preferred in Linux +because it is a simple way to add valuable information for the reader. + Chapter 7: Centralized exiting of functions @@ -306,16 +402,36 @@ time to explain badly written code. Generally, you want your comments to tell WHAT your code does, not HOW. Also, try to avoid putting comments inside a function body: if the function is so complex that you need to separately comment parts of it, -you should probably go back to chapter 5 for a while. You can make +you should probably go back to chapter 6 for a while. You can make small comments to note or warn about something particularly clever (or ugly), but try to avoid excess. Instead, put the comments at the head of the function, telling people what it does, and possibly WHY it does it. -When commenting the kernel API functions, please use the kerneldoc format. +When commenting the kernel API functions, please use the kernel-doc format. See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc for details. +Linux style for comments is the C89 "/* ... */" style. +Don't use C99-style "// ..." comments. + +The preferred style for long (multi-line) comments is: + + /* + * This is the preferred style for multi-line + * comments in the Linux kernel source code. + * Please use it consistently. + * + * Description: A column of asterisks on the left side, + * with beginning and ending almost-blank lines. + */ + +It's also important to comment data, whether they are basic types or derived +types. To this end, use just one data declaration per line (no commas for +multiple data declarations). This leaves you room for a small comment on each +item, explaining its use. + + Chapter 9: You've made a mess of it That's OK, we all do. You've probably been told by your long-time Unix @@ -566,6 +682,24 @@ result. Typical examples would be functions that return pointers; they use NULL or the ERR_PTR mechanism to report failure. + Chapter 17: Don't re-invent the kernel macros + +The header file include/linux/kernel.h contains a number of macros that +you should use, rather than explicitly coding some variant of them yourself. +For example, if you need to calculate the length of an array, take advantage +of the macro + + #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) + +Similarly, if you need to calculate the size of some structure member, use + + #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f)) + +There are also min() and max() macros that do strict type checking if you +need them. Feel free to peruse that header file to see what else is already +defined that you shouldn't reproduce in your code. + + Appendix I: References @@ -591,4 +725,4 @@ Kernel CodingStyle, by greg@kroah.com at OLS 2002: http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ -- -Last updated on 30 April 2006. +Last updated on 2006-December-06. diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 36526a1e76d..867608ab3ca 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -53,8 +53,8 @@ installmandocs: mandocs ### #External programs used -KERNELDOC = scripts/kernel-doc -DOCPROC = scripts/basic/docproc +KERNELDOC = $(srctree)/scripts/kernel-doc +DOCPROC = $(objtree)/scripts/basic/docproc XMLTOFLAGS = -m $(srctree)/Documentation/DocBook/stylesheet.xsl #XMLTOFLAGS += --skip-validation diff --git a/Documentation/DocBook/genericirq.tmpl b/Documentation/DocBook/genericirq.tmpl index 0f4a4b6321e..4215f69ce7e 100644 --- a/Documentation/DocBook/genericirq.tmpl +++ b/Documentation/DocBook/genericirq.tmpl @@ -303,10 +303,10 @@ desc->status |= running; do { if (desc->status & masked) desc->chip->enable(); - desc-status &= ~pending; + desc->status &= ~pending; handle_IRQ_event(desc->action); } while (status & pending); -desc-status &= ~running; +desc->status &= ~running; desc->chip->end(); </programlisting> </para> diff --git a/Documentation/DocBook/libata.tmpl b/Documentation/DocBook/libata.tmpl index 07a635590b3..e2e24b4778d 100644 --- a/Documentation/DocBook/libata.tmpl +++ b/Documentation/DocBook/libata.tmpl @@ -883,7 +883,7 @@ and other resources, etc. </chapter> <chapter id="ataExceptions"> - <title>ATA errors & exceptions</title> + <title>ATA errors and exceptions</title> <para> This chapter tries to identify what error/exception conditions exist diff --git a/Documentation/HOWTO b/Documentation/HOWTO index 8d51c148f72..48123dba5e6 100644 --- a/Documentation/HOWTO +++ b/Documentation/HOWTO @@ -30,6 +30,7 @@ are not a good substitute for a solid C education and/or years of experience, the following books are good for, if anything, reference: - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] - "Practical C Programming" by Steve Oualline [O'Reilly] + - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] The kernel is written using GNU C and the GNU toolchain. While it adheres to the ISO C89 standard, it uses a number of extensions that are diff --git a/Documentation/SubmitChecklist b/Documentation/SubmitChecklist index 7ac61f60037..bfbb2718a27 100644 --- a/Documentation/SubmitChecklist +++ b/Documentation/SubmitChecklist @@ -66,3 +66,13 @@ kernel patches. See Documentation/ABI/README for more information. 20: Check that it all passes `make headers_check'. + +21: Has been checked with injection of at least slab and page-allocation + fauilures. See Documentation/fault-injection/. + + If the new code is substantial, addition of subsystem-specific fault + injection might be appropriate. + +22: Newly-added code has been compiled with `gcc -W'. This will generate + lots of noise, but is good for finding bugs like "warning: comparison + between signed and unsigned". diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 302d148c2e1..b0d0043f7c4 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -134,9 +134,9 @@ Do not send more than 15 patches at once to the vger mailing lists!!! Linus Torvalds is the final arbiter of all changes accepted into the -Linux kernel. His e-mail address is <torvalds@osdl.org>. He gets -a lot of e-mail, so typically you should do your best to -avoid- sending -him e-mail. +Linux kernel. His e-mail address is <torvalds@linux-foundation.org>. +He gets a lot of e-mail, so typically you should do your best to -avoid- +sending him e-mail. Patches which are bug fixes, are "obvious" changes, or similarly require little discussion should be sent or CC'd to Linus. Patches diff --git a/Documentation/accounting/getdelays.c b/Documentation/accounting/getdelays.c index bf2b0e2f87e..e9126e794ed 100644 --- a/Documentation/accounting/getdelays.c +++ b/Documentation/accounting/getdelays.c @@ -7,6 +7,8 @@ * Copyright (C) Balbir Singh, IBM Corp. 2006 * Copyright (c) Jay Lan, SGI. 2006 * + * Compile with + * gcc -I/usr/src/linux/include getdelays.c -o getdelays */ #include <stdio.h> @@ -35,13 +37,20 @@ #define NLA_DATA(na) ((void *)((char*)(na) + NLA_HDRLEN)) #define NLA_PAYLOAD(len) (len - NLA_HDRLEN) -#define err(code, fmt, arg...) do { printf(fmt, ##arg); exit(code); } while (0) -int done = 0; -int rcvbufsz=0; - - char name[100]; -int dbg=0, print_delays=0; +#define err(code, fmt, arg...) \ + do { \ + fprintf(stderr, fmt, ##arg); \ + exit(code); \ + } while (0) + +int done; +int rcvbufsz; +char name[100]; +int dbg; +int print_delays; +int print_io_accounting; __u64 stime, utime; + #define PRINTF(fmt, arg...) { \ if (dbg) { \ printf(fmt, ##arg); \ @@ -78,8 +87,9 @@ static int create_nl_socket(int protocol) if (rcvbufsz) if (setsockopt(fd, SOL_SOCKET, SO_RCVBUF, &rcvbufsz, sizeof(rcvbufsz)) < 0) { - printf("Unable to set socket rcv buf size to %d\n", - rcvbufsz); + fprintf(stderr, "Unable to set socket rcv buf size " + "to %d\n", + rcvbufsz); return -1; } @@ -186,6 +196,15 @@ void print_delayacct(struct taskstats *t) "count", "delay total", t->swapin_count, t->swapin_delay_total); } +void print_ioacct(struct taskstats *t) +{ + printf("%s: read=%llu, write=%llu, cancelled_write=%llu\n", + t->ac_comm, + (unsigned long long)t->read_bytes, + (unsigned long long)t->write_bytes, + (unsigned long long)t->cancelled_write_bytes); +} + int main(int argc, char *argv[]) { int c, rc, rep_len, aggr_len, len2, cmd_type; @@ -208,7 +227,7 @@ int main(int argc, char *argv[]) struct msgtemplate msg; while (1) { - c = getopt(argc, argv, "dw:r:m:t:p:v:l"); + c = getopt(argc, argv, "diw:r:m:t:p:v:l"); if (c < 0) break; @@ -217,6 +236,10 @@ int main(int argc, char *argv[]) printf("print delayacct stats ON\n"); print_delays = 1; break; + case 'i': + printf("printing IO accounting\n"); + print_io_accounting = 1; + break; case 'w': strncpy(logfile, optarg, MAX_FILENAME); printf("write to file %s\n", logfile); @@ -238,14 +261,12 @@ int main(int argc, char *argv[]) if (!tid) err(1, "Invalid tgid\n"); cmd_type = TASKSTATS_CMD_ATTR_TGID; - print_delays = 1; break; case 'p': tid = atoi(optarg); if (!tid) err(1, "Invalid pid\n"); cmd_type = TASKSTATS_CMD_ATTR_PID; - print_delays = 1; break; case 'v': printf("debug on\n"); @@ -277,7 +298,7 @@ int main(int argc, char *argv[]) mypid = getpid(); id = get_family_id(nl_sd); if (!id) { - printf("Error getting family id, errno %d", errno); + fprintf(stderr, "Error getting family id, errno %d\n", errno); goto err; } PRINTF("family id %d\n", id); @@ -288,7 +309,7 @@ int main(int argc, char *argv[]) &cpumask, strlen(cpumask) + 1); PRINTF("Sent register cpumask, retval %d\n", rc); if (rc < 0) { - printf("error sending register cpumask\n"); + fprintf(stderr, "error sending register cpumask\n"); goto err; } } @@ -298,7 +319,7 @@ int main(int argc, char *argv[]) cmd_type, &tid, sizeof(__u32)); PRINTF("Sent pid/tgid, retval %d\n", rc); if (rc < 0) { - printf("error sending tid/tgid cmd\n"); + fprintf(stderr, "error sending tid/tgid cmd\n"); goto done; } } @@ -310,13 +331,15 @@ int main(int argc, char *argv[]) PRINTF("received %d bytes\n", rep_len); if (rep_len < 0) { - printf("nonfatal reply error: errno %d\n", errno); + fprintf(stderr, "nonfatal reply error: errno %d\n", + errno); continue; } if (msg.n.nlmsg_type == NLMSG_ERROR || !NLMSG_OK((&msg.n), rep_len)) { struct nlmsgerr *err = NLMSG_DATA(&msg); - printf("fatal reply error, errno %d\n", err->error); + fprintf(stderr, "fatal reply error, errno %d\n", + err->error); goto done; } @@ -356,6 +379,8 @@ int main(int argc, char *argv[]) count++; if (print_delays) print_delayacct((struct taskstats *) NLA_DATA(na)); + if (print_io_accounting) + print_ioacct((struct taskstats *) NLA_DATA(na)); if (fd) { if (write(fd, NLA_DATA(na), na->nla_len) < 0) { err(1,"write error\n"); @@ -365,7 +390,9 @@ int main(int argc, char *argv[]) goto done; break; default: - printf("Unknown nested nla_type %d\n", na->nla_type); + fprintf(stderr, "Unknown nested" + " nla_type %d\n", + na->nla_type); break; } len2 += NLA_ALIGN(na->nla_len); @@ -374,7 +401,8 @@ int main(int argc, char *argv[]) break; default: - printf("Unknown nla_type %d\n", na->nla_type); + fprintf(stderr, "Unknown nla_type %d\n", + na->nla_type); break; } na = (struct nlattr *) (GENLMSG_DATA(&msg) + len); diff --git a/Documentation/arm/Samsung-S3C24XX/Overview.txt b/Documentation/arm/Samsung-S3C24XX/Overview.txt index dda7ecdde87..28d014714ab 100644 --- a/Documentation/arm/Samsung-S3C24XX/Overview.txt +++ b/Documentation/arm/Samsung-S3C24XX/Overview.txt @@ -76,6 +76,15 @@ Machines A S3C2410 based PDA from Acer. There is a Wiki page at http://handhelds.org/moin/moin.cgi/AcerN30Documentation . + AML M5900 + + American Microsystems' M5900 + + Nex Vision Nexcoder + Nex Vision Otom + + Two machines by Nex Vision + Adding New Machines ------------------- @@ -115,6 +124,10 @@ RTC Support for the onboard RTC unit, including alarm function. + This has recently been upgraded to use the new RTC core, + and the module has been renamed to rtc-s3c to fit in with + the new rtc naming scheme. + Watchdog -------- @@ -128,7 +141,7 @@ NAND 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/ + code can be found from http://www.linux-mtd.infradead.org/ Serial @@ -168,6 +181,21 @@ Suspend to RAM See Suspend.txt for more information. +SPI +--- + + SPI drivers are available for both the in-built hardware + (although there is no DMA support yet) and a generic + GPIO based solution. + + +LEDs +---- + + There is support for GPIO based LEDs via a platform driver + in the LED subsystem. + + Platform Data ------------- diff --git a/Documentation/block/biodoc.txt b/Documentation/block/biodoc.txt index c6c9a9c10d7..3adaace328a 100644 --- a/Documentation/block/biodoc.txt +++ b/Documentation/block/biodoc.txt @@ -946,6 +946,13 @@ elevator_merged_fn called when a request in the scheduler has been scheduler for example, to reposition the request if its sorting order has changed. +elevator_allow_merge_fn called whenever the block layer determines + that a bio can be merged into an existing + request safely. The io scheduler may still + want to stop a merge at this point if it + results in some sort of conflict internally, + this hook allows it to do that. + elevator_dispatch_fn fills the dispatch queue with ready requests. I/O schedulers are free to postpone requests by not filling the dispatch queue unless @force diff --git a/Documentation/cachetlb.txt b/Documentation/cachetlb.txt index 53245c429f7..debf6813934 100644 --- a/Documentation/cachetlb.txt +++ b/Documentation/cachetlb.txt @@ -179,10 +179,21 @@ Here are the routines, one by one: lines associated with 'mm'. This interface is used to handle whole address space - page table operations such as what happens during - fork, exit, and exec. + page table operations such as what happens during exit and exec. + +2) void flush_cache_dup_mm(struct mm_struct *mm) + + This interface flushes an entire user address space from + the caches. That is, after running, there will be no cache + lines associated with 'mm'. + + This interface is used to handle whole address space + page table operations such as what happens during fork. + + This option is separate from flush_cache_mm to allow some + optimizations for VIPT caches. -2) void flush_cache_range(struct vm_area_struct *vma, +3) void flush_cache_range(struct vm_area_struct *vma, unsigned long start, unsigned long end) Here we are flushing a specific range of (user) virtual @@ -199,7 +210,7 @@ Here are the routines, one by one: call flush_cache_page (see below) for each entry which may be modified. -3) void flush_cache_page(struct vm_area_struct *vma, unsigned long addr, unsigned long pfn) +4) void flush_cache_page(struct vm_area_struct *vma, unsigned long addr, unsigned long pfn) This time we need to remove a PAGE_SIZE sized range from the cache. The 'vma' is the backing structure used by @@ -220,7 +231,7 @@ Here are the routines, one by one: This is used primarily during fault processing. -4) void flush_cache_kmaps(void) +5) void flush_cache_kmaps(void) This routine need only be implemented if the platform utilizes highmem. It will be called right before all of the kmaps @@ -232,7 +243,7 @@ Here are the routines, one by one: This routing should be implemented in asm/highmem.h -5) void flush_cache_vmap(unsigned long start, unsigned long end) +6) void flush_cache_vmap(unsigned long start, unsigned long end) void flush_cache_vunmap(unsigned long start, unsigned long end) Here in these two interfaces we are flushing a specific range @@ -362,14 +373,15 @@ maps this page at its virtual address. likely that you will need to flush the instruction cache for copy_to_user_page(). - void flush_anon_page(struct page *page, unsigned long vmaddr) + void flush_anon_page(struct vm_area_struct *vma, struct page *page, + unsigned long vmaddr) When the kernel needs to access the contents of an anonymous page, it calls this function (currently only get_user_pages()). Note: flush_dcache_page() deliberately doesn't work for an anonymous page. The default implementation is a nop (and should remain so for all coherent architectures). For incoherent architectures, it should flush - the cache of the page at vmaddr in the current user process. + the cache of the page at vmaddr. void flush_kernel_dcache_page(struct page *page) When the kernel needs to modify a user page is has obtained diff --git a/Documentation/cdrom/packet-writing.txt b/Documentation/cdrom/packet-writing.txt index 3d44c561fe6..7715d2247c4 100644 --- a/Documentation/cdrom/packet-writing.txt +++ b/Documentation/cdrom/packet-writing.txt @@ -90,6 +90,41 @@ Notes to create an ext2 filesystem on the disc. +Using the pktcdvd sysfs interface +--------------------------------- + +Since Linux 2.6.19, the pktcdvd module has a sysfs interface +and can be controlled by it. For example the "pktcdvd" tool uses +this interface. (see http://people.freenet.de/BalaGi#pktcdvd ) + +"pktcdvd" works similar to "pktsetup", e.g.: + + # pktcdvd -a dev_name /dev/hdc + # mkudffs /dev/pktcdvd/dev_name + # mount -t udf -o rw,noatime /dev/pktcdvd/dev_name /dvdram + # cp files /dvdram + # umount /dvdram + # pktcdvd -r dev_name + + +For a description of the sysfs interface look into the file: + + Documentation/ABI/testing/sysfs-block-pktcdvd + + +Using the pktcdvd debugfs interface +----------------------------------- + +To read pktcdvd device infos in human readable form, do: + + # cat /debug/pktcdvd/pktcdvd[0-7]/info + +For a description of the debugfs interface look into the file: + + Documentation/ABI/testing/debugfs-pktcdvd + + + Links ----- diff --git a/Documentation/cpu-freq/core.txt b/Documentation/cpu-freq/core.txt index 29b3f9ffc66..ce0666e5103 100644 --- a/Documentation/cpu-freq/core.txt +++ b/Documentation/cpu-freq/core.txt @@ -24,7 +24,7 @@ Contents: 1. General Information ======================= -The CPUFreq core code is located in linux/kernel/cpufreq.c. This +The CPUFreq core code is located in drivers/cpufreq/cpufreq.c. This cpufreq code offers a standardized interface for the CPUFreq architecture drivers (those pieces of code that do actual frequency transitions), as well as to "notifiers". These are device diff --git a/Documentation/crypto/api-intro.txt b/Documentation/crypto/api-intro.txt index 5a03a2801d6..e41a79aa71c 100644 --- a/Documentation/crypto/api-intro.txt +++ b/Documentation/crypto/api-intro.txt @@ -193,6 +193,7 @@ Original developers of the crypto algorithms: Kartikey Mahendra Bhatt (CAST6) Jon Oberheide (ARC4) Jouni Malinen (Michael MIC) + NTT(Nippon Telegraph and Telephone Corporation) (Camellia) SHA1 algorithm contributors: Jean-Francois Dive @@ -246,6 +247,9 @@ Tiger algorithm contributors: VIA PadLock contributors: Michal Ludvig +Camellia algorithm contributors: + NTT(Nippon Telegraph and Telephone Corporation) (Camellia) + Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com> Please send any credits updates or corrections to: diff --git a/Documentation/driver-model/devres.txt b/Documentation/driver-model/devres.txt new file mode 100644 index 00000000000..5163b85308f --- /dev/null +++ b/Documentation/driver-model/devres.txt @@ -0,0 +1,268 @@ +Devres - Managed Device Resource +================================ + +Tejun Heo <teheo@suse.de> + +First draft 10 January 2007 + + +1. Intro : Huh? Devres? +2. Devres : Devres in a nutshell +3. Devres Group : Group devres'es and release them together +4. Details : Life time rules, calling context, ... +5. Overhead : How much do we have to pay for this? +6. List of managed interfaces : Currently implemented managed interfaces + + + 1. Intro + -------- + +devres came up while trying to convert libata to use iomap. Each +iomapped address should be kept and unmapped on driver detach. For +example, a plain SFF ATA controller (that is, good old PCI IDE) in +native mode makes use of 5 PCI BARs and all of them should be +maintained. + +As with many other device drivers, libata low level drivers have +sufficient bugs in ->remove and ->probe failure path. Well, yes, +that's probably because libata low level driver developers are lazy +bunch, but aren't all low level driver developers? After spending a +day fiddling with braindamaged hardware with no document or +braindamaged document, if it's finally working, well, it's working. + +For one reason or another, low level drivers don't receive as much +attention or testing as core code, and bugs on driver detach or +initilaization failure doesn't happen often enough to be noticeable. +Init failure path is worse because it's much less travelled while +needs to handle multiple entry points. + +So, many low level drivers end up leaking resources on driver detach +and having half broken failure path implementation in ->probe() which +would leak resources or even cause oops when failure occurs. iomap +adds more to this mix. So do msi and msix. + + + 2. Devres + --------- + +devres is basically linked list of arbitrarily sized memory areas +associated with a struct device. Each devres entry is associated with +a release function. A devres can be released in several ways. No +matter what, all devres entries are released on driver detach. On +release, the associated release function is invoked and then the +devres entry is freed. + +Managed interface is created for resources commonly used by device +drivers using devres. For example, coherent DMA memory is acquired +using dma_alloc_coherent(). The managed version is called +dmam_alloc_coherent(). It is identical to dma_alloc_coherent() except +for the DMA memory allocated using it is managed and will be +automatically released on driver detach. Implementation looks like +the following. + + struct dma_devres { + size_t size; + void *vaddr; + dma_addr_t dma_handle; + }; + + static void dmam_coherent_release(struct device *dev, void *res) + { + struct dma_devres *this = res; + + dma_free_coherent(dev, this->size, this->vaddr, this->dma_handle); + } + + dmam_alloc_coherent(dev, size, dma_handle, gfp) + { + struct dma_devres *dr; + void *vaddr; + + dr = devres_alloc(dmam_coherent_release, sizeof(*dr), gfp); + ... + + /* alloc DMA memory as usual */ + vaddr = dma_alloc_coherent(...); + ... + + /* record size, vaddr, dma_handle in dr */ + dr->vaddr = vaddr; + ... + + devres_add(dev, dr); + + return vaddr; + } + +If a driver uses dmam_alloc_coherent(), the area is guaranteed to be +freed whether initialization fails half-way or the device gets +detached. If most resources are acquired using managed interface, a +driver can have much simpler init and exit code. Init path basically +looks like the following. + + my_init_one() + { + struct mydev *d; + + d = devm_kzalloc(dev, sizeof(*d), GFP_KERNEL); + if (!d) + return -ENOMEM; + + d->ring = dmam_alloc_coherent(...); + if (!d->ring) + return -ENOMEM; + + if (check something) + return -EINVAL; + ... + + return register_to_upper_layer(d); + } + +And exit path, + + my_remove_one() + { + unregister_from_upper_layer(d); + shutdown_my_hardware(); + } + +As shown above, low level drivers can be simplified a lot by using +devres. Complexity is shifted from less maintained low level drivers +to better maintained higher layer. Also, as init failure path is +shared with exit path, both can get more testing. + + + 3. Devres group + --------------- + +Devres entries can be grouped using devres group. When a group is +released, all contained normal devres entries and properly nested +groups are released. One usage is to rollback series of acquired +resources on failure. For example, + + if (!devres_open_group(dev, NULL, GFP_KERNEL)) + return -ENOMEM; + + acquire A; + if (failed) + goto err; + + acquire B; + if (failed) + goto err; + ... + + devres_remove_group(dev, NULL); + return 0; + + err: + devres_release_group(dev, NULL); + return err_code; + +As resource acquision failure usually means probe failure, constructs +like above are usually useful in midlayer driver (e.g. libata core +layer) where interface function shouldn't have side effect on failure. +For LLDs, just returning error code suffices in most cases. + +Each group is identified by void *id. It can either be explicitly +specified by @id argument to devres_open_group() or automatically +created by passing NULL as @id as in the above example. In both +cases, devres_open_group() returns the group's id. The returned id +can be passed to other devres functions to select the target group. +If NULL is given to those functions, the latest open group is +selected. + +For example, you can do something like the following. + + int my_midlayer_create_something() + { + if (!devres_open_group(dev, my_midlayer_create_something, GFP_KERNEL)) + return -ENOMEM; + + ... + + devres_close_group(dev, my_midlayer_something); + return 0; + } + + void my_midlayer_destroy_something() + { + devres_release_group(dev, my_midlayer_create_soemthing); + } + + + 4. Details + ---------- + +Lifetime of a devres entry begins on devres allocation and finishes +when it is released or destroyed (removed and freed) - no reference +counting. + +devres core guarantees atomicity to all basic devres operations and +has support for single-instance devres types (atomic +lookup-and-add-if-not-found). Other than that, synchronizing +concurrent accesses to allocated devres data is caller's +responsibility. This is usually non-issue because bus ops and +resource allocations already do the job. + +For an example of single-instance devres type, read pcim_iomap_table() +in lib/iomap.c. + +All devres interface functions can be called without context if the +right gfp mask is given. + + + 5. Overhead + ----------- + +Each devres bookkeeping info is allocated together with requested data +area. With debug option turned off, bookkeeping info occupies 16 +bytes on 32bit machines and 24 bytes on 64bit (three pointers rounded +up to ull alignment). If singly linked list is used, it can be +reduced to two pointers (8 bytes on 32bit, 16 bytes on 64bit). + +Each devres group occupies 8 pointers. It can be reduced to 6 if +singly linked list is used. + +Memory space overhead on ahci controller with two ports is between 300 +and 400 bytes on 32bit machine after naive conversion (we can +certainly invest a bit more effort into libata core layer). + + + 6. List of managed interfaces + ----------------------------- + +IO region + devm_request_region() + devm_request_mem_region() + devm_release_region() + devm_release_mem_region() + +IRQ + devm_request_irq() + devm_free_irq() + +DMA + dmam_alloc_coherent() + dmam_free_coherent() + dmam_alloc_noncoherent() + dmam_free_noncoherent() + dmam_declare_coherent_memory() + dmam_pool_create() + dmam_pool_destroy() + +PCI + pcim_enable_device() : after success, all PCI ops become managed + pcim_pin_device() : keep PCI device enabled after release + +IOMAP + devm_ioport_map() + devm_ioport_unmap() + devm_ioremap() + devm_ioremap_nocache() + devm_iounmap() + pcim_iomap() + pcim_iounmap() + pcim_iomap_table() : array of mapped addresses indexed by BAR + pcim_iomap_regions() : do request_region() and iomap() on multiple BARs diff --git a/Documentation/dvb/cards.txt b/Documentation/dvb/cards.txt index ca58e339d85..cc09187a5db 100644 --- a/Documentation/dvb/cards.txt +++ b/Documentation/dvb/cards.txt @@ -22,10 +22,10 @@ o Frontends drivers: - ves1x93 : Alps BSRV2 (ves1893 demodulator) and dbox2 (ves1993) - cx24110 : Conexant HM1221/HM1811 (cx24110 or cx24106 demod, cx24108 PLL) - grundig_29504-491 : Grundig 29504-491 (Philips TDA8083 demodulator), tsa5522 PLL - - mt312 : Zarlink mt312 or Mitel vp310 demodulator, sl1935 or tsa5059 PLL + - mt312 : Zarlink mt312 or Mitel vp310 demodulator, sl1935 or tsa5059 PLLi, Technisat Sky2Pc with bios Rev. 2.3 - stv0299 : Alps BSRU6 (tsa5059 PLL), LG TDQB-S00x (tsa5059 PLL), LG TDQF-S001F (sl1935 PLL), Philips SU1278 (tua6100 PLL), - Philips SU1278SH (tsa5059 PLL), Samsung TBMU24112IMB + Philips SU1278SH (tsa5059 PLL), Samsung TBMU24112IMB, Technisat Sky2Pc with bios Rev. 2.6 DVB-C: - ves1820 : various (ves1820 demodulator, sp5659c or spXXXX PLL) - at76c651 : Atmel AT76c651(B) with DAT7021 PLL diff --git a/Documentation/fault-injection/failcmd.sh b/Documentation/fault-injection/failcmd.sh new file mode 100644 index 00000000000..63177aba810 --- /dev/null +++ b/Documentation/fault-injection/failcmd.sh @@ -0,0 +1,4 @@ +#!/bin/bash + +echo 1 > /proc/self/make-it-fail +exec $* diff --git a/Documentation/fault-injection/failmodule.sh b/Documentation/fault-injection/failmodule.sh new file mode 100644 index 00000000000..474a8b971f9 --- /dev/null +++ b/Documentation/fault-injection/failmodule.sh @@ -0,0 +1,31 @@ +#!/bin/bash +# +# Usage: failmodule <failname> <modulename> [stacktrace-depth] +# +# <failname>: "failslab", "fail_alloc_page", or "fail_make_request" +# +# <modulename>: module name that you want to inject faults. +# +# [stacktrace-depth]: the maximum number of stacktrace walking allowed +# + +STACKTRACE_DEPTH=5 +if [ $# -gt 2 ]; then + STACKTRACE_DEPTH=$3 +fi + +if [ ! -d /debug/$1 ]; then + echo "Fault-injection $1 does not exist" >&2 + exit 1 +fi +if [ ! -d /sys/module/$2 ]; then + echo "Module $2 does not exist" >&2 + exit 1 +fi + +# Disable any fault injection +echo 0 > /debug/$1/stacktrace-depth + +echo `cat /sys/module/$2/sections/.text` > /debug/$1/require-start +echo `cat /sys/module/$2/sections/.exit.text` > /debug/$1/require-end +echo $STACKTRACE_DEPTH > /debug/$1/stacktrace-depth diff --git a/Documentation/fault-injection/fault-injection.txt b/Documentation/fault-injection/fault-injection.txt new file mode 100644 index 00000000000..b7ca560b934 --- /dev/null +++ b/Documentation/fault-injection/fault-injection.txt @@ -0,0 +1,225 @@ +Fault injection capabilities infrastructure +=========================================== + +See also drivers/md/faulty.c and "every_nth" module option for scsi_debug. + + +Available fault injection capabilities +-------------------------------------- + +o failslab + + injects slab allocation failures. (kmalloc(), kmem_cache_alloc(), ...) + +o fail_page_alloc + + injects page allocation failures. (alloc_pages(), get_free_pages(), ...) + +o fail_make_request + + injects disk IO errors on devices permitted by setting + /sys/block/<device>/make-it-fail or + /sys/block/<device>/<partition>/make-it-fail. (generic_make_request()) + +Configure fault-injection capabilities behavior +----------------------------------------------- + +o debugfs entries + +fault-inject-debugfs kernel module provides some debugfs entries for runtime +configuration of fault-injection capabilities. + +- /debug/fail*/probability: + + likelihood of failure injection, in percent. + Format: <percent> + + Note that one-failure-per-hundred is a very high error rate + for some testcases. Consider setting probability=100 and configure + /debug/fail*/interval for such testcases. + +- /debug/fail*/interval: + + specifies the interval between failures, for calls to + should_fail() that pass all the other tests. + + Note that if you enable this, by setting interval>1, you will + probably want to set probability=100. + +- /debug/fail*/times: + + specifies how many times failures may happen at most. + A value of -1 means "no limit". + +- /debug/fail*/space: + + specifies an initial resource "budget", decremented by "size" + on each call to should_fail(,size). Failure injection is + suppressed until "space" reaches zero. + +- /debug/fail*/verbose + + Format: { 0 | 1 | 2 } + specifies the verbosity of the messages when failure is + injected. '0' means no messages; '1' will print only a single + log line per failure; '2' will print a call trace too -- useful + to debug the problems revealed by fault injection. + +- /debug/fail*/task-filter: + + Format: { 'Y' | 'N' } + A value of 'N' disables filtering by process (default). + Any positive value limits failures to only processes indicated by + /proc/<pid>/make-it-fail==1. + +- /debug/fail*/require-start: +- /debug/fail*/require-end: +- /debug/fail*/reject-start: +- /debug/fail*/reject-end: + + specifies the range of virtual addresses tested during + stacktrace walking. Failure is injected only if some caller + in the walked stacktrace lies within the required range, and + none lies within the rejected range. + Default required range is [0,ULONG_MAX) (whole of virtual address space). + Default rejected range is [0,0). + +- /debug/fail*/stacktrace-depth: + + specifies the maximum stacktrace depth walked during search + for a caller within [require-start,require-end) OR + [reject-start,reject-end). + +- /debug/fail_page_alloc/ignore-gfp-highmem: + + Format: { 'Y' | 'N' } + default is 'N', setting it to 'Y' won't inject failures into + highmem/user allocations. + +- /debug/failslab/ignore-gfp-wait: +- /debug/fail_page_alloc/ignore-gfp-wait: + + Format: { 'Y' | 'N' } + default is 'N', setting it to 'Y' will inject failures + only into non-sleep allocations (GFP_ATOMIC allocations). + +o Boot option + +In order to inject faults while debugfs is not available (early boot time), +use the boot option: + + failslab= + fail_page_alloc= + fail_make_request=<interval>,<probability>,<space>,<times> + +How to add new fault injection capability +----------------------------------------- + +o #include <linux/fault-inject.h> + +o define the fault attributes + + DECLARE_FAULT_INJECTION(name); + + Please see the definition of struct fault_attr in fault-inject.h + for details. + +o provide a way to configure fault attributes + +- boot option + + If you need to enable the fault injection capability from boot time, you can + provide boot option to configure it. There is a helper function for it: + + setup_fault_attr(attr, str); + +- debugfs entries + + failslab, fail_page_alloc, and fail_make_request use this way. + Helper functions: + + init_fault_attr_entries(entries, attr, name); + void cleanup_fault_attr_entries(entries); + +- module parameters + + If the scope of the fault injection capability is limited to a + single kernel module, it is better to provide module parameters to + configure the fault attributes. + +o add a hook to insert failures + + Upon should_fail() returning true, client code should inject a failure. + + should_fail(attr, size); + +Application Examples +-------------------- + +o inject slab allocation failures into module init/cleanup code + +------------------------------------------------------------------------------ +#!/bin/bash + +FAILCMD=Documentation/fault-injection/failcmd.sh +BLACKLIST="root_plug evbug" + +FAILNAME=failslab +echo Y > /debug/$FAILNAME/task-filter +echo 10 > /debug/$FAILNAME/probability +echo 100 > /debug/$FAILNAME/interval +echo -1 > /debug/$FAILNAME/times +echo 2 > /debug/$FAILNAME/verbose +echo 1 > /debug/$FAILNAME/ignore-gfp-wait + +blacklist() +{ + echo $BLACKLIST | grep $1 > /dev/null 2>&1 +} + +oops() +{ + dmesg | grep BUG > /dev/null 2>&1 +} + +find /lib/modules/`uname -r` -name '*.ko' -exec basename {} .ko \; | + while read i + do + oops && exit 1 + + if ! blacklist $i + then + echo inserting $i... + bash $FAILCMD modprobe $i + fi + done + +lsmod | awk '{ if ($3 == 0) { print $1 } }' | + while read i + do + oops && exit 1 + + if ! blacklist $i + then + echo removing $i... + bash $FAILCMD modprobe -r $i + fi + done + +------------------------------------------------------------------------------ + +o inject slab allocation failures only for a specific module + +------------------------------------------------------------------------------ +#!/bin/bash + +FAILMOD=Documentation/fault-injection/failmodule.sh + +echo injecting errors into the module $1... + +modprobe $1 +bash $FAILMOD failslab $1 10 +echo 25 > /debug/failslab/probability + +------------------------------------------------------------------------------ + diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index 46f2a559b27..fa844fd7bde 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -50,22 +50,6 @@ Who: Dan Dennedy <dan@dennedy.org>, Stefan Richter <stefanr@s5r6.in-berlin.de> --------------------------- -What: ieee1394 core's unused exports (CONFIG_IEEE1394_EXPORT_FULL_API) -When: January 2007 -Why: There are no projects known to use these exported symbols, except - dfg1394 (uses one symbol whose functionality is core-internal now). -Who: Stefan Richter <stefanr@s5r6.in-berlin.de> - ---------------------------- - -What: ieee1394's *_oui sysfs attributes (CONFIG_IEEE1394_OUI_DB) -When: January 2007 -Files: drivers/ieee1394/: oui.db, oui2c.sh -Why: big size, little value -Who: Stefan Richter <stefanr@s5r6.in-berlin.de> - ---------------------------- - What: Video4Linux API 1 ioctls and video_decoder.h from Video devices. When: December 2006 Why: V4L1 AP1 was replaced by V4L2 API. during migration from 2.4 to 2.6 @@ -151,15 +135,6 @@ Who: Thomas Gleixner <tglx@linutronix.de> --------------------------- -What: I2C interface of the it87 driver -When: January 2007 -Why: The ISA interface is faster and should be always available. The I2C - probing is also known to cause trouble in at least one case (see - bug #5889.) -Who: Jean Delvare <khali@linux-fr.org> - ---------------------------- - 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. @@ -195,18 +170,6 @@ Who: Greg Kroah-Hartman <gregkh@suse.de> --------------------------- -What: find_trylock_page -When: January 2007 -Why: The interface no longer has any callers left in the kernel. It - is an odd interface (compared with other find_*_page functions), in - that it does not take a refcount to the page, only the page lock. - It should be replaced with find_get_page or find_lock_page if possible. - This feature removal can be reevaluated if users of the interface - cannot cleanly use something else. -Who: Nick Piggin <npiggin@suse.de> - ---------------------------- - What: Interrupt only SA_* flags When: Januar 2007 Why: The interrupt related SA_* flags are replaced by IRQF_* to move them @@ -216,33 +179,6 @@ Who: Thomas Gleixner <tglx@linutronix.de> --------------------------- -What: i2c-ite and i2c-algo-ite drivers -When: September 2006 -Why: These drivers never compiled since they were added to the kernel - tree 5 years ago. This feature removal can be reevaluated if - someone shows interest in the drivers, fixes them and takes over - maintenance. - http://marc.theaimsgroup.com/?l=linux-mips&m=115040510817448 -Who: Jean Delvare <khali@linux-fr.org> - ---------------------------- - -What: Bridge netfilter deferred IPv4/IPv6 output hook calling -When: January 2007 -Why: The deferred output hooks are a layering violation causing unusual - and broken behaviour on bridge devices. Examples of things they - break include QoS classifation using the MARK or CLASSIFY targets, - the IPsec policy match and connection tracking with VLANs on a - bridge. Their only use is to enable bridge output port filtering - within iptables with the physdev match, which can also be done by - combining iptables and ebtables using netfilter marks. Until it - will get removed the hook deferral is disabled by default and is - only enabled when needed. - -Who: Patrick McHardy <kaber@trash.net> - ---------------------------- - What: PHYSDEVPATH, PHYSDEVBUS, PHYSDEVDRIVER in the uevent environment When: October 2008 Why: The stacking of class devices makes these values misleading and @@ -262,6 +198,23 @@ Who: Jean Delvare <khali@linux-fr.org> --------------------------- +What: i2c_adapter.dev + i2c_adapter.list +When: July 2007 +Why: Superfluous, given i2c_adapter.class_dev: + * The "dev" was a stand-in for the physical device node that legacy + drivers would not have; but now it's almost always present. Any + remaining legacy drivers must upgrade (they now trigger warnings). + * The "list" duplicates class device children. + The delay in removing this is so upgraded lm_sensors and libsensors + can get deployed. (Removal causes minor changes in the sysfs layout, + notably the location of the adapter type name and parenting the i2c + client hardware directly from their controller.) +Who: Jean Delvare <khali@linux-fr.org>, + David Brownell <dbrownell@users.sourceforge.net> + +--------------------------- + What: IPv4 only connection tracking/NAT/helpers When: 2.6.22 Why: The new layer 3 independant connection tracking replaces the old @@ -270,3 +223,92 @@ Why: The new layer 3 independant connection tracking replaces the old Who: Patrick McHardy <kaber@trash.net> --------------------------- + +What: ACPI hooks (X86_SPEEDSTEP_CENTRINO_ACPI) in speedstep-centrino driver +When: December 2006 +Why: Speedstep-centrino driver with ACPI hooks and acpi-cpufreq driver are + functionally very much similar. They talk to ACPI in same way. Only + difference between them is the way they do frequency transitions. + One uses MSRs and the other one uses IO ports. Functionaliy of + speedstep_centrino with ACPI hooks is now merged into acpi-cpufreq. + That means one common driver will support all Intel Enhanced Speedstep + capable CPUs. That means less confusion over name of + speedstep-centrino driver (with that driver supposed to be used on + non-centrino platforms). That means less duplication of code and + less maintenance effort and no possibility of these two drivers + going out of sync. + Current users of speedstep_centrino with ACPI hooks are requested to + switch over to acpi-cpufreq driver. speedstep-centrino will continue + to work using older non-ACPI static table based scheme even after this + date. + +Who: Venkatesh Pallipadi <venkatesh.pallipadi@intel.com> + +--------------------------- + +<<<<<<< test:Documentation/feature-removal-schedule.txt +What: ACPI hotkey driver (CONFIG_ACPI_HOTKEY) +When: 2.6.21 +Why: hotkey.c was an attempt to consolidate multiple drivers that use + ACPI to implement hotkeys. However, hotkeys are not documented + in the ACPI specification, so the drivers used undocumented + vendor-specific hooks and turned out to be more different than + the same. + + Further, the keys and the features supplied by each platform + are different, so there will always be a need for + platform-specific drivers. + + So the new plan is to delete hotkey.c and instead, work on the + platform specific drivers to try to make them look the same + to the user when they supply the same features. + + hotkey.c has always depended on CONFIG_EXPERIMENTAL + +Who: Len Brown <len.brown@intel.com> + +--------------------------- + +What: /sys/firmware/acpi/namespace +When: 2.6.21 +Why: The ACPI namespace is effectively the symbol list for + the BIOS. The device names are completely arbitrary + and have no place being exposed to user-space. + + For those interested in the BIOS ACPI namespace, + the BIOS can be extracted and disassembled with acpidump + and iasl as documented in the pmtools package here: + http://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/utils +Who: Len Brown <len.brown@intel.com> + +--------------------------- + +What: ACPI procfs interface +When: July 2007 +Why: After ACPI sysfs conversion, ACPI attributes will be duplicated + in sysfs and the ACPI procfs interface should be removed. +Who: Zhang Rui <rui.zhang@intel.com> + +--------------------------- + +What: /proc/acpi/button +When: August 2007 +Why: /proc/acpi/button has been replaced by events to the input layer + since 2.6.20. +Who: Len Brown <len.brown@intel.com> + +--------------------------- + +What: JFFS (version 1) +When: 2.6.21 +Why: Unmaintained for years, superceded by JFFS2 for years. +Who: Jeff Garzik <jeff@garzik.org> + +--------------------------- + +What: sk98lin network driver +When: July 2007 +Why: In kernel tree version of driver is unmaintained. Sk98lin driver + replaced by the skge driver. +Who: Stephen Hemminger <shemminger@osdl.org> + diff --git a/Documentation/filesystems/9p.txt b/Documentation/filesystems/9p.txt index 43b89c214d2..4d075a4558f 100644 --- a/Documentation/filesystems/9p.txt +++ b/Documentation/filesystems/9p.txt @@ -73,8 +73,22 @@ OPTIONS RESOURCES ========= -The Linux version of the 9p server is now maintained under the npfs project -on sourceforge (http://sourceforge.net/projects/npfs). +Our current recommendation is to use Inferno (http://www.vitanuova.com/inferno) +as the 9p server. You can start a 9p server under Inferno by issuing the +following command: + ; styxlisten -A tcp!*!564 export '#U*' + +The -A specifies an unauthenticated export. The 564 is the port # (you may +have to choose a higher port number if running as a normal user). The '#U*' +specifies exporting the root of the Linux name space. You may specify a +subset of the namespace by extending the path: '#U*'/tmp would just export +/tmp. For more information, see the Inferno manual pages covering styxlisten +and export. + +A Linux version of the 9p server is now maintained under the npfs project +on sourceforge (http://sourceforge.net/projects/npfs). There is also a +more stable single-threaded version of the server (named spfs) available from +the same CVS repository. There are user and developer mailing lists available through the v9fs project on sourceforge (http://sourceforge.net/projects/v9fs). @@ -96,5 +110,5 @@ STATUS The 2.6 kernel support is working on PPC and x86. -PLEASE USE THE SOURCEFORGE BUG-TRACKER TO REPORT PROBLEMS. +PLEASE USE THE KERNEL BUGZILLA TO REPORT PROBLEMS. (http://bugzilla.kernel.org) diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking index 790ef6fbe49..28bfea75bcf 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/Locking @@ -171,6 +171,7 @@ prototypes: int (*releasepage) (struct page *, int); int (*direct_IO)(int, struct kiocb *, const struct iovec *iov, loff_t offset, unsigned long nr_segs); + int (*launder_page) (struct page *); locking rules: All except set_page_dirty may block @@ -188,6 +189,7 @@ bmap: yes invalidatepage: no yes releasepage: no yes direct_IO: no +launder_page: no yes ->prepare_write(), ->commit_write(), ->sync_page() and ->readpage() may be called from the request handler (/dev/loop). @@ -281,6 +283,12 @@ buffers from the page in preparation for freeing it. It returns zero to indicate that the buffers are (or may be) freeable. If ->releasepage is zero, the kernel assumes that the fs has no private interest in the buffers. + ->launder_page() may be called prior to releasing a page if +it is still found to be dirty. It returns zero if the page was successfully +cleaned, or an error value if not. Note that in order to prevent the page +getting mapped back in and redirtied, it needs to be kept locked +across the entire operation. + Note: currently almost all instances of address_space methods are using BKL for internal serialization and that's one of the worst sources of contention. Normally they are calling library functions (in fs/buffer.c) diff --git a/Documentation/filesystems/bfs.txt b/Documentation/filesystems/bfs.txt index d2841e0bcf0..ea825e178e7 100644 --- a/Documentation/filesystems/bfs.txt +++ b/Documentation/filesystems/bfs.txt @@ -54,4 +54,4 @@ The first 4 bytes should be 0x1badface. If you have any patches, questions or suggestions regarding this BFS implementation please contact the author: -Tigran A. Aivazian <tigran@veritas.com> +Tigran Aivazian <tigran@aivazian.fsnet.co.uk> diff --git a/Documentation/filesystems/fuse.txt b/Documentation/filesystems/fuse.txt index 345392c4cae..397a41adb4c 100644 --- a/Documentation/filesystems/fuse.txt +++ b/Documentation/filesystems/fuse.txt @@ -94,8 +94,8 @@ Mount options filesystem is free to implement it's access policy or leave it to the underlying file access mechanism (e.g. in case of network filesystems). This option enables permission checking, restricting - access based on file mode. This is option is usually useful - together with the 'allow_other' mount option. + access based on file mode. It is usually useful together with the + 'allow_other' mount option. 'allow_other' diff --git a/Documentation/filesystems/ntfs.txt b/Documentation/filesystems/ntfs.txt index 13ba649bda7..81779068b09 100644 --- a/Documentation/filesystems/ntfs.txt +++ b/Documentation/filesystems/ntfs.txt @@ -457,6 +457,8 @@ ChangeLog Note, a technical ChangeLog aimed at kernel hackers is in fs/ntfs/ChangeLog. +2.1.28: + - Fix a deadlock. 2.1.27: - Implement page migration support so the kernel can move memory used by NTFS files and directories around for management purposes. diff --git a/Documentation/filesystems/ocfs2.txt b/Documentation/filesystems/ocfs2.txt index af6defd10cb..8ccf0c1b58e 100644 --- a/Documentation/filesystems/ocfs2.txt +++ b/Documentation/filesystems/ocfs2.txt @@ -54,3 +54,6 @@ errors=panic Panic and halt the machine if an error occurs. intr (*) Allow signals to interrupt cluster operations. nointr Do not allow signals to interrupt cluster operations. +atime_quantum=60(*) OCFS2 will not update atime unless this number + of seconds has passed since the last update. + Set to zero to always update atime. diff --git a/Documentation/hwmon/f71805f b/Documentation/hwmon/f71805f index 2ca69df669c..bfd0f154959 100644 --- a/Documentation/hwmon/f71805f +++ b/Documentation/hwmon/f71805f @@ -6,6 +6,10 @@ Supported chips: Prefix: 'f71805f' Addresses scanned: none, address read from Super I/O config space Datasheet: Provided by Fintek on request + * Fintek F71872F/FG + Prefix: 'f71872f' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Provided by Fintek on request Author: Jean Delvare <khali@linux-fr.org> @@ -13,8 +17,8 @@ Thanks to Denis Kieft from Barracuda Networks for the donation of a test system (custom Jetway K8M8MS motherboard, with CPU and RAM) and for providing initial documentation. -Thanks to Kris Chen from Fintek for answering technical questions and -providing additional documentation. +Thanks to Kris Chen and Aaron Huang from Fintek for answering technical +questions and providing additional documentation. Thanks to Chris Lin from Jetway for providing wiring schematics and answering technical questions. @@ -28,8 +32,11 @@ capabilities. It can monitor up to 9 voltages (counting its own power source), 3 fans and 3 temperature sensors. This chip also has fan controlling features, using either DC or PWM, in -three different modes (one manual, two automatic). The driver doesn't -support these features yet. +three different modes (one manual, two automatic). + +The Fintek F71872F/FG Super I/O chip is almost the same, with two +additional internal voltages monitored (VSB and battery). It also features +6 VID inputs. The VID inputs are not yet supported by this driver. The driver assumes that no more than one chip is present, which seems reasonable. @@ -42,7 +49,8 @@ Voltages are sampled by an 8-bit ADC with a LSB of 8 mV. The supported range is thus from 0 to 2.040 V. Voltage values outside of this range need external resistors. An exception is in0, which is used to monitor the chip's own power source (+3.3V), and is divided internally by a -factor 2. +factor 2. For the F71872F/FG, in9 (VSB) and in10 (battery) are also +divided internally by a factor 2. The two LSB of the voltage limit registers are not used (always 0), so you can only set the limits in steps of 32 mV (before scaling). @@ -61,9 +69,12 @@ in5 VIN5 +12V 200K 20K 11.00 1.05 V in6 VIN6 VCC1.5V 10K - 1.00 1.50 V in7 VIN7 VCORE 10K - 1.00 ~1.40 V (1) in8 VIN8 VSB5V 200K 47K 1.00 0.95 V +in10 VSB VSB3.3V int. int. 2.00 1.65 V (3) +in9 VBAT VBATTERY int. int. 2.00 1.50 V (3) (1) Depends on your hardware setup. (2) Obviously not correct, swapping R1 and R2 would make more sense. +(3) F71872F/FG only. These values can be used as hints at best, as motherboard manufacturers are free to use a completely different setup. As a matter of fact, the @@ -103,3 +114,38 @@ sensor. Each channel can be used for connecting either a thermal diode or a thermistor. The driver reports the currently selected mode, but doesn't allow changing it. In theory, the BIOS should have configured everything properly. + + +Fan Control +----------- + +Both PWM (pulse-width modulation) and DC fan speed control methods are +supported. The right one to use depends on external circuitry on the +motherboard, so the driver assumes that the BIOS set the method +properly. The driver will report the method, but won't let you change +it. + +When the PWM method is used, you can select the operating frequency, +from 187.5 kHz (default) to 31 Hz. The best frequency depends on the +fan model. As a rule of thumb, lower frequencies seem to give better +control, but may generate annoying high-pitch noise. Fintek recommends +not going below 1 kHz, as the fan tachometers get confused by lower +frequencies as well. + +When the DC method is used, Fintek recommends not going below 5 V, which +corresponds to a pwm value of 106 for the driver. The driver doesn't +enforce this limit though. + +Three different fan control modes are supported: + +* Manual mode + You ask for a specific PWM duty cycle or DC voltage. + +* Fan speed mode + You ask for a specific fan speed. This mode assumes that pwm1 + corresponds to fan1, pwm2 to fan2 and pwm3 to fan3. + +* Temperature mode + You define 3 temperature/fan speed trip points, and the fan speed is + adjusted depending on the measured temperature, using interpolation. + This mode is not yet supported by the driver. diff --git a/Documentation/hwmon/it87 b/Documentation/hwmon/it87 index e783fd62e30..74a80992d23 100644 --- a/Documentation/hwmon/it87 +++ b/Documentation/hwmon/it87 @@ -9,8 +9,7 @@ Supported chips: http://www.ite.com.tw/ * IT8712F Prefix: 'it8712' - Addresses scanned: I2C 0x2d - from Super I/O config space (8 I/O ports) + Addresses scanned: from Super I/O config space (8 I/O ports) Datasheet: Publicly available at the ITE website http://www.ite.com.tw/ * IT8716F @@ -53,6 +52,18 @@ Module Parameters misconfigured by BIOS - PWM values would be inverted. This option tries to fix this. Please contact your BIOS manufacturer and ask him for fix. + +Hardware Interfaces +------------------- + +All the chips suported by this driver are LPC Super-I/O chips, accessed +through the LPC bus (ISA-like I/O ports). The IT8712F additionally has an +SMBus interface to the hardware monitoring functions. This driver no +longer supports this interface though, as it is slower and less reliable +than the ISA access, and was only available on a small number of +motherboard models. + + Description ----------- diff --git a/Documentation/hwmon/k8temp b/Documentation/hwmon/k8temp index 30d123b8d92..0005c716614 100644 --- a/Documentation/hwmon/k8temp +++ b/Documentation/hwmon/k8temp @@ -8,7 +8,7 @@ Supported chips: Datasheet: http://www.amd.com/us-en/assets/content_type/white_papers_and_tech_docs/32559.pdf Author: Rudolf Marek -Contact: Rudolf Marek <r.marek@sh.cvut.cz> +Contact: Rudolf Marek <r.marek@assembler.cz> Description ----------- diff --git a/Documentation/hwmon/pc87427 b/Documentation/hwmon/pc87427 new file mode 100644 index 00000000000..9a0708f9f49 --- /dev/null +++ b/Documentation/hwmon/pc87427 @@ -0,0 +1,38 @@ +Kernel driver pc87427 +===================== + +Supported chips: + * National Semiconductor PC87427 + Prefix: 'pc87427' + Addresses scanned: none, address read from Super I/O config space + Datasheet: http://www.winbond.com.tw/E-WINBONDHTM/partner/apc_007.html + +Author: Jean Delvare <khali@linux-fr.org> + +Thanks to Amir Habibi at Candelis for setting up a test system, and to +Michael Kress for testing several iterations of this driver. + + +Description +----------- + +The National Semiconductor Super I/O chip includes complete hardware +monitoring capabilities. It can monitor up to 18 voltages, 8 fans and +6 temperature sensors. Only the fans are supported at the moment. + +This chip also has fan controlling features, which are not yet supported +by this driver either. + +The driver assumes that no more than one chip is present, which seems +reasonable. + + +Fan Monitoring +-------------- + +Fan rotation speeds are reported as 14-bit values from a gated clock +signal. Speeds down to 83 RPM can be measured. + +An alarm is triggered if the rotation speed drops below a programmable +limit. Another alarm is triggered if the speed is too low to to be measured +(including stalled or missing fan). diff --git a/Documentation/hwmon/sysfs-interface b/Documentation/hwmon/sysfs-interface index d1d390aaf62..efef3b962cd 100644 --- a/Documentation/hwmon/sysfs-interface +++ b/Documentation/hwmon/sysfs-interface @@ -208,12 +208,14 @@ temp[1-*]_auto_point[1-*]_temp_hyst **************** temp[1-*]_type Sensor type selection. - Integers 1 to 4 or thermistor Beta value (typically 3435) + Integers 1 to 6 or thermistor Beta value (typically 3435) RW 1: PII/Celeron Diode 2: 3904 transistor 3: thermal diode 4: thermistor (default/unknown Beta) + 5: AMD AMDSI + 6: Intel PECI Not all types are supported by all chips temp[1-*]_max Temperature max value. diff --git a/Documentation/hwmon/w83627ehf b/Documentation/hwmon/w83627ehf index caa610a297e..8a15a740875 100644 --- a/Documentation/hwmon/w83627ehf +++ b/Documentation/hwmon/w83627ehf @@ -10,7 +10,7 @@ Supported chips: Authors: Jean Delvare <khali@linux-fr.org> Yuan Mu (Winbond) - Rudolf Marek <r.marek@sh.cvut.cz> + Rudolf Marek <r.marek@assembler.cz> Description ----------- diff --git a/Documentation/hwmon/w83791d b/Documentation/hwmon/w83791d index 19b2ed739fa..db9881df88a 100644 --- a/Documentation/hwmon/w83791d +++ b/Documentation/hwmon/w83791d @@ -18,7 +18,7 @@ Credits: and Mark Studebaker <mdsxyz123@yahoo.com> w83792d.c: Chunhao Huang <DZShen@Winbond.com.tw>, - Rudolf Marek <r.marek@sh.cvut.cz> + Rudolf Marek <r.marek@assembler.cz> Additional contributors: Sven Anders <anders@anduras.de> diff --git a/Documentation/hwmon/w83793 b/Documentation/hwmon/w83793 new file mode 100644 index 00000000000..51171a83165 --- /dev/null +++ b/Documentation/hwmon/w83793 @@ -0,0 +1,106 @@ +Kernel driver w83793 +==================== + +Supported chips: + * Winbond W83793G/W83793R + Prefix: 'w83793' + Addresses scanned: I2C 0x2c - 0x2f + Datasheet: Still not published + +Authors: + Yuan Mu (Winbond Electronics) + Rudolf Marek <r.marek@assembler.cz> + + +Module parameters +----------------- + +* reset int + (default 0) + This parameter is not recommended, it will lose motherboard specific + settings. Use 'reset=1' to reset the chip when loading this module. + +* force_subclients=bus,caddr,saddr1,saddr2 + This is used to force the i2c addresses for subclients of + a certain chip. Typical usage is `force_subclients=0,0x2f,0x4a,0x4b' + to force the subclients of chip 0x2f on bus 0 to i2c addresses + 0x4a and 0x4b. + + +Description +----------- + +This driver implements support for Winbond W83793G/W83793R chips. + +* Exported features + This driver exports 10 voltage sensors, up to 12 fan tachometer inputs, + 6 remote temperatures, up to 8 sets of PWM fan controls, SmartFan + (automatic fan speed control) on all temperature/PWM combinations, 2 + sets of 6-pin CPU VID input. + +* Sensor resolutions + If your motherboard maker used the reference design, the resolution of + voltage0-2 is 2mV, resolution of voltage3/4/5 is 16mV, 8mV for voltage6, + 24mV for voltage7/8. Temp1-4 have a 0.25 degree Celsius resolution, + temp5-6 have a 1 degree Celsiis resolution. + +* Temperature sensor types + Temp1-4 have 2 possible types. It can be read from (and written to) + temp[1-4]_type. + - If the value is 3, it starts monitoring using a remote termal diode + (default). + - If the value is 6, it starts monitoring using the temperature sensor + in Intel CPU and get result by PECI. + Temp5-6 can be connected to external thermistors (value of + temp[5-6]_type is 4). + +* Alarm mechanism + For voltage sensors, an alarm triggers if the measured value is below + the low voltage limit or over the high voltage limit. + For temperature sensors, an alarm triggers if the measured value goes + above the high temperature limit, and wears off only after the measured + value drops below the hysteresis value. + For fan sensors, an alarm triggers if the measured value is below the + low speed limit. + +* SmartFan/PWM control + If you want to set a pwm fan to manual mode, you just need to make sure it + is not controlled by any temp channel, for example, you want to set fan1 + to manual mode, you need to check the value of temp[1-6]_fan_map, make + sure bit 0 is cleared in the 6 values. And then set the pwm1 value to + control the fan. + + Each temperature channel can control all the 8 PWM outputs (by setting the + corresponding bit in tempX_fan_map), you can set the temperature channel + mode using temp[1-6]_pwm_enable, 2 is Thermal Cruise mode and 3 + is the SmartFanII mode. Temperature channels will try to speed up or + slow down all controlled fans, this means one fan can receive different + PWM value requests from different temperature channels, but the chip + will always pick the safest (max) PWM value for each fan. + + In Thermal Cruise mode, the chip attempts to keep the temperature at a + predefined value, within a tolerance margin. So if tempX_input > + thermal_cruiseX + toleranceX, the chip will increase the PWM value, + if tempX_input < thermal_cruiseX - toleranceX, the chip will decrease + the PWM value. If the temperature is within the tolerance range, the PWM + value is left unchanged. + + SmartFanII works differently, you have to define up to 7 PWM, temperature + trip points, defining a PWM/temperature curve which the chip will follow. + While not fundamentally different from the Thermal Cruise mode, the + implementation is quite different, giving you a finer-grained control. + +* Chassis + If the case open alarm triggers, it will stay in this state unless cleared + by any write to the sysfs file "chassis". + +* VID and VRM + The VRM version is detected automatically, don't modify the it unless you + *do* know the cpu VRM version and it's not properly detected. + + +Notes +----- + + Only Fan1-5 and PWM1-3 are guaranteed to always exist, other fan inputs and + PWM outputs may or may not exist depending on the chip pin configuration. diff --git a/Documentation/i2c/busses/i2c-amd8111 b/Documentation/i2c/busses/i2c-amd8111 index db294ee7455..460dd6635fd 100644 --- a/Documentation/i2c/busses/i2c-amd8111 +++ b/Documentation/i2c/busses/i2c-amd8111 @@ -5,7 +5,7 @@ Supported adapters: Datasheets: AMD datasheet not yet available, but almost everything can be found - in publically available ACPI 2.0 specification, which the adapter + in the publicly available ACPI 2.0 specification, which the adapter follows. Author: Vojtech Pavlik <vojtech@suse.cz> diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801 index e46c2345824..3db69a086c4 100644 --- a/Documentation/i2c/busses/i2c-i801 +++ b/Documentation/i2c/busses/i2c-i801 @@ -9,7 +9,10 @@ Supported adapters: * Intel 82801EB/ER (ICH5) (HW PEC supported, 32 byte buffer not supported) * Intel 6300ESB * Intel 82801FB/FR/FW/FRW (ICH6) - * Intel ICH7 + * Intel 82801G (ICH7) + * Intel 631xESB/632xESB (ESB2) + * Intel 82801H (ICH8) + * Intel ICH9 Datasheets: Publicly available at the Intel website Authors: diff --git a/Documentation/i2c/busses/i2c-nforce2 b/Documentation/i2c/busses/i2c-nforce2 index cd49c428a3a..7f61fbc03f7 100644 --- a/Documentation/i2c/busses/i2c-nforce2 +++ b/Documentation/i2c/busses/i2c-nforce2 @@ -10,11 +10,11 @@ Supported adapters: * nForce4 MCP51 10de:0264 * nForce4 MCP55 10de:0368 -Datasheet: not publically available, but seems to be similar to the +Datasheet: not publicly available, but seems to be similar to the AMD-8111 SMBus 2.0 adapter. Authors: - Hans-Frieder Vogt <hfvogt@arcor.de>, + Hans-Frieder Vogt <hfvogt@gmx.net>, Thomas Leibold <thomas@plx.com>, Patrick Dreker <patrick@dreker.de> @@ -38,7 +38,7 @@ Notes ----- The SMBus adapter in the nForce2 chipset seems to be very similar to the -SMBus 2.0 adapter in the AMD-8111 southbridge. However, I could only get +SMBus 2.0 adapter in the AMD-8111 south bridge. However, I could only get the driver to work with direct I/O access, which is different to the EC interface of the AMD-8111. Tested on Asus A7N8X. The ACPI DSDT table of the Asus A7N8X lists two SMBuses, both of which are supported by this driver. diff --git a/Documentation/i386/boot.txt b/Documentation/i386/boot.txt index 9575de300a6..38fe1f03fb1 100644 --- a/Documentation/i386/boot.txt +++ b/Documentation/i386/boot.txt @@ -2,7 +2,7 @@ ---------------------------- H. Peter Anvin <hpa@zytor.com> - Last update 2006-11-17 + Last update 2007-01-26 On the i386 platform, the Linux kernel uses a rather complicated boot convention. This has evolved partially due to historical aspects, as @@ -186,6 +186,7 @@ filled out, however: 7 GRuB 8 U-BOOT 9 Xen + A Gujin Please contact <hpa@zytor.com> if you need a bootloader ID value assigned. diff --git a/Documentation/ibm-acpi.txt b/Documentation/ibm-acpi.txt index e50595bfd8e..0132d363feb 100644 --- a/Documentation/ibm-acpi.txt +++ b/Documentation/ibm-acpi.txt @@ -398,25 +398,67 @@ Temperature sensors -- /proc/acpi/ibm/thermal Most ThinkPads include six or more separate temperature sensors but only expose the CPU temperature through the standard ACPI methods. -This feature shows readings from up to eight different sensors. Some -readings may not be valid, e.g. may show large negative values. For -example, on the X40, a typical output may be: +This feature shows readings from up to eight different sensors on older +ThinkPads, and it has experimental support for up to sixteen different +sensors on newer ThinkPads. Readings from sensors that are not available +return -128. +No commands can be written to this file. + +EXPERIMENTAL: The 16-sensors feature is marked EXPERIMENTAL because the +implementation directly accesses hardware registers and may not work as +expected. USE WITH CAUTION! To use this feature, you need to supply the +experimental=1 parameter when loading the module. When EXPERIMENTAL +mode is enabled, reading the first 8 sensors on newer ThinkPads will +also use an new experimental thermal sensor access mode. + +For example, on the X40, a typical output may be: temperatures: 42 42 45 41 36 -128 33 -128 -Thomas Gruber took his R51 apart and traced all six active sensors in -his laptop (the location of sensors may vary on other models): +EXPERIMENTAL: On the T43/p, a typical output may be: +temperatures: 48 48 36 52 38 -128 31 -128 48 52 48 -128 -128 -128 -128 -128 + +The mapping of thermal sensors to physical locations varies depending on +system-board model (and thus, on ThinkPad model). + +http://thinkwiki.org/wiki/Thermal_Sensors is a public wiki page that +tries to track down these locations for various models. + +Most (newer?) models seem to follow this pattern: 1: CPU -2: Mini PCI Module -3: HDD +2: (depends on model) +3: (depends on model) 4: GPU -5: Battery -6: N/A -7: Battery -8: N/A +5: Main battery: main sensor +6: Bay battery: main sensor +7: Main battery: secondary sensor +8: Bay battery: secondary sensor +9-15: (depends on model) + +For the R51 (source: Thomas Gruber): +2: Mini-PCI +3: Internal HDD + +For the T43, T43/p (source: Shmidoax/Thinkwiki.org) +http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p +2: System board, left side (near PCMCIA slot), reported as HDAPS temp +3: PCMCIA slot +9: MCH (northbridge) to DRAM Bus +10: ICH (southbridge), under Mini-PCI card, under touchpad +11: Power regulator, underside of system board, below F2 key + +The A31 has a very atypical layout for the thermal sensors +(source: Milos Popovic, http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_A31) +1: CPU +2: Main Battery: main sensor +3: Power Converter +4: Bay Battery: main sensor +5: MCH (northbridge) +6: PCMCIA/ambient +7: Main Battery: secondary sensor +8: Bay Battery: secondary sensor -No commands can be written to this file. EXPERIMENTAL: Embedded controller register dump -- /proc/acpi/ibm/ecdump ------------------------------------------------------------------------ @@ -529,27 +571,57 @@ directly accesses hardware registers and may not work as expected. USE WITH CAUTION! To use this feature, you need to supply the experimental=1 parameter when loading the module. -This feature attempts to show the current fan speed. The speed is read -directly from the hardware registers of the embedded controller. This -is known to work on later R, T and X series ThinkPads but may show a -bogus value on other models. +This feature attempts to show the current fan speed, control mode and +other fan data that might be available. The speed is read directly +from the hardware registers of the embedded controller. This is known +to work on later R, T and X series ThinkPads but may show a bogus +value on other models. + +Most ThinkPad fans work in "levels". Level 0 stops the fan. The higher +the level, the higher the fan speed, although adjacent levels often map +to the same fan speed. 7 is the highest level, where the fan reaches +the maximum recommended speed. Level "auto" means the EC changes the +fan level according to some internal algorithm, usually based on +readings from the thermal sensors. Level "disengaged" means the EC +disables the speed-locked closed-loop fan control, and drives the fan as +fast as it can go, which might exceed hardware limits, so use this level +with caution. + +The fan usually ramps up or down slowly from one speed to another, +and it is normal for the EC to take several seconds to react to fan +commands. The fan may be enabled or disabled with the following commands: echo enable >/proc/acpi/ibm/fan echo disable >/proc/acpi/ibm/fan +Placing a fan on level 0 is the same as disabling it. Enabling a fan +will try to place it in a safe level if it is too slow or disabled. + WARNING WARNING WARNING: do not leave the fan disabled unless you are -monitoring the temperature sensor readings and you are ready to enable -it if necessary to avoid overheating. +monitoring all of the temperature sensor readings and you are ready to +enable it if necessary to avoid overheating. -The fan only runs if it's enabled *and* the various temperature -sensors which control it read high enough. On the X40, this seems to -depend on the CPU and HDD temperatures. Specifically, the fan is -turned on when either the CPU temperature climbs to 56 degrees or the -HDD temperature climbs to 46 degrees. The fan is turned off when the -CPU temperature drops to 49 degrees and the HDD temperature drops to -41 degrees. These thresholds cannot currently be controlled. +An enabled fan in level "auto" may stop spinning if the EC decides the +ThinkPad is cool enough and doesn't need the extra airflow. This is +normal, and the EC will spin the fan up if the varios thermal readings +rise too much. + +On the X40, this seems to depend on the CPU and HDD temperatures. +Specifically, the fan is turned on when either the CPU temperature +climbs to 56 degrees or the HDD temperature climbs to 46 degrees. The +fan is turned off when the CPU temperature drops to 49 degrees and the +HDD temperature drops to 41 degrees. These thresholds cannot +currently be controlled. + +The fan level can be controlled with the command: + + echo 'level <level>' > /proc/acpi/ibm/thermal + +Where <level> is an integer from 0 to 7, or one of the words "auto" +or "disengaged" (without the quotes). Not all ThinkPads support the +"auto" and "disengaged" levels. On the X31 and X40 (and ONLY on those models), the fan speed can be controlled to a certain degree. Once the fan is running, it can be @@ -562,12 +634,9 @@ about 3700 to about 7350. Values outside this range either do not have any effect or the fan speed eventually settles somewhere in that range. The fan cannot be stopped or started with this command. -On the 570, temperature readings are not available through this -feature and the fan control works a little differently. The fan speed -is reported in levels from 0 (off) to 7 (max) and can be controlled -with the following command: - - echo 'level <level>' > /proc/acpi/ibm/thermal +The ThinkPad's ACPI DSDT code will reprogram the fan on its own when +certain conditions are met. It will override any fan programming done +through ibm-acpi. EXPERIMENTAL: WAN -- /proc/acpi/ibm/wan --------------------------------------- @@ -601,6 +670,26 @@ example: modprobe ibm_acpi hotkey=enable,0xffff video=auto_disable +The ibm-acpi kernel driver can be programmed to revert the fan level +to a safe setting if userspace does not issue one of the fan commands: +"enable", "disable", "level" or "watchdog" within a configurable +ammount of time. To do this, use the "watchdog" command. + + echo 'watchdog <interval>' > /proc/acpi/ibm/fan + +Interval is the ammount of time in seconds to wait for one of the +above mentioned fan commands before reseting the fan level to a safe +one. If set to zero, the watchdog is disabled (default). When the +watchdog timer runs out, it does the exact equivalent of the "enable" +fan command. + +Note that the watchdog timer stops after it enables the fan. It will +be rearmed again automatically (using the same interval) when one of +the above mentioned fan commands is received. The fan watchdog is, +therefore, not suitable to protect against fan mode changes made +through means other than the "enable", "disable", and "level" fan +commands. + Example Configuration --------------------- diff --git a/Documentation/ioctl-number.txt b/Documentation/ioctl-number.txt index edc04d74ae2..5a8bd5bd88e 100644 --- a/Documentation/ioctl-number.txt +++ b/Documentation/ioctl-number.txt @@ -191,3 +191,5 @@ Code Seq# Include File Comments <mailto:aherrman@de.ibm.com> 0xF3 00-3F video/sisfb.h sisfb (in development) <mailto:thomas@winischhofer.net> +0xF4 00-1F video/mbxfb.h mbxfb + <mailto:raph@8d.com> diff --git a/Documentation/ioctl/ioctl-decoding.txt b/Documentation/ioctl/ioctl-decoding.txt new file mode 100644 index 00000000000..bfdf7f3ee4f --- /dev/null +++ b/Documentation/ioctl/ioctl-decoding.txt @@ -0,0 +1,24 @@ +To decode a hex IOCTL code: + +Most architecures use this generic format, but check +include/ARCH/ioctl.h for specifics, e.g. powerpc +uses 3 bits to encode read/write and 13 bits for size. + + bits meaning + 31-30 00 - no parameters: uses _IO macro + 10 - read: _IOR + 01 - write: _IOW + 11 - read/write: _IOWR + + 29-16 size of arguments + + 15-8 ascii character supposedly + unique to each driver + + 7-0 function # + + + So for example 0x82187201 is a read with arg length of 0x218, +character 'r' function 1. Grepping the source reveals this is: + +#define VFAT_IOCTL_READDIR_BOTH _IOR('r', 1, struct dirent [2]) diff --git a/Documentation/kbuild/kconfig-language.txt b/Documentation/kbuild/kconfig-language.txt index 125093c3ef7..536d5bfbdb8 100644 --- a/Documentation/kbuild/kconfig-language.txt +++ b/Documentation/kbuild/kconfig-language.txt @@ -29,7 +29,7 @@ them. A single configuration option is defined like this: config MODVERSIONS bool "Set version information on all module symbols" - depends MODULES + depends on MODULES help Usually, modules have to be recompiled whenever you switch to a new kernel. ... @@ -163,7 +163,7 @@ The position of a menu entry in the tree is determined in two ways. First it can be specified explicitly: menu "Network device support" - depends NET + depends on NET config NETDEVICES ... @@ -188,10 +188,10 @@ config MODULES config MODVERSIONS bool "Set version information on all module symbols" - depends MODULES + depends on MODULES comment "module support disabled" - depends !MODULES + depends on !MODULES MODVERSIONS directly depends on MODULES, this means it's only visible if MODULES is different from 'n'. The comment on the other hand is always diff --git a/Documentation/kdump/kdump.txt b/Documentation/kdump/kdump.txt index 99f2d4d4bf7..07330681834 100644 --- a/Documentation/kdump/kdump.txt +++ b/Documentation/kdump/kdump.txt @@ -17,7 +17,7 @@ You can use common Linux commands, such as cp and scp, to copy the memory image to a dump file on the local disk, or across the network to a remote system. -Kdump and kexec are currently supported on the x86, x86_64, and ppc64 +Kdump and kexec are currently supported on the x86, x86_64, ppc64 and ia64 architectures. When the system kernel boots, it reserves a small section of memory for @@ -54,59 +54,69 @@ memory," in two ways: Setup and Installation ====================== -Install kexec-tools and the Kdump patch ---------------------------------------- +Install kexec-tools +------------------- 1) Login as the root user. 2) Download the kexec-tools user-space package from the following URL: - http://www.xmission.com/~ebiederm/files/kexec/kexec-tools-1.101.tar.gz +http://www.kernel.org/pub/linux/kernel/people/horms/kexec-tools/kexec-tools-testing.tar.gz -3) Unpack the tarball with the tar command, as follows: - - tar xvpzf kexec-tools-1.101.tar.gz - -4) Download the latest consolidated Kdump patch from the following URL: +This is a symlink to the latest version, which at the time of writing is +20061214, the only release of kexec-tools-testing so far. As other versions +are made released, the older onese will remain available at +http://www.kernel.org/pub/linux/kernel/people/horms/kexec-tools/ - http://lse.sourceforge.net/kdump/ +Note: Latest kexec-tools-testing git tree is available at - (This location is being used until all the user-space Kdump patches - are integrated with the kexec-tools package.) +git://git.kernel.org/pub/scm/linux/kernel/git/horms/kexec-tools-testing.git +or +http://www.kernel.org/git/?p=linux/kernel/git/horms/kexec-tools-testing.git;a=summary -5) Change to the kexec-tools-1.101 directory, as follows: +3) Unpack the tarball with the tar command, as follows: - cd kexec-tools-1.101 + tar xvpzf kexec-tools-testing.tar.gz -6) Apply the consolidated patch to the kexec-tools-1.101 source tree - with the patch command, as follows. (Modify the path to the downloaded - patch as necessary.) +4) Change to the kexec-tools directory, as follows: - patch -p1 < /path-to-kdump-patch/kexec-tools-1.101-kdump.patch + cd kexec-tools-testing-VERSION -7) Configure the package, as follows: +5) Configure the package, as follows: ./configure -8) Compile the package, as follows: +6) Compile the package, as follows: make -9) Install the package, as follows: +7) Install the package, as follows: make install -Download and build the system and dump-capture kernels ------------------------------------------------------- +Build the system and dump-capture kernels +----------------------------------------- +There are two possible methods of using Kdump. + +1) Build a separate custom dump-capture kernel for capturing the + kernel core dump. -Download the mainline (vanilla) kernel source code (2.6.13-rc1 or newer) -from http://www.kernel.org. Two kernels must be built: a system kernel -and a dump-capture kernel. Use the following steps to configure these -kernels with the necessary kexec and Kdump features: +2) Or use the system kernel binary itself as dump-capture kernel and there is + no need to build a separate dump-capture kernel. This is possible + only with the architecutres which support a relocatable kernel. As + of today i386 and ia64 architectures support relocatable kernel. -System kernel -------------- +Building a relocatable kernel is advantageous from the point of view that +one does not have to build a second kernel for capturing the dump. But +at the same time one might want to build a custom dump capture kernel +suitable to his needs. + +Following are the configuration setting required for system and +dump-capture kernels for enabling kdump support. + +System kernel config options +---------------------------- 1) Enable "kexec system call" in "Processor type and features." @@ -132,88 +142,182 @@ System kernel analysis tools require a vmlinux with debug symbols in order to read and analyze a dump file. -4) Make and install the kernel and its modules. Update the boot loader - (such as grub, yaboot, or lilo) configuration files as necessary. +Dump-capture kernel config options (Arch Independent) +----------------------------------------------------- -5) Boot the system kernel with the boot parameter "crashkernel=Y@X", - where Y specifies how much memory to reserve for the dump-capture kernel - and X specifies the beginning of this reserved memory. For example, - "crashkernel=64M@16M" tells the system kernel to reserve 64 MB of memory - starting at physical address 0x01000000 for the dump-capture kernel. - - On x86 and x86_64, use "crashkernel=64M@16M". - - On ppc64, use "crashkernel=128M@32M". +1) Enable "kernel crash dumps" support under "Processor type and + features": + CONFIG_CRASH_DUMP=y -The dump-capture kernel ------------------------ +2) Enable "/proc/vmcore support" under "Filesystems" -> "Pseudo filesystems". -1) Under "General setup," append "-kdump" to the current string in - "Local version." + CONFIG_PROC_VMCORE=y + (CONFIG_PROC_VMCORE is set by default when CONFIG_CRASH_DUMP is selected.) -2) On x86, enable high memory support under "Processor type and +Dump-capture kernel config options (Arch Dependent, i386) +-------------------------------------------------------- +1) On x86, enable high memory support under "Processor type and features": CONFIG_HIGHMEM64G=y or CONFIG_HIGHMEM4G -3) On x86 and x86_64, disable symmetric multi-processing support +2) On x86 and x86_64, disable symmetric multi-processing support under "Processor type and features": CONFIG_SMP=n + (If CONFIG_SMP=y, then specify maxcpus=1 on the kernel command line when loading the dump-capture kernel, see section "Load the Dump-capture Kernel".) -4) On ppc64, disable NUMA support and enable EMBEDDED support: +3) If one wants to build and use a relocatable kernel, + Enable "Build a relocatable kernel" support under "Processor type and + features" - CONFIG_NUMA=n - CONFIG_EMBEDDED=y - CONFIG_EEH=N for the dump-capture kernel + CONFIG_RELOCATABLE=y -5) Enable "kernel crash dumps" support under "Processor type and - features": +4) Use a suitable value for "Physical address where the kernel is + loaded" (under "Processor type and features"). This only appears when + "kernel crash dumps" is enabled. A suitable value depends upon + whether kernel is relocatable or not. + + If you are using a relocatable kernel use CONFIG_PHYSICAL_START=0x100000 + This will compile the kernel for physical address 1MB, but given the fact + kernel is relocatable, it can be run from any physical address hence + kexec boot loader will load it in memory region reserved for dump-capture + kernel. + + Otherwise it should be the start of memory region reserved for + second kernel using boot parameter "crashkernel=Y@X". Here X is + start of memory region reserved for dump-capture kernel. + Generally X is 16MB (0x1000000). So you can set + CONFIG_PHYSICAL_START=0x1000000 + +5) Make and install the kernel and its modules. DO NOT add this kernel + to the boot loader configuration files. - CONFIG_CRASH_DUMP=y +Dump-capture kernel config options (Arch Dependent, x86_64) +---------------------------------------------------------- +1) On x86 and x86_64, disable symmetric multi-processing support + under "Processor type and features": -6) Use a suitable value for "Physical address where the kernel is + CONFIG_SMP=n + + (If CONFIG_SMP=y, then specify maxcpus=1 on the kernel command line + when loading the dump-capture kernel, see section "Load the Dump-capture + Kernel".) + +2) Use a suitable value for "Physical address where the kernel is loaded" (under "Processor type and features"). This only appears when "kernel crash dumps" is enabled. By default this value is 0x1000000 (16MB). It should be the same as X in the "crashkernel=Y@X" boot - parameter discussed above. + parameter. - On x86 and x86_64, use "CONFIG_PHYSICAL_START=0x1000000". + For x86_64, normally "CONFIG_PHYSICAL_START=0x1000000". - On ppc64 the value is automatically set at 32MB when - CONFIG_CRASH_DUMP is set. +3) Make and install the kernel and its modules. DO NOT add this kernel + to the boot loader configuration files. -6) Optionally enable "/proc/vmcore support" under "Filesystems" -> - "Pseudo filesystems". +Dump-capture kernel config options (Arch Dependent, ppc64) +---------------------------------------------------------- - CONFIG_PROC_VMCORE=y - (CONFIG_PROC_VMCORE is set by default when CONFIG_CRASH_DUMP is selected.) - -7) Make and install the kernel and its modules. DO NOT add this kernel +- Make and install the kernel and its modules. DO NOT add this kernel to the boot loader configuration files. +Dump-capture kernel config options (Arch Dependent, ia64) +---------------------------------------------------------- + +- No specific options are required to create a dump-capture kernel + for ia64, other than those specified in the arch idependent section + above. This means that it is possible to use the system kernel + as a dump-capture kernel if desired. + + The crashkernel region can be automatically placed by the system + kernel at run time. This is done by specifying the base address as 0, + or omitting it all together. + + crashkernel=256M@0 + or + crashkernel=256M + + If the start address is specified, note that the start address of the + kernel will be aligned to 64Mb, so if the start address is not then + any space below the alignment point will be wasted. + + +Boot into System Kernel +======================= + +1) Make and install the kernel and its modules. Update the boot loader + (such as grub, yaboot, or lilo) configuration files as necessary. + +2) Boot the system kernel with the boot parameter "crashkernel=Y@X", + where Y specifies how much memory to reserve for the dump-capture kernel + and X specifies the beginning of this reserved memory. For example, + "crashkernel=64M@16M" tells the system kernel to reserve 64 MB of memory + starting at physical address 0x01000000 (16MB) for the dump-capture kernel. + + On x86 and x86_64, use "crashkernel=64M@16M". + + On ppc64, use "crashkernel=128M@32M". + + On ia64, 256M@256M is a generous value that typically works. + The region may be automatically placed on ia64, see the + dump-capture kernel config option notes above. Load the Dump-capture Kernel ============================ -After booting to the system kernel, load the dump-capture kernel using -the following command: +After booting to the system kernel, dump-capture kernel needs to be +loaded. + +Based on the architecture and type of image (relocatable or not), one +can choose to load the uncompressed vmlinux or compressed bzImage/vmlinuz +of dump-capture kernel. Following is the summary. + +For i386: + - Use vmlinux if kernel is not relocatable. + - Use bzImage/vmlinuz if kernel is relocatable. +For x86_64: + - Use vmlinux +For ppc64: + - Use vmlinux +For ia64: + - Use vmlinux or vmlinuz.gz + - kexec -p <dump-capture-kernel> \ +If you are using a uncompressed vmlinux image then use following command +to load dump-capture kernel. + + kexec -p <dump-capture-kernel-vmlinux-image> \ --initrd=<initrd-for-dump-capture-kernel> --args-linux \ - --append="root=<root-dev> init 1 irqpoll" + --append="root=<root-dev> <arch-specific-options>" +If you are using a compressed bzImage/vmlinuz, then use following command +to load dump-capture kernel. -Notes on loading the dump-capture kernel: + kexec -p <dump-capture-kernel-bzImage> \ + --initrd=<initrd-for-dump-capture-kernel> \ + --append="root=<root-dev> <arch-specific-options>" + +Please note, that --args-linux does not need to be specified for ia64. +It is planned to make this a no-op on that architecture, but for now +it should be omitted + +Following are the arch specific command line options to be used while +loading dump-capture kernel. -* <dump-capture-kernel> must be a vmlinux image (that is, an - uncompressed ELF image). bzImage does not work at this time. +For i386, x86_64 and ia64: + "init 1 irqpoll maxcpus=1" + +For ppc64: + "init 1 maxcpus=1 noirqdistrib" + + +Notes on loading the dump-capture kernel: * By default, the ELF headers are stored in ELF64 format to support systems with more than 4GB memory. The --elf32-core-headers option can @@ -231,6 +335,9 @@ Notes on loading the dump-capture kernel: * "init 1" boots the dump-capture kernel into single-user mode without networking. If you want networking, use "init 3." +* We generally don' have to bring up a SMP kernel just to capture the + dump. Hence generally it is useful either to build a UP dump-capture + kernel or specify maxcpus=1 option while loading dump-capture kernel. Kernel Panic ============ diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index b79bcdf1631..25d29851710 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -548,6 +548,13 @@ and is between 256 and 4096 characters. It is defined in the file eurwdt= [HW,WDT] Eurotech CPU-1220/1410 onboard watchdog. Format: <io>[,<irq>] + failslab= + fail_page_alloc= + fail_make_request=[KNL] + General fault injection mechanism. + Format: <interval>,<probability>,<space>,<times> + See also /Documentation/fault-injection/. + fd_mcs= [HW,SCSI] See header of drivers/scsi/fd_mcs.c. @@ -1649,6 +1656,12 @@ and is between 256 and 4096 characters. It is defined in the file sym53c416= [HW,SCSI] See header of drivers/scsi/sym53c416.c. + sysrq_always_enabled + [KNL] + Ignore sysrq setting - this boot parameter will + neutralize any effect of /proc/sys/kernel/sysrq. + Useful for debugging. + t128= [HW,SCSI] See header of drivers/scsi/t128.c. @@ -1701,6 +1714,14 @@ and is between 256 and 4096 characters. It is defined in the file uart6850= [HW,OSS] Format: <io>,<irq> + uhci-hcd.ignore_oc= + [USB] Ignore overcurrent events (default N). + Some badly-designed motherboards generate lots of + bogus events, for ports that aren't wired to + anything. Set this parameter to avoid log spamming. + Note that genuine overcurrent events won't be + reported either. + usbhid.mousepoll= [USBHID] The interval which mice are to be polled at. diff --git a/Documentation/networking/dccp.txt b/Documentation/networking/dccp.txt index dda15886bcb..387482e46c4 100644 --- a/Documentation/networking/dccp.txt +++ b/Documentation/networking/dccp.txt @@ -19,7 +19,8 @@ for real time and multimedia traffic. It has a base protocol and pluggable congestion control IDs (CCIDs). -It is at experimental RFC status and the homepage for DCCP as a protocol is at: +It is at proposed standard RFC status and the homepage for DCCP as a protocol +is at: http://www.read.cs.ucla.edu/dccp/ Missing features @@ -34,9 +35,6 @@ The known bugs are at: Socket options ============== -DCCP_SOCKOPT_PACKET_SIZE is used for CCID3 to set default packet size for -calculations. - DCCP_SOCKOPT_SERVICE sets the service. The specification mandates use of service codes (RFC 4340, sec. 8.1.2); if this socket option is not set, the socket will fall back to 0 (which means that no meaningful service code diff --git a/Documentation/pci.txt b/Documentation/pci.txt index 2b395e47896..fd5028eca13 100644 --- a/Documentation/pci.txt +++ b/Documentation/pci.txt @@ -1,142 +1,231 @@ - How To Write Linux PCI Drivers - by Martin Mares <mj@ucw.cz> on 07-Feb-2000 + How To Write Linux PCI Drivers + + by Martin Mares <mj@ucw.cz> on 07-Feb-2000 + updated by Grant Grundler <grundler@parisc-linux.org> on 23-Dec-2006 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The world of PCI is vast and it's full of (mostly unpleasant) surprises. -Different PCI devices have different requirements and different bugs -- -because of this, the PCI support layer in Linux kernel is not as trivial -as one would wish. This short pamphlet tries to help all potential driver -authors find their way through the deep forests of PCI handling. +The world of PCI is vast and full of (mostly unpleasant) surprises. +Since each CPU architecture implements different chip-sets and PCI devices +have different requirements (erm, "features"), the result is the PCI support +in the Linux kernel is not as trivial as one would wish. This short paper +tries to introduce all potential driver authors to Linux APIs for +PCI device drivers. + +A more complete resource is the third edition of "Linux Device Drivers" +by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman. +LDD3 is available for free (under Creative Commons License) from: + + http://lwn.net/Kernel/LDD3/ + +However, keep in mind that all documents are subject to "bit rot". +Refer to the source code if things are not working as described here. + +Please send questions/comments/patches about Linux PCI API to the +"Linux PCI" <linux-pci@atrey.karlin.mff.cuni.cz> mailing list. + 0. Structure of PCI drivers ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There exist two kinds of PCI drivers: new-style ones (which leave most of -probing for devices to the PCI layer and support online insertion and removal -of devices [thus supporting PCI, hot-pluggable PCI and CardBus in a single -driver]) and old-style ones which just do all the probing themselves. Unless -you have a very good reason to do so, please don't use the old way of probing -in any new code. After the driver finds the devices it wishes to operate -on (either the old or the new way), it needs to perform the following steps: +PCI drivers "discover" PCI devices in a system via pci_register_driver(). +Actually, it's the other way around. When the PCI generic code discovers +a new device, the driver with a matching "description" will be notified. +Details on this below. + +pci_register_driver() leaves most of the probing for devices to +the PCI layer and supports online insertion/removal of devices [thus +supporting hot-pluggable PCI, CardBus, and Express-Card in a single driver]. +pci_register_driver() call requires passing in a table of function +pointers and thus dictates the high level structure of a driver. + +Once the driver knows about a PCI device and takes ownership, the +driver generally needs to perform the following initialization: Enable the device - Access device configuration space - Discover resources (addresses and IRQ numbers) provided by the device - Allocate these resources - Communicate with the device + Request MMIO/IOP resources + Set the DMA mask size (for both coherent and streaming DMA) + Allocate and initialize shared control data (pci_allocate_coherent()) + Access device configuration space (if needed) + Register IRQ handler (request_irq()) + Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip) + Enable DMA/processing engines + +When done using the device, and perhaps the module needs to be unloaded, +the driver needs to take the follow steps: + Disable the device from generating IRQs + Release the IRQ (free_irq()) + Stop all DMA activity + Release DMA buffers (both streaming and coherent) + Unregister from other subsystems (e.g. scsi or netdev) + Release MMIO/IOP resources Disable the device -Most of these topics are covered by the following sections, for the rest -look at <linux/pci.h>, it's hopefully well commented. +Most of these topics are covered in the following sections. +For the rest look at LDD3 or <linux/pci.h> . If the PCI subsystem is not configured (CONFIG_PCI is not set), most of -the functions described below are defined as inline functions either completely -empty or just returning an appropriate error codes to avoid lots of ifdefs -in the drivers. +the PCI functions described below are defined as inline functions either +completely empty or just returning an appropriate error codes to avoid +lots of ifdefs in the drivers. + -1. New-style drivers -~~~~~~~~~~~~~~~~~~~~ -The new-style drivers just call pci_register_driver during their initialization -with a pointer to a structure describing the driver (struct pci_driver) which -contains: +1. pci_register_driver() call +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - name Name of the driver +PCI device drivers call pci_register_driver() during their +initialization with a pointer to a structure describing the driver +(struct pci_driver): + + field name Description + ---------- ------------------------------------------------------ id_table Pointer to table of device ID's the driver is interested in. Most drivers should export this table using MODULE_DEVICE_TABLE(pci,...). - probe Pointer to a probing function which gets called (during - execution of pci_register_driver for already existing - devices or later if a new device gets inserted) for all - PCI devices which match the ID table and are not handled - by the other drivers yet. This function gets passed a - pointer to the pci_dev structure representing the device - and also which entry in the ID table did the device - match. It returns zero when the driver has accepted the - device or an error code (negative number) otherwise. - This function always gets called from process context, - so it can sleep. - remove Pointer to a function which gets called whenever a - device being handled by this driver is removed (either - during deregistration of the driver or when it's - manually pulled out of a hot-pluggable slot). This - function always gets called from process context, so it - can sleep. - save_state Save a device's state before it's suspend. + + probe This probing function gets called (during execution + of pci_register_driver() for already existing + devices or later if a new device gets inserted) for + all PCI devices which match the ID table and are not + "owned" by the other drivers yet. This function gets + passed a "struct pci_dev *" for each device whose + entry in the ID table matches the device. The probe + function returns zero when the driver chooses to + take "ownership" of the device or an error code + (negative number) otherwise. + The probe function always gets called from process + context, so it can sleep. + + remove The remove() function gets called whenever a device + being handled by this driver is removed (either during + deregistration of the driver or when it's manually + pulled out of a hot-pluggable slot). + The remove function always gets called from process + context, so it can sleep. + suspend Put device into low power state. + suspend_late Put device into low power state. + + resume_early Wake device from low power state. resume Wake device from low power state. + + (Please see Documentation/power/pci.txt for descriptions + of PCI Power Management and the related functions.) + enable_wake Enable device to generate wake events from a low power state. - (Please see Documentation/power/pci.txt for descriptions - of PCI Power Management and the related functions) + shutdown Hook into reboot_notifier_list (kernel/sys.c). + Intended to stop any idling DMA operations. + Useful for enabling wake-on-lan (NIC) or changing + the power state of a device before reboot. + e.g. drivers/net/e100.c. + + err_handler See Documentation/pci-error-recovery.txt + + multithread_probe Enable multi-threaded probe/scan. Driver must + provide its own locking/syncronization for init + operations if this is enabled. + -The ID table is an array of struct pci_device_id ending with a all-zero entry. -Each entry consists of: +The ID table is an array of struct pci_device_id entries ending with an +all-zero entry. Each entry consists of: + + vendor,device Vendor and device ID to match (or PCI_ANY_ID) - vendor, device Vendor and device ID to match (or PCI_ANY_ID) subvendor, Subsystem vendor and device ID to match (or PCI_ANY_ID) - subdevice - class, Device class to match. The class_mask tells which bits - class_mask of the class are honored during the comparison. + subdevice, + + class Device class, subclass, and "interface" to match. + See Appendix D of the PCI Local Bus Spec or + include/linux/pci_ids.h for a full list of classes. + Most drivers do not need to specify class/class_mask + as vendor/device is normally sufficient. + + class_mask limit which sub-fields of the class field are compared. + See drivers/scsi/sym53c8xx_2/ for example of usage. + driver_data Data private to the driver. + Most drivers don't need to use driver_data field. + Best practice is to use driver_data as an index + into a static list of equivalent device types, + instead of using it as a pointer. -Most drivers don't need to use the driver_data field. Best practice -for use of driver_data is to use it as an index into a static list of -equivalent device types, not to use it as a pointer. -Have a table entry {PCI_ANY_ID, PCI_ANY_ID, PCI_ANY_ID, PCI_ANY_ID} -to have probe() called for every PCI device known to the system. +Most drivers only need PCI_DEVICE() or PCI_DEVICE_CLASS() to set up +a pci_device_id table. -New PCI IDs may be added to a device driver at runtime by writing -to the file /sys/bus/pci/drivers/{driver}/new_id. When added, the -driver will probe for all devices it can support. +New PCI IDs may be added to a device driver pci_ids table at runtime +as shown below: echo "vendor device subvendor subdevice class class_mask driver_data" > \ - /sys/bus/pci/drivers/{driver}/new_id -where all fields are passed in as hexadecimal values (no leading 0x). -Users need pass only as many fields as necessary; vendor, device, -subvendor, and subdevice fields default to PCI_ANY_ID (FFFFFFFF), -class and classmask fields default to 0, and driver_data defaults to -0UL. Device drivers must initialize use_driver_data in the dynids struct -in their pci_driver struct prior to calling pci_register_driver in order -for the driver_data field to get passed to the driver. Otherwise, only a -0 is passed in that field. +/sys/bus/pci/drivers/{driver}/new_id + +All fields are passed in as hexadecimal values (no leading 0x). +Users need pass only as many fields as necessary: + o vendor, device, subvendor, and subdevice fields default + to PCI_ANY_ID (FFFFFFFF), + o class and classmask fields default to 0 + o driver_data defaults to 0UL. + +Once added, the driver probe routine will be invoked for any unclaimed +PCI devices listed in its (newly updated) pci_ids list. When the driver exits, it just calls pci_unregister_driver() and the PCI layer automatically calls the remove hook for all devices handled by the driver. + +1.1 "Attributes" for driver functions/data + Please mark the initialization and cleanup functions where appropriate (the corresponding macros are defined in <linux/init.h>): __init Initialization code. Thrown away after the driver initializes. __exit Exit code. Ignored for non-modular drivers. - __devinit Device initialization code. Identical to __init if - the kernel is not compiled with CONFIG_HOTPLUG, normal - function otherwise. + + + __devinit Device initialization code. + Identical to __init if the kernel is not compiled + with CONFIG_HOTPLUG, normal function otherwise. __devexit The same for __exit. -Tips: - The module_init()/module_exit() functions (and all initialization - functions called only from these) should be marked __init/exit. - The struct pci_driver shouldn't be marked with any of these tags. - The ID table array should be marked __devinitdata. - The probe() and remove() functions (and all initialization - functions called only from these) should be marked __devinit/exit. - If you are sure the driver is not a hotplug driver then use only - __init/exit __initdata/exitdata. +Tips on when/where to use the above attributes: + o The module_init()/module_exit() functions (and all + initialization functions called _only_ from these) + should be marked __init/__exit. - Pointers to functions marked as __devexit must be created using - __devexit_p(function_name). That will generate the function - name or NULL if the __devexit function will be discarded. + o Do not mark the struct pci_driver. + o The ID table array should be marked __devinitdata. -2. How to find PCI devices manually (the old style) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -PCI drivers not using the pci_register_driver() interface search -for PCI devices manually using the following constructs: + o The probe() and remove() functions should be marked __devinit + and __devexit respectively. All initialization functions + exclusively called by the probe() routine, can be marked __devinit. + Ditto for remove() and __devexit. + + o If mydriver_probe() is marked with __devinit(), then all address + references to mydriver_probe must use __devexit_p(mydriver_probe) + (in the struct pci_driver declaration for example). + __devexit_p() will generate the function name _or_ NULL if the + function will be discarded. For an example, see drivers/net/tg3.c. + + o Do NOT mark a function if you are not sure which mark to use. + Better to not mark the function than mark the function wrong. + + + +2. How to find PCI devices manually +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +PCI drivers should have a really good reason for not using the +pci_register_driver() interface to search for PCI devices. +The main reason PCI devices are controlled by multiple drivers +is because one PCI device implements several different HW services. +E.g. combined serial/parallel port/floppy controller. + +A manual search may be performed using the following constructs: Searching by vendor and device ID: @@ -150,87 +239,311 @@ Searching by class ID (iterate in a similar way): Searching by both vendor/device and subsystem vendor/device ID: - pci_get_subsys(VENDOR_ID, DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev). + pci_get_subsys(VENDOR_ID,DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev). - You can use the constant PCI_ANY_ID as a wildcard replacement for +You can use the constant PCI_ANY_ID as a wildcard replacement for VENDOR_ID or DEVICE_ID. This allows searching for any device from a specific vendor, for example. - These functions are hotplug-safe. They increment the reference count on +These functions are hotplug-safe. They increment the reference count on the pci_dev that they return. You must eventually (possibly at module unload) decrement the reference count on these devices by calling pci_dev_put(). -3. Enabling and disabling devices -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Before you do anything with the device you've found, you need to enable -it by calling pci_enable_device() which enables I/O and memory regions of -the device, allocates an IRQ if necessary, assigns missing resources if -needed and wakes up the device if it was in suspended state. Please note -that this function can fail. - If you want to use the device in bus mastering mode, call pci_set_master() -which enables the bus master bit in PCI_COMMAND register and also fixes -the latency timer value if it's set to something bogus by the BIOS. +3. Device Initialization Steps +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As noted in the introduction, most PCI drivers need the following steps +for device initialization: - If you want to use the PCI Memory-Write-Invalidate transaction, + Enable the device + Request MMIO/IOP resources + Set the DMA mask size (for both coherent and streaming DMA) + Allocate and initialize shared control data (pci_allocate_coherent()) + Access device configuration space (if needed) + Register IRQ handler (request_irq()) + Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip) + Enable DMA/processing engines. + +The driver can access PCI config space registers at any time. +(Well, almost. When running BIST, config space can go away...but +that will just result in a PCI Bus Master Abort and config reads +will return garbage). + + +3.1 Enable the PCI device +~~~~~~~~~~~~~~~~~~~~~~~~~ +Before touching any device registers, the driver needs to enable +the PCI device by calling pci_enable_device(). This will: + o wake up the device if it was in suspended state, + o allocate I/O and memory regions of the device (if BIOS did not), + o allocate an IRQ (if BIOS did not). + +NOTE: pci_enable_device() can fail! Check the return value. +NOTE2: Also see pci_enable_device_bars() below. Drivers can + attempt to enable only a subset of BARs they need. + +[ OS BUG: we don't check resource allocations before enabling those + resources. The sequence would make more sense if we called + pci_request_resources() before calling pci_enable_device(). + Currently, the device drivers can't detect the bug when when two + devices have been allocated the same range. This is not a common + problem and unlikely to get fixed soon. + + This has been discussed before but not changed as of 2.6.19: + http://lkml.org/lkml/2006/3/2/194 +] + +pci_set_master() will enable DMA by setting the bus master bit +in the PCI_COMMAND register. It also fixes the latency timer value if +it's set to something bogus by the BIOS. + +If the PCI device can use the PCI Memory-Write-Invalidate transaction, call pci_set_mwi(). This enables the PCI_COMMAND bit for Mem-Wr-Inval and also ensures that the cache line size register is set correctly. -Make sure to check the return value of pci_set_mwi(), not all architectures -may support Memory-Write-Invalidate. +Check the return value of pci_set_mwi() as not all architectures +or chip-sets may support Memory-Write-Invalidate. + + +3.2 Request MMIO/IOP resources +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Memory (MMIO), and I/O port addresses should NOT be read directly +from the PCI device config space. Use the values in the pci_dev structure +as the PCI "bus address" might have been remapped to a "host physical" +address by the arch/chip-set specific kernel support. - If your driver decides to stop using the device (e.g., there was an -error while setting it up or the driver module is being unloaded), it -should call pci_disable_device() to deallocate any IRQ resources, disable -PCI bus-mastering, etc. You should not do anything with the device after +See Documentation/IO-mapping.txt for how to access device registers +or device memory. + +The device driver needs to call pci_request_region() to verify +no other device is already using the same address resource. +Conversely, drivers should call pci_release_region() AFTER calling pci_disable_device(). +The idea is to prevent two devices colliding on the same address range. + +[ See OS BUG comment above. Currently (2.6.19), The driver can only + determine MMIO and IO Port resource availability _after_ calling + pci_enable_device(). ] + +Generic flavors of pci_request_region() are request_mem_region() +(for MMIO ranges) and request_region() (for IO Port ranges). +Use these for address resources that are not described by "normal" PCI +BARs. + +Also see pci_request_selected_regions() below. + + +3.3 Set the DMA mask size +~~~~~~~~~~~~~~~~~~~~~~~~~ +[ If anything below doesn't make sense, please refer to + Documentation/DMA-API.txt. This section is just a reminder that + drivers need to indicate DMA capabilities of the device and is not + an authoritative source for DMA interfaces. ] + +While all drivers should explicitly indicate the DMA capability +(e.g. 32 or 64 bit) of the PCI bus master, devices with more than +32-bit bus master capability for streaming data need the driver +to "register" this capability by calling pci_set_dma_mask() with +appropriate parameters. In general this allows more efficient DMA +on systems where System RAM exists above 4G _physical_ address. + +Drivers for all PCI-X and PCIe compliant devices must call +pci_set_dma_mask() as they are 64-bit DMA devices. + +Similarly, drivers must also "register" this capability if the device +can directly address "consistent memory" in System RAM above 4G physical +address by calling pci_set_consistent_dma_mask(). +Again, this includes drivers for all PCI-X and PCIe compliant devices. +Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are +64-bit DMA capable for payload ("streaming") data but not control +("consistent") data. + + +3.4 Setup shared control data +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared) +memory. See Documentation/DMA-API.txt for a full description of +the DMA APIs. This section is just a reminder that it needs to be done +before enabling DMA on the device. + + +3.5 Initialize device registers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Some drivers will need specific "capability" fields programmed +or other "vendor specific" register initialized or reset. +E.g. clearing pending interrupts. + + +3.6 Register IRQ handler +~~~~~~~~~~~~~~~~~~~~~~~~ +While calling request_irq() is the the last step described here, +this is often just another intermediate step to initialize a device. +This step can often be deferred until the device is opened for use. + +All interrupt handlers for IRQ lines should be registered with IRQF_SHARED +and use the devid to map IRQs to devices (remember that all PCI IRQ lines +can be shared). + +request_irq() will associate an interrupt handler and device handle +with an interrupt number. Historically interrupt numbers represent +IRQ lines which run from the PCI device to the Interrupt controller. +With MSI and MSI-X (more below) the interrupt number is a CPU "vector". + +request_irq() also enables the interrupt. Make sure the device is +quiesced and does not have any interrupts pending before registering +the interrupt handler. + +MSI and MSI-X are PCI capabilities. Both are "Message Signaled Interrupts" +which deliver interrupts to the CPU via a DMA write to a Local APIC. +The fundamental difference between MSI and MSI-X is how multiple +"vectors" get allocated. MSI requires contiguous blocks of vectors +while MSI-X can allocate several individual ones. + +MSI capability can be enabled by calling pci_enable_msi() or +pci_enable_msix() before calling request_irq(). This causes +the PCI support to program CPU vector data into the PCI device +capability registers. + +If your PCI device supports both, try to enable MSI-X first. +Only one can be enabled at a time. Many architectures, chip-sets, +or BIOSes do NOT support MSI or MSI-X and the call to pci_enable_msi/msix +will fail. This is important to note since many drivers have +two (or more) interrupt handlers: one for MSI/MSI-X and another for IRQs. +They choose which handler to register with request_irq() based on the +return value from pci_enable_msi/msix(). + +There are (at least) two really good reasons for using MSI: +1) MSI is an exclusive interrupt vector by definition. + This means the interrupt handler doesn't have to verify + its device caused the interrupt. + +2) MSI avoids DMA/IRQ race conditions. DMA to host memory is guaranteed + to be visible to the host CPU(s) when the MSI is delivered. This + is important for both data coherency and avoiding stale control data. + This guarantee allows the driver to omit MMIO reads to flush + the DMA stream. + +See drivers/infiniband/hw/mthca/ or drivers/net/tg3.c for examples +of MSI/MSI-X usage. + + + +4. PCI device shutdown +~~~~~~~~~~~~~~~~~~~~~~~ + +When a PCI device driver is being unloaded, most of the following +steps need to be performed: + + Disable the device from generating IRQs + Release the IRQ (free_irq()) + Stop all DMA activity + Release DMA buffers (both streaming and consistent) + Unregister from other subsystems (e.g. scsi or netdev) + Disable device from responding to MMIO/IO Port addresses + Release MMIO/IO Port resource(s) + + +4.1 Stop IRQs on the device +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +How to do this is chip/device specific. If it's not done, it opens +the possibility of a "screaming interrupt" if (and only if) +the IRQ is shared with another device. + +When the shared IRQ handler is "unhooked", the remaining devices +using the same IRQ line will still need the IRQ enabled. Thus if the +"unhooked" device asserts IRQ line, the system will respond assuming +it was one of the remaining devices asserted the IRQ line. Since none +of the other devices will handle the IRQ, the system will "hang" until +it decides the IRQ isn't going to get handled and masks the IRQ (100,000 +iterations later). Once the shared IRQ is masked, the remaining devices +will stop functioning properly. Not a nice situation. + +This is another reason to use MSI or MSI-X if it's available. +MSI and MSI-X are defined to be exclusive interrupts and thus +are not susceptible to the "screaming interrupt" problem. + + +4.2 Release the IRQ +~~~~~~~~~~~~~~~~~~~ +Once the device is quiesced (no more IRQs), one can call free_irq(). +This function will return control once any pending IRQs are handled, +"unhook" the drivers IRQ handler from that IRQ, and finally release +the IRQ if no one else is using it. + + +4.3 Stop all DMA activity +~~~~~~~~~~~~~~~~~~~~~~~~~ +It's extremely important to stop all DMA operations BEFORE attempting +to deallocate DMA control data. Failure to do so can result in memory +corruption, hangs, and on some chip-sets a hard crash. -4. How to access PCI config space +Stopping DMA after stopping the IRQs can avoid races where the +IRQ handler might restart DMA engines. + +While this step sounds obvious and trivial, several "mature" drivers +didn't get this step right in the past. + + +4.4 Release DMA buffers +~~~~~~~~~~~~~~~~~~~~~~~ +Once DMA is stopped, clean up streaming DMA first. +I.e. unmap data buffers and return buffers to "upstream" +owners if there is one. + +Then clean up "consistent" buffers which contain the control data. + +See Documentation/DMA-API.txt for details on unmapping interfaces. + + +4.5 Unregister from other subsystems +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Most low level PCI device drivers support some other subsystem +like USB, ALSA, SCSI, NetDev, Infiniband, etc. Make sure your +driver isn't losing resources from that other subsystem. +If this happens, typically the symptom is an Oops (panic) when +the subsystem attempts to call into a driver that has been unloaded. + + +4.6 Disable Device from responding to MMIO/IO Port addresses +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +io_unmap() MMIO or IO Port resources and then call pci_disable_device(). +This is the symmetric opposite of pci_enable_device(). +Do not access device registers after calling pci_disable_device(). + + +4.7 Release MMIO/IO Port Resource(s) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Call pci_release_region() to mark the MMIO or IO Port range as available. +Failure to do so usually results in the inability to reload the driver. + + + +5. How to access PCI config space ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - You can use pci_(read|write)_config_(byte|word|dword) to access the config + +You can use pci_(read|write)_config_(byte|word|dword) to access the config space of a device represented by struct pci_dev *. All these functions return 0 when successful or an error code (PCIBIOS_...) which can be translated to a text string by pcibios_strerror. Most drivers expect that accesses to valid PCI devices don't fail. - If you don't have a struct pci_dev available, you can call +If you don't have a struct pci_dev available, you can call pci_bus_(read|write)_config_(byte|word|dword) to access a given device and function on that bus. - If you access fields in the standard portion of the config header, please +If you access fields in the standard portion of the config header, please use symbolic names of locations and bits declared in <linux/pci.h>. - If you need to access Extended PCI Capability registers, just call +If you need to access Extended PCI Capability registers, just call pci_find_capability() for the particular capability and it will find the corresponding register block for you. -5. Addresses and interrupts -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Memory and port addresses and interrupt numbers should NOT be read from the -config space. You should use the values in the pci_dev structure as they might -have been remapped by the kernel. - - See Documentation/IO-mapping.txt for how to access device memory. - - The device driver needs to call pci_request_region() to make sure -no other device is already using the same resource. The driver is expected -to determine MMIO and IO Port resource availability _before_ calling -pci_enable_device(). Conversely, drivers should call pci_release_region() -_after_ calling pci_disable_device(). The idea is to prevent two devices -colliding on the same address range. - -Generic flavors of pci_request_region() are request_mem_region() -(for MMIO ranges) and request_region() (for IO Port ranges). -Use these for address resources that are not described by "normal" PCI -interfaces (e.g. BAR). - - All interrupt handlers should be registered with IRQF_SHARED and use the devid -to map IRQs to devices (remember that all PCI interrupts are shared). - 6. Other interesting functions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + pci_find_slot() Find pci_dev corresponding to given bus and slot numbers. pci_set_power_state() Set PCI Power Management state (0=D0 ... 3=D3) @@ -247,11 +560,12 @@ pci_set_mwi() Enable Memory-Write-Invalidate transactions. pci_clear_mwi() Disable Memory-Write-Invalidate transactions. + 7. Miscellaneous hints ~~~~~~~~~~~~~~~~~~~~~~ -When displaying PCI slot names to the user (for example when a driver wants -to tell the user what card has it found), please use pci_name(pci_dev) -for this purpose. + +When displaying PCI device names to the user (for example when a driver wants +to tell the user what card has it found), please use pci_name(pci_dev). Always refer to the PCI devices by a pointer to the pci_dev structure. All PCI layer functions use this identification and it's the only @@ -259,31 +573,113 @@ reasonable one. Don't use bus/slot/function numbers except for very special purposes -- on systems with multiple primary buses their semantics can be pretty complex. -If you're going to use PCI bus mastering DMA, take a look at -Documentation/DMA-mapping.txt. - Don't try to turn on Fast Back to Back writes in your driver. All devices on the bus need to be capable of doing it, so this is something which needs to be handled by platform and generic code, not individual drivers. + 8. Vendor and device identifications ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For the future, let's avoid adding device ids to include/linux/pci_ids.h. -PCI_VENDOR_ID_xxx for vendors, and a hex constant for device ids. +One is not not required to add new device ids to include/linux/pci_ids.h. +Please add PCI_VENDOR_ID_xxx for vendors and a hex constant for device ids. + +PCI_VENDOR_ID_xxx constants are re-used. The device ids are arbitrary +hex numbers (vendor controlled) and normally used only in a single +location, the pci_device_id table. + +Please DO submit new vendor/device ids to pciids.sourceforge.net project. + -Rationale: PCI_VENDOR_ID_xxx constants are re-used, but device ids are not. - Further, device ids are arbitrary hex numbers, normally used only in a - single location, the pci_device_id table. 9. Obsolete functions ~~~~~~~~~~~~~~~~~~~~~ + There are several functions which you might come across when trying to port an old driver to the new PCI interface. They are no longer present in the kernel as they aren't compatible with hotplug or PCI domains or having sane locking. -pci_find_device() Superseded by pci_get_device() -pci_find_subsys() Superseded by pci_get_subsys() -pci_find_slot() Superseded by pci_get_slot() +pci_find_device() Superseded by pci_get_device() +pci_find_subsys() Superseded by pci_get_subsys() +pci_find_slot() Superseded by pci_get_slot() + + +The alternative is the traditional PCI device driver that walks PCI +device lists. This is still possible but discouraged. + + + +10. pci_enable_device_bars() and Legacy I/O Port space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Large servers may not be able to provide I/O port resources to all PCI +devices. I/O Port space is only 64KB on Intel Architecture[1] and is +likely also fragmented since the I/O base register of PCI-to-PCI +bridge will usually be aligned to a 4KB boundary[2]. On such systems, +pci_enable_device() and pci_request_region() will fail when +attempting to enable I/O Port regions that don't have I/O Port +resources assigned. + +Fortunately, many PCI devices which request I/O Port resources also +provide access to the same registers via MMIO BARs. These devices can +be handled without using I/O port space and the drivers typically +offer a CONFIG_ option to only use MMIO regions +(e.g. CONFIG_TULIP_MMIO). PCI devices typically provide I/O port +interface for legacy OSes and will work when I/O port resources are not +assigned. The "PCI Local Bus Specification Revision 3.0" discusses +this on p.44, "IMPLEMENTATION NOTE". + +If your PCI device driver doesn't need I/O port resources assigned to +I/O Port BARs, you should use pci_enable_device_bars() instead of +pci_enable_device() in order not to enable I/O port regions for the +corresponding devices. In addition, you should use +pci_request_selected_regions() and pci_release_selected_regions() +instead of pci_request_regions()/pci_release_regions() in order not to +request/release I/O port regions for the corresponding devices. + +[1] Some systems support 64KB I/O port space per PCI segment. +[2] Some PCI-to-PCI bridges support optional 1KB aligned I/O base. + + + +11. MMIO Space and "Write Posting" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Converting a driver from using I/O Port space to using MMIO space +often requires some additional changes. Specifically, "write posting" +needs to be handled. Many drivers (e.g. tg3, acenic, sym53c8xx_2) +already do this. I/O Port space guarantees write transactions reach the PCI +device before the CPU can continue. Writes to MMIO space allow the CPU +to continue before the transaction reaches the PCI device. HW weenies +call this "Write Posting" because the write completion is "posted" to +the CPU before the transaction has reached its destination. + +Thus, timing sensitive code should add readl() where the CPU is +expected to wait before doing other work. The classic "bit banging" +sequence works fine for I/O Port space: + + for (i = 8; --i; val >>= 1) { + outb(val & 1, ioport_reg); /* write bit */ + udelay(10); + } + +The same sequence for MMIO space should be: + + for (i = 8; --i; val >>= 1) { + writeb(val & 1, mmio_reg); /* write bit */ + readb(safe_mmio_reg); /* flush posted write */ + udelay(10); + } + +It is important that "safe_mmio_reg" not have any side effects that +interferes with the correct operation of the device. + +Another case to watch out for is when resetting a PCI device. Use PCI +Configuration space reads to flush the writel(). This will gracefully +handle the PCI master abort on all platforms if the PCI device is +expected to not respond to a readl(). Most x86 platforms will allow +MMIO reads to master abort (a.k.a. "Soft Fail") and return garbage +(e.g. ~0). But many RISC platforms will crash (a.k.a."Hard Fail"). + diff --git a/Documentation/powerpc/booting-without-of.txt b/Documentation/powerpc/booting-without-of.txt index b3bd36668db..33994271cb3 100644 --- a/Documentation/powerpc/booting-without-of.txt +++ b/Documentation/powerpc/booting-without-of.txt @@ -1703,29 +1703,32 @@ platforms are moved over to use the flattened-device-tree model. Required properties: - device_type : has to be "rom" - - compatible : Should specify what this ROM device is compatible with - (i.e. "onenand"). Currently, this is most likely to be "direct-mapped" - (which corresponds to the MTD physmap mapping driver). - - regs : Offset and length of the register set (or memory mapping) for + - compatible : Should specify what this flash device is compatible with. + Currently, this is most likely to be "direct-mapped" (which + corresponds to the MTD physmap mapping driver). + - reg : Offset and length of the register set (or memory mapping) for the device. + - bank-width : Width of the flash data bus in bytes. Required + for the NOR flashes (compatible == "direct-mapped" and others) ONLY. Recommended properties : - - bank-width : Width of the flash data bus in bytes. Required - for the NOR flashes (compatible == "direct-mapped" and others) ONLY. - partitions : Several pairs of 32-bit values where the first value is partition's offset from the start of the device and the second one is partition size in bytes with LSB used to signify a read only - partititon (so, the parition size should always be an even number). + partition (so, the parition size should always be an even number). - partition-names : The list of concatenated zero terminated strings representing the partition names. + - probe-type : The type of probe which should be done for the chip + (JEDEC vs CFI actually). Valid ONLY for NOR flashes. Example: flash@ff000000 { device_type = "rom"; compatible = "direct-mapped"; - regs = <ff000000 01000000>; + probe-type = "CFI"; + reg = <ff000000 01000000>; bank-width = <4>; partitions = <00000000 00f80000 00f80000 00080001>; diff --git a/Documentation/powerpc/mpc52xx-device-tree-bindings.txt b/Documentation/powerpc/mpc52xx-device-tree-bindings.txt index d077d764f82..69f016f02bb 100644 --- a/Documentation/powerpc/mpc52xx-device-tree-bindings.txt +++ b/Documentation/powerpc/mpc52xx-device-tree-bindings.txt @@ -4,6 +4,12 @@ MPC52xx Device Tree Bindings (c) 2006 Secret Lab Technologies Ltd Grant Likely <grant.likely at secretlab.ca> +********** DRAFT *********** +* WARNING: Do not depend on the stability of these bindings just yet. +* The MPC5200 device tree conventions are still in flux +* Keep an eye on the linuxppc-dev mailing list for more details +********** DRAFT *********** + I - Introduction ================ Boards supported by the arch/powerpc architecture require device tree be @@ -157,8 +163,8 @@ rtc@<addr> rtc *-rtc Real time clock mscan@<addr> mscan *-mscan CAN bus controller pci@<addr> pci *-pci PCI bridge serial@<addr> serial *-psc-uart PSC in serial mode -i2s@<addr> i2s *-psc-i2s PSC in i2s mode -ac97@<addr> ac97 *-psc-ac97 PSC in ac97 mode +i2s@<addr> sound *-psc-i2s PSC in i2s mode +ac97@<addr> sound *-psc-ac97 PSC in ac97 mode spi@<addr> spi *-psc-spi PSC in spi mode irda@<addr> irda *-psc-irda PSC in IrDA mode spi@<addr> spi *-spi MPC52xx spi device diff --git a/Documentation/s390/Debugging390.txt b/Documentation/s390/Debugging390.txt index 3f9ddbc23b2..0993969609c 100644 --- a/Documentation/s390/Debugging390.txt +++ b/Documentation/s390/Debugging390.txt @@ -480,7 +480,7 @@ r2 argument 0 / return value 0 call-clobbered r3 argument 1 / return value 1 (if long long) call-clobbered r4 argument 2 call-clobbered r5 argument 3 call-clobbered -r6 argument 5 saved +r6 argument 4 saved r7 pointer-to arguments 5 to ... saved r8 this & that saved r9 this & that saved diff --git a/Documentation/s390/driver-model.txt b/Documentation/s390/driver-model.txt index 77bf450ec39..e938c442277 100644 --- a/Documentation/s390/driver-model.txt +++ b/Documentation/s390/driver-model.txt @@ -18,11 +18,18 @@ devices/ - 0.0.0002/ - 0.1.0000/0.1.1234/ ... + - defunct/ In this example, device 0815 is accessed via subchannel 0 in subchannel set 0, device 4711 via subchannel 1 in subchannel set 0, and subchannel 2 is a non-I/O subchannel. Device 1234 is accessed via subchannel 0 in subchannel set 1. +The subchannel named 'defunct' does not represent any real subchannel on the +system; it is a pseudo subchannel where disconnnected ccw devices are moved to +if they are displaced by another ccw device becoming operational on their +former subchannel. The ccw devices will be moved again to a proper subchannel +if they become operational again on that subchannel. + You should address a ccw device via its bus id (e.g. 0.0.4711); the device can be found under bus/ccw/devices/. diff --git a/Documentation/scsi/aacraid.txt b/Documentation/scsi/aacraid.txt index 3367130e64f..dc8e44fc650 100644 --- a/Documentation/scsi/aacraid.txt +++ b/Documentation/scsi/aacraid.txt @@ -11,43 +11,42 @@ the original). Supported Cards/Chipsets ------------------------- PCI ID (pci.ids) OEM Product - 9005:0283:9005:0283 Adaptec Catapult (3210S with arc firmware) - 9005:0284:9005:0284 Adaptec Tomcat (3410S with arc firmware) 9005:0285:9005:0285 Adaptec 2200S (Vulcan) 9005:0285:9005:0286 Adaptec 2120S (Crusader) 9005:0285:9005:0287 Adaptec 2200S (Vulcan-2m) 9005:0285:9005:0288 Adaptec 3230S (Harrier) 9005:0285:9005:0289 Adaptec 3240S (Tornado) 9005:0285:9005:028a Adaptec 2020ZCR (Skyhawk) - 9005:0285:9005:028b Adaptec 2025ZCR (Terminator) + 9005:0285:9005:028b Adaptec 2025ZCR (Terminator) 9005:0286:9005:028c Adaptec 2230S (Lancer) 9005:0286:9005:028c Adaptec 2230SLP (Lancer) 9005:0286:9005:028d Adaptec 2130S (Lancer) 9005:0285:9005:028e Adaptec 2020SA (Skyhawk) - 9005:0285:9005:028f Adaptec 2025SA (Terminator) + 9005:0285:9005:028f Adaptec 2025SA (Terminator) 9005:0285:9005:0290 Adaptec 2410SA (Jaguar) - 9005:0285:103c:3227 Adaptec 2610SA (Bearcat HP release) - 9005:0285:9005:0293 Adaptec 21610SA (Corsair-16) + 9005:0285:103c:3227 Adaptec 2610SA (Bearcat HP release) + 9005:0285:9005:0293 Adaptec 21610SA (Corsair-16) 9005:0285:9005:0296 Adaptec 2240S (SabreExpress) 9005:0285:9005:0292 Adaptec 2810SA (Corsair-8) - 9005:0285:9005:0294 Adaptec Prowler - 9005:0285:9005:0297 Adaptec 4005SAS (AvonPark) - 9005:0285:9005:0298 Adaptec 4000SAS (BlackBird) + 9005:0285:9005:0297 Adaptec 4005 (AvonPark) + 9005:0285:9005:0298 Adaptec 4000 (BlackBird) 9005:0285:9005:0299 Adaptec 4800SAS (Marauder-X) 9005:0285:9005:029a Adaptec 4805SAS (Marauder-E) 9005:0286:9005:029b Adaptec 2820SA (Intruder) 9005:0286:9005:029c Adaptec 2620SA (Intruder) 9005:0286:9005:029d Adaptec 2420SA (Intruder HP release) - 9005:0286:9005:02a2 Adaptec 3800SAS (Hurricane44) - 9005:0286:9005:02a7 Adaptec 3805SAS (Hurricane80) - 9005:0286:9005:02a8 Adaptec 3400SAS (Hurricane40) - 9005:0286:9005:02ac Adaptec 1800SAS (Typhoon44) - 9005:0286:9005:02b3 Adaptec 2400SAS (Hurricane40lm) - 9005:0285:9005:02b5 Adaptec ASR5800 (Voodoo44) - 9005:0285:9005:02b6 Adaptec ASR5805 (Voodoo80) - 9005:0285:9005:02b7 Adaptec ASR5808 (Voodoo08) + 9005:0286:9005:02ac Adaptec 1800 (Typhoon44) + 9005:0285:9005:02b5 Adaptec 5445 (Voodoo44) + 9005:0285:9005:02b6 Adaptec 5805 (Voodoo80) + 9005:0285:9005:02b7 Adaptec 5085 (Voodoo08) + 9005:0285:9005:02bb Adaptec 3405 (Marauder40LP) + 9005:0285:9005:02bc Adaptec 3805 (Marauder80LP) + 9005:0285:9005:02c7 Adaptec 3085 (Marauder08ELP) + 9005:0285:9005:02bd Adaptec 31205 (Marauder120) + 9005:0285:9005:02be Adaptec 31605 (Marauder160) + 9005:0285:9005:02c3 Adaptec 51205 (Voodoo120) + 9005:0285:9005:02c4 Adaptec 51605 (Voodoo160) 1011:0046:9005:0364 Adaptec 5400S (Mustang) - 1011:0046:9005:0365 Adaptec 5400S (Mustang) 9005:0287:9005:0800 Adaptec Themisto (Jupiter) 9005:0200:9005:0200 Adaptec Themisto (Jupiter) 9005:0286:9005:0800 Adaptec Callisto (Jupiter) @@ -68,21 +67,32 @@ Supported Cards/Chipsets 9005:0285:17aa:0287 Legend S230 (Vulcan) 9005:0285:9005:0290 IBM ServeRAID 7t (Jaguar) 9005:0285:1014:02F2 IBM ServeRAID 8i (AvonPark) - 9005:0285:1014:0312 IBM ServeRAID 8i (AvonParkLite) 9005:0286:1014:9540 IBM ServeRAID 8k/8k-l4 (AuroraLite) 9005:0286:1014:9580 IBM ServeRAID 8k/8k-l8 (Aurora) - 9005:0286:1014:034d IBM ServeRAID 8s (Hurricane) - 9005:0286:9005:029e ICP ICP9024R0 (Lancer) - 9005:0286:9005:029f ICP ICP9014R0 (Lancer) + 9005:0285:1014:034d IBM ServeRAID 8s (Marauder-E) + 9005:0286:9005:029e ICP ICP9024RO (Lancer) + 9005:0286:9005:029f ICP ICP9014RO (Lancer) 9005:0286:9005:02a0 ICP ICP9047MA (Lancer) 9005:0286:9005:02a1 ICP ICP9087MA (Lancer) - 9005:0286:9005:02a3 ICP ICP5445AU (Hurricane44) - 9005:0286:9005:02a4 ICP ICP9085LI (Marauder-X) - 9005:0286:9005:02a5 ICP ICP5085BR (Marauder-E) + 9005:0285:9005:02a4 ICP ICP9085LI (Marauder-X) + 9005:0285:9005:02a5 ICP ICP5085BR (Marauder-E) 9005:0286:9005:02a6 ICP ICP9067MA (Intruder-6) - 9005:0286:9005:02a9 ICP ICP5085AU (Hurricane80) - 9005:0286:9005:02aa ICP ICP5045AU (Hurricane40) - 9005:0286:9005:02b4 ICP ICP5045AL (Hurricane40lm) + 9005:0285:9005:02b2 ICP (Voodoo 8 internal 8 external) + 9005:0285:9005:02b8 ICP ICP5445SL (Voodoo44) + 9005:0285:9005:02b9 ICP ICP5085SL (Voodoo80) + 9005:0285:9005:02ba ICP ICP5805SL (Voodoo08) + 9005:0285:9005:02bf ICP ICP5045BL (Marauder40LP) + 9005:0285:9005:02c0 ICP ICP5085BL (Marauder80LP) + 9005:0285:9005:02c8 ICP ICP5805BL (Marauder08ELP) + 9005:0285:9005:02c1 ICP ICP5125BR (Marauder120) + 9005:0285:9005:02c2 ICP ICP5165BR (Marauder160) + 9005:0285:9005:02c5 ICP ICP5125SL (Voodoo120) + 9005:0285:9005:02c6 ICP ICP5165SL (Voodoo160) + 9005:0286:9005:02ab (Typhoon40) + 9005:0286:9005:02ad (Aurora ARK) + 9005:0286:9005:02ae (Aurora Lite ARK) + 9005:0285:9005:02b0 (Sunrise Lake ARK) + 9005:0285:9005:02b1 Adaptec (Voodoo 8 internal 8 external) People ------------------------- diff --git a/Documentation/sound/alsa/ALSA-Configuration.txt b/Documentation/sound/alsa/ALSA-Configuration.txt index 9fef210ab50..c30ff1bb2d1 100644 --- a/Documentation/sound/alsa/ALSA-Configuration.txt +++ b/Documentation/sound/alsa/ALSA-Configuration.txt @@ -242,6 +242,12 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. ac97_clock - AC'97 clock (default = 48000) ac97_quirk - AC'97 workaround for strange hardware See "AC97 Quirk Option" section below. + ac97_codec - Workaround to specify which AC'97 codec + instead of probing. If this works for you + file a bug with your `lspci -vn` output. + -2 -- Force probing. + -1 -- Default behavior. + 0-2 -- Use the specified codec. spdif_aclink - S/PDIF transfer over AC-link (default = 1) This module supports one card and autoprobe. @@ -779,6 +785,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. asus-dig ASUS with SPDIF out asus-dig2 ASUS with SPDIF out (using GPIO2) uniwill 3-jack + fujitsu Fujitsu Laptops (Pi1536) F1734 2-jack lg LG laptop (m1 express dual) lg-lw LG LW20/LW25 laptop @@ -800,14 +807,18 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. ALC262 fujitsu Fujitsu Laptop hp-bpc HP xw4400/6400/8400/9400 laptops + hp-bpc-d7000 HP BPC D7000 benq Benq ED8 + hippo Hippo (ATI) with jack detection, Sony UX-90s + hippo_1 Hippo (Benq) with jack detection basic fixed pin assignment w/o SPDIF auto auto-config reading BIOS (default) ALC882/885 3stack-dig 3-jack with SPDIF I/O - 6stck-dig 6-jack digital with SPDIF I/O + 6stack-dig 6-jack digital with SPDIF I/O arima Arima W820Di1 + macpro MacPro support auto auto-config reading BIOS (default) ALC883/888 @@ -817,6 +828,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. 3stack-6ch-dig 3-jack 6-channel with SPDIF I/O 6stack-dig-demo 6-jack digital for Intel demo board acer Acer laptops (Travelmate 3012WTMi, Aspire 5600, etc) + medion Medion Laptops + targa-dig Targa/MSI + targa-2ch-dig Targs/MSI with 2-channel + laptop-eapd 3-jack with SPDIF I/O and EAPD (Clevo M540JE, M550JE) auto auto-config reading BIOS (default) ALC861/660 @@ -825,6 +840,16 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. 6stack-dig 6-jack with SPDIF I/O 3stack-660 3-jack (for ALC660) uniwill-m31 Uniwill M31 laptop + toshiba Toshiba laptop support + asus Asus laptop support + asus-laptop ASUS F2/F3 laptops + auto auto-config reading BIOS (default) + + ALC861VD/660VD + 3stack 3-jack + 3stack-dig 3-jack with SPDIF OUT + 6stack-dig 6-jack with SPDIF OUT + 3stack-660 3-jack (for ALC660VD) auto auto-config reading BIOS (default) CMI9880 @@ -845,6 +870,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. 3stack 3-stack, shared surrounds laptop 2-channel only (FSC V2060, Samsung M50) laptop-eapd 2-channel with EAPD (Samsung R65, ASUS A6J) + ultra 2-channel with EAPD (Samsung Ultra tablet PC) AD1988 6stack 6-jack @@ -854,12 +880,31 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. laptop 3-jack with hp-jack automute laptop-dig ditto with SPDIF auto auto-config reading BIOS (default) + + Conexant 5045 + laptop Laptop config + test for testing/debugging purpose, almost all controls + can be adjusted. Appearing only when compiled with + $CONFIG_SND_DEBUG=y + + Conexant 5047 + laptop Basic Laptop config + laptop-hp Laptop config for some HP models (subdevice 30A5) + laptop-eapd Laptop config with EAPD support + test for testing/debugging purpose, almost all controls + can be adjusted. Appearing only when compiled with + $CONFIG_SND_DEBUG=y STAC9200/9205/9220/9221/9254 ref Reference board 3stack D945 3stack 5stack D945 5stack + SPDIF + STAC9202/9250/9251 + ref Reference board, base config + m2-2 Some Gateway MX series laptops + m6 Some Gateway NX series laptops + STAC9227/9228/9229/927x ref Reference board 3stack D965 3stack @@ -974,6 +1019,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for Envy24HT (VT/ICE1724), Envy24PT (VT1720) based PCI sound cards. * MidiMan M Audio Revolution 5.1 * MidiMan M Audio Revolution 7.1 + * MidiMan M Audio Audiophile 192 * AMP Ltd AUDIO2000 * TerraTec Aureon 5.1 Sky * TerraTec Aureon 7.1 Space @@ -993,7 +1039,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. model - Use the given board model, one of the following: revo51, revo71, amp2000, prodigy71, prodigy71lt, - prodigy192, aureon51, aureon71, universe, + prodigy192, aureon51, aureon71, universe, ap192, k8x800, phase22, phase28, ms300, av710 This module supports multiple cards and autoprobe. @@ -1049,6 +1095,9 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. buggy_semaphore - Enable workaround for hardwares with buggy semaphores (e.g. on some ASUS laptops) (default off) + spdif_aclink - Use S/PDIF over AC-link instead of direct connection + from the controller chip + (0 = off, 1 = on, -1 = default) This module supports one chip and autoprobe. @@ -1371,6 +1420,13 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. This module supports multiple cards. + Module snd-portman2x4 + --------------------- + + Module for Midiman Portman 2x4 parallel port MIDI interface + + This module supports multiple cards. + Module snd-powermac (on ppc only) --------------------------------- diff --git a/Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl b/Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl index 1f3ae3e32d6..c4d2e3507af 100644 --- a/Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl +++ b/Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl @@ -36,7 +36,7 @@ </bookinfo> <chapter><title>Management of Cards and Devices</title> - <sect1><title>Card Managment</title> + <sect1><title>Card Management</title> !Esound/core/init.c </sect1> <sect1><title>Device Components</title> @@ -59,7 +59,7 @@ <sect1><title>PCM Format Helpers</title> !Esound/core/pcm_misc.c </sect1> - <sect1><title>PCM Memory Managment</title> + <sect1><title>PCM Memory Management</title> !Esound/core/pcm_memory.c </sect1> </chapter> diff --git a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl index 077fbe25ebf..74d3a35b59b 100644 --- a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl +++ b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl @@ -927,7 +927,7 @@ <informalexample> <programlisting> <![CDATA[ - struct mychip *chip = (struct mychip *)card->private_data; + struct mychip *chip = card->private_data; ]]> </programlisting> </informalexample> @@ -1095,7 +1095,7 @@ /* release the irq */ if (chip->irq >= 0) - free_irq(chip->irq, (void *)chip); + free_irq(chip->irq, chip); /* release the i/o ports & memory */ pci_release_regions(chip->pci); /* disable the PCI entry */ @@ -1148,7 +1148,7 @@ } chip->port = pci_resource_start(pci, 0); if (request_irq(pci->irq, snd_mychip_interrupt, - IRQF_DISABLED|IRQF_SHARED, "My Chip", chip)) { + IRQF_SHARED, "My Chip", chip)) { printk(KERN_ERR "cannot grab irq %d\n", pci->irq); snd_mychip_free(chip); return -EBUSY; @@ -1360,8 +1360,7 @@ <informalexample> <programlisting> <![CDATA[ - static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id, - struct pt_regs *regs) + static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id) { struct mychip *chip = dev_id; .... @@ -1387,7 +1386,7 @@ <programlisting> <![CDATA[ if (chip->irq >= 0) - free_irq(chip->irq, (void *)chip); + free_irq(chip->irq, chip); ]]> </programlisting> </informalexample> @@ -2127,7 +2126,7 @@ accessible via <constant>substream->runtime</constant>. This runtime pointer holds the various information; it holds the copy of hw_params and sw_params configurations, the buffer - pointers, mmap records, spinlocks, etc. Almost everyhing you + pointers, mmap records, spinlocks, etc. Almost everything you need for controlling the PCM can be found there. </para> @@ -2340,7 +2339,7 @@ struct _snd_pcm_runtime { <para> When the PCM substreams can be synchronized (typically, - synchorinized start/stop of a playback and a capture streams), + synchronized start/stop of a playback and a capture streams), you can give <constant>SNDRV_PCM_INFO_SYNC_START</constant>, too. In this case, you'll need to check the linked-list of PCM substreams in the trigger callback. This will be @@ -3062,8 +3061,7 @@ struct _snd_pcm_runtime { <title>Interrupt Handler Case #1</title> <programlisting> <![CDATA[ - static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id, - struct pt_regs *regs) + static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id) { struct mychip *chip = dev_id; spin_lock(&chip->lock); @@ -3106,8 +3104,7 @@ struct _snd_pcm_runtime { <title>Interrupt Handler Case #2</title> <programlisting> <![CDATA[ - static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id, - struct pt_regs *regs) + static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id) { struct mychip *chip = dev_id; spin_lock(&chip->lock); @@ -3247,7 +3244,7 @@ struct _snd_pcm_runtime { You can even define your own constraint rules. For example, let's suppose my_chip can manage a substream of 1 channel if and only if the format is S16_LE, otherwise it supports any format - specified in the <structname>snd_pcm_hardware</structname> stucture (or in any + specified in the <structname>snd_pcm_hardware</structname> structure (or in any other constraint_list). You can build a rule like this: <example> @@ -3691,16 +3688,6 @@ struct _snd_pcm_runtime { </para> <para> - Here, the chip instance is retrieved via - <function>snd_kcontrol_chip()</function> macro. This macro - just accesses to kcontrol->private_data. The - kcontrol->private_data field is - given as the argument of <function>snd_ctl_new()</function> - (see the later subsection - <link linkend="control-interface-constructor"><citetitle>Constructor</citetitle></link>). - </para> - - <para> The <structfield>value</structfield> field is depending on the type of control as well as on info callback. For example, the sb driver uses this field to store the register offset, @@ -3780,7 +3767,7 @@ struct _snd_pcm_runtime { <para> Like <structfield>get</structfield> callback, when the control has more than one elements, - all elemehts must be evaluated in this callback, too. + all elements must be evaluated in this callback, too. </para> </section> @@ -5541,12 +5528,12 @@ struct _snd_pcm_runtime { #ifdef CONFIG_PM static int snd_my_suspend(struct pci_dev *pci, pm_message_t state) { - .... /* do things for suspsend */ + .... /* do things for suspend */ return 0; } static int snd_my_resume(struct pci_dev *pci) { - .... /* do things for suspsend */ + .... /* do things for suspend */ return 0; } #endif @@ -6111,7 +6098,7 @@ struct _snd_pcm_runtime { <!-- ****************************************************** --> <!-- Acknowledgments --> <!-- ****************************************************** --> - <chapter id="acknowledments"> + <chapter id="acknowledgments"> <title>Acknowledgments</title> <para> I would like to thank Phil Kerr for his help for improvement and diff --git a/Documentation/sound/alsa/hda_codec.txt b/Documentation/sound/alsa/hda_codec.txt index 0be57ed8130..4eaae2a4553 100644 --- a/Documentation/sound/alsa/hda_codec.txt +++ b/Documentation/sound/alsa/hda_codec.txt @@ -277,11 +277,11 @@ Helper Functions snd_hda_get_codec_name() stores the codec name on the given string. snd_hda_check_board_config() can be used to obtain the configuration -information matching with the device. Define the table with struct -hda_board_config entries (zero-terminated), and pass it to the -function. The function checks the modelname given as a module -parameter, and PCI subsystem IDs. If the matching entry is found, it -returns the config field value. +information matching with the device. Define the model string table +and the table with struct snd_pci_quirk entries (zero-terminated), +and pass it to the function. The function checks the modelname given +as a module parameter, and PCI subsystem IDs. If the matching entry +is found, it returns the config field value. snd_hda_add_new_ctls() can be used to create and add control entries. Pass the zero-terminated array of struct snd_kcontrol_new. The same array diff --git a/Documentation/sound/alsa/soc/DAI.txt b/Documentation/sound/alsa/soc/DAI.txt new file mode 100644 index 00000000000..58cbfd01ea8 --- /dev/null +++ b/Documentation/sound/alsa/soc/DAI.txt @@ -0,0 +1,56 @@ +ASoC currently supports the three main Digital Audio Interfaces (DAI) found on +SoC controllers and portable audio CODECS today, namely AC97, I2S and PCM. + + +AC97 +==== + + AC97 is a five wire interface commonly found on many PC sound cards. It is +now also popular in many portable devices. This DAI has a reset line and time +multiplexes its data on its SDATA_OUT (playback) and SDATA_IN (capture) lines. +The bit clock (BCLK) is always driven by the CODEC (usually 12.288MHz) and the +frame (FRAME) (usually 48kHz) is always driven by the controller. Each AC97 +frame is 21uS long and is divided into 13 time slots. + +The AC97 specification can be found at :- +http://www.intel.com/design/chipsets/audio/ac97_r23.pdf + + +I2S +=== + + I2S is a common 4 wire DAI used in HiFi, STB and portable devices. The Tx and +Rx lines are used for audio transmision, whilst the bit clock (BCLK) and +left/right clock (LRC) synchronise the link. I2S is flexible in that either the +controller or CODEC can drive (master) the BCLK and LRC clock lines. Bit clock +usually varies depending on the sample rate and the master system clock +(SYSCLK). LRCLK is the same as the sample rate. A few devices support separate +ADC and DAC LRCLK's, this allows for similtanious capture and playback at +different sample rates. + +I2S has several different operating modes:- + + o I2S - MSB is transmitted on the falling edge of the first BCLK after LRC + transition. + + o Left Justified - MSB is transmitted on transition of LRC. + + o Right Justified - MSB is transmitted sample size BCLK's before LRC + transition. + +PCM +=== + +PCM is another 4 wire interface, very similar to I2S, that can support a more +flexible protocol. It has bit clock (BCLK) and sync (SYNC) lines that are used +to synchronise the link whilst the Tx and Rx lines are used to transmit and +receive the audio data. Bit clock usually varies depending on sample rate +whilst sync runs at the sample rate. PCM also supports Time Division +Multiplexing (TDM) in that several devices can use the bus similtaniuosly (This +is sometimes referred to as network mode). + +Common PCM operating modes:- + + o Mode A - MSB is transmitted on falling edge of first BCLK after FRAME/SYNC. + + o Mode B - MSB is transmitted on rising edge of FRAME/SYNC. diff --git a/Documentation/sound/alsa/soc/clocking.txt b/Documentation/sound/alsa/soc/clocking.txt new file mode 100644 index 00000000000..e93960d53a1 --- /dev/null +++ b/Documentation/sound/alsa/soc/clocking.txt @@ -0,0 +1,51 @@ +Audio Clocking +============== + +This text describes the audio clocking terms in ASoC and digital audio in +general. Note: Audio clocking can be complex ! + + +Master Clock +------------ + +Every audio subsystem is driven by a master clock (sometimes refered to as MCLK +or SYSCLK). This audio master clock can be derived from a number of sources +(e.g. crystal, PLL, CPU clock) and is responsible for producing the correct +audio playback and capture sample rates. + +Some master clocks (e.g. PLL's and CPU based clocks) are configuarble in that +their speed can be altered by software (depending on the system use and to save +power). Other master clocks are fixed at at set frequency (i.e. crystals). + + +DAI Clocks +---------- +The Digital Audio Interface is usually driven by a Bit Clock (often referred to +as BCLK). This clock is used to drive the digital audio data across the link +between the codec and CPU. + +The DAI also has a frame clock to signal the start of each audio frame. This +clock is sometimes referred to as LRC (left right clock) or FRAME. This clock +runs at exactly the sample rate (LRC = Rate). + +Bit Clock can be generated as follows:- + +BCLK = MCLK / x + + or + +BCLK = LRC * x + + or + +BCLK = LRC * Channels * Word Size + +This relationship depends on the codec or SoC CPU in particular. In general +it's best to configure BCLK to the lowest possible speed (depending on your +rate, number of channels and wordsize) to save on power. + +It's also desireable to use the codec (if possible) to drive (or master) the +audio clocks as it's usually gives more accurate sample rates than the CPU. + + + diff --git a/Documentation/sound/alsa/soc/codec.txt b/Documentation/sound/alsa/soc/codec.txt new file mode 100644 index 00000000000..48983c75aad --- /dev/null +++ b/Documentation/sound/alsa/soc/codec.txt @@ -0,0 +1,197 @@ +ASoC Codec Driver +================= + +The codec driver is generic and hardware independent code that configures the +codec to provide audio capture and playback. It should contain no code that is +specific to the target platform or machine. All platform and machine specific +code should be added to the platform and machine drivers respectively. + +Each codec driver *must* provide the following features:- + + 1) Codec DAI and PCM configuration + 2) Codec control IO - using I2C, 3 Wire(SPI) or both API's + 3) Mixers and audio controls + 4) Codec audio operations + +Optionally, codec drivers can also provide:- + + 5) DAPM description. + 6) DAPM event handler. + 7) DAC Digital mute control. + +It's probably best to use this guide in conjuction with the existing codec +driver code in sound/soc/codecs/ + +ASoC Codec driver breakdown +=========================== + +1 - Codec DAI and PCM configuration +----------------------------------- +Each codec driver must have a struct snd_soc_codec_dai to define it's DAI and +PCM's capablities and operations. This struct is exported so that it can be +registered with the core by your machine driver. + +e.g. + +struct snd_soc_codec_dai wm8731_dai = { + .name = "WM8731", + /* playback capabilities */ + .playback = { + .stream_name = "Playback", + .channels_min = 1, + .channels_max = 2, + .rates = WM8731_RATES, + .formats = WM8731_FORMATS,}, + /* capture capabilities */ + .capture = { + .stream_name = "Capture", + .channels_min = 1, + .channels_max = 2, + .rates = WM8731_RATES, + .formats = WM8731_FORMATS,}, + /* pcm operations - see section 4 below */ + .ops = { + .prepare = wm8731_pcm_prepare, + .hw_params = wm8731_hw_params, + .shutdown = wm8731_shutdown, + }, + /* DAI operations - see DAI.txt */ + .dai_ops = { + .digital_mute = wm8731_mute, + .set_sysclk = wm8731_set_dai_sysclk, + .set_fmt = wm8731_set_dai_fmt, + } +}; +EXPORT_SYMBOL_GPL(wm8731_dai); + + +2 - Codec control IO +-------------------- +The codec can ususally be controlled via an I2C or SPI style interface (AC97 +combines control with data in the DAI). The codec drivers will have to provide +functions to read and write the codec registers along with supplying a register +cache:- + + /* IO control data and register cache */ + void *control_data; /* codec control (i2c/3wire) data */ + void *reg_cache; + +Codec read/write should do any data formatting and call the hardware read write +below to perform the IO. These functions are called by the core and alsa when +performing DAPM or changing the mixer:- + + unsigned int (*read)(struct snd_soc_codec *, unsigned int); + int (*write)(struct snd_soc_codec *, unsigned int, unsigned int); + +Codec hardware IO functions - usually points to either the I2C, SPI or AC97 +read/write:- + + hw_write_t hw_write; + hw_read_t hw_read; + + +3 - Mixers and audio controls +----------------------------- +All the codec mixers and audio controls can be defined using the convenience +macros defined in soc.h. + + #define SOC_SINGLE(xname, reg, shift, mask, invert) + +Defines a single control as follows:- + + xname = Control name e.g. "Playback Volume" + reg = codec register + shift = control bit(s) offset in register + mask = control bit size(s) e.g. mask of 7 = 3 bits + invert = the control is inverted + +Other macros include:- + + #define SOC_DOUBLE(xname, reg, shift_left, shift_right, mask, invert) + +A stereo control + + #define SOC_DOUBLE_R(xname, reg_left, reg_right, shift, mask, invert) + +A stereo control spanning 2 registers + + #define SOC_ENUM_SINGLE(xreg, xshift, xmask, xtexts) + +Defines an single enumerated control as follows:- + + xreg = register + xshift = control bit(s) offset in register + xmask = control bit(s) size + xtexts = pointer to array of strings that describe each setting + + #define SOC_ENUM_DOUBLE(xreg, xshift_l, xshift_r, xmask, xtexts) + +Defines a stereo enumerated control + + +4 - Codec Audio Operations +-------------------------- +The codec driver also supports the following alsa operations:- + +/* SoC audio ops */ +struct snd_soc_ops { + int (*startup)(struct snd_pcm_substream *); + void (*shutdown)(struct snd_pcm_substream *); + int (*hw_params)(struct snd_pcm_substream *, struct snd_pcm_hw_params *); + int (*hw_free)(struct snd_pcm_substream *); + int (*prepare)(struct snd_pcm_substream *); +}; + +Please refer to the alsa driver PCM documentation for details. +http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm + + +5 - DAPM description. +--------------------- +The Dynamic Audio Power Management description describes the codec's power +components, their relationships and registers to the ASoC core. Please read +dapm.txt for details of building the description. + +Please also see the examples in other codec drivers. + + +6 - DAPM event handler +---------------------- +This function is a callback that handles codec domain PM calls and system +domain PM calls (e.g. suspend and resume). It's used to put the codec to sleep +when not in use. + +Power states:- + + SNDRV_CTL_POWER_D0: /* full On */ + /* vref/mid, clk and osc on, active */ + + SNDRV_CTL_POWER_D1: /* partial On */ + SNDRV_CTL_POWER_D2: /* partial On */ + + SNDRV_CTL_POWER_D3hot: /* Off, with power */ + /* everything off except vref/vmid, inactive */ + + SNDRV_CTL_POWER_D3cold: /* Everything Off, without power */ + + +7 - Codec DAC digital mute control. +------------------------------------ +Most codecs have a digital mute before the DAC's that can be used to minimise +any system noise. The mute stops any digital data from entering the DAC. + +A callback can be created that is called by the core for each codec DAI when the +mute is applied or freed. + +i.e. + +static int wm8974_mute(struct snd_soc_codec *codec, + struct snd_soc_codec_dai *dai, int mute) +{ + u16 mute_reg = wm8974_read_reg_cache(codec, WM8974_DAC) & 0xffbf; + if(mute) + wm8974_write(codec, WM8974_DAC, mute_reg | 0x40); + else + wm8974_write(codec, WM8974_DAC, mute_reg); + return 0; +} diff --git a/Documentation/sound/alsa/soc/dapm.txt b/Documentation/sound/alsa/soc/dapm.txt new file mode 100644 index 00000000000..c11877f5b4a --- /dev/null +++ b/Documentation/sound/alsa/soc/dapm.txt @@ -0,0 +1,297 @@ +Dynamic Audio Power Management for Portable Devices +=================================================== + +1. Description +============== + +Dynamic Audio Power Management (DAPM) is designed to allow portable Linux devices +to use the minimum amount of power within the audio subsystem at all times. It +is independent of other kernel PM and as such, can easily co-exist with the +other PM systems. + +DAPM is also completely transparent to all user space applications as all power +switching is done within the ASoC core. No code changes or recompiling are +required for user space applications. DAPM makes power switching descisions based +upon any audio stream (capture/playback) activity and audio mixer settings +within the device. + +DAPM spans the whole machine. It covers power control within the entire audio +subsystem, this includes internal codec power blocks and machine level power +systems. + +There are 4 power domains within DAPM + + 1. Codec domain - VREF, VMID (core codec and audio power) + Usually controlled at codec probe/remove and suspend/resume, although + can be set at stream time if power is not needed for sidetone, etc. + + 2. Platform/Machine domain - physically connected inputs and outputs + Is platform/machine and user action specific, is configured by the + machine driver and responds to asynchronous events e.g when HP + are inserted + + 3. Path domain - audio susbsystem signal paths + Automatically set when mixer and mux settings are changed by the user. + e.g. alsamixer, amixer. + + 4. Stream domain - DAC's and ADC's. + Enabled and disabled when stream playback/capture is started and + stopped respectively. e.g. aplay, arecord. + +All DAPM power switching descisons are made automatically by consulting an audio +routing map of the whole machine. This map is specific to each machine and +consists of the interconnections between every audio component (including +internal codec components). All audio components that effect power are called +widgets hereafter. + + +2. DAPM Widgets +=============== + +Audio DAPM widgets fall into a number of types:- + + o Mixer - Mixes several analog signals into a single analog signal. + o Mux - An analog switch that outputs only 1 of it's inputs. + o PGA - A programmable gain amplifier or attenuation widget. + o ADC - Analog to Digital Converter + o DAC - Digital to Analog Converter + o Switch - An analog switch + o Input - A codec input pin + o Output - A codec output pin + o Headphone - Headphone (and optional Jack) + o Mic - Mic (and optional Jack) + o Line - Line Input/Output (and optional Jack) + o Speaker - Speaker + o Pre - Special PRE widget (exec before all others) + o Post - Special POST widget (exec after all others) + +(Widgets are defined in include/sound/soc-dapm.h) + +Widgets are usually added in the codec driver and the machine driver. There are +convience macros defined in soc-dapm.h that can be used to quickly build a +list of widgets of the codecs and machines DAPM widgets. + +Most widgets have a name, register, shift and invert. Some widgets have extra +parameters for stream name and kcontrols. + + +2.1 Stream Domain Widgets +------------------------- + +Stream Widgets relate to the stream power domain and only consist of ADC's +(analog to digital converters) and DAC's (digital to analog converters). + +Stream widgets have the following format:- + +SND_SOC_DAPM_DAC(name, stream name, reg, shift, invert), + +NOTE: the stream name must match the corresponding stream name in your codecs +snd_soc_codec_dai. + +e.g. stream widgets for HiFi playback and capture + +SND_SOC_DAPM_DAC("HiFi DAC", "HiFi Playback", REG, 3, 1), +SND_SOC_DAPM_ADC("HiFi ADC", "HiFi Capture", REG, 2, 1), + + +2.2 Path Domain Widgets +----------------------- + +Path domain widgets have a ability to control or effect the audio signal or +audio paths within the audio subsystem. They have the following form:- + +SND_SOC_DAPM_PGA(name, reg, shift, invert, controls, num_controls) + +Any widget kcontrols can be set using the controls and num_controls members. + +e.g. Mixer widget (the kcontrols are declared first) + +/* Output Mixer */ +static const snd_kcontrol_new_t wm8731_output_mixer_controls[] = { +SOC_DAPM_SINGLE("Line Bypass Switch", WM8731_APANA, 3, 1, 0), +SOC_DAPM_SINGLE("Mic Sidetone Switch", WM8731_APANA, 5, 1, 0), +SOC_DAPM_SINGLE("HiFi Playback Switch", WM8731_APANA, 4, 1, 0), +}; + +SND_SOC_DAPM_MIXER("Output Mixer", WM8731_PWR, 4, 1, wm8731_output_mixer_controls, + ARRAY_SIZE(wm8731_output_mixer_controls)), + + +2.3 Platform/Machine domain Widgets +----------------------------------- + +Machine widgets are different from codec widgets in that they don't have a +codec register bit associated with them. A machine widget is assigned to each +machine audio component (non codec) that can be independently powered. e.g. + + o Speaker Amp + o Microphone Bias + o Jack connectors + +A machine widget can have an optional call back. + +e.g. Jack connector widget for an external Mic that enables Mic Bias +when the Mic is inserted:- + +static int spitz_mic_bias(struct snd_soc_dapm_widget* w, int event) +{ + if(SND_SOC_DAPM_EVENT_ON(event)) + set_scoop_gpio(&spitzscoop2_device.dev, SPITZ_SCP2_MIC_BIAS); + else + reset_scoop_gpio(&spitzscoop2_device.dev, SPITZ_SCP2_MIC_BIAS); + + return 0; +} + +SND_SOC_DAPM_MIC("Mic Jack", spitz_mic_bias), + + +2.4 Codec Domain +---------------- + +The Codec power domain has no widgets and is handled by the codecs DAPM event +handler. This handler is called when the codec powerstate is changed wrt to any +stream event or by kernel PM events. + + +2.5 Virtual Widgets +------------------- + +Sometimes widgets exist in the codec or machine audio map that don't have any +corresponding register bit for power control. In this case it's necessary to +create a virtual widget - a widget with no control bits e.g. + +SND_SOC_DAPM_MIXER("AC97 Mixer", SND_SOC_DAPM_NOPM, 0, 0, NULL, 0), + +This can be used to merge to signal paths together in software. + +After all the widgets have been defined, they can then be added to the DAPM +subsystem individually with a call to snd_soc_dapm_new_control(). + + +3. Codec Widget Interconnections +================================ + +Widgets are connected to each other within the codec and machine by audio +paths (called interconnections). Each interconnection must be defined in order +to create a map of all audio paths between widgets. +This is easiest with a diagram of the codec (and schematic of the machine audio +system), as it requires joining widgets together via their audio signal paths. + +i.e. from the WM8731 codec's output mixer (wm8731.c) + +The WM8731 output mixer has 3 inputs (sources) + + 1. Line Bypass Input + 2. DAC (HiFi playback) + 3. Mic Sidetone Input + +Each input in this example has a kcontrol associated with it (defined in example +above) and is connected to the output mixer via it's kcontrol name. We can now +connect the destination widget (wrt audio signal) with it's source widgets. + + /* output mixer */ + {"Output Mixer", "Line Bypass Switch", "Line Input"}, + {"Output Mixer", "HiFi Playback Switch", "DAC"}, + {"Output Mixer", "Mic Sidetone Switch", "Mic Bias"}, + +So we have :- + + Destination Widget <=== Path Name <=== Source Widget + +Or:- + + Sink, Path, Source + +Or :- + + "Output Mixer" is connected to the "DAC" via the "HiFi Playback Switch". + +When there is no path name connecting widgets (e.g. a direct connection) we +pass NULL for the path name. + +Interconnections are created with a call to:- + +snd_soc_dapm_connect_input(codec, sink, path, source); + +Finally, snd_soc_dapm_new_widgets(codec) must be called after all widgets and +interconnections have been registered with the core. This causes the core to +scan the codec and machine so that the internal DAPM state matches the +physical state of the machine. + + +3.1 Machine Widget Interconnections +----------------------------------- +Machine widget interconnections are created in the same way as codec ones and +directly connect the codec pins to machine level widgets. + +e.g. connects the speaker out codec pins to the internal speaker. + + /* ext speaker connected to codec pins LOUT2, ROUT2 */ + {"Ext Spk", NULL , "ROUT2"}, + {"Ext Spk", NULL , "LOUT2"}, + +This allows the DAPM to power on and off pins that are connected (and in use) +and pins that are NC respectively. + + +4 Endpoint Widgets +=================== +An endpoint is a start or end point (widget) of an audio signal within the +machine and includes the codec. e.g. + + o Headphone Jack + o Internal Speaker + o Internal Mic + o Mic Jack + o Codec Pins + +When a codec pin is NC it can be marked as not used with a call to + +snd_soc_dapm_set_endpoint(codec, "Widget Name", 0); + +The last argument is 0 for inactive and 1 for active. This way the pin and its +input widget will never be powered up and consume power. + +This also applies to machine widgets. e.g. if a headphone is connected to a +jack then the jack can be marked active. If the headphone is removed, then +the headphone jack can be marked inactive. + + +5 DAPM Widget Events +==================== + +Some widgets can register their interest with the DAPM core in PM events. +e.g. A Speaker with an amplifier registers a widget so the amplifier can be +powered only when the spk is in use. + +/* turn speaker amplifier on/off depending on use */ +static int corgi_amp_event(struct snd_soc_dapm_widget *w, int event) +{ + if (SND_SOC_DAPM_EVENT_ON(event)) + set_scoop_gpio(&corgiscoop_device.dev, CORGI_SCP_APM_ON); + else + reset_scoop_gpio(&corgiscoop_device.dev, CORGI_SCP_APM_ON); + + return 0; +} + +/* corgi machine dapm widgets */ +static const struct snd_soc_dapm_widget wm8731_dapm_widgets = + SND_SOC_DAPM_SPK("Ext Spk", corgi_amp_event); + +Please see soc-dapm.h for all other widgets that support events. + + +5.1 Event types +--------------- + +The following event types are supported by event widgets. + +/* dapm event types */ +#define SND_SOC_DAPM_PRE_PMU 0x1 /* before widget power up */ +#define SND_SOC_DAPM_POST_PMU 0x2 /* after widget power up */ +#define SND_SOC_DAPM_PRE_PMD 0x4 /* before widget power down */ +#define SND_SOC_DAPM_POST_PMD 0x8 /* after widget power down */ +#define SND_SOC_DAPM_PRE_REG 0x10 /* before audio path setup */ +#define SND_SOC_DAPM_POST_REG 0x20 /* after audio path setup */ diff --git a/Documentation/sound/alsa/soc/machine.txt b/Documentation/sound/alsa/soc/machine.txt new file mode 100644 index 00000000000..72bd222f2a2 --- /dev/null +++ b/Documentation/sound/alsa/soc/machine.txt @@ -0,0 +1,113 @@ +ASoC Machine Driver +=================== + +The ASoC machine (or board) driver is the code that glues together the platform +and codec drivers. + +The machine driver can contain codec and platform specific code. It registers +the audio subsystem with the kernel as a platform device and is represented by +the following struct:- + +/* SoC machine */ +struct snd_soc_machine { + char *name; + + int (*probe)(struct platform_device *pdev); + int (*remove)(struct platform_device *pdev); + + /* the pre and post PM functions are used to do any PM work before and + * after the codec and DAI's do any PM work. */ + int (*suspend_pre)(struct platform_device *pdev, pm_message_t state); + int (*suspend_post)(struct platform_device *pdev, pm_message_t state); + int (*resume_pre)(struct platform_device *pdev); + int (*resume_post)(struct platform_device *pdev); + + /* machine stream operations */ + struct snd_soc_ops *ops; + + /* CPU <--> Codec DAI links */ + struct snd_soc_dai_link *dai_link; + int num_links; +}; + +probe()/remove() +---------------- +probe/remove are optional. Do any machine specific probe here. + + +suspend()/resume() +------------------ +The machine driver has pre and post versions of suspend and resume to take care +of any machine audio tasks that have to be done before or after the codec, DAI's +and DMA is suspended and resumed. Optional. + + +Machine operations +------------------ +The machine specific audio operations can be set here. Again this is optional. + + +Machine DAI Configuration +------------------------- +The machine DAI configuration glues all the codec and CPU DAI's together. It can +also be used to set up the DAI system clock and for any machine related DAI +initialisation e.g. the machine audio map can be connected to the codec audio +map, unconnnected codec pins can be set as such. Please see corgi.c, spitz.c +for examples. + +struct snd_soc_dai_link is used to set up each DAI in your machine. e.g. + +/* corgi digital audio interface glue - connects codec <--> CPU */ +static struct snd_soc_dai_link corgi_dai = { + .name = "WM8731", + .stream_name = "WM8731", + .cpu_dai = &pxa_i2s_dai, + .codec_dai = &wm8731_dai, + .init = corgi_wm8731_init, + .ops = &corgi_ops, +}; + +struct snd_soc_machine then sets up the machine with it's DAI's. e.g. + +/* corgi audio machine driver */ +static struct snd_soc_machine snd_soc_machine_corgi = { + .name = "Corgi", + .dai_link = &corgi_dai, + .num_links = 1, +}; + + +Machine Audio Subsystem +----------------------- + +The machine soc device glues the platform, machine and codec driver together. +Private data can also be set here. e.g. + +/* corgi audio private data */ +static struct wm8731_setup_data corgi_wm8731_setup = { + .i2c_address = 0x1b, +}; + +/* corgi audio subsystem */ +static struct snd_soc_device corgi_snd_devdata = { + .machine = &snd_soc_machine_corgi, + .platform = &pxa2xx_soc_platform, + .codec_dev = &soc_codec_dev_wm8731, + .codec_data = &corgi_wm8731_setup, +}; + + +Machine Power Map +----------------- + +The machine driver can optionally extend the codec power map and to become an +audio power map of the audio subsystem. This allows for automatic power up/down +of speaker/HP amplifiers, etc. Codec pins can be connected to the machines jack +sockets in the machine init function. See soc/pxa/spitz.c and dapm.txt for +details. + + +Machine Controls +---------------- + +Machine specific audio mixer controls can be added in the dai init function.
\ No newline at end of file diff --git a/Documentation/sound/alsa/soc/overview.txt b/Documentation/sound/alsa/soc/overview.txt new file mode 100644 index 00000000000..753c5cc5984 --- /dev/null +++ b/Documentation/sound/alsa/soc/overview.txt @@ -0,0 +1,83 @@ +ALSA SoC Layer +============== + +The overall project goal of the ALSA System on Chip (ASoC) layer is to provide +better ALSA support for embedded system on chip procesors (e.g. pxa2xx, au1x00, +iMX, etc) and portable audio codecs. Currently there is some support in the +kernel for SoC audio, however it has some limitations:- + + * Currently, codec drivers are often tightly coupled to the underlying SoC + cpu. This is not ideal and leads to code duplication i.e. Linux now has 4 + different wm8731 drivers for 4 different SoC platforms. + + * There is no standard method to signal user initiated audio events. + e.g. Headphone/Mic insertion, Headphone/Mic detection after an insertion + event. These are quite common events on portable devices and ofter require + machine specific code to re route audio, enable amps etc after such an event. + + * Current drivers tend to power up the entire codec when playing + (or recording) audio. This is fine for a PC, but tends to waste a lot of + power on portable devices. There is also no support for saving power via + changing codec oversampling rates, bias currents, etc. + + +ASoC Design +=========== + +The ASoC layer is designed to address these issues and provide the following +features :- + + * Codec independence. Allows reuse of codec drivers on other platforms + and machines. + + * Easy I2S/PCM audio interface setup between codec and SoC. Each SoC interface + and codec registers it's audio interface capabilities with the core and are + subsequently matched and configured when the application hw params are known. + + * Dynamic Audio Power Management (DAPM). DAPM automatically sets the codec to + it's minimum power state at all times. This includes powering up/down + internal power blocks depending on the internal codec audio routing and any + active streams. + + * Pop and click reduction. Pops and clicks can be reduced by powering the + codec up/down in the correct sequence (including using digital mute). ASoC + signals the codec when to change power states. + + * Machine specific controls: Allow machines to add controls to the sound card + e.g. volume control for speaker amp. + +To achieve all this, ASoC basically splits an embedded audio system into 3 +components :- + + * Codec driver: The codec driver is platform independent and contains audio + controls, audio interface capabilities, codec dapm definition and codec IO + functions. + + * Platform driver: The platform driver contains the audio dma engine and audio + interface drivers (e.g. I2S, AC97, PCM) for that platform. + + * Machine driver: The machine driver handles any machine specific controls and + audio events. i.e. turing on an amp at start of playback. + + +Documentation +============= + +The documentation is spilt into the following sections:- + +overview.txt: This file. + +codec.txt: Codec driver internals. + +DAI.txt: Description of Digital Audio Interface standards and how to configure +a DAI within your codec and CPU DAI drivers. + +dapm.txt: Dynamic Audio Power Management + +platform.txt: Platform audio DMA and DAI. + +machine.txt: Machine driver internals. + +pop_clicks.txt: How to minimise audio artifacts. + +clocking.txt: ASoC clocking for best power performance.
\ No newline at end of file diff --git a/Documentation/sound/alsa/soc/platform.txt b/Documentation/sound/alsa/soc/platform.txt new file mode 100644 index 00000000000..e95b16d5a53 --- /dev/null +++ b/Documentation/sound/alsa/soc/platform.txt @@ -0,0 +1,58 @@ +ASoC Platform Driver +==================== + +An ASoC platform driver can be divided into audio DMA and SoC DAI configuration +and control. The platform drivers only target the SoC CPU and must have no board +specific code. + +Audio DMA +========= + +The platform DMA driver optionally supports the following alsa operations:- + +/* SoC audio ops */ +struct snd_soc_ops { + int (*startup)(struct snd_pcm_substream *); + void (*shutdown)(struct snd_pcm_substream *); + int (*hw_params)(struct snd_pcm_substream *, struct snd_pcm_hw_params *); + int (*hw_free)(struct snd_pcm_substream *); + int (*prepare)(struct snd_pcm_substream *); + int (*trigger)(struct snd_pcm_substream *, int); +}; + +The platform driver exports it's DMA functionailty via struct snd_soc_platform:- + +struct snd_soc_platform { + char *name; + + int (*probe)(struct platform_device *pdev); + int (*remove)(struct platform_device *pdev); + int (*suspend)(struct platform_device *pdev, struct snd_soc_cpu_dai *cpu_dai); + int (*resume)(struct platform_device *pdev, struct snd_soc_cpu_dai *cpu_dai); + + /* pcm creation and destruction */ + int (*pcm_new)(struct snd_card *, struct snd_soc_codec_dai *, struct snd_pcm *); + void (*pcm_free)(struct snd_pcm *); + + /* platform stream ops */ + struct snd_pcm_ops *pcm_ops; +}; + +Please refer to the alsa driver documentation for details of audio DMA. +http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm + +An example DMA driver is soc/pxa/pxa2xx-pcm.c + + +SoC DAI Drivers +=============== + +Each SoC DAI driver must provide the following features:- + + 1) Digital audio interface (DAI) description + 2) Digital audio interface configuration + 3) PCM's description + 4) Sysclk configuration + 5) Suspend and resume (optional) + +Please see codec.txt for a description of items 1 - 4. diff --git a/Documentation/sound/alsa/soc/pops_clicks.txt b/Documentation/sound/alsa/soc/pops_clicks.txt new file mode 100644 index 00000000000..2cf7ee5b3d7 --- /dev/null +++ b/Documentation/sound/alsa/soc/pops_clicks.txt @@ -0,0 +1,52 @@ +Audio Pops and Clicks +===================== + +Pops and clicks are unwanted audio artifacts caused by the powering up and down +of components within the audio subsystem. This is noticable on PC's when an +audio module is either loaded or unloaded (at module load time the sound card is +powered up and causes a popping noise on the speakers). + +Pops and clicks can be more frequent on portable systems with DAPM. This is +because the components within the subsystem are being dynamically powered +depending on the audio usage and this can subsequently cause a small pop or +click every time a component power state is changed. + + +Minimising Playback Pops and Clicks +=================================== + +Playback pops in portable audio subsystems cannot be completely eliminated atm, +however future audio codec hardware will have better pop and click supression. +Pops can be reduced within playback by powering the audio components in a +specific order. This order is different for startup and shutdown and follows +some basic rules:- + + Startup Order :- DAC --> Mixers --> Output PGA --> Digital Unmute + + Shutdown Order :- Digital Mute --> Output PGA --> Mixers --> DAC + +This assumes that the codec PCM output path from the DAC is via a mixer and then +a PGA (programmable gain amplifier) before being output to the speakers. + + +Minimising Capture Pops and Clicks +================================== + +Capture artifacts are somewhat easier to get rid as we can delay activating the +ADC until all the pops have occured. This follows similar power rules to +playback in that components are powered in a sequence depending upon stream +startup or shutdown. + + Startup Order - Input PGA --> Mixers --> ADC + + Shutdown Order - ADC --> Mixers --> Input PGA + + +Zipper Noise +============ +An unwanted zipper noise can occur within the audio playback or capture stream +when a volume control is changed near its maximum gain value. The zipper noise +is heard when the gain increase or decrease changes the mean audio signal +amplitude too quickly. It can be minimised by enabling the zero cross setting +for each volume control. The ZC forces the gain change to occur when the signal +crosses the zero amplitude line. diff --git a/Documentation/spi/pxa2xx b/Documentation/spi/pxa2xx index a1e0ee20f59..f9717fe9bd8 100644 --- a/Documentation/spi/pxa2xx +++ b/Documentation/spi/pxa2xx @@ -102,7 +102,7 @@ struct pxa2xx_spi_chip { u8 tx_threshold; u8 rx_threshold; u8 dma_burst_size; - u32 timeout_microsecs; + u32 timeout; u8 enable_loopback; void (*cs_control)(u32 command); }; @@ -121,7 +121,7 @@ the PXA2xx "Developer Manual" sections on the DMA controller and SSP Controllers to determine the correct value. An SSP configured for byte-wide transfers would use a value of 8. -The "pxa2xx_spi_chip.timeout_microsecs" fields is used to efficiently handle +The "pxa2xx_spi_chip.timeout" fields is used to efficiently handle trailing bytes in the SSP receiver fifo. The correct value for this field is dependent on the SPI bus speed ("spi_board_info.max_speed_hz") and the specific slave device. Please note that the PXA2xx SSP 1 does not support trailing byte @@ -162,18 +162,18 @@ static void cs8405a_cs_control(u32 command) } static struct pxa2xx_spi_chip cs8415a_chip_info = { - .tx_threshold = 12, /* SSP hardward FIFO threshold */ - .rx_threshold = 4, /* SSP hardward FIFO threshold */ + .tx_threshold = 8, /* SSP hardward FIFO threshold */ + .rx_threshold = 8, /* SSP hardward FIFO threshold */ .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */ - .timeout_microsecs = 64, /* Wait at least 64usec to handle trailing */ + .timeout = 235, /* See Intel documentation */ .cs_control = cs8415a_cs_control, /* Use external chip select */ }; static struct pxa2xx_spi_chip cs8405a_chip_info = { - .tx_threshold = 12, /* SSP hardward FIFO threshold */ - .rx_threshold = 4, /* SSP hardward FIFO threshold */ + .tx_threshold = 8, /* SSP hardward FIFO threshold */ + .rx_threshold = 8, /* SSP hardward FIFO threshold */ .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */ - .timeout_microsecs = 64, /* Wait at least 64usec to handle trailing */ + .timeout = 235, /* See Intel documentation */ .cs_control = cs8405a_cs_control, /* Use external chip select */ }; diff --git a/Documentation/sysrq.txt b/Documentation/sysrq.txt index e0188a23fd5..61613166981 100644 --- a/Documentation/sysrq.txt +++ b/Documentation/sysrq.txt @@ -1,6 +1,6 @@ Linux Magic System Request Key Hacks -Documentation for sysrq.c version 1.15 -Last update: $Date: 2001/01/28 10:15:59 $ +Documentation for sysrq.c +Last update: 2007-JAN-06 * What is the magic SysRq key? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -35,7 +35,7 @@ You can set the value in the file by the following command: Note that the value of /proc/sys/kernel/sysrq influences only the invocation via a keyboard. Invocation of any operation via /proc/sysrq-trigger is always -allowed. +allowed (by a user with admin privileges). * How do I use the magic SysRq key? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -58,7 +58,7 @@ On PowerPC - Press 'ALT - Print Screen (or F13) - <command key>, On other - If you know of the key combos for other architectures, please let me know so I can add them to this section. -On all - write a character to /proc/sysrq-trigger. eg: +On all - write a character to /proc/sysrq-trigger. e.g.: echo t > /proc/sysrq-trigger @@ -74,6 +74,8 @@ On all - write a character to /proc/sysrq-trigger. eg: 'c' - Will perform a kexec reboot in order to take a crashdump. +'d' - Shows all locks that are held. + 'o' - Will shut your system off (if configured and supported). 's' - Will attempt to sync all mounted filesystems. @@ -87,38 +89,43 @@ On all - write a character to /proc/sysrq-trigger. eg: 'm' - Will dump current memory info to your console. +'n' - Used to make RT tasks nice-able + 'v' - Dumps Voyager SMP processor info to your console. +'w' - Dumps tasks that are in uninterruptable (blocked) state. + +'x' - Used by xmon interface on ppc/powerpc platforms. + '0'-'9' - Sets the console log level, controlling which kernel messages will be printed to your console. ('0', for example would make it so that only emergency messages like PANICs or OOPSes would make it to your console.) -'f' - Will call oom_kill to kill a memory hog process +'f' - Will call oom_kill to kill a memory hog process. 'e' - Send a SIGTERM to all processes, except for init. -'i' - Send a SIGKILL to all processes, except for init. +'g' - Used by kgdb on ppc platforms. -'l' - Send a SIGKILL to all processes, INCLUDING init. (Your system - will be non-functional after this.) +'i' - Send a SIGKILL to all processes, except for init. -'h' - Will display help ( actually any other key than those listed +'h' - Will display help (actually any other key than those listed above will display help. but 'h' is easy to remember :-) * Okay, so what can I use them for? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Well, un'R'aw is very handy when your X server or a svgalib program crashes. -sa'K' (Secure Access Key) is useful when you want to be sure there are no -trojan program is running at console and which could grab your password -when you would try to login. It will kill all programs on given console -and thus letting you make sure that the login prompt you see is actually +sa'K' (Secure Access Key) is useful when you want to be sure there is no +trojan program running at console which could grab your password +when you would try to login. It will kill all programs on given console, +thus letting you make sure that the login prompt you see is actually the one from init, not some trojan program. IMPORTANT: In its true form it is not a true SAK like the one in a :IMPORTANT IMPORTANT: c2 compliant system, and it should not be mistaken as :IMPORTANT IMPORTANT: such. :IMPORTANT - It seems other find it useful as (System Attention Key) which is + It seems others find it useful as (System Attention Key) which is useful when you want to exit a program that will not let you switch consoles. (For example, X or a svgalib program.) @@ -139,8 +146,8 @@ OK or Done message...) Again, the unmount (remount read-only) hasn't taken place until you see the "OK" and "Done" message appear on the screen. -The loglevel'0'-'9' is useful when your console is being flooded with -kernel messages you do not want to see. Setting '0' will prevent all but +The loglevels '0'-'9' are useful when your console is being flooded with +kernel messages you do not want to see. Selecting '0' will prevent all but the most urgent kernel messages from reaching your console. (They will still be logged if syslogd/klogd are alive, though.) @@ -152,7 +159,7 @@ processes. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ That happens to me, also. I've found that tapping shift, alt, and control on both sides of the keyboard, and hitting an invalid sysrq sequence again -will fix the problem. (ie, something like alt-sysrq-z). Switching to another +will fix the problem. (i.e., something like alt-sysrq-z). Switching to another virtual console (ALT+Fn) and then back again should also help. * I hit SysRq, but nothing seems to happen, what's wrong? @@ -174,11 +181,11 @@ handler function you will use, B) a help_msg string, that will print when SysRQ prints help, and C) an action_msg string, that will print right before your handler is called. Your handler must conform to the prototype in 'sysrq.h'. -After the sysrq_key_op is created, you can call the macro -register_sysrq_key(int key, struct sysrq_key_op *op_p) that is defined in -sysrq.h, this will register the operation pointed to by 'op_p' at table -key 'key', if that slot in the table is blank. At module unload time, you must -call the macro unregister_sysrq_key(int key, struct sysrq_key_op *op_p), which +After the sysrq_key_op is created, you can call the kernel function +register_sysrq_key(int key, struct sysrq_key_op *op_p); this will +register the operation pointed to by 'op_p' at table key 'key', +if that slot in the table is blank. At module unload time, you must call +the function unregister_sysrq_key(int key, struct sysrq_key_op *op_p), which will remove the key op pointed to by 'op_p' from the key 'key', if and only if it is currently registered in that slot. This is in case the slot has been overwritten since you registered it. @@ -186,15 +193,12 @@ overwritten since you registered it. The Magic SysRQ system works by registering key operations against a key op lookup table, which is defined in 'drivers/char/sysrq.c'. This key table has a number of operations registered into it at compile time, but is mutable, -and 4 functions are exported for interface to it: __sysrq_lock_table, -__sysrq_unlock_table, __sysrq_get_key_op, and __sysrq_put_key_op. The -functions __sysrq_swap_key_ops and __sysrq_swap_key_ops_nolock are defined -in the header itself, and the REGISTER and UNREGISTER macros are built from -these. More complex (and dangerous!) manipulations of the table are possible -using these functions, but you must be careful to always lock the table before -you read or write from it, and to unlock it again when you are done. (And of -course, to never ever leave an invalid pointer in the table). Null pointers in -the table are always safe :) +and 2 functions are exported for interface to it: + register_sysrq_key and unregister_sysrq_key. +Of course, never ever leave an invalid pointer in the table. I.e., when +your module that called register_sysrq_key() exits, it must call +unregister_sysrq_key() to clean up the sysrq key table entry that it used. +Null pointers in the table are always safe. :) If for some reason you feel the need to call the handle_sysrq function from within a function called by handle_sysrq, you must be aware that you are in diff --git a/Documentation/tty.txt b/Documentation/tty.txt index dab56604745..5f799e612e0 100644 --- a/Documentation/tty.txt +++ b/Documentation/tty.txt @@ -39,28 +39,37 @@ Line Discipline Methods TTY side interfaces: +open() - Called when the line discipline is attached to + the terminal. No other call into the line + discipline for this tty will occur until it + completes successfully. Can sleep. + close() - This is called on a terminal when the line discipline is being unplugged. At the point of execution no further users will enter the ldisc code for this tty. Can sleep. -open() - Called when the line discipline is attached to - the terminal. No other call into the line - discipline for this tty will occur until it - completes successfully. Can sleep. +hangup() - Called when the tty line is hung up. + The line discipline should cease I/O to the tty. + No further calls into the ldisc code will occur. + Can sleep. write() - A process is writing data through the line discipline. Multiple write calls are serialized by the tty layer for the ldisc. May sleep. -flush_buffer() - May be called at any point between open and close. +flush_buffer() - (optional) May be called at any point between + open and close, and instructs the line discipline + to empty its input buffer. -chars_in_buffer() - Report the number of bytes in the buffer. +chars_in_buffer() - (optional) Report the number of bytes in the input + buffer. -set_termios() - Called on termios structure changes. The caller - passes the old termios data and the current data - is in the tty. Called under the termios semaphore so - allowed to sleep. Serialized against itself only. +set_termios() - (optional) Called on termios structure changes. + The caller passes the old termios data and the + current data is in the tty. Called under the + termios semaphore so allowed to sleep. Serialized + against itself only. read() - Move data from the line discipline to the user. Multiple read calls may occur in parallel and the @@ -92,6 +101,88 @@ write_wakeup() - May be called at any point between open and close. this function. In such a situation defer it. +Driver Access + +Line discipline methods can call the following methods of the underlying +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. + +put_char() Queues a character for writing to the tty device. + If there is no room in the queue, the character is + ignored. + +flush_chars() (Optional) If defined, must be called after + queueing characters with put_char() in order to + start transmission. + +write_room() Returns the numbers of characters the tty driver + will accept for queueing to be written. + +ioctl() Invoke device specific ioctl. + Expects data pointers to refer to userspace. + Returns ENOIOCTLCMD for unrecognized ioctl numbers. + +set_termios() Notify the tty driver that the device's termios + settings have changed. New settings are in + tty->termios. Previous settings should be passed in + the "old" argument. + +throttle() Notify the tty driver that input buffers for the + line discipline are close to full, and it should + somehow signal that no more characters should be + sent to the tty. + +unthrottle() Notify the tty driver that characters can now be + sent to the tty without fear of overrunning the + input buffers of the line disciplines. + +stop() Ask the tty driver to stop outputting characters + to the tty device. + +start() Ask the tty driver to resume sending characters + to the tty device. + +hangup() Ask the tty driver to hang up the tty device. + +break_ctl() (Optional) Ask the tty driver to turn on or off + BREAK status on the RS-232 port. If state is -1, + then the BREAK status should be turned on; if + state is 0, then BREAK should be turned off. + If this routine is not implemented, use ioctls + TIOCSBRK / TIOCCBRK instead. + +wait_until_sent() Waits until the device has written out all of the + characters in its transmitter FIFO. + +send_xchar() Send a high-priority XON/XOFF character to the device. + + +Flags + +Line discipline methods have access to tty->flags field containing the +following interesting flags: + +TTY_THROTTLED Driver input is throttled. The ldisc should call + tty->driver->unthrottle() in order to resume + reception when it is ready to process more data. + +TTY_DO_WRITE_WAKEUP If set, causes the driver to call the ldisc's + write_wakeup() method in order to resume + transmission when it can accept more data + to transmit. + +TTY_IO_ERROR If set, causes all subsequent userspace read/write + calls on the tty to fail, returning -EIO. + +TTY_OTHER_CLOSED Device is a pty and the other side has closed. + +TTY_NO_WRITE_SPLIT Prevent driver from splitting up writes into + smaller chunks. + + Locking Callers to the line discipline functions from the tty layer are required to diff --git a/Documentation/usb/CREDITS b/Documentation/usb/CREDITS index 01e7f857ef3..27a721635f9 100644 --- a/Documentation/usb/CREDITS +++ b/Documentation/usb/CREDITS @@ -21,7 +21,7 @@ difficult to maintain, add yourself with a patch if desired. Bill Ryder <bryder@sgi.com> Thomas Sailer <sailer@ife.ee.ethz.ch> Gregory P. Smith <greg@electricrain.com> - Linus Torvalds <torvalds@osdl.org> + Linus Torvalds <torvalds@linux-foundation.org> Roman Weissgaerber <weissg@vienna.at> <Kazuki.Yasumatsu@fujixerox.co.jp> diff --git a/Documentation/usb/acm.txt b/Documentation/usb/acm.txt index 737d6104c3f..17f5c2e1a57 100644 --- a/Documentation/usb/acm.txt +++ b/Documentation/usb/acm.txt @@ -46,6 +46,10 @@ Abstract Control Model (USB CDC ACM) specification. 3Com USR ISDN Pro TA + Some cell phones also connect via USB. I know the following phones work: + + SonyEricsson K800i + Unfortunately many modems and most ISDN TAs use proprietary interfaces and thus won't work with this drivers. Check for ACM compliance before buying. diff --git a/Documentation/usb/proc_usb_info.txt b/Documentation/usb/proc_usb_info.txt index 22c5331260c..077e9032d0c 100644 --- a/Documentation/usb/proc_usb_info.txt +++ b/Documentation/usb/proc_usb_info.txt @@ -213,15 +213,16 @@ C:* #Ifs=dd Cfg#=dd Atr=xx MPwr=dddmA Interface descriptor info (can be multiple per Config): -I: If#=dd Alt=dd #EPs=dd Cls=xx(sssss) Sub=xx Prot=xx Driver=ssss -| | | | | | | |__Driver name -| | | | | | | or "(none)" -| | | | | | |__InterfaceProtocol -| | | | | |__InterfaceSubClass -| | | | |__InterfaceClass -| | | |__NumberOfEndpoints -| | |__AlternateSettingNumber -| |__InterfaceNumber +I:* If#=dd Alt=dd #EPs=dd Cls=xx(sssss) Sub=xx Prot=xx Driver=ssss +| | | | | | | | |__Driver name +| | | | | | | | or "(none)" +| | | | | | | |__InterfaceProtocol +| | | | | | |__InterfaceSubClass +| | | | | |__InterfaceClass +| | | | |__NumberOfEndpoints +| | | |__AlternateSettingNumber +| | |__InterfaceNumber +| |__ "*" indicates the active altsetting (others are " ") |__Interface info tag A given interface may have one or more "alternate" settings. @@ -277,7 +278,7 @@ of the USB devices on a system's root hub. (See more below on how to do this.) The Interface lines can be used to determine what driver is -being used for each device. +being used for each device, and which altsetting it activated. The Configuration lines could be used to list maximum power (in milliamps) that a system's USB devices are using. diff --git a/Documentation/usb/usbmon.txt b/Documentation/usb/usbmon.txt index e65ec828d7a..0f6808abd61 100644 --- a/Documentation/usb/usbmon.txt +++ b/Documentation/usb/usbmon.txt @@ -77,7 +77,7 @@ that the file size is not excessive for your favourite editor. The '1t' type data consists of a stream of events, such as URB submission, URB callback, submission error. Every event is a text line, which consists -of whitespace separated words. The number of position of words may depend +of whitespace separated words. The number or position of words may depend on the event type, but there is a set of words, common for all types. Here is the list of words, from left to right: @@ -170,4 +170,152 @@ dd65f0e8 4128379808 C Bo:005:02 0 31 > * Raw binary format and API -TBD +The overall architecture of the API is about the same as the one above, +only the events are delivered in binary format. Each event is sent in +the following structure (its name is made up, so that we can refer to it): + +struct usbmon_packet { + u64 id; /* 0: URB ID - from submission to callback */ + unsigned char type; /* 8: Same as text; extensible. */ + unsigned char xfer_type; /* ISO (0), Intr, Control, Bulk (3) */ + unsigned char epnum; /* Endpoint number and transfer direction */ + unsigned char devnum; /* Device address */ + u16 busnum; /* 12: Bus number */ + char flag_setup; /* 14: Same as text */ + char flag_data; /* 15: Same as text; Binary zero is OK. */ + s64 ts_sec; /* 16: gettimeofday */ + s32 ts_usec; /* 24: gettimeofday */ + int status; /* 28: */ + unsigned int length; /* 32: Length of data (submitted or actual) */ + unsigned int len_cap; /* 36: Delivered length */ + unsigned char setup[8]; /* 40: Only for Control 'S' */ +}; /* 48 bytes total */ + +These events can be received from a character device by reading with read(2), +with an ioctl(2), or by accessing the buffer with mmap. + +The character device is usually called /dev/usbmonN, where N is the USB bus +number. Number zero (/dev/usbmon0) is special and means "all buses". +However, this feature is not implemented yet. Note that specific naming +policy is set by your Linux distribution. + +If you create /dev/usbmon0 by hand, make sure that it is owned by root +and has mode 0600. Otherwise, unpriviledged users will be able to snoop +keyboard traffic. + +The following ioctl calls are available, with MON_IOC_MAGIC 0x92: + + MON_IOCQ_URB_LEN, defined as _IO(MON_IOC_MAGIC, 1) + +This call returns the length of data in the next event. Note that majority of +events contain no data, so if this call returns zero, it does not mean that +no events are available. + + MON_IOCG_STATS, defined as _IOR(MON_IOC_MAGIC, 3, struct mon_bin_stats) + +The argument is a pointer to the following structure: + +struct mon_bin_stats { + u32 queued; + u32 dropped; +}; + +The member "queued" refers to the number of events currently queued in the +buffer (and not to the number of events processed since the last reset). + +The member "dropped" is the number of events lost since the last call +to MON_IOCG_STATS. + + MON_IOCT_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 4) + +This call sets the buffer size. The argument is the size in bytes. +The size may be rounded down to the next chunk (or page). If the requested +size is out of [unspecified] bounds for this kernel, the call fails with +-EINVAL. + + MON_IOCQ_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 5) + +This call returns the current size of the buffer in bytes. + + MON_IOCX_GET, defined as _IOW(MON_IOC_MAGIC, 6, struct mon_get_arg) + +This call waits for events to arrive if none were in the kernel buffer, +then returns the first event. Its argument is a pointer to the following +structure: + +struct mon_get_arg { + struct usbmon_packet *hdr; + void *data; + size_t alloc; /* Length of data (can be zero) */ +}; + +Before the call, hdr, data, and alloc should be filled. Upon return, the area +pointed by hdr contains the next event structure, and the data buffer contains +the data, if any. The event is removed from the kernel buffer. + + MON_IOCX_MFETCH, defined as _IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg) + +This ioctl is primarily used when the application accesses the buffer +with mmap(2). Its argument is a pointer to the following structure: + +struct mon_mfetch_arg { + uint32_t *offvec; /* Vector of events fetched */ + uint32_t nfetch; /* Number of events to fetch (out: fetched) */ + uint32_t nflush; /* Number of events to flush */ +}; + +The ioctl operates in 3 stages. + +First, it removes and discards up to nflush events from the kernel buffer. +The actual number of events discarded is returned in nflush. + +Second, it waits for an event to be present in the buffer, unless the pseudo- +device is open with O_NONBLOCK. + +Third, it extracts up to nfetch offsets into the mmap buffer, and stores +them into the offvec. The actual number of event offsets is stored into +the nfetch. + + MON_IOCH_MFLUSH, defined as _IO(MON_IOC_MAGIC, 8) + +This call removes a number of events from the kernel buffer. Its argument +is the number of events to remove. If the buffer contains fewer events +than requested, all events present are removed, and no error is reported. +This works when no events are available too. + + FIONBIO + +The ioctl FIONBIO may be implemented in the future, if there's a need. + +In addition to ioctl(2) and read(2), the special file of binary API can +be polled with select(2) and poll(2). But lseek(2) does not work. + +* Memory-mapped access of the kernel buffer for the binary API + +The basic idea is simple: + +To prepare, map the buffer by getting the current size, then using mmap(2). +Then, execute a loop similar to the one written in pseudo-code below: + + struct mon_mfetch_arg fetch; + struct usbmon_packet *hdr; + int nflush = 0; + for (;;) { + fetch.offvec = vec; // Has N 32-bit words + fetch.nfetch = N; // Or less than N + fetch.nflush = nflush; + ioctl(fd, MON_IOCX_MFETCH, &fetch); // Process errors, too + nflush = fetch.nfetch; // This many packets to flush when done + for (i = 0; i < nflush; i++) { + hdr = (struct ubsmon_packet *) &mmap_area[vec[i]]; + if (hdr->type == '@') // Filler packet + continue; + caddr_t data = &mmap_area[vec[i]] + 64; + process_packet(hdr, data); + } + } + +Thus, the main idea is to execute only one ioctl per N events. + +Although the buffer is circular, the returned headers and data do not cross +the end of the buffer, so the above pseudo-code does not need any gathering. diff --git a/Documentation/video-output.txt b/Documentation/video-output.txt new file mode 100644 index 00000000000..e517011be4f --- /dev/null +++ b/Documentation/video-output.txt @@ -0,0 +1,34 @@ + + Video Output Switcher Control + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + 2006 luming.yu@intel.com + +The output sysfs class driver provides an abstract video output layer that +can be used to hook platform specific methods to enable/disable video output +device through common sysfs interface. For example, on my IBM ThinkPad T42 +laptop, The ACPI video driver registered its output devices and read/write +method for 'state' with output sysfs class. The user interface under sysfs is: + +linux:/sys/class/video_output # tree . +. +|-- CRT0 +| |-- device -> ../../../devices/pci0000:00/0000:00:01.0 +| |-- state +| |-- subsystem -> ../../../class/video_output +| `-- uevent +|-- DVI0 +| |-- device -> ../../../devices/pci0000:00/0000:00:01.0 +| |-- state +| |-- subsystem -> ../../../class/video_output +| `-- uevent +|-- LCD0 +| |-- device -> ../../../devices/pci0000:00/0000:00:01.0 +| |-- state +| |-- subsystem -> ../../../class/video_output +| `-- uevent +`-- TV0 + |-- device -> ../../../devices/pci0000:00/0000:00:01.0 + |-- state + |-- subsystem -> ../../../class/video_output + `-- uevent + diff --git a/Documentation/video4linux/CARDLIST.cx88 b/Documentation/video4linux/CARDLIST.cx88 index 8755b3e7b09..62e32b49cec 100644 --- a/Documentation/video4linux/CARDLIST.cx88 +++ b/Documentation/video4linux/CARDLIST.cx88 @@ -43,7 +43,7 @@ 42 -> digitalnow DNTV Live! DVB-T Pro [1822:0025,1822:0019] 43 -> KWorld/VStream XPert DVB-T with cx22702 [17de:08a1,12ab:2300] 44 -> DViCO FusionHDTV DVB-T Dual Digital [18ac:db50,18ac:db54] - 45 -> KWorld HardwareMpegTV XPert [17de:0840] + 45 -> KWorld HardwareMpegTV XPert [17de:0840,1421:0305] 46 -> DViCO FusionHDTV DVB-T Hybrid [18ac:db40,18ac:db44] 47 -> pcHDTV HD5500 HDTV [7063:5500] 48 -> Kworld MCE 200 Deluxe [17de:0841] diff --git a/Documentation/video4linux/CARDLIST.saa7134 b/Documentation/video4linux/CARDLIST.saa7134 index 53ce6a39083..f6201cc37ec 100644 --- a/Documentation/video4linux/CARDLIST.saa7134 +++ b/Documentation/video4linux/CARDLIST.saa7134 @@ -76,7 +76,7 @@ 75 -> AVerMedia AVerTVHD MCE A180 [1461:1044] 76 -> SKNet MonsterTV Mobile [1131:4ee9] 77 -> Pinnacle PCTV 40i/50i/110i (saa7133) [11bd:002e] - 78 -> ASUSTeK P7131 Dual [1043:4862] + 78 -> ASUSTeK P7131 Dual [1043:4862,1043:4876] 79 -> Sedna/MuchTV PC TV Cardbus TV/Radio (ITO25 Rev:2B) 80 -> ASUS Digimatrix TV [1043:0210] 81 -> Philips Tiger reference design [1131:2018] @@ -99,3 +99,8 @@ 98 -> Proteus Pro 2309 [0919:2003] 99 -> AVerMedia TV Hybrid A16AR [1461:2c00] 100 -> Asus Europa2 OEM [1043:4860] +101 -> Pinnacle PCTV 310i [11bd:002f] +102 -> Avermedia AVerTV Studio 507 [1461:9715] +103 -> Compro Videomate DVB-T200A +104 -> Hauppauge WinTV-HVR1110 DVB-T/Hybrid [0070:6701] +105 -> Terratec Cinergy HT PCMCIA [153b:1172] diff --git a/Documentation/video4linux/cafe_ccic b/Documentation/video4linux/cafe_ccic new file mode 100644 index 00000000000..88821022a5d --- /dev/null +++ b/Documentation/video4linux/cafe_ccic @@ -0,0 +1,54 @@ +"cafe_ccic" is a driver for the Marvell 88ALP01 "cafe" CMOS camera +controller. This is the controller found in first-generation OLPC systems, +and this driver was written with support from the OLPC project. + +Current status: the core driver works. It can generate data in YUV422, +RGB565, and RGB444 formats. (Anybody looking at the code will see RGB32 as +well, but that is a debugging aid which will be removed shortly). VGA and +QVGA modes work; CIF is there but the colors remain funky. Only the OV7670 +sensor is known to work with this controller at this time. + +To try it out: either of these commands will work: + + mplayer tv:// -tv driver=v4l2:width=640:height=480 -nosound + mplayer tv:// -tv driver=v4l2:width=640:height=480:outfmt=bgr16 -nosound + +The "xawtv" utility also works; gqcam does not, for unknown reasons. + +There are a few load-time options, most of which can be changed after +loading via sysfs as well: + + - alloc_bufs_at_load: Normally, the driver will not allocate any DMA + buffers until the time comes to transfer data. If this option is set, + then worst-case-sized buffers will be allocated at module load time. + This option nails down the memory for the life of the module, but + perhaps decreases the chances of an allocation failure later on. + + - dma_buf_size: The size of DMA buffers to allocate. Note that this + option is only consulted for load-time allocation; when buffers are + allocated at run time, they will be sized appropriately for the current + camera settings. + + - n_dma_bufs: The controller can cycle through either two or three DMA + buffers. Normally, the driver tries to use three buffers; on faster + systems, however, it will work well with only two. + + - min_buffers: The minimum number of streaming I/O buffers that the driver + will consent to work with. Default is one, but, on slower systems, + better behavior with mplayer can be achieved by setting to a higher + value (like six). + + - max_buffers: The maximum number of streaming I/O buffers; default is + ten. That number was carefully picked out of a hat and should not be + assumed to actually mean much of anything. + + - flip: If this boolean parameter is set, the sensor will be instructed to + invert the video image. Whether it makes sense is determined by how + your particular camera is mounted. + +Work is ongoing with this driver, stay tuned. + +jon + +Jonathan Corbet +corbet@lwn.net diff --git a/Documentation/video4linux/zr36120.txt b/Documentation/video4linux/zr36120.txt deleted file mode 100644 index 1a1c2d03a5c..00000000000 --- a/Documentation/video4linux/zr36120.txt +++ /dev/null @@ -1,162 +0,0 @@ -Driver for Trust Computer Products Framegrabber, version 0.6.1 ------- --- ----- -------- -------- ------------ ------- - - - - -- ZORAN ------------------------------------------------------ - Author: Pauline Middelink <middelin@polyware.nl> - Date: 18 September 1999 -Version: 0.6.1 - -- Description ------------------------------------------------ - -Video4Linux compatible driver for an unknown brand framegrabber -(Sold in the Netherlands by TRUST Computer Products) and various -other zoran zr36120 based framegrabbers. - -The card contains a ZR36120 Multimedia PCI Interface and a Philips -SAA7110 Onechip Frontend videodecoder. There is also an DSP of -which I have forgotten the number, since i will never get that thing -to work without specs from the vendor itself. - -The SAA711x are capable of processing 6 different video inputs, -CVBS1..6 and Y1+C1, Y2+C2, Y3+C3. All in 50/60Hz, NTSC, PAL or -SECAM and delivering a YUV datastream. On my card the input -'CVBS-0' corresponds to channel CVBS2 and 'S-Video' to Y2+C2. - -I have some reports of other cards working with the mentioned -chip sets. For a list of other working cards please have a look -at the cards named in the tvcards struct in the beginning of -zr36120.c - -After some testing, I discovered that the carddesigner messed up -on the I2C interface. The Zoran chip includes 2 lines SDA and SCL -which (s)he connected reversely. So we have to clock on the SDA -and r/w data on the SCL pin. Life is fun... Each cardtype now has -a bit which signifies if you have a card with the same deficiency. - -Oh, for the completeness of this story I must mention that my -card delivers the VSYNC pulse of the SAA chip to GIRQ1, not -GIRQ0 as some other cards have. This is also incorporated in -the driver be clearing/setting the 'useirq1' bit in the tvcard -description. - -Another problems of continuous capturing data with a Zoran chip -is something nasty inside the chip. It effectively halves the -fps we ought to get... Here is the scenario: capturing frames -to memory is done in the so-called snapshot mode. In this mode -the Zoran stops after capturing a frame worth of data and wait -till the application set GRAB bit to indicate readiness for the -next frame. After detecting a set bit, the chip neatly waits -till the start of a frame, captures it and it goes back to off. -Smart ppl will notice the problem here. Its the waiting on the -_next_ frame each time we set the GRAB bit... Oh well, 12,5 fps -is still plenty fast for me. --- update 28/7/1999 -- -Don't believe a word I just said... Proof is the output -of `streamer -t 300 -r 25 -f avi15 -o /dev/null` - ++--+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+- 25/25 - +-s+-+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+- 25/25 - +-s+-+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+- 25/25 - +-s+-+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+- 25/25 - +-s+-+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+- 25/25 - +-s+-+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+- 25/25 - +-s+-+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+- 25/25 - +-s+-+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+- 25/25 - +-s+-+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+- 25/25 - +-s+-+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+- 25/25 - +-s+-+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+- 25/25 - +-s+-+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+- - syncer: done - writer: done -(note the /dev/null is prudent here, my system is not able to - grab /and/ write 25 fps to a file... gifts welcome :) ) -The technical reasoning follows: The zoran completed the last -frame, the VSYNC goes low, and GRAB is cleared. The interrupt -routine starts to work since its VSYNC driven, and again -activates the GRAB bit. A few ms later the VSYNC (re-)rises and -the zoran starts to work on a new and freshly broadcasted frame.... - -For pointers I used the specs of both chips. Below are the URLs: - http://www.zoran.com/ftp/download/devices/pci/ZR36120/36120data.pdf - http://www-us.semiconductor.philips.com/acrobat/datasheets/SAA_7110_A_1.pdf -Some alternatives for the Philips SAA 7110 datasheet are: - http://www.datasheetcatalog.com/datasheets_pdf/S/A/A/7/SAA7110.shtml - http://www.datasheetarchive.com/search.php?search=SAA7110&sType=part - -The documentation has very little on absolute numbers or timings -needed for the various modes/resolutions, but there are other -programs you can borrow those from. - ------- Install -------------------------------------------- -Read the file called TODO. Note its long list of limitations. - -Build a kernel with VIDEO4LINUX enabled. Activate the -BT848 driver; we need this because we have need for the -other modules (i2c and videodev) it enables. - -To install this software, extract it into a suitable directory. -Examine the makefile and change anything you don't like. Type "make". - -After making the modules check if you have the much needed -/dev/video devices. If not, execute the following 4 lines: - mknod /dev/video c 81 0 - mknod /dev/video1 c 81 1 - mknod /dev/video2 c 81 2 - mknod /dev/video3 c 81 3 - mknod /dev/video4 c 81 4 - -After making/checking the devices do: - modprobe i2c - modprobe videodev - modprobe saa7110 (optional) - modprobe saa7111 (optional) - modprobe tuner (optional) - insmod zoran cardtype=<n> - -<n> is the cardtype of the card you have. The cardnumber can -be found in the source of zr36120. Look for tvcards. If your -card is not there, please try if any other card gives some -response, and mail me if you got a working tvcard addition. - -PS. <TVCard editors behold!) - Don't forget to set video_input to the number of inputs - you defined in the video_mux part of the tvcard definition. - It's a common error to add a channel but not incrementing - video_input and getting angry with me/v4l/linux/linus :( - -You are now ready to test the framegrabber with your favorite -video4linux compatible tool - ------- Application ---------------------------------------- - -This device works with all Video4Linux compatible applications, -given the limitations in the TODO file. - ------- API ------------------------------------------------ - -This uses the V4L interface as of kernel release 2.1.116, and in -fact has not been tested on any lower version. There are a couple -of minor differences due to the fact that the amount of data returned -with each frame varies, and no doubt there are discrepancies due to my -misunderstanding of the API. I intend to convert this driver to the -new V4L2 API when it has stabilized more. - ------- Current state -------------------------------------- - -The driver is capable of overlaying a video image in screen, and -even capable of grabbing frames. It uses the BIGPHYSAREA patch -to allocate lots of large memory blocks when tis patch is -found in the kernel, but it doesn't need it. -The consequence is that, when loading the driver as a module, -the module may tell you it's out of memory, but 'free' says -otherwise. The reason is simple; the modules wants its memory -contiguous, not fragmented, and after a long uptime there -probably isn't a fragment of memory large enough... - -The driver uses a double buffering scheme, which should really -be an n-way buffer, depending on the size of allocated framebuffer -and the requested grab-size/format. -This current version also fixes a dead-lock situation during irq -time, which really, really froze my system... :) - -Good luck. - Pauline diff --git a/Documentation/x86_64/boot-options.txt b/Documentation/x86_64/boot-options.txt index dbdcaf68e3e..5c86ed6f044 100644 --- a/Documentation/x86_64/boot-options.txt +++ b/Documentation/x86_64/boot-options.txt @@ -52,6 +52,10 @@ APICs apicmaintimer. Useful when your PIT timer is totally broken. + disable_8254_timer / enable_8254_timer + Enable interrupt 0 timer routing over the 8254 in addition to over + the IO-APIC. The kernel tries to set a sensible default. + Early Console syntax: earlyprintk=vga |