GitHub-Mirror/linux-bl808
2
0
Fork 0
mirror of https://github.com/Fishwaldo/linux-bl808.git synced 2025-06-17 20:25:19 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

ipmi: Clean up comments in include files.

Browse source 
Make the comments correct and consistent.

Signed-off-by: Corey Minyard <cminyard@mvista.com>
This commit is contained in:
Corey Minyard 2018-04-04 08:54:05 -05:00
parent c81c5fc212
commit 6dc1181f9f
2 changed files with 134 additions and 86 deletions
Download patch file Download diff file Expand all files Collapse all files

105
include/linux/ipmi.h
View file

@ -23,8 +23,10 @@
struct module; struct module;
struct device; struct device;
/* Opaque type for a IPMI message user. One of these is needed to /*
send and receive messages. */ * Opaque type for a IPMI message user. One of these is needed to
* send and receive messages.
*/
typedef struct ipmi_user *ipmi_user_t; typedef struct ipmi_user *ipmi_user_t;
/* /*
@ -37,8 +39,10 @@ typedef struct ipmi_user *ipmi_user_t;
struct ipmi_recv_msg { struct ipmi_recv_msg {
struct list_head link; struct list_head link;
/* The type of message as defined in the "Receive Types" /*
defines above. */ * The type of message as defined in the "Receive Types"
* defines above.
*/
int recv_type; int recv_type;
ipmi_user_t user; ipmi_user_t user;
@ -46,19 +50,25 @@ struct ipmi_recv_msg {
long msgid; long msgid;
struct kernel_ipmi_msg msg; struct kernel_ipmi_msg msg;
/* The user_msg_data is the data supplied when a message was /*
sent, if this is a response to a sent message. If this is * The user_msg_data is the data supplied when a message was
not a response to a sent message, then user_msg_data will * sent, if this is a response to a sent message. If this is
be NULL. If the user above is NULL, then this will be the * not a response to a sent message, then user_msg_data will
intf. */ * be NULL. If the user above is NULL, then this will be the
* intf.
*/
void *user_msg_data; void *user_msg_data;
/* Call this when done with the message. It will presumably free /*
the message and do any other necessary cleanup. */ * Call this when done with the message. It will presumably free
* the message and do any other necessary cleanup.
*/
void (*done)(struct ipmi_recv_msg *msg); void (*done)(struct ipmi_recv_msg *msg);
/* Place-holder for the data, don't make any assumptions about /*
the size or existence of this, since it may change. */ * Place-holder for the data, don't make any assumptions about
* the size or existence of this, since it may change.
*/
unsigned char msg_data[IPMI_MAX_MSG_LENGTH]; unsigned char msg_data[IPMI_MAX_MSG_LENGTH];
}; };
@ -66,16 +76,20 @@ struct ipmi_recv_msg {
void ipmi_free_recv_msg(struct ipmi_recv_msg *msg); void ipmi_free_recv_msg(struct ipmi_recv_msg *msg);
struct ipmi_user_hndl { struct ipmi_user_hndl {
/* Routine type to call when a message needs to be routed to /*
the upper layer. This will be called with some locks held, * Routine type to call when a message needs to be routed to
the only IPMI routines that can be called are ipmi_request * the upper layer. This will be called with some locks held,
and the alloc/free operations. The handler_data is the * the only IPMI routines that can be called are ipmi_request
variable supplied when the receive handler was registered. */ * and the alloc/free operations. The handler_data is the
* variable supplied when the receive handler was registered.
*/
void (*ipmi_recv_hndl)(struct ipmi_recv_msg *msg, void (*ipmi_recv_hndl)(struct ipmi_recv_msg *msg,
void *user_msg_data); void *user_msg_data);
/* Called when the interface detects a watchdog pre-timeout. If /*
this is NULL, it will be ignored for the user. */ * Called when the interface detects a watchdog pre-timeout. If
* this is NULL, it will be ignored for the user.
*/
void (*ipmi_watchdog_pretimeout)(void *handler_data); void (*ipmi_watchdog_pretimeout)(void *handler_data);
/* /*
@ -91,12 +105,14 @@ int ipmi_create_user(unsigned int if_num,
void *handler_data, void *handler_data,
ipmi_user_t *user); ipmi_user_t *user);
/* Destroy the given user of the IPMI layer. Note that after this /*
function returns, the system is guaranteed to not call any * Destroy the given user of the IPMI layer. Note that after this
callbacks for the user. Thus as long as you destroy all the users * function returns, the system is guaranteed to not call any
before you unload a module, you will be safe. And if you destroy * callbacks for the user. Thus as long as you destroy all the users
the users before you destroy the callback structures, it should be * before you unload a module, you will be safe. And if you destroy
safe, too. */ * the users before you destroy the callback structures, it should be
* safe, too.
*/
int ipmi_destroy_user(ipmi_user_t user); int ipmi_destroy_user(ipmi_user_t user);
/* Get the IPMI version of the BMC we are talking to. */ /* Get the IPMI version of the BMC we are talking to. */
@ -104,12 +120,15 @@ int ipmi_get_version(ipmi_user_t user,
unsigned char *major, unsigned char *major,
unsigned char *minor); unsigned char *minor);
/* Set and get the slave address and LUN that we will use for our /*
source messages. Note that this affects the interface, not just * Set and get the slave address and LUN that we will use for our
this user, so it will affect all users of this interface. This is * source messages. Note that this affects the interface, not just
so some initialization code can come in and do the OEM-specific * this user, so it will affect all users of this interface. This is
things it takes to determine your address (if not the BMC) and set * so some initialization code can come in and do the OEM-specific
it for everyone else. Note that each channel can have its own address. */ * things it takes to determine your address (if not the BMC) and set
* it for everyone else. Note that each channel can have its own
* address.
*/
int ipmi_set_my_address(ipmi_user_t user, int ipmi_set_my_address(ipmi_user_t user,
unsigned int channel, unsigned int channel,
unsigned char address); unsigned char address);
@ -235,14 +254,18 @@ int ipmi_set_gets_events(ipmi_user_t user, bool val);
struct ipmi_smi_watcher { struct ipmi_smi_watcher {
struct list_head link; struct list_head link;
/* You must set the owner to the current module, if you are in /*
a module (generally just set it to "THIS_MODULE"). */ * You must set the owner to the current module, if you are in
* a module (generally just set it to "THIS_MODULE").
*/
struct module *owner; struct module *owner;
/* These two are called with read locks held for the interface /*
the watcher list. So you can add and remove users from the * These two are called with read locks held for the interface
IPMI interface, send messages, etc., but you cannot add * the watcher list. So you can add and remove users from the
or remove SMI watchers or SMI interfaces. */ * IPMI interface, send messages, etc., but you cannot add
* or remove SMI watchers or SMI interfaces.
*/
void (*new_smi)(int if_num, struct device *dev); void (*new_smi)(int if_num, struct device *dev);
void (*smi_gone)(int if_num); void (*smi_gone)(int if_num);
}; };
@ -250,8 +273,10 @@ struct ipmi_smi_watcher {
int ipmi_smi_watcher_register(struct ipmi_smi_watcher *watcher); int ipmi_smi_watcher_register(struct ipmi_smi_watcher *watcher);
int ipmi_smi_watcher_unregister(struct ipmi_smi_watcher *watcher); int ipmi_smi_watcher_unregister(struct ipmi_smi_watcher *watcher);
/* The following are various helper functions for dealing with IPMI /*
addresses. */ * The following are various helper functions for dealing with IPMI
* addresses.
*/
/* Return the maximum length of an IPMI address given it's type. */ /* Return the maximum length of an IPMI address given it's type. */
unsigned int ipmi_addr_length(int addr_type); unsigned int ipmi_addr_length(int addr_type);

115
include/linux/ipmi_smi.h
View file

@ -22,8 +22,10 @@
struct device; struct device;
/* This files describes the interface for IPMI system management interface /*
drivers to bind into the IPMI message handler. */ * This files describes the interface for IPMI system management interface
* drivers to bind into the IPMI message handler.
*/
/* Structure for the low-level drivers. */ /* Structure for the low-level drivers. */
typedef struct ipmi_smi *ipmi_smi_t; typedef struct ipmi_smi *ipmi_smi_t;
@ -61,10 +63,12 @@ struct ipmi_smi_msg {
struct ipmi_smi_handlers { struct ipmi_smi_handlers {
struct module *owner; struct module *owner;
/* The low-level interface cannot start sending messages to /*
the upper layer until this function is called. This may * The low-level interface cannot start sending messages to
not be NULL, the lower layer must take the interface from * the upper layer until this function is called. This may
this call. */ * not be NULL, the lower layer must take the interface from
* this call.
*/
int (*start_processing)(void *send_info, int (*start_processing)(void *send_info,
ipmi_smi_t new_intf); ipmi_smi_t new_intf);
@ -75,25 +79,31 @@ struct ipmi_smi_handlers {
*/ */
int (*get_smi_info)(void *send_info, struct ipmi_smi_info *data); int (*get_smi_info)(void *send_info, struct ipmi_smi_info *data);
/* Called to enqueue an SMI message to be sent. This /*
operation is not allowed to fail. If an error occurs, it * Called to enqueue an SMI message to be sent. This
should report back the error in a received message. It may * operation is not allowed to fail. If an error occurs, it
do this in the current call context, since no write locks * should report back the error in a received message. It may
are held when this is run. Message are delivered one at * do this in the current call context, since no write locks
a time by the message handler, a new message will not be * are held when this is run. Message are delivered one at
delivered until the previous message is returned. */ * a time by the message handler, a new message will not be
* delivered until the previous message is returned.
*/
void (*sender)(void *send_info, void (*sender)(void *send_info,
struct ipmi_smi_msg *msg); struct ipmi_smi_msg *msg);
/* Called by the upper layer to request that we try to get /*
events from the BMC we are attached to. */ * Called by the upper layer to request that we try to get
* events from the BMC we are attached to.
*/
void (*request_events)(void *send_info); void (*request_events)(void *send_info);
/* Called by the upper layer when some user requires that the /*
interface watch for events, received messages, watchdog * Called by the upper layer when some user requires that the
pretimeouts, or not. Used by the SMI to know if it should * interface watch for events, received messages, watchdog
watch for these. This may be NULL if the SMI does not * pretimeouts, or not. Used by the SMI to know if it should
implement it. */ * watch for these. This may be NULL if the SMI does not
* implement it.
*/
void (*set_need_watch)(void *send_info, bool enable); void (*set_need_watch)(void *send_info, bool enable);
/* /*
@ -101,28 +111,36 @@ struct ipmi_smi_handlers {
*/ */
void (*flush_messages)(void *send_info); void (*flush_messages)(void *send_info);
/* Called when the interface should go into "run to /*
completion" mode. If this call sets the value to true, the * Called when the interface should go into "run to
interface should make sure that all messages are flushed * completion" mode. If this call sets the value to true, the
out and that none are pending, and any new requests are run * interface should make sure that all messages are flushed
to completion immediately. */ * out and that none are pending, and any new requests are run
* to completion immediately.
*/
void (*set_run_to_completion)(void *send_info, bool run_to_completion); void (*set_run_to_completion)(void *send_info, bool run_to_completion);
/* Called to poll for work to do. This is so upper layers can /*
poll for operations during things like crash dumps. */ * Called to poll for work to do. This is so upper layers can
* poll for operations during things like crash dumps.
*/
void (*poll)(void *send_info); void (*poll)(void *send_info);
/* Enable/disable firmware maintenance mode. Note that this /*
is *not* the modes defined, this is simply an on/off * Enable/disable firmware maintenance mode. Note that this
setting. The message handler does the mode handling. Note * is *not* the modes defined, this is simply an on/off
that this is called from interrupt context, so it cannot * setting. The message handler does the mode handling. Note
block. */ * that this is called from interrupt context, so it cannot
* block.
*/
void (*set_maintenance_mode)(void *send_info, bool enable); void (*set_maintenance_mode)(void *send_info, bool enable);
/* Tell the handler that we are using it/not using it. The /*
message handler get the modules that this handler belongs * Tell the handler that we are using it/not using it. The
to; this function lets the SMI claim any modules that it * message handler get the modules that this handler belongs
uses. These may be NULL if this is not required. */ * to; this function lets the SMI claim any modules that it
* uses. These may be NULL if this is not required.
*/
int (*inc_usecount)(void *send_info); int (*inc_usecount)(void *send_info);
void (*dec_usecount)(void *send_info); void (*dec_usecount)(void *send_info);
}; };
@ -143,7 +161,8 @@ struct ipmi_device_id {
#define ipmi_version_major(v) ((v)->ipmi_version & 0xf) #define ipmi_version_major(v) ((v)->ipmi_version & 0xf)
#define ipmi_version_minor(v) ((v)->ipmi_version >> 4) #define ipmi_version_minor(v) ((v)->ipmi_version >> 4)
/* Take a pointer to an IPMI response and extract device id information from /*
* Take a pointer to an IPMI response and extract device id information from
* it. @netfn is in the IPMI_NETFN_ format, so may need to be shifted from * it. @netfn is in the IPMI_NETFN_ format, so may need to be shifted from
* a SI response. * a SI response.
*/ */
@ -187,12 +206,14 @@ static inline int ipmi_demangle_device_id(uint8_t netfn, uint8_t cmd,
return 0; return 0;
} }
/* Add a low-level interface to the IPMI driver. Note that if the /*
interface doesn't know its slave address, it should pass in zero. * Add a low-level interface to the IPMI driver. Note that if the
The low-level interface should not deliver any messages to the * interface doesn't know its slave address, it should pass in zero.
upper layer until the start_processing() function in the handlers * The low-level interface should not deliver any messages to the
is called, and the lower layer must get the interface from that * upper layer until the start_processing() function in the handlers
call. */ * is called, and the lower layer must get the interface from that
* call.
*/
int ipmi_register_smi(const struct ipmi_smi_handlers *handlers, int ipmi_register_smi(const struct ipmi_smi_handlers *handlers,
void *send_info, void *send_info,
struct device *dev, struct device *dev,
@ -223,9 +244,11 @@ static inline void ipmi_free_smi_msg(struct ipmi_smi_msg *msg)
} }
#ifdef CONFIG_IPMI_PROC_INTERFACE #ifdef CONFIG_IPMI_PROC_INTERFACE
/* Allow the lower layer to add things to the proc filesystem /*
directory for this interface. Note that the entry will * Allow the lower layer to add things to the proc filesystem
automatically be dstroyed when the interface is destroyed. */ * directory for this interface. Note that the entry will
* automatically be dstroyed when the interface is destroyed.
*/
int ipmi_smi_add_proc_entry(ipmi_smi_t smi, char *name, int ipmi_smi_add_proc_entry(ipmi_smi_t smi, char *name,
const struct file_operations *proc_ops, const struct file_operations *proc_ops,
void *data); void *data);