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