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