Skip to content

Commit

Permalink
mei: fix KDoc documentation formatting
Browse files Browse the repository at this point in the history 
Fix Kdoc documentation formatting warnings
genertaed by ./scripts/kernel-doc

Signed-off-by: Alexander Usyskin <alexander.usyskin@intel.com>
Signed-off-by: Tomas Winkler <tomas.winkler@intel.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
  • Loading branch information
Alexander Usyskin authored and Greg Kroah-Hartman committed Sep 29, 2014
1 parent 764c065 commit a8605ea
Show file tree
Hide file tree
Showing 15 changed files with 243 additions and 225 deletions.
30 changes: 13 additions & 17 deletions drivers/misc/mei/amthif.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ int mei_amthif_host_init(struct mei_device *dev)
* @dev: the device structure
* @file: pointer to file object
*
* returns returned a list entry on success, NULL on failure.
* Return: returned a list entry on success, NULL on failure.
*/
struct mei_cl_cb *mei_amthif_find_read_list_entry(struct mei_device *dev,
struct file *file)
Expand All @@ -140,15 +140,14 @@ struct mei_cl_cb *mei_amthif_find_read_list_entry(struct mei_device *dev,
* mei_amthif_read - read data from AMTHIF client
*
* @dev: the device structure
* @if_num: minor number
* @file: pointer to file object
* @*ubuf: pointer to user data in user space
* @ubuf: pointer to user data in user space
* @length: data length to read
* @offset: data read offset
*
* Locking: called under "dev->device_lock" lock
*
* returns
* Return:
* returned data length on success,
* zero if no data to read,
* negative on failure.
Expand Down Expand Up @@ -256,7 +255,7 @@ int mei_amthif_read(struct mei_device *dev, struct file *file,
* @dev: the device structure
* @cb: mei call back struct
*
* returns 0 on success, <0 on failure.
* Return: 0 on success, <0 on failure.
*
*/
static int mei_amthif_send_cmd(struct mei_device *dev, struct mei_cl_cb *cb)
Expand Down Expand Up @@ -326,7 +325,7 @@ static int mei_amthif_send_cmd(struct mei_device *dev, struct mei_cl_cb *cb)
* @dev: the device structure
* @cb: mei call back struct
*
* returns 0 on success, <0 on failure.
* Return: 0 on success, <0 on failure.
*
*/
int mei_amthif_write(struct mei_device *dev, struct mei_cl_cb *cb)
Expand Down Expand Up @@ -356,8 +355,6 @@ int mei_amthif_write(struct mei_device *dev, struct mei_cl_cb *cb)
* mei_amthif_run_next_cmd
*
* @dev: the device structure
*
* returns 0 on success, <0 on failure.
*/
void mei_amthif_run_next_cmd(struct mei_device *dev)
{
Expand Down Expand Up @@ -420,12 +417,11 @@ unsigned int mei_amthif_poll(struct mei_device *dev,
/**
* mei_amthif_irq_write - write iamthif command in irq thread context.
*
* @dev: the device structure.
* @cb_pos: callback block.
* @cl: private data of the file object.
* @cb: callback block.
* @cmpl_list: complete list.
*
* returns 0, OK; otherwise, error.
* Return: 0, OK; otherwise, error.
*/
int mei_amthif_irq_write(struct mei_cl *cl, struct mei_cl_cb *cb,
struct mei_cl_cb *cmpl_list)
Expand Down Expand Up @@ -507,7 +503,7 @@ int mei_amthif_irq_write(struct mei_cl *cl, struct mei_cl_cb *cb,
* @mei_hdr: header of amthif message
* @complete_list: An instance of our list structure
*
* returns 0 on success, <0 on failure.
* Return: 0 on success, <0 on failure.
*/
int mei_amthif_irq_read_msg(struct mei_device *dev,
struct mei_msg_hdr *mei_hdr,
Expand Down Expand Up @@ -560,7 +556,7 @@ int mei_amthif_irq_read_msg(struct mei_device *dev,
* @dev: the device structure.
* @slots: free slots.
*
* returns 0, OK; otherwise, error.
* Return: 0, OK; otherwise, error.
*/
int mei_amthif_irq_read(struct mei_device *dev, s32 *slots)
{
Expand Down Expand Up @@ -590,7 +586,7 @@ int mei_amthif_irq_read(struct mei_device *dev, s32 *slots)
* mei_amthif_complete - complete amthif callback.
*
* @dev: the device structure.
* @cb_pos: callback block.
* @cb: callback block.
*/
void mei_amthif_complete(struct mei_device *dev, struct mei_cl_cb *cb)
{
Expand Down Expand Up @@ -624,7 +620,7 @@ void mei_amthif_complete(struct mei_device *dev, struct mei_cl_cb *cb)
* mei_clear_list is called to clear resources associated with file
* when application calls close function or Ctrl-C was pressed
*
* returns true if callback removed from the list, false otherwise
* Return: true if callback removed from the list, false otherwise
*/
static bool mei_clear_list(struct mei_device *dev,
const struct file *file, struct list_head *mei_cb_list)
Expand Down Expand Up @@ -664,7 +660,7 @@ static bool mei_clear_list(struct mei_device *dev,
* mei_clear_lists is called to clear resources associated with file
* when application calls close function or Ctrl-C was pressed
*
* returns true if callback removed from the list, false otherwise
* Return: true if callback removed from the list, false otherwise
*/
static bool mei_clear_lists(struct mei_device *dev, struct file *file)
{
Expand Down Expand Up @@ -705,7 +701,7 @@ static bool mei_clear_lists(struct mei_device *dev, struct file *file)
* @dev: device structure
* @file: pointer to file structure
*
* returns 0 on success, <0 on error
* Return: 0 on success, <0 on error
*/
int mei_amthif_release(struct mei_device *dev, struct file *file)
{
Expand Down
70 changes: 41 additions & 29 deletions drivers/misc/mei/client.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,13 +27,14 @@
#include "client.h"

/**
* mei_me_cl_by_uuid - locate index of me client
* mei_me_cl_by_uuid - locate me client by uuid
*
* @dev: mei device
* @uuid: me client uuid
*
* Locking: called under "dev->device_lock" lock
*
* returns me client or NULL if not found
* Return: me client or NULL if not found
*/
struct mei_me_client *mei_me_cl_by_uuid(const struct mei_device *dev,
const uuid_le *uuid)
Expand All @@ -48,16 +49,15 @@ struct mei_me_client *mei_me_cl_by_uuid(const struct mei_device *dev,
}

/**
* mei_me_cl_by_id return index to me_clients for client_id
* mei_me_cl_by_id - locate me client by client id
*
* @dev: the device structure
* @client_id: me client id
*
* Locking: called under "dev->device_lock" lock
*
* returns me client or NULL if not found
* Return: me client or NULL if not found
*/

struct mei_me_client *mei_me_cl_by_id(struct mei_device *dev, u8 client_id)
{

Expand All @@ -69,6 +69,17 @@ struct mei_me_client *mei_me_cl_by_id(struct mei_device *dev, u8 client_id)
return NULL;
}

/**
* mei_me_cl_by_uuid_id - locate me client by client id and uuid
*
* @dev: the device structure
* @uuid: me client uuid
* @client_id: me client id
*
* Locking: called under "dev->device_lock" lock
*
* Return: me client or NULL if not found
*/
struct mei_me_client *mei_me_cl_by_uuid_id(struct mei_device *dev,
const uuid_le *uuid, u8 client_id)
{
Expand Down Expand Up @@ -109,7 +120,7 @@ void mei_me_cl_remove(struct mei_device *dev, const uuid_le *uuid, u8 client_id)
* @cl1: host client 1
* @cl2: host client 2
*
* returns true - if the clients has same host and me ids
* Return: true - if the clients has same host and me ids
* false - otherwise
*/
static inline bool mei_cl_cmp_id(const struct mei_cl *cl1,
Expand Down Expand Up @@ -184,10 +195,10 @@ void mei_io_cb_free(struct mei_cl_cb *cb)
/**
* mei_io_cb_init - allocate and initialize io callback
*
* @cl - mei client
* @cl: mei client
* @fp: pointer to file structure
*
* returns mei_cl_cb pointer or NULL;
* Return: mei_cl_cb pointer or NULL;
*/
struct mei_cl_cb *mei_io_cb_init(struct mei_cl *cl, struct file *fp)
{
Expand All @@ -211,7 +222,7 @@ struct mei_cl_cb *mei_io_cb_init(struct mei_cl *cl, struct file *fp)
* @cb: io callback structure
* @length: size of the buffer
*
* returns 0 on success
* Return: 0 on success
* -EINVAL if cb is NULL
* -ENOMEM if allocation failed
*/
Expand All @@ -235,7 +246,7 @@ int mei_io_cb_alloc_req_buf(struct mei_cl_cb *cb, size_t length)
* @cb: io callback structure
* @length: size of the buffer
*
* returns 0 on success
* Return: 0 on success
* -EINVAL if cb is NULL
* -ENOMEM if allocation failed
*/
Expand Down Expand Up @@ -305,7 +316,7 @@ void mei_cl_init(struct mei_cl *cl, struct mei_device *dev)
* mei_cl_allocate - allocates cl structure and sets it up.
*
* @dev: mei device
* returns The allocated file or NULL on failure
* Return: The allocated file or NULL on failure
*/
struct mei_cl *mei_cl_allocate(struct mei_device *dev)
{
Expand All @@ -325,7 +336,7 @@ struct mei_cl *mei_cl_allocate(struct mei_device *dev)
*
* @cl: host client
*
* returns cb on success, NULL on error
* Return: cb on success, NULL on error
*/
struct mei_cl_cb *mei_cl_find_read_cb(struct mei_cl *cl)
{
Expand All @@ -343,7 +354,7 @@ struct mei_cl_cb *mei_cl_find_read_cb(struct mei_cl *cl)
* @cl - host client
* @id - fixed host id or -1 for generic one
*
* returns 0 on success
* Return: 0 on success
* -EINVAL on incorrect values
* -ENONET if client not found
*/
Expand Down Expand Up @@ -455,10 +466,10 @@ void mei_host_client_init(struct work_struct *work)
}

/**
* mei_hbuf_acquire: try to acquire host buffer
* mei_hbuf_acquire - try to acquire host buffer
*
* @dev: the device structure
* returns true if host buffer was acquired
* Return: true if host buffer was acquired
*/
bool mei_hbuf_acquire(struct mei_device *dev)
{
Expand All @@ -485,7 +496,7 @@ bool mei_hbuf_acquire(struct mei_device *dev)
*
* Locking: called under "dev->device_lock" lock
*
* returns 0 on success, <0 on failure.
* Return: 0 on success, <0 on failure.
*/
int mei_cl_disconnect(struct mei_cl *cl)
{
Expand Down Expand Up @@ -566,7 +577,7 @@ int mei_cl_disconnect(struct mei_cl *cl)
*
* @cl: private data of the file object
*
* returns true if other client is connected, false - otherwise.
* Return: true if other client is connected, false - otherwise.
*/
bool mei_cl_is_other_connecting(struct mei_cl *cl)
{
Expand All @@ -593,10 +604,11 @@ bool mei_cl_is_other_connecting(struct mei_cl *cl)
* mei_cl_connect - connect host client to the me one
*
* @cl: host client
* @file: pointer to file structure
*
* Locking: called under "dev->device_lock" lock
*
* returns 0 on success, <0 on failure.
* Return: 0 on success, <0 on failure.
*/
int mei_cl_connect(struct mei_cl *cl, struct file *file)
{
Expand Down Expand Up @@ -671,7 +683,7 @@ int mei_cl_connect(struct mei_cl *cl, struct file *file)
*
* @cl: private data of the file object
*
* returns 1 if mei_flow_ctrl_creds >0, 0 - otherwise.
* Return: 1 if mei_flow_ctrl_creds >0, 0 - otherwise.
* -ENOENT if mei_cl is not present
* -EINVAL if single_recv_buf == 0
*/
Expand Down Expand Up @@ -707,7 +719,7 @@ int mei_cl_flow_ctrl_creds(struct mei_cl *cl)
*
* @cl: private data of the file object
*
* @returns
* Return:
* 0 on success
* -ENOENT when me client is not found
* -EINVAL when ctrl credits are <= 0
Expand Down Expand Up @@ -745,7 +757,7 @@ int mei_cl_flow_ctrl_reduce(struct mei_cl *cl)
*
* @cl: host client
*
* returns 0 on success, <0 on failure.
* Return: 0 on success, <0 on failure.
*/
int mei_cl_read_start(struct mei_cl *cl, size_t length)
{
Expand Down Expand Up @@ -823,7 +835,7 @@ int mei_cl_read_start(struct mei_cl *cl, size_t length)
* @cb: callback block.
* @cmpl_list: complete list.
*
* returns 0, OK; otherwise error.
* Return: 0, OK; otherwise error.
*/
int mei_cl_irq_write(struct mei_cl *cl, struct mei_cl_cb *cb,
struct mei_cl_cb *cmpl_list)
Expand Down Expand Up @@ -900,12 +912,12 @@ int mei_cl_irq_write(struct mei_cl *cl, struct mei_cl_cb *cb,

/**
* mei_cl_write - submit a write cb to mei device
assumes device_lock is locked
* assumes device_lock is locked
*
* @cl: host client
* @cl: write callback with filled data
* @cb: write callback with filled data
*
* returns number of bytes sent on success, <0 on failure.
* Return: number of bytes sent on success, <0 on failure.
*/
int mei_cl_write(struct mei_cl *cl, struct mei_cl_cb *cb, bool blocking)
{
Expand Down Expand Up @@ -1042,7 +1054,7 @@ void mei_cl_complete(struct mei_cl *cl, struct mei_cl_cb *cb)
/**
* mei_cl_all_disconnect - disconnect forcefully all connected clients
*
* @dev - mei device
* @dev: mei device
*/

void mei_cl_all_disconnect(struct mei_device *dev)
Expand All @@ -1060,7 +1072,7 @@ void mei_cl_all_disconnect(struct mei_device *dev)
/**
* mei_cl_all_wakeup - wake up all readers and writers they can be interrupted
*
* @dev - mei device
* @dev: mei device
*/
void mei_cl_all_wakeup(struct mei_device *dev)
{
Expand All @@ -1080,8 +1092,8 @@ void mei_cl_all_wakeup(struct mei_device *dev)

/**
* mei_cl_all_write_clear - clear all pending writes
* @dev - mei device
*
* @dev: mei device
*/
void mei_cl_all_write_clear(struct mei_device *dev)
{
Expand Down
7 changes: 5 additions & 2 deletions drivers/misc/mei/debugfs.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -161,7 +161,8 @@ static const struct file_operations mei_dbgfs_fops_devstate = {

/**
* mei_dbgfs_deregister - Remove the debugfs files and directories
* @mei - pointer to mei device private data
*
* @dev: the mei device structure
*/
void mei_dbgfs_deregister(struct mei_device *dev)
{
Expand All @@ -172,8 +173,10 @@ void mei_dbgfs_deregister(struct mei_device *dev)
}

/**
* Add the debugfs files
* mei_dbgfs_register - Add the debugfs files
*
* @dev: the mei device structure
* @name: the mei device name
*/
int mei_dbgfs_register(struct mei_device *dev, const char *name)
{
Expand Down
Loading

0 comments on commit a8605ea

Please sign in to comment.