blob: 163831a087ef1c8a1c411dc037e10a532217cdb9 [file] [log] [blame]
/* SPDX-License-Identifier: GPL-2.0+ */
* ipmi.h
* MontaVista IPMI interface
* Author: MontaVista Software, Inc.
* Corey Minyard <>
* Copyright 2002 MontaVista Software Inc.
#ifndef __LINUX_IPMI_H
#define __LINUX_IPMI_H
#include <uapi/linux/ipmi.h>
#include <linux/list.h>
#include <linux/proc_fs.h>
#include <linux/acpi.h> /* For acpi_handle */
struct module;
struct device;
* Opaque type for a IPMI message user. One of these is needed to
* send and receive messages.
struct ipmi_user;
* Stuff coming from the receive interface comes as one of these.
* They are allocated, the receiver must free them with
* ipmi_free_recv_msg() when done with the message. The link is not
* used after the message is delivered, so the upper layer may use the
* link to build a linked list, if it likes.
struct ipmi_recv_msg {
struct list_head link;
* The type of message as defined in the "Receive Types"
* defines above.
int recv_type;
struct ipmi_user *user;
struct ipmi_addr addr;
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.
void *user_msg_data;
* 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.
unsigned char msg_data[IPMI_MAX_MSG_LENGTH];
/* Allocate and free the receive message. */
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.
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.
void (*ipmi_watchdog_pretimeout)(void *handler_data);
* If not NULL, called at panic time after the interface has
* been set up to handle run to completion.
void (*ipmi_panic_handler)(void *handler_data);
* Called when the interface has been removed. After this returns
* the user handle will be invalid. The interface may or may
* not be usable when this is called, but it will return errors
* if it is not usable.
void (*shutdown)(void *handler_data);
/* Create a new user of the IPMI layer on the given interface number. */
int ipmi_create_user(unsigned int if_num,
const struct ipmi_user_hndl *handler,
void *handler_data,
struct ipmi_user **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.
int ipmi_destroy_user(struct ipmi_user *user);
/* Get the IPMI version of the BMC we are talking to. */
int ipmi_get_version(struct ipmi_user *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.
int ipmi_set_my_address(struct ipmi_user *user,
unsigned int channel,
unsigned char address);
int ipmi_get_my_address(struct ipmi_user *user,
unsigned int channel,
unsigned char *address);
int ipmi_set_my_LUN(struct ipmi_user *user,
unsigned int channel,
unsigned char LUN);
int ipmi_get_my_LUN(struct ipmi_user *user,
unsigned int channel,
unsigned char *LUN);
* Like ipmi_request, but lets you specify the number of retries and
* the retry time. The retries is the number of times the message
* will be resent if no reply is received. If set to -1, the default
* value will be used. The retry time is the time in milliseconds
* between retries. If set to zero, the default value will be
* used.
* Don't use this unless you *really* have to. It's primarily for the
* IPMI over LAN converter; since the LAN stuff does its own retries,
* it makes no sense to do it here. However, this can be used if you
* have unusual requirements.
int ipmi_request_settime(struct ipmi_user *user,
struct ipmi_addr *addr,
long msgid,
struct kernel_ipmi_msg *msg,
void *user_msg_data,
int priority,
int max_retries,
unsigned int retry_time_ms);
* Like ipmi_request, but with messages supplied. This will not
* allocate any memory, and the messages may be statically allocated
* (just make sure to do the "done" handling on them). Note that this
* is primarily for the watchdog timer, since it should be able to
* send messages even if no memory is available. This is subject to
* change as the system changes, so don't use it unless you REALLY
* have to.
int ipmi_request_supply_msgs(struct ipmi_user *user,
struct ipmi_addr *addr,
long msgid,
struct kernel_ipmi_msg *msg,
void *user_msg_data,
void *supplied_smi,
struct ipmi_recv_msg *supplied_recv,
int priority);
* Poll the IPMI interface for the user. This causes the IPMI code to
* do an immediate check for information from the driver and handle
* anything that is immediately pending. This will not block in any
* way. This is useful if you need to spin waiting for something to
* happen in the IPMI driver.
void ipmi_poll_interface(struct ipmi_user *user);
* When commands come in to the SMS, the user can register to receive
* them. Only one user can be listening on a specific netfn/cmd/chan tuple
* at a time, you will get an EBUSY error if the command is already
* registered. If a command is received that does not have a user
* registered, the driver will automatically return the proper
* error. Channels are specified as a bitfield, use IPMI_CHAN_ALL to
* mean all channels.
int ipmi_register_for_cmd(struct ipmi_user *user,
unsigned char netfn,
unsigned char cmd,
unsigned int chans);
int ipmi_unregister_for_cmd(struct ipmi_user *user,
unsigned char netfn,
unsigned char cmd,
unsigned int chans);
* Go into a mode where the driver will not autonomously attempt to do
* things with the interface. It will still respond to attentions and
* interrupts, and it will expect that commands will complete. It
* will not automatcially check for flags, events, or things of that
* nature.
* This is primarily used for firmware upgrades. The idea is that
* when you go into firmware upgrade mode, you do this operation
* and the driver will not attempt to do anything but what you tell
* it or what the BMC asks for.
* Note that if you send a command that resets the BMC, the driver
* will still expect a response from that command. So the BMC should
* reset itself *after* the response is sent. Resetting before the
* response is just silly.
* If in auto maintenance mode, the driver will automatically go into
* maintenance mode for 30 seconds if it sees a cold reset, a warm
* reset, or a firmware NetFN. This means that code that uses only
* firmware NetFN commands to do upgrades will work automatically
* without change, assuming it sends a message every 30 seconds or
* less.
* See the IPMI_MAINTENANCE_MODE_xxx defines for what the mode means.
int ipmi_get_maintenance_mode(struct ipmi_user *user);
int ipmi_set_maintenance_mode(struct ipmi_user *user, int mode);
* When the user is created, it will not receive IPMI events by
* default. The user must set this to TRUE to get incoming events.
* The first user that sets this to TRUE will receive all events that
* have been queued while no one was waiting for events.
int ipmi_set_gets_events(struct ipmi_user *user, bool val);
* Called when a new SMI is registered. This will also be called on
* every existing interface when a new watcher is registered with
* ipmi_smi_watcher_register().
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").
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.
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.
/* Return the maximum length of an IPMI address given it's type. */
unsigned int ipmi_addr_length(int addr_type);
/* Validate that the given IPMI address is valid. */
int ipmi_validate_addr(struct ipmi_addr *addr, int len);
* How did the IPMI driver find out about the device?
enum ipmi_addr_src {
const char *ipmi_addr_src_to_str(enum ipmi_addr_src src);
union ipmi_smi_info_union {
* the acpi_info element is defined for the SI_ACPI
* address type
struct {
acpi_handle acpi_handle;
} acpi_info;
struct ipmi_smi_info {
enum ipmi_addr_src addr_src;
* Base device for the interface. Don't forget to put this when
* you are done.
struct device *dev;
* The addr_info provides more detailed info for some IPMI
* devices, depending on the addr_src. Currently only SI_ACPI
* info is provided.
union ipmi_smi_info_union addr_info;
/* This is to get the private info of struct ipmi_smi */
extern int ipmi_get_smi_info(int if_num, struct ipmi_smi_info *data);
/* Helper function for computing the IPMB checksum of some data. */
unsigned char ipmb_checksum(unsigned char *data, int size);
#endif /* __LINUX_IPMI_H */