[PATCH 0/6] iio: Fix kernel docs warnings

[PATCH 0/6] iio: Fix kernel docs warnings

[Cristina Opriceana]

This patchset walks through drivers/iio/*, include/linux/iio/*
to fix kernel docs warnings.

Cristina Opriceana (6):
  iio: core: Add function params for kernel docs
  iio: buffer: Fix kernel docs warnings
  iio: trigger: Add missing fields in kernel docs
  iio: event: Add missing fields in kernel docs
  include: linux: iio: Fix function parameter name in kernel doc
  include: linux: iio: Add missing kernel doc field

 drivers/iio/industrialio-buffer.c  | 15 ++++++++++++++-
 drivers/iio/industrialio-core.c    | 25 ++++++++++++++++++++-----
 drivers/iio/industrialio-event.c   |  6 ++++++
 drivers/iio/industrialio-trigger.c | 27 ++++++++++++++++++++++++---
 include/linux/iio/consumer.h       |  2 +-
 include/linux/iio/sysfs.h          |  3 ++-
 6 files changed, 67 insertions(+), 11 deletions(-)

-- 
1.9.1

[PATCH 1/6] iio: core: Add function params for kernel docs

[Cristina Opriceana]

This patch adds the missing fields in kernel docs to remove
some warnings that appear when the IIO Documentation DocBook
is generated.

Signed-off-by: Cristina Opriceana <cristina.opriceana@gmail.com>
---
 drivers/iio/industrialio-core.c | 25 ++++++++++++++++++++-----
 1 file changed, 20 insertions(+), 5 deletions(-)

diff --git a/drivers/iio/industrialio-core.c b/drivers/iio/industrialio-core.c
index d8051cd..da643b9 100644
--- a/drivers/iio/industrialio-core.c
+++ b/drivers/iio/industrialio-core.c
@@ -406,10 +406,16 @@ EXPORT_SYMBOL_GPL(iio_enum_write);
 
 /**
  * iio_format_value() - Formats a IIO value into its string representation
- * @buf: The buffer to which the formated value gets written
- * @type: One of the IIO_VAL_... constants. This decides how the val and val2
- *        parameters are formatted.
- * @vals: pointer to the values, exact meaning depends on the type parameter.
+ * @buf:	The buffer to which the formated value gets written
+ * @type:	One of the IIO_VAL_... constants. This decides how the val
+ *		and val2 parameters are formatted.
+ * @size:	Number of IIO value entries contained in vals
+ * @vals:	Pointer to the values, exact meaning depends on the
+ *		type parameter.
+ *
+ * Return: 0 by default, a negative number on failiure or the
+ *	   total number of characters written for a type that belongs
+ *	   to the IIO_VAL_... constant.
  */
 ssize_t iio_format_value(char *buf, unsigned int type, int size, int *vals)
 {
@@ -1096,6 +1102,11 @@ EXPORT_SYMBOL_GPL(devm_iio_device_free);
 
 /**
  * iio_chrdev_open() - chrdev file open for buffer access and ioctls
+ * @inode:	Inode structure for identifying the device in the file system
+ * @filp:	File structure for iio device used to keep and later access
+ *		private data
+ *
+ * Return: 0 on success or -EBUSY if the device is already opened
  **/
 static int iio_chrdev_open(struct inode *inode, struct file *filp)
 {
@@ -1114,7 +1125,11 @@ static int iio_chrdev_open(struct inode *inode, struct file *filp)
 
 /**
  * iio_chrdev_release() - chrdev file close buffer access and ioctls
- **/
+ * @inode:	Inode structure pointer for the char device
+ * @filp:	File structure pointer for the char device
+ *
+ * Return: 0 for successful release
+ */
 static int iio_chrdev_release(struct inode *inode, struct file *filp)
 {
 	struct iio_dev *indio_dev = container_of(inode->i_cdev,
-- 
1.9.1

[PATCH 2/6] iio: buffer: Fix kernel docs warnings

[Cristina Opriceana]

Fix kernel docs for structures and functions in order to
remove some warnings when the documentation gets generated.

Signed-off-by: Cristina Opriceana <cristina.opriceana@gmail.com>
---
 drivers/iio/industrialio-buffer.c | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/drivers/iio/industrialio-buffer.c b/drivers/iio/industrialio-buffer.c
index b13f941..a671953 100644
--- a/drivers/iio/industrialio-buffer.c
+++ b/drivers/iio/industrialio-buffer.c
@@ -91,9 +91,16 @@ static bool iio_buffer_ready(struct iio_dev *indio_dev, struct iio_buffer *buf,
 
 /**
  * iio_buffer_read_first_n_outer() - chrdev read for buffer access
+ * @filp:	File structure pointer for the char device
+ * @buf:	Destination buffer for iio buffer read
+ * @n:		First n bytes to read
+ * @f_ps:	Long offset provided by the user as a seek position
  *
  * This function relies on all buffer implementations having an
  * iio_buffer as their first element.
+ *
+ * Return: negative values corresponding to error codes or ret != 0
+ *	   for ending the reading activity
  **/
 ssize_t iio_buffer_read_first_n_outer(struct file *filp, char __user *buf,
 				      size_t n, loff_t *f_ps)
@@ -143,6 +150,12 @@ ssize_t iio_buffer_read_first_n_outer(struct file *filp, char __user *buf,
 
 /**
  * iio_buffer_poll() - poll the buffer to find out if it has data
+ * @filp:	File structure poiner for device access
+ * @wait:	Poll table structure pointer for which the driver adds
+ *		a wait queue
+ *
+ * Return: (POLLIN | POLLRDNORM) if data is available for reading
+ *	   or 0 for other cases
  */
 unsigned int iio_buffer_poll(struct file *filp,
 			     struct poll_table_struct *wait)
@@ -1136,7 +1149,7 @@ int iio_scan_mask_query(struct iio_dev *indio_dev,
 EXPORT_SYMBOL_GPL(iio_scan_mask_query);
 
 /**
- * struct iio_demux_table() - table describing demux memcpy ops
+ * struct iio_demux_table - table describing demux memcpy ops
  * @from:	index to copy from
  * @to:		index to copy to
  * @length:	how many bytes to copy
-- 
1.9.1

[PATCH 3/6] iio: trigger: Add missing fields in kernel docs

[Cristina Opriceana]

Fix kernel docs warnings by adding the missing description
for each of the existing function parameters.

Signed-off-by: Cristina Opriceana <cristina.opriceana@gmail.com>
---
 drivers/iio/industrialio-trigger.c | 27 ++++++++++++++++++++++++---
 1 file changed, 24 insertions(+), 3 deletions(-)

diff --git a/drivers/iio/industrialio-trigger.c b/drivers/iio/industrialio-trigger.c
index d31098e..cae2939 100644
--- a/drivers/iio/industrialio-trigger.c
+++ b/drivers/iio/industrialio-trigger.c
@@ -40,7 +40,14 @@ static DEFINE_MUTEX(iio_trigger_list_lock);
 
 /**
  * iio_trigger_read_name() - retrieve useful identifying name
- **/
+ * @dev:	device that holds the iio_trigger
+ * @attr:	pointer to the device_attribute structure that is
+ *		being processed
+ * @buf:	buffer to print the name into
+ *
+ * Return: a negative number on failure or the number of written
+ *	   characters on success.
+ */
 static ssize_t iio_trigger_read_name(struct device *dev,
 				     struct device_attribute *attr,
 				     char *buf)
@@ -288,10 +295,17 @@ EXPORT_SYMBOL_GPL(iio_dealloc_pollfunc);
 
 /**
  * iio_trigger_read_current() - trigger consumer sysfs query current trigger
+ * @dev:	Device this iio_dev belongs to
+ * @attr:	Pointer to the device_attribute structure that
+ *		is being processed
+ * @buf:	Buffer where the current trigger name will be printed into
  *
  * For trigger consumers the current_trigger interface allows the trigger
  * used by the device to be queried.
- **/
+ *
+ * Return: a negative number on failure, the number of characters written
+ *	   on success or 0 if no trigger is available
+ */
 static ssize_t iio_trigger_read_current(struct device *dev,
 					struct device_attribute *attr,
 					char *buf)
@@ -305,11 +319,18 @@ static ssize_t iio_trigger_read_current(struct device *dev,
 
 /**
  * iio_trigger_write_current() - trigger consumer sysfs set current trigger
+ * @dev:	Device that this iio_dev belongs to
+ * @attr:	Device attribute that is being processed
+ * @buf:	String buffer that holds the name of the trigger
+ * @len:	Length of the trigger name held by buf
  *
  * For trigger consumers the current_trigger interface allows the trigger
  * used for this device to be specified at run time based on the trigger's
  * name.
- **/
+ *
+ * Return: negative error code on failure or length of the buffer
+ *	   on success
+ */
 static ssize_t iio_trigger_write_current(struct device *dev,
 					 struct device_attribute *attr,
 					 const char *buf,
-- 
1.9.1

[PATCH 4/6] iio: event: Add missing fields in kernel docs

[Cristina Opriceana]

Fix kernel docs warnings by adding the missing fields,
each with its associated description.

Signed-off-by: Cristina Opriceana <cristina.opriceana@gmail.com>
---
 drivers/iio/industrialio-event.c | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/drivers/iio/industrialio-event.c b/drivers/iio/industrialio-event.c
index 894d813..b2f63f9 100644
--- a/drivers/iio/industrialio-event.c
+++ b/drivers/iio/industrialio-event.c
@@ -32,6 +32,7 @@
  * @dev_attr_list:	list of event interface sysfs attribute
  * @flags:		file operations related flags including busy flag.
  * @group:		event interface sysfs attribute group
+ * @read_lock:		lock to protect kfifo read operations
  */
 struct iio_event_interface {
 	wait_queue_head_t	wait;
@@ -75,6 +76,11 @@ EXPORT_SYMBOL(iio_push_event);
 
 /**
  * iio_event_poll() - poll the event queue to find out if it has data
+ * @filep:	File structure pointer to identify the device
+ * @wait:	Poll table pointer to add the wait queue on
+ *
+ * Return: (POLLIN | POLLRDNORM) if data is available for reading
+ *	   or a negative error code on failure
  */
 static unsigned int iio_event_poll(struct file *filep,
 			     struct poll_table_struct *wait)
-- 
1.9.1

[PATCH 5/6] include: linux: iio: Fix function parameter name in kernel doc

[Cristina Opriceana]

Fix buffer name from kernel doc according to the function parameter.

Signed-off-by: Cristina Opriceana <cristina.opriceana@gmail.com>
---
 include/linux/iio/consumer.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/iio/consumer.h b/include/linux/iio/consumer.h
index 26fb8f6..fad5867 100644
--- a/include/linux/iio/consumer.h
+++ b/include/linux/iio/consumer.h
@@ -100,7 +100,7 @@ void iio_channel_stop_all_cb(struct iio_cb_buffer *cb_buff);
 
 /**
  * iio_channel_cb_get_channels() - get access to the underlying channels.
- * @cb_buff:		The callback buffer from whom we want the channel
+ * @cb_buffer:		The callback buffer from whom we want the channel
  *			information.
  *
  * This function allows one to obtain information about the channels.
-- 
1.9.1

[PATCH 6/6] include: linux: iio: Add missing kernel doc field

[Cristina Opriceana]

Fix kernel doc for the iio_dev_attr structure by adding its missing field.

Signed-off-by: Cristina Opriceana <cristina.opriceana@gmail.com>
---
 include/linux/iio/sysfs.h | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/include/linux/iio/sysfs.h b/include/linux/iio/sysfs.h
index 8a1d186..71fdd6f 100644
--- a/include/linux/iio/sysfs.h
+++ b/include/linux/iio/sysfs.h
@@ -18,7 +18,8 @@ struct iio_chan_spec;
  * struct iio_dev_attr - iio specific device attribute
  * @dev_attr:	underlying device attribute
  * @address:	associated register address
- * @l:		list head for maintaining list of dynamically created attrs.
+ * @l:		list head for maintaining list of dynamically created attrs
+ * @c:		specification for the underlying channels
  */
 struct iio_dev_attr {
 	struct device_attribute dev_attr;
-- 
1.9.1

Re: [PATCH 1/6] iio: core: Add function params for kernel docs

[Jonathan Cameron]

On 24/07/15 14:16, Cristina Opriceana wrote:
> This patch adds the missing fields in kernel docs to remove
> some warnings that appear when the IIO Documentation DocBook
> is generated.
> 
> Signed-off-by: Cristina Opriceana <cristina.opriceana@gmail.com>
Mostly good.  Some typos.  (some from the original).

Fixed up as noted below and applied to the togreg branch of iio.git
Thanks,

Jonathan
> ---
>  drivers/iio/industrialio-core.c | 25 ++++++++++++++++++++-----
>  1 file changed, 20 insertions(+), 5 deletions(-)
> 
> diff --git a/drivers/iio/industrialio-core.c b/drivers/iio/industrialio-core.c
> index d8051cd..da643b9 100644
> --- a/drivers/iio/industrialio-core.c
> +++ b/drivers/iio/industrialio-core.c
> @@ -406,10 +406,16 @@ EXPORT_SYMBOL_GPL(iio_enum_write);
>  
>  /**
>   * iio_format_value() - Formats a IIO value into its string representation
> - * @buf: The buffer to which the formated value gets written
> - * @type: One of the IIO_VAL_... constants. This decides how the val and val2
> - *        parameters are formatted.
> - * @vals: pointer to the values, exact meaning depends on the type parameter.
> + * @buf:	The buffer to which the formated value gets written
formatted
> + * @type:	One of the IIO_VAL_... constants. This decides how the val
> + *		and val2 parameters are formatted.
> + * @size:	Number of IIO value entries contained in vals
> + * @vals:	Pointer to the values, exact meaning depends on the
> + *		type parameter.
> + *
> + * Return: 0 by default, a negative number on failiure or the
failure
> + *	   total number of characters written for a type that belongs
> + *	   to the IIO_VAL_... constant.
>   */
>  ssize_t iio_format_value(char *buf, unsigned int type, int size, int *vals)
>  {
> @@ -1096,6 +1102,11 @@ EXPORT_SYMBOL_GPL(devm_iio_device_free);
>  
>  /**
>   * iio_chrdev_open() - chrdev file open for buffer access and ioctls
> + * @inode:	Inode structure for identifying the device in the file system
> + * @filp:	File structure for iio device used to keep and later access
> + *		private data
> + *
> + * Return: 0 on success or -EBUSY if the device is already opened
>   **/
>  static int iio_chrdev_open(struct inode *inode, struct file *filp)
>  {
> @@ -1114,7 +1125,11 @@ static int iio_chrdev_open(struct inode *inode, struct file *filp)
>  
>  /**
>   * iio_chrdev_release() - chrdev file close buffer access and ioctls
> - **/
> + * @inode:	Inode structure pointer for the char device
> + * @filp:	File structure pointer for the char device
> + *
> + * Return: 0 for successful release
> + */
>  static int iio_chrdev_release(struct inode *inode, struct file *filp)
>  {
>  	struct iio_dev *indio_dev = container_of(inode->i_cdev,
> 

Re: [PATCH 2/6] iio: buffer: Fix kernel docs warnings

[Jonathan Cameron]

On 24/07/15 14:18, Cristina Opriceana wrote:
> Fix kernel docs for structures and functions in order to
> remove some warnings when the documentation gets generated.
> 
> Signed-off-by: Cristina Opriceana <cristina.opriceana@gmail.com>
Applied with another typo fixed up.
> ---
>  drivers/iio/industrialio-buffer.c | 15 ++++++++++++++-
>  1 file changed, 14 insertions(+), 1 deletion(-)
> 
> diff --git a/drivers/iio/industrialio-buffer.c b/drivers/iio/industrialio-buffer.c
> index b13f941..a671953 100644
> --- a/drivers/iio/industrialio-buffer.c
> +++ b/drivers/iio/industrialio-buffer.c
> @@ -91,9 +91,16 @@ static bool iio_buffer_ready(struct iio_dev *indio_dev, struct iio_buffer *buf,
>  
>  /**
>   * iio_buffer_read_first_n_outer() - chrdev read for buffer access
> + * @filp:	File structure pointer for the char device
> + * @buf:	Destination buffer for iio buffer read
> + * @n:		First n bytes to read
> + * @f_ps:	Long offset provided by the user as a seek position
>   *
>   * This function relies on all buffer implementations having an
>   * iio_buffer as their first element.
> + *
> + * Return: negative values corresponding to error codes or ret != 0
> + *	   for ending the reading activity
>   **/
>  ssize_t iio_buffer_read_first_n_outer(struct file *filp, char __user *buf,
>  				      size_t n, loff_t *f_ps)
> @@ -143,6 +150,12 @@ ssize_t iio_buffer_read_first_n_outer(struct file *filp, char __user *buf,
>  
>  /**
>   * iio_buffer_poll() - poll the buffer to find out if it has data
> + * @filp:	File structure poiner for device access
pointer
> + * @wait:	Poll table structure pointer for which the driver adds
> + *		a wait queue
> + *
> + * Return: (POLLIN | POLLRDNORM) if data is available for reading
> + *	   or 0 for other cases
>   */
>  unsigned int iio_buffer_poll(struct file *filp,
>  			     struct poll_table_struct *wait)
> @@ -1136,7 +1149,7 @@ int iio_scan_mask_query(struct iio_dev *indio_dev,
>  EXPORT_SYMBOL_GPL(iio_scan_mask_query);
>  
>  /**
> - * struct iio_demux_table() - table describing demux memcpy ops
> + * struct iio_demux_table - table describing demux memcpy ops
>   * @from:	index to copy from
>   * @to:		index to copy to
>   * @length:	how many bytes to copy
> 

Re: [PATCH 3/6] iio: trigger: Add missing fields in kernel docs

[Jonathan Cameron]

On 24/07/15 14:20, Cristina Opriceana wrote:
> Fix kernel docs warnings by adding the missing description
> for each of the existing function parameters.
> 
> Signed-off-by: Cristina Opriceana <cristina.opriceana@gmail.com>
A few comments inline.
> ---
>  drivers/iio/industrialio-trigger.c | 27 ++++++++++++++++++++++++---
>  1 file changed, 24 insertions(+), 3 deletions(-)
> 
> diff --git a/drivers/iio/industrialio-trigger.c b/drivers/iio/industrialio-trigger.c
> index d31098e..cae2939 100644
> --- a/drivers/iio/industrialio-trigger.c
> +++ b/drivers/iio/industrialio-trigger.c
> @@ -40,7 +40,14 @@ static DEFINE_MUTEX(iio_trigger_list_lock);
>  
>  /**
>   * iio_trigger_read_name() - retrieve useful identifying name
> - **/
> + * @dev:	device that holds the iio_trigger
The dev structure is within the struct iio_trigger rather than the other
way around. It is there to give it it a presence in the device model.
I'd keep this statement vague and say perhaps,
device associated with the iio_trigger.
> + * @attr:	pointer to the device_attribute structure that is
> + *		being processed
> + * @buf:	buffer to print the name into
> + *
> + * Return: a negative number on failure or the number of written
> + *	   characters on success.
> + */
>  static ssize_t iio_trigger_read_name(struct device *dev,
>  				     struct device_attribute *attr,
>  				     char *buf)
> @@ -288,10 +295,17 @@ EXPORT_SYMBOL_GPL(iio_dealloc_pollfunc);
>  
>  /**
>   * iio_trigger_read_current() - trigger consumer sysfs query current trigger
> + * @dev:	Device this iio_dev belongs to
Again, this implies a tighter relationship than is actually true.
The dev isn't the underlying device (e.g. the spi one or i2c one
but rather one created by the iio subsystem to give the iio_dev a
presence in the device model - on the iio sysfs bus).
> + * @attr:	Pointer to the device_attribute structure that
> + *		is being processed
> + * @buf:	Buffer where the current trigger name will be printed into
>   *
>   * For trigger consumers the current_trigger interface allows the trigger
>   * used by the device to be queried.
> - **/
> + *
> + * Return: a negative number on failure, the number of characters written
> + *	   on success or 0 if no trigger is available
> + */
>  static ssize_t iio_trigger_read_current(struct device *dev,
>  					struct device_attribute *attr,
>  					char *buf)
> @@ -305,11 +319,18 @@ static ssize_t iio_trigger_read_current(struct device *dev,
>  
>  /**
>   * iio_trigger_write_current() - trigger consumer sysfs set current trigger
> + * @dev:	Device that this iio_dev belongs to
> + * @attr:	Device attribute that is being processed
> + * @buf:	String buffer that holds the name of the trigger
> + * @len:	Length of the trigger name held by buf
>   *
>   * For trigger consumers the current_trigger interface allows the trigger
>   * used for this device to be specified at run time based on the trigger's
>   * name.
> - **/
> + *
> + * Return: negative error code on failure or length of the buffer
> + *	   on success
> + */
>  static ssize_t iio_trigger_write_current(struct device *dev,
>  					 struct device_attribute *attr,
>  					 const char *buf,
> 

Re: [PATCH 4/6] iio: event: Add missing fields in kernel docs

[Jonathan Cameron]

On 24/07/15 14:21, Cristina Opriceana wrote:
> Fix kernel docs warnings by adding the missing fields,
> each with its associated description.
> 
> Signed-off-by: Cristina Opriceana <cristina.opriceana@gmail.com>
Applied.  Thanks

Jonathan
> ---
>  drivers/iio/industrialio-event.c | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/drivers/iio/industrialio-event.c b/drivers/iio/industrialio-event.c
> index 894d813..b2f63f9 100644
> --- a/drivers/iio/industrialio-event.c
> +++ b/drivers/iio/industrialio-event.c
> @@ -32,6 +32,7 @@
>   * @dev_attr_list:	list of event interface sysfs attribute
>   * @flags:		file operations related flags including busy flag.
>   * @group:		event interface sysfs attribute group
> + * @read_lock:		lock to protect kfifo read operations
>   */
>  struct iio_event_interface {
>  	wait_queue_head_t	wait;
> @@ -75,6 +76,11 @@ EXPORT_SYMBOL(iio_push_event);
>  
>  /**
>   * iio_event_poll() - poll the event queue to find out if it has data
> + * @filep:	File structure pointer to identify the device
> + * @wait:	Poll table pointer to add the wait queue on
> + *
> + * Return: (POLLIN | POLLRDNORM) if data is available for reading
> + *	   or a negative error code on failure
>   */
>  static unsigned int iio_event_poll(struct file *filep,
>  			     struct poll_table_struct *wait)
> 

Re: [PATCH 5/6] include: linux: iio: Fix function parameter name in kernel doc

[Jonathan Cameron]

On 24/07/15 14:23, Cristina Opriceana wrote:
> Fix buffer name from kernel doc according to the function parameter.
> 
> Signed-off-by: Cristina Opriceana <cristina.opriceana@gmail.com>
Applied

Jonathan
> ---
>  include/linux/iio/consumer.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/include/linux/iio/consumer.h b/include/linux/iio/consumer.h
> index 26fb8f6..fad5867 100644
> --- a/include/linux/iio/consumer.h
> +++ b/include/linux/iio/consumer.h
> @@ -100,7 +100,7 @@ void iio_channel_stop_all_cb(struct iio_cb_buffer *cb_buff);
>  
>  /**
>   * iio_channel_cb_get_channels() - get access to the underlying channels.
> - * @cb_buff:		The callback buffer from whom we want the channel
> + * @cb_buffer:		The callback buffer from whom we want the channel
>   *			information.
>   *
>   * This function allows one to obtain information about the channels.
> 

Re: [PATCH 6/6] include: linux: iio: Add missing kernel doc field

[Jonathan Cameron]

On 24/07/15 14:26, Cristina Opriceana wrote:
> Fix kernel doc for the iio_dev_attr structure by adding its missing field.
> 
> Signed-off-by: Cristina Opriceana <cristina.opriceana@gmail.com>
Applied to the togreg branch fo iio.git with one small change.
> ---
>  include/linux/iio/sysfs.h | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/include/linux/iio/sysfs.h b/include/linux/iio/sysfs.h
> index 8a1d186..71fdd6f 100644
> --- a/include/linux/iio/sysfs.h
> +++ b/include/linux/iio/sysfs.h
> @@ -18,7 +18,8 @@ struct iio_chan_spec;
>   * struct iio_dev_attr - iio specific device attribute
>   * @dev_attr:	underlying device attribute
>   * @address:	associated register address
> - * @l:		list head for maintaining list of dynamically created attrs.
> + * @l:		list head for maintaining list of dynamically created attrs
> + * @c:		specification for the underlying channels
Only reflects the channel (rather than channels) which resulted in it's creation
(for shared channels the code is supposed to work with any of them being pointed
to here!)

Hence channels -> channel
>   */
>  struct iio_dev_attr {
>  	struct device_attribute dev_attr;
> 

Re: [PATCH 2/6] iio: buffer: Fix kernel docs warnings

[Hartmut Knaack]

Jonathan Cameron schrieb am 02.08.2015 um 19:27:
> On 24/07/15 14:18, Cristina Opriceana wrote:
>> Fix kernel docs for structures and functions in order to
>> remove some warnings when the documentation gets generated.
>>
>> Signed-off-by: Cristina Opriceana <cristina.opriceana@gmail.com>
> Applied with another typo fixed up.

Hi,
I'm afraid there is some information missing.

>> ---
>>  drivers/iio/industrialio-buffer.c | 15 ++++++++++++++-
>>  1 file changed, 14 insertions(+), 1 deletion(-)
>>
>> diff --git a/drivers/iio/industrialio-buffer.c b/drivers/iio/industrialio-buffer.c
>> index b13f941..a671953 100644
>> --- a/drivers/iio/industrialio-buffer.c
>> +++ b/drivers/iio/industrialio-buffer.c
>> @@ -91,9 +91,16 @@ static bool iio_buffer_ready(struct iio_dev *indio_dev, struct iio_buffer *buf,
>>  
>>  /**
>>   * iio_buffer_read_first_n_outer() - chrdev read for buffer access
>> + * @filp:	File structure pointer for the char device
>> + * @buf:	Destination buffer for iio buffer read
>> + * @n:		First n bytes to read
>> + * @f_ps:	Long offset provided by the user as a seek position
>>   *
>>   * This function relies on all buffer implementations having an
>>   * iio_buffer as their first element.
>> + *
>> + * Return: negative values corresponding to error codes or ret != 0
>> + *	   for ending the reading activity

This may also return 0. Would it be wrong to state that if the return
value is not negative, then it will indicate the amount of data read?

>>   **/
>>  ssize_t iio_buffer_read_first_n_outer(struct file *filp, char __user *buf,
>>  				      size_t n, loff_t *f_ps)
>> @@ -143,6 +150,12 @@ ssize_t iio_buffer_read_first_n_outer(struct file *filp, char __user *buf,
>>  
>>  /**
>>   * iio_buffer_poll() - poll the buffer to find out if it has data
>> + * @filp:	File structure poiner for device access
> pointer
>> + * @wait:	Poll table structure pointer for which the driver adds
>> + *		a wait queue
>> + *
>> + * Return: (POLLIN | POLLRDNORM) if data is available for reading
>> + *	   or 0 for other cases

This can also return -ENODEV.

>>   */
>>  unsigned int iio_buffer_poll(struct file *filp,
>>  			     struct poll_table_struct *wait)
>> @@ -1136,7 +1149,7 @@ int iio_scan_mask_query(struct iio_dev *indio_dev,
>>  EXPORT_SYMBOL_GPL(iio_scan_mask_query);
>>  
>>  /**
>> - * struct iio_demux_table() - table describing demux memcpy ops
>> + * struct iio_demux_table - table describing demux memcpy ops
>>   * @from:	index to copy from
>>   * @to:		index to copy to
>>   * @length:	how many bytes to copy
>>
> 
> --
> To unsubscribe from this list: send the line "unsubscribe linux-iio" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

Re: [PATCH 4/6] iio: event: Add missing fields in kernel docs

[Hartmut Knaack]

Jonathan Cameron schrieb am 02.08.2015 um 19:33:
> On 24/07/15 14:21, Cristina Opriceana wrote:
>> Fix kernel docs warnings by adding the missing fields,
>> each with its associated description.
>>
>> Signed-off-by: Cristina Opriceana <cristina.opriceana@gmail.com>
> Applied.  Thanks
> 
> Jonathan
>> ---
>>  drivers/iio/industrialio-event.c | 6 ++++++
>>  1 file changed, 6 insertions(+)
>>
>> diff --git a/drivers/iio/industrialio-event.c b/drivers/iio/industrialio-event.c
>> index 894d813..b2f63f9 100644
>> --- a/drivers/iio/industrialio-event.c
>> +++ b/drivers/iio/industrialio-event.c
>> @@ -32,6 +32,7 @@
>>   * @dev_attr_list:	list of event interface sysfs attribute
>>   * @flags:		file operations related flags including busy flag.
>>   * @group:		event interface sysfs attribute group
>> + * @read_lock:		lock to protect kfifo read operations
>>   */
>>  struct iio_event_interface {
>>  	wait_queue_head_t	wait;
>> @@ -75,6 +76,11 @@ EXPORT_SYMBOL(iio_push_event);
>>  
>>  /**
>>   * iio_event_poll() - poll the event queue to find out if it has data
>> + * @filep:	File structure pointer to identify the device
>> + * @wait:	Poll table pointer to add the wait queue on
>> + *
>> + * Return: (POLLIN | POLLRDNORM) if data is available for reading
>> + *	   or a negative error code on failure

This can also return 0 if no data is available.

Actually, being unsigned int, the intended negative error code won't
appear - ouch! Any volunteers to address this issue?

>>   */
>>  static unsigned int iio_event_poll(struct file *filep,
>>  			     struct poll_table_struct *wait)
>>
> 
> --
> To unsubscribe from this list: send the line "unsubscribe linux-iio" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

Re: [PATCH 2/6] iio: buffer: Fix kernel docs warnings

[Hartmut Knaack]

Hartmut Knaack schrieb am 02.08.2015 um 21:32:
> Jonathan Cameron schrieb am 02.08.2015 um 19:27:
>> On 24/07/15 14:18, Cristina Opriceana wrote:
>>> Fix kernel docs for structures and functions in order to
>>> remove some warnings when the documentation gets generated.
>>>
>>> Signed-off-by: Cristina Opriceana <cristina.opriceana@gmail.com>
>> Applied with another typo fixed up.
> 
> Hi,
> I'm afraid there is some information missing.
> 
>>> ---
>>>  drivers/iio/industrialio-buffer.c | 15 ++++++++++++++-
>>>  1 file changed, 14 insertions(+), 1 deletion(-)
>>>
>>> diff --git a/drivers/iio/industrialio-buffer.c b/drivers/iio/industrialio-buffer.c
>>> index b13f941..a671953 100644
>>> --- a/drivers/iio/industrialio-buffer.c
>>> +++ b/drivers/iio/industrialio-buffer.c
>>> @@ -91,9 +91,16 @@ static bool iio_buffer_ready(struct iio_dev *indio_dev, struct iio_buffer *buf,
>>>  
>>>  /**
>>>   * iio_buffer_read_first_n_outer() - chrdev read for buffer access
>>> + * @filp:	File structure pointer for the char device
>>> + * @buf:	Destination buffer for iio buffer read
>>> + * @n:		First n bytes to read
>>> + * @f_ps:	Long offset provided by the user as a seek position
>>>   *
>>>   * This function relies on all buffer implementations having an
>>>   * iio_buffer as their first element.
>>> + *
>>> + * Return: negative values corresponding to error codes or ret != 0
>>> + *	   for ending the reading activity
> 
> This may also return 0. Would it be wrong to state that if the return
> value is not negative, then it will indicate the amount of data read?
> 
>>>   **/
>>>  ssize_t iio_buffer_read_first_n_outer(struct file *filp, char __user *buf,
>>>  				      size_t n, loff_t *f_ps)
>>> @@ -143,6 +150,12 @@ ssize_t iio_buffer_read_first_n_outer(struct file *filp, char __user *buf,
>>>  
>>>  /**
>>>   * iio_buffer_poll() - poll the buffer to find out if it has data
>>> + * @filp:	File structure poiner for device access
>> pointer
>>> + * @wait:	Poll table structure pointer for which the driver adds
>>> + *		a wait queue
>>> + *
>>> + * Return: (POLLIN | POLLRDNORM) if data is available for reading
>>> + *	   or 0 for other cases
> 
> This can also return -ENODEV.

On second thought however, it may return anything, given it is unsigned int.
Any volunteers?

> 
>>>   */
>>>  unsigned int iio_buffer_poll(struct file *filp,
>>>  			     struct poll_table_struct *wait)
>>> @@ -1136,7 +1149,7 @@ int iio_scan_mask_query(struct iio_dev *indio_dev,
>>>  EXPORT_SYMBOL_GPL(iio_scan_mask_query);
>>>  
>>>  /**
>>> - * struct iio_demux_table() - table describing demux memcpy ops
>>> + * struct iio_demux_table - table describing demux memcpy ops
>>>   * @from:	index to copy from
>>>   * @to:		index to copy to
>>>   * @length:	how many bytes to copy
>>>
>>
>> --
>> To unsubscribe from this list: send the line "unsubscribe linux-iio" in
>> the body of a message to majordomo@vger.kernel.org
>> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>>
> 
> --
> To unsubscribe from this list: send the line "unsubscribe linux-iio" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

Re: [PATCH 4/6] iio: event: Add missing fields in kernel docs

[Cristina Georgiana Opriceana]

On Sun, Aug 2, 2015 at 10:43 PM, Hartmut Knaack <knaack.h@gmx.de> wrote:
>
> Jonathan Cameron schrieb am 02.08.2015 um 19:33:
> > On 24/07/15 14:21, Cristina Opriceana wrote:
> >> Fix kernel docs warnings by adding the missing fields,
> >> each with its associated description.
> >>
> >> Signed-off-by: Cristina Opriceana <cristina.opriceana@gmail.com>
> > Applied.  Thanks
> >
> > Jonathan
> >> ---
> >>  drivers/iio/industrialio-event.c | 6 ++++++
> >>  1 file changed, 6 insertions(+)
> >>
> >> diff --git a/drivers/iio/industrialio-event.c b/drivers/iio/industrialio-event.c
> >> index 894d813..b2f63f9 100644
> >> --- a/drivers/iio/industrialio-event.c
> >> +++ b/drivers/iio/industrialio-event.c
> >> @@ -32,6 +32,7 @@
> >>   * @dev_attr_list:  list of event interface sysfs attribute
> >>   * @flags:          file operations related flags including busy flag.
> >>   * @group:          event interface sysfs attribute group
> >> + * @read_lock:              lock to protect kfifo read operations
> >>   */
> >>  struct iio_event_interface {
> >>      wait_queue_head_t       wait;
> >> @@ -75,6 +76,11 @@ EXPORT_SYMBOL(iio_push_event);
> >>
> >>  /**
> >>   * iio_event_poll() - poll the event queue to find out if it has data
> >> + * @filep:  File structure pointer to identify the device
> >> + * @wait:   Poll table pointer to add the wait queue on
> >> + *
> >> + * Return: (POLLIN | POLLRDNORM) if data is available for reading
> >> + *     or a negative error code on failure
>
> This can also return 0 if no data is available.
>
> Actually, being unsigned int, the intended negative error code won't
> appear - ouch! Any volunteers to address this issue?

Ah, sorry. Missed that. I'll fix it.

Cristina

> >>   */
> >>  static unsigned int iio_event_poll(struct file *filep,
> >>                           struct poll_table_struct *wait)
> >>
> >
> > --
> > To unsubscribe from this list: send the line "unsubscribe linux-iio" in
> > the body of a message to majordomo@vger.kernel.org
> > More majordomo info at  http://vger.kernel.org/majordomo-info.html
> >
>

Re: [PATCH 4/6] iio: event: Add missing fields in kernel docs

[Lars-Peter Clausen]

On 08/02/2015 09:43 PM, Hartmut Knaack wrote:
> Jonathan Cameron schrieb am 02.08.2015 um 19:33:
>> On 24/07/15 14:21, Cristina Opriceana wrote:
>>> Fix kernel docs warnings by adding the missing fields,
>>> each with its associated description.
>>>
>>> Signed-off-by: Cristina Opriceana <cristina.opriceana@gmail.com>
>> Applied.  Thanks
>>
>> Jonathan
>>> ---
>>>  drivers/iio/industrialio-event.c | 6 ++++++
>>>  1 file changed, 6 insertions(+)
>>>
>>> diff --git a/drivers/iio/industrialio-event.c b/drivers/iio/industrialio-event.c
>>> index 894d813..b2f63f9 100644
>>> --- a/drivers/iio/industrialio-event.c
>>> +++ b/drivers/iio/industrialio-event.c
>>> @@ -32,6 +32,7 @@
>>>   * @dev_attr_list:	list of event interface sysfs attribute
>>>   * @flags:		file operations related flags including busy flag.
>>>   * @group:		event interface sysfs attribute group
>>> + * @read_lock:		lock to protect kfifo read operations
>>>   */
>>>  struct iio_event_interface {
>>>  	wait_queue_head_t	wait;
>>> @@ -75,6 +76,11 @@ EXPORT_SYMBOL(iio_push_event);
>>>  
>>>  /**
>>>   * iio_event_poll() - poll the event queue to find out if it has data
>>> + * @filep:	File structure pointer to identify the device
>>> + * @wait:	Poll table pointer to add the wait queue on
>>> + *
>>> + * Return: (POLLIN | POLLRDNORM) if data is available for reading
>>> + *	   or a negative error code on failure
> 
> This can also return 0 if no data is available.
> 
> Actually, being unsigned int, the intended negative error code won't
> appear - ouch! Any volunteers to address this issue?

Sorry, my fault. It looks like the poll() callback can't return a error. So
if no device is bound we should just return 0.

- Lars

Re: [PATCH 2/6] iio: buffer: Fix kernel docs warnings

[Cristina Georgiana Opriceana]

On Sun, Aug 2, 2015 at 10:46 PM, Hartmut Knaack <knaack.h@gmx.de> wrote:
> Hartmut Knaack schrieb am 02.08.2015 um 21:32:
>> Jonathan Cameron schrieb am 02.08.2015 um 19:27:
>>> On 24/07/15 14:18, Cristina Opriceana wrote:
>>>> Fix kernel docs for structures and functions in order to
>>>> remove some warnings when the documentation gets generated.
>>>>
>>>> Signed-off-by: Cristina Opriceana <cristina.opriceana@gmail.com>
>>> Applied with another typo fixed up.
>>
>> Hi,
>> I'm afraid there is some information missing.
>>
>>>> ---
>>>>  drivers/iio/industrialio-buffer.c | 15 ++++++++++++++-
>>>>  1 file changed, 14 insertions(+), 1 deletion(-)
>>>>
>>>> diff --git a/drivers/iio/industrialio-buffer.c b/drivers/iio/industrialio-buffer.c
>>>> index b13f941..a671953 100644
>>>> --- a/drivers/iio/industrialio-buffer.c
>>>> +++ b/drivers/iio/industrialio-buffer.c
>>>> @@ -91,9 +91,16 @@ static bool iio_buffer_ready(struct iio_dev *indio_dev, struct iio_buffer *buf,
>>>>
>>>>  /**
>>>>   * iio_buffer_read_first_n_outer() - chrdev read for buffer access
>>>> + * @filp:  File structure pointer for the char device
>>>> + * @buf:   Destination buffer for iio buffer read
>>>> + * @n:             First n bytes to read
>>>> + * @f_ps:  Long offset provided by the user as a seek position
>>>>   *
>>>>   * This function relies on all buffer implementations having an
>>>>   * iio_buffer as their first element.
>>>> + *
>>>> + * Return: negative values corresponding to error codes or ret != 0
>>>> + *    for ending the reading activity
>>
>> This may also return 0. Would it be wrong to state that if the return
>> value is not negative, then it will indicate the amount of data read?
>>
>>>>   **/
>>>>  ssize_t iio_buffer_read_first_n_outer(struct file *filp, char __user *buf,
>>>>                                   size_t n, loff_t *f_ps)
>>>> @@ -143,6 +150,12 @@ ssize_t iio_buffer_read_first_n_outer(struct file *filp, char __user *buf,
>>>>
>>>>  /**
>>>>   * iio_buffer_poll() - poll the buffer to find out if it has data
>>>> + * @filp:  File structure poiner for device access
>>> pointer
>>>> + * @wait:  Poll table structure pointer for which the driver adds
>>>> + *         a wait queue
>>>> + *
>>>> + * Return: (POLLIN | POLLRDNORM) if data is available for reading
>>>> + *    or 0 for other cases
>>
>> This can also return -ENODEV.
>
> On second thought however, it may return anything, given it is unsigned int.
> Any volunteers?
>
I sent a patch changing the return value in case that no device is bound

Cristina
>>
>>>>   */
>>>>  unsigned int iio_buffer_poll(struct file *filp,
>>>>                          struct poll_table_struct *wait)
>>>> @@ -1136,7 +1149,7 @@ int iio_scan_mask_query(struct iio_dev *indio_dev,
>>>>  EXPORT_SYMBOL_GPL(iio_scan_mask_query);
>>>>
>>>>  /**
>>>> - * struct iio_demux_table() - table describing demux memcpy ops
>>>> + * struct iio_demux_table - table describing demux memcpy ops
>>>>   * @from:  index to copy from
>>>>   * @to:            index to copy to
>>>>   * @length:        how many bytes to copy
>>>>
>>>
>>> --
>>> To unsubscribe from this list: send the line "unsubscribe linux-iio" in
>>> the body of a message to majordomo@vger.kernel.org
>>> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>>>
>>
>> --
>> To unsubscribe from this list: send the line "unsubscribe linux-iio" in
>> the body of a message to majordomo@vger.kernel.org
>> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>>
>

Re: [PATCH 3/6] iio: trigger: Add missing fields in kernel docs

[Cristina Georgiana Opriceana]

On Sun, Aug 2, 2015 at 8:32 PM, Jonathan Cameron <jic23@kernel.org> wrote:
>
> On 24/07/15 14:20, Cristina Opriceana wrote:
> > Fix kernel docs warnings by adding the missing description
> > for each of the existing function parameters.
> >
> > Signed-off-by: Cristina Opriceana <cristina.opriceana@gmail.com>
> A few comments inline.
> > ---
> >  drivers/iio/industrialio-trigger.c | 27 ++++++++++++++++++++++++---
> >  1 file changed, 24 insertions(+), 3 deletions(-)
> >
> > diff --git a/drivers/iio/industrialio-trigger.c b/drivers/iio/industrialio-trigger.c
> > index d31098e..cae2939 100644
> > --- a/drivers/iio/industrialio-trigger.c
> > +++ b/drivers/iio/industrialio-trigger.c
> > @@ -40,7 +40,14 @@ static DEFINE_MUTEX(iio_trigger_list_lock);
> >
> >  /**
> >   * iio_trigger_read_name() - retrieve useful identifying name
> > - **/
> > + * @dev:     device that holds the iio_trigger
> The dev structure is within the struct iio_trigger rather than the other
> way around. It is there to give it it a presence in the device model.
> I'd keep this statement vague and say perhaps,
> device associated with the iio_trigger.

Right. It was a little over-formulated. I sent a v2.

> > + * @attr:    pointer to the device_attribute structure that is
> > + *           being processed
> > + * @buf:     buffer to print the name into
> > + *
> > + * Return: a negative number on failure or the number of written
> > + *      characters on success.
> > + */
> >  static ssize_t iio_trigger_read_name(struct device *dev,
> >                                    struct device_attribute *attr,
> >                                    char *buf)
> > @@ -288,10 +295,17 @@ EXPORT_SYMBOL_GPL(iio_dealloc_pollfunc);
> >
> >  /**
> >   * iio_trigger_read_current() - trigger consumer sysfs query current trigger
> > + * @dev:     Device this iio_dev belongs to
> Again, this implies a tighter relationship than is actually true.
> The dev isn't the underlying device (e.g. the spi one or i2c one
> but rather one created by the iio subsystem to give the iio_dev a
> presence in the device model - on the iio sysfs bus).
> > + * @attr:    Pointer to the device_attribute structure that
> > + *           is being processed
> > + * @buf:     Buffer where the current trigger name will be printed into
> >   *
> >   * For trigger consumers the current_trigger interface allows the trigger
> >   * used by the device to be queried.
> > - **/
> > + *
> > + * Return: a negative number on failure, the number of characters written
> > + *      on success or 0 if no trigger is available
> > + */
> >  static ssize_t iio_trigger_read_current(struct device *dev,
> >                                       struct device_attribute *attr,
> >                                       char *buf)
> > @@ -305,11 +319,18 @@ static ssize_t iio_trigger_read_current(struct device *dev,
> >
> >  /**
> >   * iio_trigger_write_current() - trigger consumer sysfs set current trigger
> > + * @dev:     Device that this iio_dev belongs to
> > + * @attr:    Device attribute that is being processed
> > + * @buf:     String buffer that holds the name of the trigger
> > + * @len:     Length of the trigger name held by buf
> >   *
> >   * For trigger consumers the current_trigger interface allows the trigger
> >   * used for this device to be specified at run time based on the trigger's
> >   * name.
> > - **/
> > + *
> > + * Return: negative error code on failure or length of the buffer
> > + *      on success
> > + */
> >  static ssize_t iio_trigger_write_current(struct device *dev,
> >                                        struct device_attribute *attr,
> >                                        const char *buf,
> >
>