From b7937dc41362f73cb1ed228fdd3ac32a69b17794 Mon Sep 17 00:00:00 2001 From: Christian Gromm Date: Tue, 21 Nov 2017 15:05:12 +0100 Subject: staging: most: fix comment sections This patch updates and corrects the comment sections of the code. Signed-off-by: Christian Gromm Signed-off-by: Greg Kroah-Hartman --- 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(-) (limited to 'drivers/staging/most') diff --git a/drivers/staging/most/cdev/cdev.c b/drivers/staging/most/cdev/cdev.c index 8a4ed753beae..266e2bb6ecf7 100644 --- a/drivers/staging/most/cdev/cdev.c +++ b/drivers/staging/most/cdev/cdev.c @@ -1,6 +1,6 @@ // SPDX-License-Identifier: GPL-2.0 /* - * 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 */ @@ -553,4 +553,4 @@ module_init(mod_init); module_exit(mod_exit); MODULE_AUTHOR("Christian Gromm "); 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 174c88a4bd9e..29dc89c85e33 100644 --- a/drivers/staging/most/core.c +++ b/drivers/staging/most/core.c @@ -103,14 +103,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) { @@ -469,9 +464,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) @@ -528,9 +520,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; @@ -588,26 +577,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) { @@ -637,11 +626,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) { @@ -687,23 +674,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 @@ -748,8 +734,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 * @@ -811,10 +796,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")) @@ -913,14 +894,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) { @@ -1007,7 +988,7 @@ _exit: /** * most_submit_mbo - submits an MBO to fifo - * @mbo: pointer to the MBO + * @mbo: most buffer */ void most_submit_mbo(struct mbo *mbo) { @@ -1021,7 +1002,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. @@ -1067,6 +1048,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. @@ -1112,7 +1094,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) { @@ -1129,13 +1111,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) { @@ -1170,6 +1152,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. @@ -1188,7 +1171,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"); @@ -1245,6 +1228,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) @@ -1302,17 +1286,17 @@ out: 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); @@ -1336,19 +1320,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); @@ -1365,7 +1349,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. @@ -1451,7 +1435,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; @@ -1473,7 +1457,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. @@ -1483,7 +1467,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 5a3a5c5c3347..52db7fa15f65 100644 --- a/drivers/staging/most/core.h +++ b/drivers/staging/most/core.h @@ -1,18 +1,10 @@ // SPDX-License-Identifier: GPL-2.0 /* - * 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 */ -/* - * Authors: - * Andrey Shvetsov - * Christian Gromm - * Sebastian Graf - */ - #ifndef __MOST_CORE_H__ #define __MOST_CORE_H__ @@ -74,22 +66,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#// with the * following attributes: * -available_directions * -available_datatypes @@ -124,7 +116,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. */ @@ -148,6 +140,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 @@ -156,15 +149,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 @@ -197,10 +190,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 @@ -255,13 +250,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 38d6fe94ac6b..33606584e50e 100644 --- a/drivers/staging/most/net/net.c +++ b/drivers/staging/most/net/net.c @@ -1,6 +1,6 @@ // SPDX-License-Identifier: GPL-2.0 /* - * Networking component - Networking Application Interface Module for MostCore + * net.c - Networking component for Mostcore * * Copyright (C) 2015, Microchip Technology Germany II GmbH & Co. KG */ @@ -557,4 +557,4 @@ module_init(most_net_init); module_exit(most_net_exit); MODULE_LICENSE("GPL"); MODULE_AUTHOR("Andrey Shvetsov "); -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 e93b8047561c..83cec21c85b8 100644 --- a/drivers/staging/most/sound/sound.c +++ b/drivers/staging/most/sound/sound.c @@ -755,4 +755,4 @@ module_exit(audio_exit); MODULE_LICENSE("GPL"); MODULE_AUTHOR("Christian Gromm "); -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 62b789e71399..4be1e0dc9dd2 100644 --- a/drivers/staging/most/video/video.c +++ b/drivers/staging/most/video/video.c @@ -1,6 +1,6 @@ // SPDX-License-Identifier: GPL-2.0 /* - * V4L2 Component - V4L2 Application Interface Module for MostCore + * video.c - V4L2 component for Mostcore * * Copyright (C) 2015, Microchip Technology Germany II GmbH & Co. KG */ @@ -604,6 +604,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 "); MODULE_LICENSE("GPL"); -- cgit v1.2.3