diff options
Diffstat (limited to 'Documentation/ABI/stable')
| -rw-r--r-- | Documentation/ABI/stable/firewire-cdev | 103 | ||||
| -rw-r--r-- | Documentation/ABI/stable/sysfs-acpi-pmprofile | 22 | ||||
| -rw-r--r-- | Documentation/ABI/stable/sysfs-bus-firewire | 122 | ||||
| -rw-r--r-- | Documentation/ABI/stable/vdso | 27 |
4 files changed, 274 insertions, 0 deletions
diff --git a/Documentation/ABI/stable/firewire-cdev b/Documentation/ABI/stable/firewire-cdev new file mode 100644 index 0000000..16d0308 --- /dev/null +++ b/Documentation/ABI/stable/firewire-cdev @@ -0,0 +1,103 @@ +What: /dev/fw[0-9]+ +Date: May 2007 +KernelVersion: 2.6.22 +Contact: linux1394-devel@lists.sourceforge.net +Description: + The character device files /dev/fw* are the interface between + firewire-core and IEEE 1394 device drivers implemented in + userspace. The ioctl(2)- and read(2)-based ABI is defined and + documented in <linux/firewire-cdev.h>. + + This ABI offers most of the features which firewire-core also + exposes to kernelspace IEEE 1394 drivers. + + Each /dev/fw* is associated with one IEEE 1394 node, which can + be remote or local nodes. Operations on a /dev/fw* file have + different scope: + - The 1394 node which is associated with the file: + - Asynchronous request transmission + - Get the Configuration ROM + - Query node ID + - Query maximum speed of the path between this node + and local node + - The 1394 bus (i.e. "card") to which the node is attached to: + - Isochronous stream transmission and reception + - Asynchronous stream transmission and reception + - Asynchronous broadcast request transmission + - PHY packet transmission and reception + - Allocate, reallocate, deallocate isochronous + resources (channels, bandwidth) at the bus's IRM + - Query node IDs of local node, root node, IRM, bus + manager + - Query cycle time + - Bus reset initiation, bus reset event reception + - All 1394 buses: + - Allocation of IEEE 1212 address ranges on the local + link layers, reception of inbound requests to such + an address range, asynchronous response transmission + to inbound requests + - Addition of descriptors or directories to the local + nodes' Configuration ROM + + Due to the different scope of operations and in order to let + userland implement different access permission models, some + operations are restricted to /dev/fw* files that are associated + with a local node: + - Addition of descriptors or directories to the local + nodes' Configuration ROM + - PHY packet transmission and reception + + A /dev/fw* file remains associated with one particular node + during its entire life time. Bus topology changes, and hence + node ID changes, are tracked by firewire-core. ABI users do not + need to be aware of topology. + + The following file operations are supported: + + open(2) + Currently the only useful flags are O_RDWR. + + ioctl(2) + Initiate various actions. Some take immediate effect, others + are performed asynchronously while or after the ioctl returns. + See the inline documentation in <linux/firewire-cdev.h> for + descriptions of all ioctls. + + poll(2), select(2), epoll_wait(2) etc. + Watch for events to become available to be read. + + read(2) + Receive various events. There are solicited events like + outbound asynchronous transaction completion or isochronous + buffer completion, and unsolicited events such as bus resets, + request reception, or PHY packet reception. Always use a read + buffer which is large enough to receive the largest event that + could ever arrive. See <linux/firewire-cdev.h> for descriptions + of all event types and for which ioctls affect reception of + events. + + mmap(2) + Allocate a DMA buffer for isochronous reception or transmission + and map it into the process address space. The arguments should + be used as follows: addr = NULL, length = the desired buffer + size, i.e. number of packets times size of largest packet, + prot = at least PROT_READ for reception and at least PROT_WRITE + for transmission, flags = MAP_SHARED, fd = the handle to the + /dev/fw*, offset = 0. + + Isochronous reception works in packet-per-buffer fashion except + for multichannel reception which works in buffer-fill mode. + + munmap(2) + Unmap the isochronous I/O buffer from the process address space. + + close(2) + Besides stopping and freeing I/O contexts that were associated + with the file descriptor, back out any changes to the local + nodes' Configuration ROM. Deallocate isochronous channels and + bandwidth at the IRM that were marked for kernel-assisted + re- and deallocation. + +Users: libraw1394 + libdc1394 + tools like jujuutils, fwhack, ... diff --git a/Documentation/ABI/stable/sysfs-acpi-pmprofile b/Documentation/ABI/stable/sysfs-acpi-pmprofile new file mode 100644 index 0000000..964c7a8 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-acpi-pmprofile @@ -0,0 +1,22 @@ +What: /sys/firmware/acpi/pm_profile +Date: 03-Nov-2011 +KernelVersion: v3.2 +Contact: linux-acpi@vger.kernel.org +Description: The ACPI pm_profile sysfs interface exports the platform + power management (and performance) requirement expectations + as provided by BIOS. The integer value is directly passed as + retrieved from the FADT ACPI table. +Values: For possible values see ACPI specification: + 5.2.9 Fixed ACPI Description Table (FADT) + Field: Preferred_PM_Profile + + Currently these values are defined by spec: + 0 Unspecified + 1 Desktop + 2 Mobile + 3 Workstation + 4 Enterprise Server + 5 SOHO Server + 6 Appliance PC + 7 Performance Server + >7 Reserved diff --git a/Documentation/ABI/stable/sysfs-bus-firewire b/Documentation/ABI/stable/sysfs-bus-firewire new file mode 100644 index 0000000..3d484e5 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-bus-firewire @@ -0,0 +1,122 @@ +What: /sys/bus/firewire/devices/fw[0-9]+/ +Date: May 2007 +KernelVersion: 2.6.22 +Contact: linux1394-devel@lists.sourceforge.net +Description: + IEEE 1394 node device attributes. + Read-only. Mutable during the node device's lifetime. + See IEEE 1212 for semantic definitions. + + config_rom + Contents of the Configuration ROM register. + Binary attribute; an array of host-endian u32. + + guid + The node's EUI-64 in the bus information block of + Configuration ROM. + Hexadecimal string representation of an u64. + + +What: /sys/bus/firewire/devices/fw[0-9]+/units +Date: June 2009 +KernelVersion: 2.6.31 +Contact: linux1394-devel@lists.sourceforge.net +Description: + IEEE 1394 node device attribute. + Read-only. Mutable during the node device's lifetime. + See IEEE 1212 for semantic definitions. + + units + Summary of all units present in an IEEE 1394 node. + Contains space-separated tuples of specifier_id and + version of each unit present in the node. Specifier_id + and version are hexadecimal string representations of + u24 of the respective unit directory entries. + Specifier_id and version within each tuple are separated + by a colon. + +Users: udev rules to set ownership and access permissions or ACLs of + /dev/fw[0-9]+ character device files + + +What: /sys/bus/firewire/devices/fw[0-9]+[.][0-9]+/ +Date: May 2007 +KernelVersion: 2.6.22 +Contact: linux1394-devel@lists.sourceforge.net +Description: + IEEE 1394 unit device attributes. + Read-only. Immutable during the unit device's lifetime. + See IEEE 1212 for semantic definitions. + + modalias + Same as MODALIAS in the uevent at device creation. + + rom_index + Offset of the unit directory within the parent device's + (node device's) Configuration ROM, in quadlets. + Decimal string representation. + + +What: /sys/bus/firewire/devices/*/ +Date: May 2007 +KernelVersion: 2.6.22 +Contact: linux1394-devel@lists.sourceforge.net +Description: + Attributes common to IEEE 1394 node devices and unit devices. + Read-only. Mutable during the node device's lifetime. + Immutable during the unit device's lifetime. + See IEEE 1212 for semantic definitions. + + These attributes are only created if the root directory of an + IEEE 1394 node or the unit directory of an IEEE 1394 unit + actually contains according entries. + + hardware_version + Hexadecimal string representation of an u24. + + hardware_version_name + Contents of a respective textual descriptor leaf. + + model + Hexadecimal string representation of an u24. + + model_name + Contents of a respective textual descriptor leaf. + + specifier_id + Hexadecimal string representation of an u24. + Mandatory in unit directories according to IEEE 1212. + + vendor + Hexadecimal string representation of an u24. + Mandatory in the root directory according to IEEE 1212. + + vendor_name + Contents of a respective textual descriptor leaf. + + version + Hexadecimal string representation of an u24. + Mandatory in unit directories according to IEEE 1212. + + +What: /sys/bus/firewire/drivers/sbp2/fw*/host*/target*/*:*:*:*/ieee1394_id + formerly + /sys/bus/ieee1394/drivers/sbp2/fw*/host*/target*/*:*:*:*/ieee1394_id +Date: Feb 2004 +KernelVersion: 2.6.4 +Contact: linux1394-devel@lists.sourceforge.net +Description: + SCSI target port identifier and logical unit identifier of a + logical unit of an SBP-2 target. The identifiers are specified + in SAM-2...SAM-4 annex A. They are persistent and world-wide + unique properties the SBP-2 attached target. + + Read-only attribute, immutable during the target's lifetime. + Format, as exposed by firewire-sbp2 since 2.6.22, May 2007: + Colon-separated hexadecimal string representations of + u64 EUI-64 : u24 directory_ID : u16 LUN + without 0x prefixes, without whitespace. The former sbp2 driver + (removed in 2.6.37 after being superseded by firewire-sbp2) used + a somewhat shorter format which was not as close to SAM. + +Users: udev rules to create /dev/disk/by-id/ symlinks diff --git a/Documentation/ABI/stable/vdso b/Documentation/ABI/stable/vdso new file mode 100644 index 0000000..8a1cbb5 --- /dev/null +++ b/Documentation/ABI/stable/vdso @@ -0,0 +1,27 @@ +On some architectures, when the kernel loads any userspace program it +maps an ELF DSO into that program's address space. This DSO is called +the vDSO and it often contains useful and highly-optimized alternatives +to real syscalls. + +These functions are called just like ordinary C function according to +your platform's ABI. Call them from a sensible context. (For example, +if you set CS on x86 to something strange, the vDSO functions are +within their rights to crash.) In addition, if you pass a bad +pointer to a vDSO function, you might get SIGSEGV instead of -EFAULT. + +To find the DSO, parse the auxiliary vector passed to the program's +entry point. The AT_SYSINFO_EHDR entry will point to the vDSO. + +The vDSO uses symbol versioning; whenever you request a symbol from the +vDSO, specify the version you are expecting. + +Programs that dynamically link to glibc will use the vDSO automatically. +Otherwise, you can use the reference parser in Documentation/vDSO/parse_vdso.c. + +Unless otherwise noted, the set of symbols with any given version and the +ABI of those symbols is considered stable. It may vary across architectures, +though. + +(As of this writing, this ABI documentation as been confirmed for x86_64. + The maintainers of the other vDSO-using architectures should confirm + that it is correct for their architecture.)
\ No newline at end of file |