Staging: iio: lots of doc fixes
authorRandy Dunlap <randy.dunlap@oracle.com>
Mon, 5 Oct 2009 02:34:02 +0000 (19:34 -0700)
committerGreg Kroah-Hartman <gregkh@suse.de>
Fri, 11 Dec 2009 20:23:05 +0000 (12:23 -0800)
Fix iio header files kernel-doc notation errors, spelling, typos,
indentation, grammar, etc.

It would also be good if these function names were spelled
correctly, but I didn't change them:
  iio_push_or_escallate_ring_event()
  iio_trigger_dettach_poll_func()

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Acked-by: Jonathan Cameron <jic23@cam.ac.uk>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
drivers/staging/iio/chrdev.h
drivers/staging/iio/iio.h
drivers/staging/iio/ring_generic.h
drivers/staging/iio/ring_sw.h
drivers/staging/iio/sysfs.h
drivers/staging/iio/trigger.h
drivers/staging/iio/trigger_consumer.h

index 8bc64bf0845901c31e2687b5e9403dadb87b3139..f42bafb3a894baa859d6a8076115b3ca6039c92a 100644 (file)
@@ -75,10 +75,12 @@ struct iio_shared_ev_pointer {
  * @current_events:    number of events in detected list
  * @id:                        indentifier to allow the event interface to know which
  *                     physical line it corresponds to
+ * @attr:              this chrdev's minor number sysfs attribute
  * @owner:             ensure the driver module owns the file, not iio
  * @private:           driver specific data
  * @_name:             used internally to store the sysfs name for minor id
  *                     attribute
+ * @_attrname:         the event interface's attribute name
  */
 struct iio_event_interface {
        struct device                           dev;
@@ -105,7 +107,7 @@ struct iio_event_interface {
  * @handler:           event handler function - called on event if this
  *                     event_handler is enabled.
  *
- * Each device has one list of these per interrupt line
+ * Each device has one list of these per interrupt line.
  **/
 struct iio_event_handler_list {
        struct list_head        list;
index 25ccb809221e0e2e02339ac3d8db8d50ae06dfb6..71dbfe12b5792929ebf661d5e232ab8a24f72ac6 100644 (file)
@@ -166,7 +166,7 @@ static inline int iio_scan_mask_clear(struct iio_dev *dev_info, int bit)
  * @bit: which number scan element is this
  **/
 static inline int iio_scan_mask_count_to_right(struct iio_dev *dev_info,
-int bit)
+                                               int bit)
 {
        int count = 0;
        int mask = (1 << bit);
@@ -239,7 +239,7 @@ void iio_unregister_interrupt_line(struct iio_dev *dev_info,
  * @dev_info:          IIO device structure
  * @ev_line:           Which event line (hardware interrupt)
  * @ev_code:           What event
- * @timestamp:         When the event occured
+ * @timestamp:         When the event occurred
  **/
 int iio_push_event(struct iio_dev *dev_info,
                  int ev_line,
@@ -248,11 +248,11 @@ int iio_push_event(struct iio_dev *dev_info,
 
 /**
  * struct iio_work_cont - container for when singleton handler case matters
- * @ws:                        [DEVICE]work_struct when not only possible event
- * @ws_nocheck:                [DEVICE]work_struct when only possible event
- * @address:           [DEVICE]associated register address
- * @mask:              [DEVICE]associated mask for identifying event source
- * @st:                        [DEVICE]device specific state information
+ * @ws:                        [DEVICE] work_struct when not only possible event
+ * @ws_nocheck:                [DEVICE] work_struct when only possible event
+ * @address:           [DEVICE] associated register address
+ * @mask:              [DEVICE] associated mask for identifying event source
+ * @st:                        [DEVICE] device specific state information
  **/
 struct iio_work_cont {
        struct work_struct      ws;
@@ -273,9 +273,9 @@ struct iio_work_cont {
  * @cont: the work container
  * @_checkfunc: function called when there are multiple possible int sources
  * @_nocheckfunc: function for when there is only one int source
- * @_add: driver dependant, typically a register address
- * @_mask: driver dependant, typically a bit mask for a register
- * @_st: driver dependant, typically pointer to a device state structure
+ * @_add: driver dependent, typically a register address
+ * @_mask: driver dependent, typically a bit mask for a register
+ * @_st: driver dependent, typically pointer to a device state structure
  **/
 static inline void
 iio_init_work_cont(struct iio_work_cont *cont,
@@ -290,7 +290,7 @@ iio_init_work_cont(struct iio_work_cont *cont,
        cont->st = _st;
 }
 /**
- * __iio_push_event() tries to add an event to the list associated with a chrdev
+ * __iio_push_event() tries to add an event to the list associated with a chrdev
  * @ev_int:            the event interface to which we are pushing the event
  * @ev_code:           the outgoing event code
  * @timestamp:         timestamp of the event
@@ -302,8 +302,8 @@ int __iio_push_event(struct iio_event_interface *ev_int,
                    struct iio_shared_ev_pointer*
                    shared_pointer_p);
 /**
- * __iio_change_event() change an event code in case of event escallation
- * @ev:                        the evnet to be changed
+ * __iio_change_event() - change an event code in case of event escalation
+ * @ev:                        the event to be changed
  * @ev_code:           new event code
  * @timestamp:         new timestamp
  **/
@@ -312,7 +312,7 @@ void __iio_change_event(struct iio_detected_event_list *ev,
                        s64 timestamp);
 
 /**
- * iio_setup_ev_int() Configure an event interface (chrdev)
+ * iio_setup_ev_int() - configure an event interface (chrdev)
  * @name:              name used for resulting sysfs directory etc.
  * @ev_int:            interface we are configuring
  * @owner:             module that is responsible for registering this ev_int
@@ -343,7 +343,7 @@ extern dev_t iio_devt;
 extern struct class iio_class;
 
 /**
- * iio_put_device() - reference counted deallocated of struct device
+ * iio_put_device() - reference counted deallocation of struct device
  * @dev: the iio_device containing the device
  **/
 static inline void iio_put_device(struct iio_dev *dev)
@@ -353,7 +353,7 @@ static inline void iio_put_device(struct iio_dev *dev)
 };
 
 /**
- * to_iio_dev() - get iio_dev for which we have have the struct device
+ * to_iio_dev() - get iio_dev for which we have the struct device
  * @d: the struct device
  **/
 static inline struct iio_dev *to_iio_dev(struct device *d)
@@ -377,6 +377,7 @@ struct iio_dev *iio_allocate_device(void);
 
 /**
  * iio_free_device() - free an iio_dev from a driver
+ * @dev: the iio_dev associated with the device
  **/
 void iio_free_device(struct iio_dev *dev);
 
@@ -395,7 +396,8 @@ int iio_device_get_chrdev_minor(void);
 void iio_device_free_chrdev_minor(int val);
 
 /**
- * iio_ring_enabled() helper function to test if any form of ring enabled
+ * iio_ring_enabled() - helper function to test if any form of ring is enabled
+ * @dev_info:          IIO device info structure for device
  **/
 static inline bool iio_ring_enabled(struct iio_dev *dev_info)
 {
index d9261897f3324df46bd51af049607f7e33eb1661..93b91b28a02f478ef4fc11b026c4cb36d357a15e 100644 (file)
@@ -25,9 +25,12 @@ int iio_push_ring_event(struct iio_ring_buffer *ring_buf,
                        int event_code,
                        s64 timestamp);
 /**
- * iio_push_or_escallate_ring_event() -        escallate or add as appropriate
+ * iio_push_or_escallate_ring_event() -        escalate or add as appropriate
+ * @ring_buf:          ring buffer that is the event source
+ * @event_code:                event indentification code
+ * @timestamp:         time of event
  *
- * Typical usecase is to escallate a 50% ring full to 75% full if noone has yet
+ * Typical usecase is to escalate a 50% ring full to 75% full if noone has yet
  * read the first event. Clearly the 50% full is no longer of interest in
  * typical use case.
  **/
@@ -37,10 +40,6 @@ int iio_push_or_escallate_ring_event(struct iio_ring_buffer *ring_buf,
 
 /**
  * struct iio_ring_access_funcs - access functions for ring buffers.
- * @create:            perform allocation
- * @init:              get ring buffer ready for use
- * @_exit:             reverse steps in init
- * @_free:             deallocate ring buffer
  * @mark_in_use:       reference counting, typically to prevent module removal
  * @unmark_in_use:     reduce reference count when no longer using ring buffer
  * @store_to:          actually store stuff to the ring buffer
@@ -60,7 +59,7 @@ int iio_push_or_escallate_ring_event(struct iio_ring_buffer *ring_buf,
  *
  * The purpose of this structure is to make the ring buffer element
  * modular as event for a given driver, different usecases may require
- * different ring designs (space efficiency vs speed for example.
+ * different ring designs (space efficiency vs speed for example).
  *
  * It is worth noting that a given ring implementation may only support a small
  * proportion of these functions.  The core code 'should' cope fine with any of
@@ -91,23 +90,25 @@ struct iio_ring_access_funcs {
 
 /**
  * struct iio_ring_buffer - general ring buffer structure
- * @length:            [DEVICE]number of datums in ring
- * @bpd:               [DEVICE]size of individual datum including timestamp
- * @loopcount:         [INTERN]number of times the ring has looped
- * @access_minor_name: [INTERN]store of name of the access chrdev minor number
- *                     sysfs attribute
- * @access_handler:    [INTERN]chrdev access handling
- * @event_minor_name:  [INTERN]store of name of the event chrdev minor number
- *                     sysfs attribute
- * @ev_int:            [INTERN]chrdev interface for the event chrdev
- * @shared_ev_pointer: [INTERN]the shared event pointer to allow escalation of
+ * @dev:               ring buffer device struct
+ * @access_dev:                system device struct for the chrdev
+ * @indio_dev:         industrial I/O device structure
+ * @owner:             module that owns the ring buffer (for ref counting)
+ * @id:                        unique id number
+ * @access_id:         device id number
+ * @length:            [DEVICE] number of datums in ring
+ * @bpd:               [DEVICE] size of individual datum including timestamp
+ * @loopcount:         [INTERN] number of times the ring has looped
+ * @access_handler:    [INTERN] chrdev access handling
+ * @ev_int:            [INTERN] chrdev interface for the event chrdev
+ * @shared_ev_pointer: [INTERN] the shared event pointer to allow escalation of
  *                     events
- * @ring_access:       [DRIVER]ring access functions associated with the
+ * @access:            [DRIVER] ring access functions associated with the
  *                     implementation.
- * @ring_prenable:     [DRIVER] function to run prior to marking ring enabled
- * @ring_postenable:   [DRIVER] function to run after marking ring enabled
- * @ring_predisable:   [DRIVER] function to run prior to marking ring disabled
- * @ring_postdisable:  [DRIVER] function to run after marking ring disabled
+ * @preenable:         [DRIVER] function to run prior to marking ring enabled
+ * @postenable:                [DRIVER] function to run after marking ring enabled
+ * @predisable:                [DRIVER] function to run prior to marking ring disabled
+ * @postdisable:       [DRIVER] function to run after marking ring disabled
   **/
 struct iio_ring_buffer {
        struct device dev;
@@ -133,7 +134,10 @@ void iio_ring_buffer_init(struct iio_ring_buffer *ring,
                          struct iio_dev *dev_info);
 
 /**
- * __iio_init_ring_buffer() - initialize common elements of ring buffers.
+ * __iio_init_ring_buffer() - initialize common elements of ring buffers
+ * @ring:              ring buffer that is the event source
+ * @bytes_per_datum:   size of individual datum including timestamp
+ * @length:            number of datums in ring
  **/
 static inline void __iio_init_ring_buffer(struct iio_ring_buffer *ring,
                                 int bytes_per_datum, int length)
@@ -171,7 +175,11 @@ struct iio_scan_el {
        container_of(_dev_attr, struct iio_scan_el, dev_attr);
 
 /**
- * iio_scan_el_store() - sysfs scan element selection interface.
+ * iio_scan_el_store() - sysfs scan element selection interface
+ * @dev: the target device
+ * @attr: the device attribute that is being processed
+ * @buf: input from userspace
+ * @len: length of input
  *
  * A generic function used to enable various scan elements.  In some
  * devices explicit read commands for each channel mean this is merely
@@ -184,12 +192,15 @@ ssize_t iio_scan_el_store(struct device *dev, struct device_attribute *attr,
                          const char *buf, size_t len);
 /**
  * iio_scal_el_show() -        sysfs interface to query whether a scan element is
- *                     is enabled or not.
+ *                     is enabled or not
+ * @dev: the target device
+ * @attr: the device attribute that is being processed
+ * @buf: output buffer
  **/
 ssize_t iio_scan_el_show(struct device *dev, struct device_attribute *attr,
                         char *buf);
 /**
- * IIO_SCAN_EL: - declare and initialize a scan element without control func
+ * IIO_SCAN_EL - declare and initialize a scan element without control func
  * @_name:     identifying name. Resulting struct is iio_scan_el_##_name,
  *             sysfs element, scan_en_##_name.
  * @_number:   unique id number for the scan element.
@@ -214,8 +225,14 @@ ssize_t iio_scan_el_ts_store(struct device *dev, struct device_attribute *attr,
 ssize_t iio_scan_el_ts_show(struct device *dev, struct device_attribute *attr,
                            char *buf);
 /**
- * IIO_SCAN_EL_C: - declare and initialize a scan element with a control func
+ * IIO_SCAN_EL_C - declare and initialize a scan element with a control func
  *
+ * @_name:     identifying name. Resulting struct is iio_scan_el_##_name,
+ *             sysfs element, scan_en_##_name.
+ * @_number:   unique id number for the scan element.
+ * @_bits:     number of bits in the scan element result (used in mixed bit
+ *             length devices).
+ * @_label:    indentification variable used by drivers.  Often a reg address.
  * @_controlfunc: function used to notify hardware of whether state changes
  **/
 #define IIO_SCAN_EL_C(_name, _number, _bits, _label, _controlfunc)     \
@@ -230,7 +247,7 @@ ssize_t iio_scan_el_ts_show(struct device *dev, struct device_attribute *attr,
                .set_state = _controlfunc,                              \
        }
 /**
- * IIO_SCAN_EL_TIMESTAMP: - declare a special scan element for timestamps
+ * IIO_SCAN_EL_TIMESTAMP - declare a special scan element for timestamps
  *
  * Odd one out. Handled slightly differently from other scan elements.
  **/
index ae70ee0538fb3f0cf8956b447e973a13942ff198..f0b86f02cd808afc287db224cc1f1f21b9cabe1f 100644 (file)
 #if defined CONFIG_IIO_SW_RING || defined CONFIG_IIO_SW_RING_MODULE
 
 /**
- * iio_create_sw_rb() software ring buffer allocation
+ * iio_create_sw_rb() software ring buffer allocation
  * @r:         pointer to ring buffer pointer
  **/
 int iio_create_sw_rb(struct iio_ring_buffer **r);
 
 /**
- * iio_init_sw_rb() initialize the software ring buffer
+ * iio_init_sw_rb() initialize the software ring buffer
  * @r:         pointer to a software ring buffer created by an
- *             iio_create_sw_rb call.
+ *             iio_create_sw_rb call
+ * @indio_dev:         industrial I/O device structure
  **/
 int iio_init_sw_rb(struct iio_ring_buffer *r, struct iio_dev *indio_dev);
+
 /**
- * iio_exit_sw_rb() reverse what was done in iio_init_sw_rb
+ * iio_exit_sw_rb() - reverse what was done in iio_init_sw_rb
+ * @r:         pointer to a software ring buffer created by an
+ *             iio_create_sw_rb call
  **/
 void iio_exit_sw_rb(struct iio_ring_buffer *r);
 
 /**
- * iio_free_sw_rb() free memory occupied by the core ring buffer struct
+ * iio_free_sw_rb() - free memory occupied by the core ring buffer struct
+ * @r:         pointer to a software ring buffer created by an
+ *             iio_create_sw_rb call
  **/
 void iio_free_sw_rb(struct iio_ring_buffer *r);
 
 /**
- * iio_mark_sw_rb_in_use() reference counting to prevent incorrect chances
+ * iio_mark_sw_rb_in_use() - reference counting to prevent incorrect chances
+ * @r:         pointer to a software ring buffer created by an
+ *             iio_create_sw_rb call
  **/
 void iio_mark_sw_rb_in_use(struct iio_ring_buffer *r);
 
 /**
- *  iio_unmark_sw_rb_in_use() notify the ring buffer that we don't care anymore
+ *  iio_unmark_sw_rb_in_use() - notify the ring buffer that we don't care anymore
+ * @r:         pointer to a software ring buffer created by an
+ *             iio_create_sw_rb call
  **/
 void iio_unmark_sw_rb_in_use(struct iio_ring_buffer *r);
 
 /**
- * iio_read_last_from_sw_rb() attempt to read the last stored datum from the rb
+ * iio_read_last_from_sw_rb() - attempt to read the last stored datum from the rb
+ * @r:         pointer to a software ring buffer created by an
+ *             iio_create_sw_rb call
+ * @data:      where to store the last datum
  **/
 int iio_read_last_from_sw_rb(struct iio_ring_buffer *r, u8 *data);
 
 /**
- * iio_store_to_sw_rb() store a new datum to the ring buffer
- * @rb:        pointer to ring buffer instance
- * @data:      the datum to be stored including timestamp if relevant.
- * @timestamp: timestamp which will be attached to buffer events if relevant.
+ * iio_store_to_sw_rb() store a new datum to the ring buffer
+ * @r        pointer to ring buffer instance
+ * @data:      the datum to be stored including timestamp if relevant
+ * @timestamp: timestamp which will be attached to buffer events if relevant
  **/
 int iio_store_to_sw_rb(struct iio_ring_buffer *r, u8 *data, s64 timestamp);
 
 /**
- * iio_rip_sw_rb() attempt to read data from the ring buffer
+ * iio_rip_sw_rb() attempt to read data from the ring buffer
  * @r:                 ring buffer instance
  * @count:             number of datum's to try and read
  * @data:              where the data will be stored.
@@ -94,38 +107,53 @@ int iio_rip_sw_rb(struct iio_ring_buffer *r,
                  int *dead_offset);
 
 /**
- * iio_request_update_sw_rb() update params if update needed
+ * iio_request_update_sw_rb() - update params if update needed
+ * @r:         pointer to a software ring buffer created by an
+ *             iio_create_sw_rb call
  **/
 int iio_request_update_sw_rb(struct iio_ring_buffer *r);
 
 /**
- * iio_mark_update_needed_sw_rb() tell the ring buffer it needs a param update
+ * iio_mark_update_needed_sw_rb() - tell the ring buffer it needs a param update
+ * @r:         pointer to a software ring buffer created by an
+ *             iio_create_sw_rb call
  **/
 int iio_mark_update_needed_sw_rb(struct iio_ring_buffer *r);
 
 
 /**
- * iio_get_bpd_sw_rb() get the datum size in bytes
+ * iio_get_bpd_sw_rb() - get the datum size in bytes
+ * @r:         pointer to a software ring buffer created by an
+ *             iio_create_sw_rb call
  **/
 int iio_get_bpd_sw_rb(struct iio_ring_buffer *r);
 
 /**
- * iio_set_bpd_sw_rb() set the datum size in bytes
+ * iio_set_bpd_sw_rb() - set the datum size in bytes
+ * @r:         pointer to a software ring buffer created by an
+ *             iio_create_sw_rb call
+ * @bpd:       bytes per datum value
  **/
 int iio_set_bpd_sw_rb(struct iio_ring_buffer *r, size_t bpd);
 
 /**
- * iio_get_length_sw_rb() get how many datums the rb may contain
+ * iio_get_length_sw_rb() - get how many datums the rb may contain
+ * @r:         pointer to a software ring buffer created by an
+ *             iio_create_sw_rb call
  **/
 int iio_get_length_sw_rb(struct iio_ring_buffer *r);
 
 /**
- * iio_set_length_sw_rb() set how many datums the rb may contain
+ * iio_set_length_sw_rb() - set how many datums the rb may contain
+ * @r:         pointer to a software ring buffer created by an
+ *             iio_create_sw_rb call
+ * @length:    max number of data items for the ring buffer
  **/
 int iio_set_length_sw_rb(struct iio_ring_buffer *r, int length);
 
 /**
- * iio_ring_sw_register_funcs() helper function to set up rb access
+ * iio_ring_sw_register_funcs() - helper function to set up rb access
+ * @ra:                pointer to @iio_ring_access_funcs
  **/
 static inline void iio_ring_sw_register_funcs(struct iio_ring_access_funcs *ra)
 {
index bfe4055c0ed2a6d256e772156cb31e42c221b32b..e501e1338e11bb3491af13b2845fd6cd8fdb073d 100644 (file)
@@ -15,7 +15,7 @@
 #include "iio.h"
 
 /**
- * struct iio_event_attribute - event control attribute
+ * struct iio_event_attr - event control attribute
  * @dev_attr:  underlying device attribute
  * @mask:      mask for the event when detecting
  * @listel:    list header to allow addition to list of event handlers
@@ -54,6 +54,7 @@ __init_iio_chrdev_minor_attr(struct iio_chrdev_minor_attr *minor_attr,
  * struct iio_dev_attr - iio specific device attribute
  * @dev_attr:  underlying device attribute
  * @address:   associated register address
+ * @val2:      secondary attribute value
  */
 struct iio_dev_attr {
        struct device_attribute dev_attr;
@@ -71,6 +72,8 @@ ssize_t iio_read_const_attr(struct device *dev,
 /**
  * struct iio_const_attr - constant device specific attribute
  *                         often used for things like available modes
+ * @string:    attribute string
+ * @dev_attr:  underlying device attribute
  */
 struct iio_const_attr {
        const char *string;
@@ -80,7 +83,7 @@ struct iio_const_attr {
 #define to_iio_const_attr(_dev_attr) \
        container_of(_dev_attr, struct iio_const_attr, dev_attr)
 
-/* Some attributes will be hard coded (device dependant) and not require an
+/* Some attributes will be hard coded (device dependent) and not require an
    address, in these cases pass a negative */
 #define IIO_ATTR(_name, _mode, _show, _store, _addr)           \
        { .dev_attr = __ATTR(_name, _mode, _show, _store),      \
@@ -108,102 +111,130 @@ struct iio_const_attr {
 /* Generic attributes of onetype or another */
 
 /**
- * IIO_DEV_ATTR_REG: revision number for the device
+ * IIO_DEV_ATTR_REV - revision number for the device
+ * @_show: output method for the attribute
  *
  * Very much device dependent.
  **/
 #define IIO_DEV_ATTR_REV(_show)                        \
        IIO_DEVICE_ATTR(revision, S_IRUGO, _show, NULL, 0)
+
 /**
- * IIO_DEV_ATTR_NAME: chip type dependant identifier
+ * IIO_DEV_ATTR_NAME - chip type dependent identifier
+ * @_show: output method for the attribute
  **/
 #define IIO_DEV_ATTR_NAME(_show)                               \
        IIO_DEVICE_ATTR(name, S_IRUGO, _show, NULL, 0)
 
 /**
- * IIO_DEV_ATTR_SAMP_FREQ: sets any internal clock frequency
+ * IIO_DEV_ATTR_SAMP_FREQ - sets any internal clock frequency
+ * @_mode: sysfs file mode/permissions
+ * @_show: output method for the attribute
+ * @_store: input method for the attribute
  **/
 #define IIO_DEV_ATTR_SAMP_FREQ(_mode, _show, _store)                   \
        IIO_DEVICE_ATTR(sampling_frequency, _mode, _show, _store, 0)
 
 /**
- * IIO_DEV_ATTR_AVAIL_SAMP_FREQ: list available sampling frequencies.
+ * IIO_DEV_ATTR_AVAIL_SAMP_FREQ - list available sampling frequencies
+ * @_show: output method for the attribute
  *
- * May be mode dependant on some devices
+ * May be mode dependent on some devices
  **/
 #define IIO_DEV_ATTR_AVAIL_SAMP_FREQ(_show)                            \
        IIO_DEVICE_ATTR(available_sampling_frequency, S_IRUGO, _show, NULL, 0)
 
 /**
- * IIO_DEV_ATTR_CONST_AVAIL_SAMP_FREQ: list available sampling frequencies.
+ * IIO_CONST_ATTR_AVAIL_SAMP_FREQ - list available sampling frequencies
+ * @_string: frequency string for the attribute
  *
  * Constant version
  **/
 #define IIO_CONST_ATTR_AVAIL_SAMP_FREQ(_string)        \
        IIO_CONST_ATTR(available_sampling_frequency, _string)
+
 /**
- * IIO_DEV_ATTR_SCAN_MODE: select a scan mode
+ * IIO_DEV_ATTR_SCAN_MODE - select a scan mode
+ * @_mode: sysfs file mode/permissions
+ * @_show: output method for the attribute
+ * @_store: input method for the attribute
  *
  * This is used when only certain combinations of inputs may be read in one
  * scan.
  **/
 #define IIO_DEV_ATTR_SCAN_MODE(_mode, _show, _store)           \
        IIO_DEVICE_ATTR(scan_mode, _mode, _show, _store, 0)
+
 /**
- * IIO_DEV_ATTR_AVAIL_SCAN_MODES: list available scan modes
+ * IIO_DEV_ATTR_AVAIL_SCAN_MODES - list available scan modes
+ * @_show: output method for the attribute
  **/
 #define IIO_DEV_ATTR_AVAIL_SCAN_MODES(_show)                           \
        IIO_DEVICE_ATTR(available_scan_modes, S_IRUGO, _show, NULL, 0)
 
 /**
- * IIO_DEV_ATTR_SCAN: result of scan of multiple channels
+ * IIO_DEV_ATTR_SCAN - result of scan of multiple channels
+ * @_show: output method for the attribute
  **/
 #define IIO_DEV_ATTR_SCAN(_show)               \
        IIO_DEVICE_ATTR(scan, S_IRUGO, _show, NULL, 0);
 
 /**
- * IIO_DEV_ATTR_INPUT: direct read of a single input channel
+ * IIO_DEV_ATTR_INPUT - direct read of a single input channel
+ * @_number: input channel number
+ * @_show: output method for the attribute
  **/
 #define IIO_DEV_ATTR_INPUT(_number, _show)                             \
        IIO_DEVICE_ATTR(in##_number, S_IRUGO, _show, NULL, _number)
 
-
 /**
- * IIO_DEV_ATTR_SW_RING_ENABLE: enable software ring buffer
+ * IIO_DEV_ATTR_SW_RING_ENABLE - enable software ring buffer
+ * @_show: output method for the attribute
+ * @_store: input method for the attribute
  *
- * Success may be dependant on attachment of trigger previously
+ * Success may be dependent on attachment of trigger previously.
  **/
 #define IIO_DEV_ATTR_SW_RING_ENABLE(_show, _store)                     \
        IIO_DEVICE_ATTR(sw_ring_enable, S_IRUGO | S_IWUSR, _show, _store, 0)
 
 /**
- * IIO_DEV_ATTR_HW_RING_ENABLE: enable hardware ring buffer
+ * IIO_DEV_ATTR_HW_RING_ENABLE - enable hardware ring buffer
+ * @_show: output method for the attribute
+ * @_store: input method for the attribute
  *
- * This is a different attribute from the software one as one can invision
+ * This is a different attribute from the software one as one can envision
  * schemes where a combination of the two may be used.
  **/
 #define IIO_DEV_ATTR_HW_RING_ENABLE(_show, _store)                     \
        IIO_DEVICE_ATTR(hw_ring_enable, S_IRUGO | S_IWUSR, _show, _store, 0)
 
 /**
- * IIO_DEV_ATTR_BPSE: set number of bits per scan element
+ * IIO_DEV_ATTR_BPSE - set number of bits per scan element
+ * @_mode: sysfs file mode/permissions
+ * @_show: output method for the attribute
+ * @_store: input method for the attribute
  **/
 #define IIO_DEV_ATTR_BPSE(_mode, _show, _store)                \
        IIO_DEVICE_ATTR(bpse, _mode, _show, _store, 0)
 
 /**
- * IIO_DEV_ATTR_BPSE_AVAILABLE: no of bits per scan element supported
+ * IIO_DEV_ATTR_BPSE_AVAILABLE - number of bits per scan element supported
+ * @_show: output method for the attribute
  **/
 #define IIO_DEV_ATTR_BPSE_AVAILABLE(_show)                             \
        IIO_DEVICE_ATTR(bpse_available, S_IRUGO, _show, NULL, 0)
 
 /**
- * IIO_DEV_ATTR_TEMP: many sensors have auxiliary temperature sensors
+ * IIO_DEV_ATTR_TEMP - many sensors have auxiliary temperature sensors
+ * @_show: output method for the attribute
  **/
 #define IIO_DEV_ATTR_TEMP(_show)                       \
        IIO_DEVICE_ATTR(temp, S_IRUGO, _show, NULL, 0)
+
 /**
- * IIO_EVENT_SH: generic shared event handler
+ * IIO_EVENT_SH - generic shared event handler
+ * @_name: event name
+ * @_handler: handler function to be called
  *
  * This is used in cases where more than one event may result from a single
  * handler.  Often the case that some alarm register must be read and multiple
@@ -221,8 +252,14 @@ struct iio_const_attr {
                        .prev = &iio_event_##_name.list,                \
                },                                                      \
        };
+
 /**
- * IIO_EVENT_ATTR_SH: generic shared event attribute
+ * IIO_EVENT_ATTR_SH - generic shared event attribute
+ * @_name: event name
+ * @_ev_list: event handler list
+ * @_show: output method for the attribute
+ * @_store: input method for the attribute
+ * @_mask: mask used when detecting the event
  *
  * An attribute with an associated IIO_EVENT_SH
  **/
@@ -235,7 +272,12 @@ struct iio_const_attr {
            .listel = &_ev_list };
 
 /**
- * IIO_EVENT_ATTR: non shared event attribute
+ * IIO_EVENT_ATTR - non-shared event attribute
+ * @_name: event name
+ * @_show: output method for the attribute
+ * @_store: input method for the attribute
+ * @_mask: mask used when detecting the event
+ * @_handler: handler function to be called
  **/
 #define IIO_EVENT_ATTR(_name, _show, _store, _mask, _handler)          \
        static struct iio_event_handler_list                            \
@@ -251,10 +293,14 @@ struct iio_const_attr {
            .listel = &iio_event_##_name };                             \
 
 /**
- * IIO_EVENT_ATTR_DATA_RDY: event driven by data ready signal
+ * IIO_EVENT_ATTR_DATA_RDY - event driven by data ready signal
+ * @_show: output method for the attribute
+ * @_store: input method for the attribute
+ * @_mask: mask used when detecting the event
+ * @_handler: handler function to be called
  *
  * Not typically implemented in devices where full triggering support
- * has been implemented
+ * has been implemented.
  **/
 #define IIO_EVENT_ATTR_DATA_RDY(_show, _store, _mask, _handler) \
        IIO_EVENT_ATTR(data_rdy, _show, _store, _mask, _handler)
@@ -269,19 +315,31 @@ struct iio_const_attr {
 #define IIO_EVENT_CODE_DEVICE_SPECIFIC 1000
 
 /**
- * IIO_EVENT_ATTR_RING_50_FULL: ring buffer event to indicate 50% full
+ * IIO_EVENT_ATTR_RING_50_FULL - ring buffer event to indicate 50% full
+ * @_show: output method for the attribute
+ * @_store: input method for the attribute
+ * @_mask: mask used when detecting the event
+ * @_handler: handler function to be called
  **/
 #define IIO_EVENT_ATTR_RING_50_FULL(_show, _store, _mask, _handler)    \
        IIO_EVENT_ATTR(ring_50_full, _show, _store, _mask, _handler)
 
 /**
- * IIO_EVENT_ATTR_RING_50_FULL_SH: shared ring event to indicate 50% full
+ * IIO_EVENT_ATTR_RING_50_FULL_SH - shared ring event to indicate 50% full
+ * @_evlist: event handler list
+ * @_show: output method for the attribute
+ * @_store: input method for the attribute
+ * @_mask: mask used when detecting the event
  **/
 #define IIO_EVENT_ATTR_RING_50_FULL_SH(_evlist, _show, _store, _mask)  \
        IIO_EVENT_ATTR_SH(ring_50_full, _evlist, _show, _store, _mask)
 
 /**
- * IIO_EVENT_ATTR_RING_75_FULL_SH: shared ring event to indicate 75% full
+ * IIO_EVENT_ATTR_RING_75_FULL_SH - shared ring event to indicate 75% full
+ * @_evlist: event handler list
+ * @_show: output method for the attribute
+ * @_store: input method for the attribute
+ * @_mask: mask used when detecting the event
  **/
 #define IIO_EVENT_ATTR_RING_75_FULL_SH(_evlist, _show, _store, _mask)  \
        IIO_EVENT_ATTR_SH(ring_75_full, _evlist, _show, _store, _mask)
index 8284098c9589c2bb7fbadf59602b51c58b5e7a7d..784e7b6fac1cc745157746ca632b288861296684 100644 (file)
  * @id:                        [INTERN] unique id number
  * @name:              [DRIVER] unique name
  * @dev:               [DRIVER] associated device (if relevant)
- * @sysfs_dev:         [INTERN] sysfs relevant device
  * @private_data:      [DRIVER] device specific data
  * @list:              [INTERN] used in maintenance of global trigger list
  * @alloc_list:                [DRIVER] used for driver specific trigger list
- * @poll_func_list_lock:[INTERN] protection of the polling function list
+ * @pollfunc_list_lock:        [INTERN] protection of the polling function list
  * @pollfunc_list:     [INTERN] list of functions to run on trigger.
  * @control_attrs:     [DRIVER] sysfs attributes relevant to trigger type
- * @set_trigger_state: [DRIVER] switch on/off the trigger on demand
  * @timestamp:         [INTERN] timestamp usesd by some trigs (e.g. datardy)
  * @owner:             [DRIVER] used to monitor usage count of the trigger.
+ * @use_count:         use count for the trigger
+ * @set_trigger_state: [DRIVER] switch on/off the trigger on demand
+ * @try_reenable:      function to reenable the trigger when the
+ *                     use count is zero (may be NULL)
  **/
 struct iio_trigger {
        int                             id;
@@ -68,6 +70,9 @@ static inline void iio_get_trigger(struct iio_trigger *trig)
 
 /**
  * iio_trigger_read_name() - sysfs access function to get the trigger name
+ * @dev: the system device
+ * @attr: device attributes for the device
+ * @buf: output buffer to store the trigger name
  **/
 ssize_t iio_trigger_read_name(struct device *dev,
                              struct device_attribute *attr,
@@ -79,6 +84,8 @@ ssize_t iio_trigger_read_name(struct device *dev,
 
 /**
  * iio_trigger_find_by_name() - search global trigger list
+ * @name: trigger name to search for
+ * @len: trigger name string length to compare
  **/
 struct iio_trigger *iio_trigger_find_by_name(const char *name, size_t len);
 
@@ -90,32 +97,35 @@ int iio_trigger_register(struct iio_trigger *trig_info);
 
 /**
  * iio_trigger_unregister() - unregister a trigger from the core
+ * @trig_info: trigger to be unregistered
  **/
 void iio_trigger_unregister(struct iio_trigger *trig_info);
 
 /**
  * iio_trigger_attach_poll_func() - add a function pair to be run on trigger
  * @trig:      trigger to which the function pair are being added
- * @pf:        poll function pair
+ * @pf:                poll function pair
  **/
 int iio_trigger_attach_poll_func(struct iio_trigger *trig,
                                 struct iio_poll_func *pf);
 
 /**
  * iio_trigger_dettach_poll_func() -   remove function pair from those to be
- *                                     run on trigger.
- * @trig:      trigger from which the function is being removed.
+ *                                     run on trigger
+ * @trig:      trigger from which the function is being removed
  * @pf:                poll function pair
  **/
 int iio_trigger_dettach_poll_func(struct iio_trigger *trig,
                                  struct iio_poll_func *pf);
 
 /**
- * iio_trigger_poll() - called on a trigger occuring
+ * iio_trigger_poll() - called on a trigger occurring
+ * @trig: trigger which occurred
+ *
  * Typically called in relevant hardware interrupt handler.
  **/
-void iio_trigger_poll(struct iio_trigger *);
-void iio_trigger_notify_done(struct iio_trigger *);
+void iio_trigger_poll(struct iio_trigger *trig);
+void iio_trigger_notify_done(struct iio_trigger *trig);
 
 /**
  * struct iio_poll_func - poll function pair
@@ -127,11 +137,10 @@ void iio_trigger_notify_done(struct iio_trigger *);
  *                             control on sensor supporting it.
  * @poll_func_main:            function in here is run after all immediates.
  *                             Reading from sensor etc typically involves
- *                             scheduling
- *                             from here.
+ *                             scheduling from here.
  *
- * The two stage approach used here only important when multiple sensors are
- * being triggered by a single trigger. This really comes into it's own with
+ * The two stage approach used here is only important when multiple sensors are
+ * being triggered by a single trigger. This really comes into its own with
  * simultaneous sampling devices where a simple latch command can be used to
  * make the device store the values on all inputs.
  **/
index 4c7f527dc79f1a0d1b9eebe1660d16868b84c816..a02d70b0d24ad05e6fd9e5d3a8240e2238997954 100644 (file)
 
 #ifdef CONFIG_IIO_TRIGGER
 /**
- * iio_device_register_trigger_consumer() - set up an iio_dev to use triggers.
+ * iio_device_register_trigger_consumer() - set up an iio_dev to use triggers
  * @dev_info: iio_dev associated with the device that will consume the trigger
  **/
 int iio_device_register_trigger_consumer(struct iio_dev *dev_info);
+
 /**
- * iio_device_unregister_trigger_consumer() - reverse the registration process.
+ * iio_device_unregister_trigger_consumer() - reverse the registration process
  * @dev_info: iio_dev associated with the device that consumed the trigger
  **/
 int iio_device_unregister_trigger_consumer(struct iio_dev *dev_info);
@@ -23,13 +24,14 @@ int iio_device_unregister_trigger_consumer(struct iio_dev *dev_info);
 #else
 
 /**
- * iio_device_register_trigger_consumer() - set up an iio_dev to use triggers.
+ * iio_device_register_trigger_consumer() - set up an iio_dev to use triggers
  * @dev_info: iio_dev associated with the device that will consume the trigger
  **/
 int iio_device_register_trigger_consumer(struct iio_dev *dev_info)
 {
        return 0;
 };
+
 /**
  * iio_device_unregister_trigger_consumer() - reverse the registration process
  * @dev_info: iio_dev associated with the device that consumed the trigger