Skip to content

L
linux
Commit 6dc1181f authored by Corey Minyard's avatar Corey Minyard
Browse files
Options

ipmi: Clean up comments in include files. 

Make the comments correct and consistent.
Signed-off-by: default avatarCorey Minyard <cminyard@mvista.com>
parent c81c5fc2
Hide whitespace changes
Inline Side-by-side
Showing with 134 additions and 86 deletions
include/linux/ipmi.h
View file @ 6dc1181f
......@@ -23,8 +23,10 @@
struct module;
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;
/*
......@@ -37,8 +39,10 @@ typedef struct ipmi_user *ipmi_user_t;
struct ipmi_recv_msg {
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;
ipmi_user_t user;
......@@ -46,19 +50,25 @@ struct ipmi_recv_msg {
long msgid;
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
not a response to a sent message, then user_msg_data will
be NULL. If the user above is NULL, then this will be the
intf. */
/*
* 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
* not a response to a sent message, then user_msg_data will
* be NULL. If the user above is NULL, then this will be the
* intf.
*/
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);
/* 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];
};
......@@ -66,16 +76,20 @@ struct ipmi_recv_msg {
void ipmi_free_recv_msg(struct ipmi_recv_msg *msg);
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,
the only IPMI routines that can be called are ipmi_request
and the alloc/free operations. The handler_data is the
variable supplied when the receive handler was registered. */
/*
* Routine type to call when a message needs to be routed to
* the upper layer. This will be called with some locks held,
* the only IPMI routines that can be called are ipmi_request
* 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 *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);
/*
......@@ -91,12 +105,14 @@ int ipmi_create_user(unsigned int if_num,
void *handler_data,
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
callbacks for the user. Thus as long as you destroy all the users
before you unload a module, you will be safe. And if you destroy
the users before you destroy the callback structures, it should be
safe, too. */
/*
* Destroy the given user of the IPMI layer. Note that after this
* function returns, the system is guaranteed to not call any
* callbacks for the user. Thus as long as you destroy all the users
* before you unload a module, you will be safe. And if you destroy
* the users before you destroy the callback structures, it should be
* safe, too.
*/
int ipmi_destroy_user(ipmi_user_t user);
/* 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 *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
this user, so it will affect all users of this interface. This is
so some initialization code can come in and do the OEM-specific
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. */
/*
* Set and get the slave address and LUN that we will use for our
* source messages. Note that this affects the interface, not just
* this user, so it will affect all users of this interface. This is
* so some initialization code can come in and do the OEM-specific
* 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,
unsigned int channel,
unsigned char address);
......@@ -235,14 +254,18 @@ int ipmi_set_gets_events(ipmi_user_t user, bool val);
struct ipmi_smi_watcher {
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;
/* These two are called with read locks held for the interface
the watcher list. So you can add and remove users from the
IPMI interface, send messages, etc., but you cannot add
or remove SMI watchers or SMI interfaces. */
/*
* These two are called with read locks held for the interface
* the watcher list. So you can add and remove users from the
* 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 (*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_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. */
unsigned int ipmi_addr_length(int addr_type);
......
include/linux/ipmi_smi.h
View file @ 6dc1181f
......@@ -22,8 +22,10 @@
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. */
typedef struct ipmi_smi *ipmi_smi_t;
......@@ -61,10 +63,12 @@ struct ipmi_smi_msg {
struct ipmi_smi_handlers {
struct module *owner;
/* The low-level interface cannot start sending messages to
the upper layer until this function is called. This may
not be NULL, the lower layer must take the interface from
this call. */
/*
* The low-level interface cannot start sending messages to
* the upper layer until this function is called. This may
* not be NULL, the lower layer must take the interface from
* this call.
*/
int (*start_processing)(void *send_info,
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);
/* Called to enqueue an SMI message to be sent. This
operation is not allowed to fail. If an error occurs, it
should report back the error in a received message. It may
do this in the current call context, since no write locks
are held when this is run. Message are delivered one at
a time by the message handler, a new message will not be
delivered until the previous message is returned. */
/*
* Called to enqueue an SMI message to be sent. This
* operation is not allowed to fail. If an error occurs, it
* should report back the error in a received message. It may
* do this in the current call context, since no write locks
* are held when this is run. Message are delivered one at
* a time by the message handler, a new message will not be
* delivered until the previous message is returned.
*/
void (*sender)(void *send_info,
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);
/* Called by the upper layer when some user requires that the
interface watch for events, received messages, watchdog
pretimeouts, or not. Used by the SMI to know if it should
watch for these. This may be NULL if the SMI does not
implement it. */
/*
* Called by the upper layer when some user requires that the
* interface watch for events, received messages, watchdog
* pretimeouts, or not. Used by the SMI to know if it should
* watch for these. This may be NULL if the SMI does not
* implement it.
*/
void (*set_need_watch)(void *send_info, bool enable);
/*
......@@ -101,28 +111,36 @@ struct ipmi_smi_handlers {
*/
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
interface should make sure that all messages are flushed
out and that none are pending, and any new requests are run
to completion immediately. */
/*
* Called when the interface should go into "run to
* completion" mode. If this call sets the value to true, the
* interface should make sure that all messages are flushed
* 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);
/* 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);
/* Enable/disable firmware maintenance mode. Note that this
is *not* the modes defined, this is simply an on/off
setting. The message handler does the mode handling. Note
that this is called from interrupt context, so it cannot
block. */
/*
* Enable/disable firmware maintenance mode. Note that this
* is *not* the modes defined, this is simply an on/off
* setting. The message handler does the mode handling. Note
* that this is called from interrupt context, so it cannot
* block.
*/
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
to; this function lets the SMI claim any modules that it
uses. These may be NULL if this is not required. */
/*
* Tell the handler that we are using it/not using it. The
* message handler get the modules that this handler belongs
* 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);
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_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
* a SI response.
*/
......@@ -187,12 +206,14 @@ static inline int ipmi_demangle_device_id(uint8_t netfn, uint8_t cmd,
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.
The low-level interface should not deliver any messages to the
upper layer until the start_processing() function in the handlers
is called, and the lower layer must get the interface from that
call. */
/*
* 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.
* The low-level interface should not deliver any messages to the
* upper layer until the start_processing() function in the handlers
* is called, and the lower layer must get the interface from that
* call.
*/
int ipmi_register_smi(const struct ipmi_smi_handlers *handlers,
void *send_info,
struct device *dev,
......@@ -223,9 +244,11 @@ static inline void ipmi_free_smi_msg(struct ipmi_smi_msg *msg)
}
#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
automatically be dstroyed when the interface is destroyed. */
/*
* Allow the lower layer to add things to the proc filesystem
* 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,
const struct file_operations *proc_ops,
void *data);
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7