staging: iio: Cleanup some docs in staging
Subsystems (3)
Jonathan Cameron
maintainercover staging: iio: Cleanup some docs in staging
From: Jonathan Cameron <[email protected]>
Some of these simply got left behind when drivers moved out of staging. Others were improved upon no end by more recent documentation under Documentation/ and are inaccurate or incomplete.
For now I've left a few files in the staging/iio/Documentation directory
* inkernel.txt: We need an equivalent in the main IIO docs but more than a simple rst conversion and move is needed.
* sysfs-bus-iio-dds: DDS drivers are still in staging so let us keep this with them for now.
* sysfs-bus-iio-adc-ad7280a: The driver is still in staging, so we need to deal with that before moving or removing this one.
Comments on removing these of course welcome, but this is a rare occasion when I'll probably just apply these whether or not anyone reviews the series.
Thanks,
Jonathan
Jonathan Cameron (4):
staging:iio:dac:max517 remove documentation staging:iio:light: Move tsl2x7x ABI docs to correct location. staging:iio:light: drop stale ABI docs staging:iio:documentation: Drop most generic docs
.../ABI/testing/sysfs-bus-iio-light-tsl2772 | 0 drivers/staging/iio/Documentation/dac/max517 | 41 ---------- drivers/staging/iio/Documentation/device.txt | 74 ----------------- .../staging/iio/Documentation/overview.txt | 57 ------------- drivers/staging/iio/Documentation/ring.txt | 47 ----------- .../iio/Documentation/sysfs-bus-iio-light | 79 ------------------- drivers/staging/iio/Documentation/trigger.txt | 31 -------- 7 files changed, 329 deletions(-) rename drivers/staging/iio/Documentation/light/sysfs-bus-iio-light-tsl2x7x => Documentation/ABI/testing/sysfs-bus-iio-light-tsl2772 (100%) delete mode 100644 drivers/staging/iio/Documentation/dac/max517 delete mode 100644 drivers/staging/iio/Documentation/device.txt delete mode 100644 drivers/staging/iio/Documentation/overview.txt delete mode 100644 drivers/staging/iio/Documentation/ring.txt delete mode 100644 drivers/staging/iio/Documentation/sysfs-bus-iio-light delete mode 100644 drivers/staging/iio/Documentation/trigger.txt
Signature · 1 line
2.28.0
Jonathan Cameron
maintainerPATCH 1/4 staging:iio:dac:max517 remove documentation
From: Jonathan Cameron <[email protected]>
Whilst there is some useful info in here, it can be easily obtained from datasheets. Some of the info should perhaps be incorporated into a device tree bindings doc.
As this didn't move out of staging with the driver, I'm suggesting we just drop it. We don't generally carry per driver documentation with the exception of non standard ABI which is not the case here.
--- drivers/staging/iio/Documentation/dac/max517 | 41 -------------------- 1 file changed, 41 deletions(-)
drivers/staging/iio/Documentation/dac/max517 deleted +0 -41
@@ -1,41 +0,0 @@ -Kernel driver max517 -==================== - -Supported chips: - * Maxim MAX517, MAX518, MAX519 - Prefix: 'max517' - Datasheet: Publicly available at the Maxim website - http://www.maxim-ic.com/ - -Author: - Roland Stigge <[email protected]> - -Description ------------ - -The Maxim MAX517/518/519 is an 8-bit DAC on the I2C bus. The following table -shows the different feature sets of the variants MAX517, MAX518 and MAX519: - -Feature MAX517 MAX518 MAX519 --------------------------------------------------------------------------- -One output channel X -Two output channels X X -Simultaneous output updates X X -Supply voltage as reference X -Separate reference input X -Reference input for each DAC X - -Via the iio sysfs interface, there are three attributes available: out1_raw, -out2_raw and out12_raw. With out1_raw and out2_raw, the current output values -(0..255) of the DACs can be written to the device. out12_raw can be used to set -both output channel values simultaneously. - -With MAX517, only out1_raw is available. - -Via out1_scale (and where appropriate, out2_scale), the current scaling factor -in mV can be read. - -When the operating system goes to a power down state, the Power Down function -of the chip is activated, reducing the supply current to 4uA. - -On power-up, the device is in 0V-output state.
Signature · 1 line
2.28.0
Jonathan Cameron
maintainerPATCH 2/4 staging:iio:light: Move tsl2x7x ABI docs to correct location.
In reply to Jonathan CameronFrom: Jonathan Cameron <[email protected]>
These seem to be up to date but never moved out of staging when the driver did. Hence let us move them out now.
--- .../ABI/testing/sysfs-bus-iio-light-tsl2772 | 0 1 file changed, 0 insertions(+), 0 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio-light-tsl2772 renamed from drivers/staging/iio/Documentation/light/sysfs-bus-iio-light-tsl2x7x +0 -0
Signature · 1 line
2.28.0
Re: [PATCH 2/4] staging:iio:light: Move tsl2x7x ABI docs to correct location.
Quoted 7 lines · Jonathan Cameron
From: Jonathan Cameron <[email protected]>
These seem to be up to date but never moved out of staging when the driver did. Hence let us move them out now.
Signed-off-by Jonathan Cameron <[email protected]>Cc Brian Masney <[email protected]>
Oops, that was my mistake. Thanks for the cleanup!
Brian
Quoted 10 lines
--- .../ABI/testing/sysfs-bus-iio-light-tsl2772 | 0 1 file changed, 0 insertions(+), 0 deletions(-)Documentation/ABI/testing/sysfs-bus-iio-light-tsl2772 renamed from drivers/staging/iio/Documentation/light/sysfs-bus-iio-light-tsl2x7x +0
-0Signature · 1 line
2.28.0
Jonathan Cameron
maintainerPATCH 3/4 staging:iio:light: drop stale ABI docs
In reply to Jonathan CameronFrom: Jonathan Cameron <[email protected]>
There are no remaining light drivers in staging/iio. The content of this file are either included in the non staging ABI docs, or don't seem to be used in any current driver.
--- .../iio/Documentation/sysfs-bus-iio-light | 79 ------------------- 1 file changed, 79 deletions(-)
drivers/staging/iio/Documentation/sysfs-bus-iio-light deleted +0 -79
@@ -1,79 +0,0 @@ -What: /sys/bus/iio/devices/device[n]/in_illuminance0[_input|_raw] -KernelVersion: 2.6.35 -Contact: [email protected] -Description: - This should return the calculated lux from the light sensor. If - it comes back in SI units, it should also include _input else it - should include _raw to signify it is not in SI units. - -What: /sys/.../device[n]/proximity_on_chip_ambient_infrared_suppression -KernelVersion: 2.6.37 -Contact: [email protected] -Description: - Hardware dependent mode for an ALS device to calculate the value - in proximity mode. When this is enabled, then the device should - use a infrared sensor reading to remove infrared noise from the - proximity reading. If this is not enabled, the driver can still - do this calculation manually by reading the infrared sensor - value and doing the negation in sw. - -What: /sys/bus/iio/devices/device[n]/in_proximity[_input|_raw] -KernelVersion: 2.6.37 -Contact: [email protected] -Description: - This property is supported by proximity sensors and should be - used to return the value of a reading by the sensor. If this - value is returned in SI units, it should also include _input - but if it is not, then it should include _raw. - -What: /sys/bus/iio/devices/device[n]/intensity_infrared[_input|_raw] -KernelVersion: 2.6.37 -Contact: [email protected] -Description: - This property is supported by sensors that have an infrared - sensing mode. This value should be the output from a reading - and if expressed in SI units, should include _input. If this - value is not in SI units, then it should include _raw. - -What: /sys/bus/iio/devices/device[n]/in_illuminance0_target -KernelVersion: 2.6.37 -Contact: [email protected] -Description: - This property gets/sets the last known external - lux measurement used in/for calibration. - -What: /sys/bus/iio/devices/device[n]/in_illuminance0_integration_time -KernelVersion: 2.6.37 -Contact: [email protected] -Description: - This property gets/sets the sensors ADC analog integration time. - -What: /sys/bus/iio/devices/device[n]/in_illuminance0_lux_table -KernelVersion: 2.6.37 -Contact: [email protected] -Description: - This property gets/sets the table of coefficients - used in calculating illuminance in lux. - -What: /sys/bus/iio/devices/device[n]/in_intensity_clear[_input|_raw] -What: /sys/bus/iio/devices/device[n]/in_intensity_red[_input|_raw] -What: /sys/bus/iio/devices/device[n]/in_intensity_green[_input|_raw] -What: /sys/bus/iio/devices/device[n]/in_intensity_blue[_input|_raw] -KernelVersion: 3.6.0 -Contact: [email protected] -Description: - This property is supported by sensors that have a RGBC - sensing mode. This value should be the output from a reading - and if expressed in SI units, should include _input. If this - value is not in SI units (irradiance, uW/mm^2), then it should - include _raw. - -What: /sys/bus/iio/devices/device[n]/in_cct0[_input|_raw] -KernelVersion: 3.6.0 -Contact: [email protected] -Description: - This should return the correlated color temperature from the - light sensor. If it comes back in SI units, it should also - include _input else it should include _raw to signify it is not - in SI units. -
Signature · 1 line
2.28.0
Jonathan Cameron
maintainerPATCH 4/4 staging:iio:documentation: Drop most generic docs
In reply to Jonathan CameronFrom: Jonathan Cameron <[email protected]>
These docs are both suffering from being out of date, and from being superceeded by the documentation in Documentation/driver-api/iio
Note the inkern.txt drop is left for now as this is an area not well covered by the more recent documentation outside staging.
--- drivers/staging/iio/Documentation/device.txt | 74 ------------------- .../staging/iio/Documentation/overview.txt | 57 -------------- drivers/staging/iio/Documentation/ring.txt | 47 ------------ drivers/staging/iio/Documentation/trigger.txt | 31 -------- 4 files changed, 209 deletions(-)
drivers/staging/iio/Documentation/device.txt deleted +0 -74
@@ -1,74 +0,0 @@ -IIO Device drivers - -This is not intended to provide a comprehensive guide to writing an -IIO device driver. For further information see the drivers within the -subsystem. - -The crucial structure for device drivers in iio is iio_dev. - -First allocate one using: - -struct iio_dev *indio_dev = iio_device_alloc(parent, sizeof(struct chip_state)); -where chip_state is a structure of local state data for this instance of -the chip. - -That data can be accessed using iio_priv(struct iio_dev *). - -Then fill in the following: - -- indio_dev->name - Name of the device being driven - made available as the name - attribute in sysfs. - -- indio_dev->info - pointer to a structure with elements that tend to be fixed for - large sets of different parts supported by a given driver. - This contains: - * info->event_attrs: - Attributes used to enable / disable hardware events. - * info->attrs: - General device attributes. Typically used for the weird - and the wonderful bits not covered by the channel specification. - * info->read_raw: - Raw data reading function. Used for both raw channel access - and for associate parameters such as offsets and scales. - * info->write_raw: - Raw value writing function. Used for writable device values such - as DAC values and calibbias. - * info->read_event_config: - Typically only set if there are some interrupt lines. This - is used to read if an on sensor event detector is enabled. - * info->write_event_config: - Enable / disable an on sensor event detector. - * info->read_event_value: - Read value associated with on sensor event detectors. Note that - the meaning of the returned value is dependent on the event - type. - * info->write_event_value: - Write the value associated with on sensor event detectors. E.g. - a threshold above which an interrupt occurs. Note that the - meaning of the value to be set is event type dependent. - -- indio_dev->modes: - Specify whether direct access and / or ring buffer access is supported. -- indio_dev->buffer: - An optional associated buffer. -- indio_dev->pollfunc: - Poll function related elements. This controls what occurs when a trigger - to which this device is attached sends an event. -- indio_dev->channels: - Specification of device channels. Most attributes etc. are built - from this spec. -- indio_dev->num_channels: - How many channels are there? - -Once these are set up, a call to iio_device_register(indio_dev) -will register the device with the iio core. - -Worth noting here is that, if a ring buffer is to be used, it can be -allocated prior to registering the device with the iio-core, but must -be registered afterwards (otherwise the whole parentage of devices -gets confused) - -On remove, iio_device_unregister(indio_dev) will remove the device from -the core, and iio_device_free(indio_dev) will clean up.
drivers/staging/iio/Documentation/overview.txt deleted +0 -57
57 lines not on this page · raw message
drivers/staging/iio/Documentation/ring.txt deleted +0 -47
47 lines not on this page · raw message
drivers/staging/iio/Documentation/trigger.txt deleted +0 -31
@@ -1,31 +0,0 @@ -IIO trigger drivers. - -Many triggers are provided by hardware that will also be registered as -an IIO device. Whilst this can create device specific complexities -such triggers are registered with the core in the same way as -stand-alone triggers. - -struct iio_trig *trig = iio_trigger_alloc("<trigger format string>", ...); - -allocates a trigger structure. The key elements to then fill in within -a driver are: - -trig->set_trigger_state: - Function that enables / disables the underlying source of the trigger. - -There is also a -trig->alloc_list which is useful for drivers that allocate multiple -triggers to keep track of what they have created. - -When these have been set call: - -iio_trigger_register(trig); - -to register the trigger with the core, making it available to trigger -consumers. - -Trigger Consumers - -Currently triggers are only used for the filling of software -buffers and as such any device supporting INDIO_BUFFER_TRIGGERED has the -consumer interface automatically created.
Signature · 1 line
2.28.0
Quoted 14 lines · On Sat, 5 Sep 2020 18:47:17 +0100 Jonathan Cameron <[email protected]> wrote:
From: Jonathan Cameron <[email protected]>
Some of these simply got left behind when drivers moved out of staging. Others were improved upon no end by more recent documentation under
Documentation/and are inaccurate or incomplete.For now I've left a few files in the staging/iio/Documentation directory
* inkernel.txt: We need an equivalent in the main IIO docs but more than a simple rst conversion and move is needed.
* sysfs-bus-iio-dds: DDS drivers are still in staging so let us keep this with them for now.
* sysfs-bus-iio-adc-ad7280a: The driver is still in staging, so we need to deal with that before moving or removing this one.
Quoted 2 lines
Comments on removing these of course welcome, but this is a rare occasion when I'll probably just apply these whether or not anyone reviews the series.
As mentioned, I'm not that bothered by reviews on patches removing docs so I've applied these with just the addition of the ack that Brian gave.
Thanks,
Jonathan
Quoted 27 lines
Thanks,
Jonathan
Jonathan Cameron (4):
staging:iio:dac:max517 remove documentation staging:iio:light: Move tsl2x7x ABI docs to correct location. staging:iio:light: drop stale ABI docs staging:iio:documentation: Drop most generic docs.../ABI/testing/sysfs-bus-iio-light-tsl2772 | 0 drivers/staging/iio/Documentation/dac/max517 | 41 ---------- drivers/staging/iio/Documentation/device.txt | 74 ----------------- .../staging/iio/Documentation/overview.txt | 57 ------------- drivers/staging/iio/Documentation/ring.txt | 47 ----------- .../iio/Documentation/sysfs-bus-iio-light | 79 ------------------- drivers/staging/iio/Documentation/trigger.txt | 31 -------- 7 files changed, 329 deletions(-) rename drivers/staging/iio/Documentation/light/sysfs-bus-iio-light-tsl2x7x => Documentation/ABI/testing/sysfs-bus-iio-light-tsl2772 (100%) delete mode 100644 drivers/staging/iio/Documentation/dac/max517 delete mode 100644 drivers/staging/iio/Documentation/device.txt delete mode 100644 drivers/staging/iio/Documentation/overview.txt delete mode 100644 drivers/staging/iio/Documentation/ring.txt delete mode 100644 drivers/staging/iio/Documentation/sysfs-bus-iio-light delete mode 100644 drivers/staging/iio/Documentation/trigger.txt