From: Randy Dunlap Date: Mon, 5 Oct 2009 02:34:02 +0000 (-0700) Subject: Staging: iio: lots of doc fixes X-Git-Tag: v2.6.33-rc2~13^2~166 X-Git-Url: http://ftp.safe.ca/?p=safe%2Fjmp%2Flinux-2.6;a=commitdiff_plain;h=4c572605085d65b7cf4f5b36ccac0f30866d19f9 Staging: iio: lots of doc fixes 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 Acked-by: Jonathan Cameron Signed-off-by: Greg Kroah-Hartman --- diff --git a/drivers/staging/iio/chrdev.h b/drivers/staging/iio/chrdev.h index 8bc64bf..f42bafb 100644 --- a/drivers/staging/iio/chrdev.h +++ b/drivers/staging/iio/chrdev.h @@ -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; diff --git a/drivers/staging/iio/iio.h b/drivers/staging/iio/iio.h index 25ccb80..71dbfe1 100644 --- a/drivers/staging/iio/iio.h +++ b/drivers/staging/iio/iio.h @@ -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) { diff --git a/drivers/staging/iio/ring_generic.h b/drivers/staging/iio/ring_generic.h index d926189..93b91b2 100644 --- a/drivers/staging/iio/ring_generic.h +++ b/drivers/staging/iio/ring_generic.h @@ -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. **/ diff --git a/drivers/staging/iio/ring_sw.h b/drivers/staging/iio/ring_sw.h index ae70ee0..f0b86f0 100644 --- a/drivers/staging/iio/ring_sw.h +++ b/drivers/staging/iio/ring_sw.h @@ -36,52 +36,65 @@ #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) { diff --git a/drivers/staging/iio/sysfs.h b/drivers/staging/iio/sysfs.h index bfe4055..e501e13 100644 --- a/drivers/staging/iio/sysfs.h +++ b/drivers/staging/iio/sysfs.h @@ -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) diff --git a/drivers/staging/iio/trigger.h b/drivers/staging/iio/trigger.h index 8284098..784e7b6 100644 --- a/drivers/staging/iio/trigger.h +++ b/drivers/staging/iio/trigger.h @@ -19,16 +19,18 @@ * @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. **/ diff --git a/drivers/staging/iio/trigger_consumer.h b/drivers/staging/iio/trigger_consumer.h index 4c7f527..a02d70b 100644 --- a/drivers/staging/iio/trigger_consumer.h +++ b/drivers/staging/iio/trigger_consumer.h @@ -10,12 +10,13 @@ #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