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