diff options
Diffstat (limited to 'Documentation')
59 files changed, 2308 insertions, 528 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 45b3df936d2f..0c4cc688e89a 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -187,6 +187,8 @@ firmware_class/ - request_firmware() hotplug interface info. flexible-arrays.txt - how to make use of flexible sized arrays in linux +fmc/ + - information about the FMC bus abstraction frv/ - Fujitsu FR-V Linux documentation. futex-requeue-pi.txt diff --git a/Documentation/ABI/testing/configfs-usb-gadget b/Documentation/ABI/testing/configfs-usb-gadget new file mode 100644 index 000000000000..01e769d6984d --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget @@ -0,0 +1,81 @@ +What: /config/usb-gadget +Date: Jun 2013 +KenelVersion: 3.11 +Description: + This group contains sub-groups corresponding to created + USB gadgets. + +What: /config/usb-gadget/gadget +Date: Jun 2013 +KenelVersion: 3.11 +Description: + + The attributes of a gadget: + + UDC - bind a gadget to UDC/unbind a gadget; + write UDC's name found in /sys/class/udc/* + to bind a gadget, empty string "" to unbind. + + bDeviceClass - USB device class code + bDeviceSubClass - USB device subclass code + bDeviceProtocol - USB device protocol code + bMaxPacketSize0 - maximum endpoint 0 packet size + bcdDevice - bcd device release number + bcdUSB - bcd USB specification version number + idProduct - product ID + idVendor - vendor ID + +What: /config/usb-gadget/gadget/configs +Date: Jun 2013 +KenelVersion: 3.11 +Description: + This group contains a USB gadget's configurations + +What: /config/usb-gadget/gadget/configs/config +Date: Jun 2013 +KernelVersion: 3.11 +Description: + The attributes of a configuration: + + bmAttributes - configuration characteristics + MaxPower - maximum power consumption from the bus + +What: /config/usb-gadget/gadget/configs/config/strings +Date: Jun 2013 +KernelVersion: 3.11 +Description: + This group contains subdirectories for language-specific + strings for this configuration. + +What: /config/usb-gadget/gadget/configs/config/strings/language +Date: Jun 2013 +KernelVersion: 3.11 +Description: + The attributes: + + configuration - configuration description + + +What: /config/usb-gadget/gadget/functions +Date: Jun 2013 +KenelVersion: 3.11 +Description: + This group contains functions available to this USB gadget. + +What: /config/usb-gadget/gadget/strings +Date: Jun 2013 +KenelVersion: 3.11 +Description: + This group contains subdirectories for language-specific + strings for this gadget. + +What: /config/usb-gadget/gadget/strings/language +Date: Jun 2013 +KenelVersion: 3.11 +Description: + The attributes: + + serialnumber - gadget's serial number (string) + product - gadget's product description + manufacturer - gadget's manufacturer description + diff --git a/Documentation/ABI/testing/configfs-usb-gadget-acm b/Documentation/ABI/testing/configfs-usb-gadget-acm new file mode 100644 index 000000000000..5708a568b5f6 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-acm @@ -0,0 +1,8 @@ +What: /config/usb-gadget/gadget/functions/acm.name +Date: Jun 2013 +KenelVersion: 3.11 +Description: + + This item contains just one readonly attribute: port_num. + It contains the port number of the /dev/ttyGS<n> device + associated with acm function's instance "name". diff --git a/Documentation/ABI/testing/configfs-usb-gadget-ecm b/Documentation/ABI/testing/configfs-usb-gadget-ecm new file mode 100644 index 000000000000..6b9a582ce0b5 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-ecm @@ -0,0 +1,16 @@ +What: /config/usb-gadget/gadget/functions/ecm.name +Date: Jun 2013 +KenelVersion: 3.11 +Description: + The attributes: + + ifname - network device interface name associated with + this function instance + qmult - queue length multiplier for high and + super speed + host_addr - MAC address of host's end of this + Ethernet over USB link + dev_addr - MAC address of device's end of this + Ethernet over USB link + + diff --git a/Documentation/ABI/testing/configfs-usb-gadget-eem b/Documentation/ABI/testing/configfs-usb-gadget-eem new file mode 100644 index 000000000000..dbddf36b48b3 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-eem @@ -0,0 +1,14 @@ +What: /config/usb-gadget/gadget/functions/eem.name +Date: Jun 2013 +KenelVersion: 3.11 +Description: + The attributes: + + ifname - network device interface name associated with + this function instance + qmult - queue length multiplier for high and + super speed + host_addr - MAC address of host's end of this + Ethernet over USB link + dev_addr - MAC address of device's end of this + Ethernet over USB link diff --git a/Documentation/ABI/testing/configfs-usb-gadget-ncm b/Documentation/ABI/testing/configfs-usb-gadget-ncm new file mode 100644 index 000000000000..bc309f42357d --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-ncm @@ -0,0 +1,15 @@ +What: /config/usb-gadget/gadget/functions/ncm.name +Date: Jun 2013 +KenelVersion: 3.11 +Description: + The attributes: + + ifname - network device interface name associated with + this function instance + qmult - queue length multiplier for high and + super speed + host_addr - MAC address of host's end of this + Ethernet over USB link + dev_addr - MAC address of device's end of this + Ethernet over USB link + diff --git a/Documentation/ABI/testing/configfs-usb-gadget-obex b/Documentation/ABI/testing/configfs-usb-gadget-obex new file mode 100644 index 000000000000..aaa5c96fb7c6 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-obex @@ -0,0 +1,9 @@ +What: /config/usb-gadget/gadget/functions/obex.name +Date: Jun 2013 +KenelVersion: 3.11 +Description: + + This item contains just one readonly attribute: port_num. + It contains the port number of the /dev/ttyGS<n> device + associated with obex function's instance "name". + diff --git a/Documentation/ABI/testing/configfs-usb-gadget-phonet b/Documentation/ABI/testing/configfs-usb-gadget-phonet new file mode 100644 index 000000000000..3e3b742cdfd7 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-phonet @@ -0,0 +1,8 @@ +What: /config/usb-gadget/gadget/functions/phonet.name +Date: Jun 2013 +KenelVersion: 3.11 +Description: + + This item contains just one readonly attribute: ifname. + It contains the network interface name assigned during + network device registration. diff --git a/Documentation/ABI/testing/configfs-usb-gadget-rndis b/Documentation/ABI/testing/configfs-usb-gadget-rndis new file mode 100644 index 000000000000..822e6dad8fc0 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-rndis @@ -0,0 +1,14 @@ +What: /config/usb-gadget/gadget/functions/rndis.name +Date: Jun 2013 +KenelVersion: 3.11 +Description: + The attributes: + + ifname - network device interface name associated with + this function instance + qmult - queue length multiplier for high and + super speed + host_addr - MAC address of host's end of this + Ethernet over USB link + dev_addr - MAC address of device's end of this + Ethernet over USB link diff --git a/Documentation/ABI/testing/configfs-usb-gadget-serial b/Documentation/ABI/testing/configfs-usb-gadget-serial new file mode 100644 index 000000000000..16f130c1501f --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-serial @@ -0,0 +1,9 @@ +What: /config/usb-gadget/gadget/functions/gser.name +Date: Jun 2013 +KenelVersion: 3.11 +Description: + + This item contains just one readonly attribute: port_num. + It contains the port number of the /dev/ttyGS<n> device + associated with gser function's instance "name". + diff --git a/Documentation/ABI/testing/configfs-usb-gadget-subset b/Documentation/ABI/testing/configfs-usb-gadget-subset new file mode 100644 index 000000000000..154ae597cd99 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-subset @@ -0,0 +1,14 @@ +What: /config/usb-gadget/gadget/functions/geth.name +Date: Jun 2013 +KenelVersion: 3.11 +Description: + The attributes: + + ifname - network device interface name associated with + this function instance + qmult - queue length multiplier for high and + super speed + host_addr - MAC address of host's end of this + Ethernet over USB link + dev_addr - MAC address of device's end of this + Ethernet over USB link diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index 2e33dc6b2346..dda81ffae5cf 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -690,45 +690,45 @@ Description: Actually start the buffer capture up. Will start trigger if first device and appropriate. -What: /sys/bus/iio/devices/iio:deviceX/buffer/scan_elements +What: /sys/bus/iio/devices/iio:deviceX/scan_elements KernelVersion: 2.6.37 Contact: linux-iio@vger.kernel.org Description: Directory containing interfaces for elements that will be captured for a single triggered sample set in the buffer. -What: /sys/.../buffer/scan_elements/in_accel_x_en -What: /sys/.../buffer/scan_elements/in_accel_y_en -What: /sys/.../buffer/scan_elements/in_accel_z_en -What: /sys/.../buffer/scan_elements/in_anglvel_x_en -What: /sys/.../buffer/scan_elements/in_anglvel_y_en -What: /sys/.../buffer/scan_elements/in_anglvel_z_en -What: /sys/.../buffer/scan_elements/in_magn_x_en -What: /sys/.../buffer/scan_elements/in_magn_y_en -What: /sys/.../buffer/scan_elements/in_magn_z_en -What: /sys/.../buffer/scan_elements/in_timestamp_en -What: /sys/.../buffer/scan_elements/in_voltageY_supply_en -What: /sys/.../buffer/scan_elements/in_voltageY_en -What: /sys/.../buffer/scan_elements/in_voltageY-voltageZ_en -What: /sys/.../buffer/scan_elements/in_incli_x_en -What: /sys/.../buffer/scan_elements/in_incli_y_en -What: /sys/.../buffer/scan_elements/in_pressureY_en -What: /sys/.../buffer/scan_elements/in_pressure_en +What: /sys/.../iio:deviceX/scan_elements/in_accel_x_en +What: /sys/.../iio:deviceX/scan_elements/in_accel_y_en +What: /sys/.../iio:deviceX/scan_elements/in_accel_z_en +What: /sys/.../iio:deviceX/scan_elements/in_anglvel_x_en +What: /sys/.../iio:deviceX/scan_elements/in_anglvel_y_en +What: /sys/.../iio:deviceX/scan_elements/in_anglvel_z_en +What: /sys/.../iio:deviceX/scan_elements/in_magn_x_en +What: /sys/.../iio:deviceX/scan_elements/in_magn_y_en +What: /sys/.../iio:deviceX/scan_elements/in_magn_z_en +What: /sys/.../iio:deviceX/scan_elements/in_timestamp_en +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_supply_en +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_en +What: /sys/.../iio:deviceX/scan_elements/in_voltageY-voltageZ_en +What: /sys/.../iio:deviceX/scan_elements/in_incli_x_en +What: /sys/.../iio:deviceX/scan_elements/in_incli_y_en +What: /sys/.../iio:deviceX/scan_elements/in_pressureY_en +What: /sys/.../iio:deviceX/scan_elements/in_pressure_en KernelVersion: 2.6.37 Contact: linux-iio@vger.kernel.org Description: Scan element control for triggered data capture. -What: /sys/.../buffer/scan_elements/in_accel_type -What: /sys/.../buffer/scan_elements/in_anglvel_type -What: /sys/.../buffer/scan_elements/in_magn_type -What: /sys/.../buffer/scan_elements/in_incli_type -What: /sys/.../buffer/scan_elements/in_voltageY_type -What: /sys/.../buffer/scan_elements/in_voltage_type -What: /sys/.../buffer/scan_elements/in_voltageY_supply_type -What: /sys/.../buffer/scan_elements/in_timestamp_type -What: /sys/.../buffer/scan_elements/in_pressureY_type -What: /sys/.../buffer/scan_elements/in_pressure_type +What: /sys/.../iio:deviceX/scan_elements/in_accel_type +What: /sys/.../iio:deviceX/scan_elements/in_anglvel_type +What: /sys/.../iio:deviceX/scan_elements/in_magn_type +What: /sys/.../iio:deviceX/scan_elements/in_incli_type +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_type +What: /sys/.../iio:deviceX/scan_elements/in_voltage_type +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_supply_type +What: /sys/.../iio:deviceX/scan_elements/in_timestamp_type +What: /sys/.../iio:deviceX/scan_elements/in_pressureY_type +What: /sys/.../iio:deviceX/scan_elements/in_pressure_type KernelVersion: 2.6.37 Contact: linux-iio@vger.kernel.org Description: @@ -752,29 +752,29 @@ Description: For other storage combinations this attribute will be extended appropriately. -What: /sys/.../buffer/scan_elements/in_accel_type_available +What: /sys/.../iio:deviceX/scan_elements/in_accel_type_available KernelVersion: 2.6.37 Contact: linux-iio@vger.kernel.org Description: If the type parameter can take one of a small set of values, this attribute lists them. -What: /sys/.../buffer/scan_elements/in_voltageY_index -What: /sys/.../buffer/scan_elements/in_voltageY_supply_index -What: /sys/.../buffer/scan_elements/in_accel_x_index -What: /sys/.../buffer/scan_elements/in_accel_y_index -What: /sys/.../buffer/scan_elements/in_accel_z_index -What: /sys/.../buffer/scan_elements/in_anglvel_x_index -What: /sys/.../buffer/scan_elements/in_anglvel_y_index -What: /sys/.../buffer/scan_elements/in_anglvel_z_index -What: /sys/.../buffer/scan_elements/in_magn_x_index -What: /sys/.../buffer/scan_elements/in_magn_y_index -What: /sys/.../buffer/scan_elements/in_magn_z_index -What: /sys/.../buffer/scan_elements/in_incli_x_index -What: /sys/.../buffer/scan_elements/in_incli_y_index -What: /sys/.../buffer/scan_elements/in_timestamp_index -What: /sys/.../buffer/scan_elements/in_pressureY_index -What: /sys/.../buffer/scan_elements/in_pressure_index +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_index +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_supply_index +What: /sys/.../iio:deviceX/scan_elements/in_accel_x_index +What: /sys/.../iio:deviceX/scan_elements/in_accel_y_index +What: /sys/.../iio:deviceX/scan_elements/in_accel_z_index +What: /sys/.../iio:deviceX/scan_elements/in_anglvel_x_index +What: /sys/.../iio:deviceX/scan_elements/in_anglvel_y_index +What: /sys/.../iio:deviceX/scan_elements/in_anglvel_z_index +What: /sys/.../iio:deviceX/scan_elements/in_magn_x_index +What: /sys/.../iio:deviceX/scan_elements/in_magn_y_index +What: /sys/.../iio:deviceX/scan_elements/in_magn_z_index +What: /sys/.../iio:deviceX/scan_elements/in_incli_x_index +What: /sys/.../iio:deviceX/scan_elements/in_incli_y_index +What: /sys/.../iio:deviceX/scan_elements/in_timestamp_index +What: /sys/.../iio:deviceX/scan_elements/in_pressureY_index +What: /sys/.../iio:deviceX/scan_elements/in_pressure_index KernelVersion: 2.6.37 Contact: linux-iio@vger.kernel.org Description: diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci index 1ce5ae329c04..5210a51c90fd 100644 --- a/Documentation/ABI/testing/sysfs-bus-pci +++ b/Documentation/ABI/testing/sysfs-bus-pci @@ -64,7 +64,6 @@ Description: Writing a non-zero value to this attribute will force a rescan of all PCI buses in the system, and re-discover previously removed devices. - Depends on CONFIG_HOTPLUG. What: /sys/bus/pci/devices/.../msi_irqs/ Date: September, 2011 @@ -90,7 +89,6 @@ Contact: Linux PCI developers <linux-pci@vger.kernel.org> Description: Writing a non-zero value to this attribute will hot-remove the PCI device and any of its children. - Depends on CONFIG_HOTPLUG. What: /sys/bus/pci/devices/.../pci_bus/.../rescan Date: May 2011 @@ -99,7 +97,7 @@ Description: Writing a non-zero value to this attribute will force a rescan of the bus and all child buses, and re-discover devices removed earlier from this - part of the device tree. Depends on CONFIG_HOTPLUG. + part of the device tree. What: /sys/bus/pci/devices/.../rescan Date: January 2009 @@ -109,7 +107,6 @@ Description: force a rescan of the device's parent bus and all child buses, and re-discover devices removed earlier from this part of the device tree. - Depends on CONFIG_HOTPLUG. What: /sys/bus/pci/devices/.../reset Date: July 2009 diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb index f093e59cbe5f..9759b8c91332 100644 --- a/Documentation/ABI/testing/sysfs-bus-usb +++ b/Documentation/ABI/testing/sysfs-bus-usb @@ -236,3 +236,30 @@ Description: This attribute is to expose these information to user space. The file will read "hotplug", "wired" and "not used" if the information is available, and "unknown" otherwise. + +What: /sys/bus/usb/devices/.../power/usb2_lpm_l1_timeout +Date: May 2013 +Contact: Mathias Nyman <mathias.nyman@linux.intel.com> +Description: + USB 2.0 devices may support hardware link power management (LPM) + L1 sleep state. The usb2_lpm_l1_timeout attribute allows + tuning the timeout for L1 inactivity timer (LPM timer), e.g. + needed inactivity time before host requests the device to go to L1 sleep. + Useful for power management tuning. + Supported values are 0 - 65535 microseconds. + +What: /sys/bus/usb/devices/.../power/usb2_lpm_besl +Date: May 2013 +Contact: Mathias Nyman <mathias.nyman@linux.intel.com> +Description: + USB 2.0 devices that support hardware link power management (LPM) + L1 sleep state now use a best effort service latency value (BESL) to + indicate the best effort to resumption of service to the device after the + initiation of the resume event. + If the device does not have a preferred besl value then the host can select + one instead. This usb2_lpm_besl attribute allows to tune the host selected besl + value in order to tune power saving and service latency. + + Supported values are 0 - 15. + More information on how besl values map to microseconds can be found in + USB 2.0 ECN Errata for Link Power Management, section 4.10) diff --git a/Documentation/ABI/testing/sysfs-class-uwb_rc-wusbhc b/Documentation/ABI/testing/sysfs-class-uwb_rc-wusbhc index 25b1e751b777..5977e2875325 100644 --- a/Documentation/ABI/testing/sysfs-class-uwb_rc-wusbhc +++ b/Documentation/ABI/testing/sysfs-class-uwb_rc-wusbhc @@ -36,3 +36,22 @@ Description: Refer to [ECMA-368] section 10.3.1.1 for the value to use. + +What: /sys/class/uwb_rc/uwbN/wusbhc/wusb_dnts +Date: June 2013 +KernelVersion: 3.11 +Contact: Thomas Pugliese <thomas.pugliese@gmail.com> +Description: + The device notification time slot (DNTS) count and inverval in + milliseconds that the WUSB host should use. This controls how + often the devices will have the opportunity to send + notifications to the host. + +What: /sys/class/uwb_rc/uwbN/wusbhc/wusb_retry_count +Date: June 2013 +KernelVersion: 3.11 +Contact: Thomas Pugliese <thomas.pugliese@gmail.com> +Description: + The number of retries that the WUSB host should attempt + before reporting an error for a bus transaction. The range of + valid values is [0..15], where 0 indicates infinite retries. diff --git a/Documentation/DocBook/media/v4l/dev-codec.xml b/Documentation/DocBook/media/v4l/dev-codec.xml index dca0ecd54dc6..ff44c16fc080 100644 --- a/Documentation/DocBook/media/v4l/dev-codec.xml +++ b/Documentation/DocBook/media/v4l/dev-codec.xml @@ -1,18 +1,27 @@ <title>Codec Interface</title> - <note> - <title>Suspended</title> + <para>A V4L2 codec can compress, decompress, transform, or otherwise +convert video data from one format into another format, in memory. Typically +such devices are memory-to-memory devices (i.e. devices with the +<constant>V4L2_CAP_VIDEO_M2M</constant> or <constant>V4L2_CAP_VIDEO_M2M_MPLANE</constant> +capability set). +</para> - <para>This interface has been be suspended from the V4L2 API -implemented in Linux 2.6 until we have more experience with codec -device interfaces.</para> - </note> + <para>A memory-to-memory video node acts just like a normal video node, but it +supports both output (sending frames from memory to the codec hardware) and +capture (receiving the processed frames from the codec hardware into memory) +stream I/O. An application will have to setup the stream +I/O for both sides and finally call &VIDIOC-STREAMON; for both capture and output +to start the codec.</para> - <para>A V4L2 codec can compress, decompress, transform, or otherwise -convert video data from one format into another format, in memory. -Applications send data to be converted to the driver through a -&func-write; call, and receive the converted data through a -&func-read; call. For efficiency a driver may also support streaming -I/O.</para> + <para>Video compression codecs use the MPEG controls to setup their codec parameters +(note that the MPEG controls actually support many more codecs than just MPEG). +See <xref linkend="mpeg-controls"></xref>.</para> - <para>[to do]</para> + <para>Memory-to-memory devices can often be used as a shared resource: you can +open the video node multiple times, each application setting up their own codec properties +that are local to the file handle, and each can use it independently from the others. +The driver will arbitrate access to the codec and reprogram it whenever another file +handler gets access. This is different from the usual video node behavior where the video properties +are global to the device (i.e. changing something through one file handle is visible +through another file handle).</para> diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index bfc93cdcf696..bfe823dd0f31 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -493,7 +493,7 @@ and discussions on the V4L mailing list.</revremark> </partinfo> <title>Video for Linux Two API Specification</title> - <subtitle>Revision 3.9</subtitle> + <subtitle>Revision 3.10</subtitle> <chapter id="common"> &sub-common; diff --git a/Documentation/HOWTO b/Documentation/HOWTO index a9f288ff54f9..27faae3e3846 100644 --- a/Documentation/HOWTO +++ b/Documentation/HOWTO @@ -112,7 +112,7 @@ required reading: Other excellent descriptions of how to create patches properly are: "The Perfect Patch" - http://userweb.kernel.org/~akpm/stuff/tpp.txt + http://kerneltrap.org/node/3737 "Linux kernel patch submission format" http://linux.yyz.us/patch-format.html diff --git a/Documentation/SubmitChecklist b/Documentation/SubmitChecklist index dc0e33210d7e..2b7e32dfe00d 100644 --- a/Documentation/SubmitChecklist +++ b/Documentation/SubmitChecklist @@ -105,5 +105,5 @@ kernel patches. same time, just various/random combinations of them]: CONFIG_SMP, CONFIG_SYSFS, CONFIG_PROC_FS, CONFIG_INPUT, CONFIG_PCI, - CONFIG_BLOCK, CONFIG_PM, CONFIG_HOTPLUG, CONFIG_MAGIC_SYSRQ, + CONFIG_BLOCK, CONFIG_PM, CONFIG_MAGIC_SYSRQ, CONFIG_NET, CONFIG_INET=n (but latter with CONFIG_NET=y) diff --git a/Documentation/console/console.txt b/Documentation/console/console.txt index 926cf1b5e63e..f93810d599ad 100644 --- a/Documentation/console/console.txt +++ b/Documentation/console/console.txt @@ -12,20 +12,20 @@ The second type has to be explicitly loaded and unloaded. This will be called any time with each driver sharing the console with other drivers including the system driver. However, modular drivers cannot take over the console that is currently occupied by another modular driver. (Exception: Drivers that -call take_over_console() will succeed in the takeover regardless of the type +call do_take_over_console() will succeed in the takeover regardless of the type of driver occupying the consoles.) They can only take over the console that is occupied by the system driver. In the same token, if the modular driver is released by the console, the system driver will take over. Modular drivers, from the programmer's point of view, has to call: - take_over_console() - load and bind driver to console layer - give_up_console() - unbind and unload driver + do_take_over_console() - load and bind driver to console layer + give_up_console() - unload driver, it will only work if driver is fully unbond In newer kernels, the following are also available: - register_con_driver() - unregister_con_driver() + do_register_con_driver() + do_unregister_con_driver() If sysfs is enabled, the contents of /sys/class/vtconsole can be examined. This shows the console backends currently registered by the @@ -94,12 +94,12 @@ for more details). Notes for developers: ===================== -take_over_console() is now broken up into: +do_take_over_console() is now broken up into: - register_con_driver() - bind_con_driver() - private function + do_register_con_driver() + do_bind_con_driver() - private function -give_up_console() is a wrapper to unregister_con_driver(), and a driver must +give_up_console() is a wrapper to do_unregister_con_driver(), and a driver must be fully unbound for this call to succeed. con_is_bound() will check if the driver is bound or not. @@ -109,10 +109,10 @@ Guidelines for console driver writers: In order for binding to and unbinding from the console to properly work, console drivers must follow these guidelines: -1. All drivers, except system drivers, must call either register_con_driver() - or take_over_console(). register_con_driver() will just add the driver to +1. All drivers, except system drivers, must call either do_register_con_driver() + or do_take_over_console(). do_register_con_driver() will just add the driver to the console's internal list. It won't take over the - console. take_over_console(), as it name implies, will also take over (or + console. do_take_over_console(), as it name implies, will also take over (or bind to) the console. 2. All resources allocated during con->con_init() must be released in @@ -128,10 +128,10 @@ console drivers must follow these guidelines: rebind the driver to the console arrives. 4. Upon exit of the driver, ensure that the driver is totally unbound. If the - condition is satisfied, then the driver must call unregister_con_driver() + condition is satisfied, then the driver must call do_unregister_con_driver() or give_up_console(). -5. unregister_con_driver() can also be called on conditions which make it +5. do_unregister_con_driver() can also be called on conditions which make it impossible for the driver to service console requests. This can happen with the framebuffer console that suddenly lost all of its drivers. diff --git a/Documentation/cpu-hotplug.txt b/Documentation/cpu-hotplug.txt index 9f401350f502..0efd1b905b9d 100644 --- a/Documentation/cpu-hotplug.txt +++ b/Documentation/cpu-hotplug.txt @@ -128,7 +128,7 @@ A: When doing make defconfig, Enable CPU hotplug support "Processor type and Features" -> Support for Hotpluggable CPUs -Make sure that you have CONFIG_HOTPLUG, and CONFIG_SMP turned on as well. +Make sure that you have CONFIG_SMP turned on as well. You would need to enable CONFIG_HOTPLUG_CPU for SMP suspend/resume support as well. diff --git a/Documentation/devicetree/bindings/ata/atmel-at91_cf.txt b/Documentation/devicetree/bindings/ata/atmel-at91_cf.txt new file mode 100644 index 000000000000..c1d22b3ae134 --- /dev/null +++ b/Documentation/devicetree/bindings/ata/atmel-at91_cf.txt @@ -0,0 +1,19 @@ +Atmel AT91RM9200 CompactFlash + +Required properties: +- compatible : "atmel,at91rm9200-cf". +- reg : should specify localbus address and size used. +- gpios : specifies the gpio pins to control the CF device. Detect + and reset gpio's are mandatory while irq and vcc gpio's are + optional and may be set to 0 if not present. + +Example: +compact-flash@50000000 { + compatible = "atmel,at91rm9200-cf"; + reg = <0x50000000 0x30000000>; + gpios = <&pioC 13 0 /* irq */ + &pioC 15 0 /* detect */ + 0 /* vcc */ + &pioC 5 0 /* reset */ + >; +}; diff --git a/Documentation/devicetree/bindings/extcon/extcon-twl.txt b/Documentation/devicetree/bindings/extcon/extcon-twl.txt new file mode 100644 index 000000000000..58f531ab4df3 --- /dev/null +++ b/Documentation/devicetree/bindings/extcon/extcon-twl.txt @@ -0,0 +1,15 @@ +EXTCON FOR TWL CHIPS + +PALMAS USB COMPARATOR +Required Properties: + - compatible : Should be "ti,palmas-usb" or "ti,twl6035-usb" + - vbus-supply : phandle to the regulator device tree node. + +Optional Properties: + - ti,wakeup : To enable the wakeup comparator in probe + +palmas-usb { + compatible = "ti,twl6035-usb", "ti,palmas-usb"; + vbus-supply = <&smps10_reg>; + ti,wakeup; +}; diff --git a/Documentation/devicetree/bindings/iio/dac/ad7303.txt b/Documentation/devicetree/bindings/iio/dac/ad7303.txt new file mode 100644 index 000000000000..914610f0556e --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/ad7303.txt @@ -0,0 +1,23 @@ +Analog Devices AD7303 DAC device driver + +Required properties: + - compatible: Must be "adi,ad7303" + - reg: SPI chip select number for the device + - spi-max-frequency: Max SPI frequency to use (< 30000000) + - Vdd-supply: Phandle to the Vdd power supply + +Optional properties: + - REF-supply: Phandle to the external reference voltage supply. This should + only be set if there is an external reference voltage connected to the REF + pin. If the property is not set Vdd/2 is used as the reference voltage. + +Example: + + ad7303@4 { + compatible = "adi,ad7303"; + reg = <4>; + spi-max-frequency = <10000000>; + Vdd-supply = <&vdd_supply>; + adi,use-external-reference; + REF-supply = <&vref_supply>; + }; diff --git a/Documentation/devicetree/bindings/iio/frequency/adf4350.txt b/Documentation/devicetree/bindings/iio/frequency/adf4350.txt new file mode 100644 index 000000000000..f8c181d81d2d --- /dev/null +++ b/Documentation/devicetree/bindings/iio/frequency/adf4350.txt @@ -0,0 +1,86 @@ +Analog Devices ADF4350/ADF4351 device driver + +Required properties: + - compatible: Should be one of + * "adi,adf4350": When using the ADF4350 device + * "adi,adf4351": When using the ADF4351 device + - reg: SPI chip select numbert for the device + - spi-max-frequency: Max SPI frequency to use (< 20000000) + - clocks: From common clock binding. Clock is phandle to clock for + ADF435x Reference Clock (CLKIN). + +Optional properties: + - gpios: GPIO Lock detect - If set with a valid phandle and GPIO number, + pll lock state is tested upon read. + - adi,channel-spacing: Channel spacing in Hz (influences MODULUS). + - adi,power-up-frequency: If set in Hz the PLL tunes to + the desired frequency on probe. + - adi,reference-div-factor: If set the driver skips dynamic calculation + and uses this default value instead. + - adi,reference-doubler-enable: Enables reference doubler. + - adi,reference-div2-enable: Enables reference divider. + - adi,phase-detector-polarity-positive-enable: Enables positive phase + detector polarity. Default = negative. + - adi,lock-detect-precision-6ns-enable: Enables 6ns lock detect precision. + Default = 10ns. + - adi,lock-detect-function-integer-n-enable: Enables lock detect + for integer-N mode. Default = factional-N mode. + - adi,charge-pump-current: Charge pump current in mA. + Default = 2500mA. + - adi,muxout-select: On chip multiplexer output selection. + Valid values for the multiplexer output are: + 0: Three-State Output (default) + 1: DVDD + 2: DGND + 3: R-Counter output + 4: N-Divider output + 5: Analog lock detect + 6: Digital lock detect + - adi,low-spur-mode-enable: Enables low spur mode. + Default = Low noise mode. + - adi,cycle-slip-reduction-enable: Enables cycle slip reduction. + - adi,charge-cancellation-enable: Enabled charge pump + charge cancellation for integer-N modes. + - adi,anti-backlash-3ns-enable: Enables 3ns antibacklash pulse width + for integer-N modes. + - adi,band-select-clock-mode-high-enable: Enables faster band + selection logic. + - adi,12bit-clk-divider: Clock divider value used when + adi,12bit-clkdiv-mode != 0 + - adi,clk-divider-mode: + Valid values for the clkdiv mode are: + 0: Clock divider off (default) + 1: Fast lock enable + 2: Phase resync enable + - adi,aux-output-enable: Enables auxiliary RF output. + - adi,aux-output-fundamental-enable: Selects fundamental VCO output on + the auxiliary RF output. Default = Output of RF dividers. + - adi,mute-till-lock-enable: Enables Mute-Till-Lock-Detect function. + - adi,output-power: Output power selection. + Valid values for the power mode are: + 0: -4dBm (default) + 1: -1dBm + 2: +2dBm + 3: +5dBm + - adi,aux-output-power: Auxiliary output power selection. + Valid values for the power mode are: + 0: -4dBm (default) + 1: -1dBm + 2: +2dBm + 3: +5dBm + + +Example: + lo_pll0_rx_adf4351: adf4351-rx-lpc@4 { + compatible = "adi,adf4351"; + reg = <4>; + spi-max-frequency = <10000000>; + clocks = <&clk0_ad9523 9>; + clock-names = "clkin"; + adi,channel-spacing = <10000>; + adi,power-up-frequency = <2400000000>; + adi,phase-detector-polarity-positive-enable; + adi,charge-pump-current = <2500>; + adi,output-power = <3>; + adi,mute-till-lock-enable; + }; diff --git a/Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt b/Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt new file mode 100644 index 000000000000..011679f1a425 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt @@ -0,0 +1,18 @@ +* AsahiKASEI AK8975 magnetometer sensor + +Required properties: + + - compatible : should be "asahi-kasei,ak8975" + - reg : the I2C address of the magnetometer + +Optional properties: + + - gpios : should be device tree identifier of the magnetometer DRDY pin + +Example: + +ak8975@0c { + compatible = "asahi-kasei,ak8975"; + reg = <0x0c>; + gpios = <&gpj0 7 0>; +}; diff --git a/Documentation/devicetree/bindings/media/exynos-fimc-lite.txt b/Documentation/devicetree/bindings/media/exynos-fimc-lite.txt index 3f62adfb3e0b..de9f6b78ee51 100644 --- a/Documentation/devicetree/bindings/media/exynos-fimc-lite.txt +++ b/Documentation/devicetree/bindings/media/exynos-fimc-lite.txt @@ -2,7 +2,7 @@ Exynos4x12/Exynos5 SoC series camera host interface (FIMC-LITE) Required properties: -- compatible : should be "samsung,exynos4212-fimc" for Exynos4212 and +- compatible : should be "samsung,exynos4212-fimc-lite" for Exynos4212 and Exynos4412 SoCs; - reg : physical base address and size of the device memory mapped registers; diff --git a/Documentation/devicetree/bindings/memory-controllers/mvebu-devbus.txt b/Documentation/devicetree/bindings/memory-controllers/mvebu-devbus.txt new file mode 100644 index 000000000000..653c90c34a71 --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/mvebu-devbus.txt @@ -0,0 +1,156 @@ +Device tree bindings for MVEBU Device Bus controllers + +The Device Bus controller available in some Marvell's SoC allows to control +different types of standard memory and I/O devices such as NOR, NAND, and FPGA. +The actual devices are instantiated from the child nodes of a Device Bus node. + +Required properties: + + - compatible: Currently only Armada 370/XP SoC are supported, + with this compatible string: + + marvell,mvebu-devbus + + - reg: A resource specifier for the register space. + This is the base address of a chip select within + the controller's register space. + (see the example below) + + - #address-cells: Must be set to 1 + - #size-cells: Must be set to 1 + - ranges: Must be set up to reflect the memory layout with four + integer values for each chip-select line in use: + 0 <physical address of mapping> <size> + +Mandatory timing properties for child nodes: + +Read parameters: + + - devbus,turn-off-ps: Defines the time during which the controller does not + drive the AD bus after the completion of a device read. + This prevents contentions on the Device Bus after a read + cycle from a slow device. + + - devbus,bus-width: Defines the bus width (e.g. <16>) + + - devbus,badr-skew-ps: Defines the time delay from from A[2:0] toggle, + to read data sample. This parameter is useful for + synchronous pipelined devices, where the address + precedes the read data by one or two cycles. + + - devbus,acc-first-ps: Defines the time delay from the negation of + ALE[0] to the cycle that the first read data is sampled + by the controller. + + - devbus,acc-next-ps: Defines the time delay between the cycle that + samples data N and the cycle that samples data N+1 + (in burst accesses). + + - devbus,rd-setup-ps: Defines the time delay between DEV_CSn assertion to + DEV_OEn assertion. If set to 0 (default), + DEV_OEn and DEV_CSn are asserted at the same cycle. + This parameter has no affect on <acc-first-ps> parameter + (no affect on first data sample). Set <rd-setup-ps> + to a value smaller than <acc-first-ps>. + + - devbus,rd-hold-ps: Defines the time between the last data sample to the + de-assertion of DEV_CSn. If set to 0 (default), + DEV_OEn and DEV_CSn are de-asserted at the same cycle + (the cycle of the last data sample). + This parameter has no affect on DEV_OEn de-assertion. + DEV_OEn is always de-asserted the next cycle after + last data sampled. Also this parameter has no + affect on <turn-off-ps> parameter. + Set <rd-hold-ps> to a value smaller than <turn-off-ps>. + +Write parameters: + + - devbus,ale-wr-ps: Defines the time delay from the ALE[0] negation cycle + to the DEV_WEn assertion. + + - devbus,wr-low-ps: Defines the time during which DEV_WEn is active. + A[2:0] and Data are kept valid as long as DEV_WEn + is active. This parameter defines the setup time of + address and data to DEV_WEn rise. + + - devbus,wr-high-ps: Defines the time during which DEV_WEn is kept + inactive (high) between data beats of a burst write. + DEV_A[2:0] and Data are kept valid (do not toggle) for + <wr-high-ps> - <tick> ps. + This parameter defines the hold time of address and + data after DEV_WEn rise. + + - devbus,sync-enable: Synchronous device enable. + 1: True + 0: False + +An example for an Armada XP GP board, with a 16 MiB NOR device as child +is showed below. Note that the Device Bus driver is in charge of allocating +the mbus address decoding window for each of its child devices. +The window is created using the chip select specified in the child +device node together with the base address and size specified in the ranges +property. For instance, in the example below the allocated decoding window +will start at base address 0xf0000000, with a size 0x1000000 (16 MiB) +for chip select 0 (a.k.a DEV_BOOTCS). + +This address window handling is done in this mvebu-devbus only as a temporary +solution. It will be removed when the support for mbus device tree binding is +added. + +The reg property implicitly specifies the chip select as this: + + 0x10400: DEV_BOOTCS + 0x10408: DEV_CS0 + 0x10410: DEV_CS1 + 0x10418: DEV_CS2 + 0x10420: DEV_CS3 + +Example: + + devbus-bootcs@d0010400 { + status = "okay"; + ranges = <0 0xf0000000 0x1000000>; /* @addr 0xf0000000, size 0x1000000 */ + #address-cells = <1>; + #size-cells = <1>; + + /* Device Bus parameters are required */ + + /* Read parameters */ + devbus,bus-width = <8>; + devbus,turn-off-ps = <60000>; + devbus,badr-skew-ps = <0>; + devbus,acc-first-ps = <124000>; + devbus,acc-next-ps = <248000>; + devbus,rd-setup-ps = <0>; + devbus,rd-hold-ps = <0>; + + /* Write parameters */ + devbus,sync-enable = <0>; + devbus,wr-high-ps = <60000>; + devbus,wr-low-ps = <60000>; + devbus,ale-wr-ps = <60000>; + + flash@0 { + compatible = "cfi-flash"; + + /* 16 MiB */ + reg = <0 0x1000000>; + bank-width = <2>; + #address-cells = <1>; + #size-cells = <1>; + + /* + * We split the 16 MiB in two partitions, + * just as an example. + */ + partition@0 { + label = "First"; + reg = <0 0x800000>; + }; + + partition@800000 { + label = "Second"; + reg = <0x800000 0x800000>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/staging/imx-drm/ldb.txt b/Documentation/devicetree/bindings/staging/imx-drm/ldb.txt new file mode 100644 index 000000000000..ed9377811ee2 --- /dev/null +++ b/Documentation/devicetree/bindings/staging/imx-drm/ldb.txt @@ -0,0 +1,99 @@ +Device-Tree bindings for LVDS Display Bridge (ldb) + +LVDS Display Bridge +=================== + +The LVDS Display Bridge device tree node contains up to two lvds-channel +nodes describing each of the two LVDS encoder channels of the bridge. + +Required properties: + - #address-cells : should be <1> + - #size-cells : should be <0> + - compatible : should be "fsl,imx53-ldb" or "fsl,imx6q-ldb". + Both LDB versions are similar, but i.MX6 has an additional + multiplexer in the front to select any of the four IPU display + interfaces as input for each LVDS channel. + - gpr : should be <&gpr> on i.MX53 and i.MX6q. + The phandle points to the iomuxc-gpr region containing the LVDS + control register. +- clocks, clock-names : phandles to the LDB divider and selector clocks and to + the display interface selector clocks, as described in + Documentation/devicetree/bindings/clock/clock-bindings.txt + The following clocks are expected on i.MX53: + "di0_pll" - LDB LVDS channel 0 mux + "di1_pll" - LDB LVDS channel 1 mux + "di0" - LDB LVDS channel 0 gate + "di1" - LDB LVDS channel 1 gate + "di0_sel" - IPU1 DI0 mux + "di1_sel" - IPU1 DI1 mux + On i.MX6q the following additional clocks are needed: + "di2_sel" - IPU2 DI0 mux + "di3_sel" - IPU2 DI1 mux + The needed clock numbers for each are documented in + Documentation/devicetree/bindings/clock/imx5-clock.txt, and in + Documentation/devicetree/bindings/clock/imx6q-clock.txt. + +Optional properties: + - pinctrl-names : should be "default" on i.MX53, not used on i.MX6q + - pinctrl-0 : a phandle pointing to LVDS pin settings on i.MX53, + not used on i.MX6q + - fsl,dual-channel : boolean. if it exists, only LVDS channel 0 should + be configured - one input will be distributed on both outputs in dual + channel mode + +LVDS Channel +============ + +Each LVDS Channel has to contain a display-timings node that describes the +video timings for the connected LVDS display. For detailed information, also +have a look at Documentation/devicetree/bindings/video/display-timing.txt. + +Required properties: + - reg : should be <0> or <1> + - crtcs : a list of phandles with index pointing to the IPU display interfaces + that can be used as video source for this channel. + - fsl,data-mapping : should be "spwg" or "jeida" + This describes how the color bits are laid out in the + serialized LVDS signal. + - fsl,data-width : should be <18> or <24> + +example: + +gpr: iomuxc-gpr@53fa8000 { + /* ... */ +}; + +ldb: ldb@53fa8008 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "fsl,imx53-ldb"; + gpr = <&gpr>; + clocks = <&clks 122>, <&clks 120>, + <&clks 115>, <&clks 116>, + <&clks 123>, <&clks 85>; + clock-names = "di0_pll", "di1_pll", + "di0_sel", "di1_sel", + "di0", "di1"; + + lvds-channel@0 { + reg = <0>; + crtcs = <&ipu 0>; + fsl,data-mapping = "spwg"; + fsl,data-width = <24>; + + display-timings { + /* ... */ + }; + }; + + lvds-channel@1 { + reg = <1>; + crtcs = <&ipu 1>; + fsl,data-mapping = "spwg"; + fsl,data-width = <24>; + + display-timings { + /* ... */ + }; + }; +}; diff --git a/Documentation/devicetree/bindings/tty/serial/fsl-imx-uart.txt b/Documentation/devicetree/bindings/tty/serial/fsl-imx-uart.txt index b462d0c54823..c662eb36be29 100644 --- a/Documentation/devicetree/bindings/tty/serial/fsl-imx-uart.txt +++ b/Documentation/devicetree/bindings/tty/serial/fsl-imx-uart.txt @@ -8,6 +8,8 @@ Required properties: Optional properties: - fsl,uart-has-rtscts : Indicate the uart has rts and cts - fsl,irda-mode : Indicate the uart supports irda mode +- fsl,dte-mode : Indicate the uart works in DTE mode. The uart works + is DCE mode by default. Example: @@ -16,4 +18,5 @@ serial@73fbc000 { reg = <0x73fbc000 0x4000>; interrupts = <31>; fsl,uart-has-rtscts; + fsl,dte-mode; }; diff --git a/Documentation/devicetree/bindings/tty/serial/fsl-lpuart.txt b/Documentation/devicetree/bindings/tty/serial/fsl-lpuart.txt new file mode 100644 index 000000000000..6fd1dd1638dd --- /dev/null +++ b/Documentation/devicetree/bindings/tty/serial/fsl-lpuart.txt @@ -0,0 +1,14 @@ +* Freescale low power universal asynchronous receiver/transmitter (lpuart) + +Required properties: +- compatible : Should be "fsl,<soc>-lpuart" +- reg : Address and length of the register set for the device +- interrupts : Should contain uart interrupt + +Example: + +uart0: serial@40027000 { + compatible = "fsl,vf610-lpuart"; + reg = <0x40027000 0x1000>; + interrupts = <0 61 0x00>; + }; diff --git a/Documentation/devicetree/bindings/usb/ci13xxx-imx.txt b/Documentation/devicetree/bindings/usb/ci13xxx-imx.txt index 1c04a4c9515f..b4b5b7906c88 100644 --- a/Documentation/devicetree/bindings/usb/ci13xxx-imx.txt +++ b/Documentation/devicetree/bindings/usb/ci13xxx-imx.txt @@ -5,6 +5,12 @@ Required properties: - reg: Should contain registers location and length - interrupts: Should contain controller interrupt +Recommended properies: +- phy_type: the type of the phy connected to the core. Should be one + of "utmi", "utmi_wide", "ulpi", "serial" or "hsic". Without this + property the PORTSC register won't be touched +- dr_mode: One of "host", "peripheral" or "otg". Defaults to "otg" + Optional properties: - fsl,usbphy: phandler of usb phy that connects to the only one port - fsl,usbmisc: phandler of non-core register device, with one argument diff --git a/Documentation/devicetree/bindings/usb/nvidia,tegra20-ehci.txt b/Documentation/devicetree/bindings/usb/nvidia,tegra20-ehci.txt index 34c952883276..df0933043a5b 100644 --- a/Documentation/devicetree/bindings/usb/nvidia,tegra20-ehci.txt +++ b/Documentation/devicetree/bindings/usb/nvidia,tegra20-ehci.txt @@ -6,27 +6,10 @@ Practice : Universal Serial Bus" with the following modifications and additions : Required properties : - - compatible : Should be "nvidia,tegra20-ehci" for USB controllers - used in host mode. - - phy_type : Should be one of "ulpi" or "utmi". - - nvidia,vbus-gpio : If present, specifies a gpio that needs to be - activated for the bus to be powered. - - nvidia,phy : phandle of the PHY instance, the controller is connected to. - -Required properties for phy_type == ulpi: - - nvidia,phy-reset-gpio : The GPIO used to reset the PHY. + - compatible : Should be "nvidia,tegra20-ehci". + - nvidia,phy : phandle of the PHY that the controller is connected to. + - clocks : Contains a single entry which defines the USB controller's clock. Optional properties: - - dr_mode : dual role mode. Indicates the working mode for - nvidia,tegra20-ehci compatible controllers. Can be "host", "peripheral", - or "otg". Default to "host" if not defined for backward compatibility. - host means this is a host controller - peripheral means it is device controller - otg means it can operate as either ("on the go") - - nvidia,has-legacy-mode : boolean indicates whether this controller can - operate in legacy mode (as APX 2500 / 2600). In legacy mode some - registers are accessed through the APB_MISC base address instead of - the USB controller. Since this is a legacy issue it probably does not - warrant a compatible string of its own. - - nvidia,needs-double-reset : boolean is to be set for some of the Tegra2 - USB ports, which need reset twice due to hardware issues. + - nvidia,needs-double-reset : boolean is to be set for some of the Tegra20 + USB ports, which need reset twice due to hardware issues. diff --git a/Documentation/devicetree/bindings/usb/nvidia,tegra20-usb-phy.txt b/Documentation/devicetree/bindings/usb/nvidia,tegra20-usb-phy.txt index 6bdaba2f0aa1..c4c9e9e664aa 100644 --- a/Documentation/devicetree/bindings/usb/nvidia,tegra20-usb-phy.txt +++ b/Documentation/devicetree/bindings/usb/nvidia,tegra20-usb-phy.txt @@ -4,14 +4,49 @@ The device node for Tegra SOC USB PHY: Required properties : - compatible : Should be "nvidia,tegra20-usb-phy". - - reg : Address and length of the register set for the USB PHY interface. - - phy_type : Should be one of "ulpi" or "utmi". + - reg : Defines the following set of registers, in the order listed: + - The PHY's own register set. + Always present. + - The register set of the PHY containing the UTMI pad control registers. + Present if-and-only-if phy_type == utmi. + - phy_type : Should be one of "utmi", "ulpi" or "hsic". + - clocks : Defines the clocks listed in the clock-names property. + - clock-names : The following clock names must be present: + - reg: The clock needed to access the PHY's own registers. This is the + associated EHCI controller's clock. Always present. + - pll_u: PLL_U. Always present. + - timer: The timeout clock (clk_m). Present if phy_type == utmi. + - utmi-pads: The clock needed to access the UTMI pad control registers. + Present if phy_type == utmi. + - ulpi-link: The clock Tegra provides to the ULPI PHY (cdev2). + Present if phy_type == ulpi, and ULPI link mode is in use. Required properties for phy_type == ulpi: - nvidia,phy-reset-gpio : The GPIO used to reset the PHY. +Required PHY timing params for utmi phy: + - nvidia,hssync-start-delay : Number of 480 Mhz clock cycles to wait before + start of sync launches RxActive + - nvidia,elastic-limit : Variable FIFO Depth of elastic input store + - nvidia,idle-wait-delay : Number of 480 Mhz clock cycles of idle to wait + before declare IDLE. + - nvidia,term-range-adj : Range adjusment on terminations + - nvidia,xcvr-setup : HS driver output control + - nvidia,xcvr-lsfslew : LS falling slew rate control. + - nvidia,xcvr-lsrslew : LS rising slew rate control. + Optional properties: - nvidia,has-legacy-mode : boolean indicates whether this controller can operate in legacy mode (as APX 2500 / 2600). In legacy mode some registers are accessed through the APB_MISC base address instead of - the USB controller.
\ No newline at end of file + the USB controller. + - nvidia,is-wired : boolean. Indicates whether we can do certain kind of power + optimizations for the devices that are always connected. e.g. modem. + - dr_mode : dual role mode. Indicates the working mode for the PHY. Can be + "host", "peripheral", or "otg". Defaults to "host" if not defined. + host means this is a host controller + peripheral means it is device controller + otg means it can operate as either ("on the go") + +Required properties for dr_mode == otg: + - vbus-supply: regulator for VBUS diff --git a/Documentation/devicetree/bindings/usb/usb3503.txt b/Documentation/devicetree/bindings/usb/usb3503.txt index 6813a715fc7d..8c5be48b43c8 100644 --- a/Documentation/devicetree/bindings/usb/usb3503.txt +++ b/Documentation/devicetree/bindings/usb/usb3503.txt @@ -4,6 +4,10 @@ Required properties: - compatible: Should be "smsc,usb3503". - reg: Specifies the i2c slave address, it should be 0x08. - connect-gpios: Should specify GPIO for connect. +- disabled-ports: Should specify the ports unused. + '1' or '2' or '3' are availe for this property to describe the port + number. 1~3 property values are possible to be desribed. + Do not describe this property if all ports have to be enabled. - intn-gpios: Should specify GPIO for interrupt. - reset-gpios: Should specify GPIO for reset. - initial-mode: Should specify initial mode. @@ -14,6 +18,7 @@ Examples: compatible = "smsc,usb3503"; reg = <0x08>; connect-gpios = <&gpx3 0 1>; + disabled-ports = <2 3>; intn-gpios = <&gpx3 4 1>; reset-gpios = <&gpx3 5 1>; initial-mode = <1>; diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking index 0706d32a61e6..9858f337529c 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/Locking @@ -189,7 +189,7 @@ prototypes: loff_t pos, unsigned len, unsigned copied, struct page *page, void *fsdata); sector_t (*bmap)(struct address_space *, sector_t); - int (*invalidatepage) (struct page *, unsigned long); + void (*invalidatepage) (struct page *, unsigned int, unsigned int); int (*releasepage) (struct page *, int); void (*freepage)(struct page *); int (*direct_IO)(int, struct kiocb *, const struct iovec *iov, @@ -310,8 +310,8 @@ filesystems and by the swapper. The latter will eventually go away. Please, keep it that way and don't breed new callers. ->invalidatepage() is called when the filesystem must attempt to drop -some or all of the buffers from the page when it is being truncated. It -returns zero on success. If ->invalidatepage is zero, the kernel uses +some or all of the buffers from the page when it is being truncated. It +returns zero on success. If ->invalidatepage is zero, the kernel uses block_invalidatepage() instead. ->releasepage() is called when the kernel is about to try to drop the @@ -414,7 +414,7 @@ prototypes: ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *); ssize_t (*aio_read) (struct kiocb *, const struct iovec *, unsigned long, loff_t); ssize_t (*aio_write) (struct kiocb *, const struct iovec *, unsigned long, loff_t); - int (*readdir) (struct file *, void *, filldir_t); + int (*iterate) (struct file *, struct dir_context *); unsigned int (*poll) (struct file *, struct poll_table_struct *); long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long); long (*compat_ioctl) (struct file *, unsigned int, unsigned long); diff --git a/Documentation/filesystems/f2fs.txt b/Documentation/filesystems/f2fs.txt index bd3c56c67380..b91e2f26b672 100644 --- a/Documentation/filesystems/f2fs.txt +++ b/Documentation/filesystems/f2fs.txt @@ -98,8 +98,13 @@ Cleaning Overhead MOUNT OPTIONS ================================================================================ -background_gc_off Turn off cleaning operations, namely garbage collection, - triggered in background when I/O subsystem is idle. +background_gc=%s Turn on/off cleaning operations, namely garbage + collection, triggered in background when I/O subsystem is + idle. If background_gc=on, it will turn on the garbage + collection and if background_gc=off, garbage collection + will be truned off. + Default value for this option is on. So garbage + collection is on by default. disable_roll_forward Disable the roll-forward recovery routine discard Issue discard/TRIM commands when a segment is cleaned. no_heap Disable heap-style segment allocation which finds free diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting index 4db22f6491e0..206a1bdc7321 100644 --- a/Documentation/filesystems/porting +++ b/Documentation/filesystems/porting @@ -445,3 +445,9 @@ object doesn't exist. It's remote/distributed ones that might care... [mandatory] FS_REVAL_DOT is gone; if you used to have it, add ->d_weak_revalidate() in your dentry operations instead. +-- +[mandatory] + vfs_readdir() is gone; switch to iterate_dir() instead +-- +[mandatory] + ->readdir() is gone now; switch to ->iterate() diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt index bc4b06b3160a..e6bd1ffd821e 100644 --- a/Documentation/filesystems/vfs.txt +++ b/Documentation/filesystems/vfs.txt @@ -549,7 +549,7 @@ struct address_space_operations ------------------------------- This describes how the VFS can manipulate mapping of a file to page cache in -your filesystem. As of kernel 2.6.22, the following members are defined: +your filesystem. The following members are defined: struct address_space_operations { int (*writepage)(struct page *page, struct writeback_control *wbc); @@ -566,7 +566,7 @@ struct address_space_operations { loff_t pos, unsigned len, unsigned copied, struct page *page, void *fsdata); sector_t (*bmap)(struct address_space *, sector_t); - int (*invalidatepage) (struct page *, unsigned long); + void (*invalidatepage) (struct page *, unsigned int, unsigned int); int (*releasepage) (struct page *, int); void (*freepage)(struct page *); ssize_t (*direct_IO)(int, struct kiocb *, const struct iovec *iov, @@ -685,14 +685,14 @@ struct address_space_operations { invalidatepage: If a page has PagePrivate set, then invalidatepage will be called when part or all of the page is to be removed from the address space. This generally corresponds to either a - truncation or a complete invalidation of the address space - (in the latter case 'offset' will always be 0). - Any private data associated with the page should be updated - to reflect this truncation. If offset is 0, then - the private data should be released, because the page - must be able to be completely discarded. This may be done by - calling the ->releasepage function, but in this case the - release MUST succeed. + truncation, punch hole or a complete invalidation of the address + space (in the latter case 'offset' will always be 0 and 'length' + will be PAGE_CACHE_SIZE). Any private data associated with the page + should be updated to reflect this truncation. If offset is 0 and + length is PAGE_CACHE_SIZE, then the private data should be released, + because the page must be able to be completely discarded. This may + be done by calling the ->releasepage function, but in this case the + release MUST succeed. releasepage: releasepage is called on PagePrivate pages to indicate that the page should be freed if possible. ->releasepage @@ -777,7 +777,7 @@ struct file_operations { ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *); ssize_t (*aio_read) (struct kiocb *, const struct iovec *, unsigned long, loff_t); ssize_t (*aio_write) (struct kiocb *, const struct iovec *, unsigned long, loff_t); - int (*readdir) (struct file *, void *, filldir_t); + int (*iterate) (struct file *, struct dir_context *); unsigned int (*poll) (struct file *, struct poll_table_struct *); long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long); long (*compat_ioctl) (struct file *, unsigned int, unsigned long); @@ -815,7 +815,7 @@ otherwise noted. aio_write: called by io_submit(2) and other asynchronous I/O operations - readdir: called when the VFS needs to read the directory contents + iterate: called when the VFS needs to read the directory contents poll: called by the VFS when a process wants to check if there is activity on this file and (optionally) go to sleep until there diff --git a/Documentation/fmc/00-INDEX b/Documentation/fmc/00-INDEX new file mode 100644 index 000000000000..431c69570f43 --- /dev/null +++ b/Documentation/fmc/00-INDEX @@ -0,0 +1,38 @@ + +Documentation in this directory comes from sections of the manual we +wrote for the externally-developed fmc-bus package. The complete +manual as of today (2013-02) is available in PDF format at +http://www.ohwr.org/projects/fmc-bus/files + +00-INDEX + - this file. + +FMC-and-SDB.txt + - What are FMC and SDB, basic concepts for this framework + +API.txt + - The functions that are exported by the bus driver + +parameters.txt + - The module parameters + +carrier.txt + - writing a carrier (a device) + +mezzanine.txt + - writing code for your mezzanine (a driver) + +identifiers.txt + - how identification and matching works + +fmc-fakedev.txt + - about drivers/fmc/fmc-fakedev.ko + +fmc-trivial.txt + - about drivers/fmc/fmc-trivial.ko + +fmc-write-eeprom.txt + - about drivers/fmc/fmc-write-eeprom.ko + +fmc-chardev.txt + - about drivers/fmc/fmc-chardev.ko diff --git a/Documentation/fmc/API.txt b/Documentation/fmc/API.txt new file mode 100644 index 000000000000..06b06b92c794 --- /dev/null +++ b/Documentation/fmc/API.txt @@ -0,0 +1,47 @@ +Functions Exported by fmc.ko +**************************** + +The FMC core exports the usual 4 functions that are needed for a bus to +work, and a few more: + + int fmc_driver_register(struct fmc_driver *drv); + void fmc_driver_unregister(struct fmc_driver *drv); + int fmc_device_register(struct fmc_device *fmc); + void fmc_device_unregister(struct fmc_device *fmc); + + int fmc_device_register_n(struct fmc_device **fmc, int n); + void fmc_device_unregister_n(struct fmc_device **fmc, int n); + + uint32_t fmc_readl(struct fmc_device *fmc, int offset); + void fmc_writel(struct fmc_device *fmc, uint32_t val, int off); + void *fmc_get_drvdata(struct fmc_device *fmc); + void fmc_set_drvdata(struct fmc_device *fmc, void *data); + + int fmc_reprogram(struct fmc_device *f, struct fmc_driver *d, char *gw, + int sdb_entry); + +The data structure that describe a device is detailed in *note FMC +Device::, the one that describes a driver is detailed in *note FMC +Driver::. Please note that structures of type fmc_device must be +allocated by the caller, but must not be released after unregistering. +The fmc-bus itself takes care of releasing the structure when their use +count reaches zero - actually, the device model does that in lieu of us. + +The functions to register and unregister n devices are meant to be used +by carriers that host more than one mezzanine. The devices must all be +registered at the same time because if the FPGA is reprogrammed, all +devices in the array are affected. Usually, the driver matching the +first device will reprogram the FPGA, so other devices must know they +are already driven by a reprogrammed FPGA. + +If a carrier hosts slots that are driven by different FPGA devices, it +should register as a group only mezzanines that are driven by the same +FPGA, for the reason outlined above. + +Finally, the fmc_reprogram function calls the reprogram method (see +*note The API Offered by Carriers:: and also scans the memory area for +an SDB tree. You can pass -1 as sdb_entry to disable such scan. +Otherwise, the function fails if no tree is found at the specified +entry point. The function is meant to factorize common code, and by +the time you read this it is already used by the spec-sw and fine-delay +modules. diff --git a/Documentation/fmc/FMC-and-SDB.txt b/Documentation/fmc/FMC-and-SDB.txt new file mode 100644 index 000000000000..fa14e0b24521 --- /dev/null +++ b/Documentation/fmc/FMC-and-SDB.txt @@ -0,0 +1,88 @@ + +FMC (FPGA Mezzanine Card) is the standard we use for our I/O devices, +in the context of White Rabbit and related hardware. + +In our I/O environments we need to write drivers for each mezzanine +card, and such drivers must work regardless of the carrier being used. +To achieve this, we abstract the FMC interface. + +We have a carrier for PCI-E called SPEC and one for VME called SVEC, +but more are planned. Also, we support stand-alone devices (usually +plugged on a SPEC card), controlled through Etherbone, developed by GSI. + +Code and documentation for the FMC bus was born as part of the spec-sw +project, but now it lives in its own project. Other projects, i.e. +software support for the various carriers, should include this as a +submodule. + +The most up to date version of code and documentation is always +available from the repository you can clone from: + + git://ohwr.org/fmc-projects/fmc-bus.git (read-only) + git@ohwr.org:fmc-projects/fmc-bus.git (read-write for developers) + +Selected versions of the documentation, as well as complete tar +archives for selected revisions are placed to the Files section of the +project: `http://www.ohwr.org/projects/fmc-bus/files' + + +What is FMC +*********** + +FMC, as said, stands for "FPGA Mezzanine Card". It is a standard +developed by the VME consortium called VITA (VMEbus International Trade +Association and ratified by ANSI, the American National Standard +Institute. The official documentation is called "ANSI-VITA 57.1". + +The FMC card is an almost square PCB, around 70x75 millimeters, that is +called mezzanine in this document. It usually lives plugged into +another PCB for power supply and control; such bigger circuit board is +called carrier from now on, and a single carrier may host more than one +mezzanine. + +In the typical application the mezzanine is mostly analog while the +carrier is mostly digital, and hosts an FPGA that must be configured to +match the specific mezzanine and the desired application. Thus, you may +need to load different FPGA images to drive different instances of the +same mezzanine. + +FMC, as such, is not a bus in the usual meaning of the term, because +most carriers have only one connector, and carriers with several +connectors have completely separate electrical connections to them. +This package, however, implements a bus as a software abstraction. + + +What is SDB +*********** + +SDB (Self Describing Bus) is a set of data structures that we use for +enumerating the internal structure of an FPGA image. We also use it as +a filesystem inside the FMC EEPROM. + +SDB is not mandatory for use of this FMC kernel bus, but if you have SDB +this package can make good use of it. SDB itself is developed in the +fpga-config-space OHWR project. The link to the repository is +`git://ohwr.org/hdl-core-lib/fpga-config-space.git' and what is used in +this project lives in the sdbfs subdirectory in there. + +SDB support for FMC is described in *note FMC Identification:: and +*note SDB Support:: + + +SDB Support +*********** + +The fmc.ko bus driver exports a few functions to help drivers taking +advantage of the SDB information that may be present in your own FPGA +memory image. + +The module exports the following functions, in the special header +<linux/fmc-sdb.h>. The linux/ prefix in the name is there because we +plan to submit it upstream in the future, and don't want to force +changes on our drivers if that happens. + + int fmc_scan_sdb_tree(struct fmc_device *fmc, unsigned long address); + void fmc_show_sdb_tree(struct fmc_device *fmc); + signed long fmc_find_sdb_device(struct sdb_array *tree, uint64_t vendor, + uint32_t device, unsigned long *sz); + int fmc_free_sdb_tree(struct fmc_device *fmc); diff --git a/Documentation/fmc/carrier.txt b/Documentation/fmc/carrier.txt new file mode 100644 index 000000000000..173f6d65c88d --- /dev/null +++ b/Documentation/fmc/carrier.txt @@ -0,0 +1,311 @@ +FMC Device +********** + +Within the Linux bus framework, the FMC device is created and +registered by the carrier driver. For example, the PCI driver for the +SPEC card fills a data structure for each SPEC that it drives, and +registers an associated FMC device for each card. The SVEC driver can +do exactly the same for the VME carrier (actually, it should do it +twice, because the SVEC carries two FMC mezzanines). Similarly, an +Etherbone driver will be able to register its own FMC devices, offering +communication primitives through frame exchange. + +The contents of the EEPROM within the FMC are used for identification +purposes, i.e. for matching the device with its own driver. For this +reason the device structure includes a complete copy of the EEPROM +(actually, the carrier driver may choose whether or not to return it - +for example we most likely won't have the whole EEPROM available for +Etherbone devices. + +The following listing shows the current structure defining a device. +Please note that all the machinery is in place but some details may +still change in the future. For this reason, there is a version field +at the beginning of the structure. As usual, the minor number will +change for compatible changes (like a new flag) and the major number +will increase when an incompatible change happens (for example, a +change in layout of some fmc data structures). Device writers should +just set it to the value FMC_VERSION, and be ready to get back -EINVAL +at registration time. + + struct fmc_device { + unsigned long version; + unsigned long flags; + struct module *owner; /* char device must pin it */ + struct fmc_fru_id id; /* for EEPROM-based match */ + struct fmc_operations *op; /* carrier-provided */ + int irq; /* according to host bus. 0 == none */ + int eeprom_len; /* Usually 8kB, may be less */ + int eeprom_addr; /* 0x50, 0x52 etc */ + uint8_t *eeprom; /* Full contents or leading part */ + char *carrier_name; /* "SPEC" or similar, for special use */ + void *carrier_data; /* "struct spec *" or equivalent */ + __iomem void *fpga_base; /* May be NULL (Etherbone) */ + __iomem void *slot_base; /* Set by the driver */ + struct fmc_device **devarray; /* Allocated by the bus */ + int slot_id; /* Index in the slot array */ + int nr_slots; /* Number of slots in this carrier */ + unsigned long memlen; /* Used for the char device */ + struct device dev; /* For Linux use */ + struct device *hwdev; /* The underlying hardware device */ + unsigned long sdbfs_entry; + struct sdb_array *sdb; + uint32_t device_id; /* Filled by the device */ + char *mezzanine_name; /* Defaults to ``fmc'' */ + void *mezzanine_data; + }; + +The meaning of most fields is summarized in the code comment above. + +The following fields must be filled by the carrier driver before +registration: + + * version: must be set to FMC_VERSION. + + * owner: set to MODULE_OWNER. + + * op: the operations to act on the device. + + * irq: number for the mezzanine; may be zero. + + * eeprom_len: length of the following array. + + * eeprom_addr: 0x50 for first mezzanine and so on. + + * eeprom: the full content of the I2C EEPROM. + + * carrier_name. + + * carrier_data: a unique pointer for the carrier. + + * fpga_base: the I/O memory address (may be NULL). + + * slot_id: the index of this slot (starting from zero). + + * memlen: if fpga_base is valid, the length of I/O memory. + + * hwdev: to be used in some dev_err() calls. + + * device_id: a slot-specific unique integer number. + + +Please note that the carrier should read its own EEPROM memory before +registering the device, as well as fill all other fields listed above. + +The following fields should not be assigned, because they are filled +later by either the bus or the device driver: + + * flags. + + * fru_id: filled by the bus, parsing the eeprom. + + * slot_base: filled and used by the driver, if useful to it. + + * devarray: an array og all mezzanines driven by a singe FPGA. + + * nr_slots: set by the core at registration time. + + * dev: used by Linux. + + * sdb: FPGA contents, scanned according to driver's directions. + + * sdbfs_entry: SDB entry point in EEPROM: autodetected. + + * mezzanine_data: available for the driver. + + * mezzanine_name: filled by fmc-bus during identification. + + +Note: mezzanine_data may be redundant, because Linux offers the drvdata +approach, so the field may be removed in later versions of this bus +implementation. + +As I write this, she SPEC carrier is already completely functional in +the fmc-bus environment, and is a good reference to look at. + + +The API Offered by Carriers +=========================== + +The carrier provides a number of methods by means of the +`fmc_operations' structure, which currently is defined like this +(again, it is a moving target, please refer to the header rather than +this document): + + struct fmc_operations { + uint32_t (*readl)(struct fmc_device *fmc, int offset); + void (*writel)(struct fmc_device *fmc, uint32_t value, int offset); + int (*reprogram)(struct fmc_device *f, struct fmc_driver *d, char *gw); + int (*validate)(struct fmc_device *fmc, struct fmc_driver *drv); + int (*irq_request)(struct fmc_device *fmc, irq_handler_t h, + char *name, int flags); + void (*irq_ack)(struct fmc_device *fmc); + int (*irq_free)(struct fmc_device *fmc); + int (*gpio_config)(struct fmc_device *fmc, struct fmc_gpio *gpio, + int ngpio); + int (*read_ee)(struct fmc_device *fmc, int pos, void *d, int l); + int (*write_ee)(struct fmc_device *fmc, int pos, const void *d, int l); + }; + +The individual methods perform the following tasks: + +`readl' +`writel' + These functions access FPGA registers by whatever means the + carrier offers. They are not expected to fail, and most of the time + they will just make a memory access to the host bus. If the + carrier provides a fpga_base pointer, the driver may use direct + access through that pointer. For this reason the header offers the + inline functions fmc_readl and fmc_writel that access fpga_base if + the respective method is NULL. A driver that wants to be portable + and efficient should use fmc_readl and fmc_writel. For Etherbone, + or other non-local carriers, error-management is still to be + defined. + +`validate' + Module parameters are used to manage different applications for + two or more boards of the same kind. Validation is based on the + busid module parameter, if provided, and returns the matching + index in the associated array. See *note Module Parameters:: in in + doubt. If no match is found, `-ENOENT' is returned; if the user + didn't pass `busid=', all devices will pass validation. The value + returned by the validate method can be used as index into other + parameters (for example, some drivers use the `lm32=' parameter in + this way). Such "generic parameters" are documented in *note + Module Parameters::, below. The validate method is used by + `fmc-trivial.ko', described in *note fmc-trivial::. + +`reprogram' + The carrier enumerates FMC devices by loading a standard (or + golden) FPGA binary that allows EEPROM access. Each driver, then, + will need to reprogram the FPGA by calling this function. If the + name argument is NULL, the carrier should reprogram the golden + binary. If the gateware name has been overridden through module + parameters (in a carrier-specific way) the file loaded will match + the parameters. Per-device gateware names can be specified using + the `gateware=' parameter, see *note Module Parameters::. Note: + Clients should call rhe new helper, fmc_reprogram, which both + calls this method and parse the SDB tree of the FPGA. + +`irq_request' +`irq_ack' +`irq_free' + Interrupt management is carrier-specific, so it is abstracted as + operations. The interrupt number is listed in the device + structure, and for the mezzanine driver the number is only + informative. The handler will receive the fmc pointer as dev_id; + the flags argument is passed to the Linux request_irq function, + but fmc-specific flags may be added in the future. You'll most + likely want to pass the `IRQF_SHARED' flag. + +`gpio_config' + The method allows to configure a GPIO pin in the carrier, and read + its current value if it is configured as input. See *note The GPIO + Abstraction:: for details. + +`read_ee' +`write_ee' + Read or write the EEPROM. The functions are expected to be only + called before reprogramming and the carrier should refuse them + with `ENODEV' after reprogramming. The offset is expected to be + within 8kB (the current size), but addresses up to 1MB are + reserved to fit bigger I2C devices in the future. Carriers may + offer access to other internal flash memories using these same + methods: for example the SPEC driver may define that its carrier + I2C memory is seen at offset 1M and the internal SPI flash is seen + at offset 16M. This multiplexing of several flash memories in the + same address space is is carrier-specific and should only be used + by a driver that has verified the `carrier_name' field. + + + +The GPIO Abstraction +==================== + +Support for GPIO pins in the fmc-bus environment is not very +straightforward and deserves special discussion. + +While the general idea of a carrier-independent driver seems to fly, +configuration of specific signals within the carrier needs at least +some knowledge of the carrier itself. For this reason, the specific +driver can request to configure carrier-specific GPIO pins, numbered +from 0 to at most 4095. Configuration is performed by passing a +pointer to an array of struct fmc_gpio items, as well as the length of +the array. This is the data structure: + + struct fmc_gpio { + char *carrier_name; + int gpio; + int _gpio; /* internal use by the carrier */ + int mode; /* GPIOF_DIR_OUT etc, from <linux/gpio.h> */ + int irqmode; /* IRQF_TRIGGER_LOW and so on */ + }; + +By specifying a carrier_name for each pin, the driver may access +different pins in different carriers. The gpio_config method is +expected to return the number of pins successfully configured, ignoring +requests for other carriers. However, if no pin is configured (because +no structure at all refers to the current carrier_name), the operation +returns an error so the caller will know that it is running under a +yet-unsupported carrier. + +So, for example, a driver that has been developed and tested on both +the SPEC and the SVEC may request configuration of two different GPIO +pins, and expect one such configuration to succeed - if none succeeds +it most likely means that the current carrier is a still-unknown one. + +If, however, your GPIO pin has a specific known role, you can pass a +special number in the gpio field, using one of the following macros: + + #define FMC_GPIO_RAW(x) (x) /* 4096 of them */ + #define FMC_GPIO_IRQ(x) ((x) + 0x1000) /* 256 of them */ + #define FMC_GPIO_LED(x) ((x) + 0x1100) /* 256 of them */ + #define FMC_GPIO_KEY(x) ((x) + 0x1200) /* 256 of them */ + #define FMC_GPIO_TP(x) ((x) + 0x1300) /* 256 of them */ + #define FMC_GPIO_USER(x) ((x) + 0x1400) /* 256 of them */ + +Use of virtual GPIO numbers (anything but FMC_GPIO_RAW) is allowed +provided the carrier_name field in the data structure is left +unspecified (NULL). Each carrier is responsible for providing a mapping +between virtual and physical GPIO numbers. The carrier may then use the +_gpio field to cache the result of this mapping. + +All carriers must map their I/O lines to the sets above starting from +zero. The SPEC, for example, maps interrupt pins 0 and 1, and test +points 0 through 3 (even if the test points on the PCB are called +5,6,7,8). + +If, for example, a driver requires a free LED and a test point (for a +scope probe to be plugged at some point during development) it may ask +for FMC_GPIO_LED(0) and FMC_GPIO_TP(0). Each carrier will provide +suitable GPIO pins. Clearly, the person running the drivers will know +the order used by the specific carrier driver in assigning leds and +testpoints, so to make a carrier-dependent use of the diagnostic tools. + +In theory, some form of autodetection should be possible: a driver like +the wr-nic (which uses IRQ(1) on the SPEC card) should configure +IRQ(0), make a test with software-generated interrupts and configure +IRQ(1) if the test fails. This probing step should be used because even +if the wr-nic gateware is known to use IRQ1 on the SPEC, the driver +should be carrier-independent and thus use IRQ(0) as a first bet - +actually, the knowledge that IRQ0 may fail is carrier-dependent +information, but using it doesn't make the driver unsuitable for other +carriers. + +The return value of gpio_config is defined as follows: + + * If no pin in the array can be used by the carrier, `-ENODEV'. + + * If at least one virtual GPIO number cannot be mapped, `-ENOENT'. + + * On success, 0 or positive. The value returned is the number of + high input bits (if no input is configured, the value for success + is 0). + +While I admit the procedure is not completely straightforward, it +allows configuration, input and output with a single carrier operation. +Given the typical use case of FMC devices, GPIO operations are not +expected to ever by in hot paths, and GPIO access so fare has only been +used to configure the interrupt pin, mode and polarity. Especially +reading inputs is not expected to be common. If your device has GPIO +capabilities in the hot path, you should consider using the kernel's +GPIO mechanisms. diff --git a/Documentation/fmc/fmc-chardev.txt b/Documentation/fmc/fmc-chardev.txt new file mode 100644 index 000000000000..d9ccb278e597 --- /dev/null +++ b/Documentation/fmc/fmc-chardev.txt @@ -0,0 +1,64 @@ +fmc-chardev +=========== + +This is a simple generic driver, that allows user access by means of a +character device (actually, one for each mezzanine it takes hold of). + +The char device is created as a misc device. Its name in /dev (as +created by udev) is the same name as the underlying FMC device. Thus, +the name can be a silly fmc-0000 look-alike if the device has no +identifiers nor bus_id, a more specific fmc-0400 if the device has a +bus-specific address but no associated name, or something like +fdelay-0400 if the FMC core can rely on both a mezzanine name and a bus +address. + +Currently the driver only supports read and write: you can lseek to the +desired address and read or write a register. + +The driver assumes all registers are 32-bit in size, and only accepts a +single read or write per system call. However, as a result of Unix read +and write semantics, users can simply fread or fwrite bigger areas in +order to dump or store bigger memory areas. + +There is currently no support for mmap, user-space interrupt management +and DMA buffers. They may be added in later versions, if the need +arises. + +The example below shows raw access to a SPEC card programmed with its +golden FPGA file, that features an SDB structure at offset 256 - i.e. +64 words. The mezzanine's EEPROM in this case is not programmed, so the +default name is fmc-<bus><devfn>, and there are two cards in the system: + + spusa.root# insmod fmc-chardev.ko + [ 1073.339332] spec 0000:02:00.0: Driver has no ID: matches all + [ 1073.345051] spec 0000:02:00.0: Created misc device "fmc-0200" + [ 1073.350821] spec 0000:04:00.0: Driver has no ID: matches all + [ 1073.356525] spec 0000:04:00.0: Created misc device "fmc-0400" + spusa.root# ls -l /dev/fmc* + crw------- 1 root root 10, 58 Nov 20 19:23 /dev/fmc-0200 + crw------- 1 root root 10, 57 Nov 20 19:23 /dev/fmc-0400 + spusa.root# dd bs=4 skip=64 count=1 if=/dev/fmc-0200 2> /dev/null | od -t x1z + 0000000 2d 42 44 53 >-BDS< + 0000004 + +The simple program tools/fmc-mem in this package can access an FMC char +device and read or write a word or a whole area. Actually, the program +is not specific to FMC at all, it just uses lseek, read and write. + +Its first argument is the device name, the second the offset, the third +(if any) the value to write and the optional last argument that must +begin with "+" is the number of bytes to read or write. In case of +repeated reading data is written to stdout; repeated writes read from +stdin and the value argument is ignored. + +The following examples show reading the SDB magic number and the first +SDB record from a SPEC device programmed with its golden image: + + spusa.root# ./fmc-mem /dev/fmc-0200 100 + 5344422d + spusa.root# ./fmc-mem /dev/fmc-0200 100 +40 | od -Ax -t x1z + 000000 2d 42 44 53 00 01 02 00 00 00 00 00 00 00 00 00 >-BDS............< + 000010 00 00 00 00 ff 01 00 00 00 00 00 00 51 06 00 00 >............Q...< + 000020 c9 42 a5 e6 02 00 00 00 11 05 12 20 2d 34 42 57 >.B......... -4BW< + 000030 73 6f 72 43 72 61 62 73 49 53 47 2d 00 20 20 20 >sorCrabsISG-. < + 000040 diff --git a/Documentation/fmc/fmc-fakedev.txt b/Documentation/fmc/fmc-fakedev.txt new file mode 100644 index 000000000000..e85b74a4ae30 --- /dev/null +++ b/Documentation/fmc/fmc-fakedev.txt @@ -0,0 +1,36 @@ +fmc-fakedev +=========== + +This package includes a software-only device, called fmc-fakedev, which +is able to register up to 4 mezzanines (by default it registers one). +Unlike the SPEC driver, which creates an FMC device for each PCI cards +it manages, this module creates a single instance of its set of +mezzanines. + +It is meant as the simplest possible example of how a driver should be +written, and it includes a fake EEPROM image (built using the tools +described in *note FMC Identification::),, which by default is +replicated for each fake mezzanine. + +You can also use this device to verify the match algorithms, by asking +it to test your own EEPROM image. You can provide the image by means of +the eeprom= module parameter: the new EEPROM image is loaded, as usual, +by means of the firmware loader. This example shows the defaults and a +custom EEPROM image: + + spusa.root# insmod fmc-fakedev.ko + [ 99.971247] fake-fmc-carrier: mezzanine 0 + [ 99.975393] Manufacturer: fake-vendor + [ 99.979624] Product name: fake-design-for-testing + spusa.root# rmmod fmc-fakedev + spusa.root# insmod fmc-fakedev.ko eeprom=fdelay-eeprom.bin + [ 121.447464] fake-fmc-carrier: Mezzanine 0: eeprom "fdelay-eeprom.bin" + [ 121.462725] fake-fmc-carrier: mezzanine 0 + [ 121.466858] Manufacturer: CERN + [ 121.470477] Product name: FmcDelay1ns4cha + spusa.root# rmmod fmc-fakedev + +After loading the device, you can use the write_ee method do modify its +own internal fake EEPROM: whenever the image is overwritten starting at +offset 0, the module will unregister and register again the FMC device. +This is shown in fmc-write-eeprom.txt diff --git a/Documentation/fmc/fmc-trivial.txt b/Documentation/fmc/fmc-trivial.txt new file mode 100644 index 000000000000..d1910bc67159 --- /dev/null +++ b/Documentation/fmc/fmc-trivial.txt @@ -0,0 +1,17 @@ +fmc-trivial +=========== + +The simple module fmc-trivial is just a simple client that registers an +interrupt handler. I used it to verify the basic mechanism of the FMC +bus and how interrupts worked. + +The module implements the generic FMC parameters, so it can program a +different gateware file in each card. The whole list of parameters it +accepts are: + +`busid=' +`gateware=' + Generic parameters. See mezzanine.txt + + +This driver is worth reading, in my opinion. diff --git a/Documentation/fmc/fmc-write-eeprom.txt b/Documentation/fmc/fmc-write-eeprom.txt new file mode 100644 index 000000000000..44a3bc678bf0 --- /dev/null +++ b/Documentation/fmc/fmc-write-eeprom.txt @@ -0,0 +1,125 @@ +fmc-write-eeprom +================ + +This module is designed to load a binary file from /lib/firmware and to +write it to the internal EEPROM of the mezzanine card. This driver uses +the `busid' generic parameter. + +Overwriting the EEPROM is not something you should do daily, and it is +expected to only happen during manufacturing. For this reason, the +module makes it unlikely for the random user to change a working EEPROM. + +The module takes the following measures: + + * It accepts a `file=' argument (within /lib/firmware) and if no + such argument is received, it doesn't write anything to EEPROM + (i.e. there is no default file name). + + * If the file name ends with `.bin' it is written verbatim starting + at offset 0. + + * If the file name ends with `.tlv' it is interpreted as + type-length-value (i.e., it allows writev(2)-like operation). + + * If the file name doesn't match any of the patterns above, it is + ignored and no write is performed. + + * Only cards listed with `busid=' are written to. If no busid is + specified, no programming is done (and the probe function of the + driver will fail). + + +Each TLV tuple is formatted in this way: the header is 5 bytes, +followed by data. The first byte is `w' for write, the next two bytes +represent the address, in little-endian byte order, and the next two +represent the data length, in little-endian order. The length does not +include the header (it is the actual number of bytes to be written). + +This is a real example: that writes 5 bytes at position 0x110: + + spusa.root# od -t x1 -Ax /lib/firmware/try.tlv + 000000 77 10 01 05 00 30 31 32 33 34 + 00000a + spusa.root# insmod /tmp/fmc-write-eeprom.ko busid=0x0200 file=try.tlv + [19983.391498] spec 0000:03:00.0: write 5 bytes at 0x0110 + [19983.414615] spec 0000:03:00.0: write_eeprom: success + +Please note that you'll most likely want to use SDBFS to build your +EEPROM image, at least if your mezzanines are being used in the White +Rabbit environment. For this reason the TLV format is not expected to +be used much and is not expected to be developed further. + +If you want to try reflashing fake EEPROM devices, you can use the +fmc-fakedev.ko module (see *note fmc-fakedev::). Whenever you change +the image starting at offset 0, it will deregister and register again +after two seconds. Please note, however, that if fmc-write-eeprom is +still loaded, the system will associate it to the new device, which +will be reprogrammed and thus will be unloaded after two seconds. The +following example removes the module after it reflashed fakedev the +first time. + + spusa.root# insmod fmc-fakedev.ko + [ 72.984733] fake-fmc: Manufacturer: fake-vendor + [ 72.989434] fake-fmc: Product name: fake-design-for-testing + spusa.root# insmod fmc-write-eeprom.ko busid=0 file=fdelay-eeprom.bin; \ + rmmod fmc-write-eeprom + [ 130.874098] fake-fmc: Matching a generic driver (no ID) + [ 130.887845] fake-fmc: programming 6155 bytes + [ 130.894567] fake-fmc: write_eeprom: success + [ 132.895794] fake-fmc: Manufacturer: CERN + [ 132.899872] fake-fmc: Product name: FmcDelay1ns4cha + + +Writing to the EEPROM +===================== + +Once you have created a binary file for your EEPROM, you can write it +to the storage medium using the fmc-write-eeprom (See *note +fmc-write-eeprom::, while relying on a carrier driver. The procedure +here shown here uses the SPEC driver +(`http://www.ohwr.org/projects/spec-sw'). + +The example assumes no driver is already loaded (actually, I unloaded +them by hand as everything loads automatically at boot time after you +installed the modules), and shows kernel messages together with +commands. Here the prompt is spusa.root# and two SPEC cards are plugged +in the system. + + spusa.root# insmod fmc.ko + spusa.root# insmod spec.ko + [13972.382818] spec 0000:02:00.0: probe for device 0002:0000 + [13972.392773] spec 0000:02:00.0: got file "fmc/spec-init.bin", 1484404 (0x16a674) bytes + [13972.591388] spec 0000:02:00.0: FPGA programming successful + [13972.883011] spec 0000:02:00.0: EEPROM has no FRU information + [13972.888719] spec 0000:02:00.0: No device_id filled, using index + [13972.894676] spec 0000:02:00.0: No mezzanine_name found + [13972.899863] /home/rubini/wip/spec-sw/kernel/spec-gpio.c - spec_gpio_init + [13972.906578] spec 0000:04:00.0: probe for device 0004:0000 + [13972.916509] spec 0000:04:00.0: got file "fmc/spec-init.bin", 1484404 (0x16a674) bytes + [13973.115096] spec 0000:04:00.0: FPGA programming successful + [13973.401798] spec 0000:04:00.0: EEPROM has no FRU information + [13973.407474] spec 0000:04:00.0: No device_id filled, using index + [13973.413417] spec 0000:04:00.0: No mezzanine_name found + [13973.418600] /home/rubini/wip/spec-sw/kernel/spec-gpio.c - spec_gpio_init + spusa.root# ls /sys/bus/fmc/devices + fmc-0000 fmc-0001 + spusa.root# insmod fmc-write-eeprom.ko busid=0x0200 file=fdelay-eeprom.bin + [14103.966259] spec 0000:02:00.0: Matching an generic driver (no ID) + [14103.975519] spec 0000:02:00.0: programming 6155 bytes + [14126.373762] spec 0000:02:00.0: write_eeprom: success + [14126.378770] spec 0000:04:00.0: Matching an generic driver (no ID) + [14126.384903] spec 0000:04:00.0: fmc_write_eeprom: no filename given: not programming + [14126.392600] fmc_write_eeprom: probe of fmc-0001 failed with error -2 + +Reading back the EEPROM +======================= + +In order to read back the binary content of the EEPROM of your +mezzanine device, the bus creates a read-only sysfs file called eeprom +for each mezzanine it knows about: + + spusa.root# cd /sys/bus/fmc/devices; ls -l */eeprom + -r--r--r-- 1 root root 8192 Apr 9 16:53 FmcDelay1ns4cha-f001/eeprom + -r--r--r-- 1 root root 8192 Apr 9 17:19 fake-design-for-testing-f002/eeprom + -r--r--r-- 1 root root 8192 Apr 9 17:19 fake-design-for-testing-f003/eeprom + -r--r--r-- 1 root root 8192 Apr 9 17:19 fmc-f004/eeprom diff --git a/Documentation/fmc/identifiers.txt b/Documentation/fmc/identifiers.txt new file mode 100644 index 000000000000..3bb577ff0d52 --- /dev/null +++ b/Documentation/fmc/identifiers.txt @@ -0,0 +1,168 @@ +FMC Identification +****************** + +The FMC standard requires every compliant mezzanine to carry +identification information in an I2C EEPROM. The information must be +laid out according to the "IPMI Platform Management FRU Information", +where IPMI is a lie I'd better not expand, and FRU means "Field +Replaceable Unit". + +The FRU information is an intricate unreadable binary blob that must +live at offset 0 of the EEPROM, and typically extends for a few hundred +bytes. The standard allows the application to use all the remaining +storage area of the EEPROM as it wants. + +This chapter explains how to create your own EEPROM image and how to +write it in your mezzanine, as well as how devices and drivers are +paired at run time. EEPROM programming uses tools that are part of this +package and SDB (part of the fpga-config-space package). + +The first sections are only interesting for manufacturers who need to +write the EEPROM. If you are just a software developer writing an FMC +device or driver, you may jump straight to *note SDB Support::. + + +Building the FRU Structure +========================== + +If you want to know the internals of the FRU structure and despair, you +can retrieve the document from +`http://download.intel.com/design/servers/ipmi/FRU1011.pdf' . The +standard is awful and difficult without reason, so we only support the +minimum mandatory subset - we create a simple structure and parse it +back at run time, but we are not able to either generate or parse more +arcane features like non-english languages and 6-bit text. If you need +more items of the FRU standard for your boards, please submit patches. + +This package includes the Python script that Matthieu Cattin wrote to +generate the FRU binary blob, based on an helper libipmi by Manohar +Vanga and Matthieu himself. I changed the test script to receive +parameters from the command line or from the environment (the command +line takes precedence) + +To make a long story short, in order to build a standard-compliant +binary file to be burned in your EEPROM, you need the following items: + + Environment Opt Official Name Default +--------------------------------------------------------------------- + FRU_VENDOR -v "Board Manufacturer" fmc-example + FRU_NAME -n "Board Product Name" mezzanine + FRU_SERIAL -s `Board Serial Number" 0001 + FRU_PART -p "Board Part Number" sample-part + FRU_OUTPUT -o not applicable /dev/stdout + +The "Official Name" above is what you find in the FRU official +documentation, chapter 11, page 7 ("Board Info Area Format"). The +output option is used to save the generated binary to a specific file +name instead of stdout. + +You can pass the items to the FRU generator either in the environment +or on the command line. This package has currently no support for +specifying power consumption or such stuff, but I plan to add it as +soon as I find some time for that. + +FIXME: consumption etc for FRU are here or in PTS? + +The following example creates a binary image for a specific board: + + ./tools/fru-generator -v CERN -n FmcAdc100m14b4cha \ + -s HCCFFIA___-CR000003 -p EDA-02063-V5-0 > eeprom.bin + +The following example shows a script that builds several binary EEPROM +images for a series of boards, changing the serial number for each of +them. The script uses a mix of environment variables and command line +options, and uses the same string patterns shown above. + + #!/bin/sh + + export FRU_VENDOR="CERN" + export FRU_NAME="FmcAdc100m14b4cha" + export FRU_PART="EDA-02063-V5-0" + + serial="HCCFFIA___-CR" + + for number in $(seq 1 50); do + # build number-string "ns" + ns="$(printf %06d $number)" + ./fru-generator -s "${serial}${ns}" > eeprom-${ns}.bin + done + + +Using SDB-FS in the EEPROM +========================== + +If you want to use SDB as a filesystem in the EEPROM device within the +mezzanine, you should create one such filesystem using gensdbfs, from +the fpga-config-space package on OHWR. + +By using an SBD filesystem you can cluster several files in a single +EEPROM, so both the host system and a soft-core running in the FPGA (if +any) can access extra production-time information. + +We chose to use SDB as a storage filesystem because the format is very +simple, and both the host system and the soft-core will likely already +include support code for such format. The SDB library offered by the +fpga-config-space is less than 1kB under LM32, so it proves quite up to +the task. + +The SDB entry point (which acts as a directory listing) cannot live at +offset zero in the flash device, because the FRU information must live +there. To avoid wasting precious storage space while still allowing +for more-than-minimal FRU structures, the fmc.ko will look for the SDB +record at address 256, 512 and 1024. + +In order to generate the complete EEPROM image you'll need a +configuration file for gensdbfs: you tell the program where to place +the sdb entry point, and you must force the FRU data file to be placed +at the beginning of the storage device. If needed, you can also place +other files at a special offset (we sometimes do it for backward +compatibility with drivers we wrote before implementing SDB for flash +memory). + +The directory tools/sdbfs of this package includes a well-commented +example that you may want to use as a starting point (the comments are +in the file called -SDB-CONFIG-). Reading documentation for gensdbfs +is a suggested first step anyways. + +This package (generic FMC bus support) only accesses two files in the +EEPROM: the FRU information, at offset zero, with a suggested filename +of IPMI-FRU and the short name for the mezzanine, in a file called +name. The IPMI-FRU name is not mandatory, but a strongly suggested +choice; the name filename is mandatory, because this is the preferred +short name used by the FMC core. For example, a name of "fdelay" may +supplement a Product Name like "FmcDelay1ns4cha" - exactly as +demonstrated in `tools/sdbfs'. + +Note: SDB access to flash memory is not yet supported, so the short +name currently in use is just the "Product Name" FRU string. + +The example in tools/sdbfs includes an extra file, that is needed by +the fine-delay driver, and must live at a known address of 0x1800. By +running gensdbfs on that directory you can output your binary EEPROM +image (here below spusa$ is the shell prompt): + + spusa$ ../fru-generator -v CERN -n FmcDelay1ns4cha -s proto-0 \ + -p EDA-02267-V3 > IPMI-FRU + spusa$ ls -l + total 16 + -rw-rw-r-- 1 rubini staff 975 Nov 19 18:08 --SDB-CONFIG-- + -rw-rw-r-- 1 rubini staff 216 Nov 19 18:13 IPMI-FRU + -rw-rw-r-- 1 rubini staff 11 Nov 19 18:04 fd-calib + -rw-rw-r-- 1 rubini staff 7 Nov 19 18:04 name + spusa$ sudo gensdbfs . /lib/firmware/fdelay-eeprom.bin + spusa$ sdb-read -l -e 0x100 /lib/firmware/fdelay-eeprom.bin + /home/rubini/wip/sdbfs/userspace/sdb-read: listing format is to be defined + 46696c6544617461:2e202020 00000100-000018ff . + 46696c6544617461:6e616d65 00000200-00000206 name + 46696c6544617461:66642d63 00001800-000018ff fd-calib + 46696c6544617461:49504d49 00000000-000000d7 IPMI-FRU + spusa$ ../fru-dump /lib/firmware/fdelay-eeprom.bin + /lib/firmware/fdelay-eeprom.bin: manufacturer: CERN + /lib/firmware/fdelay-eeprom.bin: product-name: FmcDelay1ns4cha + /lib/firmware/fdelay-eeprom.bin: serial-number: proto-0 + /lib/firmware/fdelay-eeprom.bin: part-number: EDA-02267-V3 + +As expected, the output file is both a proper sdbfs object and an IPMI +FRU information blob. The fd-calib file lives at offset 0x1800 and is +over-allocated to 256 bytes, according to the configuration file for +gensdbfs. diff --git a/Documentation/fmc/mezzanine.txt b/Documentation/fmc/mezzanine.txt new file mode 100644 index 000000000000..87910dbfc91e --- /dev/null +++ b/Documentation/fmc/mezzanine.txt @@ -0,0 +1,123 @@ +FMC Driver +********** + +An FMC driver is concerned with the specific mezzanine and associated +gateware. As such, it is expected to be independent of the carrier +being used: it will perform I/O accesses only by means of +carrier-provided functions. + +The matching between device and driver is based on the content of the +EEPROM (as mandated by the FMC standard) or by the actual cores +configured in the FPGA; the latter technique is used when the FPGA is +already programmed when the device is registered to the bus core. + +In some special cases it is possible for a driver to directly access +FPGA registers, by means of the `fpga_base' field of the device +structure. This may be needed for high-bandwidth peripherals like fast +ADC cards. If the device module registered a remote device (for example +by means of Etherbone), the `fpga_base' pointer will be NULL. +Therefore, drivers must be ready to deal with NULL base pointers, and +fail gracefully. Most driver, however, are not expected to access the +pointer directly but run fmc_readl and fmc_writel instead, which will +work in any case. + +In even more special cases, the driver may access carrier-specific +functionality: the `carrier_name' string allows the driver to check +which is the current carrier and make use of the `carrier_data' +pointer. We chose to use carrier names rather than numeric identifiers +for greater flexibility, but also to avoid a central registry within +the `fmc.h' file - we hope other users will exploit our framework with +their own carriers. An example use of carrier names is in GPIO setup +(see *note The GPIO Abstraction::), although the name match is not +expected to be performed by the driver. If you depend on specific +carriers, please check the carrier name and fail gracefully if your +driver finds it is running in a yet-unknown-to-it environment. + + +ID Table +======== + +Like most other Linux drivers, and FMC driver must list all the devices +which it is able to drive. This is usually done by means of a device +table, but in FMC we can match hardware based either on the contents of +their EEPROM or on the actual FPGA cores that can be enumerated. +Therefore, we have two tables of identifiers. + +Matching of FRU information depends on two names, the manufacturer (or +vendor) and the device (see *note FMC Identification::); for +flexibility during production (i.e. before writing to the EEPROM) the +bus supports a catch-all driver that specifies NULL strings. For this +reason, the table is specified as pointer-and-length, not a a +null-terminated array - the entry with NULL names can be a valid entry. + +Matching on FPGA cores depends on two numeric fields: the 64-bit vendor +number and the 32-bit device number. Support for matching based on +class is not yet implemented. Each device is expected to be uniquely +identified by an array of cores (it matches if all of the cores are +instantiated), and for consistency the list is passed as +pointer-and-length. Several similar devices can be driven by the same +driver, and thus the driver specifies and array of such arrays. + +The complete set of involved data structures is thus the following: + + struct fmc_fru_id { char *manufacturer; char *product_name; }; + struct fmc_sdb_one_id { uint64_t vendor; uint32_t device; }; + struct fmc_sdb_id { struct fmc_sdb_one_id *cores; int cores_nr; }; + + struct fmc_device_id { + struct fmc_fru_id *fru_id; int fru_id_nr; + struct fmc_sdb_id *sdb_id; int sdb_id_nr; + }; + +A better reference, with full explanation, is the <linux/fmc.h> header. + + +Module Parameters +================= + +Most of the FMC drivers need the same set of kernel parameters. This +package includes support to implement common parameters by means of +fields in the `fmc_driver' structure and simple macro definitions. + +The parameters are carrier-specific, in that they rely on the busid +concept, that varies among carriers. For the SPEC, the identifier is a +PCI bus and devfn number, 16 bits wide in total; drivers for other +carriers will most likely offer something similar but not identical, +and some code duplication is unavoidable. + +This is the list of parameters that are common to several modules to +see how they are actually used, please look at spec-trivial.c. + +`busid=' + This is an array of integers, listing carrier-specific + identification numbers. For PIC, for example, `0x0400' represents + bus 4, slot 0. If any such ID is specified, the driver will only + accept to drive cards that appear in the list (even if the FMC ID + matches). This is accomplished by the validate carrier method. + +`gateware=' + The argument is an array of strings. If no busid= is specified, + the first string of gateware= is used for all cards; otherwise the + identifiers and gateware names are paired one by one, in the order + specified. + +`show_sdb=' + For modules supporting it, this parameter asks to show the SDB + internal structure by means of kernel messages. It is disabled by + default because those lines tend to hide more important messages, + if you look at the system console while loading the drivers. + Note: the parameter is being obsoleted, because fmc.ko itself now + supports dump_sdb= that applies to every client driver. + + +For example, if you are using the trivial driver to load two different +gateware files to two different cards, you can use the following +parameters to load different binaries to the cards, after looking up +the PCI identifiers. This has been tested with a SPEC carrier. + + insmod fmc-trivial.ko \ + busid=0x0200,0x0400 \ + gateware=fmc/fine-delay.bin,fmc/simple-dio.bin + +Please note that not all sub-modules support all of those parameters. +You can use modinfo to check what is supported by each module. diff --git a/Documentation/fmc/parameters.txt b/Documentation/fmc/parameters.txt new file mode 100644 index 000000000000..59edf088e3a4 --- /dev/null +++ b/Documentation/fmc/parameters.txt @@ -0,0 +1,56 @@ +Module Parameters in fmc.ko +*************************** + +The core driver receives two module parameters, meant to help debugging +client modules. Both parameters can be modified by writing to +/sys/module/fmc/parameters/, because they are used when client drivers +are devices are registered, not when fmc.ko is loaded. + +`dump_eeprom=' + If not zero, the parameter asks the bus controller to dump the + EEPROM of any device that is registered, using printk. + +`dump_sdb=' + If not zero, the parameter prints the SDB tree of every FPGA it is + loaded by fmc_reprogram(). If greater than one, it asks to dump + the binary content of SDB records. This currently only dumps the + top-level SDB array, though. + + +EEPROM dumping avoids repeating lines, since most of the contents is +usually empty and all bits are one or zero. This is an example of the +output: + + [ 6625.850480] spec 0000:02:00.0: FPGA programming successful + [ 6626.139949] spec 0000:02:00.0: Manufacturer: CERN + [ 6626.144666] spec 0000:02:00.0: Product name: FmcDelay1ns4cha + [ 6626.150370] FMC: mezzanine 0: 0000:02:00.0 on SPEC + [ 6626.155179] FMC: dumping eeprom 0x2000 (8192) bytes + [ 6626.160087] 0000: 01 00 00 01 00 0b 00 f3 01 0a 00 a5 85 87 c4 43 + [ 6626.167069] 0010: 45 52 4e cf 46 6d 63 44 65 6c 61 79 31 6e 73 34 + [ 6626.174019] 0020: 63 68 61 c7 70 72 6f 74 6f 2d 30 cc 45 44 41 2d + [ 6626.180975] 0030: 30 32 32 36 37 2d 56 33 da 32 30 31 32 2d 31 31 + [...] + [ 6626.371366] 0200: 66 64 65 6c 61 79 0a 00 00 00 00 00 00 00 00 00 + [ 6626.378359] 0210: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + [ 6626.385361] [...] + [ 6626.387308] 1800: 70 6c 61 63 65 68 6f 6c 64 65 72 ff ff ff ff ff + [ 6626.394259] 1810: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff + [ 6626.401250] [...] + +The dump of SDB looks like the following; the example shows the simple +golden gateware for the SPEC card, removing the leading timestamps to +fit the page: + + spec 0000:02:00.0: SDB: 00000651:e6a542c9 WB4-Crossbar-GSI + spec 0000:02:00.0: SDB: 0000ce42:ff07fc47 WR-Periph-Syscon (00000000-000000ff) + FMC: mezzanine 0: 0000:02:00.0 on SPEC + FMC: poor dump of sdb first level: + 0000: 53 44 42 2d 00 02 01 00 00 00 00 00 00 00 00 00 + 0010: 00 00 00 00 00 00 01 ff 00 00 00 00 00 00 06 51 + 0020: e6 a5 42 c9 00 00 00 02 20 12 05 11 57 42 34 2d + 0030: 43 72 6f 73 73 62 61 72 2d 47 53 49 20 20 20 00 + 0040: 00 00 01 01 00 00 00 07 00 00 00 00 00 00 00 00 + 0050: 00 00 00 00 00 00 00 ff 00 00 00 00 00 00 ce 42 + 0060: ff 07 fc 47 00 00 00 01 20 12 03 05 57 52 2d 50 + 0070: 65 72 69 70 68 2d 53 79 73 63 6f 6e 20 20 20 01 diff --git a/Documentation/hwmon/submitting-patches b/Documentation/hwmon/submitting-patches index 843751c41fea..46286460462b 100644 --- a/Documentation/hwmon/submitting-patches +++ b/Documentation/hwmon/submitting-patches @@ -27,8 +27,7 @@ increase the chances of your change being accepted. explicitly below the patch header. * If your patch (or the driver) is affected by configuration options such as - CONFIG_SMP or CONFIG_HOTPLUG, make sure it compiles for all configuration - variants. + CONFIG_SMP, make sure it compiles for all configuration variants. 2. Adding functionality to existing drivers diff --git a/Documentation/kbuild/kconfig.txt b/Documentation/kbuild/kconfig.txt index 3f429ed8b3b8..213859e69e88 100644 --- a/Documentation/kbuild/kconfig.txt +++ b/Documentation/kbuild/kconfig.txt @@ -165,7 +165,7 @@ Searching in menuconfig: Example: /hotplug This lists all config symbols that contain "hotplug", - e.g., HOTPLUG, HOTPLUG_CPU, MEMORY_HOTPLUG. + e.g., HOTPLUG_CPU, MEMORY_HOTPLUG. For search help, enter / followed TAB-TAB-TAB (to highlight <Help>) and Enter. This will tell you that you can also use diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index f98ca633b528..3458d6343e01 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -420,10 +420,10 @@ tcp_synack_retries - INTEGER for a passive TCP connection will happen after 63seconds. tcp_syncookies - BOOLEAN - Only valid when the kernel was compiled with CONFIG_SYNCOOKIES + Only valid when the kernel was compiled with CONFIG_SYN_COOKIES Send out syncookies when the syn backlog queue of a socket overflows. This is to prevent against the common 'SYN flood attack' - Default: FALSE + Default: 1 Note, that syncookies is fallback facility. It MUST NOT be used to help highly loaded servers to stand diff --git a/Documentation/serial/00-INDEX b/Documentation/serial/00-INDEX index f7b0c7dc25ef..1f1b22fbd739 100644 --- a/Documentation/serial/00-INDEX +++ b/Documentation/serial/00-INDEX @@ -16,8 +16,6 @@ serial-rs485.txt - info about RS485 structures and support in the kernel. specialix.txt - info on hardware/driver for specialix IO8+ multiport serial card. -stallion.txt - - info on using the Stallion multiport serial driver. sx.txt - info on the Specialix SX/SI multiport serial driver. tty.txt diff --git a/Documentation/serial/stallion.txt b/Documentation/serial/stallion.txt deleted file mode 100644 index 4d798c0cb5cb..000000000000 --- a/Documentation/serial/stallion.txt +++ /dev/null @@ -1,392 +0,0 @@ -* NOTE - This is an unmaintained driver. Lantronix, which bought Stallion -technologies, is not active in driver maintenance, and they have no information -on when or if they will have a 2.6 driver. - -James Nelson <james4765@gmail.com> - 12-12-2004 - -Stallion Multiport Serial Driver Readme ---------------------------------------- - -Copyright (C) 1994-1999, Stallion Technologies. - -Version: 5.5.1 -Date: 28MAR99 - - - -1. INTRODUCTION - -There are two drivers that work with the different families of Stallion -multiport serial boards. One is for the Stallion smart boards - that is -EasyIO, EasyConnection 8/32 and EasyConnection 8/64-PCI, the other for -the true Stallion intelligent multiport boards - EasyConnection 8/64 -(ISA, EISA), EasyConnection/RA-PCI, ONboard and Brumby. - -If you are using any of the Stallion intelligent multiport boards (Brumby, -ONboard, EasyConnection 8/64 (ISA, EISA), EasyConnection/RA-PCI) with -Linux you will need to get the driver utility package. This contains a -firmware loader and the firmware images necessary to make the devices operate. - -The Stallion Technologies ftp site, ftp.stallion.com, will always have -the latest version of the driver utility package. - -ftp://ftp.stallion.com/drivers/ata5/Linux/ata-linux-550.tar.gz - -As of the printing of this document the latest version of the driver -utility package is 5.5.0. If a later version is now available then you -should use the latest version. - -If you are using the EasyIO, EasyConnection 8/32 or EasyConnection 8/64-PCI -boards then you don't need this package, although it does have a serial stats -display program. - -If you require DIP switch settings, or EISA configuration files, or any -other information related to Stallion boards then have a look at Stallion's -web pages at http://www.stallion.com. - - - -2. INSTALLATION - -The drivers can be used as loadable modules or compiled into the kernel. -You can choose which when doing a "config" on the kernel. - -All ISA, and EISA boards that you want to use need to be configured into -the driver(s). All PCI boards will be automatically detected when you load -the driver - so they do not need to be entered into the driver(s) -configuration structure. Note that kernel PCI support is required to use PCI -boards. - -There are two methods of configuring ISA and EISA boards into the drivers. -If using the driver as a loadable module then the simplest method is to pass -the driver configuration as module arguments. The other method is to modify -the driver source to add configuration lines for each board in use. - -If you have pre-built Stallion driver modules then the module argument -configuration method should be used. A lot of Linux distributions come with -pre-built driver modules in /lib/modules/X.Y.Z/misc for the kernel in use. -That makes things pretty simple to get going. - - -2.1 MODULE DRIVER CONFIGURATION: - -The simplest configuration for modules is to use the module load arguments -to configure any ISA or EISA boards. PCI boards are automatically -detected, so do not need any additional configuration at all. - -If using EasyIO, EasyConnection 8/32 ISA, or EasyConnection 8/63-PCI -boards then use the "stallion" driver module, Otherwise if you are using -an EasyConnection 8/64 ISA or EISA, EasyConnection/RA-PCI, ONboard, -Brumby or original Stallion board then use the "istallion" driver module. - -Typically to load up the smart board driver use: - - modprobe stallion - -This will load the EasyIO and EasyConnection 8/32 driver. It will output a -message to say that it loaded and print the driver version number. It will -also print out whether it found the configured boards or not. These messages -may not appear on the console, but typically are always logged to -/var/adm/messages or /var/log/syslog files - depending on how the klogd and -syslogd daemons are setup on your system. - -To load the intelligent board driver use: - - modprobe istallion - -It will output similar messages to the smart board driver. - -If not using an auto-detectable board type (that is a PCI board) then you -will also need to supply command line arguments to the modprobe command -when loading the driver. The general form of the configuration argument is - - board?=<name>[,<ioaddr>[,<addr>][,<irq>]] - -where: - - board? -- specifies the arbitrary board number of this board, - can be in the range 0 to 3. - - name -- textual name of this board. The board name is the common - board name, or any "shortened" version of that. The board - type number may also be used here. - - ioaddr -- specifies the I/O address of this board. This argument is - optional, but should generally be specified. - - addr -- optional second address argument. Some board types require - a second I/O address, some require a memory address. The - exact meaning of this argument depends on the board type. - - irq -- optional IRQ line used by this board. - -Up to 4 board configuration arguments can be specified on the load line. -Here is some examples: - - modprobe stallion board0=easyio,0x2a0,5 - -This configures an EasyIO board as board 0 at I/O address 0x2a0 and IRQ 5. - - modprobe istallion board3=ec8/64,0x2c0,0xcc000 - -This configures an EasyConnection 8/64 ISA as board 3 at I/O address 0x2c0 at -memory address 0xcc000. - - modprobe stallion board1=ec8/32-at,0x2a0,0x280,10 - -This configures an EasyConnection 8/32 ISA board at primary I/O address 0x2a0, -secondary address 0x280 and IRQ 10. - -You will probably want to enter this module load and configuration information -into your system startup scripts so that the drivers are loaded and configured -on each system boot. Typically configuration files are put in the -/etc/modprobe.d/ directory. - - -2.2 STATIC DRIVER CONFIGURATION: - -For static driver configuration you need to modify the driver source code. -Entering ISA and EISA boards into the driver(s) configuration structure -involves editing the driver(s) source file. It's pretty easy if you follow -the instructions below. Both drivers can support up to 4 boards. The smart -card driver (the stallion.c driver) supports any combination of EasyIO and -EasyConnection 8/32 boards (up to a total of 4). The intelligent driver -supports any combination of ONboards, Brumbys, Stallions and EasyConnection -8/64 (ISA and EISA) boards (up to a total of 4). - -To set up the driver(s) for the boards that you want to use you need to -edit the appropriate driver file and add configuration entries. - -If using EasyIO or EasyConnection 8/32 ISA boards, - In drivers/char/stallion.c: - - find the definition of the stl_brdconf array (of structures) - near the top of the file - - modify this to match the boards you are going to install - (the comments before this structure should help) - - save and exit - -If using ONboard, Brumby, Stallion or EasyConnection 8/64 (ISA or EISA) -boards, - In drivers/char/istallion.c: - - find the definition of the stli_brdconf array (of structures) - near the top of the file - - modify this to match the boards you are going to install - (the comments before this structure should help) - - save and exit - -Once you have set up the board configurations then you are ready to build -the kernel or modules. - -When the new kernel is booted, or the loadable module loaded then the -driver will emit some kernel trace messages about whether the configured -boards were detected or not. Depending on how your system logger is set -up these may come out on the console, or just be logged to -/var/adm/messages or /var/log/syslog. You should check the messages to -confirm that all is well. - - -2.3 SHARING INTERRUPTS - -It is possible to share interrupts between multiple EasyIO and -EasyConnection 8/32 boards in an EISA system. To do this you must be using -static driver configuration, modifying the driver source code to add driver -configuration. Then a couple of extra things are required: - -1. When entering the board resources into the stallion.c file you need to - mark the boards as using level triggered interrupts. Do this by replacing - the "0" entry at field position 6 (the last field) in the board - configuration structure with a "1". (This is the structure that defines - the board type, I/O locations, etc. for each board). All boards that are - sharing an interrupt must be set this way, and each board should have the - same interrupt number specified here as well. Now build the module or - kernel as you would normally. - -2. When physically installing the boards into the system you must enter - the system EISA configuration utility. You will need to install the EISA - configuration files for *all* the EasyIO and EasyConnection 8/32 boards - that are sharing interrupts. The Stallion EasyIO and EasyConnection 8/32 - EISA configuration files required are supplied by Stallion Technologies - on the EASY Utilities floppy diskette (usually supplied in the box with - the board when purchased. If not, you can pick it up from Stallion's FTP - site, ftp.stallion.com). You will need to edit the board resources to - choose level triggered interrupts, and make sure to set each board's - interrupt to the same IRQ number. - -You must complete both the above steps for this to work. When you reboot -or load the driver your EasyIO and EasyConnection 8/32 boards will be -sharing interrupts. - - -2.4 USING HIGH SHARED MEMORY - -The EasyConnection 8/64-EI, ONboard and Stallion boards are capable of -using shared memory addresses above the usual 640K - 1Mb range. The ONboard -ISA and the Stallion boards can be programmed to use memory addresses up to -16Mb (the ISA bus addressing limit), and the EasyConnection 8/64-EI and -ONboard/E can be programmed for memory addresses up to 4Gb (the EISA bus -addressing limit). - -The higher than 1Mb memory addresses are fully supported by this driver. -Just enter the address as you normally would for a lower than 1Mb address -(in the driver's board configuration structure). - - - -2.5 TROUBLE SHOOTING - -If a board is not found by the driver but is actually in the system then the -most likely problem is that the I/O address is wrong. Change the module load -argument for the loadable module form. Or change it in the driver stallion.c -or istallion.c configuration structure and rebuild the kernel or modules, or -change it on the board. - -On EasyIO and EasyConnection 8/32 boards the IRQ is software programmable, so -if there is a conflict you may need to change the IRQ used for a board. There -are no interrupts to worry about for ONboard, Brumby or EasyConnection 8/64 -(ISA and EISA) boards. The memory region on EasyConnection 8/64 and -ONboard boards is software programmable, but not on the Brumby boards. - - - -3. USING THE DRIVERS - -3.1 INTELLIGENT DRIVER OPERATION - -The intelligent boards also need to have their "firmware" code downloaded -to them. This is done via a user level application supplied in the driver -utility package called "stlload". Compile this program wherever you dropped -the package files, by typing "make". In its simplest form you can then type - - ./stlload -i cdk.sys - -in this directory and that will download board 0 (assuming board 0 is an -EasyConnection 8/64 or EasyConnection/RA board). To download to an -ONboard, Brumby or Stallion do: - - ./stlload -i 2681.sys - -Normally you would want all boards to be downloaded as part of the standard -system startup. To achieve this, add one of the lines above into the -/etc/rc.d/rc.S or /etc/rc.d/rc.serial file. To download each board just add -the "-b <brd-number>" option to the line. You will need to download code for -every board. You should probably move the stlload program into a system -directory, such as /usr/sbin. Also, the default location of the cdk.sys image -file in the stlload down-loader is /usr/lib/stallion. Create that directory -and put the cdk.sys and 2681.sys files in it. (It's a convenient place to put -them anyway). As an example your /etc/rc.d/rc.S file might have the -following lines added to it (if you had 3 boards): - - /usr/sbin/stlload -b 0 -i /usr/lib/stallion/cdk.sys - /usr/sbin/stlload -b 1 -i /usr/lib/stallion/2681.sys - /usr/sbin/stlload -b 2 -i /usr/lib/stallion/2681.sys - -The image files cdk.sys and 2681.sys are specific to the board types. The -cdk.sys will only function correctly on an EasyConnection 8/64 board. Similarly -the 2681.sys image fill only operate on ONboard, Brumby and Stallion boards. -If you load the wrong image file into a board it will fail to start up, and -of course the ports will not be operational! - -If you are using the modularized version of the driver you might want to put -the modprobe calls in the startup script as well (before the download lines -obviously). - - -3.2 USING THE SERIAL PORTS - -Once the driver is installed you will need to setup some device nodes to -access the serial ports. The simplest method is to use the /dev/MAKEDEV program. -It will automatically create device entries for Stallion boards. This will -create the normal serial port devices as /dev/ttyE# where# is the port number -starting from 0. A bank of 64 minor device numbers is allocated to each board, -so the first port on the second board is port 64,etc. A set of callout type -devices may also be created. They are created as the devices /dev/cue# where # -is the same as for the ttyE devices. - -For the most part the Stallion driver tries to emulate the standard PC system -COM ports and the standard Linux serial driver. The idea is that you should -be able to use Stallion board ports and COM ports interchangeably without -modifying anything but the device name. Anything that doesn't work like that -should be considered a bug in this driver! - -If you look at the driver code you will notice that it is fairly closely -based on the Linux serial driver (linux/drivers/char/serial.c). This is -intentional, obviously this is the easiest way to emulate its behavior! - -Since this driver tries to emulate the standard serial ports as much as -possible, most system utilities should work as they do for the standard -COM ports. Most importantly "stty" works as expected and "setserial" can -also be used (excepting the ability to auto-configure the I/O and IRQ -addresses of boards). Higher baud rates are supported in the usual fashion -through setserial or using the CBAUDEX extensions. Note that the EasyIO and -EasyConnection (all types) support at least 57600 and 115200 baud. The newer -EasyConnection XP modules and new EasyIO boards support 230400 and 460800 -baud as well. The older boards including ONboard and Brumby support a -maximum baud rate of 38400. - -If you are unfamiliar with how to use serial ports, then get the Serial-HOWTO -by Greg Hankins. It will explain everything you need to know! - - - -4. NOTES - -You can use both drivers at once if you have a mix of board types installed -in a system. However to do this you will need to change the major numbers -used by one of the drivers. Currently both drivers use major numbers 24, 25 -and 28 for their devices. Change one driver to use some other major numbers, -and then modify the mkdevnods script to make device nodes based on those new -major numbers. For example, you could change the istallion.c driver to use -major numbers 60, 61 and 62. You will also need to create device nodes with -different names for the ports, for example ttyF# and cuf#. - -The original Stallion board is no longer supported by Stallion Technologies. -Although it is known to work with the istallion driver. - -Finding a free physical memory address range can be a problem. The older -boards like the Stallion and ONboard need large areas (64K or even 128K), so -they can be very difficult to get into a system. If you have 16 Mb of RAM -then you have no choice but to put them somewhere in the 640K -> 1Mb range. -ONboards require 64K, so typically 0xd0000 is good, or 0xe0000 on some -systems. If you have an original Stallion board, "V4.0" or Rev.O, then you -need a 64K memory address space, so again 0xd0000 and 0xe0000 are good. -Older Stallion boards are a much bigger problem. They need 128K of address -space and must be on a 128K boundary. If you don't have a VGA card then -0xc0000 might be usable - there is really no other place you can put them -below 1Mb. - -Both the ONboard and old Stallion boards can use higher memory addresses as -well, but you must have less than 16Mb of RAM to be able to use them. Usual -high memory addresses used include 0xec0000 and 0xf00000. - -The Brumby boards only require 16Kb of address space, so you can usually -squeeze them in somewhere. Common addresses are 0xc8000, 0xcc000, or in -the 0xd0000 range. EasyConnection 8/64 boards are even better, they only -require 4Kb of address space, again usually 0xc8000, 0xcc000 or 0xd0000 -are good. - -If you are using an EasyConnection 8/64-EI or ONboard/E then usually the -0xd0000 or 0xe0000 ranges are the best options below 1Mb. If neither of -them can be used then the high memory support to use the really high address -ranges is the best option. Typically the 2Gb range is convenient for them, -and gets them well out of the way. - -The ports of the EasyIO-8M board do not have DCD or DTR signals. So these -ports cannot be used as real modem devices. Generally, when using these -ports you should only use the cueX devices. - -The driver utility package contains a couple of very useful programs. One -is a serial port statistics collection and display program - very handy -for solving serial port problems. The other is an extended option setting -program that works with the intelligent boards. - - - -5. DISCLAIMER - -The information contained in this document is believed to be accurate and -reliable. However, no responsibility is assumed by Stallion Technologies -Pty. Ltd. for its use, nor any infringements of patents or other rights -of third parties resulting from its use. Stallion Technologies reserves -the right to modify the design of its products and will endeavour to change -the information in manuals and accompanying documentation accordingly. - diff --git a/Documentation/sound/alsa/HD-Audio-Models.txt b/Documentation/sound/alsa/HD-Audio-Models.txt index bb8b0dc532b8..77d68e23b247 100644 --- a/Documentation/sound/alsa/HD-Audio-Models.txt +++ b/Documentation/sound/alsa/HD-Audio-Models.txt @@ -29,6 +29,8 @@ ALC269/270/275/276/280/282 alc271-dmic Enable ALC271X digital mic workaround inv-dmic Inverted internal mic workaround lenovo-dock Enables docking station I/O for some Lenovos + dell-headset-multi Headset jack, which can also be used as mic-in + dell-headset-dock Headset jack (without mic-in), and also dock I/O ALC662/663/272 ============== @@ -42,6 +44,7 @@ ALC662/663/272 asus-mode7 ASUS asus-mode8 ASUS inv-dmic Inverted internal mic workaround + dell-headset-multi Headset jack, which can also be used as mic-in ALC680 ====== diff --git a/Documentation/usb/gadget_configfs.txt b/Documentation/usb/gadget_configfs.txt new file mode 100644 index 000000000000..8ec2a67c39b7 --- /dev/null +++ b/Documentation/usb/gadget_configfs.txt @@ -0,0 +1,384 @@ + + + + + Linux USB gadget configured through configfs + + + 25th April 2013 + + + + +Overview +======== + +A USB Linux Gadget is a device which has a UDC (USB Device Controller) and can +be connected to a USB Host to extend it with additional functions like a serial +port or a mass storage capability. + +A gadget is seen by its host as a set of configurations, each of which contains +a number of interfaces which, from the gadget's perspective, are known as +functions, each function representing e.g. a serial connection or a SCSI disk. + +Linux provides a number of functions for gadgets to use. + +Creating a gadget means deciding what configurations there will be +and which functions each configuration will provide. + +Configfs (please see Documentation/filesystems/configfs/*) lends itslef nicely +for the purpose of telling the kernel about the above mentioned decision. +This document is about how to do it. + +It also describes how configfs integration into gadget is designed. + + + + +Requirements +============ + +In order for this to work configfs must be available, so CONFIGFS_FS must be +'y' or 'm' in .config. As of this writing USB_LIBCOMPOSITE selects CONFIGFS_FS. + + + + +Usage +===== + +(The original post describing the first function +made available through configfs can be seen here: +http://www.spinics.net/lists/linux-usb/msg76388.html) + +$ modprobe libcomposite +$ mount none $CONFIGFS_HOME -t configfs + +where CONFIGFS_HOME is the mount point for configfs + +1. Creating the gadgets +----------------------- + +For each gadget to be created its corresponding directory must be created: + +$ mkdir $CONFIGFS_HOME/usb_gadget/<gadget name> + +e.g.: + +$ mkdir $CONFIGFS_HOME/usb_gadget/g1 + +... +... +... + +$ cd $CONFIGFS_HOME/usb_gadget/g1 + +Each gadget needs to have its vendor id <VID> and product id <PID> specified: + +$ echo <VID> > idVendor +$ echo <PID> > idProduct + +A gadget also needs its serial number, manufacturer and product strings. +In order to have a place to store them, a strings subdirectory must be created +for each language, e.g.: + +$ mkdir strings/0x409 + +Then the strings can be specified: + +$ echo <serial number> > strings/0x409/serialnumber +$ echo <manufacturer> > strings/0x409/manufacturer +$ echo <product> > strings/0x409/product + +2. Creating the configurations +------------------------------ + +Each gadget will consist of a number of configurations, their corresponding +directories must be created: + +$ mkdir configs/<name>.<number> + +where <name> can be any string which is legal in a filesystem and the +<numebr> is the configuration's number, e.g.: + +$ mkdir configs/c.1 + +... +... +... + +Each configuration also needs its strings, so a subdirectory must be created +for each language, e.g.: + +$ mkdir configs/c.1/strings/0x409 + +Then the configuration string can be specified: + +$ echo <configuration> > configs/c.1/strings/0x409/configuration + +Some attributes can also be set for a configuration, e.g.: + +$ echo 120 > configs/c.1/MaxPower + +3. Creating the functions +------------------------- + +The gadget will provide some functions, for each function its corresponding +directory must be created: + +$ mkdir functions/<name>.<instance name> + +where <name> corresponds to one of allowed function names and instance name +is an arbitrary string allowed in a filesystem, e.g.: + +$ mkdir functions/ncm.usb0 # usb_f_ncm.ko gets loaded with request_module() + +... +... +... + +Each function provides its specific set of attributes, with either read-only +or read-write access. Where applicable they need to be written to as +appropriate. +Please refer to Documentation/ABI/*/configfs-usb-gadget* for more information. + +4. Associating the functions with their configurations +------------------------------------------------------ + +At this moment a number of gadgets is created, each of which has a number of +configurations specified and a number of functions available. What remains +is specifying which function is available in which configuration (the same +function can be used in multiple configurations). This is achieved with +creating symbolic links: + +$ ln -s functions/<name>.<instance name> configs/<name>.<number> + +e.g.: + +$ ln -s functions/ncm.usb0 configs/c.1 + +... +... +... + +5. Enabling the gadget +---------------------- + +All the above steps serve the purpose of composing the gadget of +configurations and functions. + +An example directory structure might look like this: + +. +./strings +./strings/0x409 +./strings/0x409/serialnumber +./strings/0x409/product +./strings/0x409/manufacturer +./configs +./configs/c.1 +./configs/c.1/ncm.usb0 -> ../../../../usb_gadget/g1/functions/ncm.usb0 +./configs/c.1/strings +./configs/c.1/strings/0x409 +./configs/c.1/strings/0x409/configuration +./configs/c.1/bmAttributes +./configs/c.1/MaxPower +./functions +./functions/ncm.usb0 +./functions/ncm.usb0/ifname +./functions/ncm.usb0/qmult +./functions/ncm.usb0/host_addr +./functions/ncm.usb0/dev_addr +./UDC +./bcdUSB +./bcdDevice +./idProduct +./idVendor +./bMaxPacketSize0 +./bDeviceProtocol +./bDeviceSubClass +./bDeviceClass + + +Such a gadget must be finally enabled so that the USB host can enumerate it. +In order to enable the gadget it must be bound to a UDC (USB Device Controller). + +$ echo <udc name> > UDC + +where <udc name> is one of those found in /sys/class/udc/* +e.g.: + +$ echo s3c-hsotg > UDC + + +6. Disabling the gadget +----------------------- + +$ echo "" > UDC + +7. Cleaning up +-------------- + +Remove functions from configurations: + +$ rm configs/<config name>.<number>/<function> + +where <config name>.<number> specify the configuration and <function> is +a symlink to a function being removed from the configuration, e.g.: + +$ rm configfs/c.1/ncm.usb0 + +... +... +... + +Remove strings directories in configurations + +$ rmdir configs/<config name>.<number>/strings/<lang> + +e.g.: + +$ rmdir configs/c.1/strings/0x409 + +... +... +... + +and remove the configurations + +$ rmdir configs/<config name>.<number> + +e.g.: + +rmdir configs/c.1 + +... +... +... + +Remove functions (function modules are not unloaded, though) + +$ rmdir functions/<name>.<instance name> + +e.g.: + +$ rmdir functions/ncm.usb0 + +... +... +... + +Remove strings directories in the gadget + +$ rmdir strings/<lang> + +e.g.: + +$ rmdir strings/0x409 + +and finally remove the gadget: + +$ cd .. +$ rmdir <gadget name> + +e.g.: + +$ rmdir g1 + + + + +Implementation design +===================== + +Below the idea of how configfs works is presented. +In configfs there are items and groups, both represented as directories. +The difference between an item and a group is that a group can contain +other groups. In the picture below only an item is shown. +Both items and groups can have attributes, which are represented as files. +The user can create and remove directories, but cannot remove files, +which can be read-only or read-write, depending on what they represent. + +The filesystem part of configfs operates on config_items/groups and +configfs_attributes which are generic and of the same type for all +configured elements. However, they are embedded in usage-specific +larger structures. In the picture below there is a "cs" which contains +a config_item and an "sa" which contains a configfs_attribute. + +The filesystem view would be like this: + +./ +./cs (directory) + | + +--sa (file) + | + . + . + . + +Whenever a user reads/writes the "sa" file, a function is called +which accepts a struct config_item and a struct configfs_attribute. +In the said function the "cs" and "sa" are retrieved using the well +known container_of technique and an appropriate sa's function (show or +store) is called and passed the "cs" and a character buffer. The "show" +is for displaying the file's contents (copy data from the cs to the +buffer), while the "store" is for modifying the file's contents (copy data +from the buffer to the cs), but it is up to the implementer of the +two functions to decide what they actually do. + +typedef struct configured_structure cs; +typedef struc specific_attribute sa; + + sa + +----------------------------------+ + cs | (*show)(cs *, buffer); | ++-----------------+ | (*store)(cs *, buffer, length); | +| | | | +| +-------------+ | | +------------------+ | +| | struct |-|----|------>|struct | | +| | config_item | | | |configfs_attribute| | +| +-------------+ | | +------------------+ | +| | +----------------------------------+ +| data to be set | . +| | . ++-----------------+ . + +The file names are decided by the config item/group designer, while +the directories in general can be named at will. A group can have +a number of its default sub-groups created automatically. + +For more information on configfs please see +Documentation/filesystems/configfs/*. + +The concepts described above translate to USB gadgets like this: + +1. A gadget has its config group, which has some attributes (idVendor, +idProduct etc) and default sub-groups (configs, functions, strings). +Writing to the attributes causes the information to be stored in +appropriate locations. In the configs, functions and strings sub-groups +a user can create their sub-groups to represent configurations, functions, +and groups of strings in a given language. + +2. The user creates configurations and functions, in the configurations +creates symbolic links to functions. This information is used when the +gadget's UDC attribute is written to, which means binding the gadget +to the UDC. The code in drivers/usb/gadget/configfs.c iterates over +all configurations, and in each configuration it iterates over all +functions and binds them. This way the whole gadget is bound. + +3. The file drivers/usb/gadget/configfs.c contains code for + + - gadget's config_group + - gadget's default groups (configs, functions, strings) + - associating functions with configurations (symlinks) + +4. Each USB function naturally has its own view of what it wants +configured, so config_groups for particular functions are defined +in the functions implementation files drivers/usb/gadget/f_*.c. + +5. Funciton's code is written in such a way that it uses + +usb_get_function_instance(), which, in turn, calls request_module. +So, provided that modprobe works, modules for particular functions +are loaded automatically. Please note that the converse is not true: +after a gadget is disabled and torn down, the modules remain loaded. diff --git a/Documentation/usb/hotplug.txt b/Documentation/usb/hotplug.txt index 4c945716a660..6424b130485c 100644 --- a/Documentation/usb/hotplug.txt +++ b/Documentation/usb/hotplug.txt @@ -33,9 +33,9 @@ you get the best hotplugging when you configure a highly modular system. KERNEL HOTPLUG HELPER (/sbin/hotplug) -When you compile with CONFIG_HOTPLUG, you get a new kernel parameter: -/proc/sys/kernel/hotplug, which normally holds the pathname "/sbin/hotplug". -That parameter names a program which the kernel may invoke at various times. +There is a kernel parameter: /proc/sys/kernel/hotplug, which normally +holds the pathname "/sbin/hotplug". That parameter names a program +which the kernel may invoke at various times. The /sbin/hotplug program can be invoked by any subsystem as part of its reaction to a configuration change, from a thread in that subsystem. diff --git a/Documentation/w1/w1.generic b/Documentation/w1/w1.generic index 212f4ac31c01..a31c5a242973 100644 --- a/Documentation/w1/w1.generic +++ b/Documentation/w1/w1.generic @@ -25,8 +25,8 @@ When a w1 master driver registers with the w1 subsystem, the following occurs: - sysfs entries for that w1 master are created - the w1 bus is periodically searched for new slave devices -When a device is found on the bus, w1 core checks if driver for its family is -loaded. If so, the family driver is attached to the slave. +When a device is found on the bus, w1 core tries to load the driver for its family +and check if it is loaded. If so, the family driver is attached to the slave. If there is no driver for the family, default one is assigned, which allows to perform almost any kind of operations. Each logical operation is a transaction in nature, which can contain several (two or one) low-level operations. |