diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/IPMI.txt | 13 | ||||
| -rw-r--r-- | Documentation/RCU/NMI-RCU.txt | 112 | ||||
| -rw-r--r-- | Documentation/cdrom/sonycd535 | 3 | ||||
| -rw-r--r-- | Documentation/cpusets.txt | 12 | ||||
| -rw-r--r-- | Documentation/dcdbas.txt | 91 | ||||
| -rw-r--r-- | Documentation/dell_rbu.txt | 74 | ||||
| -rw-r--r-- | Documentation/dvb/bt8xx.txt | 2 | ||||
| -rw-r--r-- | Documentation/exception.txt | 2 | ||||
| -rw-r--r-- | Documentation/feature-removal-schedule.txt | 16 | ||||
| -rw-r--r-- | Documentation/filesystems/relayfs.txt | 362 | ||||
| -rw-r--r-- | Documentation/i386/boot.txt | 35 | ||||
| -rw-r--r-- | Documentation/kernel-parameters.txt | 5 | ||||
| -rw-r--r-- | Documentation/power/swsusp.txt | 101 | ||||
| -rw-r--r-- | Documentation/power/video.txt | 1 | ||||
| -rw-r--r-- | Documentation/sonypi.txt | 10 |
15 files changed, 756 insertions, 83 deletions
diff --git a/Documentation/IPMI.txt b/Documentation/IPMI.txt index 84d3d4d10c1..bf1cf98d2a2 100644 --- a/Documentation/IPMI.txt +++ b/Documentation/IPMI.txt @@ -605,12 +605,13 @@ is in the ipmi_poweroff module. When the system requests a powerdown, it will send the proper IPMI commands to do this. This is supported on several platforms. -There is a module parameter named "poweroff_control" that may either be zero -(do a power down) or 2 (do a power cycle, power the system off, then power -it on in a few seconds). Setting ipmi_poweroff.poweroff_control=x will do -the same thing on the kernel command line. The parameter is also available -via the proc filesystem in /proc/ipmi/poweroff_control. Note that if the -system does not support power cycling, it will always to the power off. +There is a module parameter named "poweroff_powercycle" that may +either be zero (do a power down) or non-zero (do a power cycle, power +the system off, then power it on in a few seconds). Setting +ipmi_poweroff.poweroff_control=x will do the same thing on the kernel +command line. The parameter is also available via the proc filesystem +in /proc/sys/dev/ipmi/poweroff_powercycle. Note that if the system +does not support power cycling, it will always do the power off. Note that if you have ACPI enabled, the system will prefer using ACPI to power off. diff --git a/Documentation/RCU/NMI-RCU.txt b/Documentation/RCU/NMI-RCU.txt new file mode 100644 index 00000000000..d0634a5c344 --- /dev/null +++ b/Documentation/RCU/NMI-RCU.txt @@ -0,0 +1,112 @@ +Using RCU to Protect Dynamic NMI Handlers + + +Although RCU is usually used to protect read-mostly data structures, +it is possible to use RCU to provide dynamic non-maskable interrupt +handlers, as well as dynamic irq handlers. This document describes +how to do this, drawing loosely from Zwane Mwaikambo's NMI-timer +work in "arch/i386/oprofile/nmi_timer_int.c" and in +"arch/i386/kernel/traps.c". + +The relevant pieces of code are listed below, each followed by a +brief explanation. + + static int dummy_nmi_callback(struct pt_regs *regs, int cpu) + { + return 0; + } + +The dummy_nmi_callback() function is a "dummy" NMI handler that does +nothing, but returns zero, thus saying that it did nothing, allowing +the NMI handler to take the default machine-specific action. + + static nmi_callback_t nmi_callback = dummy_nmi_callback; + +This nmi_callback variable is a global function pointer to the current +NMI handler. + + fastcall void do_nmi(struct pt_regs * regs, long error_code) + { + int cpu; + + nmi_enter(); + + cpu = smp_processor_id(); + ++nmi_count(cpu); + + if (!rcu_dereference(nmi_callback)(regs, cpu)) + default_do_nmi(regs); + + nmi_exit(); + } + +The do_nmi() function processes each NMI. It first disables preemption +in the same way that a hardware irq would, then increments the per-CPU +count of NMIs. It then invokes the NMI handler stored in the nmi_callback +function pointer. If this handler returns zero, do_nmi() invokes the +default_do_nmi() function to handle a machine-specific NMI. Finally, +preemption is restored. + +Strictly speaking, rcu_dereference() is not needed, since this code runs +only on i386, which does not need rcu_dereference() anyway. However, +it is a good documentation aid, particularly for anyone attempting to +do something similar on Alpha. + +Quick Quiz: Why might the rcu_dereference() be necessary on Alpha, + given that the code referenced by the pointer is read-only? + + +Back to the discussion of NMI and RCU... + + void set_nmi_callback(nmi_callback_t callback) + { + rcu_assign_pointer(nmi_callback, callback); + } + +The set_nmi_callback() function registers an NMI handler. Note that any +data that is to be used by the callback must be initialized up -before- +the call to set_nmi_callback(). On architectures that do not order +writes, the rcu_assign_pointer() ensures that the NMI handler sees the +initialized values. + + void unset_nmi_callback(void) + { + rcu_assign_pointer(nmi_callback, dummy_nmi_callback); + } + +This function unregisters an NMI handler, restoring the original +dummy_nmi_handler(). However, there may well be an NMI handler +currently executing on some other CPU. We therefore cannot free +up any data structures used by the old NMI handler until execution +of it completes on all other CPUs. + +One way to accomplish this is via synchronize_sched(), perhaps as +follows: + + unset_nmi_callback(); + synchronize_sched(); + kfree(my_nmi_data); + +This works because synchronize_sched() blocks until all CPUs complete +any preemption-disabled segments of code that they were executing. +Since NMI handlers disable preemption, synchronize_sched() is guaranteed +not to return until all ongoing NMI handlers exit. It is therefore safe +to free up the handler's data as soon as synchronize_sched() returns. + + +Answer to Quick Quiz + + Why might the rcu_dereference() be necessary on Alpha, given + that the code referenced by the pointer is read-only? + + Answer: The caller to set_nmi_callback() might well have + initialized some data that is to be used by the + new NMI handler. In this case, the rcu_dereference() + would be needed, because otherwise a CPU that received + an NMI just after the new handler was set might see + the pointer to the new NMI handler, but the old + pre-initialized version of the handler's data. + + More important, the rcu_dereference() makes it clear + to someone reading the code that the pointer is being + protected by RCU. diff --git a/Documentation/cdrom/sonycd535 b/Documentation/cdrom/sonycd535 index 59581a4b302..b81e109970a 100644 --- a/Documentation/cdrom/sonycd535 +++ b/Documentation/cdrom/sonycd535 @@ -68,7 +68,8 @@ it a better device citizen. Further thanks to Joel Katz Porfiri Claudio <C.Porfiri@nisms.tei.ericsson.se> for patches to make the driver work with the older CDU-510/515 series, and Heiko Eissfeldt <heiko@colossus.escape.de> for pointing out that -the verify_area() checks were ignoring the results of said checks. +the verify_area() checks were ignoring the results of said checks +(note: verify_area() has since been replaced by access_ok()). (Acknowledgments from Ron Jeppesen in the 0.3 release:) Thanks to Corey Minyard who wrote the original CDU-31A driver on which diff --git a/Documentation/cpusets.txt b/Documentation/cpusets.txt index ad944c06031..47f4114fbf5 100644 --- a/Documentation/cpusets.txt +++ b/Documentation/cpusets.txt @@ -60,6 +60,18 @@ all of the cpus in the system. This removes any overhead due to load balancing code trying to pull tasks outside of the cpu exclusive cpuset only to be prevented by the tasks' cpus_allowed mask. +A cpuset that is mem_exclusive restricts kernel allocations for +page, buffer and other data commonly shared by the kernel across +multiple users. All cpusets, whether mem_exclusive or not, restrict +allocations of memory for user space. This enables configuring a +system so that several independent jobs can share common kernel +data, such as file system pages, while isolating each jobs user +allocation in its own cpuset. To do this, construct a large +mem_exclusive cpuset to hold all the jobs, and construct child, +non-mem_exclusive cpusets for each individual job. Only a small +amount of typical kernel memory, such as requests from interrupt +handlers, is allowed to be taken outside even a mem_exclusive cpuset. + User level code may create and destroy cpusets by name in the cpuset virtual file system, manage the attributes and permissions of these cpusets and which CPUs and Memory Nodes are assigned to each cpuset, diff --git a/Documentation/dcdbas.txt b/Documentation/dcdbas.txt new file mode 100644 index 00000000000..e1c52e2dc36 --- /dev/null +++ b/Documentation/dcdbas.txt @@ -0,0 +1,91 @@ +Overview + +The Dell Systems Management Base Driver provides a sysfs interface for +systems management software such as Dell OpenManage to perform system +management interrupts and host control actions (system power cycle or +power off after OS shutdown) on certain Dell systems. + +Dell OpenManage requires this driver on the following Dell PowerEdge systems: +300, 1300, 1400, 400SC, 500SC, 1500SC, 1550, 600SC, 1600SC, 650, 1655MC, +700, and 750. Other Dell software such as the open source libsmbios project +is expected to make use of this driver, and it may include the use of this +driver on other Dell systems. + +The Dell libsmbios project aims towards providing access to as much BIOS +information as possible. See http://linux.dell.com/libsmbios/main/ for +more information about the libsmbios project. + + +System Management Interrupt + +On some Dell systems, systems management software must access certain +management information via a system management interrupt (SMI). The SMI data +buffer must reside in 32-bit address space, and the physical address of the +buffer is required for the SMI. The driver maintains the memory required for +the SMI and provides a way for the application to generate the SMI. +The driver creates the following sysfs entries for systems management +software to perform these system management interrupts: + +/sys/devices/platform/dcdbas/smi_data +/sys/devices/platform/dcdbas/smi_data_buf_phys_addr +/sys/devices/platform/dcdbas/smi_data_buf_size +/sys/devices/platform/dcdbas/smi_request + +Systems management software must perform the following steps to execute +a SMI using this driver: + +1) Lock smi_data. +2) Write system management command to smi_data. +3) Write "1" to smi_request to generate a calling interface SMI or + "2" to generate a raw SMI. +4) Read system management command response from smi_data. +5) Unlock smi_data. + + +Host Control Action + +Dell OpenManage supports a host control feature that allows the administrator +to perform a power cycle or power off of the system after the OS has finished +shutting down. On some Dell systems, this host control feature requires that +a driver perform a SMI after the OS has finished shutting down. + +The driver creates the following sysfs entries for systems management software +to schedule the driver to perform a power cycle or power off host control +action after the system has finished shutting down: + +/sys/devices/platform/dcdbas/host_control_action +/sys/devices/platform/dcdbas/host_control_smi_type +/sys/devices/platform/dcdbas/host_control_on_shutdown + +Dell OpenManage performs the following steps to execute a power cycle or +power off host control action using this driver: + +1) Write host control action to be performed to host_control_action. +2) Write type of SMI that driver needs to perform to host_control_smi_type. +3) Write "1" to host_control_on_shutdown to enable host control action. +4) Initiate OS shutdown. + (Driver will perform host control SMI when it is notified that the OS + has finished shutting down.) + + +Host Control SMI Type + +The following table shows the value to write to host_control_smi_type to +perform a power cycle or power off host control action: + +PowerEdge System Host Control SMI Type +---------------- --------------------- + 300 HC_SMITYPE_TYPE1 + 1300 HC_SMITYPE_TYPE1 + 1400 HC_SMITYPE_TYPE2 + 500SC HC_SMITYPE_TYPE2 + 1500SC HC_SMITYPE_TYPE2 + 1550 HC_SMITYPE_TYPE2 + 600SC HC_SMITYPE_TYPE2 + 1600SC HC_SMITYPE_TYPE2 + 650 HC_SMITYPE_TYPE2 + 1655MC HC_SMITYPE_TYPE2 + 700 HC_SMITYPE_TYPE3 + 750 HC_SMITYPE_TYPE3 + + diff --git a/Documentation/dell_rbu.txt b/Documentation/dell_rbu.txt new file mode 100644 index 00000000000..bcfa5c35036 --- /dev/null +++ b/Documentation/dell_rbu.txt @@ -0,0 +1,74 @@ +Purpose: +Demonstrate the usage of the new open sourced rbu (Remote BIOS Update) driver +for updating BIOS images on Dell servers and desktops. + +Scope: +This document discusses the functionality of the rbu driver only. +It does not cover the support needed from aplications to enable the BIOS to +update itself with the image downloaded in to the memory. + +Overview: +This driver works with Dell OpenManage or Dell Update Packages for updating +the BIOS on Dell servers (starting from servers sold since 1999), desktops +and notebooks (starting from those sold in 2005). +Please go to http://support.dell.com register and you can find info on +OpenManage and Dell Update packages (DUP). + +Dell_RBU driver supports BIOS update using the monilothic image and packetized +image methods. In case of moniolithic the driver allocates a contiguous chunk +of physical pages having the BIOS image. In case of packetized the app +using the driver breaks the image in to packets of fixed sizes and the driver +would place each packet in contiguous physical memory. The driver also +maintains a link list of packets for reading them back. +If the dell_rbu driver is unloaded all the allocated memory is freed. + +The rbu driver needs to have an application which will inform the BIOS to +enable the update in the next system reboot. + +The user should not unload the rbu driver after downloading the BIOS image +or updating. + +The driver load creates the following directories under the /sys file system. +/sys/class/firmware/dell_rbu/loading +/sys/class/firmware/dell_rbu/data +/sys/devices/platform/dell_rbu/image_type +/sys/devices/platform/dell_rbu/data + +The driver supports two types of update mechanism; monolithic and packetized. +These update mechanism depends upon the BIOS currently running on the system. +Most of the Dell systems support a monolithic update where the BIOS image is +copied to a single contiguous block of physical memory. +In case of packet mechanism the single memory can be broken in smaller chuks +of contiguous memory and the BIOS image is scattered in these packets. + +By default the driver uses monolithic memory for the update type. This can be +changed to contiguous during the driver load time by specifying the load +parameter image_type=packet. This can also be changed later as below +echo packet > /sys/devices/platform/dell_rbu/image_type + +Do the steps below to download the BIOS image. +1) echo 1 > /sys/class/firmware/dell_rbu/loading +2) cp bios_image.hdr /sys/class/firmware/dell_rbu/data +3) echo 0 > /sys/class/firmware/dell_rbu/loading + +The /sys/class/firmware/dell_rbu/ entries will remain till the following is +done. +echo -1 > /sys/class/firmware/dell_rbu/loading + +Until this step is completed the drivr cannot be unloaded. + +Also the driver provides /sys/devices/platform/dell_rbu/data readonly file to +read back the image downloaded. This is useful in case of packet update +mechanism where the above steps 1,2,3 will repeated for every packet. +By reading the /sys/devices/platform/dell_rbu/data file all packet data +downloaded can be verified in a single file. +The packets are arranged in this file one after the other in a FIFO order. + +NOTE: +This driver requires a patch for firmware_class.c which has the addition +of request_firmware_nowait_nohotplug function to wortk +Also after updating the BIOS image an user mdoe application neeeds to execute +code which message the BIOS update request to the BIOS. So on the next reboot +the BIOS knows about the new image downloaded and it updates it self. +Also don't unload the rbu drive if the image has to be updated. + diff --git a/Documentation/dvb/bt8xx.txt b/Documentation/dvb/bt8xx.txt index e6b8d05bc08..4b8c326c6aa 100644 --- a/Documentation/dvb/bt8xx.txt +++ b/Documentation/dvb/bt8xx.txt @@ -16,7 +16,7 @@ Enable the following options: "Device drivers" => "Multimedia devices" => "Video For Linux" => "BT848 Video For Linux" "Device drivers" => "Multimedia devices" => "Digital Video Broadcasting Devices" - => "DVB for Linux" "DVB Core Support" "Nebula/Pinnacle PCTV/TwinHan PCI Cards" + => "DVB for Linux" "DVB Core Support" "BT8xx based PCI cards" 3) Loading Modules, described by two approaches =============================================== diff --git a/Documentation/exception.txt b/Documentation/exception.txt index f1d436993eb..3cb39ade290 100644 --- a/Documentation/exception.txt +++ b/Documentation/exception.txt @@ -7,7 +7,7 @@ To protect itself the kernel has to verify this address. In older versions of Linux this was done with the int verify_area(int type, const void * addr, unsigned long size) -function. +function (which has since been replaced by access_ok()). This function verified that the memory area starting at address addr and of size size was accessible for the operation specified diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index 363909056e4..2e0a01b21fe 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -51,14 +51,6 @@ Who: Adrian Bunk <bunk@stusta.de> --------------------------- -What: register_ioctl32_conversion() / unregister_ioctl32_conversion() -When: April 2005 -Why: Replaced by ->compat_ioctl in file_operations and other method - vecors. -Who: Andi Kleen <ak@muc.de>, Christoph Hellwig <hch@lst.de> - ---------------------------- - What: RCU API moves to EXPORT_SYMBOL_GPL When: April 2006 Files: include/linux/rcupdate.h, kernel/rcupdate.c @@ -74,14 +66,6 @@ Who: Paul E. McKenney <paulmck@us.ibm.com> --------------------------- -What: remove verify_area() -When: July 2006 -Files: Various uaccess.h headers. -Why: Deprecated and redundant. access_ok() should be used instead. -Who: Jesper Juhl <juhl-lkml@dif.dk> - ---------------------------- - What: IEEE1394 Audio and Music Data Transmission Protocol driver, Connection Management Procedures driver When: November 2005 diff --git a/Documentation/filesystems/relayfs.txt b/Documentation/filesystems/relayfs.txt new file mode 100644 index 00000000000..d24e1b0d4f3 --- /dev/null +++ b/Documentation/filesystems/relayfs.txt @@ -0,0 +1,362 @@ + +relayfs - a high-speed data relay filesystem +============================================ + +relayfs is a filesystem designed to provide an efficient mechanism for +tools and facilities to relay large and potentially sustained streams +of data from kernel space to user space. + +The main abstraction of relayfs is the 'channel'. A channel consists +of a set of per-cpu kernel buffers each represented by a file in the +relayfs filesystem. Kernel clients write into a channel using +efficient write functions which automatically log to the current cpu's +channel buffer. User space applications mmap() the per-cpu files and +retrieve the data as it becomes available. + +The format of the data logged into the channel buffers is completely +up to the relayfs client; relayfs does however provide hooks which +allow clients to impose some stucture on the buffer data. Nor does +relayfs implement any form of data filtering - this also is left to +the client. The purpose is to keep relayfs as simple as possible. + +This document provides an overview of the relayfs API. The details of +the function parameters are documented along with the functions in the +filesystem code - please see that for details. + +Semantics +========= + +Each relayfs channel has one buffer per CPU, each buffer has one or +more sub-buffers. Messages are written to the first sub-buffer until +it is too full to contain a new message, in which case it it is +written to the next (if available). Messages are never split across +sub-buffers. At this point, userspace can be notified so it empties +the first sub-buffer, while the kernel continues writing to the next. + +When notified that a sub-buffer is full, the kernel knows how many +bytes of it are padding i.e. unused. Userspace can use this knowledge +to copy only valid data. + +After copying it, userspace can notify the kernel that a sub-buffer +has been consumed. + +relayfs can operate in a mode where it will overwrite data not yet +collected by userspace, and not wait for it to consume it. + +relayfs itself does not provide for communication of such data between +userspace and kernel, allowing the kernel side to remain simple and not +impose a single interface on userspace. It does provide a separate +helper though, described below. + +klog, relay-app & librelay +========================== + +relayfs itself is ready to use, but to make things easier, two +additional systems are provided. klog is a simple wrapper to make +writing formatted text or raw data to a channel simpler, regardless of +whether a channel to write into exists or not, or whether relayfs is +compiled into the kernel or is configured as a module. relay-app is +the kernel counterpart of userspace librelay.c, combined these two +files provide glue to easily stream data to disk, without having to +bother with housekeeping. klog and relay-app can be used together, +with klog providing high-level logging functions to the kernel and +relay-app taking care of kernel-user control and disk-logging chores. + +It is possible to use relayfs without relay-app & librelay, but you'll +have to implement communication between userspace and kernel, allowing +both to convey the state of buffers (full, empty, amount of padding). + +klog, relay-app and librelay can be found in the relay-apps tarball on +http://relayfs.sourceforge.net + +The relayfs user space API +========================== + +relayfs implements basic file operations for user space access to +relayfs channel buffer data. Here are the file operations that are +available and some comments regarding their behavior: + +open() enables user to open an _existing_ buffer. + +mmap() results in channel buffer being mapped into the caller's + memory space. Note that you can't do a partial mmap - you must + map the entire file, which is NRBUF * SUBBUFSIZE. + +read() read the contents of a channel buffer. The bytes read are + 'consumed' by the reader i.e. they won't be available again + to subsequent reads. If the channel is being used in + no-overwrite mode (the default), it can be read at any time + even if there's an active kernel writer. If the channel is + being used in overwrite mode and there are active channel + writers, results may be unpredictable - users should make + sure that all logging to the channel has ended before using + read() with overwrite mode. + +poll() POLLIN/POLLRDNORM/POLLERR supported. User applications are + notified when sub-buffer boundaries are crossed. + +close() decrements the channel buffer's refcount. When the refcount + reaches 0 i.e. when no process or kernel client has the buffer + open, the channel buffer is freed. + + +In order for a user application to make use of relayfs files, the +relayfs filesystem must be mounted. For example, + + mount -t relayfs relayfs /mnt/relay + +NOTE: relayfs doesn't need to be mounted for kernel clients to create + or use channels - it only needs to be mounted when user space + applications need access to the buffer data. + + +The relayfs kernel API +====================== + +Here's a summary of the API relayfs provides to in-kernel clients: + + + channel management functions: + + relay_open(base_filename, parent, subbuf_size, n_subbufs, + callbacks) + relay_close(chan) + relay_flush(chan) + relay_reset(chan) + relayfs_create_dir(name, parent) + relayfs_remove_dir(dentry) + + channel management typically called on instigation of userspace: + + relay_subbufs_consumed(chan, cpu, subbufs_consumed) + + write functions: + + relay_write(chan, data, length) + __relay_write(chan, data, length) + relay_reserve(chan, length) + + callbacks: + + subbuf_start(buf, subbuf, prev_subbuf, prev_padding) + buf_mapped(buf, filp) + buf_unmapped(buf, filp) + + helper functions: + + relay_buf_full(buf) + subbuf_start_reserve(buf, length) + + +Creating a channel +------------------ + +relay_open() is used to create a channel, along with its per-cpu +channel buffers. Each channel buffer will have an associated file +created for it in the relayfs filesystem, which can be opened and +mmapped from user space if desired. The files are named +basename0...basenameN-1 where N is the number of online cpus, and by +default will be created in the root of the filesystem. If you want a +directory structure to contain your relayfs files, you can create it +with relayfs_create_dir() and pass the parent directory to +relay_open(). Clients are responsible for cleaning up any directory +structure they create when the channel is closed - use +relayfs_remove_dir() for that. + +The total size of each per-cpu buffer is calculated by multiplying the +number of sub-buffers by the sub-buffer size passed into relay_open(). +The idea behind sub-buffers is that they're basically an extension of +double-buffering to N buffers, and they also allow applications to +easily implement random-access-on-buffer-boundary schemes, which can +be important for some high-volume applications. The number and size +of sub-buffers is completely dependent on the application and even for +the same application, different conditions will warrant different +values for these parameters at different times. Typically, the right +values to use are best decided after some experimentation; in general, +though, it's safe to assume that having only 1 sub-buffer is a bad +idea - you're guaranteed to either overwrite data or lose events +depending on the channel mode being used. + +Channel 'modes' +--------------- + +relayfs channels can be used in either of two modes - 'overwrite' or +'no-overwrite'. The mode is entirely determined by the implementation +of the subbuf_start() callback, as described below. In 'overwrite' +mode, also known as 'flight recorder' mode, writes continuously cycle +around the buffer and will never fail, but will unconditionally +overwrite old data regardless of whether it's actually been consumed. +In no-overwrite mode, writes will fail i.e. data will be lost, if the +number of unconsumed sub-buffers equals the total number of +sub-buffers in the channel. It should be clear that if there is no +consumer or if the consumer can't consume sub-buffers fast enought, +data will be lost in either case; the only difference is whether data +is lost from the beginning or the end of a buffer. + +As explained above, a relayfs channel is made of up one or more +per-cpu channel buffers, each implemented as a circular buffer +subdivided into one or more sub-buffers. Messages are written into +the current sub-buffer of the channel's current per-cpu buffer via the +write functions described below. Whenever a message can't fit into +the current sub-buffer, because there's no room left for it, the +client is notified via the subbuf_start() callback that a switch to a +new sub-buffer is about to occur. The client uses this callback to 1) +initialize the next sub-buffer if appropriate 2) finalize the previous +sub-buffer if appropriate and 3) return a boolean value indicating +whether or not to actually go ahead with the sub-buffer switch. + +To implement 'no-overwrite' mode, the userspace client would provide +an implementation of the subbuf_start() callback something like the +following: + +static int subbuf_start(struct rchan_buf *buf, + void *subbuf, + void *prev_subbuf, + unsigned int prev_padding) +{ + if (prev_subbuf) + *((unsigned *)prev_subbuf) = prev_padding; + + if (relay_buf_full(buf)) + return 0; + + subbuf_start_reserve(buf, sizeof(unsigned int)); + + return 1; +} + +If the current buffer is full i.e. all sub-buffers remain unconsumed, +the callback returns 0 to indicate that the buffer switch should not +occur yet i.e. until the consumer has had a chance to read the current +set of ready sub-buffers. For the relay_buf_full() function to make +sense, the consumer is reponsible for notifying relayfs when +sub-buffers have been consumed via relay_subbufs_consumed(). Any +subsequent attempts to write into the buffer will again invoke the +subbuf_start() callback with the same parameters; only when the +consumer has consumed one or more of the ready sub-buffers will +relay_buf_full() return 0, in which case the buffer switch can +continue. + +The implementation of the subbuf_start() callback for 'overwrite' mode +would be very similar: + +static int subbuf_start(struct rchan_buf *buf, + void *subbuf, + void *prev_subbuf, + unsigned int prev_padding) +{ + if (prev_subbuf) + *((unsigned *)prev_subbuf) = prev_padding; + + subbuf_start_reserve(buf, sizeof(unsigned int)); + + return 1; +} + +In this case, the relay_buf_full() check is meaningless and the +callback always returns 1, causing the buffer switch to occur +unconditionally. It's also meaningless for the client to use the +relay_subbufs_consumed() function in this mode, as it's never +consulted. + +The default subbuf_start() implementation, used if the client doesn't +define any callbacks, or doesn't define the subbuf_start() callback, +implements the simplest possible 'no-overwrite' mode i.e. it does +nothing but return 0. + +Header information can be reserved at the beginning of each sub-buffer +by calling the subbuf_start_reserve() helper function from within the +subbuf_start() callback. This reserved area can be used to store +whatever information the client wants. In the example above, room is +reserved in each sub-buffer to store the padding count for that +sub-buffer. This is filled in for the previous sub-buffer in the +subbuf_start() implementation; the padding value for the previous +sub-buffer is passed into the subbuf_start() callback along with a +pointer to the previous sub-buffer, since the padding value isn't +known until a sub-buffer is filled. The subbuf_start() callback is +also called for the first sub-buffer when the channel is opened, to +give the client a chance to reserve space in it. In this case the +previous sub-buffer pointer passed into the callback will be NULL, so +the client should check the value of the prev_subbuf pointer before +writing into the previous sub-buffer. + +Writing to a channel +-------------------- + +kernel clients write data into the current cpu's channel buffer using +relay_write() or __relay_write(). relay_write() is the main logging +function - it uses local_irqsave() to protect the buffer and should be +used if you might be logging from interrupt context. If you know +you'll never be logging from interrupt context, you can use +__relay_write(), which only disables preemption. These functions +don't return a value, so you can't determine whether or not they +failed - the assumption is that you wouldn't want to check a return +value in the fast logging path anyway, and that they'll always succeed +unless the buffer is full and no-overwrite mode is being used, in +which case you can detect a failed write in the subbuf_start() +callback by calling the relay_buf_full() helper function. + +relay_reserve() is used to reserve a slot in a channel buffer which +can be written to later. This would typically be used in applications +that need to write directly into a channel buffer without having to +stage data in a temporary buffer beforehand. Because the actual write +may not happen immediately after the slot is reserved, applications +using relay_reserve() can keep a count of the number of bytes actually +written, either in space reserved in the sub-buffers themselves or as +a separate array. See the 'reserve' example in the relay-apps tarball +at http://relayfs.sourceforge.net for an example of how this can be +done. Because the write is under control of the client and is +separated from the reserve, relay_reserve() doesn't protect the buffer +at all - it's up to the client to provide the appropriate +synchronization when using relay_reserve(). + +Closing a channel +----------------- + +The client calls relay_close() when it's finished using the channel. +The channel and its associated buffers are destroyed when there are no +longer any references to any of the channel buffers. relay_flush() +forces a sub-buffer switch on all the channel buffers, and can be used +to finalize and process the last sub-buffers before the channel is +closed. + +Misc +---- + +Some applications may want to keep a channel around and re-use it +rather than open and close a new channel for each use. relay_reset() +can be used for this purpose - it resets a channel to its initial +state without reallocating channel buffer memory or destroying +existing mappings. It should however only be called when it's safe to +do so i.e. when the channel isn't currently being written to. + +Finally, there are a couple of utility callbacks that can be used for +different purposes. buf_mapped() is called whenever a channel buffer +is mmapped from user space and buf_unmapped() is called when it's +unmapped. The client can use this notification to trigger actions +within the kernel application, such as enabling/disabling logging to +the channel. + + +Resources +========= + +For news, example code, mailing list, etc. see the relayfs homepage: + + http://relayfs.sourceforge.net + + +Credits +======= + +The ideas and specs for relayfs came about as a result of discussions +on tracing involving the following: + +Michel Dagenais <michel.dagenais@polymtl.ca> +Richard Moore <richardj_moore@uk.ibm.com> +Bob Wisniewski <bob@watson.ibm.com> +Karim Yaghmour <karim@opersys.com> +Tom Zanussi <zanussi@us.ibm.com> + +Also thanks to Hubertus Franke for a lot of useful suggestions and bug +reports. diff --git a/Documentation/i386/boot.txt b/Documentation/i386/boot.txt index 1c48f0eba6f..10312bebe55 100644 --- a/Documentation/i386/boot.txt +++ b/Documentation/i386/boot.txt @@ -2,7 +2,7 @@ ---------------------------- H. Peter Anvin <hpa@zytor.com> - Last update 2002-01-01 + Last update 2005-09-02 On the i386 platform, the Linux kernel uses a rather complicated boot convention. This has evolved partially due to historical aspects, as @@ -34,6 +34,8 @@ Protocol 2.02: (Kernel 2.4.0-test3-pre3) New command line protocol. Protocol 2.03: (Kernel 2.4.18-pre1) Explicitly makes the highest possible initrd address available to the bootloader. +Protocol 2.04: (Kernel 2.6.14) Extend the syssize field to four bytes. + **** MEMORY LAYOUT @@ -103,10 +105,9 @@ The header looks like: Offset Proto Name Meaning /Size -01F1/1 ALL setup_sects The size of the setup in sectors +01F1/1 ALL(1 setup_sects The size of the setup in sectors 01F2/2 ALL root_flags If set, the root is mounted readonly -01F4/2 ALL syssize DO NOT USE - for bootsect.S use only -01F6/2 ALL swap_dev DO NOT USE - obsolete +01F4/4 2.04+(2 syssize The size of the 32-bit code in 16-byte paras 01F8/2 ALL ram_size DO NOT USE - for bootsect.S use only 01FA/2 ALL vid_mode Video mode control 01FC/2 ALL root_dev Default root device number @@ -129,8 +130,12 @@ Offset Proto Name Meaning 0228/4 2.02+ cmd_line_ptr 32-bit pointer to the kernel command line 022C/4 2.03+ initrd_addr_max Highest legal initrd address -For backwards compatibility, if the setup_sects field contains 0, the -real value is 4. +(1) For backwards compatibility, if the setup_sects field contains 0, the + real value is 4. + +(2) For boot protocol prior to 2.04, the upper two bytes of the syssize + field are unusable, which means the size of a bzImage kernel + cannot be determined. If the "HdrS" (0x53726448) magic number is not found at offset 0x202, the boot protocol version is "old". Loading an old kernel, the @@ -230,12 +235,16 @@ loader to communicate with the kernel. Some of its options are also relevant to the boot loader itself, see "special command line options" below. -The kernel command line is a null-terminated string up to 255 -characters long, plus the final null. +The kernel command line is a null-terminated string currently up to +255 characters long, plus the final null. A string that is too long +will be automatically truncated by the kernel, a boot loader may allow +a longer command line to be passed to permit future kernels to extend +this limit. If the boot protocol version is 2.02 or later, the address of the kernel command line is given by the header field cmd_line_ptr (see -above.) +above.) This address can be anywhere between the end of the setup +heap and 0xA0000. If the protocol version is *not* 2.02 or higher, the kernel command line is entered using the following protocol: @@ -255,7 +264,7 @@ command line is entered using the following protocol: **** SAMPLE BOOT CONFIGURATION As a sample configuration, assume the following layout of the real -mode segment: +mode segment (this is a typical, and recommended layout): 0x0000-0x7FFF Real mode kernel 0x8000-0x8FFF Stack and heap @@ -312,9 +321,9 @@ Such a boot loader should enter the following fields in the header: **** LOADING THE REST OF THE KERNEL -The non-real-mode kernel starts at offset (setup_sects+1)*512 in the -kernel file (again, if setup_sects == 0 the real value is 4.) It -should be loaded at address 0x10000 for Image/zImage kernels and +The 32-bit (non-real-mode) kernel starts at offset (setup_sects+1)*512 +in the kernel file (again, if setup_sects == 0 the real value is 4.) +It should be loaded at address 0x10000 for Image/zImage kernels and 0x100000 for bzImage kernels. The kernel is a bzImage kernel if the protocol >= 2.00 and the 0x01 diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 3d5cd7a09b2..d2f0c67ba1f 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -1174,6 +1174,11 @@ running once the system is up. New name for the ramdisk parameter. See Documentation/ramdisk.txt. + rdinit= [KNL] + Format: <full_path> + Run specified binary instead of /init from the ramdisk, + used for early userspace startup. See initrd. + reboot= [BUGS=IA-32,BUGS=ARM,BUGS=IA-64] Rebooting mode Format: <reboot_mode>[,<reboot_mode2>[,...]] See arch/*/kernel/reboot.c. diff --git a/Documentation/power/swsusp.txt b/Documentation/power/swsusp.txt index ddf907fbcc0..b0d50840788 100644 --- a/Documentation/power/swsusp.txt +++ b/Documentation/power/swsusp.txt @@ -1,22 +1,20 @@ -From kernel/suspend.c: +Some warnings, first. * BIG FAT WARNING ********************************************************* * - * If you have unsupported (*) devices using DMA... - * ...say goodbye to your data. - * * If you touch anything on disk between suspend and resume... * ...kiss your data goodbye. * - * If your disk driver does not support suspend... (IDE does) - * ...you'd better find out how to get along - * without your data. - * - * If you change kernel command line between suspend and resume... - * ...prepare for nasty fsck or worse. + * If you do resume from initrd after your filesystems are mounted... + * ...bye bye root partition. + * [this is actually same case as above] * - * If you change your hardware while system is suspended... - * ...well, it was not good idea. + * If you have unsupported (*) devices using DMA, you may have some + * problems. If your disk driver does not support suspend... (IDE does), + * it may cause some problems, too. If you change kernel command line + * between suspend and resume, it may do something wrong. If you change + * your hardware while system is suspended... well, it was not good idea; + * but it will probably only crash. * * (*) suspend/resume support is needed to make it safe. @@ -30,6 +28,13 @@ echo shutdown > /sys/power/disk; echo disk > /sys/power/state echo platform > /sys/power/disk; echo disk > /sys/power/state +Encrypted suspend image: +------------------------ +If you want to store your suspend image encrypted with a temporary +key to prevent data gathering after resume you must compile +crypto and the aes algorithm into the kernel - modules won't work +as they cannot be loaded at resume time. + Article about goals and implementation of Software Suspend for Linux ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -85,11 +90,6 @@ resume. You have your server on UPS. Power died, and UPS is indicating 30 seconds to failure. What do you do? Suspend to disk. -Ethernet card in your server died. You want to replace it. Your -server is not hotplug capable. What do you do? Suspend to disk, -replace ethernet card, resume. If you are fast your users will not -even see broken connections. - Q: Maybe I'm missing something, but why don't the regular I/O paths work? @@ -117,31 +117,6 @@ Q: Does linux support ACPI S4? A: Yes. That's what echo platform > /sys/power/disk does. -Q: My machine doesn't work with ACPI. How can I use swsusp than ? - -A: Do a reboot() syscall with right parameters. Warning: glibc gets in -its way, so check with strace: - -reboot(LINUX_REBOOT_MAGIC1, LINUX_REBOOT_MAGIC2, 0xd000fce2) - -(Thanks to Peter Osterlund:) - -#include <unistd.h> -#include <syscall.h> - -#define LINUX_REBOOT_MAGIC1 0xfee1dead -#define LINUX_REBOOT_MAGIC2 672274793 -#define LINUX_REBOOT_CMD_SW_SUSPEND 0xD000FCE2 - -int main() -{ - syscall(SYS_reboot, LINUX_REBOOT_MAGIC1, LINUX_REBOOT_MAGIC2, - LINUX_REBOOT_CMD_SW_SUSPEND, 0); - return 0; -} - -Also /sys/ interface should be still present. - Q: What is 'suspend2'? A: suspend2 is 'Software Suspend 2', a forked implementation of @@ -312,9 +287,45 @@ system is shut down or suspended. Additionally use the encrypted suspend image to prevent sensitive data from being stolen after resume. -Q: Why we cannot suspend to a swap file? +Q: Why can't we suspend to a swap file? A: Because accessing swap file needs the filesystem mounted, and filesystem might do something wrong (like replaying the journal) -during mount. [Probably could be solved by modifying every filesystem -to support some kind of "really read-only!" option. Patches welcome.] +during mount. + +There are few ways to get that fixed: + +1) Probably could be solved by modifying every filesystem to support +some kind of "really read-only!" option. Patches welcome. + +2) suspend2 gets around that by storing absolute positions in on-disk +image (and blocksize), with resume parameter pointing directly to +suspend header. + +Q: Is there a maximum system RAM size that is supported by swsusp? + +A: It should work okay with highmem. + +Q: Does swsusp (to disk) use only one swap partition or can it use +multiple swap partitions (aggregate them into one logical space)? + +A: Only one swap partition, sorry. + +Q: If my application(s) causes lots of memory & swap space to be used +(over half of the total system RAM), is it correct that it is likely +to be useless to try to suspend to disk while that app is running? + +A: No, it should work okay, as long as your app does not mlock() +it. Just prepare big enough swap partition. + +Q: What information is usefull for debugging suspend-to-disk problems? + +A: Well, last messages on the screen are always useful. If something +is broken, it is usually some kernel driver, therefore trying with as +little as possible modules loaded helps a lot. I also prefer people to +suspend from console, preferably without X running. Booting with +init=/bin/bash, then swapon and starting suspend sequence manually +usually does the trick. Then it is good idea to try with latest +vanilla kernel. + + diff --git a/Documentation/power/video.txt b/Documentation/power/video.txt index 1a44e8acb54..526d6dd267e 100644 --- a/Documentation/power/video.txt +++ b/Documentation/power/video.txt @@ -120,6 +120,7 @@ IBM ThinkPad T42p (2373-GTG) s3_bios (2) IBM TP X20 ??? (*) IBM TP X30 s3_bios (2) IBM TP X31 / Type 2672-XXH none (1), use radeontool (http://fdd.com/software/radeon/) to turn off backlight. +IBM TP X32 none (1), but backlight is on and video is trashed after long suspend IBM Thinkpad X40 Type 2371-7JG s3_bios,s3_mode (4) Medion MD4220 ??? (*) Samsung P35 vbetool needed (6) diff --git a/Documentation/sonypi.txt b/Documentation/sonypi.txt index 0f3b2405d09..c1237a92550 100644 --- a/Documentation/sonypi.txt +++ b/Documentation/sonypi.txt @@ -99,6 +99,7 @@ statically linked into the kernel). Those options are: SONYPI_MEYE_MASK 0x0400 SONYPI_MEMORYSTICK_MASK 0x0800 SONYPI_BATTERY_MASK 0x1000 + SONYPI_WIRELESS_MASK 0x2000 useinput: if set (which is the default) two input devices are created, one which interprets the jogdial events as @@ -137,6 +138,15 @@ Bugs: speed handling etc). Use ACPI instead of APM if it works on your laptop. + - sonypi lacks the ability to distinguish between certain key + events on some models. + + - some models with the nvidia card (geforce go 6200 tc) uses a + different way to adjust the backlighting of the screen. There + is a userspace utility to adjust the brightness on those models, + which can be downloaded from + http://www.acc.umu.se/~erikw/program/smartdimmer-0.1.tar.bz2 + - since all development was done by reverse engineering, there is _absolutely no guarantee_ that this driver will not crash your laptop. Permanently. |