[PATCH 0/4] staging: iio: Cleanup some docs in staging

[PATCH 0/4] staging: iio: Cleanup some docs in staging

[Jonathan Cameron]

From: Jonathan Cameron <Jonathan.Cameron@huawei.com>

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

-- 
2.28.0

[PATCH 1/4] staging:iio:dac:max517 remove documentation

[Jonathan Cameron]

From: Jonathan Cameron <Jonathan.Cameron@huawei.com>

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.

Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
Cc: Roland Stigge <stigge@antcom.de>
---
 drivers/staging/iio/Documentation/dac/max517 | 41 --------------------
 1 file changed, 41 deletions(-)

diff --git a/drivers/staging/iio/Documentation/dac/max517 b/drivers/staging/iio/Documentation/dac/max517
deleted file mode 100644
index e60ec2f91a7a..000000000000
--- a/drivers/staging/iio/Documentation/dac/max517
+++ /dev/null
@@ -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 <stigge@antcom.de>
-
-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.
-- 
2.28.0

[PATCH 2/4] staging:iio:light: Move tsl2x7x ABI docs to correct location.

[Jonathan Cameron]

From: Jonathan Cameron <Jonathan.Cameron@huawei.com>

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 <Jonathan.Cameron@huawei.com>
Cc: Brian Masney <masneyb@onstation.org>
---
 .../ABI/testing/sysfs-bus-iio-light-tsl2772                       | 0
 1 file changed, 0 insertions(+), 0 deletions(-)

diff --git a/drivers/staging/iio/Documentation/light/sysfs-bus-iio-light-tsl2x7x b/Documentation/ABI/testing/sysfs-bus-iio-light-tsl2772
similarity index 100%
rename from drivers/staging/iio/Documentation/light/sysfs-bus-iio-light-tsl2x7x
rename to Documentation/ABI/testing/sysfs-bus-iio-light-tsl2772
-- 
2.28.0

[PATCH 3/4] staging:iio:light: drop stale ABI docs

[Jonathan Cameron]

From: Jonathan Cameron <Jonathan.Cameron@huawei.com>

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.

Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
---
 .../iio/Documentation/sysfs-bus-iio-light     | 79 -------------------
 1 file changed, 79 deletions(-)

diff --git a/drivers/staging/iio/Documentation/sysfs-bus-iio-light b/drivers/staging/iio/Documentation/sysfs-bus-iio-light
deleted file mode 100644
index 7c7cd8456060..000000000000
--- a/drivers/staging/iio/Documentation/sysfs-bus-iio-light
+++ /dev/null
@@ -1,79 +0,0 @@
-What:		/sys/bus/iio/devices/device[n]/in_illuminance0[_input|_raw]
-KernelVersion:	2.6.35
-Contact:	linux-iio@vger.kernel.org
-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:	linux-iio@vger.kernel.org
-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:	linux-iio@vger.kernel.org
-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:	linux-iio@vger.kernel.org
-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:	linux-iio@vger.kernel.org
-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:	linux-iio@vger.kernel.org
-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:	linux-iio@vger.kernel.org
-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:	linux-iio@vger.kernel.org
-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:	linux-iio@vger.kernel.org
-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.
-
-- 
2.28.0

[PATCH 4/4] staging:iio:documentation: Drop most generic docs

[Jonathan Cameron]

From: Jonathan Cameron <Jonathan.Cameron@huawei.com>

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.

Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
---
 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(-)

diff --git a/drivers/staging/iio/Documentation/device.txt b/drivers/staging/iio/Documentation/device.txt
deleted file mode 100644
index 0d1275b1eb3f..000000000000
--- a/drivers/staging/iio/Documentation/device.txt
+++ /dev/null
@@ -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.
diff --git a/drivers/staging/iio/Documentation/overview.txt b/drivers/staging/iio/Documentation/overview.txt
deleted file mode 100644
index 00409d5dab4e..000000000000
--- a/drivers/staging/iio/Documentation/overview.txt
+++ /dev/null
@@ -1,57 +0,0 @@
-Overview of IIO
-
-The Industrial I/O subsystem is intended to provide support for devices
-that in some sense are analog to digital converters (ADCs). As many
-actual devices combine some ADCs with digital to analog converters
-(DACs) that functionality is also supported.
-
-The aim is to fill the gap between the somewhat similar hwmon and
-input subsystems.  Hwmon is very much directed at low sample rate
-sensors used in applications such as fan speed control and temperature
-measurement.  Input is, as its name suggests focused on input
-devices. In some cases, there is considerable overlap between these and
-IIO.
-
-A typical device falling into this category would be connected via SPI
-or I2C.
-
-Functionality of IIO
-
-* Basic device registration and handling. This is very similar to
-hwmon with simple polled access to device channels via sysfs.
-
-* Event chrdevs.  These are similar to input in that they provide a
-route to user space for hardware triggered events. Such events include
-threshold detectors, free-fall detectors and more complex action
-detection.  The events themselves are currently very simple with
-merely an event code and a timestamp.  Any data associated with the
-event must be accessed via polling.
-
-Note: A given device may have one or more event channel.  These events are
-turned on or off (if possible) via sysfs interfaces.
-
-* Hardware buffer support.  Some recent sensors have included
-fifo / ring buffers on the sensor chip.  These greatly reduce the load
-on the host CPU by buffering relatively large numbers of data samples
-based on an internal sampling clock. Examples include VTI SCA3000
-series and Analog Devices ADXL345 accelerometers.  Each buffer supports
-polling to establish when data is available.
-
-* Trigger and software buffer support. In many data analysis
-applications it is useful to be able to capture data based on some
-external signal (trigger).  These triggers might be a data ready
-signal, a gpio line connected to some external system or an on
-processor periodic interrupt.  A single trigger may initialize data
-capture or reading from a number of sensors.  These triggers are
-used in IIO to fill software buffers acting in a very similar
-fashion to the hardware buffers described above.
-
-Other documentation:
-
-device.txt - elements of a typical device driver.
-
-trigger.txt - elements of a typical trigger driver.
-
-ring.txt - additional elements required for buffer support.
-
-sysfs-bus-iio - abi documentation file.
diff --git a/drivers/staging/iio/Documentation/ring.txt b/drivers/staging/iio/Documentation/ring.txt
deleted file mode 100644
index 18718fcaf259..000000000000
--- a/drivers/staging/iio/Documentation/ring.txt
+++ /dev/null
@@ -1,47 +0,0 @@
-Buffer support within IIO
-
-This document is intended as a general overview of the functionality
-a buffer may supply and how it is specified within IIO.  For more
-specific information on a given buffer implementation, see the
-comments in the source code.  Note that some drivers allow buffer
-implementation to be selected at compile time via Kconfig options.
-
-A given buffer implementation typically embeds a struct
-iio_ring_buffer and it is a pointer to this that is provided to the
-IIO core. Access to the embedding structure is typically done via
-container_of functions.
-
-struct iio_ring_buffer contains a struct iio_ring_setup_ops *setup_ops
-which in turn contains the 4 function pointers
-(preenable, postenable, predisable and postdisable).
-These are used to perform device specific steps on either side
-of the core changing its current mode to indicate that the buffer
-is enabled or disabled (along with enabling triggering etc. as appropriate).
-
-Also in struct iio_ring_buffer is a struct iio_ring_access_funcs.
-The function pointers within here are used to allow the core to handle
-as much buffer functionality as possible. Note almost all of these
-are optional.
-
-store_to
-  If possible, push data to the buffer.
-
-read_last
-  If possible, get the most recent scan from the buffer (without removal).
-  This provides polling like functionality whilst the ring buffering is in
-  use without a separate read from the device.
-
-rip_first_n
-  The primary buffer reading function. Note that it may well not return
-  as much data as requested.
-
-request_update
-  If parameters have changed that require reinitialization or configuration of
-  the buffer this will trigger it.
-
-set_bytes_per_datum
-  Set the number of bytes for a complete scan. (All samples + timestamp)
-
-set_length
-  Set the number of complete scans that may be held by the buffer.
-
diff --git a/drivers/staging/iio/Documentation/trigger.txt b/drivers/staging/iio/Documentation/trigger.txt
deleted file mode 100644
index 299a1add98bf..000000000000
--- a/drivers/staging/iio/Documentation/trigger.txt
+++ /dev/null
@@ -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.
-- 
2.28.0

Re: [PATCH 2/4] staging:iio:light: Move tsl2x7x ABI docs to correct location.

[Brian Masney]

On Sat, Sep 05, 2020 at 06:47:19PM +0100, Jonathan Cameron wrote:
> From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> 
> 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 <Jonathan.Cameron@huawei.com>
> Cc: Brian Masney <masneyb@onstation.org>

Oops, that was my mistake. Thanks for the cleanup!

Reviewed-by: Brian Masney <masneyb@onstation.org>

Brian


> ---
>  .../ABI/testing/sysfs-bus-iio-light-tsl2772                       | 0
>  1 file changed, 0 insertions(+), 0 deletions(-)
> 
> diff --git a/drivers/staging/iio/Documentation/light/sysfs-bus-iio-light-tsl2x7x b/Documentation/ABI/testing/sysfs-bus-iio-light-tsl2772
> similarity index 100%
> rename from drivers/staging/iio/Documentation/light/sysfs-bus-iio-light-tsl2x7x
> rename to Documentation/ABI/testing/sysfs-bus-iio-light-tsl2772
> -- 
> 2.28.0

Re: [PATCH 0/4] staging: iio: Cleanup some docs in staging

[Jonathan Cameron]

On Sat,  5 Sep 2020 18:47:17 +0100
Jonathan Cameron <jic23@kernel.org> wrote:

> From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> 
> 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.
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

> 
> 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
>