[PATCH v3 18/26] staging: most: core: fix comment sections

Christian Gromm christian.gromm at microchip.com
Mon Oct 16 08:46:25 UTC 2017


This patch updates and corrects the comment sections of the code.

Signed-off-by: Christian Gromm <christian.gromm at microchip.com>
---
v2: fix patch numeration
v3: - add cover letter
    - create patches with -M switch to make file movement visible

 drivers/staging/most/core.c | 87 +++++++++++++++++++--------------------------
 drivers/staging/most/core.h | 40 ++++++++++-----------
 2 files changed, 55 insertions(+), 72 deletions(-)

diff --git a/drivers/staging/most/core.c b/drivers/staging/most/core.c
index 7961690..e3736bb 100644
--- a/drivers/staging/most/core.c
+++ b/drivers/staging/most/core.c
@@ -116,15 +116,9 @@ int most_match(struct device *dev, struct device_driver *drv)
 	_mbo;								\
 })
 
-/*		     ___	     ___
- *		     ___C H A N N E L___
- */
-
-
 /**
  * most_free_mbo_coherent - free an MBO and its coherent buffer
- * @mbo: buffer to be released
- *
+ * @mbo: most buffer
  */
 static void most_free_mbo_coherent(struct mbo *mbo)
 {
@@ -486,9 +480,6 @@ static ssize_t set_packets_per_xact_store(struct device *dev,
 	NULL,
 };
 
-/*		     ___	       ___
- *		     ___I N S T A N C E___
- */
 static ssize_t description_show(struct device *dev,
 				struct device_attribute *attr,
 				char *buf)
@@ -602,26 +593,26 @@ static ssize_t components_show(struct device_driver *drv, char *buf)
 	return offs;
 }
 /**
- * split_string - parses and changes string in the buffer buf and
- * splits it into two mandatory and one optional substrings.
+ * split_string - parses buf and extracts ':' separated substrings.
  *
  * @buf: complete string from attribute 'add_channel'
- * @a: address of pointer to 1st substring (=instance name)
- * @b: address of pointer to 2nd substring (=channel name)
- * @c: optional address of pointer to 3rd substring (=user defined name)
+ * @a: storage for 1st substring (=interface name)
+ * @b: storage for 2nd substring (=channel name)
+ * @c: storage for 3rd substring (=component name)
+ * @d: storage optional 4th substring (=user defined name)
  *
  * Examples:
  *
- * Input: "mdev0:ch6:my_channel\n" or
- *        "mdev0:ch6:my_channel"
+ * Input: "mdev0:ch6:cdev:my_channel\n" or
+ *        "mdev0:ch6:cdev:my_channel"
  *
- * Output: *a -> "mdev0", *b -> "ch6", *c -> "my_channel"
+ * Output: *a -> "mdev0", *b -> "ch6", *c -> "cdev" *d -> "my_channel"
  *
- * Input: "mdev1:ep81\n"
- * Output: *a -> "mdev1", *b -> "ep81", *c -> ""
+ * Input: "mdev1:ep81:cdev\n"
+ * Output: *a -> "mdev1", *b -> "ep81", *c -> "cdev" *d -> ""
  *
  * Input: "mdev1:ep81"
- * Output: *a -> "mdev1", *b -> "ep81", *c == NULL
+ * Output: *a -> "mdev1", *b -> "ep81", *c -> "cdev" *d == NULL
  */
 static int split_string(char *buf, char **a, char **b, char **c, char **d)
 {
@@ -651,11 +642,9 @@ static int match_bus_dev(struct device *dev, void *data)
 }
 
 /**
- * get_channel - get pointer to channel object
- * @mdev: name of the device instance
- * @mdev_ch: name of the respective channel
- *
- * This retrieves the pointer to a channel object.
+ * get_channel - get pointer to channel
+ * @mdev: name of the device interface
+ * @mdev_ch: name of channel
  */
 static struct most_channel *get_channel(char *mdev, char *mdev_ch)
 {
@@ -699,23 +688,22 @@ static int link_channel_to_component(struct most_channel *c,
 }
 
 /**
- * add_link_store - store() function for add_link attribute
- * @comp_obj: pointer to component object
- * @attr: its attributes
+ * add_link_store - store function for add_link attribute
+ * @drv: device driver
  * @buf: buffer
  * @len: buffer length
  *
  * This parses the string given by buf and splits it into
- * three substrings. Note: third substring is optional. In case a cdev
- * component is loaded the optional 3rd substring will make up the name of
+ * four substrings. Note: last substring is optional. In case a cdev
+ * component is loaded the optional 4th substring will make up the name of
  * device node in the /dev directory. If omitted, the device node will
  * inherit the channel's name within sysfs.
  *
- * Searches for a pair of device and channel and probes the component
+ * Searches for (device, channel) pair and probes the component
  *
  * Example:
- * (1) echo "mdev0:ch6:my_rxchannel" >add_link
- * (2) echo "mdev1:ep81" >add_link
+ * (1) echo "mdev0:ch6:cdev:my_rxchannel" >add_link
+ * (2) echo "mdev1:ep81:cdev" >add_link
  *
  * (1) would create the device node /dev/my_rxchannel
  * (2) would create the device node /dev/mdev1-ep81
@@ -761,8 +749,7 @@ static ssize_t add_link_store(struct device_driver *drv,
 
 /**
  * remove_link_store - store function for remove_link attribute
- * @comp_obj: pointer to component object
- * @attr: its attributes
+ * @drv: device driver
  * @buf: buffer
  * @len: buffer length
  *
@@ -823,9 +810,6 @@ static ssize_t remove_link_store(struct device_driver *drv,
 	&mc_attr_group,
 	NULL,
 };
-/*		     ___       ___
- *		     ___C O R E___
- */
 
 static inline void trash_mbo(struct mbo *mbo)
 {
@@ -917,7 +901,7 @@ static int run_enqueue_thread(struct most_channel *c, int channel_id)
 
 /**
  * arm_mbo - recycle MBO for further usage
- * @mbo: buffer object
+ * @mbo: most buffer
  *
  * This puts an MBO back to the list to have it ready for up coming
  * tx transactions.
@@ -1011,7 +995,7 @@ static int arm_mbo_chain(struct most_channel *c, int dir,
 
 /**
  * most_submit_mbo - submits an MBO to fifo
- * @mbo: pointer to the MBO
+ * @mbo: most buffer
  */
 void most_submit_mbo(struct mbo *mbo)
 {
@@ -1025,7 +1009,7 @@ void most_submit_mbo(struct mbo *mbo)
 
 /**
  * most_write_completion - write completion handler
- * @mbo: pointer to MBO
+ * @mbo: most buffer
  *
  * This recycles the MBO for further usage. In case the channel has been
  * poisoned, the MBO is scheduled to be trashed.
@@ -1071,6 +1055,7 @@ int channel_has_mbo(struct most_interface *iface, int id,
  * most_get_mbo - get pointer to an MBO of pool
  * @iface: pointer to interface instance
  * @id: channel ID
+ * @comp: driver component
  *
  * This attempts to get a free buffer out of the channel fifo.
  * Returns a pointer to MBO on success or NULL otherwise.
@@ -1116,7 +1101,7 @@ struct mbo *most_get_mbo(struct most_interface *iface, int id,
 
 /**
  * most_put_mbo - return buffer to pool
- * @mbo: buffer object
+ * @mbo: most buffer
  */
 void most_put_mbo(struct mbo *mbo)
 {
@@ -1133,7 +1118,7 @@ void most_put_mbo(struct mbo *mbo)
 
 /**
  * most_read_completion - read completion handler
- * @mbo: pointer to MBO
+ * @mbo: most buffer
  *
  * This function is called by the HDM when data has been received from the
  * hardware and copied to the buffer of the MBO.
@@ -1174,6 +1159,7 @@ static void most_read_completion(struct mbo *mbo)
  * most_start_channel - prepares a channel for communication
  * @iface: pointer to interface instance
  * @id: channel ID
+ * @comp: driver component
  *
  * This prepares the channel for usage. Cross-checks whether the
  * channel's been properly configured.
@@ -1249,6 +1235,7 @@ int most_start_channel(struct most_interface *iface, int id,
  * most_stop_channel - stops a running channel
  * @iface: pointer to interface instance
  * @id: channel ID
+ * @comp: driver component
  */
 int most_stop_channel(struct most_interface *iface, int id,
 		      struct core_component *comp)
@@ -1306,8 +1293,8 @@ int most_stop_channel(struct most_interface *iface, int id,
 EXPORT_SYMBOL_GPL(most_stop_channel);
 
 /**
- * most_register_component - registers an component (driver) with the core
- * @comp: instance of component to be registered
+ * most_register_component - registers a driver component with the core
+ * @comp: driver component
  */
 int most_register_component(struct core_component *comp)
 {
@@ -1340,8 +1327,8 @@ static int disconnect_channels(struct device *dev, void *data)
 }
 
 /**
- * most_deregister_component - deregisters an component (driver) with the core
- * @comp: component to be removed
+ * most_deregister_component - deregisters a driver component with the core
+ * @comp: driver component
  */
 int most_deregister_component(struct core_component *comp)
 {
@@ -1369,7 +1356,7 @@ static void release_channel(struct device *dev)
 
 /**
  * most_register_interface - registers an interface with core
- * @iface: pointer to the instance of the interface description.
+ * @iface: device interface
  *
  * Allocates and initializes a new interface instance and all of its channels.
  * Returns a pointer to kobject or an error pointer.
@@ -1477,7 +1464,7 @@ int most_register_interface(struct most_interface *iface)
 
 /**
  * most_deregister_interface - deregisters an interface with core
- * @iface: pointer to the interface instance description.
+ * @iface: device interface
  *
  * Before removing an interface instance from the list, all running
  * channels are stopped and poisoned.
diff --git a/drivers/staging/most/core.h b/drivers/staging/most/core.h
index d74276d..d6e9b87 100644
--- a/drivers/staging/most/core.h
+++ b/drivers/staging/most/core.h
@@ -1,6 +1,5 @@
 /*
- * most.h - Interface between MostCore,
- *   Hardware Dependent Module (HDM) and Application Interface Module (AIM).
+ * most.h - API for component and adapter drivers
  *
  * Copyright (C) 2013-2015, Microchip Technology Germany II GmbH & Co. KG
  *
@@ -12,13 +11,6 @@
  * This file is licensed under GPLv2.
  */
 
-/*
- * Authors:
- *   Andrey Shvetsov <andrey.shvetsov at k2l.de>
- *   Christian Gromm <christian.gromm at microchip.com>
- *   Sebastian Graf
- */
-
 #ifndef __MOST_CORE_H__
 #define __MOST_CORE_H__
 
@@ -80,22 +72,22 @@ enum mbo_status_flags {
  * The value is bitwise OR-combination of the values from the
  * enumeration most_channel_data_type. Zero is allowed value and means
  * "channel may not be used".
- * @num_buffer_packet: Maximum number of buffers supported by this channel
+ * @num_buffers_packet: Maximum number of buffers supported by this channel
  * for packet data types (Async,Control,QoS)
  * @buffer_size_packet: Maximum buffer size supported by this channel
  * for packet data types (Async,Control,QoS)
- * @num_buffer_streaming: Maximum number of buffers supported by this channel
+ * @num_buffers_streaming: Maximum number of buffers supported by this channel
  * for streaming data types (Sync,AV Packetized)
  * @buffer_size_streaming: Maximum buffer size supported by this channel
  * for streaming data types (Sync,AV Packetized)
  * @name_suffix: Optional suffix providean by an HDM that is attached to the
  * regular channel name.
  *
- * Describes the capabilities of a MostCore channel like supported Data Types
+ * Describes the capabilities of a MOST channel like supported Data Types
  * and directions. This information is provided by an HDM for the MostCore.
  *
  * The Core creates read only sysfs attribute files in
- * /sys/devices/virtual/most/mostcore/devices/mdev-#/mdev#-ch#/ with the
+ * /sys/devices/most/mdev#/<channel>/ with the
  * following attributes:
  *	-available_directions
  *	-available_datatypes
@@ -130,7 +122,7 @@ struct most_channel_capability {
  * @packets_per_xact: number of MOST frames that are packet inside one USB
  *		      packet. This is USB specific
  *
- * Describes the configuration for a MostCore channel. This information is
+ * Describes the configuration for a MOST channel. This information is
  * provided from the MostCore to a HDM (like the Medusa PCIe Interface) as a
  * parameter of the "configure" function call.
  */
@@ -154,6 +146,7 @@ struct most_channel_config {
  *
  * @list: list head for use by the mbo's current owner
  * @ifp: (in) associated interface instance
+ * @num_buffers_ptr: amount of pool buffers
  * @hdm_channel_id: (in) HDM channel instance
  * @virt_address: (in) kernel virtual address of the buffer
  * @bus_address: (in) bus address of the buffer
@@ -162,15 +155,15 @@ struct most_channel_config {
  * @status: (out) transfer status
  * @complete: (in) completion routine
  *
- * The MostCore allocates and initializes the MBO.
+ * The core allocates and initializes the MBO.
  *
- * The HDM receives MBO for transfer from MostCore with the call to enqueue().
+ * The HDM receives MBO for transfer from the core with the call to enqueue().
  * The HDM copies the data to- or from the buffer depending on configured
  * channel direction, set "processed_length" and "status" and completes
  * the transfer procedure by calling the completion routine.
  *
- * At the end the MostCore deallocates the MBO or recycles it for further
- * transfers for the same or different HDM.
+ * Finally, the MBO is being deallocated or recycled for further
+ * transfers of the same or a different HDM.
  *
  * Directions of usage:
  * The core driver should never access any MBO fields (even if marked
@@ -203,10 +196,12 @@ struct mbo {
 /**
  * Interface instance description.
  *
- * Describes one instance of an interface like Medusa PCIe or Vantage USB.
+ * Describes an interface of a MOST device the core driver is bound to.
  * This structure is allocated and initialized in the HDM. MostCore may not
  * modify this structure.
  *
+ * @dev: the actual device
+ * @mod: module
  * @interface Interface type. \sa most_interface_type.
  * @description PRELIMINARY.
  *   Unique description of the device instance from point of view of the
@@ -259,14 +254,15 @@ struct most_interface {
 };
 
 #define to_most_interface(d) container_of(d, struct most_interface, dev)
+
 /**
- * struct most_aim - identifies MOST device driver to mostcore
- * @name: Driver name
+ * struct core_component - identifies a loadable component for the mostcore
+ * @list: list_head
+ * @name: component name
  * @probe_channel: function for core to notify driver about channel connection
  * @disconnect_channel: callback function to disconnect a certain channel
  * @rx_completion: completion handler for received packets
  * @tx_completion: completion handler for transmitted packets
- * @context: context pointer to be used by mostcore
  */
 struct core_component {
 	struct list_head list;
-- 
1.9.1



More information about the devel mailing list