From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1758061AbcFHVPj (ORCPT ); Wed, 8 Jun 2016 17:15:39 -0400 Received: from mail1.bemta8.messagelabs.com ([216.82.243.194]:35472 "EHLO mail1.bemta8.messagelabs.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1161163AbcFHVOn (ORCPT ); Wed, 8 Jun 2016 17:14:43 -0400 X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFrrIIsWRWlGSWpSXmKPExsVywNY2Q/dAV0S 4QUeHqMXCtiUsFpd3zWFzYPL4vEkugDGKNTMvKb8igTXj/619bAUvzSvmXWRrYGzU6WLk5BAS 2MUo8bAzH8Lezyhx5Vt9FyMXkH2JUWL17PtMEM5aRomzC94wQlRtYZSYO0kLxGYTMJCYeecuO 4gtInCeReLprdwuRg4OZgE1iRvfLUHCwgIBEoce9jGB2CwCKhLzWueDjeEV8JK49fMiK4gtIS AncfLYZDCbEyj+8NdaJohVnhIt7x6zQ9hqEofPPmKDqA+WWH6mgwVijqDEyZlPwGxmAQmJgy9 eME9gFJqFJDULSWoBI9MqRo3i1KKy1CJdQ0u9pKLM9IyS3MTMHF1DAwu93NTi4sT01JzEpGK9 5PzcTYzA4K1nYGDcwThtt/shRkkOJiVR3jL3iHAhvqT8lMqMxOKM+KLSnNTiQ4wyHBxKErzJn UA5waLU9NSKtMwcYBzBpCU4eJREeE+CpHmLCxJzizPTIVKnGHU5lux6sJZJiCUvPy9VSpx3MU iRAEhRRmke3AhYTF9ilJUS5mVkYGAQ4ilILcrNLEGVf8UozsGoJMybDTKFJzOvBG7TK6AjmIC OWH4kHOSIkkSElFQDo9KGjNuefo5V7d8XryxZNnHCgsJHl4LDnn8R+do0o/bM0cqMpTLN1/24 Bd6FN1Yc5vyfddpM+PX6C8v//rZmqGQsmNfm81LlycmpS0+5NMwVKTq8aIfyXzNVPiWtS37t+ vstfjx+vu5y4qH7kyaem/9sdWX3DpUzDIwfryYkeXWul1hV++VTP7sSS3FGoqEWc1FxIgAdik 5S5AIAAA== X-Env-Sender: David.Kershner@unisys.com X-Msg-Ref: server-6.tower-75.messagelabs.com!1465420479!21744528!2 X-Originating-IP: [192.61.61.104] X-StarScan-Received: X-StarScan-Version: 8.46; banners=-,-,- X-VirusChecked: Checked From: David Kershner To: , , , , , , , , , , , , , , , , , , , , , CC: Tim Sell Subject: [PATCH v4 19/29] staging: unisys: visorbus: fix visorchannel.c comments Date: Wed, 8 Jun 2016 17:14:13 -0400 Message-ID: <1465420463-24982-20-git-send-email-david.kershner@unisys.com> X-Mailer: git-send-email 1.9.1 In-Reply-To: <1465420463-24982-1-git-send-email-david.kershner@unisys.com> References: <1465420463-24982-1-git-send-email-david.kershner@unisys.com> X-OriginalArrivalTime: 08 Jun 2016 21:14:29.0169 (UTC) FILETIME=[BE5BB210:01D1C1CA] MIME-Version: 1.0 Content-Type: text/plain Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org From: David Binder This patch ONLY touches comment lines, i.e., NO executable code is affected. Comments were fixed in visorchannel.c: * All functions worthy of documenting now use standard kerneldoc formatting. * Multi-line comments were tweaked so as to use appropriate conventions. * Minor typos were corrected. * Useless comments were removed. Signed-off-by: Tim Sell Signed-off-by: David Kershner Signed-off-by: David Binder --- drivers/staging/unisys/visorbus/visorchannel.c | 83 ++++++++++++++++++++++---- 1 file changed, 71 insertions(+), 12 deletions(-) diff --git a/drivers/staging/unisys/visorbus/visorchannel.c b/drivers/staging/unisys/visorbus/visorchannel.c index 1bfbc06..0ddfe05 100644 --- a/drivers/staging/unisys/visorbus/visorchannel.c +++ b/drivers/staging/unisys/visorbus/visorchannel.c @@ -15,7 +15,7 @@ */ /* - * This provides Supervisor channel communication primitives, which are + * This provides s-Par channel communication primitives, which are * independent of the mechanism used to access the channel data. */ @@ -55,8 +55,28 @@ struct visorchannel { uuid_le inst; }; -/* Creates the struct visorchannel abstraction for a data area in memory, - * but does NOT modify this data area. +/** + * visorchannel_create_guts() - creates the struct visorchannel abstraction + * for a data area in memory, but does NOT modify + * this data area + * @physaddr: physical address of start of channel + * @channel_bytes: size of the channel in bytes; this may 0 if the channel has + * already been initialized in memory (which is true for all + * channels provided to guest environments by the s-Par + * back-end), in which case the actual channel size will be + * read from the channel header in memory + * @gfp: gfp_t to use when allocating memory for the data struct + * @guid: uuid that identifies channel type; this may 0 if the channel + * has already been initialized in memory (which is true for all + * channels provided to guest environments by the s-Par + * back-end), in which case the actual channel guid will be + * read from the channel header in memory + * @needs_lock: must specify true if you have multiple threads of execution + * that will be calling visorchannel methods of this + * visorchannel at the same time + * + * Return: pointer to visorchannel that was created if successful, + * otherwise NULL */ static struct visorchannel * visorchannel_create_guts(u64 physaddr, unsigned long channel_bytes, @@ -77,7 +97,8 @@ visorchannel_create_guts(u64 physaddr, unsigned long channel_bytes, spin_lock_init(&channel->insert_lock); spin_lock_init(&channel->remove_lock); - /* Video driver constains the efi framebuffer so it will get a + /* + * Video driver constains the efi framebuffer so it will get a * conflict resource when requesting its full mem region. Since * we are only using the efi framebuffer for video we can ignore * this. Remember that we haven't requested it so we don't try to @@ -214,6 +235,12 @@ visorchannel_set_clientpartition(struct visorchannel *channel, return 0; } +/** + * visorchannel_get_uuid() - queries the UUID of the designated channel + * @channel: the channel to query + * + * Return: the UUID of the provided channel + */ uuid_le visorchannel_get_uuid(struct visorchannel *channel) { @@ -260,22 +287,25 @@ visorchannel_get_header(struct visorchannel *channel) return (void __iomem *)&channel->chan_hdr; } -/** Return offset of a specific SIGNAL_QUEUE_HEADER from the beginning of a - * channel header +/* + * Return offset of a specific SIGNAL_QUEUE_HEADER from the beginning of a + * channel header */ #define SIG_QUEUE_OFFSET(chan_hdr, q) \ ((chan_hdr)->ch_space_offset + \ ((q) * sizeof(struct signal_queue_header))) -/** Return offset of a specific queue entry (data) from the beginning of a - * channel header +/* + * Return offset of a specific queue entry (data) from the beginning of a + * channel header */ #define SIG_DATA_OFFSET(chan_hdr, q, sig_hdr, slot) \ (SIG_QUEUE_OFFSET(chan_hdr, q) + (sig_hdr)->sig_base_offset + \ ((slot) * (sig_hdr)->signal_size)) -/** Write the contents of a specific field within a SIGNAL_QUEUE_HEADER back - * into host memory +/* + * Write the contents of a specific field within a SIGNAL_QUEUE_HEADER back + * into host memory */ #define SIG_WRITE_FIELD(channel, queue, sig_hdr, FIELD) \ (visorchannel_write(channel, \ @@ -350,7 +380,8 @@ signalremove_inner(struct visorchannel *channel, u32 queue, void *msg) return false; sig_hdr.num_received++; - /* For each data field in SIGNAL_QUEUE_HEADER that was modified, + /* + * For each data field in SIGNAL_QUEUE_HEADER that was modified, * update host memory. */ mb(); /* required for channel synch */ @@ -361,6 +392,15 @@ signalremove_inner(struct visorchannel *channel, u32 queue, void *msg) return true; } +/** + * visorchannel_signalremove() - removes a message from the designated + * channel/queue + * @channel: the channel the message will be removed from + * @queue: the queue the message will be removed from + * @msg: the message to remove + * + * Return: boolean indicating whether the removal succeeded or failed + */ bool visorchannel_signalremove(struct visorchannel *channel, u32 queue, void *msg) { @@ -379,6 +419,15 @@ visorchannel_signalremove(struct visorchannel *channel, u32 queue, void *msg) } EXPORT_SYMBOL_GPL(visorchannel_signalremove); +/** + * visorchannel_signalempty() - checks if the designated channel/queue + * contains any messages + * @channel: the channel to query + * @queue: the queue in the channel to query + * + * Return: boolean indicating whether any messages in the designated + * channel/queue are present + */ bool visorchannel_signalempty(struct visorchannel *channel, u32 queue) { @@ -425,7 +474,8 @@ signalinsert_inner(struct visorchannel *channel, u32 queue, void *msg) sig_hdr.num_sent++; - /* For each data field in SIGNAL_QUEUE_HEADER that was modified, + /* + * For each data field in SIGNAL_QUEUE_HEADER that was modified, * update host memory. */ mb(); /* required for channel synch */ @@ -437,6 +487,15 @@ signalinsert_inner(struct visorchannel *channel, u32 queue, void *msg) return true; } +/** + * visorchannel_signalinsert() - inserts a message into the designated + * channel/queue + * @channel: the channel the message will be added to + * @queue: the queue the message will be added to + * @msg: the message to insert + * + * Return: boolean indicating whether the insertion succeeded or failed + */ bool visorchannel_signalinsert(struct visorchannel *channel, u32 queue, void *msg) { -- 1.9.1