redonkable
/
remarkable-linux
1
0
Fork 0
Code Releases Activity

Merge git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git

wifi-calibration
David Woodhouse 2008-02-03 18:29:41 +11:00
parent e619a75ff6 9135f1901e
commit c1f3ee120b
7221 changed files with 515171 additions and 269298 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -17,6 +17,7 @@
*.i
*.lst
*.symtypes
*.order
#
# Top-level generic files

16
CREDITS
View File

@ -1353,6 +1353,14 @@ S: Gen Stedmanstraat 212
S: 5623 HZ Eindhoven
S: The Netherlands
N: Oliver Hartkopp
E: oliver.hartkopp@volkswagen.de
W: http://www.volkswagen.de
D: Controller Area Network (network layer core)
S: Brieffach 1776
S: 38436 Wolfsburg
S: Germany
N: Andrew Haylett
E: ajh@primag.co.uk
D: Selection mechanism
@ -3306,6 +3314,14 @@ S: Universit=E9 de Rennes I
S: F-35042 Rennes Cedex
S: France
N: Urs Thuermann
E: urs.thuermann@volkswagen.de
W: http://www.volkswagen.de
D: Controller Area Network (network layer core)
S: Brieffach 1776
S: 38436 Wolfsburg
S: Germany
N: Jon Tombs
E: jon@gte.esi.us.es
W: http://www.esi.us.es/~jon

2
Documentation/00-INDEX
View File

@ -262,6 +262,8 @@ mtrr.txt
- how to use PPro Memory Type Range Registers to increase performance.
mutex-design.txt
- info on the generic mutex subsystem.
namespaces/
- directory with various information about namespaces
nbd.txt
- info on a TCP implementation of a network block device.
netlabel/

33
Documentation/ABI/testing/sysfs-bus-usb
View File

@ -52,3 +52,36 @@ Description:
facility is inherently dangerous, it is disabled by default
for all devices except hubs. For more information, see
Documentation/usb/persist.txt.
What: /sys/bus/usb/device/.../power/connected_duration
Date: January 2008
KernelVersion: 2.6.25
Contact: Sarah Sharp <sarah.a.sharp@intel.com>
Description:
If CONFIG_PM and CONFIG_USB_SUSPEND are enabled, then this file
is present. When read, it returns the total time (in msec)
that the USB device has been connected to the machine. This
file is read-only.
Users:
PowerTOP <power@bughost.org>
http://www.lesswatts.org/projects/powertop/
What: /sys/bus/usb/device/.../power/active_duration
Date: January 2008
KernelVersion: 2.6.25
Contact: Sarah Sharp <sarah.a.sharp@intel.com>
Description:
If CONFIG_PM and CONFIG_USB_SUSPEND are enabled, then this file
is present. When read, it returns the total time (in msec)
that the USB device has been active, i.e. not in a suspended
state. This file is read-only.
Tools can use this file and the connected_duration file to
compute the percentage of time that a device has been active.
For example,
echo $((100 * `cat active_duration` / `cat connected_duration`))
will give an integer percentage. Note that this does not
account for counter wrap.
Users:
PowerTOP <power@bughost.org>
http://www.lesswatts.org/projects/powertop/

14
Documentation/ABI/testing/sysfs-kernel-uids 100644
View File

@ -0,0 +1,14 @@
What: /sys/kernel/uids/<uid>/cpu_shares
Date: December 2007
Contact: Dhaval Giani <dhaval@linux.vnet.ibm.com>
Srivatsa Vaddagiri <vatsa@linux.vnet.ibm.com>
Description:
The /sys/kernel/uids/<uid>/cpu_shares tunable is used
to set the cpu bandwidth a user is allowed. This is a
propotional value. What that means is that if there
are two users logged in, each with an equal number of
shares, then they will get equal CPU bandwidth. Another
example would be, if User A has shares = 1024 and user
B has shares = 2048, User B will get twice the CPU
bandwidth user A will. For more details refer
Documentation/sched-design-CFS.txt

2
Documentation/DocBook/Makefile
View File

@ -11,7 +11,7 @@ DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \
procfs-guide.xml writing_usb_driver.xml \
kernel-api.xml filesystems.xml lsm.xml usb.xml \
gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
genericirq.xml s390-drivers.xml
genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml
###
# The build process is as follows (targets):

8
Documentation/DocBook/kernel-api.tmpl
View File

@ -419,7 +419,13 @@ X!Edrivers/pnp/system.c
<chapter id="blkdev">
<title>Block Devices</title>
!Eblock/ll_rw_blk.c
!Eblock/blk-core.c
!Eblock/blk-map.c
!Iblock/blk-sysfs.c
!Eblock/blk-settings.c
!Eblock/blk-exec.c
!Eblock/blk-barrier.c
!Eblock/blk-tag.c
</chapter>
<chapter id="chrdev">

6
Documentation/DocBook/rapidio.tmpl
View File

@ -133,9 +133,9 @@
!Idrivers/rapidio/rio-sysfs.c
</sect1>
<sect1><title>PPC32 support</title>
!Iarch/ppc/kernel/rio.c
!Earch/ppc/syslib/ppc85xx_rio.c
!Iarch/ppc/syslib/ppc85xx_rio.c
!Iarch/powerpc/kernel/rio.c
!Earch/powerpc/sysdev/fsl_rio.c
!Iarch/powerpc/sysdev/fsl_rio.c
</sect1>
</chapter>

1
Documentation/DocBook/s390-drivers.tmpl
View File

@ -116,6 +116,7 @@
!Iinclude/asm-s390/ccwdev.h
!Edrivers/s390/cio/device.c
!Edrivers/s390/cio/device_ops.c
!Edrivers/s390/cio/airq.c
</sect1>
<sect1 id="cmf">
<title>The channel-measurement facility</title>

409
Documentation/DocBook/scsi.tmpl 100644
View File

@ -0,0 +1,409 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
<book id="scsimid">
<bookinfo>
<title>SCSI Interfaces Guide</title>
<authorgroup>
<author>
<firstname>James</firstname>
<surname>Bottomley</surname>
<affiliation>
<address>
<email>James.Bottomley@steeleye.com</email>
</address>
</affiliation>
</author>
<author>
<firstname>Rob</firstname>
<surname>Landley</surname>
<affiliation>
<address>
<email>rob@landley.net</email>
</address>
</affiliation>
</author>
</authorgroup>
<copyright>
<year>2007</year>
<holder>Linux Foundation</holder>
</copyright>
<legalnotice>
<para>
This documentation is free software; you can redistribute
it and/or modify it under the terms of the GNU General Public
License version 2.
</para>
<para>
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.
For more details see the file COPYING in the source
distribution of Linux.
</para>
</legalnotice>
</bookinfo>
<toc></toc>
<chapter id="intro">
<title>Introduction</title>
<sect1 id="protocol_vs_bus">
<title>Protocol vs bus</title>
<para>
Once upon a time, the Small Computer Systems Interface defined both
a parallel I/O bus and a data protocol to connect a wide variety of
peripherals (disk drives, tape drives, modems, printers, scanners,
optical drives, test equipment, and medical devices) to a host
computer.
</para>
<para>
Although the old parallel (fast/wide/ultra) SCSI bus has largely
fallen out of use, the SCSI command set is more widely used than ever
to communicate with devices over a number of different busses.
</para>
<para>
The <ulink url='http://www.t10.org/scsi-3.htm'>SCSI protocol</ulink>
is a big-endian peer-to-peer packet based protocol. SCSI commands
are 6, 10, 12, or 16 bytes long, often followed by an associated data
payload.
</para>
<para>
SCSI commands can be transported over just about any kind of bus, and
are the default protocol for storage devices attached to USB, SATA,
SAS, Fibre Channel, FireWire, and ATAPI devices. SCSI packets are
also commonly exchanged over Infiniband,
<ulink url='http://i2o.shadowconnect.com/faq.php'>I20</ulink>, TCP/IP
(<ulink url='http://en.wikipedia.org/wiki/ISCSI'>iSCSI</ulink>), even
<ulink url='http://cyberelk.net/tim/parport/parscsi.html'>Parallel
ports</ulink>.
</para>
</sect1>
<sect1 id="subsystem_design">
<title>Design of the Linux SCSI subsystem</title>
<para>
The SCSI subsystem uses a three layer design, with upper, mid, and low
layers. Every operation involving the SCSI subsystem (such as reading
a sector from a disk) uses one driver at each of the 3 levels: one
upper layer driver, one lower layer driver, and the SCSI midlayer.
</para>
<para>
The SCSI upper layer provides the interface between userspace and the
kernel, in the form of block and char device nodes for I/O and
ioctl(). The SCSI lower layer contains drivers for specific hardware
devices.
</para>
<para>
In between is the SCSI mid-layer, analogous to a network routing
layer such as the IPv4 stack. The SCSI mid-layer routes a packet
based data protocol between the upper layer's /dev nodes and the
corresponding devices in the lower layer. It manages command queues,
provides error handling and power management functions, and responds
to ioctl() requests.
</para>
</sect1>
</chapter>
<chapter id="upper_layer">
<title>SCSI upper layer</title>
<para>
The upper layer supports the user-kernel interface by providing
device nodes.
</para>
<sect1 id="sd">
<title>sd (SCSI Disk)</title>
<para>sd (sd_mod.o)</para>
<!-- !Idrivers/scsi/sd.c -->
</sect1>
<sect1 id="sr">
<title>sr (SCSI CD-ROM)</title>
<para>sr (sr_mod.o)</para>
</sect1>
<sect1 id="st">
<title>st (SCSI Tape)</title>
<para>st (st.o)</para>
</sect1>
<sect1 id="sg">
<title>sg (SCSI Generic)</title>
<para>sg (sg.o)</para>
</sect1>
<sect1 id="ch">
<title>ch (SCSI Media Changer)</title>
<para>ch (ch.c)</para>
</sect1>
</chapter>
<chapter id="mid_layer">
<title>SCSI mid layer</title>
<sect1 id="midlayer_implementation">
<title>SCSI midlayer implementation</title>
<sect2 id="scsi_device.h">
<title>include/scsi/scsi_device.h</title>
<para>
</para>
!Iinclude/scsi/scsi_device.h
</sect2>
<sect2 id="scsi.c">
<title>drivers/scsi/scsi.c</title>
<para>Main file for the SCSI midlayer.</para>
!Edrivers/scsi/scsi.c
</sect2>
<sect2 id="scsicam.c">
<title>drivers/scsi/scsicam.c</title>
<para>
<ulink url='http://www.t10.org/ftp/t10/drafts/cam/cam-r12b.pdf'>SCSI
Common Access Method</ulink> support functions, for use with
HDIO_GETGEO, etc.
</para>
!Edrivers/scsi/scsicam.c
</sect2>
<sect2 id="scsi_error.c">
<title>drivers/scsi/scsi_error.c</title>
<para>Common SCSI error/timeout handling routines.</para>
!Edrivers/scsi/scsi_error.c
</sect2>
<sect2 id="scsi_devinfo.c">
<title>drivers/scsi/scsi_devinfo.c</title>
<para>
Manage scsi_dev_info_list, which tracks blacklisted and whitelisted
devices.
</para>
!Idrivers/scsi/scsi_devinfo.c
</sect2>
<sect2 id="scsi_ioctl.c">
<title>drivers/scsi/scsi_ioctl.c</title>
<para>
Handle ioctl() calls for SCSI devices.
</para>
!Edrivers/scsi/scsi_ioctl.c
</sect2>
<sect2 id="scsi_lib.c">
<title>drivers/scsi/scsi_lib.c</title>
<para>
SCSI queuing library.
</para>
!Edrivers/scsi/scsi_lib.c
</sect2>
<sect2 id="scsi_lib_dma.c">
<title>drivers/scsi/scsi_lib_dma.c</title>
<para>
SCSI library functions depending on DMA
(map and unmap scatter-gather lists).
</para>
!Edrivers/scsi/scsi_lib_dma.c
</sect2>
<sect2 id="scsi_module.c">
<title>drivers/scsi/scsi_module.c</title>
<para>
The file drivers/scsi/scsi_module.c contains legacy support for
old-style host templates. It should never be used by any new driver.
</para>
</sect2>
<sect2 id="scsi_proc.c">
<title>drivers/scsi/scsi_proc.c</title>
<para>
The functions in this file provide an interface between
the PROC file system and the SCSI device drivers
It is mainly used for debugging, statistics and to pass
information directly to the lowlevel driver.
I.E. plumbing to manage /proc/scsi/*
</para>
!Idrivers/scsi/scsi_proc.c
</sect2>
<sect2 id="scsi_netlink.c">
<title>drivers/scsi/scsi_netlink.c</title>
<para>
Infrastructure to provide async events from transports to userspace
via netlink, using a single NETLINK_SCSITRANSPORT protocol for all
transports.
See <ulink url='http://marc.info/?l=linux-scsi&amp;m=115507374832500&amp;w=2'>the
original patch submission</ulink> for more details.
</para>
!Idrivers/scsi/scsi_netlink.c
</sect2>
<sect2 id="scsi_scan.c">
<title>drivers/scsi/scsi_scan.c</title>
<para>
Scan a host to determine which (if any) devices are attached.
The general scanning/probing algorithm is as follows, exceptions are
made to it depending on device specific flags, compilation options,
and global variable (boot or module load time) settings.
A specific LUN is scanned via an INQUIRY command; if the LUN has a
device attached, a scsi_device is allocated and setup for it.
For every id of every channel on the given host, start by scanning
LUN 0. Skip hosts that don't respond at all to a scan of LUN 0.
Otherwise, if LUN 0 has a device attached, allocate and setup a
scsi_device for it. If target is SCSI-3 or up, issue a REPORT LUN,
and scan all of the LUNs returned by the REPORT LUN; else,
sequentially scan LUNs up until some maximum is reached, or a LUN is
seen that cannot have a device attached to it.
</para>
!Idrivers/scsi/scsi_scan.c
</sect2>
<sect2 id="scsi_sysctl.c">
<title>drivers/scsi/scsi_sysctl.c</title>
<para>
Set up the sysctl entry: "/dev/scsi/logging_level"
(DEV_SCSI_LOGGING_LEVEL) which sets/returns scsi_logging_level.
</para>
</sect2>
<sect2 id="scsi_sysfs.c">
<title>drivers/scsi/scsi_sysfs.c</title>
<para>
SCSI sysfs interface routines.
</para>
!Edrivers/scsi/scsi_sysfs.c
</sect2>
<sect2 id="hosts.c">
<title>drivers/scsi/hosts.c</title>
<para>
mid to lowlevel SCSI driver interface
</para>
!Edrivers/scsi/hosts.c
</sect2>
<sect2 id="constants.c">
<title>drivers/scsi/constants.c</title>
<para>
mid to lowlevel SCSI driver interface
</para>
!Edrivers/scsi/constants.c
</sect2>
</sect1>
<sect1 id="Transport_classes">
<title>Transport classes</title>
<para>
Transport classes are service libraries for drivers in the SCSI
lower layer, which expose transport attributes in sysfs.
</para>
<sect2 id="Fibre_Channel_transport">
<title>Fibre Channel transport</title>
<para>
The file drivers/scsi/scsi_transport_fc.c defines transport attributes
for Fibre Channel.
</para>
!Edrivers/scsi/scsi_transport_fc.c
</sect2>
<sect2 id="iSCSI_transport">
<title>iSCSI transport class</title>
<para>
The file drivers/scsi/scsi_transport_iscsi.c defines transport
attributes for the iSCSI class, which sends SCSI packets over TCP/IP
connections.
</para>
!Edrivers/scsi/scsi_transport_iscsi.c
</sect2>
<sect2 id="SAS_transport">
<title>Serial Attached SCSI (SAS) transport class</title>
<para>
The file drivers/scsi/scsi_transport_sas.c defines transport
attributes for Serial Attached SCSI, a variant of SATA aimed at
large high-end systems.
</para>
<para>
The SAS transport class contains common code to deal with SAS HBAs,
an aproximated representation of SAS topologies in the driver model,
and various sysfs attributes to expose these topologies and managment
interfaces to userspace.
</para>
<para>
In addition to the basic SCSI core objects this transport class
introduces two additional intermediate objects: The SAS PHY
as represented by struct sas_phy defines an "outgoing" PHY on
a SAS HBA or Expander, and the SAS remote PHY represented by
struct sas_rphy defines an "incoming" PHY on a SAS Expander or
end device. Note that this is purely a software concept, the
underlying hardware for a PHY and a remote PHY is the exactly
the same.
</para>
<para>
There is no concept of a SAS port in this code, users can see
what PHYs form a wide port based on the port_identifier attribute,
which is the same for all PHYs in a port.
</para>
!Edrivers/scsi/scsi_transport_sas.c
</sect2>
<sect2 id="SATA_transport">
<title>SATA transport class</title>
<para>
The SATA transport is handled by libata, which has its own book of
documentation in this directory.
</para>
</sect2>
<sect2 id="SPI_transport">
<title>Parallel SCSI (SPI) transport class</title>
<para>
The file drivers/scsi/scsi_transport_spi.c defines transport
attributes for traditional (fast/wide/ultra) SCSI busses.
</para>
!Edrivers/scsi/scsi_transport_spi.c
</sect2>
<sect2 id="SRP_transport">
<title>SCSI RDMA (SRP) transport class</title>
<para>
The file drivers/scsi/scsi_transport_srp.c defines transport
attributes for SCSI over Remote Direct Memory Access.
</para>
!Edrivers/scsi/scsi_transport_srp.c
</sect2>
</sect1>
</chapter>
<chapter id="lower_layer">
<title>SCSI lower layer</title>
<sect1 id="hba_drivers">
<title>Host Bus Adapter transport types</title>
<para>
Many modern device controllers use the SCSI command set as a protocol to
communicate with their devices through many different types of physical
connections.
</para>
<para>
In SCSI language a bus capable of carrying SCSI commands is
called a "transport", and a controller connecting to such a bus is
called a "host bus adapter" (HBA).
</para>
<sect2 id="scsi_debug.c">
<title>Debug transport</title>
<para>
The file drivers/scsi/scsi_debug.c simulates a host adapter with a
variable number of disks (or disk like devices) attached, sharing a
common amount of RAM. Does a lot of checking to make sure that we are
not getting blocks mixed up, and panics the kernel if anything out of
the ordinary is seen.
</para>
<para>
To be more realistic, the simulated devices have the transport
attributes of SAS disks.
</para>
<para>
For documentation see
<ulink url='http://www.torque.net/sg/sdebug26.html'>http://www.torque.net/sg/sdebug26.html</ulink>
</para>
<!-- !Edrivers/scsi/scsi_debug.c -->
</sect2>
<sect2 id="todo">
<title>todo</title>
<para>Parallel (fast/wide/ultra) SCSI, USB, SATA,
SAS, Fibre Channel, FireWire, ATAPI devices, Infiniband,
I20, iSCSI, Parallel ports, netlink...
</para>
</sect2>
</sect1>
</chapter>
</book>

90
Documentation/DocBook/uio-howto.tmpl
View File

@ -29,6 +29,12 @@
</abstract>
<revhistory>
<revision>
<revnumber>0.4</revnumber>
<date>2007-11-26</date>
<authorinitials>hjk</authorinitials>
<revremark>Removed section about uio_dummy.</revremark>
</revision>
<revision>
<revnumber>0.3</revnumber>
<date>2007-04-29</date>
@ -94,6 +100,26 @@ interested in translating it, please email me
user space. This simplifies development and reduces the risk of
serious bugs within a kernel module.
</para>
<para>
Please note that UIO is not an universal driver interface. Devices
that are already handled well by other kernel subsystems (like
networking or serial or USB) are no candidates for an UIO driver.
Hardware that is ideally suited for an UIO driver fulfills all of
the following:
</para>
<itemizedlist>
<listitem>
<para>The device has memory that can be mapped. The device can be
controlled completely by writing to this memory.</para>
</listitem>
<listitem>
<para>The device usually generates interrupts.</para>
</listitem>
<listitem>
<para>The device does not fit into one of the standard kernel
subsystems.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="thanks">
@ -174,8 +200,9 @@ interested in translating it, please email me
For cards that don't generate interrupts but need to be
polled, there is the possibility to set up a timer that
triggers the interrupt handler at configurable time intervals.
See <filename>drivers/uio/uio_dummy.c</filename> for an
example of this technique.
This interrupt simulation is done by calling
<function>uio_event_notify()</function>
from the timer's event handler.
</para>
<para>
@ -263,63 +290,11 @@ offset = N * getpagesize();
</sect1>
</chapter>
<chapter id="using-uio_dummy" xreflabel="Using uio_dummy">
<?dbhtml filename="using-uio_dummy.html"?>
<title>Using uio_dummy</title>
<para>
Well, there is no real use for uio_dummy. Its only purpose is
to test most parts of the UIO system (everything except
hardware interrupts), and to serve as an example for the
kernel module that you will have to write yourself.
</para>
<sect1 id="what_uio_dummy_does">
<title>What uio_dummy does</title>
<para>
The kernel module <filename>uio_dummy.ko</filename> creates a
device that uses a timer to generate periodic interrupts. The
interrupt handler does nothing but increment a counter. The
driver adds two custom attributes, <varname>count</varname>
and <varname>freq</varname>, that appear under
<filename>/sys/devices/platform/uio_dummy/</filename>.
</para>
<para>
The attribute <varname>count</varname> can be read and
written. The associated file
<filename>/sys/devices/platform/uio_dummy/count</filename>
appears as a normal text file and contains the total number of
timer interrupts. If you look at it (e.g. using
<function>cat</function>), you'll notice it is slowly counting
up.
</para>
<para>
The attribute <varname>freq</varname> can be read and written.
The content of
<filename>/sys/devices/platform/uio_dummy/freq</filename>
represents the number of system timer ticks between two timer
interrupts. The default value of <varname>freq</varname> is
the value of the kernel variable <varname>HZ</varname>, which
gives you an interval of one second. Lower values will
increase the frequency. Try the following:
</para>
<programlisting format="linespecific">
cd /sys/devices/platform/uio_dummy/
echo 100 > freq
</programlisting>
<para>
Use <function>cat count</function> to see how the interrupt
frequency changes.
</para>
</sect1>
</chapter>
<chapter id="custom_kernel_module" xreflabel="Writing your own kernel module">
<?dbhtml filename="custom_kernel_module.html"?>
<title>Writing your own kernel module</title>
<para>
Please have a look at <filename>uio_dummy.c</filename> as an
Please have a look at <filename>uio_cif.c</filename> as an
example. The following paragraphs explain the different
sections of this file.
</para>
@ -354,9 +329,8 @@ See the description below for details.
interrupt, it's your modules task to determine the irq number during
initialization. If you don't have a hardware generated interrupt but
want to trigger the interrupt handler in some other way, set
<varname>irq</varname> to <varname>UIO_IRQ_CUSTOM</varname>. The
uio_dummy module does this as it triggers the event mechanism in a timer
routine. If you had no interrupt at all, you could set
<varname>irq</varname> to <varname>UIO_IRQ_CUSTOM</varname>.
If you had no interrupt at all, you could set
<varname>irq</varname> to <varname>UIO_IRQ_NONE</varname>, though this
rarely makes sense.
</para></listitem>

9
Documentation/DocBook/videobook.tmpl
View File

@ -96,7 +96,6 @@ static struct video_device my_radio
{
"My radio",
VID_TYPE_TUNER,
VID_HARDWARE_MYRADIO,
radio_open.
radio_close,
NULL, /* no read */
@ -118,13 +117,6 @@ static struct video_device my_radio
indicates that the device can be tuned. Clearly our radio is going to have some
way to change channel so it is tuneable.
</para>
<para>
The VID_HARDWARE_ types are unique to each device. Numbers are assigned by
<email>alan@redhat.com</email> when device drivers are going to be released. Until then you
can pull a suitably large number out of your hat and use it. 10000 should be
safe for a very long time even allowing for the huge number of vendors
making new and different radio cards at the moment.
</para>
<para>
We declare an open and close routine, but we do not need read or write,
which are used to read and write video data to or from the card itself. As
@ -844,7 +836,6 @@ static struct video_device my_camera
"My Camera",
VID_TYPE_OVERLAY|VID_TYPE_SCALES|\
VID_TYPE_CAPTURE|VID_TYPE_CHROMAKEY,
VID_HARDWARE_MYCAMERA,
camera_open.
camera_close,
camera_read, /* no read */

210
Documentation/RCU/RTFP.txt
View File

@ -9,8 +9,8 @@ The first thing resembling RCU was published in 1980, when Kung and Lehman
[Kung80] recommended use of a garbage collector to defer destruction
of nodes in a parallel binary search tree in order to simplify its
implementation. This works well in environments that have garbage
collectors, but current production garbage collectors incur significant
read-side overhead.
collectors, but most production garbage collectors incur significant
overhead.
In 1982, Manber and Ladner [Manber82,Manber84] recommended deferring
destruction until all threads running at that time have terminated, again
@ -99,16 +99,25 @@ locking, reduces contention, reduces memory latency for readers, and
parallelizes pipeline stalls and memory latency for writers. However,
these techniques still impose significant read-side overhead in the
form of memory barriers. Researchers at Sun worked along similar lines
in the same timeframe [HerlihyLM02,HerlihyLMS03]. These techniques
can be thought of as inside-out reference counts, where the count is
represented by the number of hazard pointers referencing a given data
structure (rather than the more conventional counter field within the
data structure itself).
in the same timeframe [HerlihyLM02]. These techniques can be thought
of as inside-out reference counts, where the count is represented by the
number of hazard pointers referencing a given data structure (rather than
the more conventional counter field within the data structure itself).
By the same token, RCU can be thought of as a "bulk reference count",
where some form of reference counter covers all reference by a given CPU
or thread during a set timeframe. This timeframe is related to, but
not necessarily exactly the same as, an RCU grace period. In classic
RCU, the reference counter is the per-CPU bit in the "bitmask" field,
and each such bit covers all references that might have been made by
the corresponding CPU during the prior grace period. Of course, RCU
can be thought of in other terms as well.
In 2003, the K42 group described how RCU could be used to create
hot-pluggable implementations of operating-system functions. Later that
year saw a paper describing an RCU implementation of System V IPC
[Arcangeli03], and an introduction to RCU in Linux Journal [McKenney03a].
hot-pluggable implementations of operating-system functions [Appavoo03a].
Later that year saw a paper describing an RCU implementation of System
V IPC [Arcangeli03], and an introduction to RCU in Linux Journal
[McKenney03a].
2004 has seen a Linux-Journal article on use of RCU in dcache
[McKenney04a], a performance comparison of locking to RCU on several
@ -117,10 +126,19 @@ number of operating-system kernels [PaulEdwardMcKenneyPhD], a paper
describing how to make RCU safe for soft-realtime applications [Sarma04c],
and a paper describing SELinux performance with RCU [JamesMorris04b].
2005 has seen further adaptation of RCU to realtime use, permitting
2005 brought further adaptation of RCU to realtime use, permitting
preemption of RCU realtime critical sections [PaulMcKenney05a,
PaulMcKenney05b].
2006 saw the first best-paper award for an RCU paper [ThomasEHart2006a],
as well as further work on efficient implementations of preemptible
RCU [PaulEMcKenney2006b], but priority-boosting of RCU read-side critical
sections proved elusive. An RCU implementation permitting general
blocking in read-side critical sections appeared [PaulEMcKenney2006c],
Robert Olsson described an RCU-protected trie-hash combination
[RobertOlsson2006a].
Bibtex Entries
@article{Kung80
@ -203,6 +221,41 @@ Bibtex Entries
,Address="New Orleans, LA"
}
@conference{Pu95a,
Author = "Calton Pu and Tito Autrey and Andrew Black and Charles Consel and
Crispin Cowan and Jon Inouye and Lakshmi Kethana and Jonathan Walpole and
Ke Zhang",
Title = "Optimistic Incremental Specialization: Streamlining a Commercial
Operating System",
Booktitle = "15\textsuperscript{th} ACM Symposium on
Operating Systems Principles (SOSP'95)",
address = "Copper Mountain, CO",
month="December",
year="1995",
pages="314-321",
annotation="
Uses a replugger, but with a flag to signal when people are
using the resource at hand. Only one reader at a time.
"
}
@conference{Cowan96a,
Author = "Crispin Cowan and Tito Autrey and Charles Krasic and
Calton Pu and Jonathan Walpole",
Title = "Fast Concurrent Dynamic Linking for an Adaptive Operating System",
Booktitle = "International Conference on Configurable Distributed Systems
(ICCDS'96)",
address = "Annapolis, MD",
month="May",
year="1996",
pages="108",
isbn="0-8186-7395-8",
annotation="
Uses a replugger, but with a counter to signal when people are
using the resource at hand. Allows multiple readers.
"
}
@techreport{Slingwine95
,author="John D. Slingwine and Paul E. McKenney"
,title="Apparatus and Method for Achieving Reduced Overhead Mutual
@ -312,6 +365,49 @@ Andrea Arcangeli and Andi Kleen and Orran Krieger and Rusty Russell"
[Viewed June 23, 2004]"
}
@conference{Michael02a
,author="Maged M. Michael"
,title="Safe Memory Reclamation for Dynamic Lock-Free Objects Using Atomic
Reads and Writes"
,Year="2002"
,Month="August"
,booktitle="{Proceedings of the 21\textsuperscript{st} Annual ACM
Symposium on Principles of Distributed Computing}"
,pages="21-30"
,annotation="
Each thread keeps an array of pointers to items that it is
currently referencing. Sort of an inside-out garbage collection
mechanism, but one that requires the accessing code to explicitly
state its needs. Also requires read-side memory barriers on
most architectures.
"
}
@conference{Michael02b
,author="Maged M. Michael"
,title="High Performance Dynamic Lock-Free Hash Tables and List-Based Sets"
,Year="2002"
,Month="August"
,booktitle="{Proceedings of the 14\textsuperscript{th} Annual ACM
Symposium on Parallel
Algorithms and Architecture}"
,pages="73-82"
,annotation="
Like the title says...
"
}
@InProceedings{HerlihyLM02
,author={Maurice Herlihy and Victor Luchangco and Mark Moir}
,title="The Repeat Offender Problem: A Mechanism for Supporting Dynamic-Sized,
Lock-Free Data Structures"
,booktitle={Proceedings of 16\textsuperscript{th} International
Symposium on Distributed Computing}
,year=2002
,month="October"
,pages="339-353"
}
@article{Appavoo03a
,author="J. Appavoo and K. Hui and C. A. N. Soules and R. W. Wisniewski and
D. M. {Da Silva} and O. Krieger and M. A. Auslander and D. J. Edelsohn and
@ -447,3 +543,95 @@ Oregon Health and Sciences University"
Realtime turns into making RCU yet more realtime friendly.
"
}
@conference{ThomasEHart2006a
,Author="Thomas E. Hart and Paul E. McKenney and Angela Demke Brown"
,Title="Making Lockless Synchronization Fast: Performance Implications
of Memory Reclamation"
,Booktitle="20\textsuperscript{th} {IEEE} International Parallel and
Distributed Processing Symposium"
,month="April"
,year="2006"
,day="25-29"
,address="Rhodes, Greece"
,annotation="
Compares QSBR (AKA "classic RCU"), HPBR, EBR, and lock-free
reference counting.
"
}
@Conference{PaulEMcKenney2006b
,Author="Paul E. McKenney and Dipankar Sarma and Ingo Molnar and
Suparna Bhattacharya"
,Title="Extending RCU for Realtime and Embedded Workloads"
,Booktitle="{Ottawa Linux Symposium}"
,Month="July"
,Year="2006"
,pages="v2 123-138"
,note="Available:
\url{http://www.linuxsymposium.org/2006/view_abstract.php?content_key=184}
\url{http://www.rdrop.com/users/paulmck/RCU/OLSrtRCU.2006.08.11a.pdf}
[Viewed January 1, 2007]"
,annotation="
Described how to improve the -rt implementation of realtime RCU.
"
}
@unpublished{PaulEMcKenney2006c
,Author="Paul E. McKenney"
,Title="Sleepable {RCU}"
,month="October"
,day="9"
,year="2006"
,note="Available:
\url{http://lwn.net/Articles/202847/}
Revised:
\url{http://www.rdrop.com/users/paulmck/RCU/srcu.2007.01.14a.pdf}
[Viewed August 21, 2006]"
,annotation="
LWN article introducing SRCU.
"
}
@unpublished{RobertOlsson2006a
,Author="Robert Olsson and Stefan Nilsson"
,Title="{TRASH}: A dynamic {LC}-trie and hash data structure"
,month="August"
,day="18"
,year="2006"
,note="Available:
\url{http://www.nada.kth.se/~snilsson/public/papers/trash/trash.pdf}
[Viewed February 24, 2007]"
,annotation="
RCU-protected dynamic trie-hash combination.
"
}
@unpublished{ThomasEHart2007a
,Author="Thomas E. Hart and Paul E. McKenney and Angela Demke Brown and Jonathan Walpole"
,Title="Performance of memory reclamation for lockless synchronization"
,journal="J. Parallel Distrib. Comput."
,year="2007"
,note="To appear in J. Parallel Distrib. Comput.
\url{doi=10.1016/j.jpdc.2007.04.010}"
,annotation={
Compares QSBR (AKA "classic RCU"), HPBR, EBR, and lock-free
reference counting. Journal version of ThomasEHart2006a.
}
}
@unpublished{PaulEMcKenney2007QRCUspin
,Author="Paul E. McKenney"
,Title="Using Promela and Spin to verify parallel algorithms"
,month="August"
,day="1"
,year="2007"
,note="Available:
\url{http://lwn.net/Articles/243851/}
[Viewed September 8, 2007]"
,annotation="
LWN article describing Promela and spin, and also using Oleg
Nesterov's QRCU as an example (with Paul McKenney's fastpath).
"
}

19
Documentation/RCU/rcu.txt
View File

@ -36,6 +36,14 @@ o How can the updater tell when a grace period has completed
executed in user mode, or executed in the idle loop, we can
safely free up that item.
Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
same effect, but require that the readers manipulate CPU-local
counters. These counters allow limited types of blocking
within RCU read-side critical sections. SRCU also uses
CPU-local counters, and permits general blocking within
RCU read-side critical sections. These two variants of
RCU detect grace periods by sampling these counters.
o If I am running on a uniprocessor kernel, which can only do one
thing at a time, why should I wait for a grace period?
@ -46,7 +54,10 @@ o How can I see where RCU is currently used in the Linux kernel?
Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
"rcu_read_lock_bh", "rcu_read_unlock_bh", "call_rcu_bh",
"srcu_read_lock", "srcu_read_unlock", "synchronize_rcu",
"synchronize_net", and "synchronize_srcu".
"synchronize_net", "synchronize_srcu", and the other RCU
primitives. Or grab one of the cscope databases from:
http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html
o What guidelines should I follow when writing code that uses RCU?
@ -67,7 +78,11 @@ o I hear that RCU is patented? What is with that?
o I hear that RCU needs work in order to support realtime kernels?
Yes, work in progress.
This work is largely completed. Realtime-friendly RCU can be
enabled via the CONFIG_PREEMPT_RCU kernel configuration parameter.
However, work is in progress for enabling priority boosting of
preempted RCU read-side critical sections.This is needed if you
have CPU-bound realtime threads.
o Where can I find more information on RCU?

11
Documentation/RCU/torture.txt
View File

@ -46,12 +46,13 @@ stat_interval The number of seconds between output of torture
shuffle_interval
The number of seconds to keep the test threads affinitied
to a particular subset of the CPUs. Used in conjunction
with test_no_idle_hz.
to a particular subset of the CPUs, defaults to 5 seconds.
Used in conjunction with test_no_idle_hz.
test_no_idle_hz Whether or not to test the ability of RCU to operate in
a kernel that disables the scheduling-clock interrupt to
idle CPUs. Boolean parameter, "1" to test, "0" otherwise.
Defaults to omitting this test.
torture_type The type of RCU to test: "rcu" for the rcu_read_lock() API,
"rcu_sync" for rcu_read_lock() with synchronous reclamation,
@ -82,8 +83,6 @@ be evident. ;-)
The entries are as follows:
o "ggp": The number of counter flips (or batches) since boot.
o "rtc": The hexadecimal address of the structure currently visible
to readers.
@ -117,8 +116,8 @@ o "Reader Pipe": Histogram of "ages" of structures seen by readers.
o "Reader Batch": Another histogram of "ages" of structures seen
by readers, but in terms of counter flips (or batches) rather
than in terms of grace periods. The legal number of non-zero
entries is again two. The reason for this separate view is
that it is easier to get the third entry to show up in the
entries is again two. The reason for this separate view is that
it is sometimes easier to get the third entry to show up in the
"Reader Batch" list than in the "Reader Pipe" list.
o "Free-Block Circulation": Shows the number of torture structures

4
Documentation/SubmittingPatches
View File

@ -464,8 +464,8 @@ section Linus Computer Science 101.
Nuff said. If your code deviates too much from this, it is likely
to be rejected without further review, and without comment.
Once significant exception is when moving code from one file to
another in this case you should not modify the moved code at all in
One significant exception is when moving code from one file to
another -- in this case you should not modify the moved code at all in
the same patch which moves it. This clearly delineates the act of
moving the code and your changes. This greatly aids review of the
actual differences and allows tools to better track the history of

43
Documentation/accounting/getdelays.c
View File

@ -25,6 +25,7 @@
#include <linux/genetlink.h>
#include <linux/taskstats.h>
#include <linux/cgroupstats.h>
/*
* Generic macros for dealing with netlink sockets. Might be duplicated
@ -78,6 +79,7 @@ static void usage(void)
fprintf(stderr, " -i: print IO accounting (works only with -p)\n");
fprintf(stderr, " -l: listen forever\n");
fprintf(stderr, " -v: debug on\n");
fprintf(stderr, " -C: container path\n");
}
/*
@ -212,6 +214,14 @@ void task_context_switch_counts(struct taskstats *t)
t->nvcsw, t->nivcsw);
}
void print_cgroupstats(struct cgroupstats *c)
{
printf("sleeping %llu, blocked %llu, running %llu, stopped %llu, "
"uninterruptible %llu\n", c->nr_sleeping, c->nr_io_wait,
c->nr_running, c->nr_stopped, c->nr_uninterruptible);
}
void print_ioacct(struct taskstats *t)
{
printf("%s: read=%llu, write=%llu, cancelled_write=%llu\n",
@ -239,11 +249,14 @@ int main(int argc, char *argv[])
int maskset = 0;
char *logfile = NULL;
int loop = 0;
int containerset = 0;
char containerpath[1024];
int cfd = 0;
struct msgtemplate msg;
while (1) {
c = getopt(argc, argv, "qdiw:r:m:t:p:vl");
c = getopt(argc, argv, "qdiw:r:m:t:p:vlC:");
if (c < 0)
break;
@ -260,6 +273,10 @@ int main(int argc, char *argv[])
printf("printing task/process context switch rates\n");
print_task_context_switch_counts = 1;
break;
case 'C':
containerset = 1;
strncpy(containerpath, optarg, strlen(optarg) + 1);
break;
case 'w':
logfile = strdup(optarg);
printf("write to file %s\n", logfile);
@ -334,6 +351,11 @@ int main(int argc, char *argv[])
}
}
if (tid && containerset) {
fprintf(stderr, "Select either -t or -C, not both\n");
goto err;
}
if (tid) {
rc = send_cmd(nl_sd, id, mypid, TASKSTATS_CMD_GET,
cmd_type, &tid, sizeof(__u32));
@ -344,6 +366,20 @@ int main(int argc, char *argv[])
}
}
if (containerset) {
cfd = open(containerpath, O_RDONLY);
if (cfd < 0) {
perror("error opening container file");
goto err;
}
rc = send_cmd(nl_sd, id, mypid, CGROUPSTATS_CMD_GET,
CGROUPSTATS_CMD_ATTR_FD, &cfd, sizeof(__u32));
if (rc < 0) {
perror("error sending cgroupstats command");
goto err;
}
}
do {
int i;
@ -422,6 +458,9 @@ int main(int argc, char *argv[])
}
break;
case CGROUPSTATS_TYPE_CGROUP_STATS:
print_cgroupstats(NLA_DATA(na));
break;
default:
fprintf(stderr, "Unknown nla_type %d\n",
na->nla_type);
@ -443,5 +482,7 @@ err:
close(nl_sd);
if (fd)
close(fd);
if (cfd)
close(cfd);
return 0;
}

1
Documentation/cpu-freq/user-guide.txt
View File

@ -45,6 +45,7 @@ The following ARM processors are supported by cpufreq:
ARM Integrator
ARM-SA1100
ARM-SA1110
Intel PXA
1.2 x86

13
Documentation/cpu-hotplug.txt
View File

@ -50,7 +50,7 @@ additional_cpus=n (*) Use this to limit hotpluggable cpus. This option sets
cpu_possible_map = cpu_present_map + additional_cpus
(*) Option valid only for following architectures
- x86_64, ia64, s390
- x86_64, ia64
ia64 and x86_64 use the number of disabled local apics in ACPI tables MADT
to determine the number of potentially hot-pluggable cpus. The implementation
@ -109,12 +109,13 @@ Never use anything other than cpumask_t to represent bitmap of CPUs.
for_each_cpu_mask(x,mask) - Iterate over some random collection of cpu mask.
#include <linux/cpu.h>
lock_cpu_hotplug() and unlock_cpu_hotplug():
get_online_cpus() and put_online_cpus():
The above calls are used to inhibit cpu hotplug operations. While holding the
cpucontrol mutex, cpu_online_map will not change. If you merely need to avoid
cpus going away, you could also use preempt_disable() and preempt_enable()
for those sections. Just remember the critical section cannot call any
The above calls are used to inhibit cpu hotplug operations. While the
cpu_hotplug.refcount is non zero, the cpu_online_map will not change.
If you merely need to avoid cpus going away, you could also use
preempt_disable() and preempt_enable() for those sections.
Just remember the critical section cannot call any
function that can sleep or schedule this process away. The preempt_disable()
will work as long as stop_machine_run() is used to take a cpu down.

41
Documentation/crypto/api-intro.txt
View File

@ -33,9 +33,16 @@ The idea is to make the user interface and algorithm registration API
very simple, while hiding the core logic from both. Many good ideas
from existing APIs such as Cryptoapi and Nettle have been adapted for this.
The API currently supports three types of transforms: Ciphers, Digests and
Compressors. The compression algorithms especially seem to be performing
very well so far.
The API currently supports five main types of transforms: AEAD (Authenticated
Encryption with Associated Data), Block Ciphers, Ciphers, Compressors and
Hashes.
Please note that Block Ciphers is somewhat of a misnomer. It is in fact
meant to support all ciphers including stream ciphers. The difference
between Block Ciphers and Ciphers is that the latter operates on exactly
one block while the former can operate on an arbitrary amount of data,
subject to block size requirements (i.e., non-stream ciphers can only
process multiples of blocks).
Support for hardware crypto devices via an asynchronous interface is
under development.
@ -69,29 +76,12 @@ Here's an example of how to use the API:
Many real examples are available in the regression test module (tcrypt.c).
CONFIGURATION NOTES
As Triple DES is part of the DES module, for those using modular builds,
add the following line to /etc/modprobe.conf:
alias des3_ede des
The Null algorithms reside in the crypto_null module, so these lines
should also be added:
alias cipher_null crypto_null
alias digest_null crypto_null
alias compress_null crypto_null
The SHA384 algorithm shares code within the SHA512 module, so you'll
also need:
alias sha384 sha512
DEVELOPER NOTES
Transforms may only be allocated in user context, and cryptographic
methods may only be called from softirq and user contexts.
methods may only be called from softirq and user contexts. For
transforms with a setkey method it too should only be called from
user context.
When using the API for ciphers, performance will be optimal if each
scatterlist contains data which is a multiple of the cipher's block
@ -130,8 +120,9 @@ might already be working on.
BUGS
Send bug reports to:
Herbert Xu <herbert@gondor.apana.org.au>
Cc: David S. Miller <davem@redhat.com>
linux-crypto@vger.kernel.org
Cc: Herbert Xu <herbert@gondor.apana.org.au>,
David S. Miller <davem@redhat.com>
FURTHER INFORMATION

179
Documentation/debugging-via-ohci1394.txt 100644
View File

@ -0,0 +1,179 @@
Using physical DMA provided by OHCI-1394 FireWire controllers for debugging
---------------------------------------------------------------------------
Introduction
------------
Basically all FireWire controllers which are in use today are compliant
to the OHCI-1394 specification which defines the controller to be a PCI
bus master which uses DMA to offload data transfers from the CPU and has
a "Physical Response Unit" which executes specific requests by employing
PCI-Bus master DMA after applying filters defined by the OHCI-1394 driver.
Once properly configured, remote machines can send these requests to
ask the OHCI-1394 controller to perform read and write requests on
physical system memory and, for read requests, send the result of
the physical memory read back to the requester.
With that, it is possible to debug issues by reading interesting memory
locations such as buffers like the printk buffer or the process table.
Retrieving a full system memory dump is also possible over the FireWire,
using data transfer rates in the order of 10MB/s or more.
Memory access is currently limited to the low 4G of physical address
space which can be a problem on IA64 machines where memory is located
mostly above that limit, but it is rarely a problem on more common
hardware such as hardware based on x86, x86-64 and PowerPC.
Together with a early initialization of the OHCI-1394 controller for debugging,
this facility proved most useful for examining long debugs logs in the printk
buffer on to debug early boot problems in areas like ACPI where the system
fails to boot and other means for debugging (serial port) are either not
available (notebooks) or too slow for extensive debug information (like ACPI).
Drivers
-------
The OHCI-1394 drivers in drivers/firewire and drivers/ieee1394 initialize
the OHCI-1394 controllers to a working state and can be used to enable
physical DMA. By default you only have to load the driver, and physical
DMA access will be granted to all remote nodes, but it can be turned off
when using the ohci1394 driver.
Because these drivers depend on the PCI enumeration to be completed, an
initialization routine which can runs pretty early (long before console_init(),
which makes the printk buffer appear on the console can be called) was written.
To activate it, enable CONFIG_PROVIDE_OHCI1394_DMA_INIT (Kernel hacking menu:
Provide code for enabling DMA over FireWire early on boot) and pass the
parameter "ohci1394_dma=early" to the recompiled kernel on boot.
Tools
-----
firescope - Originally developed by Benjamin Herrenschmidt, Andi Kleen ported
it from PowerPC to x86 and x86_64 and added functionality, firescope can now
be used to view the printk buffer of a remote machine, even with live update.
Bernhard Kaindl enhanced firescope to support accessing 64-bit machines
from 32-bit firescope and vice versa:
- ftp://ftp.suse.de/private/bk/firewire/tools/firescope-0.2.2.tar.bz2
and he implemented fast system dump (alpha version - read README.txt):
- ftp://ftp.suse.de/private/bk/firewire/tools/firedump-0.1.tar.bz2
There is also a gdb proxy for firewire which allows to use gdb to access
data which can be referenced from symbols found by gdb in vmlinux:
- ftp://ftp.suse.de/private/bk/firewire/tools/fireproxy-0.33.tar.bz2
The latest version of this gdb proxy (fireproxy-0.34) can communicate (not
yet stable) with kgdb over an memory-based communication module (kgdbom).
Getting Started
---------------
The OHCI-1394 specification regulates that the OHCI-1394 controller must
disable all physical DMA on each bus reset.
This means that if you want to debug an issue in a system state where
interrupts are disabled and where no polling of the OHCI-1394 controller
for bus resets takes place, you have to establish any FireWire cable
connections and fully initialize all FireWire hardware __before__ the
system enters such state.
Step-by-step instructions for using firescope with early OHCI initialization:
1) Verify that your hardware is supported:
Load the ohci1394 or the fw-ohci module and check your kernel logs.
You should see a line similar to
ohci1394: fw-host0: OHCI-1394 1.1 (PCI): IRQ=[18] MMIO=[fe9ff800-fe9fffff]
... Max Packet=[2048] IR/IT contexts=[4/8]
when loading the driver. If you have no supported controller, many PCI,
CardBus and even some Express cards which are fully compliant to OHCI-1394
specification are available. If it requires no driver for Windows operating
systems, it most likely is. Only specialized shops have cards which are not
compliant, they are based on TI PCILynx chips and require drivers for Win-
dows operating systems.
2) Establish a working FireWire cable connection:
Any FireWire cable, as long at it provides electrically and mechanically
stable connection and has matching connectors (there are small 4-pin and
large 6-pin FireWire ports) will do.
If an driver is running on both machines you should see a line like
ieee1394: Node added: ID:BUS[0-01:1023] GUID[0090270001b84bba]
on both machines in the kernel log when the cable is plugged in
and connects the two machines.
3) Test physical DMA using firescope:
On the debug host,
- load the raw1394 module,
- make sure that /dev/raw1394 is accessible,
then start firescope:
$ firescope
Port 0 (ohci1394) opened, 2 nodes detected
FireScope
---------
Target : <unspecified>
Gen : 1
[Ctrl-T] choose target
[Ctrl-H] this menu
[Ctrl-Q] quit
------> Press Ctrl-T now, the output should be similar to:
2 nodes available, local node is: 0
0: ffc0, uuid: 00000000 00000000 [LOCAL]
1: ffc1, uuid: 00279000 ba4bb801
Besides the [LOCAL] node, it must show another node without error message.
4) Prepare for debugging with early OHCI-1394 initialization:
4.1) Kernel compilation and installation on debug target
Compile the kernel to be debugged with CONFIG_PROVIDE_OHCI1394_DMA_INIT
(Kernel hacking: Provide code for enabling DMA over FireWire early on boot)
enabled and install it on the machine to be debugged (debug target).
4.2) Transfer the System.map of the debugged kernel to the debug host
Copy the System.map of the kernel be debugged to the debug host (the host
which is connected to the debugged machine over the FireWire cable).
5) Retrieving the printk buffer contents:
With the FireWire cable connected, the OHCI-1394 driver on the debugging
host loaded, reboot the debugged machine, booting the kernel which has
CONFIG_PROVIDE_OHCI1394_DMA_INIT enabled, with the option ohci1394_dma=early.
Then, on the debugging host, run firescope, for example by using -A:
firescope -A System.map-of-debug-target-kernel
Note: -A automatically attaches to the first non-local node. It only works
reliably if only connected two machines are connected using FireWire.
After having attached to the debug target, press Ctrl-D to view the
complete printk buffer or Ctrl-U to enter auto update mode and get an
updated live view of recent kernel messages logged on the debug target.
Call "firescope -h" to get more information on firescope's options.
Notes
-----
Documentation and specifications: ftp://ftp.suse.de/private/bk/firewire/docs
FireWire is a trademark of Apple Inc. - for more information please refer to:
http://en.wikipedia.org/wiki/FireWire

2
Documentation/dontdiff
View File

@ -46,8 +46,6 @@
.mailmap
.mm
53c700_d.h
53c7xx_d.h
53c7xx_u.h
53c8xx_d.h*
BitKeeper
COPYING

12
Documentation/dvb/bt8xx.txt
View File

@ -78,6 +78,18 @@ Example:
For a full list of card ID's please see Documentation/video4linux/CARDLIST.bttv.
In case of further problems please subscribe and send questions to the mailing list: linux-dvb@linuxtv.org.
2c) Probing the cards with broken PCI subsystem ID
--------------------------------------------------
There are some TwinHan cards that the EEPROM has become corrupted for some
reason. The cards do not have correct PCI subsystem ID. But we can force
probing the cards with broken PCI subsystem ID
$ echo 109e 0878 $subvendor $subdevice > \
/sys/bus/pci/drivers/bt878/new_id
109e: PCI_VENDOR_ID_BROOKTREE
0878: PCI_DEVICE_ID_BROOKTREE_878
Authors: Richard Walker,
Jamie Honan,
Michael Hunold,

148
Documentation/feature-removal-schedule.txt
View File

@ -156,22 +156,6 @@ Who: Arjan van de Ven <arjan@linux.intel.com>
---------------------------
What: USB driver API moves to EXPORT_SYMBOL_GPL
When: February 2008
Files: include/linux/usb.h, drivers/usb/core/driver.c
Why: The USB subsystem has changed a lot over time, and it has been
possible to create userspace USB drivers using usbfs/libusb/gadgetfs
that operate as fast as the USB bus allows. Because of this, the USB
subsystem will not be allowing closed source kernel drivers to
register with it, after this grace period is over. If anyone needs
any help in converting their closed source drivers over to use the
userspace filesystems, please contact the
linux-usb-devel@lists.sourceforge.net mailing list, and the developers
there will be glad to help you out.
Who: Greg Kroah-Hartman <gregkh@suse.de>
---------------------------
What: vm_ops.nopage
When: Soon, provided in-kernel callers have been converted
Why: This interface is replaced by vm_ops.fault, but it has been around
@ -181,15 +165,6 @@ Who: Nick Piggin <npiggin@suse.de>
---------------------------
What: Interrupt only SA_* flags
When: September 2007
Why: The interrupt related SA_* flags are replaced by IRQF_* to move them
out of the signal namespace.
Who: Thomas Gleixner <tglx@linutronix.de>
---------------------------
What: PHYSDEVPATH, PHYSDEVBUS, PHYSDEVDRIVER in the uevent environment
When: October 2008
Why: The stacking of class devices makes these values misleading and
@ -200,15 +175,6 @@ Who: Kay Sievers <kay.sievers@suse.de>
---------------------------
What: i2c_adapter.list
When: July 2007
Why: Superfluous, this list duplicates the one maintained by the driver
core.
Who: Jean Delvare <khali@linux-fr.org>,
David Brownell <dbrownell@users.sourceforge.net>
---------------------------
What: ACPI procfs interface
When: July 2008
Why: ACPI sysfs conversion should be finished by January 2008.
@ -234,14 +200,6 @@ Who: Len Brown <len.brown@intel.com>
---------------------------
What: i2c-ixp2000, i2c-ixp4xx and scx200_i2c drivers
When: September 2007
Why: Obsolete. The new i2c-gpio driver replaces all hardware-specific
I2C-over-GPIO drivers.
Who: Jean Delvare <khali@linux-fr.org>
---------------------------
What: 'time' kernel boot parameter
When: January 2008
Why: replaced by 'printk.time=<value>' so that printk timestamps can be
@ -275,22 +233,6 @@ Who: Tejun Heo <htejun@gmail.com>
---------------------------
What: Legacy RTC drivers (under drivers/i2c/chips)
When: November 2007
Why: Obsolete. We have a RTC subsystem with better drivers.
Who: Jean Delvare <khali@linux-fr.org>
---------------------------
What: iptables SAME target
When: 1.1. 2008
Files: net/ipv4/netfilter/ipt_SAME.c, include/linux/netfilter_ipv4/ipt_SAME.h
Why: Obsolete for multiple years now, NAT core provides the same behaviour.
Unfixable broken wrt. 32/64 bit cleanness.
Who: Patrick McHardy <kaber@trash.net>
---------------------------
What: The arch/ppc and include/asm-ppc directories
When: Jun 2008
Why: The arch/powerpc tree is the merged architecture for ppc32 and ppc64
@ -304,16 +246,6 @@ Who: linuxppc-dev@ozlabs.org
---------------------------
What: mthca driver's MSI support
When: January 2008
Files: drivers/infiniband/hw/mthca/*.[ch]
Why: All mthca hardware also supports MSI-X, which provides
strictly more functionality than MSI. So there is no point in
having both MSI-X and MSI support in the driver.
Who: Roland Dreier <rolandd@cisco.com>
---------------------------
What: sk98lin network driver
When: Feburary 2008
Why: In kernel tree version of driver is unmaintained. Sk98lin driver
@ -332,13 +264,77 @@ Who: Thomas Gleixner <tglx@linutronix.de>
---------------------------
What: shaper network driver
When: January 2008
Files: drivers/net/shaper.c, include/linux/if_shaper.h
Why: This driver has been marked obsolete for many years.
It was only designed to work on lower speed links and has design
flaws that lead to machine crashes. The qdisc infrastructure in
2.4 or later kernels, provides richer features and is more robust.
Who: Stephen Hemminger <shemminger@linux-foundation.org>
---------------------------
What: i2c-i810, i2c-prosavage and i2c-savage4
When: May 2008
Why: These drivers are superseded by i810fb, intelfb and savagefb.
Who: Jean Delvare <khali@linux-fr.org>
---------------------------
What: bcm43xx wireless network driver
When: 2.6.26
Files: drivers/net/wireless/bcm43xx
Why: This driver's functionality has been replaced by the
mac80211-based b43 and b43legacy drivers.
Who: John W. Linville <linville@tuxdriver.com>
---------------------------
What: ieee80211 softmac wireless networking component
When: 2.6.26 (or after removal of bcm43xx and port of zd1211rw to mac80211)
Files: net/ieee80211/softmac
Why: No in-kernel drivers will depend on it any longer.
Who: John W. Linville <linville@tuxdriver.com>
---------------------------
What: rc80211-simple rate control algorithm for mac80211
When: 2.6.26
Files: net/mac80211/rc80211-simple.c
Why: This algorithm was provided for reference but always exhibited bad
responsiveness and performance and has some serious flaws. It has been
replaced by rc80211-pid.
Who: Stefano Brivio <stefano.brivio@polimi.it>
---------------------------
What (Why):
- include/linux/netfilter_ipv4/ipt_TOS.h ipt_tos.h header files
(superseded by xt_TOS/xt_tos target & match)
- "forwarding" header files like ipt_mac.h in
include/linux/netfilter_ipv4/ and include/linux/netfilter_ipv6/
- xt_CONNMARK match revision 0
(superseded by xt_CONNMARK match revision 1)
- xt_MARK target revisions 0 and 1
(superseded by xt_MARK match revision 2)
- xt_connmark match revision 0
(superseded by xt_connmark match revision 1)
- xt_conntrack match revision 0
(superseded by xt_conntrack match revision 1)
- xt_iprange match revision 0,
include/linux/netfilter_ipv4/ipt_iprange.h
(superseded by xt_iprange match revision 1)
- xt_mark match revision 0
(superseded by xt_mark match revision 1)
When: January 2009 or Linux 2.7.0, whichever comes first
Why: Superseded by newer revisions or modules
Who: Jan Engelhardt <jengelh@computergmbh.de>
---------------------------
What: b43 support for firmware revision < 410
When: July 2008
Why: The support code for the old firmware hurts code readability/maintainability
and slightly hurts runtime performance. Bugfixes for the old firmware
are not provided by Broadcom anymore.
Who: Michael Buesch <mb@bu3sch.de>

20
Documentation/filesystems/ext4.txt
View File

@ -86,9 +86,21 @@ Alex is working on a new set of patches right now.
When mounting an ext4 filesystem, the following option are accepted:
(*) == default
extents ext4 will use extents to address file data. The
extents (*) ext4 will use extents to address file data. The
file system will no longer be mountable by ext3.
noextents ext4 will not use extents for newly created files
journal_checksum Enable checksumming of the journal transactions.
This will allow the recovery code in e2fsck and the
kernel to detect corruption in the kernel. It is a
compatible change and will be ignored by older kernels.
journal_async_commit Commit block can be written to disk without waiting
for descriptor blocks. If enabled older kernels cannot
mount the device. This will enable 'journal_checksum'
internally.
journal=update Update the ext4 file system's journal to the current
format.
@ -196,6 +208,12 @@ nobh (a) cache disk block mapping information
"nobh" option tries to avoid associating buffer
heads (supported only for "writeback" mode).
mballoc (*) Use the multiple block allocator for block allocation
nomballoc disabled multiple block allocator for block allocation.
stripe=n Number of filesystem blocks that mballoc will try
to use for allocation size and alignment. For RAID5/6
systems this should be the number of data
disks * RAID chunk size in file system blocks.
Data Mode
---------

16
Documentation/filesystems/ocfs2.txt
View File

@ -35,7 +35,6 @@ Features which OCFS2 does not support yet:
- Directory change notification (F_NOTIFY)
- Distributed Caching (F_SETLEASE/F_GETLEASE/break_lease)
- POSIX ACLs
- readpages / writepages (not user visible)
Mount options
=============
@ -62,3 +61,18 @@ data=writeback Data ordering is not preserved, data may be written
preferred_slot=0(*) During mount, try to use this filesystem slot first. If
it is in use by another node, the first empty one found
will be chosen. Invalid values will be ignored.
commit=nrsec (*) Ocfs2 can be told to sync all its data and metadata
every 'nrsec' seconds. The default value is 5 seconds.
This means that if you lose your power, you will lose
as much as the latest 5 seconds of work (your
filesystem will not be damaged though, thanks to the
journaling). This default value (or any low value)
will hurt performance, but it's good for data-safety.
Setting it to 0 will have the same effect as leaving
it at the default (5 seconds).
Setting it to very large values will improve
performance.
localalloc=8(*) Allows custom localalloc size in MB. If the value is too
large, the fs will silently revert it to the default.
Localalloc is not enabled for local mounts.
localflocks This disables cluster aware flock.

51
Documentation/filesystems/proc.txt
View File

@ -857,6 +857,45 @@ CPUs.
The "procs_blocked" line gives the number of processes currently blocked,
waiting for I/O to complete.
1.9 Ext4 file system parameters
------------------------------
Ext4 file system have one directory per partition under /proc/fs/ext4/
# ls /proc/fs/ext4/hdc/
group_prealloc max_to_scan mb_groups mb_history min_to_scan order2_req
stats stream_req
mb_groups:
This file gives the details of mutiblock allocator buddy cache of free blocks
mb_history:
Multiblock allocation history.
stats:
This file indicate whether the multiblock allocator should start collecting
statistics. The statistics are shown during unmount
group_prealloc:
The multiblock allocator normalize the block allocation request to
group_prealloc filesystem blocks if we don't have strip value set.
The stripe value can be specified at mount time or during mke2fs.
max_to_scan:
How long multiblock allocator can look for a best extent (in found extents)
min_to_scan:
How long multiblock allocator must look for a best extent
order2_req:
Multiblock allocator use 2^N search using buddies only for requests greater
than or equal to order2_req. The request size is specfied in file system
blocks. A value of 2 indicate only if the requests are greater than or equal
to 4 blocks.
stream_req:
Files smaller than stream_req are served by the stream allocator, whose
purpose is to pack requests as close each to other as possible to
produce smooth I/O traffic. Avalue of 16 indicate that file smaller than 16
filesystem block size will use group based preallocation.
------------------------------------------------------------------------------
Summary
@ -1095,13 +1134,6 @@ check the amount of free space (value is in seconds). Default settings are: 4,
resume it if we have a value of 3 or more percent; consider information about
the amount of free space valid for 30 seconds
audit_argv_kb
-------------
The file contains a single value denoting the limit on the argv array size
for execve (in KiB). This limit is only applied when system call auditing for
execve is enabled, otherwise the value is ignored.
ctrl-alt-del
------------
@ -1880,11 +1912,6 @@ max_size
Maximum size of the routing cache. Old entries will be purged once the cache
reached has this size.
max_delay, min_delay
--------------------
Delays for flushing the routing cache.
redirect_load, redirect_number
------------------------------

31
Documentation/hwmon/sysfs-interface
View File

@ -328,6 +328,37 @@ curr[1-*]_input Current input value
Unit: milliampere
RO
*********
* Power *
*********
power[1-*]_average Average power use
Unit: microWatt
RO
power[1-*]_average_highest Historical average maximum power use
Unit: microWatt
RO
power[1-*]_average_lowest Historical average minimum power use
Unit: microWatt
RO
power[1-*]_input Instantaneous power use
Unit: microWatt
RO
power[1-*]_input_highest Historical maximum power use
Unit: microWatt
RO
power[1-*]_input_lowest Historical minimum power use
Unit: microWatt
RO
power[1-*]_reset_history Reset input_highest, input_lowest,
average_highest and average_lowest.
WO
**********
* Alarms *

5
Documentation/i2c/busses/i2c-i801
View File

@ -17,9 +17,8 @@ Supported adapters:
Datasheets: Publicly available at the Intel website
Authors:
Frodo Looijaard <frodol@dds.nl>,
Philip Edelbrock <phil@netroedge.com>,
Mark Studebaker <mdsxyz123@yahoo.com>
Jean Delvare <khali@linux-fr.org>
Module Parameters
@ -62,7 +61,7 @@ Not supported.
I2C Block Read Support
----------------------
Not supported at the moment.
I2C block read is supported on the 82801EB (ICH5) and later chips.
SMBus 2.0 Support

3
Documentation/i2c/busses/i2c-viapro
View File

@ -10,7 +10,7 @@ Supported adapters:
* VIA Technologies, Inc. VT8231, VT8233, VT8233A
Datasheet: available on request from VIA
* VIA Technologies, Inc. VT8235, VT8237R, VT8237A, VT8251
* VIA Technologies, Inc. VT8235, VT8237R, VT8237A, VT8237S, VT8251
Datasheet: available on request and under NDA from VIA
* VIA Technologies, Inc. CX700
@ -46,6 +46,7 @@ Your lspci -n listing must show one of these :
device 1106:3177 (VT8235)
device 1106:3227 (VT8237R)
device 1106:3337 (VT8237A)
device 1106:3372 (VT8237S)
device 1106:3287 (VT8251)
device 1106:8324 (CX700)

72
Documentation/i2c/chips/pcf8575 100644
View File

@ -0,0 +1,72 @@
About the PCF8575 chip and the pcf8575 kernel driver
====================================================
The PCF8575 chip is produced by the following manufacturers:
* Philips NXP
http://www.nxp.com/#/pip/cb=[type=product,path=50807/41735/41850,final=PCF8575_3]|pip=[pip=PCF8575_3][0]
* Texas Instruments
http://focus.ti.com/docs/prod/folders/print/pcf8575.html
Some vendors sell small PCB's with the PCF8575 mounted on it. You can connect
such a board to a Linux host via e.g. an USB to I2C interface. Examples of
PCB boards with a PCF8575:
* SFE Breakout Board for PCF8575 I2C Expander by RobotShop
http://www.robotshop.ca/home/products/robot-parts/electronics/adapters-converters/sfe-pcf8575-i2c-expander-board.html
* Breakout Board for PCF8575 I2C Expander by Spark Fun Electronics
http://www.sparkfun.com/commerce/product_info.php?products_id=8130
Description
-----------
The PCF8575 chip is a 16-bit I/O expander for the I2C bus. Up to eight of
these chips can be connected to the same I2C bus. You can find this
chip on some custom designed hardware, but you won't find it on PC
motherboards.
The PCF8575 chip consists of a 16-bit quasi-bidirectional port and an I2C-bus
interface. Each of the sixteen I/O's can be independently used as an input or
an output. To set up an I/O pin as an input, you have to write a 1 to the
corresponding output.
For more information please see the datasheet.
Detection
---------
There is no method known to detect whether a chip on a given I2C address is
a PCF8575 or whether it is any other I2C device. So there are two alternatives
to let the driver find the installed PCF8575 devices:
- Load this driver after any other I2C driver for I2C devices with addresses
in the range 0x20 .. 0x27.
- Pass the I2C bus and address of the installed PCF8575 devices explicitly to
the driver at load time via the probe=... or force=... parameters.
/sys interface
--------------
For each address on which a PCF8575 chip was found or forced the following
files will be created under /sys:
* /sys/bus/i2c/devices/<bus>-<address>/read
* /sys/bus/i2c/devices/<bus>-<address>/write
where bus is the I2C bus number (0, 1, ...) and address is the four-digit
hexadecimal representation of the 7-bit I2C address of the PCF8575
(0020 .. 0027).
The read file is read-only. Reading it will trigger an I2C read and will hence
report the current input state for the pins configured as inputs, and the
current output value for the pins configured as outputs.
The write file is read-write. Writing a value to it will configure all pins
as output for which the corresponding bit is zero. Reading the write file will
return the value last written, or -EAGAIN if no value has yet been written to
the write file.
On module initialization the configuration of the chip is not changed -- the
chip is left in the state it was already configured in through either power-up
or through previous I2C write actions.

6
Documentation/i2c/i2c-stub
View File

@ -25,6 +25,9 @@ The typical use-case is like this:
3. load the target sensors chip driver module
4. observe its behavior in the kernel log
There's a script named i2c-stub-from-dump in the i2c-tools package which
can load register values automatically from a chip dump.
PARAMETERS:
int chip_addr[10]:
@ -32,9 +35,6 @@ int chip_addr[10]:
CAVEATS:
There are independent arrays for byte/data and word/data commands. Depending
on if/how a target driver mixes them, you'll need to be careful.
If your target driver polls some byte or word waiting for it to change, the
stub could lock it up. Use i2cset to unlock it.

45
Documentation/i2c/summary
View File

@ -1,5 +1,3 @@
This is an explanation of what i2c is, and what is supported in this package.
I2C and SMBus
=============
@ -33,52 +31,17 @@ When we talk about I2C, we use the following terms:
Client
An Algorithm driver contains general code that can be used for a whole class
of I2C adapters. Each specific adapter driver depends on one algorithm
driver.
of I2C adapters. Each specific adapter driver either depends on one algorithm
driver, or includes its own implementation.
A Driver driver (yes, this sounds ridiculous, sorry) contains the general
code to access some type of device. Each detected device gets its own
data in the Client structure. Usually, Driver and Client are more closely
integrated than Algorithm and Adapter.
For a given configuration, you will need a driver for your I2C bus (usually
a separate Adapter and Algorithm driver), and drivers for your I2C devices
(usually one driver for each device). There are no I2C device drivers
in this package. See the lm_sensors project http://www.lm-sensors.nu
for device drivers.
For a given configuration, you will need a driver for your I2C bus, and
drivers for your I2C devices (usually one driver for each device).
At this time, Linux only operates I2C (or SMBus) in master mode; you can't
use these APIs to make a Linux system behave as a slave/device, either to
speak a custom protocol or to emulate some other device.
Included Bus Drivers
====================
Note that only stable drivers are patched into the kernel by 'mkpatch'.
Base modules
------------
i2c-core: The basic I2C code, including the /proc/bus/i2c* interface
i2c-dev: The /dev/i2c-* interface
i2c-proc: The /proc/sys/dev/sensors interface for device (client) drivers
Algorithm drivers
-----------------
i2c-algo-bit: A bit-banging algorithm
i2c-algo-pcf: A PCF 8584 style algorithm
i2c-algo-ibm_ocp: An algorithm for the I2C device in IBM 4xx processors (NOT BUILT BY DEFAULT)
Adapter drivers
---------------
i2c-elektor: Elektor ISA card (uses i2c-algo-pcf)
i2c-elv: ELV parallel port adapter (uses i2c-algo-bit)
i2c-pcf-epp: PCF8584 on a EPP parallel port (uses i2c-algo-pcf) (NOT mkpatched)
i2c-philips-par: Philips style parallel port adapter (uses i2c-algo-bit)
i2c-adap-ibm_ocp: IBM 4xx processor I2C device (uses i2c-algo-ibm_ocp) (NOT BUILT BY DEFAULT)
i2c-pport: Primitive parallel port adapter (uses i2c-algo-bit)
i2c-velleman: Velleman K8000 parallel port adapter (uses i2c-algo-bit)

6
Documentation/i2c/writing-clients
View File

@ -267,9 +267,9 @@ insmod parameter of the form force_<kind>.
Fortunately, as a module writer, you just have to define the `normal_i2c'
parameter. The complete declaration could look like this:
/* Scan 0x37, and 0x48 to 0x4f */
static unsigned short normal_i2c[] = { 0x37, 0x48, 0x49, 0x4a, 0x4b, 0x4c,
0x4d, 0x4e, 0x4f, I2C_CLIENT_END };
/* Scan 0x4c to 0x4f */
static const unsigned short normal_i2c[] = { 0x4c, 0x4d, 0x4e, 0x4f,
I2C_CLIENT_END };
/* Magic definition of all other variables and things */
I2C_CLIENT_INSMOD;

38
Documentation/i386/boot.txt
View File

@ -785,3 +785,41 @@ IMPORTANT: All the hooks are required to preserve %esp, %ebp, %esi and
After completing your hook, you should jump to the address
that was in this field before your boot loader overwrote it
(relocated, if appropriate.)
**** 32-bit BOOT PROTOCOL
For machine with some new BIOS other than legacy BIOS, such as EFI,
LinuxBIOS, etc, and kexec, the 16-bit real mode setup code in kernel
based on legacy BIOS can not be used, so a 32-bit boot protocol needs
to be defined.
In 32-bit boot protocol, the first step in loading a Linux kernel
should be to setup the boot parameters (struct boot_params,
traditionally known as "zero page"). The memory for struct boot_params
should be allocated and initialized to all zero. Then the setup header
from offset 0x01f1 of kernel image on should be loaded into struct
boot_params and examined. The end of setup header can be calculated as
follow:
0x0202 + byte value at offset 0x0201
In addition to read/modify/write the setup header of the struct
boot_params as that of 16-bit boot protocol, the boot loader should
also fill the additional fields of the struct boot_params as that
described in zero-page.txt.
After setupping the struct boot_params, the boot loader can load the
32/64-bit kernel in the same way as that of 16-bit boot protocol.
In 32-bit boot protocol, the kernel is started by jumping to the
32-bit kernel entry point, which is the start address of loaded
32/64-bit kernel.
At entry, the CPU must be in 32-bit protected mode with paging
disabled; a GDT must be loaded with the descriptors for selectors
__BOOT_CS(0x10) and __BOOT_DS(0x18); both descriptors must be 4G flat
segment; __BOOS_CS must have execute/read permission, and __BOOT_DS
must have read/write permission; CS must be __BOOT_CS and DS, ES, SS
must be __BOOT_DS; interrupt must be disabled; %esi must hold the base
address of the struct boot_params; %ebp, %edi and %ebx must be zero.

122
Documentation/i386/zero-page.txt
View File

@ -1,99 +1,31 @@
---------------------------------------------------------------------------
!!!!!!!!!!!!!!!WARNING!!!!!!!!
The zero page is a kernel internal data structure, not a stable ABI. It might change
without warning and the kernel has no way to detect old version of it.
If you're writing some external code like a boot loader you should only use
the stable versioned real mode boot protocol described in boot.txt. Otherwise the kernel
might break you at any time.
!!!!!!!!!!!!!WARNING!!!!!!!!!!!
----------------------------------------------------------------------------
The additional fields in struct boot_params as a part of 32-bit boot
protocol of kernel. These should be filled by bootloader or 16-bit
real-mode setup code of the kernel. References/settings to it mainly
are in:
Summary of boot_params layout (kernel point of view)
( collected by Hans Lermen and Martin Mares )
The contents of boot_params are used to pass parameters from the
16-bit realmode code of the kernel to the 32-bit part. References/settings
to it mainly are in:
include/asm-x86/bootparam.h
arch/i386/boot/setup.S
arch/i386/boot/video.S
arch/i386/kernel/head.S
arch/i386/kernel/setup.c
Offset Type Description
------ ---- -----------
0 32 bytes struct screen_info, SCREEN_INFO
ATTENTION, overlaps the following !!!
2 unsigned short EXT_MEM_K, extended memory size in Kb (from int 0x15)
0x20 unsigned short CL_MAGIC, commandline magic number (=0xA33F)
0x22 unsigned short CL_OFFSET, commandline offset
Address of commandline is calculated:
0x90000 + contents of CL_OFFSET
(only taken, when CL_MAGIC = 0xA33F)
0x40 20 bytes struct apm_bios_info, APM_BIOS_INFO
0x60 16 bytes Intel SpeedStep (IST) BIOS support information
0x80 16 bytes hd0-disk-parameter from intvector 0x41
0x90 16 bytes hd1-disk-parameter from intvector 0x46
Offset Proto Name Meaning
/Size
0xa0 16 bytes System description table truncated to 16 bytes.
( struct sys_desc_table_struct )
0xb0 - 0x13f Free. Add more parameters here if you really need them.
0x140- 0x1be EDID_INFO Video mode setup
0x1c4 unsigned long EFI system table pointer
0x1c8 unsigned long EFI memory descriptor size
0x1cc unsigned long EFI memory descriptor version
0x1d0 unsigned long EFI memory descriptor map pointer
0x1d4 unsigned long EFI memory descriptor map size
0x1e0 unsigned long ALT_MEM_K, alternative mem check, in Kb
0x1e4 unsigned long Scratch field for the kernel setup code
0x1e8 char number of entries in E820MAP (below)
0x1e9 unsigned char number of entries in EDDBUF (below)
0x1ea unsigned char number of entries in EDD_MBR_SIG_BUFFER (below)
0x1f1 char size of setup.S, number of sectors
0x1f2 unsigned short MOUNT_ROOT_RDONLY (if !=0)
0x1f4 unsigned short size of compressed kernel-part in the
(b)zImage-file (in 16 byte units, rounded up)
0x1f6 unsigned short swap_dev (unused AFAIK)
0x1f8 unsigned short RAMDISK_FLAGS
0x1fa unsigned short VGA-Mode (old one)
0x1fc unsigned short ORIG_ROOT_DEV (high=Major, low=minor)
0x1ff char AUX_DEVICE_INFO
0x200 short jump to start of setup code aka "reserved" field.
0x202 4 bytes Signature for SETUP-header, ="HdrS"
0x206 unsigned short Version number of header format
Current version is 0x0201...
0x208 8 bytes (used by setup.S for communication with boot loaders,
look there)
0x210 char LOADER_TYPE, = 0, old one
else it is set by the loader:
0xTV: T=0 for LILO
1 for Loadlin
2 for bootsect-loader
3 for SYSLINUX
4 for ETHERBOOT
5 for ELILO
7 for GRuB
8 for U-BOOT
9 for Xen
V = version
0x211 char loadflags:
bit0 = 1: kernel is loaded high (bzImage)
bit7 = 1: Heap and pointer (see below) set by boot
loader.
0x212 unsigned short (setup.S)
0x214 unsigned long KERNEL_START, where the loader started the kernel
0x218 unsigned long INITRD_START, address of loaded ramdisk image
0x21c unsigned long INITRD_SIZE, size in bytes of ramdisk image
0x220 4 bytes (setup.S)
0x224 unsigned short setup.S heap end pointer
0x226 unsigned short zero_pad
0x228 unsigned long cmd_line_ptr
0x22c unsigned long ramdisk_max
0x230 16 bytes trampoline
0x290 - 0x2cf EDD_MBR_SIG_BUFFER (edd.S)
0x2d0 - 0xd00 E820MAP
0xd00 - 0xeff EDDBUF (edd.S) for disk signature read sector
0xd00 - 0xeeb EDDBUF (edd.S) for edd data
000/040 ALL screen_info Text mode or frame buffer information
(struct screen_info)
040/014 ALL apm_bios_info APM BIOS information (struct apm_bios_info)
060/010 ALL ist_info Intel SpeedStep (IST) BIOS support information
(struct ist_info)
080/010 ALL hd0_info hd0 disk parameter, OBSOLETE!!
090/010 ALL hd1_info hd1 disk parameter, OBSOLETE!!
0A0/010 ALL sys_desc_table System description table (struct sys_desc_table)
140/080 ALL edid_info Video mode setup (struct edid_info)
1C0/020 ALL efi_info EFI 32 information (struct efi_info)
1E0/004 ALL alk_mem_k Alternative mem check, in KB
1E4/004 ALL scratch Scratch field for the kernel setup code
1E8/001 ALL e820_entries Number of entries in e820_map (below)
1E9/001 ALL eddbuf_entries Number of entries in eddbuf (below)
1EA/001 ALL edd_mbr_sig_buf_entries Number of entries in edd_mbr_sig_buffer
(below)
290/040 ALL edd_mbr_sig_buffer EDD MBR signatures
2D0/A00 ALL e820_map E820 memory map table
(array of struct e820entry)
D00/1EC ALL eddbuf EDD data (array of struct edd_info)

13
Documentation/ide.txt
View File

@ -30,7 +30,7 @@
***
*** The CMD640 is also used on some Vesa Local Bus (VLB) cards, and is *NOT*
*** automatically detected by Linux. For safe, reliable operation with such
*** interfaces, one *MUST* use the "ide0=cmd640_vlb" kernel option.
*** interfaces, one *MUST* use the "cmd640.probe_vlb" kernel option.
***
*** Use of the "serialize" option is no longer necessary.
@ -244,10 +244,6 @@ Summary of ide driver parameters for kernel command line
"hdx=nodma" : disallow DMA
"hdx=swapdata" : when the drive is a disk, byte swap all data
"hdx=bswap" : same as above..........
"hdx=scsi" : the return of the ide-scsi flag, this is useful for
allowing ide-floppy, ide-tape, and ide-cdrom|writers
to use ide-scsi emulation on a device specific option.
@ -292,9 +288,6 @@ The following are valid ONLY on ide0, which usually corresponds
to the first ATA interface found on the particular host, and the defaults for
the base,ctl ports must not be altered.
"ide0=cmd640_vlb" : *REQUIRED* for VLB cards with the CMD640 chip
(not for PCI -- automatically detected)
"ide=doubler" : probe/support IDE doublers on Amiga
There may be more options than shown -- use the source, Luke!
@ -310,6 +303,10 @@ i.e. to enable probing for ALI M14xx chipsets (ali14xx host driver) use:
* "probe" module parameter when ali14xx driver is compiled as module
("modprobe ali14xx probe")
Also for legacy CMD640 host driver (cmd640) you need to use "probe_vlb"
kernel paremeter to enable probing for VLB version of the chipset (PCI ones
are detected automatically).
================================================================================
IDE ATAPI streaming tape driver

268
Documentation/ide/ChangeLog.ide-cd.1994-2004 100644
View File

@ -0,0 +1,268 @@
/*
* 1.00 Oct 31, 1994 -- Initial version.
* 1.01 Nov 2, 1994 -- Fixed problem with starting request in
* cdrom_check_status.
* 1.03 Nov 25, 1994 -- leaving unmask_intr[] as a user-setting (as for disks)
* (from mlord) -- minor changes to cdrom_setup()
* -- renamed ide_dev_s to ide_drive_t, enable irq on command
* 2.00 Nov 27, 1994 -- Generalize packet command interface;
* add audio ioctls.
* 2.01 Dec 3, 1994 -- Rework packet command interface to handle devices
* which send an interrupt when ready for a command.
* 2.02 Dec 11, 1994 -- Cache the TOC in the driver.
* Don't use SCMD_PLAYAUDIO_TI; it's not included
* in the current version of ATAPI.
* Try to use LBA instead of track or MSF addressing
* when possible.
* Don't wait for READY_STAT.
* 2.03 Jan 10, 1995 -- Rewrite block read routines to handle block sizes
* other than 2k and to move multiple sectors in a
* single transaction.
* 2.04 Apr 21, 1995 -- Add work-around for Creative Labs CD220E drives.
* Thanks to Nick Saw <cwsaw@pts7.pts.mot.com> for
* help in figuring this out. Ditto for Acer and
* Aztech drives, which seem to have the same problem.
* 2.04b May 30, 1995 -- Fix to match changes in ide.c version 3.16 -ml
* 2.05 Jun 8, 1995 -- Don't attempt to retry after an illegal request
* or data protect error.
* Use HWIF and DEV_HWIF macros as in ide.c.
* Always try to do a request_sense after
* a failed command.
* Include an option to give textual descriptions
* of ATAPI errors.
* Fix a bug in handling the sector cache which
* showed up if the drive returned data in 512 byte
* blocks (like Pioneer drives). Thanks to
* Richard Hirst <srh@gpt.co.uk> for diagnosing this.
* Properly supply the page number field in the
* MODE_SELECT command.
* PLAYAUDIO12 is broken on the Aztech; work around it.
* 2.05x Aug 11, 1995 -- lots of data structure renaming/restructuring in ide.c
* (my apologies to Scott, but now ide-cd.c is independent)
* 3.00 Aug 22, 1995 -- Implement CDROMMULTISESSION ioctl.
* Implement CDROMREADAUDIO ioctl (UNTESTED).
* Use input_ide_data() and output_ide_data().
* Add door locking.
* Fix usage count leak in cdrom_open, which happened
* when a read-write mount was attempted.
* Try to load the disk on open.
* Implement CDROMEJECT_SW ioctl (off by default).
* Read total cdrom capacity during open.
* Rearrange logic in cdrom_decode_status. Issue
* request sense commands for failed packet commands
* from here instead of from cdrom_queue_packet_command.
* Fix a race condition in retrieving error information.
* Suppress printing normal unit attention errors and
* some drive not ready errors.
* Implement CDROMVOLREAD ioctl.
* Implement CDROMREADMODE1/2 ioctls.
* Fix race condition in setting up interrupt handlers
* when the `serialize' option is used.
* 3.01 Sep 2, 1995 -- Fix ordering of reenabling interrupts in
* cdrom_queue_request.
* Another try at using ide_[input,output]_data.
* 3.02 Sep 16, 1995 -- Stick total disk capacity in partition table as well.
* Make VERBOSE_IDE_CD_ERRORS dump failed command again.
* Dump out more information for ILLEGAL REQUEST errs.
* Fix handling of errors occurring before the
* packet command is transferred.
* Fix transfers with odd bytelengths.
* 3.03 Oct 27, 1995 -- Some Creative drives have an id of just `CD'.
* `DCI-2S10' drives are broken too.
* 3.04 Nov 20, 1995 -- So are Vertos drives.
* 3.05 Dec 1, 1995 -- Changes to go with overhaul of ide.c and ide-tape.c
* 3.06 Dec 16, 1995 -- Add support needed for partitions.
* More workarounds for Vertos bugs (based on patches
* from Holger Dietze <dietze@aix520.informatik.uni-leipzig.de>).
* Try to eliminate byteorder assumptions.
* Use atapi_cdrom_subchnl struct definition.
* Add STANDARD_ATAPI compilation option.
* 3.07 Jan 29, 1996 -- More twiddling for broken drives: Sony 55D,
* Vertos 300.
* Add NO_DOOR_LOCKING configuration option.
* Handle drive_cmd requests w/NULL args (for hdparm -t).
* Work around sporadic Sony55e audio play problem.
* 3.07a Feb 11, 1996 -- check drive->id for NULL before dereferencing, to fix
* problem with "hde=cdrom" with no drive present. -ml
* 3.08 Mar 6, 1996 -- More Vertos workarounds.
* 3.09 Apr 5, 1996 -- Add CDROMCLOSETRAY ioctl.
* Switch to using MSF addressing for audio commands.
* Reformat to match kernel tabbing style.
* Add CDROM_GET_UPC ioctl.
* 3.10 Apr 10, 1996 -- Fix compilation error with STANDARD_ATAPI.
* 3.11 Apr 29, 1996 -- Patch from Heiko Eißfeldt <heiko@colossus.escape.de>
* to remove redundant verify_area calls.
* 3.12 May 7, 1996 -- Rudimentary changer support. Based on patches
* from Gerhard Zuber <zuber@berlin.snafu.de>.
* Let open succeed even if there's no loaded disc.
* 3.13 May 19, 1996 -- Fixes for changer code.
* 3.14 May 29, 1996 -- Add work-around for Vertos 600.
* (From Hennus Bergman <hennus@sky.ow.nl>.)
* 3.15 July 2, 1996 -- Added support for Sanyo 3 CD changers
* from Ben Galliart <bgallia@luc.edu> with
* special help from Jeff Lightfoot
* <jeffml@pobox.com>
* 3.15a July 9, 1996 -- Improved Sanyo 3 CD changer identification
* 3.16 Jul 28, 1996 -- Fix from Gadi to reduce kernel stack usage for ioctl.
* 3.17 Sep 17, 1996 -- Tweak audio reads for some drives.
* Start changing CDROMLOADFROMSLOT to CDROM_SELECT_DISC.
* 3.18 Oct 31, 1996 -- Added module and DMA support.
*
* 4.00 Nov 5, 1996 -- New ide-cd maintainer,
* Erik B. Andersen <andersee@debian.org>
* -- Newer Creative drives don't always set the error
* register correctly. Make sure we see media changes
* regardless.
* -- Integrate with generic cdrom driver.
* -- CDROMGETSPINDOWN and CDROMSETSPINDOWN ioctls, based on
* a patch from Ciro Cattuto <>.
* -- Call set_device_ro.
* -- Implement CDROMMECHANISMSTATUS and CDROMSLOTTABLE
* ioctls, based on patch by Erik Andersen
* -- Add some probes of drive capability during setup.
*
* 4.01 Nov 11, 1996 -- Split into ide-cd.c and ide-cd.h
* -- Removed CDROMMECHANISMSTATUS and CDROMSLOTTABLE
* ioctls in favor of a generalized approach
* using the generic cdrom driver.
* -- Fully integrated with the 2.1.X kernel.
* -- Other stuff that I forgot (lots of changes)
*
* 4.02 Dec 01, 1996 -- Applied patch from Gadi Oxman <gadio@netvision.net.il>
* to fix the drive door locking problems.
*
* 4.03 Dec 04, 1996 -- Added DSC overlap support.
* 4.04 Dec 29, 1996 -- Added CDROMREADRAW ioclt based on patch
* by Ales Makarov (xmakarov@sun.felk.cvut.cz)
*
* 4.05 Nov 20, 1997 -- Modified to print more drive info on init
* Minor other changes
* Fix errors on CDROMSTOP (If you have a "Dolphin",
* you must define IHAVEADOLPHIN)
* Added identifier so new Sanyo CD-changer works
* Better detection if door locking isn't supported
*
* 4.06 Dec 17, 1997 -- fixed endless "tray open" messages -ml
* 4.07 Dec 17, 1997 -- fallback to set pc->stat on "tray open"
* 4.08 Dec 18, 1997 -- spew less noise when tray is empty
* -- fix speed display for ACER 24X, 18X
* 4.09 Jan 04, 1998 -- fix handling of the last block so we return
* an end of file instead of an I/O error (Gadi)
* 4.10 Jan 24, 1998 -- fixed a bug so now changers can change to a new
* slot when there is no disc in the current slot.
* -- Fixed a memory leak where info->changer_info was
* malloc'ed but never free'd when closing the device.
* -- Cleaned up the global namespace a bit by making more
* functions static that should already have been.
* 4.11 Mar 12, 1998 -- Added support for the CDROM_SELECT_SPEED ioctl
* based on a patch for 2.0.33 by Jelle Foks
* <jelle@scintilla.utwente.nl>, a patch for 2.0.33
* by Toni Giorgino <toni@pcape2.pi.infn.it>, the SCSI
* version, and my own efforts. -erik
* -- Fixed a stupid bug which egcs was kind enough to
* inform me of where "Illegal mode for this track"
* was never returned due to a comparison on data
* types of limited range.
* 4.12 Mar 29, 1998 -- Fixed bug in CDROM_SELECT_SPEED so write speed is
* now set ionly for CD-R and CD-RW drives. I had
* removed this support because it produced errors.
* It produced errors _only_ for non-writers. duh.
* 4.13 May 05, 1998 -- Suppress useless "in progress of becoming ready"
* messages, since this is not an error.
* -- Change error messages to be const
* -- Remove a "\t" which looks ugly in the syslogs
* 4.14 July 17, 1998 -- Change to pointing to .ps version of ATAPI spec
* since the .pdf version doesn't seem to work...
* -- Updated the TODO list to something more current.
*
* 4.15 Aug 25, 1998 -- Updated ide-cd.h to respect mechine endianess,
* patch thanks to "Eddie C. Dost" <ecd@skynet.be>
*
* 4.50 Oct 19, 1998 -- New maintainers!
* Jens Axboe <axboe@image.dk>
* Chris Zwilling <chris@cloudnet.com>
*
* 4.51 Dec 23, 1998 -- Jens Axboe <axboe@image.dk>
* - ide_cdrom_reset enabled since the ide subsystem
* handles resets fine now. <axboe@image.dk>
* - Transfer size fix for Samsung CD-ROMs, thanks to
* "Ville Hallik" <ville.hallik@mail.ee>.
* - other minor stuff.
*
* 4.52 Jan 19, 1999 -- Jens Axboe <axboe@image.dk>
* - Detect DVD-ROM/RAM drives
*
* 4.53 Feb 22, 1999 - Include other model Samsung and one Goldstar
* drive in transfer size limit.
* - Fix the I/O error when doing eject without a medium
* loaded on some drives.
* - CDROMREADMODE2 is now implemented through
* CDROMREADRAW, since many drives don't support
* MODE2 (even though ATAPI 2.6 says they must).
* - Added ignore parameter to ide-cd (as a module), eg
* insmod ide-cd ignore='hda hdb'
* Useful when using ide-cd in conjunction with
* ide-scsi. TODO: non-modular way of doing the
* same.
*
* 4.54 Aug 5, 1999 - Support for MMC2 class commands through the generic
* packet interface to cdrom.c.
* - Unified audio ioctl support, most of it.
* - cleaned up various deprecated verify_area().
* - Added ide_cdrom_packet() as the interface for
* the Uniform generic_packet().
* - bunch of other stuff, will fill in logs later.
* - report 1 slot for non-changers, like the other
* cd-rom drivers. don't report select disc for
* non-changers as well.
* - mask out audio playing, if the device can't do it.
*
* 4.55 Sep 1, 1999 - Eliminated the rest of the audio ioctls, except
* for CDROMREADTOC[ENTRY|HEADER]. Some of the drivers
* use this independently of the actual audio handling.
* They will disappear later when I get the time to
* do it cleanly.
* - Minimize the TOC reading - only do it when we
* know a media change has occurred.
* - Moved all the CDROMREADx ioctls to the Uniform layer.
* - Heiko Eißfeldt <heiko@colossus.escape.de> supplied
* some fixes for CDI.
* - CD-ROM leaving door locked fix from Andries
* Brouwer <Andries.Brouwer@cwi.nl>
* - Erik Andersen <andersen@xmission.com> unified
* commands across the various drivers and how
* sense errors are handled.
*
* 4.56 Sep 12, 1999 - Removed changer support - it is now in the
* Uniform layer.
* - Added partition based multisession handling.
* - Mode sense and mode select moved to the
* Uniform layer.
* - Fixed a problem with WPI CDS-32X drive - it
* failed the capabilities
*
* 4.57 Apr 7, 2000 - Fixed sense reporting.
* - Fixed possible oops in ide_cdrom_get_last_session()
* - Fix locking mania and make ide_cdrom_reset relock
* - Stop spewing errors to log when magicdev polls with
* TEST_UNIT_READY on some drives.
* - Various fixes from Tobias Ringstrom:
* tray if it was locked prior to the reset.
* - cdrom_read_capacity returns one frame too little.
* - Fix real capacity reporting.
*
* 4.58 May 1, 2000 - Clean up ACER50 stuff.
* - Fix small problem with ide_cdrom_capacity
*
* 4.59 Aug 11, 2000 - Fix changer problem in cdrom_read_toc, we weren't
* correctly sensing a disc change.
* - Rearranged some code
* - Use extended sense on drives that support it for
* correctly reporting tray status -- from
* Michael D Johnson <johnsom@orst.edu>
* 4.60 Dec 17, 2003 - Add mt rainier support
* - Bump timeout for packet commands, matches sr
* - Odd stuff
* 4.61 Jan 22, 2004 - support hardware sector sizes other than 2kB,
* Pascal Schmidt <der.eremit@email.de>
*/

63
Documentation/ide/ChangeLog.ide-floppy.1996-2002 100644
View File

@ -0,0 +1,63 @@
/*
* Many thanks to Lode Leroy <Lode.Leroy@www.ibase.be>, who tested so many
* ALPHA patches to this driver on an EASYSTOR LS-120 ATAPI floppy drive.
*
* Ver 0.1 Oct 17 96 Initial test version, mostly based on ide-tape.c.
* Ver 0.2 Oct 31 96 Minor changes.
* Ver 0.3 Dec 2 96 Fixed error recovery bug.
* Ver 0.4 Jan 26 97 Add support for the HDIO_GETGEO ioctl.
* Ver 0.5 Feb 21 97 Add partitions support.
* Use the minimum of the LBA and CHS capacities.
* Avoid hwgroup->rq == NULL on the last irq.
* Fix potential null dereferencing with DEBUG_LOG.
* Ver 0.8 Dec 7 97 Increase irq timeout from 10 to 50 seconds.
* Add media write-protect detection.
* Issue START command only if TEST UNIT READY fails.
* Add work-around for IOMEGA ZIP revision 21.D.
* Remove idefloppy_get_capabilities().
* Ver 0.9 Jul 4 99 Fix a bug which might have caused the number of
* bytes requested on each interrupt to be zero.
* Thanks to <shanos@es.co.nz> for pointing this out.
* Ver 0.9.sv Jan 6 01 Sam Varshavchik <mrsam@courier-mta.com>
* Implement low level formatting. Reimplemented
* IDEFLOPPY_CAPABILITIES_PAGE, since we need the srfp
* bit. My LS-120 drive barfs on
* IDEFLOPPY_CAPABILITIES_PAGE, but maybe it's just me.
* Compromise by not reporting a failure to get this
* mode page. Implemented four IOCTLs in order to
* implement formatting. IOCTls begin with 0x4600,
* 0x46 is 'F' as in Format.
* Jan 9 01 Userland option to select format verify.
* Added PC_SUPPRESS_ERROR flag - some idefloppy drives
* do not implement IDEFLOPPY_CAPABILITIES_PAGE, and
* return a sense error. Suppress error reporting in
* this particular case in order to avoid spurious
* errors in syslog. The culprit is
* idefloppy_get_capability_page(), so move it to
* idefloppy_begin_format() so that it's not used
* unless absolutely necessary.
* If drive does not support format progress indication
* monitor the dsc bit in the status register.
* Also, O_NDELAY on open will allow the device to be
* opened without a disk available. This can be used to
* open an unformatted disk, or get the device capacity.
* Ver 0.91 Dec 11 99 Added IOMEGA Clik! drive support by
* <paul@paulbristow.net>
* Ver 0.92 Oct 22 00 Paul Bristow became official maintainer for this
* driver. Included Powerbook internal zip kludge.
* Ver 0.93 Oct 24 00 Fixed bugs for Clik! drive
* no disk on insert and disk change now works
* Ver 0.94 Oct 27 00 Tidied up to remove strstr(Clik) everywhere
* Ver 0.95 Nov 7 00 Brought across to kernel 2.4
* Ver 0.96 Jan 7 01 Actually in line with release version of 2.4.0
* including set_bit patch from Rusty Russell
* Ver 0.97 Jul 22 01 Merge 0.91-0.96 onto 0.9.sv for ac series
* Ver 0.97.sv Aug 3 01 Backported from 2.4.7-ac3
* Ver 0.98 Oct 26 01 Split idefloppy_transfer_pc into two pieces to
* fix a lost interrupt problem. It appears the busy
* bit was being deasserted by my IOMEGA ATAPI ZIP 100
* drive before the drive was actually ready.
* Ver 0.98a Oct 29 01 Expose delay value so we can play.
* Ver 0.99 Feb 24 02 Remove duplicate code, modify clik! detection code
* to support new PocketZip drives
*/

257
Documentation/ide/ChangeLog.ide-tape.1995-2002 100644
View File

@ -0,0 +1,257 @@
/*
* Ver 0.1 Nov 1 95 Pre-working code :-)
* Ver 0.2 Nov 23 95 A short backup (few megabytes) and restore procedure
* was successful ! (Using tar cvf ... on the block
* device interface).
* A longer backup resulted in major swapping, bad
* overall Linux performance and eventually failed as
* we received non serial read-ahead requests from the
* buffer cache.
* Ver 0.3 Nov 28 95 Long backups are now possible, thanks to the
* character device interface. Linux's responsiveness
* and performance doesn't seem to be much affected
* from the background backup procedure.
* Some general mtio.h magnetic tape operations are
* now supported by our character device. As a result,
* popular tape utilities are starting to work with
* ide tapes :-)
* The following configurations were tested:
* 1. An IDE ATAPI TAPE shares the same interface
* and irq with an IDE ATAPI CDROM.
* 2. An IDE ATAPI TAPE shares the same interface
* and irq with a normal IDE disk.
* Both configurations seemed to work just fine !
* However, to be on the safe side, it is meanwhile
* recommended to give the IDE TAPE its own interface
* and irq.
* The one thing which needs to be done here is to
* add a "request postpone" feature to ide.c,
* so that we won't have to wait for the tape to finish
* performing a long media access (DSC) request (such
* as a rewind) before we can access the other device
* on the same interface. This effect doesn't disturb
* normal operation most of the time because read/write
* requests are relatively fast, and once we are
* performing one tape r/w request, a lot of requests
* from the other device can be queued and ide.c will
* service all of them after this single tape request.
* Ver 1.0 Dec 11 95 Integrated into Linux 1.3.46 development tree.
* On each read / write request, we now ask the drive
* if we can transfer a constant number of bytes
* (a parameter of the drive) only to its buffers,
* without causing actual media access. If we can't,
* we just wait until we can by polling the DSC bit.
* This ensures that while we are not transferring
* more bytes than the constant referred to above, the
* interrupt latency will not become too high and
* we won't cause an interrupt timeout, as happened
* occasionally in the previous version.
* While polling for DSC, the current request is
* postponed and ide.c is free to handle requests from
* the other device. This is handled transparently to
* ide.c. The hwgroup locking method which was used
* in the previous version was removed.
* Use of new general features which are provided by
* ide.c for use with atapi devices.
* (Programming done by Mark Lord)
* Few potential bug fixes (Again, suggested by Mark)
* Single character device data transfers are now
* not limited in size, as they were before.
* We are asking the tape about its recommended
* transfer unit and send a larger data transfer
* as several transfers of the above size.
* For best results, use an integral number of this
* basic unit (which is shown during driver
* initialization). I will soon add an ioctl to get
* this important parameter.
* Our data transfer buffer is allocated on startup,
* rather than before each data transfer. This should
* ensure that we will indeed have a data buffer.
* Ver 1.1 Dec 14 95 Fixed random problems which occurred when the tape
* shared an interface with another device.
* (poll_for_dsc was a complete mess).
* Removed some old (non-active) code which had
* to do with supporting buffer cache originated
* requests.
* The block device interface can now be opened, so
* that general ide driver features like the unmask
* interrupts flag can be selected with an ioctl.
* This is the only use of the block device interface.
* New fast pipelined operation mode (currently only on
* writes). When using the pipelined mode, the
* throughput can potentially reach the maximum
* tape supported throughput, regardless of the
* user backup program. On my tape drive, it sometimes
* boosted performance by a factor of 2. Pipelined
* mode is enabled by default, but since it has a few
* downfalls as well, you may want to disable it.
* A short explanation of the pipelined operation mode
* is available below.
* Ver 1.2 Jan 1 96 Eliminated pipelined mode race condition.
* Added pipeline read mode. As a result, restores
* are now as fast as backups.
* Optimized shared interface behavior. The new behavior
* typically results in better IDE bus efficiency and
* higher tape throughput.
* Pre-calculation of the expected read/write request
* service time, based on the tape's parameters. In
* the pipelined operation mode, this allows us to
* adjust our polling frequency to a much lower value,
* and thus to dramatically reduce our load on Linux,
* without any decrease in performance.
* Implemented additional mtio.h operations.
* The recommended user block size is returned by
* the MTIOCGET ioctl.
* Additional minor changes.
* Ver 1.3 Feb 9 96 Fixed pipelined read mode bug which prevented the
* use of some block sizes during a restore procedure.
* The character device interface will now present a
* continuous view of the media - any mix of block sizes
* during a backup/restore procedure is supported. The
* driver will buffer the requests internally and
* convert them to the tape's recommended transfer
* unit, making performance almost independent of the
* chosen user block size.
* Some improvements in error recovery.
* By cooperating with ide-dma.c, bus mastering DMA can
* now sometimes be used with IDE tape drives as well.
* Bus mastering DMA has the potential to dramatically
* reduce the CPU's overhead when accessing the device,
* and can be enabled by using hdparm -d1 on the tape's
* block device interface. For more info, read the
* comments in ide-dma.c.
* Ver 1.4 Mar 13 96 Fixed serialize support.
* Ver 1.5 Apr 12 96 Fixed shared interface operation, broken in 1.3.85.
* Fixed pipelined read mode inefficiency.
* Fixed nasty null dereferencing bug.
* Ver 1.6 Aug 16 96 Fixed FPU usage in the driver.
* Fixed end of media bug.
* Ver 1.7 Sep 10 96 Minor changes for the CONNER CTT8000-A model.
* Ver 1.8 Sep 26 96 Attempt to find a better balance between good
* interactive response and high system throughput.
* Ver 1.9 Nov 5 96 Automatically cross encountered filemarks rather
* than requiring an explicit FSF command.
* Abort pending requests at end of media.
* MTTELL was sometimes returning incorrect results.
* Return the real block size in the MTIOCGET ioctl.
* Some error recovery bug fixes.
* Ver 1.10 Nov 5 96 Major reorganization.
* Reduced CPU overhead a bit by eliminating internal
* bounce buffers.
* Added module support.
* Added multiple tape drives support.
* Added partition support.
* Rewrote DSC handling.
* Some portability fixes.
* Removed ide-tape.h.
* Additional minor changes.
* Ver 1.11 Dec 2 96 Bug fix in previous DSC timeout handling.
* Use ide_stall_queue() for DSC overlap.
* Use the maximum speed rather than the current speed
* to compute the request service time.
* Ver 1.12 Dec 7 97 Fix random memory overwriting and/or last block data
* corruption, which could occur if the total number
* of bytes written to the tape was not an integral
* number of tape blocks.
* Add support for INTERRUPT DRQ devices.
* Ver 1.13 Jan 2 98 Add "speed == 0" work-around for HP COLORADO 5GB
* Ver 1.14 Dec 30 98 Partial fixes for the Sony/AIWA tape drives.
* Replace cli()/sti() with hwgroup spinlocks.
* Ver 1.15 Mar 25 99 Fix SMP race condition by replacing hwgroup
* spinlock with private per-tape spinlock.
* Ver 1.16 Sep 1 99 Add OnStream tape support.
* Abort read pipeline on EOD.
* Wait for the tape to become ready in case it returns
* "in the process of becoming ready" on open().
* Fix zero padding of the last written block in
* case the tape block size is larger than PAGE_SIZE.
* Decrease the default disconnection time to tn.
* Ver 1.16e Oct 3 99 Minor fixes.
* Ver 1.16e1 Oct 13 99 Patches by Arnold Niessen,
* niessen@iae.nl / arnold.niessen@philips.com
* GO-1) Undefined code in idetape_read_position
* according to Gadi's email
* AJN-1) Minor fix asc == 11 should be asc == 0x11
* in idetape_issue_packet_command (did effect
* debugging output only)
* AJN-2) Added more debugging output, and
* added ide-tape: where missing. I would also
* like to add tape->name where possible
* AJN-3) Added different debug_level's
* via /proc/ide/hdc/settings
* "debug_level" determines amount of debugging output;
* can be changed using /proc/ide/hdx/settings
* 0 : almost no debugging output
* 1 : 0+output errors only
* 2 : 1+output all sensekey/asc
* 3 : 2+follow all chrdev related procedures
* 4 : 3+follow all procedures
* 5 : 4+include pc_stack rq_stack info
* 6 : 5+USE_COUNT updates
* AJN-4) Fixed timeout for retension in idetape_queue_pc_tail
* from 5 to 10 minutes
* AJN-5) Changed maximum number of blocks to skip when
* reading tapes with multiple consecutive write
* errors from 100 to 1000 in idetape_get_logical_blk
* Proposed changes to code:
* 1) output "logical_blk_num" via /proc
* 2) output "current_operation" via /proc
* 3) Either solve or document the fact that `mt rewind' is
* required after reading from /dev/nhtx to be
* able to rmmod the idetape module;
* Also, sometimes an application finishes but the
* device remains `busy' for some time. Same cause ?
* Proposed changes to release-notes:
* 4) write a simple `quickstart' section in the
* release notes; I volunteer if you don't want to
* 5) include a pointer to video4linux in the doc
* to stimulate video applications
* 6) release notes lines 331 and 362: explain what happens
* if the application data rate is higher than 1100 KB/s;
* similar approach to lower-than-500 kB/s ?
* 7) 6.6 Comparison; wouldn't it be better to allow different
* strategies for read and write ?
* Wouldn't it be better to control the tape buffer
* contents instead of the bandwidth ?
* 8) line 536: replace will by would (if I understand
* this section correctly, a hypothetical and unwanted situation
* is being described)
* Ver 1.16f Dec 15 99 Change place of the secondary OnStream header frames.
* Ver 1.17 Nov 2000 / Jan 2001 Marcel Mol, marcel@mesa.nl
* - Add idetape_onstream_mode_sense_tape_parameter_page
* function to get tape capacity in frames: tape->capacity.
* - Add support for DI-50 drives( or any DI- drive).
* - 'workaround' for read error/blank block around block 3000.
* - Implement Early warning for end of media for Onstream.
* - Cosmetic code changes for readability.
* - Idetape_position_tape should not use SKIP bit during
* Onstream read recovery.
* - Add capacity, logical_blk_num and first/last_frame_position
* to /proc/ide/hd?/settings.
* - Module use count was gone in the Linux 2.4 driver.
* Ver 1.17a Apr 2001 Willem Riede osst@riede.org
* - Get drive's actual block size from mode sense block descriptor
* - Limit size of pipeline
* Ver 1.17b Oct 2002 Alan Stern <stern@rowland.harvard.edu>
* Changed IDETAPE_MIN_PIPELINE_STAGES to 1 and actually used
* it in the code!
* Actually removed aborted stages in idetape_abort_pipeline
* instead of just changing the command code.
* Made the transfer byte count for Request Sense equal to the
* actual length of the data transfer.
* Changed handling of partial data transfers: they do not
* cause DMA errors.
* Moved initiation of DMA transfers to the correct place.
* Removed reference to unallocated memory.
* Made __idetape_discard_read_pipeline return the number of
* sectors skipped, not the number of stages.
* Replaced errant kfree() calls with __idetape_kfree_stage().
* Fixed off-by-one error in testing the pipeline length.
* Fixed handling of filemarks in the read pipeline.
* Small code optimization for MTBSF and MTBSFM ioctls.
* Don't try to unlock the door during device close if is
* already unlocked!
* Cosmetic fixes to miscellaneous debugging output messages.
* Set the minimum /proc/ide/hd?/settings values for "pipeline",
* "pipeline_min", and "pipeline_max" to 1.
*/

146
Documentation/ide/ide-tape.txt 100644
View File

@ -0,0 +1,146 @@
/*
* IDE ATAPI streaming tape driver.
*
* This driver is a part of the Linux ide driver.
*
* The driver, in co-operation with ide.c, basically traverses the
* request-list for the block device interface. The character device
* interface, on the other hand, creates new requests, adds them
* to the request-list of the block device, and waits for their completion.
*
* Pipelined operation mode is now supported on both reads and writes.
*
* The block device major and minor numbers are determined from the
* tape's relative position in the ide interfaces, as explained in ide.c.
*
* The character device interface consists of the following devices:
*
* ht0 major 37, minor 0 first IDE tape, rewind on close.
* ht1 major 37, minor 1 second IDE tape, rewind on close.
* ...
* nht0 major 37, minor 128 first IDE tape, no rewind on close.
* nht1 major 37, minor 129 second IDE tape, no rewind on close.
* ...
*
* The general magnetic tape commands compatible interface, as defined by
* include/linux/mtio.h, is accessible through the character device.
*
* General ide driver configuration options, such as the interrupt-unmask
* flag, can be configured by issuing an ioctl to the block device interface,
* as any other ide device.
*
* Our own ide-tape ioctl's can be issued to either the block device or
* the character device interface.
*
* Maximal throughput with minimal bus load will usually be achieved in the
* following scenario:
*
* 1. ide-tape is operating in the pipelined operation mode.
* 2. No buffering is performed by the user backup program.
*
* Testing was done with a 2 GB CONNER CTMA 4000 IDE ATAPI Streaming Tape Drive.
*
* Here are some words from the first releases of hd.c, which are quoted
* in ide.c and apply here as well:
*
* | Special care is recommended. Have Fun!
*
*
* An overview of the pipelined operation mode.
*
* In the pipelined write mode, we will usually just add requests to our
* pipeline and return immediately, before we even start to service them. The
* user program will then have enough time to prepare the next request while
* we are still busy servicing previous requests. In the pipelined read mode,
* the situation is similar - we add read-ahead requests into the pipeline,
* before the user even requested them.
*
* The pipeline can be viewed as a "safety net" which will be activated when
* the system load is high and prevents the user backup program from keeping up
* with the current tape speed. At this point, the pipeline will get
* shorter and shorter but the tape will still be streaming at the same speed.
* Assuming we have enough pipeline stages, the system load will hopefully
* decrease before the pipeline is completely empty, and the backup program
* will be able to "catch up" and refill the pipeline again.
*
* When using the pipelined mode, it would be best to disable any type of
* buffering done by the user program, as ide-tape already provides all the
* benefits in the kernel, where it can be done in a more efficient way.
* As we will usually not block the user program on a request, the most
* efficient user code will then be a simple read-write-read-... cycle.
* Any additional logic will usually just slow down the backup process.
*
* Using the pipelined mode, I get a constant over 400 KBps throughput,
* which seems to be the maximum throughput supported by my tape.
*
* However, there are some downfalls:
*
* 1. We use memory (for data buffers) in proportional to the number
* of pipeline stages (each stage is about 26 KB with my tape).
* 2. In the pipelined write mode, we cheat and postpone error codes
* to the user task. In read mode, the actual tape position
* will be a bit further than the last requested block.
*
* Concerning (1):
*
* 1. We allocate stages dynamically only when we need them. When
* we don't need them, we don't consume additional memory. In
* case we can't allocate stages, we just manage without them
* (at the expense of decreased throughput) so when Linux is
* tight in memory, we will not pose additional difficulties.
*
* 2. The maximum number of stages (which is, in fact, the maximum
* amount of memory) which we allocate is limited by the compile
* time parameter IDETAPE_MAX_PIPELINE_STAGES.
*
* 3. The maximum number of stages is a controlled parameter - We
* don't start from the user defined maximum number of stages
* but from the lower IDETAPE_MIN_PIPELINE_STAGES (again, we
* will not even allocate this amount of stages if the user
* program can't handle the speed). We then implement a feedback
* loop which checks if the pipeline is empty, and if it is, we
* increase the maximum number of stages as necessary until we
* reach the optimum value which just manages to keep the tape
* busy with minimum allocated memory or until we reach
* IDETAPE_MAX_PIPELINE_STAGES.
*
* Concerning (2):
*
* In pipelined write mode, ide-tape can not return accurate error codes
* to the user program since we usually just add the request to the
* pipeline without waiting for it to be serviced. In case an error
* occurs, I will report it on the next user request.
*
* In the pipelined read mode, subsequent read requests or forward
* filemark spacing will perform correctly, as we preserve all blocks
* and filemarks which we encountered during our excess read-ahead.
*
* For accurate tape positioning and error reporting, disabling
* pipelined mode might be the best option.
*
* You can enable/disable/tune the pipelined operation mode by adjusting
* the compile time parameters below.
*
*
* Possible improvements.
*
* 1. Support for the ATAPI overlap protocol.
*
* In order to maximize bus throughput, we currently use the DSC
* overlap method which enables ide.c to service requests from the
* other device while the tape is busy executing a command. The
* DSC overlap method involves polling the tape's status register
* for the DSC bit, and servicing the other device while the tape
* isn't ready.
*
* In the current QIC development standard (December 1995),
* it is recommended that new tape drives will *in addition*
* implement the ATAPI overlap protocol, which is used for the
* same purpose - efficient use of the IDE bus, but is interrupt
* driven and thus has much less CPU overhead.
*
* ATAPI overlap is likely to be supported in most new ATAPI
* devices, including new ATAPI cdroms, and thus provides us
* a method by which we can achieve higher throughput when
* sharing a (fast) ATA-2 disk with any (slow) new ATAPI device.
*/

1
Documentation/ioctl-number.txt
View File

@ -138,6 +138,7 @@ Code Seq# Include File Comments
'm' 00-1F net/irda/irmod.h conflict!
'n' 00-7F linux/ncp_fs.h
'n' E0-FF video/matrox.h matroxfb
'o' 00-1F fs/ocfs2/ocfs2_fs.h OCFS2
'p' 00-0F linux/phantom.h conflict! (OpenHaptics needs this)
'p' 00-3F linux/mc146818rtc.h conflict!
'p' 40-7F linux/nvram.h

8
Documentation/ja_JP/HOWTO
View File

@ -11,14 +11,14 @@ for non English (read: Japanese) speakers and is not intended as a
fork. So if you have any comments or updates for this file, please try
to update the original English file first.
Last Updated: 2007/09/23
Last Updated: 2007/11/16
==================================
これは、
linux-2.6.23/Documentation/HOWTO
linux-2.6.24/Documentation/HOWTO
の和訳です。
翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
翻訳日： 2007/09/19
翻訳日： 2007/11/10
翻訳者： Tsugikazu Shibata <tshibata at ab dot jp dot nec dot com>
校正者： 松倉さん <nbh--mats at nifty dot com>
小林 雅典さん (Masanori Kobayasi) <zap03216 at nifty dot ne dot jp>
@ -110,7 +110,7 @@ Linux カーネルソースツリーは幅広い範囲のドキュメントを
新しいドキュメントファイルも追加することを勧めます。
カーネルの変更が、カーネルがユーザ空間に公開しているインターフェイスの
変更を引き起こす場合、その変更を説明するマニュアルページのパッチや情報
をマニュアルページのメンテナ mtk-manpages@gmx.net に送ることを勧めま
をマニュアルページのメンテナ mtk.manpages@gmail.com に送ることを勧めま
す。
以下はカーネルソースツリーに含まれている読んでおくべきファイルの一覧で

556
Documentation/ja_JP/SubmittingPatches 100644
View File

@ -0,0 +1,556 @@
NOTE:
This is a version of Documentation/SubmittingPatches into Japanese.
This document is maintained by Keiichi KII <k-keiichi@bx.jp.nec.com>
and the JF Project team <http://www.linux.or.jp/JF/>.
If you find any difference between this document and the original file
or a problem with the translation,
please contact the maintainer of this file or JF project.
Please also note that the purpose of this file is to be easier to read
for non English (read: Japanese) speakers and is not intended as a
fork. So if you have any comments or updates of this file, please try
to update the original English file first.
Last Updated: 2007/10/24
==================================
これは、
linux-2.6.23/Documentation/SubmittingPatches の和訳
です。
翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
翻訳日： 2007/10/17
翻訳者： Keiichi Kii <k-keiichi at bx dot jp dot nec dot com>
校正者： Masanari Kobayashi さん <zap03216 at nifty dot ne dot jp>
Matsukura さん <nbh--mats at nifty dot com>
==================================
Linux カーネルに変更を加えるための Howto
又は
かの Linus Torvalds の取り扱い説明書
Linux カーネルに変更を加えたいと思っている個人又は会社にとって、パッ
チの投稿に関連した仕組みに慣れていなければ、その過程は時々みなさんを
おじけづかせることもあります。この文章はあなたの変更を大いに受け入れ
てもらえやすくする提案を集めたものです。
コードを投稿する前に、Documentation/SubmitChecklist の項目リストに目
を通してチェックしてください。もしあなたがドライバーを投稿しようとし
ているなら、Documentation/SubmittingDrivers にも目を通してください。
--------------------------------------------
セクション1 パッチの作り方と送り方
--------------------------------------------
1) 「 diff -up 」
------------
パッチの作成には「 diff -up 」又は「 diff -uprN 」を使ってください。
Linux カーネルに対する全ての変更は diff(1) コマンドによるパッチの形式で
生成してください。パッチを作成するときには、diff(1) コマンドに「 -u 」引
数を指定して、unified 形式のパッチを作成することを確認してください。また、
変更がどの C 関数で行われたのかを表示する「 -p 」引数を使ってください。
この引数は生成した差分をずっと読みやすくしてくれます。パッチは Linux
カーネルソースの中のサブディレクトリではなく Linux カーネルソースのルート
ディレクトリを基準にしないといけません。
1個のファイルについてのパッチを作成するためには、ほとんどの場合、
以下の作業を行えば十分です。
SRCTREE= linux-2.6
MYFILE= drivers/net/mydriver.c
cd $SRCTREE
cp $MYFILE $MYFILE.orig
vi $MYFILE # make your change
cd ..
diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch
複数のファイルについてのパッチを作成するためには、素の( vanilla )、す
なわち変更を加えてない Linux カーネルを展開し、自分の Linux カーネル
ソースとの差分を生成しないといけません。例えば、
MYSRC= /devel/linux-2.6
tar xvfz linux-2.6.12.tar.gz
mv linux-2.6.12 linux-2.6.12-vanilla
diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \
linux-2.6.12-vanilla $MYSRC > /tmp/patch
dontdiff ファイルには Linux カーネルのビルドプロセスの過程で生成された
ファイルの一覧がのっています。そして、それらはパッチを生成する diff(1)
コマンドで無視されるべきです。dontdiff ファイルは 2.6.12 以後のバージョ
ンの Linux カーネルソースツリーに含まれています。それより前のバージョン
の Linux カーネルソースツリーに対する dontdiff ファイルは、
<http://www.xenotime.net/linux/doc/dontdiff>から取得することができます。
投稿するパッチの中に関係のない余分なファイルが含まれていないことを確
認してください。diff(1) コマンドで生成したパッチがあなたの意図したとお
りのものであることを確認してください。
もしあなたのパッチが多くの差分を生み出すのであれば、あなたはパッチ
を意味のあるひとまとまりごとに分けたいと思うかもしれません。
これは他のカーネル開発者にとってレビューしやすくなるので、あなたの
パッチを受け入れてもらうためにはとても重要なことです。これを補助でき
る多くのスクリプトがあります。
Quilt:
http://savannah.nongnu.org/projects/quilt
Andrew Morton's patch scripts:
http://www.zip.com.au/~akpm/linux/patches/
このリンクの先のスクリプトの代わりとして、quilt がパッチマネジメント
ツールとして推奨されています(上のリンクを見てください)。
2) パッチに対する説明
パッチの中の変更点に対する技術的な詳細について説明してください。
説明はできる限り具体的に。もっとも悪い説明は「ドライバー X を更新」、
「ドライバー X に対するバグフィックス」あるいは「このパッチはサブシス
テム X に対する更新を含んでいます。どうか取り入れてください。」などです。
説明が長くなりだしたのであれば、おそらくそれはパッチを分ける必要がある
という兆候です。次の #3 を見てください。
3) パッチの分割
意味のあるひとまとまりごとに変更を個々のパッチファイルに分けてください。
例えば、もし1つのドライバーに対するバグフィックスとパフォーマンス強
化の両方の変更を含んでいるのであれば、その変更を2つ以上のパッチに分
けてください。もし変更箇所に API の更新と、その新しい API を使う新たな
ドライバーが含まれているなら、2つのパッチに分けてください。
一方で、もしあなたが多数のファイルに対して意味的に同じ1つの変更を加え
るのであれば、その変更を1つのパッチにまとめてください。言いかえると、
意味的に同じ1つの変更は1つのパッチの中に含まれます。
あるパッチが変更を完結させるために他のパッチに依存していたとしても、
それは問題ありません。パッチの説明の中で「このパッチはパッチ X に依存
している」と簡単に注意書きをつけてください。
もしパッチをより小さなパッチの集合に凝縮することができないなら、まずは
15かそこらのパッチを送り、そのレビューと統合を待って下さい。
4) パッチのスタイルチェック
あなたのパッチが基本的な( Linux カーネルの)コーディングスタイルに違反し
ていないかをチェックして下さい。その詳細を Documentation/CodingStyle で
見つけることができます。コーディングスタイルの違反はレビューする人の
時間を無駄にするだけなので、恐らくあなたのパッチは読まれることすらなく
拒否されるでしょう。
あなたはパッチを投稿する前に最低限パッチスタイルチェッカー
( scripts/patchcheck.pl )を利用してパッチをチェックすべきです。
もしパッチに違反がのこっているならば、それらの全てについてあなたは正当な
理由を示せるようにしておく必要があります。
5) 電子メールの宛先の選び方
MAINTAINERS ファイルとソースコードに目を通してください。そして、その変
更がメンテナのいる特定のサブシステムに加えられるものであることが分か
れば、その人に電子メールを送ってください。
もし、メンテナが載っていなかったり、メンテナからの応答がないなら、
LKML ( linux-kernel@vger.kernel.org )へパッチを送ってください。ほとんど
のカーネル開発者はこのメーリングリストに目を通しており、変更に対して
コメントを得ることができます。
15個より多くのパッチを同時に vger.kernel.org のメーリングリストへ送らな
いでください!!!
Linus Torvalds は Linux カーネルに入る全ての変更に対する最終的な意思決定者
です。電子メールアドレスは torvalds@linux-foundation.org になります。彼は
多くの電子メールを受け取っているため、できる限り彼に電子メールを送るのは
避けるべきです。
バグフィックスであったり、自明な変更であったり、話し合いをほとんど
必要としないパッチは Linus へ電子メールを送るか CC しなければなりません。
話し合いを必要としたり、明確なアドバンテージがないパッチは、通常まず
は LKML へ送られるべきです。パッチが議論された後にだけ、そのパッチを
Linus へ送るべきです。
6) CC (カーボンコピー)先の選び方
特に理由がないなら、LKML にも CC してください。
Linus 以外のカーネル開発者は変更に気づく必要があり、その結果、彼らはそ
の変更に対してコメントをくれたり、コードに対してレビューや提案をくれ
るかもしれません。LKML とは Linux カーネル開発者にとって一番中心的なメー
リングリストです。USB やフレームバッファデバイスや VFS や SCSI サブシステ
ムなどの特定のサブシステムに関するメーリングリストもあります。あなた
の変更に、はっきりと関連のあるメーリングリストについて知りたければ
MAINTAINERS ファイルを参照してください。
VGER.KERNEL.ORG でホスティングされているメーリングリストの一覧が下記の
サイトに載っています。
<http://vger.kernel.org/vger-lists.html>
もし、変更がユーザランドのカーネルインタフェースに影響を与え
るのであれば、MAN-PAGES のメンテナ( MAINTAINERS ファイルに一覧
があります)に man ページのパッチを送ってください。少なくとも
情報がマニュアルページの中に入ってくるように、変更が起きたという
通知を送ってください。
たとえ、メンテナが #4 で反応がなかったとしても、メンテナのコードに変更を
加えたときには、いつもメンテナに CC するのを忘れないようにしてください。
小さなパッチであれば、Adrian Bunk が管理している Trivial Patch Monkey
(ちょっとしたパッチを集めている)<trivial@kernel.org>に CC してもいい
です。ちょっとしたパッチとは以下のルールのどれか1つを満たしていなけ
ればなりません。
・ドキュメントのスペルミスの修正
・grep(1) コマンドによる検索を困難にしているスペルの修正
・コンパイル時の警告の修正(無駄な警告が散乱することは好ましくないた
めです)
・コンパイル問題の修正(それらの修正が本当に正しい場合に限る)
・実行時の問題の修正(それらの修正が本当に問題を修正している場合に限る)
・廃止予定の関数やマクロを使用しているコードの除去(例 check_region )
・問い合わせ先やドキュメントの修正
・移植性のないコードから移植性のあるコードへの置き換え(小さい範囲で
あればアーキテクチャ特有のことでも他の人がコピーできます)
・作者やメンテナによる修正(すなわち patch monkey の再転送モード)
URL: <http://www.kernel.org/pub/linux/kernel/people/bunk/trivial/>
7) MIME やリンクや圧縮ファイルや添付ファイルではなくプレインテキストのみ
Linus や他のカーネル開発者はあなたが投稿した変更を読んで、コメントでき
る必要があります。カーネル開発者にとって、あなたが書いたコードの特定の
部分にコメントをするために、標準的な電子メールクライアントで変更が引用
できることは重要です。
上記の理由で、すべてのパッチは文中に含める形式の電子メールで投稿さ
れるべきです。警告：あなたがパッチをコピー&ペーストする際には、パッ
チを改悪するエディターの折り返し機能に注意してください。
パッチを圧縮の有無に関わらず MIME 形式で添付しないでください。多くのポ
ピュラーな電子メールクライアントは MIME 形式の添付ファイルをプレーンテ
キストとして送信するとは限らないでしょう。そうなると、電子メールクラ
イアントがコードに対するコメントを付けることをできなくします。また、
MIME 形式の添付ファイルは Linus に手間を取らせることになり、その変更を
受け入れてもらう可能性が低くなってしまいます。
例外：お使いの電子メールクライアントがパッチをめちゃくちゃにするので
あれば、誰かが MIME 形式のパッチを再送するよう求めるかもしれません。
警告： Mozilla のような特定の電子メールクライアントは電子メールの
ヘッダに以下のものを付加して送ります。
---- message header ----
Content-Type: text/plain; charset=us-ascii; format=flowed
---- message header ----
問題は、「 format=flowed 」が付いた電子メールを特定の受信側の電子メール
クライアントがタブをスペースに置き換えるというような変更をすることです。
したがって送られてきたパッチは壊れているように見えるでしょう。
これを修正するには、mozilla の defaults/pref/mailnews.js ファイルを
以下のように修正します。
pref("mailnews.send_plaintext_flowed", false); // RFC 2646=======
pref("mailnews.display.disable_format_flowed_support", true);
8) 電子メールのサイズ
パッチを Linus へ送るときは常に #7 の手順に従ってください。
大きなパッチはメーリングリストやメンテナにとって不親切です。パッチが
未圧縮で 40KB を超えるようであるなら、インターネット上のアクセス可能な
サーバに保存し、保存場所を示す URL を伝えるほうが適切です。
9) カーネルバージョンの明記
パッチが対象とするカーネルのバージョンをパッチの概要か電子メールの
サブジェクトに付けることが重要です。
パッチが最新バージョンのカーネルに正しく適用できなければ、Linus は
そのパッチを採用しないでしょう。
10) がっかりせず再投稿
パッチを投稿した後は、辛抱強く待っていてください。Linus があなたのパッ
チを気に入って採用すれば、Linus がリリースする次のバージョンのカーネル
の中で姿を見せるでしょう。
しかし、パッチが次のバージョンのカーネルに入っていないなら、いくつもの
理由があるのでしょう。その原因を絞り込み、間違っているものを正し、更新
したパッチを投稿するのはあなたの仕事です。
Linus があなたのパッチに対して何のコメントもなく不採用にすることは極め
て普通のことです。それは自然な姿です。もし、Linus があなたのパッチを受
け取っていないのであれば、以下の理由が考えられます。
* パッチが最新バージョンの Linux カーネルにきちんと適用できなかった
* パッチが LKML で十分に議論されていなかった
* スタイルの問題(セクション2を参照)
* 電子メールフォーマットの問題(このセクションを参照)
* パッチに対する技術的な問題
* Linus はたくさんの電子メールを受け取っているので、どさくさに紛れて見
失った
* 不愉快にさせている
判断できない場合は、LKML にコメントを頼んでください。
11) サブジェクトに「 PATCH 」
Linus や LKML への大量の電子メールのために、サブジェクトのプレフィックスに
「 [PATCH] 」を付けることが慣習となっています。これによって Linus や他の
カーネル開発者がパッチであるのか、又は、他の議論に関する電子メールであるの
かをより簡単に識別できます。
12) パッチへの署名
誰が何をしたのかを追いかけやすくするために (特に、パッチが何人かの
メンテナを経て最終的に Linux カーネルに取り込まれる場合のために)、電子
メールでやり取りされるパッチに対して「 sign-off 」という手続きを導入し
ました。
「 sign-off 」とは、パッチがあなたの書いたものであるか、あるいは、
あなたがそのパッチをオープンソースとして提供する権利を保持している、
という証明をパッチの説明の末尾に一行記載するというものです。
ルールはとても単純です。以下の項目を確認して下さい。
原作者の証明書( DCO ) 1.1
このプロジェクトに寄与するものとして、以下のことを証明する。
(a) 本寄与は私が全体又は一部作成したものであり、私がそのファイ
ル中に明示されたオープンソースライセンスの下で公開する権利
を持っている。もしくは、
(b) 本寄与は、私が知る限り、適切なオープンソースライセンスでカバ
ーされている既存の作品を元にしている。同時に、私はそのライセ
ンスの下で、私が全体又は一部作成した修正物を、ファイル中で示
される同一のオープンソースライセンスで(異なるライセンスの下で
投稿することが許可されている場合を除いて)投稿する権利を持って
いる。もしくは、
(c) 本寄与は(a)、(b)、(c)を証明する第3者から私へ直接提供された
ものであり、私はそれに変更を加えていない。
(d) 私はこのプロジェクトと本寄与が公のものであることに理解及び同意す
る。同時に、関与した記録(投稿の際の全ての個人情報と sign-off を
含む)が無期限に保全されることと、当該プロジェクト又は関連する
オープンソースライセンスに沿った形で再配布されることに理解及び
同意する。
もしこれに同意できるなら、以下のような1行を追加してください。
Signed-off-by: Random J Developer <random@developer.example.org>
実名を使ってください。(残念ですが、偽名や匿名による寄与はできません。)
人によっては sign-off の近くに追加のタグを付加しています。それらは今のところ
無視されますが、あなたはそのタグを社内の手続きに利用したり、sign-off に特別
な情報を示したりすることができます。
13) いつ Acked-by: を使うのか
「 Signed-off-by: 」タグはその署名者がパッチの開発に関わっていたことやパッチ
の伝播パスにいたことを示しています。
ある人が直接パッチの準備や作成に関わっていないけれど、その人のパッチに対す
る承認を記録し、示したいとします。その場合、その人を示すのに Acked-by: が使
えます。Acked-by: はパッチのチェンジログにも追加されます。
パッチの影響を受けるコードのメンテナがパッチに関わっていなかったり、パッチ
の伝播パスにいなかった時にも、メンテナは Acked-by: をしばしば利用します。
Acked-by: は Signed-off-by: のように公式なタグではありません。それはメンテナが
少なくともパッチをレビューし、同意を示しているという記録です。そのような
ことからパッチの統合者がメンテナの「うん、良いと思うよ」という発言を
Acked-by: へ置き換えることがあります。
Acked-by: が必ずしもパッチ全体の承認を示しているわけではありません。例えば、
あるパッチが複数のサブシステムへ影響を与えており、その中の1つのサブシステム
のメンテナからの Acked-by: を持っているとします。その場合、Acked-by: は通常
そのメンテナのコードに影響を与える一部分だけに対する承認を示しています。
この点は、ご自分で判断してください。(その Acked-by: が)疑わしい場合は、
メーリングリストアーカイブの中の大元の議論を参照すべきです。
14) 標準的なパッチのフォーマット
標準的なパッチのサブジェクトは以下のとおりです。
Subject: [PATCH 001/123] subsystem: summary phrase
標準的なパッチの、電子メールのボディは以下の項目を含んでいます。
- パッチの作成者を明記する「 from 」行
- 空行
- 説明本体。これはこのパッチを説明するために無期限のチェンジログ
(変更履歴)にコピーされます。
- 上述した「 Signed-off-by: 」行。これも説明本体と同じくチェン
ジログ内にコピーされます。
- マーカー行は単純に「 --- 」です。
- 余計なコメントは、チェンジログには不適切です。
- 実際のパッチ(差分出力)
サブジェクト行のフォーマットは、アルファベット順で電子メールをとても
ソートしやすいものになっています。(ほとんどの電子メールクライアント
はソートをサポートしています)パッチのサブジェクトの連番は0詰めであ
るため、数字でのソートとアルファベットでのソートは同じ結果になります。
電子メールのサブジェクト内のサブシステム表記は、パッチが適用される
分野またはサブシステムを識別できるようにすべきです。
電子メールのサブジェクトの「概要の言い回し」はそのパッチの概要を正確
に表現しなければなりません。「概要の言い回し」をファイル名にしてはい
けません。一連のパッチ中でそれぞれのパッチは同じ「概要の言い回し」を
使ってはいけません(「一連のパッチ」とは順序付けられた関連のある複数の
パッチ群です)。
あなたの電子メールの「概要の言い回し」がそのパッチにとって世界で唯
一の識別子になるように心がけてください。「概要の言い回し」は git の
チェンジログの中へずっと伝播していきます。「概要の言い回し」は、開
発者が後でパッチを参照するために議論の中で利用するかもしれません。
人々はそのパッチに関連した議論を読むために「概要の言い回し」を使って
google で検索したがるでしょう。
サブジェクトの例を二つ
Subject: [patch 2/5] ext2: improve scalability of bitmap searching
Subject: [PATCHv2 001/207] x86: fix eflags tracking
「 from 」行は電子メールのボディの一番最初の行でなければなりません。
その形式は以下のとおりです。
From: Original Author <author@example.com>
「 from 」行はチェンジログの中で、そのパッチの作成者としてクレジットされ
ている人を特定するものです。「 from 」行がかけていると、電子メールのヘッ
ダーの「 From: 」が、チェンジログの中でパッチの作成者を決定するために使わ
れるでしょう。
説明本体は無期限のソースのチェンジログにコミットされます。なので、説明
本体はそのパッチに至った議論の詳細を忘れているある程度の技量を持っている人
がその詳細を思い出すことができるものでなければなりません。
「 --- 」マーカー行はパッチ処理ツールに対して、チェンジログメッセージの終端
部分を認識させるという重要な役目を果たします。
「 --- 」マーカー行の後の追加コメントの良い使用方法の1つに diffstat コマンド
があります。diffstat コマンドとは何のファイルが変更され、1ファイル当たり何行
追加され何行消されたかを示すものです。diffstat コマンドは特に大きなパッチに
おいて役立ちます。その時点でだけ又はメンテナにとってのみ関係のあるコメント
は無期限に保存されるチェンジログにとって適切ではありません。そのため、この
ようなコメントもマーカー行の後に書かれるべきです。ファイル名はカーネルソー
スツリーのトップディレクトリからの表記でリストされるため、横方向のスペース
をとり過ぎないように、diffstat コマンドにオプション「 -p 1 -w 70 」を指定し
てください(インデントを含めてちょうど80列に合うでしょう)。
適切なパッチのフォーマットの詳細についてはセクション3の参考文献を参照して
ください。
------------------------------------
セクション2 - ヒントとTIPSと小技
------------------------------------
このセクションは Linux カーネルに変更を適用することに関係のある一般的な
「お約束」の多くを載せています。物事には例外というものがあります。しか
し例外を適用するには、本当に妥当な理由が不可欠です。あなたは恐らくこの
セクションを Linus のコンピュータ・サイエンス101と呼ぶでしょう。
1) Documentation/CodingStyleを参照
言うまでもなく、あなたのコードがこのコーディングスタイルからあまりに
も逸脱していると、レビューやコメントなしに受け取ってもらえないかもし
れません。
唯一の特筆すべき例外は、コードをあるファイルから別のファイルに移動
するときです。この場合、コードを移動するパッチでは、移動されるコード
に関して移動以外の変更を一切加えるべきではありません。これにより、
コードの移動とあなたが行ったコードの修正を明確に区別できるようにな
ります。これは実際に何が変更されたかをレビューする際の大きな助けに
なるとともに、ツールにコードの履歴を追跡させることも容易になります。
投稿するより前にパッチのスタイルチェッカー( scripts/checkpatch.pl )で
あなたのパッチをチェックしてください。このスタイルチェッカーは最終結
論としてではなく、指標としてみるべきです。もし、あなたのコードが違反
はしているが修正するより良く見えるのであれば、おそらくそのままにする
のがベストです。
スタイルチェッカーによる3段階のレポート:
- エラー: 間違っている可能性が高い
- 警告：注意してレビューする必要がある
- チェック：考慮する必要がある
あなたはパッチに残っている全ての違反について、それがなぜ必要なのか正当な
理由を示せるようにしておく必要があります。
2) #ifdefは見苦しい
ifdef が散乱したコードは、読むのもメンテナンスするのも面倒です。コードの中
で ifdef を使わないでください。代わりに、ヘッダファイルの中に ifdef を入れて、
条件付きで、コードの中で使われる関数を「 static inline 」関数かマクロで定義し
てください。後はコンパイラが、何もしない箇所を最適化して取り去ってくれるで
しょう。
まずいコードの簡単な例
dev = alloc_etherdev (sizeof(struct funky_private));
if (!dev)
return -ENODEV;
#ifdef CONFIG_NET_FUNKINESS
init_funky_net(dev);
#endif
クリーンアップしたコードの例
(in header)
#ifndef CONFIG_NET_FUNKINESS
static inline void init_funky_net (struct net_device *d) {}
#endif
(in the code itself)
dev = alloc_etherdev (sizeof(struct funky_private));
if (!dev)
return -ENODEV;
init_funky_net(dev);
3) マクロより「 static inline 」を推奨
「 static inline 」関数はマクロよりもずっと推奨されています。それらは、
型安全性があり、長さにも制限が無く、フォーマットの制限もありません。
gcc においては、マクロと同じくらい軽いです。
マクロは「 static inline 」が明らかに不適切であると分かる場所(高速化パスの
いくつかの特定のケース)や「 static inline 」関数を使うことができないような
場所(マクロの引数の文字列連結のような)にだけ使われるべきです。
「 static inline 」は「 static __inline__ 」や「 extern inline 」や
「 extern __inline__ 」よりも適切です。
4) 設計に凝りすぎるな
それが有用になるかどうか分からないような不明瞭な将来を見越した設計
をしないでください。「できる限り簡単に、そして、それ以上簡単になら
ないような設計をしてください。」
----------------------
セクション3 参考文献
----------------------
Andrew Morton, "The perfect patch" (tpp).
<http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt>
Jeff Garzik, "Linux kernel patch submission format".
<http://linux.yyz.us/patch-format.html>
Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
<http://www.kroah.com/log/2005/03/31/>
<http://www.kroah.com/log/2005/07/08/>
<http://www.kroah.com/log/2005/10/19/>
<http://www.kroah.com/log/2006/01/11/>
NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
<http://marc.theaimsgroup.com/?l=linux-kernel&m=112112749912944&w=2>
Kernel Documentation/CodingStyle:
<http://users.sosdg.org/~qiyong/lxr/source/Documentation/CodingStyle>
Linus Torvalds's mail on the canonical patch format:
<http://lkml.org/lkml/2005/4/7/183>
--

111
Documentation/kbuild/kconfig-language.txt
View File

@ -24,7 +24,7 @@ visible if its parent entry is also visible.
Menu entries
------------
Most entries define a config option, all other entries help to organize
Most entries define a config option; all other entries help to organize
them. A single configuration option is defined like this:
config MODVERSIONS
@ -50,7 +50,7 @@ applicable everywhere (see syntax).
- type definition: "bool"/"tristate"/"string"/"hex"/"int"
Every config option must have a type. There are only two basic types:
tristate and string, the other types are based on these two. The type
tristate and string; the other types are based on these two. The type
definition optionally accepts an input prompt, so these two examples
are equivalent:
@ -108,7 +108,7 @@ applicable everywhere (see syntax).
equal to 'y' without visiting the dependencies. So abusing
select you are able to select a symbol FOO even if FOO depends
on BAR that is not set. In general use select only for
non-visible symbols (no promts anywhere) and for symbols with
non-visible symbols (no prompts anywhere) and for symbols with
no dependencies. That will limit the usefulness but on the
other hand avoid the illegal configurations all over. kconfig
should one day warn about such things.
@ -127,6 +127,27 @@ applicable everywhere (see syntax).
used to help visually separate configuration logic from help within
the file as an aid to developers.
- misc options: "option" <symbol>[=<value>]
Various less common options can be defined via this option syntax,
which can modify the behaviour of the menu entry and its config
symbol. These options are currently possible:
- "defconfig_list"
This declares a list of default entries which can be used when
looking for the default configuration (which is used when the main
.config doesn't exists yet.)
- "modules"
This declares the symbol to be used as the MODULES symbol, which
enables the third modular state for all config symbols.
- "env"=<value>
This imports the environment variable into Kconfig. It behaves like
a default, except that the value comes from the environment, this
also means that the behaviour when mixing it with normal defaults is
undefined at this point. The symbol is currently not exported back
to the build environment (if this is desired, it can be done via
another symbol).
Menu dependencies
-----------------
@ -162,9 +183,9 @@ An expression can have a value of 'n', 'm' or 'y' (or 0, 1, 2
respectively for calculations). A menu entry becomes visible when it's
expression evaluates to 'm' or 'y'.
There are two types of symbols: constant and nonconstant symbols.
Nonconstant symbols are the most common ones and are defined with the
'config' statement. Nonconstant symbols consist entirely of alphanumeric
There are two types of symbols: constant and non-constant symbols.
Non-constant symbols are the most common ones and are defined with the
'config' statement. Non-constant symbols consist entirely of alphanumeric
characters or underscores.
Constant symbols are only part of expressions. Constant symbols are
always surrounded by single or double quotes. Within the quote, any
@ -301,3 +322,81 @@ mainmenu:
This sets the config program's title bar if the config program chooses
to use it.
Kconfig hints
-------------
This is a collection of Kconfig tips, most of which aren't obvious at
first glance and most of which have become idioms in several Kconfig
files.
Adding common features and make the usage configurable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is a common idiom to implement a feature/functionality that are
relevant for some architectures but not all.
The recommended way to do so is to use a config variable named HAVE_*
that is defined in a common Kconfig file and selected by the relevant
architectures.
An example is the generic IOMAP functionality.
We would in lib/Kconfig see:
# Generic IOMAP is used to ...
config HAVE_GENERIC_IOMAP
config GENERIC_IOMAP
depends on HAVE_GENERIC_IOMAP && FOO
And in lib/Makefile we would see:
obj-$(CONFIG_GENERIC_IOMAP) += iomap.o
For each architecture using the generic IOMAP functionality we would see:
config X86
select ...
select HAVE_GENERIC_IOMAP
select ...
Note: we use the existing config option and avoid creating a new
config variable to select HAVE_GENERIC_IOMAP.
Note: the use of the internal config variable HAVE_GENERIC_IOMAP, it is
introduced to overcome the limitation of select which will force a
config option to 'y' no matter the dependencies.
The dependencies are moved to the symbol GENERIC_IOMAP and we avoid the
situation where select forces a symbol equals to 'y'.
Build as module only
~~~~~~~~~~~~~~~~~~~~
To restrict a component build to module-only, qualify its config symbol
with "depends on m". E.g.:
config FOO
depends on BAR && m
limits FOO to module (=m) or disabled (=n).
Build limited by a third config symbol which may be =y or =m
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A common idiom that we see (and sometimes have problems with) is this:
When option C in B (module or subsystem) uses interfaces from A (module
or subsystem), and both A and B are tristate (could be =y or =m if they
were independent of each other, but they aren't), then we need to limit
C such that it cannot be built statically if A is built as a loadable
module. (C already depends on B, so there is no dependency issue to
take care of here.)
If A is linked statically into the kernel image, C can be built
statically or as loadable module(s). However, if A is built as loadable
module(s), then C must be restricted to loadable module(s) also. This
can be expressed in kconfig language as:
config C
depends on A = y || A = B
or for real examples, use this command in a kernel tree:
$ find . -name Kconfig\* | xargs grep -ns "depends on.*=.*||.*=" | grep -v orig

105
Documentation/kernel-parameters.txt
View File

@ -34,6 +34,7 @@ parameter is applicable:
ALSA ALSA sound support is enabled.
APIC APIC support is enabled.
APM Advanced Power Management support is enabled.
AVR32 AVR32 architecture is enabled.
AX25 Appropriate AX.25 support is enabled.
BLACKFIN Blackfin architecture is enabled.
DRM Direct Rendering Management support is enabled.
@ -167,6 +168,11 @@ and is between 256 and 4096 characters. It is defined in the file
acpi_irq_isa= [HW,ACPI] If irq_balance, mark listed IRQs used by ISA
Format: <irq>,<irq>...
acpi_new_pts_ordering [HW,ACPI]
Enforce the ACPI 2.0 ordering of the _PTS control
method wrt putting devices into low power states
default: pre ACPI 2.0 ordering of _PTS
acpi_no_auto_ssdt [HW,ACPI] Disable automatic loading of SSDT
acpi_os_name= [HW,ACPI] Tell ACPI BIOS the name of the OS
@ -369,7 +375,8 @@ and is between 256 and 4096 characters. It is defined in the file
configured. Potentially dangerous and should only be
used if you are entirely sure of the consequences.
chandev= [HW,NET] Generic channel device initialisation
ccw_timeout_log [S390]
See Documentation/s390/CommonIO for details.
checkreqprot [SELINUX] Set initial checkreqprot flag value.
Format: { "0" | "1" }
@ -381,6 +388,12 @@ and is between 256 and 4096 characters. It is defined in the file
Value can be changed at runtime via
/selinux/checkreqprot.
cio_ignore= [S390]
See Documentation/s390/CommonIO for details.
cio_msg= [S390]
See Documentation/s390/CommonIO for details.
clock= [BUGS=X86-32, HW] gettimeofday clocksource override.
[Deprecated]
Forces specified clocksource (if available) to be used
@ -408,8 +421,21 @@ and is between 256 and 4096 characters. It is defined in the file
[SPARC64] tick
[X86-64] hpet,tsc
code_bytes [IA32] How many bytes of object code to print in an
oops report.
clearcpuid=BITNUM [X86]
Disable CPUID feature X for the kernel. See
include/asm-x86/cpufeature.h for the valid bit numbers.
Note the Linux specific bits are not necessarily
stable over kernel options, but the vendor specific
ones should be.
Also note that user programs calling CPUID directly
or using the feature without checking anything
will still see it. This just prevents it from
being used by the kernel or shown in /proc/cpuinfo.
Also note the kernel might malfunction if you disable
some critical bits.
code_bytes [IA32/X86_64] How many bytes of object code to print
in an oops report.
Range: 0 - 8192
Default: 64
@ -527,29 +553,30 @@ and is between 256 and 4096 characters. It is defined in the file
Format: <area>[,<node>]
See also Documentation/networking/decnet.txt.
default_blu= [VT]
vt.default_blu= [VT]
Format: <blue0>,<blue1>,<blue2>,...,<blue15>
Change the default blue palette of the console.
This is a 16-member array composed of values
ranging from 0-255.
default_grn= [VT]
vt.default_grn= [VT]
Format: <green0>,<green1>,<green2>,...,<green15>
Change the default green palette of the console.
This is a 16-member array composed of values
ranging from 0-255.
default_red= [VT]
vt.default_red= [VT]
Format: <red0>,<red1>,<red2>,...,<red15>
Change the default red palette of the console.
This is a 16-member array composed of values
ranging from 0-255.
default_utf8= [VT]
vt.default_utf8=
[VT]
Format=<0|1>
Set system-wide default UTF-8 mode for all tty's.
Default is 0 and by setting to 1, it enables UTF-8
mode for all newly opened or allocated terminals.
Default is 1, i.e. UTF-8 mode is enabled for all
newly opened terminals.
dhash_entries= [KNL]
Set number of hash buckets for dentry cache.
@ -561,6 +588,12 @@ and is between 256 and 4096 characters. It is defined in the file
See drivers/char/README.epca and
Documentation/digiepca.txt.
disable_mtrr_trim [X86, Intel and AMD only]
By default the kernel will trim any uncacheable
memory out of your available memory pool based on
MTRR settings. This parameter disables that behavior,
possibly causing your machine to run very slowly.
dmasound= [HW,OSS] Sound subsystem buffers
dscc4.setup= [NET]
@ -586,11 +619,6 @@ and is between 256 and 4096 characters. It is defined in the file
eata= [HW,SCSI]
ec_intr= [HW,ACPI] ACPI Embedded Controller interrupt mode
Format: <int>
0: polling mode
non-0: interrupt mode (default)
edd= [EDD]
Format: {"of[f]" | "sk[ipmbr]"}
See comment in arch/i386/boot/edd.S
@ -656,6 +684,10 @@ and is between 256 and 4096 characters. It is defined in the file
gamma= [HW,DRM]
gart_fix_e820= [X86_64] disable the fix e820 for K8 GART
Format: off | on
default: on
gdth= [HW,SCSI]
See header of drivers/scsi/gdth.c.
@ -690,6 +722,7 @@ and is between 256 and 4096 characters. It is defined in the file
See Documentation/isdn/README.HiSax.
hugepages= [HW,X86-32,IA-64] Maximal number of HugeTLB pages.
hugepagesz= [HW,IA-64,PPC] The size of the HugeTLB pages.
i8042.direct [HW] Put keyboard port into non-translated mode
i8042.dumbkbd [HW] Pretend that controller can only read data from
@ -790,6 +823,16 @@ and is between 256 and 4096 characters. It is defined in the file
for translation below 32 bit and if not available
then look in the higher range.
io_delay= [X86-32,X86-64] I/O delay method
0x80
Standard port 0x80 based delay
0xed
Alternate port 0xed based delay (needed on some systems)
udelay
Simple two microseconds delay
none
No delay
io7= [HW] IO7 for Marvel based alpha systems
See comment before marvel_specify_io7 in
arch/alpha/kernel/core_marvel.c.
@ -887,6 +930,14 @@ and is between 256 and 4096 characters. It is defined in the file
lapic_timer_c2_ok [X86-32,x86-64,APIC] trust the local apic timer in
C2 power state.
libata.dma= [LIBATA] DMA control
libata.dma=0 Disable all PATA and SATA DMA
libata.dma=1 PATA and SATA Disk DMA only
libata.dma=2 ATAPI (CDROM) DMA only
libata.dma=4 Compact Flash DMA only
Combinations also work, so libata.dma=3 enables DMA
for disks and CDROMs, but not CFs.
libata.noacpi [LIBATA] Disables use of ACPI in libata suspend/resume
when set.
Format: <int>
@ -1047,6 +1098,11 @@ and is between 256 and 4096 characters. It is defined in the file
Multi-Function General Purpose Timers on AMD Geode
platforms.
mfgptfix [X86-32] Fix MFGPT timers on AMD Geode platforms when
the BIOS has incorrectly applied a workaround. TinyBIOS
version 0.98 is known to be affected, 0.99 fixes the
problem by letting the user disable the workaround.
mga= [HW,DRM]
mousedev.tap_time=
@ -1119,6 +1175,10 @@ and is between 256 and 4096 characters. It is defined in the file
of returning the full 64-bit number.
The default is to return 64-bit inode numbers.
nmi_debug= [KNL,AVR32] Specify one or more actions to take
when a NMI is triggered.
Format: [state][,regs][,debounce][,die]
nmi_watchdog= [KNL,BUGS=X86-32] Debugging features for SMP kernels
no387 [BUGS=X86-32] Tells the kernel to use the 387 maths
@ -1143,6 +1203,8 @@ and is between 256 and 4096 characters. It is defined in the file
nodisconnect [HW,SCSI,M68K] Disables SCSI disconnects.
noefi [X86-32,X86-64] Disable EFI runtime services support.
noexec [IA-64]
noexec [X86-32,X86-64]
@ -1153,6 +1215,8 @@ and is between 256 and 4096 characters. It is defined in the file
register save and restore. The kernel will only save
legacy floating-point registers on task switch.
noclflush [BUGS=X86] Don't use the CLFLUSH instruction
nohlt [BUGS=ARM]
no-hlt [BUGS=X86-32] Tells the kernel that the hlt
@ -1589,7 +1653,13 @@ and is between 256 and 4096 characters. It is defined in the file
Format: <vendor>:<model>:<flags>
(flags are integer value)
scsi_logging= [SCSI]
scsi_logging_level= [SCSI] a bit mask of logging levels
See drivers/scsi/scsi_logging.h for bits. Also
settable via sysctl at dev.scsi.logging_level
(/proc/sys/dev/scsi/logging_level).
There is also a nice 'scsi_logging_level' script in the
S390-tools package, available for download at
http://www-128.ibm.com/developerworks/linux/linux390/s390-tools-1.5.4.html
scsi_mod.scan= [SCSI] sync (default) scans SCSI busses as they are
discovered. async scans them in kernel threads,
@ -1956,6 +2026,11 @@ and is between 256 and 4096 characters. It is defined in the file
vdso=1: enable VDSO (default)
vdso=0: disable VDSO mapping
vdso32= [X86-32,X86-64]
vdso32=2: enable compat VDSO (default with COMPAT_VDSO)
vdso32=1: enable 32-bit VDSO (default)
vdso32=0: disable 32-bit VDSO mapping
vector= [IA-64,SMP]
vector=percpu: enable percpu vector domain

144
Documentation/ko_KR/HOWTO
View File

@ -1,6 +1,6 @@
NOTE:
This is a version of Documentation/HOWTO translated into korean
This document is maintained by minchan Kim < minchan.kim@gmail.com>
This document is maintained by minchan Kim <minchan.kim@gmail.com>
If you find any difference between this document and the original file or
a problem with the translation, please contact the maintainer of this file.
@ -14,7 +14,7 @@ try to update the original English file first.
Documentation/HOWTO
의 한글 번역입니다.
역자： 김민찬 <minchan.kim@gmail.com >
역자： 김민찬 <minchan.kim@gmail.com>
감수： 이제이미 <jamee.lee@samsung.com>
==================================
@ -23,11 +23,11 @@ Documentation/HOWTO
이 문서는 커널 개발에 있어 가장 중요한 문서이다. 이 문서는
리눅스 커널 개발자가 되는 법과 리눅스 커널 개발 커뮤니티와 일하는
법을 담고있다. 커널 프로그래밍의기술적인 측면과 관련된 내용들은
포함하지 않으려고 하였지만 올바으로 여러분을 안내하는 데 도움이
법을 담고있다. 커널 프로그래밍의 기술적인 측면과 관련된 내용들은
포함하지 않으려고 하였지만 올바른 길로 여러분을 안내하는 데는 도움이
될 것이다.
이 문서에서 오래된 것을 발견하면 문서의 아래쪽에 나열된 메인트너에게
이 문서에서 오래된 것을 발견하면 문서의 아래쪽에 나열된 메인테이너에게
패치를 보내달라.
@ -36,12 +36,12 @@ Documentation/HOWTO
자, 여러분은 리눅스 커널 개발자가 되는 법을 배우고 싶은가? 아니면
상사로부터"이 장치를 위한 리눅스 드라이버를 작성하시오"라는 말을
들었는가? 이 문서는 여러분이 겪게 될 과정과 커뮤니티와 일하는 법을
조언하여 여러분의 목적을 달성하기 위해 필요한 것 모두를 알려주는
것이다.
들었는가? 이 문서의 목적은 여러분이 겪게 될 과정과 커뮤니티와 협력하는
법을 조언하여 여러분의 목적을 달성하기 위해 필요한 것 모두를 알려주기
위함이다.
커널은 대부분은 C로 작성되었어고 몇몇 아키텍쳐의 의존적인 부분은
어셈블리로 작성되었다. 커널 개발을 위해 C를 잘 이해하고 있어야 한다.
커널은 대부분은 C로 작성되어 있고 몇몇 아키텍쳐의 의존적인 부분은
어셈블리로 작성되어 있다. 커널 개발을 위해 C를 잘 이해하고 있어야 한다.
여러분이 특정 아키텍쳐의 low-level 개발을 할 것이 아니라면
어셈블리(특정 아키텍쳐)는 잘 알아야 할 필요는 없다.
다음의 참고서적들은 기본에 충실한 C 교육이나 수년간의 경험에 견주지는
@ -59,11 +59,11 @@ Documentation/HOWTO
어떤 참고문서도 있지 않다. 정보를 얻기 위해서는 gcc info (`info gcc`)페이지를
살펴보라.
여러분은 기존의 개발 커뮤니티와 일하는 법을 배우려고 하고 있다는 것을
기억하라. 코딩, 스타일, 절차에 관한 훌륭한 표준을 가진 사람들이 모인
여러분은 기존의 개발 커뮤니티와 협력하는 법을 배우려고 하고 있다는 것을
기억하라. 코딩, 스타일, 함수에 관한 훌륭한 표준을 가진 사람들이 모인
다양한 그룹이 있다. 이 표준들은 오랜동안 크고 지역적으로 분산된 팀들에
의해 가장 좋은 방법으로 일하기위하여 찾은 것을 기초로 만들어져왔다.
그 표준들은 문서화가 잘 되어 있기 때문에 가능한한 미리 많은 표준들에
의해 가장 좋은 방법으로 일하기 위하여 찾은 것을 기초로 만들어져 왔다.
그 표준들은 문서화가 잘 되어있기 때문에 가능한한 미리 많은 표준들에
관하여 배우려고 시도하라. 다른 사람들은 여러분이나 여러분의 회사가
일하는 방식에 적응하는 것을 원하지는 않는다.
@ -73,7 +73,7 @@ Documentation/HOWTO
리눅스 커널 소스 코드는 GPL로 배포(release)되었다. 소스트리의 메인
디렉토리에 있는 라이센스에 관하여 상세하게 쓰여 있는 COPYING이라는
파일을 봐라.여러분이 라이센스에 관한 더 깊은 문제를 가지고 있다면
파일을 봐라. 여러분이 라이센스에 관한 더 깊은 문제를 가지고 있다면
리눅스 커널 메일링 리스트에 묻지말고 변호사와 연락하라. 메일링
리스트들에 있는 사람들은 변호사가 아니기 때문에 법적 문제에 관하여
그들의 말에 의지해서는 안된다.
@ -85,12 +85,12 @@ GPL에 관한 잦은 질문들과 답변들은 다음을 참조하라.
문서
----
리눅스 커널 소스 트리는 커널 커뮤니티와 일하는 법을 배우기 위한 많은
귀중한 문서들을 가지고 있다. 새로운 기능들이 커널에 들어가게 될 때,
리눅스 커널 소스 트리는 커널 커뮤니티와 협력하는 법을 배우기위해 훌륭한
다양한 문서들을 가지고 있다. 새로운 기능들이 커널에 들어가게 될 때,
그 기능을 어떻게 사용하는지에 관한 설명을 위하여 새로운 문서 파일을
추가하는 것을 권장한다. 커널이 유저스페이스로 노출하는 인터페이스를
변경하게 되면 변경을 설명하는 메뉴얼 페이지들에 대한 패치나 정보를
mtk-manpages@gmx.net의 메인트너에게 보낼 것을 권장한다.
mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다.
다음은 커널 소스 트리에 있는 읽어야 할 파일들의 리스트이다.
README
@ -105,7 +105,7 @@ mtk-manpages@gmx.net의 메인트너에게 보낼 것을 권장한다.
Documentation/CodingStyle
이 문서는 리눅스 커널 코딩 스타일과 그렇게 한 몇몇 이유를 설명한다.
모든 새로운 코드는 이 문서에 가이드라인들을 따라야 한다. 대부분의
메인트너들은 이 규칙을 따르는 패치들만을 받아들일 것이고 많은 사람들이
메인테이너들은 이 규칙을 따르는 패치들만을 받아들일 것이고 많은 사람들이
그 패치가 올바른 스타일일 경우만 코드를 검토할 것이다.
Documentation/SubmittingPatches
@ -115,9 +115,10 @@ mtk-manpages@gmx.net의 메인트너에게 보낼 것을 권장한다.
- Email 내용들
- Email 양식
- 그것을 누구에게 보낼지
이러한 규칙들을 따르는 것이 성공을 보장하진 않는다(왜냐하면 모든
패치들은 내용과 스타일에 관하여 면밀히 검토되기 때문이다).
그러나 규칙을 따르지 않는다면 거의 성공하지도 못할 것이다.
이러한 규칙들을 따르는 것이 성공(역자주: 패치가 받아들여 지는 것)을
보장하진 않는다(왜냐하면 모든 패치들은 내용과 스타일에 관하여
면밀히 검토되기 때문이다). 그러나 규칙을 따르지 않는다면 거의
성공하지도 못할 것이다.
올바른 패치들을 만드는 법에 관한 훌륭한 다른 문서들이 있다.
"The Perfect Patch"
@ -126,13 +127,13 @@ mtk-manpages@gmx.net의 메인트너에게 보낼 것을 권장한다.
http://linux.yyz.us/patch-format.html
Documentation/stable_api_nonsense.txt
이 문서는 의도적으로 커널이 변하지 않는 API를 갖지 않도록 결정한
이 문서는 의도적으로 커널이 불변하는 API를 갖지 않도록 결정한
이유를 설명하며 다음과 같은 것들을 포함한다.
- 서브시스템 shim-layer(호환성을 위해?)
- 운영 체제들 간의 드라이버 이식성
- 운영체제들간의 드라이버 이식성
- 커널 소스 트리내에 빠른 변화를 늦추는 것(또는 빠른 변화를 막는 것)
이 문서는 리눅스 개발 철학을 이해하는데 필수적이며 다른 운영체제에서
리눅스로 옮겨오는 사람들에게는 매우 중요하다.
리눅스로 전향하는 사람들에게는 매우 중요하다.
Documentation/SecurityBugs
@ -141,10 +142,10 @@ mtk-manpages@gmx.net의 메인트너에게 보낼 것을 권장한다.
도와 달라.
Documentation/ManagementStyle
이 문서는 리눅스 커널 메인트너들이 어떻게 그들의 방법론의 정신을
어떻게 공유하고 운영하는지를 설명한다. 이것은 커널 개발에 입문하는
이 문서는 리눅스 커널 메인테이너들이 그들의 방법론에 녹아 있는
정신을 어떻게 공유하고 운영하는지를 설명한다. 이것은 커널 개발에 입문하는
모든 사람들(또는 커널 개발에 작은 호기심이라도 있는 사람들)이
읽어야 할 중요한 문서이다. 왜냐하면 이 문서는 커널 메인트너들의
읽어야 할 중요한 문서이다. 왜냐하면 이 문서는 커널 메인테이너들의
독특한 행동에 관하여 흔히 있는 오해들과 혼란들을 해소하고 있기
때문이다.
@ -160,7 +161,7 @@ mtk-manpages@gmx.net의 메인트너에게 보낼 것을 권장한다.
Documentation/applying-patches.txt
패치가 무엇이며 그것을 커널의 다른 개발 브랜치들에 어떻게
적용하는지에 관하여 자세히 설명 하고 있는 좋은 입문서이다.
적용하는지에 관하여 자세히 설명하고 있는 좋은 입문서이다.
커널은 소스 코드 그 자체에서 자동적으로 만들어질 수 있는 많은 문서들을
가지고 있다. 이것은 커널 내의 API에 대한 모든 설명, 그리고 락킹을
@ -192,7 +193,7 @@ Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, H
여러분이 어디서 시작해야 할진 모르지만 커널 개발 커뮤니티에 참여할 수
있는 일들을 찾길 원한다면 리눅스 커널 Janitor 프로젝트를 살펴봐라.
http://janitor.kernelnewbies.org/
그곳은 시작하기에 아주 딱 좋은 곳이다. 그곳은 리눅스 커널 소스 트리내에
그곳은 시작하기에 훌륭한 장소이다. 그곳은 리눅스 커널 소스 트리내에
간단히 정리되고 수정될 수 있는 문제들에 관하여 설명한다. 여러분은 이
프로젝트를 대표하는 개발자들과 일하면서 자신의 패치를 리눅스 커널 트리에
반영하기 위한 기본적인 것들을 배우게 될것이며 여러분이 아직 아이디어를
@ -212,7 +213,7 @@ Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, H
것은 Linux Cross-Reference project이며 그것은 자기 참조 방식이며
소스코드를 인덱스된 웹 페이지들의 형태로 보여준다. 최신의 멋진 커널
코드 저장소는 다음을 통하여 참조할 수 있다.
http://sosdg.org/~coywolf/lxr/
http://users.sosdg.org/~qiyong/lxr/
개발 프로세스
@ -233,44 +234,45 @@ Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, H
2.6.x 커널들은 Linux Torvalds가 관리하며 kernel.org의 pub/linux/kernel/v2.6/
디렉토리에서 참조될 수 있다.개발 프로세스는 다음과 같다.
- 새로운 커널이 배포되자마자 2주의 시간이 주어진다. 이 기간동은
메인트너들은 큰 diff들을 Linus에게 제출할 수 있다. 대개 이 패치들은
메인테이너들은 큰 diff들을 Linus에게 제출할 수 있다. 대개 이 패치들은
몇 주 동안 -mm 커널내에 이미 있었던 것들이다. 큰 변경들을 제출하는 데
선호되는 방법은 git(커널의 소스 관리 툴, 더 많은 정보들은 http://git.or.cz/
에서 참조할 수 있다)를 사용하는 것이지만 순수한 패치파일의 형식으로 보내도
에서 참조할 수 있다)를 사용하는 것이지만 순수한 패치파일의 형식으로 보내는
것도 무관하다.
- 2주 후에 -rc1 커널이 배포되며 지금부터는 전체 커널의 안정성에 영향을
미칠수 있는 새로운 기능들을 포함하지 않는 패치들만을 추가될 수 있다.
미칠수 있는 새로운 기능들을 포함하지 않는 패치들만이 추가될 수 있다.
완전히 새로운 드라이버(혹은 파일시스템)는 -rc1 이후에만 받아들여진다는
것을 기억해라. 왜냐하면 변경이 자체내에서만 발생하고 추가된 코드가
드라이버 외부의 다른 부분에는 영향을 주지 않으므로 그런 변경은
퇴보(regression)를 일으킬 만한 위험을 가지고 있지 않기 때문이다. -rc1이
회귀(역자주: 이전에는 존재하지 않았지만 새로운 기능추가나 변경으로 인해
생겨난 버그)를 일으킬 만한 위험을 가지고 있지 않기 때문이다. -rc1이
배포된 이후에 git를 사용하여 패치들을 Linus에게 보낼수 있지만 패치들은
공식적인 메일링 리스트로 보내서 검토를 받을 필요가 있다.
- 새로운 -rc는 Linus는 현재 git tree가 테스트 하기에 충분히 안정된 상태에
- 새로운 -rc는 Linus가 현재 git tree가 테스트 하기에 충분히 안정된 상태에
있다고 판단될 때마다 배포된다. 목표는 새로운 -rc 커널을 매주 배포하는
것이다.
- 이러한 프로세스는 커널이 "준비"되었다고 여겨질때까지 계속된다.
- 이러한 프로세스는 커널이 "준비(ready)"되었다고 여겨질때까지 계속된다.
프로세스는 대체로 6주간 지속된다.
- 각 -rc 배포에 있는 알려진 퇴보의 목록들은 다음 URI에 남겨진다.
- 각 -rc 배포에 있는 알려진 회귀의 목록들은 다음 URI에 남겨진다.
http://kernelnewbies.org/known_regressions
커널 배포에 있어서 언급할만한 가치가 있는 리눅스 커널 메일링 리스트의
Andrew Morton의 글이 있다.
"커널이 언제 배포될지는 아무로 모른다. 왜냐하면 배포는 알려진
"커널이 언제 배포될지는 아무도 모른다. 왜냐하면 배포는 알려진
버그의 상황에 따라 배포되는 것이지 미리정해 놓은 시간에 따라
배포되는 것은 아니기 때문이다."
배포되는 것은 아니기 때문이다."
2.6.x.y - 안정 커널 트리
------------------------
4 자리 숫자로 이루어진 버젼의 커널들은 -stable 커널들이다. 그것들은 2.6.x
커널에서 발견된 큰 퇴보들이나 보안 문제들 중 비교적 작고 중요한 수정들을
커널에서 발견된 큰 회귀들이나 보안 문제들 중 비교적 작고 중요한 수정들을
포함한다.
이것은 가장 최근의 안정적인 커널을 원하는 사용자에게 추천되는 브랜치이며,
개발/실험적 버젼을 테스트하는 것을 돕는데는 별로 관심이 없다.
개발/실험적 버젼을 테스트하는 것을 돕고자 하는 사용자들과는 별로 관련이 없다.
어떤 2.6.x.y 커널도 사용가능하지 않다면 그때는 가장 높은 숫자의 2.6.x
어떤 2.6.x.y 커널도 사용할 수 없다면 그때는 가장 높은 숫자의 2.6.x
커널이 현재의 안정 커널이다.
2.6.x.y는 "stable" 팀<stable@kernel.org>에 의해 관리되며 거의 매번 격주로
@ -294,7 +296,7 @@ Andrew Morton에 의해 배포된 실험적인 커널 패치들이다. Andrew는
서브시스템 커널 트리와 패치들을 가져와서 리눅스 커널 메일링 리스트로
온 많은 패치들과 한데 묶는다. 이 트리는 새로운 기능들과 패치들을 위한
장소를 제공하는 역할을 한다. 하나의 패치가 -mm에 한동안 있으면서 그 가치가
증명되게 되면 Andrew나 서브시스템 메인트너는 그것을 메인라인에 포함시키기
증명되게 되면 Andrew나 서브시스템 메인테이너는 그것을 메인라인에 포함시키기
위하여 Linus에게 보낸다.
커널 트리에 포함하고 싶은 모든 새로운 패치들은 Linus에게 보내지기 전에
@ -327,7 +329,7 @@ Andrew Morton에 의해 배포된 실험적인 커널 패치들이다. Andrew는
- ACPI development tree, Len Brown <len.brown@intel.com >
git.kernel.org:/pub/scm/linux/kernel/git/lenb/linux-acpi-2.6.git
- Block development tree, Jens Axboe <axboe@suse.de>
- Block development tree, Jens Axboe <jens.axboe@oracle.com>
git.kernel.org:/pub/scm/linux/kernel/git/axboe/linux-2.6-block.git
- DRM development tree, Dave Airlie <airlied@linux.ie>
@ -367,8 +369,8 @@ bugzilla.kernel.org는 리눅스 커널 개발자들이 커널의 버그를 추
kernel bugzilla를 사용하는 자세한 방법은 다음을 참조하라.
http://test.kernel.org/bugzilla/faq.html
메인 커널 소스 디렉토리에 있는 REPORTING-BUGS 파일은 커널 버그일 것 같은
것을 보고하는는 법에 관한 좋은 템플릿이고 문제를 추적하기 위해서 커널
메인 커널 소스 디렉토리에 있는 REPORTING-BUGS 파일은 커널 버그라고 생각되는
것을 보고하는 방법에 관한 좋은 템플릿이며 문제를 추적하기 위해서 커널
개발자들이 필요로 하는 정보가 무엇들인지를 상세히 설명하고 있다.
@ -383,7 +385,7 @@ kernel bugzilla를 사용하는 자세한 방법은 다음을 참조하라.
점수를 얻을 수 있는 가장 좋은 방법중의 하나이다. 왜냐하면 많은 사람들은
다른 사람들의 버그들을 수정하기 위하여 시간을 낭비하지 않기 때문이다.
이미 보고된 버그 리포트들을 가지고 작업하기 위해서 http://bugzilla.kernelorg를
이미 보고된 버그 리포트들을 가지고 작업하기 위해서 http://bugzilla.kernel.org를
참조하라. 여러분이 앞으로 생겨날 버그 리포트들의 조언자가 되길 원한다면
bugme-new 메일링 리스트나(새로운 버그 리포트들만이 이곳에서 메일로 전해진다)
bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메일로 전해진다)
@ -404,8 +406,8 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메
웹상의 많은 다른 곳에도 메일링 리스트의 아카이브들이 있다.
이러한 아카이브들을 찾으려면 검색 엔진을 사용하라. 예를 들어:
http://dir.gmane.org/gmane.linux.kernel
여러분이 새로운 문제에 관해 리스트에 올리기 전에 말하고 싶은 주제에 대한
것을 아카이브에서 먼저 찾기를 강력히 권장한다. 이미 상세하게 토론된 많은
여러분이 새로운 문제에 관해 리스트에 올리기 전에 말하고 싶은 주제에 관한
것을 아카이브에서 먼저 찾아보기를 강력히 권장한다. 이미 상세하게 토론된 많은
것들이 메일링 리스트의 아카이브에 기록되어 있다.
각각의 커널 서브시스템들의 대부분은 자신들의 개발에 관한 노력들로 이루어진
@ -443,7 +445,7 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메
무엇보다도 메일링 리스트의 다른 구독자들에게 보여주려 한다는 것을 기억하라.
커뮤니티와 일하는 법
커뮤니티와 협력하는 법
--------------------
커널 커뮤니티의 목적은 가능한한 가장 좋은 커널을 제공하는 것이다. 여러분이
@ -474,7 +476,7 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메
올바른 방향의 해결책으로 이끌어갈 의지가 있다면 받아들여질 것이라는 점을
기억하라.
여러분의 첫 패치에 여러분이 수정해야하는 십여개 정도의 회신이 오는
여러분의 첫 패치에 여러분이 수정해야하는 십여개 정도의 회신이 오는
경우도 흔하다. 이것은 여러분의 패치가 받아들여지지 않을 것이라는 것을
의미하는 것이 아니고 개인적으로 여러분에게 감정이 있어서 그러는 것도
아니다. 간단히 여러분의 패치에 제기된 문제들을 수정하고 그것을 다시
@ -486,12 +488,12 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메
커널 커뮤니티는 가장 전통적인 회사의 개발 환경과는 다르다. 여기에 여러분들의
문제를 피하기 위한 목록이 있다.
여러분들이 제안한 변경들에 관하여 말할 때 좋은 것들 :
- " 이것은 여러 문제들을 해겹합니다."
- "이것은 여러 문제들을 해겹합니다."
- "이것은 2000 라인의 코드를 제거합니다."
- "이것은 내가 말하려는 것에 관해 설명하는 패치입니다."
- "나는 5개의 다른 아키텍쳐에서 그것을 테스트했슴으로..."
- "여기에 일련의 작은 패치들이 있습음로..."
- "이것은 일반적인 머신에서 성능을 향상시키므로..."
- "여기에 일련의 작은 패치들이 있슴음로..."
- "이것은 일반적인 머신에서 성능을 향상시킴으로..."
여러분들이 말할 때 피해야 할 좋지 않은 것들 :
- "우리를 그것을 AIT/ptx/Solaris에서 이러한 방법으로 했다. 그러므로 그것은 좋은 것임에 틀립없다..."
@ -500,7 +502,7 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메
- "이것은 우리의 엔터프라이즈 상품 라인을 위한 것이다."
- "여기에 나의 생각을 말하고 있는 1000 페이지 설계 문서가 있다."
- "나는 6달동안 이것을 했으니..."
- "여기세 5000라인 짜리 패치가 있으니..."
- "여기에 5000라인 짜리 패치가 있으니..."
- "나는 현재 뒤죽박죽인 것을 재작성했다. 그리고 여기에..."
- "나는 마감시한을 가지고 있으므로 이 패치는 지금 적용될 필요가 있다."
@ -510,13 +512,13 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메
없다는 것이다. 리눅스 커널의 작업 환경에서는 단지 이메일 주소만
알수 있기 때문에 여성과 소수 민족들도 모두 받아들여진다. 국제적으로
일하게 되는 측면은 사람의 이름에 근거하여 성별을 추측할 수 없게
하기때문에 차별을 없애는 데 도움을 준다. Andrea라는 이름을 가진 남자와
하기때문에 차별을 없애는 데 도움을 준다. Andrea라는 이름을 가진 남자와
Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅스 커널에서
작업하며 생각을 표현해왔던 대부분의 여성들은 긍정적인 경험을 가지고
있다.
언어 장벽은 영어에 익숙하지 않은 몇몇 사람들에게 문제가 될 수도 있다.
언어의 훌륭한 구사는 메일링 리스트에서 올바르게 자신의 생각을
언어의 훌륭한 구사는 메일링 리스트에서 올바르게 자신의 생각을
표현하기 위하여 필요하다. 그래서 여러분은 이메일을 보내기 전에
영어를 올바르게 사용하고 있는지를 체크하는 것이 바람직하다.
@ -524,13 +526,13 @@ Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅
여러분의 변경을 나누어라
------------------------
리눅스 커널 커뮤니티는 한꺼번에 굉장히 큰 코드의 묶음을 쉽게
리눅스 커널 커뮤니티는 한꺼번에 굉장히 큰 코드의 묶음(chunk)을 쉽게
받아들이지 않는다. 변경은 적절하게 소개되고, 검토되고, 각각의
부분으로 작게 나누어져야 한다. 이것은 회사에서 하는 것과는 정확히
반대되는 것이다. 여러분들의 제안은 개발 초기에 일찍이 소개되야 한다.
그래서 여러분들은 자신이 하고 있는 것에 관하여 피드백을 받을 수 있게
된다. 커뮤니티가 여러분들이 커뮤니티와 함께 일하고 있다는 것을
느끼도록 만들고 커뮤니티가 여러분의 기능을 위한 쓰레기 장으로서
느끼도록 만들고 커뮤니티가 여러분의 기능을 위한 쓰레기 장으로써
사용되지 않고 있다는 것을 느끼게 하자. 그러나 메일링 리스트에 한번에
50개의 이메일을 보내지는 말아라. 여러분들의 일련의 패치들은 항상
더 작아야 한다.
@ -539,7 +541,7 @@ Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅
1) 작은 패치들은 여러분의 패치들이 적용될 수 있는 확률을 높여준다.
왜냐하면 다른 사람들은 정확성을 검증하기 위하여 많은 시간과 노력을
들이기를 원하지 않는다. 5줄의 패치는 메인트너가 거의 몇 초간 힐끗
들이기를 원하지 않는다. 5줄의 패치는 메인테이너가 거의 몇 초간 힐끗
보면 적용될 수 있다. 그러나 500 줄의 패치는 정확성을 검토하기 위하여
몇시간이 걸릴 수도 있다(걸리는 시간은 패치의 크기 혹은 다른 것에
비례하여 기하급수적으로 늘어난다).
@ -558,18 +560,18 @@ Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅
간결하고 가장 뛰어난 답을 보길 원한다. 훌륭한 학생은 이것을 알고
마지막으로 답을 얻기 전 중간 과정들을 제출하진 않는다.
커널 개발도 마찬가지이다. 메인트너들과 검토하는 사람들은 문제를
커널 개발도 마찬가지이다. 메인테이너들과 검토하는 사람들은 문제를
풀어나가는 과정속에 숨겨진 과정을 보길 원하진 않는다. 그들은
간결하고 멋진 답을 보길 원한다."
커뮤니티와 함께 일하며 뛰어난 답을 찾고 여러분들의 완성되지 않은 일들
사이에 균형을 유지해야 하는 어려움이 있을 수 있다. 그러므로 프로세스의
초반에 여러분의 일을 향상시키기위한 피드백을 얻는 것 뿐만 아니라
커뮤니티와 협력하며 뛰어난 답을 찾는 것과 여러분들의 끝마치지 못한 작업들
사이에 균형을 유지해야 하는 것은 어려울지도 모른다. 그러므로 프로세스의
초반에 여러분의 작업을 향상시키기위한 피드백을 얻는 것 뿐만 아니라
여러분들의 변경들을 작은 묶음으로 유지해서 심지어는 여러분의 작업의
모든 부분이 지금은 포함될 준비가 되어있지 않지만 작은 부분은 이미
모든 부분이 지금은 포함될 준비가 되어있지 않지만 작은 부분은 벌써
받아들여질 수 있도록 유지하는 것이 바람직하다.
또한 완성되지 않았고 "나중에 수정될 것이다." 와 같은 것들은 포함하는
또한 완성되지 않았고 "나중에 수정될 것이다." 와 같은 것들을 포함하는
패치들은 받아들여지지 않을 것이라는 점을 유념하라.
변경을 정당화해라
@ -577,7 +579,7 @@ Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅
여러분들의 나누어진 패치들을 리눅스 커뮤니티가 왜 반영해야 하는지를
알도록 하는 것은 매우 중요하다. 새로운 기능들이 필요하고 유용하다는
것은 반드시 그에 맞는 이유가 있어야 한다.
것은 반드시 그에 합당한 이유가 있어야 한다.
변경을 문서화해라
@ -588,7 +590,7 @@ Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅
것이다. 그리고 항상 그 내용을 보길 원하는 모든 사람들을 위해 보존될
것이다. 패치는 완벽하게 다음과 같은 내용들을 포함하여 설명해야 한다.
- 변경이 왜 필요한지
- 패치에 관한 전체 설계 어프로치
- 패치에 관한 전체 설계 접근(approach)
- 구현 상세들
- 테스트 결과들
@ -600,7 +602,7 @@ Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅
이 모든 것을 하는 것은 매우 어려운 일이다. 완벽히 소화하는 데는 적어도 몇년이
걸릴 수도 있다. 많은 인내와 결의가 필요한 계속되는 개선의 과정이다. 그러나
걸릴 수도 있다. 많은 인내와 결심이 필요한 계속되는 개선의 과정이다. 그러나
가능한한 포기하지 말라. 많은 사람들은 이전부터 해왔던 것이고 그 사람들도
정확하게 여러분들이 지금 서 있는 그 곳부터 시작했었다.
@ -620,4 +622,4 @@ David A. Wheeler, Junio Hamano, Michael Kerrisk, and Alex Shepard에게도 감
메인트너: Greg Kroah-Hartman <greg@kroah.com>
메인테이너: Greg Kroah-Hartman <greg@kroah.com>

195
Documentation/ko_KR/stable_api_nonsense.txt 100644
View File

@ -0,0 +1,195 @@
NOTE:
This is a version of Documentation/stable_api_nonsense.txt translated
into korean
This document is maintained by barrios <minchan.kim@gmail.com>
If you find any difference between this document and the original file or
a problem with the translation, please contact the maintainer of this file.
Please also note that the purpose of this file is to be easier to
read for non English (read: korean) speakers and is not intended as
a fork. So if you have any comments or updates for this file please
try to update the original English file first.
==================================
이 문서는
Documentation/stable_api_nonsense.txt
의 한글 번역입니다.
역자： 김민찬 <minchan.kim@gmail.com>
감수： 이제이미 <jamee.lee@samsung.com>
==================================
리눅스 커널 드라이버 인터페이스
(여러분들의 모든 질문에 대한 답 그리고 다른 몇가지)
Greg Kroah-Hartman <greg@kroah.com>
이 문서는 리눅스가 왜 바이너리 커널 인터페이스를 갖지 않는지, 왜 변하지
않는(stable) 커널 인터페이스를 갖지 않는지를 설명하기 위해 쓰여졌다.
이 문서는 커널과 유저공간 사이의 인터페이스가 아니라 커널 내부의
인터페이스들을 설명하고 있다는 것을 유념하라. 커널과 유저공간 사이의
인터페이스는 응용프로그램이 사용하는 syscall 인터페이스이다. 그 인터페이스는
오랫동안 거의 변하지 않았고 앞으로도 변하지 않을 것이다. 나는 pre 0.9에서
만들어졌지만 최신의 2.6 커널 배포에서도 잘 동작하는 프로그램을 가지고
있다. 이 인터페이스는 사용자와 응용프로그램 개발자들이 변하지 않을 것이라고
여길수 있는 것이다.
초록
----
여러분은 변하지 않는 커널 인터페이스를 원한다고 생각하지만 실제로는
그렇지 않으며 심지어는 그것을 알아채지 못한다. 여러분이 원하는 것은
안정되게 실행되는 드라이버이며 드라이버가 메인 커널 트리에 있을 때
그런 안정적인 드라이버를 얻을 수 있게 된다. 또한 여러분의 드라이버가
메인 커널 트리에 있다면 다른 많은 좋은 이점들을 얻게 된다. 그러한 것들이
리눅스를 강건하고, 안정적이며, 성숙한 운영체제로 만들어 놓음으로써
여러분들로 하여금 바로 리눅스를 사용하게 만드는 이유이다.
소개
----
커널 내부의 인터페이스가 바뀌는 것을 걱정하며 커널 드라이버를 작성하고
싶어하는 사람은 정말 이상한 사람이다. 세상의 대다수의 사람들은 이 인터페이스를
보지못할 것이며 전혀 걱정하지도 않는다.
먼저, 나는 closed 소스, hidden 소스, binary blobs, 소스 wrappers, 또는 GPL로
배포되었지만 소스 코드를 갖고 있지 않은 커널 드라이버들을 설명하는 어떤 다른
용어들에 관한 어떤 법적인 문제에 관해서는 언급하지 않을 것이다. 어떤 법적인
질문들을 가지고 있다면 변호사와 연락하라. 나는 프로그래머이므로 여기서 기술적인
문제들만을 설명하려고 한다. (법적인 문제를 경시하는 것은 아니다. 그런 문제들은
엄연히 현실에 있고 여러분들은 항상 그 문제들을 인식하고 있을 필요는 있다.)
자, 두가지의 주요 주제가 있다. 바이너리 커널 인터페이스들과 변하지 않는
커널 소스 인터페이들. 그것들은 서로 의존성을 가지고 있지만 바이너리
문제를 먼저 풀고 넘어갈 것이다.
바이너리 커널 인터페이스
------------------------
우리가 변하지 않는 커널 소스 인터페이스를 가지고 있다고 가정하자. 그러면
바이너리 인터페이스 또한 자연적으로 변하지 않을까? 틀렸다. 리눅스 커널에
관한 다음 사실들을 생각해보라.
- 여러분들이 사용하는 C 컴파일러의 버젼에 따라 다른 커널 자료 구조들은
다른 alignmnet들을 갖게 될것이고 다른 방법으로(함수들을 inline으로
했느냐, 아니냐) 다른 함수들을 포함하는 것도 가능한다. 중요한 것은
개별적인 함수 구성이 아니라 자료 구조 패딩이 달라진다는 점이다.
- 여러분이 선택한 커널 빌드 옵션에 따라서 커널은 다양한 것들을 가정할
수 있다.
- 다른 구조체들은 다른 필드들을 포함할 수 있다.
- 몇몇 함수들은 전혀 구현되지 않을 수도 있다(즉, 몇몇 lock들은
non-SMP 빌드에서는 사라져 버릴수도 있다).
- 커널내에 메모리는 build optoin들에 따라 다른 방법으로 align될수
있다.
- 리눅스는 많은 다양한 프로세서 아키텍쳐에서 실행된다. 한 아키텍쳐의
바이너리 드라이버를 다른 아키텍쳐에서 정상적으로 실행시킬 방법은
없다.
커널을 빌드했던 C 컴파일러와 정확하게 같은 것을 사용하고 정확하게 같은
커널 구성(configuration)을 사용하여 여러분들의 모듈을 빌드하면 간단히
많은 문제들을 해결할 수 있다. 이렇게 하는 것은 여러분들이 하나의 리눅스
배포판의 하나의 배포 버젼을 위한 모듈만을 제공한다면 별일 아닐 것이다.
그러나 각기 다른 리눅스 배포판마다 한번씩 빌드하는 수를 각 리눅스 배포판마다
제공하는 다른 릴리즈의 수와 곱하게 되면 이번에는 각 릴리즈들의 다른 빌드
옵션의 악몽과 마주하게 것이다. 또한 각 리눅스 배포판들은 다른 하드웨어
종류에(다른 프로세서 타입과 다른 옵션들) 맞춰져 있는 많은 다른 커널들을
배포한다. 그러므로 한번의 배포에서조차 여러분들의 모듈은 여러 버젼을
만들 필요가 있다.
나를 믿어라. 여러분들은 이러한 종류의 배포를 지원하려고 시도한다면 시간이
지나면 미칠지경이 될 것이다. 난 이러한 것을 오래전에 아주 어렵게 배웠다...
변하지않는 커널 소스 인터페이스들
---------------------------------
리눅스 커널 드라이버를 계속해서 메인 커널 트리에 반영하지 않고
유지보수하려고 하는 사름들과 이 문제를 논의하게 되면 훨씬 더
"논란의 여지가 많은" 주제가 될 것이다.
리눅스 커널 개발은 끊임없이 빠른 속도로 이루어지고 있으며 결코
느슨해진 적이 없다. 커널 개발자들이 현재 인터페이스들에서 버그를
발견하거나 무엇인가 할수 있는 더 좋은 방법을 찾게 되었다고 하자.
그들이 발견한 것을 실행한다면 아마도 더 잘 동작하도록 현재 인터페이스들을
수정하게 될 것이다. 그들이 그런 일을 하게되면 함수 이름들은 변하게 되고,
구조체들은 늘어나거나 줄어들게 되고, 함수 파라미터들은 재작업될 것이다.
이러한 일이 발생되면 커널 내에 이 인터페이스를 사용했던 인스턴스들이 동시에
수정될 것이며 이러한 과정은 모든 것이 계속해서 올바르게 동작할 것이라는
것을 보장한다.
이러한 것의 한 예로써, 커널 내부의 USB 인터페이스들은 이 서브시스템이
생긴 이후로 적어도 3번의 다른 재작업을 겪었다. 이 재작업들은 많은 다른
문제들을 풀었다.
- 데이터 스트림들의 동기적인 모델에서 비동기적인 모델로의 변화. 이것은
많은 드라이버들의 복잡성을 줄이고 처리량을 향상시켜 현재는 거의 모든
USB 장치들의 거의 최대 속도로 실행되고 있다.
- USB 드라이버가 USB 코어로부터 데이터 패킷들을 할당받로록 한 변경으로
인해서 지금의 모든 드라이버들은 많은 문서화된 데드락을 수정하기 위하여
USB 코어에게 더 많은 정보를 제공해야만 한다.
이것은 오랫동안 자신의 오래된 USB 인터페이스들을 유지해야 하는 closed 운영체제들과는
완전히 반대되는 것이다. closed된 운영체제들은 새로운 개발자들에게 우연히 낡은
인터페이스를 사용하게 할 기회를 주게되며, 적절하지 못한 방법으로 처리하게 되어
운영체제의 안정성을 해치는 문제를 야기하게 된다.
이 두가지의 예들 모두, 모든 개발자들은 꼭 이루어져야 하는 중요한 변화들이라고
동의를 하였고 비교적 적은 고통으로 변경되어졌다. 리눅스가 변하지 않는 소스
인터페이스를 고집한다면, 새로운 인터페이스가 만들어지게 되며 반면 기존의 오래된
것들, 그리고 깨진 것들은 계속해서 유지되어야 하며 이러한 일들은 USB 개발자들에게
또 다른 일거리를 주게 된다. 모든 리눅스 USB 개발자들에게 자신의 그들의 업무를
마친 후 시간을 투자하여 아무 득도 없는 무료 봉사를 해달라고 하는 것은 가능성이
희박한 일이다.
보안 문제 역시 리눅스에게는 매우 중요하다. 보안 문제가 발견되면 그것은
매우 짧은 시간 안에 수정된다. 보안 문제는 그 문제를 해결하기 위하여
여러번 내부 커널 인터페이스들을 재작업하게 만들었다. 이러한 문제가
발생하였을 때 그 인터페이스들을 사용하는 모든 드라이버들도 동시에
수정되어 보안 문제가 앞으로 갑작스럽게 생기지는 않을 것이라는 것을
보장한다. 내부 인터페이스들의 변경이 허락되지 않으면 이러한 종류의 보안
문제를 수정하고 그것이 다시 발생하지 않을 것이라고 보장하는 것은 가능하지
않을 것이다.
커널 인터페이스들은 계속해서 정리되고 있다. 현재 인터페이스를 사용하는
사람이 한명도 없다면 그것은 삭제된다. 이것은 커널이 가능한한 가장 작게
유지되며 존재하는 모든 가능성이 있는 인터페이스들이 테스트된다는 것을
보장한다(사용되지 않는 인터페이스들은 유효성 검증을 하기가 거의 불가능하다).
무엇을 해야 하나
---------------
자, 여러분이 메인 커널 트리에 있지 않은 리눅스 커널 드라이버를 가지고
있다면 여러분은 즉, 개발자는 무엇을 해야 하나? 모든 배포판마다 다른
커널 버젼을 위한 바이너리 드라이버를 배포하는 것은 악몽이며 계속해서
변하고 있는 커널 인터페이스들의 맞처 유지보수하려고 시도하는 것은 힘든
일이다.
간단하다. 여러분의 커널 드라이버를 메인 커널 트리에 반영하라(우리는 여기서
GPL을 따르는 배포 드라이버에 관해 얘기하고 있다는 것을 상기하라. 여러분의
코드가 이러한 분류에 해당되지 않는다면 행운을 빈다. 여러분 스스로 어떻게든
해야만 한다). 여러분의 드라이버가 트리에 있게되면 커널 인터페이스가
변경되더라도 가장 먼저 커널에 변경을 가했던 사람에 의해서 수정될 것이다.
이것은 여러분의 드라이버가 여러분의 별다른 노력없이 항상 빌드가 가능하며
동작하는 것을 보장한다.
메인 커널 트리에 여러분의 드라이버를 반영하면 얻게 되는 장점들은 다음과 같다.
- 관리의 드는 비용(원래 개발자의)은 줄어줄면서 드라이버의 질은 향상될 것이다.
- 다른 개발자들이 여러분의 드라이버에 기능들을 추가 할 것이다.
- 다른 사람들은 여러분의 드라이버에 버그를 발견하고 수정할 것이다.
- 다른 사람들은 여러분의 드라이버의 개선점을 찾을 줄 것이다.
- 외부 인터페이스 변경으로 인해 여러분의 드라이버의 수정이 필요하다면 다른
사람들이 드라이버를 업데이트할 것이다.
- 여러분의 드라이버는 별다른 노력 없이 모든 리눅스 배포판에 자동적으로
추가될 것이다.
리눅스는 다른 운영 체제보다 "쉽게 쓸수 있는(out of the box)" 많은 다른 장치들을
지원하고 어떤 다른 운영 체제보다 다양한 아키텍쳐위에서 이러한 장치들을 지원하기 때문에
이러한 증명된 개발 모델은 틀림없이 바로 가고 있는 것이다.
------
이 문서의 초안을 검토해주고 코멘트 해준 Randy Dunlap, Andrew Morton, David Brownell,
Hanna Linder, Robert Love, 그리고 Nishanth Aravamudan에게 감사한다.

573
Documentation/kobject.txt
View File

@ -1,289 +1,386 @@
The kobject Infrastructure
Everything you never wanted to know about kobjects, ksets, and ktypes
Patrick Mochel <mochel@osdl.org>
Greg Kroah-Hartman <gregkh@suse.de>
Updated: 3 June 2003
Based on an original article by Jon Corbet for lwn.net written October 1,
2003 and located at http://lwn.net/Articles/51437/
Last updated December 19, 2007
Copyright (c) 2003 Patrick Mochel
Copyright (c) 2003 Open Source Development Labs
Part of the difficulty in understanding the driver model - and the kobject
abstraction upon which it is built - is that there is no obvious starting
place. Dealing with kobjects requires understanding a few different types,
all of which make reference to each other. In an attempt to make things
easier, we'll take a multi-pass approach, starting with vague terms and
adding detail as we go. To that end, here are some quick definitions of
some terms we will be working with.
- A kobject is an object of type struct kobject. Kobjects have a name
and a reference count. A kobject also has a parent pointer (allowing
objects to be arranged into hierarchies), a specific type, and,
usually, a representation in the sysfs virtual filesystem.
Kobjects are generally not interesting on their own; instead, they are
usually embedded within some other structure which contains the stuff
the code is really interested in.
No structure should EVER have more than one kobject embedded within it.
If it does, the reference counting for the object is sure to be messed
up and incorrect, and your code will be buggy. So do not do this.
- A ktype is the type of object that embeds a kobject. Every structure
that embeds a kobject needs a corresponding ktype. The ktype controls
what happens to the kobject when it is created and destroyed.
- A kset is a group of kobjects. These kobjects can be of the same ktype
or belong to different ktypes. The kset is the basic container type for
collections of kobjects. Ksets contain their own kobjects, but you can
safely ignore that implementation detail as the kset core code handles
this kobject automatically.
When you see a sysfs directory full of other directories, generally each
of those directories corresponds to a kobject in the same kset.
We'll look at how to create and manipulate all of these types. A bottom-up
approach will be taken, so we'll go back to kobjects.
0. Introduction
Embedding kobjects
The kobject infrastructure performs basic object management that larger
data structures and subsystems can leverage, rather than reimplement
similar functionality. This functionality primarily concerns:
It is rare for kernel code to create a standalone kobject, with one major
exception explained below. Instead, kobjects are used to control access to
a larger, domain-specific object. To this end, kobjects will be found
embedded in other structures. If you are used to thinking of things in
object-oriented terms, kobjects can be seen as a top-level, abstract class
from which other classes are derived. A kobject implements a set of
capabilities which are not particularly useful by themselves, but which are
nice to have in other objects. The C language does not allow for the
direct expression of inheritance, so other techniques - such as structure
embedding - must be used.
- Object reference counting.
- Maintaining lists (sets) of objects.
- Object set locking.
- Userspace representation.
So, for example, the UIO code has a structure that defines the memory
region associated with a uio device:
The infrastructure consists of a number of object types to support
this functionality. Their programming interfaces are described below
in detail, and briefly here:
- kobjects a simple object.
- kset a set of objects of a certain type.
- ktype a set of helpers for objects of a common type.
The kobject infrastructure maintains a close relationship with the
sysfs filesystem. Each kobject that is registered with the kobject
core receives a directory in sysfs. Attributes about the kobject can
then be exported. Please see Documentation/filesystems/sysfs.txt for
more information.
The kobject infrastructure provides a flexible programming interface,
and allows kobjects and ksets to be used without being registered
(i.e. with no sysfs representation). This is also described later.
1. kobjects
1.1 Description
struct kobject is a simple data type that provides a foundation for
more complex object types. It provides a set of basic fields that
almost all complex data types share. kobjects are intended to be
embedded in larger data structures and replace fields they duplicate.
1.2 Definition
struct kobject {
const char * k_name;
struct kref kref;
struct list_head entry;
struct kobject * parent;
struct kset * kset;
struct kobj_type * ktype;
struct sysfs_dirent * sd;
wait_queue_head_t poll;
struct uio_mem {
struct kobject kobj;
unsigned long addr;
unsigned long size;
int memtype;
void __iomem *internal_addr;
};
void kobject_init(struct kobject *);
int kobject_add(struct kobject *);
int kobject_register(struct kobject *);
If you have a struct uio_mem structure, finding its embedded kobject is
just a matter of using the kobj member. Code that works with kobjects will
often have the opposite problem, however: given a struct kobject pointer,
what is the pointer to the containing structure? You must avoid tricks
(such as assuming that the kobject is at the beginning of the structure)
and, instead, use the container_of() macro, found in <linux/kernel.h>:
void kobject_del(struct kobject *);
void kobject_unregister(struct kobject *);
container_of(pointer, type, member)
struct kobject * kobject_get(struct kobject *);
void kobject_put(struct kobject *);
where pointer is the pointer to the embedded kobject, type is the type of
the containing structure, and member is the name of the structure field to
which pointer points. The return value from container_of() is a pointer to
the given type. So, for example, a pointer "kp" to a struct kobject
embedded within a struct uio_mem could be converted to a pointer to the
containing uio_mem structure with:
struct uio_mem *u_mem = container_of(kp, struct uio_mem, kobj);
Programmers often define a simple macro for "back-casting" kobject pointers
to the containing type.
1.3 kobject Programming Interface
Initialization of kobjects
kobjects may be dynamically added and removed from the kobject core
using kobject_register() and kobject_unregister(). Registration
includes inserting the kobject in the list of its dominant kset and
creating a directory for it in sysfs.
Code which creates a kobject must, of course, initialize that object. Some
of the internal fields are setup with a (mandatory) call to kobject_init():
Alternatively, one may use a kobject without adding it to its kset's list
or exporting it via sysfs, by simply calling kobject_init(). An
initialized kobject may later be added to the object hierarchy by
calling kobject_add(). An initialized kobject may be used for
reference counting.
void kobject_init(struct kobject *kobj, struct kobj_type *ktype);
Note: calling kobject_init() then kobject_add() is functionally
equivalent to calling kobject_register().
The ktype is required for a kobject to be created properly, as every kobject
must have an associated kobj_type. After calling kobject_init(), to
register the kobject with sysfs, the function kobject_add() must be called:
When a kobject is unregistered, it is removed from its kset's list,
removed from the sysfs filesystem, and its reference count is decremented.
List and sysfs removal happen in kobject_del(), and may be called
manually. kobject_put() decrements the reference count, and may also
be called manually.
int kobject_add(struct kobject *kobj, struct kobject *parent, const char *fmt, ...);
A kobject's reference count may be incremented with kobject_get(),
which returns a valid reference to a kobject; and decremented with
kobject_put(). An object's reference count may only be incremented if
it is already positive.
This sets up the parent of the kobject and the name for the kobject
properly. If the kobject is to be associated with a specific kset,
kobj->kset must be assigned before calling kobject_add(). If a kset is
associated with a kobject, then the parent for the kobject can be set to
NULL in the call to kobject_add() and then the kobject's parent will be the
kset itself.
When a kobject's reference count reaches 0, the method struct
kobj_type::release() (which the kobject's kset points to) is called.
This allows any memory allocated for the object to be freed.
As the name of the kobject is set when it is added to the kernel, the name
of the kobject should never be manipulated directly. If you must change
the name of the kobject, call kobject_rename():
int kobject_rename(struct kobject *kobj, const char *new_name);
There is a function called kobject_set_name() but that is legacy cruft and
is being removed. If your code needs to call this function, it is
incorrect and needs to be fixed.
To properly access the name of the kobject, use the function
kobject_name():
const char *kobject_name(const struct kobject * kobj);
There is a helper function to both initialize and add the kobject to the
kernel at the same time, called supprisingly enough kobject_init_and_add():
int kobject_init_and_add(struct kobject *kobj, struct kobj_type *ktype,
struct kobject *parent, const char *fmt, ...);
The arguments are the same as the individual kobject_init() and
kobject_add() functions described above.
NOTE!!!
Uevents
It is _imperative_ that you supply a destructor for dynamically
allocated kobjects to free them if you are using kobject reference
counts. The reference count controls the lifetime of the object.
If it goes to 0, then it is assumed that the object will
be freed and cannot be used.
After a kobject has been registered with the kobject core, you need to
announce to the world that it has been created. This can be done with a
call to kobject_uevent():
More importantly, you must free the object there, and not immediately
after an unregister call. If someone else is referencing the object
(e.g. through a sysfs file), they will obtain a reference to the
object, assume it's valid and operate on it. If the object is
unregistered and freed in the meantime, the operation will then
reference freed memory and go boom.
int kobject_uevent(struct kobject *kobj, enum kobject_action action);
This can be prevented, in the simplest case, by defining a release
method and freeing the object from there only. Note that this will not
secure reference count/object management models that use a dual
reference count or do other wacky things with the reference count
(like the networking layer).
Use the KOBJ_ADD action for when the kobject is first added to the kernel.
This should be done only after any attributes or children of the kobject
have been initialized properly, as userspace will instantly start to look
for them when this call happens.
When the kobject is removed from the kernel (details on how to do that is
below), the uevent for KOBJ_REMOVE will be automatically created by the
kobject core, so the caller does not have to worry about doing that by
hand.
1.4 sysfs
Reference counts
Each kobject receives a directory in sysfs. This directory is created
under the kobject's parent directory.
One of the key functions of a kobject is to serve as a reference counter
for the object in which it is embedded. As long as references to the object
exist, the object (and the code which supports it) must continue to exist.
The low-level functions for manipulating a kobject's reference counts are:
If a kobject does not have a parent when it is registered, its parent
becomes its dominant kset.
struct kobject *kobject_get(struct kobject *kobj);
void kobject_put(struct kobject *kobj);
If a kobject does not have a parent nor a dominant kset, its directory
is created at the top-level of the sysfs partition.
A successful call to kobject_get() will increment the kobject's reference
counter and return the pointer to the kobject.
When a reference is released, the call to kobject_put() will decrement the
reference count and, possibly, free the object. Note that kobject_init()
sets the reference count to one, so the code which sets up the kobject will
need to do a kobject_put() eventually to release that reference.
Because kobjects are dynamic, they must not be declared statically or on
the stack, but instead, always allocated dynamically. Future versions of
the kernel will contain a run-time check for kobjects that are created
statically and will warn the developer of this improper usage.
If all that you want to use a kobject for is to provide a reference counter
for your structure, please use the struct kref instead; a kobject would be
overkill. For more information on how to use struct kref, please see the
file Documentation/kref.txt in the Linux kernel source tree.
Creating "simple" kobjects
Sometimes all that a developer wants is a way to create a simple directory
in the sysfs hierarchy, and not have to mess with the whole complication of
ksets, show and store functions, and other details. This is the one
exception where a single kobject should be created. To create such an
entry, use the function:
struct kobject *kobject_create_and_add(char *name, struct kobject *parent);
This function will create a kobject and place it in sysfs in the location
underneath the specified parent kobject. To create simple attributes
associated with this kobject, use:
int sysfs_create_file(struct kobject *kobj, struct attribute *attr);
or
int sysfs_create_group(struct kobject *kobj, struct attribute_group *grp);
Both types of attributes used here, with a kobject that has been created
with the kobject_create_and_add(), can be of type kobj_attribute, so no
special custom attribute is needed to be created.
See the example module, samples/kobject/kobject-example.c for an
implementation of a simple kobject and attributes.
2. ksets
ktypes and release methods
2.1 Description
One important thing still missing from the discussion is what happens to a
kobject when its reference count reaches zero. The code which created the
kobject generally does not know when that will happen; if it did, there
would be little point in using a kobject in the first place. Even
predictable object lifecycles become more complicated when sysfs is brought
in as other portions of the kernel can get a reference on any kobject that
is registered in the system.
A kset is a set of kobjects that are embedded in the same type.
The end result is that a structure protected by a kobject cannot be freed
before its reference count goes to zero. The reference count is not under
the direct control of the code which created the kobject. So that code must
be notified asynchronously whenever the last reference to one of its
kobjects goes away.
Once you registered your kobject via kobject_add(), you must never use
kfree() to free it directly. The only safe way is to use kobject_put(). It
is good practice to always use kobject_put() after kobject_init() to avoid
errors creeping in.
This notification is done through a kobject's release() method. Usually
such a method has a form like:
void my_object_release(struct kobject *kobj)
{
struct my_object *mine = container_of(kobj, struct my_object, kobj);
/* Perform any additional cleanup on this object, then... */
kfree(mine);
}
One important point cannot be overstated: every kobject must have a
release() method, and the kobject must persist (in a consistent state)
until that method is called. If these constraints are not met, the code is
flawed. Note that the kernel will warn you if you forget to provide a
release() method. Do not try to get rid of this warning by providing an
"empty" release function; you will be mocked mercilessly by the kobject
maintainer if you attempt this.
Note, the name of the kobject is available in the release function, but it
must NOT be changed within this callback. Otherwise there will be a memory
leak in the kobject core, which makes people unhappy.
Interestingly, the release() method is not stored in the kobject itself;
instead, it is associated with the ktype. So let us introduce struct
kobj_type:
struct kobj_type {
void (*release)(struct kobject *);
struct sysfs_ops *sysfs_ops;
struct attribute **default_attrs;
};
This structure is used to describe a particular type of kobject (or, more
correctly, of containing object). Every kobject needs to have an associated
kobj_type structure; a pointer to that structure must be specified when you
call kobject_init() or kobject_init_and_add().
The release field in struct kobj_type is, of course, a pointer to the
release() method for this type of kobject. The other two fields (sysfs_ops
and default_attrs) control how objects of this type are represented in
sysfs; they are beyond the scope of this document.
The default_attrs pointer is a list of default attributes that will be
automatically created for any kobject that is registered with this ktype.
struct kset {
struct kobj_type * ktype;
struct list_head list;
struct kobject kobj;
struct kset_uevent_ops * uevent_ops;
ksets
A kset is merely a collection of kobjects that want to be associated with
each other. There is no restriction that they be of the same ktype, but be
very careful if they are not.
A kset serves these functions:
- It serves as a bag containing a group of objects. A kset can be used by
the kernel to track "all block devices" or "all PCI device drivers."
- A kset is also a subdirectory in sysfs, where the associated kobjects
with the kset can show up. Every kset contains a kobject which can be
set up to be the parent of other kobjects; the top-level directories of
the sysfs hierarchy are constructed in this way.
- Ksets can support the "hotplugging" of kobjects and influence how
uevent events are reported to user space.
In object-oriented terms, "kset" is the top-level container class; ksets
contain their own kobject, but that kobject is managed by the kset code and
should not be manipulated by any other user.
A kset keeps its children in a standard kernel linked list. Kobjects point
back to their containing kset via their kset field. In almost all cases,
the kobjects belonging to a ket have that kset (or, strictly, its embedded
kobject) in their parent.
As a kset contains a kobject within it, it should always be dynamically
created and never declared statically or on the stack. To create a new
kset use:
struct kset *kset_create_and_add(const char *name,
struct kset_uevent_ops *u,
struct kobject *parent);
When you are finished with the kset, call:
void kset_unregister(struct kset *kset);
to destroy it.
An example of using a kset can be seen in the
samples/kobject/kset-example.c file in the kernel tree.
If a kset wishes to control the uevent operations of the kobjects
associated with it, it can use the struct kset_uevent_ops to handle it:
struct kset_uevent_ops {
int (*filter)(struct kset *kset, struct kobject *kobj);
const char *(*name)(struct kset *kset, struct kobject *kobj);
int (*uevent)(struct kset *kset, struct kobject *kobj,
struct kobj_uevent_env *env);
};
void kset_init(struct kset * k);
int kset_add(struct kset * k);
int kset_register(struct kset * k);
void kset_unregister(struct kset * k);
The filter function allows a kset to prevent a uevent from being emitted to
userspace for a specific kobject. If the function returns 0, the uevent
will not be emitted.
struct kset * kset_get(struct kset * k);
void kset_put(struct kset * k);
The name function will be called to override the default name of the kset
that the uevent sends to userspace. By default, the name will be the same
as the kset itself, but this function, if present, can override that name.
struct kobject * kset_find_obj(struct kset *, char *);
The uevent function will be called when the uevent is about to be sent to
userspace to allow more environment variables to be added to the uevent.
One might ask how, exactly, a kobject is added to a kset, given that no
functions which perform that function have been presented. The answer is
that this task is handled by kobject_add(). When a kobject is passed to
kobject_add(), its kset member should point to the kset to which the
kobject will belong. kobject_add() will handle the rest.
If the kobject belonging to a kset has no parent kobject set, it will be
added to the kset's directory. Not all members of a kset do necessarily
live in the kset directory. If an explicit parent kobject is assigned
before the kobject is added, the kobject is registered with the kset, but
added below the parent kobject.
The type that the kobjects are embedded in is described by the ktype
pointer.
Kobject removal
A kset contains a kobject itself, meaning that it may be registered in
the kobject hierarchy and exported via sysfs. More importantly, the
kset may be embedded in a larger data type, and may be part of another
kset (of that object type).
After a kobject has been registered with the kobject core successfully, it
must be cleaned up when the code is finished with it. To do that, call
kobject_put(). By doing this, the kobject core will automatically clean up
all of the memory allocated by this kobject. If a KOBJ_ADD uevent has been
sent for the object, a corresponding KOBJ_REMOVE uevent will be sent, and
any other sysfs housekeeping will be handled for the caller properly.
For example, a block device is an object (struct gendisk) that is
contained in a set of block devices. It may also contain a set of
partitions (struct hd_struct) that have been found on the device. The
following code snippet illustrates how to express this properly.
If you need to do a two-stage delete of the kobject (say you are not
allowed to sleep when you need to destroy the object), then call
kobject_del() which will unregister the kobject from sysfs. This makes the
kobject "invisible", but it is not cleaned up, and the reference count of
the object is still the same. At a later time call kobject_put() to finish
the cleanup of the memory associated with the kobject.
struct gendisk * disk;
...
disk->kset.kobj.kset = &block_kset;
disk->kset.ktype = &partition_ktype;
kset_register(&disk->kset);
- The kset that the disk's embedded object belongs to is the
block_kset, and is pointed to by disk->kset.kobj.kset.
- The type of objects on the disk's _subordinate_ list are partitions,
and is set in disk->kset.ktype.
- The kset is then registered, which handles initializing and adding
the embedded kobject to the hierarchy.
kobject_del() can be used to drop the reference to the parent object, if
circular references are constructed. It is valid in some cases, that a
parent objects references a child. Circular references _must_ be broken
with an explicit call to kobject_del(), so that a release functions will be
called, and the objects in the former circle release each other.
2.2 kset Programming Interface
All kset functions, except kset_find_obj(), eventually forward the
calls to their embedded kobjects after performing kset-specific
operations. ksets offer a similar programming model to kobjects: they
may be used after they are initialized, without registering them in
the hierarchy.
kset_find_obj() may be used to locate a kobject with a particular
name. The kobject, if found, is returned.
There are also some helper functions which names point to the formerly
existing "struct subsystem", whose functions have been taken over by
ksets.
decl_subsys(name,type,uevent_ops)
Declares a kset named '<name>_subsys' of type <type> with
uevent_ops <uevent_ops>. For example,
decl_subsys(devices, &ktype_device, &device_uevent_ops);
is equivalent to doing:
struct kset devices_subsys = {
.ktype = &ktype_devices,
.uevent_ops = &device_uevent_ops,
};
kobject_set_name(&devices_subsys, name);
The objects that are registered with a subsystem that use the
subsystem's default list must have their kset ptr set properly. These
objects may have embedded kobjects or ksets. The
following helper makes setting the kset easier:
kobj_set_kset_s(obj,subsys)
- Assumes that obj->kobj exists, and is a struct kobject.
- Sets the kset of that kobject to the kset <subsys>.
int subsystem_register(struct kset *s);
void subsystem_unregister(struct kset *s);
These are just wrappers around the respective kset_* functions.
2.3 sysfs
ksets are represented in sysfs when their embedded kobjects are
registered. They follow the same rules of parenting, with one
exception. If a kset does not have a parent, nor is its embedded
kobject part of another kset, the kset's parent becomes its dominant
subsystem.
If the kset does not have a parent, its directory is created at the
sysfs root. This should only happen when the kset registered is
embedded in a subsystem itself.
3. struct ktype
3.1. Description
struct kobj_type {
void (*release)(struct kobject *);
struct sysfs_ops * sysfs_ops;
struct attribute ** default_attrs;
};
Object types require specific functions for converting between the
generic object and the more complex type. struct kobj_type provides
the object-specific fields, which include:
- release: Called when the kobject's reference count reaches 0. This
should convert the object to the more complex type and free it.
- sysfs_ops: Provides conversion functions for sysfs access. Please
see the sysfs documentation for more information.
- default_attrs: Default attributes to be exported via sysfs when the
object is registered.Note that the last attribute has to be
initialized to NULL ! You can find a complete implementation
in block/genhd.c
Instances of struct kobj_type are not registered; only referenced by
the kset. A kobj_type may be referenced by an arbitrary number of
ksets, as there may be disparate sets of identical objects.
Example code to copy from
For a more complete example of using ksets and kobjects properly, see the
sample/kobject/kset-example.c code.

1
Documentation/kprobes.txt
View File

@ -141,6 +141,7 @@ architectures:
- ppc64
- ia64 (Does not support probes on instruction slot1.)
- sparc64 (Return probes not yet implemented.)
- arm
3. Configuring Kprobes

75
Documentation/lguest/lguest.c
View File

@ -62,8 +62,8 @@ typedef uint8_t u8;
#endif
/* We can have up to 256 pages for devices. */
#define DEVICE_PAGES 256
/* This fits nicely in a single 4096-byte page. */
#define VIRTQUEUE_NUM 127
/* This will occupy 2 pages: it must be a power of 2. */
#define VIRTQUEUE_NUM 128
/*L:120 verbose is both a global flag and a macro. The C preprocessor allows
* this, and although I wouldn't recommend it, it works quite nicely here. */
@ -79,6 +79,9 @@ static void *guest_base;
/* The maximum guest physical address allowed, and maximum possible. */
static unsigned long guest_limit, guest_max;
/* a per-cpu variable indicating whose vcpu is currently running */
static unsigned int __thread cpu_id;
/* This is our list of devices. */
struct device_list
{
@ -153,6 +156,9 @@ struct virtqueue
void (*handle_output)(int fd, struct virtqueue *me);
};
/* Remember the arguments to the program so we can "reboot" */
static char **main_args;
/* Since guest is UP and we don't run at the same time, we don't need barriers.
* But I include them in the code in case others copy it. */
#define wmb()
@ -554,7 +560,7 @@ static void wake_parent(int pipefd, int lguest_fd)
else
FD_CLR(-fd - 1, &devices.infds);
} else /* Send LHREQ_BREAK command. */
write(lguest_fd, args, sizeof(args));
pwrite(lguest_fd, args, sizeof(args), cpu_id);
}
}
@ -1036,16 +1042,22 @@ static void add_virtqueue(struct device *dev, unsigned int num_descs,
void *p;
/* First we need some pages for this virtqueue. */
pages = (vring_size(num_descs) + getpagesize() - 1) / getpagesize();
pages = (vring_size(num_descs, getpagesize()) + getpagesize() - 1)
/ getpagesize();
p = get_pages(pages);
/* Initialize the virtqueue */
vq->next = NULL;
vq->last_avail_idx = 0;
vq->dev = dev;
/* Initialize the configuration. */
vq->config.num = num_descs;
vq->config.irq = devices.next_irq++;
vq->config.pfn = to_guest_phys(p) / getpagesize();
/* Initialize the vring. */
vring_init(&vq->vring, num_descs, p);
vring_init(&vq->vring, num_descs, p, getpagesize());
/* Add the configuration information to this device's descriptor. */
add_desc_field(dev, VIRTIO_CONFIG_F_VIRTQUEUE,
@ -1056,9 +1068,6 @@ static void add_virtqueue(struct device *dev, unsigned int num_descs,
for (i = &dev->vq; *i; i = &(*i)->next);
*i = vq;
/* Link virtqueue back to device. */
vq->dev = dev;
/* Set the routine to call when the Guest does something to this
* virtqueue. */
vq->handle_output = handle_output;
@ -1092,6 +1101,7 @@ static struct device *new_device(const char *name, u16 type, int fd,
dev->desc = new_dev_desc(type);
dev->handle_input = handle_input;
dev->name = name;
dev->vq = NULL;
return dev;
}
@ -1342,7 +1352,7 @@ static bool service_io(struct device *dev)
if (out->type & VIRTIO_BLK_T_SCSI_CMD) {
fprintf(stderr, "Scsi commands unsupported\n");
in->status = VIRTIO_BLK_S_UNSUPP;
wlen = sizeof(in);
wlen = sizeof(*in);
} else if (out->type & VIRTIO_BLK_T_OUT) {
/* Write */
@ -1363,7 +1373,7 @@ static bool service_io(struct device *dev)
/* Die, bad Guest, die. */
errx(1, "Write past end %llu+%u", off, ret);
}
wlen = sizeof(in);
wlen = sizeof(*in);
in->status = (ret >= 0 ? VIRTIO_BLK_S_OK : VIRTIO_BLK_S_IOERR);
} else {
/* Read */
@ -1376,10 +1386,10 @@ static bool service_io(struct device *dev)
ret = readv(vblk->fd, iov+1, in_num-1);
verbose("READ from sector %llu: %i\n", out->sector, ret);
if (ret >= 0) {
wlen = sizeof(in) + ret;
wlen = sizeof(*in) + ret;
in->status = VIRTIO_BLK_S_OK;
} else {
wlen = sizeof(in);
wlen = sizeof(*in);
in->status = VIRTIO_BLK_S_IOERR;
}
}
@ -1485,7 +1495,9 @@ static void setup_block_file(const char *filename)
/* Create stack for thread and run it */
stack = malloc(32768);
if (clone(io_thread, stack + 32768, CLONE_VM, dev) == -1)
/* SIGCHLD - We dont "wait" for our cloned thread, so prevent it from
* becoming a zombie. */
if (clone(io_thread, stack + 32768, CLONE_VM | SIGCHLD, dev) == -1)
err(1, "Creating clone");
/* We don't need to keep the I/O thread's end of the pipes open. */
@ -1495,7 +1507,21 @@ static void setup_block_file(const char *filename)
verbose("device %u: virtblock %llu sectors\n",
devices.device_num, cap);
}
/* That's the end of device setup. */
/* That's the end of device setup. :*/
/* Reboot */
static void __attribute__((noreturn)) restart_guest(void)
{
unsigned int i;
/* Closing pipes causes the waker thread and io_threads to die, and
* closing /dev/lguest cleans up the Guest. Since we don't track all
* open fds, we simply close everything beyond stderr. */
for (i = 3; i < FD_SETSIZE; i++)
close(i);
execv(main_args[0], main_args);
err(1, "Could not exec %s", main_args[0]);
}
/*L:220 Finally we reach the core of the Launcher, which runs the Guest, serves
* its input and output, and finally, lays it to rest. */
@ -1507,7 +1533,8 @@ static void __attribute__((noreturn)) run_guest(int lguest_fd)
int readval;
/* We read from the /dev/lguest device to run the Guest. */
readval = read(lguest_fd, &notify_addr, sizeof(notify_addr));
readval = pread(lguest_fd, &notify_addr,
sizeof(notify_addr), cpu_id);
/* One unsigned long means the Guest did HCALL_NOTIFY */
if (readval == sizeof(notify_addr)) {
@ -1517,16 +1544,23 @@ static void __attribute__((noreturn)) run_guest(int lguest_fd)
/* ENOENT means the Guest died. Reading tells us why. */
} else if (errno == ENOENT) {
char reason[1024] = { 0 };
read(lguest_fd, reason, sizeof(reason)-1);
pread(lguest_fd, reason, sizeof(reason)-1, cpu_id);
errx(1, "%s", reason);
/* ERESTART means that we need to reboot the guest */
} else if (errno == ERESTART) {
restart_guest();
/* EAGAIN means the Waker wanted us to look at some input.
* Anything else means a bug or incompatible change. */
} else if (errno != EAGAIN)
err(1, "Running guest failed");
/* Only service input on thread for CPU 0. */
if (cpu_id != 0)
continue;
/* Service input, then unset the BREAK to release the Waker. */
handle_input(lguest_fd);
if (write(lguest_fd, args, sizeof(args)) < 0)
if (pwrite(lguest_fd, args, sizeof(args), cpu_id) < 0)
err(1, "Resetting break");
}
}
@ -1567,6 +1601,12 @@ int main(int argc, char *argv[])
/* If they specify an initrd file to load. */
const char *initrd_name = NULL;
/* Save the args: we "reboot" by execing ourselves again. */
main_args = argv;
/* We don't "wait" for the children, so prevent them from becoming
* zombies. */
signal(SIGCHLD, SIG_IGN);
/* First we initialize the device list. Since console and network
* device receive input from a file descriptor, we keep an fdset
* (infds) and the maximum fd number (max_infd) with the head of the
@ -1578,6 +1618,7 @@ int main(int argc, char *argv[])
devices.lastdev = &devices.dev;
devices.next_irq = 1;
cpu_id = 0;
/* We need to know how much memory so we can set up the device
* descriptor and memory pages for the devices as we parse the command
* line. So we quickly look through the arguments to find the amount

4
Documentation/lguest/lguest.txt
View File

@ -109,10 +109,6 @@ Running Lguest:
See http://linux-net.osdl.org/index.php/Bridge for general information
on how to get bridging working.
- You can also create an inter-guest network using
"--sharenet=<filename>": any two guests using the same file are on
the same network. This file is created if it does not exist.
There is a helpful mailing list at http://ozlabs.org/mailman/listinfo/lguest
Good luck!

60
Documentation/m68k/kernel-options.txt
View File

@ -867,66 +867,6 @@ controller and should be autodetected by the driver. An example is the
24 bit region which is specified by a mask of 0x00fffffe.
5.5) 53c7xx=
------------
Syntax: 53c7xx=<sub-options...>
These options affect the A4000T, A4091, WarpEngine, Blizzard 603e+,
and GForce 040/060 SCSI controllers on the Amiga, as well as the
builtin MVME 16x SCSI controller.
The <sub-options> is a comma-separated list of the sub-options listed
below.
5.5.1) nosync
-------------
Syntax: nosync:0
Disables sync negotiation for all devices. Any value after the
colon is acceptable (and has the same effect).
5.5.2) noasync
--------------
[OBSOLETE, REMOVED]
5.5.3) nodisconnect
-------------------
Syntax: nodisconnect:0
Disables SCSI disconnects. Any value after the colon is acceptable
(and has the same effect).
5.5.4) validids
---------------
Syntax: validids:0xNN
Specify which SCSI ids the driver should pay attention to. This is
a bitmask (i.e. to only pay attention to ID#4, you'd use 0x10).
Default is 0x7f (devices 0-6).
5.5.5) opthi
5.5.6) optlo
------------
Syntax: opthi:M,optlo:N
Specify options for "hostdata->options". The acceptable definitions
are listed in drivers/scsi/53c7xx.h; the 32 high bits should be in
opthi and the 32 low bits in optlo. They must be specified in the
order opthi=M,optlo=N.
5.5.7) next
-----------
No argument. Used to separate blocks of keywords when there's more
than one 53c7xx host adapter in the system.
/* Local Variables: */
/* mode: text */
/* End: */

6
Documentation/markers.txt
View File

@ -35,12 +35,14 @@ In order to use the macro trace_mark, you should include linux/marker.h.
And,
trace_mark(subsystem_event, "%d %s", someint, somestring);
trace_mark(subsystem_event, "myint %d mystring %s", someint, somestring);
Where :
- subsystem_event is an identifier unique to your event
- subsystem is the name of your subsystem.
- event is the name of the event to mark.
- "%d %s" is the formatted string for the serializer.
- "myint %d mystring %s" is the formatted string for the serializer. "myint" and
"mystring" are repectively the field names associated with the first and
second parameter.
- someint is an integer.
- somestring is a char pointer.

2
Documentation/mips/00-INDEX
View File

@ -2,5 +2,3 @@
- this file.
AU1xxx_IDE.README
- README for MIPS AU1XXX IDE driver.
GT64120.README
- README for dir with info on MIPS boards using GT-64120 or GT-64120A.

65
Documentation/mips/GT64120.README
View File

@ -1,65 +0,0 @@
README for arch/mips/gt64120 directory and subdirectories
Jun Sun, jsun@mvista.com or jsun@junsun.net
01/27, 2001
MOTIVATION
----------
Many MIPS boards share the same system controller (or CPU companian chip),
such as GT-64120. It is highly desirable to let these boards share
the same controller code instead of duplicating them.
This directory is meant to hold all MIPS boards that use GT-64120 or GT-64120A.
HOW TO ADD A BOARD
------------------
. Create a subdirectory include/asm/gt64120/<board>.
. Create a file called gt64120_dep.h under that directory.
. Modify include/asm/gt64120/gt64120.h file to include the new gt64120_dep.h
based on config options. The board-dep section is at the end of
include/asm/gt64120/gt64120.h file. There you can find all required
definitions include/asm/gt64120/<board>/gt64120_dep.h file must supply.
. Create a subdirectory arch/mips/gt64120/<board> directory to hold
board specific routines.
. The GT-64120 common code is supplied under arch/mips/gt64120/common directory.
It includes:
1) arch/mips/gt64120/pci.c -
common PCI routine, include the top-level pcibios_init()
2) arch/mips/gt64120/irq.c -
common IRQ routine, include the top-level do_IRQ()
[This part really belongs to arch/mips/kernel. jsun]
3) arch/mips/gt64120/gt_irq.c -
common IRQ routines for GT-64120 chip. Currently it only handles
the timer interrupt.
. Board-specific routines are supplied under arch/mips/gt64120/<board> dir.
1) arch/mips/gt64120/<board>/pci.c - it provides bus fixup routine
2) arch/mips/gt64120/<board>/irq.c - it provides enable/disable irqs
and board irq setup routine (irq_setup)
3) arch/mips/gt64120/<board>/int-handler.S -
The first-level interrupt dispatching routine.
4) a bunch of other "normal" stuff (setup, prom, dbg_io, reset, etc)
. Follow other "normal" procedure to modify configuration files, etc.
TO-DO LIST
----------
. Expand arch/mips/gt64120/gt_irq.c to handle all GT-64120 interrupts.
We probably need to introduce GT_IRQ_BASE in board-dep header file,
which is used the starting irq_nr for all GT irqs.
A function, gt64120_handle_irq(), will be added so that the first-level
irq dispatcher will call this function if it detects an interrupt
from GT-64120.
. More support for GT-64120 PCI features (2nd PCI bus, perhaps)

39
Documentation/namespaces/compatibility-list.txt 100644
View File

@ -0,0 +1,39 @@
Namespaces compatibility list
This document contains the information about the problems user
may have when creating tasks living in different namespaces.
Here's the summary. This matrix shows the known problems, that
occur when tasks share some namespace (the columns) while living
in different other namespaces (the rows):
UTS IPC VFS PID User Net
UTS X
IPC X 1
VFS X
PID 1 1 X
User 2 2 X
Net X
1. Both the IPC and the PID namespaces provide IDs to address
object inside the kernel. E.g. semaphore with IPCID or
process group with pid.
In both cases, tasks shouldn't try exposing this ID to some
other task living in a different namespace via a shared filesystem
or IPC shmem/message. The fact is that this ID is only valid
within the namespace it was obtained in and may refer to some
other object in another namespace.
2. Intentionally, two equal user IDs in different user namespaces
should not be equal from the VFS point of view. In other
words, user 10 in one user namespace shouldn't have the same
access permissions to files, belonging to user 10 in another
namespace.
The same is true for the IPC namespaces being shared - two users
from different user namespaces should not access the same IPC objects
even having equal UIDs.
But currently this is not so.

14
Documentation/networking/00-INDEX
View File

@ -4,8 +4,6 @@
- information on the 3Com EtherLink Plus (3c505) driver.
6pack.txt
- info on the 6pack protocol, an alternative to KISS for AX.25
Configurable
- info on some of the configurable network parameters
DLINK.txt
- info on the D-Link DE-600/DE-620 parallel port pocket adapters
PLIP.txt
@ -26,8 +24,8 @@ baycom.txt
- info on the driver for Baycom style amateur radio modems
bridge.txt
- where to get user space programs for ethernet bridging with Linux.
comx.txt
- info on drivers for COMX line of synchronous serial adapters.
can.txt
- documentation on CAN protocol family.
cops.txt
- info on the COPS LocalTalk Linux driver
cs89x0.txt
@ -78,22 +76,14 @@ ltpc.txt
- the Apple or Farallon LocalTalk PC card driver
multicast.txt
- Behaviour of cards under Multicast
ncsa-telnet
- notes on how NCSA telnet (DOS) breaks with MTU discovery enabled.
netdevices.txt
- info on network device driver functions exported to the kernel.
olympic.txt
- IBM PCI Pit/Pit-Phy/Olympic Token Ring driver info.
policy-routing.txt
- IP policy-based routing
pt.txt
- the Gracilis Packetwin AX.25 device driver
ray_cs.txt
- Raylink Wireless LAN card driver info.
routing.txt
- the new routing mechanism
shaper.txt
- info on the module that can shape/limit transmitted traffic.
sk98lin.txt
- Marvell Yukon Chipset / SysKonnect SK-98xx compliant Gigabit
Ethernet Adapter family driver info

3
Documentation/networking/3c505.txt
View File

@ -14,8 +14,7 @@ If no base address is given at boot time, the driver will autoprobe
ports 0x300, 0x280 and 0x310 (in that order). If no IRQ is given, the driver
will try to probe for it.
The driver can be used as a loadable module. See net-modules.txt for details
of the parameters it can take.
The driver can be used as a loadable module.
Theoretically, one instance of the driver can now run multiple cards,
in the standard way (when loading a module, say "modprobe 3c505

34
Documentation/networking/Configurable
View File

@ -1,34 +0,0 @@
There are a few network parameters that can be tuned to better match
the kernel to your system hardware and intended usage. The defaults
are usually a good choice for 99% of the people 99% of the time, but
you should be aware they do exist and can be changed.
The current list of parameters can be found in the files:
linux/net/TUNABLE
Documentation/networking/ip-sysctl.txt
Some of these are accessible via the sysctl interface, and many more are
scheduled to be added in this way. For example, some parameters related
to Address Resolution Protocol (ARP) are very easily viewed and altered.
# cat /proc/sys/net/ipv4/arp_timeout
6000
# echo 7000 > /proc/sys/net/ipv4/arp_timeout
# cat /proc/sys/net/ipv4/arp_timeout
7000
Others are already accessible via the related user space programs.
For example, MAX_WINDOW has a default of 32 k which is a good choice for
modern hardware, but if you have a slow (8 bit) Ethernet card and/or a slow
machine, then this will be far too big for the card to keep up with fast
machines transmitting on the same net, resulting in overruns and receive errors.
A value of about 4 k would be more appropriate, which can be set via:
# route add -net 192.168.3.0 window 4096
The remainder of these can only be presently changed by altering a #define
in the related header file. This means an edit and recompile cycle.
Paul Gortmaker 06/96

233
Documentation/networking/bonding.txt
View File

@ -1,7 +1,7 @@
Linux Ethernet Bonding Driver HOWTO
Latest update: 24 April 2006
Latest update: 12 November 2007
Initial release : Thomas Davis <tadavis at lbl.gov>
Corrections, HA extensions : 2000/10/03-15 :
@ -166,12 +166,17 @@ to use ifenslave.
2. Bonding Driver Options
=========================
Options for the bonding driver are supplied as parameters to
the bonding module at load time. They may be given as command line
arguments to the insmod or modprobe command, but are usually specified
in either the /etc/modules.conf or /etc/modprobe.conf configuration
file, or in a distro-specific configuration file (some of which are
detailed in the next section).
Options for the bonding driver are supplied as parameters to the
bonding module at load time, or are specified via sysfs.
Module options may be given as command line arguments to the
insmod or modprobe command, but are usually specified in either the
/etc/modules.conf or /etc/modprobe.conf configuration file, or in a
distro-specific configuration file (some of which are detailed in the next
section).
Details on bonding support for sysfs is provided in the
"Configuring Bonding Manually via Sysfs" section, below.
The available bonding driver parameters are listed below. If a
parameter is not specified the default value is used. When initially
@ -554,6 +559,30 @@ xmit_hash_policy
This algorithm is 802.3ad compliant.
layer2+3
This policy uses a combination of layer2 and layer3
protocol information to generate the hash.
Uses XOR of hardware MAC addresses and IP addresses to
generate the hash. The formula is
(((source IP XOR dest IP) AND 0xffff) XOR
( source MAC XOR destination MAC ))
modulo slave count
This algorithm will place all traffic to a particular
network peer on the same slave. For non-IP traffic,
the formula is the same as for the layer2 transmit
hash policy.
This policy is intended to provide a more balanced
distribution of traffic than layer2 alone, especially
in environments where a layer3 gateway device is
required to reach most destinations.
This algorithm is 802.3ad complient.
layer3+4
This policy uses upper layer protocol information,
@ -589,8 +618,9 @@ xmit_hash_policy
or may not tolerate this noncompliance.
The default value is layer2. This option was added in bonding
version 2.6.3. In earlier versions of bonding, this parameter does
not exist, and the layer2 policy is the only policy.
version 2.6.3. In earlier versions of bonding, this parameter
does not exist, and the layer2 policy is the only policy. The
layer2+3 value was added for bonding version 3.2.2.
3. Configuring Bonding Devices
@ -787,11 +817,13 @@ the system /etc/modules.conf or /etc/modprobe.conf configuration file.
3.2 Configuration with Initscripts Support
------------------------------------------
This section applies to distros using a version of initscripts
with bonding support, for example, Red Hat Linux 9 or Red Hat
Enterprise Linux version 3 or 4. On these systems, the network
initialization scripts have some knowledge of bonding, and can be
configured to control bonding devices.
This section applies to distros using a recent version of
initscripts with bonding support, for example, Red Hat Enterprise Linux
version 3 or later, Fedora, etc. On these systems, the network
initialization scripts have knowledge of bonding, and can be configured to
control bonding devices. Note that older versions of the initscripts
package have lower levels of support for bonding; this will be noted where
applicable.
These distros will not automatically load the network adapter
driver unless the ethX device is configured with an IP address.
@ -839,11 +871,31 @@ USERCTL=no
Be sure to change the networking specific lines (IPADDR,
NETMASK, NETWORK and BROADCAST) to match your network configuration.
Finally, it is necessary to edit /etc/modules.conf (or
/etc/modprobe.conf, depending upon your distro) to load the bonding
module with your desired options when the bond0 interface is brought
up. The following lines in /etc/modules.conf (or modprobe.conf) will
load the bonding module, and select its options:
For later versions of initscripts, such as that found with Fedora
7 and Red Hat Enterprise Linux version 5 (or later), it is possible, and,
indeed, preferable, to specify the bonding options in the ifcfg-bond0
file, e.g. a line of the format:
BONDING_OPTS="mode=active-backup arp_interval=60 arp_ip_target=+192.168.1.254"
will configure the bond with the specified options. The options
specified in BONDING_OPTS are identical to the bonding module parameters
except for the arp_ip_target field. Each target should be included as a
separate option and should be preceded by a '+' to indicate it should be
added to the list of queried targets, e.g.,
arp_ip_target=+192.168.1.1 arp_ip_target=+192.168.1.2
is the proper syntax to specify multiple targets. When specifying
options via BONDING_OPTS, it is not necessary to edit /etc/modules.conf or
/etc/modprobe.conf.
For older versions of initscripts that do not support
BONDING_OPTS, it is necessary to edit /etc/modules.conf (or
/etc/modprobe.conf, depending upon your distro) to load the bonding module
with your desired options when the bond0 interface is brought up. The
following lines in /etc/modules.conf (or modprobe.conf) will load the
bonding module, and select its options:
alias bond0 bonding
options bond0 mode=balance-alb miimon=100
@ -858,9 +910,10 @@ up and running.
3.2.1 Using DHCP with Initscripts
---------------------------------
Recent versions of initscripts (the version supplied with
Fedora Core 3 and Red Hat Enterprise Linux 4 is reported to work) do
have support for assigning IP information to bonding devices via DHCP.
Recent versions of initscripts (the versions supplied with Fedora
Core 3 and Red Hat Enterprise Linux 4, or later versions, are reported to
work) have support for assigning IP information to bonding devices via
DHCP.
To configure bonding for DHCP, configure it as described
above, except replace the line "BOOTPROTO=none" with "BOOTPROTO=dhcp"
@ -870,18 +923,14 @@ is case sensitive.
3.2.2 Configuring Multiple Bonds with Initscripts
-------------------------------------------------
At this writing, the initscripts package does not directly
support loading the bonding driver multiple times, so the process for
doing so is the same as described in the "Configuring Multiple Bonds
Manually" section, below.
NOTE: It has been observed that some Red Hat supplied kernels
are apparently unable to rename modules at load time (the "-o bond1"
part). Attempts to pass that option to modprobe will produce an
"Operation not permitted" error. This has been reported on some
Fedora Core kernels, and has been seen on RHEL 4 as well. On kernels
exhibiting this problem, it will be impossible to configure multiple
bonds with differing parameters.
Initscripts packages that are included with Fedora 7 and Red Hat
Enterprise Linux 5 support multiple bonding interfaces by simply
specifying the appropriate BONDING_OPTS= in ifcfg-bondX where X is the
number of the bond. This support requires sysfs support in the kernel,
and a bonding driver of version 3.0.0 or later. Other configurations may
not support this method for specifying multiple bonding interfaces; for
those instances, see the "Configuring Multiple Bonds Manually" section,
below.
3.3 Configuring Bonding Manually with Ifenslave
-----------------------------------------------
@ -952,15 +1001,58 @@ initialization scripts lack support for configuring multiple bonds.
options, you may wish to use the "max_bonds" module parameter,
documented above.
To create multiple bonding devices with differing options, it
is necessary to use bonding parameters exported by sysfs, documented
in the section below.
To create multiple bonding devices with differing options, it is
preferrable to use bonding parameters exported by sysfs, documented in the
section below.
For versions of bonding without sysfs support, the only means to
provide multiple instances of bonding with differing options is to load
the bonding driver multiple times. Note that current versions of the
sysconfig network initialization scripts handle this automatically; if
your distro uses these scripts, no special action is needed. See the
section Configuring Bonding Devices, above, if you're not sure about your
network initialization scripts.
To load multiple instances of the module, it is necessary to
specify a different name for each instance (the module loading system
requires that every loaded module, even multiple instances of the same
module, have a unique name). This is accomplished by supplying multiple
sets of bonding options in /etc/modprobe.conf, for example:
alias bond0 bonding
options bond0 -o bond0 mode=balance-rr miimon=100
alias bond1 bonding
options bond1 -o bond1 mode=balance-alb miimon=50
will load the bonding module two times. The first instance is
named "bond0" and creates the bond0 device in balance-rr mode with an
miimon of 100. The second instance is named "bond1" and creates the
bond1 device in balance-alb mode with an miimon of 50.
In some circumstances (typically with older distributions),
the above does not work, and the second bonding instance never sees
its options. In that case, the second options line can be substituted
as follows:
install bond1 /sbin/modprobe --ignore-install bonding -o bond1 \
mode=balance-alb miimon=50
This may be repeated any number of times, specifying a new and
unique name in place of bond1 for each subsequent instance.
It has been observed that some Red Hat supplied kernels are unable
to rename modules at load time (the "-o bond1" part). Attempts to pass
that option to modprobe will produce an "Operation not permitted" error.
This has been reported on some Fedora Core kernels, and has been seen on
RHEL 4 as well. On kernels exhibiting this problem, it will be impossible
to configure multiple bonds with differing parameters (as they are older
kernels, and also lack sysfs support).
3.4 Configuring Bonding Manually via Sysfs
------------------------------------------
Starting with version 3.0, Channel Bonding may be configured
Starting with version 3.0.0, Channel Bonding may be configured
via the sysfs interface. This interface allows dynamic configuration
of all bonds in the system without unloading the module. It also
allows for adding and removing bonds at runtime. Ifenslave is no
@ -1005,9 +1097,6 @@ To enslave interface eth0 to bond bond0:
To free slave eth0 from bond bond0:
# echo -eth0 > /sys/class/net/bond0/bonding/slaves
NOTE: The bond must be up before slaves can be added. All
slaves are freed when the interface is brought down.
When an interface is enslaved to a bond, symlinks between the
two are created in the sysfs filesystem. In this case, you would get
/sys/class/net/bond0/slave_eth0 pointing to /sys/class/net/eth0, and
@ -1597,6 +1686,15 @@ one for each switch in the network). This will insure that,
regardless of which switch is active, the ARP monitor has a suitable
target to query.
Note, also, that of late many switches now support a functionality
generally referred to as "trunk failover." This is a feature of the
switch that causes the link state of a particular switch port to be set
down (or up) when the state of another switch port goes down (or up).
It's purpose is to propogate link failures from logically "exterior" ports
to the logically "interior" ports that bonding is able to monitor via
miimon. Availability and configuration for trunk failover varies by
switch, but this can be a viable alternative to the ARP monitor when using
suitable switches.
12. Configuring Bonding for Maximum Throughput
==============================================
@ -1684,7 +1782,7 @@ balance-rr: This mode is the only mode that will permit a single
interfaces. It is therefore the only mode that will allow a
single TCP/IP stream to utilize more than one interface's
worth of throughput. This comes at a cost, however: the
striping often results in peer systems receiving packets out
striping generally results in peer systems receiving packets out
of order, causing TCP/IP's congestion control system to kick
in, often by retransmitting segments.
@ -1696,22 +1794,20 @@ balance-rr: This mode is the only mode that will permit a single
interface's worth of throughput, even after adjusting
tcp_reordering.
Note that this out of order delivery occurs when both the
sending and receiving systems are utilizing a multiple
interface bond. Consider a configuration in which a
balance-rr bond feeds into a single higher capacity network
channel (e.g., multiple 100Mb/sec ethernets feeding a single
gigabit ethernet via an etherchannel capable switch). In this
configuration, traffic sent from the multiple 100Mb devices to
a destination connected to the gigabit device will not see
packets out of order. However, traffic sent from the gigabit
device to the multiple 100Mb devices may or may not see
traffic out of order, depending upon the balance policy of the
switch. Many switches do not support any modes that stripe
traffic (instead choosing a port based upon IP or MAC level
addresses); for those devices, traffic flowing from the
gigabit device to the many 100Mb devices will only utilize one
interface.
Note that the fraction of packets that will be delivered out of
order is highly variable, and is unlikely to be zero. The level
of reordering depends upon a variety of factors, including the
networking interfaces, the switch, and the topology of the
configuration. Speaking in general terms, higher speed network
cards produce more reordering (due to factors such as packet
coalescing), and a "many to many" topology will reorder at a
higher rate than a "many slow to one fast" configuration.
Many switches do not support any modes that stripe traffic
(instead choosing a port based upon IP or MAC level addresses);
for those devices, traffic for a particular connection flowing
through the switch to a balance-rr bond will not utilize greater
than one interface's worth of bandwidth.
If you are utilizing protocols other than TCP/IP, UDP for
example, and your application can tolerate out of order
@ -1911,6 +2007,10 @@ Failover may be delayed via the downdelay bonding module option.
13.2 Duplicated Incoming Packets
--------------------------------
NOTE: Starting with version 3.0.2, the bonding driver has logic to
suppress duplicate packets, which should largely eliminate this problem.
The following description is kept for reference.
It is not uncommon to observe a short burst of duplicated
traffic when the bonding device is first used, or after it has been
idle for some period of time. This is most easily observed by issuing
@ -2071,6 +2171,9 @@ The new driver was designed to be SMP safe from the start.
EtherExpress PRO/100 and a 3com 3c905b, for example). For most modes,
devices need not be of the same speed.
Starting with version 3.2.1, bonding also supports Infiniband
slaves in active-backup mode.
3. How many bonding devices can I have?
There is no limit.
@ -2129,11 +2232,15 @@ switches currently available support 802.3ad.
8. Where does a bonding device get its MAC address from?
If not explicitly configured (with ifconfig or ip link), the
MAC address of the bonding device is taken from its first slave
device. This MAC address is then passed to all following slaves and
remains persistent (even if the first slave is removed) until the
bonding device is brought down or reconfigured.
When using slave devices that have fixed MAC addresses, or when
the fail_over_mac option is enabled, the bonding device's MAC address is
the MAC address of the active slave.
For other configurations, if not explicitly configured (with
ifconfig or ip link), the MAC address of the bonding device is taken from
its first slave device. This MAC address is then passed to all following
slaves and remains persistent (even if the first slave is removed) until
the bonding device is brought down or reconfigured.
If you wish to change the MAC address, you can set it with
ifconfig or ip link:

629
Documentation/networking/can.txt 100644
View File

@ -0,0 +1,629 @@
============================================================================
can.txt
Readme file for the Controller Area Network Protocol Family (aka Socket CAN)
This file contains
1 Overview / What is Socket CAN
2 Motivation / Why using the socket API
3 Socket CAN concept
3.1 receive lists
3.2 local loopback of sent frames
3.3 network security issues (capabilities)
3.4 network problem notifications
4 How to use Socket CAN
4.1 RAW protocol sockets with can_filters (SOCK_RAW)
4.1.1 RAW socket option CAN_RAW_FILTER
4.1.2 RAW socket option CAN_RAW_ERR_FILTER
4.1.3 RAW socket option CAN_RAW_LOOPBACK
4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS
4.2 Broadcast Manager protocol sockets (SOCK_DGRAM)
4.3 connected transport protocols (SOCK_SEQPACKET)
4.4 unconnected transport protocols (SOCK_DGRAM)
5 Socket CAN core module
5.1 can.ko module params
5.2 procfs content
5.3 writing own CAN protocol modules
6 CAN network drivers
6.1 general settings
6.2 local loopback of sent frames
6.3 CAN controller hardware filters
6.4 currently supported CAN hardware
6.5 todo
7 Credits
============================================================================
1. Overview / What is Socket CAN
--------------------------------
The socketcan package is an implementation of CAN protocols
(Controller Area Network) for Linux. CAN is a networking technology
which has widespread use in automation, embedded devices, and
automotive fields. While there have been other CAN implementations
for Linux based on character devices, Socket CAN uses the Berkeley
socket API, the Linux network stack and implements the CAN device
drivers as network interfaces. The CAN socket API has been designed
as similar as possible to the TCP/IP protocols to allow programmers,
familiar with network programming, to easily learn how to use CAN
sockets.
2. Motivation / Why using the socket API
----------------------------------------
There have been CAN implementations for Linux before Socket CAN so the
question arises, why we have started another project. Most existing
implementations come as a device driver for some CAN hardware, they
are based on character devices and provide comparatively little
functionality. Usually, there is only a hardware-specific device
driver which provides a character device interface to send and
receive raw CAN frames, directly to/from the controller hardware.
Queueing of frames and higher-level transport protocols like ISO-TP
have to be implemented in user space applications. Also, most
character-device implementations support only one single process to
open the device at a time, similar to a serial interface. Exchanging
the CAN controller requires employment of another device driver and
often the need for adaption of large parts of the application to the
new driver's API.
Socket CAN was designed to overcome all of these limitations. A new
protocol family has been implemented which provides a socket interface
to user space applications and which builds upon the Linux network
layer, so to use all of the provided queueing functionality. A device
driver for CAN controller hardware registers itself with the Linux
network layer as a network device, so that CAN frames from the
controller can be passed up to the network layer and on to the CAN
protocol family module and also vice-versa. Also, the protocol family
module provides an API for transport protocol modules to register, so
that any number of transport protocols can be loaded or unloaded
dynamically. In fact, the can core module alone does not provide any
protocol and cannot be used without loading at least one additional
protocol module. Multiple sockets can be opened at the same time,
on different or the same protocol module and they can listen/send
frames on different or the same CAN IDs. Several sockets listening on
the same interface for frames with the same CAN ID are all passed the
same received matching CAN frames. An application wishing to
communicate using a specific transport protocol, e.g. ISO-TP, just
selects that protocol when opening the socket, and then can read and
write application data byte streams, without having to deal with
CAN-IDs, frames, etc.
Similar functionality visible from user-space could be provided by a
character device, too, but this would lead to a technically inelegant
solution for a couple of reasons:
* Intricate usage. Instead of passing a protocol argument to
socket(2) and using bind(2) to select a CAN interface and CAN ID, an
application would have to do all these operations using ioctl(2)s.
* Code duplication. A character device cannot make use of the Linux
network queueing code, so all that code would have to be duplicated
for CAN networking.
* Abstraction. In most existing character-device implementations, the
hardware-specific device driver for a CAN controller directly
provides the character device for the application to work with.
This is at least very unusual in Unix systems for both, char and
block devices. For example you don't have a character device for a
certain UART of a serial interface, a certain sound chip in your
computer, a SCSI or IDE controller providing access to your hard
disk or tape streamer device. Instead, you have abstraction layers
which provide a unified character or block device interface to the
application on the one hand, and a interface for hardware-specific
device drivers on the other hand. These abstractions are provided
by subsystems like the tty layer, the audio subsystem or the SCSI
and IDE subsystems for the devices mentioned above.
The easiest way to implement a CAN device driver is as a character
device without such a (complete) abstraction layer, as is done by most
existing drivers. The right way, however, would be to add such a
layer with all the functionality like registering for certain CAN
IDs, supporting several open file descriptors and (de)multiplexing
CAN frames between them, (sophisticated) queueing of CAN frames, and
providing an API for device drivers to register with. However, then
it would be no more difficult, or may be even easier, to use the
networking framework provided by the Linux kernel, and this is what
Socket CAN does.
The use of the networking framework of the Linux kernel is just the
natural and most appropriate way to implement CAN for Linux.
3. Socket CAN concept
---------------------
As described in chapter 2 it is the main goal of Socket CAN to
provide a socket interface to user space applications which builds
upon the Linux network layer. In contrast to the commonly known
TCP/IP and ethernet networking, the CAN bus is a broadcast-only(!)
medium that has no MAC-layer addressing like ethernet. The CAN-identifier
(can_id) is used for arbitration on the CAN-bus. Therefore the CAN-IDs
have to be chosen uniquely on the bus. When designing a CAN-ECU
network the CAN-IDs are mapped to be sent by a specific ECU.
For this reason a CAN-ID can be treated best as a kind of source address.
3.1 receive lists
The network transparent access of multiple applications leads to the
problem that different applications may be interested in the same
CAN-IDs from the same CAN network interface. The Socket CAN core
module - which implements the protocol family CAN - provides several
high efficient receive lists for this reason. If e.g. a user space
application opens a CAN RAW socket, the raw protocol module itself
requests the (range of) CAN-IDs from the Socket CAN core that are
requested by the user. The subscription and unsubscription of
CAN-IDs can be done for specific CAN interfaces or for all(!) known
CAN interfaces with the can_rx_(un)register() functions provided to
CAN protocol modules by the SocketCAN core (see chapter 5).
To optimize the CPU usage at runtime the receive lists are split up
into several specific lists per device that match the requested
filter complexity for a given use-case.
3.2 local loopback of sent frames
As known from other networking concepts the data exchanging
applications may run on the same or different nodes without any
change (except for the according addressing information):
___ ___ ___ _______ ___
| _ | | _ | | _ | | _ _ | | _ |
||A|| ||B|| ||C|| ||A| |B|| ||C||
|___| |___| |___| |_______| |___|
| | | | |
-----------------(1)- CAN bus -(2)---------------
To ensure that application A receives the same information in the
example (2) as it would receive in example (1) there is need for
some kind of local loopback of the sent CAN frames on the appropriate
node.
The Linux network devices (by default) just can handle the
transmission and reception of media dependent frames. Due to the
arbritration on the CAN bus the transmission of a low prio CAN-ID
may be delayed by the reception of a high prio CAN frame. To
reflect the correct* traffic on the node the loopback of the sent
data has to be performed right after a successful transmission. If
the CAN network interface is not capable of performing the loopback for
some reason the SocketCAN core can do this task as a fallback solution.
See chapter 6.2 for details (recommended).
The loopback functionality is enabled by default to reflect standard
networking behaviour for CAN applications. Due to some requests from
the RT-SocketCAN group the loopback optionally may be disabled for each
separate socket. See sockopts from the CAN RAW sockets in chapter 4.1.
* = you really like to have this when you're running analyser tools
like 'candump' or 'cansniffer' on the (same) node.
3.3 network security issues (capabilities)
The Controller Area Network is a local field bus transmitting only
broadcast messages without any routing and security concepts.
In the majority of cases the user application has to deal with
raw CAN frames. Therefore it might be reasonable NOT to restrict
the CAN access only to the user root, as known from other networks.
Since the currently implemented CAN_RAW and CAN_BCM sockets can only
send and receive frames to/from CAN interfaces it does not affect
security of others networks to allow all users to access the CAN.
To enable non-root users to access CAN_RAW and CAN_BCM protocol
sockets the Kconfig options CAN_RAW_USER and/or CAN_BCM_USER may be
selected at kernel compile time.
3.4 network problem notifications
The use of the CAN bus may lead to several problems on the physical
and media access control layer. Detecting and logging of these lower
layer problems is a vital requirement for CAN users to identify
hardware issues on the physical transceiver layer as well as
arbitration problems and error frames caused by the different
ECUs. The occurrence of detected errors are important for diagnosis
and have to be logged together with the exact timestamp. For this
reason the CAN interface driver can generate so called Error Frames
that can optionally be passed to the user application in the same
way as other CAN frames. Whenever an error on the physical layer
or the MAC layer is detected (e.g. by the CAN controller) the driver
creates an appropriate error frame. Error frames can be requested by
the user application using the common CAN filter mechanisms. Inside
this filter definition the (interested) type of errors may be
selected. The reception of error frames is disabled by default.
4. How to use Socket CAN
------------------------
Like TCP/IP, you first need to open a socket for communicating over a
CAN network. Since Socket CAN implements a new protocol family, you
need to pass PF_CAN as the first argument to the socket(2) system
call. Currently, there are two CAN protocols to choose from, the raw
socket protocol and the broadcast manager (BCM). So to open a socket,
you would write
s = socket(PF_CAN, SOCK_RAW, CAN_RAW);
and
s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM);
respectively. After the successful creation of the socket, you would
normally use the bind(2) system call to bind the socket to a CAN
interface (which is different from TCP/IP due to different addressing
- see chapter 3). After binding (CAN_RAW) or connecting (CAN_BCM)
the socket, you can read(2) and write(2) from/to the socket or use
send(2), sendto(2), sendmsg(2) and the recv* counterpart operations
on the socket as usual. There are also CAN specific socket options
described below.
The basic CAN frame structure and the sockaddr structure are defined
in include/linux/can.h:
struct can_frame {
canid_t can_id; /* 32 bit CAN_ID + EFF/RTR/ERR flags */
__u8 can_dlc; /* data length code: 0 .. 8 */
__u8 data[8] __attribute__((aligned(8)));
};
The alignment of the (linear) payload data[] to a 64bit boundary
allows the user to define own structs and unions to easily access the
CAN payload. There is no given byteorder on the CAN bus by
default. A read(2) system call on a CAN_RAW socket transfers a
struct can_frame to the user space.
The sockaddr_can structure has an interface index like the
PF_PACKET socket, that also binds to a specific interface:
struct sockaddr_can {
sa_family_t can_family;
int can_ifindex;
union {
struct { canid_t rx_id, tx_id; } tp16;
struct { canid_t rx_id, tx_id; } tp20;
struct { canid_t rx_id, tx_id; } mcnet;
struct { canid_t rx_id, tx_id; } isotp;
} can_addr;
};
To determine the interface index an appropriate ioctl() has to
be used (example for CAN_RAW sockets without error checking):
int s;
struct sockaddr_can addr;
struct ifreq ifr;
s = socket(PF_CAN, SOCK_RAW, CAN_RAW);
strcpy(ifr.ifr_name, "can0" );
ioctl(s, SIOCGIFINDEX, &ifr);
addr.can_family = AF_CAN;
addr.can_ifindex = ifr.ifr_ifindex;
bind(s, (struct sockaddr *)&addr, sizeof(addr));
(..)
To bind a socket to all(!) CAN interfaces the interface index must
be 0 (zero). In this case the socket receives CAN frames from every
enabled CAN interface. To determine the originating CAN interface
the system call recvfrom(2) may be used instead of read(2). To send
on a socket that is bound to 'any' interface sendto(2) is needed to
specify the outgoing interface.
Reading CAN frames from a bound CAN_RAW socket (see above) consists
of reading a struct can_frame:
struct can_frame frame;
nbytes = read(s, &frame, sizeof(struct can_frame));
if (nbytes < 0) {
perror("can raw socket read");
return 1;
}
/* paraniod check ... */
if (nbytes < sizeof(struct can_frame)) {
fprintf(stderr, "read: incomplete CAN frame\n");
return 1;
}
/* do something with the received CAN frame */
Writing CAN frames can be done similarly, with the write(2) system call:
nbytes = write(s, &frame, sizeof(struct can_frame));
When the CAN interface is bound to 'any' existing CAN interface
(addr.can_ifindex = 0) it is recommended to use recvfrom(2) if the
information about the originating CAN interface is needed:
struct sockaddr_can addr;
struct ifreq ifr;
socklen_t len = sizeof(addr);
struct can_frame frame;
nbytes = recvfrom(s, &frame, sizeof(struct can_frame),
0, (struct sockaddr*)&addr, &len);
/* get interface name of the received CAN frame */
ifr.ifr_ifindex = addr.can_ifindex;
ioctl(s, SIOCGIFNAME, &ifr);
printf("Received a CAN frame from interface %s", ifr.ifr_name);
To write CAN frames on sockets bound to 'any' CAN interface the
outgoing interface has to be defined certainly.
strcpy(ifr.ifr_name, "can0");
ioctl(s, SIOCGIFINDEX, &ifr);
addr.can_ifindex = ifr.ifr_ifindex;
addr.can_family = AF_CAN;
nbytes = sendto(s, &frame, sizeof(struct can_frame),
0, (struct sockaddr*)&addr, sizeof(addr));
4.1 RAW protocol sockets with can_filters (SOCK_RAW)
Using CAN_RAW sockets is extensively comparable to the commonly
known access to CAN character devices. To meet the new possibilities
provided by the multi user SocketCAN approach, some reasonable
defaults are set at RAW socket binding time:
- The filters are set to exactly one filter receiving everything
- The socket only receives valid data frames (=> no error frames)
- The loopback of sent CAN frames is enabled (see chapter 3.2)
- The socket does not receive its own sent frames (in loopback mode)
These default settings may be changed before or after binding the socket.
To use the referenced definitions of the socket options for CAN_RAW
sockets, include <linux/can/raw.h>.
4.1.1 RAW socket option CAN_RAW_FILTER
The reception of CAN frames using CAN_RAW sockets can be controlled
by defining 0 .. n filters with the CAN_RAW_FILTER socket option.
The CAN filter structure is defined in include/linux/can.h:
struct can_filter {
canid_t can_id;
canid_t can_mask;
};
A filter matches, when
<received_can_id> & mask == can_id & mask
which is analogous to known CAN controllers hardware filter semantics.
The filter can be inverted in this semantic, when the CAN_INV_FILTER
bit is set in can_id element of the can_filter structure. In
contrast to CAN controller hardware filters the user may set 0 .. n
receive filters for each open socket separately:
struct can_filter rfilter[2];
rfilter[0].can_id = 0x123;
rfilter[0].can_mask = CAN_SFF_MASK;
rfilter[1].can_id = 0x200;
rfilter[1].can_mask = 0x700;
setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, &rfilter, sizeof(rfilter));
To disable the reception of CAN frames on the selected CAN_RAW socket:
setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, NULL, 0);
To set the filters to zero filters is quite obsolete as not read
data causes the raw socket to discard the received CAN frames. But
having this 'send only' use-case we may remove the receive list in the
Kernel to save a little (really a very little!) CPU usage.
4.1.2 RAW socket option CAN_RAW_ERR_FILTER
As described in chapter 3.4 the CAN interface driver can generate so
called Error Frames that can optionally be passed to the user
application in the same way as other CAN frames. The possible
errors are divided into different error classes that may be filtered
using the appropriate error mask. To register for every possible
error condition CAN_ERR_MASK can be used as value for the error mask.
The values for the error mask are defined in linux/can/error.h .
can_err_mask_t err_mask = ( CAN_ERR_TX_TIMEOUT | CAN_ERR_BUSOFF );
setsockopt(s, SOL_CAN_RAW, CAN_RAW_ERR_FILTER,
&err_mask, sizeof(err_mask));
4.1.3 RAW socket option CAN_RAW_LOOPBACK
To meet multi user needs the local loopback is enabled by default
(see chapter 3.2 for details). But in some embedded use-cases
(e.g. when only one application uses the CAN bus) this loopback
functionality can be disabled (separately for each socket):
int loopback = 0; /* 0 = disabled, 1 = enabled (default) */
setsockopt(s, SOL_CAN_RAW, CAN_RAW_LOOPBACK, &loopback, sizeof(loopback));
4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS
When the local loopback is enabled, all the sent CAN frames are
looped back to the open CAN sockets that registered for the CAN
frames' CAN-ID on this given interface to meet the multi user
needs. The reception of the CAN frames on the same socket that was
sending the CAN frame is assumed to be unwanted and therefore
disabled by default. This default behaviour may be changed on
demand:
int recv_own_msgs = 1; /* 0 = disabled (default), 1 = enabled */
setsockopt(s, SOL_CAN_RAW, CAN_RAW_RECV_OWN_MSGS,
&recv_own_msgs, sizeof(recv_own_msgs));
4.2 Broadcast Manager protocol sockets (SOCK_DGRAM)
4.3 connected transport protocols (SOCK_SEQPACKET)
4.4 unconnected transport protocols (SOCK_DGRAM)
5. Socket CAN core module
-------------------------
The Socket CAN core module implements the protocol family
PF_CAN. CAN protocol modules are loaded by the core module at
runtime. The core module provides an interface for CAN protocol
modules to subscribe needed CAN IDs (see chapter 3.1).
5.1 can.ko module params
- stats_timer: To calculate the Socket CAN core statistics
(e.g. current/maximum frames per second) this 1 second timer is
invoked at can.ko module start time by default. This timer can be
disabled by using stattimer=0 on the module comandline.
- debug: (removed since SocketCAN SVN r546)
5.2 procfs content
As described in chapter 3.1 the Socket CAN core uses several filter
lists to deliver received CAN frames to CAN protocol modules. These
receive lists, their filters and the count of filter matches can be
checked in the appropriate receive list. All entries contain the
device and a protocol module identifier:
foo@bar:~$ cat /proc/net/can/rcvlist_all
receive list 'rx_all':
(vcan3: no entry)
(vcan2: no entry)
(vcan1: no entry)
device can_id can_mask function userdata matches ident
vcan0 000 00000000 f88e6370 f6c6f400 0 raw
(any: no entry)
In this example an application requests any CAN traffic from vcan0.
rcvlist_all - list for unfiltered entries (no filter operations)
rcvlist_eff - list for single extended frame (EFF) entries
rcvlist_err - list for error frames masks
rcvlist_fil - list for mask/value filters
rcvlist_inv - list for mask/value filters (inverse semantic)
rcvlist_sff - list for single standard frame (SFF) entries
Additional procfs files in /proc/net/can
stats - Socket CAN core statistics (rx/tx frames, match ratios, ...)
reset_stats - manual statistic reset
version - prints the Socket CAN core version and the ABI version
5.3 writing own CAN protocol modules
To implement a new protocol in the protocol family PF_CAN a new
protocol has to be defined in include/linux/can.h .
The prototypes and definitions to use the Socket CAN core can be
accessed by including include/linux/can/core.h .
In addition to functions that register the CAN protocol and the
CAN device notifier chain there are functions to subscribe CAN
frames received by CAN interfaces and to send CAN frames:
can_rx_register - subscribe CAN frames from a specific interface
can_rx_unregister - unsubscribe CAN frames from a specific interface
can_send - transmit a CAN frame (optional with local loopback)
For details see the kerneldoc documentation in net/can/af_can.c or
the source code of net/can/raw.c or net/can/bcm.c .
6. CAN network drivers
----------------------
Writing a CAN network device driver is much easier than writing a
CAN character device driver. Similar to other known network device
drivers you mainly have to deal with:
- TX: Put the CAN frame from the socket buffer to the CAN controller.
- RX: Put the CAN frame from the CAN controller to the socket buffer.
See e.g. at Documentation/networking/netdevices.txt . The differences
for writing CAN network device driver are described below:
6.1 general settings
dev->type = ARPHRD_CAN; /* the netdevice hardware type */
dev->flags = IFF_NOARP; /* CAN has no arp */
dev->mtu = sizeof(struct can_frame);
The struct can_frame is the payload of each socket buffer in the
protocol family PF_CAN.
6.2 local loopback of sent frames
As described in chapter 3.2 the CAN network device driver should
support a local loopback functionality similar to the local echo
e.g. of tty devices. In this case the driver flag IFF_ECHO has to be
set to prevent the PF_CAN core from locally echoing sent frames
(aka loopback) as fallback solution:
dev->flags = (IFF_NOARP | IFF_ECHO);
6.3 CAN controller hardware filters
To reduce the interrupt load on deep embedded systems some CAN
controllers support the filtering of CAN IDs or ranges of CAN IDs.
These hardware filter capabilities vary from controller to
controller and have to be identified as not feasible in a multi-user
networking approach. The use of the very controller specific
hardware filters could make sense in a very dedicated use-case, as a
filter on driver level would affect all users in the multi-user
system. The high efficient filter sets inside the PF_CAN core allow
to set different multiple filters for each socket separately.
Therefore the use of hardware filters goes to the category 'handmade
tuning on deep embedded systems'. The author is running a MPC603e
@133MHz with four SJA1000 CAN controllers from 2002 under heavy bus
load without any problems ...
6.4 currently supported CAN hardware (September 2007)
On the project website http://developer.berlios.de/projects/socketcan
there are different drivers available:
vcan: Virtual CAN interface driver (if no real hardware is available)
sja1000: Philips SJA1000 CAN controller (recommended)
i82527: Intel i82527 CAN controller
mscan: Motorola/Freescale CAN controller (e.g. inside SOC MPC5200)
ccan: CCAN controller core (e.g. inside SOC h7202)
slcan: For a bunch of CAN adaptors that are attached via a
serial line ASCII protocol (for serial / USB adaptors)
Additionally the different CAN adaptors (ISA/PCI/PCMCIA/USB/Parport)
from PEAK Systemtechnik support the CAN netdevice driver model
since Linux driver v6.0: http://www.peak-system.com/linux/index.htm
Please check the Mailing Lists on the berlios OSS project website.
6.5 todo (September 2007)
The configuration interface for CAN network drivers is still an open
issue that has not been finalized in the socketcan project. Also the
idea of having a library module (candev.ko) that holds functions
that are needed by all CAN netdevices is not ready to ship.
Your contribution is welcome.
7. Credits
----------
Oliver Hartkopp (PF_CAN core, filters, drivers, bcm)
Urs Thuermann (PF_CAN core, kernel integration, socket interfaces, raw, vcan)
Jan Kizka (RT-SocketCAN core, Socket-API reconciliation)
Wolfgang Grandegger (RT-SocketCAN core & drivers, Raw Socket-API reviews)
Robert Schwebel (design reviews, PTXdist integration)
Marc Kleine-Budde (design reviews, Kernel 2.6 cleanups, drivers)
Benedikt Spranger (reviews)
Thomas Gleixner (LKML reviews, coding style, posting hints)
Andrey Volkov (kernel subtree structure, ioctls, mscan driver)
Matthias Brukner (first SJA1000 CAN netdevice implementation Q2/2003)
Klaus Hitschler (PEAK driver integration)
Uwe Koppe (CAN netdevices with PF_PACKET approach)
Michael Schulze (driver layer loopback requirement, RT CAN drivers review)

248
Documentation/networking/comx.txt
View File

@ -1,248 +0,0 @@
COMX drivers for the 2.2 kernel
Originally written by: Tivadar Szemethy, <tiv@itc.hu>
Currently maintained by: Gergely Madarasz <gorgo@itc.hu>
Last change: 21/06/1999.
INTRODUCTION
This document describes the software drivers and their use for the
COMX line of synchronous serial adapters for Linux version 2.2.0 and
above.
The cards are produced and sold by ITC-Pro Ltd. Budapest, Hungary
For further info contact <info@itc.hu>
or http://www.itc.hu (mostly in Hungarian).
The firmware files and software are available from ftp://ftp.itc.hu
Currently, the drivers support the following cards and protocols:
COMX (2x64 kbps intelligent board)
CMX (1x256 + 1x128 kbps intelligent board)
HiCOMX (2x2Mbps intelligent board)
LoCOMX (1x512 kbps passive board)
MixCOM (1x512 or 2x512kbps passive board with a hardware watchdog an
optional BRI interface and optional flashROM (1-32M))
SliceCOM (1x2Mbps channelized E1 board)
PciCOM (X21)
At the moment of writing this document, the (Cisco)-HDLC, LAPB, SyncPPP and
Frame Relay (DTE, rfc1294 IP encapsulation with partially implemented Q933a
LMI) protocols are available as link-level protocol.
X.25 support is being worked on.
USAGE
Load the comx.o module and the hardware-specific and protocol-specific
modules you'll need into the running kernel using the insmod utility.
This creates the /proc/comx directory.
See the example scripts in the 'etc' directory.
/proc INTERFACE INTRO
The COMX driver set has a new type of user interface based on the /proc
filesystem which eliminates the need for external user-land software doing
IOCTL calls.
Each network interface or device (i.e. those ones you configure with 'ifconfig'
and 'route' etc.) has a corresponding directory under /proc/comx. You can
dynamically create a new interface by saying 'mkdir /proc/comx/comx0' (or you
can name it whatever you want up to 8 characters long, comx[n] is just a
convention).
Generally the files contained in these directories are text files, which can
be viewed by 'cat filename' and you can write a string to such a file by
saying 'echo _string_ >filename'. This is very similar to the sysctl interface.
Don't use a text editor to edit these files, always use 'echo' (or 'cat'
where appropriate).
When you've created the comx[n] directory, two files are created automagically
in it: 'boardtype' and 'protocol'. You have to fill in these files correctly
for your board and protocol you intend to use (see the board and protocol
descriptions in this file below or the example scripts in the 'etc' directory).
After filling in these files, other files will appear in the directory for
setting the various hardware- and protocol-related informations (for example
irq and io addresses, keepalive values etc.) These files are set to default
values upon creation, so you don't necessarily have to change all of them.
When you're ready with filling in the files in the comx[n] directory, you can
configure the corresponding network interface with the standard network
configuration utilities. If you're unable to bring the interfaces up, look up
the various kernel log files on your system, and consult the messages for
a probable reason.
EXAMPLE
To create the interface 'comx0' which is the first channel of a COMX card:
insmod comx
# insmod comx-hw-comx ; insmod comx-proto-ppp (these are usually
autoloaded if you use the kernel module loader)
mkdir /proc/comx/comx0
echo comx >/proc/comx/comx0/boardtype
echo 0x360 >/proc/comx/comx0/io <- jumper-selectable I/O port
echo 0x0a >/proc/comx/comx0/irq <- jumper-selectable IRQ line
echo 0xd000 >/proc/comx/comx0/memaddr <- software-configurable memory
address. COMX uses 64 KB, and this
can be: 0xa000, 0xb000, 0xc000,
0xd000, 0xe000. Avoid conflicts
with other hardware.
cat </etc/siol1.rom >/proc/comx/comx0/firmware <- the firmware for the card
echo HDLC >/proc/comx/comx0/protocol <- the data-link protocol
echo 10 >/proc/comx/comx0/keepalive <- the keepalive for the protocol
ifconfig comx0 1.2.3.4 pointopoint 5.6.7.8 netmask 255.255.255.255 <-
finally configure it with ifconfig
Check its status:
cat /proc/comx/comx0/status
If you want to use the second channel of this board:
mkdir /proc/comx/comx1
echo comx >/proc/comx/comx1/boardtype
echo 0x360 >/proc/comx/comx1/io
echo 10 >/proc/comx/comx1/irq
echo 0xd000 >/proc/comx/comx1/memaddr
echo 1 >/proc/comx/comx1/channel <- channels are numbered
as 0 (default) and 1
Now, check if the driver recognized that you're going to use the other
channel of the same adapter:
cat /proc/comx/comx0/twin
comx1
cat /proc/comx/comx1/twin
comx0
You don't have to load the firmware twice, if you use both channels of
an adapter, just write it into the channel 0's /proc firmware file.
Default values: io 0x360 for COMX, 0x320 (HICOMX), irq 10, memaddr 0xd0000
THE LOCOMX HARDWARE DRIVER
The LoCOMX driver doesn't require firmware, and it doesn't use memory either,
but it uses DMA channels 1 and 3. You can set the clock rate (if enabled by
jumpers on the board) by writing the kbps value into the file named 'clock'.
Set it to 'external' (it is the default) if you have external clock source.
(Note: currently the LoCOMX driver does not support the internal clock)
THE COMX, CMX AND HICOMX DRIVERS
On the HICOMX, COMX and CMX, you have to load the firmware (it is different for
the three cards!). All these adapters can share the same memory
address (we usually use 0xd0000). On the CMX you can set the internal
clock rate (if enabled by jumpers on the small adapter boards) by writing
the kbps value into the 'clock' file. You have to do this before initializing
the card. If you use both HICOMX and CMX/COMX cards, initialize the HICOMX
first. The I/O address of the HICOMX board is not configurable by any
method available to the user: it is hardwired to 0x320, and if you have to
change it, consult ITC-Pro Ltd.
THE MIXCOM DRIVER
The MixCOM board doesn't require firmware, the driver communicates with
it through I/O ports. You can have three of these cards in one machine.
THE SLICECOM DRIVER
The SliceCOM board doesn't require firmware. You can have 4 of these cards
in one machine. The driver doesn't (yet) support shared interrupts, so
you will need a separate IRQ line for every board.
Read Documentation/networking/slicecom.txt for help on configuring
this adapter.
THE HDLC/PPP LINE PROTOCOL DRIVER
The HDLC/SyncPPP line protocol driver uses the kernel's built-in syncppp
driver (syncppp.o). You don't have to manually select syncppp.o when building
the kernel, the dependencies compile it in automatically.
EXAMPLE
(setting up hw parameters, see above)
# using HDLC:
echo hdlc >/proc/comx/comx0/protocol
echo 10 >/proc/comx/comx0/keepalive <- not necessary, 10 is the default
ifconfig comx0 1.2.3.4 pointopoint 5.6.7.8 netmask 255.255.255.255
(setting up hw parameters, see above)
# using PPP:
echo ppp >/proc/comx/comx0/protocol
ifconfig comx0 up
ifconfig comx0 1.2.3.4 pointopoint 5.6.7.8 netmask 255.255.255.255
THE LAPB LINE PROTOCOL DRIVER
For this, you'll need to configure LAPB support (See 'LAPB Data Link Driver' in
'Network options' section) into your kernel (thanks to Jonathan Naylor for his
excellent implementation).
comx-proto-lapb.o provides the following files in the appropriate directory
(the default values in parens): t1 (5), t2 (1), n2 (20), mode (DTE, STD) and
window (7). Agree with the administrator of your peer router on these
settings (most people use defaults, but you have to know if you are DTE or
DCE).
EXAMPLE
(setting up hw parameters, see above)
echo lapb >/proc/comx/comx0/protocol
echo dce >/proc/comx/comx0/mode <- DCE interface in this example
ifconfig comx0 1.2.3.4 pointopoint 5.6.7.8 netmask 255.255.255.255
THE FRAME RELAY PROTOCOL DRIVER
You DON'T need any other frame relay related modules from the kernel to use
COMX-Frame Relay. This protocol is a bit more complicated than the others,
because it allows to use 'subinterfaces' or DLCIs within one physical device.
First you have to create the 'master' device (the actual physical interface)
as you would do for other protocols. Specify 'frad' as protocol type.
Now you can bring this interface up by saying 'ifconfig comx0 up' (or whatever
you've named the interface). Do not assign any IP address to this interface
and do not set any routes through it.
Then, set up your DLCIs the following way: create a comx interface for each
DLCI you intend to use (with mkdir), and write 'dlci' to the 'boardtype' file,
and 'ietf-ip' to the 'protocol' file. Currently, the only supported
encapsulation type is this (also called as RFC1294/1490 IP encapsulation).
Write the DLCI number to the 'dlci' file, and write the name of the physical
COMX device to the file called 'master'.
Now you can assign an IP address to this interface and set routes using it.
See the example file for further info and example config script.
Notes: this driver implements a DTE interface with partially implemented
Q933a LMI.
You can find an extensively commented example in the 'etc' directory.
FURTHER /proc FILES
boardtype:
Type of the hardware. Valid values are:
'comx', 'hicomx', 'locomx', 'cmx', 'slicecom'.
protocol:
Data-link protocol on this channel. Can be: HDLC, LAPB, PPP, FRAD
status:
You can read the channel's actual status from the 'status' file, for example
'cat /proc/comx/comx3/status'.
lineup_delay:
Interpreted in seconds (default is 1). Used to avoid line jitter: the system
will consider the line status 'UP' only if it is up for at least this number
of seconds.
debug:
You can set various debug options through this file. Valid options are:
'comx_events', 'comx_tx', 'comx_rx', 'hw_events', 'hw_tx', 'hw_rx'.
You can enable a debug options by writing its name prepended by a '+' into
the debug file, for example 'echo +comx_rx >comx0/debug'.
Disabling an option happens similarly, use the '-' prefix
(e.g. 'echo -hw_rx >debug').
Debug results can be read from the debug file, for example:
tail -f /proc/comx/comx2/debug

39
Documentation/networking/dccp.txt
View File

@ -14,24 +14,35 @@ Introduction
============
Datagram Congestion Control Protocol (DCCP) is an unreliable, connection
based protocol designed to solve issues present in UDP and TCP particularly
for real time and multimedia traffic.
oriented protocol designed to solve issues present in UDP and TCP, particularly
for real-time and multimedia (streaming) traffic.
It divides into a base protocol (RFC 4340) and plugable congestion control
modules called CCIDs. Like plugable TCP congestion control, at least one CCID
needs to be enabled in order for the protocol to function properly. In the Linux
implementation, this is the TCP-like CCID2 (RFC 4341). Additional CCIDs, such as
the TCP-friendly CCID3 (RFC 4342), are optional.
For a brief introduction to CCIDs and suggestions for choosing a CCID to match
given applications, see section 10 of RFC 4340.
It has a base protocol and pluggable congestion control IDs (CCIDs).
It is at proposed standard RFC status and the homepage for DCCP as a protocol
is at:
http://www.read.cs.ucla.edu/dccp/
DCCP is a Proposed Standard (RFC 2026), and the homepage for DCCP as a protocol
is at http://www.ietf.org/html.charters/dccp-charter.html
Missing features
================
The DCCP implementation does not currently have all the features that are in
the RFC.
The Linux DCCP implementation does not currently support all the features that are
specified in RFCs 4340...42.
The known bugs are at:
http://linux-net.osdl.org/index.php/TODO#DCCP
For more up-to-date versions of the DCCP implementation, please consider using
the experimental DCCP test tree; instructions for checking this out are on:
http://linux-net.osdl.org/index.php/DCCP_Testing#Experimental_DCCP_source_tree
Socket options
==============
@ -46,6 +57,12 @@ can be set before calling bind().
DCCP_SOCKOPT_GET_CUR_MPS is read-only and retrieves the current maximum packet
size (application payload size) in bytes, see RFC 4340, section 14.
DCCP_SOCKOPT_SERVER_TIMEWAIT enables the server (listening socket) to hold
timewait state when closing the connection (RFC 4340, 8.3). The usual case is
that the closing server sends a CloseReq, whereupon the client holds timewait
state. When this boolean socket option is on, the server sends a Close instead
and will enter TIMEWAIT. This option must be set after accept() returns.
DCCP_SOCKOPT_SEND_CSCOV and DCCP_SOCKOPT_RECV_CSCOV are used for setting the
partial checksum coverage (RFC 4340, sec. 9.2). The default is that checksums
always cover the entire packet and that only fully covered application data is
@ -72,6 +89,8 @@ DCCP_SOCKOPT_CCID_TX_INFO
Returns a `struct tfrc_tx_info' in optval; the buffer for optval and
optlen must be set to at least sizeof(struct tfrc_tx_info).
On unidirectional connections it is useful to close the unused half-connection
via shutdown (SHUT_WR or SHUT_RD): this will reduce per-packet processing costs.
Sysctl variables
================
@ -123,6 +142,12 @@ sync_ratelimit = 125 ms
sequence-invalid packets on the same socket (RFC 4340, 7.5.4). The unit
of this parameter is milliseconds; a value of 0 disables rate-limiting.
IOCTLS
======
FIONREAD
Works as in udp(7): returns in the `int' argument pointer the size of
the next pending datagram in bytes, or 0 when no datagram is pending.
Notes
=====

5
Documentation/networking/driver.txt
View File

@ -61,7 +61,10 @@ Transmit path guidelines:
2) Do not forget to update netdev->trans_start to jiffies after
each new tx packet is given to the hardware.
3) Do not forget that once you return 0 from your hard_start_xmit
3) A hard_start_xmit method must not modify the shared parts of a
cloned SKB.
4) Do not forget that once you return 0 from your hard_start_xmit
method, it is your driver's responsibility to free up the SKB
and in some finite amount of time.

27
Documentation/networking/ip-sysctl.txt
View File

@ -446,6 +446,33 @@ tcp_dma_copybreak - INTEGER
and CONFIG_NET_DMA is enabled.
Default: 4096
UDP variables:
udp_mem - vector of 3 INTEGERs: min, pressure, max
Number of pages allowed for queueing by all UDP sockets.
min: Below this number of pages UDP is not bothered about its
memory appetite. When amount of memory allocated by UDP exceeds
this number, UDP starts to moderate memory usage.
pressure: This value was introduced to follow format of tcp_mem.
max: Number of pages allowed for queueing by all UDP sockets.
Default is calculated at boot time from amount of available memory.
udp_rmem_min - INTEGER
Minimal size of receive buffer used by UDP sockets in moderation.
Each UDP socket is able to use the size for receiving data, even if
total pages of UDP sockets exceed udp_mem pressure. The unit is byte.
Default: 4096
udp_wmem_min - INTEGER
Minimal size of send buffer used by UDP sockets in moderation.
Each UDP socket is able to use the size for sending data, even if
total pages of UDP sockets exceed udp_mem pressure. The unit is byte.
Default: 4096
CIPSOv4 Variables:
cipso_cache_enable - BOOLEAN

16
Documentation/networking/ncsa-telnet
View File

@ -1,16 +0,0 @@
NCSA telnet doesn't work with path MTU discovery enabled. This is due to a
bug in NCSA that also stops it working with other modern networking code
such as Solaris.
The following information is courtesy of
Marek <marekm@i17linuxb.ists.pwr.wroc.pl>
There is a fixed version somewhere on ftp.upe.ac.za (sorry, I don't
remember the exact pathname, and this site is very slow from here).
It may or may not be faster for you to get it from
ftp://ftp.ists.pwr.wroc.pl/pub/msdos/telnet/ncsa_upe/tel23074.zip
(source is in v230704s.zip). I have tested it with 1.3.79 (with
path mtu discovery enabled - ncsa 2.3.08 didn't work) and it seems
to work. I don't know if anyone is working on this code - this
version is over a year old. Too bad - it's faster and often more
stable than these windoze telnets, and runs on almost anything...

58
Documentation/networking/pt.txt
View File

@ -1,58 +0,0 @@
This is the README for the Gracilis Packetwin device driver, version 0.5
ALPHA for Linux 1.3.43.
These files will allow you to talk to the PackeTwin (now know as PT) and
connect through it just like a pair of TNCs. To do this you will also
require the AX.25 code in the kernel enabled.
There are four files in this archive; this readme, a patch file, a .c file
and finally a .h file. The two program files need to be put into the
drivers/net directory in the Linux source tree, for me this is the
directory /usr/src/linux/drivers/net. The patch file needs to be patched in
at the top of the Linux source tree (/usr/src/linux in my case).
You will most probably have to edit the pt.c file to suit your own setup,
this should just involve changing some of the defines at the top of the file.
Please note that if you run an external modem you must specify a speed of 0.
The program is currently setup to run a 4800 baud external modem on port A
and a Kantronics DE-9600 daughter board on port B so if you have this (or
something similar) then you're right.
To compile in the driver, put the files in the correct place and patch in
the diff. You will have to re-configure the kernel again before you
recompile it.
The driver is not real good at the moment for finding the card. You can
'help' it by changing the order of the potential addresses in the structure
found in the pt_init() function so the address of where the card is is put
first.
After compiling, you have to get them going, they are pretty well like any
other net device and just need ifconfig to get them going.
As an example, here is my /etc/rc.net
--------------------------
#
# Configure the PackeTwin, port A.
/sbin/ifconfig pt0a 44.136.8.87 hw ax25 vk2xlz mtu 512
/sbin/ifconfig pt0a 44.136.8.87 broadcast 44.136.8.255 netmask 255.255.255.0
/sbin/route add -net 44.136.8.0 netmask 255.255.255.0 dev pt0a
/sbin/route add -net 44.0.0.0 netmask 255.0.0.0 gw 44.136.8.68 dev pt0a
/sbin/route add -net 138.25.16.0 netmask 255.255.240.0 dev pt0a
/sbin/route add -host 44.136.8.255 dev pt0a
#
# Configure the PackeTwin, port B.
/sbin/ifconfig pt0b 44.136.8.87 hw ax25 vk2xlz-1 mtu 512
/sbin/ifconfig pt0b 44.136.8.87 broadcast 44.255.255.255 netmask 255.0.0.0
/sbin/route add -host 44.136.8.216 dev pt0b
/sbin/route add -host 44.136.8.95 dev pt0b
/sbin/route add -host 44.255.255.255 dev pt0b
This version of the driver comes under the GNU GPL. If you have one of my
previous (non-GPL) versions of the driver, please update to this one.
I hope that this all works well for you. I would be pleased to hear how
many people use the driver and if it does its job.
- Craig vk2xlz <csmall@small.dropbear.id.au>

46
Documentation/networking/routing.txt
View File

@ -1,46 +0,0 @@
The directory ftp.inr.ac.ru:/ip-routing contains:
- iproute.c - "professional" routing table maintenance utility.
- rdisc.tar.gz - rdisc daemon, ported from Sun.
STRONGLY RECOMMENDED FOR ALL HOSTS.
- routing.tgz - original Mike McLagan's route by source patch.
Currently it is obsolete.
- gated.dif-ss<NEWEST>.gz - gated-R3_6Alpha_2 fixes.
Look at README.gated
- mrouted-3.8.dif.gz - mrouted-3.8 fixes.
- rtmon.c - trivial debugging utility: reads and stores netlink.
NEWS for user.
- Policy based routing. Routing decisions are made on the basis
not only of destination address, but also source address,
TOS and incoming interface.
- Complete set of IP level control messages.
Now Linux is the only OS in the world complying to RFC requirements.
Great win 8)
- New interface addressing paradigm.
Assignment of address ranges to interface,
multiple prefixes etc. etc.
Do not bother, it is compatible with the old one. Moreover:
- You don't need to do "route add aaa.bbb.ccc... eth0" anymore,
it is done automatically.
- "Abstract" UNIX sockets and security enhancements.
This is necessary to use TIRPC and TLI emulation library.
NEWS for hacker.
- New destination cache. Flexible, robust and just beautiful.
- Network stack is reordered, simplified, optimized, a lot of bugs fixed.
(well, and new bugs were introduced, but I haven't seen them yet 8))
It is difficult to describe all the changes, look into source.
If you see this file, then this patch works 8)
Alexey Kuznetsov.
kuznet@ms2.inr.ac.ru

48
Documentation/networking/shaper.txt
View File

@ -1,48 +0,0 @@
Traffic Shaper For Linux
This is the current BETA release of the traffic shaper for Linux. It works
within the following limits:
o Minimum shaping speed is currently about 9600 baud (it can only
shape down to 1 byte per clock tick)
o Maximum is about 256K, it will go above this but get a bit blocky.
o If you ifconfig the master device that a shaper is attached to down
then your machine will follow.
o The shaper must be a module.
Setup:
A shaper device is configured using the shapeconfig program.
Typically you will do something like this
shapecfg attach shaper0 eth1
shapecfg speed shaper0 64000
ifconfig shaper0 myhost netmask 255.255.255.240 broadcast 1.2.3.4.255 up
route add -net some.network netmask a.b.c.d dev shaper0
The shaper should have the same IP address as the device it is attached to
for normal use.
Gotchas:
The shaper shapes transmitted traffic. It's rather impossible to
shape received traffic except at the end (or a router) transmitting it.
Gated/routed/rwhod/mrouted all see the shaper as an additional device
and will treat it as such unless patched. Note that for mrouted you can run
mrouted tunnels via a traffic shaper to control bandwidth usage.
The shaper is device/route based. This makes it very easy to use
with any setup BUT less flexible. You may need to use iproute2 to set up
multiple route tables to get the flexibility.
There is no "borrowing" or "sharing" scheme. This is a simple
traffic limiter. We implement Van Jacobson and Sally Floyd's CBQ
architecture into Linux 2.2. This is the preferred solution. Shaper is
for simple or back compatible setups.
Alan

371
Documentation/networking/slicecom.hun
View File

@ -1,371 +0,0 @@
SliceCOM adapter felhasznaloi dokumentacioja - 0.51 verziohoz
Bartók István <bartoki@itc.hu>
Utolso modositas: Wed Aug 29 17:26:58 CEST 2001
-----------------------------------------------------------------
Hasznalata:
Forditas:
Code maturity level options
[*] Prompt for development and/or incomplete code/drivers
Network device support
Wan interfaces
<M> MultiGate (COMX) synchronous
<M> Support for MUNICH based boards: SliceCOM, PCICOM (NEW)
<M> Support for HDLC and syncPPP...
A modulok betoltese:
modprobe comx
modprobe comx-proto-ppp # a Cisco-HDLC es a SyncPPP protokollt is
# ez a modul adja
modprobe comx-hw-munich # a modul betoltodeskor azonnal jelent a
# syslogba a detektalt kartyakrol
Konfiguralas:
# Ezen az interfeszen Cisco-HDLC vonali protokoll fog futni
# Az interfeszhez rendelt idoszeletek: 1,2 (128 kbit/sec-es vonal)
# (a G.703 keretben az elso adatot vivo idoszelet az 1-es)
#
mkdir /proc/comx/comx0.1/
echo slicecom >/proc/comx/comx0.1/boardtype
echo hdlc >/proc/comx/comx0.1/protocol
echo 1 2 >/proc/comx/comx0.1/timeslots
# Ezen az interfeszen SyncPPP vonali protokoll fog futni
# Az interfeszhez rendelt idoszelet: 3 (64 kbit/sec-es vonal)
#
mkdir /proc/comx/comx0.2/
echo slicecom >/proc/comx/comx0.2/boardtype
echo ppp >/proc/comx/comx0.2/protocol
echo 3 >/proc/comx/comx0.2/timeslots
...
ifconfig comx0.1 up
ifconfig comx0.2 up
-----------------------------------------------------------------
A COMX driverek default 20 csomagnyi transmit queue-t rendelnek a halozati
interfeszekhez. WAN halozatokban ennel hosszabbat is szokas hasznalni
(20 es 100 kozott), hogy a vonal kihasznaltsaga nagy terheles eseten jobb
legyen (bar ezzel megno a varhato kesleltetes a csomagok sorban allasa miatt):
# ifconfig comx0 txqueuelen 50
Ezt a beallitasi lehetoseget csak az ujabb disztribuciok ifconfig parancsa
tamogatja (amik mar a 2.2 kernelekhez keszultek, mint a RedHat 6.1 vagy a
Debian 2.2).
A 2.1-es Debian disztribuciohoz a http://www.debian.org/~rcw/2.2/netbase/
cimrol toltheto le ujabb netbase csomag, ami mar ilyet tamogato ifconfig
parancsot tartalmaz. Bovebben a 2.2 kernel hasznalatarol Debian 2.1 alatt:
http://www.debian.org/releases/stable/running-kernel-2.2
-----------------------------------------------------------------
A kartya LED-jeinek jelentese:
piros - eg, ha Remote Alarm-ot kuld a tuloldal
zold - eg, ha a vett jelben megtalalja a keretszinkront
Reszletesebben:
piros: zold: jelentes:
- - nincs keretszinkron (nincs jel, vagy rossz a jel)
- eg "minden rendben"
eg eg a vetel OK, de a tuloldal Remote Alarm-ot kuld
eg - ez nincs ertelmezve, egyelore funkcio nelkul
-----------------------------------------------------------------
Reszletesebb leiras a hardver beallitasi lehetosegeirol:
Az altalanos,- es a protokoll-retegek beallitasi lehetosegeirol a 'comx.txt'
fajlban leirtak SliceCOM kartyanal is ervenyesek, itt csak a hardver-specifikus
beallitasi lehetosegek vannak osszefoglalva:
Konfiguralasi interfesz a /proc/comx/ alatt:
Minden timeslot-csoportnak kulon comx* interfeszt kell letrehozni mkdir-rel:
comx0, comx1, .. stb. Itt beallithato, hogy az adott interfesz hanyadik kartya
melyik timeslotja(i)bol alljon ossze. A Cisco-fele serial3:1 elnevezesek
(serial3:1 = a 3. kartyaban az 1-es idoszelet-csoport) Linuxon aliasing-ot
jelentenenek, ezert mi nem tudunk ilyen elnevezest hasznalni.
Tobb kartya eseten a comx0.1, comx0.2, ... vagy slice0.1, slice0.2 nevek
hasznalhatoak.
Tobb SliceCOM kartya is lehet egy gepben, de sajat interrupt kell mindegyiknek,
nem tud meg megosztott interruptot kezelni.
Az egesz kartyat erinto beallitasok:
Az ioport es irq beallitas nincs: amit a PCI BIOS kioszt a rendszernek,
azt hasznalja a driver.
comx0/boardnum - hanyadik SliceCOM kartya a gepben (a 'termeszetes' PCI
sorrendben ertve: ahogyan a /proc/pci-ban vagy az 'lspci'
kimeneteben megjelenik, altalaban az alaplapi PCI meghajto
aramkorokhoz kozelebb eso kartyak a kisebb sorszamuak)
Default: 0 (0-tol kezdodik a szamolas)
Bar a kovetkezoket csak egy-egy interfeszen allitjuk at, megis az egesz kartya
mukodeset egyszerre allitjak. A megkotes hogy csak UP-ban levo interfeszen
hasznalhatoak, azert van, mert kulonben nem vart eredmenyekre vezetne egy ilyen
paranccsorozat:
echo 0 >boardnum
echo internal >clock_source
echo 1 >boardnum
- Ez a 0-s board clock_source-at allitana at.
Ezek a beallitasok megmaradnak az osszes interfesz torlesekor, de torlodnek
a driver modul ki/betoltesekor.
comx0/clock_source - A Tx orajelforrasa, a Cisco-val hasonlatosra keszult.
Hasznalata:
papaya:# echo line >/proc/comx/comx0/clock_source
papaya:# echo internal >/proc/comx/comx0/clock_source
line - A Tx orajelet a vett adatfolyambol dekodolja, igyekszik
igazodni hozza. Ha nem lat orajelet az inputon, akkor
atall a sajat orajelgeneratorara.
internal - A Tx orajelet a sajat orajelgeneratora szolgaltatja.
Default: line
Normal osszeallitas eseten a tavkozlesi szolgaltato eszkoze
(pl. HDSL modem) adja az orajelet, ezert ez a default.
comx0/framing - A CRC4 ki/be kapcsolasa
A CRC4: 16 PCM keretet (A PCM keret az, amibe a 32 darab 64
kilobites csatorna van bemultiplexalva. Nem osszetevesztendo a HDLC
kerettel.) 2x8 -as csoportokra osztanak, es azokhoz 4-4 bites CRC-t
szamolnak. Elsosorban a vonal minosegenek a monitorozasara szolgal.
papaya:~# echo crc4 >/proc/comx/comx0/framing
papaya:~# echo no-crc4 >/proc/comx/comx0/framing
Default a 'crc4', a MATAV vonalak altalaban igy futnak. De ha nem
egyforma is a beallitas a vonal ket vegen, attol a forgalom altalaban
at tud menni.
comx0/linecode - A vonali kodolas beallitasa
papaya:~# echo hdb3 >/proc/comx/comx0/linecode
papaya:~# echo ami >/proc/comx/comx0/linecode
Default a 'hdb3', a MATAV vonalak igy futnak.
(az AMI kodolas igen ritka E1-es vonalaknal). Ha ez a beallitas nem
egyezik a vonal ket vegen, akkor elofordulhat hogy a keretszinkron
osszejon, de CRC4-hibak es a vonalakon atvitt adatokban is hibak
keletkeznek (amit a HDLC/SyncPPP szinten CRC-hibaval jelez)
comx0/reg - a kartya aramkoreinek, a MUNICH (reg) es a FALC (lbireg)
comx0/lbireg regisztereinek kozvetlen elerese. Hasznalata:
echo >reg 0x04 0x0 - a 4-es regiszterbe 0-t ir
echo >reg 0x104 - printk()-val kiirja a 4-es regiszter
tartalmat a syslogba.
WARNING: ezek csak a fejleszteshez keszultek, sok galibat
lehet veluk okozni!
comx0/loopback - A kartya G.703 jelenek a visszahurkolasara is van lehetoseg:
papaya:# echo none >/proc/comx/comx0/loopback
papaya:# echo local >/proc/comx/comx0/loopback
papaya:# echo remote >/proc/comx/comx0/loopback
none - nincs visszahurkolas, normal mukodes
local - a kartya a sajat maga altal adott jelet kapja vissza
remote - a kartya a kivulrol vett jelet adja kifele
Default: none
-----------------------------------------------------------------
Az interfeszhez (Cisco terminologiaban 'channel-group') kapcsolodo beallitasok:
comx0/timeslots - mely timeslotok (idoszeletek) tartoznak az adott interfeszhez.
papaya:~# cat /proc/comx/comx0/timeslots
1 3 4 5 6
papaya:~#
Egy timeslot megkeresese (hanyas interfeszbe tartozik nalunk):
papaya:~# grep ' 4' /proc/comx/comx*/timeslots
/proc/comx/comx0/timeslots:1 3 4 5 6
papaya:~#
Beallitasa:
papaya:~# echo '1 5 2 6 7 8' >/proc/comx/comx0/timeslots
A timeslotok sorrendje nem szamit, '1 3 2' ugyanaz mint az '1 2 3'.
Beallitashoz az adott interfesznek DOWN-ban kell lennie
(ifconfig comx0 down), de ugyanannak a kartyanak a tobbi interfesze
uzemelhet kozben.
Beallitaskor leellenorzi, hogy az uj timeslotok nem utkoznek-e egy
masik interfesz timeslotjaival. Ha utkoznek, akkor nem allitja at.
Mindig 10-es szamrendszerben tortenik a timeslotok ertelmezese, nehogy
a 08, 09 alaku felirast rosszul ertelmezze.
-----------------------------------------------------------------
Az interfeszek es a kartya allapotanak lekerdezese:
- A ' '-szel kezdodo sorok az eredeti kimenetet, a //-rel kezdodo sorok a
magyarazatot jelzik.
papaya:~$ cat /proc/comx/comx1/status
Interface administrative status is UP, modem status is UP, protocol is UP
Modem status changes: 0, Transmitter status is IDLE, tbusy: 0
Interface load (input): 978376 / 947808 / 951024 bits/s (5s/5m/15m)
(output): 978376 / 947848 / 951024 bits/s (5s/5m/15m)
Debug flags: none
RX errors: len: 22, overrun: 1, crc: 0, aborts: 0
buffer overrun: 0, pbuffer overrun: 0
TX errors: underrun: 0
Line keepalive (value: 10) status UP [0]
// Itt kezdodik a hardver-specifikus resz:
Controller status:
No alarms
// Alarm: hibajelzes:
//
// No alarms - minden rendben
//
// LOS - Loss Of Signal - nem erzekel jelet a bemeneten.
// AIS - Alarm Indication Signal - csak egymas utani 1-esek jonnek
// a bemeneten, a tuloldal igy is jelezheti hogy meghibasodott vagy
// nincs inicializalva.
// AUXP - Auxiliary Pattern Indication - 01010101.. sorozat jon a bemeneten.
// LFA - Loss of Frame Alignment - nincs keretszinkron
// RRA - Receive Remote Alarm - a tuloldal el, de hibat jelez.
// LMFA - Loss of CRC4 Multiframe Alignment - nincs CRC4-multikeret-szinkron
// NMF - No Multiframe alignment Found after 400 msec - ilyen alarm a no-crc4
// es crc4 keretezesek eseten nincs, lasd lentebb
//
// Egyeb lehetseges hibajelzesek:
//
// Transmit Line Short - a kartya ugy erzi hogy az adasi kimenete rovidre
// van zarva, ezert kikapcsolta az adast. (nem feltetlenul veszi eszre
// a kulso rovidzarat)
// A veteli oldal csomagjainak lancolt listai, debug celokra:
Rx ring:
rafutott: 0
lastcheck: 50845731, jiffies: 51314281
base: 017b1858
rx_desc_ptr: 0
rx_desc_ptr: 017b1858
hw_curr_ptr: 017b1858
06040000 017b1868 017b1898 c016ff00
06040000 017b1878 017b1e9c c016ff00
46040000 017b1888 017b24a0 c016ff00
06040000 017b1858 017b2aa4 c016ff00
// A kartyat hasznalo tobbi interfesz: a 0-s channel-group a comx1 interfesz,
// es az 1,2,...,16 timeslotok tartoznak hozza:
Interfaces using this board: (channel-group, interface, timeslots)
0 comx1: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
1 comx2: 17
2 comx3: 18
3 comx4: 19
4 comx5: 20
5 comx6: 21
6 comx7: 22
7 comx8: 23
8 comx9: 24
9 comx10: 25
10 comx11: 26
11 comx12: 27
12 comx13: 28
13 comx14: 29
14 comx15: 30
15 comx16: 31
// Hany esemenyt kezelt le a driver egy-egy hardver-interrupt kiszolgalasanal:
Interrupt work histogram:
hist[ 0]: 0 hist[ 1]: 2 hist[ 2]: 18574 hist[ 3]: 79
hist[ 4]: 14 hist[ 5]: 1 hist[ 6]: 0 hist[ 7]: 1
hist[ 8]: 0 hist[ 9]: 7
// Hany kikuldendo csomag volt mar a Tx-ringben amikor ujabb lett irva bele:
Tx ring histogram:
hist[ 0]: 2329 hist[ 1]: 0 hist[ 2]: 0 hist[ 3]: 0
// Az E1-interfesz hiba-szamlaloi, az rfc2495-nek megfeleloen:
// (kb. a Cisco routerek "show controllers e1" formatumaban: http://www.cisco.com/univercd/cc/td/doc/product/software/ios11/rbook/rinterfc.htm#xtocid25669126)
Data in current interval (91 seconds elapsed):
9516 Line Code Violations, 65 Path Code Violations, 2 E-Bit Errors
0 Slip Secs, 2 Fr Loss Secs, 2 Line Err Secs, 0 Degraded Mins
0 Errored Secs, 0 Bursty Err Secs, 0 Severely Err Secs, 11 Unavail Secs
Data in Interval 1 (15 minutes):
0 Line Code Violations, 0 Path Code Violations, 0 E-Bit Errors
0 Slip Secs, 0 Fr Loss Secs, 0 Line Err Secs, 0 Degraded Mins
0 Errored Secs, 0 Bursty Err Secs, 0 Severely Err Secs, 0 Unavail Secs
Data in last 4 intervals (1 hour):
0 Line Code Violations, 0 Path Code Violations, 0 E-Bit Errors
0 Slip Secs, 0 Fr Loss Secs, 0 Line Err Secs, 0 Degraded Mins
0 Errored Secs, 0 Bursty Err Secs, 0 Severely Err Secs, 0 Unavail Secs
Data in last 96 intervals (24 hours):
0 Line Code Violations, 0 Path Code Violations, 0 E-Bit Errors
0 Slip Secs, 0 Fr Loss Secs, 0 Line Err Secs, 0 Degraded Mins
0 Errored Secs, 0 Bursty Err Secs, 0 Severely Err Secs, 0 Unavail Secs
-----------------------------------------------------------------
Nehany kulonlegesebb beallitasi lehetoseg (idovel beepulhetnek majd a driverbe):
Ezekkel sok galibat lehet okozni, nagyon ovatosan kell oket hasznalni!
modified CRC-4, for improved interworking of CRC-4 and non-CRC-4
devices: (lasd page 107 es g706 Annex B)
lbireg[ 0x1b ] |= 0x08
lbireg[ 0x1c ] |= 0xc0
- ilyenkor ertelmezett az NMF - 'No Multiframe alignment Found after
400 msec' alarm.
FALC - a vonali meghajto IC
local loop - a sajat adasomat halljam vissza
remote loop - a kivulrol jovo adast adom vissza
Egy hibakeresesre hasznalhato dolog:
- 1-es timeslot local loop a FALC-ban: echo >lbireg 0x1d 0x21
- local loop kikapcsolasa: echo >lbireg 0x1d 0x00

369
Documentation/networking/slicecom.txt
View File

@ -1,369 +0,0 @@
SliceCOM adapter user's documentation - for the 0.51 driver version
Written by Bartók István <bartoki@itc.hu>
English translation: Lakatos György <gyuri@itc.hu>
Mon Dec 11 15:28:42 CET 2000
Last modified: Wed Aug 29 17:25:37 CEST 2001
-----------------------------------------------------------------
Usage:
Compiling the kernel:
Code maturity level options
[*] Prompt for development and/or incomplete code/drivers
Network device support
Wan interfaces
<M> MultiGate (COMX) synchronous
<M> Support for MUNICH based boards: SliceCOM, PCICOM (NEW)
<M> Support for HDLC and syncPPP...
Loading the modules:
modprobe comx
modprobe comx-proto-ppp # module for Cisco-HDLC and SyncPPP protocols
modprobe comx-hw-munich # the module logs information by the kernel
# about the detected boards
Configuring the board:
# This interface will use the Cisco-HDLC line protocol,
# the timeslices assigned are 1,2 (128 KiBit line speed)
# (the first data timeslice in the G.703 frame is no. 1)
#
mkdir /proc/comx/comx0.1/
echo slicecom >/proc/comx/comx0.1/boardtype
echo hdlc >/proc/comx/comx0.1/protocol
echo 1 2 >/proc/comx/comx0.1/timeslots
# This interface uses SyncPPP line protocol, the assigned
# is no. 3 (64 KiBit line speed)
#
mkdir /proc/comx/comx0.2/
echo slicecom >/proc/comx/comx0.2/boardtype
echo ppp >/proc/comx/comx0.2/protocol
echo 3 >/proc/comx/comx0.2/timeslots
...
ifconfig comx0.1 up
ifconfig comx0.2 up
-----------------------------------------------------------------
The COMX interfaces use a 10 packet transmit queue by default, however WAN
networks sometimes use bigger values (20 to 100), to utilize the line better
by large traffic (though the line delay increases because of more packets
join the queue).
# ifconfig comx0 txqueuelen 50
This option is only supported by the ifconfig command of the later
distributions, which came with 2.2 kernels, such as RedHat 6.1 or Debian 2.2.
You can download a newer netbase packet from
http://www.debian.org/~rcw/2.2/netbase/ for Debian 2.1, which has a new
ifconfig. You can get further information about using 2.2 kernel with
Debian 2.1 from http://www.debian.org/releases/stable/running-kernel-2.2
-----------------------------------------------------------------
The SliceCom LEDs:
red - on, if the interface is unconfigured, or it gets Remote Alarm-s
green - on, if the board finds frame-sync in the received signal
A bit more detailed:
red: green: meaning:
- - no frame-sync, no signal received, or signal SNAFU.
- on "Everything is OK"
on on Reception is ok, but the remote end sends Remote Alarm
on - The interface is unconfigured
-----------------------------------------------------------------
A more detailed description of the hardware setting options:
The general and the protocol layer options described in the 'comx.txt' file
apply to the SliceCom as well, I only summarize the SliceCom hardware specific
settings below.
The '/proc/comx' configuring interface:
An interface directory should be created for every timeslot group with
'mkdir', e,g: 'comx0', 'comx1' etc. The timeslots can be assigned here to the
specific interface. The Cisco-like naming convention (serial3:1 - first
timeslot group of the 3rd. board) can't be used here, because these mean IP
aliasing in Linux.
You can give any meaningful name to keep the configuration clear;
e.g: 'comx0.1', 'comx0.2', 'comx1.1', comx1.2', if you have two boards
with two interfaces each.
Settings, which apply to the board:
Neither 'io' nor 'irq' settings required, the driver uses the resources
given by the PCI BIOS.
comx0/boardnum - board number of the SliceCom in the PC (using the 'natural'
PCI order) as listed in '/proc/pci' or the output of the
'lspci' command, generally the slots nearer to the motherboard
PCI driver chips have the lower numbers.
Default: 0 (the counting starts with 0)
Though the options below are to be set on a single interface, they apply to the
whole board. The restriction, to use them on 'UP' interfaces, is because the
command sequence below could lead to unpredictable results.
# echo 0 >boardnum
# echo internal >clock_source
# echo 1 >boardnum
The sequence would set the clock source of board 0.
These settings will persist after all the interfaces are cleared, but are
cleared when the driver module is unloaded and loaded again.
comx0/clock_source - source of the transmit clock
Usage:
# echo line >/proc/comx/comx0/clock_source
# echo internal >/proc/comx/comx0/clock_source
line - The Tx clock is being decoded if the input data stream,
if no clock seen on the input, then the board will use it's
own clock generator.
internal - The Tx clock is supplied by the builtin clock generator.
Default: line
Normally, the telecommunication company's end device (the HDSL
modem) provides the Tx clock, that's why 'line' is the default.
comx0/framing - Switching CRC4 off/on
CRC4: 16 PCM frames (The 32 64Kibit channels are multiplexed into a
PCM frame, nothing to do with HDLC frames) are divided into 2x8
groups, each group has a 4 bit CRC.
# echo crc4 >/proc/comx/comx0/framing
# echo no-crc4 >/proc/comx/comx0/framing
Default is 'crc4', the Hungarian MATAV lines behave like this.
The traffic generally passes if this setting on both ends don't match.
comx0/linecode - Setting the line coding
# echo hdb3 >/proc/comx/comx0/linecode
# echo ami >/proc/comx/comx0/linecode
Default a 'hdb3', MATAV lines use this.
(AMI coding is rarely used with E1 lines). Frame sync may occur, if
this setting doesn't match the other end's, but CRC4 and data errors
will come, which will result in CRC errors on HDLC/SyncPPP level.
comx0/reg - direct access to the board's MUNICH (reg) and FALC (lbireg)
comx0/lbireg circuit's registers
# echo >reg 0x04 0x0 - write 0 to register 4
# echo >reg 0x104 - write the contents of register 4 with
printk() to syslog
WARNING! These are only for development purposes, messing with this will
result much trouble!
comx0/loopback - Places a loop to the board's G.703 signals
# echo none >/proc/comx/comx0/loopback
# echo local >/proc/comx/comx0/loopback
# echo remote >/proc/comx/comx0/loopback
none - normal operation, no loop
local - the board receives it's own output
remote - the board sends the received data to the remote side
Default: none
-----------------------------------------------------------------
Interface (channel group in Cisco terms) settings:
comx0/timeslots - which timeslots belong to the given interface
Setting:
# echo '1 5 2 6 7 8' >/proc/comx/comx0/timeslots
# cat /proc/comx/comx0/timeslots
1 2 5 6 7 8
#
Finding a timeslot:
# grep ' 4' /proc/comx/comx*/timeslots
/proc/comx/comx0/timeslots:1 3 4 5 6
#
The timeslots can be in any order, '1 2 3' is the same as '1 3 2'.
The interface has to be DOWN during the setting ('ifconfig comx0
down'), but the other interfaces could operate normally.
The driver checks if the assigned timeslots are vacant, if not, then
the setting won't be applied.
The timeslot values are treated as decimal numbers, not to misunderstand
values of 08, 09 form.
-----------------------------------------------------------------
Checking the interface and board status:
- Lines beginning with ' ' (space) belong to the original output, the lines
which begin with '//' are the comments.
papaya:~$ cat /proc/comx/comx1/status
Interface administrative status is UP, modem status is UP, protocol is UP
Modem status changes: 0, Transmitter status is IDLE, tbusy: 0
Interface load (input): 978376 / 947808 / 951024 bits/s (5s/5m/15m)
(output): 978376 / 947848 / 951024 bits/s (5s/5m/15m)
Debug flags: none
RX errors: len: 22, overrun: 1, crc: 0, aborts: 0
buffer overrun: 0, pbuffer overrun: 0
TX errors: underrun: 0
Line keepalive (value: 10) status UP [0]
// The hardware specific part starts here:
Controller status:
No alarms
// Alarm:
//
// No alarms - Everything OK
//
// LOS - Loss Of Signal - No signal sensed on the input
// AIS - Alarm Indication Signal - The remote side sends '11111111'-s,
// it tells, that there's an error condition, or it's not
// initialised.
// AUXP - Auxiliary Pattern Indication - 01010101.. received.
// LFA - Loss of Frame Alignment - no frame sync received.
// RRA - Receive Remote Alarm - the remote end's OK, but signals error cond.
// LMFA - Loss of CRC4 Multiframe Alignment - no CRC4 multiframe sync.
// NMF - No Multiframe alignment Found after 400 msec - no such alarm using
// no-crc4 or crc4 framing, see below.
//
// Other possible error messages:
//
// Transmit Line Short - the board felt, that it's output is short-circuited,
// so it switched the transmission off. (The board can't definitely tell,
// that it's output is short-circuited.)
// Chained list of the received packets, for debug purposes:
Rx ring:
rafutott: 0
lastcheck: 50845731, jiffies: 51314281
base: 017b1858
rx_desc_ptr: 0
rx_desc_ptr: 017b1858
hw_curr_ptr: 017b1858
06040000 017b1868 017b1898 c016ff00
06040000 017b1878 017b1e9c c016ff00
46040000 017b1888 017b24a0 c016ff00
06040000 017b1858 017b2aa4 c016ff00
// All the interfaces using the board: comx1, using the 1,2,...16 timeslots,
// comx2, using timeslot 17, etc.
Interfaces using this board: (channel-group, interface, timeslots)
0 comx1: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
1 comx2: 17
2 comx3: 18
3 comx4: 19
4 comx5: 20
5 comx6: 21
6 comx7: 22
7 comx8: 23
8 comx9: 24
9 comx10: 25
10 comx11: 26
11 comx12: 27
12 comx13: 28
13 comx14: 29
14 comx15: 30
15 comx16: 31
// The number of events handled by the driver during an interrupt cycle:
Interrupt work histogram:
hist[ 0]: 0 hist[ 1]: 2 hist[ 2]: 18574 hist[ 3]: 79
hist[ 4]: 14 hist[ 5]: 1 hist[ 6]: 0 hist[ 7]: 1
hist[ 8]: 0 hist[ 9]: 7
// The number of packets to send in the Tx ring, when a new one arrived:
Tx ring histogram:
hist[ 0]: 2329 hist[ 1]: 0 hist[ 2]: 0 hist[ 3]: 0
// The error counters of the E1 interface, according to the RFC2495,
// (similar to the Cisco "show controllers e1" command's output:
// http://www.cisco.com/univercd/cc/td/doc/product/software/ios11/rbook/rinterfc.htm#xtocid25669126)
Data in current interval (91 seconds elapsed):
9516 Line Code Violations, 65 Path Code Violations, 2 E-Bit Errors
0 Slip Secs, 2 Fr Loss Secs, 2 Line Err Secs, 0 Degraded Mins
0 Errored Secs, 0 Bursty Err Secs, 0 Severely Err Secs, 11 Unavail Secs
Data in Interval 1 (15 minutes):
0 Line Code Violations, 0 Path Code Violations, 0 E-Bit Errors
0 Slip Secs, 0 Fr Loss Secs, 0 Line Err Secs, 0 Degraded Mins
0 Errored Secs, 0 Bursty Err Secs, 0 Severely Err Secs, 0 Unavail Secs
Data in last 4 intervals (1 hour):
0 Line Code Violations, 0 Path Code Violations, 0 E-Bit Errors
0 Slip Secs, 0 Fr Loss Secs, 0 Line Err Secs, 0 Degraded Mins
0 Errored Secs, 0 Bursty Err Secs, 0 Severely Err Secs, 0 Unavail Secs
Data in last 96 intervals (24 hours):
0 Line Code Violations, 0 Path Code Violations, 0 E-Bit Errors
0 Slip Secs, 0 Fr Loss Secs, 0 Line Err Secs, 0 Degraded Mins
0 Errored Secs, 0 Bursty Err Secs, 0 Severely Err Secs, 0 Unavail Secs
-----------------------------------------------------------------
Some unique options, (may get into the driver later):
Treat them very carefully, these can cause much trouble!
modified CRC-4, for improved interworking of CRC-4 and non-CRC-4
devices: (see page 107 and g706 Annex B)
lbireg[ 0x1b ] |= 0x08
lbireg[ 0x1c ] |= 0xc0
- The NMF - 'No Multiframe alignment Found after 400 msec' alarm
comes into account.
FALC - the line driver chip.
local loop - I hear my transmission back.
remote loop - I echo the remote transmission back.
Something useful for finding errors:
- local loop for timeslot 1 in the FALC chip:
# echo >lbireg 0x1d 0x21
- Switching the loop off:
# echo >lbireg 0x1d 0x00

2
Documentation/networking/udplite.txt
View File

@ -236,7 +236,7 @@
This displays UDP-Lite statistics variables, whose meaning is as follows.
InDatagrams: Total number of received datagrams.
InDatagrams: The total number of datagrams delivered to users.
NoPorts: Number of packets received to an unknown port.
These cases are counted separately (not as InErrors).

4
Documentation/networking/wavelan.txt
View File

@ -12,8 +12,8 @@ and many Linux driver to support it.
"wavelan" driver (old ISA Wavelan)
----------------
o Config : Network device -> Wireless LAN -> AT&T WaveLAN
o Location : .../drivers/net/wavelan*
o in-line doc : .../drivers/net/wavelan.p.h
o Location : .../drivers/net/wireless/wavelan*
o in-line doc : .../drivers/net/wireless/wavelan.p.h
o on-line doc :
http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Wavelan.html

74
Documentation/networking/xfrm_proc.txt 100644
View File

@ -0,0 +1,74 @@
XFRM proc - /proc/net/xfrm_* files
==================================
Masahide NAKAMURA <nakam@linux-ipv6.org>
Transformation Statistics
-------------------------
xfrm_proc is a statistics shown factor dropped by transformation
for developer.
It is a counter designed from current transformation source code
and defined like linux private MIB.
Inbound statistics
~~~~~~~~~~~~~~~~~~
XfrmInError:
All errors which is not matched others
XfrmInBufferError:
No buffer is left
XfrmInHdrError:
Header error
XfrmInNoStates:
No state is found
i.e. Either inbound SPI, address, or IPsec protocol at SA is wrong
XfrmInStateProtoError:
Transformation protocol specific error
e.g. SA key is wrong
XfrmInStateModeError:
Transformation mode specific error
XfrmInStateSeqError:
Sequence error
i.e. Sequence number is out of window
XfrmInStateExpired:
State is expired
XfrmInStateMismatch:
State has mismatch option
e.g. UDP encapsulation type is mismatch
XfrmInStateInvalid:
State is invalid
XfrmInTmplMismatch:
No matching template for states
e.g. Inbound SAs are correct but SP rule is wrong
XfrmInNoPols:
No policy is found for states
e.g. Inbound SAs are correct but no SP is found
XfrmInPolBlock:
Policy discards
XfrmInPolError:
Policy error
Outbound errors
~~~~~~~~~~~~~~~
XfrmOutError:
All errors which is not matched others
XfrmOutBundleGenError:
Bundle generation error
XfrmOutBundleCheckError:
Bundle check error
XfrmOutNoStates:
No state is found
XfrmOutStateProtoError:
Transformation protocol specific error
XfrmOutStateModeError:
Transformation mode specific error
XfrmOutStateSeqError:
Sequence error
i.e. Sequence number overflow
XfrmOutStateExpired:
State is expired
XfrmOutPolBlock:
Policy discards
XfrmOutPolDead:
Policy is dead
XfrmOutPolError:
Policy error

10
Documentation/nfsroot.txt
View File

@ -92,8 +92,10 @@ ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>
autoconfiguration.
The <autoconf> parameter can appear alone as the value to the `ip'
parameter (without all the ':' characters before) in which case auto-
configuration is used.
parameter (without all the ':' characters before). If the value is
"ip=off" or "ip=none", no autoconfiguration will take place, otherwise
autoconfiguration will take place. The most common way to use this
is "ip=dhcp".
<client-ip> IP address of the client.
@ -142,8 +144,10 @@ ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>
into the kernel will be used, regardless of the value of
this option.
off or none: don't use autoconfiguration (default)
off or none: don't use autoconfiguration
(do static IP assignment instead)
on or any: use any protocol available in the kernel
(default)
dhcp: use DHCP
bootp: use BOOTP
rarp: use RARP

4
Documentation/parport-lowlevel.txt
View File

@ -339,6 +339,10 @@ Use this function to register your device driver on a parallel port
('port'). Once you have done that, you will be able to use
parport_claim and parport_release in order to use the port.
The ('name') argument is the name of the device that appears in /proc
filesystem. The string must be valid for the whole lifetime of the
device (until parport_unregister_device is called).
This function will register three callbacks into your driver:
'preempt', 'wakeup' and 'irq'. Each of these may be NULL in order to
indicate that you do not want a callback.

37
Documentation/pci.txt
View File

@ -274,8 +274,6 @@ the PCI device by calling pci_enable_device(). This will:
o allocate an IRQ (if BIOS did not).
NOTE: pci_enable_device() can fail! Check the return value.
NOTE2: Also see pci_enable_device_bars() below. Drivers can
attempt to enable only a subset of BARs they need.
[ OS BUG: we don't check resource allocations before enabling those
resources. The sequence would make more sense if we called
@ -605,40 +603,7 @@ device lists. This is still possible but discouraged.
10. pci_enable_device_bars() and Legacy I/O Port space
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Large servers may not be able to provide I/O port resources to all PCI
devices. I/O Port space is only 64KB on Intel Architecture[1] and is
likely also fragmented since the I/O base register of PCI-to-PCI
bridge will usually be aligned to a 4KB boundary[2]. On such systems,
pci_enable_device() and pci_request_region() will fail when
attempting to enable I/O Port regions that don't have I/O Port
resources assigned.
Fortunately, many PCI devices which request I/O Port resources also
provide access to the same registers via MMIO BARs. These devices can
be handled without using I/O port space and the drivers typically
offer a CONFIG_ option to only use MMIO regions
(e.g. CONFIG_TULIP_MMIO). PCI devices typically provide I/O port
interface for legacy OSes and will work when I/O port resources are not
assigned. The "PCI Local Bus Specification Revision 3.0" discusses
this on p.44, "IMPLEMENTATION NOTE".
If your PCI device driver doesn't need I/O port resources assigned to
I/O Port BARs, you should use pci_enable_device_bars() instead of
pci_enable_device() in order not to enable I/O port regions for the
corresponding devices. In addition, you should use
pci_request_selected_regions() and pci_release_selected_regions()
instead of pci_request_regions()/pci_release_regions() in order not to
request/release I/O port regions for the corresponding devices.
[1] Some systems support 64KB I/O port space per PCI segment.
[2] Some PCI-to-PCI bridges support optional 1KB aligned I/O base.
11. MMIO Space and "Write Posting"
10. MMIO Space and "Write Posting"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Converting a driver from using I/O Port space to using MMIO space

4
Documentation/pnp.txt
View File

@ -17,9 +17,9 @@ The User Interface
------------------
The Linux Plug and Play user interface provides a means to activate PnP devices
for legacy and user level drivers that do not support Linux Plug and Play. The
user interface is integrated into driverfs.
user interface is integrated into sysfs.
In addition to the standard driverfs file the following are created in each
In addition to the standard sysfs file the following are created in each
device's directory:
id - displays a list of support EISA IDs
options - displays possible resource configurations

212
Documentation/power/basic-pm-debugging.txt
View File

@ -1,45 +1,111 @@
Debugging suspend and resume
Debugging hibernation and suspend
(C) 2007 Rafael J. Wysocki <rjw@sisk.pl>, GPL
1. Testing suspend to disk (STD)
1. Testing hibernation (aka suspend to disk or STD)
To verify that the STD works, you can try to suspend in the "reboot" mode:
To check if hibernation works, you can try to hibernate in the "reboot" mode:
# echo reboot > /sys/power/disk
# echo disk > /sys/power/state
and the system should suspend, reboot, resume and get back to the command prompt
where you have started the transition. If that happens, the STD is most likely
to work correctly, but you need to repeat the test at least a couple of times in
a row for confidence. This is necessary, because some problems only show up on
a second attempt at suspending and resuming the system. You should also test
the "platform" and "shutdown" modes of suspend:
and the system should create a hibernation image, reboot, resume and get back to
the command prompt where you have started the transition. If that happens,
hibernation is most likely to work correctly. Still, you need to repeat the
test at least a couple of times in a row for confidence. [This is necessary,
because some problems only show up on a second attempt at suspending and
resuming the system.] Moreover, hibernating in the "reboot" and "shutdown"
modes causes the PM core to skip some platform-related callbacks which on ACPI
systems might be necessary to make hibernation work. Thus, if you machine fails
to hibernate or resume in the "reboot" mode, you should try the "platform" mode:
# echo platform > /sys/power/disk
# echo disk > /sys/power/state
or
which is the default and recommended mode of hibernation.
Unfortunately, the "platform" mode of hibernation does not work on some systems
with broken BIOSes. In such cases the "shutdown" mode of hibernation might
work:
# echo shutdown > /sys/power/disk
# echo disk > /sys/power/state
in which cases you will have to press the power button to make the system
resume. If that does not work, you will need to identify what goes wrong.
(it is similar to the "reboot" mode, but it requires you to press the power
button to make the system resume).
a) Test mode of STD
If neither "platform" nor "shutdown" hibernation mode works, you will need to
identify what goes wrong.
To verify if there are any drivers that cause problems you can run the STD
in the test mode:
a) Test modes of hibernation
# echo test > /sys/power/disk
To find out why hibernation fails on your system, you can use a special testing
facility available if the kernel is compiled with CONFIG_PM_DEBUG set. Then,
there is the file /sys/power/pm_test that can be used to make the hibernation
core run in a test mode. There are 5 test modes available:
freezer
- test the freezing of processes
devices
- test the freezing of processes and suspending of devices
platform
- test the freezing of processes, suspending of devices and platform
global control methods(*)
processors
- test the freezing of processes, suspending of devices, platform
global control methods(*) and the disabling of nonboot CPUs
core
- test the freezing of processes, suspending of devices, platform global
control methods(*), the disabling of nonboot CPUs and suspending of
platform/system devices
(*) the platform global control methods are only available on ACPI systems
and are only tested if the hibernation mode is set to "platform"
To use one of them it is necessary to write the corresponding string to
/sys/power/pm_test (eg. "devices" to test the freezing of processes and
suspending devices) and issue the standard hibernation commands. For example,
to use the "devices" test mode along with the "platform" mode of hibernation,
you should do the following:
# echo devices > /sys/power/pm_test
# echo platform > /sys/power/disk
# echo disk > /sys/power/state
in which case the system should freeze tasks, suspend devices, disable nonboot
CPUs (if any), wait for 5 seconds, enable nonboot CPUs, resume devices, thaw
tasks and return to your command prompt. If that fails, most likely there is
a driver that fails to either suspend or resume (in the latter case the system
may hang or be unstable after the test, so please take that into consideration).
To find this driver, you can carry out a binary search according to the rules:
Then, the kernel will try to freeze processes, suspend devices, wait 5 seconds,
resume devices and thaw processes. If "platform" is written to
/sys/power/pm_test , then after suspending devices the kernel will additionally
invoke the global control methods (eg. ACPI global control methods) used to
prepare the platform firmware for hibernation. Next, it will wait 5 seconds and
invoke the platform (eg. ACPI) global methods used to cancel hibernation etc.
Writing "none" to /sys/power/pm_test causes the kernel to switch to the normal
hibernation/suspend operations. Also, when open for reading, /sys/power/pm_test
contains a space-separated list of all available tests (including "none" that
represents the normal functionality) in which the current test level is
indicated by square brackets.
Generally, as you can see, each test level is more "invasive" than the previous
one and the "core" level tests the hardware and drivers as deeply as possible
without creating a hibernation image. Obviously, if the "devices" test fails,
the "platform" test will fail as well and so on. Thus, as a rule of thumb, you
should try the test modes starting from "freezer", through "devices", "platform"
and "processors" up to "core" (repeat the test on each level a couple of times
to make sure that any random factors are avoided).
If the "freezer" test fails, there is a task that cannot be frozen (in that case
it usually is possible to identify the offending task by analysing the output of
dmesg obtained after the failing test). Failure at this level usually means
that there is a problem with the tasks freezer subsystem that should be
reported.
If the "devices" test fails, most likely there is a driver that cannot suspend
or resume its device (in the latter case the system may hang or become unstable
after the test, so please take that into consideration). To find this driver,
you can carry out a binary search according to the rules:
- if the test fails, unload a half of the drivers currently loaded and repeat
(that would probably involve rebooting the system, so always note what drivers
have been loaded before the test),
@ -47,23 +113,46 @@ have been loaded before the test),
recently and repeat.
Once you have found the failing driver (there can be more than just one of
them), you have to unload it every time before the STD transition. In that case
please make sure to report the problem with the driver.
them), you have to unload it every time before hibernation. In that case please
make sure to report the problem with the driver.
It is also possible that a cycle can still fail after you have unloaded
all modules. In that case, you would want to look in your kernel configuration
for the drivers that can be compiled as modules (testing again with them as
modules), and possibly also try boot time options such as "noapic" or "noacpi".
It is also possible that the "devices" test will still fail after you have
unloaded all modules. In that case, you may want to look in your kernel
configuration for the drivers that can be compiled as modules (and test again
with these drivers compiled as modules). You may also try to use some special
kernel command line options such as "noapic", "noacpi" or even "acpi=off".
If the "platform" test fails, there is a problem with the handling of the
platform (eg. ACPI) firmware on your system. In that case the "platform" mode
of hibernation is not likely to work. You can try the "shutdown" mode, but that
is rather a poor man's workaround.
If the "processors" test fails, the disabling/enabling of nonboot CPUs does not
work (of course, this only may be an issue on SMP systems) and the problem
should be reported. In that case you can also try to switch the nonboot CPUs
off and on using the /sys/devices/system/cpu/cpu*/online sysfs attributes and
see if that works.
If the "core" test fails, which means that suspending of the system/platform
devices has failed (these devices are suspended on one CPU with interrupts off),
the problem is most probably hardware-related and serious, so it should be
reported.
A failure of any of the "platform", "processors" or "core" tests may cause your
system to hang or become unstable, so please beware. Such a failure usually
indicates a serious problem that very well may be related to the hardware, but
please report it anyway.
b) Testing minimal configuration
If the test mode of STD works, you can boot the system with "init=/bin/bash"
and attempt to suspend in the "reboot", "shutdown" and "platform" modes. If
that does not work, there probably is a problem with a driver statically
compiled into the kernel and you can try to compile more drivers as modules,
so that they can be tested individually. Otherwise, there is a problem with a
modular driver and you can find it by loading a half of the modules you normally
use and binary searching in accordance with the algorithm:
If all of the hibernation test modes work, you can boot the system with the
"init=/bin/bash" command line parameter and attempt to hibernate in the
"reboot", "shutdown" and "platform" modes. If that does not work, there
probably is a problem with a driver statically compiled into the kernel and you
can try to compile more drivers as modules, so that they can be tested
individually. Otherwise, there is a problem with a modular driver and you can
find it by loading a half of the modules you normally use and binary searching
in accordance with the algorithm:
- if there are n modules loaded and the attempt to suspend and resume fails,
unload n/2 of the modules and try again (that would probably involve rebooting
the system),
@ -71,19 +160,19 @@ the system),
load n/2 modules more and try again.
Again, if you find the offending module(s), it(they) must be unloaded every time
before the STD transition, and please report the problem with it(them).
before hibernation, and please report the problem with it(them).
c) Advanced debugging
In case the STD does not work on your system even in the minimal configuration
and compiling more drivers as modules is not practical or some modules cannot
be unloaded, you can use one of the more advanced debugging techniques to find
the problem. First, if there is a serial port in your box, you can boot the
kernel with the 'no_console_suspend' parameter and try to log kernel
messages using the serial console. This may provide you with some information
about the reasons of the suspend (resume) failure. Alternatively, it may be
possible to use a FireWire port for debugging with firescope
(ftp://ftp.firstfloor.org/pub/ak/firescope/). On i386 it is also possible to
In case that hibernation does not work on your system even in the minimal
configuration and compiling more drivers as modules is not practical or some
modules cannot be unloaded, you can use one of the more advanced debugging
techniques to find the problem. First, if there is a serial port in your box,
you can boot the kernel with the 'no_console_suspend' parameter and try to log
kernel messages using the serial console. This may provide you with some
information about the reasons of the suspend (resume) failure. Alternatively,
it may be possible to use a FireWire port for debugging with firescope
(ftp://ftp.firstfloor.org/pub/ak/firescope/). On x86 it is also possible to
use the PM_TRACE mechanism documented in Documentation/s2ram.txt .
2. Testing suspend to RAM (STR)
@ -91,16 +180,25 @@ use the PM_TRACE mechanism documented in Documentation/s2ram.txt .
To verify that the STR works, it is generally more convenient to use the s2ram
tool available from http://suspend.sf.net and documented at
http://en.opensuse.org/s2ram . However, before doing that it is recommended to
carry out the procedure described in section 1.
carry out STR testing using the facility described in section 1.
Assume you have resolved the problems with the STD and you have found some
failing drivers. These drivers are also likely to fail during the STR or
during the resume, so it is better to unload them every time before the STR
transition. Now, you can follow the instructions at
http://en.opensuse.org/s2ram to test the system, but if it does not work
"out of the box", you may need to boot it with "init=/bin/bash" and test
s2ram in the minimal configuration. In that case, you may be able to search
for failing drivers by following the procedure analogous to the one described in
1b). If you find some failing drivers, you will have to unload them every time
before the STR transition (ie. before you run s2ram), and please report the
problems with them.
Namely, after writing "freezer", "devices", "platform", "processors", or "core"
into /sys/power/pm_test (available if the kernel is compiled with
CONFIG_PM_DEBUG set) the suspend code will work in the test mode corresponding
to given string. The STR test modes are defined in the same way as for
hibernation, so please refer to Section 1 for more information about them. In
particular, the "core" test allows you to test everything except for the actual
invocation of the platform firmware in order to put the system into the sleep
state.
Among other things, the testing with the help of /sys/power/pm_test may allow
you to identify drivers that fail to suspend or resume their devices. They
should be unloaded every time before an STR transition.
Next, you can follow the instructions at http://en.opensuse.org/s2ram to test
the system, but if it does not work "out of the box", you may need to boot it
with "init=/bin/bash" and test s2ram in the minimal configuration. In that
case, you may be able to search for failing drivers by following the procedure
analogous to the one described in section 1. If you find some failing drivers,
you will have to unload them every time before an STR transition (ie. before
you run s2ram), and please report the problems with them.

49
Documentation/power/devices.txt
View File

@ -502,52 +502,3 @@ If the CPU can have a "cpufreq" driver, there also may be opportunities
to shift to lower voltage settings and reduce the power cost of executing
a given number of instructions. (Without voltage adjustment, it's rare
for cpufreq to save much power; the cost-per-instruction must go down.)
/sys/devices/.../power/state files
==================================
For now you can also test some of this functionality using sysfs.
DEPRECATED: USE "power/state" ONLY FOR DRIVER TESTING, AND
AVOID USING dev->power.power_state IN DRIVERS.
THESE WILL BE REMOVED. IF THE "power/state" FILE GETS REPLACED,
IT WILL BECOME SOMETHING COUPLED TO THE BUS OR DRIVER.
In each device's directory, there is a 'power' directory, which contains
at least a 'state' file. The value of this field is effectively boolean,
PM_EVENT_ON or PM_EVENT_SUSPEND.
* Reading from this file displays a value corresponding to
the power.power_state.event field. All nonzero values are
displayed as "2", corresponding to a low power state; zero
is displayed as "0", corresponding to normal operation.
* Writing to this file initiates a transition using the
specified event code number; only '0', '2', and '3' are
accepted (without a newline); '2' and '3' are both
mapped to PM_EVENT_SUSPEND.
On writes, the PM core relies on that recorded event code and the device/bus
capabilities to determine whether it uses a partial suspend() or resume()
sequence to change things so that the recorded event corresponds to the
numeric parameter.
- If the bus requires the irqs-disabled suspend_late()/resume_early()
phases, writes fail because those operations are not supported here.
- If the recorded value is the expected value, nothing is done.
- If the recorded value is nonzero, the device is partially resumed,
using the bus.resume() and/or class.resume() methods.
- If the target value is nonzero, the device is partially suspended,
using the class.suspend() and/or bus.suspend() methods and the
PM_EVENT_SUSPEND message.
Drivers have no way to tell whether their suspend() and resume() calls
have come through the sysfs power/state file or as part of entering a
system sleep state, except that when accessed through sysfs the normal
parent/child sequencing rules are ignored. Drivers (such as bus, bridge,
or hub drivers) which expose child devices may need to enforce those rules
on their own.

30
Documentation/power/drivers-testing.txt
View File

@ -6,9 +6,9 @@ Testing suspend and resume support in device drivers
Unfortunately, to effectively test the support for the system-wide suspend and
resume transitions in a driver, it is necessary to suspend and resume a fully
functional system with this driver loaded. Moreover, that should be done
several times, preferably several times in a row, and separately for the suspend
to disk (STD) and the suspend to RAM (STR) transitions, because each of these
cases involves different ordering of operations and different interactions with
several times, preferably several times in a row, and separately for hibernation
(aka suspend to disk or STD) and suspend to RAM (STR), because each of these
cases involves slightly different operations and different interactions with
the machine's BIOS.
Of course, for this purpose the test system has to be known to suspend and
@ -22,20 +22,24 @@ for more information about the debugging of suspend/resume functionality.
Once you have resolved the suspend/resume-related problems with your test system
without the new driver, you are ready to test it:
a) Build the driver as a module, load it and try the STD in the test mode (see:
Documents/power/basic-pm-debugging.txt, 1a)).
a) Build the driver as a module, load it and try the test modes of hibernation
(see: Documents/power/basic-pm-debugging.txt, 1).
b) Load the driver and attempt to suspend to disk in the "reboot", "shutdown"
and "platform" modes (see: Documents/power/basic-pm-debugging.txt, 1).
b) Load the driver and attempt to hibernate in the "reboot", "shutdown" and
"platform" modes (see: Documents/power/basic-pm-debugging.txt, 1).
c) Compile the driver directly into the kernel and try the STD in the test mode.
c) Compile the driver directly into the kernel and try the test modes of
hibernation.
d) Attempt to suspend to disk with the driver compiled directly into the kernel
in the "reboot", "shutdown" and "platform" modes.
d) Attempt to hibernate with the driver compiled directly into the kernel
in the "reboot", "shutdown" and "platform" modes.
e) Attempt to suspend to RAM using the s2ram tool with the driver loaded (see:
Documents/power/basic-pm-debugging.txt, 2). As far as the STR tests are
concerned, it should not matter whether or not the driver is built as a module.
e) Try the test modes of suspend (see: Documents/power/basic-pm-debugging.txt,
2). [As far as the STR tests are concerned, it should not matter whether or
not the driver is built as a module.]
f) Attempt to suspend to RAM using the s2ram tool with the driver loaded
(see: Documents/power/basic-pm-debugging.txt, 2).
Each of the above tests should be repeated several times and the STD tests
should be mixed with the STR tests. If any of them fails, the driver cannot be

8
Documentation/power/notifiers.txt
View File

@ -28,6 +28,14 @@ PM_POST_HIBERNATION The system memory state has been restored from a
hibernation. Device drivers' .resume() callbacks have
been executed and tasks have been thawed.
PM_RESTORE_PREPARE The system is going to restore a hibernation image.
If all goes well the restored kernel will issue a
PM_POST_HIBERNATION notification.
PM_POST_RESTORE An error occurred during the hibernation restore.
Device drivers' .resume() callbacks have been executed
and tasks have been thawed.
PM_SUSPEND_PREPARE The system is preparing for a suspend.
PM_POST_SUSPEND The system has just resumed or an error occured during

82
Documentation/power/userland-swsusp.txt
View File

@ -14,7 +14,7 @@ are going to develop your own suspend/resume utilities.
The interface consists of a character device providing the open(),
release(), read(), and write() operations as well as several ioctl()
commands defined in kernel/power/power.h. The major and minor
commands defined in include/linux/suspend_ioctls.h . The major and minor
numbers of the device are, respectively, 10 and 231, and they can
be read from /sys/class/misc/snapshot/dev.
@ -27,17 +27,17 @@ once at a time.
The ioctl() commands recognized by the device are:
SNAPSHOT_FREEZE - freeze user space processes (the current process is
not frozen); this is required for SNAPSHOT_ATOMIC_SNAPSHOT
not frozen); this is required for SNAPSHOT_CREATE_IMAGE
and SNAPSHOT_ATOMIC_RESTORE to succeed
SNAPSHOT_UNFREEZE - thaw user space processes frozen by SNAPSHOT_FREEZE
SNAPSHOT_ATOMIC_SNAPSHOT - create a snapshot of the system memory; the
SNAPSHOT_CREATE_IMAGE - create a snapshot of the system memory; the
last argument of ioctl() should be a pointer to an int variable,
the value of which will indicate whether the call returned after
creating the snapshot (1) or after restoring the system memory state
from it (0) (after resume the system finds itself finishing the
SNAPSHOT_ATOMIC_SNAPSHOT ioctl() again); after the snapshot
SNAPSHOT_CREATE_IMAGE ioctl() again); after the snapshot
has been created the read() operation can be used to transfer
it out of the kernel
@ -49,39 +49,37 @@ SNAPSHOT_ATOMIC_RESTORE - restore the system memory state from the
SNAPSHOT_FREE - free memory allocated for the snapshot image
SNAPSHOT_SET_IMAGE_SIZE - set the preferred maximum size of the image
SNAPSHOT_PREF_IMAGE_SIZE - set the preferred maximum size of the image
(the kernel will do its best to ensure the image size will not exceed
this number, but if it turns out to be impossible, the kernel will
create the smallest image possible)
SNAPSHOT_AVAIL_SWAP - return the amount of available swap in bytes (the last
argument should be a pointer to an unsigned int variable that will
SNAPSHOT_GET_IMAGE_SIZE - return the actual size of the hibernation image
SNAPSHOT_AVAIL_SWAP_SIZE - return the amount of available swap in bytes (the
last argument should be a pointer to an unsigned int variable that will
contain the result if the call is successful).
SNAPSHOT_GET_SWAP_PAGE - allocate a swap page from the resume partition
SNAPSHOT_ALLOC_SWAP_PAGE - allocate a swap page from the resume partition
(the last argument should be a pointer to a loff_t variable that
will contain the swap page offset if the call is successful)
SNAPSHOT_FREE_SWAP_PAGES - free all swap pages allocated with
SNAPSHOT_GET_SWAP_PAGE
SNAPSHOT_SET_SWAP_FILE - set the resume partition (the last ioctl() argument
should specify the device's major and minor numbers in the old
two-byte format, as returned by the stat() function in the .st_rdev
member of the stat structure)
SNAPSHOT_FREE_SWAP_PAGES - free all swap pages allocated by
SNAPSHOT_ALLOC_SWAP_PAGE
SNAPSHOT_SET_SWAP_AREA - set the resume partition and the offset (in <PAGE_SIZE>
units) from the beginning of the partition at which the swap header is
located (the last ioctl() argument should point to a struct
resume_swap_area, as defined in kernel/power/power.h, containing the
resume device specification, as for the SNAPSHOT_SET_SWAP_FILE ioctl(),
and the offset); for swap partitions the offset is always 0, but it is
different to zero for swap files (please see
Documentation/swsusp-and-swap-files.txt for details).
The SNAPSHOT_SET_SWAP_AREA ioctl() is considered as a replacement for
SNAPSHOT_SET_SWAP_FILE which is regarded as obsolete. It is
recommended to always use this call, because the code to set the resume
partition may be removed from future kernels
resume_swap_area, as defined in kernel/power/suspend_ioctls.h,
containing the resume device specification and the offset); for swap
partitions the offset is always 0, but it is different from zero for
swap files (see Documentation/swsusp-and-swap-files.txt for details).
SNAPSHOT_PLATFORM_SUPPORT - enable/disable the hibernation platform support,
depending on the argument value (enable, if the argument is nonzero)
SNAPSHOT_POWER_OFF - make the kernel transition the system to the hibernation
state (eg. ACPI S4) using the platform (eg. ACPI) driver
SNAPSHOT_S2RAM - suspend to RAM; using this call causes the kernel to
immediately enter the suspend-to-RAM state, so this call must always
@ -93,24 +91,6 @@ SNAPSHOT_S2RAM - suspend to RAM; using this call causes the kernel to
to resume the system from RAM if there's enough battery power or restore
its state on the basis of the saved suspend image otherwise)
SNAPSHOT_PMOPS - enable the usage of the hibernation_ops->prepare,
hibernate_ops->enter and hibernation_ops->finish methods (the in-kernel
swsusp knows these as the "platform method") which are needed on many
machines to (among others) speed up the resume by letting the BIOS skip
some steps or to let the system recognise the correct state of the
hardware after the resume (in particular on many machines this ensures
that unplugged AC adapters get correctly detected and that kacpid does
not run wild after the resume). The last ioctl() argument can take one
of the three values, defined in kernel/power/power.h:
PMOPS_PREPARE - make the kernel carry out the
hibernation_ops->prepare() operation
PMOPS_ENTER - make the kernel power off the system by calling
hibernation_ops->enter()
PMOPS_FINISH - make the kernel carry out the
hibernation_ops->finish() operation
Note that the actual constants are misnamed because they surface
internal kernel implementation details that have changed.
The device's read() operation can be used to transfer the snapshot image from
the kernel. It has the following limitations:
- you cannot read() more than one virtual memory page at a time
@ -122,7 +102,7 @@ The device's write() operation is used for uploading the system memory snapshot
into the kernel. It has the same limitations as the read() operation.
The release() operation frees all memory allocated for the snapshot image
and all swap pages allocated with SNAPSHOT_GET_SWAP_PAGE (if any).
and all swap pages allocated with SNAPSHOT_ALLOC_SWAP_PAGE (if any).
Thus it is not necessary to use either SNAPSHOT_FREE or
SNAPSHOT_FREE_SWAP_PAGES before closing the device (in fact it will also
unfreeze user space processes frozen by SNAPSHOT_UNFREEZE if they are
@ -133,16 +113,12 @@ snapshot image from/to the kernel will use a swap parition, called the resume
partition, or a swap file as storage space (if a swap file is used, the resume
partition is the partition that holds this file). However, this is not really
required, as they can use, for example, a special (blank) suspend partition or
a file on a partition that is unmounted before SNAPSHOT_ATOMIC_SNAPSHOT and
a file on a partition that is unmounted before SNAPSHOT_CREATE_IMAGE and
mounted afterwards.
These utilities SHOULD NOT make any assumptions regarding the ordering of
data within the snapshot image, except for the image header that MAY be
assumed to start with an swsusp_info structure, as specified in
kernel/power/power.h. This structure MAY be used by the userland utilities
to obtain some information about the snapshot image, such as the size
of the snapshot image, including the metadata and the header itself,
contained in the .size member of swsusp_info.
These utilities MUST NOT make any assumptions regarding the ordering of
data within the snapshot image. The contents of the image are entirely owned
by the kernel and its structure may be changed in future kernel releases.
The snapshot image MUST be written to the kernel unaltered (ie. all of the image
data, metadata and header MUST be written in _exactly_ the same amount, form
@ -159,7 +135,7 @@ means, such as checksums, to ensure the integrity of the snapshot image.
The suspending and resuming utilities MUST lock themselves in memory,
preferrably using mlockall(), before calling SNAPSHOT_FREEZE.
The suspending utility MUST check the value stored by SNAPSHOT_ATOMIC_SNAPSHOT
The suspending utility MUST check the value stored by SNAPSHOT_CREATE_IMAGE
in the memory location pointed to by the last argument of ioctl() and proceed
in accordance with it:
1. If the value is 1 (ie. the system memory snapshot has just been
@ -173,7 +149,7 @@ in accordance with it:
image has been saved.
(b) The suspending utility SHOULD NOT attempt to perform any
file system operations (including reads) on the file systems
that were mounted before SNAPSHOT_ATOMIC_SNAPSHOT has been
that were mounted before SNAPSHOT_CREATE_IMAGE has been
called. However, it MAY mount a file system that was not
mounted at that time and perform some operations on it (eg.
use it for saving the image).

6
Documentation/power_supply_class.txt
View File

@ -87,6 +87,10 @@ batteries use voltage for very approximated calculation of capacity.
Battery driver also can use this attribute just to inform userspace
about maximal and minimal voltage thresholds of a given battery.
VOLTAGE_MAX, VOLTAGE_MIN - same as _DESIGN voltage values except that
these ones should be used if hardware could only guess (measure and
retain) the thresholds of a given power supply.
CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - design charge values, when
battery considered full/empty.
@ -100,8 +104,6 @@ age)". I.e. these attributes represents real thresholds, not design values.
ENERGY_FULL, ENERGY_EMPTY - same as above but for energy.
CAPACITY - capacity in percents.
CAPACITY_LEVEL - capacity level. This corresponds to
POWER_SUPPLY_CAPACITY_LEVEL_*.
TEMP - temperature of the power supply.
TEMP_AMBIENT - ambient temperature.

3
Documentation/powerpc/00-INDEX
View File

@ -28,3 +28,6 @@ sound.txt
- info on sound support under Linux/PPC
zImage_layout.txt
- info on the kernel images for Linux/PPC
qe_firmware.txt
- describes the layout of firmware binaries for the Freescale QUICC
Engine and the code that parses and uploads the microcode therein.

597
Documentation/powerpc/booting-without-of.txt
View File

@ -52,6 +52,11 @@ Table of Contents
i) Freescale QUICC Engine module (QE)
j) CFI or JEDEC memory-mapped NOR flash
k) Global Utilities Block
l) Freescale Communications Processor Module
m) Chipselect/Local Bus
n) 4xx/Axon EMAC ethernet nodes
o) Xilinx IP cores
p) Freescale Synchronous Serial Interface
VII - Specifying interrupt information for devices
1) interrupts property
@ -670,10 +675,10 @@ device or bus to be described by the device tree.
In general, the format of an address for a device is defined by the
parent bus type, based on the #address-cells and #size-cells
property. In the absence of such a property, the parent's parent
values are used, etc... The kernel requires the root node to have
those properties defining addresses format for devices directly mapped
on the processor bus.
properties. Note that the parent's parent definitions of #address-cells
and #size-cells are not inhereted so every node with children must specify
them. The kernel requires the root node to have those properties defining
addresses format for devices directly mapped on the processor bus.
Those 2 properties define 'cells' for representing an address and a
size. A "cell" is a 32-bit number. For example, if both contain 2
@ -710,13 +715,14 @@ define a bus type with a more complex address format, including things
like address space bits, you'll have to add a bus translator to the
prom_parse.c file of the recent kernels for your bus type.
The "reg" property only defines addresses and sizes (if #size-cells
is non-0) within a given bus. In order to translate addresses upward
The "reg" property only defines addresses and sizes (if #size-cells is
non-0) within a given bus. In order to translate addresses upward
(that is into parent bus addresses, and possibly into CPU physical
addresses), all busses must contain a "ranges" property. If the
"ranges" property is missing at a given level, it's assumed that
translation isn't possible. The format of the "ranges" property for a
bus is a list of:
translation isn't possible, i.e., the registers are not visible on the
parent bus. The format of the "ranges" property for a bus is a list
of:
bus address, parent bus address, size
@ -734,6 +740,10 @@ fit in a single 32-bit word. New 32-bit powerpc boards should use a
1/1 format, unless the processor supports physical addresses greater
than 32-bits, in which case a 2/1 format is recommended.
Alternatively, the "ranges" property may be empty, indicating that the
registers are visible on the parent bus using an identity mapping
translation. In other words, the parent bus address space is the same
as the child bus address space.
2) Note about "compatible" properties
-------------------------------------
@ -851,12 +861,18 @@ address which can extend beyond that limit.
/cpus/PowerPC,970FX@0
/cpus/PowerPC,970FX@1
(unit addresses do not require leading zeroes)
- d-cache-line-size : one cell, L1 data cache line size in bytes
- i-cache-line-size : one cell, L1 instruction cache line size in
- d-cache-block-size : one cell, L1 data cache block size in bytes (*)
- i-cache-block-size : one cell, L1 instruction cache block size in
bytes
- d-cache-size : one cell, size of L1 data cache in bytes
- i-cache-size : one cell, size of L1 instruction cache in bytes
(*) The cache "block" size is the size on which the cache management
instructions operate. Historically, this document used the cache
"line" size here which is incorrect. The kernel will prefer the cache
block size and will fallback to cache line size for backward
compatibility.
Recommended properties:
- timebase-frequency : a cell indicating the frequency of the
@ -870,6 +886,10 @@ address which can extend beyond that limit.
for the above, the common code doesn't use that property, but
you are welcome to re-use the pSeries or Maple one. A future
kernel version might provide a common function for this.
- d-cache-line-size : one cell, L1 data cache line size in bytes
if different from the block size
- i-cache-line-size : one cell, L1 instruction cache line size in
bytes if different from the block size
You are welcome to add any property you find relevant to your board,
like some information about the mechanism used to soft-reset the
@ -1207,16 +1227,14 @@ platforms are moved over to use the flattened-device-tree model.
Required properties:
- reg : Offset and length of the register set for the device
- device_type : Should be "mdio"
- compatible : Should define the compatible device type for the
mdio. Currently, this is most likely to be "gianfar"
mdio. Currently, this is most likely to be "fsl,gianfar-mdio"
Example:
mdio@24520 {
reg = <24520 20>;
device_type = "mdio";
compatible = "gianfar";
compatible = "fsl,gianfar-mdio";
ethernet-phy@0 {
......
@ -1243,6 +1261,10 @@ platforms are moved over to use the flattened-device-tree model.
services interrupts for this device.
- phy-handle : The phandle for the PHY connected to this ethernet
controller.
- fixed-link : <a b c d e> where a is emulated phy id - choose any,
but unique to the all specified fixed-links, b is duplex - 0 half,
1 full, c is link speed - d#10/d#100/d#1000, d is pause - 0 no
pause, 1 pause, e is asym_pause - 0 no asym_pause, 1 asym_pause.
Recommended properties:
@ -1397,7 +1419,6 @@ platforms are moved over to use the flattened-device-tree model.
Example multi port host USB controller device node :
usb@22000 {
device_type = "usb";
compatible = "fsl-usb2-mph";
reg = <22000 1000>;
#address-cells = <1>;
@ -1411,7 +1432,6 @@ platforms are moved over to use the flattened-device-tree model.
Example dual role USB controller device node :
usb@23000 {
device_type = "usb";
compatible = "fsl-usb2-dr";
reg = <23000 1000>;
#address-cells = <1>;
@ -1523,7 +1543,7 @@ platforms are moved over to use the flattened-device-tree model.
i) Root QE device
Required properties:
- device_type : should be "qe";
- compatible : should be "fsl,qe";
- model : precise model of the QE, Can be "QE", "CPM", or "CPM2"
- reg : offset and length of the device registers.
- bus-frequency : the clock frequency for QUICC Engine.
@ -1537,8 +1557,7 @@ platforms are moved over to use the flattened-device-tree model.
#address-cells = <1>;
#size-cells = <1>;
#interrupt-cells = <2>;
device_type = "qe";
model = "QE";
compatible = "fsl,qe";
ranges = <0 e0100000 00100000>;
reg = <e0100000 480>;
brg-frequency = <0>;
@ -1549,8 +1568,8 @@ platforms are moved over to use the flattened-device-tree model.
ii) SPI (Serial Peripheral Interface)
Required properties:
- device_type : should be "spi".
- compatible : should be "fsl_spi".
- cell-index : SPI controller index.
- compatible : should be "fsl,spi".
- mode : the SPI operation mode, it can be "cpu" or "cpu-qe".
- reg : Offset and length of the register set for the device
- interrupts : <a b> where a is the interrupt number and b is a
@ -1563,8 +1582,8 @@ platforms are moved over to use the flattened-device-tree model.
Example:
spi@4c0 {
device_type = "spi";
compatible = "fsl_spi";
cell-index = <0>;
compatible = "fsl,spi";
reg = <4c0 40>;
interrupts = <82 0>;
interrupt-parent = <700>;
@ -1575,7 +1594,6 @@ platforms are moved over to use the flattened-device-tree model.
iii) USB (Universal Serial Bus Controller)
Required properties:
- device_type : should be "usb".
- compatible : could be "qe_udc" or "fhci-hcd".
- mode : the could be "host" or "slave".
- reg : Offset and length of the register set for the device
@ -1589,7 +1607,6 @@ platforms are moved over to use the flattened-device-tree model.
Example(slave):
usb@6c0 {
device_type = "usb";
compatible = "qe_udc";
reg = <6c0 40>;
interrupts = <8b 0>;
@ -1602,7 +1619,7 @@ platforms are moved over to use the flattened-device-tree model.
Required properties:
- device_type : should be "network", "hldc", "uart", "transparent"
"bisync" or "atm".
"bisync", "atm", or "serial".
- compatible : could be "ucc_geth" or "fsl_atm" and so on.
- model : should be "UCC".
- device-id : the ucc number(1-8), corresponding to UCCx in UM.
@ -1615,6 +1632,26 @@ platforms are moved over to use the flattened-device-tree model.
- interrupt-parent : the phandle for the interrupt controller that
services interrupts for this device.
- pio-handle : The phandle for the Parallel I/O port configuration.
- port-number : for UART drivers, the port number to use, between 0 and 3.
This usually corresponds to the /dev/ttyQE device, e.g. <0> = /dev/ttyQE0.
The port number is added to the minor number of the device. Unlike the
CPM UART driver, the port-number is required for the QE UART driver.
- soft-uart : for UART drivers, if specified this means the QE UART device
driver should use "Soft-UART" mode, which is needed on some SOCs that have
broken UART hardware. Soft-UART is provided via a microcode upload.
- rx-clock-name: the UCC receive clock source
"none": clock source is disabled
"brg1" through "brg16": clock source is BRG1-BRG16, respectively
"clk1" through "clk24": clock source is CLK1-CLK24, respectively
- tx-clock-name: the UCC transmit clock source
"none": clock source is disabled
"brg1" through "brg16": clock source is BRG1-BRG16, respectively
"clk1" through "clk24": clock source is CLK1-CLK24, respectively
The following two properties are deprecated. rx-clock has been replaced
with rx-clock-name, and tx-clock has been replaced with tx-clock-name.
Drivers that currently use the deprecated properties should continue to
do so, in order to support older device trees, but they should be updated
to check for the new properties first.
- rx-clock : represents the UCC receive clock source.
0x00 : clock source is disabled;
0x1~0x10 : clock source is BRG1~BRG16 respectively;
@ -1634,8 +1671,9 @@ platforms are moved over to use the flattened-device-tree model.
MAC addresses passed by the firmware when no information other
than indices is available to associate an address with a device.
- phy-connection-type : a string naming the controller/PHY interface type,
i.e., "mii" (default), "rmii", "gmii", "rgmii", "rgmii-id", "tbi",
or "rtbi".
i.e., "mii" (default), "rmii", "gmii", "rgmii", "rgmii-id" (Internal
Delay), "rgmii-txid" (delay on TX only), "rgmii-rxid" (delay on RX only),
"tbi", or "rtbi".
Example:
ucc@2000 {
@ -1742,7 +1780,7 @@ platforms are moved over to use the flattened-device-tree model.
vii) Multi-User RAM (MURAM)
Required properties:
- device_type : should be "muram".
- compatible : should be "fsl,qe-muram", "fsl,cpm-muram".
- mode : the could be "host" or "slave".
- ranges : Should be defined as specified in 1) to describe the
translation of MURAM addresses.
@ -1752,14 +1790,42 @@ platforms are moved over to use the flattened-device-tree model.
Example:
muram@10000 {
device_type = "muram";
compatible = "fsl,qe-muram", "fsl,cpm-muram";
ranges = <0 00010000 0000c000>;
data-only@0{
compatible = "fsl,qe-muram-data",
"fsl,cpm-muram-data";
reg = <0 c000>;
};
};
viii) Uploaded QE firmware
If a new firwmare has been uploaded to the QE (usually by the
boot loader), then a 'firmware' child node should be added to the QE
node. This node provides information on the uploaded firmware that
device drivers may need.
Required properties:
- id: The string name of the firmware. This is taken from the 'id'
member of the qe_firmware structure of the uploaded firmware.
Device drivers can search this string to determine if the
firmware they want is already present.
- extended-modes: The Extended Modes bitfield, taken from the
firmware binary. It is a 64-bit number represented
as an array of two 32-bit numbers.
- virtual-traps: The virtual traps, taken from the firmware binary.
It is an array of 8 32-bit numbers.
Example:
firmware {
id = "Soft-UART";
extended-modes = <0 0>;
virtual-traps = <0 0 0 0 0 0 0 0>;
}
j) CFI or JEDEC memory-mapped NOR flash
Flash chips (Memory Technology Devices) are often used for solid state
@ -2063,8 +2129,7 @@ platforms are moved over to use the flattened-device-tree model.
Example:
localbus@f0010100 {
compatible = "fsl,mpc8272ads-localbus",
"fsl,mpc8272-localbus",
compatible = "fsl,mpc8272-localbus",
"fsl,pq2-localbus";
#address-cells = <2>;
#size-cells = <1>;
@ -2242,6 +2307,474 @@ platforms are moved over to use the flattened-device-tree model.
available.
For Axon: 0x0000012a
o) Xilinx IP cores
The Xilinx EDK toolchain ships with a set of IP cores (devices) for use
in Xilinx Spartan and Virtex FPGAs. The devices cover the whole range
of standard device types (network, serial, etc.) and miscellanious
devices (gpio, LCD, spi, etc). Also, since these devices are
implemented within the fpga fabric every instance of the device can be
synthesised with different options that change the behaviour.
Each IP-core has a set of parameters which the FPGA designer can use to
control how the core is synthesized. Historically, the EDK tool would
extract the device parameters relevant to device drivers and copy them
into an 'xparameters.h' in the form of #define symbols. This tells the
device drivers how the IP cores are configured, but it requres the kernel
to be recompiled every time the FPGA bitstream is resynthesized.
The new approach is to export the parameters into the device tree and
generate a new device tree each time the FPGA bitstream changes. The
parameters which used to be exported as #defines will now become
properties of the device node. In general, device nodes for IP-cores
will take the following form:
(name): (generic-name)@(base-address) {
compatible = "xlnx,(ip-core-name)-(HW_VER)"
[, (list of compatible devices), ...];
reg = <(baseaddr) (size)>;
interrupt-parent = <&interrupt-controller-phandle>;
interrupts = < ... >;
xlnx,(parameter1) = "(string-value)";
xlnx,(parameter2) = <(int-value)>;
};
(generic-name): an open firmware-style name that describes the
generic class of device. Preferably, this is one word, such
as 'serial' or 'ethernet'.
(ip-core-name): the name of the ip block (given after the BEGIN
directive in system.mhs). Should be in lowercase
and all underscores '_' converted to dashes '-'.
(name): is derived from the "PARAMETER INSTANCE" value.
(parameter#): C_* parameters from system.mhs. The C_ prefix is
dropped from the parameter name, the name is converted
to lowercase and all underscore '_' characters are
converted to dashes '-'.
(baseaddr): the baseaddr parameter value (often named C_BASEADDR).
(HW_VER): from the HW_VER parameter.
(size): the address range size (often C_HIGHADDR - C_BASEADDR + 1).
Typically, the compatible list will include the exact IP core version
followed by an older IP core version which implements the same
interface or any other device with the same interface.
'reg', 'interrupt-parent' and 'interrupts' are all optional properties.
For example, the following block from system.mhs:
BEGIN opb_uartlite
PARAMETER INSTANCE = opb_uartlite_0
PARAMETER HW_VER = 1.00.b
PARAMETER C_BAUDRATE = 115200
PARAMETER C_DATA_BITS = 8
PARAMETER C_ODD_PARITY = 0
PARAMETER C_USE_PARITY = 0
PARAMETER C_CLK_FREQ = 50000000
PARAMETER C_BASEADDR = 0xEC100000
PARAMETER C_HIGHADDR = 0xEC10FFFF
BUS_INTERFACE SOPB = opb_7
PORT OPB_Clk = CLK_50MHz
PORT Interrupt = opb_uartlite_0_Interrupt
PORT RX = opb_uartlite_0_RX
PORT TX = opb_uartlite_0_TX
PORT OPB_Rst = sys_bus_reset_0
END
becomes the following device tree node:
opb_uartlite_0: serial@ec100000 {
device_type = "serial";
compatible = "xlnx,opb-uartlite-1.00.b";
reg = <ec100000 10000>;
interrupt-parent = <&opb_intc_0>;
interrupts = <1 0>; // got this from the opb_intc parameters
current-speed = <d#115200>; // standard serial device prop
clock-frequency = <d#50000000>; // standard serial device prop
xlnx,data-bits = <8>;
xlnx,odd-parity = <0>;
xlnx,use-parity = <0>;
};
Some IP cores actually implement 2 or more logical devices. In
this case, the device should still describe the whole IP core with
a single node and add a child node for each logical device. The
ranges property can be used to translate from parent IP-core to the
registers of each device. In addition, the parent node should be
compatible with the bus type 'xlnx,compound', and should contain
#address-cells and #size-cells, as with any other bus. (Note: this
makes the assumption that both logical devices have the same bus
binding. If this is not true, then separate nodes should be used
for each logical device). The 'cell-index' property can be used to
enumerate logical devices within an IP core. For example, the
following is the system.mhs entry for the dual ps2 controller found
on the ml403 reference design.
BEGIN opb_ps2_dual_ref
PARAMETER INSTANCE = opb_ps2_dual_ref_0
PARAMETER HW_VER = 1.00.a
PARAMETER C_BASEADDR = 0xA9000000
PARAMETER C_HIGHADDR = 0xA9001FFF
BUS_INTERFACE SOPB = opb_v20_0
PORT Sys_Intr1 = ps2_1_intr
PORT Sys_Intr2 = ps2_2_intr
PORT Clkin1 = ps2_clk_rx_1
PORT Clkin2 = ps2_clk_rx_2
PORT Clkpd1 = ps2_clk_tx_1
PORT Clkpd2 = ps2_clk_tx_2
PORT Rx1 = ps2_d_rx_1
PORT Rx2 = ps2_d_rx_2
PORT Txpd1 = ps2_d_tx_1
PORT Txpd2 = ps2_d_tx_2
END
It would result in the following device tree nodes:
opb_ps2_dual_ref_0: opb-ps2-dual-ref@a9000000 {
#address-cells = <1>;
#size-cells = <1>;
compatible = "xlnx,compound";
ranges = <0 a9000000 2000>;
// If this device had extra parameters, then they would
// go here.
ps2@0 {
compatible = "xlnx,opb-ps2-dual-ref-1.00.a";
reg = <0 40>;
interrupt-parent = <&opb_intc_0>;
interrupts = <3 0>;
cell-index = <0>;
};
ps2@1000 {
compatible = "xlnx,opb-ps2-dual-ref-1.00.a";
reg = <1000 40>;
interrupt-parent = <&opb_intc_0>;
interrupts = <3 0>;
cell-index = <0>;
};
};
Also, the system.mhs file defines bus attachments from the processor
to the devices. The device tree structure should reflect the bus
attachments. Again an example; this system.mhs fragment:
BEGIN ppc405_virtex4
PARAMETER INSTANCE = ppc405_0
PARAMETER HW_VER = 1.01.a
BUS_INTERFACE DPLB = plb_v34_0
BUS_INTERFACE IPLB = plb_v34_0
END
BEGIN opb_intc
PARAMETER INSTANCE = opb_intc_0
PARAMETER HW_VER = 1.00.c
PARAMETER C_BASEADDR = 0xD1000FC0
PARAMETER C_HIGHADDR = 0xD1000FDF
BUS_INTERFACE SOPB = opb_v20_0
END
BEGIN opb_uart16550
PARAMETER INSTANCE = opb_uart16550_0
PARAMETER HW_VER = 1.00.d
PARAMETER C_BASEADDR = 0xa0000000
PARAMETER C_HIGHADDR = 0xa0001FFF
BUS_INTERFACE SOPB = opb_v20_0
END
BEGIN plb_v34
PARAMETER INSTANCE = plb_v34_0
PARAMETER HW_VER = 1.02.a
END
BEGIN plb_bram_if_cntlr
PARAMETER INSTANCE = plb_bram_if_cntlr_0
PARAMETER HW_VER = 1.00.b
PARAMETER C_BASEADDR = 0xFFFF0000
PARAMETER C_HIGHADDR = 0xFFFFFFFF
BUS_INTERFACE SPLB = plb_v34_0
END
BEGIN plb2opb_bridge
PARAMETER INSTANCE = plb2opb_bridge_0
PARAMETER HW_VER = 1.01.a
PARAMETER C_RNG0_BASEADDR = 0x20000000
PARAMETER C_RNG0_HIGHADDR = 0x3FFFFFFF
PARAMETER C_RNG1_BASEADDR = 0x60000000
PARAMETER C_RNG1_HIGHADDR = 0x7FFFFFFF
PARAMETER C_RNG2_BASEADDR = 0x80000000
PARAMETER C_RNG2_HIGHADDR = 0xBFFFFFFF
PARAMETER C_RNG3_BASEADDR = 0xC0000000
PARAMETER C_RNG3_HIGHADDR = 0xDFFFFFFF
BUS_INTERFACE SPLB = plb_v34_0
BUS_INTERFACE MOPB = opb_v20_0
END
Gives this device tree (some properties removed for clarity):
plb@0 {
#address-cells = <1>;
#size-cells = <1>;
compatible = "xlnx,plb-v34-1.02.a";
device_type = "ibm,plb";
ranges; // 1:1 translation
plb_bram_if_cntrl_0: bram@ffff0000 {
reg = <ffff0000 10000>;
}
opb@20000000 {
#address-cells = <1>;
#size-cells = <1>;
ranges = <20000000 20000000 20000000
60000000 60000000 20000000
80000000 80000000 40000000
c0000000 c0000000 20000000>;
opb_uart16550_0: serial@a0000000 {
reg = <a00000000 2000>;
};
opb_intc_0: interrupt-controller@d1000fc0 {
reg = <d1000fc0 20>;
};
};
};
That covers the general approach to binding xilinx IP cores into the
device tree. The following are bindings for specific devices:
i) Xilinx ML300 Framebuffer
Simple framebuffer device from the ML300 reference design (also on the
ML403 reference design as well as others).
Optional properties:
- resolution = <xres yres> : pixel resolution of framebuffer. Some
implementations use a different resolution.
Default is <d#640 d#480>
- virt-resolution = <xvirt yvirt> : Size of framebuffer in memory.
Default is <d#1024 d#480>.
- rotate-display (empty) : rotate display 180 degrees.
ii) Xilinx SystemACE
The Xilinx SystemACE device is used to program FPGAs from an FPGA
bitstream stored on a CF card. It can also be used as a generic CF
interface device.
Optional properties:
- 8-bit (empty) : Set this property for SystemACE in 8 bit mode
iii) Xilinx EMAC and Xilinx TEMAC
Xilinx Ethernet devices. In addition to general xilinx properties
listed above, nodes for these devices should include a phy-handle
property, and may include other common network device properties
like local-mac-address.
iv) Xilinx Uartlite
Xilinx uartlite devices are simple fixed speed serial ports.
Requred properties:
- current-speed : Baud rate of uartlite
p) Freescale Synchronous Serial Interface
The SSI is a serial device that communicates with audio codecs. It can
be programmed in AC97, I2S, left-justified, or right-justified modes.
Required properties:
- compatible : compatible list, containing "fsl,ssi"
- cell-index : the SSI, <0> = SSI1, <1> = SSI2, and so on
- reg : offset and length of the register set for the device
- interrupts : <a b> where a is the interrupt number and b is a
field that represents an encoding of the sense and
level information for the interrupt. This should be
encoded based on the information in section 2)
depending on the type of interrupt controller you
have.
- interrupt-parent : the phandle for the interrupt controller that
services interrupts for this device.
- fsl,mode : the operating mode for the SSI interface
"i2s-slave" - I2S mode, SSI is clock slave
"i2s-master" - I2S mode, SSI is clock master
"lj-slave" - left-justified mode, SSI is clock slave
"lj-master" - l.j. mode, SSI is clock master
"rj-slave" - right-justified mode, SSI is clock slave
"rj-master" - r.j., SSI is clock master
"ac97-slave" - AC97 mode, SSI is clock slave
"ac97-master" - AC97 mode, SSI is clock master
Optional properties:
- codec-handle : phandle to a 'codec' node that defines an audio
codec connected to this SSI. This node is typically
a child of an I2C or other control node.
Child 'codec' node required properties:
- compatible : compatible list, contains the name of the codec
Child 'codec' node optional properties:
- clock-frequency : The frequency of the input clock, which typically
comes from an on-board dedicated oscillator.
* Freescale 83xx DMA Controller
Freescale PowerPC 83xx have on chip general purpose DMA controllers.
Required properties:
- compatible : compatible list, contains 2 entries, first is
"fsl,CHIP-dma", where CHIP is the processor
(mpc8349, mpc8360, etc.) and the second is
"fsl,elo-dma"
- reg : <registers mapping for DMA general status reg>
- ranges : Should be defined as specified in 1) to describe the
DMA controller channels.
- cell-index : controller index. 0 for controller @ 0x8100
- interrupts : <interrupt mapping for DMA IRQ>
- interrupt-parent : optional, if needed for interrupt mapping
- DMA channel nodes:
- compatible : compatible list, contains 2 entries, first is
"fsl,CHIP-dma-channel", where CHIP is the processor
(mpc8349, mpc8350, etc.) and the second is
"fsl,elo-dma-channel"
- reg : <registers mapping for channel>
- cell-index : dma channel index starts at 0.
Optional properties:
- interrupts : <interrupt mapping for DMA channel IRQ>
(on 83xx this is expected to be identical to
the interrupts property of the parent node)
- interrupt-parent : optional, if needed for interrupt mapping
Example:
dma@82a8 {
#address-cells = <1>;
#size-cells = <1>;
compatible = "fsl,mpc8349-dma", "fsl,elo-dma";
reg = <82a8 4>;
ranges = <0 8100 1a4>;
interrupt-parent = <&ipic>;
interrupts = <47 8>;
cell-index = <0>;
dma-channel@0 {
compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel";
cell-index = <0>;
reg = <0 80>;
};
dma-channel@80 {
compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel";
cell-index = <1>;
reg = <80 80>;
};
dma-channel@100 {
compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel";
cell-index = <2>;
reg = <100 80>;
};
dma-channel@180 {
compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel";
cell-index = <3>;
reg = <180 80>;
};
};
* Freescale 85xx/86xx DMA Controller
Freescale PowerPC 85xx/86xx have on chip general purpose DMA controllers.
Required properties:
- compatible : compatible list, contains 2 entries, first is
"fsl,CHIP-dma", where CHIP is the processor
(mpc8540, mpc8540, etc.) and the second is
"fsl,eloplus-dma"
- reg : <registers mapping for DMA general status reg>
- cell-index : controller index. 0 for controller @ 0x21000,
1 for controller @ 0xc000
- ranges : Should be defined as specified in 1) to describe the
DMA controller channels.
- DMA channel nodes:
- compatible : compatible list, contains 2 entries, first is
"fsl,CHIP-dma-channel", where CHIP is the processor
(mpc8540, mpc8560, etc.) and the second is
"fsl,eloplus-dma-channel"
- cell-index : dma channel index starts at 0.
- reg : <registers mapping for channel>
- interrupts : <interrupt mapping for DMA channel IRQ>
- interrupt-parent : optional, if needed for interrupt mapping
Example:
dma@21300 {
#address-cells = <1>;
#size-cells = <1>;
compatible = "fsl,mpc8540-dma", "fsl,eloplus-dma";
reg = <21300 4>;
ranges = <0 21100 200>;
cell-index = <0>;
dma-channel@0 {
compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel";
reg = <0 80>;
cell-index = <0>;
interrupt-parent = <&mpic>;
interrupts = <14 2>;
};
dma-channel@80 {
compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel";
reg = <80 80>;
cell-index = <1>;
interrupt-parent = <&mpic>;
interrupts = <15 2>;
};
dma-channel@100 {
compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel";
reg = <100 80>;
cell-index = <2>;
interrupt-parent = <&mpic>;
interrupts = <16 2>;
};
dma-channel@180 {
compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel";
reg = <180 80>;
cell-index = <3>;
interrupt-parent = <&mpic>;
interrupts = <17 2>;
};
};
* Freescale 8xxx/3.0 Gb/s SATA nodes
SATA nodes are defined to describe on-chip Serial ATA controllers.
Each SATA port should have its own node.
Required properties:
- compatible : compatible list, contains 2 entries, first is
"fsl,CHIP-sata", where CHIP is the processor
(mpc8315, mpc8379, etc.) and the second is
"fsl,pq-sata"
- interrupts : <interrupt mapping for SATA IRQ>
- cell-index : controller index.
1 for controller @ 0x18000
2 for controller @ 0x19000
3 for controller @ 0x1a000
4 for controller @ 0x1b000
Optional properties:
- interrupt-parent : optional, if needed for interrupt mapping
- reg : <registers mapping>
Example:
sata@18000 {
compatible = "fsl,mpc8379-sata", "fsl,pq-sata";
reg = <0x18000 0x1000>;
cell-index = <1>;
interrupts = <2c 8>;
interrupt-parent = < &ipic >;
};
More devices will be defined as this spec matures.
VII - Specifying interrupt information for devices

295
Documentation/powerpc/qe_firmware.txt 100644
View File

@ -0,0 +1,295 @@
Freescale QUICC Engine Firmware Uploading
-----------------------------------------
(c) 2007 Timur Tabi <timur at freescale.com>,
Freescale Semiconductor
Table of Contents
=================
I - Software License for Firmware
II - Microcode Availability
III - Description and Terminology
IV - Microcode Programming Details
V - Firmware Structure Layout
VI - Sample Code for Creating Firmware Files
Revision Information
====================
November 30, 2007: Rev 1.0 - Initial version
I - Software License for Firmware
=================================
Each firmware file comes with its own software license. For information on
the particular license, please see the license text that is distributed with
the firmware.
II - Microcode Availability
===========================
Firmware files are distributed through various channels. Some are available on
http://opensource.freescale.com. For other firmware files, please contact
your Freescale representative or your operating system vendor.
III - Description and Terminology
================================
In this document, the term 'microcode' refers to the sequence of 32-bit
integers that compose the actual QE microcode.
The term 'firmware' refers to a binary blob that contains the microcode as
well as other data that
1) describes the microcode's purpose
2) describes how and where to upload the microcode
3) specifies the values of various registers
4) includes additional data for use by specific device drivers
Firmware files are binary files that contain only a firmware.
IV - Microcode Programming Details
===================================
The QE architecture allows for only one microcode present in I-RAM for each
RISC processor. To replace any current microcode, a full QE reset (which
disables the microcode) must be performed first.
QE microcode is uploaded using the following procedure:
1) The microcode is placed into I-RAM at a specific location, using the
IRAM.IADD and IRAM.IDATA registers.
2) The CERCR.CIR bit is set to 0 or 1, depending on whether the firmware
needs split I-RAM. Split I-RAM is only meaningful for SOCs that have
QEs with multiple RISC processors, such as the 8360. Splitting the I-RAM
allows each processor to run a different microcode, effectively creating an
asymmetric multiprocessing (AMP) system.
3) The TIBCR trap registers are loaded with the addresses of the trap handlers
in the microcode.
4) The RSP.ECCR register is programmed with the value provided.
5) If necessary, device drivers that need the virtual traps and extended mode
data will use them.
Virtual Microcode Traps
These virtual traps are conditional branches in the microcode. These are
"soft" provisional introduced in the ROMcode in order to enable higher
flexibility and save h/w traps If new features are activated or an issue is
being fixed in the RAM package utilizing they should be activated. This data
structure signals the microcode which of these virtual traps is active.
This structure contains 6 words that the application should copy to some
specific been defined. This table describes the structure.
---------------------------------------------------------------
| Offset in | | Destination Offset | Size of |
| array | Protocol | within PRAM | Operand |
--------------------------------------------------------------|
| 0 | Ethernet | 0xF8 | 4 bytes |
| | interworking | | |
---------------------------------------------------------------
| 4 | ATM | 0xF8 | 4 bytes |
| | interworking | | |
---------------------------------------------------------------
| 8 | PPP | 0xF8 | 4 bytes |
| | interworking | | |
---------------------------------------------------------------
| 12 | Ethernet RX | 0x22 | 1 byte |
| | Distributor Page | | |
---------------------------------------------------------------
| 16 | ATM Globtal | 0x28 | 1 byte |
| | Params Table | | |
---------------------------------------------------------------
| 20 | Insert Frame | 0xF8 | 4 bytes |
---------------------------------------------------------------
Extended Modes
This is a double word bit array (64 bits) that defines special functionality
which has an impact on the softwarew drivers. Each bit has its own impact
and has special instructions for the s/w associated with it. This structure is
described in this table:
-----------------------------------------------------------------------
| Bit # | Name | Description |
-----------------------------------------------------------------------
| 0 | General | Indicates that prior to each host command |
| | push command | given by the application, the software must |
| | | assert a special host command (push command)|
| | | CECDR = 0x00800000. |
| | | CECR = 0x01c1000f. |
-----------------------------------------------------------------------
| 1 | UCC ATM | Indicates that after issuing ATM RX INIT |
| | RX INIT | command, the host must issue another special|
| | push command | command (push command) and immediately |
| | | following that re-issue the ATM RX INIT |
| | | command. (This makes the sequence of |
| | | initializing the ATM receiver a sequence of |
| | | three host commands) |
| | | CECDR = 0x00800000. |
| | | CECR = 0x01c1000f. |
-----------------------------------------------------------------------
| 2 | Add/remove | Indicates that following the specific host |
| | command | command: "Add/Remove entry in Hash Lookup |
| | validation | Table" used in Interworking setup, the user |
| | | must issue another command. |
| | | CECDR = 0xce000003. |
| | | CECR = 0x01c10f58. |
-----------------------------------------------------------------------
| 3 | General push | Indicates that the s/w has to initialize |
| | command | some pointers in the Ethernet thread pages |
| | | which are used when Header Compression is |
| | | activated. The full details of these |
| | | pointers is located in the software drivers.|
-----------------------------------------------------------------------
| 4 | General push | Indicates that after issuing Ethernet TX |
| | command | INIT command, user must issue this command |
| | | for each SNUM of Ethernet TX thread. |
| | | CECDR = 0x00800003. |
| | | CECR = 0x7'b{0}, 8'b{Enet TX thread SNUM}, |
| | | 1'b{1}, 12'b{0}, 4'b{1} |
-----------------------------------------------------------------------
| 5 - 31 | N/A | Reserved, set to zero. |
-----------------------------------------------------------------------
V - Firmware Structure Layout
==============================
QE microcode from Freescale is typically provided as a header file. This
header file contains macros that define the microcode binary itself as well as
some other data used in uploading that microcode. The format of these files
do not lend themselves to simple inclusion into other code. Hence,
the need for a more portable format. This section defines that format.
Instead of distributing a header file, the microcode and related data are
embedded into a binary blob. This blob is passed to the qe_upload_firmware()
function, which parses the blob and performs everything necessary to upload
the microcode.
All integers are big-endian. See the comments for function
qe_upload_firmware() for up-to-date implementation information.
This structure supports versioning, where the version of the structure is
embedded into the structure itself. To ensure forward and backwards
compatibility, all versions of the structure must use the same 'qe_header'
structure at the beginning.
'header' (type: struct qe_header):
The 'length' field is the size, in bytes, of the entire structure,
including all the microcode embedded in it, as well as the CRC (if
present).
The 'magic' field is an array of three bytes that contains the letters
'Q', 'E', and 'F'. This is an identifier that indicates that this
structure is a QE Firmware structure.
The 'version' field is a single byte that indicates the version of this
structure. If the layout of the structure should ever need to be
changed to add support for additional types of microcode, then the
version number should also be changed.
The 'id' field is a null-terminated string(suitable for printing) that
identifies the firmware.
The 'count' field indicates the number of 'microcode' structures. There
must be one and only one 'microcode' structure for each RISC processor.
Therefore, this field also represents the number of RISC processors for this
SOC.
The 'soc' structure contains the SOC numbers and revisions used to match
the microcode to the SOC itself. Normally, the microcode loader should
check the data in this structure with the SOC number and revisions, and
only upload the microcode if there's a match. However, this check is not
made on all platforms.
Although it is not recommended, you can specify '0' in the soc.model
field to skip matching SOCs altogether.
The 'model' field is a 16-bit number that matches the actual SOC. The
'major' and 'minor' fields are the major and minor revision numbrs,
respectively, of the SOC.
For example, to match the 8323, revision 1.0:
soc.model = 8323
soc.major = 1
soc.minor = 0
'padding' is neccessary for structure alignment. This field ensures that the
'extended_modes' field is aligned on a 64-bit boundary.
'extended_modes' is a bitfield that defines special functionality which has an
impact on the device drivers. Each bit has its own impact and has special
instructions for the driver associated with it. This field is stored in
the QE library and available to any driver that calles qe_get_firmware_info().
'vtraps' is an array of 8 words that contain virtual trap values for each
virtual traps. As with 'extended_modes', this field is stored in the QE
library and available to any driver that calles qe_get_firmware_info().
'microcode' (type: struct qe_microcode):
For each RISC processor there is one 'microcode' structure. The first
'microcode' structure is for the first RISC, and so on.
The 'id' field is a null-terminated string suitable for printing that
identifies this particular microcode.
'traps' is an array of 16 words that contain hardware trap values
for each of the 16 traps. If trap[i] is 0, then this particular
trap is to be ignored (i.e. not written to TIBCR[i]). The entire value
is written as-is to the TIBCR[i] register, so be sure to set the EN
and T_IBP bits if necessary.
'eccr' is the value to program into the ECCR register.
'iram_offset' is the offset into IRAM to start writing the
microcode.
'count' is the number of 32-bit words in the microcode.
'code_offset' is the offset, in bytes, from the beginning of this
structure where the microcode itself can be found. The first
microcode binary should be located immediately after the 'microcode'
array.
'major', 'minor', and 'revision' are the major, minor, and revision
version numbers, respectively, of the microcode. If all values are 0,
then these fields are ignored.
'reserved' is necessary for structure alignment. Since 'microcode'
is an array, the 64-bit 'extended_modes' field needs to be aligned
on a 64-bit boundary, and this can only happen if the size of
'microcode' is a multiple of 8 bytes. To ensure that, we add
'reserved'.
After the last microcode is a 32-bit CRC. It can be calculated using
this algorithm:
u32 crc32(const u8 *p, unsigned int len)
{
unsigned int i;
u32 crc = 0;
while (len--) {
crc ^= *p++;
for (i = 0; i < 8; i++)
crc = (crc >> 1) ^ ((crc & 1) ? 0xedb88320 : 0);
}
return crc;
}
VI - Sample Code for Creating Firmware Files
============================================
A Python program that creates firmware binaries from the header files normally
distributed by Freescale can be found on http://opensource.freescale.com.

7
Documentation/rtc.txt
View File

@ -180,9 +180,10 @@ driver returns ENOIOCTLCMD. Some common examples:
* RTC_IRQP_SET, RTC_IRQP_READ: the irq_set_freq function will be called
to set the frequency while the framework will handle the read for you
since the frequency is stored in the irq_freq member of the rtc_device
structure. Also make sure you set the max_user_freq member in your
initialization routines so the framework can sanity check the user
input for you.
structure. Your driver needs to initialize the irq_freq member during
init. Make sure you check the requested frequency is in range of your
hardware in the irq_set_freq function. If you cannot actually change
the frequency, just return -ENOTTY.
If all else fails, check out the rtc-test.c driver!

5
Documentation/s390/CommonIO
View File

@ -4,6 +4,11 @@ S/390 common I/O-Layer - command line parameters, procfs and debugfs entries
Command line parameters
-----------------------
* ccw_timeout_log
Enable logging of debug information in case of ccw device timeouts.
* cio_msg = yes | no
Determines whether information on found devices and sensed device

2
Documentation/s390/cds.txt
View File

@ -133,7 +133,7 @@ During its startup the Linux/390 system checks for peripheral devices. Each
of those devices is uniquely defined by a so called subchannel by the ESA/390
channel subsystem. While the subchannel numbers are system generated, each
subchannel also takes a user defined attribute, the so called device number.
Both subchannel number and device number cannot exceed 65535. During driverfs
Both subchannel number and device number cannot exceed 65535. During sysfs
initialisation, the information about control unit type and device types that
imply specific I/O commands (channel command words - CCWs) in order to operate
the device are gathered. Device drivers can retrieve this set of hardware

2
Documentation/scsi/00-INDEX
View File

@ -64,8 +64,6 @@ lpfc.txt
- LPFC driver release notes
megaraid.txt
- Common Management Module, shared code handling ioctls for LSI drivers
ncr53c7xx.txt
- info on driver for NCR53c7xx based adapters
ncr53c8xx.txt
- info on driver for NCR53c8xx based adapters
osst.txt

159
Documentation/scsi/ChangeLog.megaraid_sas
View File

@ -1,3 +1,162 @@
1 Release Date : Thur. Nov. 07 16:30:43 PST 2007 -
(emaild-id:megaraidlinux@lsi.com)
Sumant Patro
Bo Yang
2 Current Version : 00.00.03.16
3 Older Version : 00.00.03.15
1. Increased MFI_POLL_TIMEOUT_SECS to 60 seconds from 10. FW may take
a max of 60 seconds to respond to the INIT cmd.
1 Release Date : Fri. Sep. 07 16:30:43 PST 2007 -
(emaild-id:megaraidlinux@lsi.com)
Sumant Patro
Bo Yang
2 Current Version : 00.00.03.15
3 Older Version : 00.00.03.14
1. Added module parameter "poll_mode_io" to support for "polling"
(reduced interrupt operation). In this mode, IO completion
interrupts are delayed. At the end of initiating IOs, the
driver schedules for cmd completion if there are pending cmds
to be completed. A timer-based interrupt has also been added
to prevent IO completion processing from being delayed
indefinitely in the case that no new IOs are initiated.
1 Release Date : Fri. Sep. 07 16:30:43 PST 2007 -
(emaild-id:megaraidlinux@lsi.com)
Sumant Patro
Bo Yang
2 Current Version : 00.00.03.14
3 Older Version : 00.00.03.13
1. Setting the max_sectors_per_req based on max SGL supported by the
FW. Prior versions calculated this value from controller info
(max_sectors_1, max_sectors_2). For certain controllers/FW,
this was resulting in a value greater than max SGL supported
by the FW. Issue was first reported by users running LUKS+XFS
with megaraid_sas. Thanks to RB for providing the logs and
duplication steps that helped to get to the root cause of the
issue. 2. Increased MFI_POLL_TIMEOUT_SECS to 60 seconds from
10. FW may take a max of 60 seconds to respond to the INIT
cmd.
1 Release Date : Fri. June. 15 16:30:43 PST 2007 -
(emaild-id:megaraidlinux@lsi.com)
Sumant Patro
Bo Yang
2 Current Version : 00.00.03.13
3 Older Version : 00.00.03.12
1. Added the megasas_reset_timer routine to intercept cmd timeout and throttle io.
On Fri, 2007-03-16 at 16:44 -0600, James Bottomley wrote:
It looks like megaraid_sas at least needs this to throttle its commands
> as they begin to time out. The code keeps the existing transport
> template use of eh_timed_out (and allows the transport to override the
> host if they both have this callback).
>
> James
1 Release Date : Sat May. 12 16:30:43 PST 2007 -
(emaild-id:megaraidlinux@lsi.com)
Sumant Patro
Bo Yang
2 Current Version : 00.00.03.12
3 Older Version : 00.00.03.11
1. When MegaSAS driver receives reset call from OS, driver waits in reset
routine for max 3 minutes for all pending command completion. Now driver will
call completion routine every 5 seconds from the reset routine instead of
waiting for depending on cmd completion from isr path.
1 Release Date : Mon Apr. 30 10:25:52 PST 2007 -
(emaild-id:megaraidlinux@lsi.com)
Sumant Patro
Bo Yang
2 Current Version : 00.00.03.11
3 Older Version : 00.00.03.09
1. Memory Manager for IOCTL removed for 2.6 kernels.
pci_alloc_consistent replaced by dma_alloc_coherent. With this
change there is no need of memory manager in the driver code
On Wed, 2007-02-07 at 13:30 -0800, Andrew Morton wrote:
> I suspect all this horror is due to stupidity in the DMA API.
>
> pci_alloc_consistent() just goes and assumes GFP_ATOMIC, whereas
> the caller (megasas_mgmt_fw_ioctl) would have been perfectly happy
> to use GFP_KERNEL.
>
> I bet this fixes it
It does, but the DMA API was expanded to cope with this exact case, so
use dma_alloc_coherent() directly in the megaraid code instead. The dev
is just &pci_dev->dev.
James <James.Bottomley@SteelEye.com>
3. SYNCHRONIZE_CACHE is not supported by FW and thus blocked by driver.
4. Hibernation support added
5. Performing diskdump while running IO in RHEL 4 was failing. Fixed.
1 Release Date : Fri Feb. 09 14:36:28 PST 2007 -
(emaild-id:megaraidlinux@lsi.com)
Sumant Patro
Bo Yang
2 Current Version : 00.00.03.09
3 Older Version : 00.00.03.08
i. Under heavy IO mid-layer prints "DRIVER_TIMEOUT" errors
The driver now waits for 10 seconds to elapse instead of 5 (as in
previous release) to resume IO.
1 Release Date : Mon Feb. 05 11:35:24 PST 2007 -
(emaild-id:megaraidlinux@lsi.com)
Sumant Patro
Bo Yang
2 Current Version : 00.00.03.08
3 Older Version : 00.00.03.07
i. Under heavy IO mid-layer prints "DRIVER_TIMEOUT" errors
Fix: The driver is now throttling IO.
Checks added in megasas_queue_command to know if FW is able to
process commands within timeout period. If number of retries
is 2 or greater,the driver stops sending cmd to FW temporarily. IO is
resumed if pending cmd count reduces to 16 or 5 seconds has elapsed
from the time cmds were last sent to FW.
ii. FW enables WCE bit in Mode Sense cmd for drives that are configured
as WriteBack. The OS may send "SYNCHRONIZE_CACHE" cmd when Logical
Disks are exposed with WCE=1. User is advised to enable Write Back
mode only when the controller has battery backup. At this time
Synhronize cache is not supported by the FW. Driver will short-cycle
the cmd and return sucess without sending down to FW.
1 Release Date : Sun Jan. 14 11:21:32 PDT 2007 -
Sumant Patro <Sumant.Patro@lsil.com>/Bo Yang
2 Current Version : 00.00.03.07
3 Older Version : 00.00.03.06
i. bios_param entry added in scsi_host_template that returns disk geometry
information.
1 Release Date : Fri Oct 20 11:21:32 PDT 2006 - Sumant Patro <Sumant.Patro@lsil.com>/Bo Yang
2 Current Version : 00.00.03.06
3 Older Version : 00.00.03.05
1. Added new memory management module to support the IOCTL memory allocation. For IOCTL we try to allocate from the memory pool created during driver initialization. If mem pool is empty then we allocate at run time.
2. Added check in megasas_queue_command and dpc/isr routine to see if we have already declared adapter dead
(hw_crit_error=1). If hw_crit_error==1, now we donot accept any processing of pending cmds/accept any cmd from OS
1 Release Date : Mon Oct 02 11:21:32 PDT 2006 - Sumant Patro <Sumant.Patro@lsil.com>
2 Current Version : 00.00.03.05

4
Documentation/scsi/aacraid.txt
View File

@ -56,6 +56,10 @@ Supported Cards/Chipsets
9005:0285:9005:02d1 Adaptec 5405 (Voodoo40)
9005:0285:15d9:02d2 SMC AOC-USAS-S8i-LP
9005:0285:15d9:02d3 SMC AOC-USAS-S8iR-LP
9005:0285:9005:02d4 Adaptec 2045 (Voodoo04 Lite)
9005:0285:9005:02d5 Adaptec 2405 (Voodoo40 Lite)
9005:0285:9005:02d6 Adaptec 2445 (Voodoo44 Lite)
9005:0285:9005:02d7 Adaptec 2805 (Voodoo80 Lite)
1011:0046:9005:0364 Adaptec 5400S (Mustang)
9005:0287:9005:0800 Adaptec Themisto (Jupiter)
9005:0200:9005:0200 Adaptec Themisto (Jupiter)

30
Documentation/scsi/hptiop.txt
View File

@ -1,9 +1,9 @@
HIGHPOINT ROCKETRAID 3xxx RAID DRIVER (hptiop)
HIGHPOINT ROCKETRAID 3xxx/4xxx ADAPTER DRIVER (hptiop)
Controller Register Map
-------------------------
The controller IOP is accessed via PCI BAR0.
For Intel IOP based adapters, the controller IOP is accessed via PCI BAR0:
BAR0 offset Register
0x10 Inbound Message Register 0
@ -18,6 +18,24 @@ The controller IOP is accessed via PCI BAR0.
0x40 Inbound Queue Port
0x44 Outbound Queue Port
For Marvell IOP based adapters, the IOP is accessed via PCI BAR0 and BAR1:
BAR0 offset Register
0x20400 Inbound Doorbell Register
0x20404 Inbound Interrupt Mask Register
0x20408 Outbound Doorbell Register
0x2040C Outbound Interrupt Mask Register
BAR1 offset Register
0x0 Inbound Queue Head Pointer
0x4 Inbound Queue Tail Pointer
0x8 Outbound Queue Head Pointer
0xC Outbound Queue Tail Pointer
0x10 Inbound Message Register
0x14 Outbound Message Register
0x40-0x1040 Inbound Queue
0x1040-0x2040 Outbound Queue
I/O Request Workflow
----------------------
@ -73,15 +91,9 @@ The driver exposes following sysfs attributes:
driver-version R driver version string
firmware-version R firmware version string
The driver registers char device "hptiop" to communicate with HighPoint RAID
management software. Its ioctl routine acts as a general binary interface
between the IOP firmware and HighPoint RAID management software. New management
functions can be implemented in application/firmware without modification
in driver code.
-----------------------------------------------------------------------------
Copyright (C) 2006 HighPoint Technologies, Inc. All Rights Reserved.
Copyright (C) 2006-2007 HighPoint Technologies, Inc. All Rights Reserved.
This file is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of

19
Documentation/scsi/link_power_management_policy.txt 100644
View File

@ -0,0 +1,19 @@
This parameter allows the user to set the link (interface) power management.
There are 3 possible options:
Value Effect
----------------------------------------------------------------------------
min_power Tell the controller to try to make the link use the
least possible power when possible. This may
sacrifice some performance due to increased latency
when coming out of lower power states.
max_performance Generally, this means no power management. Tell
the controller to have performance be a priority
over power management.
medium_power Tell the controller to enter a lower power state
when possible, but do not enter the lowest power
state, thus improving latency over min_power setting.

40
Documentation/scsi/ncr53c7xx.txt
View File

@ -1,40 +0,0 @@
README for WarpEngine/A4000T/A4091 SCSI kernels.
Use the following options to disable options in the SCSI driver.
Using amiboot for example.....
To disable Synchronous Negotiation....
amiboot -k kernel 53c7xx=nosync:0
To disable Disconnection....
amiboot -k kernel 53c7xx=nodisconnect:0
To disable certain SCSI devices...
amiboot -k kernel 53c7xx=validids:0x3F
this allows only device ID's 0,1,2,3,4 and 5 for linux to handle.
(this is a bitmasked field - i.e. each bit represents a SCSI ID)
These commands work on a per controller basis and use the option 'next' to
move to the next controller in the system.
e.g.
amiboot -k kernel 53c7xx=nodisconnect:0,next,nosync:0
this uses No Disconnection on the first controller and Asynchronous
SCSI on the second controller.
Known Issues:
Two devices are known not to function with the default settings of using
synchronous SCSI. These are the Archive Viper 150 Tape Drive and the
SyQuest SQ555 removeable hard drive. When using these devices on a controller
use the 'nosync:0' option.
Please try these options and post any problems/successes to me.
Alan Hourihane <alanh@fairlite.demon.co.uk>

210
Documentation/sound/alsa/ALSA-Configuration.txt
View File

@ -57,7 +57,9 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
- Default: 1
- For auto-loading more than one card, specify this
option together with snd-card-X aliases.
slots - Reserve the slot index for the given driver.
This option takes multiple strings.
See "Module Autoloading Support" section for details.
Module snd-pcm-oss
------------------
@ -148,13 +150,6 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
Module for sound cards based on Analog Devices AD1816A/AD1815 ISA chips.
port - port # for AD1816A chip (PnP setup)
mpu_port - port # for MPU-401 UART (PnP setup)
fm_port - port # for OPL3 (PnP setup)
irq - IRQ # for AD1816A chip (PnP setup)
mpu_irq - IRQ # for MPU-401 UART (PnP setup)
dma1 - first DMA # for AD1816A chip (PnP setup)
dma2 - second DMA # for AD1816A chip (PnP setup)
clockfreq - Clock frequency for AD1816A chip (default = 0, 33000Hz)
This module supports multiple cards, autoprobe and PnP.
@ -201,14 +196,6 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
Module for sound cards based on Avance Logic ALS100/ALS120 ISA chips.
port - port # for ALS100 (SB16) chip (PnP setup)
irq - IRQ # for ALS100 (SB16) chip (PnP setup)
dma8 - 8-bit DMA # for ALS100 (SB16) chip (PnP setup)
dma16 - 16-bit DMA # for ALS100 (SB16) chip (PnP setup)
mpu_port - port # for MPU-401 UART (PnP setup)
mpu_irq - IRQ # for MPU-401 (PnP setup)
fm_port - port # for OPL3 FM (PnP setup)
This module supports multiple cards, autoprobe and PnP.
The power-management is supported.
@ -302,15 +289,6 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
Module for sound cards based on Aztech System AZT2320 ISA chip (PnP only).
port - port # for AZT2320 chip (PnP setup)
wss_port - port # for WSS (PnP setup)
mpu_port - port # for MPU-401 UART (PnP setup)
fm_port - FM port # for AZT2320 chip (PnP setup)
irq - IRQ # for AZT2320 (WSS) chip (PnP setup)
mpu_irq - IRQ # for MPU-401 UART (PnP setup)
dma1 - 1st DMA # for AZT2320 (WSS) chip (PnP setup)
dma2 - 2nd DMA # for AZT2320 (WSS) chip (PnP setup)
This module supports multiple cards, PnP and autoprobe.
The power-management is supported.
@ -350,6 +328,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
Module for sound cards based on C-Media CMI8330 ISA chips.
isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
with isapnp=0, the following options are available:
wssport - port # for CMI8330 chip (WSS)
wssirq - IRQ # for CMI8330 chip (WSS)
wssdma - first DMA # for CMI8330 chip (WSS)
@ -404,6 +386,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
Module for sound cards based on CS4232/CS4232A ISA chips.
isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
with isapnp=0, the following options are available:
port - port # for CS4232 chip (PnP setup - 0x534)
cport - control port # for CS4232 chip (PnP setup - 0x120,0x210,0xf00)
mpu_port - port # for MPU-401 UART (PnP setup - 0x300), -1 = disable
@ -412,10 +398,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
mpu_irq - IRQ # for MPU-401 UART (9,11,12,15)
dma1 - first DMA # for CS4232 chip (0,1,3)
dma2 - second DMA # for Yamaha CS4232 chip (0,1,3), -1 = disable
isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
This module supports multiple cards. This module does not support autoprobe
thus main port must be specified!!! Other ports are optional.
(if ISA PnP is not used) thus main port must be specified!!! Other ports are
optional.
The power-management is supported.
@ -425,6 +411,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
Module for sound cards based on CS4235/CS4236/CS4236B/CS4237B/
CS4238B/CS4239 ISA chips.
isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
with isapnp=0, the following options are available:
port - port # for CS4236 chip (PnP setup - 0x534)
cport - control port # for CS4236 chip (PnP setup - 0x120,0x210,0xf00)
mpu_port - port # for MPU-401 UART (PnP setup - 0x300), -1 = disable
@ -433,7 +423,6 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
mpu_irq - IRQ # for MPU-401 UART (9,11,12,15)
dma1 - first DMA # for CS4236 chip (0,1,3)
dma2 - second DMA # for CS4236 chip (0,1,3), -1 = disable
isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
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
@ -503,13 +492,6 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
Module for Diamond Technologies DT-019X / Avance Logic ALS-007 (PnP
only)
port - Port # (PnP setup)
mpu_port - Port # for MPU-401 (PnP setup)
fm_port - Port # for FM OPL-3 (PnP setup)
irq - IRQ # (PnP setup)
mpu_irq - IRQ # for MPU-401 (PnP setup)
dma8 - DMA # (PnP setup)
This module supports multiple cards. This module is enabled only with
ISA PnP support.
@ -607,10 +589,6 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
Module for sound cards based on ESS ES968 chip (PnP only).
port - port # for ES968 (SB8) chip (PnP setup)
irq - IRQ # for ES968 (SB8) chip (PnP setup)
dma1 - DMA # for ES968 (SB8) chip (PnP setup)
This module supports multiple cards, PnP and autoprobe.
The power-management is supported.
@ -633,13 +611,16 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
Module for ESS AudioDrive ES-18xx sound cards.
isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
with isapnp=0, the following options are available:
port - port # for ES-18xx chip (0x220,0x240,0x260)
mpu_port - port # for MPU-401 port (0x300,0x310,0x320,0x330), -1 = disable (default)
fm_port - port # for FM (optional, not used)
irq - IRQ # for ES-18xx chip (5,7,9,10)
dma1 - first DMA # for ES-18xx chip (0,1,3)
dma2 - first DMA # for ES-18xx chip (0,1,3)
isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
This module supports multiple cards, ISA PnP and autoprobe (without MPU-401
port if native ISA PnP routines are not used).
@ -763,9 +744,12 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
VIA VT8251/VT8237A,
SIS966, ULI M5461
[Multiple options for each card instance]
model - force the model name
position_fix - Fix DMA pointer (0 = auto, 1 = none, 2 = POSBUF, 3 = FIFO size)
probe_mask - Bitmask to probe codecs (default = -1, meaning all slots)
[Single (global) options]
single_cmd - Use single immediate commands to communicate with
codecs (for debugging only)
enable_msi - Enable Message Signaled Interrupt (MSI) (default = off)
@ -774,8 +758,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
power_save_controller - Reset HD-audio controller in power-saving mode
(default = on)
This module supports one card and autoprobe.
This module supports multiple cards and autoprobe.
Each codec may have a model table for different configurations.
If your machine isn't listed there, the default (usually minimal)
configuration is set up. You can pass "model=<name>" option to
@ -817,17 +801,23 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
will Will laptops (PB V7900)
replacer Replacer 672V
basic fixed pin assignment (old default model)
test for testing/debugging purpose, almost all controls can
adjusted. Appearing only when compiled with
$CONFIG_SND_DEBUG=y
auto auto-config reading BIOS (default)
ALC262
fujitsu Fujitsu Laptop
hp-bpc HP xw4400/6400/8400/9400 laptops
hp-bpc-d7000 HP BPC D7000
hp-tc-t5735 HP Thin Client T5735
hp-rp5700 HP RP5700
benq Benq ED8
benq-t31 Benq T31
hippo Hippo (ATI) with jack detection, Sony UX-90s
hippo_1 Hippo (Benq) with jack detection
sony-assamd Sony ASSAMD
ultra Samsung Q1 Ultra Vista model
basic fixed pin assignment w/o SPDIF
auto auto-config reading BIOS (default)
@ -835,6 +825,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
3stack 3-stack model
toshiba Toshiba A205
acer Acer laptops
dell Dell OEM laptops (Vostro 1200)
test for testing/debugging purpose, almost all controls can
adjusted. Appearing only when compiled with
$CONFIG_SND_DEBUG=y
auto auto-config reading BIOS (default)
ALC662
@ -843,6 +837,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
3stack-6ch-dig 3-stack (6-channel) with SPDIF
6stack-dig 6-stack with SPDIF
lenovo-101e Lenovo laptop
eeepc-p701 ASUS Eeepc P701
eeepc-ep20 ASUS Eeepc EP20
auto auto-config reading BIOS (default)
ALC882/885
@ -877,6 +873,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
haier-w66 Haier W66
6stack-hp HP machines with 6stack (Nettle boards)
3stack-hp HP machines with 3stack (Lucknow, Samba boards)
6stack-dell Dell machines with 6stack (Inspiron 530)
mitac Mitac 8252D
auto auto-config reading BIOS (default)
ALC861/660
@ -928,6 +926,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
AD1984
basic default configuration
thinkpad Lenovo Thinkpad T61/X61
dell Dell T3400
AD1986A
6stack 6-jack, separate surrounds (default)
@ -947,7 +946,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
auto auto-config reading BIOS (default)
Conexant 5045
laptop Laptop config
laptop-hpsense Laptop with HP sense (old model laptop)
laptop-micsense Laptop with Mic sense (old model fujitsu)
laptop-hpmicsense Laptop with HP and Mic senses
benq Benq R55E
test for testing/debugging purpose, almost all controls
can be adjusted. Appearing only when compiled with
$CONFIG_SND_DEBUG=y
@ -960,6 +962,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
can be adjusted. Appearing only when compiled with
$CONFIG_SND_DEBUG=y
Conexant 5051
laptop Basic Laptop config (default)
hp HP Spartan laptop
STAC9200
ref Reference board
dell-d21 Dell (unknown)
@ -1091,6 +1097,15 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
See hdspm.txt for details.
Module snd-hifier
-----------------
Module for the MediaTek/TempoTec HiFier Fantasia sound card.
This module supports autoprobe and multiple cards.
Power management is _not_ supported.
Module snd-ice1712
------------------
@ -1156,11 +1171,14 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
* Chaintech 9CJS
* Chaintech AV-710
* Shuttle SN25P
* Onkyo SE-90PCI
* Onkyo SE-200PCI
model - Use the given board model, one of the following:
revo51, revo71, amp2000, prodigy71, prodigy71lt,
prodigy192, aureon51, aureon71, universe, ap192,
k8x800, phase22, phase28, ms300, av710
k8x800, phase22, phase28, ms300, av710, se200pci,
se90pci
This module supports multiple cards and autoprobe.
@ -1257,15 +1275,19 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
Module for Gravis UltraSound PnP, Dynasonic 3-D/Pro, STB Sound Rage 32
and other sound cards based on AMD InterWave (tm) chip.
port - port # for InterWave chip (0x210,0x220,0x230,0x240,0x250,0x260)
irq - IRQ # for InterWave chip (3,5,9,11,12,15)
dma1 - DMA # for InterWave chip (0,1,3,5,6,7)
dma2 - DMA # for InterWave chip (0,1,3,5,6,7,-1=disable)
joystick_dac - 0 to 31, (0.59V-4.52V or 0.389V-2.98V)
midi - 1 = MIDI UART enable, 0 = MIDI UART disable (default)
pcm_voices - reserved PCM voices for the synthesizer (default 2)
effect - 1 = InterWave effects enable (default 0);
requires 8 voices
isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
with isapnp=0, the following options are available:
port - port # for InterWave chip (0x210,0x220,0x230,0x240,0x250,0x260)
irq - IRQ # for InterWave chip (3,5,9,11,12,15)
dma1 - DMA # for InterWave chip (0,1,3,5,6,7)
dma2 - DMA # for InterWave chip (0,1,3,5,6,7,-1=disable)
This module supports multiple cards, autoprobe and ISA PnP.
@ -1276,16 +1298,20 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
and other sound cards based on AMD InterWave (tm) chip with TEA6330T
circuit for extended control of bass, treble and master volume.
port - port # for InterWave chip (0x210,0x220,0x230,0x240,0x250,0x260)
port_tc - tone control (i2c bus) port # for TEA6330T chip (0x350,0x360,0x370,0x380)
irq - IRQ # for InterWave chip (3,5,9,11,12,15)
dma1 - DMA # for InterWave chip (0,1,3,5,6,7)
dma2 - DMA # for InterWave chip (0,1,3,5,6,7,-1=disable)
joystick_dac - 0 to 31, (0.59V-4.52V or 0.389V-2.98V)
midi - 1 = MIDI UART enable, 0 = MIDI UART disable (default)
pcm_voices - reserved PCM voices for the synthesizer (default 2)
effect - 1 = InterWave effects enable (default 0);
requires 8 voices
isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
with isapnp=0, the following options are available:
port - port # for InterWave chip (0x210,0x220,0x230,0x240,0x250,0x260)
port_tc - tone control (i2c bus) port # for TEA6330T chip (0x350,0x360,0x370,0x380)
irq - IRQ # for InterWave chip (3,5,9,11,12,15)
dma1 - DMA # for InterWave chip (0,1,3,5,6,7)
dma2 - DMA # for InterWave chip (0,1,3,5,6,7,-1=disable)
This module supports multiple cards, autoprobe and ISA PnP.
@ -1473,6 +1499,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
Module for Yamaha OPL3-SA2/SA3 sound cards.
isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
with isapnp=0, the following options are available:
port - control port # for OPL3-SA chip (0x370)
sb_port - SB port # for OPL3-SA chip (0x220,0x240)
wss_port - WSS port # for OPL3-SA chip (0x530,0xe80,0xf40,0x604)
@ -1481,7 +1511,6 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
irq - IRQ # for OPL3-SA chip (5,7,9,10)
dma1 - first DMA # for Yamaha OPL3-SA chip (0,1,3)
dma2 - second DMA # for Yamaha OPL3-SA chip (0,1,3), -1 = disable
isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
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!!!
@ -1494,6 +1523,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
Module for sound cards based on OPTi 82c92x and Analog Devices AD1848 chips.
Module works with OAK Mozart cards as well.
isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
with isapnp=0, the following options are available:
port - port # for WSS chip (0x530,0xe80,0xf40,0x604)
mpu_port - port # for MPU-401 UART (0x300,0x310,0x320,0x330)
fm_port - port # for OPL3 device (0x388)
@ -1508,6 +1541,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
Module for sound cards based on OPTi 82c92x and Crystal CS4231 chips.
isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
with isapnp=0, the following options are available:
port - port # for WSS chip (0x530,0xe80,0xf40,0x604)
mpu_port - port # for MPU-401 UART (0x300,0x310,0x320,0x330)
fm_port - port # for OPL3 device (0x388)
@ -1523,6 +1560,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
Module for sound cards based on OPTi 82c93x chips.
isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
with isapnp=0, the following options are available:
port - port # for WSS chip (0x530,0xe80,0xf40,0x604)
mpu_port - port # for MPU-401 UART (0x300,0x310,0x320,0x330)
fm_port - port # for OPL3 device (0x388)
@ -1533,6 +1574,22 @@ 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-oxygen
-----------------
Module for sound cards based on the C-Media CMI8788 chip:
* Asound A-8788
* AuzenTech X-Meridian
* Bgears b-Enspirer
* Club3D Theatron DTS
* HT-Omega Claro
* Razer Barracuda AC-1
* Sondigo Inferno
This module supports autoprobe and multiple cards.
Power management is _not_ supported.
Module snd-pcxhr
----------------
@ -1647,6 +1704,12 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
SoundBlaster AWE 32 (PnP),
SoundBlaster AWE 64 PnP
mic_agc - Mic Auto-Gain-Control - 0 = disable, 1 = enable (default)
csp - ASP/CSP chip support - 0 = disable (default), 1 = enable
isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
with isapnp=0, the following options are available:
port - port # for SB DSP 4.x chip (0x220,0x240,0x260)
mpu_port - port # for MPU-401 UART (0x300,0x330), -1 = disable
awe_port - base port # for EMU8000 synthesizer (0x620,0x640,0x660)
@ -1654,9 +1717,6 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
irq - IRQ # for SB DSP 4.x chip (5,7,9,10)
dma8 - 8-bit DMA # for SB DSP 4.x chip (0,1,3)
dma16 - 16-bit DMA # for SB DSP 4.x chip (5,6,7)
mic_agc - Mic Auto-Gain-Control - 0 = disable, 1 = enable (default)
csp - ASP/CSP chip support - 0 = disable (default), 1 = enable
isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
This module supports multiple cards, autoprobe and ISA PnP.
@ -1739,18 +1799,21 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
Module for Turtle Beach Maui, Tropez and Tropez+ sound cards.
use_cs4232_midi - Use CS4232 MPU-401 interface
(inaccessibly located inside your computer)
isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
with isapnp=0, the following options are available:
cs4232_pcm_port - Port # for CS4232 PCM interface.
cs4232_pcm_irq - IRQ # for CS4232 PCM interface (5,7,9,11,12,15).
cs4232_mpu_port - Port # for CS4232 MPU-401 interface.
cs4232_mpu_irq - IRQ # for CS4232 MPU-401 interface (9,11,12,15).
use_cs4232_midi - Use CS4232 MPU-401 interface
(inaccessibly located inside your computer)
ics2115_port - Port # for ICS2115
ics2115_irq - IRQ # for ICS2115
fm_port - FM OPL-3 Port #
dma1 - DMA1 # for CS4232 PCM interface.
dma2 - DMA2 # for CS4232 PCM interface.
isapnp - ISA PnP detection - 0 = disable, 1 = enable (default)
The below are options for wavefront_synth features:
wf_raw - Assume that we need to boot the OS (default:no)
@ -1965,6 +2028,16 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
This module supports multiple cards.
Module snd-virtuoso
-------------------
Module for sound cards based on the Asus AV200 chip, i.e.,
Xonar D2 and Xonar D2X.
This module supports autoprobe and multiple cards.
Power management is _not_ supported.
Module snd-vx222
----------------
@ -2135,6 +2208,23 @@ alias sound-slot-1 snd-ens1371
In this example, the interwave card is always loaded as the first card
(index 0) and ens1371 as the second (index 1).
Alternative (and new) way to fixate the slot assignment is to use
"slots" option of snd module. In the case above, specify like the
following:
options snd slots=snd-interwave,snd-ens1371
Then, the first slot (#0) is reserved for snd-interwave driver, and
the second (#1) for snd-ens1371. You can omit index option in each
driver if slots option is used (although you can still have them at
the same time as long as they don't conflict).
The slots option is especially useful for avoiding the possible
hot-plugging and the resultant slot conflict. For example, in the
case above again, the first two slots are already reserved. If any
other driver (e.g. snd-usb-audio) is loaded before snd-interwave or
snd-ens1371, it will be assigned to the third or later slot.
ALSA PCM devices to OSS devices mapping
=======================================

923
Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl
View File

File diff suppressed because it is too large Load Diff

6
Documentation/sound/alsa/soc/DAI.txt
View File

@ -1,5 +1,5 @@
ASoC currently supports the three main Digital Audio Interfaces (DAI) found on
SoC controllers and portable audio CODECS today, namely AC97, I2S and PCM.
SoC controllers and portable audio CODECs today, namely AC97, I2S and PCM.
AC97
@ -25,7 +25,7 @@ left/right clock (LRC) synchronise the link. I2S is flexible in that either the
controller or CODEC can drive (master) the BCLK and LRC clock lines. Bit clock
usually varies depending on the sample rate and the master system clock
(SYSCLK). LRCLK is the same as the sample rate. A few devices support separate
ADC and DAC LRCLK's, this allows for simultaneous capture and playback at
ADC and DAC LRCLKs, this allows for simultaneous capture and playback at
different sample rates.
I2S has several different operating modes:-
@ -35,7 +35,7 @@ I2S has several different operating modes:-
o Left Justified - MSB is transmitted on transition of LRC.
o Right Justified - MSB is transmitted sample size BCLK's before LRC
o Right Justified - MSB is transmitted sample size BCLKs before LRC
transition.
PCM

Some files were not shown because too many files have changed in this diff Show More