This patch updates and corrects the comment sections of the code.
Signed-off-by: Christian Gromm <christian.gromm@xxxxxxxxxxxxx>
---
drivers/staging/most/cdev/cdev.c | 4 +-
drivers/staging/most/core.c | 108 ++++++++++++++++---------------------
drivers/staging/most/core.h | 39 ++++++--------
drivers/staging/most/net/net.c | 4 +-
drivers/staging/most/sound/sound.c | 2 +-
drivers/staging/most/video/video.c | 4 +-
6 files changed, 70 insertions(+), 91 deletions(-)
diff --git a/drivers/staging/most/cdev/cdev.c b/drivers/staging/most/cdev/cdev.c
index c741231..225369d 100644
--- a/drivers/staging/most/cdev/cdev.c
+++ b/drivers/staging/most/cdev/cdev.c
@@ -1,5 +1,5 @@
/*
- * cdev.c - Application interfacing module for character devices
+ * cdev.c - Character device component for Mostcore
*
* Copyright (C) 2013-2015 Microchip Technology Germany II GmbH & Co. KG
*
@@ -559,4 +559,4 @@ module_init(mod_init);
module_exit(mod_exit);
MODULE_AUTHOR("Christian Gromm <christian.gromm@xxxxxxxxxxxxx>");
MODULE_LICENSE("GPL");
-MODULE_DESCRIPTION("character device AIM for mostcore");
+MODULE_DESCRIPTION("character device component for mostcore");
diff --git a/drivers/staging/most/core.c b/drivers/staging/most/core.c
index 6d7fe7d..d490bdc 100644
--- a/drivers/staging/most/core.c
+++ b/drivers/staging/most/core.c
@@ -109,14 +109,9 @@ static const struct {
_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)
{
@@ -475,9 +470,6 @@ static const struct attribute_group *channel_attr_groups[] = {
NULL,
};
-/* ___ ___
- * ___I N S T A N C E___
- */
static ssize_t description_show(struct device *dev,
struct device_attribute *attr,
char *buf)
@@ -534,9 +526,6 @@ static const struct attribute_group *interface_attr_groups[] = {
NULL,
};
-/* ___ ___
- * ___A I M___
- */
static struct core_component *match_module(char *name)
{
struct core_component *comp;
@@ -594,26 +583,26 @@ static ssize_t modules_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)
{
@@ -643,11 +632,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)
{
@@ -693,23 +680,22 @@ inline int link_channel_to_component(struct most_channel *c,
}
/**
- * add_link_store - store() function for add_link attribute
- * @aim_obj: pointer to AIM 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
- * AIM 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 AIM
+ * 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
@@ -754,8 +740,7 @@ static ssize_t add_link_store(struct device_driver *drv,
/**
* remove_link_store - store function for remove_link attribute
- * @aim_obj: pointer to AIM object
- * @attr: its attributes
+ * @drv: device driver
* @buf: buffer
* @len: buffer length
*
@@ -817,10 +802,6 @@ static const struct attribute_group *module_attr_groups[] = {
NULL,
};
-/* ___ ___
- * ___C O R E___
- */
-
int most_match(struct device *dev, struct device_driver *drv)
{
if (!strcmp(dev_name(dev), "most"))
@@ -919,14 +900,14 @@ 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.
*
* In case the MBO belongs to a channel that recently has been
* poisoned, the MBO is scheduled to be trashed.
- * Calls the completion handler of an attached AIM.
+ * Calls the completion handler of an attached component.
*/
static void arm_mbo(struct mbo *mbo)
{
@@ -1013,7 +994,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)
{
@@ -1027,7 +1008,7 @@ EXPORT_SYMBOL_GPL(most_submit_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.
@@ -1073,6 +1054,7 @@ EXPORT_SYMBOL_GPL(channel_has_mbo);
* 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.
@@ -1118,7 +1100,7 @@ EXPORT_SYMBOL_GPL(most_get_mbo);
/**
* most_put_mbo - return buffer to pool
- * @mbo: buffer object
+ * @mbo: most buffer
*/
void most_put_mbo(struct mbo *mbo)
{
@@ -1135,13 +1117,13 @@ EXPORT_SYMBOL_GPL(most_put_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.
*
* In case the channel has been poisoned it puts the buffer in the trash queue.
- * Otherwise, it passes the buffer to an AIM for further processing.
+ * Otherwise, it passes the buffer to an component for further processing.
*/
static void most_read_completion(struct mbo *mbo)
{
@@ -1176,6 +1158,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.
@@ -1194,7 +1177,7 @@ int most_start_channel(struct most_interface *iface, int id,
mutex_lock(&c->start_mutex);
if (c->pipe0.refs + c->pipe1.refs > 0)
- goto out; /* already started by other comp */
+ goto out; /* already started by another component */
if (!try_module_get(iface->mod)) {
pr_info("failed to acquire HDM lock\n");
@@ -1251,6 +1234,7 @@ EXPORT_SYMBOL_GPL(most_start_channel);
* 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)
@@ -1308,17 +1292,17 @@ int most_stop_channel(struct most_interface *iface, int id,
EXPORT_SYMBOL_GPL(most_stop_channel);
/**
- * most_register_component - registers an AIM (driver) with the core
- * @aim: instance of AIM to be registered
+ * most_register_component - registers a driver component with the core
+ * @comp: driver component
*/
int most_register_component(struct core_component *comp)
{
if (!comp) {
- pr_err("Bad driver\n");
+ pr_err("Bad component\n");
return -EINVAL;
}
list_add_tail(&comp->list, &mc.comp_list);
- pr_info("registered new application interfacing module %s\n", comp->name);
+ pr_info("registered new core component %s\n", comp->name);
return 0;
}
EXPORT_SYMBOL_GPL(most_register_component);
@@ -1342,19 +1326,19 @@ static int disconnect_channels(struct device *dev, void *data)
}
/**
- * most_deregister_component - deregisters an AIM (driver) with the core
- * @aim: AIM to be removed
+ * most_deregister_component - deregisters a driver component with the core
+ * @comp: driver component
*/
int most_deregister_component(struct core_component *comp)
{
if (!comp) {
- pr_err("Bad driver\n");
+ pr_err("Bad component\n");
return -EINVAL;
}
bus_for_each_dev(&mc.bus, NULL, comp, disconnect_channels);
list_del(&comp->list);
- pr_info("deregistering module %s\n", comp->name);
+ pr_info("deregistering component %s\n", comp->name);
return 0;
}
EXPORT_SYMBOL_GPL(most_deregister_component);
@@ -1371,7 +1355,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.
@@ -1457,7 +1441,7 @@ int most_register_interface(struct most_interface *iface)
mutex_init(&c->nq_mutex);
list_add_tail(&c->list, &iface->p->channel_list);
}
- pr_info("registered new MOST device mdev%d (%s)\n",
+ pr_info("registered new device mdev%d (%s)\n",
id, iface->description);
return 0;
@@ -1479,7 +1463,7 @@ EXPORT_SYMBOL_GPL(most_register_interface);
/**
* 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.
@@ -1489,7 +1473,7 @@ void most_deregister_interface(struct most_interface *iface)
int i;
struct most_channel *c;
- pr_info("deregistering MOST device %s (%s)\n", dev_name(&iface->dev), iface->description);
+ pr_info("deregistering device %s (%s)\n", dev_name(&iface->dev), iface->description);
for (i = 0; i < iface->num_channels; i++) {
c = iface->p->channel[i];
if (c->pipe0.comp)
diff --git a/drivers/staging/most/core.h b/drivers/staging/most/core.h
index 3c2975b..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@xxxxxx>
- * Christian Gromm <christian.gromm@xxxxxxxxxxxxx>
- * 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
@@ -261,13 +256,13 @@ 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;
diff --git a/drivers/staging/most/net/net.c b/drivers/staging/most/net/net.c
index 00a5ddf..27cd31b 100644
--- a/drivers/staging/most/net/net.c
+++ b/drivers/staging/most/net/net.c
@@ -1,5 +1,5 @@
/*
- * Networking component - Networking Application Interface Module for MostCore
+ * net.c - Networking component for Mostcore
*
* Copyright (C) 2015, Microchip Technology Germany II GmbH & Co. KG
*
@@ -563,4 +563,4 @@ module_init(most_net_init);
module_exit(most_net_exit);
MODULE_LICENSE("GPL");
MODULE_AUTHOR("Andrey Shvetsov <andrey.shvetsov@xxxxxx>");
-MODULE_DESCRIPTION("Networking Application Interface Module for MostCore");
+MODULE_DESCRIPTION("Networking Component Module for Mostcore");
diff --git a/drivers/staging/most/sound/sound.c b/drivers/staging/most/sound/sound.c
index 2c9e6c9..21231e3 100644
--- a/drivers/staging/most/sound/sound.c
+++ b/drivers/staging/most/sound/sound.c
@@ -761,4 +761,4 @@ module_exit(audio_exit);
MODULE_LICENSE("GPL");
MODULE_AUTHOR("Christian Gromm <christian.gromm@xxxxxxxxxxxxx>");
-MODULE_DESCRIPTION("Audio Application Interface Module for MostCore");
+MODULE_DESCRIPTION("Sound Component Module for Mostcore");
diff --git a/drivers/staging/most/video/video.c b/drivers/staging/most/video/video.c
index b06488b..1577f36 100644
--- a/drivers/staging/most/video/video.c
+++ b/drivers/staging/most/video/video.c
@@ -1,5 +1,5 @@
/*
- * V4L2 Component - V4L2 Application Interface Module for MostCore
+ * video.c - V4L2 component for Mostcore
*
* Copyright (C) 2015, Microchip Technology Germany II GmbH & Co. KG
*
@@ -610,6 +610,6 @@ static void __exit comp_exit(void)
module_init(comp_init);
module_exit(comp_exit);
-MODULE_DESCRIPTION("V4L2 Component Module for MostCore");
+MODULE_DESCRIPTION("V4L2 Component Module for Mostcore");
MODULE_AUTHOR("Andrey Shvetsov <andrey.shvetsov@xxxxxx>");
MODULE_LICENSE("GPL");
--
2.7.4
_______________________________________________
devel mailing list
devel@xxxxxxxxxxxxxxxxxxxxxx
http://driverdev.linuxdriverproject.org/mailman/listinfo/driverdev-devel
