Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit e19674ce authored by David Binder's avatar David Binder Committed by Greg Kroah-Hartman
Browse files

staging: unisys: visorbus: fix visorchannel.c comments 



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: default avatarTim Sell <Timothy.Sell@unisys.com>
Signed-off-by: default avatarDavid Kershner <david.kershner@unisys.com>
Signed-off-by: default avatarDavid Binder <david.binder@unisys.com>
Acked-By: default avatarNeil Horman <nhorman@tuxdriver.com>
Reviewed-by: default avatarThomas Gleixner <tglx@linutronix.de>
Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent 3fd1b3b6

drivers/staging/unisys/visorbus/visorchannel.c

+71 −12
Original line number Diff line number Diff line
@@ -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,21 +287,24 @@ 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

/*

 * 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

/*

 * 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

/*

 * 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)			 \
@@ -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)

{