ipmi: Clean up comments in include files.

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;

/*

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;

	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];

};

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);

	/*

		     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. */

		     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);

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);

};

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);

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;

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);

	 */

	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);

	/*

	 */

	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);

};

#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.

 */

	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,

}

#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);