Skip to content

Commit

Permalink
Staging: iio: lots of doc fixes
Browse files Browse the repository at this point in the history 
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>
  • Loading branch information
Randy Dunlap authored and Greg Kroah-Hartman committed Dec 11, 2009
1 parent 7e04638 commit 4c57260
Show file tree
Hide file tree
Showing 7 changed files with 228 additions and 110 deletions.
4 changes: 3 additions & 1 deletion drivers/staging/iio/chrdev.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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;
Expand Down
36 changes: 19 additions & 17 deletions drivers/staging/iio/iio.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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,
Expand All @@ -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;
Expand All @@ -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,
Expand All @@ -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
Expand All @@ -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
**/
Expand All @@ -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
Expand Down Expand Up @@ -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)
Expand All @@ -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)
Expand All @@ -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);

Expand All @@ -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)
{
Expand Down
73 changes: 45 additions & 28 deletions drivers/staging/iio/ring_generic.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
**/
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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;
Expand All @@ -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)
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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) \
Expand All @@ -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.
**/
Expand Down
Loading

0 comments on commit 4c57260

Please sign in to comment.