diff options
Diffstat (limited to 'Documentation')
28 files changed, 2009 insertions, 406 deletions
diff --git a/Documentation/DocBook/usb.tmpl b/Documentation/DocBook/usb.tmpl index 15ce0f21e5e..320af25de3a 100644 --- a/Documentation/DocBook/usb.tmpl +++ b/Documentation/DocBook/usb.tmpl @@ -253,6 +253,7 @@ !Edrivers/usb/core/urb.c !Edrivers/usb/core/message.c !Edrivers/usb/core/file.c +!Edrivers/usb/core/driver.c !Edrivers/usb/core/usb.c !Edrivers/usb/core/hub.c </chapter> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 237d54c44bc..1d47e6c09dc 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -158,7 +158,7 @@ Even if the maintainer did not respond in step #4, make sure to ALWAYS copy the maintainer when you change their code. For small patches you may want to CC the Trivial Patch Monkey -trivial@rustcorp.com.au set up by Rusty Russell; which collects "trivial" +trivial@kernel.org managed by Adrian Bunk; which collects "trivial" patches. Trivial patches must qualify for one of the following rules: Spelling fixes in documentation Spelling fixes which could break grep(1). @@ -171,7 +171,7 @@ patches. Trivial patches must qualify for one of the following rules: since people copy, as long as it's trivial) Any fix by the author/maintainer of the file. (ie. patch monkey in re-transmission mode) -URL: <http://www.kernel.org/pub/linux/kernel/people/rusty/trivial/> +URL: <http://www.kernel.org/pub/linux/kernel/people/bunk/trivial/> diff --git a/Documentation/block/biodoc.txt b/Documentation/block/biodoc.txt index 0fe01c80548..8e63831971d 100644 --- a/Documentation/block/biodoc.txt +++ b/Documentation/block/biodoc.txt @@ -31,7 +31,7 @@ The following people helped with review comments and inputs for this document: Christoph Hellwig <hch@infradead.org> Arjan van de Ven <arjanv@redhat.com> - Randy Dunlap <rddunlap@osdl.org> + Randy Dunlap <rdunlap@xenotime.net> Andre Hedrick <andre@linux-ide.org> The following people helped with fixes/contributions to the bio patches @@ -263,14 +263,8 @@ A flag in the bio structure, BIO_BARRIER is used to identify a barrier i/o. The generic i/o scheduler would make sure that it places the barrier request and all other requests coming after it after all the previous requests in the queue. Barriers may be implemented in different ways depending on the -driver. A SCSI driver for example could make use of ordered tags to -preserve the necessary ordering with a lower impact on throughput. For IDE -this might be two sync cache flush: a pre and post flush when encountering -a barrier write. - -There is a provision for queues to indicate what kind of barriers they -can provide. This is as of yet unmerged, details will be added here once it -is in the kernel. +driver. For more details regarding I/O barriers, please read barrier.txt +in this directory. 1.2.2 Request Priority/Latency diff --git a/Documentation/cpu-freq/governors.txt b/Documentation/cpu-freq/governors.txt index 933fae74c33..f4b8dc4237e 100644 --- a/Documentation/cpu-freq/governors.txt +++ b/Documentation/cpu-freq/governors.txt @@ -27,6 +27,7 @@ Contents: 2.2 Powersave 2.3 Userspace 2.4 Ondemand +2.5 Conservative 3. The Governor Interface in the CPUfreq Core @@ -110,9 +111,64 @@ directory. The CPUfreq govenor "ondemand" sets the CPU depending on the current usage. To do this the CPU must have the capability to -switch the frequency very fast. - - +switch the frequency very quickly. There are a number of sysfs file +accessible parameters: + +sampling_rate: measured in uS (10^-6 seconds), this is how often you +want the kernel to look at the CPU usage and to make decisions on +what to do about the frequency. Typically this is set to values of +around '10000' or more. + +show_sampling_rate_(min|max): the minimum and maximum sampling rates +available that you may set 'sampling_rate' to. + +up_threshold: defines what the average CPU usaged between the samplings +of 'sampling_rate' needs to be for the kernel to make a decision on +whether it should increase the frequency. For example when it is set +to its default value of '80' it means that between the checking +intervals the CPU needs to be on average more than 80% in use to then +decide that the CPU frequency needs to be increased. + +sampling_down_factor: this parameter controls the rate that the CPU +makes a decision on when to decrease the frequency. When set to its +default value of '5' it means that at 1/5 the sampling_rate the kernel +makes a decision to lower the frequency. Five "lower rate" decisions +have to be made in a row before the CPU frequency is actually lower. +If set to '1' then the frequency decreases as quickly as it increases, +if set to '2' it decreases at half the rate of the increase. + +ignore_nice_load: this parameter takes a value of '0' or '1', when set +to '0' (its default) then all processes are counted towards towards the +'cpu utilisation' value. When set to '1' then processes that are +run with a 'nice' value will not count (and thus be ignored) in the +overal usage calculation. This is useful if you are running a CPU +intensive calculation on your laptop that you do not care how long it +takes to complete as you can 'nice' it and prevent it from taking part +in the deciding process of whether to increase your CPU frequency. + + +2.5 Conservative +---------------- + +The CPUfreq governor "conservative", much like the "ondemand" +governor, sets the CPU depending on the current usage. It differs in +behaviour in that it gracefully increases and decreases the CPU speed +rather than jumping to max speed the moment there is any load on the +CPU. This behaviour more suitable in a battery powered environment. +The governor is tweaked in the same manner as the "ondemand" governor +through sysfs with the addition of: + +freq_step: this describes what percentage steps the cpu freq should be +increased and decreased smoothly by. By default the cpu frequency will +increase in 5% chunks of your maximum cpu frequency. You can change this +value to anywhere between 0 and 100 where '0' will effectively lock your +CPU at a speed regardless of its load whilst '100' will, in theory, make +it behave identically to the "ondemand" governor. + +down_threshold: same as the 'up_threshold' found for the "ondemand" +governor but for the opposite direction. For example when set to its +default value of '20' it means that if the CPU usage needs to be below +20% between samples to have the frequency decreased. 3. The Governor Interface in the CPUfreq Core ============================================= diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index 9b743198f77..8ae8dad8e15 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -47,17 +47,6 @@ Who: Paul E. McKenney <paulmck@us.ibm.com> --------------------------- -What: IEEE1394 Audio and Music Data Transmission Protocol driver, - Connection Management Procedures driver -When: November 2005 -Files: drivers/ieee1394/{amdtp,cmp}* -Why: These are incomplete, have never worked, and are better implemented - in userland via raw1394 (see http://freebob.sourceforge.net/ for - example.) -Who: Jody McIntyre <scjody@steamballoon.com> - ---------------------------- - What: raw1394: requests of type RAW1394_REQ_ISO_SEND, RAW1394_REQ_ISO_LISTEN When: November 2005 Why: Deprecated in favour of the new ioctl-based rawiso interface, which is diff --git a/Documentation/filesystems/00-INDEX b/Documentation/filesystems/00-INDEX index bcfbab899b3..74052d22d86 100644 --- a/Documentation/filesystems/00-INDEX +++ b/Documentation/filesystems/00-INDEX @@ -12,14 +12,16 @@ cifs.txt - description of the CIFS filesystem coda.txt - description of the CODA filesystem. +configfs/ + - directory containing configfs documentation and example code. cramfs.txt - info on the cram filesystem for small storage (ROMs etc) devfs/ - directory containing devfs documentation. +dlmfs.txt + - info on the userspace interface to the OCFS2 DLM. ext2.txt - info, mount options and specifications for the Ext2 filesystem. -fat_cvf.txt - - info on the Compressed Volume Files extension to the FAT filesystem hpfs.txt - info and mount options for the OS/2 HPFS. isofs.txt @@ -32,6 +34,8 @@ ntfs.txt - info and mount options for the NTFS filesystem (Windows NT). proc.txt - info on Linux's /proc filesystem. +ocfs2.txt + - info and mount options for the OCFS2 clustered filesystem. romfs.txt - Description of the ROMFS filesystem. smbfs.txt diff --git a/Documentation/filesystems/configfs/configfs.txt b/Documentation/filesystems/configfs/configfs.txt new file mode 100644 index 00000000000..c4ff96b7c4e --- /dev/null +++ b/Documentation/filesystems/configfs/configfs.txt @@ -0,0 +1,434 @@ + +configfs - Userspace-driven kernel object configuation. + +Joel Becker <joel.becker@oracle.com> + +Updated: 31 March 2005 + +Copyright (c) 2005 Oracle Corporation, + Joel Becker <joel.becker@oracle.com> + + +[What is configfs?] + +configfs is a ram-based filesystem that provides the converse of +sysfs's functionality. Where sysfs is a filesystem-based view of +kernel objects, configfs is a filesystem-based manager of kernel +objects, or config_items. + +With sysfs, an object is created in kernel (for example, when a device +is discovered) and it is registered with sysfs. Its attributes then +appear in sysfs, allowing userspace to read the attributes via +readdir(3)/read(2). It may allow some attributes to be modified via +write(2). The important point is that the object is created and +destroyed in kernel, the kernel controls the lifecycle of the sysfs +representation, and sysfs is merely a window on all this. + +A configfs config_item is created via an explicit userspace operation: +mkdir(2). It is destroyed via rmdir(2). The attributes appear at +mkdir(2) time, and can be read or modified via read(2) and write(2). +As with sysfs, readdir(3) queries the list of items and/or attributes. +symlink(2) can be used to group items together. Unlike sysfs, the +lifetime of the representation is completely driven by userspace. The +kernel modules backing the items must respond to this. + +Both sysfs and configfs can and should exist together on the same +system. One is not a replacement for the other. + +[Using configfs] + +configfs can be compiled as a module or into the kernel. You can access +it by doing + + mount -t configfs none /config + +The configfs tree will be empty unless client modules are also loaded. +These are modules that register their item types with configfs as +subsystems. Once a client subsystem is loaded, it will appear as a +subdirectory (or more than one) under /config. Like sysfs, the +configfs tree is always there, whether mounted on /config or not. + +An item is created via mkdir(2). The item's attributes will also +appear at this time. readdir(3) can determine what the attributes are, +read(2) can query their default values, and write(2) can store new +values. Like sysfs, attributes should be ASCII text files, preferably +with only one value per file. The same efficiency caveats from sysfs +apply. Don't mix more than one attribute in one attribute file. + +Like sysfs, configfs expects write(2) to store the entire buffer at +once. When writing to configfs attributes, userspace processes should +first read the entire file, modify the portions they wish to change, and +then write the entire buffer back. Attribute files have a maximum size +of one page (PAGE_SIZE, 4096 on i386). + +When an item needs to be destroyed, remove it with rmdir(2). An +item cannot be destroyed if any other item has a link to it (via +symlink(2)). Links can be removed via unlink(2). + +[Configuring FakeNBD: an Example] + +Imagine there's a Network Block Device (NBD) driver that allows you to +access remote block devices. Call it FakeNBD. FakeNBD uses configfs +for its configuration. Obviously, there will be a nice program that +sysadmins use to configure FakeNBD, but somehow that program has to tell +the driver about it. Here's where configfs comes in. + +When the FakeNBD driver is loaded, it registers itself with configfs. +readdir(3) sees this just fine: + + # ls /config + fakenbd + +A fakenbd connection can be created with mkdir(2). The name is +arbitrary, but likely the tool will make some use of the name. Perhaps +it is a uuid or a disk name: + + # mkdir /config/fakenbd/disk1 + # ls /config/fakenbd/disk1 + target device rw + +The target attribute contains the IP address of the server FakeNBD will +connect to. The device attribute is the device on the server. +Predictably, the rw attribute determines whether the connection is +read-only or read-write. + + # echo 10.0.0.1 > /config/fakenbd/disk1/target + # echo /dev/sda1 > /config/fakenbd/disk1/device + # echo 1 > /config/fakenbd/disk1/rw + +That's it. That's all there is. Now the device is configured, via the +shell no less. + +[Coding With configfs] + +Every object in configfs is a config_item. A config_item reflects an +object in the subsystem. It has attributes that match values on that +object. configfs handles the filesystem representation of that object +and its attributes, allowing the subsystem to ignore all but the +basic show/store interaction. + +Items are created and destroyed inside a config_group. A group is a +collection of items that share the same attributes and operations. +Items are created by mkdir(2) and removed by rmdir(2), but configfs +handles that. The group has a set of operations to perform these tasks + +A subsystem is the top level of a client module. During initialization, +the client module registers the subsystem with configfs, the subsystem +appears as a directory at the top of the configfs filesystem. A +subsystem is also a config_group, and can do everything a config_group +can. + +[struct config_item] + + struct config_item { + char *ci_name; + char ci_namebuf[UOBJ_NAME_LEN]; + struct kref ci_kref; + struct list_head ci_entry; + struct config_item *ci_parent; + struct config_group *ci_group; + struct config_item_type *ci_type; + struct dentry *ci_dentry; + }; + + void config_item_init(struct config_item *); + void config_item_init_type_name(struct config_item *, + const char *name, + struct config_item_type *type); + struct config_item *config_item_get(struct config_item *); + void config_item_put(struct config_item *); + +Generally, struct config_item is embedded in a container structure, a +structure that actually represents what the subsystem is doing. The +config_item portion of that structure is how the object interacts with +configfs. + +Whether statically defined in a source file or created by a parent +config_group, a config_item must have one of the _init() functions +called on it. This initializes the reference count and sets up the +appropriate fields. + +All users of a config_item should have a reference on it via +config_item_get(), and drop the reference when they are done via +config_item_put(). + +By itself, a config_item cannot do much more than appear in configfs. +Usually a subsystem wants the item to display and/or store attributes, +among other things. For that, it needs a type. + +[struct config_item_type] + + struct configfs_item_operations { + void (*release)(struct config_item *); + ssize_t (*show_attribute)(struct config_item *, + struct configfs_attribute *, + char *); + ssize_t (*store_attribute)(struct config_item *, + struct configfs_attribute *, + const char *, size_t); + int (*allow_link)(struct config_item *src, + struct config_item *target); + int (*drop_link)(struct config_item *src, + struct config_item *target); + }; + + struct config_item_type { + struct module *ct_owner; + struct configfs_item_operations *ct_item_ops; + struct configfs_group_operations *ct_group_ops; + struct configfs_attribute **ct_attrs; + }; + +The most basic function of a config_item_type is to define what +operations can be performed on a config_item. All items that have been +allocated dynamically will need to provide the ct_item_ops->release() +method. This method is called when the config_item's reference count +reaches zero. Items that wish to display an attribute need to provide +the ct_item_ops->show_attribute() method. Similarly, storing a new +attribute value uses the store_attribute() method. + +[struct configfs_attribute] + + struct configfs_attribute { + char *ca_name; + struct module *ca_owner; + mode_t ca_mode; + }; + +When a config_item wants an attribute to appear as a file in the item's +configfs directory, it must define a configfs_attribute describing it. +It then adds the attribute to the NULL-terminated array +config_item_type->ct_attrs. When the item appears in configfs, the +attribute file will appear with the configfs_attribute->ca_name +filename. configfs_attribute->ca_mode specifies the file permissions. + +If an attribute is readable and the config_item provides a +ct_item_ops->show_attribute() method, that method will be called +whenever userspace asks for a read(2) on the attribute. The converse +will happen for write(2). + +[struct config_group] + +A config_item cannot live in a vaccum. The only way one can be created +is via mkdir(2) on a config_group. This will trigger creation of a +child item. + + struct config_group { + struct config_item cg_item; + struct list_head cg_children; + struct configfs_subsystem *cg_subsys; + struct config_group **default_groups; + }; + + void config_group_init(struct config_group *group); + void config_group_init_type_name(struct config_group *group, + const char *name, + struct config_item_type *type); + + +The config_group structure contains a config_item. Properly configuring +that item means that a group can behave as an item in its own right. +However, it can do more: it can create child items or groups. This is +accomplished via the group operations specified on the group's +config_item_type. + + struct configfs_group_operations { + struct config_item *(*make_item)(struct config_group *group, + const char *name); + struct config_group *(*make_group)(struct config_group *group, + const char *name); + int (*commit_item)(struct config_item *item); + void (*drop_item)(struct config_group *group, + struct config_item *item); + }; + +A group creates child items by providing the +ct_group_ops->make_item() method. If provided, this method is called from mkdir(2) in the group's directory. The subsystem allocates a new +config_item (or more likely, its container structure), initializes it, +and returns it to configfs. Configfs will then populate the filesystem +tree to reflect the new item. + +If the subsystem wants the child to be a group itself, the subsystem +provides ct_group_ops->make_group(). Everything else behaves the same, +using the group _init() functions on the group. + +Finally, when userspace calls rmdir(2) on the item or group, +ct_group_ops->drop_item() is called. As a config_group is also a +config_item, it is not necessary for a seperate drop_group() method. +The subsystem must config_item_put() the reference that was initialized +upon item allocation. If a subsystem has no work to do, it may omit +the ct_group_ops->drop_item() method, and configfs will call +config_item_put() on the item on behalf of the subsystem. + +IMPORTANT: drop_item() is void, and as such cannot fail. When rmdir(2) +is called, configfs WILL remove the item from the filesystem tree +(assuming that it has no children to keep it busy). The subsystem is +responsible for responding to this. If the subsystem has references to +the item in other threads, the memory is safe. It may take some time +for the item to actually disappear from the subsystem's usage. But it +is gone from configfs. + +A config_group cannot be removed while it still has child items. This +is implemented in the configfs rmdir(2) code. ->drop_item() will not be +called, as the item has not been dropped. rmdir(2) will fail, as the +directory is not empty. + +[struct configfs_subsystem] + +A subsystem must register itself, ususally at module_init time. This +tells configfs to make the subsystem appear in the file tree. + + struct configfs_subsystem { + struct config_group su_group; + struct semaphore su_sem; + }; + + int configfs_register_subsystem(struct configfs_subsystem *subsys); + void configfs_unregister_subsystem(struct configfs_subsystem *subsys); + + A subsystem consists of a toplevel config_group and a semaphore. +The group is where child config_items are created. For a subsystem, +this group is usually defined statically. Before calling +configfs_register_subsystem(), the subsystem must have initialized the +group via the usual group _init() functions, and it must also have +initialized the semaphore. + When the register call returns, the subsystem is live, and it +will be visible via configfs. At that point, mkdir(2) can be called and +the subsystem must be ready for it. + +[An Example] + +The best example of these basic concepts is the simple_children +subsystem/group and the simple_child item in configfs_example.c It +shows a trivial object displaying and storing an attribute, and a simple +group creating and destroying these children. + +[Hierarchy Navigation and the Subsystem Semaphore] + +There is an extra bonus that configfs provides. The config_groups and +config_items are arranged in a hierarchy due to the fact that they +appear in a filesystem. A subsystem is NEVER to touch the filesystem +parts, but the subsystem might be interested in this hierarchy. For +this reason, the hierarchy is mirrored via the config_group->cg_children +and config_item->ci_parent structure members. + +A subsystem can navigate the cg_children list and the ci_parent pointer +to see the tree created by the subsystem. This can race with configfs' +management of the hierarchy, so configfs uses the subsystem semaphore to +protect modifications. Whenever a subsystem wants to navigate the +hierarchy, it must do so under the protection of the subsystem +semaphore. + +A subsystem will be prevented from acquiring the semaphore while a newly +allocated item has not been linked into this hierarchy. Similarly, it +will not be able to acquire the semaphore while a dropping item has not +yet been unlinked. This means that an item's ci_parent pointer will +never be NULL while the item is in configfs, and that an item will only +be in its parent's cg_children list for the same duration. This allows +a subsystem to trust ci_parent and cg_children while they hold the +semaphore. + +[Item Aggregation Via symlink(2)] + +configfs provides a simple group via the group->item parent/child +relationship. Often, however, a larger environment requires aggregation +outside of the parent/child connection. This is implemented via +symlink(2). + +A config_item may provide the ct_item_ops->allow_link() and +ct_item_ops->drop_link() methods. If the ->allow_link() method exists, +symlink(2) may be called with the config_item as the source of the link. +These links are only allowed between configfs config_items. Any +symlink(2) attempt outside the configfs filesystem will be denied. + +When symlink(2) is called, the source config_item's ->allow_link() +method is called with itself and a target item. If the source item +allows linking to target item, it returns 0. A source item may wish to +reject a link if it only wants links to a certain type of object (say, +in its own subsystem). + +When unlink(2) is called on the symbolic link, the source item is +notified via the ->drop_link() method. Like the ->drop_item() method, +this is a void function and cannot return failure. The subsystem is +responsible for responding to the change. + +A config_item cannot be removed while it links to any other item, nor +can it be removed while an item links to it. Dangling symlinks are not +allowed in configfs. + +[Automatically Created Subgroups] + +A new config_group may want to have two types of child config_items. +While this could be codified by magic names in ->make_item(), it is much +more explicit to have a method whereby userspace sees this divergence. + +Rather than have a group where some items behave differently than +others, configfs provides a method whereby one or many subgroups are +automatically created inside the parent at its creation. Thus, +mkdir("parent) results in "parent", "parent/subgroup1", up through +"parent/subgroupN". Items of type 1 can now be created in +"parent/subgroup1", and items of type N can be created in +"parent/subgroupN". + +These automatic subgroups, or default groups, do not preclude other +children of the parent group. If ct_group_ops->make_group() exists, +other child groups can be created on the parent group directly. + +A configfs subsystem specifies default groups by filling in the +NULL-terminated array default_groups on the config_group structure. +Each group in that array is populated in the configfs tree at the same +time as the parent group. Similarly, they are removed at the same time +as the parent. No extra notification is provided. When a ->drop_item() +method call notifies the subsystem the parent group is going away, it +also means every default group child associated with that parent group. + +As a consequence of this, default_groups cannot be removed directly via +rmdir(2). They also are not considered when rmdir(2) on the parent +group is checking for children. + +[Committable Items] + +NOTE: Committable items are currently unimplemented. + +Some config_items cannot have a valid initial state. That is, no +default values can be specified for the item's attributes such that the +item can do its work. Userspace must configure one or more attributes, +after which the subsystem can start whatever entity this item +represents. + +Consider the FakeNBD device from above. Without a target address *and* +a target device, the subsystem has no idea what block device to import. +The simple example assumes that the subsystem merely waits until all the +appropriate attributes are configured, and then connects. This will, +indeed, work, but now every attribute store must check if the attributes +are initialized. Every attribute store must fire off the connection if +that condition is met. + +Far better would be an explicit action notifying the subsystem that the +config_item is ready to go. More importantly, an explicit action allows +the subsystem to provide feedback as to whether the attibutes are +initialized in a way that makes sense. configfs provides this as +committable items. + +configfs still uses only normal filesystem operations. An item is +committed via rename(2). The item is moved from a directory where it +can be modified to a directory where it cannot. + +Any group that provides the ct_group_ops->commit_item() method has +committable items. When this group appears in configfs, mkdir(2) will +not work directly in the group. Instead, the group will have two +subdirectories: "live" and "pending". The "live" directory does not +support mkdir(2) or rmdir(2) either. It only allows rename(2). The +"pending" directory does allow mkdir(2) and rmdir(2). An item is +created in the "pending" directory. Its attributes can be modified at +will. Userspace commits the item by renaming it into the "live" +directory. At this point, the subsystem recieves the ->commit_item() +callback. If all required attributes are filled to satisfaction, the +method returns zero and the item is moved to the "live" directory. + +As rmdir(2) does not work in the "live" directory, an item must be +shutdown, or "uncommitted". Again, this is done via rename(2), this +time from the "live" directory back to the "pending" one. The subsystem +is notified by the ct_group_ops->uncommit_object() method. + + diff --git a/Documentation/filesystems/configfs/configfs_example.c b/Documentation/filesystems/configfs/configfs_example.c new file mode 100644 index 00000000000..f3c6e4946f9 --- /dev/null +++ b/Documentation/filesystems/configfs/configfs_example.c @@ -0,0 +1,474 @@ +/* + * vim: noexpandtab ts=8 sts=0 sw=8: + * + * configfs_example.c - This file is a demonstration module containing + * a number of configfs subsystems. + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public + * License as published by the Free Software Foundation; either + * version 2 of the License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * General Public License for more details. + * + * You should have received a copy of the GNU General Public + * License along with this program; if not, write to the + * Free Software Foundation, Inc., 59 Temple Place - Suite 330, + * Boston, MA 021110-1307, USA. + * + * Based on sysfs: + * sysfs is Copyright (C) 2001, 2002, 2003 Patrick Mochel + * + * configfs Copyright (C) 2005 Oracle. All rights reserved. + */ + +#include <linux/init.h> +#include <linux/module.h> +#include <linux/slab.h> + +#include <linux/configfs.h> + + + +/* + * 01-childless + * + * This first example is a childless subsystem. It cannot create + * any config_items. It just has attributes. + * + * Note that we are enclosing the configfs_subsystem inside a container. + * This is not necessary if a subsystem has no attributes directly + * on the subsystem. See the next example, 02-simple-children, for + * such a subsystem. + */ + +struct childless { + struct configfs_subsystem subsys; + int showme; + int storeme; +}; + +struct childless_attribute { + struct configfs_attribute attr; + ssize_t (*show)(struct childless *, char *); + ssize_t (*store)(struct childless *, const char *, size_t); +}; + +static inline struct childless *to_childless(struct config_item *item) +{ + return item ? container_of(to_configfs_subsystem(to_config_group(item)), struct childless, subsys) : NULL; +} + +static ssize_t childless_showme_read(struct childless *childless, + char *page) +{ + ssize_t pos; + + pos = sprintf(page, "%d\n", childless->showme); + childless->showme++; + + return pos; +} + +static ssize_t childless_storeme_read(struct childless *childless, + char *page) +{ + return sprintf(page, "%d\n", childless->storeme); +} + +static ssize_t childless_storeme_write(struct childless *childless, + const char *page, + size_t count) +{ + unsigned long tmp; + char *p = (char *) page; + + tmp = simple_strtoul(p, &p, 10); + if (!p || (*p && (*p != '\n'))) + return -EINVAL; + + if (tmp > INT_MAX) + return -ERANGE; + + childless->storeme = tmp; + + return count; +} + +static ssize_t childless_description_read(struct childless *childless, + char *page) +{ + return sprintf(page, +"[01-childless]\n" +"\n" +"The childless subsystem is the simplest possible subsystem in\n" +"configfs. It does not support the creation of child config_items.\n" +"It only has a few attributes. In fact, it isn't much different\n" +"than a directory in /proc.\n"); +} + +static struct childless_attribute childless_attr_showme = { + .attr = { .ca_owner = THIS_MODULE, .ca_name = "showme", .ca_mode = S_IRUGO }, + .show = childless_showme_read, +}; +static struct childless_attribute childless_attr_storeme = { + .attr = { .ca_owner = THIS_MODULE, .ca_name = "storeme", .ca_mode = S_IRUGO | S_IWUSR }, + .show = childless_storeme_read, + .store = childless_storeme_write, +}; +static struct childless_attribute childless_attr_description = { + .attr = { .ca_owner = THIS_MODULE, .ca_name = "description", .ca_mode = S_IRUGO }, + .show = childless_description_read, +}; + +static struct configfs_attribute *childless_attrs[] = { + &childless_attr_showme.attr, + &childless_attr_storeme.attr, + &childless_attr_description.attr, + NULL, +}; + +static ssize_t childless_attr_show(struct config_item *item, + struct configfs_attribute *attr, + char *page) +{ + struct childless *childless = to_childless(item); + struct childless_attribute *childless_attr = + container_of(attr, struct childless_attribute, attr); + ssize_t ret = 0; + + if (childless_attr->show) + ret = childless_attr->show(childless, page); + return ret; +} + +static ssize_t childless_attr_store(struct config_item *item, + struct configfs_attribute *attr, + const char *page, size_t count) +{ + struct childless *childless = to_childless(item); + struct childless_attribute *childless_attr = + container_of(attr, struct childless_attribute, attr); + ssize_t ret = -EINVAL; + + if (childless_attr->store) + ret = childless_attr->store(childless, page, count); + return ret; +} + +static struct configfs_item_operations childless_item_ops = { + .show_attribute = childless_attr_show, + .store_attribute = childless_attr_store, +}; + +static struct config_item_type childless_type = { + .ct_item_ops = &childless_item_ops, + .ct_attrs = childless_attrs, + .ct_owner = THIS_MODULE, +}; + +static struct childless childless_subsys = { + .subsys = { + .su_group = { + .cg_item = { + .ci_namebuf = "01-childless", + .ci_type = &childless_type, + }, + }, + }, +}; + + +/* ----------------------------------------------------------------- */ + +/* + * 02-simple-children + * + * This example merely has a simple one-attribute child. Note that + * there is no extra attribute structure, as the child's attribute is + * known from the get-go. Also, there is no container for the + * subsystem, as it has no attributes of its own. + */ + +struct simple_child { + struct config_item item; + int storeme; +}; + +static inline struct simple_child *to_simple_child(struct config_item *item) +{ + return item ? container_of(item, struct simple_child, item) : NULL; +} + +static struct configfs_attribute simple_child_attr_storeme = { + .ca_owner = THIS_MODULE, + .ca_name = "storeme", + .ca_mode = S_IRUGO | S_IWUSR, +}; + +static struct configfs_attribute *simple_child_attrs[] = { + &simple_child_attr_storeme, + NULL, +}; + +static ssize_t simple_child_attr_show(struct config_item *item, + struct configfs_attribute *attr, + char *page) +{ + ssize_t count; + struct simple_child *simple_child = to_simple_child(item); + + count = sprintf(page, "%d\n", simple_child->storeme); + + return count; +} + +static ssize_t simple_child_attr_store(struct config_item *item, + struct configfs_attribute *attr, + const char *page, size_t count) +{ + struct simple_child *simple_child = to_simple_child(item); + unsigned long tmp; + char *p = (char *) page; + + tmp = simple_strtoul(p, &p, 10); + if (!p || (*p && (*p != '\n'))) + return -EINVAL; + + if (tmp > INT_MAX) + return -ERANGE; + + simple_child->storeme = tmp; + + return count; +} + +static void simple_child_release(struct config_item *item) +{ + kfree(to_simple_child(item)); +} + +static struct configfs_item_operations simple_child_item_ops = { + .release = simple_child_release, + .show_attribute = simple_child_attr_show, + .store_attribute = simple_child_attr_store, +}; + +static struct config_item_type simple_child_type = { + .ct_item_ops = &simple_child_item_ops, + .ct_attrs = simple_child_attrs, + .ct_owner = THIS_MODULE, +}; + + +static struct config_item *simple_children_make_item(struct config_group *group, const char *name) +{ + struct simple_child *simple_child; + + simple_child = kmalloc(sizeof(struct simple_child), GFP_KERNEL); + if (!simple_child) + return NULL; + + memset(simple_child, 0, sizeof(struct simple_child)); + + config_item_init_type_name(&simple_child->item, name, + &simple_child_type); + + simple_child->storeme = 0; + + return &simple_child->item; +} + +static struct configfs_attribute simple_children_attr_description = { + .ca_owner = THIS_MODULE, + .ca_name = "description", + .ca_mode = S_IRUGO, +}; + +static struct configfs_attribute *simple_children_attrs[] = { + &simple_children_attr_description, + NULL, +}; + +static ssize_t simple_children_attr_show(struct config_item *item, + struct configfs_attribute *attr, + char *page) +{ + return sprintf(page, +"[02-simple-children]\n" +"\n" +"This subsystem allows the creation of child config_items. These\n" +"items have only one attribute that is readable and writeable.\n"); +} + +static struct configfs_item_operations simple_children_item_ops = { + .show_attribute = simple_children_attr_show, +}; + +/* + * Note that, since no extra work is required on ->drop_item(), + * no ->drop_item() is provided. + */ +static struct configfs_group_operations simple_children_group_ops = { + .make_item = simple_children_make_item, +}; + +static struct config_item_type simple_children_type = { + .ct_item_ops = &simple_children_item_ops, + .ct_group_ops = &simple_children_group_ops, + .ct_attrs = simple_children_attrs, +}; + +static struct configfs_subsystem simple_children_subsys = { + .su_group = { + .cg_item = { + .ci_namebuf = "02-simple-children", + .ci_type = &simple_children_type, + }, + }, +}; + + +/* ----------------------------------------------------------------- */ + +/* + * 03-group-children + * + * This example reuses the simple_children group from above. However, + * the simple_children group is not the subsystem itself, it is a + * child of the subsystem. Creation of a group in the subsystem creates + * a new simple_children group. That group can then have simple_child + * children of its own. + */ + +struct simple_children { + struct config_group group; +}; + +static struct config_group *group_children_make_group(struct config_group *group, const char *name) +{ + struct simple_children *simple_children; + + simple_children = kmalloc(sizeof(struct simple_children), + GFP_KERNEL); + if (!simple_children) + return NULL; + + memset(simple_children, 0, sizeof(struct simple_children)); + + config_group_init_type_name(&simple_children->group, name, + &simple_children_type); + + return &simple_children->group; +} + +static struct configfs_attribute group_children_attr_description = { + .ca_owner = THIS_MODULE, + .ca_name = "description", + .ca_mode = S_IRUGO, +}; + +static struct configfs_attribute *group_children_attrs[] = { + &group_children_attr_description, + NULL, +}; + +static ssize_t group_children_attr_show(struct config_item *item, + struct configfs_attribute *attr, + char *page) +{ + return sprintf(page, +"[03-group-children]\n" +"\n" +"This subsystem allows the creation of child config_groups. These\n" +"groups are like the subsystem simple-children.\n"); +} + +static struct configfs_item_operations group_children_item_ops = { + .show_attribute = group_children_attr_show, +}; + +/* + * Note that, since no extra work is required on ->drop_item(), + * no ->drop_item() is provided. + */ +static struct configfs_group_operations group_children_group_ops = { + .make_group = group_children_make_group, +}; + +static struct config_item_type group_children_type = { + .ct_item_ops = &group_children_item_ops, + .ct_group_ops = &group_children_group_ops, + .ct_attrs = group_children_attrs, +}; + +static struct configfs_subsystem group_children_subsys = { + .su_group = { + .cg_item = { + .ci_namebuf = "03-group-children", + .ci_type = &group_children_type, + }, + }, +}; + +/* ----------------------------------------------------------------- */ + +/* + * We're now done with our subsystem definitions. + * For convenience in this module, here's a list of them all. It + * allows the init function to easily register them. Most modules + * will only have one subsystem, and will only call register_subsystem + * on it directly. + */ +static struct configfs_subsystem *example_subsys[] = { + &childless_subsys.subsys, + &simple_children_subsys, + &group_children_subsys, + NULL, +}; + +static int __init configfs_example_init(void) +{ + int ret; + int i; + struct configfs_subsystem *subsys; + + for (i = 0; example_subsys[i]; i++) { + subsys = example_subsys[i]; + + config_group_init(&subsys->su_group); + init_MUTEX(&subsys->su_sem); + ret = configfs_register_subsystem(subsys); + if (ret) { + printk(KERN_ERR "Error %d while registering subsystem %s\n", + ret, + subsys->su_group.cg_item.ci_namebuf); + goto out_unregister; + } + } + + return 0; + +out_unregister: + for (; i >= 0; i--) { + configfs_unregister_subsystem(example_subsys[i]); + } + + return ret; +} + +static void __exit configfs_example_exit(void) +{ + int i; + + for (i = 0; example_subsys[i]; i++) { + configfs_unregister_subsystem(example_subsys[i]); + } +} + +module_init(configfs_example_init); +module_exit(configfs_example_exit); +MODULE_LICENSE("GPL"); diff --git a/Documentation/filesystems/dlmfs.txt b/Documentation/filesystems/dlmfs.txt new file mode 100644 index 00000000000..9afab845a90 --- /dev/null +++ b/Documentation/filesystems/dlmfs.txt @@ -0,0 +1,130 @@ +dlmfs +================== +A minimal DLM userspace interface implemented via a virtual file +system. + +dlmfs is built with OCFS2 as it requires most of its infrastructure. + +Project web page: http://oss.oracle.com/projects/ocfs2 +Tools web page: http://oss.oracle.com/projects/ocfs2-tools +OCFS2 mailing lists: http://oss.oracle.com/projects/ocfs2/mailman/ + +All code copyright 2005 Oracle except when otherwise noted. + +CREDITS +======= + +Some code taken from ramfs which is Copyright (C) 2000 Linus Torvalds +and Transmeta Corp. + +Mark Fasheh <mark.fasheh@oracle.com> + +Caveats +======= +- Right now it only works with the OCFS2 DLM, though support for other + DLM implementations should not be a major issue. + +Mount options +============= +None + +Usage +===== + +If you're just interested in OCFS2, then please see ocfs2.txt. The +rest of this document will be geared towards those who want to use +dlmfs for easy to setup and easy to use clustered locking in +userspace. + +Setup +===== + +dlmfs requires that the OCFS2 cluster infrastructure be in +place. Please download ocfs2-tools from the above url and configure a +cluster. + +You'll want to start heartbeating on a volume which all the nodes in +your lockspace can access. The easiest way to do this is via +ocfs2_hb_ctl (distributed with ocfs2-tools). Right now it requires +that an OCFS2 file system be in place so that it can automatically +find it's heartbeat area, though it will eventually support heartbeat +against raw disks. + +Please see the ocfs2_hb_ctl and mkfs.ocfs2 manual pages distributed +with ocfs2-tools. + +Once you're heartbeating, DLM lock 'domains' can be easily created / +destroyed and locks within them accessed. + +Locking +======= + +Users may access dlmfs via standard file system calls, or they can use +'libo2dlm' (distributed with ocfs2-tools) which abstracts the file +system calls and presents a more traditional locking api. + +dlmfs handles lock caching automatically for the user, so a lock +request for an already acquired lock will not generate another DLM +call. Userspace programs are assumed to handle their own local +locking. + +Two levels of locks are supported - Shared Read, and Exlcusive. +Also supported is a Trylock operation. + +For information on the libo2dlm interface, please see o2dlm.h, +distributed with ocfs2-tools. + +Lock value blocks can be read and written to a resource via read(2) +and write(2) against the fd obtained via your open(2) call. The +maximum currently supported LVB length is 64 bytes (though that is an +OCFS2 DLM limitation). Through this mechanism, users of dlmfs can share +small amounts of data amongst their nodes. + +mkdir(2) signals dlmfs to join a domain (which will have the same name +as the resulting directory) + +rmdir(2) signals dlmfs to leave the domain + +Locks for a given domain are represented by regular inodes inside the +domain directory. Locking against them is done via the open(2) system +call. + +The open(2) call will not return until your lock has been granted or +an error has occurred, unless it has been instructed to do a trylock +operation. If the lock succeeds, you'll get an fd. + +open(2) with O_CREAT to ensure the resource inode is created - dlmfs does +not automatically create inodes for existing lock resources. + +Open Flag Lock Request Type +--------- ----------------- +O_RDONLY Shared Read +O_RDWR Exclusive + +Open Flag Resulting Locking Behavior +--------- -------------------------- +O_NONBLOCK Trylock operation + +You must provide exactly one of O_RDONLY or O_RDWR. + +If O_NONBLOCK is also provided and the trylock operation was valid but +could not lock the resource then open(2) will return ETXTBUSY. + +close(2) drops the lock associated with your fd. + +Modes passed to mkdir(2) or open(2) are adhered to locally. Chown is +supported locally as well. This means you can use them to restrict +access to the resources via dlmfs on your local node only. + +The resource LVB may be read from the fd in either Shared Read or +Exclusive modes via the read(2) system call. It can be written via +write(2) only when open in Exclusive mode. + +Once written, an LVB will be visible to other nodes who obtain Read +Only or higher level locks on the resource. + +See Also +======== +http://opendlm.sourceforge.net/cvsmirror/opendlm/docs/dlmbook_final.pdf + +For more information on the VMS distributed locking API. diff --git a/Documentation/filesystems/ocfs2.txt b/Documentation/filesystems/ocfs2.txt new file mode 100644 index 00000000000..f2595caf052 --- /dev/null +++ b/Documentation/filesystems/ocfs2.txt @@ -0,0 +1,55 @@ +OCFS2 filesystem +================== +OCFS2 is a general purpose extent based shared disk cluster file +system with many similarities to ext3. It supports 64 bit inode +numbers, and has automatically extending metadata groups which may +also make it attractive for non-clustered use. + +You'll want to install the ocfs2-tools package in order to at least +get "mount.ocfs2" and "ocfs2_hb_ctl". + +Project web page: http://oss.oracle.com/projects/ocfs2 +Tools web page: http://oss.oracle.com/projects/ocfs2-tools +OCFS2 mailing lists: http://oss.oracle.com/projects/ocfs2/mailman/ + +All code copyright 2005 Oracle except when otherwise noted. + +CREDITS: +Lots of code taken from ext3 and other projects. + +Authors in alphabetical order: +Joel Becker <joel.becker@oracle.com> +Zach Brown <zach.brown@oracle.com> +Mark Fasheh <mark.fasheh@oracle.com> +Kurt Hackel <kurt.hackel@oracle.com> +Sunil Mushran <sunil.mushran@oracle.com> +Manish Singh <manish.singh@oracle.com> + +Caveats +======= +Features which OCFS2 does not support yet: + - sparse files + - extended attributes + - shared writeable mmap + - loopback is supported, but data written will not + be cluster coherent. + - quotas + - cluster aware flock + - Directory change notification (F_NOTIFY) + - Distributed Caching (F_SETLEASE/F_GETLEASE/break_lease) + - POSIX ACLs + - readpages / writepages (not user visible) + +Mount options +============= + +OCFS2 supports the following mount options: +(*) == default + +barrier=1 This enables/disables barriers. barrier=0 disables it, + barrier=1 enables it. +errors=remount-ro(*) Remount the filesystem read-only on an error. +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. diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt index ee4c0a8b8db..e56e842847d 100644 --- a/Documentation/filesystems/vfs.txt +++ b/Documentation/filesystems/vfs.txt @@ -162,9 +162,8 @@ get_sb() method fills in is the "s_op" field. This is a pointer to a "struct super_operations" which describes the next level of the filesystem implementation. -Usually, a filesystem uses generic one of the generic get_sb() -implementations and provides a fill_super() method instead. The -generic methods are: +Usually, a filesystem uses one of the generic get_sb() implementations +and provides a fill_super() method instead. The generic methods are: get_sb_bdev: mount a filesystem residing on a block device diff --git a/Documentation/kbuild/modules.txt b/Documentation/kbuild/modules.txt index c91caf7eb30..1c0db652b36 100644 --- a/Documentation/kbuild/modules.txt +++ b/Documentation/kbuild/modules.txt @@ -38,7 +38,7 @@ included in the kernel tree. What is covered within this file is mainly information to authors of modules. The author of an external modules should supply a makefile that hides most of the complexity so one only has to type -'make' to buld the module. A complete example will be present in +'make' to build the module. A complete example will be present in chapter ¤. Creating a kbuild file for an external module". @@ -69,7 +69,7 @@ when building an external module. --- 2.2 Available targets - $KDIR refers to path to kernel source top-level directory + $KDIR refers to the path to the kernel source top-level directory make -C $KDIR M=`pwd` Will build the module(s) located in current directory. @@ -87,11 +87,11 @@ when building an external module. make -C $KDIR M=$PWD modules_install Install the external module(s). Installation default is in /lib/modules/<kernel-version>/extra, - but may be prefixed with INSTALL_MOD_PATH - see separate chater. + but may be prefixed with INSTALL_MOD_PATH - see separate chapter. make -C $KDIR M=$PWD clean Remove all generated files for the module - the kernel - source directory is not moddified. + source directory is not modified. make -C $KDIR M=`pwd` help help will list the available target when building external @@ -99,7 +99,7 @@ when building an external module. --- 2.3 Available options: - $KDIR refer to path to kernel src + $KDIR refers to the path to the kernel source top-level directory make -C $KDIR Used to specify where to find the kernel source. @@ -206,11 +206,11 @@ following files: KERNELDIR := /lib/modules/`uname -r`/build all:: - $(MAKE) -C $KERNELDIR M=`pwd` $@ + $(MAKE) -C $(KERNELDIR) M=`pwd` $@ # Module specific targets genbin: - echo "X" > 8123_bini.o_shipped + echo "X" > 8123_bin.o_shipped endif @@ -341,13 +341,13 @@ directory and therefore needs to deal with this in their kbuild file. EXTRA_CFLAGS := -Iinclude 8123-y := 8123_if.o 8123_pci.o 8123_bin.o - Note that in the assingment there is no space between -I and the path. - This is a kbuild limitation and no space must be present. + Note that in the assignment there is no space between -I and the path. + This is a kbuild limitation: there must be no space present. === 6. Module installation -Modules which are included in the kernel is installed in the directory: +Modules which are included in the kernel are installed in the directory: /lib/modules/$(KERNELRELEASE)/kernel @@ -365,7 +365,7 @@ External modules are installed in the directory: => Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel INSTALL_MOD_PATH may be set as an ordinary shell variable or as in the - example above be specified on the commandline when calling make. + example above be specified on the command line when calling make. INSTALL_MOD_PATH has effect both when installing modules included in the kernel as well as when installing external modules. @@ -384,7 +384,7 @@ External modules are installed in the directory: === 7. Module versioning -Module versioning are enabled by the CONFIG_MODVERSIONS tag. +Module versioning is enabled by the CONFIG_MODVERSIONS tag. Module versioning is used as a simple ABI consistency check. The Module versioning creates a CRC value of the full prototype for an exported symbol and diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 6e9f1dc2688..06e362b2d5b 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -633,6 +633,14 @@ running once the system is up. inport.irq= [HW] Inport (ATI XL and Microsoft) busmouse driver Format: <irq> + combined_mode= [HW] control which driver uses IDE ports in combined + mode: legacy IDE driver, libata, or both + (in the libata case, libata.atapi_enabled=1 may be + useful as well). Note that using the ide or libata + options may affect your device naming (e.g. by + changing hdc to sdb). + Format: combined (default), ide, or libata + inttest= [IA64] io7= [HW] IO7 for Marvel based alpha systems diff --git a/Documentation/keys.txt b/Documentation/keys.txt index 31154882000..6304db59bfe 100644 --- a/Documentation/keys.txt +++ b/Documentation/keys.txt @@ -860,24 +860,6 @@ The structure has a number of fields, some of which are mandatory: It is safe to sleep in this method. - (*) int (*duplicate)(struct key *key, const struct key *source); - - If this type of key can be duplicated, then this method should be - provided. It is called to copy the payload attached to the source into the - new key. The data length on the new key will have been updated and the - quota adjusted already. - - This method will be called with the source key's semaphore read-locked to - prevent its payload from being changed, thus RCU constraints need not be - applied to the source key. - - This method does not have to lock the destination key in order to attach a - payload. The fact that KEY_FLAG_INSTANTIATED is not set in key->flags - prevents anything else from gaining access to the key. - - It is safe to sleep in this method. - - (*) int (*update)(struct key *key, const void *data, size_t datalen); If this type of key can be updated, then this method should be provided. diff --git a/Documentation/md.txt b/Documentation/md.txt index 23e6cce40f9..03a13c462cf 100644 --- a/Documentation/md.txt +++ b/Documentation/md.txt @@ -51,6 +51,30 @@ superblock can be autodetected and run at boot time. The kernel parameter "raid=partitionable" (or "raid=part") means that all auto-detected arrays are assembled as partitionable. +Boot time assembly of degraded/dirty arrays +------------------------------------------- + +If a raid5 or raid6 array is both dirty and degraded, it could have +undetectable data corruption. This is because the fact that it is +'dirty' means that the parity cannot be trusted, and the fact that it +is degraded means that some datablocks are missing and cannot reliably +be reconstructed (due to no parity). + +For this reason, md will normally refuse to start such an array. This +requires the sysadmin to take action to explicitly start the array +desipite possible corruption. This is normally done with + mdadm --assemble --force .... + +This option is not really available if the array has the root +filesystem on it. In order to support this booting from such an +array, md supports a module parameter "start_dirty_degraded" which, +when set to 1, bypassed the checks and will allows dirty degraded +arrays to be started. + +So, to boot with a root filesystem of a dirty degraded raid[56], use + + md-mod.start_dirty_degraded=1 + Superblock formats ------------------ @@ -141,6 +165,70 @@ All md devices contain: in a fully functional array. If this is not yet known, the file will be empty. If an array is being resized (not currently possible) this will contain the larger of the old and new sizes. + Some raid level (RAID1) allow this value to be set while the + array is active. This will reconfigure the array. Otherwise + it can only be set while assembling an array. + + chunk_size + This is the size if bytes for 'chunks' and is only relevant to + raid levels that involve striping (1,4,5,6,10). The address space + of the array is conceptually divided into chunks and consecutive + chunks are striped onto neighbouring devices. + The size should be atleast PAGE_SIZE (4k) and should be a power + of 2. This can only be set while assembling an array + + component_size + For arrays with data redundancy (i.e. not raid0, linear, faulty, + multipath), all components must be the same size - or at least + there must a size that they all provide space for. This is a key + part or the geometry of the array. It is measured in sectors + and can be read from here. Writing to this value may resize + the array if the personality supports it (raid1, raid5, raid6), + and if the component drives are large enough. + + metadata_version + This indicates the format that is being used to record metadata + about the array. It can be 0.90 (traditional format), 1.0, 1.1, + 1.2 (newer format in varying locations) or "none" indicating that + the kernel isn't managing metadata at all. + + level + The raid 'level' for this array. The name will often (but not + always) be the same as the name of the module that implements the + level. To be auto-loaded the module must have an alias + md-$LEVEL e.g. md-raid5 + This can be written only while the array is being assembled, not + after it is started. + + new_dev + This file can be written but not read. The value written should + be a block device number as major:minor. e.g. 8:0 + This will cause that device to be attached to the array, if it is + available. It will then appear at md/dev-XXX (depending on the + name of the device) and further configuration is then possible. + + sync_speed_min + sync_speed_max + This are similar to /proc/sys/dev/raid/speed_limit_{min,max} + however they only apply to the particular array. + If no value has been written to these, of if the word 'system' + is written, then the system-wide value is used. If a value, + in kibibytes-per-second is written, then it is used. + When the files are read, they show the currently active value + followed by "(local)" or "(system)" depending on whether it is + a locally set or system-wide value. + + sync_completed + This shows the number of sectors that have been completed of + whatever the current sync_action is, followed by the number of + sectors in total that could need to be processed. The two + numbers are separated by a '/' thus effectively showing one + value, a fraction of the process that is complete. + + sync_speed + This shows the current actual speed, in K/sec, of the current + sync_action. It is averaged over the last 30 seconds. + As component devices are added to an md array, they appear in the 'md' directory as new directories named @@ -167,6 +255,38 @@ Each directory contains: of being recoverred to This list make grow in future. + errors + An approximate count of read errors that have been detected on + this device but have not caused the device to be evicted from + the array (either because they were corrected or because they + happened while the array was read-only). When using version-1 + metadata, this value persists across restarts of the array. + + This value can be written while assembling an array thus + providing an ongoing count for arrays with metadata managed by + userspace. + + slot + This gives the role that the device has in the array. It will + either be 'none' if the device is not active in the array + (i.e. is a spare or has failed) or an integer less than the + 'raid_disks' number for the array indicating which possition + it currently fills. This can only be set while assembling an + array. A device for which this is set is assumed to be working. + + offset + This gives the location in the device (in sectors from the + start) where data from the array will be stored. Any part of + the device before this offset us not touched, unless it is + used for storing metadata (Formats 1.1 and 1.2). + + size + The amount of the device, after the offset, that can be used + for storage of data. This will normally be the same as the + component_size. This can be written while assembling an + array. If a value less than the current component_size is + written, component_size will be reduced to this value. + An active md device will also contain and entry for each active device in the array. These are named diff --git a/Documentation/networking/gianfar.txt b/Documentation/networking/gianfar.txt new file mode 100644 index 00000000000..ad474ea07d0 --- /dev/null +++ b/Documentation/networking/gianfar.txt @@ -0,0 +1,72 @@ +The Gianfar Ethernet Driver +Sysfs File description + +Author: Andy Fleming <afleming@freescale.com> +Updated: 2005-07-28 + +SYSFS + +Several of the features of the gianfar driver are controlled +through sysfs files. These are: + +bd_stash: +To stash RX Buffer Descriptors in the L2, echo 'on' or '1' to +bd_stash, echo 'off' or '0' to disable + +rx_stash_len: +To stash the first n bytes of the packet in L2, echo the number +of bytes to buf_stash_len. echo 0 to disable. + +WARNING: You could really screw these up if you set them too low or high! +fifo_threshold: +To change the number of bytes the controller needs in the +fifo before it starts transmission, echo the number of bytes to +fifo_thresh. Range should be 0-511. + +fifo_starve: +When the FIFO has less than this many bytes during a transmit, it +enters starve mode, and increases the priority of TX memory +transactions. To change, echo the number of bytes to +fifo_starve. Range should be 0-511. + +fifo_starve_off: +Once in starve mode, the FIFO remains there until it has this +many bytes. To change, echo the number of bytes to +fifo_starve_off. Range should be 0-511. + +CHECKSUM OFFLOADING + +The eTSEC controller (first included in parts from late 2005 like +the 8548) has the ability to perform TCP, UDP, and IP checksums +in hardware. The Linux kernel only offloads the TCP and UDP +checksums (and always performs the pseudo header checksums), so +the driver only supports checksumming for TCP/IP and UDP/IP +packets. Use ethtool to enable or disable this feature for RX +and TX. + +VLAN + +In order to use VLAN, please consult Linux documentation on +configuring VLANs. The gianfar driver supports hardware insertion and +extraction of VLAN headers, but not filtering. Filtering will be +done by the kernel. + +MULTICASTING + +The gianfar driver supports using the group hash table on the +TSEC (and the extended hash table on the eTSEC) for multicast +filtering. On the eTSEC, the exact-match MAC registers are used +before the hash tables. See Linux documentation on how to join +multicast groups. + +PADDING + +The gianfar driver supports padding received frames with 2 bytes +to align the IP header to a 16-byte boundary, when supported by +hardware. + +ETHTOOL + +The gianfar driver supports the use of ethtool for many +configuration options. You must run ethtool only on currently +open interfaces. See ethtool documentation for details. diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index ebc09a159f6..2b7cf19a06a 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -46,6 +46,29 @@ ipfrag_secret_interval - INTEGER for the hash secret) for IP fragments. Default: 600 +ipfrag_max_dist - INTEGER + ipfrag_max_dist is a non-negative integer value which defines the + maximum "disorder" which is allowed among fragments which share a + common IP source address. Note that reordering of packets is + not unusual, but if a large number of fragments arrive from a source + IP address while a particular fragment queue remains incomplete, it + probably indicates that one or more fragments belonging to that queue + have been lost. When ipfrag_max_dist is positive, an additional check + is done on fragments before they are added to a reassembly queue - if + ipfrag_max_dist (or more) fragments have arrived from a particular IP + address between additions to any IP fragment queue using that source + address, it's presumed that one or more fragments in the queue are + lost. The existing fragment queue will be dropped, and a new one + started. An ipfrag_max_dist value of zero disables this check. + + Using a very small value, e.g. 1 or 2, for ipfrag_max_dist can + result in unnecessarily dropping fragment queues when normal + reordering of packets occurs, which could lead to poor application + performance. Using a very large value, e.g. 50000, increases the + likelihood of incorrectly reassembling IP fragments that originate + from different IP datagrams, which could result in data corruption. + Default: 64 + INET peer storage: inet_peer_threshold - INTEGER diff --git a/Documentation/pcmcia/driver-changes.txt b/Documentation/pcmcia/driver-changes.txt index 403e7b4dcdd..97420f08c78 100644 --- a/Documentation/pcmcia/driver-changes.txt +++ b/Documentation/pcmcia/driver-changes.txt @@ -1,5 +1,16 @@ This file details changes in 2.6 which affect PCMCIA card driver authors: +* Unify detach and REMOVAL event code, as well as attach and INSERTION + code (as of 2.6.16) + void (*remove) (struct pcmcia_device *dev); + int (*probe) (struct pcmcia_device *dev); + +* Move suspend, resume and reset out of event handler (as of 2.6.16) + int (*suspend) (struct pcmcia_device *dev); + int (*resume) (struct pcmcia_device *dev); + should be initialized in struct pcmcia_driver, and handle + (SUSPEND == RESET_PHYSICAL) and (RESUME == CARD_RESET) events + * event handler initialization in struct pcmcia_driver (as of 2.6.13) The event handler is notified of all events, and must be initialized as the event() callback in the driver's struct pcmcia_driver. diff --git a/Documentation/power/interface.txt b/Documentation/power/interface.txt index f5ebda5f427..bd4ffb5bd49 100644 --- a/Documentation/power/interface.txt +++ b/Documentation/power/interface.txt @@ -41,3 +41,14 @@ to. Writing to this file will accept one of It will only change to 'firmware' or 'platform' if the system supports it. +/sys/power/image_size controls the size of the image created by +the suspend-to-disk mechanism. It can be written a string +representing a non-negative integer that will be used as an upper +limit of the image size, in megabytes. The suspend-to-disk mechanism will +do its best to ensure the image size will not exceed that number. However, +if this turns out to be impossible, it will try to suspend anyway using the +smallest image possible. In particular, if "0" is written to this file, the +suspend image will be as small as possible. + +Reading from this file will display the current image size limit, which +is set to 500 MB by default. diff --git a/Documentation/power/swsusp.txt b/Documentation/power/swsusp.txt index b0d50840788..cd0fcd89a6f 100644 --- a/Documentation/power/swsusp.txt +++ b/Documentation/power/swsusp.txt @@ -27,6 +27,11 @@ echo shutdown > /sys/power/disk; echo disk > /sys/power/state echo platform > /sys/power/disk; echo disk > /sys/power/state +If you want to limit the suspend image size to N megabytes, do + +echo N > /sys/power/image_size + +before suspend (it is limited to 500 MB by default). Encrypted suspend image: ------------------------ diff --git a/Documentation/powerpc/eeh-pci-error-recovery.txt b/Documentation/powerpc/eeh-pci-error-recovery.txt index e75d7474322..67a11a36270 100644 --- a/Documentation/powerpc/eeh-pci-error-recovery.txt +++ b/Documentation/powerpc/eeh-pci-error-recovery.txt @@ -115,7 +115,7 @@ Current PPC64 Linux EEH Implementation At this time, a generic EEH recovery mechanism has been implemented, so that individual device drivers do not need to be modified to support EEH recovery. This generic mechanism piggy-backs on the PCI hotplug -infrastructure, and percolates events up through the hotplug/udev +infrastructure, and percolates events up through the userspace/udev infrastructure. Followiing is a detailed description of how this is accomplished. @@ -172,7 +172,7 @@ A handler for the EEH notifier_block events is implemented in drivers/pci/hotplug/pSeries_pci.c, called handle_eeh_events(). It saves the device BAR's and then calls rpaphp_unconfig_pci_adapter(). This last call causes the device driver for the card to be stopped, -which causes hotplug events to go out to user space. This triggers +which causes uevents to go out to user space. This triggers user-space scripts that might issue commands such as "ifdown eth0" for ethernet cards, and so on. This handler then sleeps for 5 seconds, hoping to give the user-space scripts enough time to complete. @@ -258,29 +258,30 @@ rpa_php_unconfig_pci_adapter() { // in rpaphp_pci.c calls pci_destroy_dev (struct pci_dev *) { calls - device_unregister (&dev->dev) { // in /drivers/base/core.c + device_unregister (&dev->dev) { // in /drivers/base/core.c calls - device_del(struct device * dev) { // in /drivers/base/core.c + device_del(struct device * dev) { // in /drivers/base/core.c calls - kobject_del() { //in /libs/kobject.c + kobject_del() { //in /libs/kobject.c calls - kobject_hotplug() { // in /libs/kobject.c + kobject_uevent() { // in /libs/kobject.c calls - kset_hotplug() { // in /lib/kobject.c + kset_uevent() { // in /lib/kobject.c calls - kset->hotplug_ops->hotplug() which is really just + kset->uevent_ops->uevent() // which is really just a call to - dev_hotplug() { // in /drivers/base/core.c + dev_uevent() { // in /drivers/base/core.c calls - dev->bus->hotplug() which is really just a call to - pci_hotplug () { // in drivers/pci/hotplug.c + dev->bus->uevent() which is really just a call to + pci_uevent () { // in drivers/pci/hotplug.c which prints device name, etc.... } } - then kset_hotplug() calls - call_usermodehelper () with - argv[0]=hotplug_path[] which is "/sbin/hotplug" - --> event to userspace, + then kobject_uevent() sends a netlink uevent to userspace + --> userspace uevent + (during early boot, nobody listens to netlink events and + kobject_uevent() executes uevent_helper[], which runs the + event process /sbin/hotplug) } } kobject_del() then calls sysfs_remove_dir(), which would diff --git a/Documentation/scsi/ChangeLog.megaraid b/Documentation/scsi/ChangeLog.megaraid index 5331d91432c..09f6300eda4 100644 --- a/Documentation/scsi/ChangeLog.megaraid +++ b/Documentation/scsi/ChangeLog.megaraid @@ -1,3 +1,38 @@ +Release Date : Fri Nov 11 12:27:22 EST 2005 - Seokmann Ju <sju@lsil.com> +Current Version : 2.20.4.7 (scsi module), 2.20.2.6 (cmm module) +Older Version : 2.20.4.6 (scsi module), 2.20.2.6 (cmm module) + +1. Sorted out PCI IDs to remove megaraid support overlaps. + Based on the patch from Daniel, sorted out PCI IDs along with + charactor node name change from 'megadev' to 'megadev_legacy' to avoid + conflict. + --- + Hopefully we'll be getting the build restriction zapped much sooner, + but we should also be thinking about totally removing the hardware + support overlap in the megaraid drivers. + + This patch pencils in a date of Feb 06 for this, and performs some + printk abuse in hope that existing legacy users might pick up on what's + going on. + + Signed-off-by: Daniel Drake <dsd@gentoo.org> + --- + +2. Fixed a issue: megaraid always fails to reset handler. + --- + I found that the megaraid driver always fails to reset the + adapter with the following message: + megaraid: resetting the host... + megaraid mbox: reset sequence completed successfully + megaraid: fast sync command timed out + megaraid: reservation reset failed + when the "Cluster mode" of the adapter BIOS is enabled. + So, whenever the reset occurs, the adapter goes to + offline and just become unavailable. + + Jun'ichi Nomura [mailto:jnomura@mtc.biglobe.ne.jp] + --- + Release Date : Mon Mar 07 12:27:22 EST 2005 - Seokmann Ju <sju@lsil.com> Current Version : 2.20.4.6 (scsi module), 2.20.2.6 (cmm module) Older Version : 2.20.4.5 (scsi module), 2.20.2.5 (cmm module) diff --git a/Documentation/scsi/scsi_mid_low_api.txt b/Documentation/scsi/scsi_mid_low_api.txt index 66565d42288..8bbae3e1abd 100644 --- a/Documentation/scsi/scsi_mid_low_api.txt +++ b/Documentation/scsi/scsi_mid_low_api.txt @@ -150,7 +150,8 @@ scsi devices of which only the first 2 respond: LLD mid level LLD ===-------------------=========--------------------===------ scsi_host_alloc() --> -scsi_add_host() --------+ +scsi_add_host() ----> +scsi_scan_host() -------+ | slave_alloc() slave_configure() --> scsi_adjust_queue_depth() @@ -196,7 +197,7 @@ of the issues involved. See the section on reference counting below. The hotplug concept may be extended to SCSI devices. Currently, when an -HBA is added, the scsi_add_host() function causes a scan for SCSI devices +HBA is added, the scsi_scan_host() function causes a scan for SCSI devices attached to the HBA's SCSI transport. On newer SCSI transports the HBA may become aware of a new SCSI device _after_ the scan has completed. An LLD can use this sequence to make the mid level aware of a SCSI device: @@ -372,7 +373,7 @@ names all start with "scsi_". Summary: scsi_activate_tcq - turn on tag command queueing scsi_add_device - creates new scsi device (lu) instance - scsi_add_host - perform sysfs registration and SCSI bus scan. + scsi_add_host - perform sysfs registration and set up transport class scsi_adjust_queue_depth - change the queue depth on a SCSI device scsi_assign_lock - replace default host_lock with given lock scsi_bios_ptable - return copy of block device's partition table @@ -386,6 +387,7 @@ Summary: scsi_remove_device - detach and remove a SCSI device scsi_remove_host - detach and remove all SCSI devices owned by host scsi_report_bus_reset - report scsi _bus_ reset observed + scsi_scan_host - scan SCSI bus scsi_track_queue_full - track successive QUEUE_FULL events scsi_unblock_requests - allow further commands to be queued to given host scsi_unregister - [calls scsi_host_put()] @@ -425,10 +427,10 @@ void scsi_activate_tcq(struct scsi_device *sdev, int depth) * Might block: yes * * Notes: This call is usually performed internally during a scsi - * bus scan when an HBA is added (i.e. scsi_add_host()). So it + * bus scan when an HBA is added (i.e. scsi_scan_host()). So it * should only be called if the HBA becomes aware of a new scsi - * device (lu) after scsi_add_host() has completed. If successful - * this call we lead to slave_alloc() and slave_configure() callbacks + * device (lu) after scsi_scan_host() has completed. If successful + * this call can lead to slave_alloc() and slave_configure() callbacks * into the LLD. * * Defined in: drivers/scsi/scsi_scan.c @@ -439,7 +441,7 @@ struct scsi_device * scsi_add_device(struct Scsi_Host *shost, /** - * scsi_add_host - perform sysfs registration and SCSI bus scan. + * scsi_add_host - perform sysfs registration and set up transport class * @shost: pointer to scsi host instance * @dev: pointer to struct device of type scsi class * @@ -448,7 +450,11 @@ struct scsi_device * scsi_add_device(struct Scsi_Host *shost, * Might block: no * * Notes: Only required in "hotplug initialization model" after a - * successful call to scsi_host_alloc(). + * successful call to scsi_host_alloc(). This function does not + * scan the bus; this can be done by calling scsi_scan_host() or + * in some other transport-specific way. The LLD must set up + * the transport template before calling this function and may only + * access the transport class data after this function has been called. * * Defined in: drivers/scsi/hosts.c **/ @@ -559,7 +565,7 @@ void scsi_deactivate_tcq(struct scsi_device *sdev, int depth) * area for the LLD's exclusive use. * Both associated refcounting objects have their refcount set to 1. * Full registration (in sysfs) and a bus scan are performed later when - * scsi_add_host() is called. + * scsi_add_host() and scsi_scan_host() are called. * * Defined in: drivers/scsi/hosts.c . **/ @@ -699,6 +705,19 @@ void scsi_report_bus_reset(struct Scsi_Host * shost, int channel) /** + * scsi_scan_host - scan SCSI bus + * @shost: a pointer to a scsi host instance + * + * Might block: yes + * + * Notes: Should be called after scsi_add_host() + * + * Defined in: drivers/scsi/scsi_scan.c + **/ +void scsi_scan_host(struct Scsi_Host *shost) + + +/** * scsi_track_queue_full - track successive QUEUE_FULL events on given * device to determine if and when there is a need * to adjust the queue depth on the device. @@ -1433,7 +1452,7 @@ The following people have contributed to this document: Christoph Hellwig <hch at infradead dot org> Doug Ledford <dledford at redhat dot com> Andries Brouwer <Andries dot Brouwer at cwi dot nl> - Randy Dunlap <rddunlap at osdl dot org> + Randy Dunlap <rdunlap at xenotime dot net> Alan Stern <stern at rowland dot harvard dot edu> diff --git a/Documentation/sound/alsa/ALSA-Configuration.txt b/Documentation/sound/alsa/ALSA-Configuration.txt index 2f27f391c7c..d2578013e82 100644 --- a/Documentation/sound/alsa/ALSA-Configuration.txt +++ b/Documentation/sound/alsa/ALSA-Configuration.txt @@ -105,7 +105,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Each of top level sound card module takes the following options. index - index (slot #) of sound card - - Values: 0 through 7 or negative + - Values: 0 through 31 or negative - If nonnegative, assign that index number - if negative, interpret as a bitmask of permissible indices; the first free permitted index is assigned @@ -134,7 +134,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. dma2 - second DMA # for AD1816A chip (PnP setup) clockfreq - Clock frequency for AD1816A chip (default = 0, 33000Hz) - Module supports up to 8 cards, autoprobe and PnP. + This module supports multiple cards, autoprobe and PnP. Module snd-ad1848 ----------------- @@ -145,9 +145,11 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. irq - IRQ # for AD1848 chip dma1 - DMA # for AD1848 chip (0,1,3) - Module supports up to 8 cards. This module does not support autoprobe + This module supports multiple cards. It does not support autoprobe thus main port must be specified!!! Other ports are optional. + The power-management is supported. + Module snd-ad1889 ----------------- @@ -156,7 +158,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. ac97_quirk - AC'97 workaround for strange hardware See the description of intel8x0 module for details. - This module supports up to 8 cards. + This module supports multiple cards. Module snd-ali5451 ------------------ @@ -184,7 +186,9 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. mpu_irq - IRQ # for MPU-401 (PnP setup) fm_port - port # for OPL3 FM (PnP setup) - Module supports up to 8 cards, autoprobe and PnP. + This module supports multiple cards, autoprobe and PnP. + + The power-management is supported. Module snd-als4000 ------------------ @@ -194,7 +198,9 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. joystick_port - port # for legacy joystick support. 0 = disabled (default), 1 = auto-detect - Module supports up to 8 cards, autoprobe and PnP. + This module supports multiple cards, autoprobe and PnP. + + The power-management is supported. Module snd-atiixp ----------------- @@ -213,6 +219,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. implementation depends on the motherboard, and you'll need to choose the correct one via spdif_aclink module option. + The power-management is supported. + Module snd-atiixp-modem ----------------------- @@ -223,6 +231,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Note: The default index value of this module is -2, i.e. the first slot is excluded. + The power-management is supported. + Module snd-au8810, snd-au8820, snd-au8830 ----------------------------------------- @@ -263,8 +273,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. dma1 - 1st DMA # for AZT2320 (WSS) chip (PnP setup) dma2 - 2nd DMA # for AZT2320 (WSS) chip (PnP setup) - Module supports up to 8 cards, PnP and autoprobe. + This module supports multiple cards, PnP and autoprobe. + The power-management is supported. + Module snd-azt3328 ------------------ @@ -272,7 +284,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. joystick - Enable joystick (default off) - Module supports up to 8 cards. + This module supports multiple cards. Module snd-bt87x ---------------- @@ -282,7 +294,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. digital_rate - Override the default digital rate (Hz) load_all - Load the driver even if the card model isn't known - Module supports up to 8 cards. + This module supports multiple cards. Note: The default index value of this module is -2, i.e. the first slot is excluded. @@ -292,7 +304,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for Creative Audigy LS and SB Live 24bit - Module supports up to 8 cards. + This module supports multiple cards. Module snd-cmi8330 @@ -308,7 +320,9 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. sbdma8 - 8bit DMA # for CMI8330 chip (SB16) sbdma16 - 16bit DMA # for CMI8330 chip (SB16) - Module supports up to 8 cards and autoprobe. + This module supports multiple cards and autoprobe. + + The power-management is supported. Module snd-cmipci ----------------- @@ -321,8 +335,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. (default = 1) joystick_port - Joystick port address (0 = disable, 1 = auto-detect) - Module supports autoprobe and multiple chips (max 8). + This module supports autoprobe and multiple cards. + The power-management is supported. + Module snd-cs4231 ----------------- @@ -335,7 +351,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. dma1 - first DMA # for CS4231 chip dma2 - second DMA # for CS4231 chip - Module supports up to 8 cards. This module does not support autoprobe + This module supports multiple cards. This module does not support autoprobe thus main port must be specified!!! Other ports are optional. The power-management is supported. @@ -355,7 +371,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. dma2 - second DMA # for Yamaha CS4232 chip (0,1,3), -1 = disable isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) - Module supports up to 8 cards. This module does not support autoprobe + This module supports multiple cards. This module does not support autoprobe thus main port must be specified!!! Other ports are optional. The power-management is supported. @@ -376,7 +392,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. dma2 - second DMA # for CS4236 chip (0,1,3), -1 = disable isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) - Module supports up to 8 cards. This module does not support autoprobe + This module supports multiple cards. This module does not support autoprobe (if ISA PnP is not used) thus main port and control port must be specified!!! Other ports are optional. @@ -389,7 +405,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. dual_codec - Secondary codec ID (0 = disable, default) - Module supports up to 8 cards. + This module supports multiple cards. The power-management is supported. @@ -403,13 +419,20 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. thinkpad - Force to enable Thinkpad's CLKRUN control. mmap_valid - Support OSS mmap mode (default = 0). - Module supports up to 8 cards and autoprobe. + This module supports multiple cards and autoprobe. Usually external amp and CLKRUN controls are detected automatically from PCI sub vendor/device ids. If they don't work, give the options above explicitly. The power-management is supported. + Module snd-cs5535audio + ---------------------- + + Module for multifunction CS5535 companion PCI device + + This module supports multiple cards. + Module snd-dt019x ----------------- @@ -423,9 +446,11 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. mpu_irq - IRQ # for MPU-401 (PnP setup) dma8 - DMA # (PnP setup) - Module supports up to 8 cards. This module is enabled only with + This module supports multiple cards. This module is enabled only with ISA PnP support. + The power-management is supported. + Module snd-dummy ---------------- @@ -433,6 +458,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. or input, but you may use this module for any application which requires a sound card (like RealPlayer). + The power-management is supported. + Module snd-emu10k1 ------------------ @@ -450,7 +477,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. given in MB unit. Default value is 128. enable_ir - enable IR - Module supports up to 8 cards and autoprobe. + This module supports multiple cards and autoprobe. Input & Output configurations [extin/extout] * Creative Card wo/Digital out [0x0003/0x1f03] @@ -466,12 +493,14 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. * Creative Card 5.1 (c) 2003 [0x3fc3/0x7cff] * Creative Card all ins and outs [0x3fff/0x7fff] + The power-management is supported. + Module snd-emu10k1x ------------------- Module for Creative Emu10k1X (SB Live Dell OEM version) - Module supports up to 8 cards. + This module supports multiple cards. Module snd-ens1370 ------------------ @@ -482,7 +511,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. joystick - Enable joystick (default off) - Module supports up to 8 cards and autoprobe. + This module supports multiple cards and autoprobe. Module snd-ens1371 ------------------ @@ -495,7 +524,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. joystick_port - port # for joystick (0x200,0x208,0x210,0x218), 0 = disable (default), 1 = auto-detect - Module supports up to 8 cards and autoprobe. + This module supports multiple cards and autoprobe. Module snd-es968 ---------------- @@ -506,8 +535,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. irq - IRQ # for ES968 (SB8) chip (PnP setup) dma1 - DMA # for ES968 (SB8) chip (PnP setup) - Module supports up to 8 cards, PnP and autoprobe. + This module supports multiple cards, PnP and autoprobe. + The power-management is supported. + Module snd-es1688 ----------------- @@ -519,7 +550,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. mpu_irq - IRQ # for MPU-401 port (5,7,9,10) dma8 - DMA # for ES-1688 chip (0,1,3) - Module supports up to 8 cards and autoprobe (without MPU-401 port). + This module supports multiple cards and autoprobe (without MPU-401 port). Module snd-es18xx ----------------- @@ -534,8 +565,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. dma2 - first DMA # for ES-18xx chip (0,1,3) isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) - Module supports up to 8 cards ISA PnP and autoprobe (without MPU-401 port - if native ISA PnP routines are not used). + This module supports multiple cards, ISA PnP and autoprobe (without MPU-401 + port if native ISA PnP routines are not used). When dma2 is equal with dma1, the driver works as half-duplex. The power-management is supported. @@ -545,7 +576,9 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for sound cards based on ESS Solo-1 (ES1938,ES1946) chips. - Module supports up to 8 cards and autoprobe. + This module supports multiple cards and autoprobe. + + The power-management is supported. Module snd-es1968 ----------------- @@ -561,7 +594,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. enable_mpu - enable MPU401 (0 = off, 1 = on, 2 = auto (default)) joystick - enable joystick (default off) - Module supports up to 8 cards and autoprobe. + This module supports multiple cards and autoprobe. The power-management is supported. @@ -577,8 +610,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. - High 16-bits are video (radio) device number + 1 - example: 0x10002 (MediaForte 256-PCPR, device 1) - Module supports up to 8 cards and autoprobe. + This module supports multiple cards and autoprobe. + The power-management is supported. + Module snd-gusclassic --------------------- @@ -592,7 +627,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. voices - GF1 voices limit (14-32) pcm_voices - reserved PCM voices - Module supports up to 8 cards and autoprobe. + This module supports multiple cards and autoprobe. Module snd-gusextreme --------------------- @@ -611,7 +646,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. voices - GF1 voices limit (14-32) pcm_voices - reserved PCM voices - Module supports up to 8 cards and autoprobe (without MPU-401 port). + This module supports multiple cards and autoprobe (without MPU-401 port). Module snd-gusmax ----------------- @@ -626,7 +661,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. voices - GF1 voices limit (14-32) pcm_voices - reserved PCM voices - Module supports up to 8 cards and autoprobe. + This module supports multiple cards and autoprobe. Module snd-hda-intel -------------------- @@ -688,12 +723,14 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. (Usually SD_LPLIB register is more accurate than the position buffer.) + The power-management is supported. + Module snd-hdsp --------------- Module for RME Hammerfall DSP audio interface(s) - Module supports up to 8 cards. + This module supports multiple cards. Note: The firmware data can be automatically loaded via hotplug when CONFIG_FW_LOADER is set. Otherwise, you need to load @@ -751,7 +788,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. cs8427_timeout - reset timeout for the CS8427 chip (S/PDIF transciever) in msec resolution, default value is 500 (0.5 sec) - Module supports up to 8 cards and autoprobe. Note: The consumer part + This module supports multiple cards and autoprobe. Note: The consumer part is not used with all Envy24 based cards (for example in the MidiMan Delta serie). @@ -787,7 +824,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. aureon71, universe, k8x800, phase22, phase28, ms300, av710 - Module supports up to 8 cards and autoprobe. + This module supports multiple cards and autoprobe. Note: The supported board is detected by reading EEPROM or PCI SSID (if EEPROM isn't available). You can override the @@ -839,6 +876,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Note: The default index value of this module is -2, i.e. the first slot is excluded. + The power-management is supported. + Module snd-interwave -------------------- @@ -855,7 +894,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. effect - 1 = InterWave effects enable (default 0); requires 8 voices - Module supports up to 8 cards, autoprobe and ISA PnP. + This module supports multiple cards, autoprobe and ISA PnP. Module snd-interwave-stb ------------------------ @@ -875,14 +914,14 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. effect - 1 = InterWave effects enable (default 0); requires 8 voices - Module supports up to 8 cards, autoprobe and ISA PnP. + This module supports multiple cards, autoprobe and ISA PnP. Module snd-korg1212 ------------------- Module for Korg 1212 IO PCI card - Module supports up to 8 cards. + This module supports multiple cards. Module snd-maestro3 ------------------- @@ -894,7 +933,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. -1 for default pin (8 for allegro, 1 for others) - Module supports autoprobe and multiple chips (max 8). + This module supports autoprobe and multiple chips. Note: the binding of amplifier is dependent on hardware. If there is no sound even though all channels are unmuted, try to @@ -909,7 +948,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for Digigram miXart8 sound cards. - Module supports multiple cards. + This module supports multiple cards. Note: One miXart8 board will be represented as 4 alsa cards. See MIXART.txt for details. @@ -928,7 +967,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. irq - IRQ number or -1 (disable) pnp - PnP detection - 0 = disable, 1 = enable (default) - Module supports multiple devices (max 8) and PnP. + This module supports multiple devices and PnP. Module snd-mtpav ---------------- @@ -1014,7 +1053,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. dma2 - second DMA # for Yamaha OPL3-SA chip (0,1,3), -1 = disable isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) - Module supports up to 8 cards and ISA PnP. This module does not support + This module supports multiple cards and ISA PnP. It does not support autoprobe (if ISA PnP is not used) thus all ports must be specified!!! The power-management is supported. @@ -1064,6 +1103,13 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. This module supports only one card, autoprobe and PnP. + Module snd-pcxhr + ---------------- + + Module for Digigram PCXHR boards + + This module supports multiple cards. + Module snd-powermac (on ppc only) --------------------------------- @@ -1084,20 +1130,22 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. For ARM architecture only. + The power-management is supported. + Module snd-rme32 ---------------- Module for RME Digi32, Digi32 Pro and Digi32/8 (Sek'd Prodif32, Prodif96 and Prodif Gold) sound cards. - Module supports up to 8 cards. + This module supports multiple cards. Module snd-rme96 ---------------- Module for RME Digi96, Digi96/8 and Digi96/8 PRO/PAD/PST sound cards. - Module supports up to 8 cards. + This module supports multiple cards. Module snd-rme9652 ------------------ @@ -1107,7 +1155,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. precise_ptr - Enable precise pointer (doesn't work reliably). (default = 0) - Module supports up to 8 cards. + This module supports multiple cards. Note: snd-page-alloc module does the job which snd-hammerfall-mem module did formerly. It will allocate the buffers in advance @@ -1124,6 +1172,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module supports only one card. Module has no enable and index options. + The power-management is supported. + Module snd-sb8 -------------- @@ -1135,8 +1185,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. irq - IRQ # for SB DSP chip (5,7,9,10) dma8 - DMA # for SB DSP chip (1,3) - Module supports up to 8 cards and autoprobe. + This module supports multiple cards and autoprobe. + The power-management is supported. + Module snd-sb16 and snd-sbawe ----------------------------- @@ -1155,7 +1207,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. csp - ASP/CSP chip support - 0 = disable (default), 1 = enable isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) - Module supports up to 8 cards, autoprobe and ISA PnP. + This module supports multiple cards, autoprobe and ISA PnP. Note: To use Vibra16X cards in 16-bit half duplex mode, you must disable 16bit DMA with dma16 = -1 module parameter. @@ -1163,6 +1215,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. half duplex mode through 8-bit DMA channel by disabling their 16-bit DMA channel. + The power-management is supported. + Module snd-sgalaxy ------------------ @@ -1173,7 +1227,9 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. irq - IRQ # (7,9,10,11) dma1 - DMA # - Module supports up to 8 cards. + This module supports multiple cards. + + The power-management is supported. Module snd-sscape ----------------- @@ -1185,7 +1241,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. mpu_irq - MPU-401 IRQ # (PnP setup) dma - DMA # (PnP setup) - Module supports up to 8 cards. ISA PnP must be enabled. + This module supports multiple cards. ISA PnP must be enabled. You need sscape_ctl tool in alsa-tools package for loading the microcode. @@ -1194,21 +1250,21 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for AMD7930 sound chips found on Sparcs. - Module supports up to 8 cards. + This module supports multiple cards. Module snd-sun-cs4231 (on sparc only) ------------------------------------- Module for CS4231 sound chips found on Sparcs. - Module supports up to 8 cards. + This module supports multiple cards. Module snd-sun-dbri (on sparc only) ----------------------------------- Module for DBRI sound chips found on Sparcs. - Module supports up to 8 cards. + This module supports multiple cards. Module snd-wavefront -------------------- @@ -1228,7 +1284,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. dma2 - DMA2 # for CS4232 PCM interface. isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) - Module supports up to 8 cards and ISA PnP. + This module supports multiple cards and ISA PnP. Module snd-sonicvibes --------------------- @@ -1240,7 +1296,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. - SoundCard must have onboard SRAM for this. mge - Mic Gain Enable - 1 = enable, 0 = disable (default) - Module supports up to 8 cards and autoprobe. + This module supports multiple cards and autoprobe. Module snd-serial-u16550 ------------------------ @@ -1259,7 +1315,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. 0 = Soundcanvas, 1 = MS-124T, 2 = MS-124W S/A, 3 = MS-124W M/B, 4 = Generic - Module supports up to 8 cards. This module does not support autoprobe + This module supports multiple cards. This module does not support autoprobe thus the main port must be specified!!! Other options are optional. Module snd-trident @@ -1278,7 +1334,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. pcm_channels - max channels (voices) reserved for PCM wavetable_size - max wavetable size in kB (4-?kb) - Module supports up to 8 cards and autoprobe. + This module supports multiple cards and autoprobe. The power-management is supported. @@ -1290,14 +1346,14 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. vid - Vendor ID for the device (optional) pid - Product ID for the device (optional) - This module supports up to 8 cards, autoprobe and hotplugging. + This module supports multiple devices, autoprobe and hotplugging. Module snd-usb-usx2y -------------------- Module for Tascam USB US-122, US-224 and US-428 devices. - This module supports up to 8 cards, autoprobe and hotplugging. + This module supports multiple devices, autoprobe and hotplugging. Note: you need to load the firmware via usx2yloader utility included in alsa-tools and alsa-firmware packages. @@ -1356,6 +1412,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Note: for the MPU401 on VIA823x, use snd-mpu401 driver additionally. The mpu_port option is for VIA686 chips only. + The power-management is supported. + Module snd-via82xx-modem ------------------------ @@ -1368,6 +1426,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Note: The default index value of this module is -2, i.e. the first slot is excluded. + The power-management is supported. + Module snd-virmidi ------------------ @@ -1375,9 +1435,9 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. This module creates virtual rawmidi devices which communicate to the corresponding ALSA sequencer ports. - midi_devs - MIDI devices # (1-8, default=4) + midi_devs - MIDI devices # (1-4, default=4) - Module supports up to 8 cards. + This module supports multiple cards. Module snd-vx222 ---------------- @@ -1387,7 +1447,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. mic - Enable Microphone on V222 Mic (NYI) ibl - Capture IBL size. (default = 0, minimum size) - Module supports up to 8 cards. + This module supports multiple cards. When the driver is compiled as a module and the hotplug firmware is supported, the firmware data is loaded via hotplug automatically. @@ -1406,6 +1466,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. size is chosen. The possible IBL values can be found in /proc/asound/cardX/vx-status proc file. + The power-management is supported. + Module snd-vxpocket ------------------- @@ -1413,7 +1475,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. ibl - Capture IBL size. (default = 0, minimum size) - Module supports up to 8 cards. The module is compiled only when + This module supports multiple cards. The module is compiled only when PCMCIA is supported on kernel. With the older 2.6.x kernel, to activate the driver via the card @@ -1434,6 +1496,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Note2: snd-vxp440 driver is merged to snd-vxpocket driver since ALSA 1.0.10. + The power-management is supported. + Module snd-ymfpci ----------------- @@ -1447,7 +1511,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. 1 (auto-detect) rear_switch - enable shared rear/line-in switch (bool) - Module supports autoprobe and multiple chips (max 8). + This module supports autoprobe and multiple chips. The power-management is supported. @@ -1458,6 +1522,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Note: the driver is build only when CONFIG_ISA is set. + The power-management is supported. + AC97 Quirk Option ================= @@ -1474,7 +1540,7 @@ the proper value with this option. The following strings are accepted: - default Don't override the default setting - - disable Disable the quirk + - none Disable the quirk - hp_only Bind Master and Headphone controls as a single control - swap_hp Swap headphone and master controls - swap_surround Swap master and surround controls diff --git a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl index 260334c98d9..4963d83d151 100644 --- a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl +++ b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl @@ -18,8 +18,8 @@ </affiliation> </author> - <date>October 6, 2005</date> - <edition>0.3.5</edition> + <date>November 17, 2005</date> + <edition>0.3.6</edition> <abstract> <para> @@ -403,9 +403,8 @@ static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP; /* definition of the chip-specific record */ - typedef struct snd_mychip mychip_t; - struct snd_mychip { - snd_card_t *card; + struct mychip { + struct snd_card *card; // rest of implementation will be in the section // "PCI Resource Managements" }; @@ -413,7 +412,7 @@ /* chip-specific destructor * (see "PCI Resource Managements") */ - static int snd_mychip_free(mychip_t *chip) + static int snd_mychip_free(struct mychip *chip) { .... // will be implemented later... } @@ -421,22 +420,21 @@ /* component-destructor * (see "Management of Cards and Components") */ - static int snd_mychip_dev_free(snd_device_t *device) + static int snd_mychip_dev_free(struct snd_device *device) { - mychip_t *chip = device->device_data; - return snd_mychip_free(chip); + return snd_mychip_free(device->device_data); } /* chip-specific constructor * (see "Management of Cards and Components") */ - static int __devinit snd_mychip_create(snd_card_t *card, + static int __devinit snd_mychip_create(struct snd_card *card, struct pci_dev *pci, - mychip_t **rchip) + struct mychip **rchip) { - mychip_t *chip; + struct mychip *chip; int err; - static snd_device_ops_t ops = { + static struct snd_device_ops ops = { .dev_free = snd_mychip_dev_free, }; @@ -474,8 +472,8 @@ const struct pci_device_id *pci_id) { static int dev; - snd_card_t *card; - mychip_t *chip; + struct snd_card *card; + struct mychip *chip; int err; /* (1) */ @@ -582,7 +580,7 @@ <informalexample> <programlisting> <![CDATA[ - snd_card_t *card; + struct snd_card *card; .... card = snd_card_new(index[dev], id[dev], THIS_MODULE, 0); ]]> @@ -605,7 +603,7 @@ <informalexample> <programlisting> <![CDATA[ - mychip_t *chip; + struct mychip *chip; .... if ((err = snd_mychip_create(card, pci, &chip)) < 0) { snd_card_free(card); @@ -806,7 +804,7 @@ <informalexample> <programlisting> <![CDATA[ - snd_card_t *card; + struct snd_card *card; card = snd_card_new(index, id, module, extra_size); ]]> </programlisting> @@ -830,7 +828,7 @@ <para> After the card is created, you can attach the components (devices) to the card instance. On ALSA driver, a component is - represented as a <type>snd_device_t</type> object. + represented as a struct <structname>snd_device</structname> object. A component can be a PCM instance, a control interface, a raw MIDI interface, etc. Each of such instances has one component entry. @@ -891,14 +889,11 @@ The chip-specific information, e.g. the i/o port address, its resource pointer, or the irq number, is stored in the chip-specific record. - Usually, the chip-specific record is typedef'ed as - <type>xxx_t</type> like the following: <informalexample> <programlisting> <![CDATA[ - typedef struct snd_mychip mychip_t; - struct snd_mychip { + struct mychip { .... }; ]]> @@ -918,12 +913,12 @@ <informalexample> <programlisting> <![CDATA[ - card = snd_card_new(index[dev], id[dev], THIS_MODULE, sizeof(mychip_t)); + card = snd_card_new(index[dev], id[dev], THIS_MODULE, sizeof(struct mychip)); ]]> </programlisting> </informalexample> - whether <type>mychip_t</type> is the type of the chip record. + whether struct <structname>mychip</structname> is the type of the chip record. </para> <para> @@ -932,7 +927,7 @@ <informalexample> <programlisting> <![CDATA[ - mychip_t *chip = (mychip_t *)card->private_data; + struct mychip *chip = (struct mychip *)card->private_data; ]]> </programlisting> </informalexample> @@ -954,8 +949,8 @@ <informalexample> <programlisting> <![CDATA[ - snd_card_t *card; - mychip_t *chip; + struct snd_card *card; + struct mychip *chip; card = snd_card_new(index[dev], id[dev], THIS_MODULE, NULL); ..... chip = kzalloc(sizeof(*chip), GFP_KERNEL); @@ -971,8 +966,8 @@ <informalexample> <programlisting> <![CDATA[ - struct snd_mychip { - snd_card_t *card; + struct mychip { + struct snd_card *card; .... }; ]]> @@ -1000,7 +995,7 @@ <informalexample> <programlisting> <![CDATA[ - static snd_device_ops_t ops = { + static struct snd_device_ops ops = { .dev_free = snd_mychip_dev_free, }; .... @@ -1018,10 +1013,9 @@ <informalexample> <programlisting> <![CDATA[ - static int snd_mychip_dev_free(snd_device_t *device) + static int snd_mychip_dev_free(struct snd_device *device) { - mychip_t *chip = device->device_data; - return snd_mychip_free(chip); + return snd_mychip_free(device->device_data); } ]]> </programlisting> @@ -1087,15 +1081,15 @@ <title>PCI Resource Managements Example</title> <programlisting> <![CDATA[ - struct snd_mychip { - snd_card_t *card; + struct mychip { + struct snd_card *card; struct pci_dev *pci; unsigned long port; int irq; }; - static int snd_mychip_free(mychip_t *chip) + static int snd_mychip_free(struct mychip *chip) { /* disable hardware here if any */ .... // (not implemented in this document) @@ -1113,13 +1107,13 @@ } /* chip-specific constructor */ - static int __devinit snd_mychip_create(snd_card_t *card, + static int __devinit snd_mychip_create(struct snd_card *card, struct pci_dev *pci, - mychip_t **rchip) + struct mychip **rchip) { - mychip_t *chip; + struct mychip *chip; int err; - static snd_device_ops_t ops = { + static struct snd_device_ops ops = { .dev_free = snd_mychip_dev_free, }; @@ -1155,8 +1149,7 @@ } chip->port = pci_resource_start(pci, 0); if (request_irq(pci->irq, snd_mychip_interrupt, - SA_INTERRUPT|SA_SHIRQ, "My Chip", - (void *)chip)) { + SA_INTERRUPT|SA_SHIRQ, "My Chip", chip)) { printk(KERN_ERR "cannot grab irq %d\n", pci->irq); snd_mychip_free(chip); return -EBUSY; @@ -1268,14 +1261,14 @@ <para> Now assume that this PCI device has an I/O port with 8 bytes - and an interrupt. Then <type>mychip_t</type> will have the + and an interrupt. Then struct <structname>mychip</structname> will have the following fields: <informalexample> <programlisting> <![CDATA[ - struct snd_mychip { - snd_card_t *card; + struct mychip { + struct snd_card *card; unsigned long port; int irq; @@ -1330,8 +1323,7 @@ <programlisting> <![CDATA[ if (request_irq(pci->irq, snd_mychip_interrupt, - SA_INTERRUPT|SA_SHIRQ, "My Chip", - (void *)chip)) { + SA_INTERRUPT|SA_SHIRQ, "My Chip", chip)) { printk(KERN_ERR "cannot grab irq %d\n", pci->irq); snd_mychip_free(chip); return -EBUSY; @@ -1372,7 +1364,7 @@ static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id, struct pt_regs *regs) { - mychip_t *chip = dev_id; + struct mychip *chip = dev_id; .... return IRQ_HANDLED; } @@ -1487,7 +1479,7 @@ <informalexample> <programlisting> <![CDATA[ - struct snd_mychip { + struct mychip { .... unsigned long iobase_phys; void __iomem *iobase_virt; @@ -1517,7 +1509,7 @@ <informalexample> <programlisting> <![CDATA[ - static int snd_mychip_free(mychip_t *chip) + static int snd_mychip_free(struct mychip *chip) { .... if (chip->iobase_virt) @@ -1537,7 +1529,7 @@ <title>Registration of Device Struct</title> <para> At some point, typically after calling <function>snd_device_new()</function>, - you need to register the <structname>struct device</structname> of the chip + you need to register the struct <structname>device</structname> of the chip you're handling for udev and co. ALSA provides a macro for compatibility with older kernels. Simply call like the following: <informalexample> @@ -1739,7 +1731,7 @@ .... /* hardware definition */ - static snd_pcm_hardware_t snd_mychip_playback_hw = { + static struct snd_pcm_hardware snd_mychip_playback_hw = { .info = (SNDRV_PCM_INFO_MMAP | SNDRV_PCM_INFO_INTERLEAVED | SNDRV_PCM_INFO_BLOCK_TRANSFER | @@ -1758,7 +1750,7 @@ }; /* hardware definition */ - static snd_pcm_hardware_t snd_mychip_capture_hw = { + static struct snd_pcm_hardware snd_mychip_capture_hw = { .info = (SNDRV_PCM_INFO_MMAP | SNDRV_PCM_INFO_INTERLEAVED | SNDRV_PCM_INFO_BLOCK_TRANSFER | @@ -1777,10 +1769,10 @@ }; /* open callback */ - static int snd_mychip_playback_open(snd_pcm_substream_t *substream) + static int snd_mychip_playback_open(struct snd_pcm_substream *substream) { - mychip_t *chip = snd_pcm_substream_chip(substream); - snd_pcm_runtime_t *runtime = substream->runtime; + struct mychip *chip = snd_pcm_substream_chip(substream); + struct snd_pcm_runtime *runtime = substream->runtime; runtime->hw = snd_mychip_playback_hw; // more hardware-initialization will be done here @@ -1788,19 +1780,19 @@ } /* close callback */ - static int snd_mychip_playback_close(snd_pcm_substream_t *substream) + static int snd_mychip_playback_close(struct snd_pcm_substream *substream) { - mychip_t *chip = snd_pcm_substream_chip(substream); + struct mychip *chip = snd_pcm_substream_chip(substream); // the hardware-specific codes will be here return 0; } /* open callback */ - static int snd_mychip_capture_open(snd_pcm_substream_t *substream) + static int snd_mychip_capture_open(struct snd_pcm_substream *substream) { - mychip_t *chip = snd_pcm_substream_chip(substream); - snd_pcm_runtime_t *runtime = substream->runtime; + struct mychip *chip = snd_pcm_substream_chip(substream); + struct snd_pcm_runtime *runtime = substream->runtime; runtime->hw = snd_mychip_capture_hw; // more hardware-initialization will be done here @@ -1808,33 +1800,33 @@ } /* close callback */ - static int snd_mychip_capture_close(snd_pcm_substream_t *substream) + static int snd_mychip_capture_close(struct snd_pcm_substream *substream) { - mychip_t *chip = snd_pcm_substream_chip(substream); + struct mychip *chip = snd_pcm_substream_chip(substream); // the hardware-specific codes will be here return 0; } /* hw_params callback */ - static int snd_mychip_pcm_hw_params(snd_pcm_substream_t *substream, - snd_pcm_hw_params_t * hw_params) + static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream, + struct snd_pcm_hw_params *hw_params) { return snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params)); } /* hw_free callback */ - static int snd_mychip_pcm_hw_free(snd_pcm_substream_t *substream) + static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream) { return snd_pcm_lib_free_pages(substream); } /* prepare callback */ - static int snd_mychip_pcm_prepare(snd_pcm_substream_t *substream) + static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream) { - mychip_t *chip = snd_pcm_substream_chip(substream); - snd_pcm_runtime_t *runtime = substream->runtime; + struct mychip *chip = snd_pcm_substream_chip(substream); + struct snd_pcm_runtime *runtime = substream->runtime; /* set up the hardware with the current configuration * for example... @@ -1849,7 +1841,7 @@ } /* trigger callback */ - static int snd_mychip_pcm_trigger(snd_pcm_substream_t *substream, + static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream, int cmd) { switch (cmd) { @@ -1866,9 +1858,9 @@ /* pointer callback */ static snd_pcm_uframes_t - snd_mychip_pcm_pointer(snd_pcm_substream_t *substream) + snd_mychip_pcm_pointer(struct snd_pcm_substream *substream) { - mychip_t *chip = snd_pcm_substream_chip(substream); + struct mychip *chip = snd_pcm_substream_chip(substream); unsigned int current_ptr; /* get the current hardware pointer */ @@ -1877,7 +1869,7 @@ } /* operators */ - static snd_pcm_ops_t snd_mychip_playback_ops = { + static struct snd_pcm_ops snd_mychip_playback_ops = { .open = snd_mychip_playback_open, .close = snd_mychip_playback_close, .ioctl = snd_pcm_lib_ioctl, @@ -1889,7 +1881,7 @@ }; /* operators */ - static snd_pcm_ops_t snd_mychip_capture_ops = { + static struct snd_pcm_ops snd_mychip_capture_ops = { .open = snd_mychip_capture_open, .close = snd_mychip_capture_close, .ioctl = snd_pcm_lib_ioctl, @@ -1905,9 +1897,9 @@ */ /* create a pcm device */ - static int __devinit snd_mychip_new_pcm(mychip_t *chip) + static int __devinit snd_mychip_new_pcm(struct mychip *chip) { - snd_pcm_t *pcm; + struct snd_pcm *pcm; int err; if ((err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, @@ -1944,9 +1936,9 @@ <informalexample> <programlisting> <![CDATA[ - static int __devinit snd_mychip_new_pcm(mychip_t *chip) + static int __devinit snd_mychip_new_pcm(struct mychip *chip) { - snd_pcm_t *pcm; + struct snd_pcm *pcm; int err; if ((err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, @@ -1989,13 +1981,13 @@ specify more numbers, but they must be handled properly in open/close, etc. callbacks. When you need to know which substream you are referring to, then it can be obtained from - <type>snd_pcm_substream_t</type> data passed to each callback + struct <structname>snd_pcm_substream</structname> data passed to each callback as follows: <informalexample> <programlisting> <![CDATA[ - snd_pcm_substream_t *substream; + struct snd_pcm_substream *substream; int index = substream->number; ]]> </programlisting> @@ -2024,7 +2016,7 @@ <informalexample> <programlisting> <![CDATA[ - static snd_pcm_ops_t snd_mychip_playback_ops = { + static struct snd_pcm_ops snd_mychip_playback_ops = { .open = snd_mychip_pcm_open, .close = snd_mychip_pcm_close, .ioctl = snd_pcm_lib_ioctl, @@ -2102,18 +2094,18 @@ <title>PCM Instance with a Destructor</title> <programlisting> <![CDATA[ - static void mychip_pcm_free(snd_pcm_t *pcm) + static void mychip_pcm_free(struct snd_pcm *pcm) { - mychip_t *chip = snd_pcm_chip(pcm); + struct mychip *chip = snd_pcm_chip(pcm); /* free your own data */ kfree(chip->my_private_pcm_data); // do what you like else .... } - static int __devinit snd_mychip_new_pcm(mychip_t *chip) + static int __devinit snd_mychip_new_pcm(struct mychip *chip) { - snd_pcm_t *pcm; + struct snd_pcm *pcm; .... /* allocate your own data */ chip->my_private_pcm_data = kmalloc(...); @@ -2149,7 +2141,7 @@ <![CDATA[ struct _snd_pcm_runtime { /* -- Status -- */ - snd_pcm_substream_t *trigger_master; + struct snd_pcm_substream *trigger_master; snd_timestamp_t trigger_tstamp; /* trigger timestamp */ int overrange; snd_pcm_uframes_t avail_max; @@ -2192,8 +2184,8 @@ struct _snd_pcm_runtime { snd_pcm_sync_id_t sync; /* hardware synchronization ID */ /* -- mmap -- */ - volatile snd_pcm_mmap_status_t *status; - volatile snd_pcm_mmap_control_t *control; + volatile struct snd_pcm_mmap_status *status; + volatile struct snd_pcm_mmap_control *control; atomic_t mmap_count; /* -- locking / scheduling -- */ @@ -2204,15 +2196,15 @@ struct _snd_pcm_runtime { /* -- private section -- */ void *private_data; - void (*private_free)(snd_pcm_runtime_t *runtime); + void (*private_free)(struct snd_pcm_runtime *runtime); /* -- hardware description -- */ - snd_pcm_hardware_t hw; - snd_pcm_hw_constraints_t hw_constraints; + struct snd_pcm_hardware hw; + struct snd_pcm_hw_constraints hw_constraints; /* -- interrupt callbacks -- */ - void (*transfer_ack_begin)(snd_pcm_substream_t *substream); - void (*transfer_ack_end)(snd_pcm_substream_t *substream); + void (*transfer_ack_begin)(struct snd_pcm_substream *substream); + void (*transfer_ack_end)(struct snd_pcm_substream *substream); /* -- timer -- */ unsigned int timer_resolution; /* timer resolution */ @@ -2226,7 +2218,7 @@ struct _snd_pcm_runtime { #if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE) /* -- OSS things -- */ - snd_pcm_oss_runtime_t oss; + struct snd_pcm_oss_runtime oss; #endif }; ]]> @@ -2252,7 +2244,7 @@ struct _snd_pcm_runtime { <section id="pcm-interface-runtime-hw"> <title>Hardware Description</title> <para> - The hardware descriptor (<type>snd_pcm_hardware_t</type>) + The hardware descriptor (struct <structname>snd_pcm_hardware</structname>) contains the definitions of the fundamental hardware configuration. Above all, you'll need to define this in <link linkend="pcm-interface-operators-open-callback"><citetitle> @@ -2267,7 +2259,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - snd_pcm_runtime_t *runtime = substream->runtime; + struct snd_pcm_runtime *runtime = substream->runtime; ... runtime->hw = snd_mychip_playback_hw; /* common definition */ if (chip->model == VERY_OLD_ONE) @@ -2282,7 +2274,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static snd_pcm_hardware_t snd_mychip_playback_hw = { + static struct snd_pcm_hardware snd_mychip_playback_hw = { .info = (SNDRV_PCM_INFO_MMAP | SNDRV_PCM_INFO_INTERLEAVED | SNDRV_PCM_INFO_BLOCK_TRANSFER | @@ -2337,9 +2329,14 @@ struct _snd_pcm_runtime { <constant>PAUSE</constant> bit means that the pcm supports the <quote>pause</quote> operation, while the <constant>RESUME</constant> bit means that the pcm supports - the <quote>suspend/resume</quote> operation. If these flags - are set, the <structfield>trigger</structfield> callback below - must handle the corresponding commands. + the full <quote>suspend/resume</quote> operation. + If <constant>PAUSE</constant> flag is set, + the <structfield>trigger</structfield> callback below + must handle the corresponding (pause push/release) commands. + The suspend/resume trigger commands can be defined even without + <constant>RESUME</constant> flag. See <link + linkend="power-management"><citetitle> + Power Management</citetitle></link> section for details. </para> <para> @@ -2512,7 +2509,7 @@ struct _snd_pcm_runtime { <title>Running Status</title> <para> The running status can be referred via <constant>runtime->status</constant>. - This is the pointer to <type>snd_pcm_mmap_status_t</type> + This is the pointer to struct <structname>snd_pcm_mmap_status</structname> record. For example, you can get the current DMA hardware pointer via <constant>runtime->status->hw_ptr</constant>. </para> @@ -2520,7 +2517,7 @@ struct _snd_pcm_runtime { <para> The DMA application pointer can be referred via <constant>runtime->control</constant>, which points - <type>snd_pcm_mmap_control_t</type> record. + struct <structname>snd_pcm_mmap_control</structname> record. However, accessing directly to this value is not recommended. </para> </section> @@ -2542,9 +2539,9 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static int snd_xxx_open(snd_pcm_substream_t *substream) + static int snd_xxx_open(struct snd_pcm_substream *substream) { - my_pcm_data_t *data; + struct my_pcm_data *data; .... data = kmalloc(sizeof(*data), GFP_KERNEL); substream->runtime->private_data = data; @@ -2586,7 +2583,7 @@ struct _snd_pcm_runtime { <para> The callback function takes at least the argument with - <type>snd_pcm_substream_t</type> pointer. For retrieving the + <structname>snd_pcm_substream</structname> pointer. For retrieving the chip record from the given substream instance, you can use the following macro. @@ -2594,7 +2591,7 @@ struct _snd_pcm_runtime { <programlisting> <![CDATA[ int xxx() { - mychip_t *chip = snd_pcm_substream_chip(substream); + struct mychip *chip = snd_pcm_substream_chip(substream); .... } ]]> @@ -2616,7 +2613,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static int snd_xxx_open(snd_pcm_substream_t *substream); + static int snd_xxx_open(struct snd_pcm_substream *substream); ]]> </programlisting> </informalexample> @@ -2631,10 +2628,10 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static int snd_xxx_open(snd_pcm_substream_t *substream) + static int snd_xxx_open(struct snd_pcm_substream *substream) { - mychip_t *chip = snd_pcm_substream_chip(substream); - snd_pcm_runtime_t *runtime = substream->runtime; + struct mychip *chip = snd_pcm_substream_chip(substream); + struct snd_pcm_runtime *runtime = substream->runtime; runtime->hw = snd_mychip_playback_hw; return 0; @@ -2667,7 +2664,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static int snd_xxx_close(snd_pcm_substream_t *substream); + static int snd_xxx_close(struct snd_pcm_substream *substream); ]]> </programlisting> </informalexample> @@ -2682,7 +2679,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static int snd_xxx_close(snd_pcm_substream_t *substream) + static int snd_xxx_close(struct snd_pcm_substream *substream) { .... kfree(substream->runtime->private_data); @@ -2709,8 +2706,8 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static int snd_xxx_hw_params(snd_pcm_substream_t * substream, - snd_pcm_hw_params_t * hw_params); + static int snd_xxx_hw_params(struct snd_pcm_substream *substream, + struct snd_pcm_hw_params *hw_params); ]]> </programlisting> </informalexample> @@ -2785,7 +2782,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static int snd_xxx_hw_free(snd_pcm_substream_t * substream); + static int snd_xxx_hw_free(struct snd_pcm_substream *substream); ]]> </programlisting> </informalexample> @@ -2820,7 +2817,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static int snd_xxx_prepare(snd_pcm_substream_t * substream); + static int snd_xxx_prepare(struct snd_pcm_substream *substream); ]]> </programlisting> </informalexample> @@ -2869,7 +2866,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static int snd_xxx_trigger(snd_pcm_substream_t * substream, int cmd); + static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd); ]]> </programlisting> </informalexample> @@ -2911,8 +2908,8 @@ struct _snd_pcm_runtime { </para> <para> - When the pcm supports the suspend/resume operation - (i.e. <constant>SNDRV_PCM_INFO_RESUME</constant> flag is set), + When the pcm supports the suspend/resume operation, + regardless of full or partial suspend/resume support, <constant>SUSPEND</constant> and <constant>RESUME</constant> commands must be handled, too. These commands are issued when the power-management status is @@ -2921,6 +2918,8 @@ struct _snd_pcm_runtime { do suspend and resume of the pcm substream, and usually, they are identical with <constant>STOP</constant> and <constant>START</constant> commands, respectively. + See <link linkend="power-management"><citetitle> + Power Management</citetitle></link> section for details. </para> <para> @@ -2939,7 +2938,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static snd_pcm_uframes_t snd_xxx_pointer(snd_pcm_substream_t * substream) + static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream) ]]> </programlisting> </informalexample> @@ -3067,7 +3066,7 @@ struct _snd_pcm_runtime { static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id, struct pt_regs *regs) { - mychip_t *chip = dev_id; + struct mychip *chip = dev_id; spin_lock(&chip->lock); .... if (pcm_irq_invoked(chip)) { @@ -3111,7 +3110,7 @@ struct _snd_pcm_runtime { static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id, struct pt_regs *regs) { - mychip_t *chip = dev_id; + struct mychip *chip = dev_id; spin_lock(&chip->lock); .... if (pcm_irq_invoked(chip)) { @@ -3221,13 +3220,13 @@ struct _snd_pcm_runtime { <![CDATA[ static unsigned int rates[] = {4000, 10000, 22050, 44100}; - static snd_pcm_hw_constraint_list_t constraints_rates = { + static struct snd_pcm_hw_constraint_list constraints_rates = { .count = ARRAY_SIZE(rates), .list = rates, .mask = 0, }; - static int snd_mychip_pcm_open(snd_pcm_substream_t *substream) + static int snd_mychip_pcm_open(struct snd_pcm_substream *substream) { int err; .... @@ -3249,19 +3248,20 @@ 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 <type>snd_pcm_hardware_t</type> stucture (or in any + specified in the <structname>snd_pcm_hardware</structname> stucture (or in any other constraint_list). You can build a rule like this: <example> <title>Example of Hardware Constraints for Channels</title> <programlisting> <![CDATA[ - static int hw_rule_format_by_channels(snd_pcm_hw_params_t *params, - snd_pcm_hw_rule_t *rule) + static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params, + struct snd_pcm_hw_rule *rule) { - snd_interval_t *c = hw_param_interval(params, SNDRV_PCM_HW_PARAM_CHANNELS); - snd_mask_t *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT); - snd_mask_t fmt; + struct snd_interval *c = hw_param_interval(params, + SNDRV_PCM_HW_PARAM_CHANNELS); + struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT); + struct snd_mask fmt; snd_mask_any(&fmt); /* Init the struct */ if (c->min < 2) { @@ -3298,12 +3298,13 @@ struct _snd_pcm_runtime { <title>Example of Hardware Constraints for Channels</title> <programlisting> <![CDATA[ - static int hw_rule_channels_by_format(snd_pcm_hw_params_t *params, - snd_pcm_hw_rule_t *rule) + static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params, + struct snd_pcm_hw_rule *rule) { - snd_interval_t *c = hw_param_interval(params, SNDRV_PCM_HW_PARAM_CHANNELS); - snd_mask_t *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT); - snd_interval_t ch; + struct snd_interval *c = hw_param_interval(params, + SNDRV_PCM_HW_PARAM_CHANNELS); + struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT); + struct snd_interval ch; snd_interval_any(&ch); if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) { @@ -3376,13 +3377,13 @@ struct _snd_pcm_runtime { callbacks: <structfield>info</structfield>, <structfield>get</structfield> and <structfield>put</structfield>. Then, define a - <type>snd_kcontrol_new_t</type> record, such as: + struct <structname>snd_kcontrol_new</structname> record, such as: <example> <title>Definition of a Control</title> <programlisting> <![CDATA[ - static snd_kcontrol_new_t my_control __devinitdata = { + static struct snd_kcontrol_new my_control __devinitdata = { .iface = SNDRV_CTL_ELEM_IFACE_MIXER, .name = "PCM Playback Switch", .index = 0, @@ -3599,7 +3600,7 @@ struct _snd_pcm_runtime { <para> The <structfield>info</structfield> callback is used to get the detailed information of this control. This must store the - values of the given <type>snd_ctl_elem_info_t</type> + values of the given struct <structname>snd_ctl_elem_info</structname> object. For example, for a boolean control with a single element will be: @@ -3607,8 +3608,8 @@ struct _snd_pcm_runtime { <title>Example of info callback</title> <programlisting> <![CDATA[ - static int snd_myctl_info(snd_kcontrol_t *kcontrol, - snd_ctl_elem_info_t *uinfo) + static int snd_myctl_info(struct snd_kcontrol *kcontrol, + struct snd_ctl_elem_info *uinfo) { uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN; uinfo->count = 1; @@ -3642,8 +3643,8 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static int snd_myctl_info(snd_kcontrol_t *kcontrol, - snd_ctl_elem_info_t *uinfo) + static int snd_myctl_info(struct snd_kcontrol *kcontrol, + struct snd_ctl_elem_info *uinfo) { static char *texts[4] = { "First", "Second", "Third", "Fourth" @@ -3678,10 +3679,10 @@ struct _snd_pcm_runtime { <title>Example of get callback</title> <programlisting> <![CDATA[ - static int snd_myctl_get(snd_kcontrol_t *kcontrol, - snd_ctl_elem_value_t *ucontrol) + static int snd_myctl_get(struct snd_kcontrol *kcontrol, + struct snd_ctl_elem_value *ucontrol) { - mychip_t *chip = snd_kcontrol_chip(kcontrol); + struct mychip *chip = snd_kcontrol_chip(kcontrol); ucontrol->value.integer.value[0] = get_some_value(chip); return 0; } @@ -3717,8 +3718,8 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static int snd_sbmixer_get_single(snd_kcontrol_t *kcontrol, - snd_ctl_elem_value_t *ucontrol) + static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol, + struct snd_ctl_elem_value *ucontrol) { int reg = kcontrol->private_value & 0xff; int shift = (kcontrol->private_value >> 16) & 0xff; @@ -3754,10 +3755,10 @@ struct _snd_pcm_runtime { <title>Example of put callback</title> <programlisting> <![CDATA[ - static int snd_myctl_put(snd_kcontrol_t *kcontrol, - snd_ctl_elem_value_t *ucontrol) + static int snd_myctl_put(struct snd_kcontrol *kcontrol, + struct snd_ctl_elem_value *ucontrol) { - mychip_t *chip = snd_kcontrol_chip(kcontrol); + struct mychip *chip = snd_kcontrol_chip(kcontrol); int changed = 0; if (chip->current_value != ucontrol->value.integer.value[0]) { @@ -3814,7 +3815,7 @@ struct _snd_pcm_runtime { </informalexample> where <parameter>my_control</parameter> is the - <type>snd_kcontrol_new_t</type> object defined above, and chip + struct <structname>snd_kcontrol_new</structname> object defined above, and chip is the object pointer to be passed to kcontrol->private_data which can be referred in callbacks. @@ -3822,7 +3823,7 @@ struct _snd_pcm_runtime { <para> <function>snd_ctl_new1()</function> allocates a new - <type>snd_kcontrol_t</type> instance (that's why the definition + <structname>snd_kcontrol</structname> instance (that's why the definition of <parameter>my_control</parameter> can be with <parameter>__devinitdata</parameter> prefix), and <function>snd_ctl_add</function> assigns the given @@ -3849,7 +3850,7 @@ struct _snd_pcm_runtime { control id pointer for the notification. The event-mask specifies the types of notification, for example, in the above example, the change of control values is notified. - The id pointer is the pointer of <type>snd_ctl_elem_id_t</type> + The id pointer is the pointer of struct <structname>snd_ctl_elem_id</structname> to be notified. You can find some examples in <filename>es1938.c</filename> or <filename>es1968.c</filename> for hardware volume interrupts. @@ -3882,35 +3883,35 @@ struct _snd_pcm_runtime { <title>Example of AC97 Interface</title> <programlisting> <![CDATA[ - struct snd_mychip { + struct mychip { .... - ac97_t *ac97; + struct snd_ac97 *ac97; .... }; - static unsigned short snd_mychip_ac97_read(ac97_t *ac97, + static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97, unsigned short reg) { - mychip_t *chip = ac97->private_data; + struct mychip *chip = ac97->private_data; .... // read a register value here from the codec return the_register_value; } - static void snd_mychip_ac97_write(ac97_t *ac97, + static void snd_mychip_ac97_write(struct snd_ac97 *ac97, unsigned short reg, unsigned short val) { - mychip_t *chip = ac97->private_data; + struct mychip *chip = ac97->private_data; .... // write the given register value to the codec } - static int snd_mychip_ac97(mychip_t *chip) + static int snd_mychip_ac97(struct mychip *chip) { - ac97_bus_t *bus; - ac97_template_t ac97; + struct snd_ac97_bus *bus; + struct snd_ac97_template ac97; int err; - static ac97_bus_ops_t ops = { + static struct snd_ac97_bus_ops ops = { .write = snd_mychip_ac97_write, .read = snd_mychip_ac97_read, }; @@ -3937,8 +3938,8 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - ac97_bus_t *bus; - static ac97_bus_ops_t ops = { + struct snd_ac97_bus *bus; + static struct snd_ac97_bus_ops ops = { .write = snd_mychip_ac97_write, .read = snd_mychip_ac97_read, }; @@ -3952,13 +3953,14 @@ struct _snd_pcm_runtime { </para> <para> - And then call <function>snd_ac97_mixer()</function> with an <type>ac97_template_t</type> + And then call <function>snd_ac97_mixer()</function> with an + struct <structname>snd_ac97_template</structname> record together with the bus pointer created above. <informalexample> <programlisting> <![CDATA[ - ac97_template_t ac97; + struct snd_ac97_template ac97; int err; memset(&ac97, 0, sizeof(ac97)); @@ -3995,10 +3997,10 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static unsigned short snd_mychip_ac97_read(ac97_t *ac97, + static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97, unsigned short reg) { - mychip_t *chip = ac97->private_data; + struct mychip *chip = ac97->private_data; .... return the_register_value; } @@ -4016,7 +4018,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static void snd_mychip_ac97_write(ac97_t *ac97, + static void snd_mychip_ac97_write(struct snd_ac97 *ac97, unsigned short reg, unsigned short val) ]]> </programlisting> @@ -4163,7 +4165,7 @@ struct _snd_pcm_runtime { <title>Multiple Codecs</title> <para> When there are several codecs on the same card, you need to - call <function>snd_ac97_new()</function> multiple times with + call <function>snd_ac97_mixer()</function> multiple times with ac97.num=1 or greater. The <structfield>num</structfield> field specifies the codec number. @@ -4212,7 +4214,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - snd_rawmidi_t *rmidi; + struct snd_rawmidi *rmidi; snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, integrated, irq, irq_flags, &rmidi); ]]> @@ -4253,17 +4255,17 @@ struct _snd_pcm_runtime { Usually, the port address corresponds to the command port and port + 1 corresponds to the data port. If not, you may change the <structfield>cport</structfield> field of - <type>mpu401_t</type> manually - afterward. However, <type>mpu401_t</type> pointer is not + struct <structname>snd_mpu401</structname> manually + afterward. However, <structname>snd_mpu401</structname> pointer is not returned explicitly by <function>snd_mpu401_uart_new()</function>. You need to cast rmidi->private_data to - <type>mpu401_t</type> explicitly, + <structname>snd_mpu401</structname> explicitly, <informalexample> <programlisting> <![CDATA[ - mpu401_t *mpu; + struct snd_mpu401 *mpu; mpu = rmidi->private_data; ]]> </programlisting> @@ -4359,7 +4361,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - snd_rawmidi_t *rmidi; + struct snd_rawmidi *rmidi; err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi); if (err < 0) return err; @@ -4419,7 +4421,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static snd_rawmidi_ops_t snd_mymidi_output_ops = { + static struct snd_rawmidi_ops snd_mymidi_output_ops = { .open = snd_mymidi_output_open, .close = snd_mymidi_output_close, .trigger = snd_mymidi_output_trigger, @@ -4439,9 +4441,9 @@ struct _snd_pcm_runtime { <programlisting> <![CDATA[ struct list_head *list; - snd_rawmidi_substream_t *substream; + struct snd_rawmidi_substream *substream; list_for_each(list, &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams) { - substream = list_entry(list, snd_rawmidi_substream_t, list); + substream = list_entry(list, struct snd_rawmidi_substream, list); sprintf(substream->name, "My MIDI Port %d", substream->number + 1); } /* same for SNDRV_RAWMIDI_STREAM_INPUT */ @@ -4463,12 +4465,12 @@ struct _snd_pcm_runtime { <para> If there is more than one port, your callbacks can determine the - port index from the snd_rawmidi_substream_t data passed to each + port index from the struct snd_rawmidi_substream data passed to each callback: <informalexample> <programlisting> <![CDATA[ - snd_rawmidi_substream_t *substream; + struct snd_rawmidi_substream *substream; int index = substream->number; ]]> </programlisting> @@ -4481,7 +4483,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static int snd_xxx_open(snd_rawmidi_substream_t *substream); + static int snd_xxx_open(struct snd_rawmidi_substream *substream); ]]> </programlisting> </informalexample> @@ -4499,7 +4501,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static int snd_xxx_close(snd_rawmidi_substream_t *substream); + static int snd_xxx_close(struct snd_rawmidi_substream *substream); ]]> </programlisting> </informalexample> @@ -4522,7 +4524,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static void snd_xxx_output_trigger(snd_rawmidi_substream_t *substream, int up); + static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up); ]]> </programlisting> </informalexample> @@ -4547,7 +4549,7 @@ struct _snd_pcm_runtime { <![CDATA[ unsigned char data; while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) { - if (mychip_try_to_transmit(data)) + if (snd_mychip_try_to_transmit(data)) snd_rawmidi_transmit_ack(substream, 1); else break; /* hardware FIFO full */ @@ -4564,11 +4566,11 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - while (mychip_transmit_possible()) { + while (snd_mychip_transmit_possible()) { unsigned char data; if (snd_rawmidi_transmit(substream, &data, 1) != 1) break; /* no more data */ - mychip_transmit(data); + snd_mychip_transmit(data); } ]]> </programlisting> @@ -4603,7 +4605,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static void snd_xxx_input_trigger(snd_rawmidi_substream_t *substream, int up); + static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up); ]]> </programlisting> </informalexample> @@ -4647,7 +4649,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static void snd_xxx_drain(snd_rawmidi_substream_t *substream); + static void snd_xxx_drain(struct snd_rawmidi_substream *substream); ]]> </programlisting> </informalexample> @@ -4661,7 +4663,7 @@ struct _snd_pcm_runtime { <para> This callback is optional. If you do not set - <structfield>drain</structfield> in the snd_rawmidi_ops_t + <structfield>drain</structfield> in the struct snd_rawmidi_ops structure, ALSA will simply wait for 50 milliseconds instead. </para> @@ -4703,7 +4705,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - opl3_t *opl3; + struct snd_opl3 *opl3; snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX, integrated, &opl3); ]]> @@ -4736,7 +4738,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - opl3_t *opl3; + struct snd_opl3 *opl3; snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3); ]]> </programlisting> @@ -4767,7 +4769,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - snd_hwdep_t *opl3hwdep; + struct snd_hwdep *opl3hwdep; snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep); ]]> </programlisting> @@ -4804,7 +4806,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - snd_hwdep_t *hw; + struct snd_hwdep *hw; snd_hwdep_new(card, "My HWDEP", 0, &hw); ]]> </programlisting> @@ -4823,7 +4825,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - mydata_t *p = kmalloc(sizeof(*p), GFP_KERNEL); + struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL); hw->private_data = p; hw->private_free = mydata_free; ]]> @@ -4835,9 +4837,9 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static void mydata_free(snd_hwdep_t *hw) + static void mydata_free(struct snd_hwdep *hw) { - mydata_t *p = hw->private_data; + struct mydata *p = hw->private_data; kfree(p); } ]]> @@ -5061,9 +5063,9 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static int playback_copy(snd_pcm_substream_t *substream, int channel, + static int playback_copy(struct snd_pcm_substream *substream, int channel, snd_pcm_uframes_t pos, void *src, snd_pcm_uframes_t count); - static int capture_copy(snd_pcm_substream_t *substream, int channel, + static int capture_copy(struct snd_pcm_substream *substream, int channel, snd_pcm_uframes_t pos, void *dst, snd_pcm_uframes_t count); ]]> </programlisting> @@ -5144,7 +5146,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static int silence(snd_pcm_substream_t *substream, int channel, + static int silence(struct snd_pcm_substream *substream, int channel, snd_pcm_uframes_t pos, snd_pcm_uframes_t count); ]]> </programlisting> @@ -5211,7 +5213,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - snd_pcm_sgbuf_t *sgbuf = (snd_pcm_sgbuf_t*)substream->dma_private; + struct snd_sg_buf *sgbuf = (struct snd_sg_buf_t*)substream->dma_private; ]]> </programlisting> </informalexample> @@ -5266,7 +5268,7 @@ struct _snd_pcm_runtime { #include <linux/vmalloc.h> /* get the physical page pointer on the given offset */ - static struct page *mychip_page(snd_pcm_substream_t *substream, + static struct page *mychip_page(struct snd_pcm_substream *substream, unsigned long offset) { void *pageptr = substream->runtime->dma_area + offset; @@ -5301,7 +5303,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - snd_info_entry_t *entry; + struct snd_info_entry *entry; int err = snd_card_proc_new(card, "my-file", &entry); ]]> </programlisting> @@ -5345,8 +5347,8 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static void my_proc_read(snd_info_entry_t *entry, - snd_info_buffer_t *buffer); + static void my_proc_read(struct snd_info_entry *entry, + struct snd_info_buffer *buffer); ]]> </programlisting> </informalexample> @@ -5361,10 +5363,10 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static void my_proc_read(snd_info_entry_t *entry, - snd_info_buffer_t *buffer) + static void my_proc_read(struct snd_info_entry *entry, + struct snd_info_buffer *buffer) { - chip_t *chip = entry->private_data; + struct my_chip *chip = entry->private_data; snd_iprintf(buffer, "This is my chip!\n"); snd_iprintf(buffer, "Port = %ld\n", chip->port); @@ -5453,7 +5455,7 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static long my_file_io_read(snd_info_entry_t *entry, + static long my_file_io_read(struct snd_info_entry *entry, void *file_private_data, struct file *file, char *buf, @@ -5488,22 +5490,60 @@ struct _snd_pcm_runtime { <constant>CONFIG_PM</constant>. </para> + <para> + If the driver supports the suspend/resume + <emphasis>fully</emphasis>, that is, the device can be + properly resumed to the status at the suspend is called, + you can set <constant>SNDRV_PCM_INFO_RESUME</constant> flag + to pcm info field. Usually, this is possible when the + registers of ths chip can be safely saved and restored to the + RAM. If this is set, the trigger callback is called with + <constant>SNDRV_PCM_TRIGGER_RESUME</constant> after resume + callback is finished. + </para> + + <para> + Even if the driver doesn't support PM fully but only the + partial suspend/resume is possible, it's still worthy to + implement suspend/resume callbacks. In such a case, applications + would reset the status by calling + <function>snd_pcm_prepare()</function> and restart the stream + appropriately. Hence, you can define suspend/resume callbacks + below but don't set <constant>SNDRV_PCM_INFO_RESUME</constant> + info flag to the PCM. + </para> + + <para> + Note that the trigger with SUSPEND can be always called when + <function>snd_pcm_suspend_all</function> is called, + regardless of <constant>SNDRV_PCM_INFO_RESUME</constant> flag. + The <constant>RESUME</constant> flag affects only the behavior + of <function>snd_pcm_resume()</function>. + (Thus, in theory, + <constant>SNDRV_PCM_TRIGGER_RESUME</constant> isn't needed + to be handled in the trigger callback when no + <constant>SNDRV_PCM_INFO_RESUME</constant> flag is set. But, + it's better to keep it for compatibility reason.) + </para> <para> - ALSA provides the common power-management layer. Each card driver - needs to have only low-level suspend and resume callbacks. + In the earlier version of ALSA drivers, a common + power-management layer was provided, but it has been removed. + The driver needs to define the suspend/resume hooks according to + the bus the device is assigned. In the case of PCI driver, the + callbacks look like below: <informalexample> <programlisting> <![CDATA[ #ifdef CONFIG_PM - static int snd_my_suspend(snd_card_t *card, pm_message_t state) + static int snd_my_suspend(struct pci_dev *pci, pm_message_t state) { - .... // do things for suspsend + .... /* do things for suspsend */ return 0; } - static int snd_my_resume(snd_card_t *card) + static int snd_my_resume(struct pci_dev *pci) { - .... // do things for suspsend + .... /* do things for suspsend */ return 0; } #endif @@ -5516,11 +5556,18 @@ struct _snd_pcm_runtime { The scheme of the real suspend job is as following. <orderedlist> - <listitem><para>Retrieve the chip data from pm_private_data field.</para></listitem> + <listitem><para>Retrieve the card and the chip data.</para></listitem> + <listitem><para>Call <function>snd_power_change_state()</function> with + <constant>SNDRV_CTL_POWER_D3hot</constant> to change the + power status.</para></listitem> <listitem><para>Call <function>snd_pcm_suspend_all()</function> to suspend the running PCM streams.</para></listitem> + <listitem><para>If AC97 codecs are used, call + <function>snd_ac97_resume()</function> for each codec.</para></listitem> <listitem><para>Save the register values if necessary.</para></listitem> <listitem><para>Stop the hardware if necessary.</para></listitem> - <listitem><para>Disable the PCI device by calling <function>pci_disable_device()</function>.</para></listitem> + <listitem><para>Disable the PCI device by calling + <function>pci_disable_device()</function>. Then, call + <function>pci_save_state()</function> at last.</para></listitem> </orderedlist> </para> @@ -5530,18 +5577,24 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static int mychip_suspend(snd_card_t *card, pm_message_t state) + static int mychip_suspend(strut pci_dev *pci, pm_message_t state) { /* (1) */ - mychip_t *chip = card->pm_private_data; + struct snd_card *card = pci_get_drvdata(pci); + struct mychip *chip = card->private_data; /* (2) */ - snd_pcm_suspend_all(chip->pcm); + snd_power_change_state(card, SNDRV_CTL_POWER_D3hot); /* (3) */ - snd_mychip_save_registers(chip); + snd_pcm_suspend_all(chip->pcm); /* (4) */ - snd_mychip_stop_hardware(chip); + snd_ac97_suspend(chip->ac97); /* (5) */ - pci_disable_device(chip->pci); + snd_mychip_save_registers(chip); + /* (6) */ + snd_mychip_stop_hardware(chip); + /* (7) */ + pci_disable_device(pci); + pci_save_state(pci); return 0; } ]]> @@ -5553,14 +5606,17 @@ struct _snd_pcm_runtime { The scheme of the real resume job is as following. <orderedlist> - <listitem><para>Retrieve the chip data from pm_private_data field.</para></listitem> - <listitem><para>Enable the pci device again by calling - <function>pci_enable_device()</function>.</para></listitem> + <listitem><para>Retrieve the card and the chip data.</para></listitem> + <listitem><para>Set up PCI. First, call <function>pci_restore_state()</function>. + Then enable the pci device again by calling <function>pci_enable_device()</function>. + Call <function>pci_set_master()</function> if necessary, too.</para></listitem> <listitem><para>Re-initialize the chip.</para></listitem> <listitem><para>Restore the saved registers if necessary.</para></listitem> <listitem><para>Resume the mixer, e.g. calling <function>snd_ac97_resume()</function>.</para></listitem> <listitem><para>Restart the hardware (if any).</para></listitem> + <listitem><para>Call <function>snd_power_change_state()</function> with + <constant>SNDRV_CTL_POWER_D0</constant> to notify the processes.</para></listitem> </orderedlist> </para> @@ -5570,12 +5626,15 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static void mychip_resume(mychip_t *chip) + static int mychip_resume(struct pci_dev *pci) { /* (1) */ - mychip_t *chip = card->pm_private_data; + struct snd_card *card = pci_get_drvdata(pci); + struct mychip *chip = card->private_data; /* (2) */ - pci_enable_device(chip->pci); + pci_restore_state(pci); + pci_enable_device(pci); + pci_set_master(pci); /* (3) */ snd_mychip_reinit_chip(chip); /* (4) */ @@ -5584,6 +5643,8 @@ struct _snd_pcm_runtime { snd_ac97_resume(chip->ac97); /* (6) */ snd_mychip_restart_chip(chip); + /* (7) */ + snd_power_change_state(card, SNDRV_CTL_POWER_D0); return 0; } ]]> @@ -5592,8 +5653,23 @@ struct _snd_pcm_runtime { </para> <para> - OK, we have all callbacks now. Let's set up them now. In the - initialization of the card, add the following: + As shown in the above, it's better to save registers after + suspending the PCM operations via + <function>snd_pcm_suspend_all()</function> or + <function>snd_pcm_suspend()</function>. It means that the PCM + streams are already stoppped when the register snapshot is + taken. But, remind that you don't have to restart the PCM + stream in the resume callback. It'll be restarted via + trigger call with <constant>SNDRV_PCM_TRIGGER_RESUME</constant> + when necessary. + </para> + + <para> + OK, we have all callbacks now. Let's set them up. In the + initialization of the card, make sure that you can get the chip + data from the card instance, typically via + <structfield>private_data</structfield> field, in case you + created the chip data individually. <informalexample> <programlisting> @@ -5602,33 +5678,56 @@ struct _snd_pcm_runtime { const struct pci_device_id *pci_id) { .... - snd_card_t *card; - mychip_t *chip; + struct snd_card *card; + struct mychip *chip; .... - snd_card_set_pm_callback(card, snd_my_suspend, snd_my_resume, chip); + card = snd_card_new(index[dev], id[dev], THIS_MODULE, NULL); + .... + chip = kzalloc(sizeof(*chip), GFP_KERNEL); + .... + card->private_data = chip; + .... + } +]]> + </programlisting> + </informalexample> + + When you created the chip data with + <function>snd_card_new()</function>, it's anyway accessible + via <structfield>private_data</structfield> field. + + <informalexample> + <programlisting> +<![CDATA[ + static int __devinit snd_mychip_probe(struct pci_dev *pci, + const struct pci_device_id *pci_id) + { + .... + struct snd_card *card; + struct mychip *chip; + .... + card = snd_card_new(index[dev], id[dev], THIS_MODULE, + sizeof(struct mychip)); + .... + chip = card->private_data; .... } ]]> </programlisting> </informalexample> - Here you don't have to put ifdef CONFIG_PM around, since it's already - checked in the header and expanded to empty if not needed. </para> <para> - If you need a space for saving the registers, you'll need to - allocate the buffer for it here, too, since it would be fatal + If you need a space for saving the registers, allocate the + buffer for it here, too, since it would be fatal if you cannot allocate a memory in the suspend phase. The allocated buffer should be released in the corresponding destructor. </para> <para> - And next, set suspend/resume callbacks to the pci_driver, - This can be done by passing a macro SND_PCI_PM_CALLBACKS - in the pci_driver struct. This macro is expanded to the correct - (global) callbacks if CONFIG_PM is set. + And next, set suspend/resume callbacks to the pci_driver. <informalexample> <programlisting> @@ -5638,7 +5737,10 @@ struct _snd_pcm_runtime { .id_table = snd_my_ids, .probe = snd_my_probe, .remove = __devexit_p(snd_my_remove), - SND_PCI_PM_CALLBACKS + #ifdef CONFIG_PM + .suspend = snd_my_suspend, + .resume = snd_my_resume, + #endif }; ]]> </programlisting> diff --git a/Documentation/sound/alsa/Procfile.txt b/Documentation/sound/alsa/Procfile.txt index 25c5d648aef..1fe48846d78 100644 --- a/Documentation/sound/alsa/Procfile.txt +++ b/Documentation/sound/alsa/Procfile.txt @@ -138,6 +138,22 @@ card*/codec97#0/ac97#?-?+regs # echo 02 9f1f > /proc/asound/card0/codec97#0/ac97#0-0+regs +USB Audio Streams +----------------- + +card*/stream* + Shows the assignment and the current status of each audio stream + of the given card. This information is very useful for debugging. + + +HD-Audio Codecs +--------------- + +card*/codec#* + Shows the general codec information and the attribute of each + widget node. + + Sequencer Information --------------------- diff --git a/Documentation/sound/alsa/hda_codec.txt b/Documentation/sound/alsa/hda_codec.txt index e9d07b8f1ac..0be57ed8130 100644 --- a/Documentation/sound/alsa/hda_codec.txt +++ b/Documentation/sound/alsa/hda_codec.txt @@ -63,7 +63,7 @@ The bus instance is created via snd_hda_bus_new(). You need to pass the card instance, the template, and the pointer to store the resultant bus instance. -int snd_hda_bus_new(snd_card_t *card, const struct hda_bus_template *temp, +int snd_hda_bus_new(struct snd_card *card, const struct hda_bus_template *temp, struct hda_bus **busp); It returns zero if successful. A negative return value means any @@ -166,14 +166,14 @@ The ops field contains the following callback functions: struct hda_pcm_ops { int (*open)(struct hda_pcm_stream *info, struct hda_codec *codec, - snd_pcm_substream_t *substream); + struct snd_pcm_substream *substream); int (*close)(struct hda_pcm_stream *info, struct hda_codec *codec, - snd_pcm_substream_t *substream); + struct snd_pcm_substream *substream); int (*prepare)(struct hda_pcm_stream *info, struct hda_codec *codec, unsigned int stream_tag, unsigned int format, - snd_pcm_substream_t *substream); + struct snd_pcm_substream *substream); int (*cleanup)(struct hda_pcm_stream *info, struct hda_codec *codec, - snd_pcm_substream_t *substream); + struct snd_pcm_substream *substream); }; All are non-NULL, so you can call them safely without NULL check. @@ -284,7 +284,7 @@ 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 snd_kcontrol_new_t. The same array +Pass the zero-terminated array of struct snd_kcontrol_new. The same array can be passed to snd_hda_resume_ctls() for resume. Note that this will call control->put callback of these entries. So, put callback should check codec->in_resume and force to restore the @@ -292,7 +292,7 @@ given value if it's non-zero even if the value is identical with the cached value. Macros HDA_CODEC_VOLUME(), HDA_CODEC_MUTE() and their variables can be -used for the entry of snd_kcontrol_new_t. +used for the entry of struct snd_kcontrol_new. The input MUX helper callbacks for such a control are provided, too: snd_hda_input_mux_info() and snd_hda_input_mux_put(). See diff --git a/Documentation/sysrq.txt b/Documentation/sysrq.txt index baf17b38158..ad0bedf678b 100644 --- a/Documentation/sysrq.txt +++ b/Documentation/sysrq.txt @@ -202,17 +202,13 @@ you must call __handle_sysrq_nolock instead. * I have more questions, who can I ask? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You may feel free to send email to myrdraal@deathsdoor.com, and I will -respond as soon as possible. - -Myrdraal - And I'll answer any questions about the registration system you got, also responding as soon as possible. -Crutcher * Credits ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Written by Mydraal <myrdraal@deathsdoor.com> +Written by Mydraal <vulpyne@vulpyne.net> Updated by Adam Sulmicki <adam@cfar.umd.edu> Updated by Jeremy M. Dolan <jmd@turbogeek.org> 2001/01/28 10:15:59 Added to by Crutcher Dunnavant <crutcher+kernel@datastacks.com> |