From b3201b563d36eb799d3f9e14871d5dda2b11f3e8 Mon Sep 17 00:00:00 2001 From: Stefan Roese Date: Thu, 12 Apr 2012 11:05:35 +0200 Subject: staging:iio:adc: Add SPEAr ADC driver This patch implements the basic single data conversion support for the SPEAr600 SoC ADC. The register layout of SPEAr600 differs a bit from other SPEAr SoC variants (e.g. SPEAr3xx). These differences are handled via DT compatible testing. Resulting in a multi-arch binary. This driver is currently tested only on SPEAr600. Future patches may add support for other SoC variants (SPEAr3xx) and features like software buffer or DMA. Signed-off-by: Stefan Roese Acked-by: Jonathan Cameron Acked-by: Viresh Kumar Cc: Greg KH Signed-off-by: Greg Kroah-Hartman --- .../bindings/staging/iio/adc/spear-adc.txt | 26 ++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 Documentation/devicetree/bindings/staging/iio/adc/spear-adc.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/staging/iio/adc/spear-adc.txt b/Documentation/devicetree/bindings/staging/iio/adc/spear-adc.txt new file mode 100644 index 000000000000..02ea23a63f20 --- /dev/null +++ b/Documentation/devicetree/bindings/staging/iio/adc/spear-adc.txt @@ -0,0 +1,26 @@ +* ST SPEAr ADC device driver + +Required properties: +- compatible: Should be "st,spear600-adc" +- reg: Address and length of the register set for the device +- interrupt-parent: Should be the phandle for the interrupt controller + that services interrupts for this device +- interrupts: Should contain the ADC interrupt +- sampling-frequency: Default sampling frequency + +Optional properties: +- vref-external: External voltage reference in milli-volts. If omitted + the internal voltage reference will be used. +- average-samples: Number of samples to generate an average value. If + omitted, single data conversion will be used. + +Examples: + + adc: adc@d8200000 { + compatible = "st,spear600-adc"; + reg = <0xd8200000 0x1000>; + interrupt-parent = <&vic1>; + interrupts = <6>; + sampling-frequency = <5000000>; + vref-external = <2500>; /* 2.5V VRef */ + }; -- cgit v1.2.3 From 1f9e349460389963838aa5428425e7dc31000af6 Mon Sep 17 00:00:00 2001 From: Roland Stigge Date: Sat, 21 Apr 2012 10:10:16 +0200 Subject: iio: Add device tree support to LPC32xx ADC This patch adds device tree support to the LPC32xx's ADC. Signed-off-by: Roland Stigge Signed-off-by: Greg Kroah-Hartman --- .../devicetree/bindings/staging/iio/adc/lpc32xx-adc.txt | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 Documentation/devicetree/bindings/staging/iio/adc/lpc32xx-adc.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/staging/iio/adc/lpc32xx-adc.txt b/Documentation/devicetree/bindings/staging/iio/adc/lpc32xx-adc.txt new file mode 100644 index 000000000000..b3629d3a9adf --- /dev/null +++ b/Documentation/devicetree/bindings/staging/iio/adc/lpc32xx-adc.txt @@ -0,0 +1,16 @@ +* NXP LPC32xx SoC ADC controller + +Required properties: +- compatible: must be "nxp,lpc3220-adc" +- reg: physical base address of the controller and length of memory mapped + region. +- interrupts: The ADC interrupt + +Example: + + adc@40048000 { + compatible = "nxp,lpc3220-adc"; + reg = <0x40048000 0x1000>; + interrupt-parent = <&mic>; + interrupts = <39 0>; + }; -- cgit v1.2.3 From 8af2c75a328355c23d68d3f8651ad52af3c7979d Mon Sep 17 00:00:00 2001 From: Jonathan Cameron Date: Wed, 25 Apr 2012 15:55:00 +0100 Subject: IIO: Move the core abi documentation from staging This file contains only the most generic elements. Other class specific and device specific ABI documents will follow over time. Signed-off-by: Jonathan Cameron Signed-off-by: Greg Kroah-Hartman --- Documentation/ABI/testing/sysfs-bus-iio | 730 ++++++++++++++++++++++++++++++++ 1 file changed, 730 insertions(+) create mode 100644 Documentation/ABI/testing/sysfs-bus-iio (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio new file mode 100644 index 000000000000..2ce4dadaf3f5 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -0,0 +1,730 @@ +What: /sys/bus/iio/devices/iio:deviceX +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Hardware chip or device accessed by one communication port. + Corresponds to a grouping of sensor channels. X is the IIO + index of the device. + +What: /sys/bus/iio/devices/triggerX +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + An event driven driver of data capture to an in kernel buffer. + May be provided by a device driver that also has an IIO device + based on hardware generated events (e.g. data ready) or + provided by a separate driver for other hardware (e.g. + periodic timer, GPIO or high resolution timer). + Contains trigger type specific elements. These do not + generalize well and hence are not documented in this file. + X is the IIO index of the trigger. + +What: /sys/bus/iio/devices/iio:deviceX/buffer +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Directory of attributes relating to the buffer for the device. + +What: /sys/bus/iio/devices/iio:deviceX/name +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Description of the physical chip / device for device X. + Typically a part number. + +What: /sys/bus/iio/devices/iio:deviceX/sampling_frequency +What: /sys/bus/iio/devices/iio:deviceX/buffer/sampling_frequency +What: /sys/bus/iio/devices/triggerX/sampling_frequency +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Some devices have internal clocks. This parameter sets the + resulting sampling frequency. In many devices this + parameter has an effect on input filters etc rather than + simply controlling when the input is sampled. As this + effects datardy triggers, hardware buffers and the sysfs + direct access interfaces, it may be found in any of the + relevant directories. If it effects all of the above + then it is to be found in the base device directory. + +What: /sys/bus/iio/devices/iio:deviceX/sampling_frequency_available +What: /sys/.../iio:deviceX/buffer/sampling_frequency_available +What: /sys/bus/iio/devices/triggerX/sampling_frequency_available +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + When the internal sampling clock can only take a small + discrete set of values, this file lists those available. + +What: /sys/bus/iio/devices/iio:deviceX/oversampling_ratio +KernelVersion: 2.6.38 +Contact: linux-iio@vger.kernel.org +Description: + Hardware dependent ADC oversampling. Controls the sampling ratio + of the digital filter if available. + +What: /sys/bus/iio/devices/iio:deviceX/oversampling_ratio_available +KernelVersion: 2.6.38 +Contact: linux-iio@vger.kernel.org +Description: + Hardware dependent values supported by the oversampling filter. + +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_raw +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_raw +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Raw (unscaled no bias removal etc) voltage measurement from + channel Y. In special cases where the channel does not + correspond to externally available input one of the named + versions may be used. The number must always be specified and + unique to allow association with event codes. Units after + application of scale and offset are microvolts. + +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY-voltageZ_raw +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Raw (unscaled) differential voltage measurement equivalent to + channel Y - channel Z where these channel numbers apply to the + physically equivalent inputs when non differential readings are + separately available. In differential only parts, then all that + is required is a consistent labeling. Units after application + of scale and offset are microvolts. + +What: /sys/bus/iio/devices/iio:deviceX/in_capacitanceY_raw +KernelVersion: 3.2 +Contact: linux-iio@vger.kernel.org +Description: + Raw capacitance measurement from channel Y. Units after + application of scale and offset are nanofarads. + +What: /sys/.../iio:deviceX/in_capacitanceY-in_capacitanceZ_raw +KernelVersion: 3.2 +Contact: linux-iio@vger.kernel.org +Description: + Raw differential capacitance measurement equivalent to + channel Y - channel Z where these channel numbers apply to the + physically equivalent inputs when non differential readings are + separately available. In differential only parts, then all that + is required is a consistent labeling. Units after application + of scale and offset are nanofarads. + +What: /sys/bus/iio/devices/iio:deviceX/in_temp_raw +What: /sys/bus/iio/devices/iio:deviceX/in_tempX_raw +What: /sys/bus/iio/devices/iio:deviceX/in_temp_x_raw +What: /sys/bus/iio/devices/iio:deviceX/in_temp_y_raw +What: /sys/bus/iio/devices/iio:deviceX/in_temp_z_raw +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Raw (unscaled no bias removal etc) temperature measurement. + If an axis is specified it generally means that the temperature + sensor is associated with one part of a compound device (e.g. + a gyroscope axis). Units after application of scale and offset + are milli degrees Celsuis. + +What: /sys/bus/iio/devices/iio:deviceX/in_tempX_input +KernelVersion: 2.6.38 +Contact: linux-iio@vger.kernel.org +Description: + Scaled temperature measurement in milli degrees Celsius. + +What: /sys/bus/iio/devices/iio:deviceX/in_accel_x_raw +What: /sys/bus/iio/devices/iio:deviceX/in_accel_y_raw +What: /sys/bus/iio/devices/iio:deviceX/in_accel_z_raw +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Acceleration in direction x, y or z (may be arbitrarily assigned + but should match other such assignments on device). + Has all of the equivalent parameters as per voltageY. Units + after application of scale and offset are m/s^2. + +What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_raw +What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_raw +What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_raw +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Angular velocity about axis x, y or z (may be arbitrarily + assigned) Data converted by application of offset then scale to + radians per second. Has all the equivalent parameters as + per voltageY. Units after application of scale and offset are + radians per second. + +What: /sys/bus/iio/devices/iio:deviceX/in_incli_x_raw +What: /sys/bus/iio/devices/iio:deviceX/in_incli_y_raw +What: /sys/bus/iio/devices/iio:deviceX/in_incli_z_raw +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Inclination raw reading about axis x, y or z (may be + arbitrarily assigned). Data converted by application of offset + and scale to Degrees. + +What: /sys/bus/iio/devices/iio:deviceX/in_magn_x_raw +What: /sys/bus/iio/devices/iio:deviceX/in_magn_y_raw +What: /sys/bus/iio/devices/iio:deviceX/in_magn_z_raw +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Magnetic field along axis x, y or z (may be arbitrarily + assigned). Data converted by application of offset + then scale to Gauss. + +What: /sys/bus/iio/devices/iio:deviceX/in_accel_x_peak_raw +What: /sys/bus/iio/devices/iio:deviceX/in_accel_y_peak_raw +What: /sys/bus/iio/devices/iio:deviceX/in_accel_z_peak_raw +KernelVersion: 2.6.36 +Contact: linux-iio@vger.kernel.org +Description: + Highest value since some reset condition. These + attributes allow access to this and are otherwise + the direct equivalent of the Y[_name]_raw attributes. + +What: /sys/bus/iio/devices/iio:deviceX/in_accel_xyz_squared_peak_raw +KernelVersion: 2.6.36 +Contact: linux-iio@vger.kernel.org +Description: + A computed peak value based on the sum squared magnitude of + the underlying value in the specified directions. + +What: /sys/bus/iio/devices/iio:deviceX/in_accel_offset +What: /sys/bus/iio/devices/iio:deviceX/in_accel_x_offset +What: /sys/bus/iio/devices/iio:deviceX/in_accel_y_offset +What: /sys/bus/iio/devices/iio:deviceX/in_accel_z_offset +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_offset +What: /sys/bus/iio/devices/iio:deviceX/in_voltage_offset +What: /sys/bus/iio/devices/iio:deviceX/in_tempY_offset +What: /sys/bus/iio/devices/iio:deviceX/in_temp_offset +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + If known for a device, offset to be added to [Y]_raw prior + to scaling by [Y]_scale in order to obtain value in the + units as specified in [y]_raw documentation. + Not present if the offset is always 0 or unknown. If Y or + axis is not present, then the offset applies to all + in channels of . + May be writable if a variable offset can be applied on the + device. Note that this is different to calibbias which + is for devices (or drivers) that apply offsets to compensate + for variation between different instances of the part, typically + adjusted by using some hardware supported calibration procedure. + Calibbias is applied internally, offset is applied in userspace + to the _raw output. + +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_scale +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_scale +What: /sys/bus/iio/devices/iio:deviceX/in_voltage_scale +What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_scale +What: /sys/bus/iio/devices/iio:deviceX/in_accel_scale +What: /sys/bus/iio/devices/iio:deviceX/in_accel_peak_scale +What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_scale +What: /sys/bus/iio/devices/iio:deviceX/in_magn_scale +What: /sys/bus/iio/devices/iio:deviceX/in_magn_x_scale +What: /sys/bus/iio/devices/iio:deviceX/in_magn_y_scale +What: /sys/bus/iio/devices/iio:deviceX/in_magn_z_scale +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + If known for a device, scale to be applied to Y[_name]_raw + post addition of [Y][_name]_offset in order to obtain the + measured value in units as specified in + [Y][_name]_raw documentation. If shared across all in + channels then Y and are not present and the value is + called [Y][_name]_scale. The peak modifier means this + value is applied to Y[_name]_peak_raw values. + +What: /sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_illuminance0_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_proximity0_calibbias +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Hardware applied calibration offset. (assumed to fix production + inaccuracies). + +What /sys/bus/iio/devices/iio:deviceX/in_voltageY_calibscale +What /sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_calibscale +What /sys/bus/iio/devices/iio:deviceX/in_voltage_calibscale +What /sys/bus/iio/devices/iio:deviceX/in_accel_x_calibscale +What /sys/bus/iio/devices/iio:deviceX/in_accel_y_calibscale +What /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibscale +What /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibscale +What /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibscale +What /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibscale +what /sys/bus/iio/devices/iio:deviceX/in_illuminance0_calibscale +what /sys/bus/iio/devices/iio:deviceX/in_proximity0_calibscale +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Hardware applied calibration scale factor. (assumed to fix + production inaccuracies). If shared across all channels, + _calibscale is used. + +What: /sys/bus/iio/devices/iio:deviceX/in_accel_scale_available +What: /sys/.../iio:deviceX/in_voltageX_scale_available +What: /sys/.../iio:deviceX/in_voltage-voltage_scale_available +What: /sys/.../iio:deviceX/out_voltageX_scale_available +What: /sys/.../iio:deviceX/in_capacitance_scale_available +KernelVersion: 2.635 +Contact: linux-iio@vger.kernel.org +Description: + If a discrete set of scale values are available, they + are listed in this attribute. + +What: /sys/.../in_accel_filter_low_pass_3db_frequency +What: /sys/.../in_magn_filter_low_pass_3db_frequency +What: /sys/.../in_anglvel_filter_low_pass_3db_frequency +KernelVersion: 3.2 +Contact: linux-iio@vger.kernel.org +Description: + If a known or controllable low pass filter is applied + to the underlying data channel, then this parameter + gives the 3dB frequency of the filter in Hz. + +What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_raw +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + Raw (unscaled, no bias etc.) output voltage for + channel Y. The number must always be specified and + unique if the output corresponds to a single channel. + +What: /sys/bus/iio/devices/iio:deviceX/out_voltageY&Z_raw +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + Raw (unscaled, no bias etc.) output voltage for an aggregate of + channel Y, channel Z, etc. This interface is available in cases + where a single output sets the value for multiple channels + simultaneously. + +What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_powerdown_mode +What: /sys/bus/iio/devices/iio:deviceX/out_voltage_powerdown_mode +KernelVersion: 2.6.38 +Contact: linux-iio@vger.kernel.org +Description: + Specifies the output powerdown mode. + DAC output stage is disconnected from the amplifier and + 1kohm_to_gnd: connected to ground via an 1kOhm resistor + 100kohm_to_gnd: connected to ground via an 100kOhm resistor + three_state: left floating + For a list of available output power down options read + outX_powerdown_mode_available. If Y is not present the + mode is shared across all outputs. + +What: /sys/.../iio:deviceX/out_votlageY_powerdown_mode_available +What: /sys/.../iio:deviceX/out_voltage_powerdown_mode_available +KernelVersion: 2.6.38 +Contact: linux-iio@vger.kernel.org +Description: + Lists all available output power down modes. + If Y is not present the mode is shared across all outputs. + +What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_powerdown +What: /sys/bus/iio/devices/iio:deviceX/out_voltage_powerdown +KernelVersion: 2.6.38 +Contact: linux-iio@vger.kernel.org +Description: + Writing 1 causes output Y to enter the power down mode specified + by the corresponding outY_powerdown_mode. Clearing returns to + normal operation. Y may be suppressed if all outputs are + controlled together. + +What: /sys/bus/iio/devices/iio:deviceX/events +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Configuration of which hardware generated events are passed up + to user-space. + +What: /sys/.../iio:deviceX/events/in_accel_x_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_accel_x_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_accel_y_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_accel_y_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_accel_z_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_accel_z_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_anglvel_x_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_anglvel_x_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_anglvel_y_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_anglvel_y_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_anglvel_z_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_anglvel_z_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_magn_x_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_magn_x_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_magn_y_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_magn_y_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_magn_z_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_magn_z_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_voltageY_supply_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_voltageY_supply_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_voltageY_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_voltageY_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_tempY_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_tempY_thresh_falling_en +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + Event generated when channel passes a threshold in the specified + (_rising|_falling) direction. If the direction is not specified, + then either the device will report an event which ever direction + a single threshold value is passed in (e.g. + [Y][_name]__thresh_value) or + [Y][_name]__thresh_rising_value and + [Y][_name]__thresh_falling_value may take + different values, but the device can only enable both thresholds + or neither. + Note the driver will assume the last p events requested are + to be enabled where p is however many it supports (which may + vary depending on the exact set requested. So if you want to be + sure you have set what you think you have, check the contents of + these attributes after everything is configured. Drivers may + have to buffer any parameters so that they are consistent when + a given event type is enabled a future point (and not those for + whatever event was previously enabled). + +What: /sys/.../iio:deviceX/events/in_accel_x_roc_rising_en +What: /sys/.../iio:deviceX/events/in_accel_x_roc_falling_en +What: /sys/.../iio:deviceX/events/in_accel_y_roc_rising_en +What: /sys/.../iio:deviceX/events/in_accel_y_roc_falling_en +What: /sys/.../iio:deviceX/events/in_accel_z_roc_rising_en +What: /sys/.../iio:deviceX/events/in_accel_z_roc_falling_en +What: /sys/.../iio:deviceX/events/in_anglvel_x_roc_rising_en +What: /sys/.../iio:deviceX/events/in_anglvel_x_roc_falling_en +What: /sys/.../iio:deviceX/events/in_anglvel_y_roc_rising_en +What: /sys/.../iio:deviceX/events/in_anglvel_y_roc_falling_en +What: /sys/.../iio:deviceX/events/in_anglvel_z_roc_rising_en +What: /sys/.../iio:deviceX/events/in_anglvel_z_roc_falling_en +What: /sys/.../iio:deviceX/events/in_magn_x_roc_rising_en +What: /sys/.../iio:deviceX/events/in_magn_x_roc_falling_en +What: /sys/.../iio:deviceX/events/in_magn_y_roc_rising_en +What: /sys/.../iio:deviceX/events/in_magn_y_roc_falling_en +What: /sys/.../iio:deviceX/events/in_magn_z_roc_rising_en +What: /sys/.../iio:deviceX/events/in_magn_z_roc_falling_en +What: /sys/.../iio:deviceX/events/in_voltageY_supply_roc_rising_en +What: /sys/.../iio:deviceX/events/in_voltageY_supply_roc_falling_en +What: /sys/.../iio:deviceX/events/in_voltageY_roc_rising_en +What: /sys/.../iio:deviceX/events/in_voltageY_roc_falling_en +What: /sys/.../iio:deviceX/events/in_tempY_roc_rising_en +What: /sys/.../iio:deviceX/events/in_tempY_roc_falling_en +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + Event generated when channel passes a threshold on the rate of + change (1st differential) in the specified (_rising|_falling) + direction. If the direction is not specified, then either the + device will report an event which ever direction a single + threshold value is passed in (e.g. + [Y][_name]__roc_value) or + [Y][_name]__roc_rising_value and + [Y][_name]__roc_falling_value may take + different values, but the device can only enable both rate of + change thresholds or neither. + Note the driver will assume the last p events requested are + to be enabled where p is however many it supports (which may + vary depending on the exact set requested. So if you want to be + sure you have set what you think you have, check the contents of + these attributes after everything is configured. Drivers may + have to buffer any parameters so that they are consistent when + a given event type is enabled a future point (and not those for + whatever event was previously enabled). + +What: /sys/.../events/in_accel_x_raw_thresh_rising_value +What: /sys/.../events/in_accel_x_raw_thresh_falling_value +What: /sys/.../events/in_accel_y_raw_thresh_rising_value +What: /sys/.../events/in_accel_y_raw_thresh_falling_value +What: /sys/.../events/in_accel_z_raw_thresh_rising_value +What: /sys/.../events/in_accel_z_raw_thresh_falling_value +What: /sys/.../events/in_anglvel_x_raw_thresh_rising_value +What: /sys/.../events/in_anglvel_x_raw_thresh_falling_value +What: /sys/.../events/in_anglvel_y_raw_thresh_rising_value +What: /sys/.../events/in_anglvel_y_raw_thresh_falling_value +What: /sys/.../events/in_anglvel_z_raw_thresh_rising_value +What: /sys/.../events/in_anglvel_z_raw_thresh_falling_value +What: /sys/.../events/in_magn_x_raw_thresh_rising_value +What: /sys/.../events/in_magn_x_raw_thresh_falling_value +What: /sys/.../events/in_magn_y_raw_thresh_rising_value +What: /sys/.../events/in_magn_y_raw_thresh_falling_value +What: /sys/.../events/in_magn_z_raw_thresh_rising_value +What: /sys/.../events/in_magn_z_raw_thresh_falling_value +What: /sys/.../events/in_voltageY_supply_raw_thresh_rising_value +What: /sys/.../events/in_voltageY_supply_raw_thresh_falling_value +What: /sys/.../events/in_voltageY_raw_thresh_rising_value +What: /sys/.../events/in_voltageY_raw_thresh_falling_value +What: /sys/.../events/in_tempY_raw_thresh_rising_value +What: /sys/.../events/in_tempY_raw_thresh_falling_value +What: /sys/.../events/in_illuminance0_thresh_falling_value +what: /sys/.../events/in_illuminance0_thresh_rising_value +what: /sys/.../events/in_proximity0_thresh_falling_value +what: /sys/.../events/in_proximity0_thresh_rising_value +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + Specifies the value of threshold that the device is comparing + against for the events enabled by + Y[_name]_thresh[_rising|falling]_en. + If separate attributes exist for the two directions, but + direction is not specified for this attribute, then a single + threshold value applies to both directions. + The raw or input element of the name indicates whether the + value is in raw device units or in processed units (as _raw + and _input do on sysfs direct channel read attributes). + +What: /sys/.../events/in_accel_x_raw_roc_rising_value +What: /sys/.../events/in_accel_x_raw_roc_falling_value +What: /sys/.../events/in_accel_y_raw_roc_rising_value +What: /sys/.../events/in_accel_y_raw_roc_falling_value +What: /sys/.../events/in_accel_z_raw_roc_rising_value +What: /sys/.../events/in_accel_z_raw_roc_falling_value +What: /sys/.../events/in_anglvel_x_raw_roc_rising_value +What: /sys/.../events/in_anglvel_x_raw_roc_falling_value +What: /sys/.../events/in_anglvel_y_raw_roc_rising_value +What: /sys/.../events/in_anglvel_y_raw_roc_falling_value +What: /sys/.../events/in_anglvel_z_raw_roc_rising_value +What: /sys/.../events/in_anglvel_z_raw_roc_falling_value +What: /sys/.../events/in_magn_x_raw_roc_rising_value +What: /sys/.../events/in_magn_x_raw_roc_falling_value +What: /sys/.../events/in_magn_y_raw_roc_rising_value +What: /sys/.../events/in_magn_y_raw_roc_falling_value +What: /sys/.../events/in_magn_z_raw_roc_rising_value +What: /sys/.../events/in_magn_z_raw_roc_falling_value +What: /sys/.../events/in_voltageY_supply_raw_roc_rising_value +What: /sys/.../events/in_voltageY_supply_raw_roc_falling_value +What: /sys/.../events/in_voltageY_raw_roc_rising_value +What: /sys/.../events/in_voltageY_raw_roc_falling_value +What: /sys/.../events/in_tempY_raw_roc_rising_value +What: /sys/.../events/in_tempY_raw_roc_falling_value +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + Specifies the value of rate of change threshold that the + device is comparing against for the events enabled by + [Y][_name]_roc[_rising|falling]_en. + If separate attributes exist for the two directions, + but direction is not specified for this attribute, + then a single threshold value applies to both directions. + The raw or input element of the name indicates whether the + value is in raw device units or in processed units (as _raw + and _input do on sysfs direct channel read attributes). + +What: /sys/.../events/in_accel_x_thresh_rising_period +What: /sys/.../events/in_accel_x_thresh_falling_period +hat: /sys/.../events/in_accel_x_roc_rising_period +What: /sys/.../events/in_accel_x_roc_falling_period +What: /sys/.../events/in_accel_y_thresh_rising_period +What: /sys/.../events/in_accel_y_thresh_falling_period +What: /sys/.../events/in_accel_y_roc_rising_period +What: /sys/.../events/in_accel_y_roc_falling_period +What: /sys/.../events/in_accel_z_thresh_rising_period +What: /sys/.../events/in_accel_z_thresh_falling_period +What: /sys/.../events/in_accel_z_roc_rising_period +What: /sys/.../events/in_accel_z_roc_falling_period +What: /sys/.../events/in_anglvel_x_thresh_rising_period +What: /sys/.../events/in_anglvel_x_thresh_falling_period +What: /sys/.../events/in_anglvel_x_roc_rising_period +What: /sys/.../events/in_anglvel_x_roc_falling_period +What: /sys/.../events/in_anglvel_y_thresh_rising_period +What: /sys/.../events/in_anglvel_y_thresh_falling_period +What: /sys/.../events/in_anglvel_y_roc_rising_period +What: /sys/.../events/in_anglvel_y_roc_falling_period +What: /sys/.../events/in_anglvel_z_thresh_rising_period +What: /sys/.../events/in_anglvel_z_thresh_falling_period +What: /sys/.../events/in_anglvel_z_roc_rising_period +What: /sys/.../events/in_anglvel_z_roc_falling_period +What: /sys/.../events/in_magn_x_thresh_rising_period +What: /sys/.../events/in_magn_x_thresh_falling_period +What: /sys/.../events/in_magn_x_roc_rising_period +What: /sys/.../events/in_magn_x_roc_falling_period +What: /sys/.../events/in_magn_y_thresh_rising_period +What: /sys/.../events/in_magn_y_thresh_falling_period +What: /sys/.../events/in_magn_y_roc_rising_period +What: /sys/.../events/in_magn_y_roc_falling_period +What: /sys/.../events/in_magn_z_thresh_rising_period +What: /sys/.../events/in_magn_z_thresh_falling_period +What: /sys/.../events/in_magn_z_roc_rising_period +What: /sys/.../events/in_magn_z_roc_falling_period +What: /sys/.../events/in_voltageY_supply_thresh_rising_period +What: /sys/.../events/in_voltageY_supply_thresh_falling_period +What: /sys/.../events/in_voltageY_supply_roc_rising_period +What: /sys/.../events/in_voltageY_supply_roc_falling_period +What: /sys/.../events/in_voltageY_thresh_rising_period +What: /sys/.../events/in_voltageY_thresh_falling_period +What: /sys/.../events/in_voltageY_roc_rising_period +What: /sys/.../events/in_voltageY_roc_falling_period +What: /sys/.../events/in_tempY_thresh_rising_period +What: /sys/.../events/in_tempY_thresh_falling_period +What: /sys/.../events/in_tempY_roc_rising_period +What: /sys/.../events/in_tempY_roc_falling_period +What: /sys/.../events/in_accel_x&y&z_mag_falling_period +What: /sys/.../events/in_intensity0_thresh_period +What: /sys/.../events/in_proximity0_thresh_period +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + Period of time (in seconds) for which the condition must be + met before an event is generated. If direction is not + specified then this period applies to both directions. + +What: /sys/.../iio:deviceX/events/in_accel_mag_en +What: /sys/.../iio:deviceX/events/in_accel_mag_rising_en +What: /sys/.../iio:deviceX/events/in_accel_mag_falling_en +What: /sys/.../iio:deviceX/events/in_accel_x_mag_en +What: /sys/.../iio:deviceX/events/in_accel_x_mag_rising_en +What: /sys/.../iio:deviceX/events/in_accel_x_mag_falling_en +What: /sys/.../iio:deviceX/events/in_accel_y_mag_en +What: /sys/.../iio:deviceX/events/in_accel_y_mag_rising_en +What: /sys/.../iio:deviceX/events/in_accel_y_mag_falling_en +What: /sys/.../iio:deviceX/events/in_accel_z_mag_en +What: /sys/.../iio:deviceX/events/in_accel_z_mag_rising_en +What: /sys/.../iio:deviceX/events/in_accel_z_mag_falling_en +What: /sys/.../iio:deviceX/events/in_accel_x&y&z_mag_rising_en +What: /sys/.../iio:deviceX/events/in_accel_x&y&z_mag_falling_en +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + Similar to in_accel_x_thresh[_rising|_falling]_en, but here the + magnitude of the channel is compared to the threshold, not its + signed value. + +What: /sys/.../events/in_accel_raw_mag_value +What: /sys/.../events/in_accel_x_raw_mag_rising_value +What: /sys/.../events/in_accel_y_raw_mag_rising_value +What: /sys/.../events/in_accel_z_raw_mag_rising_value +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + The value to which the magnitude of the channel is compared. If + number or direction is not specified, applies to all channels of + this type. + +What: /sys/bus/iio/devices/iio:deviceX/trigger/current_trigger +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + The name of the trigger source being used, as per string given + in /sys/class/iio/triggerY/name. + +What: /sys/bus/iio/devices/iio:deviceX/buffer/length +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Number of scans contained by the buffer. + +What: /sys/bus/iio/devices/iio:deviceX/buffer/bytes_per_datum +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + Bytes per scan. Due to alignment fun, the scan may be larger + than implied directly by the scan_element parameters. + +What: /sys/bus/iio/devices/iio:deviceX/buffer/enable +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +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 +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 +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-in_type +What: /sys/.../buffer/scan_elements/in_voltageY_supply_type +What: /sys/.../buffer/scan_elements/in_timestamp_type +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + Description of the scan element data storage within the buffer + and hence the form in which it is read from user-space. + Form is [be|le]:[s|u]bits/storagebits[>>shift]. + be or le specifies big or little endian. s or u specifies if + signed (2's complement) or unsigned. bits is the number of bits + of data and storagebits is the space (after padding) that it + occupies in the buffer. shift if specified, is the shift that + needs to be applied prior to masking out unused bits. Some + devices put their data in the middle of the transferred elements + with additional information on both sides. Note that some + devices will have additional information in the unused bits + so to get a clean value, the bits value must be used to mask + the buffer output value appropriately. The storagebits value + also specifies the data alignment. So s48/64>>2 will be a + signed 48 bit integer stored in a 64 bit location aligned to + a a64 bit boundary. To obtain the clean value, shift right 2 + and apply a mask to zero the top 16 bits of the result. + For other storage combinations this attribute will be extended + appropriately. + +What: /sys/.../buffer/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 +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + A single positive integer specifying the position of this + scan element in the buffer. Note these are not dependent on + what is enabled and may not be contiguous. Thus for user-space + to establish the full layout these must be used in conjunction + with all _en attributes to establish which channels are present, + and the relevant _type attributes to establish the data storage + format. + +What: /sys/.../iio:deviceX/in_anglvel_z_quadrature_correction_raw +KernelVersion: 2.6.38 +Contact: linux-iio@vger.kernel.org +Description: + This attribute is used to read the amount of quadrature error + present in the device at a given time. -- cgit v1.2.3 From cc4729826fd1a478f235fbcf58c0f97663f8d7e3 Mon Sep 17 00:00:00 2001 From: Martyn Welch Date: Thu, 3 May 2012 17:36:54 +0100 Subject: VME: Move API documentation to Documentation folder The documentation for the VME device driver API is currently in drivers/vme/vme_api.txt, move this to Documentation/vme_api.txt Signed-of-by: Martyn Welch Acked-by: Rob Landley Signed-off-by: Greg Kroah-Hartman --- Documentation/vme_api.txt | 396 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 396 insertions(+) create mode 100644 Documentation/vme_api.txt (limited to 'Documentation') diff --git a/Documentation/vme_api.txt b/Documentation/vme_api.txt new file mode 100644 index 000000000000..856efa35f6e3 --- /dev/null +++ b/Documentation/vme_api.txt @@ -0,0 +1,396 @@ + VME Device Driver API + ===================== + +Driver registration +=================== + +As with other subsystems within the Linux kernel, VME device drivers register +with the VME subsystem, typically called from the devices init routine. This is +achieved via a call to the following function: + + int vme_register_driver (struct vme_driver *driver); + +If driver registration is successful this function returns zero, if an error +occurred a negative error code will be returned. + +A pointer to a structure of type 'vme_driver' must be provided to the +registration function. The structure is as follows: + + struct vme_driver { + struct list_head node; + const char *name; + int (*match)(struct vme_dev *); + int (*probe)(struct vme_dev *); + int (*remove)(struct vme_dev *); + void (*shutdown)(void); + struct device_driver driver; + struct list_head devices; + unsigned int ndev; + }; + +At the minimum, the '.name', '.match' and '.probe' elements of this structure +should be correctly set. The '.name' element is a pointer to a string holding +the device driver's name. + +The '.match' function allows controlling the number of devices that need to +be registered. The match function should return 1 if a device should be +probed and 0 otherwise. This example match function (from vme_user.c) limits +the number of devices probed to one: + + #define USER_BUS_MAX 1 + ... + static int vme_user_match(struct vme_dev *vdev) + { + if (vdev->id.num >= USER_BUS_MAX) + return 0; + return 1; + } + +The '.probe' element should contain a pointer to the probe routine. The +probe routine is passed a 'struct vme_dev' pointer as an argument. The +'struct vme_dev' structure looks like the following: + + struct vme_dev { + int num; + struct vme_bridge *bridge; + struct device dev; + struct list_head drv_list; + struct list_head bridge_list; + }; + +Here, the 'num' field refers to the sequential device ID for this specific +driver. The bridge number (or bus number) can be accessed using +dev->bridge->num. + +A function is also provided to unregister the driver from the VME core and is +usually called from the device driver's exit routine: + + void vme_unregister_driver (struct vme_driver *driver); + + +Resource management +=================== + +Once a driver has registered with the VME core the provided match routine will +be called the number of times specified during the registration. If a match +succeeds, a non-zero value should be returned. A zero return value indicates +failure. For all successful matches, the probe routine of the corresponding +driver is called. The probe routine is passed a pointer to the devices +device structure. This pointer should be saved, it will be required for +requesting VME resources. + +The driver can request ownership of one or more master windows, slave windows +and/or dma channels. Rather than allowing the device driver to request a +specific window or DMA channel (which may be used by a different driver) this +driver allows a resource to be assigned based on the required attributes of the +driver in question: + + struct vme_resource * vme_master_request(struct vme_dev *dev, + u32 aspace, u32 cycle, u32 width); + + struct vme_resource * vme_slave_request(struct vme_dev *dev, u32 aspace, + u32 cycle); + + struct vme_resource *vme_dma_request(struct vme_dev *dev, u32 route); + +For slave windows these attributes are split into the VME address spaces that +need to be accessed in 'aspace' and VME bus cycle types required in 'cycle'. +Master windows add a further set of attributes in 'width' specifying the +required data transfer widths. These attributes are defined as bitmasks and as +such any combination of the attributes can be requested for a single window, +the core will assign a window that meets the requirements, returning a pointer +of type vme_resource that should be used to identify the allocated resource +when it is used. For DMA controllers, the request function requires the +potential direction of any transfers to be provided in the route attributes. +This is typically VME-to-MEM and/or MEM-to-VME, though some hardware can +support VME-to-VME and MEM-to-MEM transfers as well as test pattern generation. +If an unallocated window fitting the requirements can not be found a NULL +pointer will be returned. + +Functions are also provided to free window allocations once they are no longer +required. These functions should be passed the pointer to the resource provided +during resource allocation: + + void vme_master_free(struct vme_resource *res); + + void vme_slave_free(struct vme_resource *res); + + void vme_dma_free(struct vme_resource *res); + + +Master windows +============== + +Master windows provide access from the local processor[s] out onto the VME bus. +The number of windows available and the available access modes is dependent on +the underlying chipset. A window must be configured before it can be used. + + +Master window configuration +--------------------------- + +Once a master window has been assigned the following functions can be used to +configure it and retrieve the current settings: + + int vme_master_set (struct vme_resource *res, int enabled, + unsigned long long base, unsigned long long size, u32 aspace, + u32 cycle, u32 width); + + int vme_master_get (struct vme_resource *res, int *enabled, + unsigned long long *base, unsigned long long *size, u32 *aspace, + u32 *cycle, u32 *width); + +The address spaces, transfer widths and cycle types are the same as described +under resource management, however some of the options are mutually exclusive. +For example, only one address space may be specified. + +These functions return 0 on success or an error code should the call fail. + + +Master window access +-------------------- + +The following functions can be used to read from and write to configured master +windows. These functions return the number of bytes copied: + + ssize_t vme_master_read(struct vme_resource *res, void *buf, + size_t count, loff_t offset); + + ssize_t vme_master_write(struct vme_resource *res, void *buf, + size_t count, loff_t offset); + +In addition to simple reads and writes, a function is provided to do a +read-modify-write transaction. This function returns the original value of the +VME bus location : + + unsigned int vme_master_rmw (struct vme_resource *res, + unsigned int mask, unsigned int compare, unsigned int swap, + loff_t offset); + +This functions by reading the offset, applying the mask. If the bits selected in +the mask match with the values of the corresponding bits in the compare field, +the value of swap is written the specified offset. + + +Slave windows +============= + +Slave windows provide devices on the VME bus access into mapped portions of the +local memory. The number of windows available and the access modes that can be +used is dependent on the underlying chipset. A window must be configured before +it can be used. + + +Slave window configuration +-------------------------- + +Once a slave window has been assigned the following functions can be used to +configure it and retrieve the current settings: + + int vme_slave_set (struct vme_resource *res, int enabled, + unsigned long long base, unsigned long long size, + dma_addr_t mem, u32 aspace, u32 cycle); + + int vme_slave_get (struct vme_resource *res, int *enabled, + unsigned long long *base, unsigned long long *size, + dma_addr_t *mem, u32 *aspace, u32 *cycle); + +The address spaces, transfer widths and cycle types are the same as described +under resource management, however some of the options are mutually exclusive. +For example, only one address space may be specified. + +These functions return 0 on success or an error code should the call fail. + + +Slave window buffer allocation +------------------------------ + +Functions are provided to allow the user to allocate and free a contiguous +buffers which will be accessible by the VME bridge. These functions do not have +to be used, other methods can be used to allocate a buffer, though care must be +taken to ensure that they are contiguous and accessible by the VME bridge: + + void * vme_alloc_consistent(struct vme_resource *res, size_t size, + dma_addr_t *mem); + + void vme_free_consistent(struct vme_resource *res, size_t size, + void *virt, dma_addr_t mem); + + +Slave window access +------------------- + +Slave windows map local memory onto the VME bus, the standard methods for +accessing memory should be used. + + +DMA channels +============ + +The VME DMA transfer provides the ability to run link-list DMA transfers. The +API introduces the concept of DMA lists. Each DMA list is a link-list which can +be passed to a DMA controller. Multiple lists can be created, extended, +executed, reused and destroyed. + + +List Management +--------------- + +The following functions are provided to create and destroy DMA lists. Execution +of a list will not automatically destroy the list, thus enabling a list to be +reused for repetitive tasks: + + struct vme_dma_list *vme_new_dma_list(struct vme_resource *res); + + int vme_dma_list_free(struct vme_dma_list *list); + + +List Population +--------------- + +An item can be added to a list using the following function ( the source and +destination attributes need to be created before calling this function, this is +covered under "Transfer Attributes"): + + int vme_dma_list_add(struct vme_dma_list *list, + struct vme_dma_attr *src, struct vme_dma_attr *dest, + size_t count); + +NOTE: The detailed attributes of the transfers source and destination + are not checked until an entry is added to a DMA list, the request + for a DMA channel purely checks the directions in which the + controller is expected to transfer data. As a result it is + possible for this call to return an error, for example if the + source or destination is in an unsupported VME address space. + +Transfer Attributes +------------------- + +The attributes for the source and destination are handled separately from adding +an item to a list. This is due to the diverse attributes required for each type +of source and destination. There are functions to create attributes for PCI, VME +and pattern sources and destinations (where appropriate): + +Pattern source: + + struct vme_dma_attr *vme_dma_pattern_attribute(u32 pattern, u32 type); + +PCI source or destination: + + struct vme_dma_attr *vme_dma_pci_attribute(dma_addr_t mem); + +VME source or destination: + + struct vme_dma_attr *vme_dma_vme_attribute(unsigned long long base, + u32 aspace, u32 cycle, u32 width); + +The following function should be used to free an attribute: + + void vme_dma_free_attribute(struct vme_dma_attr *attr); + + +List Execution +-------------- + +The following function queues a list for execution. The function will return +once the list has been executed: + + int vme_dma_list_exec(struct vme_dma_list *list); + + +Interrupts +========== + +The VME API provides functions to attach and detach callbacks to specific VME +level and status ID combinations and for the generation of VME interrupts with +specific VME level and status IDs. + + +Attaching Interrupt Handlers +---------------------------- + +The following functions can be used to attach and free a specific VME level and +status ID combination. Any given combination can only be assigned a single +callback function. A void pointer parameter is provided, the value of which is +passed to the callback function, the use of this pointer is user undefined: + + int vme_irq_request(struct vme_dev *dev, int level, int statid, + void (*callback)(int, int, void *), void *priv); + + void vme_irq_free(struct vme_dev *dev, int level, int statid); + +The callback parameters are as follows. Care must be taken in writing a callback +function, callback functions run in interrupt context: + + void callback(int level, int statid, void *priv); + + +Interrupt Generation +-------------------- + +The following function can be used to generate a VME interrupt at a given VME +level and VME status ID: + + int vme_irq_generate(struct vme_dev *dev, int level, int statid); + + +Location monitors +================= + +The VME API provides the following functionality to configure the location +monitor. + + +Location Monitor Management +--------------------------- + +The following functions are provided to request the use of a block of location +monitors and to free them after they are no longer required: + + struct vme_resource * vme_lm_request(struct vme_dev *dev); + + void vme_lm_free(struct vme_resource * res); + +Each block may provide a number of location monitors, monitoring adjacent +locations. The following function can be used to determine how many locations +are provided: + + int vme_lm_count(struct vme_resource * res); + + +Location Monitor Configuration +------------------------------ + +Once a bank of location monitors has been allocated, the following functions +are provided to configure the location and mode of the location monitor: + + int vme_lm_set(struct vme_resource *res, unsigned long long base, + u32 aspace, u32 cycle); + + int vme_lm_get(struct vme_resource *res, unsigned long long *base, + u32 *aspace, u32 *cycle); + + +Location Monitor Use +-------------------- + +The following functions allow a callback to be attached and detached from each +location monitor location. Each location monitor can monitor a number of +adjacent locations: + + int vme_lm_attach(struct vme_resource *res, int num, + void (*callback)(int)); + + int vme_lm_detach(struct vme_resource *res, int num); + +The callback function is declared as follows. + + void callback(int num); + + +Slot Detection +============== + +This function returns the slot ID of the provided bridge. + + int vme_slot_get(struct vme_dev *dev); -- cgit v1.2.3 From 5a44988207ee16b96e5445b8e95ab9881ce310cc Mon Sep 17 00:00:00 2001 From: Tomas Winkler Date: Wed, 9 May 2012 16:39:00 +0300 Subject: mei: move doc files Documentation/misc-devices/mei 1. move mei.txt, TODO, and the example code under Documentation/misc-devices/mei 2. update the TODO file Signed-off-by: Tomas Winkler Signed-off-by: Greg Kroah-Hartman --- Documentation/Makefile | 2 +- Documentation/misc-devices/mei/Makefile | 8 + Documentation/misc-devices/mei/TODO | 5 + Documentation/misc-devices/mei/mei-amt-version.c | 481 +++++++++++++++++++++++ Documentation/misc-devices/mei/mei.txt | 215 ++++++++++ 5 files changed, 710 insertions(+), 1 deletion(-) create mode 100644 Documentation/misc-devices/mei/Makefile create mode 100644 Documentation/misc-devices/mei/TODO create mode 100644 Documentation/misc-devices/mei/mei-amt-version.c create mode 100644 Documentation/misc-devices/mei/mei.txt (limited to 'Documentation') diff --git a/Documentation/Makefile b/Documentation/Makefile index 30b656ece7aa..31d302bc5863 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -1,3 +1,3 @@ obj-m := DocBook/ accounting/ auxdisplay/ connector/ \ filesystems/ filesystems/configfs/ ia64/ laptops/ networking/ \ - pcmcia/ spi/ timers/ watchdog/src/ + pcmcia/ spi/ timers/ watchdog/src/ misc-devices/mei/ diff --git a/Documentation/misc-devices/mei/Makefile b/Documentation/misc-devices/mei/Makefile new file mode 100644 index 000000000000..00e8c3e836ff --- /dev/null +++ b/Documentation/misc-devices/mei/Makefile @@ -0,0 +1,8 @@ +# kbuild trick to avoid linker error. Can be omitted if a module is built. +obj- := dummy.o + +# List of programs to build +hostprogs-y := mei-amt-version +HOSTCFLAGS_mei-amt-version.o += -I$(objtree)/usr/include +# Tell kbuild to always build the programs +always := $(hostprogs-y) diff --git a/Documentation/misc-devices/mei/TODO b/Documentation/misc-devices/mei/TODO new file mode 100644 index 000000000000..933b2999e19a --- /dev/null +++ b/Documentation/misc-devices/mei/TODO @@ -0,0 +1,5 @@ +TODO: + - Cleanup and split the timer function +Upon Unstaging: + - Documentation/ioctl/ioctl-number.txt + - Updated MAINTAINERS diff --git a/Documentation/misc-devices/mei/mei-amt-version.c b/Documentation/misc-devices/mei/mei-amt-version.c new file mode 100644 index 000000000000..01804f216312 --- /dev/null +++ b/Documentation/misc-devices/mei/mei-amt-version.c @@ -0,0 +1,481 @@ +/****************************************************************************** + * Intel Management Engine Interface (Intel MEI) Linux driver + * Intel MEI Interface Header + * + * This file is provided under a dual BSD/GPLv2 license. When using or + * redistributing this file, you may do so under either license. + * + * GPL LICENSE SUMMARY + * + * Copyright(c) 2012 Intel Corporation. All rights reserved. + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of version 2 of the GNU General Public License as + * published by the Free Software Foundation. + * + * This program is distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110, + * USA + * + * The full GNU General Public License is included in this distribution + * in the file called LICENSE.GPL. + * + * Contact Information: + * Intel Corporation. + * linux-mei@linux.intel.com + * http://www.intel.com + * + * BSD LICENSE + * + * Copyright(c) 2003 - 2012 Intel Corporation. All rights reserved. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * * Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * * Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * * Neither the name Intel Corporation nor the names of its + * contributors may be used to endorse or promote products derived + * from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + *****************************************************************************/ + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +/***************************************************************************** + * Intel Management Engine Interface + *****************************************************************************/ + +#define mei_msg(_me, fmt, ARGS...) do { \ + if (_me->verbose) \ + fprintf(stderr, fmt, ##ARGS); \ +} while (0) + +#define mei_err(_me, fmt, ARGS...) do { \ + fprintf(stderr, "Error: " fmt, ##ARGS); \ +} while (0) + +struct mei { + uuid_le guid; + bool initialized; + bool verbose; + unsigned int buf_size; + unsigned char prot_ver; + int fd; +}; + +static void mei_deinit(struct mei *cl) +{ + if (cl->fd != -1) + close(cl->fd); + cl->fd = -1; + cl->buf_size = 0; + cl->prot_ver = 0; + cl->initialized = false; +} + +static bool mei_init(struct mei *me, const uuid_le *guid, + unsigned char req_protocol_version, bool verbose) +{ + int result; + struct mei_client *cl; + struct mei_connect_client_data data; + + mei_deinit(me); + + me->verbose = verbose; + + me->fd = open("/dev/mei", O_RDWR); + if (me->fd == -1) { + mei_err(me, "Cannot establish a handle to the Intel MEI driver\n"); + goto err; + } + memcpy(&me->guid, guid, sizeof(*guid)); + memset(&data, 0, sizeof(data)); + me->initialized = true; + + memcpy(&data.in_client_uuid, &me->guid, sizeof(me->guid)); + result = ioctl(me->fd, IOCTL_MEI_CONNECT_CLIENT, &data); + if (result) { + mei_err(me, "IOCTL_MEI_CONNECT_CLIENT receive message. err=%d\n", result); + goto err; + } + cl = &data.out_client_properties; + mei_msg(me, "max_message_length %d\n", cl->max_msg_length); + mei_msg(me, "protocol_version %d\n", cl->protocol_version); + + if ((req_protocol_version > 0) && + (cl->protocol_version != req_protocol_version)) { + mei_err(me, "Intel MEI protocol version not supported\n"); + goto err; + } + + me->buf_size = cl->max_msg_length; + me->prot_ver = cl->protocol_version; + + return true; +err: + mei_deinit(me); + return false; +} + +static ssize_t mei_recv_msg(struct mei *me, unsigned char *buffer, + ssize_t len, unsigned long timeout) +{ + ssize_t rc; + + mei_msg(me, "call read length = %zd\n", len); + + rc = read(me->fd, buffer, len); + if (rc < 0) { + mei_err(me, "read failed with status %zd %s\n", + rc, strerror(errno)); + mei_deinit(me); + } else { + mei_msg(me, "read succeeded with result %zd\n", rc); + } + return rc; +} + +static ssize_t mei_send_msg(struct mei *me, const unsigned char *buffer, + ssize_t len, unsigned long timeout) +{ + struct timeval tv; + ssize_t written; + ssize_t rc; + fd_set set; + + tv.tv_sec = timeout / 1000; + tv.tv_usec = (timeout % 1000) * 1000000; + + mei_msg(me, "call write length = %zd\n", len); + + written = write(me->fd, buffer, len); + if (written < 0) { + rc = -errno; + mei_err(me, "write failed with status %zd %s\n", + written, strerror(errno)); + goto out; + } + + FD_ZERO(&set); + FD_SET(me->fd, &set); + rc = select(me->fd + 1 , &set, NULL, NULL, &tv); + if (rc > 0 && FD_ISSET(me->fd, &set)) { + mei_msg(me, "write success\n"); + } else if (rc == 0) { + mei_err(me, "write failed on timeout with status\n"); + goto out; + } else { /* rc < 0 */ + mei_err(me, "write failed on select with status %zd\n", rc); + goto out; + } + + rc = written; +out: + if (rc < 0) + mei_deinit(me); + + return rc; +} + +/*************************************************************************** + * Intel Advanced Management Technolgy ME Client + ***************************************************************************/ + +#define AMT_MAJOR_VERSION 1 +#define AMT_MINOR_VERSION 1 + +#define AMT_STATUS_SUCCESS 0x0 +#define AMT_STATUS_INTERNAL_ERROR 0x1 +#define AMT_STATUS_NOT_READY 0x2 +#define AMT_STATUS_INVALID_AMT_MODE 0x3 +#define AMT_STATUS_INVALID_MESSAGE_LENGTH 0x4 + +#define AMT_STATUS_HOST_IF_EMPTY_RESPONSE 0x4000 +#define AMT_STATUS_SDK_RESOURCES 0x1004 + + +#define AMT_BIOS_VERSION_LEN 65 +#define AMT_VERSIONS_NUMBER 50 +#define AMT_UNICODE_STRING_LEN 20 + +struct amt_unicode_string { + uint16_t length; + char string[AMT_UNICODE_STRING_LEN]; +} __attribute__((packed)); + +struct amt_version_type { + struct amt_unicode_string description; + struct amt_unicode_string version; +} __attribute__((packed)); + +struct amt_version { + uint8_t major; + uint8_t minor; +} __attribute__((packed)); + +struct amt_code_versions { + uint8_t bios[AMT_BIOS_VERSION_LEN]; + uint32_t count; + struct amt_version_type versions[AMT_VERSIONS_NUMBER]; +} __attribute__((packed)); + +/*************************************************************************** + * Intel Advanced Management Technolgy Host Interface + ***************************************************************************/ + +struct amt_host_if_msg_header { + struct amt_version version; + uint16_t _reserved; + uint32_t command; + uint32_t length; +} __attribute__((packed)); + +struct amt_host_if_resp_header { + struct amt_host_if_msg_header header; + uint32_t status; + unsigned char data[0]; +} __attribute__((packed)); + +const uuid_le MEI_IAMTHIF = UUID_LE(0x12f80028, 0xb4b7, 0x4b2d, \ + 0xac, 0xa8, 0x46, 0xe0, 0xff, 0x65, 0x81, 0x4c); + +#define AMT_HOST_IF_CODE_VERSIONS_REQUEST 0x0400001A +#define AMT_HOST_IF_CODE_VERSIONS_RESPONSE 0x0480001A + +const struct amt_host_if_msg_header CODE_VERSION_REQ = { + .version = {AMT_MAJOR_VERSION, AMT_MINOR_VERSION}, + ._reserved = 0, + .command = AMT_HOST_IF_CODE_VERSIONS_REQUEST, + .length = 0 +}; + + +struct amt_host_if { + struct mei mei_cl; + unsigned long