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