include/linux/ipmi.h

   1 /* SPDX-License-Identifier: GPL-2.0+ */
   2 /*
   3  * ipmi.h
   4  *
   5  * MontaVista IPMI interface
   6  *
   7  * Author: MontaVista Software, Inc.
   8  *         Corey Minyard <minyard@mvista.com>
   9  *         source@mvista.com
  10  *
  11  * Copyright 2002 MontaVista Software Inc.
  12  *
  13  */
  14 #ifndef __LINUX_IPMI_H
  15 #define __LINUX_IPMI_H
  16
  17 #include <uapi/linux/ipmi.h>
  18
  19 #include <linux/list.h>
  20 #include <linux/proc_fs.h>
  21 #include <linux/acpi.h> /* For acpi_handle */
  22
  23 struct module;
  24 struct device;
  25
  26 /*
  27  * Opaque type for a IPMI message user.  One of these is needed to
  28  * send and receive messages.
  29  */
  30 struct ipmi_user;
  31
  32 /*
  33  * Stuff coming from the receive interface comes as one of these.
  34  * They are allocated, the receiver must free them with
  35  * ipmi_free_recv_msg() when done with the message.  The link is not
  36  * used after the message is delivered, so the upper layer may use the
  37  * link to build a linked list, if it likes.
  38  */
  39 struct ipmi_recv_msg {
  40         struct list_head link;
  41
  42         /*
  43          * The type of message as defined in the "Receive Types"
  44          * defines above.
  45          */
  46         int              recv_type;
  47
  48         struct ipmi_user *user;
  49         struct ipmi_addr addr;
  50         long             msgid;
  51         struct kernel_ipmi_msg  msg;
  52
  53         /*
  54          * The user_msg_data is the data supplied when a message was
  55          * sent, if this is a response to a sent message.  If this is
  56          * not a response to a sent message, then user_msg_data will
  57          * be NULL.  If the user above is NULL, then this will be the
  58          * intf.
  59          */
  60         void             *user_msg_data;
  61
  62         /*
  63          * Call this when done with the message.  It will presumably free
  64          * the message and do any other necessary cleanup.
  65          */
  66         void (*done)(struct ipmi_recv_msg *msg);
  67
  68         /*
  69          * Place-holder for the data, don't make any assumptions about
  70          * the size or existence of this, since it may change.
  71          */
  72         unsigned char   msg_data[IPMI_MAX_MSG_LENGTH];
  73 };
  74
  75 #define INIT_IPMI_RECV_MSG(done_handler) \
  76 {                                       \
  77         .done = done_handler            \
  78 }
  79
  80 /* Allocate and free the receive message. */
  81 void ipmi_free_recv_msg(struct ipmi_recv_msg *msg);
  82
  83 struct ipmi_user_hndl {
  84         /*
  85          * Routine type to call when a message needs to be routed to
  86          * the upper layer.  This will be called with some locks held,
  87          * the only IPMI routines that can be called are ipmi_request
  88          * and the alloc/free operations.  The handler_data is the
  89          * variable supplied when the receive handler was registered.
  90          */
  91         void (*ipmi_recv_hndl)(struct ipmi_recv_msg *msg,
  92                                void                 *user_msg_data);
  93
  94         /*
  95          * Called when the interface detects a watchdog pre-timeout.  If
  96          * this is NULL, it will be ignored for the user.
  97          */
  98         void (*ipmi_watchdog_pretimeout)(void *handler_data);
  99
 100         /*
 101          * If not NULL, called at panic time after the interface has
 102          * been set up to handle run to completion.
 103          */
 104         void (*ipmi_panic_handler)(void *handler_data);
 105
 106         /*
 107          * Called when the interface has been removed.  After this returns
 108          * the user handle will be invalid.  The interface may or may
 109          * not be usable when this is called, but it will return errors
 110          * if it is not usable.
 111          */
 112         void (*shutdown)(void *handler_data);
 113 };
 114
 115 /* Create a new user of the IPMI layer on the given interface number. */
 116 int ipmi_create_user(unsigned int          if_num,
 117                      const struct ipmi_user_hndl *handler,
 118                      void                  *handler_data,
 119                      struct ipmi_user      **user);
 120
 121 /*
 122  * Destroy the given user of the IPMI layer.  Note that after this
 123  * function returns, the system is guaranteed to not call any
 124  * callbacks for the user.  Thus as long as you destroy all the users
 125  * before you unload a module, you will be safe.  And if you destroy
 126  * the users before you destroy the callback structures, it should be
 127  * safe, too.
 128  */
 129 int ipmi_destroy_user(struct ipmi_user *user);
 130
 131 /* Get the IPMI version of the BMC we are talking to. */
 132 int ipmi_get_version(struct ipmi_user *user,
 133                      unsigned char *major,
 134                      unsigned char *minor);
 135
 136 /*
 137  * Set and get the slave address and LUN that we will use for our
 138  * source messages.  Note that this affects the interface, not just
 139  * this user, so it will affect all users of this interface.  This is
 140  * so some initialization code can come in and do the OEM-specific
 141  * things it takes to determine your address (if not the BMC) and set
 142  * it for everyone else.  Note that each channel can have its own
 143  * address.
 144  */
 145 int ipmi_set_my_address(struct ipmi_user *user,
 146                         unsigned int  channel,
 147                         unsigned char address);
 148 int ipmi_get_my_address(struct ipmi_user *user,
 149                         unsigned int  channel,
 150                         unsigned char *address);
 151 int ipmi_set_my_LUN(struct ipmi_user *user,
 152                     unsigned int  channel,
 153                     unsigned char LUN);
 154 int ipmi_get_my_LUN(struct ipmi_user *user,
 155                     unsigned int  channel,
 156                     unsigned char *LUN);
 157
 158 /*
 159  * Like ipmi_request, but lets you specify the number of retries and
 160  * the retry time.  The retries is the number of times the message
 161  * will be resent if no reply is received.  If set to -1, the default
 162  * value will be used.  The retry time is the time in milliseconds
 163  * between retries.  If set to zero, the default value will be
 164  * used.
 165  *
 166  * Don't use this unless you *really* have to.  It's primarily for the
 167  * IPMI over LAN converter; since the LAN stuff does its own retries,
 168  * it makes no sense to do it here.  However, this can be used if you
 169  * have unusual requirements.
 170  */
 171 int ipmi_request_settime(struct ipmi_user *user,
 172                          struct ipmi_addr *addr,
 173                          long             msgid,
 174                          struct kernel_ipmi_msg  *msg,
 175                          void             *user_msg_data,
 176                          int              priority,
 177                          int              max_retries,
 178                          unsigned int     retry_time_ms);
 179
 180 /*
 181  * Like ipmi_request, but with messages supplied.  This will not
 182  * allocate any memory, and the messages may be statically allocated
 183  * (just make sure to do the "done" handling on them).  Note that this
 184  * is primarily for the watchdog timer, since it should be able to
 185  * send messages even if no memory is available.  This is subject to
 186  * change as the system changes, so don't use it unless you REALLY
 187  * have to.
 188  */
 189 int ipmi_request_supply_msgs(struct ipmi_user     *user,
 190                              struct ipmi_addr     *addr,
 191                              long                 msgid,
 192                              struct kernel_ipmi_msg *msg,
 193                              void                 *user_msg_data,
 194                              void                 *supplied_smi,
 195                              struct ipmi_recv_msg *supplied_recv,
 196                              int                  priority);
 197
 198 /*
 199  * Poll the IPMI interface for the user.  This causes the IPMI code to
 200  * do an immediate check for information from the driver and handle
 201  * anything that is immediately pending.  This will not block in any
 202  * way.  This is useful if you need to spin waiting for something to
 203  * happen in the IPMI driver.
 204  */
 205 void ipmi_poll_interface(struct ipmi_user *user);
 206
 207 /*
 208  * When commands come in to the SMS, the user can register to receive
 209  * them.  Only one user can be listening on a specific netfn/cmd/chan tuple
 210  * at a time, you will get an EBUSY error if the command is already
 211  * registered.  If a command is received that does not have a user
 212  * registered, the driver will automatically return the proper
 213  * error.  Channels are specified as a bitfield, use IPMI_CHAN_ALL to
 214  * mean all channels.
 215  */
 216 int ipmi_register_for_cmd(struct ipmi_user *user,
 217                           unsigned char netfn,
 218                           unsigned char cmd,
 219                           unsigned int  chans);
 220 int ipmi_unregister_for_cmd(struct ipmi_user *user,
 221                             unsigned char netfn,
 222                             unsigned char cmd,
 223                             unsigned int  chans);
 224
 225 /*
 226  * Go into a mode where the driver will not autonomously attempt to do
 227  * things with the interface.  It will still respond to attentions and
 228  * interrupts, and it will expect that commands will complete.  It
 229  * will not automatcially check for flags, events, or things of that
 230  * nature.
 231  *
 232  * This is primarily used for firmware upgrades.  The idea is that
 233  * when you go into firmware upgrade mode, you do this operation
 234  * and the driver will not attempt to do anything but what you tell
 235  * it or what the BMC asks for.
 236  *
 237  * Note that if you send a command that resets the BMC, the driver
 238  * will still expect a response from that command.  So the BMC should
 239  * reset itself *after* the response is sent.  Resetting before the
 240  * response is just silly.
 241  *
 242  * If in auto maintenance mode, the driver will automatically go into
 243  * maintenance mode for 30 seconds if it sees a cold reset, a warm
 244  * reset, or a firmware NetFN.  This means that code that uses only
 245  * firmware NetFN commands to do upgrades will work automatically
 246  * without change, assuming it sends a message every 30 seconds or
 247  * less.
 248  *
 249  * See the IPMI_MAINTENANCE_MODE_xxx defines for what the mode means.
 250  */
 251 int ipmi_get_maintenance_mode(struct ipmi_user *user);
 252 int ipmi_set_maintenance_mode(struct ipmi_user *user, int mode);
 253
 254 /*
 255  * When the user is created, it will not receive IPMI events by
 256  * default.  The user must set this to TRUE to get incoming events.
 257  * The first user that sets this to TRUE will receive all events that
 258  * have been queued while no one was waiting for events.
 259  */
 260 int ipmi_set_gets_events(struct ipmi_user *user, bool val);
 261
 262 /*
 263  * Called when a new SMI is registered.  This will also be called on
 264  * every existing interface when a new watcher is registered with
 265  * ipmi_smi_watcher_register().
 266  */
 267 struct ipmi_smi_watcher {
 268         struct list_head link;
 269
 270         /*
 271          * You must set the owner to the current module, if you are in
 272          * a module (generally just set it to "THIS_MODULE").
 273          */
 274         struct module *owner;
 275
 276         /*
 277          * These two are called with read locks held for the interface
 278          * the watcher list.  So you can add and remove users from the
 279          * IPMI interface, send messages, etc., but you cannot add
 280          * or remove SMI watchers or SMI interfaces.
 281          */
 282         void (*new_smi)(int if_num, struct device *dev);
 283         void (*smi_gone)(int if_num);
 284 };
 285
 286 int ipmi_smi_watcher_register(struct ipmi_smi_watcher *watcher);
 287 int ipmi_smi_watcher_unregister(struct ipmi_smi_watcher *watcher);
 288
 289 /*
 290  * The following are various helper functions for dealing with IPMI
 291  * addresses.
 292  */
 293
 294 /* Return the maximum length of an IPMI address given it's type. */
 295 unsigned int ipmi_addr_length(int addr_type);
 296
 297 /* Validate that the given IPMI address is valid. */
 298 int ipmi_validate_addr(struct ipmi_addr *addr, int len);
 299
 300 /*
 301  * How did the IPMI driver find out about the device?
 302  */
 303 enum ipmi_addr_src {
 304         SI_INVALID = 0, SI_HOTMOD, SI_HARDCODED, SI_SPMI, SI_ACPI, SI_SMBIOS,
 305         SI_PCI, SI_DEVICETREE, SI_PLATFORM, SI_LAST
 306 };
 307 const char *ipmi_addr_src_to_str(enum ipmi_addr_src src);
 308
 309 union ipmi_smi_info_union {
 310 #ifdef CONFIG_ACPI
 311         /*
 312          * the acpi_info element is defined for the SI_ACPI
 313          * address type
 314          */
 315         struct {
 316                 acpi_handle acpi_handle;
 317         } acpi_info;
 318 #endif
 319 };
 320
 321 struct ipmi_smi_info {
 322         enum ipmi_addr_src addr_src;
 323
 324         /*
 325          * Base device for the interface.  Don't forget to put this when
 326          * you are done.
 327          */
 328         struct device *dev;
 329
 330         /*
 331          * The addr_info provides more detailed info for some IPMI
 332          * devices, depending on the addr_src.  Currently only SI_ACPI
 333          * info is provided.
 334          */
 335         union ipmi_smi_info_union addr_info;
 336 };
 337
 338 /* This is to get the private info of struct ipmi_smi */
 339 extern int ipmi_get_smi_info(int if_num, struct ipmi_smi_info *data);
 340
 341 #define GET_DEVICE_ID_MAX_RETRY         5
 342
 343 /* Helper function for computing the IPMB checksum of some data. */
 344 unsigned char ipmb_checksum(unsigned char *data, int size);
 345
 346 #endif /* __LINUX_IPMI_H */